@fabricorg/platform-host 7.2.2 → 7.3.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @fabricorg/platform-host
 
+## 7.3.0
+
+### Minor Changes
+
+- adf8ff1: Operators can now requeue a dead-lettered outbox record without hand-written SQL. Before this, a record that exhausted the relay's `maxAttempts` stayed in `dead_letter`, and the only way back was an `UPDATE` that reset its attempt count, recorded no actor or reason, and could race another operator. ADR 0018 makes a governed requeue a prerequisite for adopting webhook delivery, because webhook fan-out depends on the relay and can exhaust it during a long receiver outage.
+
+  - `host.requeueOutboxDeadLetter({ outboxId, tenantId, spaceId, actorId, actorType, reason, availableAt? })` reads the record within the tenant and space and calls the new `PlatformHostAuthorization.authorizeOutboxRequeue` with the record's event type, classification, status and attempt count. The hook is called on the authorization object, so a class-based authorizer keeps `this`. The host then calls the store's compare-and-set with the lease token it read. It returns `{ status: "requeued", record, requeue }` or `{ status: "refused", refusal, currentStatus?, message }`, where `refusal` is `not_authorized`, `not_found`, `not_dead_letter` or `stale`.
+  - An authorization applies only to the dead letter it was made for. Every relay claim increments the record's lease token and a requeue never lowers it. A record that was requeued by someone else, retried and dead-lettered again while the authorizer ran therefore carries a different token, and the requeue is refused as `stale` instead of resetting the new dead letter's budget.
+  - Recovery semantics: a requeued record is `pending` with `attemptCount` 0, `availableAt` set to the host clock or the caller's later time, and no lease owner. Its lease token is kept, so a relay holding an older lease cannot checkpoint it. It keeps `lastError`. The relay republishes it under the same `eventId`, so delivery stays at least once and consumers keep deduplicating on that ID. The attempt budget starts over, so a record can be requeued and exhausted again.
+  - Audit evidence: the store writes the transition and one `OutboxRequeueRecord` in the same atomic step. The record holds the actor, reason, time, new availability, and the attempt count, last error, availability and lease token it replaced. Neither store has a method that updates or deletes evidence rows. `listOutboxRequeues({ tenantId, spaceId, outboxId? })` reads them. The memory store keeps the evidence in a non-public field and returns copies with their own Date objects, so editing returned evidence does not change stored history. This is not an action invocation: it writes no action invocation record and no policy decision record.
+  - Fail-closed behaviour: without `authorizeOutboxRequeue`, every requeue is refused as `not_authorized`. An authorizer that throws stops the requeue before anything is written, and any answer other than `true` is a deny. A refused actor gets `not_authorized` whether or not the record exists. A record under another tenant or space is `not_found`. A pending or published record is `not_dead_letter`. Of two concurrent requeues, one wins and the other gets `not_dead_letter`. A blank actor, scope or reason, a reason over 1,000 characters, or an invalid `availableAt` throws before the store is read.
+  - Store capability: the methods live on the new `OutboxRequeuePlatformHostStore` (`getOutboxRecord`, `requeueOutboxDeadLetter`, `listOutboxRequeues`), which extends `OutboxPlatformHostStore`. A custom outbox store written before this still satisfies `OutboxPlatformHostStore`; the host operation throws when the store lacks the new methods. `MemoryPlatformHostStore` and `PostgresPlatformHostStore` implement it, and one contract suite runs over both.
+  - PostgreSQL: migration 5 (`outbox_requeue`) creates `fabric_platform.event_outbox_requeues` with an index on tenant, space, record and time. It leaves `event_outbox` unchanged. The requeue is one statement that locks the row, rechecks `status='dead_letter'` and the expected lease token under the lock, updates the row and inserts the evidence. It was verified against PostgreSQL 17 locally, including a test where another transaction holds the row lock.
+  - Telemetry: `outbox.requeued` (`fabric.platform.outbox.requeued`) and `outbox.requeue_refused` (`fabric.platform.outbox.requeue_refused`) are added to `PLATFORM_HOST_METRIC_NAMES` and the telemetry event names.
+  - Compatibility: `GovernedActionHost` is unchanged, so an existing hand-written implementation still type-checks. The operation is on the new `OutboxRequeueHost` interface, and `createGovernedActionHost()` now declares the return type `GovernedActionHost & OutboxRequeueHost`. `PlatformHostAuthorization` gains only the optional `authorizeOutboxRequeue`. `cloneOutboxRecord` now copies the record's Date fields instead of sharing them, so memory-store outbox reads no longer hand out the stored Dates. The event payload and provenance remain shared references to the stored objects, as before.
+
+- 8c7d2a1: Make policy resolution invocation-aware and record which policy snapshot was used.
+
+  - `@fabricorg/platform-host`: `resolvePolicies` now receives the new exported `ResolvePoliciesInput`, which extends `ActionExecutionAuthorizationInput` with `declaredPolicyIds`. It adds `actionInvocationId`, `invocation`, `executionReason`, and `parameters`. The `parameters` are the schema-parsed durable (post-redaction) parameters, the same value passed to `authorizeExecution`, not the caller's original input. Two invocations by the same actor for the same action can now be told apart. Existing resolvers keep working because the input only gained fields.
+  - `@fabricorg/platform`: new `PolicyAuthorityReference` (`snapshotId`, optional `contentHash`), an opaque consumer-defined reference that Platform does not interpret. It is an optional `authority` on `RuntimePolicyDefinition` and on `PolicyDispatchEvidence`. `evaluatePolicyDefinition` copies a definition's `authority` into the outcome's `dispatchEvidence` for code, data, and hybrid policies, including missing-evaluator blocks. Hosts persist it with the policy evaluation. Definitions without `authority` produce unchanged evidence.
+  - Host keeps the first persisted policy evaluation per invocation and policy, so a resolver must return the same snapshot for an `actionInvocationId` on every attempt (`initial`, `recovery`, `approval_resume`).
+
+- 81bba1a: Outbox envelopes can now carry actor identity. It is opt-in, and the default is unchanged.
+
+  - **Default unchanged.** Without the new hook, `EnterpriseEventEnvelope` has no `actorId` or `actorType` keys, for every payload classification including `public` and `internal`. Existing bus publishers receive the same envelope as before. This differs from `includeProvenance`, whose default includes provenance for non-restricted events.
+  - **Opting in.** Add `outbox.includeActor(event, classification)` to `createGovernedActionHost()`. Only a return value of exactly `true` adds the canonical event's `actorId` and `actorType` to the envelope. A direct `appendEventWithOutbox(event, metadata)` caller opts in with `metadata.includeActor: true`. `toEnterpriseEventEnvelope()` follows the same rule.
+  - **Disclosure.** An included actor reaches every sink of every relay reading that outbox: buses, webhook fan-out, and anything else wired to `runOutboxRelayCycle()`. Opt in only when every one of those sinks may hold actor identifiers, or wrap the publisher so it strips `actorId`/`actorType` before handing the envelope to sinks that must not see them. Restricted events stay actorless unless your hook returns `true` for them.
+  - **Suppressed vs legacy.** Each outbox record now stores the decision as `OutboxRecord.actorDisclosure`: `"included"` or `"suppressed"`. `runOutboxRelayCycle()` passes it to the publisher as `context.actorDisclosure` (new exported `EnterpriseEventPublishContext`). A record written before this release has no stored decision, and the relay reports it as `"legacy"`. `suppressed` means the application chose not to share the actor. `legacy` means the record predates the decision. The memory and PostgreSQL stores read the actor back only from `included` records, so neither envelope carries an actor, and replaying the outbox does not add one to a legacy record. A consumer that needs the actor for a legacy record must read it from the canonical event.
+  - **PostgreSQL schema.** `ensureSchema()` applies migration 4 (`outbox_actor_disclosure`). It adds a nullable `event_outbox.actor_disclosure` column with no default, so rows written before the migration stay `NULL` and read as legacy. It also adds a `NOT VALID` check constraint, so existing rows are not scanned. The check accepts `NULL`: every non-`NULL` value written from now on must be `included` or `suppressed`. Writers on an older Host version keep inserting `NULL`, which reads as legacy. Outbox hydration reads `actorId`/`actorType` only from rows whose column is `included`.
+  - **Rollout order.** (1) Run `ensureSchema()` so migration 4 is applied; writers on this version insert into the new column and fail without it. (2) Upgrade every relay that reads the shared outbox. (3) Only then enable `includeActor`. A relay on an older Host version hydrates outbox rows without the actor fields and publishes with no `actorDisclosure` in the context, then acknowledges the record. A consumer behind that relay receives an actorless envelope that it reads as legacy, although the row says `included`. Because the record is then marked published, the actor is not delivered again for that event.
+  - **Custom outbox stores.** A third-party `OutboxPlatformHostStore` should persist `outboxActorDisclosure(metadata)` (newly exported) as the record's `actorDisclosure`. Until it does, the relay reports its records as `legacy`.
+  - `publish(event, context?)` keeps its signature. The context type gained the optional `actorDisclosure`, so existing publishers and callers compile unchanged.
+
+- 8e631b0: Actions can now refuse a submission before Host records anything for it. Before this, `submitAction` persisted an invocation's parameters before anything validated them: the action's schema ran only at execution. An action whose parameters must be checked against trusted context, such as a secret reference the tenant's secret store must hold, could refuse at execution, but the refused value was already in the invocation record. `redactActionParameters` could strip values, but it is synchronous, gets no tenant or actor, and is an option the application has to remember to wire.
+
+  - **`@fabricorg/platform`: `ActionDefinition.admitSubmission`** (optional). It is an async check that receives `ActionAdmissionInput`: `actionId`, `tenantId`, `spaceId`, `actorId`, `actorType`, the submitted `parameters` and a `signal` typed as the new structural `ActionAdmissionSignal` (so the `actions` entry still compiles without DOM or Node type libraries; Host passes a real `AbortSignal`). It answers `ActionAdmissionDecision`, which is `{ admitted: true }` or `{ admitted: false, code }`. The code must be fixed text chosen by the action, never a submitted value. `ActionContext.admittedAt` (optional) is how a handler learns that the host admitted its invocation. Module and action registration now reject an `admitSubmission` that is not a function. A host that does not know the field ignores it, so a handler that depends on admission should refuse without `ctx.admittedAt`.
+  - **`@fabricorg/platform-host`: ordering.** `submitAction` runs the check on every submission of an action that declares it: inline, dispatched, offline replays, and re-submissions under an existing idempotency key. It runs after entitlement and `authorize`, so an unauthorized submitter never reaches it. It is the last await before `createActionInvocation`: for such an action, provenance normalization, `composition.resolveInitiatingReleaseDigest` and runtime evidence run before it, and redaction, the parameter digest and the authorization-binding check after it. Actions without the check keep the previous order (redaction, digest and binding check before provenance normalization and the composition callback). The check gets the submission's trusted scope and actor, never scope taken from the parameters, and a copy of the parameters made for it alone. For an action with the check, Host persists its own copy, taken when `submitAction` was called, so neither the caller nor the check holds a reference to what is stored (tests "the persisted parameters are the copy that was checked …" and "a parameter getter is read exactly once …" in `tests/submission-admission.test.ts`).
+  - **`@fabricorg/platform-host`: one snapshot of the submission's identity.** `submitAction` now reads the scalar fields of the caller's `SubmitActionInput` (`actionId`, `tenantId`, `spaceId`, `actorId`, `actorType`, `correlationId`, `causationId`, `executionReason`, `idempotencyKey`, `authorizationBindingId`) once, before its first await, and every later step uses those values (`snapshotSubmission`, `src/submission-snapshot.ts`). Before this, Host reread the caller's object after awaiting `checkEntitlement`, `authorize` and the composition callback, so a caller that changed `tenantId`, `actorId` or `actionId` during those awaits could get an invocation persisted and executed under values that were never authorized. This affects every action (tests "changing the caller's input while admission awaits …", "… while authorize awaits …" and "the identity snapshot still applies …"). A scalar field that holds an object, a function or a symbol, a read of one that throws, or an input that is not an object makes `submitAction` throw an `Error` with a fixed message and record nothing; in each case the field does not yield a value of its declared type.
+  - **Parameters, provenance and binding.** For an action that declares `admitSubmission`, Host reads each of the three once, before its first await, and keeps its own copies. Parameters are copied as JSON data: `null`, strings, booleans, finite numbers, dense arrays, and objects whose prototype is `Object.prototype` or `null`; each own enumerable string-keyed property is read once, `undefined` values are left out, and symbol keys and non-enumerable properties are skipped. Anything else is refused as `invalid_parameters` before the check runs: a Proxy, a function, a symbol, a bigint, `NaN` or `Infinity`, a Date, a Map, a class instance, an ArrayBuffer, a SharedArrayBuffer, a typed array or DataView (so no caller-held view can write to a checked value), an array hole or `undefined` element, a cycle, or a getter that throws. Provenance and binding are copied field by field, each declared field read once from an own or inherited property, so class instances are accepted and undeclared fields are not kept. For every other action nothing about these three fields changes: Host reads them from the caller's input at the same points and as often as before, and `redactActionParameters`, the digest, the store, the handler and `provenance.onTrace` get what they got before (tests under "an action without admitSubmission: everything but the identity snapshot is as before"). The composition callback, `composition.resolveInitiatingReleaseDigest`, now gets a view of the submission instead of the caller's object, for every action: its scalar fields are the snapshot's, so the release evidence it resolves is for the tenant, actor and action Host persists (before, a caller that changed `tenantId` while `authorize` awaited could have the callback resolve another tenant's release digest, which Host then persisted under the original tenant). For an action without the check, the view's `parameters`, `provenance` and `authorizationBinding` read and assign the caller's input, so the callback reaches the same objects as before; other properties of the caller's object are not on the view (test "scope, actor and action changed while authorize awaits do not reach the composition callback …").
+  - **Fail-closed behaviour.** Only `{ admitted: true }` admits, read as an own data property. `submitAction` throws the new `ActionAdmissionError` (`code: "ACTION_ADMISSION_REFUSED"`, `actionId`, `refusal`, and `refusalCode` for a refusal) in each of these cases: a refusal whose code matches `^[a-z][A-Za-z0-9_.:-]{0,127}$` (`refused`); a throw or a non-function check (`failed`); an answer that does not settle within the new `admissionTimeoutMs` option, default 10 000 (`timed_out`); any other answer (`invalid_decision`); and parameters that are not JSON data (`invalid_parameters`). The deadline is judged when the answer settles, on the monotonic clock (`performance.now()`), not by a race with a timer. An answer or throw that settles `admissionTimeoutMs` or more after the call is `timed_out` even when its handler runs before the timer, as when the check blocked the event loop past the deadline (test "an answer that settles after admissionTimeoutMs is refused even when the check blocked the event loop …"). The timer only ends the wait on a promise that never settles. Every `timed_out` refusal aborts the check's signal before `submitAction` throws. Host writes nothing for a refused submission: no invocation, no idempotency key (the key stays free), no event, no policy record and no error. The error message names the action, the refusal and the check's code only. It never contains a submitted value or anything the check threw. `admissionTimeoutMs` must be a whole number from 1 to 2 147 483 647, the largest delay `setTimeout` honours. Otherwise `createGovernedActionHost` throws: NaN, Infinity, 0, negatives, fractions and 2^31 are refused.
+  - **Durable evidence and execution.** An admitted invocation records `ActionInvocationRecord.admittedAt`, which is set on creation and never patched. Host passes it to the handler as `ActionContext.admittedAt`. Host refuses to execute an invocation of an action that declares `admitSubmission` when its record has no `admittedAt`, whether inline, from the worker or after an approval. The invocation fails with a fixed message and the handler does not run. Such a record comes from an older Host, a direct store write, or a custom store that does not persist `admittedAt`. Custom `PlatformHostStore` implementations should store and return `admittedAt`. Until they do, actions that declare `admitSubmission` fail at execution, and nothing else changes.
+  - **PostgreSQL.** `ensureSchema()` applies migration 6 (`invocation_admission`), which adds the nullable `action_invocations.admitted_at timestamptz` column with no default. Existing rows and rows of actions without the check stay `NULL`.
+  - **Rollout order.** The PostgreSQL store names `admitted_at` only when it inserts an admitted invocation, and every invocation read selects `*` and treats a missing column as no `admittedAt`. So actions without `admitSubmission` are submitted, read back and executed on a schema without migration 6, as before (live test "without migration 6, an action without admitSubmission is submitted …"). Before submitting an action that declares `admitSubmission`: (1) run `ensureSchema()`; without migration 6 such a submission fails with an error naming the migration and writes nothing. (2) Upgrade every Host process, workers included. An older worker executes such an invocation without checking `admittedAt`, and an older submitter persists its parameters unchecked. A handler that requires `ctx.admittedAt` still refuses to act under an older Host.
+  - **Telemetry.** `invocation.admission_refused` (`fabric.platform.invocation.admission_refused`) is emitted with the `refusal` attribute. A refused submission emits no `invocation.submitted`.
+  - **Compatibility.** Every addition is optional. Actions without `admitSubmission` run no check, record no `admittedAt`, get no new parameter refusal and see their parameters, provenance and binding handled as before; the one change for them is that the scalar fields are read once at submission, so a change the caller makes to one of them while `submitAction` awaits is no longer read, and a scalar field that does not yield a value of its declared type is refused with the fixed message above. Rejecting non-JSON parameters for every action would have refused Dates, Maps and class instances that existing callers may pass, a breaking change this minor does not make. On PostgreSQL, only the insert of an admitted invocation names the new `admitted_at` column, so migration 6 is needed only before the first action that declares `admitSubmission` is submitted, as the rollout order above says. `redactActionParameters` stays defense in depth. For an action with the check, it runs on Host's copy after admission.
+
+## 7.2.3
+
+### Patch Changes
+
+- fd1f88f: Publish the current packaged documentation, product names and resolved workspace dependency minimums under new patch versions. The release audit found retained package versions whose consumer-visible metadata differs from their registry tarballs. Runtime source is unchanged apart from regenerated generator version stamps.
+
+  The release guard now retains nested manifest fields while canonicalizing key order, so dependency, peer and export changes cannot disappear from the comparison. Development-only dependencies remain excluded.
+
 ## 7.2.2
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ pnpm add @fabricorg/platform@^1.2.0 @fabricorg/platform-host@^6.0.0 @fabricorg/a
 
 ## AI agent integration boundary
 
