@happyvertical/smrt-ingestion 0.55.5 → 0.55.7

package/AGENTS.md

@@ -11,6 +11,8 @@ belongs under `/server`. Generated REST/CLI/MCP model mutation is disabled.
 See [README.md](README.md) for host integration and recovery/deletion operation.
 See [EXTRACTION.md](EXTRACTION.md) for extraction contracts, provider isolation
 requirements and corpus validation.
+See [PROPOSALS.md](PROPOSALS.md) for the optional server-only proposal stage,
+current catalog/candidate authority and immutable source pinning.
 
 All records require tenant and confidential scope. Hosts create service scopes
 from authenticated sessions; source metadata is never authority. Every read and
@@ -25,9 +27,17 @@ submission never run inside ingestion database transactions.
 
 Validation: `pnpm test`, `pnpm test:postgres`, `pnpm test:providers`, `pnpm typecheck`, `pnpm build`.
 The PostgreSQL command provisions a real database and fails if unavailable.
+Fixture teardown uses `src/test-support/postgres-cleanup.ts`: only owned
+exec_/ing_/ext_/sources_ names, normal DROP, bounded 55006-only retry. Never
+force-terminate backends, grant signal privileges, or ignore leaked sessions.
 Build includes browser import validation. The provider lane exercises local SDK
 adapters and process isolation, without claiming live remote recognition quality.
-The component/e2e/evaluation
-commands are reserved by ADR 0004 and fail explicitly until their owning children
-supply real suites.
+`src/svelte` owns transport-neutral review components and browser-safe host callbacks.
+See [FEEDBACK.md](FEEDBACK.md) for revision-bound explicit feedback, scoped example retrieval,
+provider-boundary revalidation and authorized routing policy adoption.
+See [REVIEW.md](REVIEW.md) for authenticated hosts, bounded saved-review reloads,
+assignment ownership, logical split re-extraction and the maintained browser proof.
+UI validation additionally requires `pnpm test:components` and `pnpm test:e2e`;
+`typecheck` includes Svelte and `build` includes the types-first `/svelte` entry.
+The evaluation command remains reserved for #3677 and fails explicitly.
 See ../../docs/test-matrix/3670-ingestion-foundation.md for behavior coverage.

package/FEEDBACK.md

