@fabricorg/platform-host 5.0.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @fabricorg/platform-host
 
+## 6.0.0
+
+### Major Changes
+
+- fb14d67: Add versioned PostgreSQL migrations and live PostgreSQL 16 certification. Fence and renew invocation
+  and outbox leases, bound publisher calls, reject stale finalization, and add deterministic Temporal
+  saga workflow binding with explicit parent lifecycle activities.
+
+### Minor Changes
+
+- ef4e3eb: Classify adapter outcomes: add additive `AdapterOutcomeKind` (`success`, `transient_failure`,
+  `permanent_failure`, `timeout`, `ambiguous`) and `AdapterOutcomeEvidence` to the portable adapter
+  contract. The retry layer now retries only transient idempotent outcomes; permanent failures,
+  timeouts, and ambiguous results are never retried. Ambiguous outcomes are routed to
+  `reconciliation_required` with durable `ExternalReconciliation` evidence and an
+  `AdapterInvocationAmbiguous` lifecycle event. Add deadline and cancellation context to
+  `AdapterExecutionContext`. Backward compatible: adapters that omit `outcome` behave as before.
+- 293561d: Close adapter and saga correctness gaps: deliver actual deadline and AbortSignal context to adapters, require the governed Host to classify thrown adapter failures before retrying, reject contradictory successful ambiguous outcomes, reserve parent lifecycle identity prefixes, and provide a durable Platform Host parent lifecycle adapter tested through public store seams.
+- 9a145a3: Add assembly and initiating SDUI release digests to durable governance runtime
+  evidence. Hosts can attach both through trusted configuration, including a
+  per-submission release resolver, and validate digest shape before creating the
+  invocation. Composition-bound hosts verify their assembly lockfile against the
+  exact loaded capability artifacts before accepting submissions.
+- 4e585a4: Close final production-maturity correctness gaps: expired leases can no longer be renewed,
+  saga parent transitions are serialized, atomic, terminal-safe, and retry-idempotent by lifecycle identity, hydrated
+  projections must meet requested checkpoints, and SDUI releases accept components only from
+  resolved document packs. The release gate now verifies every package and public subpath in
+  isolated ESM, CommonJS, and TypeScript consumers.
+- 12ffe62: Add vendor-neutral lifecycle telemetry and tenant-safe health/readiness snapshots for workers,
+  leases, outbox delivery, reconciliation-required work, and approval waits. Health output contains
+  aggregate counts only and does not expose invocation parameters or secrets.
+- fb14d67: Execute state guards with trusted Host context, correct filtered-ledger replay semantics, make
+  dispatcher failure retryable, fail closed for unsafe saga and non-idempotent recovery paths, preserve
+  outbox consistency, and bound and redact OPA HTTP failures.
+- 5b6ccd5: Certification evidence now invokes real public Host/store/worker/outbox APIs instead of toy simulations. Fault and load certification exercises `createGovernedActionHost`, `MemoryPlatformHostStore`, `runPlatformActionWorkerCycle`, and `runOutboxRelayCycle` through their public seams. The machine-readable report includes a `pendingGates` section that distinguishes local passes from required external evidence. Publish and verify scripts include `@fabricorg/assembly` and `@fabricorg/sdui-release` in dependency-safe order. A new `pnpm verify:packed` script packs all public packages and installs them into clean ESM and CommonJS consumers using only declared dependencies.
+
+### Patch Changes
+
+- Updated dependencies [62dd1ca]
+  - @fabricorg/assembly@0.2.0
+
+### Additional release notes
+
+### Major Changes
+
+- Add checksummed forward-only PostgreSQL migrations, live PostgreSQL 16 CI certification, renewable
+  fenced invocation and outbox leases, transaction-scoped fenced finalization, and bounded outbox
+  publishing. Recoverable stores now implement lease renewal and fenced update operations, and
+  dispatch inputs include the action ID required for deterministic workflow binding. Host also
+  declares `@fabricorg/assembly` as a peer used to verify composition-bound module artifacts; see
+  `MIGRATION-6-PRODUCTION.md`.
+
+### Minor Changes
+
+- Add vendor-neutral lifecycle telemetry and tenant-safe health/readiness snapshots for workers,
+  invocation and outbox leases, backlog, dead letters, reconciliation-required work, and approval
+  waits. Health output contains aggregate counts only and reports unavailable sources as unhealthy.
+- Classify adapter outcomes: route ambiguous adapter results to `reconciliation_required` with
+  durable `ExternalReconciliation` evidence and an `AdapterInvocationAmbiguous` lifecycle event.
+  Permanent failures and timeouts are not retried. Add `adapter_reconciliation` column to the
+  PostgreSQL action invocations table.
+- Deliver actual deadline and `AbortSignal` context to adapters via `adapterDeadlineMs` host option.
+  The governed Host explicitly classifies thrown adapter failures before retrying (`classifyThrownError`).
+  Reject contradictory successful ambiguous outcomes via `assertAdapterOutcomeConsistency`.
+- Add `createDurableSagaParentLifecycle` adapter: a Platform Host store-backed implementation of
+  the saga parent lifecycle contract (progress, approval, cancellation, completion, failure) that
+  survives worker rollover through durable store seams.
+- Refuse invocation and outbox lease renewal after expiry. Make saga parent lifecycle events and
+  parent status transitions atomic, idempotent by stable lifecycle identity, and contradictory-evidence
+  safe. Serialize concurrent transitions with a transaction-scoped parent lock and prevent distinct
+  transitions from rewriting terminal parent state.
+- Evaluate state-machine guards with authoritative state and trusted context inside the mutation
+  unit of work, with an optional transaction-scoped state reader for custom stores.
+- Keep failed dispatcher submissions pending and allow idempotent resubmission to retry the stable
+  workflow ID.
+- Fail closed for direct saga execution and interrupted inline non-idempotent actions.
+- Workers no longer claim unleased `running` rows created by inline execution, saga lifecycle retries
+  use an identity-scoped event lookup while holding the parent lock, and completed adapters clear
+  their deadline timers.
+- Preserve provisional consistency when PostgreSQL outbox rows are hydrated.
+- Persist verified assembly and initiating promoted-release digests with every
+  composition-bound invocation. Registry module artifacts are checked against
+  the approved lockfile before Host accepts submissions.
+
 ## 5.0.0
 
 ### Major Changes

