mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 16:12:11 +00:00
Merge branch 'worktree-agent-a908bda23e0007c88' into release/v1.30.31
This commit is contained in:
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");
|
||||
});
|
||||
});
|
||||
@@ -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" }),
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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({
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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) ─────────────────────────────────────
|
||||
|
||||
Reference in new issue
Block a user