@happyvertical/smrt-ingestion 0.57.20 → 0.57.22

package/FEEDBACK.md

@@ -30,6 +30,110 @@ 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.
 
+Observed `action_decision` events carry the decision's `decisionMode`
+(`review` or `review_own`) and `selfDecision` flag from the durable decision
+record; `selfDecision` is true whenever the decider submitted the item, in
+either mode. A submitter confirming their own proposal (#4085) is observed as a
+decision by that actor, never as reviewer correctness evidence; consumers that
+derive reviewer agreement must exclude `selfDecision: true` events, and nothing
+in this package turns them into automation eligibility.
+
+## Reviewer routing choices
+
+A `reviewer_routing` record is appended inside the owning transaction when
+feedback is configured and `capture` is authorized, at the moment the choice is
+final: `resolveItem` (REVIEW.md) records `choice: 'none'` keyed
+`routing:<requestId>`, and `submitDecision` records `choice: 'handler'` keyed
+`routing:<decision requestId>` when a reviewer **approves** a reviewer-selected
+action. Handler-choice capture requires `mode: 'review'`: a `review_own`
+submitter approval authorizes normally but appends no reviewer-routing example or
+rule support. A reviewer using the reviewer path may still record an explicit
+routing choice for their own receipt; it does not judge any model suggestion.
+Starting an action records nothing; rejecting or deferring it never produces an
+example. The record needs no model suggestion: it binds the current
+completed/partial attempt (`attemptId`, output digest, analysis revision, frozen
+evidence hashes and the extracted text as `query`), the acting reviewer
+(`reviewer`, also `approvedBy` for a handler choice), the actor who started the
+action (`startedBy`), the start reason, and for a handler choice the
+`handlerId@version`, exact approved arguments and the approved action binding
+(revision and binding hash). Denied or oversized capture, an unavailable source
+pin or malformed evidence skip the projection and leave the authoritative
+decision or disposition intact; database write failures still roll everything
+back. There is no
+supersession: a correction after approval (`previewProposal` on the current
+revision) changes the revision, which retires the old record from retrieval and
+support until the new revision is approved and captured again; a correction
+before approval records nothing until that revision is approved.
+
+Settledness is a selection-time condition. Once a generation used an example,
+or a rule suggestion stored its support, the lineage re-checks (reading the
+generation, reviewing or deciding its actions, reading or adopting the rule,
+and replaying `suggestRoutingRule`, which returns the stored suggestion) verify:
+
+- every record: its digest, that it is not superseded, retention (no
+  redaction or deletion), the unchanged source attempt digest and frozen
+  evidence hashes, and live `retrieve` authority in the same tenant and
+  confidential scope with every generation recipient allowed by the source's
+  provider policy;
+- an `interpretation` record (unchanged from #3676): its action's current
+  revision, binding hash, attempt, handler@version and arguments; the action's
+  target preconditions at their recorded revisions unless the action
+  `succeeded`; the prompt, configuration and model versions; and that the action
+  is not reviewer-selected;
+- a `reviewer_routing` record with `choice: 'handler'`: its action's current
+  revision, binding hash, attempt, handler@version and arguments, that the
+  action is still reviewer-selected, and that its targets are still accessible
+  (not their revisions: the record means the handler choice, not target state);
+- a `reviewer_routing` record with `choice: 'none'`: it has no action, so the
+  source item is re-checked under the first currently offered receiving handler
+  that still authorizes it.
+
+Rule support (`suggestRoutingRule`, and on read, adoption and replay of a stored
+suggestion) additionally requires: at least two records from distinct source
+items; `judgment: 'correct'` with matching prompt/configuration/model versions
+for an interpretation record; `choice: 'handler'` for a routing record; each
+record's handler@version equal to the receiving binding's; and each source's
+live routing projection (or full arguments when no projection is configured)
+equal to the receiving action's. Settledness of a routing source is checked only
+when the support is first selected.
+
+A later disposition, approval lapse, outcome change or target write of a routing
+source never revokes it.
+
+Retrieval scans `interpretation` and `reviewer_routing` records together under
+the same bounds and lexical matcher. A routing example is returned only when its
+digest verifies, its attempt and evidence hashes are unchanged, the source item
+is still readable in the same tenant and confidential scope, every generation
+recipient is allowed by the source's live provider policy, and (for a chosen
+handler) the action is still reviewer-selected and settled — applied
+(`executing`, `succeeded`) or `authorized` with an unexpired approval, on an item
+without a disposition — its binding is still the current revision, and the handler with its candidate
+references is currently offered to the receiver. A `none` choice is
+revalidated under the first currently offered receiving handler the source item
+authorizes. Routing examples carry `kind: 'reviewer_routing'`,
+`judgment: 'correct'`, `routing: { choice, reason }`, `handlerId: 'none'` with an
+empty action for closed items, and no model/prompt/configuration versions, since
+no suggestion was judged. They are included in provider input and selection
+provenance exactly like interpretation examples and are rechecked by the same
+lineage gates.
+
+`suggestRoutingRule` accepts `reviewer_routing` support only for `choice: 'handler'`
+records whose action is settled in the same sense when the support is chosen
+(a lapsed, unapplied approval or a disposition excludes it) and whose handler, version and
+full arguments match the receiving binding and each other, from distinct source
+items, under the live routing projection; `none`, rejected, deferred and
+re-corrected records never support a rule. Suggestions and adoptions keep every existing #3676
+rule: no catalog, candidate, permission or automation expansion, and
+`automaticActionEligible: false`. Reviewer-selected actions themselves are refused
+by `authorizeAutomatic`. They are routing choices, never labels for a model
+suggestion: `recordFeedback` refuses an interpretation judgment on one (even
+when the item also carries a generation, and whatever its decision), retrieval
+and rule support ignore interpretation records bound to one, and `ActionReview`
+hides the correctness buttons for them. A disposition says nothing about
+whether a suggestion was right, so interpretation judgments on a resolved item
+still count. Only
+`startReviewerAction` mints that origin; `createAction` refuses it.
+
 ## Retrieval and provider boundaries
 
 `retrieveFeedback({ itemId, query })` derives the current offered catalog,
@@ -51,6 +155,39 @@ 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.
 
+A judgment recorded on an action whose generation ran under a reviewer
+instruction (REVIEW.md) stores only a reference, `instruction: {id, digest}`,
+after verifying the generation's provenance against the authenticated
+extraction record. **Write side:** the reference is ~100 bytes, so instruction
+text never counts against the judgment's write budget (`feedback.maxBytes` /
+`policy.maxBytes`) and cannot make `recordFeedback` fail with `Feedback
+limit`. `retrieve` re-verifies the source record and joins the text, returning
+`{id, digest, text}`; a stored reference that no longer matches the source's
+record excludes the example. Because one long instruction joined at read time
+could otherwise push every selection that ranks it over budget and deny
+generation scope-wide, `recordFeedback` also builds that single joined example
+exactly as `retrieve` would and refuses with `Feedback instruction exceeds
+retrieval budget` (nothing is written) when it alone exceeds
+`min(feedback.maxBytes, handler policy.maxBytes)`. An example that fits exactly
+records and retrieves. **This guard covers only the single-example case** on the
+judged handler's own budget: retrieval still sums up to `maxExamples` examples
+and takes the minimum across *every* offered handler of the receiving item, so a
+multi-example selection, or a receiving item with a narrower handler budget, can
+still exceed the budget and fails closed as below. It is returned as part of the example so comparable later items see the guidance
+that produced the judged suggestion. It is example content only: it does not
+transfer to the receiving generation's configuration or prompt section, and it
+expands no catalog, candidate, permission or automation eligibility. **Read-side budget
+impact:** joined instruction text (up to 4,000 characters, more bytes for
+non-ASCII) counts toward the exact serialized selection budget — the narrowest
+of `feedback.maxBytes` and each offered handler's `policy.maxBytes` — like any
+other example field. The existing fail-closed rule is unchanged: an over-budget
+selection rejects with `Feedback limit` and generation records
+`provider_error` without provider I/O; examples are not silently trimmed. Hosts
+that enable reviewer instructions together with feedback should size
+`feedback.maxBytes` (and the policy ceilings) for at least
+`maxExamples × (4,000 characters of instruction + the example's own fields)`,
+or lower `maxExamples`.
+
 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

