fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

tests/integration/platform/progress-transport.test.ts

@@ -13,9 +13,13 @@
  */
 import { randomUUID } from "node:crypto";
 import { eq } from "drizzle-orm";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { db, schema } from "../../../apps/api/src/db/index.js";
-import { updateSingleFileProgress } from "../../../apps/api/src/routes/progress.js";
+import { sharedRedis } from "../../../apps/api/src/jobs/connection.js";
+import {
+  publishEphemeral,
+  updateSingleFileProgress,
+} from "../../../apps/api/src/routes/progress.js";
 import { buildTestApp, loginAsAdmin, type TestApp } from "../test-server.js";
 
 let testApp: TestApp;
@@ -33,11 +37,62 @@ afterAll(async () => {
 }, 10_000);
 
 describe("Redis progress transport", () => {
+  it("cannot miss a terminal publish while the connection is replaying prior state", async () => {
+    const jobId = `tp-replay-race-${randomUUID()}`;
+    const redis = sharedRedis();
+    const originalGet = redis.get.bind(redis);
+    let injected = false;
+    const getSpy = vi.spyOn(redis, "get").mockImplementation(async (key) => {
+      const cached = await originalGet(key);
+      if (!injected && String(key).endsWith(`terminal:${jobId}`)) {
+        injected = true;
+        publishEphemeral({
+          jobId,
+          type: "single",
+          phase: "complete",
+          percent: 100,
+          result: { text: "published during replay" },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      return cached;
+    });
+
+    try {
+      const responsePromise = app.inject({
+        method: "GET",
+        url: `/api/v1/jobs/${jobId}/progress`,
+        headers: { authorization: `Bearer ${adminToken}` },
+      });
+      const settledDuringReplay = await Promise.race([
+        responsePromise.then(() => true),
+        new Promise<false>((resolve) => setTimeout(() => resolve(false), 500)),
+      ]);
+
+      // Let a broken implementation settle too, so this regression test never
+      // leaks an open SSE request into suite teardown.
+      if (!settledDuringReplay) {
+        publishEphemeral({
+          jobId,
+          type: "single",
+          phase: "failed",
+          percent: 100,
+          error: "cleanup terminal",
+        });
+      }
+      const response = await responsePromise;
+      expect(settledDuringReplay).toBe(true);
+      expect(response.body).toContain("published during replay");
+    } finally {
+      getSpy.mockRestore();
+    }
+  });
+
   it("replays a terminal single-file event from the Redis terminal key", async () => {
     const jobId = `tp-${randomUUID()}`;
 
     // Publish a terminal event
-    updateSingleFileProgress({
+    await updateSingleFileProgress({
       jobId,
       phase: "complete",
       percent: 100,
@@ -86,6 +141,9 @@ describe("Redis progress transport", () => {
     expect(job).toBeDefined();
     expect(job!.status).toBe("completed");
     expect(job!.type).toBe("single");
+    expect((job?.progress as { result?: { downloadUrl?: string } })?.result?.downloadUrl).toBe(
+      "/x",
+    );
 
     // Clean up
     await db.delete(schema.jobs).where(eq(schema.jobs.id, jobId));
@@ -126,10 +184,43 @@ describe("Redis progress transport", () => {
     await db.delete(schema.jobs).where(eq(schema.jobs.id, jobId));
   });
 
-  it("synthesizes a legacy event from the DB when terminal key has expired", async () => {
+  it("replays a durable completed result from the DB when the terminal key has expired", async () => {
     const jobId = `tp-db-${randomUUID()}`;
 
     // Insert a completed row directly (simulating expired terminal key)
+    await db.insert(schema.jobs).values({
+      id: jobId,
+      type: "single",
+      status: "completed",
+      progress: { percent: 100, result: { downloadUrl: "/durable-result" } },
+      inputRefs: [],
+      completedAt: new Date(),
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: `/api/v1/jobs/${jobId}/progress`,
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const dataMatch = res.body.match(/data: (.+)/);
+    if (!dataMatch) throw new Error("Expected an SSE data frame");
+    const event = JSON.parse(dataMatch[1]);
+    expect(event.type).toBe("single");
+    expect(event.phase).toBe("complete");
+    expect(event.percent).toBe(100);
+    expect(event.result?.downloadUrl).toBe("/durable-result");
+
+    // Clean up
+    await db.delete(schema.jobs).where(eq(schema.jobs.id, jobId));
+  });
+
+  it("settles legacy completed rows whose result is no longer available", async () => {
+    const jobId = `tp-db-legacy-${randomUUID()}`;
+
     await db.insert(schema.jobs).values({
       id: jobId,
       type: "single",
@@ -149,11 +240,11 @@ describe("Redis progress transport", () => {
 
     expect(res.statusCode).toBe(200);
     const dataMatch = res.body.match(/data: (.+)/);
-    expect(dataMatch).not.toBeNull();
-    const event = JSON.parse(dataMatch![1]);
+    if (!dataMatch) throw new Error("Expected an SSE data frame");
+    const event = JSON.parse(dataMatch[1]);
     expect(event.type).toBe("single");
-    expect(event.phase).toBe("complete");
-    expect(event.percent).toBe(100);
+    expect(event.phase).toBe("failed");
+    expect(event.error).toContain("result is no longer available");
 
     // Clean up
     await db.delete(schema.jobs).where(eq(schema.jobs.id, jobId));