@happyvertical/smrt-ingestion 0.57.29 → 0.57.30

package/dist/smrt-knowledge.json

@@ -3,21 +3,21 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-ingestion",
-  "packageVersion": "0.57.29",
+  "packageVersion": "0.57.30",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "cc3bdbaad6d9094f5bbb4a198c3d5777ec84add2d1ef0c826a21d779ac1623b5",
-    "packageJson": "09573009230522e77bd0ca8b9698f9caf45c536ac05bd1801a0524370f86313d",
+    "manifest": "bcd80ac78403da1c6b813093141db45da30d210f2c1e7a2ddf3ca32d449128ce",
+    "packageJson": "8f347e181d955037272d5b54808242498e5aa37097fb4fe69618223678c74917",
     "agents": "dea14442054ec1de798cba9be1fbdd955f44b0e4672639cbf3db8101d290c1fb",
     "moduleDoc:agents/execution.md": "3b223cb3c85312a29bb6157f22b153b4d643dca790b149f47c35396f981f2dc7",
-    "moduleDoc:README.md": "be4566cae048c1e451fd6fa9448345ce35d29531c83fafec508c6390ceb7cc2e",
+    "moduleDoc:README.md": "49384c00608705488c26fb8c515c70cd7ba17a62d0b4c41ace2a821206011edd",
     "moduleDoc:EXTRACTION.md": "b735a25a7be75f3a13f3f9e92b0c25834c1394835c16ccd73a076d5720c14243",
-    "moduleDoc:PROPOSALS.md": "91b1cbdb9284fc17aac0adc28462c626e16cd0b60dcb7cfb0ab933c0c0d2f38f",
+    "moduleDoc:PROPOSALS.md": "c0e8e98d0d29841ce579138d4aaffd164eed81627d31b252094056b1f0e4b9e7",
     "moduleDoc:FEEDBACK.md": "bf244222a1bc24843bdb7e94320dc3c0dfb7cb892001639d274786f4b667dacb",
-    "moduleDoc:REVIEW.md": "32ab9bb518ea2c82b2e6093294d86c5b82122b677c0552993b5f269c6d29cfe2",
+    "moduleDoc:REVIEW.md": "eb2714386988a15f762bdc726b1fb3aa85a08e97e9363317f39234ebceddedb0",
     "agentSurface:src/test-support/execution.ts": "cc72288b2605fc687b820da558fa862da1bab799cebe4ee88b32be9e902618b8",
