@happyvertical/smrt-ingestion 0.57.21 → 0.57.23

package/REVIEW.md

@@ -1,9 +1,12 @@
 # Authenticated review surfaces
 
-`@happyvertical/smrt-ingestion/svelte` exports `IntakeInbox`, `IntakeReview` and
-`EvidenceViewer`. The browser-safe DTO entry exports their `IntakeReviewHost`
+`@happyvertical/smrt-ingestion/svelte` exports `IntakeInbox`, `IntakeReview`,
+`IntakeWorkspace` 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.
+Existing `IntakeInbox` hosts now keep the previous rows visible, with their
+controls disabled, while a refresh or filter change loads; any failed read
+(Load more included) still clears them.
 
 The host authenticates every request, resolves tenant/actor/confidential scope
 from its session, enforces CSRF on mutations, and constructs `IngestionService`.
@@ -103,6 +106,49 @@ 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.
 
+## Submitter-scoped decisions
+
+For trusted internal sources the person who submitted an item may confirm or
+decline their own proposal without the reviewer inbox. `listOwnProposals`
+returns only items whose server-recorded `submitter_id` equals the current
+authenticated actor, each with its bounded saved review page reloaded under
+current item, handler and target authority. An item the actor can no longer
+read (the host `authorize` returns false or throws `IntakeAccessDeniedError`)
+is skipped before projection: the page is filled from readable items only, in
+50-row batches, and `nextCursor` names the last emitted item and is present
+only when a further readable item was actually found. Neither the entries, the
+page size nor the cursor reveal a hidden item. If one call has to skip 1000
+hidden submissions it fails with `Own proposal scan limit` rather than return a
+short page or a cursor that stops inside the hidden run; this error is the only
+signal, and it says only that such a run exists. Any other `authorize` error
+propagates instead of shrinking the list. An item that is still readable but
+whose reviews are denied is returned as `{ item, reviews: null, unavailable:
+true }`: that covers ingestion's own denials and any throw from the host
+`assertTarget` (deleted or revoked targets), whose text is never returned.
+Integrity, validation and database errors from ingestion itself propagate. The
+reviewer `listReviews` surface keeps propagating host target errors unchanged.
+`submitOwnDecision` takes the same `ReviewInput` CAS fields and request ID as
+`submitDecision` and accepts `approve`, `reject` and `defer` only; `correct`
+belongs to the reviewer surface. It runs under the `review_own` execution
+operation: the host's `authorize` must return `submitter: true`, the resolved
+policy must have `submitterReview` enabled, and the recorded submitter must be
+the current actor and also the receipt's captured execution principal (the
+identity the effect runs as), checked under the item lock and again at apply.
+A receipt captured for a bot or service principal is never self-approvable. Policy enablement, handler/operation allowlists, captured
+ceiling, confidential access, retention and the first-valid-decision lock are
+unchanged. The decision is a human decision by that actor, recorded with
+`mode: 'review_own'`; reviewer decisions carry `mode: 'review'`. In both modes
+`selfDecision` is true exactly when the deciding actor is the item's
+submitter, so a reviewer approving their own submission is never independent
+review. A self-decision is not a reviewer judgment: it never feeds
+automation eligibility (machine authorization remains the separate evaluated
+`kind: 'machine'` path) and its feedback events carry the same marker. The
+`unavailable` entry discloses nothing about the denied handler or target.
+`applyAction` then runs once under the approver's live grants exactly as
+for reviewer decisions. Hosts render this surface from their own authenticated
+session; presentation state confers no authority, and a source payload cannot
+nominate a submitter.
+
 ## Assignment and logical splits
 
 Assignment is explicitly host-owned, durable and versioned. `assign` receives
@@ -283,6 +329,215 @@ 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.
 