package/PROPOSALS.md

@@ -32,7 +32,8 @@ the authorized transaction executor. Query by tenant and confidential scope
 `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.
+`needs_review`; a person may still preview it explicitly, and automation never
+becomes eligible.
 
 Completed generation reload checks process authority, the current attempt, and
 owner/candidate visibility in the same final transaction. Database-backed grant
@@ -64,6 +65,12 @@ that declaration and its target authorization semantics.
    or pass an explicit attempt ID to additionally reject stale client state.
    Queued/running revisions never return an older completed attempt.
 
+`analyze` refuses an interpretation configuration whose pinned source is not
+the item's latest extraction, checked under the item lock before anything is
+superseded (`GenerationSourceStaleError`, nothing appended). A preparation
+superseded by a later extraction therefore fails at append time rather than
+after a revision was created.
+
 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
@@ -78,6 +85,25 @@ Expired, cancelled, revoked, retried or superseded workers cannot read or publis
 current lease and each offered handler/candidate are rechecked immediately before
 each outbound generative/decision boundary and before publication.
 
+### Inline interpretation
+
+Receipts created with `dispatch: 'inline'` (text/structured parts only) run the
+same stages in-process through `interpretInline(itemId, { requestId, extraction
+})`: an immutable extraction revision claimed under a fenced lease and extracted
+with the built-in UTF-8 extractor, then `prepareGeneration` and a fenced
+interpretation revision generated by `generateProposals`. The analysis lease,
+catalog digest and live catalog/candidate checks, source pin, provenance and
+`StageFailure` categories are identical to the job path; no dispatch intent is
+ever deliverable and nothing is enqueued. A retry with the same `requestId`
+replays the recorded revisions rather than re-preparing against a superseded
+source, also under concurrency. The interpretation append rechecks, under the
+item lock, that its pinned extraction is still the latest revision and refuses
+a superseded pin: first through the general latest-extraction check that
+every interpretation append runs (`GenerationSourceStaleError`), then by the
+inline check that the pinned attempt is still current (`Generation source changed`). Generated suggestions still require explicit preview and a human
+decision, either through the reviewer surface or the submitter-scoped surface
+described in [REVIEW.md](REVIEW.md).
+
 ## Providers and validation
 
 `createSDKProposalGenerator(client, identity, {maxTokens,timeoutMs})` uses an
@@ -99,6 +125,33 @@ 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.
 
+When the pinned extraction carries an authenticated reviewer instruction
+(REVIEW.md), `prepareGeneration` copies it into the interpretation configuration
+and `generateProposals` verifies that copy against the extraction record and its
+own digest before provider disclosure (`integrity` otherwise). The prompt then
+carries it in its own **trusted reviewer guidance** section after the fixed
+system instruction and handler contract: the guidance is named as authenticated
+human input, limited to the offered catalog, and the evidence remains untrusted
+data. `GenerativeProposalInput.reviewerInstruction` exposes `{id, text}` to custom
+generators; `provenance.reviewerInstruction` records `{id, digest}`. The
+instruction never changes `offered`, `catalogDigest`, argument schemas,
+permissions or `automaticActionEligible`; a reply that follows guidance outside
+the catalog fails validation like any other hostile output. **Budget cost:** the instruction counts once against the input budget
+(`maxInputBytes`, each offered handler's `maxBytes` and the live policy
+ceiling), as its JSON-escaped text inside the prompt's guidance section — up
+to 4,000 characters plus escaping and the fixed guidance sentence. The
+`reviewerInstruction` field duplicated for custom generators is not counted
+again. The decision stage also carries it once: its request state holds the
+evidence-side input with the un-guided base instructions under `evidence`, and
+the guidance only under a separate `reviewerGuidance` key, never under
+`evidence`; the decision budget measures that serialized request as sent. Size `maxInputBytes` with that headroom. Learned examples are
+still retrieved for an instructed generation; only a logical split correction
+suppresses them. Every instruction costs a fresh extraction revision before the
+new interpretation: the predecessor-pin contract above (source = immediately
+preceding revision, current-revision reads) is deliberately left intact rather
+than reused for a same-source second interpretation, so OCR/speech hosts budget
+one extraction per instruction, as for split corrections.
+
 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
@@ -108,6 +161,26 @@ 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.
 
+A rejected reply ends the attempt as `provider_error` with the `malformed_output`
+warning and a bounded, value-free `provenance.failure` `{category, reason}` (#4207).
+The reason lists schema-owned paths, keywords and schema constants, for example
+`/outcome enum (allowedValues=proposals|unknown|...)` and
+`/suggestions/0 required (missingProperty=evidence)`, or the fixed internal check
+and its path, such as `Unoffered handler: /suggestions/0`. Path segments are
+kept only when they are keys declared under the schema's `properties` or
+indexes into a value that actually is an array in the rejected reply; any other
+segment, numeric or not (for example a key under an open
+`additionalProperties` argument sub-schema, or a numeric key of an object),
+becomes `?`, and an extra property's name is never echoed.
+It never contains document text, argument values, evidence content or
+model-chosen keys, is cut at 1000 characters,
+and is dropped before the output-limit fallback. Hosts read it from the
+completed/partial analysis at `analysis.result.output.proposals.provenance.failure`.
+The SDK adapter constrains replies with a `json_schema` response format built
+from the validator's schema and the fixed instructions describe the shape; a
+custom `ProposalGenerator` receives no schema, so its raw reply meets the
+validator directly and the same reason is recorded.
+
 `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,
