@fabricorg/platform-host 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,9 +1,43 @@
 # @fabricorg/platform-host
 
+## 3.0.0
+
+### Major Changes
+
+- Deliver Phase 1 correctness and contracts: payload-bound idempotency with staged enforcement,
+  capture/replay authority evidence, bounded invocation provenance, capability execution and view usage
+  semantics, event-schema compatibility classification, and deterministic conformance plans.
+- Default payload-bound conflicts to enforcement in Host 3 and return existing nonterminal invocations
+  without redispatch; dispatcher deployments must use the documented store-backed recovery worker.
+
+### Patch Changes
+
+- Updated dependencies
+  - @fabricorg/platform@0.12.0
+
+## 2.0.1
+
+### Patch Changes
+
+- Close final uplift audit gaps: align Host 2.x documentation and migration evidence, surface every
+  compiler/generator API to LLM consumers, make memory outbox egress directly usable, sanitize relay
+  failures, validate complete archetype state maps, support recursive JSON Schema generation, reject
+  cross-platform path traversal, synchronize artifact version stamps, and include package licenses.
+- Require explicit domain snapshot/restore support before memory stores advertise atomic outbox
+  transactions, buffer Host lifecycle commits until success, fail missing transaction capabilities
+  before handlers run, sanitize relay failures, and exclude sensitive Host lifecycle events from bus
+  egress by default.
+- Prevalidate buffered memory transactions so failed commits cannot append partial event or outbox rows.
+- Qualify result-validation rollback documentation by the configured domain transaction provider.
+- Updated dependencies
+  - @fabricorg/platform@0.11.1
+
 ## 2.0.0
 
-### Minor Changes
+### Major Changes
 
+- Require `@fabricorg/platform@^0.11.0` and its manifest v2/result-schema contract. Applications
+  upgrading from Host 1.x must upgrade Platform in the same deployment and regenerate manifest consumers.
 - Add the optional durable event outbox, PostgreSQL and memory adapters, and at-least-once relay.
 - Add manifest v2 typed entity contracts, v1 reader normalization, optional action result schemas, and
   Host enforcement of result validation before events and adapters.
@@ -14,13 +48,6 @@
 - Updated dependencies
   - @fabricorg/platform@0.11.0
 
-## Unreleased
-
-- Validate optional action result schemas immediately after handler execution and before events or
-  adapters. Invalid results roll back the handler transaction and persist a sanitized failure.
-- Add optional memory and PostgreSQL outbox capabilities with atomic canonical-event records,
-  lease-based at-least-once relay, retry, replay, and dead-letter state.
-
 ## 1.0.0
 
 ### Minor Changes

package/MIGRATION-2-IDEMPOTENCY.md

@@ -0,0 +1,32 @@
+# Payload-bound idempotency rollout
+
+`ensureSchema()` adds nullable parameter-digest, actor/binding, provenance, authority, and reconciliation
+columns. Existing rows remain valid. New idempotent submissions always record
+`fabric-canonical-json-sha256-v1`.
+
+1. Before adopting Host 3's enforcement default, deploy with `conflictMode: "audit-only"` and capture `onConflict`/`onLegacyRecord` metrics.
+2. Soak until modified-payload key reuse has been removed from callers.
+3. Opt selected applications into `conflictMode: "enforce"`; the same key with different command
+   identity now throws `IDEMPOTENCY_CONFLICT`.
+4. Remove the override after upgrading to Host 3; enforcement is its default.
+
+Rollback to audit-only is configuration-only. Do not drop digest columns during rollback; they are
+additive evidence and permit enforcement to resume without rebuilding history. Legacy null-digest rows
+continue old-key payload recovery because their original payload identity cannot be reconstructed safely.
+Host 3 still rejects actor, authority-binding, and action-version conflicts for those rows; review these
+identities during the audit-only soak before enabling enforcement.
+
+The additive `reconciliation_required` action status is terminal in Phase 1 and requires an operator-
+owned reconciliation path; exhaustive `ActionStatus` consumers must handle it. Custom stores must
+persist the widened invocation fields, including `parameterDigest`, actor/authority binding, provenance,
+and `authorizationReconciliation`. A store that drops them cannot claim payload-bound enforcement or
+durable reconciliation evidence.
+
+An action-version change is part of command identity. A retry using a key first recorded under a prior
+action version is reported in audit-only mode and rejected in enforce mode; drain or retain the prior
+action version for the retry window before deploying a breaking action revision.
+
+Duplicate submission now returns an existing nonterminal invocation without redispatching it, which
+prevents concurrent callers from driving the same mutation twice. Production asynchronous deployments
+must run the store-backed worker/recovery loop; a dispatcher-only deployment cannot use client retry as
+recovery for a crash between durable creation and dispatch.

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.10.0 @fabricorg/platform-host@^1.0.0
+pnpm add @fabricorg/platform@^0.12.0 @fabricorg/platform-host@^3.0.0
 ```
 
 ## AI agent integration boundary
@@ -15,7 +15,7 @@ registration, and submit stable idempotent commands. The gateway derives tenant
 calls `submitAction()`; an agent must never call handlers, adapters, workflow internals, or database
 writes directly.
 
-See the [Platform Host 1.0 agent integration
+See the [Platform Host 3.x agent integration
 guide](https://platform.fabric.pro/docs/platform/reference/platform-host) for application wiring,
 execution-time authorization, the PostgreSQL transaction binder, recovery semantics, and the external
 gateway contract.
@@ -45,6 +45,12 @@ bounded batches with an atomic lease and `FOR UPDATE SKIP LOCKED`, and an expire
 recoverable after interruption. Pass a stable `idempotencyKey` to `submitAction()` so retries resolve
 to the original tenant-scoped invocation instead of creating another mutation.
 
+New rows bind that key to the action version, actor/authority binding, and a versioned canonical
+parameter digest. Host 3 defaults to `enforce`, which throws `IdempotencyConflictError`; configure
+`idempotency.conflictMode` as `audit-only` for a preflight soak. Legacy null-digest rows skip only the
+parameter comparison and call `onLegacyRecord`; actor, authority-binding, and action-version mismatches
+still reject in enforce mode. See `MIGRATION-2-IDEMPOTENCY.md`.
+
 Lifecycle records use deterministic checkpoint ids. Recovered idempotent actions do not repeat an
 adapter that already reached `succeeded`, and event, policy, and adapter writes are append-safe. A
 stale action that was not declared idempotent fails terminally for manual reconciliation instead of
@@ -58,6 +64,20 @@ schema-parsed durable parameters, canonical invocation, opaque `authorizationBin
 `executionReason` of `initial`, `approval_resume`, or `recovery` immediately before policies and
 mutation code run.
 
