@fabricorg/platform-host 8.5.0 → 8.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @fabricorg/platform-host
 
+## 8.7.0
+
+### Minor Changes
+
+- a28154f: Register Host-owned staged invocation principals, persist their names through recovery, and dispatch children through entitlement, admission, and authorization as the registered actor. PostgreSQL migration 14 adds nullable principal evidence columns and is required before deploying 8.7.0 anywhere staged invocations are used, including principal-less stages. Run `ensureSchema()`, deploy 8.7.0 or later to every process that runs the Host (executes staging parent actions, dispatches stages, or runs the Platform worker) without principal declarations, and only then ship modules that declare principals. An older worker can claim a principal-bearing stage and dispatch it as the parent's actor because it does not read or fence the new principal column.
+
+## 8.6.0
+
+### Minor Changes
+
+- 019ba30: Add the agent proposal submission envelope and Host HITL evaluator context with durable invocation identity. Snapshot proposals before awaiting authorization; validate strict approval evidence and support `redactAgentProposal` beside parameter redaction, after admission where declared. Persist and evaluate the redacted envelope, including on recovery and approval resume.
+
+  Idempotency compares redacted proposals and adds the `agent_proposal` conflict reason, including presence changes and legacy records. Consumers with exhaustive conflict-reason switches must handle the new value.
+
+  Run `ensureSchema()` to apply PostgreSQL migration 13 (`agent_proposal`) before submitting the first proposal. Inserts without proposals omit the new column. Staged and saga children do not inherit their parent's envelope.
+
 ## 8.5.0
 
 ### Minor Changes

package/README.md

@@ -1478,6 +1478,17 @@ child schema before the parent transaction commits. `redactActionParameters` run
 the redacted, schema-valid parameters are the only parameters written to the stage record and later
 used to create the child invocation.
 
+A parent action may select a Host-owned dispatch identity by declaring
+`stagedInvocationPrincipals`, which maps an allowlisted child action ID to a principal name. Host
+composition registers those names through `PlatformHostOptions.stagedInvocationPrincipals` with an
+`actorId` and Platform `ActorType`. A registry-backed Host refuses construction when a referenced
+name is absent; a resolve-only Host refuses the stage when it encounters an absent registration.
+The request allowlist remains exactly `key`, `actionId`, and `parameters`, so a handler or finalizer
+cannot supply `principal`, `actorId`, `actorType`, or an authorization binding. Host snapshots its
+registration at construction, records the principal name in the staged row, and resolves that
+durable name at dispatch. If a later Host no longer registers it, dispatch definitively rejects the
+stage instead of using the parent actor.
+
 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,
@@ -1487,8 +1498,9 @@ execution preflight and interrupts that invocation. For `before_adapters`, the h
 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.
+action, version evidence, parameter digest, parameter value, principal name, batch size, or batch
+digest moves the parent to reconciliation without changing stored requests. Principal-less batches
+retain their earlier canonical identity and digest.
 
 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
