@fabricorg/platform-host 3.0.0 → 5.0.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
+import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
 
 /** Durable Host lifecycle generation, independent from the npm package version. */
 declare const PLATFORM_HOST_CONTRACT_VERSION: 2;
-type InvocationSource = "sdui" | "api" | "agent" | "worker" | "system";
+type InvocationSource = "ui" | "api" | "agent" | "worker" | "system" | (string & {});
 type NamespacedAttributes = Record<string, string>;
 interface InvocationProvenance {
     source: InvocationSource;
@@ -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;
 }
@@ -431,6 +437,8 @@ interface PlatformActionWorkerCycleResult {
 interface PlatformHostOptions<TDb> {
     store: PlatformHostStore<TDb>;
     authorization: PlatformHostAuthorization;
+    /** Preferred explicit catalog assembled from this runtime's Fabric modules. */
+    registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine">;
     /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
     resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
     adapters?: readonly AdapterImplementation[];

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
+import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
 
 /** Durable Host lifecycle generation, independent from the npm package version. */
 declare const PLATFORM_HOST_CONTRACT_VERSION: 2;
-type InvocationSource = "sdui" | "api" | "agent" | "worker" | "system";
+type InvocationSource = "ui" | "api" | "agent" | "worker" | "system" | (string & {});
 type NamespacedAttributes = Record<string, string>;
 interface InvocationProvenance {
     source: InvocationSource;
@@ -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;
 }
@@ -431,6 +437,8 @@ interface PlatformActionWorkerCycleResult {
 interface PlatformHostOptions<TDb> {
     store: PlatformHostStore<TDb>;
     authorization: PlatformHostAuthorization;
+    /** Preferred explicit catalog assembled from this runtime's Fabric modules. */
+    registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine">;
     /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
     resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
     adapters?: readonly AdapterImplementation[];

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AdapterRegistry, resolveAction, createFabricId, assertGovernanceRuntimeEvidence, FABRIC_GOVERNANCE_CONTRACT_VERSION, assertMutationGovernanceContext, evaluatePolicyDefinitions, aggregatePolicyOutcomes, validateTransition, executeWithAdapterRetry, resolveStateMachine } from '@fabricorg/platform';
+import { AdapterRegistry, createFabricId, assertGovernanceRuntimeEvidence, FABRIC_GOVERNANCE_CONTRACT_VERSION, assertMutationGovernanceContext, evaluatePolicyDefinitions, aggregatePolicyOutcomes, validateStateMachineTransition, executeWithAdapterRetry } from '@fabricorg/platform';
 import { createHash } from 'crypto';
 
 // src/host.ts
@@ -29,10 +29,10 @@ function digestParameters(parameters) {
   return createHash("sha256").update(canonicalJson(parameters)).digest("hex");
 }
 var ATTRIBUTE_NAME = /^[a-z][a-z0-9-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
-var INVOCATION_SOURCES = /* @__PURE__ */ new Set(["sdui", "api", "agent", "worker", "system"]);
+var INVOCATION_SOURCE = /^(?:ui|sdui|api|agent|worker|system|[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+)$/;
 function normalizeProvenance(input, options) {
   if (!input) return void 0;
-  if (!INVOCATION_SOURCES.has(input.source)) throw new Error(`Invalid invocation provenance source: ${input.source}`);
+  if (!INVOCATION_SOURCE.test(input.source)) throw new Error(`Invalid invocation provenance source: ${input.source}`);
   const maxAttributes = options?.maxAttributes ?? 16;
   const maxValueLength = options?.maxValueLength ?? 256;
   const allowlist = new Set(options?.auditAttributeAllowlist ?? []);
@@ -81,7 +81,10 @@ function createGovernedActionHost(options) {
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const extractEvents = options.extractEvents ?? DEFAULT_EXTRACT_EVENTS;
-  const actionResolver = options.resolveAction ?? resolveAction;
+  const configuredActionResolver = options.resolveAction ?? options.registry?.resolveAction;
+  if (!configuredActionResolver) throw new Error("Platform Host requires an explicit module registry or resolveAction function.");
+  const actionResolver = configuredActionResolver;
+  const stateMachineResolver = options.registry?.resolveStateMachine ?? (() => void 0);
   const eventResultFields = options.eventResultFields ?? ["_events"];
   async function submitAction(input) {
     if (input.executionReason && !["initial", "offline_replay"].includes(input.executionReason)) {
@@ -89,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}`);
@@ -161,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,
@@ -170,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 {
@@ -180,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(
@@ -204,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(
@@ -218,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 {
@@ -335,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) {
@@ -348,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,
@@ -370,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,
@@ -386,6 +395,7 @@ function createGovernedActionHost(options) {
         parameters: parsed.data,
         db: options.store.db,
         services: options.services,
+        resolveCodePolicy: options.registry?.resolvePolicy,
         mode: "execute",
         now: now()
       });
@@ -438,10 +448,11 @@ function createGovernedActionHost(options) {
           spaceId,
           binding.entityType,
           entityId
-        ) ?? initialState(binding.entityType) : initialState(binding.entityType);
+        ) ?? initialState(stateMachineResolver(binding.entityType)) : initialState(stateMachineResolver(binding.entityType));
         const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
         if (targetState !== "") {
-          const transition = validateTransition(
+          const transition = validateStateMachineTransition(
+            stateMachineResolver(binding.entityType),
             binding.entityType,
             currentState,
             targetState,
@@ -710,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),
@@ -760,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,
@@ -803,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 = {
@@ -825,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);
@@ -927,8 +946,7 @@ function declaredPolicies(policyIds) {
     codeEvaluatorPolicyId: policyId
   }));
 }
-function initialState(entityType) {
-  const machine = resolveStateMachine(entityType);
+function initialState(machine) {
   return Object.values(machine?.states ?? {}).find((state) => state.stateClass === "initial")?.id ?? "none";
 }
 function isTerminal(status) {
@@ -994,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
   };
 }
@@ -1425,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);
@@ -1712,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,
@@ -1732,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
       ]
     );
   }
@@ -1743,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
@@ -1769,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
       ]
     );
   }
@@ -2011,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) {