@fabricorg/platform-host 4.0.0 → 5.0.0

package/dist/index.d.cts

@@ -213,6 +213,8 @@ interface EnterpriseEventEnvelope {
         source: InvocationSource;
         auditAttributes?: NamespacedAttributes;
     };
+    /** Present only for events an action declaring provisional consistency emitted. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     payload: unknown;
 }
 interface OutboxRecord {
@@ -393,6 +395,8 @@ interface SubmitActionResult {
     result?: Record<string, unknown>;
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
+    /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
     hitlRiskTier?: AgentActionRiskTier;
 }
@@ -402,6 +406,8 @@ interface ExecuteActionResult {
     result?: Record<string, unknown>;
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
+    /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
     hitlRiskTier?: AgentActionRiskTier;
 }

package/dist/index.d.ts

@@ -213,6 +213,8 @@ interface EnterpriseEventEnvelope {
         source: InvocationSource;
         auditAttributes?: NamespacedAttributes;
     };
+    /** Present only for events an action declaring provisional consistency emitted. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     payload: unknown;
 }
 interface OutboxRecord {
@@ -393,6 +395,8 @@ interface SubmitActionResult {
     result?: Record<string, unknown>;
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
+    /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
     hitlRiskTier?: AgentActionRiskTier;
 }
@@ -402,6 +406,8 @@ interface ExecuteActionResult {
     result?: Record<string, unknown>;
     error?: string;
     reconciliation?: AuthorizationReconciliationOutcome;
+    /** Mirrors the action's declared consistency so a caller knows whether the result is settled. */
+    consistency?: "authoritative-now" | "provisional-until-reconciled";
     hitlRoute?: AgentActionRoute;
     hitlRiskTier?: AgentActionRiskTier;
 }

package/dist/index.js

@@ -92,6 +92,12 @@ function createGovernedActionHost(options) {
     }
     const action = actionResolver(input.actionId);
     if (!action) throw new Error(`Unknown action: ${input.actionId}`);