+## Reviewer-chosen actions and "handled, no action"
+
+A reviewer is not limited to model suggestions. `ItemReviewView.catalog` carries
+the handlers the item's catalog currently offers (`listHandlers`, discovery media
+types and live preview authority; it is presentation, never a grant). The optional
+`startAction` callback forwards `StartActionInput` (`itemId`, `handlerId@version`,
+explicit `args`, `requestId`, optional `reason`) to `startReviewerAction`, which
+requires the current reviewer grant under that handler, a completed or partial
+attempt on the current analysis revision, and an operation handler the item's
+evidence media types offer. Plan handlers go through `previewPlan`. The server
+creates an action keyed `reviewer:<requestId>` with origin `reviewer-selected`
+(`createAction` refuses that key prefix and origin, so process authority cannot
+mint reviewer provenance; re-previewing such an action with `previewProposal`
+needs the reviewer grant and keeps its handler fixed, so only its arguments can
+be corrected),
+runs the handler's normal `validate`/`preview`, publishes a `waiting_review`
+revision and requires the same explicit approval and apply as a generated
+proposal. Replays with the same request return the same review; changed arguments
+or reason conflict. Such actions are never automation-eligible: `authorizeAutomatic`
+refuses them regardless of policy opt-ins. The UI pre-fills arguments only from a
+same-handler suggestion (for example a `needs_review` one) and a single original's
+evidence references, lists the required fields still missing, and submits exactly
+what the reviewer typed. An item whose current attempt failed outright must be
+reprocessed first; an interpretation that completed with `provider_error`,
+`unknown` or no suggestions can be acted on directly. `ReviewAction.origin`
+exposes the provenance so `ActionReview` can label human-started actions.
+
+The optional `resolve` callback forwards `ResolveItemInput`
+(`disposition: 'resolve_no_action'`, `requestId`, optional `reason`) to
+`resolveItem`. It needs reviewer authority under any handler the item's captured
+ceiling offers and refuses while an action is `authorized` with a live approval,
+`executing`, `outcome_unknown` or `succeeded`; waiting, deferred, rejected and
+failed actions, and authorized ones whose approval expired, may remain (neither
+an exhausted failed action nor a lapsed approval can be rejected, so they must
+not keep the queue open). Afterwards only reject remains: those actions can no
+longer be approved, corrected, deferred, re-previewed, retried, applied or
+automated. `submitDecision` refuses every decision but `reject`, no new revision
+is published for the item, `applyAction` rechecks the disposition before any
+effect, and `analyze`, `reviseLogicalSplit` and `createAction` refuse the item
+under its lock before any write, so it is never reanalysed, re-split or given a
+new action. `resolveItem` supersedes any queued or running analysis under the
+same lock and `claimAnalysis` refuses a resolved item, so no provider is called
+after a human closed it; the item's `processingState` keeps its last value (it
+describes analysis, not review), and the inbox state `resolved` is authoritative.
+`publishProposal` (process authority) refuses a resolved item and any
+reviewer-selected action. The UI hides Approve, Defer, Apply, every edit control, suggestion
+preview and split controls on a resolved item.
+Resolved 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.
+
+Paged 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.
+
+The append-only `intake_dispositions` record is terminal: replaying the same
+request returns the same disposition, any other request conflicts, and
+`startReviewerAction` refuses the item. `IntakeItemDTO.disposition` projects only
+`{ state: 'resolved', at }` to any item reader (`listItems` reads it in the same
+statement as the page); the reviewer and reason are returned only by
+`getItemDisposition`, which requires reviewer authority, and the review hosts put
+them on `ItemReviewView.disposition` (omitted when that read is denied, so the
+view shows only "Handled, no action"). `loadReviewSummary` reports inbox state `resolved` unless an action
+actually succeeded. Privacy deletion and retention expiry redact the reason and
+reviewer (`intake_dispositions.data`) and keep only the kind. The disposition is
+distinct from `reject`, which still means the proposal was wrong. Closing an item
+records `reviewer_routing` feedback immediately; a started action records it only
+when the reviewer approves it (see FEEDBACK.md). Capture is an optional projection
+that never vetoes the decision or disposition.
+
+`startReviewerAction` applies the handler's discovery media types and the live
+reviewer grant/policy for that handler. It intentionally does not apply the
+proposal catalog's provider-policy filter or `maxHandlers` slice: those bound what
+a model may be offered, and a human choosing a handler sends nothing to a
+provider. The UI picker shows the offered catalog, so a handler hidden from it is
+only reachable by a reviewer who already holds `review` authority for it. The maintained
+browser fixture serves both operations behind CSRF and the same session scope.
+
+## Single-page triage workspace
+
+`IntakeWorkspace` (#4215) composes the existing pieces so a reviewer works the
+whole queue on one page: the paged inbox as a list pane, the review view of the
+selected item beside it (the original above its action form), and the
+reviewer-instruction message box of the item pane. Props: `host`, `contextKey`
+(replace on session change, as for the other components), optional initial
+`itemId`, `pollMs`, `rowAside` and `onselect(itemId | undefined)`, which only
+reports the selection (to keep a URL in step) and never navigates. It adds **no
+host callback and no server authority**: every read is the host's `list` and
+`load`, every action still goes through the handler preview and an explicit
+approval and apply under the approver's live grants, and the message steers the
+model only, exactly as in `IntakeReview`.
+
+- **Inline original.** In the item pane `EvidenceViewer` shows one part at a
+  time (`layout="pager"`), opening on the first part that renders inline (the
+  uploaded file rather than its capture record), with previous/next original.
+  A PDF with more than one *observed* page (extraction locations or proposed
+  page groups; `pages` prop) gets previous/next page, which reloads the frame
+  at the same-origin URL plus `#page=n`; only `evidenceUrl`-approved URLs ever
+  reach a frame. `IntakeReview` gets the same page navigation over its
+  unchanged stacked list of parts. The chosen part and page belong to the item
+  view (bindable `chosen`/`page`), so they survive in-place reloads, Prepare
+  review, Approve and Apply.
+- **Keyboard.** J/K and Alt+Down/Alt+Up move to the next/previous row (loading
+  the next page at the end), ignored while focus is in a text field, select or
+  editable region; "Previous item"/"Next item" buttons carry
+  `aria-keyshortcuts`. The selected row is `aria-current`, and every selection
+  moves focus to the item pane region, named by the row's label. A navigation
+  that waited for the next page is dropped if the reviewer chose another item
+  meanwhile.
+- **Unsent input.** The pane holds unsent input when it has instruction text,
+  an edited suggestion draft or split draft, a chosen start handler or start
+  reason, a no-action reason, or an action editor with edited arguments, a
+  reason or a feedback comment. It is read from the drafts themselves, so it
+  holds while a reload has cleared the view; while the view is denied nothing
+  is shown and nothing counts (the drafts stay in memory and return with an
+  authorized refresh, as before). A reviewer-initiated move (J/K, Alt+arrows,
+  Next/Previous item, a row's Review button) then asks inline, in a group
+  labelled by its note: "Stay on this item" takes focus and returns it to the
+  field the reviewer last used; "Discard and open the other item" proceeds.
+  When an item is closed without action (here or by another session), input a
+  closed item cannot take
+  (instruction, suggestion and split drafts, a started action, a no-action
+  reason) is discarded.
+- **Live state.** A row's status follows the item: "Interpreting…", "Ready to
+  review", "Needs review" with missing argument names or the generation
+  outcome, "Awaiting approval", "Approved, not yet applied", "Failed" with a
+  safe category, "Handled, no action", or the listed inbox state. Rows the
+  reviewer has not opened show the listed state only; reasons come from a
+  loaded view, never from server exception text. The open item's own polling
+  (`ReviewView`, unchanged backoff and three-failure fail-closed) reports each
+  displayed view and the workspace patches that row in place
+  (`InboxView.patch`, keeping the listed label and preview, and the row's
+  assignment unless the patch carries a newer assignment version, so a view
+  read before an assignment never rolls the row or the next expected version
+  back), so the row follows each newer read of the form and the list is
+  **not** re-listed per tick. An item the
+  reviewer leaves while its stage is in flight, or before the pane showed the
+  result of its last operation (an instruction just recorded), keeps
+  following: the workspace re-reads followed items with the same `load` (first
+  review page) on the pane's backoff, at most **5** reads per tick, one after
+  another, least recently read first (so every followed row is reached), with
+  only one tick running at a time. At most **20** items are followed; beyond
+  that the longest-followed one (the earliest started, whatever the read
+  rotation) stops. An item left while its pane was mid-operation (an Apply not
+  yet answered) keeps following while a read still shows an action authorized
+  or executing: exactly **3** more reads when it never answers, the fourth
+  ending the follow. That debt belongs to the operation, so it survives
+  reopening and leaving the item again until a view shows the operation
+  answered or the reads run out; leaving mid-operation again starts a full
+  debt for the new operation. Each follow has a
+  generation: an answer from an earlier follow of the same item (one asked
+  before the reviewer reopened or left it again) is dropped, and its failure
+  does not count toward the new follow's three. An item stops being followed
+  when it settles, its view is denied, three reads in a row throw, its row
+  leaves the displayed list (a filter or a refreshed page removed it), the
+  list fails closed, or the cap drops it; a denial, the failure stop or the
+  cap drops its cached status and restores its entry exactly as its page read
+  returned it (never a patched entry). Opening an item drops its cached
+  status until the pane shows a view; a denial in the open pane (a failed
+  action, the pane's own fail-closed poll, or a first load that failed) does
+  the same as a follow denial, clears the announcement, and the item is not
+  followed when left. A settled stage that was seen running is announced in a
+  polite status region ("badger-po.pdf: Ready to review"), only while its row
+  is displayed; a refreshed page or a failed list clears it.
+  Other rows update on Refresh, a filter change or when opened; there is no
+  streaming. While a refresh or "Load more" is pending, the displayed rows stay
+  (controls disabled) and keep taking patches. Every read (a page, a pane
+  view, including an unchanged poll, and a follow read) is numbered when its
+  request starts, and each row shows the entry of its newest read, whatever
+  the source: a page read before a pane or follow read never regresses the
+  row, and a page read after them replaces what they showed. The same rule
+  governs a follow: a follow read older than the row's newest read changes
+  no status, does not stop the follow and announces nothing (a newer read
+  settles it), so the announcement never contradicts the row. Cached status reasons follow the same ordering, even when entries have identical
+  fingerprints. "Load more" continues the
+  filter the rows were listed under, not filter inputs edited since, and does
+  not repeat a row already shown. A failed "Load more" fails closed like any
+  failed read (the host cannot tell a transient failure from a revoked
+  grant): the rows clear and the list shows its error.
+- **Approve and advance.** After an approve, apply or "Handled, no action" whose
+  reload left nothing for the reviewer (closed without action, or an action
+  succeeded and none is waiting for approval, waiting to be applied, executing,
+  unknown or failed; stale, rejected and deferred actions do not hold it), the
+  item's row is patched and leaves the list when it no longer matches the
+  listed state/assignee filter, and the next row that is not closed or
+  completed opens and takes focus, with no navigation and no re-listing. An
+  approval that leaves an apply step keeps the item open with Apply in place.
+  Unloaded saved-review pages and an active background stage also prevent
+  settlement. Advancing skips completed inbox pages until a reviewable row
+  appears; a page that makes no progress stops the walk.
+  It never advances over unsent input on the same item: the item stays open,
+  the input stays, and a note says it is finished but has unsent input; the
+  reviewer moves on explicitly, through the confirmation; input typed while
+  the next page loads counts too. When no open row is displayed, the advance
+  appends pages of finished rows until one has an open row or no page
+  remains, at most **5** appends. After each append, the advance (like
+  J/K at the end of the list) finds its place again by id: just after the
+  item it left, or, if that row has gone, at the first row that followed it
+  and is still listed, or at the first new row, so a row that left the list
+  meanwhile never shifts it onto the wrong item. Its notes (and "nothing else
+  needs review") are written into one persistent polite status region. The queue is never reported empty when
+  that is unknown: past the bound, or when an append cannot start (a refresh
+  is pending) or is superseded, the item stays open with a note to try Next
+  item again, which still works; when an append fails, the list has failed
+  closed (no rows, Next disabled), so the item stays open with a note to
+  refresh the list to continue. The open item stays listed while the
+  reviewer works on it even if its state stops matching the filter; it
+  leaves once they move on.
+  When nothing is left the pane says so. The per-row "Handled, no action"
+  control is hidden in the workspace (`resolveInRow={false}`) so closing always
+  goes through the item pane and advances.
+
+
 ## Maintained browser proof
 
 `pnpm test:components` runs real Svelte component tests; `pnpm test:e2e` runs the
@@ -323,8 +578,13 @@ Import `createIntakeReviewHost` and `IntakeReviewHostOptions` from
 options)` with a service constructed from the current authenticated session.
 The returned `IntakeReviewHost` implements inbox state projection across saved
 review pages, current generation loading, stable `ui:<index>` intention keys,
-action/plan preview CAS lookup, decisions, apply, corrections, candidates, split
-and feedback. Repeated preparation of an unchanged authorized suggestion retains
+action/plan preview CAS lookup, decisions, apply, corrections, candidates, split,
+feedback, the offered `catalog`, `startAction` and `resolve`. Any catalog
+failure (not configured, bound exceeded, denied) omits `catalog`, so the picker
+disappears while existing reviews stay reviewable; item, review and evidence
+denials still propagate as before; the reference host (`reference/review-host.ts`)
+degrades the same way. Repeated
+preparation of an unchanged authorized suggestion retains
 its current review instead of creating a new revision. Changed arguments still
 require explicit re-preview and a fresh human decision.
 `list({ state?, assigneeId?, cursor?, limit? })` returns one page newest receipt
@@ -518,3 +778,11 @@ choosing the same local file explicitly starts a new upload identity. Opening
 then dismissing the chooser preserves the separately retained originals and
 request identity for retry; it does not clear the shared FilePicker's native-form
 behavior. Successful upload and host/context disposal still discard retry state.
+
+Workspace ordering also protects an open item during an awaited automatic page walk:
+the selected row remains until navigation succeeds, except that a failed list read
+clears the inbox. Applying an action is disabled
+while that action card holds unsent arguments, reason, or feedback comment. A list
+refresh retires earlier follow snapshots; only follow reads started after that
+page request may override its rows, so a newer refresh cannot be regressed by an
+already settled or older in-flight follow read.

package/agents/execution.md

@@ -37,6 +37,34 @@ 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.
 
+`operation: 'review_own'` is the submitter-scoped decision gate (#4085). The
+service accepts it only when the host's `authorize` result carries
+`submitter: true`, the resolved policy's `submitterReview` is enabled (the
+application layer opts in; tenant/source layers may only set it `false`), and
+the item's server-recorded `submitter_id` (the receiving service's authenticated
+`scope.actorId`) equals the current actor and the captured
+`execution.principalId`; apply rechecks that a `review_own` decision's reviewer
+is that submitter and principal. All other `review` checks apply
+unchanged; `correct` is refused. The decision row records `mode` and
+`selfDecision` (decider is the submitter, in either mode), and `feedbackEvent` copies them as `decisionMode`/`selfDecision`;
+`authorizeAutomatic` never reads human decisions, so a self-decision cannot
+become automation evidence. `listOwnProposals` reads with the ordinary `read`
+operation per handler after an item-level `read` check. Unreadable items are
+skipped before projection (1000 hidden rows per call, then `Own proposal scan
+limit`) and the cursor names only emitted items with a confirmed readable
+successor. On this surface every host `assertTarget` throw is mapped to the
+exported `IntakeAccessDeniedError` (message `Intake unavailable`, the type of
+every execution denial), so the item becomes an `unavailable` entry and host
+error text is not returned; hosts need no change. Other errors propagate,
+including a throwing grant store in `authorize`. The feedback anti-widening
+check also refuses a re-evaluation that turns `submitterReview` on.
+Deletion redaction blanks `submitter_id` and `owner_key` with the payloads and
+drops `execution.principalId` unless an external action is still `executing`
+or `outcome_unknown`; `finish` and the reconcile state update release it once
+none is left, and later deletion sweeps do the same.
+Hosts whose `authorize` switches exhaustively on the operation fail closed for
+the new value until they opt in.
+
 `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
@@ -47,6 +75,50 @@ row lock before public `Contents` reads. A current `PrincipalRun` intersects liv
 permissions with the captured ceiling and checks the exact registered collection
 operation at every effect. No `runOnce` atomicity is assumed.
 
+## Reviewer-chosen actions and dispositions
+
+`startAction(StartActionInput)` lets an authenticated reviewer begin any
+operation handler the item's evidence media types offer, without a model
+suggestion. It checks `review` access under that handler before any callback,
+refuses plan handlers and resolved items, binds the current analysis revision's
+completed/partial attempt, inserts an action keyed `reviewer:<requestId>` with
+`data.origin = 'reviewer-selected'`, and reuses `buildBinding`/`publish`: schema
+validation, `validate`, `preview`, exact normalized arguments, target locks,
+evidence pins and the request ledger behave exactly as for `previewProposal`.
+Replays re-preview against the original revision and return the same review.
+Approval, apply, retention, redaction and reconciliation are unchanged.
+`authorizeAutomatic` refuses `reviewer-selected` actions and resolved items;
+human routing is never machine authority.
+
+`resolveItem(ResolveItemInput)` appends one terminal `intake_dispositions` row
+(`disposition = 'resolved_no_action'`, reason/reviewer in redactable `data`)
+under the item lock. Reviewer authority is taken from the first handler the
+captured ceiling and policy offer; no new grant exists. It refuses while any
+action is `authorized` with an unexpired approval for its current review
+version, `executing`, `outcome_unknown` or `succeeded`; `failed` actions and
+lapsed approvals do not block it (neither can be rejected). Afterwards
+`submitDecision` refuses everything but `reject`, `publish` refuses any new
+revision (correction, re-preview, plan preview), the apply gate (`approved`)
+refuses any execution or retry, and `IngestionService.analyze`,
+`reviseLogicalSplit` and `createAction` refuse the item under its lock before
+any write. `createAction` (process authority) also refuses the reserved
+`reviewer:` key prefix and `reviewer-selected` origin, which only
+`startReviewerAction` mints; `previewProposal` on such an action requires
+`review` access and the current handler@version. `resolveItem` supersedes
+queued/running analyses and completes dispatch intents under the item lock, and
+`claimAnalysis` returns `null` for a resolved item; `publishProposal` refuses
+a resolved item and any reviewer-selected action. `[feedbackActionTransaction]`
+takes `targetRevisions` (default true); routing lineage re-checks pass false. The feedback context's
+`settled` flag gates selection only; lineage re-checks ignore it (FEEDBACK.md). `intake_dispositions` is a new model: deploy
+its manifest migration (`pnpm ... db:migrate`) before upgrading hosts;
+`assertReady` checks it, and both privacy deletion and retention expiry
+(`redactExecution`) redact its payload with the other item-owned tables.
+`IntakeItemDTO.disposition` is `{ state: 'resolved', at }` (row `created_at`,
+never redacted); `getItemDisposition` returns reviewer and reason under
+`reviewerAccess`. `resolveItem` captures an optional `reviewer_routing` feedback projection in the
+same transaction; a reviewer-selected action is captured when its approval is
+recorded (FEEDBACK.md).
+
 ## Durable review and effects
 
 Preview appends a proposal bound to exact analysis attempt/evidence, handler,