@fabricorg/platform-host 8.1.2 → 8.3.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @fabricorg/platform-host
 
+## 8.3.0
+
+### Minor Changes
+
+- 749c507: Add host-owned staged descendant invocations. Actions declare an allowlist and return typed child
+  requests; Platform Host validates and redacts them atomically, releases them only after parent
+  completion, and dispatches them through fresh entitlement, authorization, admission, runtime
+  evidence, policy, and HITL decisions.
+
+  PostgreSQL migration 11 adds the staged-invocation ledger and caller-unforgeable child-origin unique
+  index. Child identity is a Host-only parent-invocation/stage-key origin. Child creation is
+  atomically fenced on the stage's pending status, lease owner, lease token, and unexpired lease;
+  PostgreSQL locks that stage row `FOR SHARE` while the fenced insert is in flight.
+
+  Each attempt settles a stage through one sequence. It first looks the child up by origin: a child
+  created by an earlier attempt is handed to the dispatcher again with its stable workflow ID while it
+  remains pending, without pre-submission checks or repeated governance, even after a deploy changes
+  the child's schema. Otherwise Host submits the child. When that submission did not itself return
+  the child (a failed check, a refusal, an error, or a timeout), Host rotates the lease token through
+  the store operation `rotateStagedInvocationLease` before an authoritative lookup, so the attempt's
+  own timed-out submission can no longer create the child. A stage is rejected only when that lookup
+  finds no child, and a dead-lettered stage records the child ID whenever the attempt found or created
+  a child. A stage becomes dispatched only after confirmed handoff, when no dispatcher is configured,
+  or when the child has already left pending. A failed child lookup settles the stage for retry and
+  does not dead-letter it. Settlements are compare-and-set on the lease owner and current token and
+  keep a child ID recorded earlier. A store error on one stage is reported through the sweep's
+  `onError` option (the Platform worker passes its own) and does not stop the rest of the batch.
+  Handoff failures retry after a constant one-second delay by default; callers provide `retryDelayMs`
+  for backoff. Public entitlement and authorization refusals now expose `SubmissionRefusalError` with
+  stable `code: "ACTION_SUBMISSION_REFUSED"`. The child inherits the parent's actor type: a
+  natural-person parent therefore does not enter agent HITL, while an agent parent follows the normal
+  agent approval route.
+
+## 8.2.0
+
+### Minor Changes
+
+- 71d306f: Add optional action-level finalization for atomic, immediate after_adapters actions, including non-idempotent actions. Export JSON finalization types, registration validation, a manifest protocol descriptor and defineFinalizingAction to guard handlers against older hosts.
+
+  Host requires atomic transactions, invocation locking and transaction-scoped lease fencing before application execution. On normal success the hook consumes stored redacted outputs and commits transaction-local domain writes, declared events, outbox and the merged result together. Hook or validation failure rolls back finalization and settles reconciliation_required when durable provider effects exist, or failed when there are none, with redacted error text. Lease loss escapes without a stale-worker verdict. Handler preparation writes remain separately committed.
+
+  If entry to or COMMIT of the final success transaction (after adapters) fails with an unknown outcome, Host raises RecoverableFinalizationError and records no verdict. An uncommitted invocation stays running for recovery; a committed completed invocation retains its stored verdict and result for re-execution.
+
+  Explicit undefined on the optional hook return fields events, resultPatch and eventSchemaVersion is treated as omitted. Payloads and result-patch values retain strict JSON validation and reject undefined.
+
+  Failed, ambiguous, degraded and accepted/handoff outcomes do not invoke the hook. Existing actions retain their lifecycle.
+
+  Before adapters, normalize hook parameters and public handler data through a JSON round-trip, stripping private handler carriers. Dates become ISO strings and undefined object properties drop; serialization failures such as cycles or BigInt fail before provider execution. Handler events are normalized separately. Hook event schema versions default to the action version when omitted.
+
+  Add optional Host eventContracts name validation for events returned by the finalize hook. It checks eventType and subjectType membership only; handler events, payload schemas and schema-version compatibility are outside this option's scope. Recovery refusal also preserves ambiguity evidence for in-flight adapter rows alongside succeeded effects.
+
+- d5e7caa: Add optional adapter-step deadlineMs durations overriding the Host-wide duration,
+  including when the Host duration is unset or zero. Action and module registration, manifest export,
+  and manifest normalization reject step durations that are not positive finite integers.
+  Host validates resolved steps before handler or adapter execution. Invalid
+  durations fail a first execution without invoking adapters; retries with recorded
+  applied effects or unknown adapter outcomes require reconciliation instead.
+  Manifests preserve valid step durations.
+
+  Correct adapterDeadlineMs documentation: it is a duration starting just before
+  step retry execution, not an epoch timestamp. Host-wide behavior is unchanged.
+  Budgets span retries; expiry prevents a subsequent attempt and signals cooperative
+  cancellation of an in-flight call. An aborted call that throws retains the existing
+  ambiguous-outcome reconciliation semantics.
+
+- f32aae6: Commit versioned finalization preparation with handler writes, bounded to 256 KiB of canonical UTF-8 JSON. Recovery skips the handler, reuses succeeded adapter outputs and durable skips, and finalizes through the locked success transaction, including non-idempotent actions. Finalizing getInput callbacks receive normalized public data; legacy callbacks retain raw inputs.
+
+  Unknown adapter outcomes, incompatible protocol/action versions/ordered step identities, handoffs and governance refusal after effects retain reconciliation semantics. Missing checkpoints retain prior recovery behavior. Preparation validation/write failures roll back before adapters; unknown commit outcomes and lease loss remain recoverable without a stale verdict.
+
+  Apply migration 10 with ensureSchema before deploying checkpoint-writing Hosts. Updates omitting the field do not require its column.
+
+  A checkpoint bypasses non-idempotent interruption gates only when recorded adapter rows are succeeded. Failed rows preserve interruption settlement without repeating the provider call: failed without recorded success, reconciliation_required after another step succeeded. Leased non-idempotent replay additionally requires store-level and transaction-level writeAdapterInvocation fencing. Idempotent finalizing actions retain failed-row retry under existing adapter retry rules, using saved preparation.
+
+  On the live path, a finalizing action with an earlier succeeded adapter and a later permanent adapter failure now settles reconciliation_required instead of failed, without running the hook. Subsequent execution failures after a recorded provider effect likewise preserve reconciliation of partial progress.
+
+- 3d24330: Permit bounded leased retries of non-idempotent actions after retryable pre-effect governance errors. The additive deferredBeforeEffectAttempt record field proves only the immediately preceding claim deferred before handler or adapter effects. Missing or stale proof retains interruption failure. Marker-write failure retains terminal failure where persistence succeeds; lease loss preserves fencing errors. Approval resume, inline execution, exhausted budgets, and errors after the governance window retain their existing refusal semantics. Workspace dependents receive compatible patch releases.
+
+  PostgreSQL migration 9 (`pre_effect_governance_deferral`) adds the nullable marker column. Run `ensureSchema()` before deploying Hosts that may defer non-idempotent actions. Invocation updates that do not carry the marker omit its column, preserving writes on schemas without migration 9.
+
 ## 8.1.2
 
 ### Patch Changes

