@happyvertical/smrt-ingestion 0.57.19 → 0.57.21

package/dist/server.js

@@ -1,14 +1,28 @@
+import { c as GenerationSnapshotStaleError, f as generationSnapshotRead, l as GenerationSourceStaleError, p as listReadGate, u as HandlerArgumentsInvalidError } from "./chunks/execution-9CfjxX8I.js";
 import "./models.js";
-import { n as generationSnapshotRead } from "./chunks/execution-internal-DWteDHM2.js";
-import { a as proposalReadConfiguration, i as proposeDocumentSplits, n as createSDKExtractionAdapter, o as assertProposalLimits, r as extractAnalysis, t as GenerationSnapshotStaleError } from "./chunks/proposal-errors-VxcTU6Db.js";
+import { a as assertProposalLimits, i as proposalReadConfiguration, n as extractAnalysis, r as proposeDocumentSplits, t as createSDKExtractionAdapter } from "./chunks/extraction-CJ-zrbg0.js";
+import { i as reviewerInstructionView, n as ReviewerInstructionInvalidError, r as ReviewerInstructionStaleError, t as REVIEWER_INSTRUCTION_MAX_LENGTH } from "./chunks/reviewer-instruction-Db3jDN9a.js";
 import { detectEngine, isEmbeddedDatabase, isTransientDatabaseError, withEmbeddedWriteTransaction } from "@happyvertical/smrt-core";
 import { withTenant } from "@happyvertical/smrt-tenancy";
-import { createHash, randomUUID } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID } from "node:crypto";
 import { Asset } from "@happyvertical/smrt-assets";
 import { SmrtJobCollection } from "@happyvertical/smrt-jobs";
 import { join } from "node:path";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, readFile, readdir, rename, writeFile } from "node:fs/promises";
+//#region src/presented-filename.ts
+var UNSAFE = "[\\p{Cc}\\p{Cf}\\p{Cs}\\p{Zl}\\p{Zp}\\p{Default_Ignorable_Code_Point}]";
+var UNSAFE_CHARACTER = new RegExp(UNSAFE, "u");
+var UNSAFE_CHARACTERS = new RegExp(UNSAFE, "gu");
+function isStorableFilename(value) {
+	return typeof value === "string" && value.trim().length > 0 && value.length <= 512 && !UNSAFE_CHARACTER.test(value);
+}
+function presentedFilename(value) {
+	if (typeof value !== "string") return void 0;
+	const name = value.replace(UNSAFE_CHARACTERS, "").trim();
+	return isStorableFilename(name) ? name : void 0;
+}
+//#endregion
 //#region src/review-analysis.ts
 async function loadReviewAnalysis(service, item, reviews, cursor) {
 	if (!["completed", "partial"].includes(item.processingState) || reviews.generationStale) return { reviews };
@@ -23,6 +37,28 @@ async function loadReviewAnalysis(service, item, reviews, cursor) {
 	}
 }
 //#endregion
