fix: release QA hardening across processing, media, security, and CI gates (#649)

A release-readiness QA pass over the whole product. The commits split into
defects a user would hit and gates that were reporting green while measuring
nothing.

## Fixes that change behaviour

Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so
request.ip came from a client-set header and a forged X-Forwarded-For got past
the login limiter. The default is now a private-network trust list.

A transient Postgres outage stranded in-flight jobs, leaving finished output on
disk with no row pointing at it. A reconciler now resolves those rows and adopts
the bytes rather than dropping the work.

A Redis connection that moved to a new address wedged every read-blocked
consumer, so completions stopped signalling while health still answered 200.
Socket timeouts plus subscriber pings recover it.

Installing more than one AI bundle left the shared venv multi-versioned and
silently broke three tools. The installer now reconciles distributions to one
version each.

Converting an image to JXL at quality 1 through 4 returned a 500, because
libjxl 0.7 rejects the distance those values compute. The quality is floored at
what the encoder honours. A missing ffmpeg was also reported to the user as a
corrupt upload; it now says the engine is unavailable.

RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at
0.22.2, and the release scan was split so it can fail on an unfixed critical
instead of hiding it behind ignore-unfixed.

## Gates that could not fail

Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs
build; coverage discarded its whole report on any failing test; the lint gate
skipped root tests, scripts, and two workspaces; and several generated matrices
counted a host missing ffmpeg as a passing tool. Each now measures what it
claims.

Full evidence and the outstanding release items are tracked locally and are not
part of this branch.

tests/integration/tools/video/auto-subtitles.test.ts

@@ -1,15 +1,22 @@
 /**
  * Integration tests for the auto-subtitles tool (/api/v1/tools/video/auto-subtitles).
  *
- * The transcription bundle (faster-whisper) is not installed locally, so the
- * 501 gate is always hit. Validation paths (bad settings) fire after the 501
- * check. The bundle-gated happy path lives in a skipped describe for
- * in-container-after-install runs.
+ * Missing-bundle contracts run only when the transcription capability is
+ * absent. Installed happy paths run when the capability is detected or when
+ * REQUIRE_AI_FEATURES makes its absence a release-gate failure.
  */
 
 import { readFileSync } from "node:fs";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { isToolInstalled } from "../../../../apps/api/src/lib/feature-status.js";
 import { fixtures } from "../../../fixtures/index.js";
+import { installedAiCapabilityGate } from "../../../helpers/installed-ai-capability-gate.js";
+import {
+  expectKnownTranscript,
+  expectSrtArtifact,
+  expectVttArtifact,
+} from "../../../helpers/installed-ai-output-oracles.js";
+import { waitForDownloadedJobArtifact } from "../../settle-job.js";
 import {
   buildTestApp,
   createMultipartPayload,
@@ -18,6 +25,13 @@ import {
 } from "../../test-server.js";
 
 const MP4 = readFileSync(fixtures.video.tiny("mp4"));
+const SPEECH_MP4 = readFileSync(fixtures.video.speech.mp4);
+const REQUIRE_AI_FEATURES = process.env.REQUIRE_AI_FEATURES === "1";
+const AI_CAPABILITY = installedAiCapabilityGate(
+  "auto-subtitles",
+  REQUIRE_AI_FEATURES,
+  isToolInstalled,
+);
 
 let testApp: TestApp;
 let app: TestApp["app"];
@@ -34,68 +48,74 @@ afterAll(async () => {
 }, 10_000);
 
 describe("auto-subtitles", () => {
-  // -- 501 gate (always fires locally: bundle never installed) --
+  // -- Missing-capability contract --
 
-  it("returns 501 FEATURE_NOT_INSTALLED when bundle is absent", async () => {
-    const { body, contentType } = createMultipartPayload([
-      {
-        name: "file",
-        filename: "tiny.mp4",
-        contentType: "video/mp4",
-        content: MP4,
-      },
-      { name: "settings", content: JSON.stringify({}) },
-    ]);
+  it.skipIf(!AI_CAPABILITY.runUnavailableContract)(
+    "returns 501 FEATURE_NOT_INSTALLED when bundle is absent",
+    async () => {
+      const { body, contentType } = createMultipartPayload([
+        {
+          name: "file",
+          filename: "tiny.mp4",
+          contentType: "video/mp4",
+          content: MP4,
+        },
+        { name: "settings", content: JSON.stringify({}) },
+      ]);
 
-    const res = await app.inject({
-      method: "POST",
-      url: "/api/v1/tools/video/auto-subtitles",
-      headers: {
-        authorization: `Bearer ${adminToken}`,
-        "content-type": contentType,
-      },
-      body,
-    });
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/v1/tools/video/auto-subtitles",
+        headers: {
+          authorization: `Bearer ${adminToken}`,
+          "content-type": contentType,
+        },
+        body,
+      });
 
-    expect(res.statusCode).toBe(501);
-    const json = JSON.parse(res.body);
-    expect(json.code).toBe("FEATURE_NOT_INSTALLED");
-    expect(json.feature).toBe("transcription");
-    expect(json.featureName).toBe("Transcription");
-    expect(json.estimatedSize).toBeDefined();
-  });
+      expect(res.statusCode).toBe(501);
+      const json = JSON.parse(res.body);
+      expect(json.code).toBe("FEATURE_NOT_INSTALLED");
+      expect(json.feature).toBe("transcription");
+      expect(json.featureName).toBe("Transcription");
+      expect(json.estimatedSize).toBeDefined();
+    },
+  );
 
   // -- Validation (501 fires before settings parse, so these also 501) --
 
-  it("returns 501 even with invalid format (gate fires first)", async () => {
-    const { body, contentType } = createMultipartPayload([
-      {
-        name: "file",
-        filename: "tiny.mp4",
-        contentType: "video/mp4",
-        content: MP4,
-      },
-      {
-        name: "settings",
-        content: JSON.stringify({ format: "ass" }),
-      },
-    ]);
+  it.skipIf(!AI_CAPABILITY.runUnavailableContract)(
+    "returns 501 even with invalid format (gate fires first)",
+    async () => {
+      const { body, contentType } = createMultipartPayload([
+        {
+          name: "file",
+          filename: "tiny.mp4",
+          contentType: "video/mp4",
+          content: MP4,
+        },
+        {
+          name: "settings",
+          content: JSON.stringify({ format: "ass" }),
+        },
+      ]);
 
-    const res = await app.inject({
-      method: "POST",
-      url: "/api/v1/tools/video/auto-subtitles",
-      headers: {
-        authorization: `Bearer ${adminToken}`,
-        "content-type": contentType,
-      },
-      body,
-    });
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/v1/tools/video/auto-subtitles",
+        headers: {
+          authorization: `Bearer ${adminToken}`,
+          "content-type": contentType,
+        },
+        body,
+      });
 
-    // 501 because the bundle gate fires before settings validation
-    expect(res.statusCode).toBe(501);
-    const json = JSON.parse(res.body);
-    expect(json.code).toBe("FEATURE_NOT_INSTALLED");
-  });
+      // 501 because the bundle gate fires before settings validation
+      expect(res.statusCode).toBe(501);
+      const json = JSON.parse(res.body);
+      expect(json.code).toBe("FEATURE_NOT_INSTALLED");
+    },
+  );
 
   it("rejects unauthenticated requests (401)", async () => {
     const { body, contentType } = createMultipartPayload([
@@ -118,71 +138,93 @@ describe("auto-subtitles", () => {
     expect(res.statusCode).toBe(401);
   });
 
-  // -- Bundle-gated happy path (skipped locally, runs after bundle install) --
+  // -- Installed/required capability contract --
 
-  // The transcription bundle is ~600 MB and only available in Docker.
-  // These tests run when the bundle is installed (e.g., during Task 7 smoke).
-  // Locally they always skip.
-  describe.skip("with transcription bundle installed", () => {
-    it("generates subtitles from video (202 + async)", async () => {
-      const { body, contentType } = createMultipartPayload([
-        {
-          name: "file",
-          filename: "tiny.mp4",
-          contentType: "video/mp4",
-          content: MP4,
-        },
-        {
-          name: "settings",
-          content: JSON.stringify({ format: "srt" }),
-        },
-      ]);
+  describe.skipIf(!AI_CAPABILITY.runInstalledContract)(
+    "with transcription bundle installed",
+    () => {
+      it("generates subtitles from video (202 + async)", async () => {
+        const { body, contentType } = createMultipartPayload([
+          {
+            name: "file",
+            filename: "speech-10s.mp4",
+            contentType: "video/mp4",
+            content: SPEECH_MP4,
+          },
+          {
+            name: "settings",
+            content: JSON.stringify({ format: "srt" }),
+          },
+        ]);
 
-      const res = await app.inject({
-        method: "POST",
-        url: "/api/v1/tools/video/auto-subtitles",
-        headers: {
-          authorization: `Bearer ${adminToken}`,
-          "content-type": contentType,
-        },
-        body,
-      });
+        const res = await app.inject({
+          method: "POST",
+          url: "/api/v1/tools/video/auto-subtitles",
+          headers: {
+            authorization: `Bearer ${adminToken}`,
+            "content-type": contentType,
+          },
+          body,
+        });
 
-      expect(res.statusCode).toBe(202);
-      const json = JSON.parse(res.body);
-      expect(json.jobId).toBeDefined();
-      expect(json.async).toBe(true);
-    }, 120_000);
+        expect(res.statusCode).toBe(202);
+        const json = JSON.parse(res.body);
+        expect(json.jobId).toBeDefined();
+        expect(json.async).toBe(true);
+        const artifact = await waitForDownloadedJobArtifact(
+          app,
+          adminToken,
+          "auto-subtitles",
+          json.jobId as string,
+          240_000,
+        );
+        expect(artifact.filename).toBe("speech-10s.srt");
+        expect(artifact.contentType).toBe("application/x-subrip");
+        const subtitles = artifact.buffer.toString("utf8");
+        expectSrtArtifact(subtitles);
+        expectKnownTranscript(subtitles);
+      }, 300_000);
 
-    it("generates VTT subtitles from video", async () => {
-      const { body, contentType } = createMultipartPayload([
-        {
-          name: "file",
-          filename: "tiny.mp4",
-          contentType: "video/mp4",
-          content: MP4,
-        },
-        {
-          name: "settings",
-          content: JSON.stringify({ format: "vtt" }),
-        },
-      ]);
+      it("generates VTT subtitles from video", async () => {
+        const { body, contentType } = createMultipartPayload([
+          {
+            name: "file",
+            filename: "speech-10s.mp4",
+            contentType: "video/mp4",
+            content: SPEECH_MP4,
+          },
+          {
+            name: "settings",
+            content: JSON.stringify({ format: "vtt" }),
+          },
+        ]);
 
-      const res = await app.inject({
-        method: "POST",
-        url: "/api/v1/tools/video/auto-subtitles",
-        headers: {
-          authorization: `Bearer ${adminToken}`,
-          "content-type": contentType,
-        },
-        body,
-      });
+        const res = await app.inject({
+          method: "POST",
+          url: "/api/v1/tools/video/auto-subtitles",
+          headers: {
+            authorization: `Bearer ${adminToken}`,
+            "content-type": contentType,
+          },
+          body,
+        });
 
-      expect(res.statusCode).toBe(202);
-      const json = JSON.parse(res.body);
-      expect(json.jobId).toBeDefined();
-      // Full VTT structure validation (WEBVTT header, dot timestamps)
-      // happens after polling completes in the Task 7 smoke.
-    }, 120_000);
-  });
+        expect(res.statusCode).toBe(202);
+        const json = JSON.parse(res.body);
+        expect(json.jobId).toBeDefined();
+        const artifact = await waitForDownloadedJobArtifact(
+          app,
+          adminToken,
+          "auto-subtitles",
+          json.jobId as string,
+          240_000,
+        );
+        expect(artifact.filename).toBe("speech-10s.vtt");
+        expect(artifact.contentType).toBe("text/vtt");
+        const subtitles = artifact.buffer.toString("utf8");
+        expectVttArtifact(subtitles);
+        expectKnownTranscript(subtitles);
+      }, 300_000);
+    },
+  );
 });

tests/integration/tools/video/burn-subtitles.test.ts

@@ -57,7 +57,10 @@ async function resolveResult(res: Awaited<ReturnType<typeof testApp.app.inject>>
     await new Promise((r) => setTimeout(r, 500));
   }
   expect(row?.status).toBe("completed");
-  const outName = (row?.outputRefs as string[])[0].split("/").pop() as string;
+  if (!Array.isArray(row?.outputRefs) || typeof row.outputRefs[0] !== "string") {
+    throw new Error("Completed burn-subtitles job has no output reference");
+  }
+  const outName = row.outputRefs[0].split("/").pop() as string;
   const dl = await testApp.app.inject({
     method: "GET",
     url: `/api/v1/download/${jobId}/${encodeURIComponent(outName)}`,
@@ -132,4 +135,20 @@ describe.skipIf(!ffmpegAvailable())("burn-subtitles (requires ffmpeg)", () => {
     const parsed = JSON.parse(res.body);
     expect(parsed.error).toMatch(/subtitle/i);
   }, 60_000);
+
+  it("rejects a missing subtitle before enqueue", async () => {
+    const { body, contentType } = createMultipartPayload([
+      { name: "file", filename: "tiny.mp4", contentType: "video/mp4", content: MP4 },
+      { name: "settings", content: JSON.stringify({}) },
+    ]);
+    const res = await testApp.app.inject({
+      method: "POST",
+      url: "/api/v1/tools/video/burn-subtitles",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toMatch(/at least 2 files/i);
+  });
 });

tests/integration/tools/video/embed-subtitles.test.ts

@@ -71,4 +71,20 @@ describe.skipIf(!ffmpegAvailable())("embed-subtitles (requires ffmpeg)", () => {
 
     expect(res.statusCode).toBe(400);
   }, 60_000);
+
+  it("rejects a missing subtitle before enqueue", async () => {
+    const { body, contentType } = createMultipartPayload([
+      { name: "file", filename: "tiny.mp4", contentType: "video/mp4", content: MP4 },
+      { name: "settings", content: JSON.stringify({}) },
+    ]);
+    const res = await testApp.app.inject({
+      method: "POST",
+      url: "/api/v1/tools/video/embed-subtitles",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toMatch(/at least 2 files/i);
+  });
 });

tests/integration/tools/video/images-to-video.test.ts

@@ -65,7 +65,7 @@ describe.skipIf(!ffmpegAvailable())("images-to-video (requires ffmpeg)", () => {
     expect(v?.height).toBe(720);
   }, 60_000);
 
-  it("rejects a single image with 422", async () => {
+  it("rejects a single image with 400 before enqueue", async () => {
     const { body, contentType } = createMultipartPayload([
       { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG },
       { name: "settings", content: JSON.stringify({}) },
@@ -77,9 +77,8 @@ describe.skipIf(!ffmpegAvailable())("images-to-video (requires ffmpeg)", () => {
       body,
     });
 
-    // fast hint: inline 422
-    expect(res.statusCode).toBe(422);
+    expect(res.statusCode).toBe(400);
     const parsed = JSON.parse(res.body);
-    expect(parsed.details).toMatch(/at least two images/i);
+    expect(parsed.error).toMatch(/at least 2 files/i);
   }, 60_000);
 });

tests/integration/tools/video/merge-videos.test.ts

@@ -54,7 +54,10 @@ async function resolveResult(res: Awaited<ReturnType<typeof testApp.app.inject>>
     await new Promise((r) => setTimeout(r, 500));
   }
   expect(row?.status).toBe("completed");
-  const outName = (row?.outputRefs as string[])[0].split("/").pop() as string;
+  if (!Array.isArray(row?.outputRefs) || typeof row.outputRefs[0] !== "string") {
+    throw new Error("Completed merge-videos job has no output reference");
+  }
+  const outName = row.outputRefs[0].split("/").pop() as string;
   const dl = await testApp.app.inject({
     method: "GET",
     url: `/api/v1/download/${jobId}/${encodeURIComponent(outName)}`,
@@ -116,28 +119,7 @@ describe.skipIf(!ffmpegAvailable())("merge-videos (requires ffmpeg)", () => {
       body,
     });
 
-    // merge-videos has executionHint "long", so 202 is returned immediately.
-    // The worker then fails with InputValidationError. Poll for the failure.
-    expect(res.statusCode).toBe(202);
-    const { jobId } = JSON.parse(res.body);
-    expect(jobId).toBeDefined();
-
-    const { db, schema } = await import("../../../../apps/api/src/db/index.js");
-    const { eq } = await import("drizzle-orm");
-    let row: { status: string; error: unknown } | undefined;
-    for (let i = 0; i < 60; i++) {
-      [row] = await db
-        .select({ status: schema.jobs.status, error: schema.jobs.error })
-        .from(schema.jobs)
-        .where(eq(schema.jobs.id, jobId));
-      if (row && ["completed", "failed", "canceled"].includes(row.status)) break;
-      await new Promise((r) => setTimeout(r, 500));
-    }
-
-    // Observed behavior: 202 (async) -> job status "failed" with error message.
-    // The plan noted "400/422" but long-hint tools skip the sync window.
-    expect(row?.status).toBe("failed");
-    const error = row?.error as { message?: string } | null;
-    expect(error?.message).toMatch(/at least two/i);
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toMatch(/at least 2 files/i);
   }, 60_000);
 });

tests/integration/tools/video/replace-audio.test.ts

@@ -94,10 +94,8 @@ describe.skipIf(!ffmpegAvailable())("replace-audio (requires ffmpeg)", () => {
       body,
     });
 
-    // Fast-hint tool: processV2 checks input count and throws,
-    // caught by the factory's generic catch -> 422.
-    expect(res.statusCode).toBe(422);
+    expect(res.statusCode).toBe(400);
     const parsed = JSON.parse(res.body);
-    expect(parsed.details).toMatch(/video and an audio/i);
+    expect(parsed.error).toMatch(/at least 2 files/i);
   }, 60_000);
 });