package/README.md

@@ -55,7 +55,8 @@ immediately before the first policy-evaluation record is written. Host rethrows
 without a failure/status write when:
 
 - the invocation has a lease owner and a defined lease token;
-- the action declares `idempotent: true`;
+- the action declares `idempotent: true`, or Host successfully records the current claim in
+  `deferredBeforeEffectAttempt` through a lease-fenced write;
 - `attemptCount` is below `retryableExecutionMaxAttempts`, a positive integer option defaulting to 5; and
 - execution is not a `resumeApprovedInvocation()` call.
 
@@ -65,12 +66,24 @@ deferrals do not increment `failed`. The worker counts by error type: a `Retryab
 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,
+retry or separate backoff. The next claim increments `attemptCount`. At the cap, or for an unleased
+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 application governance errors retain terminal failure behavior. Host store errors after
 a recorded provider effect follow the recovery rules below.
 
+Non-idempotent governance retry requires a durable `deferredBeforeEffectAttempt` equal to the
+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.
+
+PostgreSQL migration 9 (`pre_effect_governance_deferral`) adds the nullable marker column.
+Run `ensureSchema()` before deploying Hosts that may defer non-idempotent actions. Invocation
+updates without the marker omit the column and continue to work on schemas without migration 9.
+If a marker write fails, Host refuses retry with `pre-effect marker could not be recorded` when
+it can persist the terminal verdict; lease loss preserves its fencing error.
+
 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.
@@ -133,7 +146,7 @@ Lifecycle records use deterministic checkpoint ids. Recovered idempotent actions
 adapter that already reached `succeeded`. Built-in stores deduplicate event and policy inserts by
 checkpoint ID. Adapter rows are mutable; stale-worker protection requires the optional
 `writeAdapterInvocation` capability described below. A
-reclaimed non-idempotent action inspects its adapter checkpoints: running or succeeded rows route
+reclaimed non-idempotent action without compatible finalization preparation inspects its adapter checkpoints: running or succeeded rows route
 to reconciliation; no rows or only failed rows retain terminal failure for manual review.
 
 Returned `ambiguous` or `timeout` outcomes, timeouts thrown from `adapter.execute` (including an
@@ -201,8 +214,8 @@ On a store without atomic support, if the verdict cannot be written at all, no d
 call succeeds: neither verdict nor checkpoint is saved, as after a crash mid-call. A leftover `running`
 step can then re-run on recovery for an idempotent action under the same `adapterInvocationId`
 idempotency key, within the worker recovery budget. A reclaimed non-idempotent action with a
-running row without a matching durable handoff settles that step as unknown. A succeeded row or
-durable handoff instead ends `reconciliation_required` as an applied effect. Adapters should be
+running row without a matching durable handoff settles that step as unknown. Without compatible
+finalization preparation, a succeeded row or durable handoff instead ends `reconciliation_required` as an applied effect. Adapters should be
 idempotent or carry that stable key. The same exposure applies if two atomic attempts roll back
 and the fallback verdict cannot be written.
 
@@ -212,7 +225,7 @@ This includes later adapter checkpoints, obligation reads, and the completion wr
 `before_adapters` and `after_adapters`. Recovery also protects Host store operations before
 and around the handler when an earlier provider effect is recorded. Authorization, policy and handler callbacks
 retain their own failure semantics. Idempotent recovery repairs recorded success/handoff evidence
-without calling that step's provider. Non-idempotent interruption ends `reconciliation_required`
+without calling that step's provider. Without compatible finalization preparation, non-idempotent interruption ends `reconciliation_required`
 instead of repairing the invocation. Lease loss retains its fencing error.
 
 If neither record is durable, Host retries the failed handoff or marker write once. After a
@@ -229,10 +242,12 @@ Recovery may replay that unrecorded outcome for an idempotent action under its s
 `adapterInvocationId`, within the worker budget. A reclaimed non-idempotent action instead
 ends `reconciliation_required`. A durable handoff takes precedence over its running row and is
 recorded as an applied effect with its external reference. A running row without such a handoff
-is settled as unknown. A succeeded row also ends `reconciliation_required`. With no rows or only failed rows, the existing
+is settled as unknown. Without compatible finalization preparation, a succeeded row also ends `reconciliation_required`. With no rows or only failed rows, the existing
 non-idempotent interruption gates still fail the invocation.
 
-For idempotent recovery, the handler still runs before the adapter loop. The loop reads each
+For idempotent recovery without an action finalizer, the handler still runs before the adapter loop.
+Finalizing actions with compatible durable preparation replay without rerunning the handler;
+missing or incompatible preparation retains effect-aware refusal. See [action-level finalization](#action-level-finalization). The loop reads each
 checkpoint before `getInput()` or adapter lookup. Succeeded rows and durable handoffs use stored
 adapter type, operation, vendor, input and output; a falsy new input or removed adapter does not
 skip evidence repair. Stable event IDs deduplicate replayed accepted and success events; newly
@@ -245,7 +260,7 @@ Host calls `extractExecutionAttestation` with stored input/output and checkpoint
 it must return deterministic evidence for the same input. A handoff checkpoint with no output,
 or withheld output, skips extraction. Repair errors remain recoverable within the budget.
 
-Known limits: a later step's definite provider failure or pre-call refusal can still end the
+Known limits for actions without checkpointed finalization: a later step's definite provider failure or pre-call refusal can still end the
 invocation `failed` after an earlier step succeeded. Authorization denials, ordinary handler
 failures, validation/state-guard rejection, and unsatisfied policy obligations on recovery retain
 their existing terminal outcomes. These are decisions or application failures, not Host store
@@ -398,7 +413,6 @@ still treats a failure inside the handler callback as a handler outcome.
 failing, the row stays `running` although the provider was not called. For an action not declared
 idempotent, the next claim settles that step as an unknown provider outcome.
 
-
 A deadline sweep retains the handoff and sets `pendingCompletion.overdueAt` with its
 `reconciliation_required` verdict. A late callback settles that verdict only when the handoff also
 has `parkedAt`, proving Host reached parking after its remaining steps and finalization. An unparked
@@ -466,6 +480,22 @@ in the `before_adapters` phase stay appended. If the breaker opens between retry
 retrying and records the refusal. See the `@fabricorg/platform` README for thresholds and outcome
 mapping.
 
+## Adapter execution deadlines
+
+`PlatformHostOptions.adapterDeadlineMs` is a duration in milliseconds, starting
+after step input preparation, just before the step enters retry execution.
+An action's `AdapterStep.deadlineMs` overrides that duration for the step, including
+when the Host option is unset or zero. Step durations must be positive finite integers;
+action and module registration, manifest normalization and export reject invalid
+values. Host also validates resolved steps before handler or adapter execution.
+
+The budget spans retry attempts and delays; it is not renewed per attempt.
+Host supplies an epoch-millisecond `AdapterExecutionContext.deadlineMs` and an
+`AbortSignal`. Adapters must observe the signal to abandon an in-flight call.
+Expiry before an attempt prevents that attempt; an aborted call that throws follows
+the existing ambiguous-outcome reconciliation path. With no step duration and an
+unset or zero Host duration, neither context field is supplied.
+
 ## Execution authorization
 
 Submission authorization proves that a caller may create an invocation. Applications that delegate
@@ -562,7 +592,116 @@ evidence, so concurrent transitions serialize. Retrying the same identity and ev
 reusing it with contradictory evidence fails closed, and a distinct transition cannot rewrite a
 terminal parent. `createSagaParentActivities()` supplies deterministic identities for Temporal callers.
 
-Actions can optionally declare `resultSchema`. The Host validates public handler result data after
+### Action-level finalization
+
+Define provider-dependent domain work with `defineFinalizingAction({ ...action, finalize })`.
+This helper guards the handler against older hosts by requiring
+`ctx.finalizationProtocol === "atomic-after-adapters-v1"`, including when no handler was
+provided. An optional callback alone cannot make an older host refuse execution.
+
+Finalizing actions declare `eventPhase: "after_adapters"`, atomic kind, and immediate
+completion (or omit kind/completion). Non-idempotent actions are supported. Host refuses
+execution before handler or adapters unless the store provides atomic mutation transactions,
+invocation locking, and transaction-scoped lease fencing. There is no fallback.
+
+`finalize(ctx, { params, handlerData, adapterOutputs })` receives transaction-bound `ctx.db`
+and identity/provenance, without services. Each ordered step is either skipped or succeeded
+with its index, adapter type, operation, invocation ID, and stored redacted JSON output.
+Before adapters, Host strips `eventResultFields` from handler data and normalizes the hook's
+parameters and public handler data using `JSON.parse(JSON.stringify(value))`, then validates
+the normalized JSON. Dates become ISO strings, undefined object properties drop, and class
+instances use their JSON representation; non-finite numbers become null. Cycles, BigInt or
+other serialization failures fail the handler phase before adapter calls or adapter rows.
+Handler events are normalized in that phase too. The hook receives copies of the saved
+normalized inputs, so adapter input preparation cannot change them.
+Perform transaction-local domain writes here; provider calls belong in adapters. Earlier
+handler writes commit separately and are outside this atomic completion.
+
+Return only `{ events?, resultPatch? }` with JSON-compatible values. Explicit `undefined` on
+`events`, `resultPatch`, or an event's `eventSchemaVersion` is treated as omitted; undefined
+payloads or nested payload/result-patch values are rejected. Events require non-empty
+event/subject identifiers, a payload, and an optional positive integer schema version;
+event types must be declared in `emitsEvents`. Host checks event and subject names against
+`eventContracts` when supplied for hook-returned events only; handler events are outside
+that option's scope. It checks name membership, without validating payload schemas or schema
+version compatibility. Host owns envelope identity, scope, actor and timestamps.
+Hook and handler events default `eventSchemaVersion` to `action.version` when omitted;
+an explicit event schema version is preserved.
+Handler events use `domain:<index>`, hook events use `finalize:<index>`, followed by
+`state:transition`. The result patch merges shallowly over the public handler data; keys
+in `eventResultFields` are rejected. For these actions `resultSchema` validates the merged
+result inside the final transaction.
+
+The final transaction locks and checks the running invocation before calling the hook.
+Hook, validation, event-append or completion-write failure rolls back finalizer domain
+writes, events, outbox and completion, then settles `reconciliation_required` through
+applied-effect settlement when durable provider effects exist. With zero steps or all steps
+skipped, it settles `failed` without claiming a provider effect. Error text uses Host error
+redaction. Lease loss rolls back and
+escapes without a stale-worker verdict. Failed, ambiguous, degraded and accepted/handoff
+outcomes do not call the hook.
+
+If transaction entry or COMMIT fails with an unknown outcome, Host raises
+`RecoverableFinalizationError` and records no verdict. An uncommitted invocation stays
+`running` for recovery; if COMMIT succeeded despite the error, its stored `completed`
+verdict and result remain intact and are returned on re-execution.
+
+**Durable preparation and recovery.** The handler transaction commits a JSON
+`finalizationCheckpoint` with protocol `atomic-after-adapters-v1`, action version, ordered
+adapter type/operation identities, normalized parameters and public handler data, handler
+events, public result, optional pending transition event and skipped indexes. Adapter inputs
+are excluded. Parameters derive from the already-redacted durable invocation input.
+Finalizing `getInput` callbacks receive copies of normalized parameters and public handler
+data on both paths; other actions retain raw inputs. Skip decisions are computed before
+preparation commits. Replay does not call `getInput` for recorded skips or succeeded rows.
+For an unstarted step, it recomputes input from the saved normalized values; callbacks must
+be deterministic for those values.
+
+On resumed running invocations or later attempts, a compatible checkpoint bypasses the
+handler, including for non-idempotent actions. Succeeded rows supply their stored redacted
+outputs; steps without rows can run because Host creates a running row before calling the
+provider. Recovery retains entitlement, authorization and policy checks. A refusal after
+an applied effect requires reconciliation. Finalization uses the same locked, lease-fenced
+success transaction as live execution. A completed invocation returns its stored result.
+
+Running or ambiguous adapter rows require reconciliation, before checkpoint compatibility
+checks. Protocol, action version or step count/order/type/operation changes refuse replay;
+retain compatible definitions while work is recoverable. Handoffs cannot replay a finalizer.
+Refusals reconcile when an effect exists or may exist, and fail when no effect is recorded.
+Missing checkpoints retain the previous recovery rules, including reconciliation after
+succeeded adapter evidence. Recovery-attempt budgets and deadline/capability refusals remain
+in force. A checkpoint bypasses non-idempotent interruption gates only when each recorded
+adapter row is succeeded; missing rows may start, but failed rows retain interruption
+settlement without another provider call. Failed rows do not prove the provider had no effect.
+Settlement fails without recorded success and reconciles when another step succeeded.
+For leased non-idempotent replay, both the store and mutation transaction must provide
+`writeAdapterInvocation` for lease-fenced adapter creation and updates. Without either
+capability the existing interruption gates remain in force. Idempotent finalizing actions
+retain failed-row retry through the adapter loop under existing retry rules, using saved
+preparation rather than rerunning the handler.
+
+On the live path, a finalizing action whose earlier adapter succeeded and whose later adapter
+returns a permanent failure settles `reconciliation_required`, rather than `failed`. The hook
+does not run. This also applies to subsequent execution failures after a recorded provider
+effect, so the terminal status preserves the need to reconcile partial progress.
+
+Canonical checkpoint JSON is limited to **256 KiB in UTF-8**, a conservative fixed bound on
+durable evidence and transaction size. Oversize or unserializable preparation fails before
+adapters and rolls back handler writes. Store entry/commit errors with unknown outcomes raise
+`RecoverableFinalizationError` without a terminal verdict. Checkpoint write failures roll
+back preparation, so adapters do not run.
+
+**Rollout:** apply PostgreSQL migration **10**, `finalization_preparation_checkpoint`, using
+`ensureSchema()` before deploying Hosts that write checkpoints. It adds nullable
+`action_invocations.finalization_checkpoint jsonb`. Updates without the checkpoint field do
+not name the column and remain usable on older schemas. Custom stores must persist the field
+atomically with handler writes and honor explicit `undefined` clearing. Memory storage follows
+the same patch semantics. The saved transition event preserves the original emission decision;
+`pendingStateTransition` alone cannot encode suppression by a handler-emitted transition.
+
+### Result validation
+
+Actions without a finalizer can optionally declare `resultSchema`. The Host validates public handler result data after
 the handler and before canonical event append or adapter execution. Invalid results fail the invocation,
 emit no domain/completion event, invoke no adapter, and persist only a sanitized validation failure.
 Domain writes roll back only when the configured store transaction provider includes those writes.
@@ -778,6 +917,11 @@ Only JSON-data parameters can be admitted. Anything else is refused as `invalid_
 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 …").
 