+    if (action.execution?.connectivity === "online-required" && input.executionReason === "offline_replay") {
+      throw new Error(`Action ${input.actionId} is online-required and cannot be submitted as an offline replay.`);
+    }
+    if (action.execution?.sensitivity === "restricted" && Object.keys(input.provenance?.auditAttributes ?? {}).length > 0) {
+      throw new Error(`Action ${input.actionId} declares restricted sensitivity; provenance audit attributes must not be durably recorded.`);
+    }
     const authorizationInput = toAuthorizationInput(action, input);
     if (!await options.authorization.checkEntitlement(authorizationInput)) {
       throw new Error(`Module "${action.namespace}" is not enabled for tenant ${input.tenantId}`);
@@ -164,7 +170,7 @@ function createGovernedActionHost(options) {
     }
     const durableWorkflowId = `action-invocation-${durableInvocation.id}`;
     if (durableInvocation.id !== actionInvocationId) {
-      return {
+      return withConsistency({
         actionInvocationId: durableInvocation.id,
         status: durableInvocation.status,
         workflowId: durableWorkflowId,
@@ -173,7 +179,7 @@ function createGovernedActionHost(options) {
         ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
         ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {},
         ...durableInvocation.authorizationReconciliation ? { reconciliation: durableInvocation.authorizationReconciliation } : {}
-      };
+      }, input.actionId);
     }
     if (options.dispatcher) {
       try {
@@ -183,14 +189,14 @@ function createGovernedActionHost(options) {
           spaceId: input.spaceId,
           workflowId: durableWorkflowId
         });
-        return {
+        return withConsistency({
           actionInvocationId: durableInvocation.id,
           status: durableInvocation.status,
           workflowId: dispatched.workflowId,
           ...dispatched.runId ? { runId: dispatched.runId } : {},
           ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
           ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {}
-        };
+        }, input.actionId);
       } catch (error) {
         const message = errorMessage(error);
         await options.store.updateActionInvocation(
@@ -207,7 +213,7 @@ function createGovernedActionHost(options) {
       input.tenantId,
       input.spaceId
     );
-    return { ...executed, workflowId: durableWorkflowId };
+    return { ...withConsistency(executed, input.actionId), workflowId: durableWorkflowId };
   }
   async function executeInvocation(actionInvocationId, tenantId, spaceId, executionOptions = {}, executionReasonOverride) {
     const loadedInvocation = await options.store.getActionInvocation(
@@ -221,7 +227,7 @@ function createGovernedActionHost(options) {
     const resumingRunningInvocation = loadedInvocation.status === "running";
     let invocation = loadedInvocation;
     if (isTerminal(invocation.status) || invocation.status === "waiting_for_approval") {
-      return actionResult(invocation);
+      return withConsistency(actionResult(invocation), invocation.actionId);
     }
     if (invocation.status === "running" && invocation.leaseOwner && executionOptions.leaseOwner !== invocation.leaseOwner) {
       return {
@@ -338,7 +344,7 @@ function createGovernedActionHost(options) {
           message: `Action ${action.actionId} requires durable capture-time authorization evidence`
         };
         await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { status: "reconciliation_required", error: reconciliation.message, authorizationReconciliation: reconciliation });
-        return { actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation };
+        return withConsistency({ actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation }, action.actionId);
       }
       const bindingExpired = authorityMoment !== "capture" && invocation.authorizationBinding?.expiresAt !== void 0 && Date.parse(invocation.authorizationBinding.expiresAt) <= now().getTime();
       if (bindingExpired) {
@@ -351,7 +357,7 @@ function createGovernedActionHost(options) {
           message: `Authorization binding for action ${action.actionId} expired before execution`
         };
         await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { status: "reconciliation_required", error: reconciliation.message, authorizationReconciliation: reconciliation });
-        return { actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation };
+        return withConsistency({ actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation }, action.actionId);
       }
       const executionAuthorized = authorityMoment === "capture" ? invocation.authorizationBinding !== void 0 : options.authorization.authorizeExecution ? await options.authorization.authorizeExecution({
         ...authorizationInput,
@@ -373,7 +379,7 @@ function createGovernedActionHost(options) {
           message: `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`
         };
         await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { status: "reconciliation_required", error: reconciliation.message, authorizationReconciliation: reconciliation });
-        return { actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation };
+        return withConsistency({ actionInvocationId, status: "reconciliation_required", error: reconciliation.message, reconciliation }, action.actionId);
       }
       const definitions = options.resolvePolicies ? await options.resolvePolicies({
         ...authorizationInput,
@@ -715,7 +721,7 @@ function createGovernedActionHost(options) {
       spaceId
     );
     if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
-    if (isTerminal(invocation.status)) return actionResult(invocation);
+    if (isTerminal(invocation.status)) return withConsistency(actionResult(invocation), invocation.actionId);
     if (invocation.status !== "waiting_for_approval") {
       return {
         ...actionResult(invocation),
@@ -765,9 +771,9 @@ function createGovernedActionHost(options) {
     const transitioned = transition.invocation ?? await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
     if (!transition.applied || !transitioned) {
       if (!transitioned) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
-      return actionResult(transitioned);
+      return withConsistency(actionResult(transitioned), transitioned.actionId);
     }
-    if (!decision.approved) return actionResult(transitioned);
+    if (!decision.approved) return withConsistency(actionResult(transitioned), transitioned.actionId);
     return executeInvocation(
       actionInvocationId,
       tenantId,
@@ -808,6 +814,13 @@ function createGovernedActionHost(options) {
       spaceId
     });
   }
+  function declaredConsistency(actionId) {
+    return actionResolver(actionId)?.execution?.consistency;
+  }
+  function withConsistency(result, actionId) {
+    const consistency = declaredConsistency(actionId);
+    return consistency ? { ...result, consistency } : result;
+  }
   async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1, transaction) {
     const timestamp = now();
     const envelope = {
@@ -830,7 +843,8 @@ function createGovernedActionHost(options) {
       recordedAt: timestamp,
       correlationId: invocation.correlationId,
       ...invocation.causationId ? { causationId: invocation.causationId } : {},
-      ...invocation.provenance ? { provenance: { source: invocation.provenance.source, ...invocation.provenance.auditAttributes ? { auditAttributes: invocation.provenance.auditAttributes } : {} } } : {}
+      ...invocation.provenance ? { provenance: { source: invocation.provenance.source, ...invocation.provenance.auditAttributes ? { auditAttributes: invocation.provenance.auditAttributes } : {} } } : {},
+      ...declaredConsistency(invocation.actionId) === "provisional-until-reconciled" ? { consistency: "provisional-until-reconciled" } : {}
     };
     if (options.outbox) {
       const hostLifecycleEvent = (/* @__PURE__ */ new Set(["AdapterInvocationStarted", "AdapterInvocationSucceeded", "AdapterInvocationFailed", "ComplianceBlocked"])).has(envelope.eventType);
@@ -998,6 +1012,8 @@ function toEnterpriseEventEnvelope(event, metadata) {
     payloadClassification: metadata.payloadClassification,
     ...metadata.traceContext ? { traceContext: { ...metadata.traceContext } } : {},
     ...metadata.includeProvenance && event.provenance ? { provenance: event.provenance } : {},
+    // A provisional fact must stay marked as provisional once it leaves the platform.
+    ...event.consistency ? { consistency: event.consistency } : {},
     payload: event.payload
   };
 }
@@ -1429,10 +1445,11 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 				actor_id text NOT NULL, actor_type text NOT NULL, action_invocation_id text,
 				payload jsonb NOT NULL, sequence bigint NOT NULL,
 				occurred_at timestamptz NOT NULL, recorded_at timestamptz NOT NULL,
-				correlation_id text NOT NULL, causation_id text, provenance jsonb,
+				correlation_id text NOT NULL, causation_id text, provenance jsonb, consistency text,
 				UNIQUE (tenant_id, space_id, sequence)
 			);
 			ALTER TABLE fabric_platform.asset_events ADD COLUMN IF NOT EXISTS provenance jsonb;
+			ALTER TABLE fabric_platform.asset_events ADD COLUMN IF NOT EXISTS consistency text;
 			CREATE INDEX IF NOT EXISTS asset_events_subject_idx
 				ON fabric_platform.asset_events
 				(tenant_id, space_id, subject_type, subject_id, sequence);
@@ -1716,8 +1733,8 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
       `INSERT INTO fabric_platform.asset_events
 			 (id,tenant_id,space_id,event_type,event_schema_version,subject_type,subject_id,
 			  actor_id,actor_type,action_invocation_id,payload,sequence,occurred_at,recorded_at,
-			  correlation_id,causation_id,provenance)
-				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14,$15,$16,$17::jsonb)
+			  correlation_id,causation_id,provenance,consistency)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14,$15,$16,$17::jsonb,$18)
 				 ON CONFLICT (id) DO NOTHING`,
       [
         event.id,
@@ -1736,7 +1753,8 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
         event.recordedAt,
         event.correlationId,
         event.causationId ?? null,
-        event.provenance ? JSON.stringify(event.provenance) : null
+        event.provenance ? JSON.stringify(event.provenance) : null,
+        event.consistency ?? null
       ]
     );
   }
@@ -1747,8 +1765,8 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
 				INSERT INTO fabric_platform.asset_events
 				 (id,tenant_id,space_id,event_type,event_schema_version,subject_type,subject_id,
 				  actor_id,actor_type,action_invocation_id,payload,sequence,occurred_at,recorded_at,
-				  correlation_id,causation_id,provenance)
-				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14,$15,$16,$17::jsonb)
+				  correlation_id,causation_id,provenance,consistency)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14,$15,$16,$17::jsonb,$19)
 				 ON CONFLICT (id) DO NOTHING RETURNING id
 			)
 			INSERT INTO fabric_platform.event_outbox
@@ -1773,7 +1791,8 @@ var PostgresPlatformHostStore = class _PostgresPlatformHostStore {
         event.correlationId,
         event.causationId ?? null,
         event.provenance ? JSON.stringify(event.provenance) : null,
-        JSON.stringify(envelope)
+        JSON.stringify(envelope),
+        event.consistency ?? null
       ]
     );
   }
@@ -2015,7 +2034,8 @@ function toEventRecord(row) {
     recordedAt: new Date(row.recorded_at),
     correlationId: String(row.correlation_id),
     ...row.causation_id ? { causationId: String(row.causation_id) } : {},
-    ...row.provenance ? { provenance: row.provenance } : {}
+    ...row.provenance ? { provenance: row.provenance } : {},
+    ...row.consistency ? { consistency: row.consistency } : {}
   };
 }
 function toOutboxRecord(row) {