Ship production optimization M1-M12.5A: queues, metrics, HTTP observability, and vector search reliability.

Keep similar-ai from tripping the global circuit on a lone URL 502, clamp Qdrant search to 100, and add Server-Timing plus slow-request logging. Studio shared props, Academy S3 exists caching, heat chunking, and Redis/scheduler hygiene stay in this rollout.

app/Http/Controllers/Api/SimilarAiArtworksController.php

@@ -6,10 +6,12 @@ namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Controller;
 use App\Models\Artwork;
+use App\Services\Vision\VectorGatewayException;
 use App\Services\Vision\VectorService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
-use RuntimeException;
+use Illuminate\Support\Facades\Log;
+use Throwable;
 
 final class SimilarAiArtworksController extends Controller
 {
@@ -35,11 +37,12 @@ final class SimilarAiArtworksController extends Controller
 
         try {
             $items = $this->vectors->similarToArtwork($artwork, $limit);
-        } catch (RuntimeException $e) {
+        } catch (Throwable $e) {
+            $this->logSimilarityFailure($artwork->id, $e);
+
             return response()->json([
                 'data' => [],
                 'reason' => 'vector_gateway_error',
-                'message' => $e->getMessage(),
             ], 502);
         }
 
@@ -52,4 +55,19 @@ final class SimilarAiArtworksController extends Controller
             ],
         ]);
     }
+
+    private function logSimilarityFailure(int $artworkId, Throwable $e): void
+    {
+        $gateway = $e instanceof VectorGatewayException ? $e : null;
+
+        Log::warning('Vector similarity search failed', [
+            'artwork_id' => $artworkId,
+            'route' => 'api.art.similar-ai',
+            'failure_stage' => $gateway?->operation ?? 'unknown',
+            'exception_class' => $e::class,
+            'http_status' => $gateway?->httpStatus,
+            'circuit_worthy' => $gateway?->circuitWorthy ?? false,
+            'circuit_open' => app(\App\Services\Vision\VectorGatewayClient::class)->circuitOpen(),
+        ]);
+    }
 }

app/Http/Controllers/ArtworkDownloadController.php

@@ -58,6 +58,16 @@ final class ArtworkDownloadController extends Controller
             abort(404);
         }
 
+        if (! File::isFile($filePath)) {
+            Log::warning('Artwork original file missing for download.', [
+                'artwork_id' => $artwork->id,
+                'ext' => $ext,
+                'resolved_path' => $filePath,
+            ]);
+
+            abort(404);
+        }
+
         $this->recordDownload($request, $artwork->id);
         $this->incrementDownloadCountIfAvailable($artwork->id);
 
@@ -70,16 +80,6 @@ final class ArtworkDownloadController extends Controller
             ]);
         }
 
-        if (! File::isFile($filePath)) {
-            Log::warning('Artwork original file missing for download.', [
-                'artwork_id' => $artwork->id,
-                'ext' => $ext,
-                'resolved_path' => $filePath,
-            ]);
-
-            abort(404);
-        }
-
         $downloadName = $this->buildDownloadFilename((string) $artwork->file_name, $ext);
 
         // X-Accel-Redirect is safe only when nginx is explicitly configured to

app/Http/Controllers/SitemapController.php

@@ -22,6 +22,18 @@ final class SitemapController extends Controller
 
     public function index(): Response|BinaryFileResponse
     {
+        if ((bool) config('sitemaps.pre_generated.enabled', true)) {
+            foreach ([
+                public_path('sitemaps/index.xml'),
+                public_path('sitemaps/sitemap.xml'),
+                public_path('sitemap.xml'),
+            ] as $path) {
+                if (is_file($path) && is_readable($path)) {
+                    return $this->xmlFileResponse($path);
+                }
+            }
+        }
+
         // 1. Published release (release management pipeline fallback).
         $published = $this->published->resolveIndex();
         if ($published !== null) {