+Entitlement and submission-authorization refusals throw `SubmissionRefusalError`. It remains an
+`Error` with the existing message and adds stable `code: "ACTION_SUBMISSION_REFUSED"`, `actionId`,
+and `refusal: "entitlement" | "authorization"` fields so internal dispatchers can distinguish a
+definitive refusal from a retryable failure.
+
 Only `{ admitted: true }`, read as an own data property, admits. Each of these makes
 `submitAction` throw `ActionAdmissionError` (`code: "ACTION_ADMISSION_REFUSED"`, `refusal`, and
 `refusalCode` for `refused`):
@@ -891,7 +1035,7 @@ must match the current state and invocation. Missing provenance leaves normal va
 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
+`StateTransitioned` after the handler's domain events and any action-finalizer 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
@@ -900,7 +1044,8 @@ 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
+accept a parked external handoff, after domain events and any action-finalizer events.
+Actions with `finalize` reconcile accepted handoffs without calling the hook. 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
@@ -1066,11 +1211,13 @@ cast in an index expression is not immutable and PostgreSQL refuses it.
 
 ## Tenant isolation
 
-`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` run eight checks against a host
+`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` run nine 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.
+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.
 
 Host passes `AdapterInvocationScope` from the store-loaded action invocation to
 `getAdapterInvocation(id, scope)` and `updateAdapterInvocation(id, patch, scope)`. Custom stores
