@fabricorg/platform-host 8.8.0 → 8.10.0

package/README.md

@@ -41,7 +41,7 @@ injected `now` clock is also passed to ordinary policy evaluation.
 
 Production polling workers can use `createStoreBackedActionDispatcher()` plus
 `runPlatformActionWorker()`. The pending invocation row is the durable queue item; workers claim
-bounded batches with an atomic, renewable lease and `FOR UPDATE SKIP LOCKED`. Every claim advances a
+bounded batches with an atomic, renewable lease and `FOR NO KEY UPDATE SKIP LOCKED`. Every claim advances a
 fencing token. A heartbeat may renew only a lease that has not expired; after expiry, the work must be
 reclaimed so its token advances. An expired worker cannot finalize after another worker takes ownership. Pass a stable
 `idempotencyKey` to `submitAction()` so retries resolve
@@ -76,7 +76,7 @@ Non-idempotent governance retry requires a durable `deferredBeforeEffectAttempt`
 preceding claim count. Each retry must record its own pre-effect deferral to permit another claim.
 A missing or stale marker retains interruption failure and manual reconciliation. Marker-write
 failure ends terminally when the verdict can be persisted; lease loss retains the recoverable
-fencing error. Handler and adapter errors are outside this deferral window.
+fencing error. Handler and adapter errors are outside this governance deferral window; handler rollback retry is described below.
 
 PostgreSQL migration 9 (`pre_effect_governance_deferral`) adds the nullable marker column.
 Run `ensureSchema()` before deploying Hosts that may defer non-idempotent actions. Invocation
@@ -96,6 +96,124 @@ both count worker claims.
 A retryable obligation-resolver error fails terminally with the policy evidence from that attempt.
 Preview evaluation does not enter this execution catch.
 
+## Retry a rolled-back handler transaction
+
+Throw `RetryableHandlerError` from `@fabricorg/platform` (or its `/policies` export) to assert
+that the handler's effects stayed inside the supplied Host transaction and it can run again.
+Host can retry that transaction within the same execution attempt. The default budget is three
+total tries; `handlerRetry.maxAttempts` accepts integers from 1 to 10, with 1 disabling retry.
+The worker claim, `attemptCount`, policy evaluations, obligations and approval decision are retained.
+This is separate from `RetryableExecutionError`, whose handler throws retain terminal failure behavior.
+
+Retry requires the atomic `transactionWithEvents` path, a throw from the handler call, and
+`ConfirmedTransactionRollback` from that transaction call with the identical thrown error as `cause`.
+Bare errors, other wrappers, failed rollback and errors at commit do not qualify. Errors from
+transactional authorization, state validation, result/child validation, event extraction/persistence,
+staging or finalization preparation do not qualify; neither does a returned `{ success: false }`.
+`ReconciliationRequiredError`, `RetryableExecutionError` and Host's recoverable fencing errors retain
+their existing outcomes and bypass the classifier.
+
+There must be no adapter row from the resume scan (including failed/running rows), durable provider
+effect, or pending completion/handoff. Before a retried try runs application code, its transaction
+locks and checks invocation ownership. Leased execution checks the captured owner and token and
+uses a transaction-scoped lease fence. Inline execution requires an unleased running row without
+lease expiry; built-in workers do not claim such rows. Missing locking/fencing support prevents retry.
+Lease loss raises the existing recoverable fencing error rather than a stale owner's failed verdict.
+
+Host reparses copied durable parameters and restores copied provenance, admission time and
+transactional authorization input. Uncopyable inputs, failed reparse or a changed parsed value stop
+retrying. Preparation, adapter inputs and staged requests are published from the committed try.
+A compatible replay checkpoint continues to bypass the handler. Exhaustion settles the last handler
+error through `redactErrorText` with `source: "handler"` and the existing status handling.
+
+```ts
+import { isTransientPostgresTransactionError } from "@fabricorg/platform-host";
+
+const host = createGovernedActionHost({
+  store,
+  registry,
+  authorization,
+  handlerRetry: {
+    maxAttempts: 3,
+    classify: (error, { actionId }) =>
+      actionId === "records.update" && isTransientPostgresTransactionError(error),
+    delayMs: (retry) => Math.random() * Math.min(1000, 25 * 2 ** (retry - 1)),
+    onRetry: ({ actionInvocationId, attempt, maxAttempts }) =>
+      metrics.recordHandlerRetry(actionInvocationId, attempt, maxAttempts),
+  },
+});
+```
+
+`classify` must return literal `true` to opt a raw error in; a thrown classifier refuses retry.
+It asserts safety for the whole retried unit, not just the SQL statement that failed.
+`isTransientPostgresTransactionError` recognizes candidate SQLSTATEs `40001` (serialization),
+`40P01` (deadlock victim) and `55P03` (lock unavailable), following up to 16 errors through `cause`
+with cycle and throwing-getter protection. It is not proof of rollback or absence of effects.
+
+Without `delayMs`, Host uses full jitter on a 25 ms exponential backoff capped at 1000 ms.
+A configured number or callback result is clamped to 0–1000 ms; callback retry numbers start at 1.
+A throwing or non-finite delay stops retries with the original handler error. `onRetry` runs before
+the delay; `attempt` identifies the upcoming try (2 through `maxAttempts`). Synchronous throws and
+asynchronous rejections are ignored without awaiting the observer. Delay happens between finished
+transactions; Host does not race a transaction against a timer. Retrying delays the worker's other claimed rows. A crash mid-retry uses existing recovery.
+
+With retry enabled, in-transaction authorization, state guards and the other transaction callbacks
+run again per try. They and the handler must keep effects inside the supplied transaction. Avoid
+independent commits, HTTP calls, signals, nontransactional service writes and unawaited work.
+
+### Provider rollback evidence
+
+Rollback evidence is optional. A provider that propagates bare errors gets no handler retry.
+`PostgresPlatformHostStore` does not infer rollback. Built-in stores expose provider rollback
+confirmation to Host's handler transaction through an internal callback request. Ordinary application
+transactions, store-internal approval/erasure transactions and other Host APIs retain their prior
+error contracts, including callback-error identity and erasure's SQLSTATE mappings, when the
+provider below wraps callback failures.
+The request travels on the callback Host passes to `transactionWithEvents`. Code that decorates a
+built-in store's `transactionWithEvents` and substitutes its own callback drops the request, so
+handler retry stays off for that store; a decorator that passes Host's callback through unchanged
+keeps it.
+An application-owned provider can use this pattern with its transaction-bound domain store:
+
+```ts
+import { ConfirmedTransactionRollback, type PostgresPlatformHostTransactionProvider } from "@fabricorg/platform-host";
+
+type ApplicationDb = ReturnType<typeof domainStore.withClient>;
+const transactionProvider: PostgresPlatformHostTransactionProvider<ApplicationDb> = {
+  async run(run) {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      let result;
+      try {
+        result = await run({ db: domainStore.withClient(client), sql: client });
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw new ConfirmedTransactionRollback(error);
+      }
+      // COMMIT errors remain outside the callback rollback signal.
+      try {
+        await client.query("COMMIT");
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+      return result;
+    } finally {
+      client.release();
+    }
+  },
+};
+```
+
+The provider throws the wrapper after successful `ROLLBACK` of a failed callback. If rollback
+throws, that rejection supplies no confirmation. Memory confirms a failed callback for the Host
+handler request after successful Host-ledger undo and a configured provider's `restore`. Commit-phase
+errors and providerless approval transactions supply no confirmation. Ordinary public Memory
+transaction callbacks retain their original errors. Custom atomic stores that expose the wrapper
+through their public transaction API are supported; Host's non-handler transaction boundary and
+exported conformance rejection checks normalize that transport evidence before classifying errors.
+
 **Handler transaction reconciliation.** A handler or store transaction wrapper can throw
 `ReconciliationRequiredError(message, { cause })` from `@fabricorg/platform` (also exported from
 `@fabricorg/platform/policies`) when a domain effect may already have committed and an operator