+`offline_replay` is the extensible evidence value for disconnected commands. Actions with execution
+semantics can declare whether capture, execution, or both govern authority. A denied governed replay
+returns structured `reconciliation_required` evidence.
+
+For `execution` and `both`, the Host rejects an expired `AuthorizationBinding` before calling mutation
+code and returns `authorization_expired` reconciliation evidence. `resourceScope` remains an opaque,
+audit-safe scope identifier; the application-owned `authorizeExecution` implementation resolves and
+checks it against current resource state.
+
+`InvocationProvenance` carries namespaced trace and audit attributes. Durable audit attributes fail
+closed when no allowlist is configured, pass through `redactAuditAttributes`, and remain bounded.
+Trace attributes go only to the configured trace callback. Restricted outbox payloads omit provenance
+by default; `outbox.includeProvenance` is the explicit classification-aware override.
+
 ```ts
 const host = createGovernedActionHost({
   store,
@@ -101,10 +121,11 @@ Stores without this additive capability retain the legacy boundary for compatibi
 claim atomic domain-write/event persistence.
 
 Actions can optionally declare `resultSchema`. The Host validates public handler result data after
-the handler and before canonical event append or adapter execution. Invalid results roll back the
-handler transaction, emit no domain/completion event, invoke no adapter, and persist only a sanitized
-validation failure. This validates the handler result contract; it does not observe arbitrary writes
-through an application-owned `TDb`.
+the handler and before canonical event append or adapter execution. Invalid results fail the invocation,
+emit no domain/completion event, invoke no adapter, and persist only a sanitized validation failure.
+Domain writes roll back only when the configured store transaction provider includes those writes.
+This validates the handler result contract; it does not observe arbitrary writes through an
+application-owned `TDb`.
 
 ## Agent HITL
 
@@ -177,7 +198,7 @@ explain which contract and provider adapter governed a mutation after dependenci
 const host = createGovernedActionHost({
   // ...
   runtimeEvidence: {
-    hostPackageVersion: "1.0.0",
+    hostPackageVersion: "3.0.0",
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },
@@ -196,3 +217,11 @@ the proven event transaction. `runOutboxRelayCycle()` leases and publishes recor
 and dead-letter handling. Delivery is at least once: consumers deduplicate on immutable
 `eventId`. Payload classification is metadata, not a redaction mechanism; event payloads must
 already be audit-safe.
+
+Adapter and compliance lifecycle events remain canonical but are excluded from bus egress by default.
+Use `shouldPublish` to opt them in only when the application has made their payloads safe for that bus.
+
+For deterministic local tests, `MemoryPlatformHostStore` enables governed Host outbox egress only
+when its constructor receives a `MemoryPlatformHostTransactionProvider` with domain `snapshot` and
+`restore` functions. Without that explicit rollback seam, `transactionalOutbox` is false and Host
+construction rejects outbox configuration. PostgreSQL remains the production implementation.