Merge branch 'worktree-agent-a908bda23e0007c88' into release/v1.30.31

This commit is contained in:
Marc-André Bombeck committed 2026-07-19 10:07:42 +02:00
commit cd502d5aef
20 files changed
+818 -82

No files matched your search

@@ -0,0 +1,105 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { _resetCryptoCacheForTests } from "@/lib/crypto";
import {
encryptDocumentSummary,
serialiseDocumentDetail,
type SerialisableDocument,
} from "@/lib/documents/store";
/**
* What the detail DTO says about a summary has to match what the user can
* actually see. The state column is the source of truth for the four outcomes,
* with one exception the view depends on: a READY row whose ciphertext will not
* open has no summary to render, so reporting READY would leave a heading over
* nothing.
*/
const KEY_V1 =
"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
beforeEach(() => {
vi.unstubAllEnvs();
vi.stubEnv("ENCRYPTION_KEYS", "");
vi.stubEnv("ENCRYPTION_ACTIVE_KEY_ID", "");
vi.stubEnv("ENCRYPTION_KEY", KEY_V1);
_resetCryptoCacheForTests();
});
function row(overrides: Partial<SerialisableDocument> = {}) {
return {
id: "doc-1",
userId: "user-1",
kind: "OTHER",
title: "Discharge letter",
filename: "letter.pdf",
mimeType: "application/pdf",
byteSize: 1024,
contentCodec: "binary2",
contentSha256: null,
status: "STORED",
providerType: null,
reportDate: null,
documentDate: null,
errorReason: null,
summaryEncrypted: null,
summaryGeneratedAt: null,
summaryState: "NONE",
createdAt: new Date("2026-02-14T00:00:00Z"),
updatedAt: new Date("2026-02-14T00:00:00Z"),
deletedAt: null,
...overrides,
} as unknown as SerialisableDocument;
}
describe("serialiseDocumentDetail — summary state", () => {
it("returns the stored summary as READY", () => {
const dto = serialiseDocumentDetail(
row({
summaryEncrypted: encryptDocumentSummary("A discharge letter."),
summaryGeneratedAt: new Date("2026-02-15T09:00:00Z"),
summaryState: "READY",
}),
[],
);
expect(dto.summary).toBe("A discharge letter.");
expect(dto.summaryState).toBe("READY");
expect(dto.summaryGeneratedAt).toBe("2026-02-15T09:00:00.000Z");
});
it.each(["NONE", "PENDING", "WITHHELD", "UNAVAILABLE"] as const)(
"passes %s through with no summary",
(summaryState) => {
const dto = serialiseDocumentDetail(row({ summaryState }), []);
expect(dto.summary).toBeNull();
expect(dto.summaryState).toBe(summaryState);
},
);
it("degrades an undecryptable READY row to UNAVAILABLE", () => {
// A rotated-away key. There is no summary to show, so the DTO must not
// keep promising one — and the ciphertext is never returned either.
const dto = serialiseDocumentDetail(
row({
summaryEncrypted: new TextEncoder().encode("not-ciphertext"),
summaryState: "READY",
}),
[],
);
expect(dto.summary).toBeNull();
expect(dto.summaryState).toBe("UNAVAILABLE");
});
it("degrades a READY row with no ciphertext at all to UNAVAILABLE", () => {
const dto = serialiseDocumentDetail(
row({ summaryEncrypted: null, summaryState: "READY" }),
[],
);
expect(dto.summary).toBeNull();
expect(dto.summaryState).toBe("UNAVAILABLE");
});
});
+12
View File
@@ -20,6 +20,7 @@ import { servingClassFor } from "@/lib/documents/upload-policy";
import type {
DocumentConditionLinkDto,
DocumentContentIndexSourceValue,
DocumentSummaryStateValue,
ExtractedFactDto,
FactData,
FactProvenance,
@@ -241,12 +242,22 @@ export function serialiseDocumentDetail(
// failing the whole detail load — the field is descriptive, not load-bearing,
// and the ciphertext is never returned (fail-closed to null).
let summary: string | null = null;
// The stored state is the truth EXCEPT when the ciphertext will not open: a
// READY row we cannot decrypt has no summary to show, and reporting READY
// would leave the view rendering a heading over nothing. Degrade to
// UNAVAILABLE so what the user is told matches what they can see.
let summaryState: DocumentSummaryStateValue = doc.summaryState;
if (doc.summaryEncrypted && doc.summaryEncrypted.byteLength > 0) {
try {
summary = decryptDocumentSummary(doc.summaryEncrypted);
} catch {
summary = null;
summaryState = "UNAVAILABLE";
}
} else if (summaryState === "READY") {
// READY with no ciphertext should be unreachable; trust the bytes, not the
// flag, rather than promising a summary that is not there.
summaryState = "UNAVAILABLE";
}
return {
...serialiseDocument(
@@ -262,5 +273,6 @@ export function serialiseDocumentDetail(
summaryGeneratedAt: doc.summaryGeneratedAt
? doc.summaryGeneratedAt.toISOString()
: null,
summaryState,
};
}
@@ -182,16 +182,58 @@ describe("runDocumentSummaryJob — gating", () => {
expect(reserveBudget).not.toHaveBeenCalled();
expect(runDocumentSummary).not.toHaveBeenCalled();
expect(prisma.inboundDocument.updateMany).not.toHaveBeenCalled();
// No summary is written — but the attempt is RECORDED. Leaving the row
// untouched is what made the detail view claim "being generated" forever.
expect(prisma.inboundDocument.updateMany).toHaveBeenCalledWith(
expect.objectContaining({ data: { summaryState: "UNAVAILABLE" } }),
);
});
it("refunds the budget and persists nothing when the provider call throws", async () => {
it("refunds the budget and records UNAVAILABLE when the provider call throws", async () => {
vi.mocked(runDocumentSummary).mockRejectedValueOnce(new Error("boom"));
await runDocumentSummaryJob({ userId: "user-1", documentId: "doc-1" });
// Reservation refunded to zero spend; no write.
// Reservation refunded to zero spend; no summary written, state recorded.
expect(reconcileSpend).toHaveBeenCalledWith("user-1", 5, 0, "2026-07-17");
expect(prisma.inboundDocument.updateMany).not.toHaveBeenCalled();
expect(prisma.inboundDocument.updateMany).toHaveBeenCalledWith(
expect.objectContaining({ data: { summaryState: "UNAVAILABLE" } }),
);
});
it("records WITHHELD — not silence — when the safety screen blocks the summary", async () => {
vi.mocked(runDocumentSummary).mockResolvedValueOnce({
summary: "",
blocked: "dose_directive",
} as never);
await runDocumentSummaryJob({ userId: "user-1", documentId: "doc-1" });
// The blocked prose NEVER lands. Only the state does, and it is not
// terminal — the guard refuses to overwrite READY, nothing else.
expect(prisma.inboundDocument.updateMany).toHaveBeenCalledWith({
where: {
id: "doc-1",
userId: "user-1",
deletedAt: null,
summaryState: { not: "READY" },
},
data: { summaryState: "WITHHELD" },
});
const calls = vi.mocked(prisma.inboundDocument.updateMany).mock.calls;
for (const [arg] of calls) {
expect(arg.data).not.toHaveProperty("summaryEncrypted");
}
});
it("marks a stored summary READY so the view serves it from storage", async () => {
await runDocumentSummaryJob({ userId: "user-1", documentId: "doc-1" });
expect(prisma.inboundDocument.updateMany).toHaveBeenCalledWith(
expect.objectContaining({
where: expect.objectContaining({ summaryEncrypted: null }),
data: expect.objectContaining({ summaryState: "READY" }),
}),
);
});
});
+47 -5
View File
@@ -44,9 +44,31 @@ import { encryptDocumentSummary } from "@/lib/documents/store";
import { prisma } from "@/lib/db";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { annotate } from "@/lib/logging/context";
import type { DocumentSummaryState } from "@/generated/prisma/client";
export const DOCUMENT_SUMMARY_QUEUE = "document-summary";
/**
* Record what became of this document's summary. Never touches a READY row —
* a stored summary is the terminal state and a later run must not downgrade it.
* Owner-scoped like every other write here.
*/
async function markSummaryState(
userId: string,
documentId: string,
state: Exclude<DocumentSummaryState, "READY">,
): Promise<void> {
await prisma.inboundDocument.updateMany({
where: {
id: documentId,
userId,
deletedAt: null,
summaryState: { not: "READY" },
},
data: { summaryState: state },
});
}
/** Serial concurrency — provider calls, kept off the request pool. */
export const DOCUMENT_SUMMARY_CONCURRENCY = 1;
@@ -87,6 +109,8 @@ export async function runDocumentSummaryJob(
// on-demand route stays the only way to summarise). Fail-closed on a missing
// row.
if (!(await documentAutoReadEnabled(userId))) {
// Opting out is not a failed attempt — leave the state alone so the view
// keeps offering the manual action rather than claiming we tried.
annotate({
action: { name: "documents.summary.autoSkipped" },
meta: { documentId, reason: "opt-out" },
@@ -99,6 +123,7 @@ export async function runDocumentSummaryJob(
// there is no local text-layer fallback for a descriptive summary).
const { pick } = await resolveDocumentVisionProvider(userId);
if (!pick) {
await markSummaryState(userId, documentId, "UNAVAILABLE");
annotate({
action: { name: "documents.summary.autoSkipped" },
meta: { documentId, reason: "no-provider" },
@@ -117,6 +142,7 @@ export async function runDocumentSummaryJob(
surface: "insights",
});
} catch (err) {
await markSummaryState(userId, documentId, "UNAVAILABLE");
annotate({
action: { name: "documents.summary.autoSkipped" },
meta: {
@@ -135,6 +161,7 @@ export async function runDocumentSummaryJob(
if (!vision.ok) {
// Cannot read this file with the picked provider (decrypt miss, unsupported
// type, or a PDF needing an Anthropic provider). Graceful no-op.
await markSummaryState(userId, documentId, "UNAVAILABLE");
annotate({
action: { name: "documents.summary.autoSkipped" },
meta: { documentId, reason: vision.reason },
@@ -151,6 +178,7 @@ export async function runDocumentSummaryJob(
);
// Budget exhausted → skip (no local fallback for a summary).
if (!reservation.allowed) {
await markSummaryState(userId, documentId, "UNAVAILABLE");
annotate({
action: { name: "documents.summary.autoSkipped" },
meta: { documentId, reason: "budget" },
@@ -185,12 +213,19 @@ export async function runDocumentSummaryJob(
reservation.reserved,
dateKey,
);
// WITHHOLD policy. Persisting the refusal copy would be worse than no
// summary: `updateMany` below is guarded on `summaryEncrypted: null`, so
// the first write wins and a stored refusal would stamp the document
// permanently with no path to regenerate. Leaving the column null keeps the
// on-demand route as the manual fallback, exactly as a provider miss does.
// WITHHOLD policy, v1.30.31. The model's prose still never lands — a
// summary that tripped the outbound screen must never be shown as if it
// were fine, and that rule is unchanged.
//
// What changed is the consequence. Withholding was chosen so a refusal
// could not stamp the document permanently, but leaving the column null
// achieved exactly that anyway: the detail view read null as "still
// generating" and said so forever, with no signal and no way out. The fact
// of the refusal is now recorded as a STATE (never the text), the view says
// so honestly, and WITHHELD is not terminal — `markSummaryState` only
// refuses to overwrite READY, so asking again re-runs the whole gauntlet.
if (blocked) {
await markSummaryState(userId, documentId, "WITHHELD");
annotate({
action: { name: "documents.summary.outbound_blocked" },
meta: { documentId, reason: blocked, providerType: pick.providerType },
@@ -210,6 +245,7 @@ export async function runDocumentSummaryJob(
data: {
summaryEncrypted: encryptDocumentSummary(summary),
summaryGeneratedAt: new Date(),
summaryState: "READY",
},
});
annotate({
@@ -226,6 +262,7 @@ export async function runDocumentSummaryJob(
// (the on-demand route remains the manual fallback). Never rethrow — a
// transient provider error must not retry-loop or fail the queue.
await reconcileSpend(userId, reservation.reserved, 0, dateKey);
await markSummaryState(userId, documentId, "UNAVAILABLE");
annotate({
action: { name: "documents.summary.autoFailed" },
meta: { documentId, reason: "provider_error" },
@@ -259,6 +296,11 @@ export async function enqueueDocumentSummary(
retryBackoff: true,
singletonKey: `document-summary|${documentId}`,
});
// PENDING is claimed only once a job genuinely exists. That is the whole
// point: the detail view may say "being generated" for this state, so
// nothing may set it speculatively — a dropped send (no boss, DB hiccup)
// leaves the state alone and the view offers the manual action instead.
if (jobId) await markSummaryState(userId, documentId, "PENDING");
return { enqueued: Boolean(jobId) };
} catch (err) {
annotate({
+3 -1
View File
@@ -23,6 +23,7 @@ import {
documentUpdateSchema,
inboundConfirmSchema,
inboundFactEditSchema,
DOCUMENT_SUMMARY_STATES,
INBOUND_DOCUMENT_KINDS,
INBOUND_DOCUMENT_STATUSES,
} from "@/lib/validations/inbound-documents";
@@ -165,11 +166,12 @@ const inboundDocumentDetail = inboundDocument
facts: z.array(extractedFact),
summary: z.string().nullable(),
summaryGeneratedAt: z.string().nullable(),
summaryState: z.enum(DOCUMENT_SUMMARY_STATES),
})
.meta({
id: "InboundDocumentDetail",
description:
"A stored document plus its staged facts. `summary` is a short (3-4 sentence) plain-language description of WHAT the document is, generated once in the background right after upload when the `documentsAutoAiRead` opt-in is ON (that flag is also the standing AI-egress consent); it is descriptive only, never a diagnosis, and is null when auto-read is OFF, no provider is configured, or the background summary has not run yet. `summaryGeneratedAt` is when it was generated (null until then).",
'A stored document plus its staged facts. `summary` is a short (3-4 sentence) plain-language description of WHAT the document is, generated once and then served from storage; it is descriptive only, never a diagnosis. `summaryGeneratedAt` is when it was generated (null until then). `summaryState` says what became of it, because a null `summary` on its own is ambiguous: NONE = never attempted (the `documentsAutoAiRead` opt-in was off at upload, or the document predates it — no backfill reaches these), PENDING = a job is enqueued or running, READY = stored and returned in `summary`, WITHHELD = generated but blocked by the outbound safety screen and therefore never returned as text, UNAVAILABLE = attempted and could not produce one (no vision provider, spent budget, withdrawn consent, unreadable file, provider error). Only PENDING may be presented as "being generated"; WITHHELD and UNAVAILABLE are both re-attemptable via POST `/api/documents/inbound/{id}/summary`. Treat an unknown value as UNAVAILABLE when decoding.',
});
const listResponse = z
+23
View File
@@ -98,6 +98,22 @@ export function toContentIndexSource(
: null;
}
/**
* What became of a document's plain-language summary. Mirrors the Prisma
* `DocumentSummaryState` enum. The detail view branches on this rather than on
* a null summary, which cannot tell "never attempted" from "in flight" from
* "withheld" from "could not produce".
*/
export const DOCUMENT_SUMMARY_STATES = [
"NONE",
"PENDING",
"READY",
"WITHHELD",
"UNAVAILABLE",
] as const;
export type DocumentSummaryStateValue =
(typeof DOCUMENT_SUMMARY_STATES)[number];
/** The document lifecycle states. STORED is the library default. */
export const INBOUND_DOCUMENT_STATUSES = [
"STORED",
@@ -301,6 +317,13 @@ export interface InboundDocumentDetailDto extends InboundDocumentDto {
summary: string | null;
/** When the background summary was generated (ISO 8601), or null. */
summaryGeneratedAt: string | null;
/**
* What became of the summary. A null `summary` is ambiguous on its own —
* never attempted, mid-flight, withheld by the safety screen and could-not-
* produce all look identical — so the view reads this instead of guessing
* "still generating".
*/
summaryState: DocumentSummaryStateValue;
}
// ─── Edit (correction before approval) ─────────────────────────────────────