@@ -133,11 +251,13 @@ The signal does not change failures in pre-handler governance or validation, sta
 exceptions, adapters, or finalization. Application governance errors and definite adapter failures retain their
 `failed` paths; post-success errors follow the recovery rules below. State guards still fail closed.
 Transient `after_adapters` finalization failures escape as `RecoverableFinalizationError` for
-recovery within `recoveryMaxAttempts`. An ordinary handler error still records `failed`. This signal requests an operator decision,
+recovery within `recoveryMaxAttempts`. A handler error without eligible confirmed rollback still records `failed`. This signal requests an operator decision,
 not an automatic retry or a claim that the current transaction committed.
 
 New rows bind that key to the action version, actor/authority binding, and a versioned canonical
-parameter digest. Host 3 defaults to `enforce`, which throws `IdempotencyConflictError`; configure
+parameter digest. An empty `authorizationBindingId` is treated as absent for submission
+idempotency identity and receipt ownership, including stored empty IDs from older Hosts.
+Host 3 defaults to `enforce`, which throws `IdempotencyConflictError`; configure
 `idempotency.conflictMode` as `audit-only` for a preflight soak. Legacy null-digest rows skip only the
 parameter comparison and call `onLegacyRecord`; actor, authority-binding, and action-version mismatches
 still reject in enforce mode. See `MIGRATION-2-IDEMPOTENCY.md`.
@@ -345,7 +465,7 @@ and accept the weaker stale-worker guarantee. Parent annotations similarly have
 
 Atomic finalizers require transaction-scoped `writeAdapterInvocation` when the store advertises the
 capability and execution holds a lease. A missing member selects verdict-first fallback before
-transaction evidence writes. PostgreSQL locks the matching parent with `FOR UPDATE` before the
+transaction evidence writes. PostgreSQL locks the matching parent with `FOR NO KEY UPDATE` before the
 adapter mutation in one SQL statement. Memory rechecks buffered lease and adapter predicates at
 commit and excludes claims and other conditional writes while applying the commit. A commit-time
 conflict rolls back and raises `RecoverableFinalizationError`. No schema migration is added by this
@@ -564,6 +684,35 @@ When `authorizeExecution` is absent, the Host reuses `authorize` at the executio
 completed idempotent replay returns its existing result without creating or executing a new
 mutation.
 