-    "agentSurface:src/test-support/proposals.ts": "6cd79fb74ef3e4fb47bb8e86c8d720d162c78b04ee02023b3717a3096b97c27b"
+    "agentSurface:src/test-support/proposals.ts": "c52a97b2481c2aeb054c4fb68d4658cbc74f435a2cc5a026c7210b5972311451"
   },
   "exports": [
     ".",
@@ -1710,7 +1710,7 @@
     {
       "path": "README.md",
       "module": "README",
-      "content": "# @happyvertical/smrt-ingestion\n\nDurable receipt, evidence, analysis attempts and action-journal foundations for\n[ADR 0004](../../docs/adr/0004-application-aware-ingestion.md).\n\nThe root, `/models` and `/dto` entry points are browser-safe. Import\n`IngestionService` from `/server` in trusted host code. Generated REST, CLI and\nMCP access to the persistence models is disabled; hosts expose authorized DTO\nmethods through their authenticated application transport.\n\nBefore starting a service, deploy the package manifest through the public s-m-r-t\nmigration APIs or `smrt db:migrate`. `assertReady()` only checks existing tables.\nSQLite and PostgreSQL are supported; other engines fail construction. Index\nadditions ship the same way: `intake_items_received_idx` (newest-first inbox\npaging on `tenant_id, confidential_scope_id, created_at, id`) is declared on the model and reaches existing deployments through the\nnext manifest migration; there are no hand-written migration files in this\npackage, and `smrt doctor --db` / `db:status --parity` report the index until\nit is applied.\n\n`listItemsPage({ limit?, cursor?, state?, itemIds?, scanLimit? })` returns\n`{ items: [{ item, state, cursor }], scanned, nextCursor? }`: one authorized\ninbox page newest receipt first with each row's durable inbox state and\ncontinuation cursor, and the number of rows the call examined. `listItems()`\nremains as a deprecated array-returning method that walks the private page\nscan to the end. Without the optional `cursorKey` service option every cursor\nnames the last row the actor can read, and a page that finds no readable row\nwithin its scan limit fails with `IntakeScanLimitError`; with a server secret\nof at least 32 bytes, cursors are sealed and such a page resumes past what it\nskipped. `scanned` is for host\naccounting only. See [REVIEW.md](REVIEW.md) for the paging and authorization\ncontract.\n\nA host supplies a database, AssetRuntime, authenticated tenant/actor/confidential\nscope, a live authorization callback, a registered jobs target, and an idempotent\n`purgeDerived` callback for host-owned previews, retrieval indexes and caches.\nThe authorization callback receives the captured ceiling and the current\ntransaction executor; it must intersect current grants with that ceiling. Never\nconstruct the scope, retention policy or budgets from incoming document labels.\n\n`receive` accepts bounded original byte buffers, with stable source part IDs,\nparent relationships, optional upstream identity/version and an optional\noriginal `filename` (kept for labels on `IntakeEvidenceDTO.filename`, never\npart of receipt identity). The multipart upload source, email attachments and\nthe watched folder all supply it, as may a host `snapshotReference` part or a\nvendor webhook's verified parts. Every source delivers through one place that\nremoves control, format (bidi, zero-width, tag), line-separator and\ndefault-ignorable characters (Unicode properties, see\n`src/presented-filename.ts`) and drops a name that is then empty or over 512\ncharacters, so an odd name falls back to the default label instead of failing\nthe receipt (`receive` itself rejects such a name from a direct caller as\n`invalid`, and names are cleaned again when read back). Removing every format\nand default-ignorable character has display-only effects, since nothing uses\nthe name as identity: emoji ZWJ sequences and presentation selectors flatten,\nZWNJ/ZWJ are removed from Persian and Indic text (letters may join\ndifferently), and ideographic variation selectors are removed (a CJK variant\nshows its base glyph). Unicode normalization\n(NFC/NFKC) and confusable look-alike characters are out of scope: the name is\nstill untrusted text, so render it as text, never as markup or a path. The\nupstream `sourceReference` is stored but not exposed on the DTO: its ids are\nupstream locators, not display text, and they are never cleaned. For email\nthey are the provider's message locator (plus the attachment part id); for the\nwatched folder the id is the raw folder entry name, whose cleaned form is what\n`filename` exposes. Source adapters own\nstreaming and upstream snapshot retrieval. Receipt identity is tenant + source +\ndelivery key; changing bytes or authenticated scope conflicts. Content equality\nin a different conversation does not deduplicate an arrival. The returned item\nID and version are safe acknowledgment data, never a storage URL.\n\nStorage intents contain a stable asset ID and a public AssetStore-planned URI\nbefore byte I/O. Preservation verifies existing bytes instead of replacing them.\nA receipt becomes ready only after every part is durable and its dispatch intent\ncommits. A source retries the same receive call after failure or lost\nacknowledgment. Hosts schedule `repairDispatches` after restart and periodically;\nit repairs missing/failed queue submissions through SmrtJobCollection. The host\njob restores the captured scope and calls the analysis lifecycle methods. Run\nTaskRunner with the `ingestion` queue enabled.\n\n`analyze` appends immutable input/configuration revisions. `claimAnalysis` uses\nleases, monotonic fences and attempt budgets; `completeAnalysis` rejects expired\nor superseded workers. Terminal attempt output/provenance is preserved. Queue\nsubmission budgets also stop repeated handler failures in visible\n`needs_attention`. Reprocessing does not mint actions. `createAction`,\n`publishProposal` and `appendPlan` persist explicit intentions and exact attempt\nbindings for the later review/execution layer. They do not approve or apply\nbusiness operations. Decision/execution/feedback models are persistence\nfoundations; policy, handler expansion, review and business apply belong to the\nlater epic children.\n\n`expire` revokes access and pending work before removing bytes and calling\n`purgeDerived`. Interrupted deletion is retried by `repairDeletions` and\n`sweepRetention`. Minimal receipt/action identities remain, including successful\naction result digests; all content-bearing journal payloads are redacted. Private\ncleanup locators remain in deletion tombstones so repeated sweeps can remove a\nlate stale writer's orphan bytes even after the asset owner row is gone. Source\nadapters must enforce their configured delivery-age cutoff; expired replay IDs\nnever become fresh work. Continue running the cleanup sweep for the retained\nstorage namespace. Upstream source mutation/deletion cannot change copied\noriginals; explicit privacy deletion revokes every ingestion-derived payload and\nrequires host cache/index purge.\n\nSee [EXTRACTION.md](EXTRACTION.md) for bounded extraction, lease-bound input\nsnapshots, provider isolation requirements and the extraction corpus.\n\nValidation commands are `pnpm test`, `pnpm test:postgres`, `pnpm test:providers`, `pnpm typecheck` and\n`pnpm build` (including built browser import inspection). The PostgreSQL lane\nrequires the repository's configured database service and never silently skips.\nThe provider lane exercises local SDK adapters and process isolation; it does not\nclaim live remote recognition quality. `pnpm test:components` and `pnpm test:e2e`\ncover the maintained review surface. `pnpm test:evaluation` checks repository\nevaluation tooling contracts; measured held-out quality requires a separately\nfrozen protocol and an approved aggregate provider budget. See the [behavior matrix](../../docs/test-matrix/3670-ingestion-foundation.md).\n\n## Authoritative review and execution\n\nConfigure `IngestionOptions.execution` for policy, immutable previews, authenticated\ndecisions and idempotent domain execution. See [execution integration](agents/execution.md)\nfor the public handler catalog, required host authorization/target locks, deployment\nmigrations and jobs continuation integration. The maintained application reference\nin `reference/handlers.ts` creates draft ContentDocuments and attaches retained\nevidence through public domain APIs; it is not a published runtime adapter.\n\n## Configured source adapters\n\nThe server entry exports `createSourceDeliveryHandler`, `EmailSourceAdapter`,\n`WatchFolderSourceAdapter`, and `createVendorWebhookHandler`. Construct a\n`SourceBinding` from authenticated host configuration: enabled flag, scoped\n`IngestionService`, stable source ID/version, captured authority ceiling,\nretention policy, allowed media types and receipt limits. Re-resolve this binding\nwhen grants/configuration change. Source payloads never supply authority.\n\nThe reference POST handler authenticates before reading bytes and requires\n`Idempotency-Key`. JSON accepts exactly `capturedAt` and one of `text`,\n`structured`, or `reference: { owner: 'asset'|'message', id, version }`.\nThe host's `snapshotReference` must authorize current ownership and return copied\nbytes; an absent snapshot fails rather than acknowledging a mutable locator.\nMultipart accepts one `file` plus `captureId` (equal to the idempotency key),\n`capturedAt`, `captureSource` (`camera`, `native_picker`, `audio`, `document`), and optional\nlowercase SHA-256 `sha256`. This reuses mobile's durable UUID Idempotency-Key,\nMIME-bearing file part and explicit capture metadata convention. Captures retain\noriginal bytes and a parent metadata evidence record. Configure both the wire\nlimit `maxRequestBytes` and receipt `maxBytes`/`maxParts`; include\n`application/json` in the media allowlist for capture/email metadata. Signature\nchecks cover PDF, TIFF, PNG/JPEG/WebP and WAV/Ogg/WebM/MP3/MP4 audio; signature\nacceptance promises preservation, not extraction support or codec validity.\n\nEmail is explicitly opt-in per configured account. `EmailSourceAdapter` takes a\n`readMessage` callback compatible with the messages owner's\n`EmailAccount.readIntakeMessage(providerLookup, maxBytes, imapIdentity?)` snapshot.\nThe provider lookup is Gmail message ID, POP3 UIDL, or IMAP RFC Message-ID; it\nis separate from the delivery dedupe key. IMAP requires `{ folder, uidValidity,\nuid }`: the method selects the mailbox and verifies UIDVALIDITY and returned UID.\nAmbiguous sender IDs resolving to another UID fail explicitly. That method connects,\nfetches the full message including actual attachment bytes, copies the bytes,\nand disconnects. Metadata-only attachments fail explicitly. It never reads an\nattachment path supplied by a provider. A host lists provider deliveries using a\nstable account-specific locator (for IMAP include folder, UIDVALIDITY and UID),\nan explicit revision, and an opaque resumable checkpoint. Same locator/revision\nwith changed bytes conflicts; an explicit new revision creates a new receipt.\nDo not use sender-controlled RFC Message-ID as the sole transport identity.\n`receiveBatch` processes in order and stops at the first failure. The host owns\ndurable checkpoint storage and commits its `acknowledge` callback only after the\nadapter has received accepted/duplicate. If checkpoint persistence fails, retry\nreturns the original receipt. Message/thread/attachment relationships are copied;\ncredentials and arbitrary headers are excluded. The ordinary `syncFrom` metadata\nsync remains separate; `hasAttachments` is never proof of byte preservation.\n\nWatch-folder intake polls only an explicitly configured existing private local\ndirectory. Producers should close their files, preferably publishing with atomic\nrename. Two unchanged size/inode/mtime/ctime observations separated by\n`stabilityMs` are required, and the interval runs again after claim/restart.\nA private `.ingestion-claims/<UUID>/claim.json` intent is synced before atomically\nrenaming the original into that directory. Keep the directory on one filesystem,\nunder the host's ownership; symlink inputs are refused. A file descriptor still\nheld by an uncooperative producer can write after any stability window, so the\nproducer close/publish protocol is required for immutable input. Accepted or\nduplicate receipts move the entire claim to `.ingestion-processed`; do not delete\nclaims to retry. Polling recovers persisted UUIDs after process death, so receipt\nreplay deduplicates ready-without-ack. `failure.json` and poll results expose safe\ncategories while originals remain available. Intent directories without an\noriginal mean death before claim or a competing poll won; the producer original\nhas not been removed. Operators may remove these empty intents after confirming\nno active importer. Keep processed originals according to the host's retention\npolicy. This adapter does not watch arbitrary paths or start background loops.\n\nVendor webhooks use a host `verify(request, originalBytes)` callback after bounded\nraw-body reading. The callback must verify signature, delivery time/replay window\nand account ownership, then return trusted binding and durable delivery identity.\nNo vendor implementation or hardware driver is selected. All adapters invoke\nonly receipt preservation, never domain writes, AI tools or external actions.\n\nSee [PROPOSALS.md](PROPOSALS.md) for bounded application catalog discovery, durable\ninterpretation revisions, optional typed decisions and explicit generated preview.\n\n## Human review\n\nMount the `/svelte` inbox and review components through an authenticated host using\nthe browser-safe `IntakeReviewHost` DTO contract. See [REVIEW.md](REVIEW.md) for\nexact revision-bound callbacks, live evidence access, logical split corrections,\nassignment ownership, and the maintained upload-to-domain-result browser fixture.\n`IntakeWorkspace` puts the inbox, the selected item with its original inline,\nthe message box and approve-and-advance on one page with keyboard next/previous;\nit uses the same callbacks and adds no authority (REVIEW.md, \"Single-page triage\nworkspace\").\n\nOptional explicit feedback and scoped example retrieval are documented in\n[FEEDBACK.md](FEEDBACK.md). Approval and execution outcomes remain separate from\ninterpretation correctness; routing policy adoption is explicit and versioned.\n\nReviewers can start any offered handler for an item (`startReviewerAction`) or\nclose it as handled without action (`resolveItem`); the published host adapter\nwires both as `startAction`/`resolve` and exposes the offered `catalog`. Hosts\nwith their own transport add the two POST operations behind the same session,\nCSRF and reviewer checks as `decide`, and map a thrown\n`HandlerArgumentsInvalidError` (name and value-free `issues`) from `startAction`\nexactly as they do for `preview` so the form stays inline (see\n[REVIEW.md](REVIEW.md)). The `intake_dispositions` table requires\na manifest migration before upgrading.\n\n## Recipe preview\n\n`ingestion.inbox` and `ingestion.review` declare the user-facing inbox and\nreview workflows for app discovery. The reference workflow and measured\nevaluation are now published, but the evaluation did not meet supported-reference\nquality gates and did not establish safety. Automation remains disabled. The\nrecipes do not configure a source or provider, expose generic CRUD routes, or\nenable automatic execution. Mount `IntakeInbox` and `IntakeReview` with an\nauthenticated `IntakeReviewHost`; [REVIEW.md](REVIEW.md) remains the source of\ntruth for its scoped callbacks and freshness checks. See the [adoption\nchecklist](../../docs/evaluation/3677-adoption.md) and [measured\nreport](../../docs/evaluation/3677-measured-evaluation.md) for the release\nlimits.\n\nThe recipe manifest registers those existing browser components as\n`/ingestion/inbox` and `/ingestion/review` routes for a host to mount. The route\nmetadata does not supply a host, source, provider, or demo fixture, and it does\nnot change the preview-only status. Neither recipe declares generic model\nnavigation: the ingestion records have no generated screens, so hosts use the\nauthenticated route surfaces instead. Both recipes declare `both` runtime: their\ncomponents render in a browser, while the authenticated review host and package\ndependency closure require a server.\n\n## First analysis and host constraints\n\n`receive` retains evidence and queues the initial dispatch, but does not choose\nan extraction configuration. Before a worker can analyze a new item, the host must\ncall `analyze(itemId, { stage: 'extract', extraction: { configurationRevision,\nlimits } }, requestId)`, then claim that returned revision and run `extractAnalysis`.\nUse a stable request ID for retries. `repairDispatches` repairs queue delivery;\nit does not supply the missing extraction request. After extraction, use\n`prepareGeneration` and `analyze` to request interpretation.\n\nRetention requires `replayUntil >= expiresAt`; an earlier replay deadline rejects\neven a fresh delivery as `expired`. The replay tombstone must outlive retained\nsource bytes. Set both deadlines explicitly before calling `receive`.\n\nHandler preview `normalizedArgs` must equal the submitted arguments exactly.\nIt is an integrity assertion, not a normalization hook: defaults or tidying must\nhappen before submitting args for preview, so review binds exactly what was sent.\n\nProposal limits must be positive safe integers. `maxHandlers`, `maxCandidates`\nand `maxSuggestions` are each capped at 20; `timeoutMs` is capped at 2147483647.\nInvalid limits are rejected when constructing `IngestionService`, before receipt\nor interpretation. See [REVIEW.md](REVIEW.md) for the published server review host.\n\n## Trusted internal sources\n\nA host with a trusted internal source, such as chat messages recorded in\nsmrt-messages, can receive **by reference**, interpret **inline**, and let the\n**submitter** confirm their own proposal (#4085). None of these modes changes\ncopied receipts: their identity, validation, queueing and retention are\nuntouched, and a replay that switches mode conflicts.\n\n**Receive by reference.** A part may be `{ partId, reference: { owner, id,\nversion? }, snapshot: { text } | { structured } }` instead of bytes. The\nservice derives UTF-8 bytes once (`text/plain` or canonical `application/json`;\ntext, reference fields and owner identity containing NUL or unpaired\nsurrogates are rejected `invalid` on every engine, and `expireOwned` refuses\nthem, so distinct owners can never collapse onto one stored key),\nhashes them into the receipt identity, and stores only that snapshot in the\ndurable evidence row; no AssetStore object or asset record is created, and\n`readEvidence` serves the snapshot after the same hash/length check. The\nreference is identity and provenance, never authority. Such parts must be\ntext or structured; files still arrive as copied bytes.\n\n**Owner-bound retention.** `retention: { kind: 'owner', owner: { kind, id },\nversion, expiresAt, replayUntil, acceptAfter }` binds the receipt to its\nowner's lifecycle. The time deadlines remain required and validated exactly as\nbefore: they are the hard privacy ceiling, and `sweepRetention` and execution's\npolicy ceiling still apply. When the owner is deleted the host calls\n`expireOwned({ kind, id })` from its deletion path; every active receipt bound\nto that owner is revoked and removed through the existing `expire` /\n`repairDeletions` protocol, which redacts the snapshot together with every\nother payload, and the deleted delivery is never re-admitted. The owner key is\nrecorded in the indexed `owner_key` column (`<kind>:<id>`, so `kind` cannot\ncontain `:`). Deletion redaction blanks `owner_key` and `submitter_id` together\nwith every payload: only the receipt identity (`delivery_key`) and the captured\nceiling survive, and the ceiling loses `execution.principalId` unless an\nexternal action is still `executing` or `outcome_unknown`. So once nothing is\nleft to reconcile, a redacted row no longer links an owner to an actor, and a\nrepeated `expireOwned` finds nothing. Redaction also overwrites every\nidentity- or content-derived digest (`payload_digest`, `scope_digest`, analysis\n`input_digest`, attempt `output_digest`, plan `digest` and proposal, decision\nand execution `binding_hash`) with the fixed marker `redacted`; successful\nresult digests remain as the replay tombstone. The principal is retained only\nfor an external action that was still in flight when the item was redacted,\nbecause reconciling it authorizes under that principal; it is dropped when that\nreconciliation reaches a final state, or by the next `repairDeletions` /\n`sweepRetention` pass. For a self-approvable receipt the principal is the\nsubmitter, so until then it identifies the sender. Later deletion sweeps pass\nthis redacted ceiling to the host's `authorize({ operation: 'delete' })`, so\ndelete authorization must not depend on `execution.principalId`: a host that\nrequires it would refuse, and the sweep would stop with later deletion intents\nstill pending. A successful result digest\nis a plain SHA-256 of the canonical result, so it can confirm a guessed result:\nkeep handler results to record ids or opaque references, never content.\n\nA replay of a deleted delivery is rejected and never becomes fresh work. While\ndeletion is still pending it returns `rejected/expired`; once redaction has\ncompleted the identity digests are gone, so it returns `rejected/conflict`.\nSources treat both as terminal and must not retry. `delivery_key` stays in plaintext because it is\nthe unique receipt identity and the package holds no secret to key it: hosts\nmust use an opaque value (for example a random UUID recorded with the message)\nand must not encode owner ids, sender ids or content in `deliveryKey`.\n\nHost ordering for owner deletion: first stop issuing receipts for the owner,\nthen call `expireOwned`, and call it again once in-flight receipts settle (or\nfrom a periodic sweep). A receipt still in flight when its owner is expired\nreturns `{ kind: 'rejected', category: 'expired' }` rather than `accepted`, but\none that reserved its row after the first `expireOwned` is only found by the\nlater call; until then the time ceiling bounds it. Services are confidential-scope bound, so\na host whose owner has receipts in several confidential scopes calls\n`expireOwned` from each scope's service; a foreign tenant or scope sees zero.\n\n**Inline mode.** `receive({ ..., dispatch: 'inline' })` requires text/structured\nparts only, records the route provenance but **no deliverable dispatch intent**\nfor any revision (every intent is retained as `completed`, so no worker or\n`repairDispatches` ever picks it up), and does not enqueue. The host then calls\n`interpretInline(itemId, { requestId, extraction: { configurationRevision,\nlimits } })`, which runs in-process exactly what the job path runs: an\nimmutable `stage: 'extract'` revision claimed under a fenced lease and\nextracted with the built-in UTF-8 extractor, then `prepareGeneration` and the\n`stage: 'interpret'` revision with the same analysis lease, catalog-live\nchecks, provenance and failure categories as `generateProposals`. A retry with\nthe same `requestId` replays the immutable revisions, including when two\nidentical calls race. The interpretation is appended under the item lock only\nwhile its pinned extraction is still the latest revision; if another request\nreprocessed the item meanwhile it fails with `GenerationSourceStaleError` (the\ngeneral latest-extraction check every interpretation append runs, #4228) or,\nfor a pin whose extraction attempt was replaced, `Generation source changed`. The result reports each\nstage's attempt and safe error and, when generation completed, the authorized\n`getCompletedAnalysis` snapshot. Inline is for send-triggered suggestions that\nmust not depend on the scheduler; it is not a bypass of review or execution.\n\n**Submitter-scoped approval.** The service records `submitter_id` as the\nauthenticated `scope.actorId` of the receiving service, server-side; payload\nand source metadata never supply it. `listOwnProposals({ cursor?, limit? })`\nlists only this actor's own active submissions with their saved review pages,\nreloaded under current item/handler/target authority, without the reviewer\ninbox. A submission the actor can no longer read is skipped before projection\nand never named by the cursor; a readable one whose reviews are denied by\ningestion authority is returned as `{ item, reviews: null, unavailable: true }`\nwith no reason, so one revoked grant never hides the others. `submitOwnDecision(input)` accepts `approve`, `reject` or `defer` (never\n`correct`) under the `review_own` authority: the host's execution `authorize`\nmust return `submitter: true` for that actor, the application policy must opt\nin with `submitterReview: true` (narrower layers may only disable it), and the\nitem's recorded submitter must equal the current actor. Every other check is\nthe ordinary one, and `applyAction` remains the single once-only effect path\nunder the approver's live grants. Because the effect runs as the receipt's\ncaptured `capturedCeiling.execution.principalId`, `review_own` additionally\nrequires that principal to be the submitter itself (`submitter_id ===\nscope.actorId === principalId`), checked under the item lock at decision time\nand again at apply; a receipt captured for a bot or service principal can only\nbe approved by a reviewer. The decision is recorded with `mode` (`review` or\n`review_own`) and `selfDecision`, which is true whenever the deciding actor is\nthe item's submitter, in either mode (mirrored as `decisionMode` /\n`selfDecision` on feedback events), so a self-confirmation is never mistaken\nfor independent review and never contributes to automation eligibility. See\n[REVIEW.md](REVIEW.md) and [execution integration](agents/execution.md).\n\n## Dispatch route ownership and legacy recovery\n\nA receipt retains a versioned, server-owned `jobTarget` snapshot, and every\nanalysis dispatch retains the same route. Receipt replay and later analysis\ncannot retarget it. `repairDispatches()` filters by retained route before the\ncalling host's authorization or delivery budget, then rechecks provenance under\nthe item lock. A failed job for another host sharing the same tenant and\nconfidential scope neither runs on this host nor blocks its unrelated receipt.\nMatching routes still require current access within the captured permission\nceiling; their authorization and queue failures remain visible. Job arguments\ncontinue to contain identifiers only.\n\nLegacy receipts lacking route metadata can use existing recorded job authority\nonly when all available provenance agrees. A linked job must match the tenant,\ningestion queue, item, dispatch ID and revision exactly. This preserves recorded\njob authority, not a reconstruction of the host's historical intention. Conflicting\nor malformed provenance fails closed. Deleted jobs are absent provenance: an\nexisting protected route survives deletion, but without one the route remains\nunknown and automatic repair skips it.\n\n`inspectDispatchRoute(itemId)` requires normal read authority and returns a\nstatus, fingerprint and verified target (or null). For genuinely provenance-free\nlegacy receipts a host may opt into `dispatchRecovery.authorize`. Without this\nseparate operator authorization callback recovery is disabled. Quiesce legacy\nworkers and investigate their recorded job history before authorizing recovery;\nmissing history is not proof of a particular intended handler. Call\n`recoverDispatchRoute({ itemId, expectedFingerprint, evidenceRef })` with the\ninspection fingerprint and a nonblank evidence reference of at most 512\ncharacters. The target comes exclusively from that service's trusted,\nconstructor-snapshotted configuration, never from the request.\n\nRecovery acquires the item lock, rechecks current/captured process permissions\nand the separate host operator permission, and verifies the exact fingerprint.\nIt refuses bound, conflicting or stale authority. It appends retained operator,\ndate, evidence and original fingerprint provenance and binds missing dispatch\nmetadata atomically; it does not enqueue, alter original receipt/analysis/action\nfacts, or replace prior provenance. The exact original fingerprint/evidence retry\nreturns the retained binding, including under concurrent delivery, but still\nrechecks both permissions. A different decision conflicts. Once reviewed,\nnormal matching-host `repairDispatches()` may enqueue work separately. Hosts\nwithout legacy tenants need not configure recovery at all.\n"
+      "content": "# @happyvertical/smrt-ingestion\n\nDurable receipt, evidence, analysis attempts and action-journal foundations for\n[ADR 0004](../../docs/adr/0004-application-aware-ingestion.md).\n\nThe root, `/models` and `/dto` entry points are browser-safe. Import\n`IngestionService` from `/server` in trusted host code. Generated REST, CLI and\nMCP access to the persistence models is disabled; hosts expose authorized DTO\nmethods through their authenticated application transport.\n\nBefore starting a service, deploy the package manifest through the public s-m-r-t\nmigration APIs or `smrt db:migrate`. `assertReady()` only checks existing tables.\nSQLite and PostgreSQL are supported; other engines fail construction. Index\nadditions ship the same way: `intake_items_received_idx` (newest-first inbox\npaging on `tenant_id, confidential_scope_id, created_at, id`) is declared on the model and reaches existing deployments through the\nnext manifest migration; there are no hand-written migration files in this\npackage, and `smrt doctor --db` / `db:status --parity` report the index until\nit is applied.\n\n`listItemsPage({ limit?, cursor?, state?, itemIds?, scanLimit? })` returns\n`{ items: [{ item, state, cursor }], scanned, nextCursor? }`: one authorized\ninbox page newest receipt first with each row's durable inbox state and\ncontinuation cursor, and the number of rows the call examined. `listItems()`\nremains as a deprecated array-returning method that walks the private page\nscan to the end. Without the optional `cursorKey` service option every cursor\nnames the last row the actor can read, and a page that finds no readable row\nwithin its scan limit fails with `IntakeScanLimitError`; with a server secret\nof at least 32 bytes, cursors are sealed and such a page resumes past what it\nskipped. `scanned` is for host\naccounting only. See [REVIEW.md](REVIEW.md) for the paging and authorization\ncontract.\n\nA host supplies a database, AssetRuntime, authenticated tenant/actor/confidential\nscope, a live authorization callback, a registered jobs target, and an idempotent\n`purgeDerived` callback for host-owned previews, retrieval indexes and caches.\nThe authorization callback receives the captured ceiling and the current\ntransaction executor; it must intersect current grants with that ceiling. Never\nconstruct the scope, retention policy or budgets from incoming document labels.\n\n`receive` accepts bounded original byte buffers, with stable source part IDs,\nparent relationships, optional upstream identity/version and an optional\noriginal `filename` (kept for labels on `IntakeEvidenceDTO.filename`, never\npart of receipt identity). The multipart upload source, email attachments and\nthe watched folder all supply it, as may a host `snapshotReference` part or a\nvendor webhook's verified parts. Every source delivers through one place that\nremoves control, format (bidi, zero-width, tag), line-separator and\ndefault-ignorable characters (Unicode properties, see\n`src/presented-filename.ts`) and drops a name that is then empty or over 512\ncharacters, so an odd name falls back to the default label instead of failing\nthe receipt (`receive` itself rejects such a name from a direct caller as\n`invalid`, and names are cleaned again when read back). Removing every format\nand default-ignorable character has display-only effects, since nothing uses\nthe name as identity: emoji ZWJ sequences and presentation selectors flatten,\nZWNJ/ZWJ are removed from Persian and Indic text (letters may join\ndifferently), and ideographic variation selectors are removed (a CJK variant\nshows its base glyph). Unicode normalization\n(NFC/NFKC) and confusable look-alike characters are out of scope: the name is\nstill untrusted text, so render it as text, never as markup or a path. The\nupstream `sourceReference` is stored but not exposed on the DTO: its ids are\nupstream locators, not display text, and they are never cleaned. For email\nthey are the provider's message locator (plus the attachment part id); for the\nwatched folder the id is the raw folder entry name, whose cleaned form is what\n`filename` exposes. Source adapters own\nstreaming and upstream snapshot retrieval. Receipt identity is tenant + source +\ndelivery key; changing bytes or authenticated scope conflicts. Content equality\nin a different conversation does not deduplicate an arrival. The returned item\nID and version are safe acknowledgment data, never a storage URL.\n\nStorage intents contain a stable asset ID and a public AssetStore-planned URI\nbefore byte I/O. Preservation verifies existing bytes instead of replacing them.\nA receipt becomes ready only after every part is durable and its dispatch intent\ncommits. A source retries the same receive call after failure or lost\nacknowledgment. Hosts schedule `repairDispatches` after restart and periodically;\nit repairs missing/failed queue submissions through SmrtJobCollection. The host\njob restores the captured scope and calls the analysis lifecycle methods. Run\nTaskRunner with the `ingestion` queue enabled.\n\n`analyze` appends immutable input/configuration revisions. `claimAnalysis` uses\nleases, monotonic fences and attempt budgets; `completeAnalysis` rejects expired\nor superseded workers. Terminal attempt output/provenance is preserved. Queue\nsubmission budgets also stop repeated handler failures in visible\n`needs_attention`. Reprocessing does not mint actions. `createAction`,\n`publishProposal` and `appendPlan` persist explicit intentions and exact attempt\nbindings for the later review/execution layer. They do not approve or apply\nbusiness operations. Decision/execution/feedback models are persistence\nfoundations; policy, handler expansion, review and business apply belong to the\nlater epic children.\n\n`expire` revokes access and pending work before removing bytes and calling\n`purgeDerived`. Interrupted deletion is retried by `repairDeletions` and\n`sweepRetention`. Minimal receipt/action identities remain, including successful\naction result digests; all content-bearing journal payloads are redacted. Private\ncleanup locators remain in deletion tombstones so repeated sweeps can remove a\nlate stale writer's orphan bytes even after the asset owner row is gone. Source\nadapters must enforce their configured delivery-age cutoff; expired replay IDs\nnever become fresh work. Continue running the cleanup sweep for the retained\nstorage namespace. Upstream source mutation/deletion cannot change copied\noriginals; explicit privacy deletion revokes every ingestion-derived payload and\nrequires host cache/index purge.\n\nSee [EXTRACTION.md](EXTRACTION.md) for bounded extraction, lease-bound input\nsnapshots, provider isolation requirements and the extraction corpus.\n\nValidation commands are `pnpm test`, `pnpm test:postgres`, `pnpm test:providers`, `pnpm typecheck` and\n`pnpm build` (including built browser import inspection). The PostgreSQL lane\nrequires the repository's configured database service and never silently skips.\nThe provider lane exercises local SDK adapters and process isolation; it does not\nclaim live remote recognition quality. `pnpm test:components` and `pnpm test:e2e`\ncover the maintained review surface. `pnpm test:evaluation` checks repository\nevaluation tooling contracts; measured held-out quality requires a separately\nfrozen protocol and an approved aggregate provider budget. See the [behavior matrix](../../docs/test-matrix/3670-ingestion-foundation.md).\n\n## Authoritative review and execution\n\nConfigure `IngestionOptions.execution` for policy, immutable previews, authenticated\ndecisions and idempotent domain execution. See [execution integration](agents/execution.md)\nfor the public handler catalog, required host authorization/target locks, deployment\nmigrations and jobs continuation integration. The maintained application reference\nin `reference/handlers.ts` creates draft ContentDocuments and attaches retained\nevidence through public domain APIs; it is not a published runtime adapter.\n\n## Configured source adapters\n\nThe server entry exports `createSourceDeliveryHandler`, `EmailSourceAdapter`,\n`WatchFolderSourceAdapter`, and `createVendorWebhookHandler`. Construct a\n`SourceBinding` from authenticated host configuration: enabled flag, scoped\n`IngestionService`, stable source ID/version, captured authority ceiling,\nretention policy, allowed media types and receipt limits. Re-resolve this binding\nwhen grants/configuration change. Source payloads never supply authority.\n\nThe reference POST handler authenticates before reading bytes and requires\n`Idempotency-Key`. JSON accepts exactly `capturedAt` and one of `text`,\n`structured`, or `reference: { owner: 'asset'|'message', id, version }`.\nThe host's `snapshotReference` must authorize current ownership and return copied\nbytes; an absent snapshot fails rather than acknowledging a mutable locator.\nMultipart accepts one `file` plus `captureId` (equal to the idempotency key),\n`capturedAt`, `captureSource` (`camera`, `native_picker`, `audio`, `document`), and optional\nlowercase SHA-256 `sha256`. This reuses mobile's durable UUID Idempotency-Key,\nMIME-bearing file part and explicit capture metadata convention. Captures retain\noriginal bytes and a parent metadata evidence record. Configure both the wire\nlimit `maxRequestBytes` and receipt `maxBytes`/`maxParts`; include\n`application/json` in the media allowlist for capture/email metadata. Signature\nchecks cover PDF, TIFF, PNG/JPEG/WebP and WAV/Ogg/WebM/MP3/MP4 audio; signature\nacceptance promises preservation, not extraction support or codec validity.\n\nEmail is explicitly opt-in per configured account. `EmailSourceAdapter` takes a\n`readMessage` callback compatible with the messages owner's\n`EmailAccount.readIntakeMessage(providerLookup, maxBytes, imapIdentity?)` snapshot.\nThe provider lookup is Gmail message ID, POP3 UIDL, or IMAP RFC Message-ID; it\nis separate from the delivery dedupe key. IMAP requires `{ folder, uidValidity,\nuid }`: the method selects the mailbox and verifies UIDVALIDITY and returned UID.\nAmbiguous sender IDs resolving to another UID fail explicitly. That method connects,\nfetches the full message including actual attachment bytes, copies the bytes,\nand disconnects. Metadata-only attachments fail explicitly. It never reads an\nattachment path supplied by a provider. A host lists provider deliveries using a\nstable account-specific locator (for IMAP include folder, UIDVALIDITY and UID),\nan explicit revision, and an opaque resumable checkpoint. Same locator/revision\nwith changed bytes conflicts; an explicit new revision creates a new receipt.\nDo not use sender-controlled RFC Message-ID as the sole transport identity.\n`receiveBatch` processes in order and stops at the first failure. The host owns\ndurable checkpoint storage and commits its `acknowledge` callback only after the\nadapter has received accepted/duplicate. If checkpoint persistence fails, retry\nreturns the original receipt. Message/thread/attachment relationships are copied;\ncredentials and arbitrary headers are excluded. The ordinary `syncFrom` metadata\nsync remains separate; `hasAttachments` is never proof of byte preservation.\n\nWatch-folder intake polls only an explicitly configured existing private local\ndirectory. Producers should close their files, preferably publishing with atomic\nrename. Two unchanged size/inode/mtime/ctime observations separated by\n`stabilityMs` are required, and the interval runs again after claim/restart.\nA private `.ingestion-claims/<UUID>/claim.json` intent is synced before atomically\nrenaming the original into that directory. Keep the directory on one filesystem,\nunder the host's ownership; symlink inputs are refused. A file descriptor still\nheld by an uncooperative producer can write after any stability window, so the\nproducer close/publish protocol is required for immutable input. Accepted or\nduplicate receipts move the entire claim to `.ingestion-processed`; do not delete\nclaims to retry. Polling recovers persisted UUIDs after process death, so receipt\nreplay deduplicates ready-without-ack. `failure.json` and poll results expose safe\ncategories while originals remain available. Intent directories without an\noriginal mean death before claim or a competing poll won; the producer original\nhas not been removed. Operators may remove these empty intents after confirming\nno active importer. Keep processed originals according to the host's retention\npolicy. This adapter does not watch arbitrary paths or start background loops.\n\nVendor webhooks use a host `verify(request, originalBytes)` callback after bounded\nraw-body reading. The callback must verify signature, delivery time/replay window\nand account ownership, then return trusted binding and durable delivery identity.\nNo vendor implementation or hardware driver is selected. All adapters invoke\nonly receipt preservation, never domain writes, AI tools or external actions.\n\nSee [PROPOSALS.md](PROPOSALS.md) for bounded application catalog discovery, durable\ninterpretation revisions, optional typed decisions and explicit generated preview.\n\n## Human review\n\nMount the `/svelte` inbox and review components through an authenticated host using\nthe browser-safe `IntakeReviewHost` DTO contract. See [REVIEW.md](REVIEW.md) for\nexact revision-bound callbacks, live evidence access, logical split corrections,\nassignment ownership, and the maintained upload-to-domain-result browser fixture.\n`IntakeWorkspace` puts the inbox, the selected item with its original inline,\nthe message box and approve-and-advance on one page with keyboard next/previous;\nit uses the same callbacks and adds no authority (REVIEW.md, \"Single-page triage\nworkspace\").\n\nOptional explicit feedback and scoped example retrieval are documented in\n[FEEDBACK.md](FEEDBACK.md). Approval and execution outcomes remain separate from\ninterpretation correctness; routing policy adoption is explicit and versioned.\n\nReviewers can start any offered handler for an item (`startReviewerAction`) or\nclose it as handled without action (`resolveItem`); the published host adapter\nwires both as `startAction`/`resolve` and exposes the offered `catalog`. Hosts\nwith their own transport add the two POST operations behind the same session,\nCSRF and reviewer checks as `decide`, and map a thrown\n`HandlerArgumentsInvalidError` (name and value-free `issues`) from `startAction`\nexactly as they do for `preview` so the form stays inline (see\n[REVIEW.md](REVIEW.md)). The `intake_dispositions` table requires\na manifest migration before upgrading.\n\n## Recipe preview\n\n`ingestion.inbox` and `ingestion.review` declare the user-facing inbox and\nreview workflows for app discovery. The reference workflow and measured\nevaluation are now published, but the evaluation did not meet supported-reference\nquality gates and did not establish safety. Automation remains disabled. The\nrecipes do not configure a source or provider, expose generic CRUD routes, or\nenable automatic execution. Mount `IntakeInbox` and `IntakeReview` with an\nauthenticated `IntakeReviewHost`; [REVIEW.md](REVIEW.md) remains the source of\ntruth for its scoped callbacks and freshness checks. See the [adoption\nchecklist](../../docs/evaluation/3677-adoption.md) and [measured\nreport](../../docs/evaluation/3677-measured-evaluation.md) for the release\nlimits.\n\nThe recipe manifest registers those existing browser components as\n`/ingestion/inbox` and `/ingestion/review` routes for a host to mount. The route\nmetadata does not supply a host, source, provider, or demo fixture, and it does\nnot change the preview-only status. Neither recipe declares generic model\nnavigation: the ingestion records have no generated screens, so hosts use the\nauthenticated route surfaces instead. Both recipes declare `both` runtime: their\ncomponents render in a browser, while the authenticated review host and package\ndependency closure require a server.\n\n## First analysis and host constraints\n\n`receive` retains evidence and queues the initial dispatch, but does not choose\nan extraction configuration. Before a worker can analyze a new item, the host must\ncall `analyze(itemId, { stage: 'extract', extraction: { configurationRevision,\nlimits } }, requestId)`, then claim that returned revision and run `extractAnalysis`.\nUse a stable request ID for retries. `repairDispatches` repairs queue delivery;\nit does not supply the missing extraction request. After extraction, use\n`prepareGeneration` and `analyze` to request interpretation.\n\nRetention requires `replayUntil >= expiresAt`; an earlier replay deadline rejects\neven a fresh delivery as `expired`. The replay tombstone must outlive retained\nsource bytes. Set both deadlines explicitly before calling `receive`.\n\nHandler preview `normalizedArgs` must equal the submitted arguments exactly.\nIt is an integrity assertion, not a normalization hook: defaults or tidying must\nhappen before submitting args for preview, so review binds exactly what was sent.\n\nProposal limits must be positive safe integers. `maxHandlers`, `maxCandidates`\nand `maxSuggestions` are each capped at 20; `timeoutMs` is capped at 2147483647.\nInvalid limits are rejected when constructing `IngestionService`, before receipt\nor interpretation. See [REVIEW.md](REVIEW.md) for the published server review host.\n\n`proposals.failureCapture` (`{ enabled, maxBytes?, redact? }`) is off by\ndefault. With `enabled: true` and a host `redact` hook, a failed interpretation\nattempt keeps the model output (or the parsed output that failed validation)\nfor diagnosis: cut to\n`maxBytes` (default 16384, at most 65536 UTF-8 bytes) after the host\n`redact` hook, stored beside the attempt result (not digested), readable only\nthrough the reviewer-authorized `getFailedAttemptCapture(itemId, attemptId?)`\nand removed with the item. A missing or failed hook stores only\n`redaction_failed` metadata, never text. Hosts own the semantic redaction policy;\nno built-in sanitizer is supplied. Invalid settings are rejected at construction.\nSee [PROPOSALS.md](PROPOSALS.md#failed-attempt-capture-opt-in-4285).\n\n## Trusted internal sources\n\nA host with a trusted internal source, such as chat messages recorded in\nsmrt-messages, can receive **by reference**, interpret **inline**, and let the\n**submitter** confirm their own proposal (#4085). None of these modes changes\ncopied receipts: their identity, validation, queueing and retention are\nuntouched, and a replay that switches mode conflicts.\n\n**Receive by reference.** A part may be `{ partId, reference: { owner, id,\nversion? }, snapshot: { text } | { structured } }` instead of bytes. The\nservice derives UTF-8 bytes once (`text/plain` or canonical `application/json`;\ntext, reference fields and owner identity containing NUL or unpaired\nsurrogates are rejected `invalid` on every engine, and `expireOwned` refuses\nthem, so distinct owners can never collapse onto one stored key),\nhashes them into the receipt identity, and stores only that snapshot in the\ndurable evidence row; no AssetStore object or asset record is created, and\n`readEvidence` serves the snapshot after the same hash/length check. The\nreference is identity and provenance, never authority. Such parts must be\ntext or structured; files still arrive as copied bytes.\n\n**Owner-bound retention.** `retention: { kind: 'owner', owner: { kind, id },\nversion, expiresAt, replayUntil, acceptAfter }` binds the receipt to its\nowner's lifecycle. The time deadlines remain required and validated exactly as\nbefore: they are the hard privacy ceiling, and `sweepRetention` and execution's\npolicy ceiling still apply. When the owner is deleted the host calls\n`expireOwned({ kind, id })` from its deletion path; every active receipt bound\nto that owner is revoked and removed through the existing `expire` /\n`repairDeletions` protocol, which redacts the snapshot together with every\nother payload, and the deleted delivery is never re-admitted. The owner key is\nrecorded in the indexed `owner_key` column (`<kind>:<id>`, so `kind` cannot\ncontain `:`). Deletion redaction blanks `owner_key` and `submitter_id` together\nwith every payload: only the receipt identity (`delivery_key`) and the captured\nceiling survive, and the ceiling loses `execution.principalId` unless an\nexternal action is still `executing` or `outcome_unknown`. So once nothing is\nleft to reconcile, a redacted row no longer links an owner to an actor, and a\nrepeated `expireOwned` finds nothing. Redaction also overwrites every\nidentity- or content-derived digest (`payload_digest`, `scope_digest`, analysis\n`input_digest`, attempt `output_digest`, plan `digest` and proposal, decision\nand execution `binding_hash`) with the fixed marker `redacted`; successful\nresult digests remain as the replay tombstone. The principal is retained only\nfor an external action that was still in flight when the item was redacted,\nbecause reconciling it authorizes under that principal; it is dropped when that\nreconciliation reaches a final state, or by the next `repairDeletions` /\n`sweepRetention` pass. For a self-approvable receipt the principal is the\nsubmitter, so until then it identifies the sender. Later deletion sweeps pass\nthis redacted ceiling to the host's `authorize({ operation: 'delete' })`, so\ndelete authorization must not depend on `execution.principalId`: a host that\nrequires it would refuse, and the sweep would stop with later deletion intents\nstill pending. A successful result digest\nis a plain SHA-256 of the canonical result, so it can confirm a guessed result:\nkeep handler results to record ids or opaque references, never content.\n\nA replay of a deleted delivery is rejected and never becomes fresh work. While\ndeletion is still pending it returns `rejected/expired`; once redaction has\ncompleted the identity digests are gone, so it returns `rejected/conflict`.\nSources treat both as terminal and must not retry. `delivery_key` stays in plaintext because it is\nthe unique receipt identity and the package holds no secret to key it: hosts\nmust use an opaque value (for example a random UUID recorded with the message)\nand must not encode owner ids, sender ids or content in `deliveryKey`.\n\nHost ordering for owner deletion: first stop issuing receipts for the owner,\nthen call `expireOwned`, and call it again once in-flight receipts settle (or\nfrom a periodic sweep). A receipt still in flight when its owner is expired\nreturns `{ kind: 'rejected', category: 'expired' }` rather than `accepted`, but\none that reserved its row after the first `expireOwned` is only found by the\nlater call; until then the time ceiling bounds it. Services are confidential-scope bound, so\na host whose owner has receipts in several confidential scopes calls\n`expireOwned` from each scope's service; a foreign tenant or scope sees zero.\n\n**Inline mode.** `receive({ ..., dispatch: 'inline' })` requires text/structured\nparts only, records the route provenance but **no deliverable dispatch intent**\nfor any revision (every intent is retained as `completed`, so no worker or\n`repairDispatches` ever picks it up), and does not enqueue. The host then calls\n`interpretInline(itemId, { requestId, extraction: { configurationRevision,\nlimits } })`, which runs in-process exactly what the job path runs: an\nimmutable `stage: 'extract'` revision claimed under a fenced lease and\nextracted with the built-in UTF-8 extractor, then `prepareGeneration` and the\n`stage: 'interpret'` revision with the same analysis lease, catalog-live\nchecks, provenance and failure categories as `generateProposals`. A retry with\nthe same `requestId` replays the immutable revisions, including when two\nidentical calls race. The interpretation is appended under the item lock only\nwhile its pinned extraction is still the latest revision; if another request\nreprocessed the item meanwhile it fails with `GenerationSourceStaleError` (the\ngeneral latest-extraction check every interpretation append runs, #4228) or,\nfor a pin whose extraction attempt was replaced, `Generation source changed`. The result reports each\nstage's attempt and safe error and, when generation completed, the authorized\n`getCompletedAnalysis` snapshot. Inline is for send-triggered suggestions that\nmust not depend on the scheduler; it is not a bypass of review or execution.\n\n**Submitter-scoped approval.** The service records `submitter_id` as the\nauthenticated `scope.actorId` of the receiving service, server-side; payload\nand source metadata never supply it. `listOwnProposals({ cursor?, limit? })`\nlists only this actor's own active submissions with their saved review pages,\nreloaded under current item/handler/target authority, without the reviewer\ninbox. A submission the actor can no longer read is skipped before projection\nand never named by the cursor; a readable one whose reviews are denied by\ningestion authority is returned as `{ item, reviews: null, unavailable: true }`\nwith no reason, so one revoked grant never hides the others. `submitOwnDecision(input)` accepts `approve`, `reject` or `defer` (never\n`correct`) under the `review_own` authority: the host's execution `authorize`\nmust return `submitter: true` for that actor, the application policy must opt\nin with `submitterReview: true` (narrower layers may only disable it), and the\nitem's recorded submitter must equal the current actor. Every other check is\nthe ordinary one, and `applyAction` remains the single once-only effect path\nunder the approver's live grants. Because the effect runs as the receipt's\ncaptured `capturedCeiling.execution.principalId`, `review_own` additionally\nrequires that principal to be the submitter itself (`submitter_id ===\nscope.actorId === principalId`), checked under the item lock at decision time\nand again at apply; a receipt captured for a bot or service principal can only\nbe approved by a reviewer. The decision is recorded with `mode` (`review` or\n`review_own`) and `selfDecision`, which is true whenever the deciding actor is\nthe item's submitter, in either mode (mirrored as `decisionMode` /\n`selfDecision` on feedback events), so a self-confirmation is never mistaken\nfor independent review and never contributes to automation eligibility. See\n[REVIEW.md](REVIEW.md) and [execution integration](agents/execution.md).\n\n## Dispatch route ownership and legacy recovery\n\nA receipt retains a versioned, server-owned `jobTarget` snapshot, and every\nanalysis dispatch retains the same route. Receipt replay and later analysis\ncannot retarget it. `repairDispatches()` filters by retained route before the\ncalling host's authorization or delivery budget, then rechecks provenance under\nthe item lock. A failed job for another host sharing the same tenant and\nconfidential scope neither runs on this host nor blocks its unrelated receipt.\nMatching routes still require current access within the captured permission\nceiling; their authorization and queue failures remain visible. Job arguments\ncontinue to contain identifiers only.\n\nLegacy receipts lacking route metadata can use existing recorded job authority\nonly when all available provenance agrees. A linked job must match the tenant,\ningestion queue, item, dispatch ID and revision exactly. This preserves recorded\njob authority, not a reconstruction of the host's historical intention. Conflicting\nor malformed provenance fails closed. Deleted jobs are absent provenance: an\nexisting protected route survives deletion, but without one the route remains\nunknown and automatic repair skips it.\n\n`inspectDispatchRoute(itemId)` requires normal read authority and returns a\nstatus, fingerprint and verified target (or null). For genuinely provenance-free\nlegacy receipts a host may opt into `dispatchRecovery.authorize`. Without this\nseparate operator authorization callback recovery is disabled. Quiesce legacy\nworkers and investigate their recorded job history before authorizing recovery;\nmissing history is not proof of a particular intended handler. Call\n`recoverDispatchRoute({ itemId, expectedFingerprint, evidenceRef })` with the\ninspection fingerprint and a nonblank evidence reference of at most 512\ncharacters. The target comes exclusively from that service's trusted,\nconstructor-snapshotted configuration, never from the request.\n\nRecovery acquires the item lock, rechecks current/captured process permissions\nand the separate host operator permission, and verifies the exact fingerprint.\nIt refuses bound, conflicting or stale authority. It appends retained operator,\ndate, evidence and original fingerprint provenance and binds missing dispatch\nmetadata atomically; it does not enqueue, alter original receipt/analysis/action\nfacts, or replace prior provenance. The exact original fingerprint/evidence retry\nreturns the retained binding, including under concurrent delivery, but still\nrechecks both permissions. A different decision conflicts. Once reviewed,\nnormal matching-host `repairDispatches()` may enqueue work separately. Hosts\nwithout legacy tenants need not configure recovery at all.\n"
     },
     {
       "path": "EXTRACTION.md",
@@ -1720,7 +1720,7 @@
     {
       "path": "PROPOSALS.md",
       "module": "PROPOSALS",
-      "content": "# Application-aware proposal generation\n\n`@happyvertical/smrt-ingestion/proposals` is server-only. Configure\n`IngestionOptions.proposals` and the existing `execution.handlers` catalog.\nHandlers opt into discovery with `discovery.mediaTypes`, `references`, and an\noptional `candidates` callback. There is one catalog: the same operation or\nordered playbook adapter is discovered, validated, previewed, and later applied\nby the execution service. Generation never approves or applies.\n\nCredential-free review hosts may configure `IngestionOptions.proposalRead` with\n`ProposalReadConfiguration`: public generator/decision identities, version,\nprompt version, limits and thresholds only. It reads completed proposals,\npreserves current authority and snapshot validation, and permits human preview;\nit never accepts a generator or provider client. If a process supplies both\nsettings, their public configuration must match exactly. Preparing or generating\nproposals still requires `proposals` with a real generator.\n\n## Discovery and authority\n\n`listHandlers(itemId)` returns a bounded detached catalog. The owning execution\nservice checks the current principal, captured permissions/handler/operation\nceiling, policy, confidential scope, public registered operation facts, and\nordered playbook definition. Every configured provider must occur in the current\npolicy's `providers` allowlist. Missing grants remove handlers before model input.\nAn authorized catalog larger than the configured bound is rejected; the host must\nnarrow it explicitly instead of relying on silent truncation.\n\n`findCandidates({itemId,handlerId,handlerVersion,query,limit})` returns\n`{items,truncated}`. Its trusted handler callback receives `HandlerContext` with\nthe authorized transaction executor. Query by tenant and confidential scope\n**before** selecting, ranking, or building labels. Use a bounded query (often\n`limit + 1`) and report `hasMore`. The service projects candidate identity, model,\nrevision and label, then checks every target with the owning execution callback.\nThere are no hidden counts or pagination tokens. Truncated discovery forces\n`needs_review`; a person may still preview it explicitly, and automation never\nbecomes eligible.\n\nCompleted generation reload checks process authority, the current attempt, and\nowner/candidate visibility in the same final transaction. Database-backed grant\ncallbacks must use the supplied executor. The owning retention lifecycle encloses\nthat transaction so a denied read cannot roll back an authorized shorter privacy\nceiling; restoration starts only after the outer transaction has rolled back.\n\nCandidate callbacks perform bounded database reads only: no provider I/O, network,\nor domain mutations. Target locks and existing retention enforcement remain\nowned by execution. Hosts configure their database's statement deadlines; an\narbitrary trusted callback is not a sandbox. Each existing-record argument must\nbe a declared top-level `references` field of kind `candidate` with its qualified\nmodel, or `evidence`. Closed JSON argument schemas are required. The host owns\nthat declaration and its target authorization semantics.\n\n## Durable stages\n\n1. Complete extraction through the existing analysis ledger.\n2. Call `prepareGeneration(itemId, extractionAttemptId)`. It reads the current\n   completed/partial immutable extraction and returns configuration with\n   `stage: 'interpret'`, pinned source attempt/revision/input/output/evidence\n   digests, prompt/configuration/catalog/provider versions, limits and thresholds.\n3. Pass that configuration to `analyze(itemId, configuration, requestKey)` and\n   claim its new revision with `claimAnalysis`.\n4. The host's existing job callback routes on the frozen `configuration.stage`:\n   extraction invokes `extractAnalysis`; interpretation invokes\n   `generateProposals(lease)`.\n5. Reload the current completed generation using `getCompletedAnalysis(itemId)`,\n   or pass an explicit attempt ID to additionally reject stale client state.\n   Queued/running revisions never return an older completed attempt.\n\n`analyze` refuses an interpretation configuration whose pinned source is not\nthe item's latest extraction, checked under the item lock before anything is\nsuperseded (`GenerationSourceStaleError`, nothing appended). A preparation\nsuperseded by a later extraction therefore fails at append time rather than\nafter a revision was created.\n\nA generation revision does not rewrite terminal extraction. Reprocessing starts\nwith a new extraction revision, followed by interpretation, while the host keeps\nthe same business intention keys. An interrupted still-current generation lease\ncan be retried; terminal generation output remains immutable. `getGenerationInput`\nreads historical extraction only through the current generation lease and its\nfrozen source pin. It verifies same-item scope, immutable hashes, durable evidence,\nand current process permission before returning detached data. The source must be\nthe immediately preceding revision, so an intervening reprocess invalidates a\nprepared generation. Completed generation reads additionally recheck current\ncatalog and target visibility before disclosing persisted candidate labels.\nExpired, cancelled, revoked, retried or superseded workers cannot read or publish late output. The\ncurrent lease and each offered handler/candidate are rechecked immediately before\neach outbound generative/decision boundary and before publication.\n\n### Inline interpretation\n\nReceipts created with `dispatch: 'inline'` (text/structured parts only) run the\nsame stages in-process through `interpretInline(itemId, { requestId, extraction\n})`: an immutable extraction revision claimed under a fenced lease and extracted\nwith the built-in UTF-8 extractor, then `prepareGeneration` and a fenced\ninterpretation revision generated by `generateProposals`. The analysis lease,\ncatalog digest and live catalog/candidate checks, source pin, provenance and\n`StageFailure` categories are identical to the job path; no dispatch intent is\never deliverable and nothing is enqueued. A retry with the same `requestId`\nreplays the recorded revisions rather than re-preparing against a superseded\nsource, also under concurrency. The interpretation append rechecks, under the\nitem lock, that its pinned extraction is still the latest revision and refuses\na superseded pin: first through the general latest-extraction check that\nevery interpretation append runs (`GenerationSourceStaleError`), then by the\ninline check that the pinned attempt is still current (`Generation source changed`). Generated suggestions still require explicit preview and a human\ndecision, either through the reviewer surface or the submitter-scoped surface\ndescribed in [REVIEW.md](REVIEW.md).\n\n## Providers and validation\n\n`createSDKProposalGenerator(client, identity, {maxTokens,timeoutMs})` uses an\nexisting AI SDK `chat` client. It sends a fixed system instruction and separate\nJSON evidence/catalog data, requests JSON, supplies cancellation and bounds, uses\nno tools or continuation, and rejects known truncation or tool calls,\nunexpected models, malformed JSON and oversized output. Configure SDK clients\nwithout automatic retry that would bypass application boundary checks. The\nadapter's public identity is exactly provider/model/version; credentials and raw\nprovider errors are never provenance.\n\nThe fixed system instruction (`proposalInstructions`, extended per item by\n`proposalInstructionsFor` with the handler argument contract and split\neligibility) is generic and value-free. It treats evidence as untrusted data,\nnever instructions, and limits suggestions to offered handlers and candidates.\nIt asks the model to fill every argument readable from the evidence\n(identifiers, numbers, dates, quantities, amounts and currency) in the form its\nschema requires, never inventing a value the evidence does not show; a value\nthat cannot be expressed in that form is treated as absent. Each value must be\nthe one whose label or context matches the field's name and description; when\nseveral similar values appear, a field whose named value is missing is treated\nas absent rather than given a substitute. A candidate reference is chosen only\nfrom that handler's listed candidates, and an evidence reference copies the\nsupplied `evidenceId`. `missingFields` lists exactly the required fields left\nout of `args`, and a required field is left out only when its value is genuinely\nabsent or no offered candidate matches. On required-only schema refusals, the\nvalidator computes the absent required set and corrects a mismatched model\ndeclaration; the instruction guides the model without making its declaration\nauthoritative. Absent optional fields stay out\nof both `args` and `missingFields`. The model prefers `no_action` when no\noffered handler's description fits the document's role, and `unknown` when the\nevidence cannot be interpreted (#4290). Domain routing, such as which received\ndocuments an application ignores, belongs in host handler descriptions or\nreviewer guidance, not in this text. The text is not persisted. It is not part\nof the frozen interpretation configuration, the input, catalog or output\ndigests, or the stored generation output, so a package release that changes it\nleaves stored attempts readable and previewable unchanged. New attempts send the\nnew text, but their digests do not record it; a host that needs provenance to\ntell the two apart bumps its own `promptVersion`, which, like any configuration\nchange, makes earlier attempts read as stale (`GenerationSnapshotStaleError`).\n\nA trusted custom `ProposalGenerator` must likewise honor cancellation, bound its\nresponse, and explicitly declare validated `complete` or `unknown` completion.\nThe SDK currently normalizes missing/unknown finish reasons to `stop`\n([owning SDK follow-up](https://github.com/happyvertical/sdk/issues/1381)), so its\nadapter conservatively declares `unknown`, persisted as\n`generation_completion_unknown`. Otherwise valid suggestions remain available\nfor human preview; automatic eligibility always remains false. The service\ndeadline aborts requests and prevents late publication; it does not claim to terminate computation at a remote\nprovider or isolate native allocations. Extractor process limits remain separate.\n\nWhen the pinned extraction carries an authenticated reviewer instruction\n(REVIEW.md), `prepareGeneration` copies it into the interpretation configuration\nand `generateProposals` verifies that copy against the extraction record and its\nown digest before provider disclosure (`integrity` otherwise). The prompt then\ncarries it in its own **trusted reviewer guidance** section after the fixed\nsystem instruction and handler contract: the guidance is named as authenticated\nhuman input, limited to the offered catalog, and the evidence remains untrusted\ndata. `GenerativeProposalInput.reviewerInstruction` exposes `{id, text}` to custom\ngenerators; `provenance.reviewerInstruction` records `{id, digest}`. The\ninstruction never changes `offered`, `catalogDigest`, argument schemas,\npermissions or `automaticActionEligible`; a reply that follows guidance outside\nthe catalog fails validation like any other hostile output. **Budget cost:** the instruction counts once against the input budget\n(`maxInputBytes`, each offered handler's `maxBytes` and the live policy\nceiling), as its JSON-escaped text inside the prompt's guidance section — up\nto 4,000 characters plus escaping and the fixed guidance sentence. The\n`reviewerInstruction` field duplicated for custom generators is not counted\nagain. The decision stage also carries it once: its request state holds the\nevidence-side input with the un-guided base instructions under `evidence`, and\nthe guidance only under a separate `reviewerGuidance` key, never under\n`evidence`; the decision budget measures that serialized request as sent. Size `maxInputBytes` with that headroom. Learned examples are\nstill retrieved for an instructed generation; only a logical split correction\nsuppresses them. Every instruction costs a fresh extraction revision before the\nnew interpretation: the predecessor-pin contract above (source = immediately\npreceding revision, current-revision reads) is deliberately left intact rather\nthan reused for a same-source second interpretation, so OCR/speech hosts budget\none extraction per instruction, as for split corrections.\n\nModel output can contain only offered handler versions, schema-valid arguments,\nretained evidence locations and offered alternative handler/candidate keys.\nCandidate IDs must occur in the offered set, and evidence IDs in retained source\nresults. Unknown enums, invented IDs, extra authority/tool/approval fields and\nmalformed structures fail closed. Missing required fields are retained as\n`missingFields`, with `needs_review`; values are never invented to satisfy a\nschema. Observed page/time/source granularity is preserved. Logical scan splits\nuse `proposeDocumentSplits`; originals and hashes remain intact.\n\nWhen a suggestion's arguments fail the handler schema **only** on `required`\n(#4284), the suggestion is kept rather than rejecting the attempt: its\narguments stay exactly as generated and `missingFields` names every missing\nrequired argument. The schema, not the model, decides what is missing. A\ndeclaration that matches the computed set (in any order) is kept exactly as the\nmodel wrote it, so an already valid reply is unchanged byte for byte and replay\nstays deterministic. A declaration that differs (unlisted misses, or listed\nfields that are present or optional) is replaced by the sorted computed set and\nthe suggestion is `needs_review` even when nothing is left missing;\n`provenance.missingFieldsCorrection` then records `{suggestions, added,\nremoved}` counts only, and is absent otherwise and dropped whenever the\nsuggestions are discarded. A miss at the\nargument root is the bare property name; a miss inside a present nested object\nor array item is an RFC 6901 JSON Pointer relative to the arguments, such as\n`/vendor/name` or `/lines/0/sku`. An entry starting with `/` is therefore a\npointer, so a handler should not declare a root property whose name itself\nstarts with `/`. Names come from the handler schema's own `required` lists,\nnever from argument values or model-chosen keys; `required` inside `allOf` or\ninside object-form `dependencies` (`{a: {required: ['b']}}`) counts like any\nother. The schema walk does not follow `$ref`: a miss directly at a property\nwhose schema is a `$ref` is kept, but a miss deeper inside the referenced\ndefinition cannot be named from the schema and rejects (fail-safe). The attempt still rejects as before when any other\nkeyword fails beside or instead of `required`: type, enum, pattern, bounds,\n`additionalProperties`, an `anyOf`/`oneOf` branch, an `if`/`then`/`else` branch\n(Ajv adds an `if` error), `not`, or array-form `dependencies` (its own keyword,\nalthough it names the missing property). It also rejects when a miss lies under\na key the schema does not declare, or when more than 30 fields are missing.\nHandler schemas compile in Ajv strict mode, so draft-2019 keywords such as\n`dependentRequired` are refused at compile time. Such a suggestion is ordinary\n`needs_review` output: the decision gate can only withhold readiness, never\ngrant it, `automaticActionEligible` stays false, and generated preview of\nincomplete arguments fails the handler schema (see Explicit preview below).\n\nA generated split whose groups fail that check is dropped, not the whole reply\n(#4288): the suggestions and any other splits are validated as before, the\ndropped split is never published or applied, and `provenance.splitsDropped`\nrecords `{count, checks: ['split_groups']}`, never pages or evidence ids. Any\nother split error still fails the attempt. If every split is dropped, the reply\nhas no split; a reviewer can still split through `reviseLogicalSplit`, and a\nrecorded split correction the reply no longer matches ends as\n`human_split_not_respected`. A split for unknown or repeated evidence is still\nrejected, even when the earlier split on that evidence was dropped. Like\n`duplicatesRemoved`, `splitsDropped` is kept only on a published, validated\nreply. Stored output is never re-validated, so earlier attempts and their\ndigests replay unchanged.\n\nA rejected reply ends the attempt as `provider_error` with the `malformed_output`\nwarning and a bounded, value-free `provenance.failure` `{category, reason}` (#4207).\nThe reason lists schema-owned paths, keywords and schema constants, for example\n`/outcome enum (allowedValues=proposals|unknown|...)` and\n`/suggestions/0 required (missingProperty=evidence)`, or the fixed internal check\nand its path, such as `Unoffered handler: /suggestions/0`. Path segments are\nkept only when they are keys declared under the schema's `properties` or\nindexes into a value that actually is an array in the rejected reply; any other\nsegment, numeric or not (for example a key under an open\n`additionalProperties` argument sub-schema, or a numeric key of an object),\nbecomes `?`, and an extra property's name is never echoed.\nIt never contains document text, argument values, evidence content or\nmodel-chosen keys, is cut at 1000 characters,\nand is dropped before the output-limit fallback. Hosts read it from the\ncompleted/partial analysis at `analysis.result.output.proposals.provenance.failure`.\nThe SDK adapter constrains replies with a `json_schema` response format built\nfrom the validator's schema and the fixed instructions describe the shape; a\ncustom `ProposalGenerator` receives no schema, so its raw reply meets the\nvalidator directly and the same reason is recorded.\nThe provider-facing schema is made portable (`portableResponseSchema`, #4260):\nkeywords that common OpenAI-compatible structured-output backends reject are\nremoved at schema positions, including inside handler argument schemas\n(`uniqueItems`, `contains`, `multipleOf`, `format`, `patternProperties`,\n`propertyNames`, `min`/`maxProperties`, `not`, `if`/`then`/`else`,\n`dependent*`, `unevaluated*`, and the `default`/`examples` annotations; the\nfull list and reasons are in `src/proposal-sdk.ts`). With `uniqueItems`, for\nexample, vLLM's xgrammar feature check flags the schema, its auto mode routes\nit to llguidance, and llguidance answers\n`400 Grammar error: Unimplemented keys: [\"uniqueItems\"]`. This only loosens the\ngrammar: the validator still enforces the constraints, including unique\n`alternatives` and `missingFields`, and the fixed instructions ask for distinct\nentries. The exception is `format`, which is advisory: the validator runs Ajv\nwith `validateFormats: false`, so `format` is enforced nowhere. Because a model\ncan still repeat an entry, fresh generator output is normalized first (#4286):\nwithin each suggestion, repeated `alternatives` and `missingFields` entries\n(equal by canonical JSON) are dropped, keeping the first. Nothing else is\nrewritten, and `uniqueItems` still applies to the result. The count, never the\nvalues, is recorded as `provenance.duplicatesRemoved`, present only when\nnon-zero and only on a published, validated reply. The published output, and so\nits digest, is the normalized form. Stored attempts are read and replayed as\npersisted; they are never renormalized. When\n`patternProperties` is removed, the same object's `additionalProperties` is\nremoved too, so the grammar does not shrink to `{}`. The `contentSchema` annotation is omitted as well, so nested unsupported\nconstraints cannot leak through an unvisited schema position. A backend may\nrecursively inspect typed schema-like objects even inside `enum` or `const`\ndata. When such data contains an unsupported keyword, the whole containing\n`enum`/`const` constraint is omitted conservatively; literal data is never\nrewritten. Harmless property names and ordinary enum/const data stay intact.\nThe original validator remains authoritative for omitted literal constraints.\nThere is no automatic `json_object` fallback.\n\nInvariant: the provider copy only ever accepts a superset of what the original\naccepts. Each removed keyword is a conjunct, so removing it only widens. The two\nplaces where removal would narrow are rewritten:\n- every `oneOf` becomes `anyOf` (or joins an existing `anyOf` through `allOf`),\n  because loosened `oneOf` branches could both match and reject a value the\n  original accepted;\n- an object that loses `patternProperties` also loses `additionalProperties`.\n\nProvider-only `$ref`, `$dynamicRef`, and `$recursiveRef` constraints are also\nremoved. Rewriting or deleting a subschema can invalidate pointer or anchor\ntargets, including targets inside nested `$id` resources. Dropping references\nconservatively widens the grammar without resolving untrusted schema resources;\nproperty names and enum/const data named `$ref` remain unchanged. Referenced\nconstraints, recursion, and dynamic scope remain enforced by the original\nvalidator, so provider guidance for reference-based arguments is less precise.\n\nThe validator still checks the original, including `oneOf` exclusivity. A\nproperty-style regression checks original-valid ⇒ portable-valid across the\nremoved keywords. Handler argument schemas may still carry `allOf` through\nunchanged; its support across backends is unverified, so check such a handler\nagainst the deployed backend.\n\nA generator call that throws ends the attempt as `provider_error` with the\n`unavailable` warning and `provenance.failure` `{category: 'unavailable',\nreason}`. The reason is value-free by construction: a provider's own text can\nquote the prompt or document, so it is never copied. The reason is built only\nfrom a fixed phrase and, for an SDK `AIError` only, the HTTP status (from a\nstructured field, or from the exact `<status> ...` / `TypeSafe request failed\n(<status>): ...` shapes the SDK produces), the SDK error code (from the closed\nlist of codes the SDK raises) and, for a schema rejection, quoted tokens that\nare JSON Schema keywords. Any other error contributes at most a structured\nnumeric status. For example: `provider rejected the response schema (HTTP 400,\ncode API_ERROR); unsupported response-schema keywords: uniqueItems`, or just\n`provider call failed`. It is cut at 500 characters.\n\n`createSDKProposalDecisionClient(client)` adapts an existing SDK client’s optional\ncapability without changing its errors or protocol. Optional `decision` uses public core `executeDecision` and the existing SDK\npredicate, choice, score and batch contracts. Supported-effect predicates,\nhandler classification, candidate entity matching, and action ambiguity/risk\nare distinct questions. Their validated probabilities and provenance are stored\nseparately from generative provenance and unknown OCR certainty. The complete\nserialized decision request, including suggestions and questions, must fit the\nminimum configured/current policy byte ceiling before capability probing and\nagain before deciding. A policy change between these boundaries fails closed.\nActually incomplete extraction always requires review. Unknown provider\ncompletion metadata is preserved as `source_completion_unknown`; it does not\nblock otherwise schema-valid **human** preview or imply completeness. Automatic\naction eligibility remains false. An unconfigured decision path\nis recorded explicitly. Configured errors produce a durable safe failure outcome;\nthey never silently switch to a generative decision fallback.\n\n### Decision readiness gate (#4209)\n\nFor every suggestion `i` the request asks `supported_i` (predicate),\n`route_i` (choice over the offered `handlerId@version` keys plus `none`),\n`risk_i` (ordered score over `clear`, `uncertain`, `ambiguous`) and one\n`entity_i_<field>` choice per candidate-reference argument. The validated\nanswers are always persisted under `provenance.decision.answers`. With the\ndefault `decisionReadiness: 'gate'` they are read as follows, and any failing\ncheck sets the suggestion to `needs_review` (a tie also sets the outcome to\n`ambiguous`):\n\n- `supported.probability >= minimumDecisionProbability` (default `0.8`).\n- `route.choice` equals the suggestion's own `handlerId@handlerVersion`,\n  `route.confidence >= minimumDecisionProbability`, and the gap between the two\n  largest route probabilities is greater than `tieMargin` (default `0.1`).\n- `risk.score < 1`: only the `clear` level passes; `uncertain` and `ambiguous`\n  require review.\n- Each entity match chooses the suggested candidate's key with confidence at or\n  above the threshold and a gap above `tieMargin`.\n\nThese values are provider outputs read as if they were calibrated\nprobabilities; nothing in this package calibrates them for this use. The\nteamworks-os measurement in #4209 (self-hosted Laya `typed-decisions`) found no\nseparation between right and wrong suggestions: a correctly read vendor invoice\nscored `supported` 0.37, garbage input 0.45–0.50, a wrongly proposed purchase\norder 0.51, route confidence 0.003–0.15 and `risk` ≥ 0.94, so the gate sent\nevery suggestion to review. Until a labelled sample shows separation, treat the\nanswers as diagnostics and configure:\n\n- `decisionMaxLen`: positive integer forwarded unchanged as the per-request\n  `maxLen` of the decision client (the SDK Laya provider's token window; the\n  checkpoint default is 1024 and the serialized evidence plus suggestions is\n  otherwise truncated). Other clients ignore it.\n- `decisionReadiness: 'record'`: the decision still runs, is bounded and\n  authorized exactly as before and its answers, usage, `readiness` and `maxLen`\n  are recorded, but the gate never changes `outcome` or `disposition`; readiness\n  comes from the validator alone (`missingFields`, outcome, source completeness).\n  A client error or timeout is recorded as the `decision_unavailable`\n  warning. A reply that comes back and then fails the core `executeDecision`\n  identity or answer-shape check is recorded as `decision_malformed` with the\n  reply's usage; this is the path for injected `DecisionClient`s. SDK clients,\n  including the Laya provider behind `createSDKProposalDecisionClient`,\n  validate the reply's shape inside `client.decide` and throw, so a malformed\n  SDK reply is recorded as `decision_unavailable` with no usage. Every case\n  records the `provenance.decision` identity. The generated suggestions stay\n  as they were. The serialized request exceeding the byte budget is a\n  configuration failure, not a provider answer: it ends the attempt as `limit`\n  in both modes, and in `gate` mode every failure above still ends the attempt\n  as `provider_error`. Lease, catalog, policy and provider-allowlist revocation\n  fail closed in both modes.\n\nSuccessful output also records `provenance.decision.readiness` (`'gate'` or\n`'record'`) and `maxLen` when set; configuration digests are unchanged, but\npersisted output is therefore not byte-identical to earlier releases.\n\nBoth settings are public configuration: they are part of\n`ProposalReadConfiguration`, the frozen `GenerationStageConfiguration.proposals`\n(present only when set, so existing digests are unchanged) and the completed\nsnapshot authority check. Invalid values fail at proposal service construction.\nNeither mode affects automation: `automaticActionEligible` stays `false`, and\n`authorizeAutomatic` reads only the host's `evaluateAutomatic` callback and\npolicy, never these answers.\n\nOutput records zero, one or multiple suggestions, alternatives, missing fields,\nsource links, proposed splits, versions, allowlisted usage, warnings and explicit\n`unknown`, `ambiguous`, `no_action`, `needs_review` or `provider_error` outcomes.\n`automaticActionEligible` is always false. Provider input/output and the complete\nserialized persisted envelope are bounded by configuration, live policy and the\nreceipt ceiling. Oversized output becomes a bounded review/limit result; when\nno safe envelope fits, the owning service records fixed `failAnalysis` metadata\noutside the provider payload budget without retaining provider output.\n\n## Explicit preview and stable intentions\n\nThe host chooses persisted suggestion indexes and calls:\n\n```ts\nawait service.previewGeneratedProposals({\n  itemId,\n  attemptId: generationAttemptId,\n  selections: [{\n    index: 0,\n    intentionKey: 'document:meeting-2026-10-09',\n    expectedRevision: 0,\n    requestId: 'review-request-1',\n  }],\n});\n```\n\n`intentionKey` is the host's stable business-intention identity across generation\nrevisions. Never derive a fresh key from model output, suggestion order or a retry.\nSelections must reference current persisted validated `ready_for_review` or\n`needs_review` output (#4208); a `provider_error` attempt, an unoffered handler or\na non-interpretation stage is rejected. A `needs_review` suggestion whose\n`missingFields` are still absent fails the handler schema inside the ordinary\npreview (`HandlerArgumentsInvalidError`, `Invalid handler payload`, whose\nvalue-free `issues` name the missing schema fields, for example\n`{ path: '/title', keyword: 'required' }`; see REVIEW.md) and publishes\nnothing; the reviewer supplies\nthe missing values through the explicit human path (`previewProposal` /\n`previewPlan`, as the published review host does for `preview({args})`), and the\nhandler's `validate` and `preview` run again on the completed arguments.\nEach batch requires distinct suggestion indexes and intention keys; duplicate\nindexes are rejected before any operation or plan preview is written.\nThe service rechecks current catalog/schema/target/source provenance, then calls\nthe existing operation or plan preview. Each result still requires the ordinary\nhuman review and execution APIs. Reprocessing creates no new business identity;\nsuccessful-action replay protection stays with execution.\n\n## Evidence and limits\n\nThe test matrix is `docs/test-matrix/3673-ingestion-proposals.md`. SQLite and real\nPostgreSQL suites exercise authority, revisions, abstention, hostile output,\ncompound proposals, split provenance and reviewed domain effects. The upload\nreference composes authenticated multipart delivery of a generated embedded-text\nPDF through the actual packaged PDF child, durable interpretation, and the existing\nordered ContentDocument draft/retained-asset plan. It checks duplicate delivery,\nunauthenticated and foreign-tenant denial, explicit approval of both steps,\nidempotent execution replay, page provenance, and unchanged original bytes.\nThe compound-email case uses a declared messages-owner snapshot fixture.\n\nLocal HTTP fixtures execute the actual AI SDK transport and cancellation contract.\nGenerative responses and the separate injected PDF split boundaries establish\ndeterministic orchestration, not model accuracy or OCR quality. No held-out routing\nevaluation or automatic approval is claimed. Missing/unknown AI completion remains\nexplicit under [SDK #1381](https://github.com/happyvertical/sdk/issues/1381).\n\nProposal limits are checked at `IngestionService` construction: positive safe\nintegers, at most 20 handlers/candidates/suggestions and 2147483647 ms timeout.\nInterpretation output uses the exported `GenerationAnalysisOutput` wrapper at\n`analysis.result.output.proposals`; the published review host unwraps it.\nAn explicit feedback `retrieve` denial omits optional examples and feedback\nprovenance and continues generation. Item/execution denials, unexpected failures,\nand revocation after examples were selected still fail closed before disclosure.\n"
+      "content": "# Application-aware proposal generation\n\n`@happyvertical/smrt-ingestion/proposals` is server-only. Configure\n`IngestionOptions.proposals` and the existing `execution.handlers` catalog.\nHandlers opt into discovery with `discovery.mediaTypes`, `references`, and an\noptional `candidates` callback. There is one catalog: the same operation or\nordered playbook adapter is discovered, validated, previewed, and later applied\nby the execution service. Generation never approves or applies.\n\nCredential-free review hosts may configure `IngestionOptions.proposalRead` with\n`ProposalReadConfiguration`: public generator/decision identities, version,\nprompt version, limits and thresholds only. It reads completed proposals,\npreserves current authority and snapshot validation, and permits human preview;\nit never accepts a generator or provider client. If a process supplies both\nsettings, their public configuration must match exactly. Preparing or generating\nproposals still requires `proposals` with a real generator.\n\n## Discovery and authority\n\n`listHandlers(itemId)` returns a bounded detached catalog. The owning execution\nservice checks the current principal, captured permissions/handler/operation\nceiling, policy, confidential scope, public registered operation facts, and\nordered playbook definition. Every configured provider must occur in the current\npolicy's `providers` allowlist. Missing grants remove handlers before model input.\nAn authorized catalog larger than the configured bound is rejected; the host must\nnarrow it explicitly instead of relying on silent truncation.\n\n`findCandidates({itemId,handlerId,handlerVersion,query,limit})` returns\n`{items,truncated}`. Its trusted handler callback receives `HandlerContext` with\nthe authorized transaction executor. Query by tenant and confidential scope\n**before** selecting, ranking, or building labels. Use a bounded query (often\n`limit + 1`) and report `hasMore`. The service projects candidate identity, model,\nrevision and label, then checks every target with the owning execution callback.\nThere are no hidden counts or pagination tokens. Truncated discovery forces\n`needs_review`; a person may still preview it explicitly, and automation never\nbecomes eligible.\n\nCompleted generation reload checks process authority, the current attempt, and\nowner/candidate visibility in the same final transaction. Database-backed grant\ncallbacks must use the supplied executor. The owning retention lifecycle encloses\nthat transaction so a denied read cannot roll back an authorized shorter privacy\nceiling; restoration starts only after the outer transaction has rolled back.\n\nCandidate callbacks perform bounded database reads only: no provider I/O, network,\nor domain mutations. Target locks and existing retention enforcement remain\nowned by execution. Hosts configure their database's statement deadlines; an\narbitrary trusted callback is not a sandbox. Each existing-record argument must\nbe a declared top-level `references` field of kind `candidate` with its qualified\nmodel, or `evidence`. Closed JSON argument schemas are required. The host owns\nthat declaration and its target authorization semantics.\n\n## Durable stages\n\n1. Complete extraction through the existing analysis ledger.\n2. Call `prepareGeneration(itemId, extractionAttemptId)`. It reads the current\n   completed/partial immutable extraction and returns configuration with\n   `stage: 'interpret'`, pinned source attempt/revision/input/output/evidence\n   digests, prompt/configuration/catalog/provider versions, limits and thresholds.\n3. Pass that configuration to `analyze(itemId, configuration, requestKey)` and\n   claim its new revision with `claimAnalysis`.\n4. The host's existing job callback routes on the frozen `configuration.stage`:\n   extraction invokes `extractAnalysis`; interpretation invokes\n   `generateProposals(lease)`.\n5. Reload the current completed generation using `getCompletedAnalysis(itemId)`,\n   or pass an explicit attempt ID to additionally reject stale client state.\n   Queued/running revisions never return an older completed attempt.\n\n`analyze` refuses an interpretation configuration whose pinned source is not\nthe item's latest extraction, checked under the item lock before anything is\nsuperseded (`GenerationSourceStaleError`, nothing appended). A preparation\nsuperseded by a later extraction therefore fails at append time rather than\nafter a revision was created.\n\nA generation revision does not rewrite terminal extraction. Reprocessing starts\nwith a new extraction revision, followed by interpretation, while the host keeps\nthe same business intention keys. An interrupted still-current generation lease\ncan be retried; terminal generation output remains immutable. `getGenerationInput`\nreads historical extraction only through the current generation lease and its\nfrozen source pin. It verifies same-item scope, immutable hashes, durable evidence,\nand current process permission before returning detached data. The source must be\nthe immediately preceding revision, so an intervening reprocess invalidates a\nprepared generation. Completed generation reads additionally recheck current\ncatalog and target visibility before disclosing persisted candidate labels.\nExpired, cancelled, revoked, retried or superseded workers cannot read or publish late output. The\ncurrent lease and each offered handler/candidate are rechecked immediately before\neach outbound generative/decision boundary and before publication.\n\n### Inline interpretation\n\nReceipts created with `dispatch: 'inline'` (text/structured parts only) run the\nsame stages in-process through `interpretInline(itemId, { requestId, extraction\n})`: an immutable extraction revision claimed under a fenced lease and extracted\nwith the built-in UTF-8 extractor, then `prepareGeneration` and a fenced\ninterpretation revision generated by `generateProposals`. The analysis lease,\ncatalog digest and live catalog/candidate checks, source pin, provenance and\n`StageFailure` categories are identical to the job path; no dispatch intent is\never deliverable and nothing is enqueued. A retry with the same `requestId`\nreplays the recorded revisions rather than re-preparing against a superseded\nsource, also under concurrency. The interpretation append rechecks, under the\nitem lock, that its pinned extraction is still the latest revision and refuses\na superseded pin: first through the general latest-extraction check that\nevery interpretation append runs (`GenerationSourceStaleError`), then by the\ninline check that the pinned attempt is still current (`Generation source changed`). Generated suggestions still require explicit preview and a human\ndecision, either through the reviewer surface or the submitter-scoped surface\ndescribed in [REVIEW.md](REVIEW.md).\n\n## Providers and validation\n\n`createSDKProposalGenerator(client, identity, {maxTokens,timeoutMs})` uses an\nexisting AI SDK `chat` client. It sends a fixed system instruction and separate\nJSON evidence/catalog data, requests JSON, supplies cancellation and bounds, uses\nno tools or continuation, and rejects known truncation or tool calls,\nunexpected models, malformed JSON and oversized output. Configure SDK clients\nwithout automatic retry that would bypass application boundary checks. The\nadapter's public identity is exactly provider/model/version; credentials and raw\nprovider errors are never provenance.\n\nThe fixed system instruction (`proposalInstructions`, extended per item by\n`proposalInstructionsFor` with the handler argument contract and split\neligibility) is generic and value-free. It treats evidence as untrusted data,\nnever instructions, and limits suggestions to offered handlers and candidates.\nIt asks the model to fill every argument readable from the evidence\n(identifiers, numbers, dates, quantities, amounts and currency) in the form its\nschema requires, never inventing a value the evidence does not show; a value\nthat cannot be expressed in that form is treated as absent. Each value must be\nthe one whose label or context matches the field's name and description; when\nseveral similar values appear, a field whose named value is missing is treated\nas absent rather than given a substitute. A candidate reference is chosen only\nfrom that handler's listed candidates, and an evidence reference copies the\nsupplied `evidenceId`. `missingFields` lists exactly the required fields left\nout of `args`, and a required field is left out only when its value is genuinely\nabsent or no offered candidate matches. On required-only schema refusals, the\nvalidator computes the absent required set and corrects a mismatched model\ndeclaration; the instruction guides the model without making its declaration\nauthoritative. Absent optional fields stay out\nof both `args` and `missingFields`. The model prefers `no_action` when no\noffered handler's description fits the document's role, and `unknown` when the\nevidence cannot be interpreted (#4290). Domain routing, such as which received\ndocuments an application ignores, belongs in host handler descriptions or\nreviewer guidance, not in this text. The text is not persisted. It is not part\nof the frozen interpretation configuration, the input, catalog or output\ndigests, or the stored generation output, so a package release that changes it\nleaves stored attempts readable and previewable unchanged. New attempts send the\nnew text, but their digests do not record it; a host that needs provenance to\ntell the two apart bumps its own `promptVersion`, which, like any configuration\nchange, makes earlier attempts read as stale (`GenerationSnapshotStaleError`).\n\nA trusted custom `ProposalGenerator` must likewise honor cancellation, bound its\nresponse, and explicitly declare validated `complete` or `unknown` completion.\nThe SDK currently normalizes missing/unknown finish reasons to `stop`\n([owning SDK follow-up](https://github.com/happyvertical/sdk/issues/1381)), so its\nadapter conservatively declares `unknown`, persisted as\n`generation_completion_unknown`. Otherwise valid suggestions remain available\nfor human preview; automatic eligibility always remains false. The service\ndeadline aborts requests and prevents late publication; it does not claim to terminate computation at a remote\nprovider or isolate native allocations. Extractor process limits remain separate.\n\nWhen the pinned extraction carries an authenticated reviewer instruction\n(REVIEW.md), `prepareGeneration` copies it into the interpretation configuration\nand `generateProposals` verifies that copy against the extraction record and its\nown digest before provider disclosure (`integrity` otherwise). The prompt then\ncarries it in its own **trusted reviewer guidance** section after the fixed\nsystem instruction and handler contract: the guidance is named as authenticated\nhuman input, limited to the offered catalog, and the evidence remains untrusted\ndata. `GenerativeProposalInput.reviewerInstruction` exposes `{id, text}` to custom\ngenerators; `provenance.reviewerInstruction` records `{id, digest}`. The\ninstruction never changes `offered`, `catalogDigest`, argument schemas,\npermissions or `automaticActionEligible`; a reply that follows guidance outside\nthe catalog fails validation like any other hostile output. **Budget cost:** the instruction counts once against the input budget\n(`maxInputBytes`, each offered handler's `maxBytes` and the live policy\nceiling), as its JSON-escaped text inside the prompt's guidance section — up\nto 4,000 characters plus escaping and the fixed guidance sentence. The\n`reviewerInstruction` field duplicated for custom generators is not counted\nagain. The decision stage also carries it once: its request state holds the\nevidence-side input with the un-guided base instructions under `evidence`, and\nthe guidance only under a separate `reviewerGuidance` key, never under\n`evidence`; the decision budget measures that serialized request as sent. Size `maxInputBytes` with that headroom. Learned examples are\nstill retrieved for an instructed generation; only a logical split correction\nsuppresses them. Every instruction costs a fresh extraction revision before the\nnew interpretation: the predecessor-pin contract above (source = immediately\npreceding revision, current-revision reads) is deliberately left intact rather\nthan reused for a same-source second interpretation, so OCR/speech hosts budget\none extraction per instruction, as for split corrections.\n\nModel output can contain only offered handler versions, schema-valid arguments,\nretained evidence locations and offered alternative handler/candidate keys.\nCandidate IDs must occur in the offered set, and evidence IDs in retained source\nresults. Unknown enums, invented IDs, extra authority/tool/approval fields and\nmalformed structures fail closed. Missing required fields are retained as\n`missingFields`, with `needs_review`; values are never invented to satisfy a\nschema. Observed page/time/source granularity is preserved. Logical scan splits\nuse `proposeDocumentSplits`; originals and hashes remain intact.\n\nWhen a suggestion's arguments fail the handler schema **only** on `required`\n(#4284), the suggestion is kept rather than rejecting the attempt: its\narguments stay exactly as generated and `missingFields` names every missing\nrequired argument. The schema, not the model, decides what is missing. A\ndeclaration that matches the computed set (in any order) is kept exactly as the\nmodel wrote it, so an already valid reply is unchanged byte for byte and replay\nstays deterministic. A declaration that differs (unlisted misses, or listed\nfields that are present or optional) is replaced by the sorted computed set and\nthe suggestion is `needs_review` even when nothing is left missing;\n`provenance.missingFieldsCorrection` then records `{suggestions, added,\nremoved}` counts only, and is absent otherwise and dropped whenever the\nsuggestions are discarded. A miss at the\nargument root is the bare property name; a miss inside a present nested object\nor array item is an RFC 6901 JSON Pointer relative to the arguments, such as\n`/vendor/name` or `/lines/0/sku`. An entry starting with `/` is therefore a\npointer, so a handler should not declare a root property whose name itself\nstarts with `/`. Names come from the handler schema's own `required` lists,\nnever from argument values or model-chosen keys; `required` inside `allOf` or\ninside object-form `dependencies` (`{a: {required: ['b']}}`) counts like any\nother. The schema walk does not follow `$ref`: a miss directly at a property\nwhose schema is a `$ref` is kept, but a miss deeper inside the referenced\ndefinition cannot be named from the schema and rejects (fail-safe). The attempt still rejects as before when any other\nkeyword fails beside or instead of `required`: type, enum, pattern, bounds,\n`additionalProperties`, an `anyOf`/`oneOf` branch, an `if`/`then`/`else` branch\n(Ajv adds an `if` error), `not`, or array-form `dependencies` (its own keyword,\nalthough it names the missing property). It also rejects when a miss lies under\na key the schema does not declare, or when more than 30 fields are missing.\nHandler schemas compile in Ajv strict mode, so draft-2019 keywords such as\n`dependentRequired` are refused at compile time. Such a suggestion is ordinary\n`needs_review` output: the decision gate can only withhold readiness, never\ngrant it, `automaticActionEligible` stays false, and generated preview of\nincomplete arguments fails the handler schema (see Explicit preview below).\n\nA generated split whose groups fail that check is dropped, not the whole reply\n(#4288): the suggestions and any other splits are validated as before, the\ndropped split is never published or applied, and `provenance.splitsDropped`\nrecords `{count, checks: ['split_groups']}`, never pages or evidence ids. Any\nother split error still fails the attempt. If every split is dropped, the reply\nhas no split; a reviewer can still split through `reviseLogicalSplit`, and a\nrecorded split correction the reply no longer matches ends as\n`human_split_not_respected`. A split for unknown or repeated evidence is still\nrejected, even when the earlier split on that evidence was dropped. Like\n`duplicatesRemoved`, `splitsDropped` is kept only on a published, validated\nreply. Stored output is never re-validated, so earlier attempts and their\ndigests replay unchanged.\n\nA rejected reply ends the attempt as `provider_error` with the `malformed_output`\nwarning and a bounded, value-free `provenance.failure` `{category, reason}` (#4207).\nThe reason lists schema-owned paths, keywords and schema constants, for example\n`/outcome enum (allowedValues=proposals|unknown|...)` and\n`/suggestions/0 required (missingProperty=evidence)`, or the fixed internal check\nand its path, such as `Unoffered handler: /suggestions/0`. Path segments are\nkept only when they are keys declared under the schema's `properties` or\nindexes into a value that actually is an array in the rejected reply; any other\nsegment, numeric or not (for example a key under an open\n`additionalProperties` argument sub-schema, or a numeric key of an object),\nbecomes `?`, and an extra property's name is never echoed.\nIt never contains document text, argument values, evidence content or\nmodel-chosen keys, is cut at 1000 characters,\nand is dropped before the output-limit fallback. Hosts read it from the\ncompleted/partial analysis at `analysis.result.output.proposals.provenance.failure`.\nThe SDK adapter constrains replies with a `json_schema` response format built\nfrom the validator's schema and the fixed instructions describe the shape; a\ncustom `ProposalGenerator` receives no schema, so its raw reply meets the\nvalidator directly and the same reason is recorded.\nThe provider-facing schema is made portable (`portableResponseSchema`, #4260):\nkeywords that common OpenAI-compatible structured-output backends reject are\nremoved at schema positions, including inside handler argument schemas\n(`uniqueItems`, `contains`, `multipleOf`, `format`, `patternProperties`,\n`propertyNames`, `min`/`maxProperties`, `not`, `if`/`then`/`else`,\n`dependent*`, `unevaluated*`, and the `default`/`examples` annotations; the\nfull list and reasons are in `src/proposal-sdk.ts`). With `uniqueItems`, for\nexample, vLLM's xgrammar feature check flags the schema, its auto mode routes\nit to llguidance, and llguidance answers\n`400 Grammar error: Unimplemented keys: [\"uniqueItems\"]`. This only loosens the\ngrammar: the validator still enforces the constraints, including unique\n`alternatives` and `missingFields`, and the fixed instructions ask for distinct\nentries. The exception is `format`, which is advisory: the validator runs Ajv\nwith `validateFormats: false`, so `format` is enforced nowhere. Because a model\ncan still repeat an entry, fresh generator output is normalized first (#4286):\nwithin each suggestion, repeated `alternatives` and `missingFields` entries\n(equal by canonical JSON) are dropped, keeping the first. Nothing else is\nrewritten, and `uniqueItems` still applies to the result. The count, never the\nvalues, is recorded as `provenance.duplicatesRemoved`, present only when\nnon-zero and only on a published, validated reply. The published output, and so\nits digest, is the normalized form. Stored attempts are read and replayed as\npersisted; they are never renormalized. When\n`patternProperties` is removed, the same object's `additionalProperties` is\nremoved too, so the grammar does not shrink to `{}`. The `contentSchema` annotation is omitted as well, so nested unsupported\nconstraints cannot leak through an unvisited schema position. A backend may\nrecursively inspect typed schema-like objects even inside `enum` or `const`\ndata. When such data contains an unsupported keyword, the whole containing\n`enum`/`const` constraint is omitted conservatively; literal data is never\nrewritten. Harmless property names and ordinary enum/const data stay intact.\nThe original validator remains authoritative for omitted literal constraints.\nThere is no automatic `json_object` fallback.\n\nInvariant: the provider copy only ever accepts a superset of what the original\naccepts. Each removed keyword is a conjunct, so removing it only widens. The two\nplaces where removal would narrow are rewritten:\n- every `oneOf` becomes `anyOf` (or joins an existing `anyOf` through `allOf`),\n  because loosened `oneOf` branches could both match and reject a value the\n  original accepted;\n- an object that loses `patternProperties` also loses `additionalProperties`.\n\nProvider-only `$ref`, `$dynamicRef`, and `$recursiveRef` constraints are also\nremoved. Rewriting or deleting a subschema can invalidate pointer or anchor\ntargets, including targets inside nested `$id` resources. Dropping references\nconservatively widens the grammar without resolving untrusted schema resources;\nproperty names and enum/const data named `$ref` remain unchanged. Referenced\nconstraints, recursion, and dynamic scope remain enforced by the original\nvalidator, so provider guidance for reference-based arguments is less precise.\n\nThe validator still checks the original, including `oneOf` exclusivity. A\nproperty-style regression checks original-valid ⇒ portable-valid across the\nremoved keywords. Handler argument schemas may still carry `allOf` through\nunchanged; its support across backends is unverified, so check such a handler\nagainst the deployed backend.\n\nA generator call that throws ends the attempt as `provider_error` with the\n`unavailable` warning and `provenance.failure` `{category: 'unavailable',\nreason}`. The reason is value-free by construction: a provider's own text can\nquote the prompt or document, so it is never copied. The reason is built only\nfrom a fixed phrase and:\n\n- for an SDK `AIError` only, the HTTP status (from a structured field, or from\n  the exact `<status> ...` / `TypeSafe request failed (<status>): ...` shapes\n  the SDK produces), the SDK error code (from the closed list of codes the SDK\n  raises), for a schema rejection the quoted tokens that are JSON Schema\n  keywords, and the OpenAI SDK's exact fixed transport messages\n  (`Connection error.`, `Request timed out.`, `Request was aborted.`,\n  `(no status code or body)`), which its `mapError` keeps without a cause;\n- for the SDK adapter's own refusal of a reply it did receive, a fixed problem:\n  finish reason other than `stop` (named from the closed list `stop`, `length`,\n  `tool_calls`, `content_filter`, otherwise `other`), truncation, tool calls,\n  an unexpected response model, no text content, an empty reply, a reply over\n  the output limit, or a reply that is not valid JSON (#4285);\n- for any other error (#4285), the code-defined constructor name (an\n  identifier ending in `Error` or `Exception`; never the settable `name`),\n  an `AbortError`/`TimeoutError` name, a network `code` from a closed list\n  (`ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`, `EAI_AGAIN`,\n  `UND_ERR_*`, TLS certificate codes, ...) read from the error, up to three\n  `cause` levels and an `AggregateError`'s entries, and a structured numeric\n  status. A timeout or abort is named as one, except that a structured HTTP\n  status always wins over an abort name or network timeout code on a non-SDK\n  error, whether on the error itself or in its cause chain. An SDK error's\n  abort is read only from its code or exact transport message.\n\nFor example: `provider rejected the response schema (HTTP 400, code API_ERROR);\nunsupported response-schema keywords: uniqueItems`,\n`provider response incomplete (finish reason length)`,\n`provider call failed (class TypeError, network ECONNREFUSED)`,\n`provider call aborted or timed out (class DOMException, name TimeoutError)`, or\n`provider call failed (class Error)`. It is cut at 500 characters.\n\n**Why some failures were a bare `provider call failed` (#4285).** The SDK\nadapter's own response checks threw plain `Error`s (finish reason not `stop`,\ne.g. `length` when the reply reached `maxTokens`; truncation; tool calls; an\nunexpected response model; non-text or oversized content) and `JSON.parse`\nthrew a `SyntaxError` for an empty or non-JSON reply. The reason deliberately\nreads nothing from a non-SDK error, so all of these collapsed into the fixed\nphrase. Transport failures through the OpenAI SDK already carried\n`code API_ERROR`. The adapter now raises `ProposalResponseError` with a fixed\nproblem, and other non-SDK errors contribute the transport facts above. The\ncategory is unchanged (`unavailable`).\n\n### Failed-attempt capture (opt-in, #4285)\n\nThe value-free reason cannot show what the model actually sent. A host that\nneeds that for diagnosis can opt in to keeping it:\n\n```ts\nproposals: {\n  // ...\n  failureCapture: {\n    enabled: true,      // required; absent or false keeps capture off\n    maxBytes: 16384,    // default 16384, at most 65536 (UTF-8 bytes, after redaction)\n    redact: ({ text, source }) => hostRedaction(text), // required to retain text\n  },\n},\n```\n\n`ProposalConfiguration.failureCapture` is **off by default**. When enabled with\na host `redact` hook, a failed interpretation attempt (`provider_error`) keeps\none of:\n\n- `raw_response`: the reply text the SDK adapter refused (for example invalid\n  JSON or a `length` finish), or\n- `generated_output`: the generator's parsed output, as JSON, that failed\n  validation, the declared-completion check or the output limit.\n\nErrors without model output (transport, timeouts, authority, decision\nfailures) capture nothing. Successful attempts never store a capture.\n\nWithout a `redact` hook, only `status: 'redaction_failed'` metadata is stored,\nwith `redacted: false` and no text; the candidate text is not materialized.\nThere is no built-in sanitizer. Hosts own the hook's semantic redaction policy;\nthe service cannot verify that the returned text removes every document secret.\n\nThe text, cut to the larger of the generation `maxOutputBytes` and\n`maxBytes`, goes through the host `redact` hook, and the result is cut to\n`maxBytes` without splitting a character (`truncated: true` when either cut\napplied). NUL and unpaired surrogates are stored as U+FFFD so PostgreSQL JSON accepts the record. When\nthe hook throws, returns a non-string or exceeds its asynchronous wait budget,\nonly `status: 'redaction_failed'` is stored. The budget is the generation\n`timeoutMs`, cut to half of the analysis lease still left when the hook starts\n(no time left: the hook is not called). The hook runs after the authority\nrecheck, reserving the rest of the lease for the second recheck and publication.\nThis timer cannot preempt synchronous work or cancel the hook. Hosts must use\nbounded, nonblocking redactors. Missing or failed redaction does not replace the\nattempt's real failure or value-free reason; hook errors are discarded.\n\n**Where it lives.** In the attempt row's `data` JSON, as `failureCapture`\nbeside the result fields, never inside `result`: it needs no migration, is not\npart of `output_digest` or any configuration digest, never appears in\n`getCompletedAnalysis` or any other snapshot, and is not public read\nconfiguration (`proposalReadConfiguration` omits it, so read-only hosts still\nmatch). Proposal digests, replay and frozen generation configuration are\nunchanged by enabling it.\n\n**Reading it back.** Only\n`IngestionService.getFailedAttemptCapture(itemId, attemptId?)` returns it\n(`FailedAttemptCapture` from `/dto`, or `null` when nothing was stored). The\nattempt defaults to the item's current analysis attempt. It requires the\nexecution catalog and the current **reviewer** authority for that item (the\nsame gate as `getItemDisposition`) inside the caller's tenant and confidential\nscope; every denial, expiry, cancellation or foreign item fails closed before\nthe row is read. It is never part of a list DTO, inbox row, review page,\nlog line, checkpoint name, telemetry or error message.\nPublication and reads also reject a persisted `captured` record with\n`redacted: false`; capture text must be marked as processed by a configured\nhost hook. Persisted caps must remain within 1–65536 bytes, and captured text\nmust fit its declared UTF-8 byte cap; malformed records fail closed.\n\n**Retention and deletion.** It follows the item. There is no separate delete\nAPI: `expire`, `sweepRetention` and the `repairDeletions` retry of an\ninterrupted propagation all empty attempt `data`, which removes the capture\nwith the rest of the payload; a revoked item is unreadable before that.\n\n`createSDKProposalDecisionClient(client)` adapts an existing SDK client’s optional\ncapability without changing its errors or protocol. Optional `decision` uses public core `executeDecision` and the existing SDK\npredicate, choice, score and batch contracts. Supported-effect predicates,\nhandler classification, candidate entity matching, and action ambiguity/risk\nare distinct questions. Their validated probabilities and provenance are stored\nseparately from generative provenance and unknown OCR certainty. The complete\nserialized decision request, including suggestions and questions, must fit the\nminimum configured/current policy byte ceiling before capability probing and\nagain before deciding. A policy change between these boundaries fails closed.\nActually incomplete extraction always requires review. Unknown provider\ncompletion metadata is preserved as `source_completion_unknown`; it does not\nblock otherwise schema-valid **human** preview or imply completeness. Automatic\naction eligibility remains false. An unconfigured decision path\nis recorded explicitly. Configured errors produce a durable safe failure outcome;\nthey never silently switch to a generative decision fallback.\n\n### Decision readiness gate (#4209)\n\nFor every suggestion `i` the request asks `supported_i` (predicate),\n`route_i` (choice over the offered `handlerId@version` keys plus `none`),\n`risk_i` (ordered score over `clear`, `uncertain`, `ambiguous`) and one\n`entity_i_<field>` choice per candidate-reference argument. The validated\nanswers are always persisted under `provenance.decision.answers`. With the\ndefault `decisionReadiness: 'gate'` they are read as follows, and any failing\ncheck sets the suggestion to `needs_review` (a tie also sets the outcome to\n`ambiguous`):\n\n- `supported.probability >= minimumDecisionProbability` (default `0.8`).\n- `route.choice` equals the suggestion's own `handlerId@handlerVersion`,\n  `route.confidence >= minimumDecisionProbability`, and the gap between the two\n  largest route probabilities is greater than `tieMargin` (default `0.1`).\n- `risk.score < 1`: only the `clear` level passes; `uncertain` and `ambiguous`\n  require review.\n- Each entity match chooses the suggested candidate's key with confidence at or\n  above the threshold and a gap above `tieMargin`.\n\nThese values are provider outputs read as if they were calibrated\nprobabilities; nothing in this package calibrates them for this use. The\nteamworks-os measurement in #4209 (self-hosted Laya `typed-decisions`) found no\nseparation between right and wrong suggestions: a correctly read vendor invoice\nscored `supported` 0.37, garbage input 0.45–0.50, a wrongly proposed purchase\norder 0.51, route confidence 0.003–0.15 and `risk` ≥ 0.94, so the gate sent\nevery suggestion to review. Until a labelled sample shows separation, treat the\nanswers as diagnostics and configure:\n\n- `decisionMaxLen`: positive integer forwarded unchanged as the per-request\n  `maxLen` of the decision client (the SDK Laya provider's token window; the\n  checkpoint default is 1024 and the serialized evidence plus suggestions is\n  otherwise truncated). Other clients ignore it.\n- `decisionReadiness: 'record'`: the decision still runs, is bounded and\n  authorized exactly as before and its answers, usage, `readiness` and `maxLen`\n  are recorded, but the gate never changes `outcome` or `disposition`; readiness\n  comes from the validator alone (`missingFields`, outcome, source completeness).\n  A client error or timeout is recorded as the `decision_unavailable`\n  warning. A reply that comes back and then fails the core `executeDecision`\n  identity or answer-shape check is recorded as `decision_malformed` with the\n  reply's usage; this is the path for injected `DecisionClient`s. SDK clients,\n  including the Laya provider behind `createSDKProposalDecisionClient`,\n  validate the reply's shape inside `client.decide` and throw, so a malformed\n  SDK reply is recorded as `decision_unavailable` with no usage. Every case\n  records the `provenance.decision` identity. The generated suggestions stay\n  as they were. The serialized request exceeding the byte budget is a\n  configuration failure, not a provider answer: it ends the attempt as `limit`\n  in both modes, and in `gate` mode every failure above still ends the attempt\n  as `provider_error`. Lease, catalog, policy and provider-allowlist revocation\n  fail closed in both modes.\n\nSuccessful output also records `provenance.decision.readiness` (`'gate'` or\n`'record'`) and `maxLen` when set; configuration digests are unchanged, but\npersisted output is therefore not byte-identical to earlier releases.\n\nBoth settings are public configuration: they are part of\n`ProposalReadConfiguration`, the frozen `GenerationStageConfiguration.proposals`\n(present only when set, so existing digests are unchanged) and the completed\nsnapshot authority check. Invalid values fail at proposal service construction.\nNeither mode affects automation: `automaticActionEligible` stays `false`, and\n`authorizeAutomatic` reads only the host's `evaluateAutomatic` callback and\npolicy, never these answers.\n\nOutput records zero, one or multiple suggestions, alternatives, missing fields,\nsource links, proposed splits, versions, allowlisted usage, warnings and explicit\n`unknown`, `ambiguous`, `no_action`, `needs_review` or `provider_error` outcomes.\n`automaticActionEligible` is always false. Provider input/output and the complete\nserialized persisted envelope are bounded by configuration, live policy and the\nreceipt ceiling. Oversized output becomes a bounded review/limit result; when\nno safe envelope fits, the owning service records fixed `failAnalysis` metadata\noutside the provider payload budget without retaining provider output.\n\n## Explicit preview and stable intentions\n\nThe host chooses persisted suggestion indexes and calls:\n\n```ts\nawait service.previewGeneratedProposals({\n  itemId,\n  attemptId: generationAttemptId,\n  selections: [{\n    index: 0,\n    intentionKey: 'document:meeting-2026-10-09',\n    expectedRevision: 0,\n    requestId: 'review-request-1',\n  }],\n});\n```\n\n`intentionKey` is the host's stable business-intention identity across generation\nrevisions. Never derive a fresh key from model output, suggestion order or a retry.\nSelections must reference current persisted validated `ready_for_review` or\n`needs_review` output (#4208); a `provider_error` attempt, an unoffered handler or\na non-interpretation stage is rejected. A `needs_review` suggestion whose\n`missingFields` are still absent fails the handler schema inside the ordinary\npreview (`HandlerArgumentsInvalidError`, `Invalid handler payload`, whose\nvalue-free `issues` name the missing schema fields, for example\n`{ path: '/title', keyword: 'required' }`; see REVIEW.md) and publishes\nnothing; the reviewer supplies\nthe missing values through the explicit human path (`previewProposal` /\n`previewPlan`, as the published review host does for `preview({args})`), and the\nhandler's `validate` and `preview` run again on the completed arguments.\nEach batch requires distinct suggestion indexes and intention keys; duplicate\nindexes are rejected before any operation or plan preview is written.\nThe service rechecks current catalog/schema/target/source provenance, then calls\nthe existing operation or plan preview. Each result still requires the ordinary\nhuman review and execution APIs. Reprocessing creates no new business identity;\nsuccessful-action replay protection stays with execution.\n\n## Evidence and limits\n\nThe test matrix is `docs/test-matrix/3673-ingestion-proposals.md`. SQLite and real\nPostgreSQL suites exercise authority, revisions, abstention, hostile output,\ncompound proposals, split provenance and reviewed domain effects. The upload\nreference composes authenticated multipart delivery of a generated embedded-text\nPDF through the actual packaged PDF child, durable interpretation, and the existing\nordered ContentDocument draft/retained-asset plan. It checks duplicate delivery,\nunauthenticated and foreign-tenant denial, explicit approval of both steps,\nidempotent execution replay, page provenance, and unchanged original bytes.\nThe compound-email case uses a declared messages-owner snapshot fixture.\n\nLocal HTTP fixtures execute the actual AI SDK transport and cancellation contract.\nGenerative responses and the separate injected PDF split boundaries establish\ndeterministic orchestration, not model accuracy or OCR quality. No held-out routing\nevaluation or automatic approval is claimed. Missing/unknown AI completion remains\nexplicit under [SDK #1381](https://github.com/happyvertical/sdk/issues/1381).\n\nProposal limits are checked at `IngestionService` construction: positive safe\nintegers, at most 20 handlers/candidates/suggestions and 2147483647 ms timeout.\nInterpretation output uses the exported `GenerationAnalysisOutput` wrapper at\n`analysis.result.output.proposals`; the published review host unwraps it.\nAn explicit feedback `retrieve` denial omits optional examples and feedback\nprovenance and continues generation. Item/execution denials, unexpected failures,\nand revocation after examples were selected still fail closed before disclosure.\n"
     },
     {
       "path": "FEEDBACK.md",
@@ -1730,7 +1730,7 @@
     {
       "path": "REVIEW.md",
       "module": "REVIEW",
-      "content": "# Authenticated review surfaces\n\n`@happyvertical/smrt-ingestion/svelte` exports `IntakeInbox`, `IntakeReview`,\n`IntakeWorkspace` and `EvidenceViewer`. The browser-safe DTO entry exports their `IntakeReviewHost`\ncallback contract. Import styling/theme configuration from smrt-ui in the host.\nComponents use smrt-ui primitives and the `ingestion.*` i18n catalog.\nExisting `IntakeInbox` hosts now keep the previous rows visible, with their\ncontrols disabled, while a refresh or filter change loads; any failed read\n(Load more included) still clears them.\n\nThe host authenticates every request, resolves tenant/actor/confidential scope\nfrom its session, enforces CSRF on mutations, and constructs `IngestionService`.\nNever accept scope, reviewer, permissions or a principal from callback JSON.\nOnly supply authorized evidence URLs and escaped text; original URLs are\nsame-origin authenticated handlers that recheck `readEvidence` on every read.\nCandidate discovery uses `findCandidates` with current grants. Presentation\nstate and disabled buttons provide no server authority.\n\n`listReviews(itemId, {cursor?,limit?})` reloads saved action identities and their\ncurrent plan membership without browser storage. It returns at most 50 actions,\nwith an opaque action-ID cursor. Every payload requires current item, handler,\nparent plan and target access under the owning transaction. Denied reads fail\nclosed. Target reads check current authorization separately from historical\nrevision freshness: unfinished drift returns state-only stale reviews without\nremoving unrelated entries; succeeded results remain readable after authorized\ntarget changes. Apply still enforces exact bound target revisions. Expired entries\ncontain only review identity/state. Stale entries never disclose old args or target\nlabels; an authorized parent plan additionally exposes `stalePlan` identity, key,\ncurrent plan revision and handler identity. Hosts must collect fresh explicit args\nfrom the reviewer/current authorized evidence and call `previewPlan` with that\nexact plan CAS and the current completed analysis attempt. Action revision is not\nplan revision. Re-expansion preserves action identity and requires fresh approval.\nSuccess results are rechecked through the durable result reader.\nPlan membership contains the exact parent args/version so edits call\n`previewPlan`, not per-step correction. An item may have more review pages; the\nhost must aggregate state across pages when projecting a production inbox state.\n\nA `needs_review` suggestion is completable, not only rejectable (#4208). That\nincludes a suggestion kept because its arguments missed only required fields\n(#4284); nested misses appear as JSON Pointers such as `/vendor/name`. The\ncomponent shows its `missingFields`, an editable `Suggested arguments (JSON)`\ndraft prefilled from the generated arguments, and the candidate picker for\ndeclared candidate fields; Prepare review stays disabled while required fields\nare still missing from an unchanged draft. An unchanged draft previews the\ngenerated snapshot as before; an edited draft is sent as `preview({..., args})`,\nwhich the published host publishes through the ordinary `previewProposal` /\n`previewPlan` with the same `ui:<index>` intention, never by rewriting the\ngeneration. The handler validates the human arguments again before a\n`waiting_review` action exists, approval remains a separate explicit decision,\n`ActionReview` lists top-level required arguments missing from the current\ndraft while editing (nested misses named by JSON Pointer in `missingFields` are\nnot re-checked in the browser; the server's revalidation refuses them and the\ncomponent shows that inline as `HandlerArgumentsInvalidError`), and no authority or automation eligibility is added: a failed attempt,\nan unoffered handler or a foreign stage is still refused by the host.\n`preview` throws on every failure, as before. When the handler's argument\nschema or `validate` refused the arguments being previewed (operation preview,\nwhich also carries corrections, a reviewer-started action, or plan preview),\nthe server throws `HandlerArgumentsInvalidError` (`name` set, messages\nunchanged). An argument-schema refusal also carries `issues`: a frozen list of\nat most `HANDLER_ARGUMENT_ISSUE_LIMIT` (20) `{ path, keyword? }` entries\n(`HandlerArgumentIssue`). `path` is built only from schema-declared property\nnames, `required` names and real array indexes and is cut at\n`HANDLER_ARGUMENT_PATH_LIMIT` (160)\ncharacters (never splitting a `~0`/`~1` escape). Segments are escaped per RFC\n6901 (`~` as `~0`, `/` as `~1`), with two departures: `/` is the whole\narguments object (never a key `\"\"`), and `?` stands for a data-named key. A\n`required` refusal appends the missing schema name to the parent's path. The\nformat relates to a suggestion's `missingFields` as follows: a root path\n`/name` is the bare `missingFields` entry `name` (unescaped), and a nested\nentry is the same escaped pointer in both (for example `/vendor/a~1b~0c`).\nThe bundled view shows a root issue without its leading `/`, so its refused\nfields read like the missing-information list. `ProposalValidationError`\nreasons share the schema-owned segment rule but stay unescaped.\n`keyword` is the failing schema keyword. Argument values, Ajv\n`params`/messages and handler messages are never included. A `validate`\nrefusal has no `issues` (the handler contract returns only `ok`). The size and\nshape preconditions checked before the schema runs (arguments over the policy\nbyte limit, or a handler schema that is not a closed `type: 'object'` with\n`additionalProperties: false`) stay a plain `Error`: they fail closed as a\ndenial, never as the inline refusal. Apply-time and\nexternal-send revalidation and result-schema checks keep a plain `Error`. The component shows an inline message and\nkeeps the view and draft when `preview` either rejects with an error whose\n`name` is `HandlerArgumentsInvalidError` or resolves `{ rejected: 'invalid' }`\n(`PreviewRejection`, optionally with the same `issues`). A transport that\ncrosses a process boundary preserves the inline UX by keeping that name and\n`issues` (for example re-throwing an `Error` with\n`name = 'HandlerArgumentsInvalidError'` in the browser callback) or by\nreturning `{ rejected: 'invalid', issues? }` for that case only, as the\nmaintained fixture's `previewForReview` and `startActionForReview` do. Since\n#4281 the fixture's rejection body also carries `issues` when the schema\nrefused; read `rejected === 'invalid'` rather than comparing the whole body\nwith strict equality. Without either, the refusal behaves like\nany other failure: the view is cleared exactly as before this change, and the\nreviewer's in-memory draft returns after an authorized refresh. Every other\nthrown preview or candidate-search failure (denied, revoked, unavailable or\nunknown) clears the view.\nUnsent drafts live only in component memory, keyed by attempt and suggestion\nindex. They survive Refresh, a failed callback, an action on another card and a\ntransient `unavailable`/`stale` reload; a `revoked` or `expired` result\ndiscards them, a successful preview clears that card's draft, and an available\nreload drops drafts for attempts or cards no longer offered.\n\nThe host's `load` callback supplies a current `ItemReviewView`, using\n`getCompletedAnalysis` with no historical fallback. Generated suggestions bind\nthe **current generation attempt**, not `generation.source.attemptId` (the prior\nextraction). `previewGeneratedProposals` publishes exact reviews and continues to reject stale\ngeneration candidate pins. When `listReviews` reports `generationStale`, the host\nomits obsolete generation output and renders authorized saved reviews/results.\nCompleted saved actions do not hide healthy unprepared suggestions. The saved-binding hint is not\nan authoritative generation-availability check: a fresh human preview can bind a\ncurrent target while the immutable generation still pins its former revision.\n`getCompletedAnalysis` remains strict and throws server-only\n`GenerationSnapshotStaleError` only after every current catalog/provider/candidate\nread is authorized and an immutable candidate revision differs. The maintained\nhost catches only that class, reacquires `listReviews` under current owning\nauthority, and returns that new page without generation output. It never reuses\nthe earlier page after an error. Denials and unknown failures propagate; healthy\ngeneration still exposes unprepared sibling suggestions. Stale entries expose handler\nand attempt identity only when that attempt is still the current completed/partial\nanalysis. An empty-args editor submits fresh explicit human arguments through\n`previewProposal` or `previewPlan` with the saved CAS; it never reuses old generated\narguments, rewrites the generation snapshot or transfers approval. Analysis-stale\nentries without an attempt require normal reprocessing. Approve,\nreject, defer and correct call `submitDecision`; corrected args create a new\nrevision which requires a separate human approval. After an approve/defer/reject\ndecision, optional `editAction` calls `previewProposal` with the current action\nrevision to publish a new review; completed/executing/unknown actions cannot be\nrevised. Local dirty args disable Apply but confer no authority. Plan edits re-expand through\n`previewPlan` with the current **plan** revision. `applyAction` accepts only an\naction ID. Unknown external outcomes require server reconciliation; the UI\nnever offers a blind resend. Stable result IDs survive reload and retry.\n\nReplace `contextKey` whenever authenticated tenant/session context changes.\nChanging it or itemId destroys the old view and fences late callback results.\nDenied refresh clears prior originals, candidates, arguments and results.\nMissing confidence is unavailable; page/time links exist only for observed\nlocations. Provider errors and unresolved/partial results remain review states.\n\n## Submitter-scoped decisions\n\nFor trusted internal sources the person who submitted an item may confirm or\ndecline their own proposal without the reviewer inbox. `listOwnProposals`\nreturns only items whose server-recorded `submitter_id` equals the current\nauthenticated actor, each with its bounded saved review page reloaded under\ncurrent item, handler and target authority. An item the actor can no longer\nread (the host `authorize` returns false or throws `IntakeAccessDeniedError`)\nis skipped before projection: the page is filled from readable items only, in\n50-row batches, and `nextCursor` names the last emitted item and is present\nonly when a further readable item was actually found. Neither the entries, the\npage size nor the cursor reveal a hidden item. If one call has to skip 1000\nhidden submissions it fails with `Own proposal scan limit` rather than return a\nshort page or a cursor that stops inside the hidden run; this error is the only\nsignal, and it says only that such a run exists. Any other `authorize` error\npropagates instead of shrinking the list. An item that is still readable but\nwhose reviews are denied is returned as `{ item, reviews: null, unavailable:\ntrue }`: that covers ingestion's own denials and any throw from the host\n`assertTarget` (deleted or revoked targets), whose text is never returned.\nIntegrity, validation and database errors from ingestion itself propagate. The\nreviewer `listReviews` surface keeps propagating host target errors unchanged.\n`submitOwnDecision` takes the same `ReviewInput` CAS fields and request ID as\n`submitDecision` and accepts `approve`, `reject` and `defer` only; `correct`\nbelongs to the reviewer surface. It runs under the `review_own` execution\noperation: the host's `authorize` must return `submitter: true`, the resolved\npolicy must have `submitterReview` enabled, and the recorded submitter must be\nthe current actor and also the receipt's captured execution principal (the\nidentity the effect runs as), checked under the item lock and again at apply.\nA receipt captured for a bot or service principal is never self-approvable. Policy enablement, handler/operation allowlists, captured\nceiling, confidential access, retention and the first-valid-decision lock are\nunchanged. The decision is a human decision by that actor, recorded with\n`mode: 'review_own'`; reviewer decisions carry `mode: 'review'`. In both modes\n`selfDecision` is true exactly when the deciding actor is the item's\nsubmitter, so a reviewer approving their own submission is never independent\nreview. A self-decision is not a reviewer judgment: it never feeds\nautomation eligibility (machine authorization remains the separate evaluated\n`kind: 'machine'` path) and its feedback events carry the same marker. The\n`unavailable` entry discloses nothing about the denied handler or target.\n`applyAction` then runs once under the approver's live grants exactly as\nfor reviewer decisions. Hosts render this surface from their own authenticated\nsession; presentation state confers no authority, and a source payload cannot\nnominate a submitter.\n\n## Assignment and logical splits\n\nAssignment is explicitly host-owned, durable and versioned. `assign` receives\nan expected assignment version and request ID; the host must authorize the\nmanager, constrain eligible assignees, CAS the durable record and reject stale\nwrites. Assignment does not grant read, review or execution rights. The maintained\nfixture provisions its own SQLite assignment table before serving requests; no\nproduction ingestion table or migration is introduced for assignment.\n\n`reviseLogicalSplit` authorizes the current generation through the same-executor\ncatalog/candidate gate and the existing reviewer grant and policy reviewer list.\nProcess access alone cannot mint or replay a human correction; reviewer authority\nis checked before mutation and again before publication. A generation without a\nreviewable catalogue cannot be corrected through this reviewer API.\nIt requires all observed pages exactly once, an exact\ncurrent attempt/revision and a request ID. It records the authenticated actor\nand predecessor as a **human correction** in a new immutable extraction\nconfiguration, queues re-extraction and immediately makes previous suggestions\nand approvals stale. It never changes original bytes/evidence or labels a human\nedit as model output. The host processes the new extraction, then calls\n`prepareGeneration` and the normal fenced interpretation stage. The supported\nimmediate-predecessor extraction pin is unchanged. The generator receives a\nhuman correction only after its digest matches the authoritative source. Ordinary\n`analyze` calls cannot mint an extraction correction; the owning split API is the\nauthenticated origin, and forged interpretation corrections fail before provider\ndisclosure. If its proposed grouping differs from the correction, suggestions are withheld\nwith `human_split_not_respected`. New proposals require new explicit review.\nThe reference host runs these stages synchronously for browser determinism;\nproduction hosts dispatch the existing durable analysis jobs.\n\n## Reviewer instructions\n\n`recordReviewerInstruction({itemId, attemptId, expectedRevision, text,\nrequestId})` records a plain-text instruction for one item (\"This is a customer\nPO from Badger; file it, do not bill it\") as the second kind of **human\ncorrection**. It is authorized exactly like `reviseLogicalSplit`: the current\ngeneration must pass the same-executor catalog/candidate gate and the reviewer\ngrant plus policy reviewer list, and authority is checked before mutation and\nagain before publication. Process access, `analyze`, and a client payload cannot\nmint one: `analyze` rejects a `reviewerInstruction` key on an extraction\nconfiguration, and an interpretation copy that differs from the pinned\nextraction's record fails with `Generation evidence changed` before provider\ndisclosure. Text is required, trimmed-nonempty and at most 4,000 characters.\n\nThe record is immutable: `{id, text, actorId, recordedAt, supersedesId, digest}`\nplus the request binding, written into a new extraction configuration beside\nany existing split correction. Recording supersedes current suggestions and\napprovals, queues the normal fenced re-extraction and interpretation through the\nexisting dispatch path, and returns immediately; the reviewer keeps working\nwhile the item reports `processing`. `prepareGeneration` copies the instruction\ninto the interpretation configuration, the generator receives it only after its\ndigest matches the authoritative extraction record, and saved generation\nprovenance records `reviewerInstruction: {id, digest}`. A later instruction\nrecords `supersedesId` and replaces the earlier one for future interpretations;\n`listReviewerInstructions(itemId)` returns the full history, newest first, and\nhistory is never deleted. The instruction steers the model only: it cannot add\nhandlers, candidates, schemas, permissions or automation eligibility, replies\nare validated as usual, and suggestions still require explicit preview and\napproval. A replay with the same request ID returns the same revision; a changed\ntext under the same request ID conflicts.\n\n**Cost.** Each recorded instruction appends a new extraction revision, so the\nitem is extracted again before it is interpreted again: cheap for embedded-text\nPDFs and plain text, but OCR/speech hosts spend provider budget per instruction,\nexactly as they do per split correction. The pinned extraction is not reused\nbecause the interpretation contract requires its source to be the immediately\npreceding revision and `getCompletedAnalysis(itemId, attemptId)` serves only\nthe current revision (PROPOSALS.md, \"Durable stages\"); reusing it would mean\nweakening that predecessor pin, which protects every generation from an\nintervening reprocess, so this feature follows the split path instead.\n\n**State and failure.** An in-flight stage (queued/running) reports the item as\n`processing` even when earlier, now-stale actions exist. If the re-extraction or\ninterpretation fails, `getReinterpretationState(itemId)` returns the latest\nattempt's safe failure category and the latest completed generation attempt;\nthe host projects them as `instruction.failure` and `instruction.binding`, and\n`recordReviewerInstruction` accepts that historical attempt as its anchor when\n`expectedRevision` is the item's current (failed) revision and no later\n**interpretation** completed and nothing is queued or running, so the reviewer\ncan retry or change the instruction after either stage fails. A completed\nextraction whose own interpretation failed belongs to the failed attempt, not a\nnewer result; a completed extraction whose interpretation has **not been\nappended yet** is in flight (the host is between stages) and is refused with\n`ReviewerInstructionStaleError` (`Stale reviewer instruction`), so a second\nreviewer cannot pre-empt it. That gap expires: once the extraction attempt's\ncompletion plus the item's analysis lease duration (`limits.leaseMs`, the lease\n`claimAnalysis` grants) has passed with no interpretation appended,\n`getReinterpretationState` reports `failure: 'not_started'` with the retry\nbinding and the guard allows the retry. `not_started` means **the\ninterpretation did not start within the lease window**: the host crashed,\nthrew between `prepareGeneration` and `analyze`, or its queue is merely slow.\nPre-empting a slow but healthy host is safe because `analyze` refuses an\ninterpretation whose pinned extraction is no longer the item's latest, under\nthe item lock and before anything is superseded\n(`GenerationSourceStaleError`, nothing appended): the slow host's late append\ncannot clobber the retry. Missing or malformed timing (no attempt, no\n`completedAt`, non-finite `leaseMs`) counts as already expired rather than\nholding retries forever. The \"still being re-read\" note shown after a stale\nresult is cleared by the next reload that shows the item settled; the draft\nthen carries a persistent \"This item changed while you were writing; your\ninstruction was not recorded.\" note (any stale cause: another reinterpretation,\na split, or a host reprocess) until the reviewer edits or resubmits it. The guard and\n`getReinterpretationState` share one predicate, and the latter's\n`reinterpreting` flag (projected as `instruction.reinterpreting`) is true in\nthe gap too, so the component keeps polling and keeps Re-read disabled there.\nThe published host maps two typed errors to `instruct` results:\n`ReviewerInstructionStaleError` → `{ stale: true }` (refresh-and-retry: reload\nwith a note, draft kept) and `ReviewerInstructionInvalidError` → `{ invalid:\ntrue }` (empty, whitespace-only or over 4,000 characters: shown inline, draft\nkept). Neither is a denial. Custom hosts should map them the same way; a host\nthat lets either propagate as a thrown error makes the component treat it like\nany other failed mutation, i.e. a whole-view deny with the \"view unavailable\"\nmessage, as before these results existed. The maintained fixture's\n`/api/instruct` now answers an invalid text with HTTP 200 `{ invalid: true }`\ninstead of 409. A retry from an older anchor builds on the **whole configuration**\nof the newest extraction after it (replacing only the instruction), because that\nis the item's current configuration: corrections chain forward through it and a\nhost reprocess replaces it. So a split followed by a failed stage is never\nsilently dropped, and a failed reprocess's changed configuration is neither\nreverted nor overlaid with a split it dropped. **Concurrency.** `recordReviewerInstruction` and `reviseLogicalSplit` each\nrun their whole decision in one transaction under the item row lock: the\nanchor snapshot read takes the lock first, the execution authorization of\nthat snapshot takes it again (`UPDATE intake_items` row lock), the guard step\nre-asserts it explicitly, and\nthe request-key replay check, the revision and later-work guards, the\ncarried-forward split, the history read that sets `supersedesId`, and the\nappend all run under it. On PostgreSQL a second reviewer at the same revision\nblocks on that lock and is then refused (`ReviewerInstructionStaleError` /\n`Stale logical split`), so the ledger cannot fork; an instruction racing a\nsplit (in either order) is refused rather than built from the pre-split\nconfiguration; and a double-click whose duplicate commits after the unlocked\nreplay check is answered as a replay of the committed request, not a conflict\nor a denial.\n\n**Host reprocess.** A host reprocess (a plain `analyze()` extraction the host\nconfigures itself) cannot carry human corrections — `analyze` rejects\n`humanCorrection`/`reviewerInstruction` on extraction configurations — so it\ndrops the split and the instruction alike, and neither is applied to its\ninterpretations. The instruction is then reported as `dropped`, not pending:\n`getReinterpretationState().instructionInEffect` names the instruction the\nnewest extraction carries (verified by digest) and is null after such a\nreprocess. History is unchanged; the reviewer can re-record the instruction,\nwhich supersedes the dropped one.\n\n`ItemReviewView.instruction` exposes `current` (the latest recorded instruction\nstill in effect, i.e. carried by the newest extraction), optional `dropped`\n(the latest recorded instruction a reprocess dropped), `applied` (the\ninstruction the displayed **generation** ran under; a completed extraction alone\napplies nothing), `stale` (the displayed suggestions predate the current\ninstruction), optional `failure` and optional `binding`. Feedback examples that carry instruction\ntext count it toward the feedback byte budget (FEEDBACK.md). The optional host callback\n`IntakeReviewHost.instruct` is implemented by the published adapter when the\nservice supports it, with an optional `onInstruct(itemId, revision)` wakeup\nmirroring `onSplit`. The review component renders \"Instructions for the\nassistant\" with \"Re-read with these instructions\", shows \"Reinterpreting…\" while\nthe item's stage is queued/running, repeats the existing authenticated `load`\non `pollMs` (default 2 s, backing off to 5×) and patches the view in place —\ndrafts, split edits, focus and the evidence viewer survive and no loading\nplaceholder is shown — stops when the stage is no longer in flight, and then\nshows the instruction that produced the current suggestions, marking a\nsuperseded one as stale. An explicit host denial on a poll tick fails closed at\nonce; a thrown tick is treated as transient (view and drafts kept, a\n\"Couldn't refresh; retrying.\" note, backoff continues), but because hosts may\nalso throw for revoked access, three consecutive thrown ticks fail closed.\n**Hosts must signal revocation by returning `availability: 'revoked'`** (or\nanother non-`available` state) from `load`, not by throwing: a returned denial\nclears the view on that tick, while a host that throws on revocation leaves the\nalready-displayed content visible until the third thrown tick (about 10 s at the\ndefault interval and backoff) before the view fails closed.\nSplit drafts survive a refresh only when the reviewer edited them. A failed stage shows its safe category with the form\nstill available. There is no\nstreaming channel; status is read through the existing item/analysis APIs. The\nmaintained fixture records the instruction durably and then runs the stages in\nthe background so the browser proof exercises the in-place update.\n\n`feedback` is an optional explicit correctness callback, separate from approval\nchoice and execution success. No learning, feedback storage or rule promotion is\nimplemented by these components; #3676 owns those services. Do not pass feedback\nor a feedback callback to readers without the relevant host grant.\n\n## Reviewer-chosen actions and \"handled, no action\"\n\nA reviewer is not limited to model suggestions. `ItemReviewView.catalog` carries\nthe handlers the item's catalog currently offers (`listHandlers`, discovery media\ntypes and live preview authority; it is presentation, never a grant). The optional\n`startAction` callback forwards `StartActionInput` (`itemId`, `handlerId@version`,\nexplicit `args`, `requestId`, optional `reason`) to `startReviewerAction`, which\nrequires the current reviewer grant under that handler, a completed or partial\nattempt on the current analysis revision, and an operation handler the item's\nevidence media types offer. Plan handlers go through `previewPlan`. The server\ncreates an action keyed `reviewer:<requestId>` with origin `reviewer-selected`\n(`createAction` refuses that key prefix and origin, so process authority cannot\nmint reviewer provenance; re-previewing such an action with `previewProposal`\nneeds the reviewer grant and keeps its handler fixed, so only its arguments can\nbe corrected),\nruns the handler's normal `validate`/`preview`, publishes a `waiting_review`\nrevision and requires the same explicit approval and apply as a generated\nproposal. The reviewer typed these arguments, so a handler argument-schema or\n`validate` refusal throws `HandlerArgumentsInvalidError` with the value-free\n`issues` described above, and the rolled-back transaction leaves no action row\n(#4281). Every other refusal (input shape, access, handler unavailable, item\nresolved, identity or request conflict, normalization mismatch) stays a plain\ndenial. `startAction` follows the `preview` contract: it throws, or a transport\nmay resolve `{ rejected: 'invalid', issues? }` for that one case. The component\nkeeps the start form, handler, arguments and reason, shows an inline refusal and\nlists any field paths; any other failure clears the view as before. Replays\nwith the same request return the same review; changed arguments or reason\nconflict. Such actions are never automation-eligible: `authorizeAutomatic`\nrefuses them regardless of policy opt-ins. The UI pre-fills arguments only from a\nsame-handler suggestion (for example a `needs_review` one) and a single original's\nevidence references, lists the required fields still missing, and submits exactly\nwhat the reviewer typed. An item whose current attempt failed outright must be\nreprocessed first; an interpretation that completed with `provider_error`,\n`unknown` or no suggestions can be acted on directly. `ReviewAction.origin`\nexposes the provenance so `ActionReview` can label human-started actions.\n\nThe optional `resolve` callback forwards `ResolveItemInput`\n(`disposition: 'resolve_no_action'`, `requestId`, optional `reason`) to\n`resolveItem`. It needs reviewer authority under any handler the item's captured\nceiling offers and refuses while an action is `authorized` with a live approval,\n`executing`, `outcome_unknown` or `succeeded`; waiting, deferred, rejected and\nfailed actions, and authorized ones whose approval expired, may remain (neither\nan exhausted failed action nor a lapsed approval can be rejected, so they must\nnot keep the queue open). Afterwards only reject remains: those actions can no\nlonger be approved, corrected, deferred, re-previewed, retried, applied or\nautomated. `submitDecision` refuses every decision but `reject`, no new revision\nis published for the item, `applyAction` rechecks the disposition before any\neffect, and `analyze`, `reviseLogicalSplit` and `createAction` refuse the item\nunder its lock before any write, so it is never reanalysed, re-split or given a\nnew action. `resolveItem` supersedes any queued or running analysis under the\nsame lock and `claimAnalysis` refuses a resolved item, so no provider is called\nafter a human closed it; the item's `processingState` keeps its last value (it\ndescribes analysis, not review), and the inbox state `resolved` is authoritative.\n`publishProposal` (process authority) refuses a resolved item and any\nreviewer-selected action. The UI hides Approve, Defer, Apply, every edit control, suggestion\npreview and split controls on a resolved item.\nResolved items hide the instruction editor and stop reinterpretation polling, even if an older processing projection is still queued. Recording an instruction cannot append a new revision after resolution.\n\nPaged lists project the resolved state and disposition time in the same bounded, scope-filtered query, so state filters and row controls agree with a full item reload.\n\nThe append-only `intake_dispositions` record is terminal: replaying the same\nrequest returns the same disposition, any other request conflicts, and\n`startReviewerAction` refuses the item. `IntakeItemDTO.disposition` projects only\n`{ state: 'resolved', at }` to any item reader (`listItems` reads it in the same\nstatement as the page); the reviewer and reason are returned only by\n`getItemDisposition`, which requires reviewer authority, and the review hosts put\nthem on `ItemReviewView.disposition` (omitted when that read is denied, so the\nview shows only \"Handled, no action\"). `loadReviewSummary` reports inbox state `resolved` unless an action\nactually succeeded. Privacy deletion and retention expiry redact the reason and\nreviewer (`intake_dispositions.data`) and keep only the kind. The disposition is\ndistinct from `reject`, which still means the proposal was wrong. Closing an item\nrecords `reviewer_routing` feedback immediately; a started action records it only\nwhen the reviewer approves it (see FEEDBACK.md). Capture is an optional projection\nthat never vetoes the decision or disposition.\n\n`startReviewerAction` applies the handler's discovery media types and the live\nreviewer grant/policy for that handler. It intentionally does not apply the\nproposal catalog's provider-policy filter or `maxHandlers` slice: those bound what\na model may be offered, and a human choosing a handler sends nothing to a\nprovider. The UI picker shows the offered catalog, so a handler hidden from it is\nonly reachable by a reviewer who already holds `review` authority for it. The maintained\nbrowser fixture serves both operations behind CSRF and the same session scope.\n\n## Single-page triage workspace\n\n`IntakeWorkspace` (#4215) composes the existing pieces so a reviewer works the\nwhole queue on one page: the paged inbox as a list pane, the review view of the\nselected item beside it (the original above its action form), and the\nreviewer-instruction message box of the item pane. Props: `host`, `contextKey`\n(replace on session change, as for the other components), optional initial\n`itemId`, `pollMs`, `rowAside` and `onselect(itemId | undefined)`, which only\nreports the selection (to keep a URL in step) and never navigates. It adds **no\nhost callback and no server authority**: every read is the host's `list` and\n`load`, every action still goes through the handler preview and an explicit\napproval and apply under the approver's live grants, and the message steers the\nmodel only, exactly as in `IntakeReview`.\n\n- **Inline original.** In the item pane `EvidenceViewer` shows one part at a\n  time (`layout=\"pager\"`), opening on the first part that renders inline (the\n  uploaded file rather than its capture record), with previous/next original.\n  A PDF with more than one *observed* page (extraction locations or proposed\n  page groups; `pages` prop) gets previous/next page, which reloads the frame\n  at the same-origin URL plus `#page=n`; only `evidenceUrl`-approved URLs ever\n  reach a frame. `IntakeReview` gets the same page navigation over its\n  unchanged stacked list of parts. The chosen part and page belong to the item\n  view (bindable `chosen`/`page`), so they survive in-place reloads, Prepare\n  review, Approve and Apply.\n- **Keyboard.** J/K and Alt+Down/Alt+Up move to the next/previous row (loading\n  the next page at the end), ignored while focus is in a text field, select or\n  editable region; \"Previous item\"/\"Next item\" buttons carry\n  `aria-keyshortcuts`. The selected row is `aria-current`, and every selection\n  moves focus to the item pane region, named by the row's label. A navigation\n  that waited for the next page is dropped if the reviewer chose another item\n  meanwhile.\n- **Unsent input.** The pane holds unsent input when it has instruction text,\n  an edited suggestion draft or split draft, a chosen start handler or start\n  reason, a no-action reason, or an action editor with edited arguments, a\n  reason or a feedback comment. It is read from the drafts themselves, so it\n  holds while a reload has cleared the view; while the view is denied nothing\n  is shown and nothing counts (the drafts stay in memory and return with an\n  authorized refresh, as before). A reviewer-initiated move (J/K, Alt+arrows,\n  Next/Previous item, a row's Review button) then asks inline, in a group\n  labelled by its note: \"Stay on this item\" takes focus and returns it to the\n  field the reviewer last used; \"Discard and open the other item\" proceeds.\n  When an item is closed without action (here or by another session), input a\n  closed item cannot take\n  (instruction, suggestion and split drafts, a started action, a no-action\n  reason) is discarded.\n- **Live state.** A row's status follows the item: \"Interpreting…\", \"Ready to\n  review\", \"Needs review\" with missing argument names or the generation\n  outcome, \"Awaiting approval\", \"Approved, not yet applied\", \"Failed\" with a\n  safe category, \"Handled, no action\", or the listed inbox state. Rows the\n  reviewer has not opened show the listed state only; reasons come from a\n  loaded view, never from server exception text. The open item's own polling\n  (`ReviewView`, unchanged backoff and three-failure fail-closed) reports each\n  displayed view and the workspace patches that row in place\n  (`InboxView.patch`, keeping the listed label and preview, and the row's\n  assignment unless the patch carries a newer assignment version, so a view\n  read before an assignment never rolls the row or the next expected version\n  back), so the row follows each newer read of the form and the list is\n  **not** re-listed per tick. An item the\n  reviewer leaves while its stage is in flight, or before the pane showed the\n  result of its last operation (an instruction just recorded), keeps\n  following: the workspace re-reads followed items with the same `load` (first\n  review page) on the pane's backoff, at most **5** reads per tick, one after\n  another, least recently read first (so every followed row is reached), with\n  only one tick running at a time. At most **20** items are followed; beyond\n  that the longest-followed one (the earliest started, whatever the read\n  rotation) stops. An item left while its pane was mid-operation (an Apply not\n  yet answered) keeps following while a read still shows an action authorized\n  or executing: exactly **3** more reads when it never answers, the fourth\n  ending the follow. That debt belongs to the operation, so it survives\n  reopening and leaving the item again until a view shows the operation\n  answered or the reads run out; leaving mid-operation again starts a full\n  debt for the new operation. Each follow has a\n  generation: an answer from an earlier follow of the same item (one asked\n  before the reviewer reopened or left it again) is dropped, and its failure\n  does not count toward the new follow's three. An item stops being followed\n  when it settles, its view is denied, three reads in a row throw, its row\n  leaves the displayed list (a filter or a refreshed page removed it), the\n  list fails closed, or the cap drops it; a denial, the failure stop or the\n  cap drops its cached status and restores its entry exactly as its page read\n  returned it (never a patched entry). Opening an item drops its cached\n  status until the pane shows a view; a denial in the open pane (a failed\n  action, the pane's own fail-closed poll, or a first load that failed) does\n  the same as a follow denial, clears the announcement, and the item is not\n  followed when left. A settled stage that was seen running is announced in a\n  polite status region (\"badger-po.pdf: Ready to review\"), only while its row\n  is displayed; a refreshed page or a failed list clears it.\n  Other rows update on Refresh, a filter change or when opened; there is no\n  streaming. While a refresh or \"Load more\" is pending, the displayed rows stay\n  (controls disabled) and keep taking patches. Every read (a page, a pane\n  view, including an unchanged poll, and a follow read) is numbered when its\n  request starts, and each row shows the entry of its newest read, whatever\n  the source: a page read before a pane or follow read never regresses the\n  row, and a page read after them replaces what they showed. The same rule\n  governs a follow: a follow read older than the row's newest read changes\n  no status, does not stop the follow and announces nothing (a newer read\n  settles it), so the announcement never contradicts the row. Cached status reasons follow the same ordering, even when entries have identical\n  fingerprints. \"Load more\" continues the\n  filter the rows were listed under, not filter inputs edited since, and does\n  not repeat a row already shown. A failed \"Load more\" fails closed like any\n  failed read (the host cannot tell a transient failure from a revoked\n  grant): the rows clear and the list shows its error.\n- **Approve and advance.** After an approve, apply or \"Handled, no action\" whose\n  reload left nothing for the reviewer (closed without action, or an action\n  succeeded and none is waiting for approval, waiting to be applied, executing,\n  unknown or failed; stale, rejected and deferred actions do not hold it), the\n  item's row is patched and leaves the list when it no longer matches the\n  listed state/assignee filter, and the next row that is not closed or\n  completed opens and takes focus, with no navigation and no re-listing. An\n  approval that leaves an apply step keeps the item open with Apply in place.\n  Unloaded saved-review pages and an active background stage also prevent\n  settlement. Advancing skips completed inbox pages until a reviewable row\n  appears; a page that makes no progress stops the walk.\n  It never advances over unsent input on the same item: the item stays open,\n  the input stays, and a note says it is finished but has unsent input; the\n  reviewer moves on explicitly, through the confirmation; input typed while\n  the next page loads counts too. When no open row is displayed, the advance\n  appends pages of finished rows until one has an open row or no page\n  remains, at most **5** appends. After each append, the advance (like\n  J/K at the end of the list) finds its place again by id: just after the\n  item it left, or, if that row has gone, at the first row that followed it\n  and is still listed, or at the first new row, so a row that left the list\n  meanwhile never shifts it onto the wrong item. Its notes (and \"nothing else\n  needs review\") are written into one persistent polite status region. The queue is never reported empty when\n  that is unknown: past the bound, or when an append cannot start (a refresh\n  is pending) or is superseded, the item stays open with a note to try Next\n  item again, which still works; when an append fails, the list has failed\n  closed (no rows, Next disabled), so the item stays open with a note to\n  refresh the list to continue. The open item stays listed while the\n  reviewer works on it even if its state stops matching the filter; it\n  leaves once they move on.\n  When nothing is left the pane says so. The per-row \"Handled, no action\"\n  control is hidden in the workspace (`resolveInRow={false}`) so closing always\n  goes through the item pane and advances.\n\n\n## Maintained browser proof\n\n`pnpm test:components` runs real Svelte component tests; `pnpm test:e2e` runs the\npackage-local authenticated Vite application under Chromium. The fixture uses\nHttpOnly same-site sessions, CSRF, real SQLite/assets/ingestion/content APIs,\nproduction unpdf child extraction and a deterministic proposal generator. Its\nhardcoded test login is fixture-only and is never a production auth provider.\nImage/audio originals remain inspectable when no OCR/speech provider is\nconfigured; the suite makes no recognition-quality claim and spends no provider\nbudget. `reference/review-host.ts` is a maintained development fixture, not a\npublished server entry. Browser tests show actual approved args and persisted\nContentDocument results, stale tabs, reload, retries and negative access.\n\nRun full package `test`, `test:postgres`, `test:providers`, `build`, `typecheck`,\n`test:components`, `test:e2e`; use the root Node/pnpm versions. Set a short\n`CI_TEST_TMPDIR`/`TMPDIR`, and optionally\n`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to the supported installed Chromium.\n`pnpm test:evaluation` checks repository evaluation tooling contracts; measured\nheld-out quality remains a separate frozen-protocol, budget-gated #3677 run.\n\nThe existing CI browser job includes ingestion changes and shared UI primitive\nchanges in affected mode, and runs the ingestion browser suite in full mode. Its\nnormal dependency build precedes the suite and failed runs upload browser evidence.\n\nThe maintained host derives inbox state by traversing bounded public review pages,\nauthorizing every action/parent/target before classification. It retains only\nscalar totals and the requested page; an off-page denial denies the whole view.\nThe component's Load more and subsequent refresh/mutation reload every displayed\npage using fresh cursors, then publish the combined authorized set together. Old\npage payloads are cleared while loading; any unavailable page clears all payloads.\nThis keeps plan controls and earlier steps visible across page boundaries without\nreusing a prior authorization decision.\n\n## Published server adapter\n\nImport `createIntakeReviewHost` and `IntakeReviewHostOptions` from\n`@happyvertical/smrt-ingestion/server`. Call `createIntakeReviewHost(service,\noptions)` with a service constructed from the current authenticated session.\nThe returned `IntakeReviewHost` implements inbox state projection across saved\nreview pages, current generation loading, stable `ui:<index>` intention keys,\naction/plan preview CAS lookup, decisions, apply, corrections, candidates, split,\nfeedback, the offered `catalog`, `startAction` and `resolve`. Any catalog\nfailure (not configured, bound exceeded, denied) omits `catalog`, so the picker\ndisappears while existing reviews stay reviewable; item, review and evidence\ndenials still propagate as before; the reference host (`reference/review-host.ts`)\ndegrades the same way. Repeated\npreparation of an unchanged authorized suggestion retains\nits current review instead of creating a new revision. Changed arguments still\nrequire explicit re-preview and a fresh human decision.\n`list({ state?, assigneeId?, cursor?, limit? })` returns one page newest receipt\nfirst (`intake_items.created_at`, id tiebreak) through `service.listItemsPage`.\n`limit` defaults to 20 and is capped at 100; the cursor is an opaque\n(received-at, id) continuation, never a bare id. Tenant, confidential scope,\nretention and the `state` filter run inside the page query, so a page is full\nand `nextCursor` is present only when more rows follow.\n\nAuthority is rechecked at the same two levels `load` applies, but per page\nrather than per row: the host authorize callback once per distinct captured\nceiling in a batch, and the execution read gate (policy, ceiling, handler and\noperation allowlists, principal) once per distinct (item, handler) bound by\nthe page's saved actions. The list gate is read-only: it evaluates the same\nchecks as `listReviews` without the retention write, so an item that the item\nview would narrow past its deadline is simply not listed. The list gate also\nresolves each bound handler and rejects version drift against the saved\nbinding and omits a cancelled item, as `listReviews` does; it does not\nevaluate per-action target,\nevidence or plan gates, so an item whose target became unreadable still lists\nand its item view refuses. An item whose bound\nhandler the actor cannot currently read is not listed at all, rather than\nlisted with a state derived from actions the actor may not see; actions\nwithout a proposal bind no handler and are not gated, as in `listReviews`.\nHandler bindings (handler id and version, projected in SQL, distinct per\nitem) are read once per fetched batch for the rows that passed the item-level\ngate. Note the host cost plainly: the execution `authorize` callback runs once\nper distinct (item, handler) bound by a scanned row that passed the item-level\ngate. Each item is its own authorization subject, so nothing is deduplicated\nacross items; the count is bounded by rows scanned (at most\n`ITEM_SCAN_CEILING`) and runs in host code rather than as N+1 database reads. Either host callback, the item-level `authorize` or the execution\n`authorize` behind the handler gate, follows the same rule: a refusal (false,\nor an access check that fails) hides the rows it covers, and a callback that\nthrows rejects the whole page (and `listItems()`) with its error, as `load`\ndoes, so a transient failure never lets paging move past readable rows.\nDenied or unreadable rows are skipped without\ndisclosure and the page refills from the next rows; refills grow from the page\nsize to 100 rows per query, so a fully denied scope costs about a dozen page\nreads and as many binding reads per call. One service call examines at most\n`ITEM_SCAN_CEILING` (1000) rows, or the caller's smaller `scanLimit`, and\nreports the count as `scanned`; when a mostly-denied scope reaches the ceiling\nthe page comes back short with a `nextCursor`. Rows are authorized first and\nthe `state` filter is then applied to the fetched batch, so it is bounded by\nthe same scan limit: a rare state yields short pages with a cursor rather than\nan unbounded walk inside one query. A row the actor can read whose state does\nnot match discloses nothing and may anchor the cursor, so a filter with no\nmatch among the next 1000 rows returns an empty page with a cursor and still\npages to the end. The host `list` passes its remaining budget as `scanLimit`, so the\nrows scanned across the service calls of one host call never exceed 1000: a\nshort service page with a cursor, or an exhausted budget while filtering by\nassignee, ends the host call with the same cursor and the caller continues.\nOnly rows the service wrote are supported: cursors carry the canonical\nmillisecond ISO receipt time the service stores. A row whose stored receipt\ntime is not that form (on SQLite anything but `YYYY-MM-DDTHH:MM:SS.mmmZ`,\nincluding a parseable value without milliseconds or with an offset; on\nPostgreSQL a value with a sub-millisecond part) is never listed, whatever the\nactor's access, and counts toward the scan, as does a row whose id is not a\nUUID. On SQLite a non-text stored value (an integer, say) and a receipt value\nor id longer than 64 characters or containing a NUL character are excluded by\nthe page query itself: the first sorts after every text value so the scan\ncould never move past it, the second could not be carried by any cursor, and\nthe third is returned truncated at the NUL, so it would look canonical and\nsort above a legitimate row at the truncated value. Within a call the scan moves\npast a service-foreign row by its exact stored value, and an unsealed cursor\nnames the last row before it that the actor can read. A call that finds no readable row within its scan limit (at\nmost 1000) fails closed with `IntakeScanLimitError` unless a `cursorKey` is\nconfigured, as below. The host\n`list` returns what earlier service calls collected, with their cursor, when\na later call fails that way.\n\n`listItems()` is deprecated and kept only for callers of the array-returning\nAPI. It walks every page, so its cost grows with the scope, including one\nexecution authorization per (item, handler) across the whole scope. It follows\nthe internal scan position, which never leaves the service, so runs of rows\nthe actor cannot read never stop it and it returns `[]` where nothing is\nreadable. Items are newest-first and gated exactly as on a page.\n\nThe page's inbox state is the durable projection of the saved action journal\nand processing state, computed once per scanned row inside the page query;\n`load` remains the authoritative, live-gated projection for one item (it still\nprojects individual stale actions, which the list does not). Cost is\nproportional to the page for unfiltered pages and common states, and to the\nnumber of items scanned until enough matches are found for rare states: the\nstate is not persisted, because the action journal is append-only and\nprojecting it into an indexed column would need a maintained denormalisation\nin the execution service plus a migration, which this change does not take.\nListing does not load original bytes.\n\nCursors never disclose an unreadable row. Without a `cursorKey` in the\nservice options, every cursor (each row's and `nextCursor`) names a row the\nactor can read (the last one when a page stops early); a page that spends its scan limit before filling hands back\nthe last such row, and one that found none fails closed with\n`IntakeScanLimitError` (`Intake scan limit`, no id or time). A run of rows the\nactor cannot read (refused by the captured ceiling or the execution gate, or\nstored with a non-canonical receipt time) at least as long as the scan limit\ntherefore stops an unkeyed walk there; readable rows that the `state` filter\nexcludes never count toward such a run. With a `cursorKey` (a server secret of at least 32 bytes), every\ncursor is sealed with AES-256-GCM, bound to the tenant, confidential scope and\nactor, and a budget-stopped page returns a sealed position past what it\nskipped, so the walk always progresses. Sealed cursors have a fixed length\n(the plaintext is padded to 1024 bytes) and a fresh nonce per seal, so neither\ntheir length nor their bytes reveal anything about the stop row. `scanned` is for trusted host\naccounting and must not be sent to clients; a short page with a cursor tells\na caller only that unlisted rows exist, never which.\n\nNewest-first paging relies on `intake_items_received_idx`\n(`tenant_id, confidential_scope_id, created_at, id`), the full ordering key, so\nan unfiltered page is a backward index scan that stops at the page boundary;\nthe foundation suite asserts that plan on both engines (SQLite\n`EXPLAIN QUERY PLAN`, PostgreSQL `EXPLAIN`), with the per-row state counters\nserved by `intake_actions_item_idx`. On SQLite the page query pins the index with `INDEXED BY` (except under an\nid restriction, where direct id lookups are cheaper), because without planner\nstatistics SQLite otherwise picks `intake_items_expiry_idx` plus a sort; the\nSQLite plan check runs without `ANALYZE`. A deployment must have applied the\nmanifest migration, or the page query fails with a missing-index error. This package ships no\nmigration files: indexes are declared on the model, the build emits them into\n`dist/manifest.json`, and `smrt db:migrate` / the public migration API create\nthem, which is how `intake_items_receipt_idx` shipped. Deploy the manifest\nmigration before upgrading hosts; `db:status --parity` reports the index as\nmissing until then.\n\nSupply four application adapters: `upload(files, requestId)` (authenticated\nreceipt plus first extraction request), `assignment(itemId)` (durable read),\n`assign(input)` (manager authorization, eligible assignees, durable CAS and request\nreplay protection), and `evidence(part)` (safe label/text or authenticated\nsame-origin URL), which `load` calls for every part and `list` never calls;\n`load` sets no row preview on its entry.\n\nRow previews are opt-in through an optional fifth adapter,\n`rowEvidence(rows)`. When it is supplied, `list` reads the page's durable\nevidence metadata with one `service.listEvidence(itemIds)` query (at most 100\nids; items the scope cannot read, and expired or inactive items, are omitted\nwithout disclosure; the host `authorize` runs once per distinct captured\nceiling through the same gate as `listItemsPage`, so a refusal or a\nmalformed captured ceiling hides the item and a failing `authorize` rejects\nthe page; an item whose stored data does not parse is skipped by both\n`listItemsPage` and `listEvidence`, never fatal). It then calls `rowEvidence`\nonce with each row's primary part (`{ itemId, evidence }`) and publishes the\nreturned `{ label, viewUrl?, thumbnailUrl? }` as `InboxEntry.evidence`\n(`{ evidence, label, viewUrl?, thumbnailUrl? }`, never text). Build those URLs\nfrom metadata without reading bytes; if `rowEvidence` throws or returns a\nmalformed answer, the page still lists without previews, and a row without\ndurable parts never gets one. When it is omitted, rows show no original link.\nEither way `list` reads the page's evidence metadata once, in that same query,\nso the row label can use the original filename; it never reads original bytes\nand never calls `evidence(part)`. The primary part is chosen by role, not media\ntype: the shallowest child part when any part has a parent (an upload's file\nunder its capture record, an email's first attachment under the message, even\nwhen that child is JSON), else the first root part (a watched-folder file);\npart ids sort numerically. `IntakeInbox`/`InboxView` accept an\noptional `rowAside` snippet receiving the `InboxEntry`; without it a row renders\nthe host's \"Open original\" link (new tab) and thumbnail when the URLs are\nsame-origin; each link's accessible name is \"Open original: <row label>\", and\na row shows no wrapper when neither URL is usable. The slot is a plain `div`,\nnot an `aside` landmark, so a page does not add one landmark per row. Optional\n`label(item, evidence)` changes presentation; `evidence` is the item's durable\nparts with the primary part first, and the default label is the primary part's\nown original `filename`, else `Intake <8 hex>`. Optional\n`assignments(itemIds)` reads one page's assignments in one batch (otherwise\n`assignment` runs per row), and optional `assignedItemIds(assigneeId)` lets\n`list` push the assignee filter into the page query (junk ids are dropped, not\nfatal); without it an assignee filter scans further pages and filters by\n`assignment`, which stays correct but costs more rows. The page's continuation\nis always the last row actually returned, so an assignment that changes\nbetween the page read and the assignment read costs at most one extra scan and\nnever skips or repeats a row. Optional\n`enableFeedback: true` exposes the optional feedback callback when the service\nhas feedback configured. Optional `onSplit(itemId, revision)` wakes the host worker after the durable extraction\nrequest; repair dispatches if wakeup fails. The factory creates no assignment\nschema and grants no permissions. Create it per session, authenticate every HTTP\ncall and enforce CSRF before dispatching a mutation.\n\n`GenerationAnalysisOutput` is exported by `/dto` and describes the interpretation\nwrapper `{ proposals: GenerationOutput }` under `analysis.result.output`.\nThe factory unwraps this into `ItemReviewView.generation`. Stale generation is\nomitted while authorized saved reviews remain available; access denials propagate.\nThe reference application still owns its fixture provisioning and HTTP transport.\n\n## Explicit upload retries\n\nThe inbox retains selected original files and the receive request identity when\nupload fails or acknowledgment is lost. Retry Upload explicitly with the same\nselection; Refresh does not replace that identity. Selecting files again starts a\nnew receipt identity, even when names match. Successful upload clears the selection\nand identity. Replacing the authenticated host/context or destroying the component\ndiscards both and fences late completion from the prior context. No automatic\nupload retry or authorization bypass occurs.\n\nThe inbox clears only its native file-input value when opening the picker, so\nchoosing the same local file explicitly starts a new upload identity. Opening\nthen dismissing the chooser preserves the separately retained originals and\nrequest identity for retry; it does not clear the shared FilePicker's native-form\nbehavior. Successful upload and host/context disposal still discard retry state.\n\nWorkspace ordering also protects an open item during an awaited automatic page walk:\nthe selected row remains until navigation succeeds, except that a failed list read\nclears the inbox. Applying an action is disabled\nwhile that action card holds unsent arguments, reason, or feedback comment. A list\nrefresh retires earlier follow snapshots; only follow reads started after that\npage request may override its rows, so a newer refresh cannot be regressed by an\nalready settled or older in-flight follow read.\n"
+      "content": "# Authenticated review surfaces\n\n`@happyvertical/smrt-ingestion/svelte` exports `IntakeInbox`, `IntakeReview`,\n`IntakeWorkspace` and `EvidenceViewer`. The browser-safe DTO entry exports their `IntakeReviewHost`\ncallback contract. Import styling/theme configuration from smrt-ui in the host.\nComponents use smrt-ui primitives and the `ingestion.*` i18n catalog.\nExisting `IntakeInbox` hosts now keep the previous rows visible, with their\ncontrols disabled, while a refresh or filter change loads; any failed read\n(Load more included) still clears them.\n\nThe host authenticates every request, resolves tenant/actor/confidential scope\nfrom its session, enforces CSRF on mutations, and constructs `IngestionService`.\nNever accept scope, reviewer, permissions or a principal from callback JSON.\nOnly supply authorized evidence URLs and escaped text; original URLs are\nsame-origin authenticated handlers that recheck `readEvidence` on every read.\nCandidate discovery uses `findCandidates` with current grants. Presentation\nstate and disabled buttons provide no server authority.\n\n`listReviews(itemId, {cursor?,limit?})` reloads saved action identities and their\ncurrent plan membership without browser storage. It returns at most 50 actions,\nwith an opaque action-ID cursor. Every payload requires current item, handler,\nparent plan and target access under the owning transaction. Denied reads fail\nclosed. Target reads check current authorization separately from historical\nrevision freshness: unfinished drift returns state-only stale reviews without\nremoving unrelated entries; succeeded results remain readable after authorized\ntarget changes. Apply still enforces exact bound target revisions. Expired entries\ncontain only review identity/state. Stale entries never disclose old args or target\nlabels; an authorized parent plan additionally exposes `stalePlan` identity, key,\ncurrent plan revision and handler identity. Hosts must collect fresh explicit args\nfrom the reviewer/current authorized evidence and call `previewPlan` with that\nexact plan CAS and the current completed analysis attempt. Action revision is not\nplan revision. Re-expansion preserves action identity and requires fresh approval.\nSuccess results are rechecked through the durable result reader.\nPlan membership contains the exact parent args/version so edits call\n`previewPlan`, not per-step correction. An item may have more review pages; the\nhost must aggregate state across pages when projecting a production inbox state.\n\nA `needs_review` suggestion is completable, not only rejectable (#4208). That\nincludes a suggestion kept because its arguments missed only required fields\n(#4284); nested misses appear as JSON Pointers such as `/vendor/name`. The\ncomponent shows its `missingFields`, an editable `Suggested arguments (JSON)`\ndraft prefilled from the generated arguments, and the candidate picker for\ndeclared candidate fields; Prepare review stays disabled while required fields\nare still missing from an unchanged draft. An unchanged draft previews the\ngenerated snapshot as before; an edited draft is sent as `preview({..., args})`,\nwhich the published host publishes through the ordinary `previewProposal` /\n`previewPlan` with the same `ui:<index>` intention, never by rewriting the\ngeneration. The handler validates the human arguments again before a\n`waiting_review` action exists, approval remains a separate explicit decision,\n`ActionReview` lists top-level required arguments missing from the current\ndraft while editing (nested misses named by JSON Pointer in `missingFields` are\nnot re-checked in the browser; the server's revalidation refuses them and the\ncomponent shows that inline as `HandlerArgumentsInvalidError`), and no authority or automation eligibility is added: a failed attempt,\nan unoffered handler or a foreign stage is still refused by the host.\n`preview` throws on every failure, as before. When the handler's argument\nschema or `validate` refused the arguments being previewed (operation preview,\nwhich also carries corrections, a reviewer-started action, or plan preview),\nthe server throws `HandlerArgumentsInvalidError` (`name` set, messages\nunchanged). An argument-schema refusal also carries `issues`: a frozen list of\nat most `HANDLER_ARGUMENT_ISSUE_LIMIT` (20) `{ path, keyword? }` entries\n(`HandlerArgumentIssue`). `path` is built only from schema-declared property\nnames, `required` names and real array indexes and is cut at\n`HANDLER_ARGUMENT_PATH_LIMIT` (160)\ncharacters (never splitting a `~0`/`~1` escape). Segments are escaped per RFC\n6901 (`~` as `~0`, `/` as `~1`), with two departures: `/` is the whole\narguments object (never a key `\"\"`), and `?` stands for a data-named key. A\n`required` refusal appends the missing schema name to the parent's path. The\nformat relates to a suggestion's `missingFields` as follows: a root path\n`/name` is the bare `missingFields` entry `name` (unescaped), and a nested\nentry is the same escaped pointer in both (for example `/vendor/a~1b~0c`).\nThe bundled view shows a root issue without its leading `/`, so its refused\nfields read like the missing-information list. `ProposalValidationError`\nreasons share the schema-owned segment rule but stay unescaped.\n`keyword` is the failing schema keyword. Argument values, Ajv\n`params`/messages and handler messages are never included. A `validate`\nrefusal has no `issues` (the handler contract returns only `ok`). The size and\nshape preconditions checked before the schema runs (arguments over the policy\nbyte limit, or a handler schema that is not a closed `type: 'object'` with\n`additionalProperties: false`) stay a plain `Error`: they fail closed as a\ndenial, never as the inline refusal. Apply-time and\nexternal-send revalidation and result-schema checks keep a plain `Error`. The component shows an inline message and\nkeeps the view and draft when `preview` either rejects with an error whose\n`name` is `HandlerArgumentsInvalidError` or resolves `{ rejected: 'invalid' }`\n(`PreviewRejection`, optionally with the same `issues`). A transport that\ncrosses a process boundary preserves the inline UX by keeping that name and\n`issues` (for example re-throwing an `Error` with\n`name = 'HandlerArgumentsInvalidError'` in the browser callback) or by\nreturning `{ rejected: 'invalid', issues? }` for that case only, as the\nmaintained fixture's `previewForReview` and `startActionForReview` do. Since\n#4281 the fixture's rejection body also carries `issues` when the schema\nrefused; read `rejected === 'invalid'` rather than comparing the whole body\nwith strict equality. Without either, the refusal behaves like\nany other failure: the view is cleared exactly as before this change, and the\nreviewer's in-memory draft returns after an authorized refresh. Every other\nthrown preview or candidate-search failure (denied, revoked, unavailable or\nunknown) clears the view.\nUnsent drafts live only in component memory, keyed by attempt and suggestion\nindex. They survive Refresh, a failed callback, an action on another card and a\ntransient `unavailable`/`stale` reload; a `revoked` or `expired` result\ndiscards them, a successful preview clears that card's draft, and an available\nreload drops drafts for attempts or cards no longer offered.\n\nThe host's `load` callback supplies a current `ItemReviewView`, using\n`getCompletedAnalysis` with no historical fallback. Generated suggestions bind\nthe **current generation attempt**, not `generation.source.attemptId` (the prior\nextraction). `previewGeneratedProposals` publishes exact reviews and continues to reject stale\ngeneration candidate pins. When `listReviews` reports `generationStale`, the host\nomits obsolete generation output and renders authorized saved reviews/results.\nCompleted saved actions do not hide healthy unprepared suggestions. The saved-binding hint is not\nan authoritative generation-availability check: a fresh human preview can bind a\ncurrent target while the immutable generation still pins its former revision.\n`getCompletedAnalysis` remains strict and throws server-only\n`GenerationSnapshotStaleError` only after every current catalog/provider/candidate\nread is authorized and an immutable candidate revision differs. The maintained\nhost catches only that class, reacquires `listReviews` under current owning\nauthority, and returns that new page without generation output. It never reuses\nthe earlier page after an error. Denials and unknown failures propagate; healthy\ngeneration still exposes unprepared sibling suggestions. Stale entries expose handler\nand attempt identity only when that attempt is still the current completed/partial\nanalysis. An empty-args editor submits fresh explicit human arguments through\n`previewProposal` or `previewPlan` with the saved CAS; it never reuses old generated\narguments, rewrites the generation snapshot or transfers approval. Analysis-stale\nentries without an attempt require normal reprocessing. Approve,\nreject, defer and correct call `submitDecision`; corrected args create a new\nrevision which requires a separate human approval. After an approve/defer/reject\ndecision, optional `editAction` calls `previewProposal` with the current action\nrevision to publish a new review; completed/executing/unknown actions cannot be\nrevised. Local dirty args disable Apply but confer no authority. Plan edits re-expand through\n`previewPlan` with the current **plan** revision. `applyAction` accepts only an\naction ID. Unknown external outcomes require server reconciliation; the UI\nnever offers a blind resend. Stable result IDs survive reload and retry.\n\nReplace `contextKey` whenever authenticated tenant/session context changes.\nChanging it or itemId destroys the old view and fences late callback results.\nDenied refresh clears prior originals, candidates, arguments and results.\nMissing confidence is unavailable; page/time links exist only for observed\nlocations. Provider errors and unresolved/partial results remain review states.\nA host that enabled `proposals.failureCapture` may fetch a failed attempt's\nredacted model output with `getFailedAttemptCapture(itemId, attemptId?)`.\nRetaining text requires a configured host redaction hook; a missing or failed\nhook yields only `redaction_failed` metadata. The host owns that redaction policy.\nThe getter requires current reviewer authority for that item and fails closed\notherwise;\n`load`, inbox rows and review pages never include it, so a host shows it only\nbehind its own explicit diagnostic action (see\n[PROPOSALS.md](PROPOSALS.md#failed-attempt-capture-opt-in-4285)).\n\n## Submitter-scoped decisions\n\nFor trusted internal sources the person who submitted an item may confirm or\ndecline their own proposal without the reviewer inbox. `listOwnProposals`\nreturns only items whose server-recorded `submitter_id` equals the current\nauthenticated actor, each with its bounded saved review page reloaded under\ncurrent item, handler and target authority. An item the actor can no longer\nread (the host `authorize` returns false or throws `IntakeAccessDeniedError`)\nis skipped before projection: the page is filled from readable items only, in\n50-row batches, and `nextCursor` names the last emitted item and is present\nonly when a further readable item was actually found. Neither the entries, the\npage size nor the cursor reveal a hidden item. If one call has to skip 1000\nhidden submissions it fails with `Own proposal scan limit` rather than return a\nshort page or a cursor that stops inside the hidden run; this error is the only\nsignal, and it says only that such a run exists. Any other `authorize` error\npropagates instead of shrinking the list. An item that is still readable but\nwhose reviews are denied is returned as `{ item, reviews: null, unavailable:\ntrue }`: that covers ingestion's own denials and any throw from the host\n`assertTarget` (deleted or revoked targets), whose text is never returned.\nIntegrity, validation and database errors from ingestion itself propagate. The\nreviewer `listReviews` surface keeps propagating host target errors unchanged.\n`submitOwnDecision` takes the same `ReviewInput` CAS fields and request ID as\n`submitDecision` and accepts `approve`, `reject` and `defer` only; `correct`\nbelongs to the reviewer surface. It runs under the `review_own` execution\noperation: the host's `authorize` must return `submitter: true`, the resolved\npolicy must have `submitterReview` enabled, and the recorded submitter must be\nthe current actor and also the receipt's captured execution principal (the\nidentity the effect runs as), checked under the item lock and again at apply.\nA receipt captured for a bot or service principal is never self-approvable. Policy enablement, handler/operation allowlists, captured\nceiling, confidential access, retention and the first-valid-decision lock are\nunchanged. The decision is a human decision by that actor, recorded with\n`mode: 'review_own'`; reviewer decisions carry `mode: 'review'`. In both modes\n`selfDecision` is true exactly when the deciding actor is the item's\nsubmitter, so a reviewer approving their own submission is never independent\nreview. A self-decision is not a reviewer judgment: it never feeds\nautomation eligibility (machine authorization remains the separate evaluated\n`kind: 'machine'` path) and its feedback events carry the same marker. The\n`unavailable` entry discloses nothing about the denied handler or target.\n`applyAction` then runs once under the approver's live grants exactly as\nfor reviewer decisions. Hosts render this surface from their own authenticated\nsession; presentation state confers no authority, and a source payload cannot\nnominate a submitter.\n\n## Assignment and logical splits\n\nAssignment is explicitly host-owned, durable and versioned. `assign` receives\nan expected assignment version and request ID; the host must authorize the\nmanager, constrain eligible assignees, CAS the durable record and reject stale\nwrites. Assignment does not grant read, review or execution rights. The maintained\nfixture provisions its own SQLite assignment table before serving requests; no\nproduction ingestion table or migration is introduced for assignment.\n\n`reviseLogicalSplit` authorizes the current generation through the same-executor\ncatalog/candidate gate and the existing reviewer grant and policy reviewer list.\nProcess access alone cannot mint or replay a human correction; reviewer authority\nis checked before mutation and again before publication. A generation without a\nreviewable catalogue cannot be corrected through this reviewer API.\nIt requires all observed pages exactly once, an exact\ncurrent attempt/revision and a request ID. It records the authenticated actor\nand predecessor as a **human correction** in a new immutable extraction\nconfiguration, queues re-extraction and immediately makes previous suggestions\nand approvals stale. It never changes original bytes/evidence or labels a human\nedit as model output. The host processes the new extraction, then calls\n`prepareGeneration` and the normal fenced interpretation stage. The supported\nimmediate-predecessor extraction pin is unchanged. The generator receives a\nhuman correction only after its digest matches the authoritative source. Ordinary\n`analyze` calls cannot mint an extraction correction; the owning split API is the\nauthenticated origin, and forged interpretation corrections fail before provider\ndisclosure. If its proposed grouping differs from the correction, suggestions are withheld\nwith `human_split_not_respected`. New proposals require new explicit review.\nThe reference host runs these stages synchronously for browser determinism;\nproduction hosts dispatch the existing durable analysis jobs.\n\n## Reviewer instructions\n\n`recordReviewerInstruction({itemId, attemptId, expectedRevision, text,\nrequestId})` records a plain-text instruction for one item (\"This is a customer\nPO from Badger; file it, do not bill it\") as the second kind of **human\ncorrection**. It is authorized exactly like `reviseLogicalSplit`: the current\ngeneration must pass the same-executor catalog/candidate gate and the reviewer\ngrant plus policy reviewer list, and authority is checked before mutation and\nagain before publication. Process access, `analyze`, and a client payload cannot\nmint one: `analyze` rejects a `reviewerInstruction` key on an extraction\nconfiguration, and an interpretation copy that differs from the pinned\nextraction's record fails with `Generation evidence changed` before provider\ndisclosure. Text is required, trimmed-nonempty and at most 4,000 characters.\n\nThe record is immutable: `{id, text, actorId, recordedAt, supersedesId, digest}`\nplus the request binding, written into a new extraction configuration beside\nany existing split correction. Recording supersedes current suggestions and\napprovals, queues the normal fenced re-extraction and interpretation through the\nexisting dispatch path, and returns immediately; the reviewer keeps working\nwhile the item reports `processing`. `prepareGeneration` copies the instruction\ninto the interpretation configuration, the generator receives it only after its\ndigest matches the authoritative extraction record, and saved generation\nprovenance records `reviewerInstruction: {id, digest}`. A later instruction\nrecords `supersedesId` and replaces the earlier one for future interpretations;\n`listReviewerInstructions(itemId)` returns the full history, newest first, and\nhistory is never deleted. The instruction steers the model only: it cannot add\nhandlers, candidates, schemas, permissions or automation eligibility, replies\nare validated as usual, and suggestions still require explicit preview and\napproval. A replay with the same request ID returns the same revision; a changed\ntext under the same request ID conflicts.\n\n**Cost.** Each recorded instruction appends a new extraction revision, so the\nitem is extracted again before it is interpreted again: cheap for embedded-text\nPDFs and plain text, but OCR/speech hosts spend provider budget per instruction,\nexactly as they do per split correction. The pinned extraction is not reused\nbecause the interpretation contract requires its source to be the immediately\npreceding revision and `getCompletedAnalysis(itemId, attemptId)` serves only\nthe current revision (PROPOSALS.md, \"Durable stages\"); reusing it would mean\nweakening that predecessor pin, which protects every generation from an\nintervening reprocess, so this feature follows the split path instead.\n\n**State and failure.** An in-flight stage (queued/running) reports the item as\n`processing` even when earlier, now-stale actions exist. If the re-extraction or\ninterpretation fails, `getReinterpretationState(itemId)` returns the latest\nattempt's safe failure category and the latest completed generation attempt;\nthe host projects them as `instruction.failure` and `instruction.binding`, and\n`recordReviewerInstruction` accepts that historical attempt as its anchor when\n`expectedRevision` is the item's current (failed) revision and no later\n**interpretation** completed and nothing is queued or running, so the reviewer\ncan retry or change the instruction after either stage fails. A completed\nextraction whose own interpretation failed belongs to the failed attempt, not a\nnewer result; a completed extraction whose interpretation has **not been\nappended yet** is in flight (the host is between stages) and is refused with\n`ReviewerInstructionStaleError` (`Stale reviewer instruction`), so a second\nreviewer cannot pre-empt it. That gap expires: once the extraction attempt's\ncompletion plus the item's analysis lease duration (`limits.leaseMs`, the lease\n`claimAnalysis` grants) has passed with no interpretation appended,\n`getReinterpretationState` reports `failure: 'not_started'` with the retry\nbinding and the guard allows the retry. `not_started` means **the\ninterpretation did not start within the lease window**: the host crashed,\nthrew between `prepareGeneration` and `analyze`, or its queue is merely slow.\nPre-empting a slow but healthy host is safe because `analyze` refuses an\ninterpretation whose pinned extraction is no longer the item's latest, under\nthe item lock and before anything is superseded\n(`GenerationSourceStaleError`, nothing appended): the slow host's late append\ncannot clobber the retry. Missing or malformed timing (no attempt, no\n`completedAt`, non-finite `leaseMs`) counts as already expired rather than\nholding retries forever. The \"still being re-read\" note shown after a stale\nresult is cleared by the next reload that shows the item settled; the draft\nthen carries a persistent \"This item changed while you were writing; your\ninstruction was not recorded.\" note (any stale cause: another reinterpretation,\na split, or a host reprocess) until the reviewer edits or resubmits it. The guard and\n`getReinterpretationState` share one predicate, and the latter's\n`reinterpreting` flag (projected as `instruction.reinterpreting`) is true in\nthe gap too, so the component keeps polling and keeps Re-read disabled there.\nThe published host maps two typed errors to `instruct` results:\n`ReviewerInstructionStaleError` → `{ stale: true }` (refresh-and-retry: reload\nwith a note, draft kept) and `ReviewerInstructionInvalidError` → `{ invalid:\ntrue }` (empty, whitespace-only or over 4,000 characters: shown inline, draft\nkept). Neither is a denial. Custom hosts should map them the same way; a host\nthat lets either propagate as a thrown error makes the component treat it like\nany other failed mutation, i.e. a whole-view deny with the \"view unavailable\"\nmessage, as before these results existed. The maintained fixture's\n`/api/instruct` now answers an invalid text with HTTP 200 `{ invalid: true }`\ninstead of 409. A retry from an older anchor builds on the **whole configuration**\nof the newest extraction after it (replacing only the instruction), because that\nis the item's current configuration: corrections chain forward through it and a\nhost reprocess replaces it. So a split followed by a failed stage is never\nsilently dropped, and a failed reprocess's changed configuration is neither\nreverted nor overlaid with a split it dropped. **Concurrency.** `recordReviewerInstruction` and `reviseLogicalSplit` each\nrun their whole decision in one transaction under the item row lock: the\nanchor snapshot read takes the lock first, the execution authorization of\nthat snapshot takes it again (`UPDATE intake_items` row lock), the guard step\nre-asserts it explicitly, and\nthe request-key replay check, the revision and later-work guards, the\ncarried-forward split, the history read that sets `supersedesId`, and the\nappend all run under it. On PostgreSQL a second reviewer at the same revision\nblocks on that lock and is then refused (`ReviewerInstructionStaleError` /\n`Stale logical split`), so the ledger cannot fork; an instruction racing a\nsplit (in either order) is refused rather than built from the pre-split\nconfiguration; and a double-click whose duplicate commits after the unlocked\nreplay check is answered as a replay of the committed request, not a conflict\nor a denial.\n\n**Host reprocess.** A host reprocess (a plain `analyze()` extraction the host\nconfigures itself) cannot carry human corrections — `analyze` rejects\n`humanCorrection`/`reviewerInstruction` on extraction configurations — so it\ndrops the split and the instruction alike, and neither is applied to its\ninterpretations. The instruction is then reported as `dropped`, not pending:\n`getReinterpretationState().instructionInEffect` names the instruction the\nnewest extraction carries (verified by digest) and is null after such a\nreprocess. History is unchanged; the reviewer can re-record the instruction,\nwhich supersedes the dropped one.\n\n`ItemReviewView.instruction` exposes `current` (the latest recorded instruction\nstill in effect, i.e. carried by the newest extraction), optional `dropped`\n(the latest recorded instruction a reprocess dropped), `applied` (the\ninstruction the displayed **generation** ran under; a completed extraction alone\napplies nothing), `stale` (the displayed suggestions predate the current\ninstruction), optional `failure` and optional `binding`. Feedback examples that carry instruction\ntext count it toward the feedback byte budget (FEEDBACK.md). The optional host callback\n`IntakeReviewHost.instruct` is implemented by the published adapter when the\nservice supports it, with an optional `onInstruct(itemId, revision)` wakeup\nmirroring `onSplit`. The review component renders \"Instructions for the\nassistant\" with \"Re-read with these instructions\", shows \"Reinterpreting…\" while\nthe item's stage is queued/running, repeats the existing authenticated `load`\non `pollMs` (default 2 s, backing off to 5×) and patches the view in place —\ndrafts, split edits, focus and the evidence viewer survive and no loading\nplaceholder is shown — stops when the stage is no longer in flight, and then\nshows the instruction that produced the current suggestions, marking a\nsuperseded one as stale. An explicit host denial on a poll tick fails closed at\nonce; a thrown tick is treated as transient (view and drafts kept, a\n\"Couldn't refresh; retrying.\" note, backoff continues), but because hosts may\nalso throw for revoked access, three consecutive thrown ticks fail closed.\n**Hosts must signal revocation by returning `availability: 'revoked'`** (or\nanother non-`available` state) from `load`, not by throwing: a returned denial\nclears the view on that tick, while a host that throws on revocation leaves the\nalready-displayed content visible until the third thrown tick (about 10 s at the\ndefault interval and backoff) before the view fails closed.\nSplit drafts survive a refresh only when the reviewer edited them. A failed stage shows its safe category with the form\nstill available. There is no\nstreaming channel; status is read through the existing item/analysis APIs. The\nmaintained fixture records the instruction durably and then runs the stages in\nthe background so the browser proof exercises the in-place update.\n\n`feedback` is an optional explicit correctness callback, separate from approval\nchoice and execution success. No learning, feedback storage or rule promotion is\nimplemented by these components; #3676 owns those services. Do not pass feedback\nor a feedback callback to readers without the relevant host grant.\n\n## Reviewer-chosen actions and \"handled, no action\"\n\nA reviewer is not limited to model suggestions. `ItemReviewView.catalog` carries\nthe handlers the item's catalog currently offers (`listHandlers`, discovery media\ntypes and live preview authority; it is presentation, never a grant). The optional\n`startAction` callback forwards `StartActionInput` (`itemId`, `handlerId@version`,\nexplicit `args`, `requestId`, optional `reason`) to `startReviewerAction`, which\nrequires the current reviewer grant under that handler, a completed or partial\nattempt on the current analysis revision, and an operation handler the item's\nevidence media types offer. Plan handlers go through `previewPlan`. The server\ncreates an action keyed `reviewer:<requestId>` with origin `reviewer-selected`\n(`createAction` refuses that key prefix and origin, so process authority cannot\nmint reviewer provenance; re-previewing such an action with `previewProposal`\nneeds the reviewer grant and keeps its handler fixed, so only its arguments can\nbe corrected),\nruns the handler's normal `validate`/`preview`, publishes a `waiting_review`\nrevision and requires the same explicit approval and apply as a generated\nproposal. The reviewer typed these arguments, so a handler argument-schema or\n`validate` refusal throws `HandlerArgumentsInvalidError` with the value-free\n`issues` described above, and the rolled-back transaction leaves no action row\n(#4281). Every other refusal (input shape, access, handler unavailable, item\nresolved, identity or request conflict, normalization mismatch) stays a plain\ndenial. `startAction` follows the `preview` contract: it throws, or a transport\nmay resolve `{ rejected: 'invalid', issues? }` for that one case. The component\nkeeps the start form, handler, arguments and reason, shows an inline refusal and\nlists any field paths; any other failure clears the view as before. Replays\nwith the same request return the same review; changed arguments or reason\nconflict. Such actions are never automation-eligible: `authorizeAutomatic`\nrefuses them regardless of policy opt-ins. The UI pre-fills arguments only from a\nsame-handler suggestion (for example a `needs_review` one) and a single original's\nevidence references, lists the required fields still missing, and submits exactly\nwhat the reviewer typed. An item whose current attempt failed outright must be\nreprocessed first; an interpretation that completed with `provider_error`,\n`unknown` or no suggestions can be acted on directly. `ReviewAction.origin`\nexposes the provenance so `ActionReview` can label human-started actions.\n\nThe optional `resolve` callback forwards `ResolveItemInput`\n(`disposition: 'resolve_no_action'`, `requestId`, optional `reason`) to\n`resolveItem`. It needs reviewer authority under any handler the item's captured\nceiling offers and refuses while an action is `authorized` with a live approval,\n`executing`, `outcome_unknown` or `succeeded`; waiting, deferred, rejected and\nfailed actions, and authorized ones whose approval expired, may remain (neither\nan exhausted failed action nor a lapsed approval can be rejected, so they must\nnot keep the queue open). Afterwards only reject remains: those actions can no\nlonger be approved, corrected, deferred, re-previewed, retried, applied or\nautomated. `submitDecision` refuses every decision but `reject`, no new revision\nis published for the item, `applyAction` rechecks the disposition before any\neffect, and `analyze`, `reviseLogicalSplit` and `createAction` refuse the item\nunder its lock before any write, so it is never reanalysed, re-split or given a\nnew action. `resolveItem` supersedes any queued or running analysis under the\nsame lock and `claimAnalysis` refuses a resolved item, so no provider is called\nafter a human closed it; the item's `processingState` keeps its last value (it\ndescribes analysis, not review), and the inbox state `resolved` is authoritative.\n`publishProposal` (process authority) refuses a resolved item and any\nreviewer-selected action. The UI hides Approve, Defer, Apply, every edit control, suggestion\npreview and split controls on a resolved item.\nResolved items hide the instruction editor and stop reinterpretation polling, even if an older processing projection is still queued. Recording an instruction cannot append a new revision after resolution.\n\nPaged lists project the resolved state and disposition time in the same bounded, scope-filtered query, so state filters and row controls agree with a full item reload.\n\nThe append-only `intake_dispositions` record is terminal: replaying the same\nrequest returns the same disposition, any other request conflicts, and\n`startReviewerAction` refuses the item. `IntakeItemDTO.disposition` projects only\n`{ state: 'resolved', at }` to any item reader (`listItems` reads it in the same\nstatement as the page); the reviewer and reason are returned only by\n`getItemDisposition`, which requires reviewer authority, and the review hosts put\nthem on `ItemReviewView.disposition` (omitted when that read is denied, so the\nview shows only \"Handled, no action\"). `loadReviewSummary` reports inbox state `resolved` unless an action\nactually succeeded. Privacy deletion and retention expiry redact the reason and\nreviewer (`intake_dispositions.data`) and keep only the kind. The disposition is\ndistinct from `reject`, which still means the proposal was wrong. Closing an item\nrecords `reviewer_routing` feedback immediately; a started action records it only\nwhen the reviewer approves it (see FEEDBACK.md). Capture is an optional projection\nthat never vetoes the decision or disposition.\n\n`startReviewerAction` applies the handler's discovery media types and the live\nreviewer grant/policy for that handler. It intentionally does not apply the\nproposal catalog's provider-policy filter or `maxHandlers` slice: those bound what\na model may be offered, and a human choosing a handler sends nothing to a\nprovider. The UI picker shows the offered catalog, so a handler hidden from it is\nonly reachable by a reviewer who already holds `review` authority for it. The maintained\nbrowser fixture serves both operations behind CSRF and the same session scope.\n\n## Single-page triage workspace\n\n`IntakeWorkspace` (#4215) composes the existing pieces so a reviewer works the\nwhole queue on one page: the paged inbox as a list pane, the review view of the\nselected item beside it (the original above its action form), and the\nreviewer-instruction message box of the item pane. Props: `host`, `contextKey`\n(replace on session change, as for the other components), optional initial\n`itemId`, `pollMs`, `rowAside` and `onselect(itemId | undefined)`, which only\nreports the selection (to keep a URL in step) and never navigates. It adds **no\nhost callback and no server authority**: every read is the host's `list` and\n`load`, every action still goes through the handler preview and an explicit\napproval and apply under the approver's live grants, and the message steers the\nmodel only, exactly as in `IntakeReview`.\n\n- **Inline original.** In the item pane `EvidenceViewer` shows one part at a\n  time (`layout=\"pager\"`), opening on the first part that renders inline (the\n  uploaded file rather than its capture record), with previous/next original.\n  A PDF with more than one *observed* page (extraction locations or proposed\n  page groups; `pages` prop) gets previous/next page, which reloads the frame\n  at the same-origin URL plus `#page=n`; only `evidenceUrl`-approved URLs ever\n  reach a frame. `IntakeReview` gets the same page navigation over its\n  unchanged stacked list of parts. The chosen part and page belong to the item\n  view (bindable `chosen`/`page`), so they survive in-place reloads, Prepare\n  review, Approve and Apply.\n- **Keyboard.** J/K and Alt+Down/Alt+Up move to the next/previous row (loading\n  the next page at the end), ignored while focus is in a text field, select or\n  editable region; \"Previous item\"/\"Next item\" buttons carry\n  `aria-keyshortcuts`. The selected row is `aria-current`, and every selection\n  moves focus to the item pane region, named by the row's label. A navigation\n  that waited for the next page is dropped if the reviewer chose another item\n  meanwhile.\n- **Unsent input.** The pane holds unsent input when it has instruction text,\n  an edited suggestion draft or split draft, a chosen start handler or start\n  reason, a no-action reason, or an action editor with edited arguments, a\n  reason or a feedback comment. It is read from the drafts themselves, so it\n  holds while a reload has cleared the view; while the view is denied nothing\n  is shown and nothing counts (the drafts stay in memory and return with an\n  authorized refresh, as before). A reviewer-initiated move (J/K, Alt+arrows,\n  Next/Previous item, a row's Review button) then asks inline, in a group\n  labelled by its note: \"Stay on this item\" takes focus and returns it to the\n  field the reviewer last used; \"Discard and open the other item\" proceeds.\n  When an item is closed without action (here or by another session), input a\n  closed item cannot take\n  (instruction, suggestion and split drafts, a started action, a no-action\n  reason) is discarded.\n- **Live state.** A row's status follows the item: \"Interpreting…\", \"Ready to\n  review\", \"Needs review\" with missing argument names or the generation\n  outcome, \"Awaiting approval\", \"Approved, not yet applied\", \"Failed\" with a\n  safe category, \"Handled, no action\", or the listed inbox state. Rows the\n  reviewer has not opened show the listed state only; reasons come from a\n  loaded view, never from server exception text. The open item's own polling\n  (`ReviewView`, unchanged backoff and three-failure fail-closed) reports each\n  displayed view and the workspace patches that row in place\n  (`InboxView.patch`, keeping the listed label and preview, and the row's\n  assignment unless the patch carries a newer assignment version, so a view\n  read before an assignment never rolls the row or the next expected version\n  back), so the row follows each newer read of the form and the list is\n  **not** re-listed per tick. An item the\n  reviewer leaves while its stage is in flight, or before the pane showed the\n  result of its last operation (an instruction just recorded), keeps\n  following: the workspace re-reads followed items with the same `load` (first\n  review page) on the pane's backoff, at most **5** reads per tick, one after\n  another, least recently read first (so every followed row is reached), with\n  only one tick running at a time. At most **20** items are followed; beyond\n  that the longest-followed one (the earliest started, whatever the read\n  rotation) stops. An item left while its pane was mid-operation (an Apply not\n  yet answered) keeps following while a read still shows an action authorized\n  or executing: exactly **3** more reads when it never answers, the fourth\n  ending the follow. That debt belongs to the operation, so it survives\n  reopening and leaving the item again until a view shows the operation\n  answered or the reads run out; leaving mid-operation again starts a full\n  debt for the new operation. Each follow has a\n  generation: an answer from an earlier follow of the same item (one asked\n  before the reviewer reopened or left it again) is dropped, and its failure\n  does not count toward the new follow's three. An item stops being followed\n  when it settles, its view is denied, three reads in a row throw, its row\n  leaves the displayed list (a filter or a refreshed page removed it), the\n  list fails closed, or the cap drops it; a denial, the failure stop or the\n  cap drops its cached status and restores its entry exactly as its page read\n  returned it (never a patched entry). Opening an item drops its cached\n  status until the pane shows a view; a denial in the open pane (a failed\n  action, the pane's own fail-closed poll, or a first load that failed) does\n  the same as a follow denial, clears the announcement, and the item is not\n  followed when left. A settled stage that was seen running is announced in a\n  polite status region (\"badger-po.pdf: Ready to review\"), only while its row\n  is displayed; a refreshed page or a failed list clears it.\n  Other rows update on Refresh, a filter change or when opened; there is no\n  streaming. While a refresh or \"Load more\" is pending, the displayed rows stay\n  (controls disabled) and keep taking patches. Every read (a page, a pane\n  view, including an unchanged poll, and a follow read) is numbered when its\n  request starts, and each row shows the entry of its newest read, whatever\n  the source: a page read before a pane or follow read never regresses the\n  row, and a page read after them replaces what they showed. The same rule\n  governs a follow: a follow read older than the row's newest read changes\n  no status, does not stop the follow and announces nothing (a newer read\n  settles it), so the announcement never contradicts the row. Cached status reasons follow the same ordering, even when entries have identical\n  fingerprints. \"Load more\" continues the\n  filter the rows were listed under, not filter inputs edited since, and does\n  not repeat a row already shown. A failed \"Load more\" fails closed like any\n  failed read (the host cannot tell a transient failure from a revoked\n  grant): the rows clear and the list shows its error.\n- **Approve and advance.** After an approve, apply or \"Handled, no action\" whose\n  reload left nothing for the reviewer (closed without action, or an action\n  succeeded and none is waiting for approval, waiting to be applied, executing,\n  unknown or failed; stale, rejected and deferred actions do not hold it), the\n  item's row is patched and leaves the list when it no longer matches the\n  listed state/assignee filter, and the next row that is not closed or\n  completed opens and takes focus, with no navigation and no re-listing. An\n  approval that leaves an apply step keeps the item open with Apply in place.\n  Unloaded saved-review pages and an active background stage also prevent\n  settlement. Advancing skips completed inbox pages until a reviewable row\n  appears; a page that makes no progress stops the walk.\n  It never advances over unsent input on the same item: the item stays open,\n  the input stays, and a note says it is finished but has unsent input; the\n  reviewer moves on explicitly, through the confirmation; input typed while\n  the next page loads counts too. When no open row is displayed, the advance\n  appends pages of finished rows until one has an open row or no page\n  remains, at most **5** appends. After each append, the advance (like\n  J/K at the end of the list) finds its place again by id: just after the\n  item it left, or, if that row has gone, at the first row that followed it\n  and is still listed, or at the first new row, so a row that left the list\n  meanwhile never shifts it onto the wrong item. Its notes (and \"nothing else\n  needs review\") are written into one persistent polite status region. The queue is never reported empty when\n  that is unknown: past the bound, or when an append cannot start (a refresh\n  is pending) or is superseded, the item stays open with a note to try Next\n  item again, which still works; when an append fails, the list has failed\n  closed (no rows, Next disabled), so the item stays open with a note to\n  refresh the list to continue. The open item stays listed while the\n  reviewer works on it even if its state stops matching the filter; it\n  leaves once they move on.\n  When nothing is left the pane says so. The per-row \"Handled, no action\"\n  control is hidden in the workspace (`resolveInRow={false}`) so closing always\n  goes through the item pane and advances.\n\n\n## Maintained browser proof\n\n`pnpm test:components` runs real Svelte component tests; `pnpm test:e2e` runs the\npackage-local authenticated Vite application under Chromium. The fixture uses\nHttpOnly same-site sessions, CSRF, real SQLite/assets/ingestion/content APIs,\nproduction unpdf child extraction and a deterministic proposal generator. Its\nhardcoded test login is fixture-only and is never a production auth provider.\nImage/audio originals remain inspectable when no OCR/speech provider is\nconfigured; the suite makes no recognition-quality claim and spends no provider\nbudget. `reference/review-host.ts` is a maintained development fixture, not a\npublished server entry. Browser tests show actual approved args and persisted\nContentDocument results, stale tabs, reload, retries and negative access.\n\nRun full package `test`, `test:postgres`, `test:providers`, `build`, `typecheck`,\n`test:components`, `test:e2e`; use the root Node/pnpm versions. Set a short\n`CI_TEST_TMPDIR`/`TMPDIR`, and optionally\n`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to the supported installed Chromium.\n`pnpm test:evaluation` checks repository evaluation tooling contracts; measured\nheld-out quality remains a separate frozen-protocol, budget-gated #3677 run.\n\nThe existing CI browser job includes ingestion changes and shared UI primitive\nchanges in affected mode, and runs the ingestion browser suite in full mode. Its\nnormal dependency build precedes the suite and failed runs upload browser evidence.\n\nThe maintained host derives inbox state by traversing bounded public review pages,\nauthorizing every action/parent/target before classification. It retains only\nscalar totals and the requested page; an off-page denial denies the whole view.\nThe component's Load more and subsequent refresh/mutation reload every displayed\npage using fresh cursors, then publish the combined authorized set together. Old\npage payloads are cleared while loading; any unavailable page clears all payloads.\nThis keeps plan controls and earlier steps visible across page boundaries without\nreusing a prior authorization decision.\n\n## Published server adapter\n\nImport `createIntakeReviewHost` and `IntakeReviewHostOptions` from\n`@happyvertical/smrt-ingestion/server`. Call `createIntakeReviewHost(service,\noptions)` with a service constructed from the current authenticated session.\nThe returned `IntakeReviewHost` implements inbox state projection across saved\nreview pages, current generation loading, stable `ui:<index>` intention keys,\naction/plan preview CAS lookup, decisions, apply, corrections, candidates, split,\nfeedback, the offered `catalog`, `startAction` and `resolve`. Any catalog\nfailure (not configured, bound exceeded, denied) omits `catalog`, so the picker\ndisappears while existing reviews stay reviewable; item, review and evidence\ndenials still propagate as before; the reference host (`reference/review-host.ts`)\ndegrades the same way. Repeated\npreparation of an unchanged authorized suggestion retains\nits current review instead of creating a new revision. Changed arguments still\nrequire explicit re-preview and a fresh human decision.\n`list({ state?, assigneeId?, cursor?, limit? })` returns one page newest receipt\nfirst (`intake_items.created_at`, id tiebreak) through `service.listItemsPage`.\n`limit` defaults to 20 and is capped at 100; the cursor is an opaque\n(received-at, id) continuation, never a bare id. Tenant, confidential scope,\nretention and the `state` filter run inside the page query, so a page is full\nand `nextCursor` is present only when more rows follow.\n\nAuthority is rechecked at the same two levels `load` applies, but per page\nrather than per row: the host authorize callback once per distinct captured\nceiling in a batch, and the execution read gate (policy, ceiling, handler and\noperation allowlists, principal) once per distinct (item, handler) bound by\nthe page's saved actions. The list gate is read-only: it evaluates the same\nchecks as `listReviews` without the retention write, so an item that the item\nview would narrow past its deadline is simply not listed. The list gate also\nresolves each bound handler and rejects version drift against the saved\nbinding and omits a cancelled item, as `listReviews` does; it does not\nevaluate per-action target,\nevidence or plan gates, so an item whose target became unreadable still lists\nand its item view refuses. An item whose bound\nhandler the actor cannot currently read is not listed at all, rather than\nlisted with a state derived from actions the actor may not see; actions\nwithout a proposal bind no handler and are not gated, as in `listReviews`.\nHandler bindings (handler id and version, projected in SQL, distinct per\nitem) are read once per fetched batch for the rows that passed the item-level\ngate. Note the host cost plainly: the execution `authorize` callback runs once\nper distinct (item, handler) bound by a scanned row that passed the item-level\ngate. Each item is its own authorization subject, so nothing is deduplicated\nacross items; the count is bounded by rows scanned (at most\n`ITEM_SCAN_CEILING`) and runs in host code rather than as N+1 database reads. Either host callback, the item-level `authorize` or the execution\n`authorize` behind the handler gate, follows the same rule: a refusal (false,\nor an access check that fails) hides the rows it covers, and a callback that\nthrows rejects the whole page (and `listItems()`) with its error, as `load`\ndoes, so a transient failure never lets paging move past readable rows.\nDenied or unreadable rows are skipped without\ndisclosure and the page refills from the next rows; refills grow from the page\nsize to 100 rows per query, so a fully denied scope costs about a dozen page\nreads and as many binding reads per call. One service call examines at most\n`ITEM_SCAN_CEILING` (1000) rows, or the caller's smaller `scanLimit`, and\nreports the count as `scanned`; when a mostly-denied scope reaches the ceiling\nthe page comes back short with a `nextCursor`. Rows are authorized first and\nthe `state` filter is then applied to the fetched batch, so it is bounded by\nthe same scan limit: a rare state yields short pages with a cursor rather than\nan unbounded walk inside one query. A row the actor can read whose state does\nnot match discloses nothing and may anchor the cursor, so a filter with no\nmatch among the next 1000 rows returns an empty page with a cursor and still\npages to the end. The host `list` passes its remaining budget as `scanLimit`, so the\nrows scanned across the service calls of one host call never exceed 1000: a\nshort service page with a cursor, or an exhausted budget while filtering by\nassignee, ends the host call with the same cursor and the caller continues.\nOnly rows the service wrote are supported: cursors carry the canonical\nmillisecond ISO receipt time the service stores. A row whose stored receipt\ntime is not that form (on SQLite anything but `YYYY-MM-DDTHH:MM:SS.mmmZ`,\nincluding a parseable value without milliseconds or with an offset; on\nPostgreSQL a value with a sub-millisecond part) is never listed, whatever the\nactor's access, and counts toward the scan, as does a row whose id is not a\nUUID. On SQLite a non-text stored value (an integer, say) and a receipt value\nor id longer than 64 characters or containing a NUL character are excluded by\nthe page query itself: the first sorts after every text value so the scan\ncould never move past it, the second could not be carried by any cursor, and\nthe third is returned truncated at the NUL, so it would look canonical and\nsort above a legitimate row at the truncated value. Within a call the scan moves\npast a service-foreign row by its exact stored value, and an unsealed cursor\nnames the last row before it that the actor can read. A call that finds no readable row within its scan limit (at\nmost 1000) fails closed with `IntakeScanLimitError` unless a `cursorKey` is\nconfigured, as below. The host\n`list` returns what earlier service calls collected, with their cursor, when\na later call fails that way.\n\n`listItems()` is deprecated and kept only for callers of the array-returning\nAPI. It walks every page, so its cost grows with the scope, including one\nexecution authorization per (item, handler) across the whole scope. It follows\nthe internal scan position, which never leaves the service, so runs of rows\nthe actor cannot read never stop it and it returns `[]` where nothing is\nreadable. Items are newest-first and gated exactly as on a page.\n\nThe page's inbox state is the durable projection of the saved action journal\nand processing state, computed once per scanned row inside the page query;\n`load` remains the authoritative, live-gated projection for one item (it still\nprojects individual stale actions, which the list does not). Cost is\nproportional to the page for unfiltered pages and common states, and to the\nnumber of items scanned until enough matches are found for rare states: the\nstate is not persisted, because the action journal is append-only and\nprojecting it into an indexed column would need a maintained denormalisation\nin the execution service plus a migration, which this change does not take.\nListing does not load original bytes.\n\nCursors never disclose an unreadable row. Without a `cursorKey` in the\nservice options, every cursor (each row's and `nextCursor`) names a row the\nactor can read (the last one when a page stops early); a page that spends its scan limit before filling hands back\nthe last such row, and one that found none fails closed with\n`IntakeScanLimitError` (`Intake scan limit`, no id or time). A run of rows the\nactor cannot read (refused by the captured ceiling or the execution gate, or\nstored with a non-canonical receipt time) at least as long as the scan limit\ntherefore stops an unkeyed walk there; readable rows that the `state` filter\nexcludes never count toward such a run. With a `cursorKey` (a server secret of at least 32 bytes), every\ncursor is sealed with AES-256-GCM, bound to the tenant, confidential scope and\nactor, and a budget-stopped page returns a sealed position past what it\nskipped, so the walk always progresses. Sealed cursors have a fixed length\n(the plaintext is padded to 1024 bytes) and a fresh nonce per seal, so neither\ntheir length nor their bytes reveal anything about the stop row. `scanned` is for trusted host\naccounting and must not be sent to clients; a short page with a cursor tells\na caller only that unlisted rows exist, never which.\n\nNewest-first paging relies on `intake_items_received_idx`\n(`tenant_id, confidential_scope_id, created_at, id`), the full ordering key, so\nan unfiltered page is a backward index scan that stops at the page boundary;\nthe foundation suite asserts that plan on both engines (SQLite\n`EXPLAIN QUERY PLAN`, PostgreSQL `EXPLAIN`), with the per-row state counters\nserved by `intake_actions_item_idx`. On SQLite the page query pins the index with `INDEXED BY` (except under an\nid restriction, where direct id lookups are cheaper), because without planner\nstatistics SQLite otherwise picks `intake_items_expiry_idx` plus a sort; the\nSQLite plan check runs without `ANALYZE`. A deployment must have applied the\nmanifest migration, or the page query fails with a missing-index error. This package ships no\nmigration files: indexes are declared on the model, the build emits them into\n`dist/manifest.json`, and `smrt db:migrate` / the public migration API create\nthem, which is how `intake_items_receipt_idx` shipped. Deploy the manifest\nmigration before upgrading hosts; `db:status --parity` reports the index as\nmissing until then.\n\nSupply four application adapters: `upload(files, requestId)` (authenticated\nreceipt plus first extraction request), `assignment(itemId)` (durable read),\n`assign(input)` (manager authorization, eligible assignees, durable CAS and request\nreplay protection), and `evidence(part)` (safe label/text or authenticated\nsame-origin URL), which `load` calls for every part and `list` never calls;\n`load` sets no row preview on its entry.\n\nRow previews are opt-in through an optional fifth adapter,\n`rowEvidence(rows)`. When it is supplied, `list` reads the page's durable\nevidence metadata with one `service.listEvidence(itemIds)` query (at most 100\nids; items the scope cannot read, and expired or inactive items, are omitted\nwithout disclosure; the host `authorize` runs once per distinct captured\nceiling through the same gate as `listItemsPage`, so a refusal or a\nmalformed captured ceiling hides the item and a failing `authorize` rejects\nthe page; an item whose stored data does not parse is skipped by both\n`listItemsPage` and `listEvidence`, never fatal). It then calls `rowEvidence`\nonce with each row's primary part (`{ itemId, evidence }`) and publishes the\nreturned `{ label, viewUrl?, thumbnailUrl? }` as `InboxEntry.evidence`\n(`{ evidence, label, viewUrl?, thumbnailUrl? }`, never text). Build those URLs\nfrom metadata without reading bytes; if `rowEvidence` throws or returns a\nmalformed answer, the page still lists without previews, and a row without\ndurable parts never gets one. When it is omitted, rows show no original link.\nEither way `list` reads the page's evidence metadata once, in that same query,\nso the row label can use the original filename; it never reads original bytes\nand never calls `evidence(part)`. The primary part is chosen by role, not media\ntype: the shallowest child part when any part has a parent (an upload's file\nunder its capture record, an email's first attachment under the message, even\nwhen that child is JSON), else the first root part (a watched-folder file);\npart ids sort numerically. `IntakeInbox`/`InboxView` accept an\noptional `rowAside` snippet receiving the `InboxEntry`; without it a row renders\nthe host's \"Open original\" link (new tab) and thumbnail when the URLs are\nsame-origin; each link's accessible name is \"Open original: <row label>\", and\na row shows no wrapper when neither URL is usable. The slot is a plain `div`,\nnot an `aside` landmark, so a page does not add one landmark per row. Optional\n`label(item, evidence)` changes presentation; `evidence` is the item's durable\nparts with the primary part first, and the default label is the primary part's\nown original `filename`, else `Intake <8 hex>`. Optional\n`assignments(itemIds)` reads one page's assignments in one batch (otherwise\n`assignment` runs per row), and optional `assignedItemIds(assigneeId)` lets\n`list` push the assignee filter into the page query (junk ids are dropped, not\nfatal); without it an assignee filter scans further pages and filters by\n`assignment`, which stays correct but costs more rows. The page's continuation\nis always the last row actually returned, so an assignment that changes\nbetween the page read and the assignment read costs at most one extra scan and\nnever skips or repeats a row. Optional\n`enableFeedback: true` exposes the optional feedback callback when the service\nhas feedback configured. Optional `onSplit(itemId, revision)` wakes the host worker after the durable extraction\nrequest; repair dispatches if wakeup fails. The factory creates no assignment\nschema and grants no permissions. Create it per session, authenticate every HTTP\ncall and enforce CSRF before dispatching a mutation.\n\n`GenerationAnalysisOutput` is exported by `/dto` and describes the interpretation\nwrapper `{ proposals: GenerationOutput }` under `analysis.result.output`.\nThe factory unwraps this into `ItemReviewView.generation`. Stale generation is\nomitted while authorized saved reviews remain available; access denials propagate.\nThe reference application still owns its fixture provisioning and HTTP transport.\n\n## Explicit upload retries\n\nThe inbox retains selected original files and the receive request identity when\nupload fails or acknowledgment is lost. Retry Upload explicitly with the same\nselection; Refresh does not replace that identity. Selecting files again starts a\nnew receipt identity, even when names match. Successful upload clears the selection\nand identity. Replacing the authenticated host/context or destroying the component\ndiscards both and fences late completion from the prior context. No automatic\nupload retry or authorization bypass occurs.\n\nThe inbox clears only its native file-input value when opening the picker, so\nchoosing the same local file explicitly starts a new upload identity. Opening\nthen dismissing the chooser preserves the separately retained originals and\nrequest identity for retry; it does not clear the shared FilePicker's native-form\nbehavior. Successful upload and host/context disposal still discard retry state.\n\nWorkspace ordering also protects an open item during an awaited automatic page walk:\nthe selected row remains until navigation succeeds, except that a failed list read\nclears the inbox. Applying an action is disabled\nwhile that action card holds unsent arguments, reason, or feedback comment. A list\nrefresh retires earlier follow snapshots; only follow reads started after that\npage request may override its rows, so a newer refresh cannot be regressed by an\nalready settled or older in-flight follow read.\n"
     }
   ],
   "agentSurface": {
@@ -1765,7 +1765,7 @@
         "code": "not-module-scope",
         "helper": "definePlaybook",
         "message": "`definePlaybook()` must be called at module scope to be emitted into the manifest and knowledge graph. A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.",
-        "line": 1634,
+        "line": 2373,
         "column": 9,
         "sourceFile": "src/test-support/proposals.ts"
       },
@@ -1773,7 +1773,7 @@
         "code": "not-module-scope",
         "helper": "definePlaybook",
         "message": "`definePlaybook()` must be called at module scope to be emitted into the manifest and knowledge graph. A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.",
-        "line": 2206,
+        "line": 2945,
         "column": 9,
         "sourceFile": "src/test-support/proposals.ts"
       },
@@ -1781,7 +1781,7 @@
         "code": "not-module-scope",
         "helper": "definePlaybook",
         "message": "`definePlaybook()` must be called at module scope to be emitted into the manifest and knowledge graph. A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.",
-        "line": 7353,
+        "line": 8094,
         "column": 9,
         "sourceFile": "src/test-support/proposals.ts"
       },
@@ -1789,7 +1789,7 @@
         "code": "not-module-scope",
         "helper": "definePlaybook",
         "message": "`definePlaybook()` must be called at module scope to be emitted into the manifest and knowledge graph. A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.",
-        "line": 7982,
+        "line": 8723,
         "column": 7,
         "sourceFile": "src/test-support/proposals.ts"
       }