Run document summaries and filing suggestions in the background

The summary and suggest routes accept `Prefer: respond-async`: after the
same quick refusals they answer 202 with a run id, and the background
document AI worker runs the read under two new run kinds
(DOCUMENT_SUMMARY, DOCUMENT_SUGGEST, migration 0370). Without the header
both routes answer synchronously as before; both paths run one shared
body, so they cannot drift.

The worker asks the capability for the record and re-checks the wire for
the provider it picks before every read. A summary that is to be stored
marks the document PENDING while queued, READY when it lands, and
UNAVAILABLE when the run fails or the write does not land. A second
request attaches to a live run only when it would produce the same thing.

The vault asks for both in the background and shows the same calm
waiting line the index uses, worded so a transient read never promises
that leaving the page keeps it. The egress guard and the route inventory
now hold every run kind to its dispatcher re-check and its capability.
This commit is contained in:
Marc-André Bombeck committed 2026-10-03 20:51:57 +02:00
1 parent 7cd323499e
commit eda5776886
24 files changed
+2061 -800

No files matched your search

@@ -20,6 +20,11 @@
* files (`tests/integration/ai-optional-*.test.ts`) prove behaviour; this
* proves no route escapes classification and no data route grows a gate.
*
* 5. Every kind of background run (`DOCUMENT_AI_RUN_KINDS`) is queued by a
* route on `AI_ROUTES` that asks the capability the worker asks again for
* that kind (`DOCUMENT_AI_RUN_CAPABILITY`), so a run cannot answer to a
* different switch than the request that started it.
*
* Mutation checks (each turned this file red by name): adding
* `await requireAiCapability("statusText")` to `insights/ecg/route.ts`;
* removing the capability call from `insights/chat/route.ts`; swapping
@@ -31,6 +36,11 @@ import { join, relative, resolve } from "node:path";
import { describe, expect, it } from "vitest";
import { AI_CAPABILITY_KEYS } from "@/lib/ai/capabilities/types";
import {
DOCUMENT_AI_RUN_CAPABILITY,
DOCUMENT_AI_RUN_KINDS,
type DocumentAiRunKindValue,
} from "@/lib/documents/ai-runs/types";
import { AI_ROUTES, DATA_ROUTES } from "./ai-route-inventory";
@@ -154,3 +164,27 @@ describe("AI capability route inventory", () => {
expect(both).toEqual([]);
});
});
/** The route that queues each kind of background run. */
const RUN_QUEUED_BY: Record<DocumentAiRunKindValue, string> = {
DOCUMENT_INDEX: "src/app/api/documents/inbound/[id]/index/route.ts",
LABS_OCR_EXTRACT: "src/app/api/labs/ocr/extract/route.ts",
DOCUMENT_SUMMARY: "src/app/api/documents/inbound/[id]/summary/route.ts",
DOCUMENT_SUGGEST: "src/app/api/documents/inbound/[id]/suggest/route.ts",
};
describe("background run kinds", () => {
it.each(DOCUMENT_AI_RUN_KINDS)(
"%s is queued by an AI route under the capability the worker re-checks",
(kind) => {
const path = RUN_QUEUED_BY[kind];
const entry = AI_ROUTES[path];
expect(entry, `${path} is not on AI_ROUTES`).toBeDefined();
expect(entry.capabilities).toContain(DOCUMENT_AI_RUN_CAPABILITY[kind]);
expect(
new RegExp(`kind:\\s*"${kind}"`).test(code(path)),
`${path} does not queue ${kind}`,
).toBe(true);
},
);
});