@@ -117,15 +190,76 @@ 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
+Actually incomplete extraction always requires 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.
 
+### Decision readiness gate (#4209)
+
+For every suggestion `i` the request asks `supported_i` (predicate),
+`route_i` (choice over the offered `handlerId@version` keys plus `none`),
+`risk_i` (ordered score over `clear`, `uncertain`, `ambiguous`) and one
+`entity_i_<field>` choice per candidate-reference argument. The validated
+answers are always persisted under `provenance.decision.answers`. With the
+default `decisionReadiness: 'gate'` they are read as follows, and any failing
+check sets the suggestion to `needs_review` (a tie also sets the outcome to
+`ambiguous`):
+
+- `supported.probability >= minimumDecisionProbability` (default `0.8`).
+- `route.choice` equals the suggestion's own `handlerId@handlerVersion`,
+  `route.confidence >= minimumDecisionProbability`, and the gap between the two
+  largest route probabilities is greater than `tieMargin` (default `0.1`).
+- `risk.score < 1`: only the `clear` level passes; `uncertain` and `ambiguous`
+  require review.
+- Each entity match chooses the suggested candidate's key with confidence at or
+  above the threshold and a gap above `tieMargin`.
+
+These values are provider outputs read as if they were calibrated
+probabilities; nothing in this package calibrates them for this use. The
+teamworks-os measurement in #4209 (self-hosted Laya `typed-decisions`) found no
+separation between right and wrong suggestions: a correctly read vendor invoice
+scored `supported` 0.37, garbage input 0.45–0.50, a wrongly proposed purchase
+order 0.51, route confidence 0.003–0.15 and `risk` ≥ 0.94, so the gate sent
+every suggestion to review. Until a labelled sample shows separation, treat the
+answers as diagnostics and configure:
+
+- `decisionMaxLen`: positive integer forwarded unchanged as the per-request
+  `maxLen` of the decision client (the SDK Laya provider's token window; the
+  checkpoint default is 1024 and the serialized evidence plus suggestions is
+  otherwise truncated). Other clients ignore it.
+- `decisionReadiness: 'record'`: the decision still runs, is bounded and
+  authorized exactly as before and its answers, usage, `readiness` and `maxLen`
+  are recorded, but the gate never changes `outcome` or `disposition`; readiness
+  comes from the validator alone (`missingFields`, outcome, source completeness).
+  A client error or timeout is recorded as the `decision_unavailable`
+  warning. A reply that comes back and then fails the core `executeDecision`
+  identity or answer-shape check is recorded as `decision_malformed` with the
+  reply's usage; this is the path for injected `DecisionClient`s. SDK clients,
+  including the Laya provider behind `createSDKProposalDecisionClient`,
+  validate the reply's shape inside `client.decide` and throw, so a malformed
+  SDK reply is recorded as `decision_unavailable` with no usage. Every case
+  records the `provenance.decision` identity. The generated suggestions stay
+  as they were. The serialized request exceeding the byte budget is a
+  configuration failure, not a provider answer: it ends the attempt as `limit`
+  in both modes, and in `gate` mode every failure above still ends the attempt
+  as `provider_error`. Lease, catalog, policy and provider-allowlist revocation
+  fail closed in both modes.
+
+Successful output also records `provenance.decision.readiness` (`'gate'` or
+`'record'`) and `maxLen` when set; configuration digests are unchanged, but
+persisted output is therefore not byte-identical to earlier releases.
+
+Both settings are public configuration: they are part of
+`ProposalReadConfiguration`, the frozen `GenerationStageConfiguration.proposals`
+(present only when set, so existing digests are unchanged) and the completed
+snapshot authority check. Invalid values fail at proposal service construction.
+Neither mode affects automation: `automaticActionEligible` stays `false`, and
+`authorizeAutomatic` reads only the host's `evaluateAutomatic` callback and
+policy, never these answers.
+
 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.
