@fabricorg/platform-host 8.2.0 → 8.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @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

package/README.md

@@ -917,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`):
@@ -1206,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
@@ -1345,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`.