@@ -1205,6 +1352,129 @@ CI certifies concurrent migrations, command idempotency, and schema behavior aga
 Lakebase failover, backup, and restore remain adopter certification gates and are not implied by the
 PostgreSQL CI result.
 
+## Staged descendant invocations
+
+An action declaring `stagesInvocations` may return up to 32 child requests from its handler or
+`after_adapters` finalizer. A request key is 1–128 characters and matches
+`[A-Za-z0-9][A-Za-z0-9._:-]*`. The Host accepts at most 64 KiB of canonical JSON per request and
+256 KiB for the canonical batch. Keys are unique within the combined handler/finalizer batch.
+Every action ID must be allowlisted and registered, and each parameter object must pass the current
+child schema before the parent transaction commits. `redactActionParameters` runs during staging;
+the redacted, schema-valid parameters are the only parameters written to the stage record and later
+used to create the child invocation.
+
+Staging requires `transactionWithEvents`, a transaction-scoped `stageInvocations`, and a store whose
+`transactionalStagedInvocations` flag is true. Host construction checks the advertised staged-store
+operations and atomic-store capability: scoped origin lookup, lease-fenced child creation, claim,
+renewal, lease-token rotation, settlement, cancellation, listing, and `transactionWithEvents`. The transaction object itself is available only when execution begins, so
+a missing transaction-scoped `stageInvocations` method is caught by the first staging action's
+execution preflight and interrupts that invocation. For `before_adapters`, the handler's batch
+commits with the handler mutation. For `after_adapters`, handler and finalizer requests commit with
+events and the completed parent verdict. A finalizing action retains its handler requests in the
+durable finalization checkpoint. Replaying an identical parent batch is a no-op; any changed key,
+action, version evidence, parameter digest, parameter value, batch size, or batch digest moves the
+parent to reconciliation without changing stored requests.
+
+A pending stage is claimable only while its immutable parent scope matches and the parent is
+`completed`. Parents ending `failed`, `blocked_by_policy`, or `validation_failed` have pending stages
+cancelled by the sweep. `reconciliation_required` and nonterminal parents leave stages pending and
+unclaimed. `host.dispatchStagedInvocations` uses renewable leases, a monotonic lease token,
+per-submission timeout, retry availability, a default ten-row claim batch, and a default ten-attempt
+dead-letter budget. The normal Platform worker runs this sweep by default only when its Host registry
+contains an action with a non-empty `stagesInvocations` allowlist. `dispatchStagedInvocations: true`
+forces a sweep and `dispatchStagedInvocations: false` disables it. A deployment that has no staging
+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, backed by a separate
+unique index. It carries no idempotency key, so a public caller cannot pre-claim its identity with a
+staged-looking string. A crash after parent commit is recovered by a later sweep. A crash after child
+creation but before the stage checkpoint resolves the same child by `stagedOrigin`. PostgreSQL
+migration 11 creates `staged_invocations`, adds the nullable origin columns and partial unique index,
+and adds the claim and parent indexes.
+
+Each claimed row goes through one settlement sequence (`dispatchStagedRow` in `src/host.ts`):
+
+1. Host renews the claim's lease, skipping the row if the lease is gone, and looks the child up by
+   `stagedOrigin` in the parent's tenant and space. Every claim replaces the lease token, so a
+   creation still in flight from an earlier attempt holds an older token and fails the creation
+   fence; this lookup therefore settles what earlier attempts did. A child found here goes to step 4
+   without the pre-submission checks or any entitlement, authorization, or admission call.
+2. With no child, Host checks that the parent is still `completed` and that the child action is
+   still registered, does not require capture-time authority, and accepts the stored parameters. It
+   then submits through the shared submission pipeline under the claim's lease token, bounded by
+   `submissionTimeoutMs`.
+3. If that submission's own fenced create returned the child, Host settles with its ID: `dispatched`
+   when the handoff succeeded or no dispatcher is configured, otherwise a retry that records the ID
+   (`dead_lettered` once the attempt budget is spent). In every other case (a failed pre-submission
+   check, a refusal, an error, or a timeout) Host first rotates the lease token with
+   `rotateStagedInvocationLease`. The only other possible creator is this attempt's own timed-out
+   submission, which still holds the old token, so after the rotation it can no longer create the
+   child and the lookup that follows is authoritative. A child found there goes to step 4. With none,
+   a definitive refusal settles `rejected`, and anything else settles for retry or, at the attempt
+   limit, `dead_lettered`.
+4. For a known child that is still `pending`, Host calls the configured dispatcher again with the
+   stable workflow ID `action-invocation-<id>`, bounded by `submissionTimeoutMs`. A confirmed
+   handoff, no dispatcher, or a child that has left `pending` settles `dispatched`; a failed or
+   unconfirmed handoff settles for retry or `dead_lettered`. Both record the child ID.
+
+Each settlement is one compare-and-set on the row's lease owner and current token, and a settlement
+that carries no child ID keeps one recorded earlier (both stores; shared contract test "keeps a
+recorded child id when a settlement carries none"). A settlement that finds the lease gone writes
+nothing, and the row's next claim starts again at step 1. A child lookup that fails settles the row
+for retry with the error `Staged child lookup failed.`, not as `rejected` or `dead_lettered`, even
+past the attempt limit. That attempt still counts, so the next attempt that can read the lookup and
+fails is dead-lettered if the budget is spent. A store
+error from renewal, rotation, or settlement ends only that row: the sweep counts it as failed,
+passes the error to `onError`, and continues with the next row. The Platform worker passes its own
+`onError`. Without a dispatcher, the submission that creates a child also executes it inline, as
+`submitAction` does; the stage settles `dispatched` once the child exists, even when that execution
+outlasts `submissionTimeoutMs`.
+
+Child creation is fenced in the store operation that inserts the invocation. The stage must still be
+`pending`, owned by the submitting worker at the matching lease token, and unexpired. PostgreSQL
+locks the qualifying stage row `FOR SHARE` in a CTE before `INSERT ... SELECT`. A token rotation of
+that row therefore waits for an in-flight insert to commit, and an insert under the old token that
+reaches the row while a rotation is uncommitted waits for it and then inserts nothing; the live
+PostgreSQL contract tests observe both orders. The memory store's fence, insert, rotation, and
+settlements run without an intervening await. An existing child is returned regardless of the fence,
+but a stale attempt with no child reports lease loss and writes nothing. While a submission or a
+handoff runs, a heartbeat renews the row's current lease token.
+
+Dispatch inherits the immutable parent's tenant, space, actor ID/type, and correlation ID; causation
+is the parent invocation ID. It does not copy the parent's authorization binding or approval decision.
+The child receives current entitlement, submission authorization, `admitSubmission`, runtime
+evidence, dispatcher, execution authorization, policy, and HITL handling as a fresh governed
+decision. Consequently, a natural-person parent produces a natural-person child and does not trigger
+agent HITL; an agent parent produces an agent child and follows the normal agent route. A definitive
+admission refusal, a submission authorization or entitlement refusal, or a failed pre-submission
+check settles `rejected` only after the token rotation and an authoritative lookup that finds no
+child. When that lookup finds one, as after a deploy that changes the schema of a child whose earlier
+handoff failed, the stage takes the existing-child path instead, so a `rejected` stage has no child.
+Admission failures/timeouts, store failures, and submission timeouts before child creation retry and
+eventually become `dead_lettered`. The default retry delay is a constant one second; callers provide
+`retryDelayMs(attemptCount)` when they need linear, exponential, jittered, or another backoff policy.
+A stage becomes `dispatched` only when the child exists and the current dispatcher handoff succeeds,
+no dispatcher is configured, or the child is no longer `pending`. A dispatcher failure after creation
+leaves the stage pending with the child ID and consumes the attempt. Exhausting the attempt budget
+moves it to `dead_lettered` while retaining that child ID: this terminal state means Host could not
+confirm dispatcher handoff, not that no child was created. A `dead_lettered` stage without a child ID
+was settled after an authoritative lookup found none. Later child policy blocks, approval waits,
+validation failures, or execution failures do not rewrite a dispatched stage. Stored stage errors
+are fixed messages and do not include request parameters or caught secret text:
+
+- `Staged invocation dispatch failed.`
+- `Staged invocation submission was definitively refused.`
+- `Staged child dispatcher handoff was not confirmed.`
+- `Staged child lookup failed.`
+
+`dispatchStagedInvocations` returns counters for the sweep. Each claimed row is counted once, as
+`dispatched`, `rejected`, or `failed`; `failed` also covers rows whose lease was lost before
+settlement and rows whose processing threw, and `deadLettered` is the part of `failed` settled as
+`dead_lettered`.
+
+This release does not provide operator requeue of dead-lettered stages, lifecycle events for stage
+transitions, a parent-result field listing children, or per-stage release options.
+
 ## Durable outbox egress
 
 Configure `outbox` on `createGovernedActionHost()` only with an `OutboxPlatformHostStore`.