+Applications whose authority is protected by database locks can also configure
+`authorizeExecutionInTransaction`. Host calls it after state-machine validation and directly before
+the handler (or the handlerless action's event/state-transition work), with the same execution input
+plus the `db` supplied to the handler transaction. Only `true` permits the effect; `false` and
+non-boolean results roll the transaction back and use the same authorization-refusal settlement as
+`authorizeExecution`. A throw rolls the transaction back and settles the invocation as `failed`.
+Unlike `authorizeExecution`, a `RetryableExecutionError` thrown here is not deferred for a later
+attempt, because the hook runs after policy evidence is recorded; retry transient authority-store
+errors, such as a lock timeout, inside the hook. The hook runs on initial execution, approval resume,
+recovery, offline replay and staged dispatch when those paths execute the handler transaction. It is
+intentionally skipped for `authorityMoment: "capture"`, whose durable capture evidence governs instead.
+
+The hook guards the handler transaction only. A finalizing action's `finalize` callback runs in a
+later transaction, after adapters, without this hook, and a recovery attempt that resumes from a
+finalization checkpoint skips the handler transaction and therefore the hook. Only the
+pre-transaction `authorizeExecution` check runs on that attempt.
+
+With `transactionWithEvents`, the hook shares the application transaction and `db` used by the
+handler. A finalizing action has already locked its invocation row, and state-machine validation has
+already performed its application reads before the hook runs; ordinary actions do not acquire an
+invocation-row lock here. Host does not choose lock strengths for application state or authority
+rows. Applications should document a consistent order from those existing locks to any locks acquired
+by the hook. The legacy `store.transaction` path invokes the hook and handler in the same callback on
+the same `db`, but that base store seam does not itself promise a database transaction. A store
+whose `transaction` is not a real database transaction, such as `PostgresPlatformHostStore` built
+without a transaction provider, gives the hook no atomicity with the handler's writes: a lock the
+hook takes is released before the handler runs. Use a store with `transactionWithEvents` when the
+hook must close the revocation gap.
+
 External gateways should persist a compact admission record bound to the tenant, registration, actor,
 action, canonical parameter hash, resource scope, and expiry, then pass its opaque non-secret identifier
 as `authorizationBindingId` to `submitAction()`. Credentials and signed principal proofs do not belong
@@ -781,13 +930,24 @@ The evaluator returns `auto-execute`, `needs-approval`, `escalate`, or `rejected
   from execution claims.
 - `rejected` terminally fails before policies and mutation code run.
 
-An approval workflow calls `resumeApprovedInvocation()` instead of invoking the handler directly. The
+An approval workflow can record a decision for a worker or call `resumeApprovedInvocation()` to execute inline. For inline resume, the
 host authorizes the approver (using `authorizeApproval` when provided), then atomically persists the
 decision and changes `waiting_for_approval` to either leased `running` or terminal `failed`. This keeps
 the decision in the mutation ledger and prevents an approval/worker race.
 `authorizeApproval` receives the parked `actionInvocationId` and durable, post-redaction `invocation`
 record so the application can verify the approver's authority over that specific invocation.
 
+`authorizeApprovalInTransaction` is the optional final authority boundary for both inline resume and
+`recordApprovalDecision`. The store locks and classifies the invocation first, then calls the hook with
+the transaction-bound `db` and locked invocation immediately before a decision write. Only `true`
+permits the decision. A refusal leaves inline resume waiting and makes record-only approval return
+`unauthorized` with its configured refusal evidence; a throw rolls back. Applied-decision replay,
+expired decisions, and rows that cannot accept a decision do not call the hook. The built-in
+PostgreSQL store holds the invocation row's `FOR NO KEY UPDATE` lock while the hook runs; the memory store
+holds its serialized mutation unit. Applications choose any authority-row lock strength and should
+acquire authority locks after the invocation lock to keep one lock order. Configuring this hook
+requires `transactionalApprovalAuthorization: true`; Host rejects stores that do not advertise it.
+
 ```ts
 await host.resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, {
   approved: true,
@@ -802,6 +962,97 @@ Custom stores remain source-compatible when HITL is unused. To enable HITL they
 additive `ApprovalPlatformHostStore` capability. Both built-in stores implement it; Postgres users must
 call `ensureSchema()` so the HITL evidence and approval-decision columns are added.
 
+### Record a decision for worker execution
+
+`createGovernedActionHost()` also returns `ApprovalDecisionRecordingHost`; the base
+`GovernedActionHost` interface retains its handwritten-host shape. An HTTP endpoint can commit a
+decision without running the handler, adapters or `executeInvocation`:
+
+```ts
+const result = await host.recordApprovalDecision(actionInvocationId, tenantId, spaceId, {
+  requestId: decisionRequestId,
+  approved: true,
+  approverId: reviewer.id,
+  approverType: "natural_person",
+  evidence: { verificationRef: receiptId },
+});
+// result.outcome === "approved": the row is pending for a worker claim.
+```
+
+`requestId` must be a non-blank string of at most 256 characters. Keep it stable across transport
+retries. The result contains `outcome`, `actionInvocationId`, current `status`, `replayed`, and the
+stored `decision` for `approved` or `denied`, including replays. Non-applied outcomes omit
+`decision`, protecting another approver's identity, reason and evidence. Host snapshots and validates
+evidence before authorization.
+
+| Outcome | Durable effect |
+| --- | --- |
+| `approved` | Commit the decision and queue `pending`, clearing lease/error without changing `attemptCount`. |
+| `denied` | Commit the decision and settle `failed`, using the inline denial patch. |
+| `unauthorized` | Entitlement or approval authorization returned false; invocation unchanged. |
+| `expired` | A due waiting approval settles `failed` with `approvalExpiry`; a terminal row already carrying approval expiry and no decision remains unchanged. The attempted decision is not applied. |
+| `already_decided` | An existing decision belongs to a different request, or the same request changes verdict or approver id/type; invocation unchanged. |
+| `late_terminal` | Terminal row without an approval decision or approval expiry; unchanged. |
+| `not_waiting` | Non-terminal row without a decision that is not waiting for approval; unchanged. |
+| `unsupported` | Waiting row outside Host HITL atomic approval; unchanged. |
+
+The store's locked classifier checks an applied request id, verdict and approver id/type before
+checking authorization refusal and row state. A matching retry returns its original `approved` or
+`denied` outcome with `replayed: true` after pending, running, completion or failure, and appends no
+events. An opposite verdict is `already_decided`. Older decisions without request ids also produce
+`already_decided` for an authorized request. For a different request id, authorization refusal
+returns `unauthorized` before existing-decision classification. An authorized late retry returns
+`expired` from a terminal row's `approvalExpiry`, including when a sweep expired it. It remains
+`replayed: false`, because this is row-state classification rather than a stored decision receipt.
+The compatibility authorizers still run before the transaction; thrown callback errors propagate even
+on a retry. When `authorizeApprovalInTransaction` is configured, its locked result also has to allow
+the write. An applied-decision replay still runs the compatibility callbacks but skips the
+in-transaction hook because it writes nothing.
+
+The store operation atomically classifies, changes state and appends its events/outbox rows.
+PostgreSQL requires a transaction provider (`transactionWithEvents`); unsupported stores throw a
+configuration error before writing. Recording does not use `beginApprovalDecision`, whose inline
+contract remains leased `running`. Missing scoped rows and invalid ids/evidence throw.
+An unresolved waiting action returns `unsupported` without changing the row, with or without a
+deadline, including one already due. Approval authorization is skipped when the action cannot
+resolve; the locked classifier leaves the invocation unchanged in that case. Inline resume keeps
+its existing unknown-action behavior.
+
+The stored decision carries `requestId` and `recordedAtAttempt` in the existing decision JSON.
+The first worker claim after recording has `attemptCount === recordedAtAttempt + 1`. Host computes
+`approval_resume` for that claim, exempts the non-idempotent interruption guard and compares the
+recovery budget using `attemptCount - recordedAtAttempt`. The earlier parking claim therefore does
+not exhaust this first run at `recoveryMaxAttempts: 1`; an inline-origin wait recorded at zero works
+the same way. Attempt history is retained. Later claims use the existing recovery checks, budget
+and `recovery` reason, comparing the absolute `attemptCount` against `recoveryMaxAttempts`
+without subtracting the recorded count. Retryable governance failures on the approved claim retain leased-attempt
+retry behavior instead of the inline resume override's terminal behavior.
+
+The pending row is recoverable through `runPlatformActionWorkerCycle` without a separate enqueue.
+Hosts without a worker must dispatch the pending row themselves. `executeInvocation` exists but is
+not a concurrent-safe targeted claim. Upgrade workers before using this API: older workers mishandle
+recorded approvals' attempt and execution-reason semantics. Saga-parent waits are excluded through
+`ActionDefinition.kind === "saga"`; Host HITL also requires a `needs-approval` or `escalate` checkpoint.
+
+Set `approvalDecisionAttemptEvents: true` to append `APPROVAL_DECISION_REFUSED_EVENT`
+(`ApprovalDecisionRefused`) for non-applied outcomes. It defaults off. The payload contains outcome,
+request id, approver id/type, attempted `approved` verdict, observed `status` and `attemptedAt` ISO
+time, without evidence, reason text or parameters. Scoped row lookup supplies tenant and space;
+a wrong scope throws not-found without an event. Refusal event ids combine invocation identity with
+the SHA-256 digest of the exact request id (`digestParameters`), preserving punctuation through
+`lifecycleId` sanitization. Store event-id deduplication retains one event for a repeated request.
+The attempt factory runs after any update with the pre-patch observed row: waiting on first expiry,
+failed on a later attempt against that expired row. Applied-decision replays append nothing. The
+classifier appends within its transaction, including on expiry, so append failure rolls back the
+state patch and events. Host construction requires atomic approval, transaction and outbox support
+when the option is on. `approvalLifecycleEvents` independently controls applied decision/expiry events.
+
+After commit, Host emits `invocation.failed` for an applied denial or expiry. Custom recording stores
+return `applied` alongside outcome, invocation and replay information so Host can distinguish a new
+transition from a previously expired row. Replays and unchanged rows emit no additional status
+telemetry. Approval queues pending without a recording-time status event, matching sibling approval
+paths; the worker emits execution telemetry when it executes the invocation.
+
 ### Approval deadlines, evidence, and lifecycle events
 
 `HostHitlDecision.approvalExpiresAt` accepts an absolute, valid `Date`. Alternatively,
@@ -1040,6 +1291,14 @@ an offline replay and a re-submission under an existing idempotency key:
    `redactActionParameters` changes it (test "the persisted parameters are the copy that was
    checked …").
 
+When recording refusals is enabled, the recording path first checks request-only metadata:
+correlation/causation consistency, provenance source and trace attributes, audit attributes when no
+audit redactor is configured, and parameter-independent authorization-binding fields. A failure
+throws the validation error and leaves the key free. This validation does not run redaction or trace
+hooks. Binding digest comparison and capture-time expiry are checked before recording, except
+that the digest is not compared for actions declaring `admitSubmission`. Audit validation after a
+configured redactor retains its normal ordering.
+
 Only JSON-data parameters can be admitted. Anything else is refused as `invalid_parameters`
 directly after `authorize`, before the composition callback and the check run. A SharedArrayBuffer or a view over one is refused this way,
 since the caller could still write to its memory (test "a parameter backed by a SharedArrayBuffer …").
@@ -1059,10 +1318,63 @@ Only `{ admitted: true }`, read as an own data property, admits. Each of these m
 - any other answer (`invalid_decision`);
 - parameters that are not JSON data (`invalid_parameters`).
 
-Host writes nothing for a refused submission: no invocation, idempotency key, event, policy record
+By default, Host writes nothing for a refused submission: no invocation, idempotency key, event, policy record
 or error, so the key stays free. The message names the action, the refusal and the check's code
 only. Host emits `invocation.admission_refused` telemetry with the refusal.
 
+### Opt-in recorded submission refusals
+
+Set `idempotency: { recordRefusals: true }` to reserve a refused submission's idempotency key.
+The default is `false`. Activation requires a store implementing `recordSubmissionRefusal`
+and `conflictMode: "enforce"` (the default); `"audit-only"` is rejected at host creation.
+This applies to keyed, non-staged submissions from any actor type. With the option on, an
+empty string is a present key; the default path continues to treat it as keyless. Keyless submissions,
+including staged children, retain the default behavior.
+
+Host records entitlement and authorization refusals, and admission kinds `refused` and
+`invalid_parameters`. Admission `failed`, `timed_out`, and `invalid_decision`, malformed-request
+errors and store errors do not become recorded refusals. A recording failure surfaces the store
+error; an error's `recorded: true` confirms that the key is occupied by a refusal matching the
+caller. A durable insert winner decides whether the key holds a refusal or an executable invocation.
+
+A refusal occupies one `action_invocations` row with terminal status `submission_refused` and a
+validated `submissionRefusal` descriptor. Parameters and result are fixed empty objects; agent
+proposal and provenance attributes are absent. The descriptor carries a fixed class and, for
+admission, the refusal kind and optional fixed `refusalCode`. An `admitSubmission` refusal code
+is durable evidence when this option is on: choose it from fixed action codes, without deriving
+it from submitted values (see `ActionAdmissionDecision` in `packages/platform/actions/index.ts`).
+Create new refusals through `recordSubmissionRefusal`; generic creation and status updates
+reject `submission_refused` as an input status. Refusal rows appear in invocation listings.
+Execution, resume and store mutation paths leave
+these rows inert. The stored-record erasure operator can redact their payload fields;
+Host does not schedule automatic retention. See **Erasing stored records**.
+
+Entitlement, authorization and admission checks still run on replay before Host tries an insert;
+there is no refusal lookup before the checks (use the separate `readSubmissionOutcome` receipt read below). A matching caller receives the stored refusal,
+including after the checks start passing. Identity compares actor id and type, authorization
+binding id, action version, and a parameter digest when the stored refusal has one. A refused
+caller with a different identity receives its own unrecorded refusal. An admitted caller with a
+different identity receives `IdempotencyConflictError`. A refused caller does not receive the
+stored result of an executable invocation that won the key.
+
+For actions without `admitSubmission`, Host digests parameters at the refusal site; a digest
+failure records nothing and is surfaced. For actions declaring `admitSubmission`, refusal sites
+do not digest parameters, including entitlement and authorization refusals: the parameters have
+not passed admission. These refusal rows are not parameter-bound, so changing parameters alone
+does not free their keys. Use a new key for a new request.
+
+A caller who fails authorization can occupy a key within the tenant, space and action scope.
+Applications must select trusted tenant/space context and suitable key namespaces. If an
+entitlement or authorization callback returns `false` during an outage, that response becomes
+a permanent refusal when its insert wins. Throw for an unavailable dependency rather than
+reporting a definitive denial.
+
+Before enabling the option, apply PostgreSQL migration 15 through `ensureSchema()` and upgrade
+all hosts sharing the database. Older hosts do not recognize `submission_refused` and could
+execute a refusal row. Migration 15 adds nullable `submission_refusal`; the existing status
+column is unconstrained text and parameters accept the fixed empty object. The memory and
+PostgreSQL stores use the same key scope as ordinary invocation insertion.
+
 The deadline is judged when the check's answer settles, not by which of the answer and a timer
 wins a race. Host reads the monotonic clock (`performance.now()`) when the check is called and
 again in the handler attached to the check's promise. An answer, or a throw, that settles
@@ -1093,6 +1405,25 @@ submitted …"). Before submitting an action that declares `admitSubmission`: (1
 migration 6, and nothing is written; (2) upgrade every worker, since a worker on an older Host would
 execute such an invocation without checking `admittedAt`.
 
+### Read a historical submission receipt
+
+`host.readSubmissionOutcome({ tenantId, spaceId, actionId, idempotencyKey, actorId,
+actorType, authorizationBindingId })` reads receipt metadata without rerunning mutation
+permission or admission checks. The embedding application must supply trusted, authenticated
+tenant, space and actor identity. The original principal can read its receipt after mutation
+permission is revoked. The key is exact, including the valid empty string.
+
+A refusal error with `recorded: false` establishes nothing about key ownership: an admitted
+invocation or another principal's record may hold it. Use the receipt read to observe a
+visible durable outcome. `no_record` means no record visible to this principal at this
+snapshot; it does not establish that the key is free. A returned invocation status is an
+observation and may change. Refused receipts include only their validated descriptor;
+erased receipts include only identity, version and recorded status. No pending work is dispatched.
+
+The operation is available independently of refusal recording and conflict mode. Custom
+stores implement optional `getSubmissionOutcomeByKey`; an unsupported store throws
+`SubmissionOutcomeUnsupportedError`. Storage errors propagate. See ADR 0022.
+
 ## External mutation governance
 
 Hosts can configure `resolveMutationGovernance` to persist an approved, provider-neutral
@@ -1338,13 +1669,18 @@ cast in an index expression is not immutable and PostgreSQL refuses it.
 
 ## Tenant isolation
 
-`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` run nine checks against a host
+`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` run ten checks against a host
 and its store. They prove scope on the invocation reads and writes, idempotency keys, event streams,
 worker claims, staged-invocation lists and claims, external completion, an optional governed read,
 and adapter checkpoint reads and writes they probe. The subject supplies a host, a recoverable
 store, a registered action, and two scopes in different tenants. Adapter and staged checks create
 scoped probes and retire their parent invocations afterwards. The staged check is skipped for a
-store that does not advertise transactional staged invocations.
+store that does not advertise transactional staged invocations. The refusal check is skipped when
+`recordSubmissionRefusal` is absent. When present, it tests refusal insertion/replay and ordinary
+invocation creation under one key/action in another tenant and another space. It creates terminal
+refusal rows and completed probe invocations in the other tenant’s and other space’s fresh probe
+spaces; refusal rows retain their identity and refusal verdict through the stored-record erasure operator. A PostgreSQL store must have migration
+15 applied (`ensureSchema()`) before running the kit, or the new check fails.
 
 Host passes `AdapterInvocationScope` from the store-loaded action invocation to
 `getAdapterInvocation(id, scope)` and `updateAdapterInvocation(id, patch, scope)`. Custom stores
@@ -1356,6 +1692,115 @@ refusals and an admitted update in our scope. The two adapter isolation checks
 fail for stores that ignore scope. Deployments running `runTenantIsolationChecks` against a custom
 store will see new failures until that store honours the argument.
 
+## Staged invocation conformance
+
+`stagedInvocationChecks()` and `runStagedInvocationChecks(subject)` expose 11 destructive
+checks for isolated test stores. `StagedInvocationSubject.makeHarness()` returns a fresh
+`StagedContractHarness`: a staged/atomic store and optional `raceCreateThenRotate` and
+`raceRotateThenCreate` hooks. The hooks retain a transaction during the competing operation;
+without them the checks use ordinary concurrent or ordered store calls.
+
+The probes cover principal round trips and fencing, lease owner/status/token/expiry fences,
+token rotation, child identity retention, create/rotation ordering, parent status gating,
+and batch replay/drift refusal. They do not establish database-clock authority.
+
+```ts
+const result = await runStagedInvocationChecks({
+  makeHarness: async () => ({ store: await createIsolatedStagedStore() }),
+});
+```
+
+## Outbox requeue conformance
+
+`outboxRequeueChecks()` and `runOutboxRequeueChecks(subject)` expose seven destructive
+checks. `OutboxRequeueSubject.makeStore()` supplies a fresh store implementing the outbox
+requeue port, including relay operations and readback. Probes cover budget reset and event
+identity, concurrent requeue, stale authorization generations, detached evidence, relay races,
+live-record refusal, and tenant/space refusal.
+
+```ts
+const result = await runOutboxRequeueChecks({ makeStore: createIsolatedRequeueStore });
+```
+
+## Approval conformance
+
+`approvalChecks()` and `runApprovalChecks(subject)` expose 44 destructive checks, including
+approval lifecycle parity. `ApprovalSubject.makeStore()` supplies a fresh `ApprovalCheckStore`
+with approval, recovery, outbox, and transaction support for the host-based probes. These build
+Host instances internally. Parameterized variants of a named case run within its check.
+
+Probes cover recording, replay and contradiction, authorization boundaries, expiry, refusal
+evidence and telemetry, transaction rollback, inline decision parity, and recovery budgets.
+They exercise the supplied store with the packaged Host; they do not certify application policy.
+
+```ts
+const result = await runApprovalChecks({ makeStore: createIsolatedApprovalStore });
+```
+
+For these sets, inspect each result's `status`, `evidence`, and optional `error`. Missing optional
+capabilities yield `skipped`; the recorded approval probes also skip absent transactional
+approval lifecycle/outbox support. Probe errors and missing readback fail. `passed` means no check
+failed and can include skips. Checks leave invocation, event, and outbox records under fresh
+identities/spaces. Use isolated test stores with no competing workers or relays; requeue probes
+can mark rows published without sending to a real consumer. A store factory must provide the
+transaction support its advertised capabilities require.
+
+
+## Outbox relay conformance
+
+`outboxRelayChecks()` and `runOutboxRelayChecks({ makeStore })` expose eight destructive
+checks. `OutboxRelaySubject.makeStore()` returns a fresh `OutboxPlatformHostStore<unknown>`
+for each check. The public types are `OutboxRelaySubject`, `OutboxRelayCheck` and
+`OutboxRelayConformanceResult`; `OutboxRelayResult` remains the relay cycle's result type.
+
+Probes cover claim eligibility (including equal availability and expiry boundaries), claim
+owner/expiry/attempt/token effects, a one-row batch limit, concurrent claim exclusivity,
+owner/token settlement fences, settled-row refusal and renewal fences. Each check uses a base
+time one hour ahead of the wall clock, with claim and renewal expiry modeled through explicit
+`now` inputs and a margin for wall-clock settlement guards. New rows must be available by their
+first claim time, at least one hour after the check starts; availability need not equal `recordedAt`.
+The relay checks require numeric lease tokens that increase on each claim, including reclaim,
+even though the general outbox types keep token fields and parameters optional.
+The `claim-limit` check pins only the batch limit: PostgreSQL orders claim
+candidates but does not guarantee the order of its returned update rows, and the relay does
+not rely on returned order. When `renewOutboxLeaseAndRead` is absent, the renewal check still
+exercises `renewOutboxLease` and does not skip.
+
+Out of scope: claim/listOutbox returned ordering and settlement of expired but unreclaimed
+leases (the probes settle while leases are unexpired by the wall clock), relay attempt budgets
+and backoff policy (`src/outbox.ts`, `runOutboxRelayCycle`),
+error text, dead-letter requeue (`outboxRequeueChecks`), and first-write-wins event appends
+(`eventAppendChecks`). These checks ship with the package version, so upgrading Host and
+rerunning them shows where a custom store has fallen behind.
+
+```ts
+const result = await runOutboxRelayChecks({ makeStore: createIsolatedOutboxStore });
+```
+
+## Invocation idempotency conformance
+
+`invocationIdempotencyChecks()` and `runInvocationIdempotencyChecks({ makeStore })` expose
+seven destructive checks. `InvocationIdempotencySubject.makeStore()` returns a fresh
+`PlatformHostStore<unknown>` for each check, with optional `recordSubmissionRefusal` support.
+The other public types are `InvocationIdempotencyCheck` and `InvocationIdempotencyResult`.
+
+Probes cover first-row replay and readback with changed submission fields, tenant/space/action
+key scope, distinct unkeyed inserts, empty-string keys, concurrent first-write arbitration,
+admission timestamp retention and refusal/admitted winner arbitration. The concurrent probe
+reads each submitted candidate id through the base store port. Only `refusal-winner` skips
+when `recordSubmissionRefusal` is absent; thrown probes and failed readbacks fail. Inspect
+individual statuses: `passed` means no check failed and can include that optional skip.
+
+Out of scope: duplicate-id creates without a key (the stores differ), conflict classification
+(Host's responsibility), and cross-tenant refusal scoping (already covered by
+`fabric.tenancy.submission-refusal-scoped.v1`). These checks ship with the package version,
+so upgrading Host and rerunning them shows where a custom store has fallen behind.
+Use isolated stores with no competing workers; both sets leave records under fresh ids/spaces.
+
+```ts
+const result = await runInvocationIdempotencyChecks({ makeStore: createIsolatedInvocationStore });
+```
+
 ## Event append conformance
 
 `eventAppendChecks()` and `runEventAppendChecks(subject)` run six checks for first-write-wins
@@ -1526,7 +1971,8 @@ declarations therefore does not query the migration-11 tables by default.
 
 The child has a Host-only `stagedOrigin` of parent invocation ID plus stage key and, when selected,
 the durable principal name. `authorizeExecution` can inspect `invocation.stagedOrigin.principal`
-alongside the child's durable parameters and actor. Public `SubmitActionInput` has no
+alongside the child's durable parameters and actor. When configured, `authorizeExecutionInTransaction`
+receives the same staged origin on the child's handler transaction. Public `SubmitActionInput` has no
 `stagedOrigin`; Host adds it through the internal staged-dispatch path.
 The lookup and unique index intentionally remain keyed by tenant, space, parent invocation ID, and
 stage key: one parent stage key identifies one child, while the principal is evidence for that
@@ -1800,3 +2246,329 @@ Apply PostgreSQL migration 13 (`agent_proposal`) with `ensureSchema()` before th
 proposal submission. Inserts without proposals omit the new column, following the
 `admitted_at` rollout pattern. Existing migration SQL is unchanged; readers accept legacy
 rows without a proposal. See `src/postgres-store.ts` (`ensureSchema`, `toActionRecord`).
+
+## Erasing stored records
+
+`createGovernedActionHost()` also returns the separate `StoredRecordErasureHost`
+operator capability. `GovernedActionHost` keeps its existing shape. Applications
+can use `createStoredRecordErasureHost(store, authorization)` without constructing an action
+runtime. Supply trusted `actorId` and `actorType` from the authenticated application session.
+`validateErasureInput` requires nonblank actor fields, rejects NUL/lone-surrogate
+characters in `actorId`, and checks `actorType` with Platform's `isActorType`.
+The factory's required second argument selects `authorizeStoredRecordErasure` from `PlatformHostAuthorization`; the
+integrated Host passes its own authorization object.
+
+After `validateErasureInput`, the operator calls `authorization.authorizeStoredRecordErasure`
+with exactly `{ actorId, actorType, tenantId, spaceId, requestId, targets }`. Targets are
+validated, detached copies; the hook receives neither `redact` nor stored payloads.
+The operator awaits the hook through the authorization object, preserving class receivers,
+before calling the store, with no prior record reads. Its strict `authorized !== true`
+guard permits erasure only for a `true` result.
+
+Absent hooks and non-`true` results throw the exported
+`StoredRecordErasureAuthorizationError` with `refusal: "not_authorized"`.
+Absence uses `"Stored-record erasure is refused because no authorizeStoredRecordErasure is configured."`
+Other refusals use `"Actor <actorId> is not authorized to erase stored records in this scope."`
+Typed refusals contain no target-existence details. A thrown hook error propagates
+unchanged before store access, distinguishing a failed check from an explicit denial.
+Successful operations return `EraseStoredRecordsResult`; validation errors and
+`ErasureBusyError` remain distinct failures.
+
+```ts
+import { createStoredRecordErasureHost } from "@fabricorg/platform-host";
+
+// Reuse the application's authorization object; no configured erasure hook means refusal.
+const operator = createStoredRecordErasureHost(store, authorization);
+const result = await operator.eraseStoredRecords({
+  actorId: "privacy-operator",
+  actorType: "natural_person",
+  requestId: "privacy-request-2026-11-10",
+  lockTimeoutMs: 250, // Optional; target/connection acquisition budget.
+  workTimeoutMs: 5000, // Optional; rewrite work budget.
+  tenantId: "tenant-a",
+  spaceId: "production",
+  targets: [
+    { kind: "invocation", invocationId: "act_123" },
+    { kind: "event", eventId: "evt_456" },
+  ],
+  redact(record) {
+    // Transform the detached payload fields and return the same record context.
+    // This example removes a known application value, retaining object shapes.
+    return JSON.parse(JSON.stringify(record).replaceAll("value-to-remove", "[erased]"));
+  },
+});
+```
+
+`ErasablePlatformHostStore<TDb>` extends `PlatformHostStore<TDb>` with
+`eraseStoredRecords(input: EraseStoredRecordsInput): Promise<EraseStoredRecordsResult>`.
+This store capability is an unauthenticated persistence port, not an authorization boundary.
+Direct callers must enforce authorization; the Host operator enforces it through the hook.
+Both built-in stores use `erasureAudit` to retain the request's `actorId` and `actorType`
+in the `HostRecordsErased` event envelope. These are identifying metadata, outside the
+redaction view, rather than erased payload values.
+The base store port has no new required method. Unsupported stores fail with an
+explicit capability error. The built-in memory and PostgreSQL stores implement
+this capability; PostgreSQL requires an application transaction provider.
+`validateErasureInput` rejects missing or blank scope/request identifiers, malformed
+targets, NUL/lone-surrogate identifiers, duplicate kind/ID pairs, batches outside 1–100 targets, and non-function
+redactors before invoking the store. IDs shared by different target kinds are distinct.
+The result retains request target order, reports `erased`, `already_erased`, `active`,
+or `not_found`, and counts processed records by record kind without returning payloads.
+Absent and foreign-scope targets both return `not_found`.
+
+An invocation target covers its invocation payload fields, adapter inputs/outputs/errors
+and reconciliation, staged parameters/errors linked as parent or child, policy evaluations,
+policy obligations, execution attestations, external reconciliations, canonical events,
+outbox envelopes/errors/trace context, and outbox requeue reason/prior-error evidence.
+An event target covers the canonical event and its outbox/requeue copies. It does not
+rewrite copies inside the owning invocation's `finalizationCheckpoint.handlerEvents`,
+`stateTransition`, result or other invocation evidence: checkpoint events have no event ID
+to join. Use an invocation target to cover those copies of the logical event. The
+`ERASURE_COLUMNS` source manifest and schema-discovered inventory tests classify
+text and JSON columns. The event callback runs once per canonical event in a batch;
+stores copy its redacted payload and disclosed provenance into the outbox envelope.
+Outbox-specific errors and trace context have their own callback view. Legacy outbox
+rows lacking a canonical event expose their payload/provenance in that outbox view. Overlapping
+targets do not invoke the callback twice for the same stored record in one batch.
+
+`StoredRecordErasureView` discriminates record kinds and exposes identifying context
+as readonly properties plus payload field names in `fields`. `redactStoredFields` uses
+`ERASURE_PROTECTED_PATHS` to omit specific Host-owned paths and restore their values.
+There is no recursive blacklist of key names. For example, policy fact values under
+`outcome.guidance.factsUsed[].value` remain visible even when they contain `id`, `type`,
+`status` or `provider`. Application extensions outside the paths below are visible.
+
+| Record/field | Protected paths relative to that field |
+| --- | --- |
+| Invocation/event/outbox `provenance` | `source`, `correlationId`, `causationId` |
+| Invocation `authorizationBinding` | `id`, `tenantId`, `actorId`, `actionId`, `parameterDigest`, `governingMoment`, `capturedAt`, `expiresAt` |
+| Invocation `authorizationReconciliation` | `kind`, `governingMoment`, `executionReason`, `authorizationBindingId`, `provenance.source`, `provenance.correlationId`, `provenance.causationId` |
+| Invocation `adapterReconciliation` | `kind`, `adapterType`, `operation`, `vendor`, `adapterInvocationId`, `externalReference` |
+| Invocation `approvalDecision` | `approved`, `approverId`, `approverType`, `decidedAt`, `requestId`, `recordedAtAttempt` |
+| Invocation `pendingCompletion` | `provider`, `adapterType`, `operation`, `adapterInvocationId`, `externalReference`, `acceptedAt`, `dueAt`, `parkedAt`, `overdueAt`; a non-null pending completion prevents erasure |
+| Invocation `externalCompletion` | `digest`, `externalReference`, `provider`, `outcome`, `observedAt`, `recordedAt` |
+| Invocation `pendingStateTransition` | `entityType`, `entityId`, `fromState`, `toState` |
+| Invocation `approvalExpiry` | `expiresAt`, `expiredAt` |
+| Invocation `submissionRefusal` | `class`, `refusal`, `refusalCode` |
+| Invocation `finalizationCheckpoint` | `protocol`, `actionVersion`, `steps.length`, `handlerEvents.length`, `stagedInvocations.length`, `steps[].adapterType`, `steps[].operation`, `skipped`; identity fields `eventType`, `eventSchemaVersion`, `subjectType`, `subjectId` and `payload.fromState/toState` on `handlerEvents[]` and `stateTransition`; `stagedInvocations[].key/actionId/expectedActionVersion/principal` |
+| Adapter `reconciliation` | `kind`, `adapterType`, `operation`, `vendor`, `adapterInvocationId`, `externalReference`, `adapterEventSubject.subjectType`, `adapterEventSubject.subjectId` |
+| Policy evaluation `outcome` | `policyId`, `policyVersion`, `policyKind`, `result` |
+| Execution attestation `attestation` | `provider`, `operation`, `externalOperationId`, `satisfiesObligations`, `startedAt`, `completedAt` |
+| External reconciliation `reconciliation` | `status`, `provider`, `externalOperationId`, `attempt`, `observedAt` |
+| Event/outbox `payload` | Top-level `fromState`, `toState`; `HostRecordsErased` additionally retains `requestId`, `targets`, `counts` |
+| Other payload fields | No protected descendants; record headers remain outside the callback view |
+
+The store rejects changed context or field names, protected-path insertion, invalid JSON,
+NUL/lone-surrogate strings, incompatible field types and removal of structural containers.
+Keep array shapes when they contain protected descendants. Null/absent fields remain
+null/absent. Supply a synchronous, pure JSON transformation; a thrown error aborts the batch.
+Settled parameters and results need not retain their execution schemas.
+
+Invocation erasure checks settlement on its locked closure. Event-only owner observations have the concurrency limit below. Pending,
+running and waiting-for-approval invocations are active. A terminal invocation also
+remains active with a pending external completion, a live invocation lease, a pending
+linked stage, or a live linked stage/outbox lease. An event inherits its owning
+invocation's active refusal and checks its own outbox lease. Completed, failed,
+blocked-by-policy, validation-failed, submission-refused and reconciliation-required
+rows without these conditions are settled. Pending stages can make completed parents
+active: staged dispatch runs after parent completion. A reconciliation-required row
+without a pending completion can be erased; marker guards fence later evidence writes.
+
+The PostgreSQL transaction and memory critical section atomically apply accepted
+rewrites, scope-bound markers and a sequenced `HostRecordsErased` audit event. The audit
+contains request ID, target kind/ID/outcome and counts, without erased values, value
+hashes or a free-text reason. Active/missing targets may coexist with erased targets
+in one successful batch. A callback failure rolls back rewrites, markers and the audit.
+Repeated requests reapply the callback to stored redacted data and report
+`already_erased`; `requestId` identifies audit work rather than suppressing retries.
+
+PostgreSQL erasure requires a transaction provider running READ COMMITTED; it checks
+`SHOW transaction_isolation` and refuses other levels. Ordinary writers at stricter
+isolation levels may receive a serialization failure instead of an erased outcome.
+Apply migration 16, upgrade **all Host instances sharing the database**, then enable
+erasure. Older Host SQL and direct application SQL bypass these guards and are unsupported
+once erasure is enabled. Migration 16 adds metadata columns, markers and erasure-lookup
+indexes without triggers or write-path functions. Like migrations 1–15 it runs in the
+migration runner's transaction and takes table DDL locks; ordinary index builds block
+writes for their duration on large tables. Plan an appropriate maintenance window.
+
+`eraseStoredRecords` processes sorted targets inside individual savepoints. An invocation
+target locks its invocation and dependent adapter, governance, staged parent/child, event,
+outbox and requeue rows. It also locks the stage identified by the child's stored
+`staged_parent_invocation_id` and `staged_stage_key`, even before that stage has recorded
+its child ID. A pending or leased origin stage keeps the child active; a settled origin
+stage is redacted with the child. This follows the stage, not the parent invocation's
+payloads or other stages; target the parent separately for its checkpoint copies. An event target locks its event and delivery/requeue rows, without
+locking its invocation owner or sibling rows. Canonical delivery copies are found by event
+ID. Legacy outbox-only rows with null owner columns are found through the indexed envelope
+`actionInvocationId`; new inserts populate the owner column explicitly. No advisory lock
+is taken by erasure. The migration runner retains its separate schema advisory lock.
+
+The first existing target lock may wait within `lockTimeoutMs` (default 250 ms, including
+provider acquisition). While retaining target locks, subsequent row locks, including the
+final tenant/space sequence-row lock, use `NOWAIT`; contention rolls back with
+`ErasureBusyError`. The audit allocation and insert are the final SQL statements before
+provider commit. Before opening that transaction, a separate provider transaction commits
+an `event_sequences` row with `next_sequence=0` using `ON CONFLICT DO NOTHING`. It takes no
+target locks. It attempts the insert only when it sees no committed row for the tenant and
+space, so it can wait, within the acquisition budget, only for another transaction's
+uncommitted first insert of that row. The zero seed consumes no event
+sequence: the first allocation returns 1. The erasure transaction then locks the existing
+row with `NOWAIT`; it does not try to insert a missing sequence row while holding targets.
+The seed can remain after a refused or rolled-back erasure without consuming a sequence.
+Steady event appends in the same tenant and space can starve erasure: it can repeatedly
+report busy on this final nonwaiting lock. Each retry repeats callbacks and rewrites before
+attempting that lock; busy rolls those rewrites back.
+
+Dependent rows are locked before settlement and callbacks. A claim/renewal committed before
+those locks is observed. Active/missing targets roll back to their savepoints, releasing
+locks acquired for that target before processing the next. Locks retained from an earlier
+overlapping accepted target stay held. Invocation settlement is evaluated on locked rows.
+For an event-only target the owner's status, stages and sibling leases are observed after
+the event closure is locked, but are not themselves locked. A concurrent change to that
+owner/sibling activity can therefore race that observation. Target the invocation when
+settlement of its complete closure must be serialized.
+
+Ordinary invocation updates predicate on their own `records_erased_at`. Existing dependent
+updates use their row stamp; insertion paths without a proven transaction-held owner lock
+use a materialized owner read with `FOR KEY SHARE` inside the insertion statement. Host's
+ordinary owner locks change from the released version's `FOR UPDATE` to `FOR NO KEY UPDATE`. Transaction-held owner reads are reused
+for event and reconciliation insertion. Staged creation fences parent and initial child;
+dispatch/failure attachment fences the newly attached child. An erased child cannot acquire
+a stage containing old parameters through these methods. Host terminally rejects an
+unsettled stage if an older/custom store nevertheless returns an erased child by origin,
+so the attachment refusal cannot keep that stage retrying indefinitely. Replay conflict updates preserve
+the stored row, and event reappend remains first-write-wins.
+
+Outbox, stage and invocation claims lock actual candidate rows with `SKIP LOCKED`, without
+a blocking parent lock. Stage cancellation also selects candidates with `SKIP LOCKED`; transactional approval
+expiry uses the optional `lockDueApprovals` transaction member for that selection. Delivery of erased outbox records remains usable: claims,
+renewals, publish/fail acknowledgement and requeue use stored redacted envelopes; failure
+withholds supplied error text and requeue withholds supplied reason text while retaining
+stored prior errors. The optional `renewOutboxLeaseAndRead` capability returns the stored
+envelope atomically with renewal. Relays use that envelope and reject expired responses;
+custom stores retain the boolean `renewOutboxLease` API. A custom store implementing
+erasure without optional renew-and-read keeps a window in which the relay can publish an
+envelope claimed before erasure.
+
+Callers that do not erase still pay an owner `FOR KEY SHARE` lock for owned inserts outside
+a supplied mutation transaction, one locking invocation read per transactional Host event
+append, and one renew-and-read round trip per relayed record. Payload writes that classify
+a zero-row refusal add a classification `SELECT`, including retried owned duplicate event
+appends; conditional boolean/lease writes and ownerless duplicate events omit that query.
+The Host changeset reports the local invocation/adapter insert/update measurements and
+their scope.
+
+These row acquisitions keep erasure from waiting on an ordinary row writer while retaining
+its earlier target locks; it cannot supply the waiting edge of such a row-lock deadlock
+cycle. They do not promise freedom from indirect waits in arbitrary application transactions,
+DDL interference, writer-configured timeouts or external transaction-provider behavior.
+Memory mirrors erased outcomes using its transaction queue and synchronous commit; it does
+not provide PostgreSQL's row-level lock footprint.
+
+Indexed selection, callbacks, rewrites and audit work use `workTimeoutMs` (default 5000 ms).
+Remaining-budget checks and PostgreSQL statement/idle-transaction timeouts bound SQL and idle
+lock retention. Neither budget preempts synchronous JavaScript or promises a hard real-time
+network deadline. Timeout options accept integer milliseconds from 1 to 60000. Providers
+should commit promptly, preserve original rollback errors and discard failed connections.
+Ordinary query timeouts retain their PostgreSQL identity; database-caused `ErasureBusyError`
+retains its cause.
+
+Erasure removes the invocation `parameterDigest` (SQL `NULL`, including
+`submission_refused` rows). Store-owned rewrites replace
+`authorizationBinding.parameterDigest`, `externalCompletion.digest` and the
+`parameterDigest` of rewritten stage rows with exported `ERASED_DIGEST = "erased"`.
+The sentinel is outside the 64-hex SHA-256 output space and preserves required string
+fields and the stage column's `NOT NULL` constraint. `ERASURE_PROTECTED_PATHS` keeps
+these nested fields out of the callback view and rejects their insertion;
+`redactStoredFields` overwrites them after merging protected structure. The stores
+remove or replace top-level digests in the row rewrite, alongside its erasure stamp.
+Repeating erasure leaves these digest fields absent or set to the same sentinel.
+
+Private proposal/event comparison columns, memory maps and equality ports are removed.
+Migration 16 is edited in place because it has not been published; migrations 1–15
+retain their SQL. `packages/platform-host/tests/erasure-digest-cases.ts` checks raw records in both stores,
+including repeat erasure, and `erasureChecks` checks the four digest outcomes.
+
+Host keyed resubmission and recorded-refusal paths evaluate retained actor, binding ID
+and action-version conflicts first. An enforce-mode conflict raises
+`IdempotencyConflictError`; otherwise an erased row raises `StoredRecordsErasedError`,
+including in audit-only mode, before the legacy callback or redacted-result return.
+A caller that is itself refused while the key holds an erased row is handled separately:
+against an erased recorded refusal, a retained-identity conflict leaves the caller's own
+refusal in place and a matching identity raises `StoredRecordsErasedError`; an erased row
+of any other status leaves the caller's own refusal in place.
+`createDurableSagaParentLifecycle` preserves its event-type conflict check, then refuses
+an erased prior event before comparing payloads. Erasure-capable custom stores expose
+`storedRecordsErased` on the mutation transaction's `getEvent` result.
+Store batch-replay paths refuse erased stage rows before digest comparisons, including
+an origin stage erased with its child before child-ID attachment.
+`packages/platform-host/tests/erasure-digest-cases.ts` pins same/different payload refusals and unchanged events.
+
+Host overwrites only the digests it computes itself. A hash that another package or the
+application places inside stored evidence is shown to the redactor and is kept unless the
+redactor removes it. `@fabricorg/policy-opa` stores one by default: `inputHash`, a SHA-256
+of the policy input, in the policy outcome's engine metadata. Remove it in the redactor
+when the policy input can contain erased values, or configure the evaluator's `hashInput`.
+
+The staged `batchDigest` formula now covers parent ID and sorted keys, actions,
+versions and optional principals, excluding parameters and parameter digests.
+Migration 16 replaces persisted `batch_digest` values with `LEGACY_BATCH_DIGEST`.
+Custom `PlatformHostStore` implementations persisting stages should overwrite stored
+batch digests with that placeholder and skip only the batch-digest comparison for
+those rows; the remaining request identity and batch-size comparisons still apply.
+`stagedInvocationRequestMatches` and `LEGACY_BATCH_DIGEST` are exported from
+`@fabricorg/platform-host` for this comparison.
+During a rolling upgrade, an old Host can write payload-covering digests after the
+migration runs. Finish the rollout before relying on this guarantee, and replace
+any such late-written digests with the placeholder.
+Erasure replaces external reconciliation IDs with fresh random `rec_` IDs, including
+on repeated erasure, following the existing reapplication of the redactor.
+See `packages/platform-host/tests/erasure-digests.test.ts` and
+`packages/platform-host/tests/staged-invocations.test.ts` for regression coverage.
+
+Application hashes outside the protected Host paths remain visible to the redactor.
+
+| Field | Coverage and reader before erasure | Erasure result |
+| --- | --- | --- |
+| Invocation `parameterDigest` | Submitted parameters at identity capture, potentially including values removed by write-time redaction; `idempotencyConflict` and `refusalIdentityConflict` | Removed / SQL `NULL` |
+| `authorizationBinding.parameterDigest` | Parameters bound to captured authority; `validateAuthorizationBinding` validates the incoming binding, rather than comparing the stored binding digest | `ERASED_DIGEST` |
+| Staged `parameterDigest` | Canonical child parameters; `stagedInvocationRequestIdentity` feeds store exact-batch comparisons; staged dispatch does not read this field | `ERASED_DIGEST` on rewritten stages |
+| Staged `batchDigest` | Parent ID plus sorted requests; store `stageInvocations` / `applyStagedBatch` drift checks | Payload-free formula; legacy values replaced by migration 16 |
+| `externalCompletion.digest` | Provider, reference, outcome, result, error and evidence, excluding observation time; completion duplicate/contradiction and conditional-write comparisons | `ERASED_DIGEST` |
+| Private proposal / saga payload comparisons | Original proposal and saga payload comparisons | Removed, including columns and memory maps |
+| Contradiction reconciliation ID | `recordCompletionReconciliation` hashes provider/reference/kind, with the kind carrying a completion-digest prefix | Replaced with a fresh random ID |
+
+An older Host reading the missing invocation digest treats the erased row as a legacy
+record and can accept a changed request under its existing key. This is an additional
+reason to upgrade Host instances sharing storage before the first erasure; older writers
+also bypass the erasure guards.
+
+Store SQL guards reject invocation/evidence writes after erasure with `StoredRecordsErasedError`
+(`HOST_RECORDS_ERASED`). Conditional `updateSettledActionInvocation` and
+`writeAdapterInvocation` return `false` in both built-in stores. Late approval recording
+returns its normal replay/refusal outcome without appending fresh attempt evidence for an
+erased record. External completion refuses before reading its supplied payload (`ExternalCompletionError.refusal ===
+"erased"`, a permanent refusal). Completion processing loads the scoped invocation
+before validating supplied completion fields. Erasure retains live memory invocation
+references during its await-free commit so a delayed read observes the marker. First-write-wins event append retains
+the existing redacted event. Outbox claims hydrate the stored redacted envelope. For an erasable store, the relay
+renews the lease and uses the returned stored envelope immediately before publisher handoff and withholds stale claims or
+renewal responses that arrived after the renewed lease expired;
+requeue retains that envelope and redacted prior-error evidence. Requeue replaces
+new operator reason text with `[erased]`, and failure settlement discards new publisher
+error text for erased events. This prevents those late inputs from restoring old text.
+
+Apply migration 16 with `ensureSchema()` and upgrade **Host instances sharing the
+database before the first erasure**. Mixed versions can hold previously loaded payloads.
+A payload handed to a publisher, adapter, caller, cache or downstream consumer before
+erasure commits cannot be recalled. This operation does not erase external systems,
+backups, application domain data or consumer projections; arrange those separately.
+See webhook-delivery's **Event erasure** section for the equivalent delivery limit.
+
+`erasureChecks()` and `runErasureChecks(subject)` provide eight destructive checks for
+isolated test stores. Supply `payloadRecords.seed/read` fixture access to verify the
+record kinds outside the base store's read port. Missing erasure support or fixture
+access reports the relevant check as `skipped`; callback/check errors report `failed`.
+The success probes check for exactly one scoped `HostRecordsErased` event with the
+request's `actorId` and `actorType`. Both built-in stores run the complete kit in their tests.