tests/integration/tools/video/video-to-gif.test.ts

@@ -1,6 +1,11 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { ffmpegAvailable } from "@snapotter/media-engine";
 import sharp from "sharp";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { InputValidationError } from "../../../../apps/api/src/modality/contract.js";
+import { getToolConfig } from "../../../../apps/api/src/routes/tool-factory.js";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
 import {
   buildTestApp,
@@ -36,6 +41,48 @@ async function pollJob(jobId: string) {
 }
 
 describe.skipIf(!ffmpegAvailable())("video-to-gif (requires ffmpeg)", () => {
+  it("normalizes sub-microsecond offsets instead of emitting exponential ffmpeg syntax", async () => {
+    const config = getToolConfig("video-to-gif");
+    if (!config?.processV2) throw new Error("video-to-gif processV2 must be registered");
+    const scratchDir = await mkdtemp(join(tmpdir(), "snapotter-video-to-gif-test-"));
+
+    try {
+      const result = await config.processV2({
+        inputs: [{ buffer: MP4, filename: "tiny.mp4", ref: "test/tiny.mp4" }],
+        settings: { fps: 1, width: 120, startS: Number.MIN_VALUE, durationS: 1 },
+        scratchDir,
+        signal: new AbortController().signal,
+        report: () => undefined,
+      });
+      if (!result.scratchPath) throw new Error("video-to-gif must return a scratch path");
+      const output = await readFile(result.scratchPath);
+      expect(output.subarray(0, 4).toString("ascii")).toBe("GIF8");
+    } finally {
+      await rm(scratchDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects a start time beyond the video instead of running an empty encode", async () => {
+    const config = getToolConfig("video-to-gif");
+    if (!config?.processV2) throw new Error("video-to-gif processV2 must be registered");
+    const processV2 = config.processV2;
+    const scratchDir = await mkdtemp(join(tmpdir(), "snapotter-video-to-gif-test-"));
+
+    try {
+      await expect(
+        processV2({
+          inputs: [{ buffer: MP4, filename: "tiny.mp4", ref: "test/tiny.mp4" }],
+          settings: { fps: 1, width: 672, startS: 2, durationS: 1 },
+          scratchDir,
+          signal: new AbortController().signal,
+          report: () => undefined,
+        }),
+      ).rejects.toBeInstanceOf(InputValidationError);
+    } finally {
+      await rm(scratchDir, { recursive: true, force: true });
+    }
+  });
+
   it("returns 202 (long hint) and produces a GIF with GIF8 magic", async () => {
     const { body, contentType } = createMultipartPayload([
       { name: "file", filename: "tiny.mp4", contentType: "video/mp4", content: MP4 },