@@ -0,0 +1,117 @@
+# Explicit ingestion feedback
+
+Configure `IngestionOptions.feedback` to opt in. The existing `intake_feedback`
+ledger owns these records; no new schema, embedding service or provider is added.
+`FeedbackConfiguration` sets a version, maximum examples, scan count, serialized
+bytes and lexical similarity threshold, plus a live scoped authorization callback.
+Hard ceilings are 20 examples, 1,000 scanned records and 1 MB. Choose substantially
+smaller application limits. The proposal's complete serialized request, including
+examples, must also fit the current minimum application/source/provider budget.
+
+`recordFeedback` accepts the exact displayed action revision, review version and
+binding hash, an explicit correct/incorrect judgment, optional reason text and a
+request ID. The server resolves reviewer, tenant/confidential scope, retained
+source evidence, extraction/generation versions and current handler arguments.
+A replay returns the same immutable receipt; changed payloads conflict.
+`supersedesId` appends a replacement for the specified prior interpretation
+judgment. A second successor conflicts. Revised actions make old bindings
+ineligible. Approval and successful execution never imply that extracted fields
+are correct.
+
+Decision and downstream execution facts are captured inside their owning
+transaction, keyed by immutable event ID and signal, when the configured capture
+authority allows the optional memory projection and it fits the configured byte
+cap. Denial or an oversized automatic projection leaves the underlying
+authoritative decision/outcome intact, including failure and reconciliation.
+Explicit `recordFeedback` and `observeFeedback` requests still reject invalid or
+oversized writes; actual database failures still propagate and roll back. Failed/rolled-back domain
+work and unknown external outcomes remain distinct. `observeFeedback` can replay
+an authorized existing event; it cannot supply a correctness label or fabricate
+an execution result. An initial denial does not mutate retention. Once authorized,
+a narrowed privacy ceiling survives business rollback and later revocation.
+
+## Retrieval and provider boundaries
+
+`retrieveFeedback({ itemId, query })` derives the current offered catalog,
+candidates and model/prompt/configuration versions on the server. Callers cannot
+provide candidate authority. The deterministic matcher uses lowercase Unicode
+word-set Jaccard similarity (minimum 0.2), then immutable record ID for ties.
+Scanning, recursive provenance checks and returned examples are bounded; a limited scan does not promise an
+exhaustive history search. Both positive and negative explicit examples are kept.
+
+Every selected source must still be readable in the same tenant and confidential
+scope, with its current action/analysis binding, target grants, handler version,
+model/prompt/configuration compatibility and retention. Each source's current
+provider policy must allow the generation recipient and any configured decision
+recipient; the source owner rechecks that policy on both initial and final live
+contexts. Receiving checks cover every offered handler, before and after source
+checks, using each live grant, actual provider recipients and the narrowest byte
+ceiling. Both retrieval and reference revalidation budget the full reconstructed
+examples. A receiving item's provider grant cannot substitute for a source grant.
+Superseded, revoked, deleted or incompatible sources are excluded. Current explicit human corrections
+take precedence: a generation carrying one does not retrieve learned examples.
+
+Full examples exist only in the authorized provider request. The SDK proposal
+adapter includes that typed selection in its serialized user message when
+present; disabled feedback leaves the original request shape unchanged. Saved generation
+provenance contains the receiving query, selection configuration digest and
+immutable feedback IDs/digests, not copied source example content. Selected
+references are rechecked before generation, capability probing, decision calls,
+publication and completed-result reads. A newly added example does not invalidate
+an older selection; a revoked or superseded selected example does. Feedback
+lineage is bounded and fails closed. Saved-action reads and pending decisions,
+automatic authorization, preview publication/replay and execution also revalidate
+selected lineage under the
+owning transaction. Revoking, deleting or superseding a selected example blocks
+pending actions; regenerate their proposals and obtain fresh approval to recover.
+A preview replay checks the exact persisted proposal it returns, including its
+analysis attempt; a newer action revision cannot supply replacement lineage.
+Plan replay and final sealed plan-step publication use the same gate.
+For already successful actions, current-authorized durable outcomes remain
+readable/replayable, but invalid learned lineage suppresses saved proposal
+display, arguments and plan payload. An empty selection carries no learned source
+and does not turn optional feedback-capture denial into action denial. Examples
+never expand the offered catalog, candidate IDs, operation permissions or
+automation eligibility.
+
+All durable feedback belongs to the source item's existing retention/redaction
+lifecycle. There is no separate memory store or delayed indexing writer to clean
+up. Hosts using other derived stores still implement the existing `purgeDerived`
+contract. Core `LearningMemory` is intentionally not used here: its success/failure
+reinforcement and default ancestor-scope fallback do not represent separate
+correctness/decision/outcome signals and strict confidential-scope eligibility.
+
+## Routing suggestions and adoption
+
+`suggestRoutingRule` requires repeated current explicit positive judgments with
+from distinct source items with matching handler/version and arguments, and returns supporting immutable IDs,
+shared query terms and the policy owner's preview/version. Suggestions cannot
+execute or modify policy. `getRoutingRule` rechecks the displayed binding and all
+supporting examples. Arguments are routing preferences, never executable grants.
+
+`adoptRoutingRule` requires the exact suggestion digest and expected policy
+version plus current reviewer and adoption authority. The configured policy owner
+must perform its version compare-and-swap and audit on the supplied database
+executor. The ingestion transaction records the exact returned version/audit ID.
+Replays do not adopt twice. Revocation or permission/policy widening rolls back
+both changes. The host callback may store routing preferences only: it must not
+change grants, provider permissions or automation controls. Adoption always
+returns `automaticActionEligible: false`; subsequent proposals retain normal
+current policy and explicit review requirements.
+
+## Review UI and evidence
+
+The optional `IntakeReviewHost.feedback` callback carries the exact displayed
+revision and binding. Correct/incorrect controls are explicit and independent of
+Approve/Apply. Unsaved argument edits disable correctness controls until the
+displayed binding is current again. Hosts must authenticate that callback and connect it to
+`recordFeedback`; client-supplied reviewer/scope fields are not accepted. The
+maintained browser fixture demonstrates this transport with CSRF protection and
+rejects substituted revisions.
+
+See [the behavior matrix](../../docs/test-matrix/3676-ingestion-feedback.md) for
+validation and the frozen learning protocol. The small authored deterministic
+cohort demonstrates contract-level influence, not provider quality or measured
+production improvement. Real-provider evaluation belongs to #3677. There are no
+sampled automatic outcomes in this feature; reporting that stratum as unavailable
+avoids inventing correctness labels from successful jobs.

