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/unit/api/graceful-shutdown-order.test.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const source = readFileSync(resolve(root, "apps/api/src/index.ts"), "utf8");
+
+describe("API graceful shutdown order", () => {
+  it("drains BullMQ workers before force-stopping the Accurate OCR dispatcher", () => {
+    const shutdownStart = source.indexOf("async function shutdown(signal: string)");
+    const shutdownEnd = source.indexOf('process.on("SIGTERM"', shutdownStart);
+    const shutdownSource = source.slice(shutdownStart, shutdownEnd);
+    const closeWorkers = shutdownSource.indexOf("await closeWorkers();");
+    const shutdownOcrDispatcher = shutdownSource.indexOf("shutdownOcrDispatcher");
+
+    expect(shutdownStart).toBeGreaterThanOrEqual(0);
+    expect(shutdownEnd).toBeGreaterThan(shutdownStart);
+    expect(closeWorkers).toBeGreaterThanOrEqual(0);
+    expect(shutdownOcrDispatcher).toBeGreaterThanOrEqual(0);
+    expect(closeWorkers).toBeLessThan(shutdownOcrDispatcher);
+  });
+});