@fabricorg/platform-host 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @fabricorg/platform-host
 
+## 0.7.0 — 2026-07-27
+
+- Add parameter-aware execution authorization immediately before policies and mutation execution,
+  including approval resume and interrupted-work recovery.
+- Persist an opaque authorization binding with each invocation so applications can revalidate the
+  exact admission without retaining credentials or caller proofs.
+- Add an optional transaction-scoped mutation unit of work that commits domain writes and
+  before-adapter events atomically.
+- Atomically append `after_adapters` completion events with invocation completion when the store
+  provides the unit-of-work capability; finalization failures remain recoverable and do not repeat
+  succeeded adapter checkpoints.
+- Advance the durable Host lifecycle contract to version 2.
+
+## 0.6.0
+
+- Persist governance, Host, provider-bridge, package, and policy-ruleset generations with every new invocation.
+- Add PostgreSQL `runtime_evidence` migration and in-memory/PostgreSQL conformance coverage.
+- Run the shared external-mutation fixture used by the .NET parity suite.
+
 ## 0.5.1 — 2026-07-20
 
 - Include the audit-safe, redacted adapter input in execution-attestation extraction so integrations can identify external resources even when provider responses are minimal.

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.7.0 @fabricorg/platform-host@^0.4.1
+pnpm add @fabricorg/platform@^0.9.0 @fabricorg/platform-host@^0.7.0
 ```
 
 Vertical packages register `FabricModule` definitions. Host applications provide tenant authorization,
@@ -36,6 +36,51 @@ 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.
 
+## Execution authorization
+
+Submission authorization proves that a caller may create an invocation. Applications that delegate
+resource-scoped authority should also configure `authorizeExecution`. The Host calls it with the
+schema-parsed durable parameters, canonical invocation, opaque `authorizationBindingId`, and an
+`executionReason` of `initial`, `approval_resume`, or `recovery` immediately before policies and
+mutation code run.
+
+```ts
+const host = createGovernedActionHost({
+  store,
+  authorization: {
+    checkEntitlement,
+    authorize: authorizeSubmission,
+    authorizeExecution: async ({ invocation, parameters, executionReason }) =>
+      admissionStore.authorize({
+        admissionId: invocation.authorizationBindingId,
+        parameters,
+        executionReason,
+      }),
+  },
+});
+```
+
+When `authorizeExecution` is absent, the Host reuses `authorize` at the execution boundary. A
+completed idempotent replay returns its existing result without creating or executing a new
+mutation.
+
+## Atomic mutation unit of work
+
+Production stores can implement `AtomicMutationPlatformHostStore.transactionWithEvents`. The
+transaction-scoped `db`, event sequence, event append, event listing, and invocation update methods
+must all use the same database transaction.
+
+`PostgresPlatformHostStore` enables this capability when constructed with a
+`PostgresPlatformHostTransactionProvider`. The application owns that narrow binder because only the
+application knows how its `TDb` is rebound to the transaction's SQL client.
+
+- `before_adapters`: handler domain writes and declared domain events commit or roll back together.
+- `after_adapters`: completion events and invocation completion commit together. A finalization
+  failure leaves the invocation recoverable; succeeded adapter checkpoints are not repeated.
+
+Stores without this additive capability retain the legacy boundary for compatibility and must not
+claim atomic domain-write/event persistence.
+
 ## Agent HITL
 
 Hosts can inject a vertical-owned `hitlEvaluator`. It runs only for `actorType: "agent"`, after schema
@@ -98,6 +143,22 @@ The built-in stores persist footprints, delegation, obligations, attestations, a
 observations. Provider-specific authentication and clients do not belong here. For Databricks, use
 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.
+
+```ts
+const host = createGovernedActionHost({
+  // ...
+  runtimeEvidence: {
+    hostPackageVersion: "0.7.0",
+    policyRulesetVersion: "gtm-rules.v8",
+    providerBridge: { name: "@fabric-harness/databricks", version: "1" },
+  },
+});
+```
+
 `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()`.

package/dist/index.cjs

@@ -2,11 +2,19 @@
 
 var platform = require('@fabricorg/platform');
 
+// src/host.ts
+
+// src/types.ts
+var PLATFORM_HOST_CONTRACT_VERSION = 2;
+
 // src/host.ts
 var DEFAULT_EXTRACT_EVENTS = (data) => {
   const value = data._events;
   return Array.isArray(value) ? value : [];
 };
+var RecoverableFinalizationError = class extends Error {
+  name = "RecoverableFinalizationError";
+};
 function createGovernedActionHost(options) {
   const adapters = new platform.AdapterRegistry();
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
@@ -27,6 +35,12 @@ function createGovernedActionHost(options) {
     const actionInvocationId = platform.createFabricId("act");
     const correlationId = input.correlationId ?? platform.createFabricId("corr");
     const durableParameters = options.redactActionParameters ? options.redactActionParameters(input.actionId, input.parameters) : input.parameters;
+    const runtimeEvidence = {
+      governanceContractVersion: platform.FABRIC_GOVERNANCE_CONTRACT_VERSION,
+      hostContractVersion: PLATFORM_HOST_CONTRACT_VERSION,
+      ...options.runtimeEvidence
+    };
+    platform.assertGovernanceRuntimeEvidence(runtimeEvidence);
     const durableInvocation = await options.store.createActionInvocation({
       id: actionInvocationId,
       tenantId: input.tenantId,
@@ -38,9 +52,11 @@ function createGovernedActionHost(options) {
       status: "pending",
       parameters: durableParameters,
       result: {},
+      runtimeEvidence,
       correlationId,
       ...input.causationId ? { causationId: input.causationId } : {},
-      ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+      ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+      ...input.authorizationBindingId ? { authorizationBindingId: input.authorizationBindingId } : {}
     });
     const durableWorkflowId = `action-invocation-${durableInvocation.id}`;
     if (durableInvocation.id !== actionInvocationId && isTerminal(durableInvocation.status)) {
@@ -88,7 +104,7 @@ function createGovernedActionHost(options) {
     );
     return { ...executed, workflowId: durableWorkflowId };
   }
-  async function executeInvocation(actionInvocationId, tenantId, spaceId, executionOptions = {}) {
+  async function executeInvocation(actionInvocationId, tenantId, spaceId, executionOptions = {}, executionReasonOverride) {
     const loadedInvocation = await options.store.getActionInvocation(
       actionInvocationId,
       tenantId,
@@ -97,6 +113,7 @@ function createGovernedActionHost(options) {
     if (!loadedInvocation) {
       throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
     }
+    const resumingRunningInvocation = loadedInvocation.status === "running";
     let invocation = loadedInvocation;
     if (isTerminal(invocation.status) || invocation.status === "waiting_for_approval") {
       return actionResult(invocation);
@@ -198,6 +215,28 @@ function createGovernedActionHost(options) {
         }
       }
       const authorizationInput = toAuthorizationInput(action, invocation);
+      const executionReason = executionReasonOverride ?? (invocation.attemptCount > 1 || resumingRunningInvocation && invocation.attemptCount === 0 ? "recovery" : "initial");
+      if (!await options.authorization.checkEntitlement(authorizationInput)) {
+        return fail(
+          invocation,
+          "failed",
+          `Module "${action.namespace}" is no longer enabled for tenant ${tenantId}`
+        );
+      }
+      const executionAuthorized = options.authorization.authorizeExecution ? await options.authorization.authorizeExecution({
+        ...authorizationInput,
+        actionInvocationId,
+        parameters: parsed.data,
+        invocation,
+        executionReason
+      }) : await options.authorization.authorize(authorizationInput);
+      if (!executionAuthorized) {
+        return fail(
+          invocation,
+          "failed",
+          `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`
+        );
+      }
       const definitions = options.resolvePolicies ? await options.resolvePolicies({
         ...authorizationInput,
         declaredPolicyIds: action.policies ?? []
@@ -282,8 +321,8 @@ function createGovernedActionHost(options) {
       let data;
       let domainEvents = [];
       try {
-        const handlerResult = await options.store.transaction(
-          (db) => action.handler ? action.handler(
+        const runHandler = async (db, transaction) => {
+          const handlerResult = action.handler ? await action.handler(
             {
               actionInvocationId,
               tenantId,
@@ -296,28 +335,39 @@ function createGovernedActionHost(options) {
               services: options.services
             },
             parsed.data
-          ) : Promise.resolve({ success: true, data: {} })
-        );
-        if (!handlerResult.success) {
-          return fail(invocation, "failed", handlerResult.error ?? "Action handler failed");
-        }
-        data = handlerResult.data ?? {};
-        domainEvents = extractEvents(data);
-        const undeclaredEvent = domainEvents.find(
-          (event) => !action.emitsEvents.includes(event.eventType)
-        );
-        if (undeclaredEvent) {
-          return fail(
-            invocation,
-            "failed",
-            `${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`
+          ) : { success: true, data: {} };
+          if (!handlerResult.success) {
+            throw new Error(handlerResult.error ?? "Action handler failed");
+          }
+          const handlerData = handlerResult.data ?? {};
+          const events = extractEvents(handlerData);
+          const undeclaredEvent = events.find(
+            (event) => !action.emitsEvents.includes(event.eventType)
           );
-        }
-        if (action.eventPhase !== "after_adapters") {
-          for (const [index, event] of domainEvents.entries()) {
-            await appendEvent(invocation, event, `domain:${index}`, action.version);
+          if (undeclaredEvent) {
+            throw new Error(
+              `${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`
+            );
           }
-        }
+          if (action.eventPhase !== "after_adapters") {
+            for (const [index, event] of events.entries()) {
+              await appendEvent(
+                invocation,
+                event,
+                `domain:${index}`,
+                action.version,
+                transaction
+              );
+            }
+          }
+          return { data: handlerData, domainEvents: events };
+        };
+        const atomicStore = asAtomicMutationStore(options.store);
+        const executed = atomicStore ? await atomicStore.transactionWithEvents(
+          (transaction) => runHandler(transaction.db, transaction)
+        ) : await options.store.transaction((db) => runHandler(db));
+        data = executed.data;
+        domainEvents = executed.domainEvents;
       } catch (error) {
         return fail(invocation, "failed", errorMessage(error));
       }
@@ -448,11 +498,6 @@ function createGovernedActionHost(options) {
           return fail(invocation, "failed", message);
         }
       }
-      if (action.eventPhase === "after_adapters") {
-        for (const [index, event] of domainEvents.entries()) {
-          await appendEvent(invocation, event, `domain:${index}`, action.version);
-        }
-      }
       const governanceStore = asGovernanceStore(options.store);
       if (governanceStore && options.resolvePolicyObligations) {
         const obligations = await governanceStore.listPolicyObligations(actionInvocationId, tenantId, spaceId);
@@ -462,10 +507,43 @@ function createGovernedActionHost(options) {
         }
       }
       const result = withoutPrivateHostFields(data, eventResultFields);
-      await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
-        status: "completed",
-        result
-      });
+      try {
+        const atomicStore = asAtomicMutationStore(options.store);
+        if (action.eventPhase === "after_adapters" && atomicStore) {
+          await atomicStore.transactionWithEvents(async (transaction) => {
+            for (const [index, event] of domainEvents.entries()) {
+              await appendEvent(
+                invocation,
+                event,
+                `domain:${index}`,
+                action.version,
+                transaction
+              );
+            }
+            await transaction.updateActionInvocation(
+              actionInvocationId,
+              tenantId,
+              spaceId,
+              { status: "completed", result }
+            );
+          });
+        } else {
+          if (action.eventPhase === "after_adapters") {
+            for (const [index, event] of domainEvents.entries()) {
+              await appendEvent(invocation, event, `domain:${index}`, action.version);
+            }
+          }
+          await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
+            status: "completed",
+            result
+          });
+        }
+      } catch (error) {
+        if (action.eventPhase === "after_adapters") {
+          throw new RecoverableFinalizationError(errorMessage(error));
+        }
+        throw error;
+      }
       return {
         actionInvocationId,
         status: "completed",
@@ -474,6 +552,7 @@ function createGovernedActionHost(options) {
         ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
       };
     } catch (error) {
+      if (error instanceof RecoverableFinalizationError) throw error;
       return fail(invocation, "failed", errorMessage(error));
     }
   }
@@ -538,7 +617,13 @@ function createGovernedActionHost(options) {
       return actionResult(transitioned);
     }
     if (!decision.approved) return actionResult(transitioned);
-    return executeInvocation(actionInvocationId, tenantId, spaceId, { leaseOwner });
+    return executeInvocation(
+      actionInvocationId,
+      tenantId,
+      spaceId,
+      { leaseOwner },
+      "approval_resume"
+    );
   }
   async function recordExecutionAttestation(actionInvocationId, tenantId, spaceId, attestation, adapterInvocationId) {
     const governanceStore = asGovernanceStore(options.store);
@@ -572,7 +657,7 @@ function createGovernedActionHost(options) {
       spaceId
     });
   }
-  async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1) {
+  async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1, transaction) {
     const timestamp = now();
     const envelope = {
       id: lifecycleId("evt", invocation.id, deduplicationKey),
@@ -586,7 +671,7 @@ function createGovernedActionHost(options) {
       actorType: invocation.actorType,
       actionInvocationId: invocation.id,
       payload: event.payload,
-      sequence: await options.store.nextEventSequence(
+      sequence: await (transaction ?? options.store).nextEventSequence(
         invocation.tenantId,
         invocation.spaceId
       ),
@@ -595,7 +680,7 @@ function createGovernedActionHost(options) {
       correlationId: invocation.correlationId,
       ...invocation.causationId ? { causationId: invocation.causationId } : {}
     };
-    await options.store.appendEvent(envelope);
+    await (transaction ?? options.store).appendEvent(envelope);
   }
   async function fail(invocation, status, error) {
     await options.store.updateActionInvocation(
@@ -628,6 +713,10 @@ function asApprovalStore(store) {
   const candidate = store;
   return typeof candidate.recordHitlDecision === "function" && typeof candidate.beginApprovalDecision === "function" ? store : void 0;
 }
+function asAtomicMutationStore(store) {
+  const candidate = store;
+  return typeof candidate.transactionWithEvents === "function" ? store : void 0;
+}
 function asGovernanceStore(store) {
   const candidate = store;
   return typeof candidate.recordMutationGovernance === "function" && typeof candidate.appendPolicyObligations === "function" && typeof candidate.appendExecutionAttestation === "function" ? store : void 0;
@@ -854,13 +943,26 @@ var MemoryPlatformHostStore = class {
 };
 
 // src/postgres-store.ts
-var PostgresPlatformHostStore = class {
-  constructor(db, sql) {
+var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
+  constructor(db, sql, transactionProvider) {
     this.db = db;
     this.sql = sql;
+    if (transactionProvider) {
+      this.transactionWithEvents = async (run) => transactionProvider.run(async ({ db: db2, sql: sql2 }) => {
+        const scoped = new _PostgresPlatformHostStore(db2, sql2);
+        return run({
+          db: db2,
+          appendEvent: (event) => scoped.appendEvent(event),
+          nextEventSequence: (tenantId, spaceId) => scoped.nextEventSequence(tenantId, spaceId),
+          listEvents: (tenantId, spaceId) => scoped.listEvents(tenantId, spaceId),
+          updateActionInvocation: (id, tenantId, spaceId, patch) => scoped.updateActionInvocation(id, tenantId, spaceId, patch)
+        });
+      });
+    }
   }
   db;
   sql;
+  transactionWithEvents;
   async ensureSchema() {
     await this.sql.query(`
 			CREATE SCHEMA IF NOT EXISTS fabric_platform;
@@ -869,15 +971,17 @@ var PostgresPlatformHostStore = class {
 				action_id text NOT NULL, action_version integer NOT NULL,
 				actor_id text NOT NULL, actor_type text NOT NULL, status text NOT NULL,
 				parameters jsonb NOT NULL, result jsonb NOT NULL DEFAULT '{}'::jsonb,
-				correlation_id text NOT NULL, causation_id text, idempotency_key text, error text,
+				correlation_id text NOT NULL, causation_id text, idempotency_key text,
+				authorization_binding_id text, error text,
 				attempt_count integer NOT NULL DEFAULT 0, lease_owner text,
 				lease_expires_at timestamptz, hitl_route text, hitl_risk_tier text,
 				hitl_reason text, hitl_policy_version text, approval_decision jsonb,
-				mutation_footprint jsonb, execution_principal jsonb,
+				mutation_footprint jsonb, execution_principal jsonb, runtime_evidence jsonb,
 				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL
 			);
 			ALTER TABLE fabric_platform.action_invocations
 				ADD COLUMN IF NOT EXISTS idempotency_key text,
+				ADD COLUMN IF NOT EXISTS authorization_binding_id text,
 				ADD COLUMN IF NOT EXISTS attempt_count integer NOT NULL DEFAULT 0,
 				ADD COLUMN IF NOT EXISTS lease_owner text,
 				ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz,
@@ -887,7 +991,8 @@ var PostgresPlatformHostStore = class {
 				ADD COLUMN IF NOT EXISTS hitl_policy_version text,
 				ADD COLUMN IF NOT EXISTS approval_decision jsonb,
 				ADD COLUMN IF NOT EXISTS mutation_footprint jsonb,
-				ADD COLUMN IF NOT EXISTS execution_principal jsonb;
+				ADD COLUMN IF NOT EXISTS execution_principal jsonb,
+				ADD COLUMN IF NOT EXISTS runtime_evidence jsonb;
 			CREATE UNIQUE INDEX IF NOT EXISTS action_invocations_idempotency_idx
 				ON fabric_platform.action_invocations
 				(tenant_id, space_id, action_id, idempotency_key)
@@ -951,8 +1056,9 @@ var PostgresPlatformHostStore = class {
     const result = await this.sql.query(
       `INSERT INTO fabric_platform.action_invocations
 			 (id,tenant_id,space_id,action_id,action_version,actor_id,actor_type,status,
-			  parameters,result,correlation_id,causation_id,idempotency_key,error,created_at,updated_at)
-			 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$15)
+				  parameters,result,correlation_id,causation_id,idempotency_key,
+				  authorization_binding_id,error,runtime_evidence,created_at,updated_at)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$16::jsonb,$17,$17)
 			 ON CONFLICT (tenant_id,space_id,action_id,idempotency_key)
 			 WHERE idempotency_key IS NOT NULL DO UPDATE SET id=fabric_platform.action_invocations.id
 			 RETURNING *`,
@@ -970,7 +1076,9 @@ var PostgresPlatformHostStore = class {
         input.correlationId,
         input.causationId ?? null,
         input.idempotencyKey ?? null,
+        input.authorizationBindingId ?? null,
         input.error ?? null,
+        input.runtimeEvidence ? JSON.stringify(input.runtimeEvidence) : null,
         now
       ]
     );
@@ -1332,6 +1440,7 @@ function toActionRecord(row) {
     correlationId: String(row.correlation_id),
     ...row.causation_id ? { causationId: String(row.causation_id) } : {},
     ...row.idempotency_key ? { idempotencyKey: String(row.idempotency_key) } : {},
+    ...row.authorization_binding_id ? { authorizationBindingId: String(row.authorization_binding_id) } : {},
     attemptCount: Number(row.attempt_count ?? 0),
     ...row.lease_owner ? { leaseOwner: String(row.lease_owner) } : {},
     ...row.lease_expires_at ? { leaseExpiresAt: new Date(row.lease_expires_at) } : {},
@@ -1342,6 +1451,7 @@ function toActionRecord(row) {
     ...row.approval_decision ? { approvalDecision: toApprovalDecision(row.approval_decision) } : {},
     ...row.mutation_footprint ? { mutationFootprint: row.mutation_footprint } : {},
     ...row.execution_principal ? { executionPrincipal: row.execution_principal } : {},
+    ...row.runtime_evidence ? { runtimeEvidence: row.runtime_evidence } : {},
     ...row.error ? { error: String(row.error) } : {},
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at)
@@ -1476,6 +1586,7 @@ async function abortableDelay(milliseconds, signal) {
 }
 
 exports.MemoryPlatformHostStore = MemoryPlatformHostStore;
+exports.PLATFORM_HOST_CONTRACT_VERSION = PLATFORM_HOST_CONTRACT_VERSION;
 exports.PostgresPlatformHostStore = PostgresPlatformHostStore;
 exports.createGovernedActionHost = createGovernedActionHost;
 exports.createStoreBackedActionDispatcher = createStoreBackedActionDispatcher;