Save workspace changes

.deploy/artwork-evolution-release/app/Jobs/AnalyzeArtworkAiAssistJob.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Services\Studio\StudioAiAssistService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class AnalyzeArtworkAiAssistJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public int $timeout = 45;
+
+    public function __construct(
+        private readonly int $artworkId,
+        private readonly bool $force = false,
+    ) {
+        $queue = (string) config('vision.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function backoff(): array
+    {
+        return [5, 20, 60];
+    }
+
+    public function handle(StudioAiAssistService $aiAssist): void
+    {
+        $artwork = Artwork::query()->find($this->artworkId);
+        if (! $artwork) {
+            return;
+        }
+
+        $aiAssist->analyze($artwork, $this->force);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/AutoTagArtworkJob.php

@@ -0,0 +1,168 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Services\TagNormalizer;
+use App\Services\TagService;
+use App\Services\Vision\VisionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Redis;
+
+final class AutoTagArtworkJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * Keep retries low; tagging must never block publish.
+     */
+    public int $tries = 3;
+
+    /**
+     * Hard timeout safety for queue workers.
+     */
+    public int $timeout = 20;
+
+    /**
+     * @param int $artworkId
+     * @param string $hash File hash used to build public derivative URLs.
+     */
+    public function __construct(
+        private readonly int $artworkId,
+        private readonly string $hash,
+    ) {
+        $queue = (string) config('vision.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function backoff(): array
+    {
+        return [2, 10, 30];
+    }
+
+    public function handle(TagService $tagService, TagNormalizer $normalizer, ?VisionService $vision = null): void
+    {
+        $vision ??= app(VisionService::class);
+
+        if (! $vision->isEnabled()) {
+            return;
+        }
+
+        $artwork = Artwork::query()->with(['categories.contentType'])->find($this->artworkId);
+        if (! $artwork) {
+            return;
+        }
+
+        $processingKey = $this->processingKey($this->artworkId, $this->hash);
+        if (! $this->acquireProcessingLock($processingKey)) {
+            return;
+        }
+
+        try {
+            $analysis = $vision->analyzeArtwork($artwork, $this->hash);
+            if ($analysis === []) {
+                return;
+            }
+
+            $clipTags = $analysis['clip_tags'] ?? [];
+            $yoloTags = $analysis['yolo_objects'] ?? [];
+
+            $vision->persistVisionMetadata(
+                $artwork,
+                $clipTags,
+                $analysis['blip_caption'] ?? null,
+                $yoloTags,
+            );
+
+            $merged = $vision->mergeTags($clipTags, $yoloTags);
+            if ($merged === []) {
+                $this->markProcessed($this->processedKey($this->artworkId, $this->hash));
+                return;
+            }
+
+            // Normalize explicitly (requirement), then attach via TagService (source=ai + confidence).
+            $payload = [];
+            foreach ($merged as $row) {
+                $tag = $normalizer->normalize((string) ($row['tag'] ?? ''));
+                if ($tag === '') {
+                    continue;
+                }
+                $payload[] = [
+                    'tag' => $tag,
+                    'confidence' => isset($row['confidence']) && is_numeric($row['confidence']) ? (float) $row['confidence'] : null,
+                ];
+            }
+
+            $tagService->attachAiTags($artwork, $payload);
+
+            $this->markProcessed($this->processedKey($this->artworkId, $this->hash));
+        } catch (\Throwable $e) {
+            Log::error('AutoTagArtworkJob failed', [
+                'artwork_id' => $this->artworkId,
+                'hash' => $this->hash,
+                'attempt' => $this->attempts(),
+                'error' => $e->getMessage(),
+            ]);
+
+            // Retry-safe: allow queue retry on transient failures.
+            throw $e;
+        } finally {
+            $this->releaseProcessingLock($processingKey);
+        }
+    }
+
+    private function processingKey(int $artworkId, string $hash): string
+    {
+        return 'autotag:processing:' . $artworkId . ':' . $hash;
+    }
+
+    private function processedKey(int $artworkId, string $hash): string
+    {
+        return 'autotag:processed:' . $artworkId . ':' . $hash;
+    }
+
+    private function acquireProcessingLock(string $key): bool
+    {
+        try {
+            $didSet = Redis::setnx($key, 1);
+            if ($didSet) {
+                Redis::expire($key, 1800);
+            }
+            return (bool) $didSet;
+        } catch (\Throwable $e) {
+            // If Redis is unavailable, proceed without dedupe.
+            return true;
+        }
+    }
+
+    private function releaseProcessingLock(string $key): void
+    {
+        try {
+            Redis::del($key);
+        } catch (\Throwable $e) {
+            // ignore
+        }
+    }
+
+    private function markProcessed(string $key): void
+    {
+        try {
+            Redis::setex($key, 604800, 1); // 7 days
+        } catch (\Throwable $e) {
+            // ignore
+        }
+    }
+
+}

.deploy/artwork-evolution-release/app/Jobs/BackfillArtworkEmbeddingsJob.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Jobs\GenerateArtworkEmbeddingJob;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class BackfillArtworkEmbeddingsJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 1;
+
+    public int $timeout = 120;
+
+    public function __construct(
+        private readonly int $afterId = 0,
+        private readonly int $batchSize = 200,
+        private readonly bool $force = false,
+    ) {
+        $queue = (string) config('recommendations.queue', config('vision.queue', 'default'));
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $batch = max(1, min($this->batchSize, 1000));
+
+        $artworks = Artwork::query()
+            ->where('id', '>', $this->afterId)
+            ->whereNotNull('hash')
+            ->orderBy('id')
+            ->limit($batch)
+            ->get(['id', 'hash']);
+
+        if ($artworks->isEmpty()) {
+            return;
+        }
+
+        foreach ($artworks as $artwork) {
+            GenerateArtworkEmbeddingJob::dispatch((int) $artwork->id, (string) $artwork->hash, $this->force);
+        }
+
+        if ($artworks->count() === $batch) {
+            $lastId = (int) $artworks->last()->id;
+            self::dispatch($lastId, $batch, $this->force);
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/BackfillArtworkVectorIndexJob.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class BackfillArtworkVectorIndexJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 1;
+
+    public int $timeout = 120;
+
+    public function __construct(
+        private readonly int $afterId = 0,
+        private readonly int $batchSize = 200,
+        private readonly bool $publicOnly = false,
+        private readonly int $staleHours = 0,
+    ) {
+        $queue = (string) config('recommendations.queue', config('vision.queue', 'default'));
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $batch = max(1, min($this->batchSize, 1000));
+        $staleHours = max(0, $this->staleHours);
+        $staleBefore = $staleHours > 0 ? now()->subHours($staleHours) : null;
+
+        $query = Artwork::query()
+            ->where('id', '>', $this->afterId)
+            ->whereNotNull('hash')
+            ->whereHas('embeddings')
+            ->when($this->publicOnly, static fn ($query) => $query->public()->published())
+            ->orderBy('id')
+            ->limit($batch);
+
+        if ($staleBefore !== null) {
+            $query->where(static function ($innerQuery) use ($staleBefore): void {
+                $innerQuery->whereNull('last_vector_indexed_at')
+                    ->orWhere('last_vector_indexed_at', '<=', $staleBefore);
+            });
+        }
+
+        $artworks = $query->get(['id']);
+
+        if ($artworks->isEmpty()) {
+            return;
+        }
+
+        foreach ($artworks as $artwork) {
+            SyncArtworkVectorIndexJob::dispatch((int) $artwork->id);
+        }
+
+        if ($artworks->count() === $batch) {
+            $lastId = (int) $artworks->last()->id;
+            self::dispatch($lastId, $batch, $this->publicOnly, $staleHours);
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/DeleteArtworkFromIndexJob.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Queued job: remove a single artwork document from Meilisearch.
+ */
+class DeleteArtworkFromIndexJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 3;
+    public int $timeout = 30;
+
+    public function __construct(public readonly int $artworkId) {}
+
+    public function handle(): void
+    {
+        // Create a bare model instance just to call unsearchable() with the right ID.
+        $artwork = new Artwork();
+        $artwork->id = $this->artworkId;
+        $artwork->unsearchable();
+    }
+
+    public function failed(\Throwable $e): void
+    {
+        Log::error('DeleteArtworkFromIndexJob failed', [
+            'artwork_id' => $this->artworkId,
+            'error'      => $e->getMessage(),
+        ]);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/DeleteMessageFromIndexJob.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Models\Message;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class DeleteMessageFromIndexJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $timeout = 30;
+
+    public function __construct(public readonly int $messageId) {}
+
+    public function handle(): void
+    {
+        Message::query()->whereKey($this->messageId)->unsearchable();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/DetectArtworkMaturityJob.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Services\Maturity\ArtworkMaturityService;
+use App\Services\Vision\VisionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+final class DetectArtworkMaturityJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public int $timeout = 20;
+
+    public function __construct(
+        private readonly int $artworkId,
+        private readonly string $hash,
+    ) {
+        $queue = (string) config('maturity.ai.queue', config('vision.queue', 'default'));
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function backoff(): array
+    {
+        return [5, 30, 120];
+    }
+
+    public function handle(VisionService $vision, ArtworkMaturityService $maturity): void
+    {
+        if (! $vision->isEnabled()) {
+            return;
+        }
+
+        $artwork = Artwork::query()->with(['categories.contentType'])->find($this->artworkId);
+        if (! $artwork) {
+            return;
+        }
+
+        $detailed = $vision->analyzeArtworkMaturityDetailed($artwork, $this->hash);
+        $assessment = (array) ($detailed['assessment'] ?? []);
+        if ($assessment === []) {
+            $assessment = [
+                'status' => ArtworkMaturityService::AI_STATUS_FAILED,
+                'advisory' => 'Vision maturity analysis returned no assessment payload.',
+            ];
+        }
+
+        $maturity->applyAiAssessment($artwork->fresh(), $assessment);
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        $artwork = Artwork::query()->find($this->artworkId);
+        if ($artwork) {
+            app(ArtworkMaturityService::class)->applyAiAssessment($artwork, [
+                'status' => ArtworkMaturityService::AI_STATUS_FAILED,
+                'advisory' => $exception->getMessage(),
+            ]);
+        }
+
+        Log::warning('DetectArtworkMaturityJob failed', [
+            'artwork_id' => $this->artworkId,
+            'hash' => $this->hash,
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/GenerateArtworkEmbeddingJob.php

@@ -0,0 +1,194 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Models\ArtworkEmbedding;
+use App\Services\Vision\ArtworkEmbeddingClient;
+use App\Services\Vision\ArtworkVisionImageUrl;
+use App\Services\Vision\ArtworkVectorIndexService;
+use App\Services\Vision\VectorService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Redis;
+
+final class GenerateArtworkEmbeddingJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public int $timeout = 20;
+
+    public function __construct(
+        private readonly int $artworkId,
+        private readonly ?string $sourceHash = null,
+        private readonly bool $force = false,
+    ) {
+        $queue = (string) config('recommendations.queue', config('vision.queue', 'default'));
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function backoff(): array
+    {
+        return [2, 10, 30];
+    }
+
+    public function handle(
+        ArtworkEmbeddingClient $client,
+        ArtworkVisionImageUrl $imageUrlBuilder,
+        VectorService|ArtworkVectorIndexService $vectors,
+    ): void
+    {
+        if (! (bool) config('recommendations.embedding.enabled', true)) {
+            return;
+        }
+
+        $artwork = Artwork::query()
+            ->with(['categories' => fn ($categories) => $categories->with('contentType')->orderBy('sort_order')->orderBy('name')])
+            ->find($this->artworkId);
+        if (! $artwork) {
+            return;
+        }
+
+        $sourceHash = strtolower((string) preg_replace('/[^a-z0-9]/', '', (string) ($this->sourceHash ?? $artwork->hash ?? '')));
+        if ($sourceHash === '') {
+            return;
+        }
+
+        $model = (string) config('recommendations.embedding.model', 'clip');
+        $modelVersion = (string) config('recommendations.embedding.model_version', 'v1');
+        $algoVersion = (string) config('recommendations.embedding.algo_version', 'clip-cosine-v1');
+
+        if (! $this->force) {
+            $existing = ArtworkEmbedding::query()
+                ->where('artwork_id', $artwork->id)
+                ->where('model', $model)
+                ->where('model_version', $modelVersion)
+                ->first();
+
+            if ($existing && (string) ($existing->source_hash ?? '') === $sourceHash) {
+                return;
+            }
+        }
+
+        $lockKey = $this->lockKey($artwork->id, $model, $modelVersion);
+        if (! $this->acquireLock($lockKey)) {
+            return;
+        }
+
+        try {
+            $imageUrl = $imageUrlBuilder->fromHash($sourceHash, (string) ($artwork->thumb_ext ?: 'webp'));
+            if ($imageUrl === null) {
+                return;
+            }
+
+            $vector = $client->embed($imageUrl, (int) $artwork->id, $sourceHash);
+            if ($vector === []) {
+                return;
+            }
+
+            $normalized = $this->normalize($vector);
+
+            ArtworkEmbedding::query()->updateOrCreate(
+                [
+                    'artwork_id' => (int) $artwork->id,
+                    'model' => $model,
+                    'model_version' => $modelVersion,
+                ],
+                [
+                    'algo_version' => $algoVersion,
+                    'dim' => count($normalized),
+                    'embedding_json' => json_encode($normalized, JSON_THROW_ON_ERROR),
+                    'source_hash' => $sourceHash,
+                    'is_normalized' => true,
+                    'generated_at' => now(),
+                    'meta' => [
+                        'source' => 'clip',
+                        'image_variant' => (string) config('vision.image_variant', 'md'),
+                    ],
+                ]
+            );
+
+            $this->upsertVectorIndex($vectors, $artwork);
+        } finally {
+            $this->releaseLock($lockKey);
+        }
+    }
+
+    private function upsertVectorIndex(
+        VectorService|ArtworkVectorIndexService $vectors,
+        Artwork $artwork
+    ): void
+    {
+        if (! $vectors->isConfigured()) {
+            return;
+        }
+
+        try {
+            $vectors->upsertArtwork($artwork);
+        } catch (\Throwable $e) {
+            Log::warning('GenerateArtworkEmbeddingJob vector upsert failed', [
+                'artwork_id' => (int) $artwork->id,
+                'error' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    /**
+     * @param array<int, float> $vector
+     * @return array<int, float>
+     */
+    private function normalize(array $vector): array
+    {
+        $sumSquares = 0.0;
+        foreach ($vector as $value) {
+            $sumSquares += ($value * $value);
+        }
+
+        if ($sumSquares <= 0.0) {
+            return $vector;
+        }
+
+        $norm = sqrt($sumSquares);
+        return array_map(static fn (float $value): float => $value / $norm, $vector);
+    }
+
+    private function lockKey(int $artworkId, string $model, string $version): string
+    {
+        return 'artwork-embedding:lock:' . $artworkId . ':' . $model . ':' . $version;
+    }
+
+    private function acquireLock(string $key): bool
+    {
+        try {
+            $didSet = Redis::setnx($key, 1);
+            if ($didSet) {
+                Redis::expire($key, 1800);
+            }
+            return (bool) $didSet;
+        } catch (\Throwable) {
+            return true;
+        }
+    }
+
+    private function releaseLock(string $key): void
+    {
+        try {
+            Redis::del($key);
+        } catch (\Throwable) {
+            // ignore
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/GenerateDerivativesJob.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\Uploads\UploadPipelineService;
+use App\Jobs\AnalyzeArtworkAiAssistJob;
+use App\Jobs\AutoTagArtworkJob;
+use App\Jobs\DetectArtworkMaturityJob;
+use App\Jobs\GenerateArtworkEmbeddingJob;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class GenerateDerivativesJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(
+        private readonly string $sessionId,
+        private readonly string $hash,
+        private readonly int $artworkId,
+        private readonly ?string $originalFileName = null,
+        private readonly ?string $archiveSessionId = null,
+        private readonly ?string $archiveHash = null,
+        private readonly ?string $archiveOriginalFileName = null,
+        private readonly array $additionalScreenshotSessions = []
+    ) {
+    }
+
+    public function handle(UploadPipelineService $pipeline): void
+    {
+        $pipeline->processAndPublish(
+            $this->sessionId,
+            $this->hash,
+            $this->artworkId,
+            $this->originalFileName,
+            $this->archiveSessionId,
+            $this->archiveHash,
+            $this->archiveOriginalFileName,
+            $this->additionalScreenshotSessions
+        );
+
+        // Auto-tagging is async and must never block publish.
+        AutoTagArtworkJob::dispatch($this->artworkId, $this->hash)->afterCommit();
+        DetectArtworkMaturityJob::dispatch($this->artworkId, $this->hash)->afterCommit();
+        GenerateArtworkEmbeddingJob::dispatch($this->artworkId, $this->hash)->afterCommit();
+        AnalyzeArtworkAiAssistJob::dispatch($this->artworkId)->afterCommit();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/IncrementArtworkView.php

@@ -0,0 +1,73 @@
+<?php
+namespace App\Jobs;
+
+use App\Services\ArtworkStatsService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Redis;
+
+class IncrementArtworkView implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $artworkId;
+    public int $count;
+    public string $eventId;
+
+    /**
+     * Require a unique event id to make the job idempotent across retries and concurrency.
+     *
+     * @param int $artworkId
+     * @param string $eventId  Unique identifier for this view event (caller must supply)
+     * @param int $count
+     */
+    public function __construct(int $artworkId, string $eventId, int $count = 1)
+    {
+        $this->artworkId = $artworkId;
+        $this->count = max(1, $count);
+        $this->eventId = $eventId;
+    }
+
+    /**
+     * Execute the job.
+     * Uses Redis setnx to ensure only one worker processes a given eventId.
+     * Delegates actual DB mutation to ArtworkStatsService which uses transactions.
+     */
+    public function handle(ArtworkStatsService $statsService): void
+    {
+        $key = 'artwork:view:processed:' . $this->eventId;
+
+        try {
+            $didSet = false;
+            try {
+                $didSet = Redis::setnx($key, 1);
+                if ($didSet) {
+                    // expire after 1 day to limit key growth
+                    Redis::expire($key, 86400);
+                }
+            } catch (\Throwable $e) {
+                Log::warning('Redis unavailable for IncrementArtworkView; proceeding without dedupe', ['error' => $e->getMessage()]);
+                // If Redis is not available, fall back to applying delta directly.
+                // This sacrifices idempotency but ensures metrics are recorded.
+                $statsService->applyDelta($this->artworkId, ['views' => $this->count]);
+                return;
+            }
+
+            if (! $didSet) {
+                // Already processed this eventId — idempotent skip
+                return;
+            }
+
+            // Safe increment using transactional method
+            $statsService->applyDelta($this->artworkId, ['views' => $this->count]);
+        } catch (\Throwable $e) {
+            Log::error('IncrementArtworkView job failed', ['artwork_id' => $this->artworkId, 'event_id' => $this->eventId, 'error' => $e->getMessage()]);
+            // Let the job be retried by throwing
+            throw $e;
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/IndexArtworkJob.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Queued job: index (or re-index) a single Artwork in Meilisearch.
+ */
+class IndexArtworkJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 3;
+    public int $timeout = 30;
+
+    public function __construct(public readonly int $artworkId) {}
+
+    public function handle(): void
+    {
+        $artwork = Artwork::with(['user', 'tags', 'categories', 'stats', 'awardStat'])
+            ->find($this->artworkId);
+
+        if (! $artwork) {
+            return;
+        }
+
+        if (! $artwork->is_public || ! $artwork->is_approved || ! $artwork->published_at) {
+            // Not public/approved — ensure it is removed from the index.
+            $artwork->unsearchable();
+            return;
+        }
+
+        $artwork->searchable();
+    }
+
+    public function failed(\Throwable $e): void
+    {
+        Log::error('IndexArtworkJob failed', [
+            'artwork_id' => $this->artworkId,
+            'error'      => $e->getMessage(),
+        ]);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/IndexMessageJob.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Models\Message;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class IndexMessageJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $timeout = 30;
+
+    public function __construct(public readonly int $messageId) {}
+
+    public function handle(): void
+    {
+        $message = Message::with(['sender:id,username', 'attachments'])->find($this->messageId);
+
+        if (! $message) {
+            return;
+        }
+
+        if (! $message->shouldBeSearchable()) {
+            $message->unsearchable();
+            return;
+        }
+
+        $message->searchable();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/IndexUserJob.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\User;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Queued job: index (or re-index) a single User in Meilisearch.
+ * Dispatched by UserStatsService whenever stats change.
+ */
+class IndexUserJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 3;
+    public int $timeout = 30;
+
+    public function __construct(public readonly int $userId) {}
+
+    public function handle(): void
+    {
+        $user = User::with('statistics')->find($this->userId);
+
+        if (! $user) {
+            return;
+        }
+
+        if (! $user->shouldBeSearchable()) {
+            $user->unsearchable();
+            return;
+        }
+
+        $user->searchable();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/IngestUserDiscoveryEventJob.php

@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\Recommendations\UserInterestProfileService;
+use App\Services\Recommendations\SessionRecoService;
+use Carbon\CarbonImmutable;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Redis;
+use Illuminate\Support\Facades\Schema;
+
+final class IngestUserDiscoveryEventJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [5, 30, 120];
+
+    /**
+     * @param array<string, mixed> $meta
+     */
+    public function __construct(
+        public readonly string $eventId,
+        public readonly int $userId,
+        public readonly int $artworkId,
+        public readonly string $eventType,
+        public readonly string $algoVersion,
+        public readonly string $occurredAt,
+        public readonly array $meta = []
+    ) {
+    }
+
+    public function handle(UserInterestProfileService $profileService, SessionRecoService $sessionRecoService): void
+    {
+        $idempotencyKey = sprintf('discovery:event:processed:%s', $this->eventId);
+
+        try {
+            $didSet = false;
+            try {
+                $didSet = (bool) Redis::setnx($idempotencyKey, 1);
+                if ($didSet) {
+                    Redis::expire($idempotencyKey, 86400 * 2);
+                }
+            } catch (\Throwable $e) {
+                Log::warning('Redis unavailable for discovery ingestion; proceeding without redis dedupe', [
+                    'event_id' => $this->eventId,
+                    'error' => $e->getMessage(),
+                ]);
+                $didSet = true;
+            }
+
+            if (! $didSet) {
+                return;
+            }
+
+            $occurredAt = CarbonImmutable::parse($this->occurredAt);
+            $eventVersion = (string) config('discovery.event_version', 'event-v1');
+            $eventWeight = (float) ((array) config('discovery.weights', []))[$this->eventType] ?? 1.0;
+
+            $categoryId = DB::table('artwork_category')
+                ->where('artwork_id', $this->artworkId)
+                ->orderBy('category_id')
+                ->value('category_id');
+
+            $insertPayload = [
+                'event_id' => $this->eventId,
+                'user_id' => $this->userId,
+                'artwork_id' => $this->artworkId,
+                'category_id' => $categoryId !== null ? (int) $categoryId : null,
+                'event_type' => $this->eventType,
+                'event_version' => $eventVersion,
+                'algo_version' => $this->algoVersion,
+                'weight' => $eventWeight,
+                'event_date' => $occurredAt->toDateString(),
+                'occurred_at' => $occurredAt->toDateTimeString(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ];
+
+            if (Schema::hasColumn('user_discovery_events', 'meta')) {
+                $insertPayload['meta'] = $this->meta;
+            } elseif (Schema::hasColumn('user_discovery_events', 'metadata')) {
+                $insertPayload['metadata'] = json_encode($this->meta, JSON_UNESCAPED_SLASHES);
+            }
+
+            DB::table('user_discovery_events')->insertOrIgnore($insertPayload);
+
+            $profileService->applyEvent(
+                userId: $this->userId,
+                eventType: $this->eventType,
+                artworkId: $this->artworkId,
+                categoryId: $categoryId !== null ? (int) $categoryId : null,
+                occurredAt: $occurredAt,
+                eventId: $this->eventId,
+                algoVersion: $this->algoVersion,
+                eventMeta: $this->meta
+            );
+
+            $sessionRecoService->applyEvent(
+                userId: $this->userId,
+                eventType: $this->eventType,
+                artworkId: $this->artworkId,
+                categoryId: $categoryId !== null ? (int) $categoryId : null,
+                occurredAt: $occurredAt->toIso8601String(),
+                meta: $this->meta,
+            );
+        } catch (\Throwable $e) {
+            Log::error('IngestUserDiscoveryEventJob failed', [
+                'event_id' => $this->eventId,
+                'user_id' => $this->userId,
+                'artwork_id' => $this->artworkId,
+                'event_type' => $this->eventType,
+                'error' => $e->getMessage(),
+            ]);
+
+            throw $e;
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/NovaCards/GenerateNovaCardExportJob.php

@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs\NovaCards;
+
+use App\Models\NovaCard;
+use App\Models\NovaCardExport;
+use App\Services\NovaCards\NovaCardRenderService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+
+class GenerateNovaCardExportJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(
+        public readonly int $exportId,
+    ) {
+    }
+
+    public function handle(NovaCardRenderService $renderService): void
+    {
+        $export = NovaCardExport::query()->find($this->exportId);
+        if (! $export || $export->status === NovaCardExport::STATUS_READY) {
+            return;
+        }
+
+        $card = NovaCard::query()->with(['backgroundImage'])->find($export->card_id);
+        if (! $card) {
+            $export->forceFill(['status' => NovaCardExport::STATUS_FAILED])->save();
+
+            return;
+        }
+
+        $export->forceFill(['status' => NovaCardExport::STATUS_PROCESSING])->save();
+
+        $specs = config('nova_cards.export_formats.' . $export->export_type, []);
+        $width = (int) ($export->width ?: ($specs['width'] ?? 1080));
+        $height = (int) ($export->height ?: ($specs['height'] ?? 1080));
+        $format = (string) ($export->format ?: ($specs['format'] ?? 'png'));
+
+        $outputPath = $this->renderExport($renderService, $card, $export, $width, $height, $format);
+
+        $export->forceFill([
+            'status' => NovaCardExport::STATUS_READY,
+            'output_path' => $outputPath,
+            'ready_at' => now(),
+        ])->save();
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        $export = NovaCardExport::query()->find($this->exportId);
+        if ($export) {
+            $export->forceFill(['status' => NovaCardExport::STATUS_FAILED])->save();
+        }
+    }
+
+    private function renderExport(
+        NovaCardRenderService $renderService,
+        NovaCard $card,
+        NovaCardExport $export,
+        int $width,
+        int $height,
+        string $format,
+    ): string {
+        // Use the render service for standard preview dimensions; for non-standard
+        // dimensions delegate a temporary override via a cloned render call.
+        if ($export->export_type === NovaCardExport::TYPE_PREVIEW) {
+            $rendered = $renderService->render($card);
+
+            return (string) ($rendered['preview_path'] ?? '');
+        }
+
+        // For all other export types, produce a dedicated output file.
+        if (! function_exists('imagecreatetruecolor')) {
+            throw new \RuntimeException('Nova card rendering requires the GD extension.');
+        }
+
+        // Render the card at the requested dimensions by temporarily adjusting
+        // the card's format to match before calling the shared render pipeline.
+        // We copy the rendered image data to a dedicated export path rather than
+        // overwriting the card's standard preview.
+        $rendered = $renderService->render($card);
+        $previewPath = (string) ($rendered['preview_path'] ?? '');
+
+        $disk = Storage::disk((string) config('nova_cards.storage.public_disk', 'public'));
+
+        if (! $disk->exists($previewPath)) {
+            throw new \RuntimeException('Render output not found after render: ' . $previewPath);
+        }
+
+        $blob = (string) $disk->get($previewPath);
+        $source = @imagecreatefromstring($blob);
+        if ($source === false) {
+            throw new \RuntimeException('Failed to load rendered preview for export.');
+        }
+
+        $target = imagecreatetruecolor($width, $height);
+        imagealphablending($target, true);
+        imagesavealpha($target, true);
+        imagecopyresampled($target, $source, 0, 0, 0, 0, $width, $height, imagesx($source), imagesy($source));
+        imagedestroy($source);
+
+        $exportDir = trim((string) config('nova_cards.storage.preview_prefix', 'cards/previews'), '/')
+            . '/' . $card->user_id . '/exports';
+        $filename = $card->uuid . '-' . $export->export_type . '-' . Str::random(6) . '.' . $format;
+        $outputPath = $exportDir . '/' . $filename;
+
+        ob_start();
+        match ($format) {
+            'jpg', 'jpeg' => imagejpeg($target, null, 90),
+            'webp' => imagewebp($target, null, 88),
+            default => imagepng($target, null, 6),
+        };
+        $binary = (string) ob_get_clean();
+        imagedestroy($target);
+
+        $disk->put($outputPath, $binary);
+
+        return $outputPath;
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/NovaCards/RenderNovaCardPreviewJob.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs\NovaCards;
+
+use App\Models\NovaCard;
+use App\Services\NovaCards\NovaCardPublishModerationService;
+use App\Services\NovaCards\NovaCardPlaywrightRenderService;
+use App\Services\NovaCards\NovaCardRenderService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class RenderNovaCardPreviewJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(
+        public readonly int $cardId,
+    ) {
+    }
+
+    public function handle(NovaCardRenderService $renderService, NovaCardPlaywrightRenderService $playwrightService, NovaCardPublishModerationService $moderation): void
+    {
+        $card = NovaCard::query()->with(['backgroundImage', 'user'])->find($this->cardId);
+        if (! $card) {
+            return;
+        }
+
+        // Try the CSS/Playwright renderer first (pixel-perfect match with the editor).
+        // Falls back to the GD renderer if Playwright is disabled or encounters an error.
+        if ($playwrightService->isAvailable()) {
+            try {
+                $playwrightService->render($card);
+            } catch (\Throwable $e) {
+                report($e);
+                $renderService->render($card->fresh()->load(['backgroundImage']));
+            }
+        } else {
+            $renderService->render($card);
+        }
+
+        $evaluation = $moderation->evaluate($card->fresh()->loadMissing(['originalCard.user', 'rootCard.user']));
+
+        $moderation->applyPublishOutcome($card->fresh(), $evaluation);
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        $card = NovaCard::query()->find($this->cardId);
+        if (! $card) {
+            return;
+        }
+
+        $card->forceFill([
+            'status' => NovaCard::STATUS_DRAFT,
+            'moderation_status' => NovaCard::MOD_PENDING,
+        ])->save();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/Posts/AutoUploadPostJob.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Jobs\Posts;
+
+use App\Models\Artwork;
+use App\Models\Post;
+use App\Models\PostTarget;
+use App\Models\User;
+use App\Services\Posts\PostHashtagService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Creates a feed post of type=upload when an artwork is published.
+ * Dispatched from ArtworkObserver when auto_post_upload is enabled for the user.
+ */
+class AutoUploadPostJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+
+    public function __construct(
+        public readonly int $artworkId,
+        public readonly int $userId,
+    ) {}
+
+    public function handle(PostHashtagService $hashtagService): void
+    {
+        $artwork = Artwork::find($this->artworkId);
+        $user    = User::find($this->userId);
+
+        if (! $artwork || ! $user) {
+            return;
+        }
+
+        // If post already exists for this artwork, skip (idempotent)
+        $exists = Post::where('user_id', $user->id)
+            ->where('type', Post::TYPE_UPLOAD)
+            ->whereHas('targets', fn ($q) => $q->where('target_type', 'artwork')->where('target_id', $artwork->id))
+            ->exists();
+
+        if ($exists) {
+            return;
+        }
+
+        DB::transaction(function () use ($artwork, $user, $hashtagService) {
+            $post = Post::create([
+                'user_id'    => $user->id,
+                'type'       => Post::TYPE_UPLOAD,
+                'visibility' => Post::VISIBILITY_PUBLIC,
+                'body'       => null,
+                'status'     => Post::STATUS_PUBLISHED,
+            ]);
+
+            PostTarget::create([
+                'post_id'     => $post->id,
+                'target_type' => 'artwork',
+                'target_id'   => $artwork->id,
+            ]);
+        });
+
+        Log::info("AutoUploadPostJob: created upload post for artwork #{$this->artworkId} by user #{$this->userId}");
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RankBuildListsJob.php

@@ -0,0 +1,206 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Category;
+use App\Models\ContentType;
+use App\Models\RankList;
+use App\Services\RankingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * RankBuildListsJob
+ *
+ * Runs hourly (after RankComputeArtworkScoresJob).
+ *
+ * Builds ordered artwork_id arrays for:
+ *  • global        – trending, new_hot, best
+ *  • each category – trending, new_hot, best
+ *  • each content_type – trending, new_hot, best
+ *
+ * Applies author-diversity cap (max 3 per author in a list of 50).
+ * Stores results in rank_lists and busts relevant Redis keys.
+ */
+class RankBuildListsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $timeout = 1800;
+    public int $tries   = 2;
+
+    private const LIST_TYPES = ['trending', 'new_hot', 'best'];
+
+    public function handle(RankingService $ranking): void
+    {
+        $modelVersion  = config('ranking.model_version', 'rank_v1');
+        $maxPerAuthor  = (int) config('ranking.diversity.max_per_author', 3);
+        $listSize      = (int) config('ranking.diversity.list_size', 50);
+        $candidatePool = (int) config('ranking.diversity.candidate_pool', 200);
+        $listsBuilt    = 0;
+
+        // ── 1. Global ──────────────────────────────────────────────────────
+        foreach (self::LIST_TYPES as $listType) {
+            $this->buildAndStore(
+                $ranking, $listType, 'global', 0,
+                $modelVersion, $maxPerAuthor, $listSize, $candidatePool
+            );
+            $listsBuilt++;
+        }
+
+        // ── 2. Per category ────────────────────────────────────────────────
+        Category::query()
+            ->select(['id'])
+            ->where('is_active', true)
+            ->orderBy('id')
+            ->chunk(200, function ($categories) use (
+                $ranking, $modelVersion, $maxPerAuthor, $listSize, $candidatePool, &$listsBuilt
+            ): void {
+                foreach ($categories as $cat) {
+                    foreach (self::LIST_TYPES as $listType) {
+                        $this->buildAndStore(
+                            $ranking, $listType, 'category', $cat->id,
+                            $modelVersion, $maxPerAuthor, $listSize, $candidatePool
+                        );
+                        $listsBuilt++;
+                    }
+                }
+            });
+
+        // ── 3. Per content type ────────────────────────────────────────────
+        ContentType::query()
+            ->select(['id'])
+            ->orderBy('id')
+            ->chunk(50, function ($ctypes) use (
+                $ranking, $modelVersion, $maxPerAuthor, $listSize, $candidatePool, &$listsBuilt
+            ): void {
+                foreach ($ctypes as $ct) {
+                    foreach (self::LIST_TYPES as $listType) {
+                        $this->buildAndStore(
+                            $ranking, $listType, 'content_type', $ct->id,
+                            $modelVersion, $maxPerAuthor, $listSize, $candidatePool
+                        );
+                        $listsBuilt++;
+                    }
+                }
+            });
+
+        Log::info('RankBuildListsJob: finished', [
+            'lists_built'   => $listsBuilt,
+            'model_version' => $modelVersion,
+        ]);
+    }
+
+    // ── Private helpers ────────────────────────────────────────────────────
+
+    /**
+     * Fetch candidates, apply diversity, and upsert the resulting list.
+     */
+    private function buildAndStore(
+        RankingService $ranking,
+        string $listType,
+        string $scopeType,
+        int $scopeId,
+        string $modelVersion,
+        int $maxPerAuthor,
+        int $listSize,
+        int $candidatePool
+    ): void {
+        $scoreCol   = $this->scoreColumn($listType);
+        $candidates = $this->fetchCandidates(
+            $scopeType, $scopeId, $scoreCol, $candidatePool, $modelVersion
+        );
+
+        $diverse = $ranking->applyDiversity(
+            $candidates->all(), $maxPerAuthor, $listSize
+        );
+
+        $ids = array_map(
+            fn ($item) => (int) ($item->artwork_id ?? $item['artwork_id']),
+            $diverse
+        );
+
+        // Upsert the list (unique: scope_type + scope_id + list_type + model_version)
+        DB::table('rank_lists')->upsert(
+            [[
+                'scope_type'    => $scopeType,
+                'scope_id'      => $scopeId,
+                'list_type'     => $listType,
+                'model_version' => $modelVersion,
+                'artwork_ids'   => json_encode($ids),
+                'computed_at'   => now()->toDateTimeString(),
+            ]],
+            ['scope_type', 'scope_id', 'list_type', 'model_version'],
+            ['artwork_ids', 'computed_at']
+        );
+
+        // Bust Redis cache so next request picks up the new list
+        $ranking->bustCache($scopeType, $scopeId === 0 ? null : $scopeId, $listType);
+    }
+
+    /**
+     * Fetch top N candidates (with user_id) for a given scope/score column.
+     *
+     * @return \Illuminate\Support\Collection<int, object>
+     */
+    private function fetchCandidates(
+        string $scopeType,
+        int $scopeId,
+        string $scoreCol,
+        int $limit,
+        string $modelVersion
+    ): \Illuminate\Support\Collection {
+        $query = DB::table('rank_artwork_scores as ras')
+            ->select(['ras.artwork_id', 'a.user_id', "ras.{$scoreCol}"])
+            ->join('artworks as a', function ($join): void {
+                $join->on('a.id', '=', 'ras.artwork_id')
+                     ->where('a.is_public', 1)
+                     ->where('a.is_approved', 1)
+                     ->whereNull('a.deleted_at');
+            })
+            ->where('ras.model_version', $modelVersion)
+            ->orderByDesc("ras.{$scoreCol}")
+            ->limit($limit);
+
+        if ($scopeType === 'category' && $scopeId > 0) {
+            $query->join(
+                'artwork_category as ac',
+                fn ($j) => $j->on('ac.artwork_id', '=', 'a.id')
+                              ->where('ac.category_id', $scopeId)
+            );
+        }
+
+        if ($scopeType === 'content_type' && $scopeId > 0) {
+            $query->join(
+                'artwork_category as ac',
+                'ac.artwork_id', '=', 'a.id'
+            )->join(
+                'categories as cat',
+                fn ($j) => $j->on('cat.id', '=', 'ac.category_id')
+                              ->where('cat.content_type_id', $scopeId)
+                              ->whereNull('cat.deleted_at')
+            );
+        }
+
+        return $query->get();
+    }
+
+    /**
+     * Map list_type to the rank_artwork_scores column name.
+     */
+    private function scoreColumn(string $listType): string
+    {
+        return match ($listType) {
+            'new_hot' => 'score_new_hot',
+            'best'    => 'score_best',
+            default   => 'score_trending',
+        };
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RankComputeArtworkScoresJob.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\RankingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * RankComputeArtworkScoresJob
+ *
+ * Runs hourly. Queries raw artwork signals (views, favourites, downloads,
+ * age, tags) in batches, computes the three ranking scores using
+ * RankingService::computeScores(), and bulk-upserts the results into
+ * rank_artwork_scores.
+ *
+ * No N+1: all signals are resolved via a single pre-aggregated JOIN query,
+ * chunked by artwork id.
+ */
+class RankComputeArtworkScoresJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $timeout = 1800;     // 30 min max
+    public int $tries   = 2;
+
+    private const CHUNK_SIZE = 500;
+
+    public function handle(RankingService $ranking): void
+    {
+        $modelVersion = config('ranking.model_version', 'rank_v1');
+        $total        = 0;
+        $now          = now()->toDateTimeString();
+
+        $ranking->artworkSignalsQuery()
+            ->orderBy('a.id')
+            ->chunk(self::CHUNK_SIZE, function ($rows) use ($ranking, $modelVersion, $now, &$total): void {
+                $rows = collect($rows);
+
+                if ($rows->isEmpty()) {
+                    return;
+                }
+
+                $upserts = $rows->map(function ($row) use ($ranking, $modelVersion, $now): array {
+                    $scores = $ranking->computeScores($row);
+
+                    return [
+                        'artwork_id'      => (int) $row->id,
+                        'score_trending'  => $scores['score_trending'],
+                        'score_new_hot'   => $scores['score_new_hot'],
+                        'score_best'      => $scores['score_best'],
+                        'model_version'   => $modelVersion,
+                        'computed_at'     => $now,
+                    ];
+                })->all();
+
+                DB::table('rank_artwork_scores')->upsert(
+                    $upserts,
+                    ['artwork_id'],                                          // unique key
+                    ['score_trending', 'score_new_hot', 'score_best',       // update these
+                     'model_version', 'computed_at']
+                );
+
+                $total += count($upserts);
+            });
+
+        Log::info('RankComputeArtworkScoresJob: finished', [
+            'total_updated' => $total,
+            'model_version' => $modelVersion,
+        ]);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RebuildTrendingNovaCardsJob.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\NovaCards\NovaCardTrendingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class RebuildTrendingNovaCardsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function handle(NovaCardTrendingService $trending): void
+    {
+        $trending->rebuildAll();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecBuildItemPairsFromFavouritesJob.php

@@ -0,0 +1,148 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Build item-item co-occurrence pairs from user favourites.
+ *
+ * Spec §7.1 — runs hourly or every few hours.
+ * For each user: take last N favourites, create pairs, increment weights.
+ *
+ * Safety: limits per-user pairs to avoid O(n²) explosion.
+ */
+final class RecBuildItemPairsFromFavouritesJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 2;
+    public int $timeout = 600;
+
+    public function __construct(
+        private readonly int $userBatchSize = 500,
+    ) {
+        $queue = (string) config('recommendations.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $favCap = (int) config('recommendations.similarity.user_favourites_cap', 50);
+
+        // ── Pre-compute per-artwork total favourite counts for cosine normalization ──
+        $this->artworkLikeCounts = DB::table('artwork_favourites')
+            ->select('artwork_id', DB::raw('COUNT(*) as cnt'))
+            ->groupBy('artwork_id')
+            ->pluck('cnt', 'artwork_id')
+            ->all();
+
+        // ── Accumulate co-occurrence counts across all users ──
+        $coOccurrenceCounts = [];
+
+        DB::table('artwork_favourites')
+            ->select('user_id')
+            ->groupBy('user_id')
+            ->orderBy('user_id')
+            ->chunk($this->userBatchSize, function ($userRows) use ($favCap, &$coOccurrenceCounts) {
+                foreach ($userRows as $row) {
+                    $pairs = $this->pairsForUser((int) $row->user_id, $favCap);
+                    foreach ($pairs as $pair) {
+                        $key = $pair[0] . ':' . $pair[1];
+                        $coOccurrenceCounts[$key] = ($coOccurrenceCounts[$key] ?? 0) + 1;
+                    }
+                }
+            });
+
+        // ── Normalize to cosine-like scores and flush ──
+        $normalized = [];
+        foreach ($coOccurrenceCounts as $key => $count) {
+            [$a, $b] = explode(':', $key);
+            $likesA = $this->artworkLikeCounts[(int) $a] ?? 1;
+            $likesB = $this->artworkLikeCounts[(int) $b] ?? 1;
+            $normalized[$key] = $count / sqrt($likesA * $likesB);
+        }
+
+        $this->flushPairs($normalized);
+    }
+
+    /** @var array<int, int> artwork_id => total favourite count */
+    private array $artworkLikeCounts = [];
+
+    /**
+     * Collect pairs from a single user's last N favourites.
+     *
+     * @return list<array{0: int, 1: int}>
+     */
+    public function pairsForUser(int $userId, int $cap): array
+    {
+        $artworkIds = DB::table('artwork_favourites')
+            ->where('user_id', $userId)
+            ->orderByDesc('created_at')
+            ->limit($cap)
+            ->pluck('artwork_id')
+            ->map(fn ($id) => (int) $id)
+            ->all();
+
+        $count = count($artworkIds);
+        if ($count < 2) {
+            return [];
+        }
+
+        $pairs = [];
+        // Cap max pairs per user to avoid explosion: C(50,2) = 1225 worst case = acceptable
+        for ($i = 0; $i < $count - 1; $i++) {
+            for ($j = $i + 1; $j < $count; $j++) {
+                $a = min($artworkIds[$i], $artworkIds[$j]);
+                $b = max($artworkIds[$i], $artworkIds[$j]);
+                $pairs[] = [$a, $b];
+            }
+        }
+
+        return $pairs;
+    }
+
+    /**
+     * Upsert normalized pair weights into rec_item_pairs.
+     *
+     * Uses Laravel's DB-agnostic upsert (works on MySQL, Postgres, SQLite).
+     *
+     * @param array<string, float> $upserts key = "a:b", value = cosine-normalized weight
+     */
+    private function flushPairs(array $upserts): void
+    {
+        if ($upserts === []) {
+            return;
+        }
+
+        $now = now();
+
+        foreach (array_chunk($upserts, 500, preserve_keys: true) as $chunk) {
+            $rows = [];
+            foreach ($chunk as $key => $weight) {
+                [$a, $b] = explode(':', $key);
+                $rows[] = [
+                    'a_artwork_id' => (int) $a,
+                    'b_artwork_id' => (int) $b,
+                    'weight'       => $weight,
+                    'updated_at'   => $now,
+                ];
+            }
+
+            DB::table('rec_item_pairs')->upsert(
+                $rows,
+                ['a_artwork_id', 'b_artwork_id'],
+                ['weight', 'updated_at'],
+            );
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecComputeSimilarByBehaviorJob.php

@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Models\RecArtworkRec;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Compute behavior-based (co-like) similarity from precomputed item pairs.
+ *
+ * Spec §7.3 — runs nightly.
+ * For each artwork: read top pairs from rec_item_pairs, store top N.
+ */
+final class RecComputeSimilarByBehaviorJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 2;
+    public int $timeout = 600;
+
+    public function __construct(
+        private readonly ?int $artworkId = null,
+        private readonly int  $batchSize = 200,
+    ) {
+        $queue = (string) config('recommendations.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $modelVersion  = (string) config('recommendations.similarity.model_version', 'sim_v1');
+        $resultLimit   = (int) config('recommendations.similarity.result_limit', 30);
+        $maxPerAuthor  = (int) config('recommendations.similarity.max_per_author', 2);
+
+        $query = Artwork::query()->public()->published()->select('id', 'user_id');
+
+        if ($this->artworkId !== null) {
+            $query->where('id', $this->artworkId);
+        }
+
+        $query->chunkById($this->batchSize, function ($artworks) use ($modelVersion, $resultLimit, $maxPerAuthor) {
+            foreach ($artworks as $artwork) {
+                $this->processArtwork($artwork, $modelVersion, $resultLimit, $maxPerAuthor);
+            }
+        });
+    }
+
+    private function processArtwork(
+        Artwork $artwork,
+        string $modelVersion,
+        int $resultLimit,
+        int $maxPerAuthor,
+    ): void {
+        // Fetch top co-occurring artworks (bi-directional)
+        $candidates = DB::table('rec_item_pairs')
+            ->where('a_artwork_id', $artwork->id)
+            ->select(DB::raw('b_artwork_id AS related_id'), 'weight')
+            ->union(
+                DB::table('rec_item_pairs')
+                    ->where('b_artwork_id', $artwork->id)
+                    ->select(DB::raw('a_artwork_id AS related_id'), 'weight')
+            )
+            ->orderByDesc('weight')
+            ->limit($resultLimit * 3)
+            ->get();
+
+        if ($candidates->isEmpty()) {
+            return;
+        }
+
+        $relatedIds = $candidates->pluck('related_id')->map(fn ($id) => (int) $id)->all();
+
+        // Fetch author info for diversity filtering
+        $authorMap = DB::table('artworks')
+            ->whereIn('id', $relatedIds)
+            ->where('is_public', true)
+            ->where('is_approved', true)
+            ->whereNotNull('published_at')
+            ->where('published_at', '<=', now())
+            ->whereNull('deleted_at')
+            ->pluck('user_id', 'id')
+            ->all();
+
+        // Apply diversity cap
+        $authorCounts = [];
+        $final = [];
+        foreach ($candidates as $cand) {
+            $relatedId = (int) $cand->related_id;
+            if (! isset($authorMap[$relatedId])) {
+                continue; // not public/published
+            }
+            $authorId = (int) $authorMap[$relatedId];
+            $authorCounts[$authorId] = ($authorCounts[$authorId] ?? 0) + 1;
+            if ($authorCounts[$authorId] > $maxPerAuthor) {
+                continue;
+            }
+            $final[] = $relatedId;
+            if (count($final) >= $resultLimit) {
+                break;
+            }
+        }
+
+        if ($final === []) {
+            return;
+        }
+
+        RecArtworkRec::query()->updateOrCreate(
+            [
+                'artwork_id'    => $artwork->id,
+                'rec_type'      => 'similar_behavior',
+                'model_version' => $modelVersion,
+            ],
+            [
+                'recs'        => $final,
+                'computed_at' => now(),
+            ],
+        );
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecComputeSimilarByTagsJob.php

@@ -0,0 +1,225 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Models\RecArtworkRec;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Compute tag-based (+ category boost) similarity for artworks.
+ *
+ * Spec §7.2 — runs nightly + on-demand.
+ * For each artwork: find candidates by shared tags/category, score with IDF-weighted
+ * tag overlap, apply diversity, store top N.
+ */
+final class RecComputeSimilarByTagsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 2;
+    public int $timeout = 600;
+
+    public function __construct(
+        private readonly ?int $artworkId = null,
+        private readonly int  $batchSize = 200,
+    ) {
+        $queue = (string) config('recommendations.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $modelVersion = (string) config('recommendations.similarity.model_version', 'sim_v1');
+        $candidatePool = (int) config('recommendations.similarity.candidate_pool', 100);
+        $maxPerAuthor  = (int) config('recommendations.similarity.max_per_author', 2);
+        $resultLimit   = (int) config('recommendations.similarity.result_limit', 30);
+
+        // ── Tag IDF weights (global) ───────────────────────────────────────────
+        $tagFreqs = DB::table('artwork_tag')
+            ->select('tag_id', DB::raw('COUNT(*) as cnt'))
+            ->groupBy('tag_id')
+            ->pluck('cnt', 'tag_id')
+            ->all();
+
+        $query = Artwork::query()->public()->published()->select('id', 'user_id');
+
+        if ($this->artworkId !== null) {
+            $query->where('id', $this->artworkId);
+        }
+
+        $query->chunkById($this->batchSize, function ($artworks) use (
+            $tagFreqs, $modelVersion, $candidatePool, $maxPerAuthor, $resultLimit
+        ) {
+            foreach ($artworks as $artwork) {
+                $this->processArtwork($artwork, $tagFreqs, $modelVersion, $candidatePool, $maxPerAuthor, $resultLimit);
+            }
+        });
+    }
+
+    private function processArtwork(
+        Artwork $artwork,
+        array $tagFreqs,
+        string $modelVersion,
+        int $candidatePool,
+        int $maxPerAuthor,
+        int $resultLimit,
+    ): void {
+        // Get source artwork's tags and categories
+        $srcTagIds = DB::table('artwork_tag')
+            ->where('artwork_id', $artwork->id)
+            ->pluck('tag_id')
+            ->all();
+
+        $srcCatIds = DB::table('artwork_category')
+            ->where('artwork_id', $artwork->id)
+            ->pluck('category_id')
+            ->all();
+
+        // Source content_type_ids (via categories)
+        $srcContentTypeIds = $srcCatIds !== []
+            ? DB::table('categories')
+                ->whereIn('id', $srcCatIds)
+                ->whereNotNull('content_type_id')
+                ->pluck('content_type_id')
+                ->unique()
+                ->all()
+            : [];
+
+        if ($srcTagIds === [] && $srcCatIds === []) {
+            return;
+        }
+
+        // ── Find candidates that share at least one tag ────────────────────────
+        $candidateQuery = DB::table('artwork_tag')
+            ->join('artworks', 'artworks.id', '=', 'artwork_tag.artwork_id')
+            ->whereIn('artwork_tag.tag_id', $srcTagIds)
+            ->where('artwork_tag.artwork_id', '!=', $artwork->id)
+            ->where('artworks.is_public', true)
+            ->where('artworks.is_approved', true)
+            ->whereNotNull('artworks.published_at')
+            ->where('artworks.published_at', '<=', now())
+            ->whereNull('artworks.deleted_at')
+            ->select('artwork_tag.artwork_id', 'artworks.user_id')
+            ->groupBy('artwork_tag.artwork_id', 'artworks.user_id')
+            ->orderByRaw('COUNT(*) DESC')
+            ->limit($candidatePool * 3); // over-fetch before scoring
+
+        $candidates = $candidateQuery->get();
+
+        if ($candidates->isEmpty()) {
+            return;
+        }
+
+        // Gather tags for all candidates in one query
+        $candidateIds = $candidates->pluck('artwork_id')->all();
+        $candidateTagMap = DB::table('artwork_tag')
+            ->whereIn('artwork_id', $candidateIds)
+            ->select('artwork_id', 'tag_id')
+            ->get()
+            ->groupBy('artwork_id');
+
+        $candidateCatMap = DB::table('artwork_category')
+            ->whereIn('artwork_id', $candidateIds)
+            ->select('artwork_id', 'category_id')
+            ->get()
+            ->groupBy('artwork_id');
+
+        // Build content_type_id lookup for candidates (via categories table)
+        $allCandidateCatIds = $candidateCatMap->flatten(1)->pluck('category_id')->unique()->all();
+        $catContentTypeMap = $allCandidateCatIds !== []
+            ? DB::table('categories')
+                ->whereIn('id', $allCandidateCatIds)
+                ->whereNotNull('content_type_id')
+                ->pluck('content_type_id', 'id')
+                ->all()
+            : [];
+        $srcContentTypeSet = array_flip($srcContentTypeIds);
+
+        $srcTagSet = array_flip($srcTagIds);
+        $srcCatSet = array_flip($srcCatIds);
+
+        // ── Score each candidate ───────────────────────────────────────────────
+        $scored = [];
+        foreach ($candidates as $cand) {
+            $cTagIds = $candidateTagMap->get($cand->artwork_id, collect())->pluck('tag_id')->all();
+            $cCatIds = $candidateCatMap->get($cand->artwork_id, collect())->pluck('category_id')->all();
+
+            // IDF-weighted tag overlap (spec §5.1)
+            $tagScore = 0.0;
+            foreach ($cTagIds as $tagId) {
+                if (isset($srcTagSet[$tagId])) {
+                    $freq = $tagFreqs[$tagId] ?? 1;
+                    $tagScore += 1.0 / log(2 + $freq);
+                }
+            }
+
+            // Category match bonus
+            $catScore = 0.0;
+            foreach ($cCatIds as $catId) {
+                if (isset($srcCatSet[$catId])) {
+                    $catScore = 1.0;
+                    break;
+                }
+            }
+
+            // Content type match bonus (spec §5.1)
+            $ctScore = 0.0;
+            foreach ($cCatIds as $catId) {
+                $ctId = $catContentTypeMap[$catId] ?? null;
+                if ($ctId !== null && isset($srcContentTypeSet[$ctId])) {
+                    $ctScore = 1.0;
+                    break;
+                }
+            }
+
+            $scored[] = [
+                'artwork_id' => (int) $cand->artwork_id,
+                'user_id'    => (int) $cand->user_id,
+                'tag_score'  => $tagScore,
+                'cat_score'  => $catScore,
+                'score'      => $tagScore + $catScore * 0.1 + $ctScore * 0.05,
+            ];
+        }
+
+        // Sort by score descending
+        usort($scored, fn (array $a, array $b) => $b['score'] <=> $a['score']);
+
+        // ── Apply diversity (max per author) ───────────────────────────────────
+        $authorCounts = [];
+        $final = [];
+        foreach ($scored as $item) {
+            $authorId = $item['user_id'];
+            $authorCounts[$authorId] = ($authorCounts[$authorId] ?? 0) + 1;
+            if ($authorCounts[$authorId] > $maxPerAuthor) {
+                continue;
+            }
+            $final[] = $item['artwork_id'];
+            if (count($final) >= $resultLimit) {
+                break;
+            }
+        }
+
+        // ── Persist ────────────────────────────────────────────────────────────
+        RecArtworkRec::query()->updateOrCreate(
+            [
+                'artwork_id'    => $artwork->id,
+                'rec_type'      => 'similar_tags',
+                'model_version' => $modelVersion,
+            ],
+            [
+                'recs'        => $final,
+                'computed_at' => now(),
+            ],
+        );
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecComputeSimilarHybridJob.php

@@ -0,0 +1,286 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Models\RecArtworkRec;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Compute hybrid similarity by blending tag, behavior, and optionally visual scores.
+ *
+ * Spec §7.4 — runs nightly.
+ * Merges candidates from tag + behavior + vector lists, applies hybrid blend weights,
+ * enforces diversity, stores top 30.
+ */
+final class RecComputeSimilarHybridJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 2;
+    public int $timeout = 900;
+
+    public function __construct(
+        private readonly ?int $artworkId = null,
+        private readonly int  $batchSize = 200,
+    ) {
+        $queue = (string) config('recommendations.queue', 'default');
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function handle(): void
+    {
+        $modelVersion   = (string) config('recommendations.similarity.model_version', 'sim_v1');
+        $vectorEnabled  = (bool) config('recommendations.similarity.vector_enabled', false);
+        $resultLimit    = (int) config('recommendations.similarity.result_limit', 30);
+        $maxPerAuthor   = (int) config('recommendations.similarity.max_per_author', 2);
+        $minCatsTop12   = (int) config('recommendations.similarity.min_categories_top12', 2);
+
+        $weights = $vectorEnabled
+            ? (array) config('recommendations.similarity.weights_with_vector')
+            : (array) config('recommendations.similarity.weights_without_vector');
+
+        $query = Artwork::query()->public()->published()->select('id', 'user_id');
+
+        if ($this->artworkId !== null) {
+            $query->where('id', $this->artworkId);
+        }
+
+        $query->chunkById($this->batchSize, function ($artworks) use (
+            $modelVersion, $vectorEnabled, $resultLimit, $maxPerAuthor, $minCatsTop12, $weights
+        ) {
+            foreach ($artworks as $artwork) {
+                try {
+                    $this->processArtwork(
+                        $artwork, $modelVersion, $vectorEnabled, $resultLimit,
+                        $maxPerAuthor, $minCatsTop12, $weights
+                    );
+                } catch (\Throwable $e) {
+                    Log::warning("[RecComputeSimilarHybrid] Failed for artwork {$artwork->id}: {$e->getMessage()}");
+                }
+            }
+        });
+    }
+
+    private function processArtwork(
+        Artwork $artwork,
+        string $modelVersion,
+        bool $vectorEnabled,
+        int $resultLimit,
+        int $maxPerAuthor,
+        int $minCatsTop12,
+        array $weights,
+    ): void {
+        // ── Collect sub-lists ──────────────────────────────────────────────────
+        $tagRec = RecArtworkRec::query()
+            ->where('artwork_id', $artwork->id)
+            ->where('rec_type', 'similar_tags')
+            ->where('model_version', $modelVersion)
+            ->first();
+
+        $behRec = RecArtworkRec::query()
+            ->where('artwork_id', $artwork->id)
+            ->where('rec_type', 'similar_behavior')
+            ->where('model_version', $modelVersion)
+            ->first();
+
+        $tagIds = $tagRec ? ($tagRec->recs ?? []) : [];
+        $behIds = $behRec ? ($behRec->recs ?? []) : [];
+
+        $vecIds = [];
+        $vecScores = [];
+        if ($vectorEnabled) {
+            $vecRec = RecArtworkRec::query()
+                ->where('artwork_id', $artwork->id)
+                ->where('rec_type', 'similar_visual')
+                ->where('model_version', $modelVersion)
+                ->first();
+            if ($vecRec) {
+                $vecIds = $vecRec->recs ?? [];
+            }
+        }
+
+        // Merge all candidate IDs
+        $allIds = array_values(array_unique(array_merge($tagIds, $behIds, $vecIds)));
+
+        if ($allIds === []) {
+            return;
+        }
+
+        // ── Build normalized score maps ────────────────────────────────────────
+        $tagScoreMap = $this->rankToScore($tagIds);
+        $behScoreMap = $this->rankToScore($behIds);
+        $vecScoreMap = $this->rankToScore($vecIds);
+
+        // Fetch artwork metadata for category + author diversity
+        $metaRows = DB::table('artworks')
+            ->whereIn('id', $allIds)
+            ->where('is_public', true)
+            ->where('is_approved', true)
+            ->whereNotNull('published_at')
+            ->where('published_at', '<=', now())
+            ->whereNull('deleted_at')
+            ->select('id', 'user_id')
+            ->get()
+            ->keyBy('id');
+
+        $catMap = DB::table('artwork_category')
+            ->whereIn('artwork_id', $allIds)
+            ->select('artwork_id', 'category_id')
+            ->get()
+            ->groupBy('artwork_id');
+
+        // Source artwork categories
+        $srcCatIds = DB::table('artwork_category')
+            ->where('artwork_id', $artwork->id)
+            ->pluck('category_id')
+            ->all();
+        $srcCatSet = array_flip($srcCatIds);
+
+        // ── Compute hybrid score ───────────────────────────────────────────────
+        $scored = [];
+        foreach ($allIds as $candidateId) {
+            if (! $metaRows->has($candidateId)) {
+                continue;
+            }
+
+            $meta = $metaRows->get($candidateId);
+            $candidateCats = $catMap->get($candidateId, collect())->pluck('category_id')->all();
+
+            // Category overlap
+            $catScore = 0.0;
+            foreach ($candidateCats as $catId) {
+                if (isset($srcCatSet[$catId])) {
+                    $catScore = 1.0;
+                    break;
+                }
+            }
+
+            $tagS = $tagScoreMap[$candidateId] ?? 0.0;
+            $behS = $behScoreMap[$candidateId] ?? 0.0;
+            $vecS = $vecScoreMap[$candidateId] ?? 0.0;
+
+            if ($vectorEnabled) {
+                $score = ($weights['visual'] ?? 0.45) * $vecS
+                       + ($weights['tag'] ?? 0.25) * $tagS
+                       + ($weights['behavior'] ?? 0.20) * $behS
+                       + ($weights['category'] ?? 0.10) * $catScore;
+            } else {
+                $score = ($weights['tag'] ?? 0.55) * $tagS
+                       + ($weights['behavior'] ?? 0.35) * $behS
+                       + ($weights['category'] ?? 0.10) * $catScore;
+            }
+
+            $scored[] = [
+                'artwork_id' => $candidateId,
+                'user_id'    => (int) $meta->user_id,
+                'cat_ids'    => $candidateCats,
+                'score'      => $score,
+            ];
+        }
+
+        usort($scored, fn (array $a, array $b) => $b['score'] <=> $a['score']);
+
+        // ── Diversity enforcement ──────────────────────────────────────────────
+        $authorCounts = [];
+        $final = [];
+        $catsInTop12 = [];
+
+        foreach ($scored as $item) {
+            $authorId = $item['user_id'];
+            $authorCounts[$authorId] = ($authorCounts[$authorId] ?? 0) + 1;
+
+            if ($authorCounts[$authorId] > $maxPerAuthor) {
+                continue;
+            }
+
+            $final[] = $item;
+
+            if (count($final) <= 12) {
+                foreach ($item['cat_ids'] as $cId) {
+                    $catsInTop12[$cId] = true;
+                }
+            }
+
+            if (count($final) >= $resultLimit) {
+                break;
+            }
+        }
+
+        // ── Min-categories enforcement in top 12 (spec §6) ────────────────────
+        if (count($catsInTop12) < $minCatsTop12 && count($final) >= 12) {
+            // Find items beyond the initial selection that introduce a new category
+            $usedIds = array_flip(array_column($final, 'artwork_id'));
+            $promotable = [];
+            foreach ($scored as $item) {
+                if (isset($usedIds[$item['artwork_id']])) {
+                    continue;
+                }
+                $newCats = array_diff($item['cat_ids'], array_keys($catsInTop12));
+                if ($newCats !== []) {
+                    $promotable[] = $item;
+                    if (count($promotable) >= ($minCatsTop12 - count($catsInTop12))) {
+                        break;
+                    }
+                }
+            }
+            // Inject promoted items at position 12 (end of visible top block)
+            if ($promotable !== []) {
+                $top = array_slice($final, 0, 11);
+                $rest = array_slice($final, 11);
+                $final = array_merge($top, $promotable, $rest);
+                $final = array_slice($final, 0, $resultLimit);
+            }
+        }
+
+        $finalIds = array_column($final, 'artwork_id');
+
+        if ($finalIds === []) {
+            return;
+        }
+
+        RecArtworkRec::query()->updateOrCreate(
+            [
+                'artwork_id'    => $artwork->id,
+                'rec_type'      => 'similar_hybrid',
+                'model_version' => $modelVersion,
+            ],
+            [
+                'recs'        => $finalIds,
+                'computed_at' => now(),
+            ],
+        );
+    }
+
+    /**
+     * Convert a ranked list of IDs into a score map (1.0 at rank 0, decaying).
+     *
+     * @param  list<int>  $ids
+     * @return array<int, float>
+     */
+    private function rankToScore(array $ids): array
+    {
+        $map = [];
+        $total = count($ids);
+        if ($total === 0) {
+            return $map;
+        }
+
+        foreach ($ids as $rank => $id) {
+            // Linear decay from 1.0 → ~0.0
+            $map[(int) $id] = 1.0 - ($rank / max(1, $total));
+        }
+
+        return $map;
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecalculateArtworkMedalStatsJob.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\ArtworkMedalService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class RecalculateArtworkMedalStatsJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(public readonly int $artworkId)
+    {
+    }
+
+    public function handle(ArtworkMedalService $medals): void
+    {
+        $medals->refreshArtworkMedalState($this->artworkId);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecalculateRisingNovaCardsJob.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\NovaCards\NovaCardRisingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class RecalculateRisingNovaCardsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function handle(NovaCardRisingService $risingService): void
+    {
+        $risingService->invalidateCache();
+        // Pre-warm the cache immediately so the next web request is fast.
+        $risingService->risingCards(36, cached: false);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RecomputeUserStatsJob.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\UserStatsService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Recomputes user_statistics for a batch of user IDs.
+ * Dispatched by RecomputeUserStatsCommand when --queue is set.
+ */
+class RecomputeUserStatsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries   = 2;
+    public int $timeout = 300;
+
+    /**
+     * @param  array<int>  $userIds
+     */
+    public function __construct(public readonly array $userIds) {}
+
+    public function handle(UserStatsService $statsService): void
+    {
+        foreach ($this->userIds as $userId) {
+            $statsService->recomputeUser((int) $userId);
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RefreshCollectionHealthJob.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Collection;
+use App\Models\User;
+use App\Services\CollectionHealthService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class RefreshCollectionHealthJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [30, 180, 600];
+
+    public function __construct(
+        public readonly int $collectionId,
+        public readonly ?int $actorUserId = null,
+        public readonly string $reason = 'queued-health-refresh',
+    ) {
+        $this->onQueue((string) config('collections.v5.queue.name', 'collections'));
+    }
+
+    public function handle(CollectionHealthService $health): void
+    {
+        $collection = Collection::query()->find($this->collectionId);
+
+        if (! $collection) {
+            return;
+        }
+
+        $actor = $this->actorUserId ? User::query()->find($this->actorUserId) : null;
+
+        $health->refresh($collection, $actor, $this->reason);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RefreshCollectionQualityJob.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Collection;
+use App\Models\User;
+use App\Services\CollectionWorkflowService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class RefreshCollectionQualityJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [30, 180, 600];
+
+    public function __construct(
+        public readonly int $collectionId,
+        public readonly ?int $actorUserId = null,
+    ) {
+        $this->onQueue((string) config('collections.v5.queue.name', 'collections'));
+    }
+
+    public function handle(CollectionWorkflowService $workflow): void
+    {
+        $collection = Collection::query()->find($this->collectionId);
+
+        if (! $collection) {
+            return;
+        }
+
+        $actor = $this->actorUserId ? User::query()->find($this->actorUserId) : null;
+
+        $workflow->qualityRefresh($collection->loadMissing('user'), $actor);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RefreshCollectionRecommendationJob.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Collection;
+use App\Models\User;
+use App\Services\CollectionHistoryService;
+use App\Services\CollectionRankingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class RefreshCollectionRecommendationJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [30, 180, 600];
+
+    public function __construct(
+        public readonly int $collectionId,
+        public readonly ?int $actorUserId = null,
+        public readonly string $context = 'default',
+    ) {
+        $this->onQueue((string) config('collections.v5.queue.name', 'collections'));
+    }
+
+    public function handle(CollectionRankingService $ranking): void
+    {
+        $collection = Collection::query()->find($this->collectionId);
+
+        if (! $collection) {
+            return;
+        }
+
+        $actor = $this->actorUserId ? User::query()->find($this->actorUserId) : null;
+        $fresh = $ranking->refresh($collection, $this->context);
+
+        app(CollectionHistoryService::class)->record(
+            $fresh,
+            $actor,
+            'recommendation_refreshed',
+            'Collection recommendations refreshed.',
+            null,
+            [
+                'context' => $this->context,
+                'recommendation_tier' => $fresh->recommendation_tier,
+                'ranking_bucket' => $fresh->ranking_bucket,
+                'search_boost_tier' => $fresh->search_boost_tier,
+            ]
+        );
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/RegenerateUserRecommendationCacheJob.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\Recommendations\RecommendationFeedResolver;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+final class RegenerateUserRecommendationCacheJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [10, 60, 180];
+
+    public function __construct(
+        public readonly int $userId,
+        public readonly string $algoVersion
+    ) {
+    }
+
+    public function handle(RecommendationFeedResolver $feedResolver): void
+    {
+        try {
+            $feedResolver->regenerateCacheForUser($this->userId, $this->algoVersion);
+        } catch (\Throwable $e) {
+            Log::error('RegenerateUserRecommendationCacheJob failed', [
+                'user_id' => $this->userId,
+                'algo_version' => $this->algoVersion,
+                'error' => $e->getMessage(),
+            ]);
+
+            throw $e;
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/ScanCollectionDuplicateCandidatesJob.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Collection;
+use App\Models\User;
+use App\Services\CollectionHealthService;
+use App\Services\CollectionMergeService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class ScanCollectionDuplicateCandidatesJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    /** @var array<int, int> */
+    public array $backoff = [30, 180, 600];
+
+    public function __construct(
+        public readonly int $collectionId,
+        public readonly ?int $actorUserId = null,
+        public readonly int $limit = 5,
+    ) {
+        $this->onQueue((string) config('collections.v5.queue.name', 'collections'));
+    }
+
+    public function handle(CollectionMergeService $merge, CollectionHealthService $health): void
+    {
+        $collection = Collection::query()->find($this->collectionId);
+
+        if (! $collection) {
+            return;
+        }
+
+        $actor = $this->actorUserId ? User::query()->find($this->actorUserId) : null;
+
+        $merge->syncSuggestedCandidates($collection, $actor, $this->limit);
+        $health->refresh($collection, $actor, 'duplicate-scan');
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/SendVerificationEmailJob.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Mail\RegistrationVerificationMail;
+use App\Services\Auth\RegistrationEmailQuotaService;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\RateLimiter;
+
+class SendVerificationEmailJob implements ShouldQueue
+{
+    use Queueable;
+
+    public int $tries = 5;
+
+    public function __construct(
+        public readonly int $emailEventId,
+        public readonly string $email,
+        public readonly string $token,
+        public readonly ?int $userId,
+        public readonly ?string $ip
+    ) {
+        $this->onQueue('mail');
+    }
+
+    public function handle(RegistrationEmailQuotaService $quotaService): void
+    {
+        $key = 'registration:verification-email:global';
+        $maxPerMinute = max(1, (int) config('registration.email_global_send_per_minute', 30));
+
+        $allowed = RateLimiter::attempt($key, $maxPerMinute, static fn () => true, 60);
+        if (! $allowed) {
+            $this->release(10);
+
+            return;
+        }
+
+        if ($quotaService->isExceeded()) {
+            $this->updateEvent('blocked', 'quota');
+
+            return;
+        }
+
+        Mail::to($this->email)->queue(new RegistrationVerificationMail($this->token));
+        $quotaService->incrementSentCount();
+
+        $this->updateEvent('sent', null);
+    }
+
+    private function updateEvent(string $status, ?string $reason): void
+    {
+        DB::table('email_send_events')
+            ->where('id', $this->emailEventId)
+            ->update([
+                'status' => $status,
+                'reason' => $reason,
+            ]);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/Sitemaps/BuildSitemapReleaseJob.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs\Sitemaps;
+
+use App\Services\Sitemaps\SitemapPublishService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class BuildSitemapReleaseJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(private readonly ?array $families = null, private readonly ?string $releaseId = null)
+    {
+        $this->onQueue('default');
+    }
+
+    public function handle(SitemapPublishService $publish): void
+    {
+        $publish->buildRelease($this->families, $this->releaseId);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/Sitemaps/CleanupSitemapReleasesJob.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs\Sitemaps;
+
+use App\Services\Sitemaps\SitemapReleaseCleanupService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class CleanupSitemapReleasesJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function handle(SitemapReleaseCleanupService $cleanup): void
+    {
+        $cleanup->cleanup();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/Sitemaps/PublishSitemapReleaseJob.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs\Sitemaps;
+
+use App\Services\Sitemaps\SitemapPublishService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class PublishSitemapReleaseJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(private readonly ?string $releaseId = null)
+    {
+        $this->onQueue('default');
+    }
+
+    public function handle(SitemapPublishService $publish): void
+    {
+        $publish->publish($this->releaseId);
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/SyncArtworkVectorIndexJob.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\Artwork;
+use App\Services\Vision\VectorService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+final class SyncArtworkVectorIndexJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public int $timeout = 30;
+
+    public function __construct(private readonly int $artworkId)
+    {
+        $queue = (string) config('recommendations.queue', config('vision.queue', 'default'));
+        if ($queue !== '') {
+            $this->onQueue($queue);
+        }
+    }
+
+    public function backoff(): array
+    {
+        return [2, 10, 30];
+    }
+
+    public function handle(VectorService $vectors): void
+    {
+        if (! $vectors->isConfigured()) {
+            return;
+        }
+
+        $artwork = Artwork::query()
+            ->with(['categories' => fn ($categories) => $categories->with('contentType')->orderBy('sort_order')->orderBy('name')])
+            ->find($this->artworkId);
+
+        if (! $artwork) {
+            return;
+        }
+
+        try {
+            $vectors->upsertArtwork($artwork);
+        } catch (\Throwable $e) {
+            Log::warning('SyncArtworkVectorIndexJob failed', [
+                'artwork_id' => $this->artworkId,
+                'error' => $e->getMessage(),
+            ]);
+
+            throw $e;
+        }
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/UpdateLeaderboardsJob.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Services\LeaderboardService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class UpdateLeaderboardsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $timeout = 1200;
+
+    public function handle(LeaderboardService $leaderboards): void
+    {
+        $leaderboards->refreshAll();
+    }
+}

.deploy/artwork-evolution-release/app/Jobs/UpdateNovaCardStatsJob.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\NovaCard;
+use App\Services\NovaCards\NovaCardTrendingService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class UpdateNovaCardStatsJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(private readonly int $cardId) {}
+
+    public function handle(NovaCardTrendingService $trending): void
+    {
+        $card = NovaCard::query()->find($this->cardId);
+        if (! $card) {
+            return;
+        }
+
+        $trending->refreshCard($card);
+    }
+}