@@ -1500,29 +1512,56 @@ contains an action with a non-empty `stagesInvocations` allowlist. `dispatchStag
 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.
+The child has a Host-only `stagedOrigin` of parent invocation ID plus stage key and, when selected,
+the durable principal name. `authorizeExecution` can inspect `invocation.stagedOrigin.principal`
+alongside the child's durable parameters and actor. Public `SubmitActionInput` has no
+`stagedOrigin`; Host adds it through the internal staged-dispatch path.
+The lookup and unique index intentionally remain keyed by tenant, space, parent invocation ID, and
+stage key: one parent stage key identifies one child, while the principal is evidence for that
+durable intent rather than a second child identity. The child 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 stage settlement resolves the
+same child, including its principal evidence, by `stagedOrigin`. PostgreSQL migration 11 creates the
+staged tables and origin index; migration 14 adds nullable `principal` and
+`staged_origin_principal` columns for the staged record and child invocation.
+
+Migration 14 is a deployment prerequisite for this Host version wherever staged invocations are
+used, including stages that do not select a principal: the staging and fenced child-insert SQL name
+the new nullable columns in both cases. Use this rollout order for a shared PostgreSQL database:
+
+1. Run `ensureSchema()` and confirm migration 14 (`staged_invocation_principals`) is recorded.
+2. Deploy `@fabricorg/platform-host` 8.7.0 or later to every process that runs this Host: processes
+   that execute staging parent actions (including inline execution inside `submitAction`), run
+   `dispatchStagedInvocations`, or run the Platform worker. Keep module principal declarations
+   disabled during this step. An older Host that executes a parent ignores the declaration and
+   stages the child without a principal, so every later dispatch uses the parent's actor.
+3. After those processes are upgraded, ship modules that declare `stagedInvocationPrincipals`.
+
+An older worker can claim a principal-bearing row because its claim query does not filter on the
+new column. It then reads no principal evidence and can submit the child as the parent's actor; its
+older fenced insert also does not compare the principal. Depending on which version handles the stage, it can be
+rejected after its intent is lost or the child can complete under the wrong actor. Running migration
+14 before step 2 also matters for principal-less stages because this Host version names the columns
+when staging and dispatching them.
 
 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
+   `stagedOrigin` in the parent's tenant and space. Each 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`.
+   resolves any recorded principal against the current Host registration, then submits through the
+   shared submission pipeline under the claim's lease token, bounded by `submissionTimeoutMs`.
+   Entitlement, submission authorization, admission, and execution authorization all evaluate the
+   registered principal just as they do for any other submission.
 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
+   `rotateStagedInvocationLease`. The remaining 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
@@ -1712,3 +1751,40 @@ This capability lives on `OutboxRequeuePlatformHostStore`, which extends `Outbox
 `MemoryPlatformHostStore` and `PostgresPlatformHostStore` implement it, and a custom outbox store
 without it makes the operation throw. PostgreSQL adds migration 5, the
 `fabric_platform.event_outbox_requeues` table, which `ensureSchema()` creates.
+
+### Agent proposals and Host evaluator context
+
+Agent callers can submit `SubmitActionInput.agentProposal` separately from action parameters:
+`{ confidence, riskTier, agentSessionId, agentRunId, reason, evidence }`. Confidence must be
+finite; risk tier is `low`, `medium`, or `high`. Session/run IDs must contain non-whitespace
+text and fit within 256 UTF-16 code units; reason may be empty and is limited to 4096 code
+units. Evidence uses the approval-decision strict JSON object validation and
+`MAX_APPROVAL_EVIDENCE_BYTES` (16 KiB). Invalid proposals and proposals from other actor
+types reject submission before invocation creation through the existing Error rejection path.
+
+For the submission snapshot, Host reads `agentProposal` once and deeply copies it before
+its first await, including for actions without `admitSubmission`. The sibling
+`redactAgentProposal(actionId, proposal)` hook runs beside `redactActionParameters`: after
+admission for actions declaring `admitSubmission`, otherwise before composition resolution.
+Its result is validated and copied again. A thrown hook or invalid output rejects submission
+without creating an invocation, like a thrown parameter-redaction hook. Applications should
+remove secrets and unnecessary sensitive evidence through this hook before durable storage.
+
+The redacted proposal is stored on `ActionInvocationRecord` and compared canonically on
+idempotent re-submission. Differences, including absence versus presence, add the
+`agent_proposal` conflict reason under the configured `enforce` or `audit-only` mode,
+including legacy records without parameter digests. Exhaustive conflict-reason switches
+must handle this new value.
+
+`hitlEvaluator` receives `HostHitlEvaluatorContext`, extending the portable context with
+`actionInvocationId` and the durable `invocation` read before evaluation. Proposal fields
+supply confidence, risk tier, session ID, and run ID individually, falling back to parameters
+for absent fields. Reason and evidence are available through `invocation.agentProposal`.
+Approval authorization and resumed execution authorization receive that durable proposal too.
+Staged and saga children do not inherit a parent's proposal. Approval lifecycle event payloads
+and Host telemetry do not include the envelope.
+
+Apply PostgreSQL migration 13 (`agent_proposal`) with `ensureSchema()` before the first
+proposal submission. Inserts without proposals omit the new column, following the
+`admitted_at` rollout pattern. Existing migration SQL is unchanged; readers accept legacy
+rows without a proposal. See `src/postgres-store.ts` (`ensureSchema`, `toActionRecord`).