-Application and vertical owners install this package. Hermes, Fabric Harness, and other external agent
+Application and vertical owners install this package. Hermes, TechFabric Harness, and other external agent
 runtimes do not import Platform Host merely to call a deployed application. They connect to the
 application's authenticated REST or MCP gateway, discover only the actions allowed by their
 registration, and submit stable idempotent commands. The gateway derives tenant and actor identity and
@@ -16,7 +16,7 @@ calls `submitAction()`; an agent must never call handlers, adapters, workflow in
 writes directly.
 
 See the [Platform Host 6.x agent integration
-guide](https://platform.fabric.pro/docs/platform/reference/platform-host) for application wiring,
+guide](https://platform.techfabric.com/docs/platform/reference/platform-host) for application wiring,
 execution-time authorization, the PostgreSQL transaction binder, recovery semantics, and the external
 gateway contract.
 
@@ -73,6 +73,17 @@ schema-parsed durable parameters, canonical invocation, opaque `authorizationBin
 `executionReason` of `initial`, `approval_resume`, or `recovery` immediately before policies and
 mutation code run.
 
+`resolvePolicies` receives the same trusted execution input (`ResolvePoliciesInput`): `actionInvocationId`,
+the canonical `invocation`, `executionReason`, and the schema-parsed durable `parameters` (after
+`redactActionParameters`, not the caller's original values), plus `declaredPolicyIds`. Two invocations
+by the same actor for the same action are therefore distinguishable, so a resolver can return the
+policy snapshot pinned to that invocation. A returned `RuntimePolicyDefinition` may set
+`authority: { snapshotId, contentHash? }`; Platform copies it into the persisted policy outcome's
+`dispatchEvidence.authority` without interpreting it. Host keeps the first persisted evaluation per
+invocation and policy, so a resolver must return the same snapshot for an `actionInvocationId` on
+every attempt, including `recovery` and `approval_resume`. Consumers on an older `@fabricorg/platform`
+that lacks `PolicyAuthorityReference` should upgrade before setting `authority`.
+
 `offline_replay` is the extensible evidence value for disconnected commands. Actions with execution
 semantics can declare whether capture, execution, or both govern authority. A denied governed replay
 returns structured `reconciliation_required` evidence.
@@ -85,7 +96,9 @@ checks it against current resource state.
 `InvocationProvenance` carries namespaced trace and audit attributes. Durable audit attributes fail
 closed when no allowlist is configured, pass through `redactAuditAttributes`, and remain bounded.
 Trace attributes go only to the configured trace callback. Restricted outbox payloads omit provenance
-by default; `outbox.includeProvenance` is the explicit classification-aware override.
+by default; `outbox.includeProvenance` is the explicit classification-aware override. Outbox envelopes
+leave out the actor for every classification unless `outbox.includeActor` opts in (see
+[Durable outbox egress](#durable-outbox-egress)).
 
 ```ts
 const host = createGovernedActionHost({
@@ -194,6 +207,122 @@ 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.
 
+## Submission snapshot
+
+`submitAction` reads the scalar fields of the caller's `SubmitActionInput` once, before its first
+await (`snapshotSubmission`, `src/submission-snapshot.ts`, called first in `submitAction`,
+`src/host.ts`): `actionId`, `tenantId`, `spaceId`, `actorId`, `actorType`, `correlationId`,
+`causationId`, `executionReason`, `idempotencyKey` and `authorizationBindingId`. Every later step
+uses those values, and every hook, callback, store and dispatcher call Host makes for the submission
+is given those values: entitlement, `authorize`, the composition callback, the admission check,
+redaction, the binding check, telemetry, `createActionInvocation`, the idempotency comparison and
+dispatch (test "scope, actor and action changed while authorize awaits do not reach the
+composition callback …"). So a caller that changes one of them on its object while entitlement,
+`authorize`, the composition callback or an admission check awaits does not change the action,
+scope, actor, ids or keys Host authorizes, persists or executes. This holds for every action (tests
+"changing the caller's input while admission awaits …", "… while authorize awaits …" and "the
+identity snapshot still applies …" in `tests/submission-admission.test.ts`). A scalar field that
+holds an object, a function or a symbol, a read that throws, or an input that is not an object makes
+`submitAction` throw an `Error` with a fixed message and record nothing. In each case the field read
+does not yield a value of its declared type.
+
+What Host does with `parameters`, `provenance` and `authorizationBinding` depends on the action:
+
+- **An action that declares `admitSubmission`** gets Host's own copies of all three, also taken
+  before the first await (`privateSubmission`). Each field is read once. The parameters are copied
+  as JSON data: `null`, strings, booleans, finite numbers, dense arrays, and objects whose prototype
+  is `Object.prototype` or `null`. Each own enumerable string-keyed property is read once, so a
+  getter runs once. A property whose value is `undefined` is left out, and symbol keys and
+  non-enumerable properties are skipped. Parameters that are not JSON data are refused as
+  `invalid_parameters` (next section): a Proxy, a function, a symbol, a bigint, `NaN` or `Infinity`,
+  a Date, a Map, a class instance, an ArrayBuffer, a SharedArrayBuffer, a typed array or DataView, an
+  array hole or `undefined` element, a cycle, or a getter that throws. `provenance` and
+  `authorizationBinding` are copied field by field: each declared field is read once, from an own or
+  inherited property, so a class instance is accepted, and undeclared fields are not copied. Neither
+  the caller, the admission check nor the composition callback holds a reference to the parameters,
+  provenance or binding Host persists for such an action; `redactActionParameters` gets Host's copy
+  (tests "the persisted parameters are the copy that was checked …", "a parameter getter is read
+  exactly once …" and "class-instance provenance and binding are read field by field once …").
+- **Any other action** is handled as it was before the snapshot existed. Host does not copy these
+  three fields. It reads them from the caller's input at the same points, and as often, as it did
+  before. `redactActionParameters`, the parameter digest, the store and the handler get the caller's
+  parameters object, and `provenance.onTrace` gets what it got before. Redaction, the digest and the
+  binding check still run before provenance normalization and the composition callback. The
+  callback receives a view of the submission rather than the caller's object: its scalar fields
+  are the snapshot's, and its `parameters`, `provenance` and `authorizationBinding` read and assign
+  the caller's input (`liveSubmissionView`), so it reaches the same objects with the same reads as
+  before. So for these actions a change the caller makes to its parameters,
+  provenance or binding while Host awaits is seen exactly as before; only the scalar fields above are
+  fixed at submission (the tests under "an action without admitSubmission: everything but the
+  identity snapshot is as before" and "parameters, provenance and binding are read where they were
+  read before …").
+
+## Submission admission
+
+An action can declare `admitSubmission` (Platform 1.7.0) when its parameters must be checked against
+trusted context before they may be persisted at all, for example a secret reference the tenant's
+secret store must hold. `submitAction` runs the check on every submission of that action, including
+an offline replay and a re-submission under an existing idempotency key:
+
+1. after entitlement and `authorize`, so an unauthorized submitter never reaches it;
+2. with the snapshot's `tenantId`, `spaceId`, `actorId` and `actorType`, never scope taken from
+   the parameters, a copy of the snapshot's parameters made for the check alone, and an
+   `AbortSignal`;
+3. as the last await before `createActionInvocation`. Redaction, the parameter digest, the
+   authorization-binding check and the idempotency lookup all come after it. They run on the
+   snapshot's own copy, which is what Host persists. The check never holds a reference to that
+   copy, and neither does the caller. So the value persisted is the value checked, unless
+   `redactActionParameters` changes it (test "the persisted parameters are the copy that was
+   checked …").
+
+Only JSON-data parameters can be admitted. Anything else is refused as `invalid_parameters`
+directly after `authorize`, before the composition callback and the check run. A SharedArrayBuffer or a view over one is refused this way,
+since the caller could still write to its memory (test "a parameter backed by a SharedArrayBuffer …").
+
+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`):
+
+- `{ admitted: false, code }` with a code matching `^[a-z][A-Za-z0-9_.:-]{0,127}$` (`refused`);
+- a throw, or a check that is not a function (`failed`);
+- an answer that did not settle within `admissionTimeoutMs` (`timed_out`);
+- any other answer (`invalid_decision`);
+- parameters that are not JSON data (`invalid_parameters`).
+
+Host writes nothing for a refused submission: no invocation, idempotency key, event, policy record
+or error, so the key stays free. The message names the action, the refusal and the check's code
+only. Host emits `invocation.admission_refused` telemetry with the refusal.
+
+The deadline is judged when the check's answer settles, not by which of the answer and a timer
+wins a race. Host reads the monotonic clock (`performance.now()`) when the check is called and
+again in the handler attached to the check's promise. An answer, or a throw, that settles
+`admissionTimeoutMs` or more after the call is `timed_out`. That holds when the check blocked the
+event loop past the deadline and its answer ran before the timer could (test "an answer that settles
+after admissionTimeoutMs is refused even when the check blocked the event loop …"). The timer only
+ends the wait on a promise that never settles. Every `timed_out` refusal aborts the check's signal
+before `submitAction` throws. `admissionTimeoutMs` defaults to 10 000. It must be a whole number from
+1 to 2 147 483 647, the largest delay `setTimeout` honours. Otherwise `createGovernedActionHost`
+throws.
+
+Host stores when it admitted the submission as `admittedAt` on the invocation (PostgreSQL migration
+6, `admitted_at`) and passes it to the handler as `ActionContext.admittedAt`. It refuses to execute
+an invocation of an action that declares `admitSubmission` when the record has no `admittedAt`,
+whether executed inline, by the worker or after an approval. Such a record comes from a Host older
+than 7.3.0, a direct store write, or a custom store that does not persist `admittedAt`. A handler
+that depends on admission can also require `ctx.admittedAt`, so it refuses under an older Host,
+which ignores `admitSubmission`. Actions that declare no check run no check and record no
+`admittedAt`. Their only change is the scalar snapshot above.
+
+Rollout: the PostgreSQL store names `admitted_at` only in the insert of an admitted invocation.
+An invocation of an action without `admitSubmission` is written with the same columns as before,
+and every invocation read selects `*` and treats a missing column as no `admittedAt`, so this
+version submits, reads back and executes such actions on a schema without migration 6, as the
+previous version did (live test "without migration 6, an action without admitSubmission is
+submitted …"). Before submitting an action that declares `admitSubmission`: (1) run
+`ensureSchema()` so migration 6 exists; without it that submission fails with an error naming
+migration 6, and nothing is written; (2) upgrade every worker, since a worker on an older Host would
+execute such an invocation without checking `admittedAt`.
+
 ## External mutation governance
 
 Hosts can configure `resolveMutationGovernance` to persist an approved, provider-neutral
@@ -362,7 +491,113 @@ already be audit-safe.
 Adapter and compliance lifecycle events remain canonical but are excluded from bus egress by default.
 Use `shouldPublish` to opt them in only when the application has made their payloads safe for that bus.
 
+The envelope leaves out the actor by default, for every payload classification. `outbox.includeActor`
+opts events in: when it returns `true`, the envelope carries the event's `actorId` and `actorType`.
+With the hook absent, the envelope a publisher receives is unchanged and has no actor keys at all.
+`includeActor` takes the same `(event, classification)` arguments as `includeProvenance`, but its
+default is "never" rather than "unless restricted". Only a literal `true` opts an event in.
+
+```ts
+outbox: {
+  producerModuleVersion,
+  classifyPayload,
+  includeActor: (event, classification) => classification !== "restricted",
+}
+```
+
+An included actor reaches every sink of every relay that reads this outbox, so opt in only when every
+one of them may hold actor identifiers. To give the actor to one sink only, a composite publisher must
+strip `actorId` and `actorType` before handing the envelope to the others.
+
+Each outbox record stores the decision as `actorDisclosure` (`"included"` or `"suppressed"`), and
+`runOutboxRelayCycle()` passes it to the publisher as `context.actorDisclosure`. A record written before
+Host stored the decision has no `actorDisclosure`, and the relay reports it as `"legacy"`. Host's
+stores read the actor back only from `included` records, so a legacy envelope carries no actor.
+Replaying the outbox cannot add one, so a consumer that needs the actor must read it from the
+canonical event. `suppressed` means the application chose not to share
+the actor. On PostgreSQL the decision lives in the `event_outbox.actor_disclosure` column, added by
+`ensureSchema()` migration 4. Rows that existed before that migration stay `NULL` and read as legacy.
+The column's check accepts `NULL`; every non-`NULL` value must be `included` or `suppressed`.
+Writers on an older Host version keep inserting `NULL` (legacy).
+
+Roll out in this order:
+
+1. Run `ensureSchema()` so migration 4 is applied. Writers on this version insert into the new
+   column and fail without it.
+2. Upgrade every relay that reads the shared outbox.
+3. Only then enable `includeActor`.
+
+The order matters because a relay on an older Host version hydrates outbox rows without the actor
+fields, publishes with no `actorDisclosure` in the context, and acknowledges the record. A consumer
+behind that relay receives an actorless envelope that it reads as legacy, although the row says
+`included`, and the published record is not relayed again.
+
 For deterministic local tests, `MemoryPlatformHostStore` enables governed Host outbox egress only
 when its constructor receives a `MemoryPlatformHostTransactionProvider` with domain `snapshot` and
 `restore` functions. Without that explicit rollback seam, `transactionalOutbox` is false and Host
 construction rejects outbox configuration. PostgreSQL remains the production implementation.
+
+### Requeueing a dead letter
+
+A record that exhausts the relay's `maxAttempts` moves to `dead_letter` and stays there. Once the
+consumer that rejected it is fixed, an operator moves it back with `requeueOutboxDeadLetter`:
+
+```ts
+const host = createGovernedActionHost({
+  store,
+  registry,
+  authorization: {
+    checkEntitlement,
+    authorize,
+    // Required: without it every requeue is refused as not_authorized.
+    authorizeOutboxRequeue: async ({ tenantId, actorId, record }) =>
+      operators.canReplay(tenantId, actorId, record?.eventType),
+  },
+});
+
+const result = await host.requeueOutboxDeadLetter({
+  outboxId: "evt_01J...",
+  tenantId,
+  spaceId,
+  actorId: session.actorId, // from the authenticated session, not the request body
+  actorType: "natural_person",
+  reason: "Receiver fixed in release 42",
+});
+if (result.status === "refused") {
+  // result.refusal is "not_authorized", "not_found", "not_dead_letter", or "stale"
+}
+```
+
+The host reads the record within the tenant and space, asks `authorizeOutboxRequeue` with the
+record's event type, classification, status and attempt count, and then calls the store's
+compare-and-set with the lease token it read. Every relay claim increments that token, so the
+store accepts only the dead letter that was authorized, not one that was requeued, retried and
+dead-lettered again while the authorizer ran. The store moves the record from `dead_letter` to
+`pending`, resets
+`attemptCount` to 0, sets `availableAt` (the host clock unless the caller gives a later time),
+clears the lease owner and keeps the lease token increasing, so a stale relay cannot checkpoint
+the record. In the same step it appends an `OutboxRequeueRecord` saying who requeued the record,
+when and why, together with the attempt count, last error, availability and lease token that the
+requeue replaced. The record keeps its `lastError`. The next relay cycle republishes it under the
+same `eventId`, so consumers still deduplicate on it. `listOutboxRequeues` reads the evidence.
+
+Refusals are returned, not thrown. An actor who is refused is told `not_authorized` whether or
+not the record exists. A record in another tenant or space is `not_found`. A pending or published
+record is `not_dead_letter`, and so is the losing side of two concurrent requeues, since only one
+compare-and-set can see `dead_letter`. A record that is a dead letter again, but a later one than
+the host read, is `stale`; read and authorize it again. An exception thrown by
+`authorizeOutboxRequeue` propagates,
+and nothing is requeued. Each requeue emits `outbox.requeued` (`fabric.platform.outbox.requeued`)
+and each refusal emits `outbox.requeue_refused`. The health snapshot's dead-letter count drops
+because the record is pending again. Requeue evidence the store returns is a copy, so editing a
+result or a history entry does not change the stored history. A returned outbox record has its own
+Date fields, but its event payload and provenance are shared with the stored record, as before.
+
+The operation is on `OutboxRequeueHost`, not `GovernedActionHost`, so a hand-written
+`GovernedActionHost` from 7.2 still satisfies that interface. `createGovernedActionHost()` returns
+`GovernedActionHost & OutboxRequeueHost`.
+
+This capability lives on `OutboxRequeuePlatformHostStore`, which extends `OutboxPlatformHostStore`.
+`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.