+//#region src/review-instruction-view.ts
+async function loadInstructionView(service, itemId, analysis) {
+	let [latest] = await service.listReviewerInstructions(itemId);
+	const applied = analysis?.configuration.stage === "interpret" && analysis.configuration.reviewerInstruction ? reviewerInstructionView(analysis.configuration.reviewerInstruction) : null;
+	if (!latest && !applied) return void 0;
+	const state = await service.getReinterpretationState(itemId);
+	if (state.instructionInEffect !== null && state.instructionInEffect !== latest?.id) [latest] = await service.listReviewerInstructions(itemId);
+	const current = latest && latest.id === state.instructionInEffect ? latest : null;
+	return {
+		current,
+		applied,
+		stale: !!analysis && !!current && current.id !== applied?.id,
+		...latest && state.instructionInEffect === null ? { dropped: latest } : {},
+		...state.failure ? { failure: state.failure } : {},
+		...state.reinterpreting ? { reinterpreting: true } : {},
+		...analysis?.configuration.stage !== "interpret" && state.generationAttemptId ? { binding: {
+			attemptId: state.generationAttemptId,
+			expectedRevision: state.revision
+		} } : {}
+	};
+}
+//#endregion
 //#region src/review-summary.ts
 async function loadReviewSummary(service, item, requestedCursor) {
 	let requested;
@@ -45,7 +81,7 @@ async function loadReviewSummary(service, item, requestedCursor) {
 	} while (cursor);
 	const current = await service.getItem(item.id);
 	if (!requested) throw new Error("Review page unavailable");
-	const state = total ? succeeded === total ? "completed" : succeeded ? "partially_completed" : deferred ? "deferred" : failed ? "failed" : "waiting" : ["queued", "running"].includes(current.processingState) ? "processing" : current.processingState === "needs_attention" ? "failed" : "unresolved";
+	const state = ["queued", "running"].includes(current.processingState) ? "processing" : total ? succeeded === total ? "completed" : succeeded ? "partially_completed" : deferred ? "deferred" : failed ? "failed" : "waiting" : current.processingState === "needs_attention" ? "failed" : "unresolved";
 	return {
 		reviews: requested,
 		state
@@ -53,31 +89,139 @@ async function loadReviewSummary(service, item, requestedCursor) {
 }
 //#endregion
 //#region src/review-host.ts
+function primaryEvidence(parts) {
+	const depth = (part) => {
+		let level = 0;
+		let parent = part.parentEvidenceId;
+		const seen = /* @__PURE__ */ new Set();
+		while (parent && !seen.has(parent)) {
+			seen.add(parent);
+			level++;
+			parent = parts.find((p) => p.id === parent)?.parentEvidenceId ?? null;
+		}
+		return level;
+	};
+	const ordered = [...parts].sort((a, b) => depth(a) - depth(b) || a.partId.localeCompare(b.partId, "en", { numeric: true }));
+	return ordered.find((part) => depth(part) > 0) ?? ordered[0];
+}
 function createIntakeReviewHost(service, options) {
-	const label = options.label ?? ((item) => `Intake ${item.id.slice(0, 8)}`);
-	const entry = async (item) => {
-		const { state } = await loadReviewSummary(service, item);
-		const assignment = await options.assignment(item.id);
-		await service.getItem(item.id);
-		return {
-			item,
-			label: label(item),
-			state,
-			assignment
-		};
+	const label = options.label ?? ((item, evidence) => primaryEvidence(evidence)?.filename ?? `Intake ${item.id.slice(0, 8)}`);
+	const labelled = (parts) => {
+		const primary = primaryEvidence(parts);
+		return primary ? [primary, ...parts.filter((part) => part !== primary)] : [...parts];
+	};
+	const decorateRows = async (entries) => {
+		if (!entries.length) return entries;
+		let parts;
+		try {
+			parts = await service.listEvidence(entries.map((entry) => entry.item.id));
+		} catch (error) {
+			if (options.rowEvidence) throw error;
+			return entries.map((entry) => ({
+				...entry,
+				label: label(entry.item, [])
+			}));
+		}
+		const named = entries.map((entry) => ({
+			...entry,
+			label: label(entry.item, labelled(parts.get(entry.item.id) ?? []))
+		}));
+		if (!options.rowEvidence) return named;
+		const rows = [];
+		for (const entry of named) {
+			const primary = primaryEvidence(parts.get(entry.item.id) ?? []);
+			if (primary) rows.push({
+				itemId: entry.item.id,
+				evidence: primary
+			});
+		}
+		if (!rows.length) return named;
+		const primaries = new Map(rows.map((row) => [row.itemId, row.evidence]));
+		try {
+			const views = await options.rowEvidence(rows);
+			return named.map((entry) => {
+				const primary = primaries.get(entry.item.id);
+				if (!primary) return entry;
+				const view = views.get(entry.item.id);
+				if (!view) return entry;
+				if (typeof view.label !== "string") throw new Error("Invalid row evidence");
+				const evidence = {
+					evidence: primary,
+					label: view.label
+				};
+				if (typeof view.viewUrl === "string") evidence.viewUrl = view.viewUrl;
+				if (typeof view.thumbnailUrl === "string") evidence.thumbnailUrl = view.thumbnailUrl;
+				return {
+					...entry,
+					evidence
+				};
+			});
+		} catch {
+			return named;
+		}
+	};
+	const assignments = async (itemIds) => {
+		if (!itemIds.length) return /* @__PURE__ */ new Map();
+		if (options.assignments) return options.assignments(itemIds);
+		const read = /* @__PURE__ */ new Map();
+		for (const itemId of itemIds) read.set(itemId, await options.assignment(itemId));
+		return read;
 	};
 	return {
 		async list(input) {
-			const items = (await service.listItems()).sort((a, b) => a.id.localeCompare(b.id)).filter((item) => !input.cursor || item.id > input.cursor).slice(0, 21);
-			const projected = [];
-			for (const item of items.slice(0, 20)) {
-				const current = await entry(item);
-				if ((!input.state || current.state === input.state) && (!input.assigneeId || current.assignment.assigneeId === input.assigneeId)) projected.push(current);
+			const requested = input.limit ?? 20;
+			const limit = Number.isNaN(requested) ? 20 : Math.min(100, Math.max(1, Math.floor(requested)));
+			let itemIds;
+			if (input.assigneeId && options.assignedItemIds) {
+				const assigned = [...new Set((await options.assignedItemIds(input.assigneeId)).filter(isIntakeId))];
+				if (assigned.length <= 1e3) itemIds = assigned;
+			}
+			const items = [];
+			let cursor = input.cursor;
+			let examined = 0;
+			for (;;) {
+				let page;
+				try {
+					page = await service.listItemsPage({
+						limit,
+						cursor,
+						state: input.state,
+						itemIds,
+						scanLimit: ITEM_SCAN_CEILING - examined
+					});
+				} catch (error) {
+					if (error instanceof IntakeScanLimitError && cursor !== input.cursor) return {
+						items: await decorateRows(items),
+						...cursor ? { nextCursor: cursor } : {}
+					};
+					throw error;
+				}
+				examined += page.scanned;
+				const read = await assignments(page.items.map(({ item }) => item.id));
+				for (const [index, { item, state, cursor: rowCursor }] of page.items.entries()) {
+					const assignment = read.get(item.id) ?? {
+						assigneeId: null,
+						version: 0
+					};
+					if (input.assigneeId && assignment.assigneeId !== input.assigneeId) continue;
+					items.push({
+						item,
+						label: "",
+						state,
+						assignment
+					});
+					if (items.length === limit) return {
+						items: await decorateRows(items),
+						...page.nextCursor || index < page.items.length - 1 ? { nextCursor: rowCursor } : {}
+					};
+				}
+				if (!page.nextCursor) return { items: await decorateRows(items) };
+				if (page.items.length < limit || examined >= 1e3) return {
+					items: await decorateRows(items),
+					nextCursor: page.nextCursor
+				};
+				cursor = page.nextCursor;
 			}
-			return {
-				items: projected,
-				...items.length > 20 ? { nextCursor: items[19].id } : {}
-			};
 		},
 		async load(itemId, cursor) {
 			const item = await service.getItem(itemId);
@@ -89,30 +233,33 @@ function createIntakeReviewHost(service, options) {
 				evidence: part
 			});
 			const assignment = await options.assignment(itemId);
+			const instruction = await loadInstructionView(service, itemId, analysis);
 			await service.getItem(itemId);
 			return {
 				entry: {
 					item,
-					label: label(item),
+					label: label(item, labelled(evidence.map((view) => view.evidence))),
 					state: summary.state,
 					assignment
 				},
 				evidence,
 				analysis,
 				reviews,
+				...instruction ? { instruction } : {},
 				availability: "available",
 				...analysis?.configuration.stage === "interpret" ? { generation: analysis.result.output.proposals } : {}
 			};
 		},
 		upload: (files, requestId) => options.upload(files, requestId),
 		async preview(input) {
-			if (!Number.isSafeInteger(input.index) || input.index < 0 || typeof input.attemptId !== "string" || !input.attemptId || typeof input.requestId !== "string" || !input.requestId.trim()) throw new Error("Invalid preview");
+			if (!Number.isSafeInteger(input.index) || input.index < 0 || typeof input.attemptId !== "string" || !input.attemptId || typeof input.requestId !== "string" || !input.requestId.trim() || input.args !== void 0 && (!input.args || typeof input.args !== "object" || Array.isArray(input.args))) throw new Error("Invalid preview");
 			const analysis = await service.getCompletedAnalysis(input.itemId, input.attemptId);
 			const generation = analysis.result.output.proposals;
-			if (analysis.configuration.stage !== "interpret" || generation?.suggestions[input.index]?.disposition !== "ready_for_review") throw new Error("Preview unavailable");
-			const suggestion = generation.suggestions[input.index];
+			const suggestion = generation?.suggestions[input.index];
+			if (analysis.configuration.stage !== "interpret" || generation?.outcome === "provider_error" || !suggestion || !["ready_for_review", "needs_review"].includes(suggestion.disposition)) throw new Error("Preview unavailable");
 			const handler = generation.offered.find(({ handler: handler2 }) => handler2.id === suggestion.handlerId && handler2.version === suggestion.handlerVersion)?.handler;
 			if (!handler) throw new Error("Preview unavailable");
+			const args = input.args ? structuredClone(input.args) : suggestion.args;
 			const intentionKey = `ui:${input.index}`;
 			const actionId = handler.kind === "plan" ? void 0 : await service.createAction(input.itemId, intentionKey, {
 				origin: "generated-proposal",
@@ -129,7 +276,7 @@ function createIntakeReviewHost(service, options) {
 					expectedRevision = handler.kind === "plan" ? found.plan?.revision ?? found.stalePlan?.revision ?? 0 : found.review.revision;
 					if (binding?.attemptId === input.attemptId && binding.handlerId === suggestion.handlerId && binding.handlerVersion === suggestion.handlerVersion && binding.args) {
 						const { intakeBindingDigest } = await import("./execution.js");
-						if (intakeBindingDigest(binding.args) === intakeBindingDigest(suggestion.args)) return;
+						if (intakeBindingDigest(binding.args) === intakeBindingDigest(args)) return;
 					}
 					break;
 				}
@@ -137,6 +284,26 @@ function createIntakeReviewHost(service, options) {
 				if (cursor && cursors.has(cursor)) throw new Error("Repeated review cursor");
 				if (cursor) cursors.add(cursor);
 			} while (cursor);
+			if (input.args) {
+				const shared = {
+					itemId: input.itemId,
+					attemptId: input.attemptId,
+					expectedRevision,
+					requestId: input.requestId,
+					handlerId: suggestion.handlerId,
+					handlerVersion: suggestion.handlerVersion,
+					args
+				};
+				if (handler.kind === "plan") await service.previewPlan({
+					...shared,
+					planKey: intentionKey
+				});
+				else if (actionId) await service.previewProposal({
+					...shared,
+					actionId
+				});
+				return;
+			}
 			await service.previewGeneratedProposals({
 				itemId: input.itemId,
 				attemptId: input.attemptId,
@@ -167,6 +334,17 @@ function createIntakeReviewHost(service, options) {
 			const result = await service.reviseLogicalSplit(input);
 			await options.onSplit?.(input.itemId, result.revision);
 		},
+		async instruct(input) {
+			let result;
+			try {
+				result = await service.recordReviewerInstruction(input);
+			} catch (error) {
+				if (error instanceof ReviewerInstructionStaleError) return { stale: true };
+				if (error instanceof ReviewerInstructionInvalidError) return { invalid: true };
+				throw error;
+			}
+			await options.onInstruct?.(input.itemId, result.revision);
+		},
 		...options.enableFeedback ? { feedback: (input) => service.recordFeedback(input) } : {}
 	};
 }
@@ -190,6 +368,10 @@ function text(value) {
 	if (typeof value !== "string" || !value || value.length > 1024) throw new SourceInputError("invalid");
 	return value;
 }
+function withPresentedFilename(value) {
+	const filename = presentedFilename(value);
+	return filename ? { filename } : {};
+}
 function timestamp(value) {
 	const date = new Date(text(value));
 	if (!Number.isFinite(date.getTime())) throw new SourceInputError("invalid");
@@ -286,7 +468,10 @@ async function deliver(binding, deliveryKey, deliveredAt, parts) {
 			limits: binding.limits,
 			deliveryKey,
 			deliveredAt,
-			parts
+			parts: parts.map(({ filename, ...part }) => ({
+				...part,
+				...withPresentedFilename(filename)
+			}))
 		});
 	} catch (error) {
 		return safeFailure(error);
@@ -352,6 +537,7 @@ var EmailSourceAdapter = class {
 					parentPartId: "message",
 					mediaType: attachment.mediaType,
 					bytes: attachment.bytes,
+					filename: attachment.filename,
 					sourceReference: {
 						owner: "message-attachment",
 						id: `${delivery.locator}:${attachment.partId}`,
@@ -485,11 +671,14 @@ function createSourceDeliveryHandler(options) {
 					fields[name] = value;
 				} else {
 					if (name !== "file" || parts.length) throw new SourceInputError("invalid");
+					const presented = presentedFilename(value.name);
+					const original = presented === "blob" ? void 0 : presented;
 					parts.push({
 						partId: "file",
 						parentPartId: "capture",
 						mediaType: value.type,
-						bytes: await boundedBytes(value.stream(), binding.limits.maxBytes)
+						bytes: await boundedBytes(value.stream(), binding.limits.maxBytes),
+						...original ? { filename: original } : {}
 					});
 				}
 				if (parts.length !== 1 || text(fields.captureId) !== key || ![
@@ -604,6 +793,7 @@ var WatchFolderSourceAdapter = class {
 				partId: "original",
 				mediaType,
 				bytes,
+				filename: claim.filename,
 				sourceReference: {
 					owner: "watch-folder",
 					id: claim.filename,
@@ -763,9 +953,65 @@ function bytesHash(value) {
 function nonempty(value) {
 	if (typeof value !== "string" || !value.trim() || value.length > 512) throw new Error("Invalid intake identifier");
 }
+function filename(value) {
+	if (!isStorableFilename(value)) throw new Error("Invalid intake filename");
+}
 function integer(value, max = 2147483647) {
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > max) throw new Error("Invalid intake limit");
 }
+var ITEM_PAGE_DEFAULT = 20;
+var ITEM_PAGE_CEILING = 100;
+var ITEM_SCAN_CEILING = 1e3;
+var ITEM_ID_FILTER_CEILING = 1e3;
+function isIntakeId(value) {
+	return typeof value === "string" && uuid.test(value);
+}
+var INBOX_STATES = [
+	"processing",
+	"unresolved",
+	"waiting",
+	"failed",
+	"deferred",
+	"partially_completed",
+	"completed"
+];
+function actionCount(where = "") {
+	return `(SELECT COUNT(*) FROM intake_actions a WHERE a.tenant_id = i.tenant_id AND a.confidential_scope_id = i.confidential_scope_id AND a.item_id = i.id${where ? ` AND ${where}` : ""})`;
+}
+var INBOX_STATE_SQL = `CASE WHEN i.processing_state IN ('queued','running') THEN 'processing' WHEN ${actionCount()} = 0 THEN CASE WHEN i.processing_state = 'needs_attention' THEN 'failed' ELSE 'unresolved' END WHEN ${actionCount("a.state <> 'succeeded'")} = 0 THEN 'completed' WHEN ${actionCount("a.state = 'succeeded'")} > 0 THEN 'partially_completed' WHEN ${actionCount("a.state = 'deferred'")} > 0 THEN 'deferred' WHEN ${actionCount("a.state IN ('failed','outcome_unknown')")} > 0 THEN 'failed' ELSE 'waiting' END`;
+var RECEIPT_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function receiptTime(row) {
+	const value = row.created_at;
+	if (typeof value === "string") return RECEIPT_TIME.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value ? value : void 0;
+	if (value instanceof Date && Number.isFinite(value.getTime()) && (row.receipt_ms === true || Number(row.receipt_ms) === 1)) return value.toISOString();
+}
+var IntakeScanLimitError = class extends Error {
+	constructor() {
+		super("Intake scan limit");
+		this.name = "IntakeScanLimitError";
+	}
+};
+var SEALED_CURSOR_BYTES = 1024;
+var SCAN_KEY_CHARS = 64;
+function samePosition(a, b) {
+	return a.key === b.key && a.id === b.id;
+}
+function encodeItemCursor(receivedAt, id) {
+	return Buffer.from(JSON.stringify([receivedAt, id])).toString("base64url");
+}
+function decodeItemCursor(cursor) {
+	let parsed;
+	try {
+		parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+	} catch {
+		throw new Error("Invalid item page");
+	}
+	if (!Array.isArray(parsed) || parsed.length !== 2 || typeof parsed[0] !== "string" || !Number.isFinite(Date.parse(parsed[0])) || new Date(parsed[0]).toISOString() !== parsed[0] || typeof parsed[1] !== "string" || !uuid.test(parsed[1])) throw new Error("Invalid item page");
+	return {
+		receivedAt: parsed[0],
+		id: parsed[1]
+	};
+}
 function persistedDate(value) {
 	return value instanceof Date ? value : new Date(String(value));
 }
@@ -783,12 +1029,18 @@ var IngestionService = class {
 		}
 		this.db = options.db;
 		this.scope = Object.freeze({ ...options.scope });
+		if (options.cursorKey !== void 0) {
+			const secret = typeof options.cursorKey === "string" ? Buffer.from(options.cursorKey, "utf8") : Buffer.from(options.cursorKey);
+			if (secret.length < 32) throw new Error("Cursor key must be at least 32 bytes");
+			this.cursorKey = createHash("sha256").update("smrt-ingestion:list-cursor:v1").update(secret).digest();
+		}
 		if (!uuid.test(this.scope.tenantId)) throw new Error("Required tenant UUID");
 		nonempty(this.scope.actorId);
 		nonempty(this.scope.confidentialScopeId);
 		const configured = this.db;
 		const engine = detectEngine(this.db.url || configured.config?.url || "", configured.type || configured.config?.type);
 		if (!["sqlite", "postgres"].includes(engine) || !this.db.transaction) throw new Error("Ingestion requires transactional SQLite or PostgreSQL");
+		this.engine = engine;
 		nonempty(options.jobTarget.objectType);
 		nonempty(options.jobTarget.method);
 		this.dispatchTarget = Object.freeze({
@@ -800,6 +1052,8 @@ var IngestionService = class {
 	options;
 	db;
 	scope;
+	engine;
+	cursorKey;
 	dispatchTarget;
 	async execution() {
 		if (!this.options.execution) throw new Error("Intake execution is not configured");
@@ -860,7 +1114,7 @@ var IngestionService = class {
 		return (await this.proposalReader()).preview(input);
 	}
 	async feedback() {
-		const { IntakeFeedbackService } = await import("./chunks/feedback-CJB900iG.js").then((n) => n.r);
+		const { IntakeFeedbackService } = await import("./chunks/feedback-CuUzWKzP.js").then((n) => n.r);
 		return new IntakeFeedbackService(this.options);
 	}
 	async recordFeedback(input) {
@@ -970,6 +1224,7 @@ var IngestionService = class {
 				total += part.bytes.byteLength;
 				const hash = bytesHash(part.bytes);
 				if (part.expectedHash && part.expectedHash !== hash) throw new Error("Invalid hash");
+				if (part.filename !== void 0) filename(part.filename);
 				return {
 					...part,
 					bytes: Buffer.from(part.bytes),
@@ -1057,7 +1312,10 @@ var IngestionService = class {
 					byte_length: part.bytes.byteLength,
 					media_type: part.mediaType,
 					source_uri: "",
-					data: canonical({ sourceReference: part.sourceReference ?? null })
+					data: canonical({
+						sourceReference: part.sourceReference ?? null,
+						...part.filename === void 0 ? {} : { filename: part.filename }
+					})
 				});
 			}
 			return {
@@ -1385,15 +1643,286 @@ var IngestionService = class {
 		}
 		return repaired;
 	}
-	/** List only authorized active items; omitted items do not contribute counts. */
+	/**
+	* One authorized inbox page, newest receipt first with the id as tiebreak.
+	* Tenant, confidential scope, retention and the id restriction run in the
+	* query; rows are authorized before the `state` filter is applied to the
+	* fetched batch, so every filter is bounded by the scan limit (default
+	* ITEM_SCAN_CEILING). Authority is rechecked at two levels: the host
+	* `authorize('read')` once per distinct captured ceiling, and the execution
+	* read gate once per distinct (item, handler) bound by a scanned row that
+	* passed the first. Without a `cursorKey` every cursor names a row the
+	* actor can read; with one, all cursors are sealed and a budget-stopped
+	* page may resume past rows the actor cannot read. `scanned` is for trusted
+	* host accounting and must not be sent to clients.
+	*/
+	async listItemsPage(input = {}) {
+		const limit = input.limit ?? ITEM_PAGE_DEFAULT;
+		if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || input.state !== void 0 && !INBOX_STATES.includes(input.state) || input.itemIds !== void 0 && (!Array.isArray(input.itemIds) || input.itemIds.length > 1e3 || !input.itemIds.every(isIntakeId)) || input.scanLimit !== void 0 && (!Number.isSafeInteger(input.scanLimit) || input.scanLimit < 1 || input.scanLimit > 1e3)) throw new Error("Invalid item page");
+		if (input.itemIds && !input.itemIds.length) return {
+			items: [],
+			scanned: 0
+		};
+		const start = input.cursor ? this.decodeCursor(input.cursor) : void 0;
+		const scan = await this.scanItems(input, limit, input.scanLimit ?? 1e3, start);
+		const items = scan.items.map(({ item, state, position: position2 }) => ({
+			item,
+			state,
+			cursor: this.encodeCursor(position2)
+		}));
+		if (scan.done) return {
+			items,
+			scanned: scan.scanned
+		};
+		const last = scan.items.at(-1)?.position;
+		if (scan.full && last) return {
+			items,
+			scanned: scan.scanned,
+			nextCursor: this.encodeCursor(last)
+		};
+		const position = this.cursorKey ? scan.scanFrom : scan.lastReadable;
+		if (!position || start && samePosition(position, start)) throw new IntakeScanLimitError();
+		return {
+			items,
+			scanned: scan.scanned,
+			nextCursor: this.encodeCursor(position)
+		};
+	}
+	/**
+	* The bounded page scan behind `listItemsPage` and `listItems`. It returns
+	* the rows to list with their positions, the exact scan position reached
+	* (`scanFrom`, which may be a row the actor cannot read and must never
+	* leave the service unsealed), and the last row the actor can read
+	* (`lastReadable`, which may not match the `state` filter).
+	*/
+	async scanItems(input, limit, scanCeiling, start) {
+		let scanFrom = start;
+		let lastReadable;
+		const now = this.now().toISOString();
+		const allowed = this.ceilingGate();
+		const handlers = this.handlerGate();
+		const items = [];
+		let examined = 0;
+		const sqlite = this.engine === "sqlite";
+		const pinned = sqlite && !input.itemIds ? " INDEXED BY intake_items_received_idx" : "";
+		const textOnly = sqlite ? ` AND typeof(i.created_at) = 'text' AND length(i.created_at) <= ${SCAN_KEY_CHARS} AND length(i.id) <= ${SCAN_KEY_CHARS} AND instr(i.created_at, char(0)) = 0 AND instr(i.id, char(0)) = 0` : "";
+		const receipt = sqlite ? "i.created_at AS receipt_raw, 1 AS receipt_ms" : "i.created_at::text AS receipt_raw, (i.created_at = date_trunc('milliseconds', i.created_at)) AS receipt_ms";
+		for (;;) {
+			const params = [
+				this.scope.tenantId,
+				this.scope.confidentialScopeId,
+				now
+			];
+			let where = textOnly;
+			if (scanFrom) {
+				where += " AND (i.created_at < ? OR (i.created_at = ? AND i.id < ?))";
+				params.push(scanFrom.key, scanFrom.key, scanFrom.id);
+			}
+			if (input.itemIds) {
+				where += ` AND i.id IN (${input.itemIds.map(() => "?").join(",")})`;
+				params.push(...input.itemIds);
+			}
+			const wanted = limit - items.length;
+			const batch = Math.min(scanCeiling - examined, Math.max(wanted, Math.min(100, examined)));
+			const rows = (await this.db.query(`SELECT i.*, ${INBOX_STATE_SQL} AS inbox_state, ${actionCount()} AS action_count, ${receipt} FROM intake_items i${pinned} WHERE i.tenant_id = ? AND i.confidential_scope_id = ? AND i.visibility = 'active' AND i.expires_at > ?${where} ORDER BY i.created_at DESC, i.id DESC LIMIT ?`, ...params, batch + 1)).rows;
+			const more = rows.length > batch;
+			const candidates = rows.slice(0, batch);
+			const passed = /* @__PURE__ */ new Set();
+			for (const row of candidates) {
+				let data;
+				try {
+					data = object(row.data);
+				} catch {
+					continue;
+				}
+				if (await allowed(data)) passed.add(row);
+			}
+			await handlers.resolve(candidates.filter((row) => passed.has(row) && Number(row.action_count) > 0));
+			let consumed = 0;
+			for (const row of candidates) {
+				consumed++;
+				examined++;
+				const id = String(row.id);
+				const receivedAt = receiptTime(row);
+				if (receivedAt !== void 0) scanFrom = {
+					key: receivedAt,
+					id
+				};
+				else if (typeof row.receipt_raw === "string") scanFrom = {
+					key: row.receipt_raw,
+					id
+				};
+				if (receivedAt === void 0 || !isIntakeId(id) || !passed.has(row)) continue;
+				if (Number(row.action_count) > 0 && !await handlers.readable(row)) continue;
+				const position = {
+					key: receivedAt,
+					id
+				};
+				lastReadable = position;
+				if (input.state && row.inbox_state !== input.state) continue;
+				items.push({
+					item: this.itemDTO(row),
+					state: String(row.inbox_state),
+					position
+				});
+				if (items.length === limit) break;
+			}
+			const remaining = more || consumed < candidates.length;
+			const full = items.length === limit;
+			if (!remaining || full || examined >= scanCeiling) return {
+				items,
+				scanned: examined,
+				done: !remaining,
+				full,
+				scanFrom,
+				lastReadable
+			};
+		}
+	}
+	/** Associated data that binds a sealed cursor to this authenticated scope. */
+	cursorScope() {
+		return Buffer.from(canonical({
+			tenantId: this.scope.tenantId,
+			confidentialScopeId: this.scope.confidentialScopeId,
+			actorId: this.scope.actorId
+		}));
+	}
+	encodeCursor(position) {
+		if (!this.cursorKey) return encodeItemCursor(position.key, position.id);
+		const body = Buffer.alloc(SEALED_CURSOR_BYTES, 32);
+		const json = Buffer.from(JSON.stringify([position.key, position.id]));
+		if (json.length > SEALED_CURSOR_BYTES) throw new Error("Cursor position too long");
+		json.copy(body);
+		const iv = randomBytes(12);
+		const cipher = createCipheriv("aes-256-gcm", this.cursorKey, iv);
+		cipher.setAAD(this.cursorScope());
+		const sealed = Buffer.concat([cipher.update(body), cipher.final()]);
+		return Buffer.concat([
+			iv,
+			cipher.getAuthTag(),
+			sealed
+		]).toString("base64url");
+	}
+	decodeCursor(cursor) {
+		if (!this.cursorKey) {
+			const { receivedAt, id } = decodeItemCursor(cursor);
+			return {
+				key: receivedAt,
+				id
+			};
+		}
+		try {
+			const bytes = Buffer.from(cursor, "base64url");
+			if (bytes.length !== 1052) throw new Error("size");
+			const decipher = createDecipheriv("aes-256-gcm", this.cursorKey, bytes.subarray(0, 12));
+			decipher.setAAD(this.cursorScope());
+			decipher.setAuthTag(bytes.subarray(12, 28));
+			const parsed = JSON.parse(Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString("utf8"));
+			if (!Array.isArray(parsed) || parsed.length !== 2 || typeof parsed[0] !== "string" || !parsed[0] || typeof parsed[1] !== "string" || !parsed[1]) throw new Error("shape");
+			return {
+				key: parsed[0],
+				id: parsed[1]
+			};
+		} catch {
+			throw new Error("Invalid item page");
+		}
+	}
+	/**
+	* Every authorized active item, newest receipt first.
+	* @deprecated Use `listItemsPage`. Kept so callers of the array-returning
+	* API keep working. It walks every page, so its cost grows with the scope,
+	* including one execution authorization per (item, handler) across the
+	* whole scope. It follows the internal scan position, which never leaves
+	* the service, so runs of rows the actor cannot read never stop it. Items
+	* are gated exactly as on a page.
+	*/
 	async listItems() {
-		const rows = await this.rows(this.db, "intake_items", "visibility='active' AND expires_at>?", [this.now().toISOString()]);
-		const result = [];
-		for (const row of rows) try {
-			await this.authorize("read", object(row.data));
-			result.push(this.itemDTO(row));
-		} catch {}
-		return result;
+		const all = [];
+		let from;
+		for (;;) {
+			const scan = await this.scanItems({}, 100, ITEM_SCAN_CEILING, from);
+			all.push(...scan.items.map(({ item }) => item));
+			if (scan.done) return all;
+			if (!scan.scanFrom || from && samePosition(scan.scanFrom, from)) throw new Error("Intake list made no progress");
+			from = scan.scanFrom;
+		}
+	}
+	/**
+	* One read authorization per distinct captured ceiling for a page of rows.
+	* A refusal hides the rows; a malformed ceiling hides its row; a host
+	* callback that throws rejects the page with that error.
+	*/
+	ceilingGate() {
+		const ceilings = /* @__PURE__ */ new Map();
+		return (data) => {
+			let ceiling;
+			try {
+				ceiling = object(data.capturedCeiling ?? {});
+			} catch {
+				return Promise.resolve(false);
+			}
+			const key = canonical(ceiling);
+			let decision = ceilings.get(key);
+			if (!decision) {
+				decision = Promise.resolve(this.options.authorize({
+					scope: this.scope,
+					operation: "read",
+					capturedCeiling: ceiling,
+					db: this.db
+				})).then((granted) => granted === true);
+				ceilings.set(key, decision);
+			}
+			return decision;
+		};
+	}
+	/**
+	* The handler checks `listReviews` applies per action, batched for a page:
+	* the bindings of the rows' current proposals are projected in SQL
+	* (handler id, version, operation and capability; distinct per item) once
+	* per fetched batch, then the execution list read gate runs once per distinct
+	* (item, handler) of a row that passed the item-level gate. An item whose
+	* bound handler the actor cannot currently read, whose binding drifted
+	* from the configured handler, or whose bindings cannot be resolved, is
+	* not listed. Actions without a proposal carry no handler and are not
+	* gated, as in `listReviews`.
+	*/
+	handlerGate() {
+		const bound = /* @__PURE__ */ new Map();
+		let execution;
+		const service = () => {
+			execution ??= (this.options.execution ? this.execution() : Promise.resolve(void 0)).catch(() => void 0);
+			return execution;
+		};
+		const field = (name, text) => this.engine === "sqlite" ? `json_extract(p.data, '$.binding.${name}')` : `(p.data::jsonb)->'binding'${text ? "->>" : "->"}'${name}'`;
+		const parsed = (value) => {
+			if (typeof value !== "string") return value;
+			try {
+				return JSON.parse(value);
+			} catch {
+				return;
+			}
+		};
+		return {
+			resolve: async (rows) => {
+				const pending = rows.filter((row) => !bound.has(String(row.id)));
+				if (!pending.length) return;
+				for (const row of pending) bound.set(String(row.id), []);
+				const found = (await this.db.query(`SELECT DISTINCT p.item_id, ${field("handlerId", true)} AS handler_id, ${field("handlerVersion", true)} AS handler_version, ${field("operation", false)} AS operation, ${field("capability", false)} AS capability FROM intake_proposals p JOIN intake_actions a ON a.tenant_id = p.tenant_id AND a.confidential_scope_id = p.confidential_scope_id AND a.id = p.action_id AND a.proposal_revision = p.revision WHERE p.tenant_id = ? AND p.confidential_scope_id = ? AND p.item_id IN (${pending.map(() => "?").join(",")})`, this.scope.tenantId, this.scope.confidentialScopeId, ...pending.map((row) => String(row.id)))).rows;
+				for (const row of found) bound.get(String(row.item_id))?.push({
+					handlerId: row.handler_id == null ? "" : String(row.handler_id),
+					handlerVersion: row.handler_version == null ? "" : String(row.handler_version),
+					operation: parsed(row.operation),
+					capability: parsed(row.capability)
+				});
+			},
+			readable: async (row) => {
+				for (const binding of bound.get(String(row.id)) ?? []) {
+					const gate = await service();
+					if (!gate || !await gate[listReadGate](row, binding)) return false;
+				}
+				return true;
+			}
+		};
 	}
 	itemDTO(row) {
 		return {
@@ -1410,14 +1939,48 @@ var IngestionService = class {
 	}
 	async getEvidence(itemId) {
 		await this.item(itemId, "read");
-		return (await this.rows(this.db, "intake_evidence", "item_id=? AND state='durable'", [itemId])).map((e) => ({
+		return (await this.rows(this.db, "intake_evidence", "item_id=? AND state='durable'", [itemId])).map((e) => this.evidenceDTO(e));
+	}
+	/**
+	* Durable evidence for one inbox page in a single query, keyed by item id.
+	* Items that are not active, retained and readable are omitted (no
+	* existence disclosure); the host authorize callback runs once per distinct
+	* captured ceiling rather than once per item, through the same gate as
+	* `listItemsPage`: a refusal or a malformed ceiling hides the item, and a
+	* host callback that throws rejects the read.
+	*/
+	async listEvidence(itemIds) {
+		if (!Array.isArray(itemIds) || itemIds.length > 100 || !itemIds.every(isIntakeId)) throw new Error("Invalid item page");
+		const result = /* @__PURE__ */ new Map();
+		if (!itemIds.length) return result;
+		const rows = (await this.db.query(`SELECT e.*, i.data AS item_data FROM intake_evidence e JOIN intake_items i ON i.tenant_id = e.tenant_id AND i.confidential_scope_id = e.confidential_scope_id AND i.id = e.item_id WHERE e.tenant_id = ? AND e.confidential_scope_id = ? AND e.state = 'durable' AND i.visibility = 'active' AND i.expires_at > ? AND e.item_id IN (${itemIds.map(() => "?").join(",")}) ORDER BY e.item_id, e.part_id`, this.scope.tenantId, this.scope.confidentialScopeId, this.now().toISOString(), ...itemIds)).rows;
+		const allowed = this.ceilingGate();
+		for (const row of rows) {
+			let data;
+			try {
+				data = object(row.item_data);
+			} catch {
+				continue;
+			}
+			if (!await allowed(data)) continue;
+			const itemId = String(row.item_id);
+			const parts = result.get(itemId) ?? [];
+			parts.push(this.evidenceDTO(row));
+			result.set(itemId, parts);
+		}
+		return result;
+	}
+	evidenceDTO(e) {
+		const filename2 = presentedFilename(object(e.data).filename);
+		return {
 			id: String(e.id),
 			partId: String(e.part_id),
 			parentEvidenceId: e.parent_evidence_id ? String(e.parent_evidence_id) : null,
 			mediaType: String(e.media_type),
 			contentHash: String(e.content_hash),
-			byteLength: Number(e.byte_length)
-		}));
+			byteLength: Number(e.byte_length),
+			...filename2 ? { filename: filename2 } : {}
+		};
 	}
 	async readEvidence(itemId, evidenceId) {
 		await this.item(itemId, "read");
@@ -1434,6 +1997,7 @@ var IngestionService = class {
 	async analyze(itemId, configuration, requestKey) {
 		const frozen = structuredClone(configuration);
 		if (Object.hasOwn(frozen, "humanCorrection") && frozen.stage !== "interpret") throw new Error("Human corrections require authenticated split revision");
+		if (Object.hasOwn(frozen, "reviewerInstruction") && frozen.stage !== "interpret") throw new Error("Reviewer instructions require authenticated instruction revision");
 		return this.tx((db) => this.appendAnalysis(db, itemId, frozen, requestKey));
 	}
 	async appendAnalysis(db, itemId, configuration, requestKey) {
@@ -1444,7 +2008,8 @@ var IngestionService = class {
 		if (!await this.matchesDispatchRoute(db, item)) throw new Error("Intake dispatch route unavailable");
 		await this.bindDispatchRoute(db, item);
 		if (item.receipt_state !== "ready" || item.cancelled) throw new Error("Intake not processable");
-		const replay = (await this.rows(db, "intake_analyses", "item_id=?", [itemId])).find((a) => object(a.data).requestKey === requestKey);
+		const previous = await this.rows(db, "intake_analyses", "item_id=?", [itemId]);
+		const replay = previous.find((a) => object(a.data).requestKey === requestKey);
 		if (replay) {
 			if (object(replay.data).configDigest !== configDigest) throw new Error("Analysis request conflict");
 			return {
@@ -1452,6 +2017,9 @@ var IngestionService = class {
 				revision: Number(replay.revision)
 			};
 		}
+		if (configuration.stage === "interpret") {
+			if (Number(object(object(configuration.proposals).source).revision) !== previous.filter((row) => object(object(row.data).configuration).stage !== "interpret").reduce((max, row) => Math.max(max, Number(row.revision)), Number.NEGATIVE_INFINITY)) throw new GenerationSourceStaleError();
+		}
 		const evidence = await this.rows(db, "intake_evidence", "item_id=? AND state='durable'", [itemId]);
 		await db.query("UPDATE intake_analysis_attempts SET state='superseded' WHERE tenant_id=? AND confidential_scope_id=? AND item_id=? AND state IN ('queued','running')", this.scope.tenantId, this.scope.confidentialScopeId, itemId);
 		await db.query("UPDATE intake_analyses SET state='superseded' WHERE tenant_id=? AND confidential_scope_id=? AND item_id=? AND state IN ('queued','running')", this.scope.tenantId, this.scope.confidentialScopeId, itemId);
@@ -1523,9 +2091,22 @@ var IngestionService = class {
 			await (await this.proposalReader())[generationSnapshotRead](frozen.itemId, (work) => this.tx(work), (db) => this.completedAnalysisSnapshot(db, frozen.itemId, frozen.attemptId, false), void 0, true);
 			return replay;
 		}
+		await this.point("split:checked");
 		let result;
-		await (await this.proposalReader())[generationSnapshotRead](frozen.itemId, (work) => this.tx(work), (db) => this.completedAnalysisSnapshot(db, frozen.itemId, frozen.attemptId, true), async (db, current) => {
-			if (current.revision !== frozen.expectedRevision) throw new Error("Stale logical split");
+		await (await this.proposalReader())[generationSnapshotRead](frozen.itemId, (work) => this.tx(work), (db) => this.completedAnalysisSnapshot(db, frozen.itemId, frozen.attemptId, false), async (db, current) => {
+			await this.lock(db, frozen.itemId);
+			await this.point("split:locked");
+			const [found] = (await this.rows(db, "intake_analyses", "item_id=?", [frozen.itemId])).filter((row) => object(row.data).requestKey === requestKey);
+			if (found) {
+				if (digest(object(object(found.data).configuration).humanCorrection) !== digest(correction)) throw new Error("Split request conflict");
+				result = {
+					id: String(found.id),
+					revision: Number(found.revision)
+				};
+				return;
+			}
+			const item = await this.item(frozen.itemId, "process", db);
+			if (current.revision !== frozen.expectedRevision || Number(item.analysis_revision) !== frozen.expectedRevision) throw new Error("Stale logical split");
 			const pin = object(object(current.configuration.proposals).source);
 			const source = await this.completedAnalysisSnapshot(db, frozen.itemId, String(pin.attemptId), false);
 			for (const key of [
@@ -1550,6 +2131,7 @@ var IngestionService = class {
 				}
 			}
 			if (!observed.size || pages.length !== observed.size || pages.some((page) => !observed.has(page))) throw new Error("Split must cover observed pages exactly");
+			await this.point("split:guarded");
 			result = await this.appendAnalysis(db, frozen.itemId, {
 				...source.configuration,
 				humanCorrection: correction
@@ -1558,6 +2140,210 @@ var IngestionService = class {
 		if (!result) throw new Error("Split unavailable");
 		return result;
 	}
+	/**
+	* Record an authenticated reviewer instruction as an immutable human correction
+	* and queue a fresh extraction plus interpretation that carries it as trusted
+	* guidance. The text steers the model only; it never changes the catalog,
+	* candidates, schemas, permissions or automation eligibility.
+	*/
+	async recordReviewerInstruction(input) {
+		const frozen = structuredClone(input);
+		nonempty(frozen.requestId);
+		nonempty(frozen.attemptId);
+		integer(frozen.expectedRevision);
+		if (typeof frozen.text !== "string" || !frozen.text.trim() || frozen.text.length > 4e3) throw new ReviewerInstructionInvalidError();
+		const requestKey = `instruction:${frozen.requestId}`;
+		const intent = {
+			kind: "reviewer_instruction",
+			itemId: frozen.itemId,
+			attemptId: frozen.attemptId,
+			expectedRevision: frozen.expectedRevision,
+			requestId: frozen.requestId,
+			actorId: this.scope.actorId,
+			text: frozen.text
+		};
+		const replayIntent = (record) => {
+			const { id: _id, recordedAt: _recordedAt, supersedesId: _supersedesId, digest: _digest, ...rest } = record;
+			return rest;
+		};
+		const replay = await this.tx(async (db) => {
+			await this.lock(db, frozen.itemId);
+			await this.item(frozen.itemId, "process", db);
+			const found = (await this.rows(db, "intake_analyses", "item_id=?", [frozen.itemId])).find((row) => object(row.data).requestKey === requestKey);
+			if (!found) return null;
+			const record = object(object(object(found.data).configuration).reviewerInstruction);
+			if (digest(replayIntent(record)) !== digest(intent)) throw new Error("Reviewer instruction request conflict");
+			return {
+				id: String(found.id),
+				revision: Number(found.revision),
+				instruction: reviewerInstructionView(record)
+			};
+		});
+		if (replay) {
+			await (await this.proposalReader())[generationSnapshotRead](frozen.itemId, (work) => this.tx(work), (db) => this.completedAnalysisSnapshot(db, frozen.itemId, frozen.attemptId, false), void 0, true);
+			return replay;
+		}
+		await this.point("instruction:checked");
+		let result;
+		await (await this.proposalReader())[generationSnapshotRead](frozen.itemId, (work) => this.tx(work), (db) => this.completedAnalysisSnapshot(db, frozen.itemId, frozen.attemptId, false), async (db, current) => {
+			await this.lock(db, frozen.itemId);
+			await this.point("instruction:locked");
+			const [found] = (await this.rows(db, "intake_analyses", "item_id=?", [frozen.itemId])).filter((row) => object(row.data).requestKey === requestKey);
+			if (found) {
+				const record2 = object(object(object(found.data).configuration).reviewerInstruction);
+				if (digest(replayIntent(record2)) !== digest(intent)) throw new Error("Reviewer instruction request conflict");
+				result = {
+					id: String(found.id),
+					revision: Number(found.revision),
+					instruction: reviewerInstructionView(record2)
+				};
+				return;
+			}
+			const item = await this.item(frozen.itemId, "process", db);
+			if (Number(item.analysis_revision) !== frozen.expectedRevision) throw new ReviewerInstructionStaleError();
+			let carriedConfiguration;
+			if (current.revision !== frozen.expectedRevision) {
+				const later = await this.laterWork(db, item, current.revision);
+				if (later.phase === "in_flight" || later.phase === "superseded") throw new ReviewerInstructionStaleError();
+				carriedConfiguration = later.configuration;
+			}
+			const pin = object(object(current.configuration.proposals).source);
+			const source = await this.completedAnalysisSnapshot(db, frozen.itemId, String(pin.attemptId), false);
+			for (const key of [
+				"attemptId",
+				"revision",
+				"inputDigest",
+				"outputDigest",
+				"evidenceDigest"
+			]) if (pin[key] !== source[key]) throw new Error("Instruction source changed");
+			const [previous] = await this.recordedInstructions(db, frozen.itemId);
+			const body = {
+				...intent,
+				id: randomUUID(),
+				recordedAt: date(this.now()),
+				supersedesId: previous?.id ?? null
+			};
+			const record = {
+				...body,
+				digest: digest(body)
+			};
+			await this.point("instruction:guarded");
+			result = {
+				...await this.appendAnalysis(db, frozen.itemId, {
+					...carriedConfiguration ?? source.configuration,
+					reviewerInstruction: record
+				}, requestKey),
+				instruction: reviewerInstructionView(record)
+			};
+		}, true);
+		if (!result) throw new Error("Reviewer instruction unavailable");
+		return result;
+	}
+	/**
+	* How the revisions after an anchor generation relate to it. Shared by the
+	* retry guard and getReinterpretationState so they cannot disagree.
+	* A completed extraction with no interpretation appended is in flight until
+	* its attempt's completion plus the item's analysis lease duration
+	* (`limits.leaseMs`, the same lease claimAnalysis grants); after that it is
+	* treated as a reinterpretation that did not start.
+	*/
+	async laterWork(db, item, anchorRevision) {
+		const later = (await this.rows(db, "intake_analyses", "item_id=? AND revision>?", [String(item.id), anchorRevision])).sort((a, b) => Number(b.revision) - Number(a.revision));
+		const stage = (row) => object(object(row.data).configuration).stage;
+		const newestExtraction = later.find((row) => stage(row) !== "interpret");
+		const configuration = newestExtraction ? object(object(newestExtraction.data).configuration) : void 0;
+		const [latest] = later;
+		if (!latest) return {
+			phase: "none",
+			failure: null,
+			configuration
+		};
+		if (later.some((row) => ["completed", "partial"].includes(String(row.state)) && stage(row) === "interpret")) return {
+			phase: "superseded",
+			failure: null,
+			configuration
+		};
+		if (later.some((row) => ["queued", "running"].includes(String(row.state)))) return {
+			phase: "in_flight",
+			failure: null,
+			configuration
+		};
+		const [attempt] = latest.current_attempt_id ? await this.rows(db, "intake_analysis_attempts", "id=? AND item_id=?", [latest.current_attempt_id, String(item.id)]) : [];
+		if (["completed", "partial"].includes(String(latest.state))) {
+			const completedAt = attempt ? object(attempt.data).completedAt : void 0;
+			const leaseMs = Number(object(object(item.data).limits).leaseMs);
+			const started = typeof completedAt === "string" ? persistedDate(completedAt).getTime() : NaN;
+			const deadline = Number.isFinite(started) && Number.isFinite(leaseMs) ? started + leaseMs : Number.NEGATIVE_INFINITY;
+			return this.now().getTime() <= deadline ? {
+				phase: "in_flight",
+				failure: null,
+				configuration
+			} : {
+				phase: "failed",
+				failure: "not_started",
+				configuration
+			};
+		}
+		const safe = attempt?.safe_error ? String(attempt.safe_error) : "";
+		return {
+			phase: "failed",
+			failure: failures.has(safe) ? safe : null,
+			configuration
+		};
+	}
+	/** Pollable reinterpretation state: current revision, safe failure and the retry anchor. */
+	async getReinterpretationState(itemId) {
+		const item = await this.item(itemId, "read");
+		const analyses = (await this.rows(this.db, "intake_analyses", "item_id=?", [itemId])).sort((a, b) => Number(b.revision) - Number(a.revision));
+		const generation = analyses.find((row) => ["completed", "partial"].includes(String(row.state)) && row.current_attempt_id && object(object(row.data).configuration).stage === "interpret");
+		let failure = null;
+		let reinterpreting = false;
+		if (generation) {
+			const later = await this.laterWork(this.db, item, Number(generation.revision));
+			failure = later.failure;
+			reinterpreting = later.phase === "in_flight";
+		} else {
+			const latest = analyses[0];
+			reinterpreting = ["queued", "running"].includes(String(latest?.state));
+			if (latest && String(latest.state) === "needs_attention" && latest.current_attempt_id) {
+				const [attempt] = await this.rows(this.db, "intake_analysis_attempts", "id=? AND item_id=?", [latest.current_attempt_id, itemId]);
+				if (attempt?.safe_error && failures.has(String(attempt.safe_error))) failure = String(attempt.safe_error);
+			}
+		}
+		const newestExtraction = analyses.find((row) => object(object(row.data).configuration).stage !== "interpret");
+		const carried = newestExtraction ? object(object(newestExtraction.data).configuration).reviewerInstruction : void 0;
+		const instructionInEffect = carried ? reviewerInstructionView(carried).id : null;
+		await this.item(itemId, "read");
+		return {
+			revision: Number(item.analysis_revision),
+			processingState: String(item.processing_state),
+			failure,
+			reinterpreting,
+			instructionInEffect,
+			generationAttemptId: generation ? String(generation.current_attempt_id) : null
+		};
+	}
+	/** Immutable instruction history, newest first. History is never deleted. */
+	async listReviewerInstructions(itemId) {
+		await this.item(itemId, "read");
+		const history = await this.recordedInstructions(this.db, itemId);
+		await this.item(itemId, "read");
+		return history;
+	}
+	async recordedInstructions(db, itemId) {
+		const rows = await this.rows(db, "intake_analyses", "item_id=?", [itemId]);
+		const seen = /* @__PURE__ */ new Set();
+		const history = [];
+		for (const row of rows.sort((a, b) => Number(b.revision) - Number(a.revision))) {
+			const configuration = object(object(row.data).configuration);
+			if (configuration.stage === "interpret" || !configuration.reviewerInstruction) continue;
+			const instruction = reviewerInstructionView(configuration.reviewerInstruction);
+			if (seen.has(instruction.id)) continue;
+			seen.add(instruction.id);
+			history.push(instruction);
+		}
+		return history;
+	}
 	/** Allocate a fenced attempt; active leases cannot be stolen before expiry. */
 	async claimAnalysis(itemId, revision, workerId) {
 		integer(revision);
@@ -1697,7 +2483,7 @@ var IngestionService = class {
 			"outputDigest",
 			"evidenceDigest"
 		]) if (pin[key] !== source[key]) throw new Error("Generation source changed");
-		if (source.result.provider !== "smrt-ingestion-extraction" || source.configuration.stage === "interpret" || source.revision !== generation.revision - 1 || digest(configuration.humanCorrection ?? null) !== digest(source.configuration.humanCorrection ?? null) || digest(generation.evidence.map((entry) => ({
+		if (source.result.provider !== "smrt-ingestion-extraction" || source.configuration.stage === "interpret" || source.revision !== generation.revision - 1 || digest(configuration.humanCorrection ?? null) !== digest(source.configuration.humanCorrection ?? null) || digest(configuration.reviewerInstruction ?? null) !== digest(source.configuration.reviewerInstruction ?? null) || digest(generation.evidence.map((entry) => ({
 			id: entry.id,
 			hash: entry.contentHash
 		}))) !== source.evidenceDigest) throw new Error("Generation evidence changed");
@@ -2021,6 +2807,6 @@ var IngestionService = class {
 	}
 };
 //#endregion
-export { EmailSourceAdapter, GenerationSnapshotStaleError, IngestionService, WatchFolderSourceAdapter, createIntakeReviewHost, createSDKExtractionAdapter, createSourceDeliveryHandler, createVendorWebhookHandler, extractAnalysis, proposeDocumentSplits };
+export { EmailSourceAdapter, GenerationSnapshotStaleError, GenerationSourceStaleError, HandlerArgumentsInvalidError, ITEM_ID_FILTER_CEILING, ITEM_PAGE_CEILING, ITEM_SCAN_CEILING, IngestionService, IntakeScanLimitError, REVIEWER_INSTRUCTION_MAX_LENGTH, ReviewerInstructionInvalidError, ReviewerInstructionStaleError, WatchFolderSourceAdapter, createIntakeReviewHost, createSDKExtractionAdapter, createSourceDeliveryHandler, createVendorWebhookHandler, extractAnalysis, isIntakeId, proposeDocumentSplits, reviewerInstructionView };
 
 //# sourceMappingURL=server.js.map