@fabricorg/platform-host 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @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

package/dist/index.cjs

@@ -94,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}`);
@@ -166,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,
@@ -175,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 {
@@ -185,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(
@@ -209,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(
@@ -223,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 {
@@ -340,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) {
@@ -353,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,
@@ -375,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,
@@ -717,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),
@@ -767,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,
@@ -810,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 = {
@@ -832,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);
@@ -1000,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
   };
 }
@@ -1431,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);
@@ -1718,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,
@@ -1738,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
       ]
     );
   }
@@ -1749,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
@@ -1775,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
       ]
     );
   }
@@ -2017,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) {