@fabricorg/platform 1.7.0 → 1.8.0

package/CHANGELOG.md

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

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 |
@@ -112,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 chunkXCAOO6KG_cjs = require('../chunk-XCAOO6KG.cjs');
+var chunkUGWGHTNC_cjs = require('../chunk-UGWGHTNC.cjs');
 
 
 
 Object.defineProperty(exports, "ACTOR_TYPES", {
   enumerable: true,
-  get: function () { return chunkXCAOO6KG_cjs.ACTOR_TYPES; }
+  get: function () { return chunkUGWGHTNC_cjs.ACTOR_TYPES; }
 });
 Object.defineProperty(exports, "assertActionId", {
   enumerable: true,
-  get: function () { return chunkXCAOO6KG_cjs.assertActionId; }
+  get: function () { return chunkUGWGHTNC_cjs.assertActionId; }
 });
 Object.defineProperty(exports, "assertActorType", {
   enumerable: true,
-  get: function () { return chunkXCAOO6KG_cjs.assertActorType; }
+  get: function () { return chunkUGWGHTNC_cjs.assertActorType; }
 });
 Object.defineProperty(exports, "createActionRegistry", {
   enumerable: true,
-  get: function () { return chunkXCAOO6KG_cjs.createActionRegistry; }
+  get: function () { return chunkUGWGHTNC_cjs.createActionRegistry; }
 });
 Object.defineProperty(exports, "isActorType", {
   enumerable: true,
-  get: function () { return chunkXCAOO6KG_cjs.isActorType; }
+  get: function () { return chunkUGWGHTNC_cjs.isActorType; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/actions/index.d.cts

@@ -205,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

package/dist/actions/index.d.ts

@@ -205,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

package/dist/actions/index.js

@@ -1,3 +1,3 @@
-export { ACTOR_TYPES, assertActionId, assertActorType, createActionRegistry, isActorType } from '../chunk-6QX4I45I.js';
+export { ACTOR_TYPES, assertActionId, assertActorType, createActionRegistry, isActorType } from '../chunk-PIDZQAEL.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/adapters/index.cjs

@@ -1,40 +1,64 @@
 'use strict';
 
-var chunkXZQZQ5SW_cjs = require('../chunk-XZQZQ5SW.cjs');
+var chunkIF6NJORI_cjs = require('../chunk-IF6NJORI.cjs');
 
 
 
+Object.defineProperty(exports, "AdapterCircuitBreakerRegistry", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.AdapterCircuitBreakerRegistry; }
+});
+Object.defineProperty(exports, "AdapterCircuitOpenError", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.AdapterCircuitOpenError; }
+});
 Object.defineProperty(exports, "AdapterRegistry", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.AdapterRegistry; }
+  get: function () { return chunkIF6NJORI_cjs.AdapterRegistry; }
+});
+Object.defineProperty(exports, "InMemoryAdapterCircuitBreaker", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.InMemoryAdapterCircuitBreaker; }
 });
 Object.defineProperty(exports, "MissingAdapterRegistrationError", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.MissingAdapterRegistrationError; }
+  get: function () { return chunkIF6NJORI_cjs.MissingAdapterRegistrationError; }
+});
+Object.defineProperty(exports, "assertAdapterCircuitBreakerConfig", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.assertAdapterCircuitBreakerConfig; }
 });
 Object.defineProperty(exports, "assertAdapterOutcomeConsistency", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.assertAdapterOutcomeConsistency; }
+  get: function () { return chunkIF6NJORI_cjs.assertAdapterOutcomeConsistency; }
 });
 Object.defineProperty(exports, "classifyAdapterOutcome", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.classifyAdapterOutcome; }
+  get: function () { return chunkIF6NJORI_cjs.classifyAdapterOutcome; }
+});
+Object.defineProperty(exports, "classifyCircuitBreakerOutcome", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.classifyCircuitBreakerOutcome; }
 });
 Object.defineProperty(exports, "executeWithAdapterRetry", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.executeWithAdapterRetry; }
+  get: function () { return chunkIF6NJORI_cjs.executeWithAdapterRetry; }
 });
 Object.defineProperty(exports, "getRetryDelayMs", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.getRetryDelayMs; }
+  get: function () { return chunkIF6NJORI_cjs.getRetryDelayMs; }
+});
+Object.defineProperty(exports, "isAdapterCircuitOpenError", {
+  enumerable: true,
+  get: function () { return chunkIF6NJORI_cjs.isAdapterCircuitOpenError; }
 });
 Object.defineProperty(exports, "resolveAdapterRetryPolicy", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.resolveAdapterRetryPolicy; }
+  get: function () { return chunkIF6NJORI_cjs.resolveAdapterRetryPolicy; }
 });
 Object.defineProperty(exports, "shouldRetryAdapterOutcome", {
   enumerable: true,
-  get: function () { return chunkXZQZQ5SW_cjs.shouldRetryAdapterOutcome; }
+  get: function () { return chunkIF6NJORI_cjs.shouldRetryAdapterOutcome; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map