@fabricorg/platform-host 2.0.1 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @fabricorg/platform-host
 
+## 4.0.0
+
+### Major Changes
+
+- Make the capability runtime vertical-neutral and instance-scoped. Move experience and display
+  semantics into a namespaced companion package, require explicit host registries, replace privacy
+  field defaults with caller-owned policy, add PostgreSQL projection adapters, and generate executable
+  ProjectionHost read and PlatformHost mutation seams.
+
+### Patch Changes
+
+- Updated dependencies
+  - @fabricorg/platform@1.0.0
+
+## 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

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.11.0 @fabricorg/platform-host@^2.0.0
+pnpm add @fabricorg/platform@^1.0.0 @fabricorg/platform-host@^4.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 2.x agent integration
+See the [Platform Host 4.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.
@@ -32,8 +32,8 @@ Actor → ActionInvocation → Schema → Agent HITL → PolicyEvaluation → St
 worker entry point. With no dispatcher the host executes inline, which is intended for tests and local
 development only.
 
-Applications that assemble action catalogs per runtime can provide `resolveAction` instead of
-mutating the process-wide platform registry. A custom `extractEvents` implementation can pair with
+Applications construct a `createModuleRegistry()` per runtime and pass it as `registry`; a narrow
+`resolveAction` function remains available for adapters. No process-wide platform registry exists. A custom `extractEvents` implementation can pair with
 `eventResultFields` so its event carrier is removed from the durable invocation result. Domain events
 without an explicit `eventSchemaVersion` inherit the action version, while host lifecycle events stay
 at version 1. Emitted domain events must appear in the action's `emitsEvents` declaration. The
@@ -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,9 +64,24 @@ 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,
+  registry,
   authorization: {
     checkEntitlement,
     authorize: authorizeSubmission,
@@ -178,7 +199,7 @@ explain which contract and provider adapter governed a mutation after dependenci
 const host = createGovernedActionHost({
   // ...
   runtimeEvidence: {
-    hostPackageVersion: "2.0.1",
+    hostPackageVersion: "3.0.0",
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },