@fabricorg/platform-host 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @fabricorg/platform-host
 
+## 0.5.0 — 2026-07-20
+
+- Persist resolved mutation footprints and execution-principal delegation.
+- Persist and enforce policy obligations through external execution attestations.
+- Add append-safe external reconciliation evidence to memory and PostgreSQL stores.
+
+## 0.4.3 — 2026-07-20
+
+- Cast approval-resume leases to `timestamptz` for PostgreSQL and Lakebase SQL adapters.
+
 ## 0.4.2 — 2026-07-20
 
 - Reject handler-emitted domain events absent from the action's `emitsEvents` declaration.

package/README.md

@@ -86,6 +86,18 @@ and pass an opaque identifier instead; action parameters are intentionally durab
 Hosts should additionally configure `redactActionParameters` as a fail-safe allowlist for actions
 whose ingress is adjacent to secret material; redaction runs before the invocation row is created.
 
+## External mutation governance
+
+Hosts can configure `resolveMutationGovernance` to persist an approved, provider-neutral
+`MutationFootprint` and `ExecutionPrincipal` after schema validation. `resolvePolicyObligations`
+makes required controls durable. `extractExecutionAttestation` converts successful adapter output
+into audit-safe external evidence and can satisfy named obligations. Required obligations that are
+still pending or failed prevent completion.
+
+The built-in stores persist footprints, delegation, obligations, attestations, and reconciliation
+observations. Provider-specific authentication and clients do not belong here. For Databricks, use
+the optional Platform integration exported by `@fabric-harness/databricks`.
+
 `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

@@ -129,6 +129,23 @@ function createGovernedActionHost(options) {
         const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
         return fail(invocation, "validation_failed", message);
       }
+      if (options.resolveMutationGovernance && !invocation.mutationFootprint) {
+        const governanceStore2 = asGovernanceStore(options.store);
+        if (!governanceStore2) {
+          return fail(invocation, "failed", "The configured mutation-governance resolver requires a governance-capable store.");
+        }
+        const context = await options.resolveMutationGovernance({
+          actionInvocationId,
+          actionId: action.actionId,
+          tenantId,
+          spaceId,
+          actorId: invocation.actorId,
+          actorType: invocation.actorType,
+          parameters: parsed.data
+        });
+        platform.assertMutationGovernanceContext(context);
+        invocation = await governanceStore2.recordMutationGovernance(actionInvocationId, tenantId, spaceId, context);
+      }
       if (invocation.actorType === "agent" && options.hitlEvaluator) {
         const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
         const approvalStore = asApprovalStore(options.store);
@@ -219,6 +236,26 @@ function createGovernedActionHost(options) {
         }, `compliance:${aggregate.policyId}`);
         return fail(invocation, "blocked_by_policy", reason);
       }
+      if (options.resolvePolicyObligations) {
+        const governanceStore2 = asGovernanceStore(options.store);
+        if (!governanceStore2) {
+          return fail(invocation, "failed", "Policy obligations require a governance-capable store.");
+        }
+        const existing = await governanceStore2.listPolicyObligations(actionInvocationId, tenantId, spaceId);
+        if (existing.length === 0) {
+          const createdAt = now();
+          const obligations = await options.resolvePolicyObligations(outcomes);
+          await governanceStore2.appendPolicyObligations(obligations.map((obligation) => ({
+            ...obligation,
+            status: obligation.status ?? "pending",
+            actionInvocationId,
+            tenantId,
+            spaceId,
+            createdAt,
+            updatedAt: createdAt
+          })));
+        }
+      }
       const binding = action.stateMachine;
       if (binding) {
         const entityId = binding.getEntityId(parsed.data);
@@ -374,6 +411,21 @@ function createGovernedActionHost(options) {
             output,
             updatedAt: now()
           });
+          if (options.extractExecutionAttestation) {
+            const attestation = await options.extractExecutionAttestation({
+              actionInvocationId,
+              adapterInvocationId,
+              adapterType: step.adapterType,
+              operation: step.operation,
+              vendor: adapter.vendor,
+              startedAt,
+              completedAt: now(),
+              output
+            });
+            if (attestation) {
+              await recordExecutionAttestation(actionInvocationId, tenantId, spaceId, attestation, adapterInvocationId);
+            }
+          }
           await appendEvent(invocation, {
             eventType: "AdapterInvocationSucceeded",
             subjectType: adapterEventSubject.subjectType,
@@ -400,6 +452,14 @@ function createGovernedActionHost(options) {
           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);
+        const unsatisfied = obligations.filter((obligation) => (obligation.required ?? true) && obligation.status !== "satisfied" && obligation.status !== "waived");
+        if (unsatisfied.length > 0) {
+          return fail(invocation, "failed", `Unsatisfied policy obligations: ${unsatisfied.map((item) => item.id).join(", ")}`);
+        }
+      }
       const result = withoutPrivateHostFields(data, eventResultFields);
       await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
         status: "completed",
@@ -479,6 +539,38 @@ function createGovernedActionHost(options) {
     if (!decision.approved) return actionResult(transitioned);
     return executeInvocation(actionInvocationId, tenantId, spaceId, { leaseOwner });
   }
+  async function recordExecutionAttestation(actionInvocationId, tenantId, spaceId, attestation, adapterInvocationId) {
+    const governanceStore = asGovernanceStore(options.store);
+    if (!governanceStore) throw new Error("Execution attestations require a governance-capable store.");
+    const invocation = await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    const id = lifecycleId("att", actionInvocationId, adapterInvocationId ?? `${attestation.provider}:${attestation.operation}:${attestation.externalOperationId ?? "external"}`);
+    await governanceStore.appendExecutionAttestation({
+      ...attestation,
+      id,
+      actionInvocationId,
+      tenantId,
+      spaceId,
+      ...adapterInvocationId ? { adapterInvocationId } : {},
+      recordedAt: now()
+    });
+    for (const obligationId of attestation.satisfiesObligations ?? []) {
+      await governanceStore.updatePolicyObligation(actionInvocationId, obligationId, "satisfied", attestation.evidenceReferences);
+    }
+  }
+  async function recordExternalReconciliation(actionInvocationId, tenantId, spaceId, reconciliation) {
+    const governanceStore = asGovernanceStore(options.store);
+    if (!governanceStore) throw new Error("External reconciliation requires a governance-capable store.");
+    const invocation = await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    await governanceStore.appendExternalReconciliation({
+      ...reconciliation,
+      id: lifecycleId("rec", actionInvocationId, `${reconciliation.provider}:${reconciliation.attempt}`),
+      actionInvocationId,
+      tenantId,
+      spaceId
+    });
+  }
   async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1) {
     const timestamp = now();
     const envelope = {
@@ -519,7 +611,7 @@ function createGovernedActionHost(options) {
       ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
     };
   }
-  return { submitAction, executeInvocation, resumeApprovedInvocation };
+  return { submitAction, executeInvocation, resumeApprovedInvocation, recordExecutionAttestation, recordExternalReconciliation };
 }
 function actionResult(invocation) {
   return {
@@ -535,6 +627,10 @@ function asApprovalStore(store) {
   const candidate = store;
   return typeof candidate.recordHitlDecision === "function" && typeof candidate.beginApprovalDecision === "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;
+}
 function numberValue(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
@@ -597,6 +693,9 @@ var MemoryPlatformHostStore = class {
   policyEvaluations = [];
   adapterInvocations = [];
   events = [];
+  policyObligations = [];
+  executionAttestations = [];
+  externalReconciliations = [];
   async transaction(run) {
     return run(this.db);
   }
@@ -665,6 +764,40 @@ var MemoryPlatformHostStore = class {
     if (this.policyEvaluations.some((candidate) => candidate.id === record.id)) return;
     this.policyEvaluations.push(record);
   }
+  async recordMutationGovernance(actionInvocationId, tenantId, spaceId, context) {
+    const record = await this.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!record) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    record.mutationFootprint = context.footprint;
+    record.executionPrincipal = context.executionPrincipal;
+    record.updatedAt = /* @__PURE__ */ new Date();
+    return record;
+  }
+  async appendPolicyObligations(records) {
+    for (const record of records) {
+      if (!this.policyObligations.some((candidate) => candidate.actionInvocationId === record.actionInvocationId && candidate.id === record.id)) {
+        this.policyObligations.push(record);
+      }
+    }
+  }
+  async listPolicyObligations(actionInvocationId, tenantId, spaceId) {
+    return this.policyObligations.filter((record) => record.actionInvocationId === actionInvocationId && record.tenantId === tenantId && record.spaceId === spaceId);
+  }
+  async updatePolicyObligation(actionInvocationId, obligationId, status, evidenceReferences) {
+    const record = this.policyObligations.find((candidate) => candidate.actionInvocationId === actionInvocationId && candidate.id === obligationId);
+    if (!record) throw new Error(`Policy obligation not found: ${obligationId}`);
+    record.status = status;
+    if (evidenceReferences) record.evidenceReferences = evidenceReferences;
+    record.updatedAt = /* @__PURE__ */ new Date();
+  }
+  async appendExecutionAttestation(record) {
+    if (!this.executionAttestations.some((candidate) => candidate.id === record.id)) this.executionAttestations.push(record);
+  }
+  async listExecutionAttestations(actionInvocationId, tenantId, spaceId) {
+    return this.executionAttestations.filter((record) => record.actionInvocationId === actionInvocationId && record.tenantId === tenantId && record.spaceId === spaceId);
+  }
+  async appendExternalReconciliation(record) {
+    if (!this.externalReconciliations.some((candidate) => candidate.id === record.id)) this.externalReconciliations.push(record);
+  }
   async createAdapterInvocation(record) {
     if (this.adapterInvocations.some((candidate) => candidate.id === record.id)) return;
     this.adapterInvocations.push(record);
@@ -739,6 +872,7 @@ var PostgresPlatformHostStore = class {
 				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,
 				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL
 			);
 			ALTER TABLE fabric_platform.action_invocations
@@ -750,7 +884,9 @@ var PostgresPlatformHostStore = class {
 				ADD COLUMN IF NOT EXISTS hitl_risk_tier text,
 				ADD COLUMN IF NOT EXISTS hitl_reason text,
 				ADD COLUMN IF NOT EXISTS hitl_policy_version text,
-				ADD COLUMN IF NOT EXISTS approval_decision jsonb;
+				ADD COLUMN IF NOT EXISTS approval_decision jsonb,
+				ADD COLUMN IF NOT EXISTS mutation_footprint jsonb,
+				ADD COLUMN IF NOT EXISTS execution_principal jsonb;
 			CREATE UNIQUE INDEX IF NOT EXISTS action_invocations_idempotency_idx
 				ON fabric_platform.action_invocations
 				(tenant_id, space_id, action_id, idempotency_key)
@@ -769,6 +905,24 @@ var PostgresPlatformHostStore = class {
 				input jsonb NOT NULL, output jsonb, error text, attempt integer NOT NULL,
 				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL
 			);
+			CREATE TABLE IF NOT EXISTS fabric_platform.policy_obligations (
+				action_invocation_id text NOT NULL, id text NOT NULL,
+				tenant_id text NOT NULL, space_id text NOT NULL, type text NOT NULL,
+				status text NOT NULL, required boolean NOT NULL DEFAULT true,
+				description text, evidence_references jsonb, metadata jsonb,
+				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+				PRIMARY KEY (action_invocation_id,id)
+			);
+			CREATE TABLE IF NOT EXISTS fabric_platform.execution_attestations (
+				id text PRIMARY KEY, action_invocation_id text NOT NULL,
+				tenant_id text NOT NULL, space_id text NOT NULL, adapter_invocation_id text,
+				attestation jsonb NOT NULL, recorded_at timestamptz NOT NULL
+			);
+			CREATE TABLE IF NOT EXISTS fabric_platform.external_reconciliations (
+				id text PRIMARY KEY, action_invocation_id text NOT NULL,
+				tenant_id text NOT NULL, space_id text NOT NULL,
+				reconciliation jsonb NOT NULL
+			);
 			CREATE TABLE IF NOT EXISTS fabric_platform.event_sequences (
 				tenant_id text NOT NULL, space_id text NOT NULL, next_sequence bigint NOT NULL,
 				PRIMARY KEY (tenant_id, space_id)
@@ -880,7 +1034,7 @@ var PostgresPlatformHostStore = class {
 			 status=CASE WHEN $5::boolean THEN 'running' ELSE 'failed' END,
 			 error=CASE WHEN $5::boolean THEN NULL ELSE $6 END,
 			 lease_owner=CASE WHEN $5::boolean THEN $7 ELSE NULL END,
-			 lease_expires_at=CASE WHEN $5::boolean THEN $8 ELSE NULL END,
+			 lease_expires_at=CASE WHEN $5::boolean THEN $8::timestamptz ELSE NULL END,
 			 attempt_count=CASE WHEN $5::boolean THEN GREATEST(attempt_count,1) ELSE attempt_count END,
 			 updated_at=$9
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND status='waiting_for_approval'
@@ -914,6 +1068,80 @@ var PostgresPlatformHostStore = class {
       ]
     );
   }
+  async recordMutationGovernance(actionInvocationId, tenantId, spaceId, context) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.action_invocations SET mutation_footprint=$4::jsonb,
+			 execution_principal=$5::jsonb, updated_at=now()
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 RETURNING *`,
+      [actionInvocationId, tenantId, spaceId, JSON.stringify(context.footprint), JSON.stringify(context.executionPrincipal)]
+    );
+    if (!result.rows[0]) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    return toActionRecord(result.rows[0]);
+  }
+  async appendPolicyObligations(records) {
+    for (const record of records) {
+      await this.sql.query(
+        `INSERT INTO fabric_platform.policy_obligations
+				 (action_invocation_id,id,tenant_id,space_id,type,status,required,description,evidence_references,metadata,created_at,updated_at)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12)
+				 ON CONFLICT (action_invocation_id,id) DO NOTHING`,
+        [
+          record.actionInvocationId,
+          record.id,
+          record.tenantId,
+          record.spaceId,
+          record.type,
+          record.status,
+          record.required ?? true,
+          record.description ?? null,
+          record.evidenceReferences ? JSON.stringify(record.evidenceReferences) : null,
+          record.metadata ? JSON.stringify(record.metadata) : null,
+          record.createdAt,
+          record.updatedAt
+        ]
+      );
+    }
+  }
+  async listPolicyObligations(actionInvocationId, tenantId, spaceId) {
+    const result = await this.sql.query(
+      `SELECT * FROM fabric_platform.policy_obligations WHERE action_invocation_id=$1 AND tenant_id=$2 AND space_id=$3 ORDER BY created_at,id`,
+      [actionInvocationId, tenantId, spaceId]
+    );
+    return result.rows.map(toObligationRecord);
+  }
+  async updatePolicyObligation(actionInvocationId, obligationId, status, evidenceReferences) {
+    await this.sql.query(
+      `UPDATE fabric_platform.policy_obligations SET status=$3,
+			 evidence_references=COALESCE($4::jsonb,evidence_references), updated_at=now()
+			 WHERE action_invocation_id=$1 AND id=$2`,
+      [actionInvocationId, obligationId, status, evidenceReferences ? JSON.stringify(evidenceReferences) : null]
+    );
+  }
+  async appendExecutionAttestation(record) {
+    const { id, actionInvocationId, tenantId, spaceId, adapterInvocationId, recordedAt, ...attestation } = record;
+    await this.sql.query(
+      `INSERT INTO fabric_platform.execution_attestations
+			 (id,action_invocation_id,tenant_id,space_id,adapter_invocation_id,attestation,recorded_at)
+			 VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7) ON CONFLICT (id) DO NOTHING`,
+      [id, actionInvocationId, tenantId, spaceId, adapterInvocationId ?? null, JSON.stringify(attestation), recordedAt]
+    );
+  }
+  async listExecutionAttestations(actionInvocationId, tenantId, spaceId) {
+    const result = await this.sql.query(
+      `SELECT * FROM fabric_platform.execution_attestations WHERE action_invocation_id=$1 AND tenant_id=$2 AND space_id=$3 ORDER BY recorded_at,id`,
+      [actionInvocationId, tenantId, spaceId]
+    );
+    return result.rows.map(toAttestationRecord);
+  }
+  async appendExternalReconciliation(record) {
+    const { id, actionInvocationId, tenantId, spaceId, ...reconciliation } = record;
+    await this.sql.query(
+      `INSERT INTO fabric_platform.external_reconciliations
+			 (id,action_invocation_id,tenant_id,space_id,reconciliation)
+			 VALUES ($1,$2,$3,$4,$5::jsonb) ON CONFLICT (id) DO NOTHING`,
+      [id, actionInvocationId, tenantId, spaceId, JSON.stringify(reconciliation)]
+    );
+  }
   async createAdapterInvocation(record) {
     await this.sql.query(
       `INSERT INTO fabric_platform.adapter_invocations
@@ -1111,11 +1339,41 @@ function toActionRecord(row) {
     ...row.hitl_reason ? { hitlReason: String(row.hitl_reason) } : {},
     ...row.hitl_policy_version ? { hitlPolicyVersion: String(row.hitl_policy_version) } : {},
     ...row.approval_decision ? { approvalDecision: toApprovalDecision(row.approval_decision) } : {},
+    ...row.mutation_footprint ? { mutationFootprint: row.mutation_footprint } : {},
+    ...row.execution_principal ? { executionPrincipal: row.execution_principal } : {},
     ...row.error ? { error: String(row.error) } : {},
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at)
   };
 }
+function toObligationRecord(row) {
+  return {
+    id: String(row.id),
+    actionInvocationId: String(row.action_invocation_id),
+    tenantId: String(row.tenant_id),
+    spaceId: String(row.space_id),
+    type: String(row.type),
+    status: String(row.status),
+    required: Boolean(row.required),
+    ...row.description ? { description: String(row.description) } : {},
+    ...row.evidence_references ? { evidenceReferences: row.evidence_references } : {},
+    ...row.metadata ? { metadata: row.metadata } : {},
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at)
+  };
+}
+function toAttestationRecord(row) {
+  const attestation = row.attestation;
+  return {
+    ...attestation,
+    id: String(row.id),
+    actionInvocationId: String(row.action_invocation_id),
+    tenantId: String(row.tenant_id),
+    spaceId: String(row.space_id),
+    ...row.adapter_invocation_id ? { adapterInvocationId: String(row.adapter_invocation_id) } : {},
+    recordedAt: new Date(row.recorded_at)
+  };
+}
 function toApprovalDecision(value) {
   const decision = value;
   return {