@fabricorg/platform-host 3.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @fabricorg/platform-host
 
+## 5.0.0
+
+### Major Changes
+
+- c504d0a: Enforce every field of `ActionExecutionContract` or hand it to an explicit owner.
+
+  - `connectivity`: an action declaring `online-required` is refused when submitted with
+    `executionReason: "offline_replay"`. What a client offers offline is a composition decision; what
+    the Host accepts is not.
+  - `consistency`: an action declaring `provisional-until-reconciled` marks the events it emits and the
+    submission result, so bus consumers and reconciliation flows can tell a settled fact from a pending
+    one without a lookup.
+  - `sensitivity`: an action declaring `restricted` refuses a submission carrying provenance audit
+    attributes instead of durably recording them.
+  - `completion`: `immediate` combined with `kind: "saga"` is rejected at registry build.
+
+  `consistency` is persisted by the PostgreSQL store (additive nullable column, applied by
+  `ensureSchema()`) and carried through `toEnterpriseEventEnvelope()` to the bus, so a provisional fact
+  stays marked as provisional after replay and after publication. Every result path is decorated, so an
+  idempotent replay reports the same consistency as the original submission.
+
+  Applications that previously submitted offline replays of online-required actions, or audit
+  attributes on restricted actions, now receive an explicit error where both were silent.
+
+  At release, raise the `@fabricorg/platform` peer floor to the version carrying
+  `AssetEventEnvelope.consistency`.
+
+## 4.0.0
+
+### Major Changes
+
+- Make the capability runtime vertical-neutral and instance-scoped. Move experience and display
+  semantics into a namespaced companion package, require explicit host registries, replace privacy
+  field defaults with caller-owned policy, add PostgreSQL projection adapters, and generate executable
+  ProjectionHost read and PlatformHost mutation seams.
+
+### Patch Changes
+
+- Updated dependencies
+  - @fabricorg/platform@1.0.0
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.12.0 @fabricorg/platform-host@^3.0.0
+pnpm add @fabricorg/platform@^1.0.0 @fabricorg/platform-host@^4.0.0
 ```
 
 ## AI agent integration boundary
@@ -15,7 +15,7 @@ registration, and submit stable idempotent commands. The gateway derives tenant
 calls `submitAction()`; an agent must never call handlers, adapters, workflow internals, or database
 writes directly.
 
-See the [Platform Host 3.x agent integration
+See the [Platform Host 4.x 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.
@@ -32,8 +32,8 @@ Actor → ActionInvocation → Schema → Agent HITL → PolicyEvaluation → St
 worker entry point. With no dispatcher the host executes inline, which is intended for tests and local
 development only.
 
-Applications that assemble action catalogs per runtime can provide `resolveAction` instead of
-mutating the process-wide platform registry. A custom `extractEvents` implementation can pair with
+Applications construct a `createModuleRegistry()` per runtime and pass it as `registry`; a narrow
+`resolveAction` function remains available for adapters. No process-wide platform registry exists. A custom `extractEvents` implementation can pair with
 `eventResultFields` so its event carrier is removed from the durable invocation result. Domain events
 without an explicit `eventSchemaVersion` inherit the action version, while host lifecycle events stay
 at version 1. Emitted domain events must appear in the action's `emitsEvents` declaration. The
@@ -81,6 +81,7 @@ by default; `outbox.includeProvenance` is the explicit classification-aware over
 ```ts
 const host = createGovernedActionHost({
   store,
+  registry,
   authorization: {
     checkEntitlement,
     authorize: authorizeSubmission,

package/dist/index.cjs

@@ -31,10 +31,10 @@ function digestParameters(parameters) {
   return crypto.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 ?? []);
@@ -83,7 +83,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 ?? platform.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)) {
@@ -91,6 +94,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}`);
@@ -163,7 +172,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,
@@ -172,7 +181,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 {
@@ -182,14 +191,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(
@@ -206,7 +215,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(
@@ -220,7 +229,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 {
@@ -337,7 +346,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) {
@@ -350,7 +359,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,
@@ -372,7 +381,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,
@@ -388,6 +397,7 @@ function createGovernedActionHost(options) {
         parameters: parsed.data,
         db: options.store.db,
         services: options.services,
+        resolveCodePolicy: options.registry?.resolvePolicy,
         mode: "execute",
         now: now()
       });
@@ -440,10 +450,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 = platform.validateTransition(
+          const transition = platform.validateStateMachineTransition(
+            stateMachineResolver(binding.entityType),
             binding.entityType,
             currentState,
             targetState,
@@ -712,7 +723,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),
@@ -762,9 +773,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,
@@ -805,6 +816,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 = {
@@ -827,7 +845,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);
@@ -929,8 +948,7 @@ function declaredPolicies(policyIds) {
     codeEvaluatorPolicyId: policyId
   }));
 }
-function initialState(entityType) {
-  const machine = platform.resolveStateMachine(entityType);
+function initialState(machine) {
   return Object.values(machine?.states ?? {}).find((state) => state.stateClass === "initial")?.id ?? "none";
 }
 function isTerminal(status) {
@@ -996,6 +1014,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
   };
 }
@@ -1427,10 +1447,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);
@@ -1714,8 +1735,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,
@@ -1734,7 +1755,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
       ]
     );
   }
@@ -1745,8 +1767,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
@@ -1771,7 +1793,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
       ]
     );
   }
@@ -2013,7 +2036,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) {