@fabricorg/platform-host 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @fabricorg/platform-host
 
+## 1.0.0
+
+### Minor Changes
+
+- fdd3e69: Add provider-neutral external mutation footprints, delegated principals, enforceable obligations,
+  execution attestations, and reconciliation evidence with durable host-store support.
+- 714ad06: Add enforceable Fabric-family compatibility controls and durable runtime contract-version evidence.
+- 82aa9c8: Add parameter-aware execution-time authorization, opaque durable admission bindings, and an
+  application-bound PostgreSQL unit of work for atomic domain/event persistence and recoverable
+  after-adapter finalization.
+
+### Patch Changes
+
+- Updated dependencies [bc7d3ab]
+- Updated dependencies [fdd3e69]
+- Updated dependencies [714ad06]
+- Updated dependencies [43c5770]
+- Updated dependencies [986636b]
+  - @fabricorg/platform@0.10.0
+
+## 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.

package/README.md

@@ -3,9 +3,23 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.9.0 @fabricorg/platform-host@^0.6.0
+pnpm add @fabricorg/platform@^0.9.0 @fabricorg/platform-host@^0.7.0
 ```
 
+## AI agent integration boundary
+
+Application and vertical owners install this package. Hermes, Fabric Harness, and other external agent
+runtimes do not import Platform Host merely to call a deployed application. They connect to the
+application's authenticated REST or MCP gateway, discover only the actions allowed by their
+registration, and submit stable idempotent commands. The gateway derives tenant and actor identity and
+calls `submitAction()`; an agent must never call handlers, adapters, workflow internals, or database
+writes directly.
+
+See the [Platform Host 0.7 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.
+
 Vertical packages register `FabricModule` definitions. Host applications provide tenant authorization,
 module entitlements, persistence, projections, and an optional durable dispatcher. The package owns the
 ordering and lifecycle invariant:
@@ -36,6 +50,56 @@ 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.
+
+External gateways should persist a compact admission record bound to the tenant, registration, actor,
+action, canonical parameter hash, resource scope, and expiry, then pass its opaque non-secret identifier
+as `authorizationBindingId` to `submitAction()`. Credentials and signed principal proofs do not belong
+in action parameters or workflow history.
+
+## 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
@@ -107,7 +171,7 @@ explain which contract and provider adapter governed a mutation after dependenci
 const host = createGovernedActionHost({
   // ...
   runtimeEvidence: {
-    hostPackageVersion: "0.6.0",
+    hostPackageVersion: "0.7.0",
     policyRulesetVersion: "gtm-rules.v8",
     providerBridge: { name: "@fabric-harness/databricks", version: "1" },
   },

package/dist/index.cjs

@@ -5,13 +5,16 @@ var platform = require('@fabricorg/platform');
 // src/host.ts
 
 // src/types.ts
-var PLATFORM_HOST_CONTRACT_VERSION = 1;
+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);
@@ -52,7 +55,8 @@ function createGovernedActionHost(options) {
       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)) {
@@ -100,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,
@@ -109,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);
@@ -210,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 ?? []
@@ -294,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,
@@ -308,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));
       }
@@ -460,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);
@@ -474,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",
@@ -486,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));
     }
   }
@@ -550,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);
@@ -584,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),
@@ -598,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
       ),
@@ -607,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(
@@ -640,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;
@@ -866,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;
@@ -881,7 +971,8 @@ 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,
@@ -890,6 +981,7 @@ var PostgresPlatformHostStore = class {
 			);
 			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,
@@ -964,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,runtime_evidence,created_at,updated_at)
-				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15::jsonb,$16,$16)
+				  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 *`,
@@ -983,6 +1076,7 @@ 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
@@ -1346,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) } : {},