Merge branch 'feat/ai-extraction-routes' into feat/ai-jobs-stored-text

Brings in the extraction routes and the capability re-check at the wire
(`aiEgressRefusal`), so the jobs and stored-text work can share it.
Conflicts in the document routes, the fenced chat, the auto-read toggle
and its contract text resolve to the extraction branch: those files no
longer call the per-pick document consent helper.
This commit is contained in:
Marc-André Bombeck committed 2026-09-24 09:27:43 +02:00
commit f158f01f18
57 files changed
+3158 -676

No files matched your search

@@ -0,0 +1,254 @@
/**
* The capability re-check at the wire, and the gate option that leaves the
* provider questions to the route's own pick.
*
* The loader is replaced so each case hands the gate exactly the inputs it
* needs; the receipt read is replaced so the exact-pick consent answer can be
* steered independently of the presence-based one.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
let auth: Record<string, unknown> | undefined;
vi.mock("@/lib/logging/context", () => ({
getEvent: () => ({ getAuth: () => auth, addWarning: vi.fn() }),
}));
vi.mock("@/lib/sharing/grants", async (importOriginal) => ({
...(await importOriginal<typeof import("@/lib/sharing/grants")>()),
findActiveGrant: vi.fn(),
}));
vi.mock("../load", () => ({ loadAiCapabilityInputs: vi.fn() }));
vi.mock("@/lib/db", () => ({
prisma: { consentReceipt: { findFirst: vi.fn() } },
}));
import { prisma } from "@/lib/db";
import { MODULE_KEYS, type ModuleKey } from "@/lib/modules/registry";
import type { ModuleAccessState } from "@/lib/sharing/module-disclosure";
import { aiEgressRefusal, assertAiEgress } from "../egress";
import { requireAiCapability } from "../gate";
import { loadAiCapabilityInputs } from "../load";
import { AiUnavailableError } from "../refusal";
import type { AiCapabilityInputs } from "../resolve";
function inputs(
overrides: Partial<AiCapabilityInputs> = {},
): AiCapabilityInputs {
const moduleAccess = {} as Record<ModuleKey, ModuleAccessState>;
for (const key of MODULE_KEYS) moduleAccess[key] = "enabled";
return {
switches: {
enabled: true,
coach: true,
briefing: true,
insightStatus: true,
documentAi: true,
},
moduleAccess,
providerWorkAdmitted: true,
provider: {
entries: [{ providerType: "local", vision: true }],
localOcrEnabled: false,
managedBy: "local",
},
activeConsentKinds: new Set(),
recordKind: "self",
...overrides,
};
}
const LOAD = vi.mocked(loadAiCapabilityInputs);
const RECEIPT = vi.mocked(prisma.consentReceipt.findFirst);
beforeEach(() => {
LOAD.mockReset();
RECEIPT.mockReset();
RECEIPT.mockResolvedValue(null);
auth = { user_id: "user-1" };
});
describe("requireAiCapability with pickDecides", () => {
it("leaves no_provider to the route's pick", async () => {
LOAD.mockResolvedValue(
inputs({
provider: { entries: [], localOcrEnabled: false, managedBy: null },
}),
);
await expect(
requireAiCapability("documentAi", { pickDecides: true }),
).resolves.toMatchObject({ available: true });
});
it("leaves consent_required to the route's pick", async () => {
LOAD.mockResolvedValue(
inputs({
provider: {
entries: [{ providerType: "openai", vision: true }],
localOcrEnabled: false,
managedBy: "user",
},
}),
);
await expect(
requireAiCapability("documentAi", { pickDecides: true }),
).resolves.toMatchObject({ available: true });
});
it("still refuses a layer the pick cannot answer", async () => {
LOAD.mockResolvedValue(
inputs({ switches: { ...inputs().switches, documentAi: false } }),
);
const error = await requireAiCapability("documentAi", {
pickDecides: true,
}).catch((e) => e);
expect(error).toBeInstanceOf(AiUnavailableError);
expect(error.meta.errorCode).toBe("assistant.disabled.documentAi");
});
});
describe("aiEgressRefusal inside a request", () => {
it("refuses when the operator switch is off, whatever the pick", async () => {
LOAD.mockResolvedValue(
inputs({ switches: { ...inputs().switches, documentAi: false } }),
);
const refusal = await aiEgressRefusal("documentAi", "user-1", ["local"]);
expect(refusal).toBeInstanceOf(AiUnavailableError);
expect(refusal?.meta).toEqual({
errorCode: "assistant.disabled.documentAi",
capability: "documentAi",
reason: "operator_disabled",
});
});
it("refuses the master switch through every extraction capability", async () => {
LOAD.mockResolvedValue(
inputs({ switches: { ...inputs().switches, enabled: false } }),
);
for (const key of ["documentAi", "labsOcr", "medicationExtract"] as const) {
const refusal = await aiEgressRefusal(key, "user-1", ["local"]);
expect(refusal?.reason, key).toBe("operator_disabled");
}
});
it("asks for a receipt when the actual pick leaves the machine", async () => {
// Presence says a local model would read it; the route picked an external
// provider anyway (text mode reads the chain head). The pick decides.
LOAD.mockResolvedValue(inputs());
const refusal = await aiEgressRefusal("documentAi", "user-1", ["openai"]);
expect(refusal?.meta).toEqual({
errorCode: "consent.ai.required",
capability: "documentAi",
reason: "consent_required",
});
expect(RECEIPT).toHaveBeenCalledWith(
expect.objectContaining({
where: expect.objectContaining({
userId: "user-1",
revokedAt: null,
kind: { in: ["ai_extraction", "ai_full"] },
}),
}),
);
});
it("admits an external pick with an extraction receipt", async () => {
LOAD.mockResolvedValue(inputs());
RECEIPT.mockResolvedValue({ id: "r1" } as never);
await expect(
aiEgressRefusal("documentAi", "user-1", ["openai"]),
).resolves.toBeNull();
});
it("needs no receipt for a local pick, even when presence says one is needed", async () => {
LOAD.mockResolvedValue(
inputs({
provider: {
entries: [{ providerType: "openai", vision: true }],
localOcrEnabled: false,
managedBy: "user",
},
}),
);
await expect(
aiEgressRefusal("documentAi", "user-1", ["local"]),
).resolves.toBeNull();
expect(RECEIPT).not.toHaveBeenCalled();
});
it("checks every entry of a cascading chain under the document rule", async () => {
LOAD.mockResolvedValue(inputs());
const refusal = await aiEgressRefusal("medicationExtract", "user-1", [
"local",
"admin-openai",
]);
expect(refusal?.reason).toBe("consent_required");
await expect(
aiEgressRefusal("medicationExtract", "user-1", ["local"]),
).resolves.toBeNull();
});
it("uses the self-snapshot rule for the Coach: a person's own key needs nothing", async () => {
LOAD.mockResolvedValue(inputs());
await expect(
aiEgressRefusal("coach", "user-1", ["openai"]),
).resolves.toBeNull();
const refusal = await aiEgressRefusal("coach", "user-1", ["admin-openai"]);
expect(refusal?.reason).toBe("consent_required");
expect(RECEIPT).toHaveBeenLastCalledWith(
expect.objectContaining({
where: expect.objectContaining({
kind: { in: ["ai_coach", "ai_full"] },
}),
}),
);
});
it("fails closed when the inputs cannot be loaded", async () => {
LOAD.mockResolvedValue(null);
const refusal = await aiEgressRefusal("labsOcr", "user-1", ["local"]);
expect(refusal?.reason).toBe("check_failed");
expect(refusal?.status).toBe(503);
});
});
describe("aiEgressRefusal outside a request (a job)", () => {
beforeEach(() => {
auth = undefined;
});
it("resolves for the record the job names", async () => {
LOAD.mockResolvedValue(
inputs({ switches: { ...inputs().switches, documentAi: false } }),
);
const refusal = await aiEgressRefusal("documentAi", "user-9", ["local"]);
expect(refusal?.reason).toBe("operator_disabled");
expect(LOAD).toHaveBeenCalledWith(
expect.objectContaining({ recordId: "user-9" }),
);
});
it("admits the wire when every layer is open", async () => {
LOAD.mockResolvedValue(inputs());
await expect(
aiEgressRefusal("documentAi", "user-9", ["local"]),
).resolves.toBeNull();
});
});
describe("assertAiEgress", () => {
it("throws the refusal", async () => {
LOAD.mockResolvedValue(
inputs({ switches: { ...inputs().switches, documentAi: false } }),
);
await expect(
assertAiEgress("medicationExtract", "user-1", ["local"]),
).rejects.toBeInstanceOf(AiUnavailableError);
});
it("returns quietly when the wire is open", async () => {
LOAD.mockResolvedValue(inputs());
await expect(
assertAiEgress("labsOcr", "user-1", ["local"]),
).resolves.toBeUndefined();
});
});
+96
View File
@@ -0,0 +1,96 @@
/**
* The capability re-check at the wire.
*
* `requireAiCapability` answers at the top of a route, before anything is
* picked. That is the refusal a client sees, but it is not the last word: a
* route may pick its provider in its own order, and a job enqueued before the
* operator turned a switch off runs long after any route answered. So every
* place that hands input to a model (the document provider pick, the labs
* scan, the medication extractor, the fenced document chat) asks again here,
* with the provider it is about to send to, immediately before it sends.
*
* Two questions, both about the actual wire:
*
* 1. Is the capability still open for this record? Inside a request this is
* the request's own resolution (memoised per request, so the answer
* matches the one the route gave); outside a request it is the job's
* resolution for the record it names.
* 2. Does sending to exactly these providers need a consent receipt, and is
* one active? Presence cannot answer this for a route that reads the
* chain in its own order, so the pick answers it here, from the same
* rule and the same receipt kinds the capability table declares.
*
* `no_provider` is never answered here: a caller that has a pick has a
* provider, and one without a pick refuses with its own typed code.
*/
import { prisma } from "@/lib/db";
import { getEvent } from "@/lib/logging/context";
import { aiCapabilityForJob, requireAiCapability } from "./gate";
import { AiUnavailableError } from "./refusal";
import { consentNeededForProviders } from "./resolve";
import {
AI_CAPABILITIES,
PICK_DECIDED_REASONS,
type AiCapabilityKey,
} from "./types";
/** Whether the record holds an active receipt of one of these kinds. */
async function hasActiveReceipt(
recordId: string,
kinds: readonly string[],
): Promise<boolean> {
const row = await prisma.consentReceipt.findFirst({
where: { userId: recordId, revokedAt: null, kind: { in: [...kinds] } },
select: { id: true },
});
return row !== null;
}
/**
* Why input may not leave for these providers right now, or `null` when it
* may. Never throws for a refusal; a database error propagates, which is the
* closed direction for a caller about to send.
*
* @param recordId The record the input belongs to. Inside a request the
* request's own record is used, which is the record the route acts on.
* @param providerTypes The providers the input is about to reach: the one
* picked provider for a single-pick read, the whole chain for a cascade.
*/
export async function aiEgressRefusal(
key: AiCapabilityKey,
recordId: string,
providerTypes: readonly string[],
): Promise<AiUnavailableError | null> {
if (getEvent()?.getAuth()?.user_id) {
try {
await requireAiCapability(key, { pickDecides: true });
} catch (error) {
if (error instanceof AiUnavailableError) return error;
throw error;
}
} else {
const state = await aiCapabilityForJob(recordId, key);
if (state.reason !== null && !PICK_DECIDED_REASONS.has(state.reason)) {
return new AiUnavailableError(key, state.reason);
}
}
if (
consentNeededForProviders(key, providerTypes) &&
!(await hasActiveReceipt(recordId, AI_CAPABILITIES[key].consent.kinds))
) {
return new AiUnavailableError(key, "consent_required");
}
return null;
}
/** {@link aiEgressRefusal}, thrown. For routes, where `apiHandler` renders it. */
export async function assertAiEgress(
key: AiCapabilityKey,
recordId: string,
providerTypes: readonly string[],
): Promise<void> {
const refusal = await aiEgressRefusal(key, recordId, providerTypes);
if (refusal) throw refusal;
}
+18 -2
View File
@@ -40,7 +40,11 @@ import { providerWorkAuthorityForRecord } from "@/lib/sharing/provider-work-auth
import { loadAiCapabilityInputs, type AiCapabilityScope } from "./load";
import { explainAiCapability, resolveAiCapability } from "./resolve";
import { AiUnavailableError, type NoProviderRefusal } from "./refusal";
import type { AiCapabilityKey, AiCapabilityState } from "./types";
import {
PICK_DECIDED_REASONS,
type AiCapabilityKey,
type AiCapabilityState,
} from "./types";
export interface AiGateOptions {
/**
@@ -50,6 +54,15 @@ export interface AiGateOptions {
recordId?: string;
/** The route's own `no_provider` refusal, where a client already reads it. */
noProvider?: NoProviderRefusal;
/**
* Leave `no_provider` and `consent_required` to the provider the route
* actually picks. The resolver answers both from presence, which is right
* for the published payload but can differ from a route that reads the
* chain in its own order (a text-mode document read takes the chain head,
* not the first vision entry). A route that sets this must run the pick
* through `assertAiEgress` / `aiEgressRefusal`, which answers both exactly.
*/
pickDecides?: boolean;
}
/**
@@ -118,7 +131,10 @@ export async function requireAiCapability(
} catch {
finding = { reason: "check_failed", module: null };
}
if (finding.reason !== null) {
if (
finding.reason !== null &&
!(options.pickDecides && PICK_DECIDED_REASONS.has(finding.reason))
) {
throw new AiUnavailableError(
key,
finding.reason,
+23
View File
@@ -223,6 +223,29 @@ function consentNeeded(
);
}
/**
* Whether sending to exactly these providers needs a receipt under the
* capability's consent rule. The egress re-check asks it about the providers a
* route actually picked, so the answer at the wire comes from the same rule the
* published capability does. Pass the one picked provider for a single-pick
* read, or the whole chain for a cascade.
*/
export function consentNeededForProviders(
key: AiCapabilityKey,
providerTypes: readonly string[],
): boolean {
return consentNeeded(AI_CAPABILITIES[key], {
// Every entry named here is one the route will send to, so each counts as
// able to read the input.
entries: providerTypes.map((providerType) => ({
providerType,
vision: true,
})),
localOcrEnabled: false,
managedBy: null,
});
}
function consentReason(
def: AiCapabilityDefinition,
provider: ProviderPresence,
+9
View File
@@ -84,6 +84,15 @@ export interface AiCapabilityState {
export const ON_DEVICE_ALLOWED_REASONS: ReadonlySet<AiUnavailableReason> =
new Set<AiUnavailableReason>(["no_provider", "consent_required"]);
/**
* The reasons a route's own provider pick answers exactly: whether there is a
* provider, and whether sending to it needs a receipt. The resolver answers
* both from presence, which is right for the published payload; a route that
* reads the chain in its own order asks again about the provider it picked.
*/
export const PICK_DECIDED_REASONS: ReadonlySet<AiUnavailableReason> =
new Set<AiUnavailableReason>(["no_provider", "consent_required"]);
/**
* The operator's assistant switches below the master. Each maps to a cost or
* egress profile an operator can reason about: the Coach, the daily briefing
@@ -2,9 +2,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
/**
* v1.29.x (S7) — the shared fenced turn pipeline (design §3, adversarial tests
* 12, 14, 16, 17, 18, 19). Pins: per-document egress consent fan-out (ALL clear
* or refuse, zero egress + no user turn persisted on partial consent), the SINGLE
* consent-checked provider (no cascade), numeric grounding over the LIVE
* 12, 14, 16, 17, 18, 19). Pins: the capability re-check at the wire (the
* document pick answers `documentAi`, each extra capability the entry point
* names is asked for the same provider; any refusal means zero egress and no
* user turn persisted), the SINGLE checked provider (no cascade), numeric grounding over the LIVE
* attachment UNION, and the owner-scoped context loader (a corrupted/foreign join
* row yields null → the turn refuses, never foreign text).
*/
@@ -21,8 +22,8 @@ vi.mock("@/lib/documents/content-index", () => ({
vi.mock("@/lib/documents/provider-order", () => ({
resolveDocumentTextProvider: vi.fn(),
}));
vi.mock("@/lib/ai/consent-guard", () => ({
assertDocumentEgressConsent: vi.fn().mockResolvedValue(undefined),
vi.mock("@/lib/ai/capabilities/egress", () => ({
assertAiEgress: vi.fn(),
}));
vi.mock("@/lib/ai/coach/budget", () => ({
buildDateKey: vi.fn(() => "2026-07-16"),
@@ -49,7 +50,8 @@ import {
} from "../fenced-chat";
import { loadDocumentChatText } from "@/lib/documents/content-index";
import { resolveDocumentTextProvider } from "@/lib/documents/provider-order";
import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
import { assertAiEgress } from "@/lib/ai/capabilities/egress";
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
import { runStreamingRawCompletionWithFallback } from "@/lib/ai/provider-runner";
import { appendMessage } from "@/lib/ai/coach/persistence";
@@ -90,12 +92,13 @@ const baseArgs = {
contractLocale: "en" as const,
locale: "en" as const,
signal: new AbortController().signal,
alsoRequires: [],
};
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(resolveDocumentTextProvider).mockResolvedValue(PICK as never);
vi.mocked(assertDocumentEgressConsent).mockResolvedValue(undefined);
vi.mocked(assertAiEgress).mockResolvedValue(undefined);
vi.mocked(appendMessage).mockImplementation(
async (p) => ({ id: p.role === "assistant" ? "a" : "u", ...p }) as never,
);
@@ -106,35 +109,67 @@ beforeEach(() => {
} as never);
});
describe("streamFencedReply — consent fan-out", () => {
it("checks egress consent ONCE PER attached document", async () => {
await streamFencedReply({
...baseArgs,
docs: [doc("a", "x"), doc("b", "y"), doc("c", "z")],
});
expect(assertDocumentEgressConsent).toHaveBeenCalledTimes(3);
// The document rule is the extraction receipt for the picked provider;
// no chat surface rides along to widen it.
expect(assertDocumentEgressConsent).toHaveBeenCalledWith({
userId: "user-1",
providerType: "anthropic",
});
});
it("refuses (throws) with ZERO egress + no user turn persisted when ANY document's consent fails", async () => {
vi.mocked(assertDocumentEgressConsent)
.mockResolvedValueOnce(undefined)
.mockRejectedValueOnce(new Error("ConsentRequiredError"));
describe("streamFencedReply — the capability at the wire", () => {
it("throws the document pick's refusal with ZERO egress and no user turn persisted", async () => {
const refusal = new AiUnavailableError("documentAi", "consent_required");
vi.mocked(resolveDocumentTextProvider).mockResolvedValue({
chain: [],
pick: null,
withheld: refusal,
} as never);
await expect(
streamFencedReply({ ...baseArgs, docs: [doc("a", "x"), doc("b", "y")] }),
).rejects.toThrow();
).rejects.toBe(refusal);
expect(runStreamingRawCompletionWithFallback).not.toHaveBeenCalled();
expect(appendMessage).not.toHaveBeenCalled();
});
it("asks every extra capability about the picked provider", async () => {
await drain(
await streamFencedReply({
...baseArgs,
alsoRequires: ["coach"],
docs: [doc("a", "x"), doc("b", "y")],
}),
);
expect(assertAiEgress).toHaveBeenCalledTimes(1);
expect(assertAiEgress).toHaveBeenCalledWith("coach", "user-1", [
"anthropic",
]);
});
it("refuses with ZERO egress when an extra capability closed", async () => {
vi.mocked(assertAiEgress).mockRejectedValueOnce(
new AiUnavailableError("coach", "operator_disabled"),
);
await expect(
streamFencedReply({
...baseArgs,
alsoRequires: ["coach"],
docs: [doc("a", "x")],
}),
).rejects.toBeInstanceOf(AiUnavailableError);
expect(runStreamingRawCompletionWithFallback).not.toHaveBeenCalled();
expect(appendMessage).not.toHaveBeenCalled();
});
it("keeps a missing provider an SSE frame, not a refusal", async () => {
vi.mocked(resolveDocumentTextProvider).mockResolvedValue({
chain: [],
pick: null,
withheld: null,
} as never);
const events = await drain(
await streamFencedReply({ ...baseArgs, docs: [doc("a", "x")] }),
);
expect(events).toContainEqual(
expect.objectContaining({ code: "documents.chat.provider.none" }),
);
});
});
describe("streamFencedReply — single provider, no cascade", () => {
it("passes exactly the ONE consent-checked provider entry to the runner", async () => {
it("passes exactly the ONE checked provider entry to the runner", async () => {
await drain(
await streamFencedReply({ ...baseArgs, docs: [doc("a", "x")] }),
);
@@ -53,6 +53,7 @@ vi.mock("@/lib/ai/ai-budgets", () => ({
}));
import { indexDocumentContent } from "../index-document";
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
import {
loadOwnedDocument,
prepareVisionInput,
@@ -259,6 +260,26 @@ describe("indexDocumentContent — local fallback path", () => {
});
});
describe("indexDocumentContent — the documentAi capability", () => {
it("indexes through the provider-free text layer when the pick was withheld", async () => {
// The operator turned document reading off after the upload enqueued this
// job: the pick comes back empty with the refusal beside it, no model is
// called, and the text layer still makes the document searchable.
vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
chain: [],
pick: null,
withheld: new AiUnavailableError("documentAi", "operator_disabled"),
} as never);
const outcome = await indexDocumentContent("user-1", "doc-1");
expect(transcribeDocument).not.toHaveBeenCalled();
expect(reserveBudget).not.toHaveBeenCalled();
expect(localExtractText).toHaveBeenCalledTimes(1);
expect(outcome).toMatchObject({ indexed: true });
});
});
describe("indexDocumentContent — fail-closed", () => {
it("returns not-found for an unknown / non-owned document", async () => {
vi.mocked(loadOwnedDocument).mockResolvedValue(null as never);
@@ -12,13 +12,27 @@ vi.mock("@/lib/labs/ocr-capability", () => ({
resolveVisionProvider: vi.fn(),
resolveTextProvider: vi.fn(),
}));
vi.mock("@/lib/ai/capabilities/egress", () => ({
aiEgressRefusal: vi.fn(),
}));
vi.mock("@/lib/ai/capabilities/gate", () => ({
getAiCapability: vi.fn(),
}));
import {
documentEgressClass,
reorderChainForDocumentClass,
requireDocumentTextProvider,
requireDocumentVisionProvider,
resolveDocumentAiCapability,
resolveDocumentTextProvider,
resolveDocumentVisionProvider,
} from "../provider-order";
import { aiEgressRefusal } from "@/lib/ai/capabilities/egress";
import { getAiCapability } from "@/lib/ai/capabilities/gate";
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
import {
resolveTextProvider,
resolveVisionProvider,
type VisionProviderPick,
} from "@/lib/labs/ocr-capability";
@@ -103,7 +117,11 @@ describe("documentEgressClass", () => {
});
describe("resolveDocumentVisionProvider", () => {
beforeEach(() => vi.mocked(resolveVisionProvider).mockReset());
beforeEach(() => {
vi.mocked(resolveVisionProvider).mockReset();
vi.mocked(aiEgressRefusal).mockReset();
vi.mocked(aiEgressRefusal).mockResolvedValue(null);
});
it("invokes the shared resolver with the document reorder that demotes codex", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue({
@@ -124,3 +142,152 @@ describe("resolveDocumentVisionProvider", () => {
).toEqual(["local", "codex"]);
});
});
function visionPick(providerType: string): VisionProviderPick {
return {
chain: [entry(providerType)],
localOcrEnabled: false,
pick: {
entry: entry(providerType),
providerType: providerType as never,
pdfSupported: false,
},
};
}
describe("the document pick re-checks documentAi at the wire", () => {
beforeEach(() => {
vi.mocked(resolveVisionProvider).mockReset();
vi.mocked(resolveTextProvider).mockReset();
vi.mocked(aiEgressRefusal).mockReset();
vi.mocked(aiEgressRefusal).mockResolvedValue(null);
});
it("asks about the picked provider, under documentAi", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("openai"));
const result = await resolveDocumentVisionProvider("u1");
expect(aiEgressRefusal).toHaveBeenCalledWith("documentAi", "u1", [
"openai",
]);
expect(result.pick?.providerType).toBe("openai");
expect(result.withheld).toBeNull();
});
it("withholds the pick when the capability closed after the route answered", async () => {
// A job enqueued before the operator turned the switch off: the pick is
// resolved, and the wire says no. The caller sees no provider to call.
const refusal = new AiUnavailableError("documentAi", "operator_disabled");
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("local"));
vi.mocked(aiEgressRefusal).mockResolvedValue(refusal);
const result = await resolveDocumentVisionProvider("u1");
expect(result.pick).toBeNull();
expect(result.withheld).toBe(refusal);
});
it("withholds a text-mode pick the same way", async () => {
const refusal = new AiUnavailableError("documentAi", "consent_required");
vi.mocked(resolveTextProvider).mockResolvedValue({
chain: [entry("codex")],
pick: { entry: entry("codex"), providerType: "codex" },
});
vi.mocked(aiEgressRefusal).mockResolvedValue(refusal);
const result = await resolveDocumentTextProvider("u1");
expect(aiEgressRefusal).toHaveBeenCalledWith("documentAi", "u1", ["codex"]);
expect(result.pick).toBeNull();
expect(result.withheld).toBe(refusal);
});
it("does not ask when nothing was picked", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue({
chain: [],
localOcrEnabled: false,
pick: null,
});
const result = await resolveDocumentVisionProvider("u1");
expect(aiEgressRefusal).not.toHaveBeenCalled();
expect(result.withheld).toBeNull();
});
it("the route form throws the refusal", async () => {
const refusal = new AiUnavailableError("documentAi", "operator_disabled");
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("local"));
vi.mocked(aiEgressRefusal).mockResolvedValue(refusal);
await expect(requireDocumentVisionProvider("u1")).rejects.toBe(refusal);
});
it("the route form refuses a missing provider with the vault's own code", async () => {
vi.mocked(resolveTextProvider).mockResolvedValue({ chain: [], pick: null });
const error = await requireDocumentTextProvider("u1").catch((e) => e);
expect(error).toBeInstanceOf(AiUnavailableError);
expect(error.status).toBe(422);
expect(error.meta).toEqual({
errorCode: "documents.inbound.providerUnsupported",
capability: "documentAi",
reason: "no_provider",
});
});
});
describe("resolveDocumentAiCapability", () => {
beforeEach(() => {
vi.mocked(resolveVisionProvider).mockReset();
vi.mocked(aiEgressRefusal).mockReset();
vi.mocked(getAiCapability).mockReset();
});
it("reports the capability beside the provider answer", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("local"));
vi.mocked(getAiCapability).mockResolvedValue({
available: true,
reason: null,
onDeviceAllowed: true,
});
const dto = await resolveDocumentAiCapability("u1");
expect(dto).toMatchObject({
available: true,
mode: "vision",
egress: "local",
ai: { available: true, reason: null },
});
// A probe never runs the wire re-check: it sends nothing.
expect(aiEgressRefusal).not.toHaveBeenCalled();
});
it("is unavailable when the operator turned document reading off", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("local"));
vi.mocked(getAiCapability).mockResolvedValue({
available: false,
reason: "operator_disabled",
onDeviceAllowed: false,
});
const dto = await resolveDocumentAiCapability("u1");
expect(dto).toEqual({
available: false,
mode: null,
reason: null,
pdfSupported: false,
egress: null,
ai: {
available: false,
reason: "operator_disabled",
onDeviceAllowed: false,
},
});
});
it("stays available when only a consent receipt is missing, so the read can ask for it", async () => {
vi.mocked(resolveVisionProvider).mockResolvedValue(visionPick("openai"));
vi.mocked(getAiCapability).mockResolvedValue({
available: false,
reason: "consent_required",
onDeviceAllowed: true,
});
const dto = await resolveDocumentAiCapability("u1");
expect(dto).toMatchObject({
available: true,
mode: "vision",
egress: "external",
ai: { reason: "consent_required" },
});
});
});
+33 -22
View File
@@ -19,9 +19,12 @@
* - NO TOOLS, NO SNAPSHOT — one completion per turn.
* - PROMPT-INJECTION FENCING — every document fenced as DATA (`fenceDocument`),
* per-doc header fields marker-scrubbed (`buildFencedChatSystemPrompt`).
* - PER-DOCUMENT EGRESS CONSENT — the single picked provider (no cascade) is
* consent-checked once per attached document; ALL must clear or the turn
* refuses (403) BEFORE any egress and BEFORE the user turn is persisted.
* - CAPABILITY AT THE WIRE — the single picked provider (no cascade) is
* re-checked against `documentAi` (the operator's switch, the module, the
* sharing grant, and a document consent receipt for a pick that leaves the
* machine) and against every other capability the entry point names (the
* Coach, for a turn inside a Coach conversation). Any refusal is a 403
* BEFORE any egress and BEFORE the user turn is persisted.
* - NUMERIC GROUNDING over the LIVE attachment union only — recomputed per turn
* from the join rows, never history / snapshot.
* - OWNER-SCOPED TEXT LOADER as a second ownership layer — a corrupted/foreign
@@ -33,7 +36,8 @@ import { prisma } from "@/lib/db";
import { createSseStream } from "@/lib/sse/create-stream";
import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
import { assertAiEgress } from "@/lib/ai/capabilities/egress";
import type { AiCapabilityKey } from "@/lib/ai/capabilities/types";
import {
AllProvidersFailedError,
runStreamingRawCompletionWithFallback,
@@ -260,12 +264,19 @@ export interface StreamFencedReplyArgs {
/** i18n locale for outbound-guard fallbacks. */
locale: Locale;
signal: AbortSignal;
/**
* The capabilities this turn is answered under, beside `documentAi`, which
* every fenced turn needs because it reads documents. The Coach's fenced
* chat adds `coach`; the vault's single-document chat adds nothing.
*/
alsoRequires: readonly AiCapabilityKey[];
}
/**
* Run ONE fenced turn against a resolved conversation and its live documents, and
* return the SSE response. May throw `ConsentRequiredError` (403, rendered as
* JSON by the api-handler) BEFORE any egress — the consent fan-out runs first.
* return the SSE response. May throw `AiUnavailableError` (403, rendered as
* JSON by the api-handler) BEFORE any egress — the capability re-check runs
* first.
*/
export async function streamFencedReply(
args: StreamFencedReplyArgs,
@@ -274,28 +285,28 @@ export async function streamFencedReply(
args;
// ── Provider resolution: document order (local-first, codex last), SINGLE
// pick, NO cascade — so the exact egress equals the consent-checked target. ──
const { pick } = await resolveDocumentTextProvider(userId);
// pick, NO cascade — so the exact egress equals the checked target. The pick
// re-checks `documentAi` for that provider, consent receipt included; a
// refusal is thrown (403) before any egress. ──
const { pick, withheld } = await resolveDocumentTextProvider(userId);
if (withheld) throw withheld;
if (!pick) {
annotate({ action: { name: "documents.chat.noProvider" } });
return streamFencedError("documents.chat.provider.none");
}
// ── Per-document egress consent fan-out. Structured as a loop over the live
// attachments (annotated per doc id) so a future per-document consent
// dimension slots into this seam. ALL must clear or the first throws
// ConsentRequiredError (403) — zero egress on partial consent, BEFORE budget
// and BEFORE the user turn is persisted. ──
for (const doc of docs) {
annotate({
action: { name: "documents.chat.consent_check" },
meta: { documentId: doc.documentId, provider: pick.providerType },
});
await assertDocumentEgressConsent({
userId,
providerType: pick.providerType,
});
// ── Every other capability the entry point answers under, for the same
// provider, BEFORE budget and BEFORE the user turn is persisted. ──
for (const key of args.alsoRequires) {
await assertAiEgress(key, userId, [pick.providerType]);
}
annotate({
action: { name: "documents.chat.consent_check" },
meta: {
documentIds: docs.map((doc) => doc.documentId),
provider: pick.providerType,
},
});
// Persist the user's turn first so it's on disk regardless of the outcome.
await appendMessage({ conversationId, role: "user", content: message });
+16 -3
View File
@@ -3,8 +3,13 @@
* both the per-document auto-index-on-upload job and the corpus backfill.
*
* Provider resolution follows the DOCUMENT order (local-first, codex last —
* `resolveDocumentVisionProvider`), NOT the cost-first app-wide chain, and the
* external egress is governed by the per-user `documentsAutoAiRead` opt-in:
* `resolveDocumentVisionProvider`), NOT the cost-first app-wide chain. That
* pick re-checks the `documentAi` capability for the provider it picked: with
* the operator's switch off, the module off, or (for a pick that leaves the
* machine) no extraction consent receipt, there is no pick and the tree goes
* straight to the provider-free text-layer path below, so search keeps working
* with AI off. The external egress is further governed by the per-user
* `documentsAutoAiRead` opt-in:
*
* 1. LOCAL PROVIDER (a self-hosted vision model) — never egresses, so it runs
* whenever it is the document-order pick, toggle-independent.
@@ -149,7 +154,15 @@ export interface ResolvedIndexProvider {
export async function resolveIndexProvider(
userId: string,
): Promise<ResolvedIndexProvider> {
const { chain, pick } = await resolveDocumentVisionProvider(userId);
// A pick the `documentAi` capability refused comes back null, which lands on
// the local text-layer path exactly like having no provider at all.
const { chain, pick, withheld } = await resolveDocumentVisionProvider(userId);
if (withheld) {
annotate({
action: { name: "documents.contentIndex.providerWithheld" },
meta: { reason: withheld.reason },
});
}
let consentOk = false;
if (pick) {
if (!isExternalDocumentEgress(pick.providerType)) {
+134 -21
View File
@@ -19,12 +19,28 @@
* consented opt-in.
*
* The reorder only decides WHICH configured provider is preferred; it never
* invents a provider. Egress consent (`assertDocumentEgressConsent`) and the
* per-egress vendor-blind UI notice sit on top of this order — the reorder
* keeps codex from being the silent default, the consent gate keeps any
* external egress from happening without an active receipt.
* invents a provider. The per-egress vendor-blind UI notice sits on top of
* this order — the reorder keeps codex from being the silent default.
*
* The pick is also the document class's wire: every read of a stored document
* resolves its provider here, the vault routes and the background jobs alike,
* so this is where the `documentAi` capability is asked again, about the
* provider actually picked, immediately before anything is sent. A switch the
* operator turned off after a job was enqueued stops the job here, and an
* external pick without an extraction consent receipt never reaches its
* provider. The document class is the `documentAi` capability; there is no
* other key a caller could pass, so the check is built in rather than taken
* as an argument.
*/
import { isExternalDocumentEgress } from "@/lib/ai/consent-guard";
import { aiEgressRefusal } from "@/lib/ai/capabilities/egress";
import { getAiCapability } from "@/lib/ai/capabilities/gate";
import { PICK_DECIDED_REASONS } from "@/lib/ai/capabilities/types";
import {
AiUnavailableError,
type NoProviderRefusal,
} from "@/lib/ai/capabilities/refusal";
import type { ProviderChainResolved } from "@/lib/ai/provider-runner";
import { documentProviderRank } from "@/lib/documents/provider-rank";
import { RASTERIZATION_AVAILABLE } from "@/lib/documents/rasterize-pdf";
import {
@@ -38,6 +54,15 @@ import type {
DocumentEgressClass,
} from "@/lib/validations/inbound-documents";
/**
* How the vault refuses a read with no provider that can serve it. The code
* predates the capability envelope and a client already branches on it.
*/
export const DOCUMENT_NO_PROVIDER: NoProviderRefusal = {
errorCode: "documents.inbound.providerUnsupported",
status: 422,
};
/**
* Reorder a resolved chain for the document class: stable sort by
* `documentProviderRank`, so within a rank tier the user's own chain order is
@@ -53,27 +78,92 @@ export const reorderChainForDocumentClass: ChainReorder = (chain) => {
};
/**
* Resolve the vision provider for a DOCUMENT read — local-first, codex last.
* Same shape as `resolveVisionProvider`; the returned `chain` is already in
* document order and the `pick` is the first vision-capable entry in it.
* A document pick after the wire re-check. `pick` is null when nothing can
* serve the read OR when the capability refused it; `withheld` says which.
* A job reads `pick` and skips; a route throws `withheld` so the person sees
* the real reason.
*/
export function resolveDocumentVisionProvider(
export type DocumentProviderPick<T> = T & {
withheld: AiUnavailableError | null;
};
async function atTheWire<T extends { pick: { providerType: string } | null }>(
userId: string,
): Promise<VisionProviderPick> {
return resolveVisionProvider(userId, {
reorder: reorderChainForDocumentClass,
});
resolved: T,
): Promise<DocumentProviderPick<T>> {
if (!resolved.pick) return { ...resolved, withheld: null };
const withheld = await aiEgressRefusal("documentAi", userId, [
resolved.pick.providerType,
]);
return withheld
? { ...resolved, pick: null, withheld }
: { ...resolved, withheld: null };
}
/**
* Resolve the text-mode (browser-OCR) structuring provider for a DOCUMENT —
* local-first, codex last. The `pick` is the first entry of the reordered
* chain.
* Resolve the vision provider for a DOCUMENT read — local-first, codex last.
* Same shape as `resolveVisionProvider`; the returned `chain` is already in
* document order and the `pick` is the first vision-capable entry in it, or
* null when `documentAi` refuses the wire.
*/
export function resolveDocumentTextProvider(userId: string) {
return resolveTextProvider(userId, {
reorder: reorderChainForDocumentClass,
});
export async function resolveDocumentVisionProvider(
userId: string,
): Promise<DocumentProviderPick<VisionProviderPick>> {
return atTheWire(
userId,
await resolveVisionProvider(userId, {
reorder: reorderChainForDocumentClass,
}),
);
}
/**
* Resolve the text-mode structuring provider for a DOCUMENT — local-first,
* codex last. The `pick` is the first entry of the reordered chain, or null
* when `documentAi` refuses the wire.
*/
export async function resolveDocumentTextProvider(userId: string): Promise<
DocumentProviderPick<{
chain: ProviderChainResolved[];
pick: { entry: ProviderChainResolved; providerType: string } | null;
}>
> {
return atTheWire(
userId,
await resolveTextProvider(userId, {
reorder: reorderChainForDocumentClass,
}),
);
}
function required<T>(result: {
pick: T | null;
withheld: AiUnavailableError | null;
}): T {
if (result.withheld) throw result.withheld;
if (!result.pick) {
throw new AiUnavailableError(
"documentAi",
"no_provider",
null,
DOCUMENT_NO_PROVIDER,
);
}
return result.pick;
}
/**
* The route form of {@link resolveDocumentVisionProvider}: the pick, or the
* refusal thrown for `apiHandler` to render (`documents.inbound.providerUnsupported`
* when nothing can read the document, the capability envelope otherwise).
*/
export async function requireDocumentVisionProvider(userId: string) {
return required(await resolveDocumentVisionProvider(userId));
}
/** The route form of {@link resolveDocumentTextProvider}. */
export async function requireDocumentTextProvider(userId: string) {
return required(await resolveDocumentTextProvider(userId));
}
/**
@@ -89,12 +179,31 @@ export function documentEgressClass(providerType: string): DocumentEgressClass {
* Resolve the document AI capability for the vault UI. The `mode` /
* `pdfSupported` / `egress` reflect the DOCUMENT provider order (local-first),
* so the affordance the UI offers matches exactly what the document routes do.
*
* `ai` is the `documentAi` capability for the request's record. A read the
* operator, the record's modules or the sharing grant close is not offered
* (`available: false`, no mode). A missing consent receipt keeps the read
* offered: the read itself is where the person is asked for the receipt, and
* hiding the button would leave them no way to give it.
*/
export async function resolveDocumentAiCapability(
userId: string,
): Promise<DocumentAiCapabilityDto> {
const { chain, pick, localOcrEnabled } =
await resolveDocumentVisionProvider(userId);
const [{ chain, pick, localOcrEnabled }, ai] = await Promise.all([
resolveVisionProvider(userId, { reorder: reorderChainForDocumentClass }),
getAiCapability("documentAi"),
]);
if (ai.reason !== null && !PICK_DECIDED_REASONS.has(ai.reason)) {
return {
available: false,
mode: null,
reason: null,
pdfSupported: false,
egress: null,
ai,
};
}
// A vision-capable provider is available — the read runs directly over the
// stored original. Egress follows the picked provider. PDFs are readable
@@ -108,6 +217,7 @@ export async function resolveDocumentAiCapability(
reason: null,
pdfSupported: pick.pdfSupported || RASTERIZATION_AVAILABLE,
egress: documentEgressClass(pick.providerType),
ai,
};
}
@@ -119,6 +229,7 @@ export async function resolveDocumentAiCapability(
reason: "no-provider",
pdfSupported: false,
egress: null,
ai,
};
}
@@ -131,6 +242,7 @@ export async function resolveDocumentAiCapability(
reason: null,
pdfSupported: false,
egress: documentEgressClass(chain[0]!.providerType),
ai,
};
}
@@ -141,5 +253,6 @@ export async function resolveDocumentAiCapability(
reason: "enable-local-ocr",
pdfSupported: false,
egress: null,
ai,
};
}
@@ -31,10 +31,10 @@
* matcher that stopped matching cannot agree with an empty world.
*
* Mutation checks: adding `await requireAssistantSurface("coach")` to any
* route outside the frozen list turns guard 3 red by file name; removing the
* `aiCapabilityForJob(userId, "documentAi")` calls from the document jobs
* turns guard 2 red for `documentAi`; putting
* `assistantCorrelationsEnabled` back on the schema turns guard 1 red.
* route outside the frozen list turns guard 3 red by file name; deleting the
* `requireAiCapability("documentAi"` calls from the document routes (the only
* reader of that switch's capabilities in the route tree) turns guard 2 red;
* putting `assistantCorrelationsEnabled` back on the schema turns guard 1 red.
*/
import { readdirSync, readFileSync, statSync } from "node:fs";
import path from "node:path";
@@ -100,9 +100,6 @@ const PLUMBING = [
* Switches with no reader yet, and why that is correct for now. An entry is
* a claim with an expiry: the test below fails as soon as a reader appears.
*/
// Empty since the document jobs resolve `documentAi` (the summary job, its
// catch-up pass and the index backfill). A new switch that ships before its
// reader is listed here with the reason.
const AWAITING_READER: Record<string, string> = {};
/**
@@ -130,7 +127,6 @@ const RETIRED_GATE_CALLERS = [
"src/app/api/insights/pregenerate/route.ts",
"src/app/api/insights/pulse-status/route.ts",
"src/app/api/insights/weight-status/route.ts",
"src/app/api/medications/extract/route.ts",
"src/app/coach/page.tsx",
];
@@ -0,0 +1,163 @@
/**
* The labs scan's wire and its probe.
*
* `requireLabsOcrProvider` is where a lab report meets a provider: it picks
* the provider for the scan mode and asks the `labsOcr` capability again about
* exactly that provider. `resolveOcrCapability` is the probe the Labs page
* reads to decide whether to offer a scan at all.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("@/lib/db", () => ({
prisma: {
user: { findUnique: vi.fn() },
appSettings: { findUnique: vi.fn() },
},
}));
vi.mock("@/lib/ai/provider", () => ({
resolveProviderChain: vi.fn(),
resolveProvider: vi.fn(),
}));
vi.mock("@/lib/ai/codex-client", () => ({
resolveCodexVisionSlug: vi.fn(() => "gpt-5"),
}));
vi.mock("@/lib/ai/capabilities/egress", () => ({
aiEgressRefusal: vi.fn(),
}));
vi.mock("@/lib/ai/capabilities/gate", () => ({
getAiCapability: vi.fn(),
}));
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
vi.mock("@/lib/documents/rasterize-pdf", () => ({
RASTERIZATION_AVAILABLE: true,
}));
import { prisma } from "@/lib/db";
import { resolveProvider, resolveProviderChain } from "@/lib/ai/provider";
import { aiEgressRefusal } from "@/lib/ai/capabilities/egress";
import { getAiCapability } from "@/lib/ai/capabilities/gate";
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
import {
requireLabsOcrProvider,
resolveOcrCapability,
} from "../ocr-capability";
function entry(providerType: string) {
return { providerType, instance: { type: providerType } } as never;
}
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(prisma.user.findUnique).mockResolvedValue({
aiModel: "claude-sonnet-4-5",
labsLocalOcrEnabled: true,
} as never);
vi.mocked(prisma.appSettings.findUnique).mockResolvedValue({
adminAiModel: null,
} as never);
vi.mocked(resolveProvider).mockResolvedValue({ type: "none" } as never);
vi.mocked(aiEgressRefusal).mockResolvedValue(null);
vi.mocked(getAiCapability).mockResolvedValue({
available: true,
reason: null,
onDeviceAllowed: true,
});
});
describe("requireLabsOcrProvider", () => {
it("re-checks labsOcr for the vision pick", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
const pick = await requireLabsOcrProvider("u1", "vision");
expect(pick.providerType).toBe("anthropic");
expect(aiEgressRefusal).toHaveBeenCalledWith("labsOcr", "u1", [
"anthropic",
]);
});
it("re-checks labsOcr for the text-mode chain head, not the first vision entry", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([
entry("codex"),
entry("local"),
]);
const pick = await requireLabsOcrProvider("u1", "text");
expect(pick.providerType).toBe("codex");
expect(aiEgressRefusal).toHaveBeenCalledWith("labsOcr", "u1", ["codex"]);
});
it("throws the wire's refusal and hands back no provider", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
const refusal = new AiUnavailableError("labsOcr", "operator_disabled");
vi.mocked(aiEgressRefusal).mockResolvedValue(refusal);
await expect(requireLabsOcrProvider("u1", "vision")).rejects.toBe(refusal);
});
it("keeps the scan's own code when nothing can read the report", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([]);
const error = await requireLabsOcrProvider("u1", "vision").catch((e) => e);
expect(error).toBeInstanceOf(AiUnavailableError);
expect(error.status).toBe(422);
expect(error.meta).toEqual({
errorCode: "labs.ocr.providerUnsupported",
capability: "labsOcr",
reason: "no_provider",
});
expect(aiEgressRefusal).not.toHaveBeenCalled();
});
});
describe("resolveOcrCapability", () => {
it("offers the scan and reports the capability beside it", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
const dto = await resolveOcrCapability("u1");
expect(dto).toMatchObject({
available: true,
mode: "vision",
ai: { available: true },
});
expect(getAiCapability).toHaveBeenCalledWith("labsOcr");
});
it("offers nothing when the operator turned document reading off", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
vi.mocked(getAiCapability).mockResolvedValue({
available: false,
reason: "operator_disabled",
onDeviceAllowed: false,
});
await expect(resolveOcrCapability("u1")).resolves.toEqual({
available: false,
mode: null,
reason: null,
pdfSupported: false,
ai: {
available: false,
reason: "operator_disabled",
onDeviceAllowed: false,
},
});
});
it("offers nothing with the labs module off", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
vi.mocked(getAiCapability).mockResolvedValue({
available: false,
reason: "module_disabled",
onDeviceAllowed: false,
});
const dto = await resolveOcrCapability("u1");
expect(dto.available).toBe(false);
expect(dto.mode).toBeNull();
});
it("keeps the scan offered when only a consent receipt is missing", async () => {
vi.mocked(resolveProviderChain).mockResolvedValue([entry("anthropic")]);
vi.mocked(getAiCapability).mockResolvedValue({
available: false,
reason: "consent_required",
onDeviceAllowed: true,
});
const dto = await resolveOcrCapability("u1");
expect(dto).toMatchObject({ available: true, mode: "vision" });
});
});
+88 -5
View File
@@ -9,11 +9,19 @@
* one place) and pair each surviving entry with the model that drives its
* vision allowlist.
*/
import { aiEgressRefusal } from "@/lib/ai/capabilities/egress";
import { getAiCapability } from "@/lib/ai/capabilities/gate";
import {
AiUnavailableError,
type NoProviderRefusal,
} from "@/lib/ai/capabilities/refusal";
import { PICK_DECIDED_REASONS } from "@/lib/ai/capabilities/types";
import type { ProviderChainResolved } from "@/lib/ai/provider-runner";
import { resolveProvider, resolveProviderChain } from "@/lib/ai/provider";
import { resolveCodexVisionSlug } from "@/lib/ai/codex-client";
import { RASTERIZATION_AVAILABLE } from "@/lib/documents/rasterize-pdf";
import { prisma } from "@/lib/db";
import { annotate } from "@/lib/logging/context";
import {
supportsPdfForProvider,
supportsVisionForConfig,
@@ -167,20 +175,91 @@ export async function resolveTextProvider(
};
}
/**
* How a lab scan refuses with no provider that can serve it. The code predates
* the capability envelope and a client already branches on it.
*/
export const LABS_OCR_NO_PROVIDER: NoProviderRefusal = {
errorCode: "labs.ocr.providerUnsupported",
status: 422,
};
/**
* The labs scan's wire. Resolve the provider for one scan mode and ask the
* `labsOcr` capability again about exactly that provider, immediately before
* the report is sent: the operator's switch, the labs module, the sharing
* grant, and a document-class consent receipt for any pick that leaves the
* machine (a lab report is a document). Throws the refusal for `apiHandler`
* to render; a missing provider keeps its `labs.ocr.providerUnsupported` code.
*
* Vision mode picks the first vision-capable entry in chain order; text mode
* (the person's in-browser OCR) takes the chain head, which is why the pick,
* not the published capability, answers the consent question.
*/
export async function requireLabsOcrProvider(
userId: string,
mode: "vision",
): Promise<NonNullable<VisionProviderPick["pick"]>>;
export async function requireLabsOcrProvider(
userId: string,
mode: "text",
): Promise<{ entry: ProviderChainResolved; providerType: string }>;
export async function requireLabsOcrProvider(
userId: string,
mode: "vision" | "text",
) {
const { chain, pick } =
mode === "vision"
? await resolveVisionProvider(userId)
: await resolveTextProvider(userId);
if (!pick) {
annotate({
action: { name: "labs.ocr.providerUnsupported" },
meta: {
chainLength: chain.length,
...(mode === "text" ? { mode } : {}),
},
});
throw new AiUnavailableError(
"labsOcr",
"no_provider",
null,
LABS_OCR_NO_PROVIDER,
);
}
const refusal = await aiEgressRefusal("labsOcr", userId, [pick.providerType]);
if (refusal) throw refusal;
return pick;
}
/**
* The cheap capability DTO for the probe endpoint: whether scanning is
* available + why not + whether PDFs are accepted. Built from the same
* resolution the extract route uses, so the UI never shows an entry the
* extract route would 422.
*
* `ai` is the `labsOcr` capability for the request's record. A scan the
* operator, the labs module or the sharing grant close is not offered
* (`available: false`, no mode). A missing consent receipt keeps the scan
* offered: the scan is where the person is asked for the receipt.
*/
export async function resolveOcrCapability(
userId: string,
options?: ResolveProviderOptions,
): Promise<OcrCapabilityDto> {
const { chain, pick, localOcrEnabled } = await resolveVisionProvider(
userId,
options,
);
const [{ chain, pick, localOcrEnabled }, ai] = await Promise.all([
resolveVisionProvider(userId),
getAiCapability("labsOcr"),
]);
if (ai.reason !== null && !PICK_DECIDED_REASONS.has(ai.reason)) {
return {
available: false,
mode: null,
reason: null,
pdfSupported: false,
ai,
};
}
// Prefer the native vision path whenever it is available — it is more
// accurate and the client does not download the OCR WASM. PDFs are readable
@@ -195,6 +274,7 @@ export async function resolveOcrCapability(
mode: "vision",
reason: null,
pdfSupported: pick.pdfSupported || RASTERIZATION_AVAILABLE,
ai,
};
}
@@ -206,6 +286,7 @@ export async function resolveOcrCapability(
mode: null,
reason: "no-provider",
pdfSupported: false,
ai,
};
}
@@ -219,6 +300,7 @@ export async function resolveOcrCapability(
mode: "text",
reason: null,
pdfSupported: false,
ai,
};
}
@@ -229,5 +311,6 @@ export async function resolveOcrCapability(
mode: null,
reason: "enable-local-ocr",
pdfSupported: false,
ai,
};
}
+7 -1
View File
@@ -38,7 +38,12 @@
*/
export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
{
ai: ["ai.provider.none", "ai.record.notPermitted", "ai.unavailable"],
ai: [
"ai.budget.exceeded",
"ai.provider.none",
"ai.record.notPermitted",
"ai.unavailable",
],
ai_provider: ["ai_provider.invalid", "ai_provider.no_fields"],
allergy: ["allergy.invalid"],
analytics: ["analytics.invalid_query"],
@@ -62,6 +67,7 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
],
backup: ["backup.payload.undecryptable", "backup.section.missing"],
coach: [
"coach.budget.exceeded",
"coach.conversation.invalidTitle",
"coach.conversation.notFound",
"coach.fenced.attachmentConflict",
@@ -0,0 +1,84 @@
/**
* The refusals the extraction group answers with: reading a stored document,
* scanning a lab report, and turning typed medication text into a schedule.
*
* Three capabilities under one operator switch ("Reading documents",
* `documentAi`), one consent rule (any provider that leaves the machine needs
* an `ai_extraction` or `ai_full` receipt), and one envelope. Written once so
* the vault, the labs scan and the medication extractor describe the same
* refusal in the same words.
*/
import type { AiCapabilityKey } from "@/lib/ai/capabilities/types";
import { errorEnvelope } from "./shared";
const MODULE_BY_CAPABILITY: Partial<Record<AiCapabilityKey, string>> = {
documentAi: "inboundDocuments",
labsOcr: "labs",
};
/**
* The 403 sentence for one extraction capability (plus any capability the
* route also answers under, such as `coach` for a fenced Coach turn).
*/
export function aiExtractionRefusalDescription(
capability: AiCapabilityKey,
...alsoUnder: AiCapabilityKey[]
): string {
const owningModule = MODULE_BY_CAPABILITY[capability];
const also =
alsoUnder.length === 0
? ""
: ` The route also answers under ${alsoUnder.map((key) => `\`${key}\``).join(", ")}, with the same envelope and that capability's own codes (\`assistant.disabled.coach\`, \`module.disabled\` with \`meta.module = "coach"\` when the Coach is off for the record).`;
return (
`AI refusal: the \`${capability}\` capability is unavailable for this record. The envelope carries \`meta.errorCode\`, \`meta.capability\` and \`meta.reason\` (one of \`AiUnavailableReason\`). ` +
"`assistant.disabled.documentAi` — the operator turned off reading documents, or every AI feature (the master switch). " +
(owningModule
? `\`module.disabled\` with \`meta.module = "${owningModule}"\` — the module is off for this record. `
: "") +
"`ai.record.notPermitted` — AI work is not admitted inside this record (a delegate acting in somebody else's record). " +
"`consent.ai.required` — the provider this request would reach leaves the machine and the record holds no active `ai_extraction` or `ai_full` receipt; only a self-hosted model is exempt. The question is answered for the provider actually picked, so it can differ from the published capability when a text-mode read takes a different provider than a vision read would." +
also
);
}
/** The 503 an extraction route answers when the capability could not be resolved. */
export const AI_EXTRACTION_UNAVAILABLE_DESCRIPTION =
"`ai.unavailable` — the inputs behind the AI capability could not be read, and the answer failed closed. Nothing was sent. Retry later.";
type AiExtractionRefusals = {
"403": {
description: string;
content: { "application/json": { schema: typeof errorEnvelope } };
};
"503": {
description: string;
content: { "application/json": { schema: typeof errorEnvelope } };
};
};
// Memoised so identical responses are one object: the YAML emitter aliases by
// identity, and a fresh object per operation would print the paragraph again.
const cache = new Map<string, AiExtractionRefusals>();
/** `{ "403", "503" }` for an extraction route. Spread before `stdResponses`. */
export function aiExtractionRefusals(
capability: AiCapabilityKey,
...alsoUnder: AiCapabilityKey[]
): AiExtractionRefusals {
const key = [capability, ...alsoUnder].join(",");
const cached = cache.get(key);
if (cached) return cached;
const refusals: AiExtractionRefusals = {
"403": {
description: aiExtractionRefusalDescription(capability, ...alsoUnder),
content: { "application/json": { schema: errorEnvelope } },
},
"503": {
description: AI_EXTRACTION_UNAVAILABLE_DESCRIPTION,
content: { "application/json": { schema: errorEnvelope } },
},
};
cache.set(key, refusals);
return refusals;
}
+14 -3
View File
@@ -58,6 +58,11 @@ import {
recordRefusal,
stdResponses,
} from "./shared";
import {
AI_EXTRACTION_UNAVAILABLE_DESCRIPTION,
aiExtractionRefusalDescription,
aiExtractionRefusals,
} from "./ai-extraction-refusals";
// The assigning form, deliberately: `schema.meta({...})` as a bare statement
// returns a clone and registers nothing, so the component id would never
@@ -936,7 +941,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Insights"],
summary: "Send a FENCED multi-document coach turn (streaming reply)",
description:
"v1.29.x (S7) — sends a user turn and streams a grounded prose reply about the documents attached to a coach conversation, as Server-Sent Events (`text/event-stream`: one `data: <json>\\n\\n` frame per event; `token` / `done` / `error`, HTTP 200 even for a provider/refusal outcome). FENCED by construction: NO tools, NO health snapshot; every attached document is fenced as untrusted DATA (per-document header fields marker-scrubbed); the single picked provider is egress-consent-checked once per attached document (403 `consent.ai.required` if any fails); the reply is numerically grounded against the LIVE attachments' figures only. `conversationId` continues an existing fenced thread; `attachmentIds` (first-turn ONLY, min 1, max 5) creates a fresh fenced thread — supplying BOTH is a 422. The body is `.strict()`: `scope` / `guidedQuestion` / `prefill` / `userId` are rejected. A plain tool conversation 404s here. Module-gated on `inboundDocuments`; rate-limited (shared `document-chat` bucket). Renders as plain text (no markdown). Auth via cookie or Bearer.",
"v1.29.x (S7) — sends a user turn and streams a grounded prose reply about the documents attached to a coach conversation, as Server-Sent Events (`text/event-stream`: one `data: <json>\\n\\n` frame per event; `token` / `done` / `error`, HTTP 200 even for a provider/refusal outcome). FENCED by construction: NO tools, NO health snapshot; every attached document is fenced as untrusted DATA (per-document header fields marker-scrubbed); answers under the `coach` and `documentAi` capabilities, both re-checked for the single picked provider immediately before anything is sent (403 with the capability envelope when either is closed; `consent.ai.required` when that provider leaves the machine without an `ai_extraction` / `ai_full` receipt; no provider is the `documents.chat.provider.none` error frame); the reply is numerically grounded against the LIVE attachments' figures only. `conversationId` continues an existing fenced thread; `attachmentIds` (first-turn ONLY, min 1, max 5) creates a fresh fenced thread — supplying BOTH is a 422. The body is `.strict()`: `scope` / `guidedQuestion` / `prefill` / `userId` are rejected. A plain tool conversation 404s here. Module-gated on `inboundDocuments`; rate-limited (shared `document-chat` bucket). Renders as plain text (no markdown). Auth via cookie or Bearer.",
requestBody: {
required: true,
content: {
@@ -959,7 +964,12 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
"403": {
description:
"AI consent required for an external provider (`errorCode: consent.ai.required`). A 422 (`stdResponses`) covers an un-indexed / unavailable attachment (`coach.fenced.attachmentUnavailable`), the attachment cap (`coach.fenced.attachmentLimit`), or `attachmentIds` sent with a `conversationId` (`coach.fenced.attachmentConflict`).",
aiExtractionRefusalDescription("documentAi", "coach") +
" A 422 (`stdResponses`) covers an un-indexed / unavailable attachment (`coach.fenced.attachmentUnavailable`), the attachment cap (`coach.fenced.attachmentLimit`), or `attachmentIds` sent with a `conversationId` (`coach.fenced.attachmentConflict`).",
content: { "application/json": { schema: errorEnvelope } },
},
"503": {
description: AI_EXTRACTION_UNAVAILABLE_DESCRIPTION,
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
@@ -971,7 +981,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Insights"],
summary: "Attach a document to a coach conversation",
description:
"v1.29.x (S7) — attaches one already-stored, content-indexed document to an existing conversation and sets its sticky `documentScoped` flag TRUE (the one legal, privilege-reducing tool→fenced transition; audit-logged when a flip occurs). Validates the document is owned + live + indexed + within the 5-document cap. Idempotent: attaching an already-attached document is a 200. A foreign / unknown conversation or document maps to 404. Module-gated on `inboundDocuments`; rate-limited. Auth via cookie or Bearer.",
"v1.29.x (S7) — attaches one already-stored, content-indexed document to an existing conversation and sets its sticky `documentScoped` flag TRUE (the one legal, privilege-reducing tool→fenced transition; audit-logged when a flip occurs). Validates the document is owned + live + indexed + within the 5-document cap. Idempotent: attaching an already-attached document is a 200. A foreign / unknown conversation or document maps to 404. Module-gated on `inboundDocuments`; answers under the `coach` and `documentAi` capabilities (nothing is sent to a provider here, so a missing provider or consent receipt is left to the next turn); rate-limited. Detaching (DELETE) is never refused for AI reasons: it removes the person\'s own data. Auth via cookie or Bearer.",
parameters: [
{
name: "id",
@@ -1003,6 +1013,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
description: "Conversation or document not found / not owned.",
content: { "application/json": { schema: errorEnvelope } },
},
...aiExtractionRefusals("documentAi", "coach"),
...stdResponses,
},
},
+22 -14
View File
@@ -28,6 +28,8 @@ import {
INBOUND_DOCUMENT_STATUSES,
} from "@/lib/validations/inbound-documents";
import { aiExtractionRefusals } from "./ai-extraction-refusals";
import { aiCapabilityState } from "./profile";
import {
dataEnvelope,
errorEnvelope,
@@ -208,7 +210,7 @@ const inboundDocumentDetail = inboundDocument
.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 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.',
'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, reading documents with AI was closed for the record 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
@@ -440,7 +442,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Probe document-AI availability + egress",
description:
'Cheap probe (no provider call) the vault uses to decide the AI transport and whether to warn before a read leaves the machine. Resolved over the DOCUMENT provider order (local-first, ChatGPT-subscription OAuth last), so `mode` / `pdfSupported` / `egress` match exactly what the document AI routes do. `egress` is vendor-blind: `"local"` (a self-hosted model — the document never leaves the operator\'s machine) or `"external"` (a third-party AI service). The vault shows a per-egress notice before any external document read; sending a document to any external provider also requires an active AI-consent receipt.',
'Cheap probe (no provider call) the vault uses to decide the AI transport and whether to warn before a read leaves the machine. Resolved over the DOCUMENT provider order (local-first, ChatGPT-subscription OAuth last), so `mode` / `pdfSupported` / `egress` match exactly what the document AI routes do. `egress` is vendor-blind: `"local"` (a self-hosted model — the document never leaves the operator\'s machine) or `"external"` (a third-party AI service). The vault shows a per-egress notice before any external document read; sending a document to any external provider also requires an active `ai_extraction` or `ai_full` consent receipt. `ai` is the `documentAi` capability for the record: when the operator turned reading documents off, the module is off, or the record is somebody else\'s, `available` is false with a null `reason` and `ai.reason` says why. A missing consent receipt leaves the read offered (`ai.reason = "consent_required"`), because the read is where the person is asked for it.',
responses: {
"200": {
description: "Document-AI capability flags + egress class.",
@@ -456,6 +458,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
.nullable(),
pdfSupported: z.boolean(),
egress: z.enum(["local", "external"]).nullable(),
ai: aiCapabilityState,
})
.meta({ id: "DocumentAiCapability" }),
"DocumentAiCapabilityEnvelope",
@@ -492,7 +495,11 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
name: z.string(),
}),
),
assistAvailable: z.boolean(),
assistAvailable: z
.boolean()
.describe(
"Whether a document read can run for this record now: a provider can serve it and the `documentAi` capability is not closed by the operator, the module or the sharing grant. The same answer as `available` on GET /api/documents/inbound/capability.",
),
contentIndex: z.object({
enabled: z.boolean(),
indexedCount: z.number(),
@@ -739,7 +746,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Extract facts from a stored document",
description:
'Optional AI enhancement on an already-stored document. Runs the dedicated OCR/vision provider over the stored original and stages STRUCTURED FACTS for review. AI-consent / rate / budget gated. With no provider configured this returns 422 (`documents.inbound.providerUnsupported`) — the stored document is untouched, only the enhancement fails. Three modes: VISION (empty body) decrypts and scans the stored original (PDF needs an Anthropic vision provider); TEXT (`application/json`, opt-in local OCR) `{ mode: "text", text }` structures browser-OCR\'d text; STORED (`application/json`) `{ mode: "stored" }` structures the document\'s own stored extracted text (its content index) — the manual recovery for a skipped/failed automatic staging run, 422 `documents.inbound.notIndexed` when no stored text exists. Extraction reproduces what the document states — it never interprets. Nothing reaches the structured stores here; the confirm route is the only write path.',
'Optional AI enhancement on an already-stored document. Runs the dedicated OCR/vision provider over the stored original and stages STRUCTURED FACTS for review. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated. With no provider configured this returns 422 (`documents.inbound.providerUnsupported`, with `meta.capability` and `meta.reason = "no_provider"`) — the stored document is untouched, only the enhancement fails. Three modes: VISION (empty body) decrypts and scans the stored original (PDF needs an Anthropic vision provider); TEXT (`application/json`, opt-in local OCR) `{ mode: "text", text }` structures browser-OCR\'d text; STORED (`application/json`) `{ mode: "stored" }` structures the document\'s own stored extracted text (its content index) — the manual recovery for a skipped/failed automatic staging run, 422 `documents.inbound.notIndexed` when no stored text exists. Extraction reproduces what the document states — it never interprets. Nothing reaches the structured stores here; the confirm route is the only write path.',
parameters: [
{
name: "id",
@@ -784,6 +791,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"Re-extraction refused: at least one fact on this document is already APPROVED. `meta.errorCode` = `documents.inbound.alreadyPartlyConfirmed`. Re-extracting would sever committed-record provenance and duplicate committed records, so the user must finish reviewing or discard the document first.",
content: { "application/json": { schema: errorEnvelope } },
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
@@ -793,7 +801,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Suggest filing metadata (drafts only)",
description:
'Optional AI assist on an already-stored document. Runs ONE provider call over the stored original (VISION, empty body) or browser-OCR\'d text (TEXT, `application/json` `{ mode: "text", text }`, opt-in local OCR) and returns a `{ title, kind, documentDate }` DRAFT for the edit form. AI-consent / rate / budget gated (shares the per-user document-AI bucket with extract/summary/index — default 6/hour, operator-tunable via `DOCUMENT_AI_LIMIT_PER_HOUR`; a slot is only consumed when the request reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-Limit` / `-Remaining` / `-Reset` triple, and `meta.retryAt`). WRITES NOTHING — never stages facts, never flips status; the user reviews and saves. 422 (`documents.inbound.providerUnsupported`) with no provider configured. Never interprets or diagnoses; the title is a neutral filing label.',
'Optional AI assist on an already-stored document. Runs ONE provider call over the stored original (VISION, empty body) or browser-OCR\'d text (TEXT, `application/json` `{ mode: "text", text }`, opt-in local OCR) and returns a `{ title, kind, documentDate }` DRAFT for the edit form. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated (shares the per-user document-AI bucket with extract/summary/index — default 6/hour, operator-tunable via `DOCUMENT_AI_LIMIT_PER_HOUR`; a slot is only consumed when the request reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-Limit` / `-Remaining` / `-Reset` triple, and `meta.retryAt`). WRITES NOTHING — never stages facts, never flips status; the user reviews and saves. 422 (`documents.inbound.providerUnsupported`) with no provider configured. Never interprets or diagnoses; the title is a neutral filing label.',
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
],
@@ -829,6 +837,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
@@ -838,7 +847,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Summarise or transcribe a document",
description:
'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot, while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as extract. AI-consent / rate / budget gated. 422 with no provider.',
'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot, while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as extract. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated. 422 `documents.inbound.providerUnsupported` with no provider.',
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
{
@@ -903,6 +912,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
@@ -912,7 +922,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Build / refresh the content-search index",
description:
"Populates or refreshes one document's content-search index so search matches INSIDE its body. VISION (empty body) decrypts the stored original and runs one provider transcription (AI-consent / rate / budget gated); TEXT (`application/json` `{ mode: \"text\", text }`, opt-in local OCR) indexes browser-OCR'd text with no provider egress. Persists ONLY AES-256-GCM ciphertext of the text plus opaque HMAC token hashes — no plaintext body, no plaintext token. Gated on the existing AI consent (no separate per-user toggle). Idempotent; re-indexing overwrites in place. A successful index continues into the same lab auto-staging the background worker performs (still-STORED lab-looking document with no facts, both modules on, provider + consent eligible); `labFactsStaged` reports how many facts were staged PENDING for review — confirmation stays the only write into Labs.",
"Populates or refreshes one document's content-search index so search matches INSIDE its body. VISION (empty body) decrypts the stored original and runs one provider transcription (answers under the `documentAi` capability — 403 with the capability envelope when it is closed, including a missing `ai_extraction` / `ai_full` receipt for a provider that leaves the machine — then rate / budget gated); TEXT (`application/json` `{ mode: \"text\", text }`, opt-in local OCR) indexes browser-OCR'd text with no provider egress and stays available with AI off, so search keeps working. Persists ONLY AES-256-GCM ciphertext of the text plus opaque HMAC token hashes — no plaintext body, no plaintext token. Idempotent; re-indexing overwrites in place. A successful index continues into the same lab auto-staging the background worker performs (still-STORED lab-looking document with no facts, both modules on, provider + consent eligible); `labFactsStaged` reports how many facts were staged PENDING for review — confirmation stays the only write into Labs.",
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
],
@@ -951,6 +961,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
@@ -960,7 +971,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Chat about a document (streaming reply)",
description:
"v1.27.33 — sends a user turn and streams a grounded prose reply about ONE stored document as Server-Sent Events (`text/event-stream`, not JSON: one `data: <json>\\n\\n` frame per event). Frame `type` is `token` (a chunk of reply text), `done` (`{ type, conversationId, messageId, usage? }`), or `error` (`{ type, code, message }`); HTTP status is 200 even for a provider/refusal outcome (dispatch on the `error` frame). The reply is grounded ONLY in the document's indexed text — NO health snapshot, NO tools, NO other document. The document text is fenced as untrusted DATA (prompt-injection defence); the inbound message + every prior turn are injection-screened and the reply is dose/risk-screened + numerically grounded against the document's own figures. Available only for a content-indexed document (422 `documents.inbound.notIndexed` otherwise). AI-consent-gated (403 `consent.ai.required` for an external provider), budget- and rate-limited. Omitting `conversationId` starts a new thread. Renders as plain text on the client (no markdown). Auth via cookie or Bearer.",
"v1.27.33 — sends a user turn and streams a grounded prose reply about ONE stored document as Server-Sent Events (`text/event-stream`, not JSON: one `data: <json>\\n\\n` frame per event). Frame `type` is `token` (a chunk of reply text), `done` (`{ type, conversationId, messageId, usage? }`), or `error` (`{ type, code, message }`); HTTP status is 200 even for a provider/refusal outcome (dispatch on the `error` frame). The reply is grounded ONLY in the document's indexed text — NO health snapshot, NO tools, NO other document. The document text is fenced as untrusted DATA (prompt-injection defence); the inbound message + every prior turn are injection-screened and the reply is dose/risk-screened + numerically grounded against the document's own figures. Available only for a content-indexed document (422 `documents.inbound.notIndexed` otherwise). Answers under the `documentAi` capability (403 with the capability envelope when it is closed; `consent.ai.required` for a provider that leaves the machine without an `ai_extraction` / `ai_full` receipt), budget- and rate-limited; no provider is the `documents.chat.provider.none` error frame. Reading the history (GET) stays available whatever the capability says. Omitting `conversationId` starts a new thread. Renders as plain text on the client (no markdown). Auth via cookie or Bearer.",
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
],
@@ -984,11 +995,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"403": {
description:
"AI consent required for an external provider (`errorCode: consent.ai.required`).",
content: { "application/json": { schema: errorEnvelope } },
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
@@ -1044,7 +1051,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Index all documents for content search",
description:
"Enqueues a background job that content-indexes the caller's not-yet-indexed documents (one provider transcription each, bounded + resumable). Gated on the module, a configured vision provider (422 `documents.inbound.providerUnsupported` otherwise), and the existing AI consent (403 otherwise). Returns immediately; the work runs off-request on the queue.",
"Enqueues a background job that content-indexes the caller's not-yet-indexed documents (one provider transcription each, bounded + resumable). Gated on the module, the `documentAi` capability (403 with the capability envelope), a configured vision provider (422 `documents.inbound.providerUnsupported` otherwise), and an `ai_extraction` / `ai_full` consent receipt when that provider leaves the machine (403 `consent.ai.required`). Returns immediately; the work runs off-request on the queue, which re-checks the capability before every read.",
responses: {
"200": {
description:
@@ -1060,6 +1067,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
},
+8 -2
View File
@@ -5,6 +5,8 @@
*/
import { z } from "zod/v4";
import type { ZodOpenApiObject } from "zod-openapi";
import { aiExtractionRefusalDescription } from "../ai-extraction-refusals";
import {
createMedicationSchema,
updateMedicationSchema,
@@ -1336,7 +1338,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
summary:
"Extract scheduling fields from a free-text medication description",
description:
"Runs the user's free-text description through the Coach provider chain and returns a citation-guarded partial payload the wizard merges onto whatever the user already typed. `name` and `dose` are dropped when not substring-matched in the original text so the wizard cannot land a hallucinated brand or dose. `cadenceKind` / `doseUnit` / `weekdays` are closed enums; numeric fields are clamped. Rate-limited 10 requests / 5 minutes / user, gated against the daily Coach token budget.",
"Runs the user's free-text description through the Coach provider chain and returns a citation-guarded partial payload the wizard merges onto whatever the user already typed. `name` and `dose` are dropped when not substring-matched in the original text so the wizard cannot land a hallucinated brand or dose. `cadenceKind` / `doseUnit` / `weekdays` are closed enums; numeric fields are clamped. Answers under the `medicationExtract` capability (the operator's reading-documents switch; free-text medication input is health data, so any provider in the chain that leaves the machine needs an active `ai_extraction` or `ai_full` consent receipt). Rate-limited 10 requests / 5 minutes / user, gated against the daily Coach token budget (429 `coach.budget.exceeded`).",
requestBody: {
required: true,
content: {
@@ -1360,9 +1362,13 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"Upstream provider returned an empty, unparseable, or off-schema reply.",
content: { "application/json": { schema: errorEnvelope } },
},
"403": {
description: aiExtractionRefusalDescription("medicationExtract"),
content: { "application/json": { schema: errorEnvelope } },
},
"503": {
description:
"No AI provider configured for the calling user (or operator).",
'No answer could be produced. `meta.errorCode = "ai.provider.none"` (with `meta.capability` and `meta.reason = "no_provider"`): no AI provider is configured for the calling user or the operator — the status predates the capability envelope and is kept for clients that branch on it. `ai.unavailable`: the capability could not be resolved and failed closed. No code: every provider in the chain failed.',
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
+6 -2
View File
@@ -17,6 +17,8 @@ import { z } from "zod/v4";
import { ocrCommitSchema } from "@/lib/validations/labs-ocr";
import { aiExtractionRefusals } from "./ai-extraction-refusals";
import { aiCapabilityState } from "./profile";
import {
dataEnvelope,
idempotencyKeyParameter,
@@ -40,11 +42,12 @@ const capabilityResponse = z
mode: z.enum(["vision", "text"]).nullable(),
reason: z.enum(["no-provider", "enable-local-ocr"]).nullable(),
pdfSupported: z.boolean(),
ai: aiCapabilityState,
})
.meta({
id: "OcrCapabilityResponse",
description:
"Whether the caller's configured AI provider can ingest a lab report (drives the UI's scan affordance). `mode` is `vision` when the provider reads the image directly, `text` when the image is OCR'd in-browser and only the extracted text is sent (opt-in local OCR for text-only providers), or null when unavailable. `reason` explains an unavailable state; `pdfSupported` is true when the provider reads PDFs natively (Anthropic) or the server-side rasterizer can render the pages for any other vision provider. No provider call is made.",
"Whether the caller's configured AI provider can ingest a lab report (drives the UI's scan affordance). `mode` is `vision` when the provider reads the image directly, `text` when the image is OCR'd in-browser and only the extracted text is sent (opt-in local OCR for text-only providers), or null when unavailable. `reason` explains an unavailable state; `pdfSupported` is true when the provider reads PDFs natively (Anthropic) or the server-side rasterizer can render the pages for any other vision provider. `ai` is the `labsOcr` capability for the record: when the operator turned reading documents off, the labs module is off, or the record is somebody else\'s, `available` is false with a null `reason` and `ai.reason` says why. A missing consent receipt leaves the scan offered (`ai.reason = \"consent_required\"`), because the scan is where the person is asked for it. No provider call is made.",
});
const extractConfidence = z.object({
@@ -165,7 +168,7 @@ export const ocrPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Labs"],
summary: "Extract lab readings from a photo, PDF, or OCR'd text",
description:
"Read-only (NOT idempotent) extraction. Two modes by content-type. VISION (`multipart/form-data`): a `file` (JPEG/PNG/WebP, or PDF — read natively on Anthropic, else rasterized to page images for any other vision provider; ≤ 12 MiB) is run through the user's vision-capable provider; the upload lives in memory only and is never persisted or logged. TEXT (`application/json`, opt-in local OCR): the browser OCR's the image (tesseract.js) and POSTs `{ mode: \"text\", text }` — only the extracted text reaches the server, so a text-only provider (e.g. ChatGPT-OAuth) reaches the same review/commit flow. Both modes are gated by AI consent, a per-user hourly rate bucket (default 6, operator-tunable via `LABS_OCR_LIMIT_PER_HOUR`; a slot is only consumed when the scan reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-*` triple and `meta.retryAt`), and the per-day token budget, and return proposed rows for the mandatory human review screen — nothing is written. Extracted content is treated as untrusted (prompt-injection); the review step is the safety boundary.",
"Read-only (NOT idempotent) extraction. Two modes by content-type. VISION (`multipart/form-data`): a `file` (JPEG/PNG/WebP, or PDF — read natively on Anthropic, else rasterized to page images for any other vision provider; ≤ 12 MiB) is run through the user's vision-capable provider; the upload lives in memory only and is never persisted or logged. TEXT (`application/json`, opt-in local OCR): the browser OCR's the image (tesseract.js) and POSTs `{ mode: \"text\", text }` — only the extracted text reaches the server, so a text-only provider (e.g. ChatGPT-OAuth) reaches the same review/commit flow. Both modes are model work and answer under the `labsOcr` capability (the operator's reading-documents switch, the labs module, and — because a lab report is a document — an active `ai_extraction` or `ai_full` consent receipt for any provider that leaves the machine, checked for the provider actually picked: the first vision-capable entry in vision mode, the chain head in text mode). No provider is 422 `labs.ocr.providerUnsupported`; text mode without the local-OCR opt-in is 422 `labs.ocr.localOcrDisabled`. Then both pass a per-user hourly rate bucket (default 6, operator-tunable via `LABS_OCR_LIMIT_PER_HOUR`; a slot is only consumed when the scan reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-*` triple and `meta.retryAt`) and the per-day token budget, and return proposed rows for the mandatory human review screen — nothing is written. Extracted content is treated as untrusted (prompt-injection); the review step is the safety boundary.",
requestBody: {
required: true,
content: {
@@ -200,6 +203,7 @@ export const ocrPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
...aiExtractionRefusals("labsOcr"),
...stdResponses,
},
},
+10 -5
View File
@@ -709,7 +709,7 @@ const glucoseUnitResponse = z
const documentsAutoAiReadPatchRequest = documentsAutoAiReadPatchSchema.meta({
id: "DocumentsAutoAiReadPatchRequest",
description:
"Turn automatic AI reading of newly uploaded documents on or off. Turning it on also mints an `ai_extraction` consent receipt and schedules a catch-up over the existing vault.",
"Turn automatic AI reading of newly uploaded documents on or off. Turning it on also mints an `ai_full` consent receipt and schedules a catch-up over the existing vault.",
});
const documentsAutoAiReadResponse = z
@@ -1044,7 +1044,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Auth"],
summary: "Probe the AI provider connection",
description:
"Sends a tiny fixed prompt to the resolved provider and reports whether it answered. The body is OPTIONAL: with no body the saved configuration is tested; with one, the unsaved selection is tested without touching the user row, so the settings surface can verify a credential before persisting it. Plaintext keys sent this way are never stored.\n\n**This route never returns 5xx, and that is deliberate.** A 5xx from the origin is rewritten to an HTML error page by a reverse proxy or CDN, and the client's `res.json()` then dies on `<!DOCTYPE`. So a provider failure comes back as **200 with `ok: false`** plus a categorised, secret-free `reasonCode`. Branch on `ok`, not on the status. The provider's own error text and body excerpt are logged for the operator and never put on the wire.\n\nThe probe is metered on the same daily AI budget every other AI surface writes to, because with an empty body it can resolve the OPERATOR's shared key — unmetered, that would be invisible spend on a surface that exists to answer 'are my settings right?'. A probe that fails is refunded.\n\nTwo ceilings: 5 per minute and 50 per day, per user.",
"Sends a tiny fixed prompt to the resolved provider and reports whether it answered. The body is OPTIONAL: with no body the saved configuration is tested; with one, the unsaved selection is tested without touching the user row, so the settings surface can verify a credential before persisting it. Plaintext keys sent this way are never stored.\n\n**This route never returns 5xx, and that is deliberate.** A 5xx from the origin is rewritten to an HTML error page by a reverse proxy or CDN, and the client's `res.json()` then dies on `<!DOCTYPE`. So a provider failure comes back as **200 with `ok: false`** plus a categorised, secret-free `reasonCode`. Branch on `ok`, not on the status. The provider's own error text and body excerpt are logged for the operator and never put on the wire.\n\nThe probe is metered on the same daily AI budget every other AI surface writes to, because with an empty body it can resolve the OPERATOR's shared key — unmetered, that would be invisible spend on a surface that exists to answer 'are my settings right?'. A probe that fails is refunded.\n\nTwo ceilings: 5 per minute and 50 per day, per user.\n\nWith the operator\'s master AI switch off the probe is refused (403 `assistant.disabled.enabled`, `meta.reason = \"operator_disabled\"`): no AI call leaves the server then, and this is an AI call. When the switches cannot be read the answer fails closed with 403 `ai.unavailable` (`meta.reason = \"check_failed\"`) rather than the usual 503, for the no-5xx reason above.",
requestBody: {
required: false,
content: { "application/json": { schema: aiTestRequest } },
@@ -1059,6 +1059,11 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"403": {
description:
'The operator\'s master AI switch is off (`meta.errorCode = "assistant.disabled.enabled"`), or the switches could not be read (`ai.unavailable`). Nothing was sent.',
content: { "application/json": { schema: errorEnvelope } },
},
"413": {
description: "Body exceeds 64 KiB.",
content: { "application/json": { schema: errorEnvelope } },
@@ -1071,12 +1076,12 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
...stdResponses,
"422": {
description:
"Nothing could be probed. Either the override body failed validation, or the resolved configuration is not usable — no provider selected, a required key or base URL missing, a model name missing for the gateway, ChatGPT OAuth not connected, or a base URL pointing at an internal host. The message names which.",
'Nothing could be probed. Either the override body failed validation, or the resolved configuration is not usable — no provider selected, a required key or base URL missing, a model name missing for the gateway, ChatGPT OAuth not connected, or a base URL pointing at an internal host. The message names which; a resolved configuration with no provider at all carries `meta.errorCode = "ai.provider.none"`.',
content: { "application/json": { schema: errorEnvelope } },
},
"429": {
description:
"One of three ceilings: 5 probes per minute, 50 per day, or the account's daily AI token budget is exhausted. The message distinguishes them.",
'One of three ceilings: 5 probes per minute, 50 per day, or the account\'s daily AI token budget is exhausted. The message distinguishes them; the budget refusal also carries `meta.errorCode = "ai.budget.exceeded"`.',
content: { "application/json": { schema: errorEnvelope } },
},
},
@@ -1820,7 +1825,7 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
summary: "Set the automatic document-reading opt-in",
description:
"Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" +
"Turning it ON does two further things a caller should expect. It is the consent act for reading documents, so the write appends an `ai_extraction` `ConsentReceipt`: the narrow kind that covers documents, lab report scans and typed medication text and nothing else (not the Coach, not the analysis). DELETE /api/consent/ai/latest revokes it without touching this flag, and the revocation wins: document reading stops even while the flag stays on. And a genuine OFF→ON flip schedules a bounded catch-up over the documents already in the vault, because the summary job is enqueued at upload time and would otherwise only ever apply to future uploads. The catch-up is fire-and-forget and re-runs every consent and budget gate per document.\n\n" +
"Turning it ON does two further things a caller should expect. It is itself the standing consent act, so the write appends an `ai_extraction` `ConsentReceipt` unless one that covers document reads (`ai_extraction` or `ai_full`) is already active. The receipt covers reading documents, lab reports and medication text and nothing else: the Coach and the AI analysis keep asking for their own consent (earlier releases minted `ai_full` here, and those receipts stay valid). DELETE /api/consent/ai/latest?kind=ai_extraction revokes it without touching this flag. And a genuine OFF→ON flip schedules a bounded catch-up over the documents already in the vault, because the summary job is enqueued at upload time and would otherwise only ever apply to future uploads; it is skipped while the `documentAi` capability is closed for the record. The catch-up is fire-and-forget and re-runs every consent and budget gate per document.\n\n" +
"The body cap here is 1 KB, far tighter than the 64 KB its siblings allow — a payload above it is refused with 413 rather than parsed.",
requestBody: {
required: true,
+8
View File
@@ -26,6 +26,8 @@
*/
import { z } from "zod/v4";
import type { AiCapabilityState } from "@/lib/ai/capabilities/types";
/** Max facts a single document may stage / confirm. A dense letter is ~40. */
export const INBOUND_MAX_FACTS = 120;
@@ -840,6 +842,12 @@ export interface DocumentAiCapabilityDto {
* - null: no read is available (see `reason`).
*/
egress: DocumentEgressClass | null;
/**
* The `documentAi` capability for this record. When it is closed by
* anything other than a missing provider or a missing consent receipt,
* `available` is false with a null `reason`, and this says why.
*/
ai: AiCapabilityState;
}
// ─── AI assist / summary / index (Document vault P2) ────────────────────────
+7
View File
@@ -16,6 +16,7 @@
* The DTO types the routes return + the UI consumes are derived here so the
* three layers agree on one shape.
*/
import type { AiCapabilityState } from "@/lib/ai/capabilities/types";
import { z } from "zod/v4";
import type { WrittenOutcome } from "@/lib/outcome/written-outcome";
@@ -258,6 +259,12 @@ export interface OcrCapabilityDto {
reason: "no-provider" | "enable-local-ocr" | null;
/** Whether PDF uploads are accepted (Anthropic vision provider only). */
pdfSupported: boolean;
/**
* The `labsOcr` capability for this record. When it is closed by anything
* other than a missing provider or a missing consent receipt, `available`
* is false with a null `reason`, and this says why.
*/
ai: AiCapabilityState;
}
/**