@fabricorg/platform 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @fabricorg/platform
 
+## 1.8.0
+
+### Minor Changes
+
+- eac74a9: Adapter circuit breakers now work. `AdapterImplementation.circuitBreaker` was declared and documented, but nothing read it. Platform now implements the breaker, and Host enforces it (issue #22).
+
+  **Release note: new failure semantics.** An adapter that declares `circuitBreaker: { mode: "enforce", ... }` can now have calls refused. Before this release that config had no effect. Review every adapter that already declares `mode: "enforce"` before upgrading, or switch it to `"monitor"` to observe first.
+
+  - **`@fabricorg/platform` (adapters subpath and root).**
+    - New exports: `InMemoryAdapterCircuitBreaker`, `AdapterCircuitBreakerRegistry`, `AdapterCircuitOpenError`, `isAdapterCircuitOpenError`, `classifyCircuitBreakerOutcome`, `assertAdapterCircuitBreakerConfig`, and the types `AdapterCircuitBreaker`, `AdapterCircuitBreakerProvider`, `AdapterCircuitState`, `AdapterCircuitOutcome`, `AdapterCircuitAdmission`, `AdapterCircuitBreakerEvent` and `AdapterCircuitBreakerManualOverride`. `AdapterCircuitAdmission.generation` identifies the epoch an admission was granted in.
+    - `AdapterCircuitBreakerConfig` gains the optional `manualOverride` (`"force_open"` or `"force_closed"`) and `probeLeaseMs` fields. No existing field changed.
+    - The breaker is per process: state is in memory, is not shared between replicas and is lost on restart.
+    - It goes closed → open → half-open (one probe) → closed, over a rolling `windowMs` and a `cooldownMs`. At most one half-open probe is outstanding until it records or its lease expires. The lease is the new optional `probeLeaseMs` (default `max(cooldownMs, windowMs)`), independent of the cooldown. `check()` is a side-effect-free preview.
+    - Only outcomes from the current epoch change state. The breaker's epoch advances on every state change, manual-override change and probe grant, and each admission carries it as `generation`. An outcome admitted in an earlier epoch is dropped: it never closes or reopens the breaker, never resolves or frees the probe slot, and is not counted toward a later trip. For example, a replaced probe that fails after its replacement closed the breaker does not reopen it. A direct `record()` call without an admission, or with one that has no `generation`, is treated as current.
+    - `failureThreshold` is a failure count, matching the .NET port. Once `minimumSamples` (default `failureThreshold`) outcomes are in the window, the breaker opens on `failureThreshold` consecutive failures, or on a failure ratio of at least `failureThreshold / minimumSamples`.
+    - Outcomes `transient_failure`, `timeout`, `ambiguous` and unclassified thrown errors count as failures. `permanent_failure` is ignored.
+  - **`executeWithAdapterRetry`** takes an optional `circuitBreaker`. Without it, behaviour is unchanged.
+    - With it, admission is checked immediately before every attempt, with no await between admission and `execute`, and the outcome of every attempt that reached `execute` is recorded.
+    - New optional `prepareAttempt(attempt, maxAttempts)` hook, awaited before admission. If it throws, no admission is taken and no outcome is recorded; the error is classified and retried or rethrown like an error thrown by `execute`.
+    - In `enforce` mode, a refused attempt is not executed and `AdapterCircuitOpenError` is thrown (`code: "ADAPTER_CIRCUIT_OPEN"`, with `adapterKey`, `attempt` and `retryAfterMs` when known).
+    - When the breaker opens between attempts, retrying stops and the same error is thrown.
+    - `monitor` mode never blocks. It reports `would_reject` telemetry through `onEvent`, and the callback's errors are swallowed. Events are delivered after the breaker operation that produced them commits, never during a decision or a record, so a callback that calls back into the breaker (for example to force it open) sees committed state, and its change applies from the next decision on. A callback never revokes an admission that is already committed; the README lists the two edge cases this leaves (a breaker call made from inside a callback, and `cooldownMs: 0`).
+  - **`@fabricorg/platform-host`.**
+    - Each Host instance keeps one breaker per `adapterType:operation`. A breaker is created on the adapter's first call, and only for adapters that declare `circuitBreaker`.
+    - Host now writes each attempt number to the adapter invocation record in `prepareAttempt`, before breaker admission, instead of inside `execute`. A store failure there is classified and retried as before, and is not counted against the breaker.
+    - The new `adapterCircuitBreakers` option supplies a shared `AdapterCircuitBreakerRegistry` or a custom provider (shared breakers, telemetry, manual override).
+    - A circuit-open refusal means the adapter never ran. Host marks the adapter invocation `failed` and appends `AdapterInvocationFailed` with the additive payload fields `reason: "circuit_open"` and `retryAfterMs`. The invocation then fails with status `failed`, the same path as an unsuccessful adapter result.
+    - A refusal is never routed to `reconciliation_required`, and it is never classified as a timeout. Domain events already appended in the `before_adapters` phase are kept.
+    - `createGovernedActionHost()` now throws at construction if an adapter declares an invalid `circuitBreaker` config, for example a `failureThreshold` below 1. Such a config was previously ignored.
+    - **Peer range:** Host now requires `@fabricorg/platform` `^1.8.0` (was `^1.2.0`), because it imports the new breaker exports at runtime. The manifest declares it as `workspace:^`, like the other workspace packages that peer on Platform, so the published range is the Platform version released with Host. A literal `^1.8.0` would fail the packed-consumer check (`pnpm verify:packed`) until the version PR publishes 1.8.0. A side effect: each later Host release will require at least the Platform version that is current when that Host is released.
+
+- e0f7ca7: Platform can now build evidence packets. `@fabricorg/platform/evidence` previously declared only the envelope types, so applications had to write their own generator (issue #24).
+
+  **Release note: new redaction and tenant-isolation semantics for applications that adopt the generator.** Nothing changes for code that does not call it.
+
+  - **`generateEvidencePacket(input, context, options)`** builds a `sealed` `EvidencePacketEnvelope` for one subject through an application-supplied read port. It persists nothing; storing the packet is the application's job.
+    - Subjects: the primary subject first, then the related subjects from `resolveRelatedSubjects`, de-duplicated and sorted by `subjectType` then `subjectId`. `includeRelated: false`, or a port without the resolver, uses only the primary subject, and `payload.includeRelated` records whether the lookup ran.
+    - It reads events, then the action invocations, policy evaluations and adapter invocations those events reference. The three dependent readers are optional; an absent one yields an empty section, and none is called when no event references an action invocation.
+    - **Fails closed on scope.** A record whose `tenantId` or `spaceId` differs from the generation context throws `EvidencePacketGenerationError` (`code: "EVIDENCE_SCOPE_MISMATCH"`) instead of being included or dropped. The check runs on the record as returned and again after normalization. A dependent record the generator did not ask for throws `EVIDENCE_UNREQUESTED_RECORD`. Errors thrown by the port propagate and no packet is returned.
+    - What the generator enforces on port data is tenant/space scope, requested invocation ids and record shape. It does not check an event's subject against the requested subjects; choosing the events (for example including events of the primary subject's own action invocations) is the port's responsibility.
+    - The payload is plain JSON: every `Date` becomes an ISO string, and values JSON cannot represent faithfully (NaN, Infinity, invalid `Date` objects, bigint, Maps, class instances without `toJSON`, an own `__proto__` key) throw `EVIDENCE_INVALID_RECORD` instead of being changed or dropped. A cyclic value is not detected and fails with a `RangeError` instead; no packet is produced. Fields inherited from a prototype are not read. Events are sorted by the `occurredAt` instant, the `recordedAt` instant, `sequence`, then `id`; the other sections by `id`.
+    - Event `occurredAt`/`recordedAt` strings must be ISO 8601 or PostgreSQL ISO date-times with an explicit zone (`Z`, `+HH`, `+HH:MM` or `+HHMM`, offset hours up to 14, optionally after a single space), for example `2026-05-01 10:20:30.123456+00`. They are parsed field by field rather than with `new Date(string)`: a zone-less string, any other format, or an out-of-range field (February 30, hour 24, offset `+15`) throws `EVIDENCE_INVALID_RECORD` instead of being guessed or rolled over, so the payload and checksum do not depend on the host's time zone or on the JavaScript engine's fallback parser. Timestamps are kept to millisecond precision (the fraction is truncated).
+    - **Redaction uses the existing privacy engine.** `options.anonymizationPolicy` (required; pass `{ fields: [] }` to redact nothing) runs through `AnonymizationEngine` with data class `"evidence_packet"`, before hashing. The resulting `AnonymizationMetadata` is stored as `payload.redaction`. Its `jobId` defaults to the packet id and its `reason` to `"evidence_packet_generation"`. Envelope subjects and reference metadata are read from the redacted payload.
+    - **`_privacy` values are validated.** The engine passes any `_privacy` key through without applying the policy, because it stores its own metadata there. The generator accepts a `_privacy` value from the port, at any depth, only when it has exactly the engine's `AnonymizationMetadata` shape (as on an event anonymized with `anonymizeAssetEventPayload`); any other `_privacy` value throws `EVIDENCE_INVALID_RECORD`. `redactedAt` must be an exact `toISOString()` value and `beforeChecksum` a SHA-256 hex digest. Residual risk: the free-text fields (`reason`, `jobId`, `policyVersion`, `fieldPath`, and the `preservedSemantics` entries) are type-checked as strings but not inspected, so sensitive text a port writes into them reaches the packet. The data-class and redaction-method lists the validator uses fail type-checking if they drift from `PlatformDataClass` or `RedactionMethod`.
+    - Record `id`s must pass through redaction unchanged; a policy that removes or changes one throws `EVIDENCE_IDENTIFIER_REDACTED`. Subject ids may be transformed (for example tokenized) but must remain non-empty strings. The engine scopes tokens to their field path and array position, so a tokenized value differs in each place it appears and cannot be used to match records or look packets up; tokenizing `actionInvocationId` likewise breaks the links to action invocations, undetected. Like `beforeChecksum`, `tokenize` and `hash` outputs let a low-entropy value be guessed.
+    - Not redacted: values used as object keys (the policy matches field names and paths), and envelope fields copied from the context or input (`generatedBy`, `correlationId`, `causationId`, `policyVersion`).
+    - References: one per action invocation, asset event, policy evaluation and adapter invocation, with identifier-only metadata (for example `eventType`, subject ids, `adapterType`, `operation`, `status`).
+  - **New read-port and record types:** `EvidencePacketReadPort`, `EvidenceEventQuery`, `EvidenceScope`, `EvidenceEventRecord` (satisfied by `AssetEventEnvelope` and `AssetEventLike`), `EvidenceRecord`, `EvidenceInvocationRecord`, `EvidenceJsonRecord`, `EvidenceTimestamp`, `EvidencePacketPayload`, `GenerateEvidencePacketInput` and `GenerateEvidencePacketOptions`, plus `EvidencePacketGenerationError` and its code type.
+  - **Checksums.** `checksum` is the hex SHA-256 of `canonicalJson(payload)`. The new constant `EVIDENCE_PACKET_CHECKSUM_ALGORITHM` (`"fabric-canonical-json-sha256-v1"`, the same identifier as Host's parameter digest because the algorithm is the same) is recorded in the new optional `EvidencePacketEnvelope.checksumAlgorithm` field. No existing field changed. `verifyEvidencePacketChecksum(envelope)` recomputes it and returns `false`, without throwing, on a mismatch, a missing checksum or an unknown algorithm. `computeEvidencePacketChecksum(payload)` is exported too. The checksum covers the payload only, not the other envelope fields.
+  - **`canonicalJson`** is now exported from `@fabricorg/platform/evidence` and the root. It moved from `@fabricorg/platform-host` unchanged, byte for byte, including its treatment of `Date` as `{}`.
+  - `createEvidencePacketRenderer(options)` wraps the generator as an `EvidenceRenderer`. Other new constants: `EVIDENCE_PACKET_SCHEMA_VERSION`, `DEFAULT_EVIDENCE_PACKET_TYPE` (`"compliance_evidence"`) and `DEFAULT_EVIDENCE_REDACTION_REASON`.
+
+### Patch Changes
+
+- d5fa7c2: Documentation only: the `SagaContext.awaitSignal` contract now says that a runtime drops a signal whose stable signal ID it has already received for the saga, and that FIFO buffering applies among distinct signals. Signals without an ID are not deduplicated. No runtime in this package implements `awaitSignal`; `@fabricorg/platform-temporal` ships `createSagaSignalInbox()` for Temporal workflows (issue #23).
+
+## 1.7.0
+
+### Minor Changes
+
+- 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`).
+
+- 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.
+
 ## 1.6.0
 
 ### Minor Changes

package/README.md

@@ -48,12 +48,12 @@ That's what this package gives you. Nothing more.
 | `@fabricorg/platform/state-machines` | `StateMachineDefinition`, structural and guard-aware transition evaluation |
 | `@fabricorg/platform/events` | `AssetEventEnvelope`, `EventTypeRegistry` |
 | `@fabricorg/platform/projections` | Replay/snapshot framework |
-| `@fabricorg/platform/adapters` | `AdapterRegistry`, retry + circuit-breaker |
+| `@fabricorg/platform/adapters` | `AdapterRegistry`, `executeWithAdapterRetry`, in-process circuit breaker (`InMemoryAdapterCircuitBreaker`, `AdapterCircuitBreakerRegistry`, `AdapterCircuitOpenError`) |
 | `@fabricorg/platform/modules` | `FabricModule<TDb>`, `createModuleRegistry` |
 | `@fabricorg/platform/manifest` | `exportModuleManifest`, `exportModuleManifestBundle`, `ModuleManifest` |
 | `@fabricorg/platform/ids` | `createFabricId`, `FABRIC_ID_PREFIXES` |
 | `@fabricorg/platform/privacy` | Redaction + data classification |
-| `@fabricorg/platform/evidence` | Compliance evidence packets |
+| `@fabricorg/platform/evidence` | Compliance evidence packets: `generateEvidencePacket`, `verifyEvidencePacketChecksum`, `canonicalJson` (see [Evidence packets](#evidence-packets)) |
 | `@fabricorg/platform/governance` | External footprints, delegated principals, obligations, attestations, and reconciliation |
 | `@fabricorg/platform/objects` | Shared object-type contracts |
 | `@fabricorg/platform/testing` | In-memory adapter registry, fake `ActionContext`, deterministic IDs |
@@ -103,6 +103,8 @@ const json = JSON.stringify(manifest, null, 2);
 
 An entity schema does not validate arbitrary writes through `TDb`. Persisted-record validation requires an explicit Host/database adapter. When an action declares `resultSchema`, Platform Host validates the public result after the handler and before events or adapters; failure rolls back domain writes only when the Host store has a transaction provider that includes them.
 
+An action may also declare `admitSubmission`, an async check that decides whether a submission may be recorded at all. It receives the trusted `tenantId`, `spaceId`, `actorId` and `actorType`, the submitted parameters and a `signal` (`ActionAdmissionSignal`, a structural subset of `AbortSignal`; Host passes a real one), and answers `{ admitted: true }` or `{ admitted: false, code }` with a fixed code. `@fabricorg/platform-host` 7.3.0 and later runs it after authorizing the submitter and before writing anything for the submission, refuses on a throw, timeout or any other answer, and passes the admission time to the handler as `ActionContext.admittedAt`. An older host ignores the field, so a handler that relies on it should refuse without `ctx.admittedAt`. Registration rejects an `admitSubmission` that is not a function.
+
 ## The action lifecycle
 
 Every `invokeAction(id, params)` call goes through:
@@ -110,12 +112,223 @@ Every `invokeAction(id, params)` call goes through:
 1. **`evaluatePolicies`** — every policy registered for the action runs (code/data/hybrid). A single `block` halts the invocation. Policies may return `guidance` (`factsUsed` + typed `correctiveActions`) so hosts can show exactly why a block happened and what the operator can do next. Corrective actions declare `kind: "invoke_action" | "navigate" | "manual"` so UIs do not guess whether a remediation is executable.
 2. **State-machine validation** — if the action's target entity is bound to a state machine, the Host reads authoritative state at the mutation boundary, validates the requested transition, and executes its guard with trusted entity, actor, parameter, invocation, and database context. A false or throwing guard fails closed.
 3. **Handler** — `actionDef.handler(ctx, params)` runs inside a single `TDb` transaction. Handler parses its own input via its `schema` (single source of truth).
-4. **Adapters** — for each `actionDef.adapterSteps`, the registered implementation runs via `executeWithAdapterRetry` (idempotent retry, exponential backoff, circuit breaker). Adapters may classify outcomes as `success`, `transient_failure`, `permanent_failure`, `timeout`, or `ambiguous`; only transient idempotent outcomes are retried. Ambiguous outcomes are routed to `reconciliation_required` with durable evidence.
+4. **Adapters** — for each `actionDef.adapterSteps`, the registered implementation runs via `executeWithAdapterRetry` (idempotent retry, exponential backoff, and an optional per-adapter circuit breaker; see [Adapter circuit breakers](#adapter-circuit-breakers)). Adapters may classify outcomes as `success`, `transient_failure`, `permanent_failure`, `timeout`, or `ambiguous`; only transient idempotent outcomes are retried. Ambiguous outcomes are routed to `reconciliation_required` with durable evidence.
 5. **Events** — domain events are appended; projections derive read models on next replay.
 6. **Completion** — invocation status is marked, telemetry emitted.
 
 `validateActionParameters` is also exposed for preview/dry-run paths but is **not** part of the execute pipeline.
 
+## Adapter circuit breakers
+
+`AdapterImplementation.circuitBreaker` configures a breaker for one adapter operation:
+
+```ts
+const sendAdapter: AdapterImplementation = {
+  adapterType: "email",
+  operation: "send",
+  vendor: "mailco",
+  idempotent: true,
+  circuitBreaker: { mode: "enforce", failureThreshold: 5, windowMs: 60_000, cooldownMs: 30_000 },
+  execute: async (input, context) => ({ success: true }),
+};
+```
+
+`AdapterCircuitBreakerRegistry` creates one `InMemoryAdapterCircuitBreaker` per `adapterType:operation`
+from each adapter's own config, on first use, and none for an adapter without a config.
+`executeWithAdapterRetry({ ..., circuitBreaker })` asks it for admission immediately before every
+attempt, with no await between admission and the `execute` call, and records the outcome of every
+attempt that reached `execute`. Put any awaited work an attempt needs first (for example, writing
+the attempt number) in the optional `prepareAttempt(attempt, maxAttempts)` hook, which runs before
+admission. If `prepareAttempt` throws, no admission is taken and no outcome is recorded; the error is
+classified and retried or rethrown like an error thrown by `execute`. Without `circuitBreaker` and
+`prepareAttempt` the retry loop is unchanged.
+`@fabricorg/platform-host` 7.4.0 and later wires this up for every adapter step.
+
+**Scope.** The breaker is in-process memory. It is not distributed: each process, replica or Host
+instance with its own registry trips on the failures it observes itself, and state is lost on restart.
+To share a breaker across processes, implement the `AdapterCircuitBreaker` interface over shared
+storage and supply it through an `AdapterCircuitBreakerProvider`.
+
+**States.** `closed` → `open` → (after `cooldownMs`) `half_open` → `closed` or back to `open`.
+Half-open admits one probe call. A probe success closes the breaker and clears its window, and a
+probe failure reopens it and restarts the cooldown. In `enforce` mode, other calls are refused while
+the probe is in flight. The probe holds its slot until it records an outcome or its lease of
+`probeLeaseMs` expires (default `max(cooldownMs, windowMs)`, independent of the cooldown, so
+`cooldownMs: 0` still admits one probe at a time). After the lease expires the next call becomes the
+probe. `check()` is a side-effect-free preview: it does not commit an elapsed cooldown, take the
+probe, change the epoch or emit telemetry.
+
+**Stale outcomes.** An outcome may change the breaker's state only if the call was admitted in the
+breaker's current epoch. The epoch advances on every state change (including the one an elapsed
+cooldown commits), every manual-override change, and every probe grant. Each admission returned by
+`acquire()` carries its epoch as `generation`, and `executeWithAdapterRetry` passes it back to
+`record()`. An outcome from an earlier epoch is dropped: it does not close or reopen the breaker,
+does not resolve or free the probe slot, and is not added to the rolling window, so it cannot help
+trip the breaker later. This covers a replaced probe that reports after its replacement closed the
+breaker, and a call admitted while closed whose failure arrives after the breaker opened. Outcomes
+from the current epoch count exactly as described under Thresholds. A direct caller that records
+without an admission, or with one that has no `generation`, is treated as current: the outcome is
+sampled, can trip a closed breaker and resolves an outstanding probe.
+
+**Thresholds.** `failureThreshold` is a failure count, with the same rule as the .NET port. Let
+`M = minimumSamples ?? failureThreshold`. Once at least `M` outcomes fall within the last `windowMs`,
+a recorded failure opens the breaker when either:
+
+- the most recent `failureThreshold` outcomes are all failures, or
+- the failure ratio in the window is at least `failureThreshold / M`.
+
+Without `minimumSamples` this means "`failureThreshold` consecutive failures". With
+`failureThreshold: 10, minimumSamples: 20` the breaker also opens at a 50% failure rate over at least
+20 calls. `assertAdapterCircuitBreakerConfig` rejects a non-positive or fractional `failureThreshold`
+or `minimumSamples`, a non-positive `windowMs`, and a negative `cooldownMs`.
+
+**Modes.** `monitor` runs the same state machine and telemetry but never blocks a call. Calls that
+`enforce` mode would have refused are reported as `would_reject`. `enforce` refuses calls while
+the breaker is open: `execute` is not called, and `executeWithAdapterRetry` throws
+`AdapterCircuitOpenError` (`code: "ADAPTER_CIRCUIT_OPEN"`, `adapterKey`, `state`, `attempt`,
+`retryAfterMs` when known). If the breaker opens between attempts, retrying stops and the same error
+is thrown. Use `isAdapterCircuitOpenError(error)` to recognise it, which also works across duplicate
+copies of this package.
+
+**Outcome mapping** (`classifyCircuitBreakerOutcome`):
+
+| Adapter outcome | Counts as |
+|---|---|
+| `success` | success |
+| `transient_failure` | failure |
+| `timeout` | failure |
+| `ambiguous` | failure (no definite answer is a health signal, even though Host routes it to reconciliation) |
+| `permanent_failure` | ignored (the dependency answered and rejected the request; not a dependency failure) |
+| thrown error | the kind `classifyThrownError` returns, `transient_failure` by default, mapped as above |
+
+**Manual override.** `manualOverride: "force_open" | "force_closed"` in the config, or
+`breaker.setManualOverride(...)` at runtime (`undefined` clears it). An override pins the reported
+state and suspends automatic transitions. Outcomes of calls admitted under the override keep being
+recorded; setting or clearing the override starts a new epoch, so outcomes of calls admitted before
+the change are dropped as stale. Like an automatic open, `force_open` blocks only in `enforce` mode.
+Clearing returns the breaker to `closed` with its window intact.
+
+**Telemetry.** Pass `onEvent` to the breaker or registry to receive `state_change` (with a
+`reason`), `rejected` and `would_reject` events. Errors the callback throws, and promises it
+rejects, are swallowed so telemetry cannot change a call's outcome. Events are delivered after the
+operation that produced them commits, never part-way through a decision or a record. Committing an
+elapsed cooldown is its own step, delivered before `acquire()` decides, so a callback that forces the
+breaker open on `cooldown_elapsed` refuses that call. A callback may call back into the breaker: it
+sees committed state, its changes apply from the next decision on, and the events they produce are
+delivered after it returns, in order. A callback never revokes an admission that is already
+committed, so there are two exceptions to the cooldown rule above: a breaker call made from inside a
+callback decides before its own `cooldown_elapsed` is delivered, and with `cooldownMs: 0` a cooldown
+that falls due again during a decision (because a callback reopened the breaker) is admitted before
+its event is delivered. Use a non-zero `cooldownMs` and avoid calling `acquire()` from a callback if
+an override set from telemetry must always stop the next call.
+
+## Evidence packets
+
+`generateEvidencePacket` builds a sealed, redacted, checksummed evidence packet for one subject. Your
+application supplies a read port over its own store; the generator persists nothing, so storing the
+returned envelope is up to you.
+
+```ts
+import {
+  generateEvidencePacket,
+  verifyEvidencePacketChecksum,
+  type EvidencePacketReadPort,
+} from "@fabricorg/platform/evidence";
+
+const port: EvidencePacketReadPort = {
+  listEvents: ({ tenantId, spaceId, subjects }) => store.eventsFor(tenantId, spaceId, subjects),
+  // Optional. Each absent reader leaves its section empty.
+  resolveRelatedSubjects: (subject, scope) => store.relatedSubjects(subject, scope),
+  listActionInvocations: (scope, ids) => store.actionInvocations(scope, ids),
+  listPolicyEvaluations: (scope, invocationIds) => store.policyEvaluations(scope, invocationIds),
+  listAdapterInvocations: (scope, invocationIds) => store.adapterInvocations(scope, invocationIds),
+};
+
+const packet = await generateEvidencePacket(
+  { subject: { subjectType: "Case", subjectId: caseId }, policyVersion: "2026-06" },
+  { tenantId, spaceId, actorId, correlationId, db, now: new Date() },
+  {
+    port,
+    anonymizationPolicy: { fields: [{ match: "key", value: "email", method: "tokenize" }] },
+  },
+);
+await store.savePacket(packet);
+verifyEvidencePacketChecksum(packet); // true until the payload is altered
+```
+
+What the tests in `evidence/generator.test.ts` cover:
+
+- **Scope fails closed.** A record from the port whose `tenantId` or `spaceId` differs from the context
+  throws `EvidencePacketGenerationError` with code `EVIDENCE_SCOPE_MISMATCH`, in every section. The
+  check runs on the record as returned and again after normalization. A dependent record for an action
+  invocation the generator did not request throws `EVIDENCE_UNREQUESTED_RECORD`. An error thrown by the
+  port propagates, and no packet is returned.
+- **What the port decides.** The generator does not check an event's subject against the requested
+  subjects: a port may return events recorded against the primary subject's own action invocations
+  under another subject. Selecting the right events is the port's job.
+- **Record shape.** Records must have a non-empty `id`, and events their documented fields.
+  `occurredAt` and `recordedAt` must be a `Date` or an ISO 8601 / PostgreSQL ISO date-time string
+  with an explicit zone: `YYYY-MM-DD` (or a signed 4–6 digit year), `T` or a space,
+  `HH:MM[:SS[.fraction]]`, an optional single space, then `Z`, `+HH`, `+HH:MM` or `+HHMM` with offset
+  hours up to 14 (for example `2026-05-01 10:20:30.123456+00`). The string is parsed field by
+  field without `Date`'s lenient parser, and an out-of-range field (February 30, hour 24, offset
+  `+15`) or any other format throws `EVIDENCE_INVALID_RECORD` instead of being rolled over or
+  guessed. A zone-less string such as `"2026-05-01 00:00:00"` throws too, because reading it would
+  depend on the host's time zone. Timestamps are kept to millisecond precision, truncated
+  (`.123999+00` becomes `.123Z`). Values JSON cannot represent faithfully (NaN, Infinity, invalid
+  `Date` objects, bigint, Maps, class instances without `toJSON`, an own `__proto__` key) throw
+  `EVIDENCE_INVALID_RECORD` instead of being changed or dropped. A cyclic value (including a `toJSON`
+  that returns itself) is not detected: it fails with a `RangeError` rather than an
+  `EvidencePacketGenerationError`, and no packet is produced. Fields inherited from a prototype are not read.
+- **Subjects.** The primary subject comes first, then the related subjects, de-duplicated and sorted.
+  Related subjects are used only when the port has `resolveRelatedSubjects` and `includeRelated` is not
+  `false`; `payload.includeRelated` records whether that lookup ran.
+- **Deterministic payload.** Events are sorted by the `occurredAt` instant, then the `recordedAt`
+  instant, `sequence` and `id`; the other sections by `id`. Every `Date` becomes an ISO string, and
+  event timestamps given as zoned strings are rewritten as the ISO string of the same instant; other
+  strings are kept as given. So with the same `now`, packet id and options, the same records give the
+  same payload and checksum when they come back in a different order, with keys in a different order,
+  or with an event timestamp as a `Date` or as a zoned string (the tests use `Z`, `+00`, `+00:00` and
+  `+0200`) for the same millisecond.
+- **Redaction before hashing.** The payload runs through the privacy `AnonymizationEngine` with data
+  class `"evidence_packet"`, and its `AnonymizationMetadata` is stored as `payload.redaction` (`jobId`
+  defaults to the packet id, `reason` to `"evidence_packet_generation"`, `redactedAt` to the generation
+  time). In the tests, a redacted value does not appear anywhere in the serialized envelope, because the
+  envelope's subjects and reference metadata are read from the redacted payload.
+  - The engine passes any `_privacy` key through without applying the policy, because that is where it
+    keeps its own metadata. The generator therefore accepts a `_privacy` value from the port, at any
+    depth, only when it has exactly the `AnonymizationMetadata` shape the engine writes (for example on
+    an event already anonymized with `anonymizeAssetEventPayload`); any other `_privacy` value throws
+    `EVIDENCE_INVALID_RECORD`. Fixed-format fields are pinned: `redactedAt` (top level and per field)
+    must be an exact `toISOString()` value and `beforeChecksum` 64 lowercase hex characters. The
+    free-text fields (`reason`, `jobId`, `policyVersion`, each `fieldPath`, and the `preservedSemantics`
+    entries) are only type-checked as strings, not inspected, so a port that writes sensitive text into
+    them would carry it into the packet.
+  - Record `id`s must come through redaction unchanged; a policy that removes or changes one (for
+    example `mask` on `id`) throws `EVIDENCE_IDENTIFIER_REDACTED`. Subject ids may be transformed, for
+    example tokenized, but must remain non-empty strings.
+  - The engine scopes each token to its field path, including array positions. The same raw value
+    therefore gets a different token in each place it appears, within one packet and across packets
+    (a related subject's token changes when its position in `subjects` does). Tokenized values cannot
+    be used to match records or to look packets up; index the raw subject outside the packet if you
+    need that. For the same reason, tokenizing `actionInvocationId` breaks the link between records
+    and their action invocations, and the generator does not detect it.
+  - The policy matches field names and paths, not values used as object keys, so a sensitive value
+    stored as a key (`{ byEmail: { "jane@example.com": 1 } }`) is not redacted.
+  - Envelope fields copied from the context (`generatedBy`, `correlationId`, `causationId`) and from
+    the input (`policyVersion`) are not redacted.
+  - The engine's field metadata keeps a SHA-256 `beforeChecksum` of each redacted value, as it does
+    elsewhere. `hash` output is an unsalted SHA-256, and every input to a `tokenize` token (tenant,
+    space, field path, policy version) is in the packet. So a low-entropy value can be guessed from
+    any of the three; keep such values out of the store or use opaque references.
+- **Checksum.** `checksum` is the hex SHA-256 of `canonicalJson(payload)`, recorded with
+  `checksumAlgorithm: EVIDENCE_PACKET_CHECKSUM_ALGORITHM`. `verifyEvidencePacketChecksum` returns `false`
+  for a changed payload, a missing checksum or an unknown algorithm. The checksum covers the payload,
+  not the other envelope fields.
+
+`createEvidencePacketRenderer(options)` wraps the generator as an `EvidenceRenderer` for one packet
+type.
+
 ## Saga actions
 
 Multi-step orchestrations declare `kind: "saga"` on the `ActionDefinition` and ship a `SagaImplementation`:

package/dist/actions/index.cjs

@@ -1,28 +1,28 @@
 'use strict';
 
-var chunkDDX5FKOM_cjs = require('../chunk-DDX5FKOM.cjs');
+var chunkUGWGHTNC_cjs = require('../chunk-UGWGHTNC.cjs');
 
 
 
 Object.defineProperty(exports, "ACTOR_TYPES", {
   enumerable: true,
-  get: function () { return chunkDDX5FKOM_cjs.ACTOR_TYPES; }
+  get: function () { return chunkUGWGHTNC_cjs.ACTOR_TYPES; }
 });
 Object.defineProperty(exports, "assertActionId", {
   enumerable: true,
-  get: function () { return chunkDDX5FKOM_cjs.assertActionId; }
+  get: function () { return chunkUGWGHTNC_cjs.assertActionId; }
 });
 Object.defineProperty(exports, "assertActorType", {
   enumerable: true,
-  get: function () { return chunkDDX5FKOM_cjs.assertActorType; }
+  get: function () { return chunkUGWGHTNC_cjs.assertActorType; }
 });
 Object.defineProperty(exports, "createActionRegistry", {
   enumerable: true,
-  get: function () { return chunkDDX5FKOM_cjs.createActionRegistry; }
+  get: function () { return chunkUGWGHTNC_cjs.createActionRegistry; }
 });
 Object.defineProperty(exports, "isActorType", {
   enumerable: true,
-  get: function () { return chunkDDX5FKOM_cjs.isActorType; }
+  get: function () { return chunkUGWGHTNC_cjs.isActorType; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/actions/index.d.cts

@@ -40,7 +40,72 @@ interface ActionContext<TDb = unknown> {
     };
     db: TDb;
     services?: FabricRuntimeServices;
+    /**
+     * When the host admitted this invocation's submission through the
+     * action's `admitSubmission` check, read from the durable invocation
+     * record. Absent when the action declares no check, or when the runtime
+     * that built this context does not run declared admission checks (a host
+     * older than the one that introduced them). A handler whose action
+     * declares `admitSubmission` can refuse to run without it.
+     */
+    admittedAt?: Date;
+}
+/**
+ * Trusted facts a host gives an action's `admitSubmission` check. Scope and
+ * actor come from the host's authenticated submission, never from the
+ * parameters.
+ */
+interface ActionAdmissionInput {
+    readonly actionId: ActionId;
+    readonly tenantId: string;
+    readonly spaceId: string;
+    readonly actorId: string;
+    readonly actorType: ActorType;
+    /**
+     * The submitted parameters, unvalidated, as a copy made for this check.
+     * `@fabricorg/platform-host` records its own copy of the same value, taken
+     * before the check ran, and only if the check admits it; changing this
+     * copy changes nothing the host records.
+     */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /**
+     * Aborted when the host's admission deadline passes. Hosts pass an
+     * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles
+     * at or after the deadline, even one that settles before the abort.
+     */
+    readonly signal: ActionAdmissionSignal;
 }
+/**
+ * The part of an `AbortSignal` an admission check can rely on. Declared
+ * structurally so this module compiles without DOM or Node type libraries; a
+ * host passes a real `AbortSignal`, which satisfies it.
+ */
+interface ActionAdmissionSignal {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+/**
+ * An admission check's answer. Only `{ admitted: true }` admits. A refusal's
+ * `code` must be a fixed code chosen by the action (lower-case first letter,
+ * then letters, digits, `_`, `.`, `:` or `-`, at most 128 characters), never
+ * a submitted value: the host puts it in the error it throws.
+ */
+type ActionAdmissionDecision = {
+    readonly admitted: true;
+} | {
+    readonly admitted: false;
+    readonly code: string;
+};
+/**
+ * Decides whether a submission may be recorded at all. A host that supports
+ * it runs the check after authorizing the submitter and before it writes
+ * anything durable for the submission; a refusal, a throw, a timeout or any
+ * answer other than `{ admitted: true }` refuses the submission.
+ */
+type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
 interface ActionResult {
     success: boolean;
     data?: Record<string, unknown>;
@@ -70,6 +135,16 @@ interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
     namespace: string;
     version: number;
     schema: SchemaValidator;
+    /**
+     * Optional check a host runs on every submission before it records
+     * anything durable for it (invocation, idempotency key, events, errors).
+     * Use it when parameters must be validated against trusted context, for
+     * example a secret reference the tenant's secret store must hold, before
+     * they may be persisted. `@fabricorg/platform-host` runs it from the
+     * release that introduced it; an older host ignores it, so a handler that
+     * relies on it should require `ActionContext.admittedAt`.
+     */
+    admitSubmission?: ActionAdmission;
     /** Optional validation contract for the public handler result data. */
     resultSchema?: SchemaValidator;
     handler?: ActionHandler<TDb>;
@@ -130,8 +205,15 @@ interface SagaContext {
      * Wait for a named external signal carrying a payload of `T`, with a timeout.
      *
      * Resolves with the payload of the first signal received, or `null` if the timeout
-     * fires first. Subsequent signals with the same name received before another
-     * `awaitSignal` call are buffered (FIFO) so no signal is lost.
+     * fires first. Subsequent distinct signals with the same name received before
+     * another `awaitSignal` call are buffered in FIFO order so none is lost.
+     *
+     * A signal may carry a stable signal ID that the sender keeps the same on each redelivery
+     * (for example a webhook delivery ID or an approval decision ID). A runtime drops
+     * a signal whose ID it has already received for this saga, so a sender retrying
+     * after a timeout does not wake the saga twice. Signals without an ID are not
+     * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`
+     * for Temporal runtimes.
      *
      * Intended for agent-driven and webhook-driven coordination: replace polling loops
      * with push-based wakeups while preserving the saga's deterministic replay
@@ -184,4 +266,4 @@ interface ActionRegistry<TDb = unknown> {
 }
 declare function createActionRegistry<TDb = unknown>(definitions?: readonly ActionDefinition<TDb>[]): ActionRegistry<TDb>;
 
-export { ACTOR_TYPES, type ActionCompletionMode, type ActionConnectivity, type ActionConsistency, type ActionContext, type ActionDataSensitivity, type ActionDefinition, type ActionExecutionContract, type ActionHandler, type ActionId, type ActionIdempotencyStance, type ActionRegistry, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type AuthorityMoment, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, createActionRegistry, isActorType };
+export { ACTOR_TYPES, type ActionAdmission, type ActionAdmissionDecision, type ActionAdmissionInput, type ActionAdmissionSignal, type ActionCompletionMode, type ActionConnectivity, type ActionConsistency, type ActionContext, type ActionDataSensitivity, type ActionDefinition, type ActionExecutionContract, type ActionHandler, type ActionId, type ActionIdempotencyStance, type ActionRegistry, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type AuthorityMoment, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, createActionRegistry, isActorType };

package/dist/actions/index.d.ts

@@ -40,7 +40,72 @@ interface ActionContext<TDb = unknown> {
     };
     db: TDb;
     services?: FabricRuntimeServices;
+    /**
+     * When the host admitted this invocation's submission through the
+     * action's `admitSubmission` check, read from the durable invocation
+     * record. Absent when the action declares no check, or when the runtime
+     * that built this context does not run declared admission checks (a host
+     * older than the one that introduced them). A handler whose action
+     * declares `admitSubmission` can refuse to run without it.
+     */
+    admittedAt?: Date;
+}
+/**
+ * Trusted facts a host gives an action's `admitSubmission` check. Scope and
+ * actor come from the host's authenticated submission, never from the
+ * parameters.
+ */
+interface ActionAdmissionInput {
+    readonly actionId: ActionId;
+    readonly tenantId: string;
+    readonly spaceId: string;
+    readonly actorId: string;
+    readonly actorType: ActorType;
+    /**
+     * The submitted parameters, unvalidated, as a copy made for this check.
+     * `@fabricorg/platform-host` records its own copy of the same value, taken
+     * before the check ran, and only if the check admits it; changing this
+     * copy changes nothing the host records.
+     */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /**
+     * Aborted when the host's admission deadline passes. Hosts pass an
+     * `AbortSignal`. `@fabricorg/platform-host` refuses an answer that settles
+     * at or after the deadline, even one that settles before the abort.
+     */
+    readonly signal: ActionAdmissionSignal;
 }
+/**
+ * The part of an `AbortSignal` an admission check can rely on. Declared
+ * structurally so this module compiles without DOM or Node type libraries; a
+ * host passes a real `AbortSignal`, which satisfies it.
+ */
+interface ActionAdmissionSignal {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+/**
+ * An admission check's answer. Only `{ admitted: true }` admits. A refusal's
+ * `code` must be a fixed code chosen by the action (lower-case first letter,
+ * then letters, digits, `_`, `.`, `:` or `-`, at most 128 characters), never
+ * a submitted value: the host puts it in the error it throws.
+ */
+type ActionAdmissionDecision = {
+    readonly admitted: true;
+} | {
+    readonly admitted: false;
+    readonly code: string;
+};
+/**
+ * Decides whether a submission may be recorded at all. A host that supports
+ * it runs the check after authorizing the submitter and before it writes
+ * anything durable for the submission; a refusal, a throw, a timeout or any
+ * answer other than `{ admitted: true }` refuses the submission.
+ */
+type ActionAdmission = (input: ActionAdmissionInput) => Promise<ActionAdmissionDecision>;
 interface ActionResult {
     success: boolean;
     data?: Record<string, unknown>;
@@ -70,6 +135,16 @@ interface ActionDefinition<TDb = unknown> extends SurfaceDeclaration {
     namespace: string;
     version: number;
     schema: SchemaValidator;
+    /**
+     * Optional check a host runs on every submission before it records
+     * anything durable for it (invocation, idempotency key, events, errors).
+     * Use it when parameters must be validated against trusted context, for
+     * example a secret reference the tenant's secret store must hold, before
+     * they may be persisted. `@fabricorg/platform-host` runs it from the
+     * release that introduced it; an older host ignores it, so a handler that
+     * relies on it should require `ActionContext.admittedAt`.
+     */
+    admitSubmission?: ActionAdmission;
     /** Optional validation contract for the public handler result data. */
     resultSchema?: SchemaValidator;
     handler?: ActionHandler<TDb>;
@@ -130,8 +205,15 @@ interface SagaContext {
      * Wait for a named external signal carrying a payload of `T`, with a timeout.
      *
      * Resolves with the payload of the first signal received, or `null` if the timeout
-     * fires first. Subsequent signals with the same name received before another
-     * `awaitSignal` call are buffered (FIFO) so no signal is lost.
+     * fires first. Subsequent distinct signals with the same name received before
+     * another `awaitSignal` call are buffered in FIFO order so none is lost.
+     *
+     * A signal may carry a stable signal ID that the sender keeps the same on each redelivery
+     * (for example a webhook delivery ID or an approval decision ID). A runtime drops
+     * a signal whose ID it has already received for this saga, so a sender retrying
+     * after a timeout does not wake the saga twice. Signals without an ID are not
+     * deduplicated. `@fabricorg/platform-temporal` provides `createSagaSignalInbox()`
+     * for Temporal runtimes.
      *
      * Intended for agent-driven and webhook-driven coordination: replace polling loops
      * with push-based wakeups while preserving the saga's deterministic replay
@@ -184,4 +266,4 @@ interface ActionRegistry<TDb = unknown> {
 }
 declare function createActionRegistry<TDb = unknown>(definitions?: readonly ActionDefinition<TDb>[]): ActionRegistry<TDb>;
 
-export { ACTOR_TYPES, type ActionCompletionMode, type ActionConnectivity, type ActionConsistency, type ActionContext, type ActionDataSensitivity, type ActionDefinition, type ActionExecutionContract, type ActionHandler, type ActionId, type ActionIdempotencyStance, type ActionRegistry, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type AuthorityMoment, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, createActionRegistry, isActorType };
+export { ACTOR_TYPES, type ActionAdmission, type ActionAdmissionDecision, type ActionAdmissionInput, type ActionAdmissionSignal, type ActionCompletionMode, type ActionConnectivity, type ActionConsistency, type ActionContext, type ActionDataSensitivity, type ActionDefinition, type ActionExecutionContract, type ActionHandler, type ActionId, type ActionIdempotencyStance, type ActionRegistry, type ActionResult, type ActionStateMachineBinding, type ActionStatus, type ActorType, type AdapterStep, type AdapterStepRetryPolicy, type AuthorityMoment, type FabricRuntimeServices, type SagaChildActionInput, type SagaCompletion, type SagaCompletionEvent, type SagaContext, type SagaImplementation, type SagaRunChild, type SchemaParseIssue, type SchemaParseResult, type SchemaValidator, assertActionId, assertActorType, createActionRegistry, isActorType };