@fabricorg/platform-host 7.4.0 → 7.6.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @fabricorg/platform-host
 
+## 7.6.0
+
+### Minor Changes
+
+- 74295fd: Add optional `updateAdapterInvocation` and `appendExternalReconciliation` members to `PlatformHostMutationTransaction` (issue #71). The adapter update retains the store method's tenant/space/invocation scope semantics. Memory transactions buffer these writes and undo ledger writes if commit fails; PostgreSQL delegates them to the transaction-bound scoped store.
+
+  Host uses these members for withheld-output and refused-handoff finalization. Evidence events and the adapter's succeeded marker precede the fenced terminal verdict inside the transaction. Withheld-output governance reconciliation shares that transaction when applicable. Leased atomic finalization also requires transaction-scoped `updateLeasedActionInvocation`; missing required members select the verdict-first fallback before evidence writes. Host retries the whole transaction once on a non-lease error, then selects the verdict-first fallback if the retry also fails with a non-lease error. Lease loss on either attempt raises `RecoverableFinalizationError` without fallback. Status telemetry fires after an atomic commit or through fallback verdict persistence. Refused-handoff completion reconciliation logging and its tolerated-failure error update remain after commit. Event IDs, payloads, returned results, and pending-completion selection are unchanged.
+
+  **Release note: failure semantics (issue #71).** When atomic finalization succeeds on a store with the required transaction members, the degraded verdict and its evidence commit together. A rolled-back atomic attempt leaves the invocation and adapter row `running` until the retry or fallback commits. Repeated non-lease transaction failures select the verdict-first fallback so the invocation can reach terminal `reconciliation_required` even when atomic evidence cannot be written. If the fallback evidence write also fails, Host throws `RecoverableFinalizationError` after the verdict commits, retaining the prior terminal-verdict/evidence-gap behavior. Lease loss or failure to persist the fallback verdict can still leave the invocation reclaimable; the adapter then re-runs under its `adapterInvocationId` idempotency key, as after a crash immediately following the adapter return. Previously a terminal verdict could remain with missing evidence and a running adapter row. Non-atomic stores and transactions lacking the required members keep the old verdict-first order and its evidence gap. Custom stores must implement the new transaction members in the same transaction to get the atomic behavior. Finalization failures retain `RecoverableFinalizationError`; adapters still need idempotency or a stable idempotency key.
+
+  A store wrapper that spreads a built-in transaction object (`...transaction`) inherits the new members: Host commits these writes through the inner transaction rather than through the wrapper's store-level overrides of `updateAdapterInvocation` or `appendExternalReconciliation`.
+
+  A successful COMMIT with a lost acknowledgement can cause the leased retry to report lease loss (`RecoverableFinalizationError`) even though the stored state is complete, as with the previous verdict retry.
+
+- 5d93521: Add `ReconciliationRequiredError` and `isReconciliationRequiredError` to Platform's root and policies exports (issue #70). The error accepts a message and optional cause; its stable name and `EXECUTION_RECONCILIATION_REQUIRED` code support recognition across package copies.
+
+  Host honours this signal at the handler-transaction catch, including a store wrapper detecting that its own recovery receipt no longer matches the action's declared events or result schema before handing it back. Wrappers cannot tell which Host transaction they wrap: the same API also serves finalization and external completion. Translate only conditions the store detects itself, not Host internal errors matched by message text; those errors have no public stable code or message contract. Put non-sensitive operator detail in the message because `cause` is not stored. It redacts the message, persists terminal `reconciliation_required`, and returns consistency and HITL metadata. The existing status telemetry fires through persistence. Re-execution returns the terminal record without running the handler; adapters do not run after this signal. Atomic `transactionWithEvents` stores roll back the attempt's domain writes, domain events, and `StateTransitioned` together. On the `transaction`-only fallback, Host appends events directly and the built-in stores do not roll back: domain writes and any events already appended during the attempt stay persisted beside the `reconciliation_required` record, as they already do beside `failed`. A custom fallback transaction may roll back domain writes, but Host does not make event appends atomic with those writes.
+
+  **Release note: failure semantics (issue #70).** Previously these handler-transaction throws recorded terminal `failed`. Opting into `ReconciliationRequiredError` now requests an operator decision where a domain effect may already have committed. Ordinary handler errors, pre-handler governance/validation, state guards, adapters, and finalization retain their existing failure or recovery semantics. `after_adapters` finalization still uses `RecoverableFinalizationError`. Workers continue counting returned reconciliation results as `failed`. No new event is introduced. Host's Platform peer remains `workspace:^` so published packages require the Platform release containing the runtime exports.
+
+- 73d5f98: Preserve the validated transition for idempotent `after_adapters` actions in the optional durable invocation field `pendingStateTransition` (issue #69). Host saves the entity type, entity ID, original state, and target. With a mutation transaction, it writes through transaction-scoped `updateActionInvocation` after the handler succeeds and result/events validate, just before the callback returns. This avoids holding the invocation row lock during the handler while keeping the evidence atomic with domain writes. Without a mutation transaction, Host writes before the handler. Non-idempotent actions do not write the field. The saved transition is retained as evidence after completion. Memory and PostgreSQL stores persist it through invocation patches; PostgreSQL supports both ordinary and leased updates.
+
+  **Release note: recovery semantics (issue #69).** A recovered replay admitted by the same-invocation state shortcut can emit the original `StateTransitioned` after adapters when the saved entity type, entity ID, and target match the current binding and state. It uses the saved `fromState`, the existing payload shape, and the stable `state:transition` event ID; built-in event and outbox stores deduplicate that ID. A handler-supplied transition for the same subject still suppresses Host emission. Custom stores must persist and reload `pendingStateTransition`, including through transaction-scoped `updateActionInvocation`, to get this behavior. Invocations started before upgrading have no saved transition and get no re-emitted event. Missing or mismatched evidence preserves replay acceptance without fabricating a prior state. PostgreSQL `ensureSchema()` adds the `pending_state_transition jsonb` column through additive migration 7, preserving the checksums of earlier migrations. `before_adapters` continues to record the transition with the handler's events and does not write this field.
+
+## 7.5.0
+
+### Minor Changes
+
+- e32ee98: Add opt-in tenant/space/vendor circuit-breaker isolation (issue #52). Platform exports `AdapterCircuitBreakerScope` and `scopedAdapterCircuitBreakerKey` from the root and adapters subpath, accepts optional scope in providers, and adds registry `key` and `getByKey` APIs. Host passes trusted invocation tenant/space scope to providers.
+
+  The default `adapterType:operation` key and its shared failure domain are unchanged. Consumers can inject `new AdapterCircuitBreakerRegistry({ key: scopedAdapterCircuitBreakerKey })` to prevent one tenant's failures from refusing another tenant's calls. The helper encodes components, distinguishes absent space/vendor from empty values, and uses a separate vendor-specific unscoped namespace when scope is absent. Calls without scope share that namespace; tenant isolation requires scope. Keys appear in telemetry and errors, so use non-secret identifiers.
+
+  The first config seen for a key wins, including custom keys; later conflicting configs reuse the existing breaker without throwing. Existing one-argument providers remain compatible. Host's `workspace:^` Platform peer declaration is unchanged: passing an extra argument is compatible with older implementations, and Host adds no runtime import of the new helper. Release tooling resolves the workspace peer against the released Platform version.
+
+- cfada18: Restrict the idempotent same-state replay shortcut to the invocation that wrote the current recorded state (issue #55).
+
+  **Release note: validation change.** The shortcut now applies only to a retry of the invocation whose event set the current recorded state. A new invocation re-applying an already-reached state is validated normally and fails unless the state machine defines that edge. Model a self-loop for a new mutation, or submit with the same idempotency key to deduplicate to the original invocation at submission. An idempotent action targeting the machine's initial state on an entity with no recorded state (or a binding with no entity ID), previously admitted by the shortcut, is now validated normally and needs an initial-state self-loop.
+
+  Stores and mutation transactions can implement the new optional `getEntityStateSource()` method to return the state and invocation writer of the event selected by `getEntityState()`. Memory and PostgreSQL stores provide it, including transaction-scoped reads. Custom stores without the method fall back to subject-scoped `listEvents()` provenance, or to normal transition validation when neither capability is available. Unavailable provenance does not authorize the shortcut.
+
+- f136016: Add optional Host redaction hooks for adapter output, error text, and external completion results (issue #53).
+
+  `redactAdapterOutput` runs before adapter output persistence and handoff processing. Adapter rows, success events and `extractExecutionAttestation` receive redacted output. A throwing hook or null, array, or non-object return withholds output. Host writes its reconciliation verdict before audit evidence and the succeeded adapter marker, retrying a failed idempotent verdict write once while retaining lease fencing. After a durable verdict, direct execution/recovery do not repeat the adapter. Later evidence/marker failures retain the verdict but can leave incomplete evidence; if both verdict-write attempts fail, the adapter can run again on recovery, the same exposure as a crash mid-step. Adapters behind these paths should be idempotent or carry a stable idempotency key. Lease loss can also prevent this branch from recording its verdict. A first accepted reference is retained for callback evidence.
+
+  `redactErrorText` receives exported `ErrorTextRedactionContext`. Empty error input bypasses the hook unchanged. For non-empty input, execution paths use a fixed placeholder if the hook throws or returns a non-string or empty string. Completion error-text redaction failures instead refuse before writes as non-retryable `redaction_failed`. Circuit-open and consistency messages pass through this hook as adapter text; Host's own fixed text bypasses it.
+
+  `redactExternalCompletionResult` runs before merge, validation and persistence; a throw or null, array, or non-object return refuses before writes. Both object hooks accept class instances and Dates, using the existing adapter-output `isRecord` predicate. Stored digests hash redacted result/error values when hooks are set. A matching legacy raw incoming digest is acknowledged in memory before invoking hooks; newly stored digests use redacted values. Contradiction detection compares retained values otherwise. Keep redactors deterministic and stable across deploys; a changed redactor can make a repeat look like different evidence. Existing records are not rewritten.
+
+  Consumers with an exhaustive switch over `ExternalCompletionRefusal` need the new `redaction_failed` case. `redactActionParameters` and `redactAdapterInput` behavior is unchanged. Independently of the new hooks, a worker that loses its lease inside an adapter step now rethrows `RecoverableFinalizationError` without marking the adapter failed, preserving the new owner's row. Refused handoffs write their reconciliation verdict before the adapter marker and emit safe success/accepted audit events. These are default-behavior changes.
+
+- 4e429a3: Add `RetryableExecutionError` and `isRetryableExecutionError` to Platform's root and policies exports (issue #56). The error accepts a message and optional cause; its stable name and `EXECUTION_RETRYABLE` code support recognition across package copies.
+
+  Host adds `retryableExecutionMaxAttempts` (positive integer, default 5). During governance before policy-evaluation persistence, the error is rethrown unchanged for a leased, idempotent invocation below that cap, excluding approval resume. Workers report it through `onError`, stop the heartbeat, and can reclaim the invocation after lease expiry. Cycle results and `worker.cycle.completed` telemetry include an optional `deferred` count when positive; it counts every `RetryableExecutionError` that escapes execution, and those do not increment `failed`.
+
+  The retry region covers parameter validation, mutation-governance resolution and its single-record checkpoint write, HITL evaluation and its single-record checkpoint write, entitlement, execution authorization, policy resolution, and policy evaluation. Host reuses persisted mutation-governance and HITL decisions through checkpoint guards. The region ends before the first policy-evaluation record is written. Policy persistence, `ComplianceBlocked`, obligation listing/resolution/persistence, state-machine checks, the handler transaction, handlers, adapters, and finalization retain their existing failure/reconciliation/recovery semantics.
+
+  **Release note: failure semantics (issue #56).** Previously a transient thrown governance error terminally failed the invocation. Opting into `RetryableExecutionError` now leaves an eligible invocation `running` for lease-based recovery, with no failure/status write and no policy evidence written by that attempt. Unleased inline execution, approval resume, non-idempotent actions, and attempts at the cap fail with an explanatory message through the existing redactor. Approval resume's temporary lease does not establish that a recovery worker is configured. Obligation-resolver and policy/obligation-persistence errors remain terminal. Application callbacks should be repeatable and use stable invocation-scoped evidence. Host's Platform peer range remains `workspace:^` so published packages require the Platform release containing the new runtime exports.
+
+- 90c1266: Scope adapter invocation reads and writes by tenant, space, and owning action invocation (issue #57). Export `AdapterInvocationScope` and add it as an optional trailing argument to store get/update methods; Host supplies it from the store-loaded invocation, and the shipped memory and PostgreSQL stores enforce all three fields when supplied. Calls without scope retain ID-only behavior for compatibility. Custom store implementers must honour the new optional `scope` argument: the two new adapter isolation checks fail for a store that ignores it, so a deployment running `runTenantIsolationChecks` against a custom store will see new failures until the store scopes these lookups. `TenantIsolationCheck["id"]` gains two members and `runTenantIsolationChecks` results now carry eight entries, so exhaustive switches over check IDs need the additional cases.
+- 93b9830: Host now emits `StateTransitioned` after a validated bound state-machine transition and successful handler execution, following the action's `eventPhase` (issue #54).
+
+  The version-1 payload contains `entityType`, `entityId`, `fromState`, `toState`, and `causedByAction`. The subject identifies the bound entity. Host appends the fact immediately after the handler's domain events using a stable invocation-scoped event ID. With `transactionWithEvents`, it shares the domain events' transaction in the selected phase; otherwise it follows the legacy non-atomic boundary, as domain events do. It is published through the outbox by default; applications can filter it with `outbox.shouldPublish`.
+
+  Under `before_adapters`, the transition is appended during handler execution. Under `after_adapters`, it is deferred to finalization after required adapter steps succeed or accept a parked external handoff. Adapter failure withholds both domain events and the transition, so the invocation does not advance Host's recorded entity state even though handler writes may have committed. Atomic finalization commits the deferred events and invocation update together; fallback stores retain non-atomic append and update behavior. Invalid transitions, failed handlers, empty targets, undefined or empty entity IDs, and replay-only acceptance in the target state do not emit a Host transition fact.
+
+  Applications that append their own `StateTransitioned` for the bound entity get no duplicate from Host: the handler's returned events suppress Host emission when both subject type and ID match, in either event phase. Those applications should drop the workaround to use Host emission.
+
+  **Release note: validation change.** Previously, when an application did not write `toState` in its events, Host's recorded state remained unset and validation fell back to the initial state on later calls. Host's new transition fact advances recorded state, so later calls validate against that advanced state. A non-idempotent bound action that previously passed repeatedly (for example, `draft -> active`) can now be rejected on the second call (`active -> active`) unless the machine defines that edge. Model the missing edges or self-loops, or submit with the same idempotency key to deduplicate to the original invocation at submission. Applications that already emitted `toState` in their domain events see no change to this validation behavior when that `toState` matches the binding's target state; otherwise Host's fact, appended after the domain events, sets the recorded state to the target. This minor release introduces the stated failure semantics.
+
 ## 7.4.0
 
 ### Minor Changes

package/README.md

@@ -47,6 +47,79 @@ reclaimed so its token advances. An expired worker cannot finalize after another
 `idempotencyKey` to `submitAction()` so retries resolve
 to the original tenant-scoped invocation instead of creating another mutation.
 
+For transient governance dependency failures, throw `RetryableExecutionError` from
+`@fabricorg/platform` (also exported from `@fabricorg/platform/policies`). The retry region covers
+parameter validation, mutation-governance resolution, HITL evaluation, entitlement and execution
+authorization (including the `authorize` fallback), policy resolution, and policy evaluation. It ends
+immediately before the first policy-evaluation record is written. Host rethrows the original error
+without a failure/status write when:
+
+- the invocation has a lease owner and a defined lease token;
+- the action declares `idempotent: true`;
+- `attemptCount` is below `retryableExecutionMaxAttempts`, a positive integer option defaulting to 5; and
+- execution is not a `resumeApprovedInvocation()` call.
+
+The worker reports the original error through `onError` and stops its heartbeat. Its cycle result
+and `worker.cycle.completed` telemetry include `deferred` only when the count is greater than zero;
+deferrals do not increment `failed`. The worker counts by error type: a `RetryableExecutionError`
+that a store wrapper throws from Host's own reads or status writes also lands in `deferred`. In that
+case the row likewise stays leased for a later claim, but outside this cap. Retry becomes eligible when the current lease expires, so the
+delay is the remaining lease duration, followed by the worker's next claim; there is no immediate
+retry or separate backoff. The next claim increments `attemptCount`. At the cap, or for an unleased,
+non-idempotent, or approval-resume invocation, Host records `failed` with the reason retry was refused,
+through the error-text redactor. Approval resume is excluded because its temporary lease does not
+establish that a recovery worker is configured. Ordinary thrown errors retain terminal failure behavior.
+
+The retry region includes Host's single-record store writes for mutation-governance and HITL
+checkpoints. Later attempts reuse these persisted decisions through the `mutationFootprint` and
+`hitlRoute` guards. Callbacks should be safe to repeat and return stable invocation-scoped evidence.
+A deferral happens before the attempt writes any policy evidence: the complete definition batch must
+evaluate before Host starts appending policy records. Policy persistence, the `ComplianceBlocked`
+event, obligation listing/resolution/persistence, state-machine checks, the handler transaction,
+handlers, adapters, and finalization retain their existing failure/reconciliation/recovery semantics.
+A retryable obligation-resolver error fails terminally with the policy evidence from that attempt.
+Preview evaluation does not enter this execution catch.
+
+**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
+must decide how to proceed. For example, a recovery-receipt store can check its own stored result
+against the action's current declared events and result schema before handing that result back.
+If its own check detects an incompatible receipt from an earlier attempt, it can throw this signal.
+Put non-sensitive operator detail in the message: Host stores the redacted message, not `cause`.
+The cross-copy predicate
+`isReconciliationRequiredError` recognises the stable name and `EXECUTION_RECONCILIATION_REQUIRED`
+code as well as local instances.
+
+A `transactionWithEvents` wrapper cannot tell which Host transaction it is wrapping from the public
+callback contract: Host also uses this API for `after_adapters` finalization and external completion.
+Translate only a condition the store detects itself while recovering its own receipt, and let other
+errors propagate unchanged. Do not match Host's internal validation-error messages; those errors
+have no public stable code or message contract.
+
+Host honours the signal only at the handler-transaction catch, covering `transactionWithEvents`
+and the fallback `transaction`. It redacts the message with `redactErrorText` using `source: "handler"`,
+records terminal `reconciliation_required`, and returns the error with the action's consistency and
+persisted HITL route/risk tier. Status persistence emits the existing reconciliation telemetry.
+Re-execution returns the terminal record without running the handler. Workers retain their existing
+counting: a returned reconciliation result increments `failed`, not `completed` or `deferred`.
+
+Atomic `transactionWithEvents` stores roll back the attempt's domain writes, domain events, and
+Host's `StateTransitioned` together when the transaction throws. On the `transaction`-only fallback,
+Host appends events directly. The built-in stores simply run the callback without rollback: domain
+writes and any events Host appended during the attempt stay persisted beside the
+`reconciliation_required` record, as they already do beside `failed`. A custom fallback transaction
+may roll back its domain writes, but Host does not make its event appends atomic with those writes.
+Host does not run adapters after this signal or add a new lifecycle event for it. Effects or evidence
+committed by earlier attempts are not undone.
+
+The signal does not change failures in pre-handler governance or validation, state-transition guard
+exceptions, adapters, or finalization. Governance and adapter throws retain their existing `failed`
+paths. State guards still fail closed. `after_adapters` finalization failures still escape as
+`RecoverableFinalizationError` for recovery; other finalization throws retain their existing failure
+path. An ordinary handler error 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
 `idempotency.conflictMode` as `audit-only` for a preflight soak. Legacy null-digest rows skip only the
@@ -77,6 +150,30 @@ process, to receive breaker telemetry (`new AdapterCircuitBreakerRegistry({ onEv
 manual override (`registry.get(type, operation)?.setManualOverride("force_open")`), or to supply a
 custom `AdapterCircuitBreakerProvider`.
 
+The default key is shared across tenants, spaces, and vendors within one registry: one tenant's
+failures can open the breaker for another. For tenant/space/vendor isolation, inject a scoped registry:
+
+```ts
+import { AdapterCircuitBreakerRegistry, scopedAdapterCircuitBreakerKey } from "@fabricorg/platform/adapters";
+
+const adapterCircuitBreakers = new AdapterCircuitBreakerRegistry({ key: scopedAdapterCircuitBreakerKey });
+// Pass adapterCircuitBreakers to createGovernedActionHost({ store, registry, adapters, ... }).
+```
+
+Host passes the trusted `{ tenantId, spaceId }` invocation context to `forAdapter(adapter, scope)`;
+providers receive it from `@fabricorg/platform-host` 7.5.0 on. Existing one-argument providers remain compatible. The first config
+seen for a registry key wins; later conflicting configs reuse the existing breaker without throwing.
+Adapters sharing a key should use the same configuration. The helper URI-encodes components and
+preserves a readable `adapterType:operation` suffix for ordinary identifiers. Missing space or vendor
+is distinct from an empty string; `vendor` is required by the TypeScript adapter contract.
+Calls made outside Host without scope use a separate vendor-specific `unscoped` namespace and share
+breakers there; tenant isolation requires scope. Use non-secret identifiers because keys appear in
+telemetry and errors. Breakers are never evicted: a scoped key creates one breaker per tenant, space, vendor and operation
+for the life of the registry, and those keys are high-cardinality, so do not use them as metric labels.
+For a custom-keyed breaker, use
+`registry.getByKey(scopedAdapterCircuitBreakerKey(adapter, scope))`; `get(type, operation)` continues
+to look up the default key.
+
 The breaker is consulted immediately before every attempt, including retries. Host writes the attempt number to the adapter invocation record first, in `prepareAttempt`, so nothing awaits between admission and the adapter call; a store failure there is not counted against the breaker. In `monitor` mode it
 never blocks. In `enforce` mode, while it is open, Host does not call the adapter: the adapter
 invocation is marked `failed`, `AdapterInvocationFailed` is appended with
@@ -153,17 +250,26 @@ in action parameters or workflow history.
 Production stores can implement `AtomicMutationPlatformHostStore.transactionWithEvents`. The
 transaction-scoped `db`, event sequence, event append, event listing, and invocation update methods
 must all use the same database transaction.
+The optional transaction-scoped `updateAdapterInvocation` and `appendExternalReconciliation`
+operations extend this unit of work to degraded adapter finalization, as described under redaction
+below.
 
 `PostgresPlatformHostStore` enables this capability when constructed with a
 `PostgresPlatformHostTransactionProvider`. The application owns that narrow binder because only the
 application knows how its `TDb` is rebound to the transaction's SQL client.
 
-- `before_adapters`: handler domain writes and declared domain events commit or roll back together.
-- `after_adapters`: completion events and invocation completion commit together. A finalization
+With `transactionWithEvents`:
+
+- `before_adapters`: handler domain writes, declared domain events, and the Host-generated
+  `StateTransitioned` fact commit or roll back together.
+- `after_adapters`: declared domain events, the Host-generated `StateTransitioned` fact, and
+  invocation finalization commit together after required adapter steps succeed or accept a
+  parked external handoff. Handler writes have already committed separately. A finalization
   failure leaves the invocation recoverable; succeeded adapter checkpoints are not repeated.
 
-Stores without this additive capability retain the legacy boundary for compatibility and must not
-claim atomic domain-write/event persistence.
+Stores without `transactionWithEvents` retain the legacy non-atomic boundary for domain writes,
+events, and invocation persistence. A partial append or finalization failure can leave some
+records persisted; this path does not provide atomic domain-write/event persistence.
 
 `createDurableSagaParentLifecycle()` requires this capability. Each parent lifecycle transition uses a
 stable `lifecycleId` as its causation identity, appends its audit event, and updates the parent invocation
@@ -229,6 +335,80 @@ and pass an opaque identifier instead; action parameters are intentionally durab
 Hosts should additionally configure `redactActionParameters` as a fail-safe allowlist for actions
 whose ingress is adjacent to secret material; redaction runs before the invocation row is created.
 
+Three optional `PlatformHostOptions` hooks cover other Host-recorded values.
+
+| Hook | When it runs and what uses its return value |
+| --- | --- |
+| `redactAdapterOutput(actionId, adapterType, operation, output)` | Once after a successful adapter result is converted to output, before handoff handling. The adapter row, `AdapterInvocationSucceeded` payload, and `extractExecutionAttestation` input use the redacted output. |
+| `redactErrorText(context, message)` | At the origin of caught handler/execution errors, adapter result errors and ambiguous-outcome reasons, and completion errors. The invocation/adapter errors, reconciliation messages and reasons, completion evidence, failure events, and returned error reuse that text. |
+| `redactExternalCompletionResult(actionId, provider, result)` | After a completion matches its invocation, before merging, result-schema validation, persistence, and digesting. See [External completion](#external-completion). |
+
+`ErrorTextRedactionContext` is exported. It contains `actionId` and `source` (`handler`, `adapter`,
+`external_completion`, or `execution`); adapter errors also supply `adapterType`, `operation`, and
+`provider` (the adapter vendor), while completion errors supply `provider`. Exceptions from
+application execution hooks such as `getInput` and `extractExecutionAttestation` use `execution`.
+Host-authored fixed messages and structured identifiers, including `externalReference`, bypass this
+hook. Circuit-open errors and consistency errors use adapter context because an adapter can supply
+those messages or their interpolated values. When Host adds context around a caught store error,
+only the caught part is redacted. Empty originating error text bypasses the hook unchanged. For non-empty input, a hook that throws,
+returns a non-string, or returns an empty string uses `Error text withheld: the error-text redactor failed.` on execution paths. These paths retain
+their failure classification when the error can be persisted. For a completion error, the same hook
+failures refuse with non-retryable `redaction_failed` before writes, allowing a sender to submit the
+callback after the redactor is repaired.
+
+If `redactAdapterOutput` throws or returns null, an array, or a non-object value, the external effect
+has already happened. Host withholds output and records a `reconciliation_required` verdict. Its
+safe evidence includes the retained handoff's `ExternalOperationAccepted`,
+`AdapterInvocationSucceeded` with redacted input and `outputWithheld: true` without output, and
+fixed-text reconciliation evidence when the store supports governance. The events use the normal
+step deduplication keys. A first accepted reference is retained as `pendingCompletion`, so its
+callback can still land as evidence. References come from the original adapter result.
+
+For withheld output and refused handoffs (immediate completion or a second handoff), Host uses
+`transactionWithEvents` when the transaction supplies `updateAdapterInvocation`,
+`updateLeasedActionInvocation` for a leased invocation, and `appendExternalReconciliation` for
+withheld output on a governance-capable store. These optional members must
+share the event/verdict transaction; the adapter update must enforce the store method's supplied
+tenant, space, and invocation scope. Both built-in stores provide them when configured with a
+transaction provider. Custom stores must implement them to get this atomic behavior.
+
+When atomic finalization succeeds, evidence events, any withheld-output reconciliation entry, the adapter's `succeeded`
+marker, and the terminal `reconciliation_required` verdict commit together. Host writes evidence and
+the marker before the fenced verdict, which releases the lease, then emits status telemetry after
+commit. It retries the whole transaction once on a non-lease error. If the retry also fails with a
+non-lease error, Host selects the verdict-first fallback described below. Lease loss is not retried
+or converted to fallback; it raises `RecoverableFinalizationError`. Atomic rollback leaves the
+invocation and adapter row `running` until a retry or fallback commits. If lease loss or an unavailable
+fallback verdict prevents finalization, the invocation remains reclaimable and the adapter can run
+again under the same `adapterInvocationId` idempotency key. Adapters should be idempotent or carry
+that stable idempotency key.
+
+Without the required transaction members, or after two non-lease transaction failures, Host keeps
+the verdict-first order: the `reconciliation_required` verdict precedes evidence and the adapter marker. It retries the verdict
+write once, except on lease loss. A later evidence or marker failure raises
+`RecoverableFinalizationError` after the verdict commits and can leave a terminal verdict with missing
+evidence, including when the same deterministic failure affects the transaction and fallback. If both verdict-write attempts fail, the adapter can run again on recovery,
+the same exposure as a crash mid-step; adapters should be idempotent or carry a stable idempotency key.
+Direct execution returns a durable terminal verdict and recovery excludes it through terminal-status
+checks. Refused-handoff completion reconciliation logging stays after finalization. After atomic
+finalization, a failed log write leaves the committed verdict and adapter marker intact if the
+unfenced invocation-error update succeeds. If that error update also fails, the existing adapter-error
+catch can mark the adapter and invocation `failed`.
+
+`extractExecutionAttestation` receives the redacted output, so an extractor that needs a stripped
+field can fail after the external effect, following the existing extractor-failure behavior.
+
+`redactActionParameters` and `redactAdapterInput` behavior is unchanged. Independently of hook
+configuration, a stale worker that loses its lease inside an adapter step rethrows without marking
+the adapter failed, preserving the new owner's row. Refused-handoff ordering and audit events also
+change without the new hooks.
+
+Applications own the safety of domain events/results, policy and HITL evidence, explicit
+attestations/reconciliations, saga lifecycle inputs, approval reasons, and outbox publisher errors.
+Parameter-schema issue messages used for `validation_failed`, the `HITL rejected` reason, policy
+block reasons, and action-result validation paths are not passed through `redactErrorText`.
+These hooks do not rewrite historical records or exceptions delivered to a worker's `onError`.
+
 ## Submission snapshot
 
 `submitAction` reads the scalar fields of the caller's `SubmitActionInput` once, before its first
@@ -393,13 +573,104 @@ controlled deployment migration step, and hydrate projections from `listEvents()
 uses ordered immutable checksums, a migration ledger, and a transaction-scoped advisory lock. It
 remains safe to call at startup, but deployment-owned migrations are preferred.
 
-State-machine transition checks run inside the Host mutation unit of work. Transaction-capable
-stores should expose transaction-scoped `getEntityState()` so the guard reads the same database
-snapshot used by the handler and event append. Existing custom stores without that optional
-transaction method fall back to the store-level authoritative read.
+State-machine transition checks run inside the Host mutation unit of work, before the handler. Stores implementing `transactionWithEvents`
+should expose transaction-scoped `getEntityState()` so the guard reads the same database snapshot
+used by the handler. Existing custom stores without that optional transaction method fall back
+to the store-level authoritative read.
+
+An idempotent action may resume in its target state despite a missing self-loop only when the
+event that set the current recorded state belongs to that same `actionInvocationId`. The handler
+can rerun while stable event IDs suppress duplicate events. A new invocation validates normally;
+model a self-loop if it should re-apply the state, or use the same idempotency key to deduplicate
+to the original invocation at submission.
+
+The optional `getEntityStateSource(tenantId, spaceId, entityType, entityId)` store and transaction
+method returns `{ state, actionInvocationId }` from the same event as `getEntityState()`, or
+`undefined` when provenance is unavailable. Memory transaction reads include pending events.
+Host prefers the transaction method, then the store method. If neither is implemented, it uses
+transaction `listEvents()`, otherwise store `listEvents()` when available, selecting the subject's
+highest-sequence event with a string `payload.toState`. The source state and invocation writer
+must match the current state and invocation. Missing provenance leaves normal validation in force;
+custom stores can continue compiling without the optional method.
+
+After a valid transition for a binding with a non-empty entity ID and target, Host appends
+`StateTransitioned` immediately after the handler's domain events, following the action's
+`eventPhase`. Its subject is the bound entity and its version-1 payload is
+`{ entityType, entityId, fromState, toState, causedByAction }`. `fromState` is the trusted state
+read before the handler, and `causedByAction` is the action ID. The event uses a stable
+invocation-scoped ID and is publishable through the outbox by default; `outbox.shouldPublish`
+can filter it. It does not need an `emitsEvents` declaration from the action.
+
+For `before_adapters`, the transition is appended with the handler's domain events. For
+`after_adapters`, it is deferred to finalization after required adapter steps succeed or
+accept a parked external handoff, immediately after domain events. Adapter failure withholds
+both domain events and the transition, leaving the built-in stores' ledger-derived entity state
+unchanged by that invocation even though handler writes may have committed. Custom stores that
+read domain rows can already observe the target state at this point. With `transactionWithEvents`, the
+transition shares the transaction used for domain events in the selected phase; otherwise it
+follows the same legacy non-atomic boundary as domain events.
+
+For idempotent `after_adapters` actions, Host saves `pendingStateTransition` on the invocation.
+It contains `{ entityType, entityId, fromState, toState }` from the validated transition.
+Custom stores must persist and return this optional invocation-record field through
+`updateActionInvocation`, including the transaction-scoped method. With a mutation transaction,
+Host writes the field after the handler succeeds and result/events validate, just before returning
+from the transaction callback. This keeps the invocation row lock out of the handler run while the
+saved transition commits or rolls back with the domain writes. The `transaction`-only fallback saves
+it separately before the handler. Non-idempotent actions do not write this field. It is retained as
+evidence after completion. PostgreSQL `ensureSchema()` adds `pending_state_transition jsonb`.
+
+On an admitted same-invocation replay, Host uses the saved `fromState` when the saved entity type,
+entity ID, and target match the current binding and state. The fact follows the usual event phase
+and stable `state:transition` ID, so built-in stores deduplicate an already appended event.
+Invocations started before upgrading, or stores that omit this evidence, retain replay acceptance
+without a re-emitted transition. Mismatched evidence also suppresses replay emission.
+
+Invalid transitions, failed handlers, replay acceptance without matching saved evidence, and
+bindings without a non-empty entity ID or target do not produce a Host transition fact. If the handler
+returns its own `StateTransitioned` with the bound entity's subject type and ID, Host suppresses
+its generated fact in either event phase. Applications using that workaround should remove it
+to use Host emission.
+
+Host's new transition fact advances recorded state even if handler domain events omit `toState`.
+Later calls validate against that advanced state; a new invocation can fail if the
+machine lacks the corresponding edge or self-loop. Model those edges, or submit with the same
+idempotency key to deduplicate to the original invocation. Applications already recording `toState` in
+domain events retain their existing state advancement behavior when that `toState` matches the
+binding's target; otherwise Host's later fact sets the recorded state to the target.
 
 ## External completion
 
+Configure `redactExternalCompletionResult` to withhold sensitive completion fields. Host applies it
+once to a supplied result (including a result attached to a failed callback). The redacted value
+feeds `externalCompletion.result`; for a completed outcome it also feeds the adapter output,
+`ExternalOperationCompleted` payload, merged invocation result, and returned result. A supplied
+`completion.error` passes through `redactErrorText` before recording, including when attached to a
+completed outcome. A missing error uses Host's fixed failure message, which bypasses the hook.
+
+The recorded digest hashes the redacted result and error when hooks are configured. A repeat first compares the raw incoming digest in memory before invoking any hook, recognizing
+legacy records even if a newly configured redactor would fail. Otherwise it compares the redacted digest. Newly stored digests use the redacted representation.
+Contradiction detection therefore compares what redactors retain; differences they discard are
+considered the same news. The compatibility match leaves historical records intact.
+
+Redactors should be deterministic and stable across deploys. A changed redactor can make a repeat
+look like different evidence and trigger contradiction handling.
+
+The object hooks accept non-null, non-array objects, including class instances and Dates, matching
+the existing adapter-output `isRecord` predicate. Strings, arrays and null are rejected.
+
+If completion-result redaction throws or returns null, an array, or a non-object, or completion
+error-text redaction throws or returns a non-string or empty string for non-empty input, `ExternalCompletionError.refusal` is `redaction_failed` and
+`retryable` is false. Host refuses it before writing the invocation, adapter row, event, or
+reconciliation evidence; fix the redactor before submitting again. Consumers with exhaustive
+`ExternalCompletionRefusal` switches need a `redaction_failed` case. Other permanent refusals are
+`not_found`, `not_awaiting`, `immediate_contract`, `reference_mismatch`, `provider_mismatch`,
+`invalid_completion`, and `result_invalid`; `still_executing` is retryable.
+
+While a redaction hook is failing, a contradicting repeat that needs redaction is also refused with
+`redaction_failed`, without recording a contradiction. A matching legacy raw digest still returns
+before hooks run. Empty completion error input bypasses the error-text hook unchanged.
+
 An action declaring `completion: "accepted"` or `"long-running"` may hand its work to an external
 system. The adapter returns `acceptedExternalOperation: { externalReference }`; the Host parks the
 invocation as `running` with no lease, emits `ExternalOperationAccepted`, and leaves it for the
@@ -421,7 +692,8 @@ reference, outcome, result, error, and evidence. A contradictory one, a flipped
 outcome with different evidence, moves the invocation to
 `reconciliation_required`, keeps the first outcome on record, logs the second, and emits
 `ExternalOperationContradicted`. Under an atomic store the read and write happen under one lock. The
-callback's result is validated against the action's result schema and stripped of private fields.
+callback's redacted result is merged with the invocation result, stripped of private fields, and
+validated against the action's result schema before writes. The stored merge is what is validated.
 An invocation that ended for another reason while a handoff was pending keeps its status and records
 the callback as evidence. Declare `completionDeadlineMs` on `long-running` actions;
 `reconcileOverdueCompletions()` moves overdue handoffs to reconciliation while keeping the handoff so
@@ -453,12 +725,20 @@ cast in an index expression is not immutable and PostgreSQL refuses it.
 
 ## Tenant isolation
 
-`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` prove that scope is a key on every
-read, write, claim, and completion: an invocation is invisible, inert, and uncompletable under another
-tenant's scope; the same idempotency key in two tenants is two invocations; event streams carry only
-their own tenant's events; a tenant-scoped worker claims nothing of another's; and a governed read
-the subject lends shows the other tenant none of ours. The subject supplies a host, a recoverable
-store, a registered action, and two scopes in different tenants.
+`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` run eight checks against a host
+and its store. They prove scope on the invocation reads and writes, idempotency keys, event streams,
+worker 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 checks create probes in dedicated spaces and retire them afterwards.
+
+Host passes `AdapterInvocationScope` from the store-loaded action invocation to
+`getAdapterInvocation(id, scope)` and `updateAdapterInvocation(id, patch, scope)`. Custom stores
+must match `tenantId`, `spaceId`, and `actionInvocationId` when scope is supplied. A mismatch returns
+`undefined` on read and leaves the row unchanged on update (a not-found error is permitted).
+The trailing argument is optional to preserve existing custom-store and direct-call compatibility;
+calls without it retain ID-only behavior in the shipped stores. 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.
 
 ## Runtime observability and health