package/MIGRATION-6-PRODUCTION.md

@@ -0,0 +1,59 @@
+# Migrating `@fabricorg/platform-host` 5.x to 6.x
+
+Host 6 makes production recovery fencing explicit and adds optional,
+assembly-verified runtime composition.
+
+## Install the composition peer
+
+Host now imports `@fabricorg/assembly` for lockfile and runtime artifact
+verification. Install a compatible release beside Host:
+
+```sh
+pnpm add @fabricorg/platform-host@^6 @fabricorg/assembly@^0.3 @fabricorg/platform@^1.2
+```
+
+## Update recoverable stores and dispatchers
+
+- Implement the new invocation and outbox lease-renewal and fenced-update
+  methods on custom recoverable stores.
+- Implement `getEvent()` on custom atomic mutation transactions so saga
+  lifecycle retries perform an identity-scoped lookup instead of scanning the
+  tenant event ledger.
+- Preserve monotonic lease tokens and reject writes from expired or superseded
+  claims.
+- Include `actionId` in custom dispatcher inputs so workflow identity remains
+  deterministic.
+- Run `PostgresPlatformHostStore.ensureSchema()` through your controlled
+  migration process before starting Host 6 workers.
+- Treat applied migration checksums as immutable. Add a new migration version
+  for every schema change instead of editing the version 1 baseline.
+
+Memory and PostgreSQL adapters included with Host already satisfy these
+contracts.
+
+## Opt into verified composition
+
+Existing hosts can omit `composition`. To bind runtime execution to an approved
+application assembly:
+
+1. Set `version` and `manifestDigest` on every registered `FabricModule`.
+2. Pass the integrity-checked `AssemblyLockfile` through `composition.assembly`.
+3. Resolve an initiating promoted release digest from trusted gateway or release
+   registry context, never from action parameters.
+
+```ts
+const host = createGovernedActionHost({
+  registry,
+  store,
+  authorization,
+  composition: {
+    assembly,
+    resolveInitiatingReleaseDigest: (submission) =>
+      releaseRegistry.resolveTrustedDigest(submission.provenance),
+  },
+});
+```
+
+Host refuses to start when a registered module's namespace, version, or
+compiler manifest digest differs from the approved lockfile. Resolver failures
+and invalid release digests fail before durable invocation creation.

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^1.0.0 @fabricorg/platform-host@^4.0.0
+pnpm add @fabricorg/platform@^1.2.0 @fabricorg/platform-host@^6.0.0 @fabricorg/assembly@^0.3.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 4.x agent integration
+See the [Platform Host 6.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.
@@ -41,8 +41,10 @@ injected `now` clock is also passed to ordinary policy evaluation.
 
 Production polling workers can use `createStoreBackedActionDispatcher()` plus
 `runPlatformActionWorker()`. The pending invocation row is the durable queue item; workers claim
-bounded batches with an atomic lease and `FOR UPDATE SKIP LOCKED`, and an expired `running` lease is
-recoverable after interruption. Pass a stable `idempotencyKey` to `submitAction()` so retries resolve
+bounded batches with an atomic, renewable lease and `FOR UPDATE SKIP LOCKED`. Every claim advances a
+fencing token. A heartbeat may renew only a lease that has not expired; after expiry, the work must be
+reclaimed so its token advances. An expired worker cannot finalize after another worker takes ownership. 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
@@ -56,6 +58,13 @@ adapter that already reached `succeeded`, and event, policy, and adapter writes
 stale action that was not declared idempotent fails terminally for manual reconciliation instead of
 silently rerunning unknown side effects.
 
+Adapters may classify outcomes as `success`, `transient_failure`, `permanent_failure`, `timeout`,
+or `ambiguous`. The retry layer retries only transient idempotent outcomes; permanent failures,
+timeouts, and ambiguous results are never retried. An ambiguous outcome — where the external effect
+may or may not have been applied — is routed to `reconciliation_required` with durable
+`ExternalReconciliation` evidence and an `AdapterInvocationAmbiguous` lifecycle event rather than
+blindly retrying an unsafe effect.
+
 ## Execution authorization
 
 Submission authorization proves that a caller may create an invocation. Applications that delegate
@@ -121,6 +130,13 @@ application knows how its `TDb` is rebound to the transaction's SQL client.
 Stores without this additive capability retain the legacy boundary for compatibility and must not
 claim atomic domain-write/event persistence.
 
+`createDurableSagaParentLifecycle()` requires this capability. Each parent lifecycle transition uses a
+stable `lifecycleId` as its causation identity, appends its audit event, and updates the parent invocation
+in the same transaction. The transaction locks the parent invocation row before checking prior
+evidence, so concurrent transitions serialize. Retrying the same identity and evidence is a no-op;
+reusing it with contradictory evidence fails closed, and a distinct transition cannot rewrite a
+terminal parent. `createSagaParentActivities()` supplies deterministic identities for Temporal callers.
+
 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 fail the invocation,
 emit no domain/completion event, invoke no adapter, and persist only a sanitized validation failure.
@@ -191,9 +207,18 @@ observations. Provider-specific authentication and clients do not belong here. F
 the optional Platform integration exported by `@fabric-harness/databricks`.
 
 Every newly submitted invocation also records `runtimeEvidence`. The host always supplies the
-portable governance and host contract generations; applications should add the deployed host
-package version, policy ruleset version, and provider bridge identity. This makes an audit record
-explain which contract and provider adapter governed a mutation after dependencies have moved on.
+portable governance and host contract generations; applications should add the
+deployed host package version, policy ruleset version, and provider bridge
+identity. A trusted `composition` configuration attaches the verified assembly
+digest and can resolve the promoted SDUI release that initiated each submission.
+Neither identity is accepted directly from caller input. This makes an audit
+record explain which composition, release, contract, and provider adapter
+governed a mutation after dependencies have moved on.
+
+Composition-bound hosts require an explicit module registry. Every registered
+module must carry its published `version` and compiler `manifestDigest`; Host
+compares those identities directly with the integrity-checked assembly lockfile
+before accepting any submission.
 
 ```ts
 const host = createGovernedActionHost({
@@ -203,19 +228,72 @@ const host = createGovernedActionHost({
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },
+  composition: {
+    assembly: assemblyLockfile,
+    resolveInitiatingReleaseDigest: (submission) =>
+      releaseRegistry.resolveTrustedDigest(submission.provenance),
+  },
 });
 ```
 
 `MemoryPlatformHostStore` is for tests and local demos. Production control planes use
-`PostgresPlatformHostStore` with Databricks Lakebase (or standard Postgres), call
-`ensureSchema()` at startup, and hydrate projections from `listEvents()`.
+`PostgresPlatformHostStore` with Databricks Lakebase (or standard Postgres), run `ensureSchema()` in a
+controlled deployment migration step, and hydrate projections from `listEvents()`. `ensureSchema()`
+uses ordered immutable checksums, a migration ledger, and a transaction-scoped advisory lock. It
+remains safe to call at startup, but deployment-owned migrations are preferred.
+
+State-machine transition checks run inside the Host mutation unit of work. Transaction-capable
+stores should expose transaction-scoped `getEntityState()` so the guard reads the same database
+snapshot used by the handler and event append. Existing custom stores without that optional
+transaction method fall back to the store-level authoritative read.
+
+## Runtime observability and health
+
+Platform Host exposes vendor-neutral lifecycle telemetry through the optional `telemetry` sink on
+`createGovernedActionHost()`, `runPlatformActionWorkerCycle()`, and `runOutboxRelayCycle()`. A sink can
+be a callback or `{ record }`; it receives stable event and metric names from
+`PLATFORM_HOST_METRIC_NAMES`. Telemetry is best effort and never changes mutation or checkpoint
+behavior.
+
+```ts
+import {
+  getPlatformHostHealthSnapshot,
+  PLATFORM_HOST_METRIC_NAMES,
+} from "@fabricorg/platform-host";
+
+const health = await getPlatformHostHealthSnapshot({
+  store,
+  tenantId,
+  spaceId,
+  workers: [{ lastHeartbeatAt, staleAfterMs: 30_000 }],
+  telemetry: (record) => { metrics.record(record); },
+});
+```
+
+The snapshot contains only scoped aggregate counts for invocation backlog, running and expired
+leases, approval waits, reconciliation-required work, outbox backlog, expired leases, and dead
+letters. It never returns invocation parameters, results, actor data, payloads, or errors. An
+unavailable health source is reported as `unhealthy` and not ready; stale workers and operational
+lease/dead-letter/reconciliation findings are represented by readiness reason codes.
+
+Dispatcher submission failures leave the durable invocation `pending`. Re-submit the same
+idempotency key to retry the stable workflow ID, or use a store-backed worker. The Host never marks
+a logical mutation failed merely because a queue or workflow service was temporarily unavailable.
+
+Saga actions require a durable workflow dispatcher and a worker-side `SagaImplementation` mapping.
+Calling `executeInvocation()` for a saga through the atomic Host path fails closed. Interrupted
+inline actions that are not declared idempotent also fail closed and require manual reconciliation.
+
+CI certifies concurrent migrations, command idempotency, and schema behavior against PostgreSQL 16.
+Lakebase failover, backup, and restore remain adopter certification gates and are not implied by the
+PostgreSQL CI result.
 
 ## Durable outbox egress
 
 Configure `outbox` on `createGovernedActionHost()` only with an `OutboxPlatformHostStore`.
 The Host then uses `appendEventWithOutbox` so the canonical event and delivery record share
-the proven event transaction. `runOutboxRelayCycle()` leases and publishes records with retry
-and dead-letter handling. Delivery is at least once: consumers deduplicate on immutable
+the proven event transaction. `runOutboxRelayCycle()` uses renewable fenced leases, a bounded
+publisher deadline, retry, 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.