@@ -154,7 +288,14 @@ await service.previewGeneratedProposals({
 
 `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.
+Selections must reference current persisted validated `ready_for_review` or
+`needs_review` output (#4208); a `provider_error` attempt, an unoffered handler or
+a non-interpretation stage is rejected. A `needs_review` suggestion whose
+`missingFields` are still absent fails the handler schema inside the ordinary
+preview (`Invalid handler payload`) and publishes nothing; the reviewer supplies
+the missing values through the explicit human path (`previewProposal` /
+`previewPlan`, as the published review host does for `preview({args})`), and the
+handler's `validate` and `preview` run again on the completed arguments.
 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

package/README.md

@@ -10,7 +10,25 @@ methods through their authenticated application transport.
 
 Before starting a service, deploy the package manifest through the public s-m-r-t
 migration APIs or `smrt db:migrate`. `assertReady()` only checks existing tables.
-SQLite and PostgreSQL are supported; other engines fail construction.
+SQLite and PostgreSQL are supported; other engines fail construction. Index
+additions ship the same way: `intake_items_received_idx` (newest-first inbox
+paging on `tenant_id, confidential_scope_id, created_at, id`) is declared on the model and reaches existing deployments through the
+next manifest migration; there are no hand-written migration files in this
+package, and `smrt doctor --db` / `db:status --parity` report the index until
+it is applied.
+
+`listItemsPage({ limit?, cursor?, state?, itemIds?, scanLimit? })` returns
+`{ items: [{ item, state, cursor }], scanned, nextCursor? }`: one authorized
+inbox page newest receipt first with each row's durable inbox state and
+continuation cursor, and the number of rows the call examined. `listItems()`
+remains as a deprecated array-returning method that walks the private page
+scan to the end. Without the optional `cursorKey` service option every cursor
+names the last row the actor can read, and a page that finds no readable row
+within its scan limit fails with `IntakeScanLimitError`; with a server secret
+of at least 32 bytes, cursors are sealed and such a page resumes past what it
+skipped. `scanned` is for host
+accounting only. See [REVIEW.md](REVIEW.md) for the paging and authorization
+contract.
 
 A host supplies a database, AssetRuntime, authenticated tenant/actor/confidential
 scope, a live authorization callback, a registered jobs target, and an idempotent
@@ -20,7 +38,29 @@ transaction executor; it must intersect current grants with that ceiling. Never
 construct the scope, retention policy or budgets from incoming document labels.
 
 `receive` accepts bounded original byte buffers, with stable source part IDs,
-parent relationships and optional upstream identity/version. Source adapters own
+parent relationships, optional upstream identity/version and an optional
+original `filename` (kept for labels on `IntakeEvidenceDTO.filename`, never
+part of receipt identity). The multipart upload source, email attachments and
+the watched folder all supply it, as may a host `snapshotReference` part or a
+vendor webhook's verified parts. Every source delivers through one place that
+removes control, format (bidi, zero-width, tag), line-separator and
+default-ignorable characters (Unicode properties, see
+`src/presented-filename.ts`) and drops a name that is then empty or over 512
+characters, so an odd name falls back to the default label instead of failing
+the receipt (`receive` itself rejects such a name from a direct caller as
+`invalid`, and names are cleaned again when read back). Removing every format
+and default-ignorable character has display-only effects, since nothing uses
+the name as identity: emoji ZWJ sequences and presentation selectors flatten,
+ZWNJ/ZWJ are removed from Persian and Indic text (letters may join
+differently), and ideographic variation selectors are removed (a CJK variant
+shows its base glyph). Unicode normalization
+(NFC/NFKC) and confusable look-alike characters are out of scope: the name is
+still untrusted text, so render it as text, never as markup or a path. The
+upstream `sourceReference` is stored but not exposed on the DTO: its ids are
+upstream locators, not display text, and they are never cleaned. For email
+they are the provider's message locator (plus the attachment part id); for the
+watched folder the id is the raw folder entry name, whose cleaned form is what
+`filename` exposes. Source adapters own
 streaming and upstream snapshot retrieval. Receipt identity is tenant + source +
 delivery key; changing bytes or authenticated scope conflicts. Content equality
 in a different conversation does not deduplicate an arrival. The returned item
@@ -157,11 +197,22 @@ Mount the `/svelte` inbox and review components through an authenticated host us
 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.
+`IntakeWorkspace` puts the inbox, the selected item with its original inline,
+the message box and approve-and-advance on one page with keyboard next/previous;
+it uses the same callbacks and adds no authority (REVIEW.md, "Single-page triage
+workspace").
 
 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.
 
+Reviewers can start any offered handler for an item (`startReviewerAction`) or
+close it as handled without action (`resolveItem`); the published host adapter
+wires both as `startAction`/`resolve` and exposes the offered `catalog`. Hosts
+with their own transport add the two POST operations behind the same session,
+CSRF and reviewer checks as `decide`. The `intake_dispositions` table requires
+a manifest migration before upgrading.
+
 ## Recipe preview
 
 `ingestion.inbox` and `ingestion.review` declare the user-facing inbox and
@@ -208,6 +259,121 @@ and `maxSuggestions` are each capped at 20; `timeoutMs` is capped at 2147483647.
 Invalid limits are rejected when constructing `IngestionService`, before receipt
 or interpretation. See [REVIEW.md](REVIEW.md) for the published server review host.
 
+## Trusted internal sources
+
+A host with a trusted internal source, such as chat messages recorded in
+smrt-messages, can receive **by reference**, interpret **inline**, and let the
+**submitter** confirm their own proposal (#4085). None of these modes changes
+copied receipts: their identity, validation, queueing and retention are
+untouched, and a replay that switches mode conflicts.
+
+**Receive by reference.** A part may be `{ partId, reference: { owner, id,
+version? }, snapshot: { text } | { structured } }` instead of bytes. The
+service derives UTF-8 bytes once (`text/plain` or canonical `application/json`;
+text, reference fields and owner identity containing NUL or unpaired
+surrogates are rejected `invalid` on every engine, and `expireOwned` refuses
+them, so distinct owners can never collapse onto one stored key),
+hashes them into the receipt identity, and stores only that snapshot in the
+durable evidence row; no AssetStore object or asset record is created, and
+`readEvidence` serves the snapshot after the same hash/length check. The
+reference is identity and provenance, never authority. Such parts must be
+text or structured; files still arrive as copied bytes.
+
+**Owner-bound retention.** `retention: { kind: 'owner', owner: { kind, id },
+version, expiresAt, replayUntil, acceptAfter }` binds the receipt to its
+owner's lifecycle. The time deadlines remain required and validated exactly as
+before: they are the hard privacy ceiling, and `sweepRetention` and execution's
+policy ceiling still apply. When the owner is deleted the host calls
+`expireOwned({ kind, id })` from its deletion path; every active receipt bound
+to that owner is revoked and removed through the existing `expire` /
+`repairDeletions` protocol, which redacts the snapshot together with every
+other payload, and the deleted delivery is never re-admitted. The owner key is
+recorded in the indexed `owner_key` column (`<kind>:<id>`, so `kind` cannot
+contain `:`). Deletion redaction blanks `owner_key` and `submitter_id` together
+with every payload: only the receipt identity (`delivery_key`) and the captured
+ceiling survive, and the ceiling loses `execution.principalId` unless an
+external action is still `executing` or `outcome_unknown`. So once nothing is
+left to reconcile, a redacted row no longer links an owner to an actor, and a
+repeated `expireOwned` finds nothing. Redaction also overwrites every
+identity- or content-derived digest (`payload_digest`, `scope_digest`, analysis
+`input_digest`, attempt `output_digest`, plan `digest` and proposal, decision
+and execution `binding_hash`) with the fixed marker `redacted`; successful
+result digests remain as the replay tombstone. The principal is retained only
+for an external action that was still in flight when the item was redacted,
+because reconciling it authorizes under that principal; it is dropped when that
+reconciliation reaches a final state, or by the next `repairDeletions` /
+`sweepRetention` pass. For a self-approvable receipt the principal is the
+submitter, so until then it identifies the sender. Later deletion sweeps pass
+this redacted ceiling to the host's `authorize({ operation: 'delete' })`, so
+delete authorization must not depend on `execution.principalId`: a host that
+requires it would refuse, and the sweep would stop with later deletion intents
+still pending. A successful result digest
+is a plain SHA-256 of the canonical result, so it can confirm a guessed result:
+keep handler results to record ids or opaque references, never content.
+
+A replay of a deleted delivery is rejected and never becomes fresh work. While
+deletion is still pending it returns `rejected/expired`; once redaction has
+completed the identity digests are gone, so it returns `rejected/conflict`.
+Sources treat both as terminal and must not retry. `delivery_key` stays in plaintext because it is
+the unique receipt identity and the package holds no secret to key it: hosts
+must use an opaque value (for example a random UUID recorded with the message)
+and must not encode owner ids, sender ids or content in `deliveryKey`.
+
+Host ordering for owner deletion: first stop issuing receipts for the owner,
+then call `expireOwned`, and call it again once in-flight receipts settle (or
+from a periodic sweep). A receipt still in flight when its owner is expired
+returns `{ kind: 'rejected', category: 'expired' }` rather than `accepted`, but
+one that reserved its row after the first `expireOwned` is only found by the
+later call; until then the time ceiling bounds it. Services are confidential-scope bound, so
+a host whose owner has receipts in several confidential scopes calls
+`expireOwned` from each scope's service; a foreign tenant or scope sees zero.
+
+**Inline mode.** `receive({ ..., dispatch: 'inline' })` requires text/structured
+parts only, records the route provenance but **no deliverable dispatch intent**
+for any revision (every intent is retained as `completed`, so no worker or
+`repairDispatches` ever picks it up), and does not enqueue. The host then calls
+`interpretInline(itemId, { requestId, extraction: { configurationRevision,
+limits } })`, which runs in-process exactly what the job path runs: an
+immutable `stage: 'extract'` revision claimed under a fenced lease and
+extracted with the built-in UTF-8 extractor, then `prepareGeneration` and the
+`stage: 'interpret'` revision with the same analysis lease, catalog-live
+checks, provenance and failure categories as `generateProposals`. A retry with
+the same `requestId` replays the immutable revisions, including when two
+identical calls race. The interpretation is appended under the item lock only
+while its pinned extraction is still the latest revision; if another request
+reprocessed the item meanwhile it fails with `GenerationSourceStaleError` (the
+general latest-extraction check every interpretation append runs, #4228) or,
+for a pin whose extraction attempt was replaced, `Generation source changed`. The result reports each
+stage's attempt and safe error and, when generation completed, the authorized
+`getCompletedAnalysis` snapshot. Inline is for send-triggered suggestions that
+must not depend on the scheduler; it is not a bypass of review or execution.
+
+**Submitter-scoped approval.** The service records `submitter_id` as the
+authenticated `scope.actorId` of the receiving service, server-side; payload
+and source metadata never supply it. `listOwnProposals({ cursor?, limit? })`
+lists only this actor's own active submissions with their saved review pages,
+reloaded under current item/handler/target authority, without the reviewer
+inbox. A submission the actor can no longer read is skipped before projection
+and never named by the cursor; a readable one whose reviews are denied by
+ingestion authority is returned as `{ item, reviews: null, unavailable: true }`
+with no reason, so one revoked grant never hides the others. `submitOwnDecision(input)` accepts `approve`, `reject` or `defer` (never
+`correct`) under the `review_own` authority: the host's execution `authorize`
+must return `submitter: true` for that actor, the application policy must opt
+in with `submitterReview: true` (narrower layers may only disable it), and the
+item's recorded submitter must equal the current actor. Every other check is
+the ordinary one, and `applyAction` remains the single once-only effect path
+under the approver's live grants. Because the effect runs as the receipt's
+captured `capturedCeiling.execution.principalId`, `review_own` additionally
+requires that principal to be the submitter itself (`submitter_id ===
+scope.actorId === principalId`), checked under the item lock at decision time
+and again at apply; a receipt captured for a bot or service principal can only
+be approved by a reviewer. The decision is recorded with `mode` (`review` or
+`review_own`) and `selfDecision`, which is true whenever the deciding actor is
+the item's submitter, in either mode (mirrored as `decisionMode` /
+`selfDecision` on feedback events), so a self-confirmation is never mistaken
+for independent review and never contributes to automation eligibility. See
+[REVIEW.md](REVIEW.md) and [execution integration](agents/execution.md).
+
 ## Dispatch route ownership and legacy recovery
 
 A receipt retains a versioned, server-owned `jobTarget` snapshot, and every