package/PROPOSALS.md

@@ -0,0 +1,173 @@
+# Application-aware proposal generation
+
+`@happyvertical/smrt-ingestion/proposals` is server-only. Configure
+`IngestionOptions.proposals` and the existing `execution.handlers` catalog.
+Handlers opt into discovery with `discovery.mediaTypes`, `references`, and an
+optional `candidates` callback. There is one catalog: the same operation or
+ordered playbook adapter is discovered, validated, previewed, and later applied
+by the execution service. Generation never approves or applies.
+
+## Discovery and authority
+
+`listHandlers(itemId)` returns a bounded detached catalog. The owning execution
+service checks the current principal, captured permissions/handler/operation
+ceiling, policy, confidential scope, public registered operation facts, and
+ordered playbook definition. Every configured provider must occur in the current
+policy's `providers` allowlist. Missing grants remove handlers before model input.
+An authorized catalog larger than the configured bound is rejected; the host must
+narrow it explicitly instead of relying on silent truncation.
+
+`findCandidates({itemId,handlerId,handlerVersion,query,limit})` returns
+`{items,truncated}`. Its trusted handler callback receives `HandlerContext` with
+the authorized transaction executor. Query by tenant and confidential scope
+**before** selecting, ranking, or building labels. Use a bounded query (often
+`limit + 1`) and report `hasMore`. The service projects candidate identity, model,
+revision and label, then checks every target with the owning execution callback.
+There are no hidden counts or pagination tokens. Truncated discovery forces
+`needs_review` and cannot enter generated preview.
+
+Completed generation reload checks process authority, the current attempt, and
+owner/candidate visibility in the same final transaction. Database-backed grant
+callbacks must use the supplied executor. The owning retention lifecycle encloses
+that transaction so a denied read cannot roll back an authorized shorter privacy
+ceiling; restoration starts only after the outer transaction has rolled back.
+
+Candidate callbacks perform bounded database reads only: no provider I/O, network,
+or domain mutations. Target locks and existing retention enforcement remain
+owned by execution. Hosts configure their database's statement deadlines; an
+arbitrary trusted callback is not a sandbox. Each existing-record argument must
+be a declared top-level `references` field of kind `candidate` with its qualified
+model, or `evidence`. Closed JSON argument schemas are required. The host owns
+that declaration and its target authorization semantics.
+
+## Durable stages
+
+1. Complete extraction through the existing analysis ledger.
+2. Call `prepareGeneration(itemId, extractionAttemptId)`. It reads the current
+   completed/partial immutable extraction and returns configuration with
+   `stage: 'interpret'`, pinned source attempt/revision/input/output/evidence
+   digests, prompt/configuration/catalog/provider versions, limits and thresholds.
+3. Pass that configuration to `analyze(itemId, configuration, requestKey)` and
+   claim its new revision with `claimAnalysis`.
+4. The host's existing job callback routes on the frozen `configuration.stage`:
+   extraction invokes `extractAnalysis`; interpretation invokes
+   `generateProposals(lease)`.
+5. Reload the current completed generation using `getCompletedAnalysis(itemId)`,
+   or pass an explicit attempt ID to additionally reject stale client state.
+   Queued/running revisions never return an older completed attempt.
+
+A generation revision does not rewrite terminal extraction. Reprocessing starts
+with a new extraction revision, followed by interpretation, while the host keeps
+the same business intention keys. An interrupted still-current generation lease
+can be retried; terminal generation output remains immutable. `getGenerationInput`
+reads historical extraction only through the current generation lease and its
+frozen source pin. It verifies same-item scope, immutable hashes, durable evidence,
+and current process permission before returning detached data. The source must be
+the immediately preceding revision, so an intervening reprocess invalidates a
+prepared generation. Completed generation reads additionally recheck current
+catalog and target visibility before disclosing persisted candidate labels.
+Expired, cancelled, revoked, retried or superseded workers cannot read or publish late output. The
+current lease and each offered handler/candidate are rechecked immediately before
+each outbound generative/decision boundary and before publication.
+
+## Providers and validation
+
+`createSDKProposalGenerator(client, identity, {maxTokens,timeoutMs})` uses an
+existing AI SDK `chat` client. It sends a fixed system instruction and separate
+JSON evidence/catalog data, requests JSON, supplies cancellation and bounds, uses
+no tools or continuation, and rejects known truncation or tool calls,
+unexpected models, malformed JSON and oversized output. Configure SDK clients
+without automatic retry that would bypass application boundary checks. The
+adapter's public identity is exactly provider/model/version; credentials and raw
+provider errors are never provenance.
+
+A trusted custom `ProposalGenerator` must likewise honor cancellation, bound its
+response, and explicitly declare validated `complete` or `unknown` completion.
+The SDK currently normalizes missing/unknown finish reasons to `stop`
+([owning SDK follow-up](https://github.com/happyvertical/sdk/issues/1381)), so its
+adapter conservatively declares `unknown`, persisted as
+`generation_completion_unknown`. Otherwise valid suggestions remain available
+for human preview; automatic eligibility always remains false. The service
+deadline aborts requests and prevents late publication; it does not claim to terminate computation at a remote
+provider or isolate native allocations. Extractor process limits remain separate.
+
+Model output can contain only offered handler versions, schema-valid arguments,
+retained evidence locations and offered alternative handler/candidate keys.
+Candidate IDs must occur in the offered set, and evidence IDs in retained source
+results. Unknown enums, invented IDs, extra authority/tool/approval fields and
+malformed structures fail closed. Missing required top-level fields are retained
+as `missingFields`, with `needs_review`; values are never invented to satisfy a
+schema. Observed page/time/source granularity is preserved. Logical scan splits
+use `proposeDocumentSplits`; originals and hashes remain intact.
+
+`createSDKProposalDecisionClient(client)` adapts an existing SDK client’s optional
+capability without changing its errors or protocol. Optional `decision` uses public core `executeDecision` and the existing SDK
+predicate, choice, score and batch contracts. Supported-effect predicates,
+handler classification, candidate entity matching, and action ambiguity/risk
+are distinct questions. Their validated probabilities and provenance are stored
+separately from generative provenance and unknown OCR certainty. The complete
+serialized decision request, including suggestions and questions, must fit the
+minimum configured/current policy byte ceiling before capability probing and
+again before deciding. A policy change between these boundaries fails closed.
+Ties, support probability or selected-handler confidence below
+`minimumDecisionProbability`, and actually incomplete extraction require review.
+Unknown provider
+completion metadata is preserved as `source_completion_unknown`; it does not
+block otherwise schema-valid **human** preview or imply completeness. Automatic
+action eligibility remains false. An unconfigured decision path
+is recorded explicitly. Configured errors produce a durable safe failure outcome;
+they never silently switch to a generative decision fallback.
+
+Output records zero, one or multiple suggestions, alternatives, missing fields,
+source links, proposed splits, versions, allowlisted usage, warnings and explicit
+`unknown`, `ambiguous`, `no_action`, `needs_review` or `provider_error` outcomes.
+`automaticActionEligible` is always false. Provider input/output and the complete
+serialized persisted envelope are bounded by configuration, live policy and the
+receipt ceiling. Oversized output becomes a bounded review/limit result; when
+no safe envelope fits, the owning service records fixed `failAnalysis` metadata
+outside the provider payload budget without retaining provider output.
+
+## Explicit preview and stable intentions
+
+The host chooses persisted suggestion indexes and calls:
+
+```ts
+await service.previewGeneratedProposals({
+  itemId,
+  attemptId: generationAttemptId,
+  selections: [{
+    index: 0,
+    intentionKey: 'document:meeting-2026-10-09',
+    expectedRevision: 0,
+    requestId: 'review-request-1',
+  }],
+});
+```
+
+`intentionKey` is the host's stable business-intention identity across generation
+revisions. Never derive a fresh key from model output, suggestion order or a retry.
+Selections must reference current persisted validated `ready_for_review` output.
+Each batch requires distinct suggestion indexes and intention keys; duplicate
+indexes are rejected before any operation or plan preview is written.
+The service rechecks current catalog/schema/target/source provenance, then calls
+the existing operation or plan preview. Each result still requires the ordinary
+human review and execution APIs. Reprocessing creates no new business identity;
+successful-action replay protection stays with execution.
+
+## Evidence and limits
+
+The test matrix is `docs/test-matrix/3673-ingestion-proposals.md`. SQLite and real
+PostgreSQL suites exercise authority, revisions, abstention, hostile output,
+compound proposals, split provenance and reviewed domain effects. The upload
+reference composes authenticated multipart delivery of a generated embedded-text
+PDF through the actual packaged PDF child, durable interpretation, and the existing
+ordered ContentDocument draft/retained-asset plan. It checks duplicate delivery,
+unauthenticated and foreign-tenant denial, explicit approval of both steps,
+idempotent execution replay, page provenance, and unchanged original bytes.
+The compound-email case uses a declared messages-owner snapshot fixture.
+
+Local HTTP fixtures execute the actual AI SDK transport and cancellation contract.
+Generative responses and the separate injected PDF split boundaries establish
+deterministic orchestration, not model accuracy or OCR quality. No held-out routing
+evaluation or automatic approval is claimed. Missing/unknown AI completion remains
+explicit under [SDK #1381](https://github.com/happyvertical/sdk/issues/1381).

package/README.md

@@ -146,3 +146,17 @@ raw-body reading. The callback must verify signature, delivery time/replay windo
 and account ownership, then return trusted binding and durable delivery identity.
 No vendor implementation or hardware driver is selected. All adapters invoke
 only receipt preservation, never domain writes, AI tools or external actions.
+
+See [PROPOSALS.md](PROPOSALS.md) for bounded application catalog discovery, durable
+interpretation revisions, optional typed decisions and explicit generated preview.
+
+## Human review
+
+Mount the `/svelte` inbox and review components through an authenticated host using
+the browser-safe `IntakeReviewHost` DTO contract. See [REVIEW.md](REVIEW.md) for
+exact revision-bound callbacks, live evidence access, logical split corrections,
+assignment ownership, and the maintained upload-to-domain-result browser fixture.
+
+Optional explicit feedback and scoped example retrieval are documented in
+[FEEDBACK.md](FEEDBACK.md). Approval and execution outcomes remain separate from
+interpretation correctness; routing policy adoption is explicit and versioned.

package/REVIEW.md

@@ -0,0 +1,136 @@
+# Authenticated review surfaces
+
+`@happyvertical/smrt-ingestion/svelte` exports `IntakeInbox`, `IntakeReview` and
+`EvidenceViewer`. The browser-safe DTO entry exports their `IntakeReviewHost`
+callback contract. Import styling/theme configuration from smrt-ui in the host.
+Components use smrt-ui primitives and the `ingestion.*` i18n catalog.
+
+The host authenticates every request, resolves tenant/actor/confidential scope
+from its session, enforces CSRF on mutations, and constructs `IngestionService`.
+Never accept scope, reviewer, permissions or a principal from callback JSON.
+Only supply authorized evidence URLs and escaped text; original URLs are
+same-origin authenticated handlers that recheck `readEvidence` on every read.
+Candidate discovery uses `findCandidates` with current grants. Presentation
+state and disabled buttons provide no server authority.
+
+`listReviews(itemId, {cursor?,limit?})` reloads saved action identities and their
+current plan membership without browser storage. It returns at most 50 actions,
+with an opaque action-ID cursor. Every payload requires current item, handler,
+parent plan and target access under the owning transaction. Denied reads fail
+closed. Target reads check current authorization separately from historical
+revision freshness: unfinished drift returns state-only stale reviews without
+removing unrelated entries; succeeded results remain readable after authorized
+target changes. Apply still enforces exact bound target revisions. Expired entries
+contain only review identity/state. Stale entries never disclose old args or target
+labels; an authorized parent plan additionally exposes `stalePlan` identity, key,
+current plan revision and handler identity. Hosts must collect fresh explicit args
+from the reviewer/current authorized evidence and call `previewPlan` with that
+exact plan CAS and the current completed analysis attempt. Action revision is not
+plan revision. Re-expansion preserves action identity and requires fresh approval.
+Success results are rechecked through the durable result reader.
+Plan membership contains the exact parent args/version so edits call
+`previewPlan`, not per-step correction. An item may have more review pages; the
+host must aggregate state across pages when projecting a production inbox state.
+
+The host's `load` callback supplies a current `ItemReviewView`, using
+`getCompletedAnalysis` with no historical fallback. Generated suggestions bind
+the **current generation attempt**, not `generation.source.attemptId` (the prior
+extraction). `previewGeneratedProposals` publishes exact reviews and continues to reject stale
+generation candidate pins. When `listReviews` reports `generationStale`, the host
+omits obsolete generation output and renders authorized saved reviews/results.
+Completed saved actions do not hide healthy unprepared suggestions. The saved-binding hint is not
+an authoritative generation-availability check: a fresh human preview can bind a
+current target while the immutable generation still pins its former revision.
+`getCompletedAnalysis` remains strict and throws server-only
+`GenerationSnapshotStaleError` only after every current catalog/provider/candidate
+read is authorized and an immutable candidate revision differs. The maintained
+host catches only that class, reacquires `listReviews` under current owning
+authority, and returns that new page without generation output. It never reuses
+the earlier page after an error. Denials and unknown failures propagate; healthy
+generation still exposes unprepared sibling suggestions. Stale entries expose handler
+and attempt identity only when that attempt is still the current completed/partial
+analysis. An empty-args editor submits fresh explicit human arguments through
+`previewProposal` or `previewPlan` with the saved CAS; it never reuses old generated
+arguments, rewrites the generation snapshot or transfers approval. Analysis-stale
+entries without an attempt require normal reprocessing. Approve,
+reject, defer and correct call `submitDecision`; corrected args create a new
+revision which requires a separate human approval. After an approve/defer/reject
+decision, optional `editAction` calls `previewProposal` with the current action
+revision to publish a new review; completed/executing/unknown actions cannot be
+revised. Local dirty args disable Apply but confer no authority. Plan edits re-expand through
+`previewPlan` with the current **plan** revision. `applyAction` accepts only an
+action ID. Unknown external outcomes require server reconciliation; the UI
+never offers a blind resend. Stable result IDs survive reload and retry.
+
+Replace `contextKey` whenever authenticated tenant/session context changes.
+Changing it or itemId destroys the old view and fences late callback results.
+Denied refresh clears prior originals, candidates, arguments and results.
+Missing confidence is unavailable; page/time links exist only for observed
+locations. Provider errors and unresolved/partial results remain review states.
+
+## Assignment and logical splits
+
+Assignment is explicitly host-owned, durable and versioned. `assign` receives
+an expected assignment version and request ID; the host must authorize the
+manager, constrain eligible assignees, CAS the durable record and reject stale
+writes. Assignment does not grant read, review or execution rights. The maintained
+fixture provisions its own SQLite assignment table before serving requests; no
+production ingestion table or migration is introduced for assignment.
+
+`reviseLogicalSplit` authorizes the current generation through the same-executor
+catalog/candidate gate and the existing reviewer grant and policy reviewer list.
+Process access alone cannot mint or replay a human correction; reviewer authority
+is checked before mutation and again before publication. A generation without a
+reviewable catalogue cannot be corrected through this reviewer API.
+It requires all observed pages exactly once, an exact
+current attempt/revision and a request ID. It records the authenticated actor
+and predecessor as a **human correction** in a new immutable extraction
+configuration, queues re-extraction and immediately makes previous suggestions
+and approvals stale. It never changes original bytes/evidence or labels a human
+edit as model output. The host processes the new extraction, then calls
+`prepareGeneration` and the normal fenced interpretation stage. The supported
+immediate-predecessor extraction pin is unchanged. The generator receives a
+human correction only after its digest matches the authoritative source. Ordinary
+`analyze` calls cannot mint an extraction correction; the owning split API is the
+authenticated origin, and forged interpretation corrections fail before provider
+disclosure. If its proposed grouping differs from the correction, suggestions are withheld
+with `human_split_not_respected`. New proposals require new explicit review.
+The reference host runs these stages synchronously for browser determinism;
+production hosts dispatch the existing durable analysis jobs.
+
+`feedback` is an optional explicit correctness callback, separate from approval
+choice and execution success. No learning, feedback storage or rule promotion is
+implemented by these components; #3676 owns those services. Do not pass feedback
+or a feedback callback to readers without the relevant host grant.
+
+## Maintained browser proof
+
+`pnpm test:components` runs real Svelte component tests; `pnpm test:e2e` runs the
+package-local authenticated Vite application under Chromium. The fixture uses
+HttpOnly same-site sessions, CSRF, real SQLite/assets/ingestion/content APIs,
+production unpdf child extraction and a deterministic proposal generator. Its
+hardcoded test login is fixture-only and is never a production auth provider.
+Image/audio originals remain inspectable when no OCR/speech provider is
+configured; the suite makes no recognition-quality claim and spends no provider
+budget. `reference/review-host.ts` is a maintained development fixture, not a
+published server entry. Browser tests show actual approved args and persisted
+ContentDocument results, stale tabs, reload, retries and negative access.
+
+Run full package `test`, `test:postgres`, `test:providers`, `build`, `typecheck`,
+`test:components`, `test:e2e`; use the root Node/pnpm versions. Set a short
+`CI_TEST_TMPDIR`/`TMPDIR`, and optionally
+`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to the supported installed Chromium.
+The evaluation lane remains explicitly unavailable until #3677.
+
+The existing CI browser job includes ingestion changes and shared UI primitive
+changes in affected mode, and runs the ingestion browser suite in full mode. Its
+normal dependency build precedes the suite and failed runs upload browser evidence.
+
+The maintained host derives inbox state by traversing bounded public review pages,
+authorizing every action/parent/target before classification. It retains only
+scalar totals and the requested page; an off-page denial denies the whole view.
+The component's Load more and subsequent refresh/mutation reload every displayed
+page using fresh cursors, then publish the combined authorized set together. Old
+page payloads are cleared while loading; any unavailable page clears all payloads.
+This keeps plan controls and earlier steps visible across page boundaries without
+reusing a prior authorization decision.

package/agents/execution.md

@@ -0,0 +1,132 @@
+# Review and execution integration
+
+`/execution` exports `IntakeExecutionService`, handler/host types, policy
+resolution, binding digests and `continueIntakeReview`. `IngestionService` exposes
+these operations when its optional `execution` configuration is present. Its
+loader is lazy: importing `/server` alone does not import the principal stack.
+`/dto` exposes execution messages using type-only exports. No generated REST,
+CLI or MCP mutation endpoint is enabled; applications authenticate their own
+service surface and create `IngestionScope` from the session.
+
+## Catalog and authority
+
+Applications supply a trusted `IntakeExecutionOptions.handlers` catalog.
+`OperationHandler` has qualified ID, immutable version, description, object JSON
+schemas for arguments/results, allowlisted `resultModels`, `validate`, `preview`,
+a registered `{model, action, version}` operation and explicit effect/idempotency/
+open-world capability declaration. Preview returns display, exact normalized
+arguments and target revision preconditions. There is no arbitrary tool execution
+or expression evaluation. Reviewer display wraps application fields under `preview`
+and symbolic metadata under `dependencies`; plan steps additionally wrap that
+object under `step` alongside the plan preview. Application display keys cannot
+overwrite framework metadata or be silently overwritten by it. A version change
+requires a new preview and approval.
+`PlanHandler` references a real registered playbook key and resolved definition
+hash; expansion contains only ordered operation handlers and typed earlier-step
+result references. Discovery/proposal generation consumes this catalog rather
+than creating another registry. Semantic model output is never host configuration.
+
+Authenticated receipt context captures `capturedCeiling.execution` with principal
+ID and permission/handler/operation ceilings. The execution host's `authorize`
+resolves current grants and application/tenant/source/(optional request) policy
+on the supplied executor, checking the active requester and confidential scope.
+Lists intersect, budgets minimize, review requirements OR, and disabled policy
+wins. Policy versions must change when policy semantics change. Normal operation
+requires human review; machine authorization requires explicit evaluated opt-ins
+at all three authority layers and remains separate provenance from human review.
+The reference handlers always require review; no evaluation claim is made here.
+
+`mutationBoundary: 'serialized'` is an explicit host guarantee, not an inferred
+property of a permissions array: grant revocation must serialize with the supplied
+transaction, or the owning mutation must revalidate under its own lock. The host
+must implement that guarantee before enabling handlers. `assertTarget` similarly
+locks current tenant/confidential ownership and revision against concurrent
+writers using the supplied executor. The reference host demonstrates a scoped
+row lock before public `Contents` reads. A current `PrincipalRun` intersects live
+permissions with the captured ceiling and checks the exact registered collection
+operation at every effect. No `runOnce` atomicity is assumed.
+
+## Durable review and effects
+
+Preview appends a proposal bound to exact analysis attempt/evidence, handler,
+arguments, policy and target preconditions. Decision requests use unique durable
+request IDs; reusing an ID with changed content is rejected. First valid review
+wins under the item lock. Corrections append a new revision; reject/defer remain
+non-executable. Plan corrections use re-expansion. Human decisions expire and
+live authority is checked again before each step. Raw foundation proposals cannot
+bypass execution's schema, preview, evidence and approval verification.
+
+Database handlers must use `context.db` for every domain effect and must perform
+no external I/O. Domain result and successful execution commit together. A domain savepoint rolls failed effects
+back while preserving the item lock and atomically consuming the retry attempt. Completed
+actions survive job cleanup and evidence retention; expired originals leave a
+minimal result digest tombstone, preventing a second effect. Active result reads
+recheck host visibility and result target ownership.
+
+External handlers reserve a stable action idempotency key before submission.
+Timeout, process death or ambiguous outcome requires reconciliation; an expired
+lease never means permission to resend. `reconcile` must return authoritative
+`succeeded`, `not_applied` or `unknown`. `not_applied` is safe only when the provider
+can exclude a late acceptance of the original send; uncertainty stays `unknown`.
+The same key is reused after a conclusive non-application. Cancellation prevents
+pending work but cannot retract a send already issued. Applications must arrange
+provider reconciliation before privacy retention removes the binding; a redacted
+unknown action fails closed and cannot automatically execute again.
+
+Each plan step has a stable action identity. Completed steps are immutable and
+return their original result. Symbolic record IDs bind to exact earlier proposal
+revision, successful result digest/model and target revision; they cannot point
+across items or form cycles. Failed dependent steps never repeat predecessors.
+The plan preview and target preconditions are part of its digest and visible in
+each step review; changed preview/preconditions require a fresh review.
+Abort/continue follows the pinned public playbook definition, with fresh authority
+at every step.
+
+`continueIntakeReview` uses the existing jobs continuation context. Applications
+create tasks with owner, tenant and exact `{recordId, revision, inputKey}` binding
+and configure `authorizeMcpTask` to revalidate it. A continuation answer only wakes
+the task; the service reloads the authoritative decision. Waiting persists without
+an occupied worker and survives runner restart.
+
+## Deployment and evidence
+
+Apply normal manifest migrations before runtime. Execution imports the public
+agents/users principal stack, which registers profiles including `ProfileAsset`;
+execution-enabled hosts must migrate their dependency graph (including profile
+asset joins used by asset deletion). `/server` receipt-only imports register none
+of these additional models. Content is not a runtime dependency of ingestion.
+`reference/handlers.ts` is an application/test fixture, excluded from published
+entries and declarations; importing it deliberately adds Content and its asset
+joins, whose migrations the application then owns. No runtime DDL is performed.
+
+Real SQLite and PostgreSQL execution suites exercise the public Content draft and
+attachment APIs, transaction rollback, actor/context denials, simultaneous applies
+and reviewers, retention replay, external process death and actual TaskRunner
+restart. See the issue 3674 test matrix for the complete release evidence mapping.
+
+## Layered retention and request automation
+
+Every automation-bearing policy layer, including an optional request layer, must
+match the evaluated version. An absent request automation block adds no evaluator
+restriction; it cannot replace the three required application/tenant/source opt-ins.
+
+Authorized execution-policy access monotonically narrows the existing intake
+expiry to `min(existing expires_at, item.created_at + resolved retentionMs)`.
+The anchor is receipt creation, never review, retry or replay time. A longer later
+policy never extends a recorded deadline. This hard maximum applies to the whole
+intake item: the existing `sweepRetention` protocol removes retained originals and
+derivatives, preserving replay identities. No second expiry column or hidden clock
+is introduced, and no blob I/O occurs in an execution transaction.
+
+At an observed expired deadline, execution reads/completions erase proposal,
+decision, execution, plan, action and feedback payloads under the item lock. Review
+reads return existing identity/hash fields with `state: 'expired'` and empty
+`display`; completed action replay returns its digest-only tombstone. Failed writes, including ordinary validation/CAS/policy rejection and domain
+savepoint rollback, cannot roll back an already-authorized retention ceiling or
+redaction. Restoring a recorded authorized maximum needs no new content-read grant;
+later revocation cannot undo it. Initial denied authorization records no intent.
+Completed replay checks the deadline again after target authorization
+callbacks before returning cached content. Proposal publication and automatic
+authorization also recheck after preview/evaluator callbacks, before publishing
+retained proposal or decision payloads. Unknown
+external outcomes remain unknown/reconcile-only, never eligible for blind resend.