@fabricorg/platform-host 8.6.0 → 8.8.0

package/dist/index.d.cts

@@ -275,6 +275,8 @@ export interface FinalizationCheckpoint {
 export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
+  /** Host-registered principal name captured in the durable staged intent. */
+  principal?: string;
 }
 export interface AgentProposal {
   confidence?: number;
@@ -757,6 +759,8 @@ export interface StagedInvocationRecord {
   parentActionId: ActionId;
   key: string;
   actionId: ActionId;
+  /** Host-registered principal name selected by the parent action declaration. */
+  principal?: string;
   expectedActionVersion: number;
   parameters: Record<string, unknown>;
   parameterDigest: string;
@@ -1498,6 +1502,11 @@ export interface PlatformHostOptions<TDb> {
   registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine"> & Partial<Pick<ModuleRegistry<TDb>, "orderedModules">>;
   /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
   resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
+  /** Host-owned identities available to parent action declarations for staged dispatch. */
+  stagedInvocationPrincipals?: Readonly<Record<string, {
+    actorId: string;
+    actorType: ActorType;
+  }>>;
   adapters?: readonly AdapterImplementation[];
   /**
    * Supplies the circuit breaker for each adapter call. Defaults to a new
@@ -2233,11 +2242,13 @@ export declare const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
 export declare const MAX_STAGED_INVOCATION_BYTES: number;
 export declare const MAX_STAGED_INVOCATION_BATCH_BYTES: number;
 export declare const STAGED_INVOCATION_KEY_PATTERN: RegExp;
+export declare const STAGED_INVOCATION_PRINCIPAL_PATTERN: RegExp;
 interface PrepareStagedInvocationBatchInput<TDb> {
   parent: Pick<ActionInvocationRecord, "id" | "tenantId" | "spaceId" | "actionId">;
   parentAction: ActionDefinition<TDb>;
   requests: readonly StagedInvocationRequest[];
   resolveAction(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  stagedInvocationPrincipals?: Readonly<Record<string, unknown>>;
   redactParameters?(actionId: ActionId, parameters: Record<string, unknown>): Record<string, unknown>;
   /** Keys whose parameters already passed the redactor into a durable checkpoint. */
   redactedKeys?: readonly string[];

package/dist/index.d.ts

@@ -275,6 +275,8 @@ export interface FinalizationCheckpoint {
 export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
+  /** Host-registered principal name captured in the durable staged intent. */
+  principal?: string;
 }
 export interface AgentProposal {
   confidence?: number;
@@ -757,6 +759,8 @@ export interface StagedInvocationRecord {
   parentActionId: ActionId;
   key: string;
   actionId: ActionId;
+  /** Host-registered principal name selected by the parent action declaration. */
+  principal?: string;
   expectedActionVersion: number;
   parameters: Record<string, unknown>;
   parameterDigest: string;
@@ -1498,6 +1502,11 @@ export interface PlatformHostOptions<TDb> {
   registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine"> & Partial<Pick<ModuleRegistry<TDb>, "orderedModules">>;
   /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
   resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
+  /** Host-owned identities available to parent action declarations for staged dispatch. */
+  stagedInvocationPrincipals?: Readonly<Record<string, {
+    actorId: string;
+    actorType: ActorType;
+  }>>;
   adapters?: readonly AdapterImplementation[];
   /**
    * Supplies the circuit breaker for each adapter call. Defaults to a new
@@ -2233,11 +2242,13 @@ export declare const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
 export declare const MAX_STAGED_INVOCATION_BYTES: number;
 export declare const MAX_STAGED_INVOCATION_BATCH_BYTES: number;
 export declare const STAGED_INVOCATION_KEY_PATTERN: RegExp;
+export declare const STAGED_INVOCATION_PRINCIPAL_PATTERN: RegExp;
 interface PrepareStagedInvocationBatchInput<TDb> {
   parent: Pick<ActionInvocationRecord, "id" | "tenantId" | "spaceId" | "actionId">;
   parentAction: ActionDefinition<TDb>;
   requests: readonly StagedInvocationRequest[];
   resolveAction(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  stagedInvocationPrincipals?: Readonly<Record<string, unknown>>;
   redactParameters?(actionId: ActionId, parameters: Record<string, unknown>): Record<string, unknown>;
   /** Keys whose parameters already passed the redactor into a durable checkpoint. */
   redactedKeys?: readonly string[];

package/dist/index.js

@@ -1,5 +1,5 @@
 import { types } from "util";
-import { AdapterCircuitBreakerRegistry, AdapterRegistry, FABRIC_GOVERNANCE_CONTRACT_VERSION, ReconciliationRequiredError, aggregatePolicyOutcomes, assertActionFinalization, assertAdapterCircuitBreakerConfig, assertAdapterOutcomeConsistency, assertAdapterStepDeadlines, assertGovernanceRuntimeEvidence, assertMutationGovernanceContext, canonicalJson, createFabricId, evaluatePolicyDefinitions, evaluateStateMachineTransition, executeWithAdapterRetry, isAdapterCircuitOpenError, isReconciliationRequiredError, isRetryableExecutionError } from "@fabricorg/platform";
+import { AdapterCircuitBreakerRegistry, AdapterRegistry, FABRIC_GOVERNANCE_CONTRACT_VERSION, ReconciliationRequiredError, aggregatePolicyOutcomes, assertActionFinalization, assertAdapterCircuitBreakerConfig, assertAdapterOutcomeConsistency, assertAdapterStepDeadlines, assertGovernanceRuntimeEvidence, assertMutationGovernanceContext, canonicalJson, createFabricId, evaluatePolicyDefinitions, evaluateStateMachineTransition, executeWithAdapterRetry, isActorType, isAdapterCircuitOpenError, isReconciliationRequiredError, isRetryableExecutionError } from "@fabricorg/platform";
 import { performance } from "perf_hooks";
 import { assertAssemblyRuntimeCompatible } from "@fabricorg/assembly";
 import { createHash } from "crypto";
@@ -1374,6 +1374,7 @@ const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
 const MAX_STAGED_INVOCATION_BYTES = 65536;
 const MAX_STAGED_INVOCATION_BATCH_BYTES = 262144;
 const STAGED_INVOCATION_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const STAGED_INVOCATION_PRINCIPAL_PATTERN = /^[a-z][a-z0-9._:-]{0,127}$/;
 /** Validate and normalize one immutable batch before its parent transaction commits. */
 function prepareStagedInvocationBatch(input) {
 	if (!Array.isArray(input.requests)) throw new Error("stagedInvocations must be an array.");
@@ -1393,6 +1394,8 @@ function prepareStagedInvocationBatch(input) {
 		if (!(input.parentAction.stagesInvocations ?? []).includes(request.actionId)) throw new Error(`Action "${input.parentAction.actionId}" may not stage "${String(request.actionId)}".`);
 		const child = input.resolveAction(request.actionId);
 		if (!child) throw new Error(`Staged action "${String(request.actionId)}" is not registered.`);
+		const principal = input.parentAction.stagedInvocationPrincipals?.[child.actionId];
+		if (principal !== void 0 && !Object.hasOwn(input.stagedInvocationPrincipals ?? {}, principal)) throw new Error(`Staged invocation principal "${principal}" is not registered with this Platform Host.`);
 		const parameters = finalizationJson(request.parameters);
 		if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) throw new Error(`stagedInvocations[${index}] parameters must be a JSON object.`);
 		if (!child.schema.safeParse(parameters).success) throw new Error(`stagedInvocations[${index}] parameters do not match action "${child.actionId}".`);
@@ -1407,24 +1410,27 @@ function prepareStagedInvocationBatch(input) {
 		if (byteLength(canonicalJson({
 			key: request.key,
 			actionId: child.actionId,
-			parameters: durableParameters
+			parameters: durableParameters,
+			...principal !== void 0 ? { principal } : {}
 		})) > 65536) throw new Error(`stagedInvocations[${index}] exceeds ${MAX_STAGED_INVOCATION_BYTES} bytes.`);
 		return {
 			key: request.key,
 			actionId: child.actionId,
 			expectedActionVersion: child.version,
 			parameters: durableParameters,
-			parameterDigest: digestParameters(durableParameters)
+			parameterDigest: digestParameters(durableParameters),
+			...principal !== void 0 ? { principal } : {}
 		};
 	});
 	for (const [index, request] of normalized.entries()) if (normalized.findIndex((candidate) => candidate.key === request.key) !== index) throw new Error(`stagedInvocations contains duplicate key "${request.key}".`);
 	normalized.sort((left, right) => compareText(left.key, right.key) || compareText(left.actionId, right.actionId));
-	const batchIdentity = normalized.map(({ key, actionId, expectedActionVersion, parameters, parameterDigest }) => ({
+	const batchIdentity = normalized.map(({ key, actionId, expectedActionVersion, parameters, parameterDigest, principal }) => ({
 		key,
 		actionId,
 		expectedActionVersion,
 		parameters,
-		parameterDigest
+		parameterDigest,
+		...principal !== void 0 ? { principal } : {}
 	}));
 	if (byteLength(canonicalJson(batchIdentity)) > 262144) throw new Error(`stagedInvocations batch exceeds ${MAX_STAGED_INVOCATION_BATCH_BYTES} bytes.`);
 	const batchDigest = digestParameters({
@@ -1459,7 +1465,8 @@ function stagedInvocationRequestIdentity(record) {
 		expectedActionVersion: record.expectedActionVersion,
 		parameters: record.parameters,
 		parameterDigest: record.parameterDigest,
-		batchDigest: record.batchDigest
+		batchDigest: record.batchDigest,
+		...record.principal !== void 0 ? { principal: record.principal } : {}
 	});
 }
 function cloneStagedInvocationRecord(record) {
@@ -1526,6 +1533,20 @@ const STAGED_ERROR = Object.freeze({
 	lookup: "Staged child lookup failed."
 });
 function createGovernedActionHost(options) {
+	const configuredStagedPrincipals = options.stagedInvocationPrincipals;
+	if (configuredStagedPrincipals !== void 0 && (!configuredStagedPrincipals || typeof configuredStagedPrincipals !== "object" || Array.isArray(configuredStagedPrincipals))) throw new Error("stagedInvocationPrincipals must be an object.");
+	const stagedInvocationPrincipals = Object.freeze(Object.fromEntries(Object.entries(configuredStagedPrincipals ?? {}).map(([name, candidate]) => {
+		if (!STAGED_INVOCATION_PRINCIPAL_PATTERN.test(name)) throw new Error(`Invalid staged invocation principal name: ${name}`);
+		if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) throw new Error(`Staged invocation principal "${name}" must be an object.`);
+		const actorId = candidate.actorId;
+		const actorType = candidate.actorType;
+		if (typeof actorId !== "string" || actorId.length === 0) throw new Error(`Staged invocation principal "${name}" actorId must be a non-empty string.`);
+		if (typeof actorType !== "string" || !isActorType(actorType)) throw new Error(`Staged invocation principal "${name}" has invalid actorType.`);
+		return [name, Object.freeze({
+			actorId,
+			actorType
+		})];
+	})));
 	if (options.approvalDefaultTtlMs !== void 0 && (!Number.isSafeInteger(options.approvalDefaultTtlMs) || options.approvalDefaultTtlMs <= 0)) throw new Error("approvalDefaultTtlMs must be a positive safe integer in milliseconds.");
 	if (options.approvalLifecycleEvents) {
 		const approvalStore = asApprovalStore(options.store);
@@ -1559,6 +1580,9 @@ function createGovernedActionHost(options) {
 	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;
+	if (options.registry?.orderedModules) {
+		for (const module of options.registry.orderedModules) for (const action of module.actions ?? []) for (const principal of Object.values(action.stagedInvocationPrincipals ?? {})) if (!Object.hasOwn(stagedInvocationPrincipals, principal)) throw new Error(`Staged invocation principal "${principal}" referenced by action "${action.actionId}" is not registered with this Platform Host.`);
+	}
 	const stagedStore = asStagedInvocationStore(options.store);
 	const declaresStaging = options.registry?.orderedModules?.some((module) => (module.actions ?? []).some((action) => (action.stagesInvocations?.length ?? 0) > 0)) ?? false;
 	if (declaresStaging && (!stagedStore || !asAtomicMutationStore(options.store))) throw new Error("Staged descendant invocations require a store with transactionalStagedInvocations and transactionWithEvents capabilities.");
@@ -2702,6 +2726,7 @@ function createGovernedActionHost(options) {
 							parentAction: action,
 							requests: rawStagedInvocations,
 							resolveAction: actionResolver,
+							stagedInvocationPrincipals,
 							redactParameters: options.redactActionParameters,
 							now: now()
 						});
@@ -3122,6 +3147,7 @@ function createGovernedActionHost(options) {
 									...invocation.causationId ? { causationId: invocation.causationId } : {},
 									attempt,
 									maxAttempts,
+									...executionLease ? { lease: executionLease } : {},
 									...deadlineMs ? { deadlineMs } : {},
 									...adapterController ? { signal: adapterController.signal } : {}
 								});
@@ -3573,6 +3599,7 @@ function createGovernedActionHost(options) {
 									parentAction: action,
 									requests: stagedRequests,
 									resolveAction: actionResolver,
+									stagedInvocationPrincipals,
 									redactParameters: options.redactActionParameters,
 									redactedKeys: handlerStagedInvocations.map((request) => request.key),
 									now: now()
@@ -4143,6 +4170,8 @@ function createGovernedActionHost(options) {
 		if (!parent || parent.status !== "completed") throw new Error("Staged parent is not completed.");
 		const child = actionResolver(record.actionId);
 		if (!child) throw new StagedDispatchRejectionError("Staged action is no longer registered.");
+		const principal = record.principal !== void 0 && Object.hasOwn(stagedInvocationPrincipals, record.principal) ? stagedInvocationPrincipals[record.principal] : void 0;
+		if (record.principal !== void 0 && !principal) throw new StagedDispatchRejectionError("Staged invocation principal is no longer registered.");
 		if (child.execution?.authorityMoment === "capture") throw new StagedDispatchRejectionError("Staged action now requires capture-time authority.");
 		if (!child.schema.safeParse(structuredClone(record.parameters)).success) throw new StagedDispatchRejectionError("Staged parameters no longer match the registered action.");
 		return submitActionInternal({
@@ -4150,8 +4179,8 @@ function createGovernedActionHost(options) {
 			parameters: structuredClone(record.parameters),
 			tenantId: parent.tenantId,
 			spaceId: parent.spaceId,
-			actorId: parent.actorId,
-			actorType: parent.actorType,
+			actorId: principal?.actorId ?? parent.actorId,
+			actorType: principal?.actorType ?? parent.actorType,
 			correlationId: parent.correlationId,
 			causationId: parent.id,
 			provenance: {
@@ -4165,7 +4194,8 @@ function createGovernedActionHost(options) {
 				id: record.id,
 				origin: {
 					parentInvocationId: parent.id,
-					stageKey: record.key
+					stageKey: record.key,
+					...record.principal !== void 0 ? { principal: record.principal } : {}
 				},
 				workerId: lease.workerId,
 				leaseToken: lease.leaseToken,
@@ -4835,7 +4865,7 @@ var MemoryPlatformHostStore = class {
 			kind: "existing",
 			invocation: existing
 		};
-		if (!this.stagedInvocations.find((record) => record.id === input.stageId && record.tenantId === invocation.tenantId && record.spaceId === invocation.spaceId && record.parentInvocationId === invocation.stagedOrigin.parentInvocationId && record.key === invocation.stagedOrigin.stageKey && record.actionId === invocation.actionId && record.status === "pending" && record.leaseOwner === input.workerId && record.leaseToken === input.leaseToken && record.leaseExpiresAt !== void 0 && record.leaseExpiresAt > now)) return { kind: "lease_lost" };
+		if (!this.stagedInvocations.find((record) => record.id === input.stageId && record.tenantId === invocation.tenantId && record.spaceId === invocation.spaceId && record.parentInvocationId === invocation.stagedOrigin.parentInvocationId && record.key === invocation.stagedOrigin.stageKey && record.actionId === invocation.actionId && record.principal === invocation.stagedOrigin.principal && record.status === "pending" && record.leaseOwner === input.workerId && record.leaseToken === input.leaseToken && record.leaseExpiresAt !== void 0 && record.leaseExpiresAt > now)) return { kind: "lease_lost" };
 		const createdAt = /* @__PURE__ */ new Date();
 		const record = {
 			...invocation,
@@ -5683,6 +5713,16 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				version: 13,
 				name: "agent_proposal",
 				sql: `ALTER TABLE fabric_platform.action_invocations ADD COLUMN IF NOT EXISTS agent_proposal jsonb;`
+			},
+			{
+				version: 14,
+				name: "staged_invocation_principals",
+				sql: `
+				ALTER TABLE fabric_platform.staged_invocations
+					ADD COLUMN IF NOT EXISTS principal text;
+				ALTER TABLE fabric_platform.action_invocations
+					ADD COLUMN IF NOT EXISTS staged_origin_principal text;
+			`
 			}
 		]);
 	}
@@ -5747,9 +5787,9 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		const current = input.now ?? /* @__PURE__ */ new Date();
 		const admitted = invocation.admittedAt !== void 0;
 		const admittedColumn = admitted ? ",admitted_at" : "";
-		const admittedValue = admitted ? ",$30" : "";
+		const admittedValue = admitted ? ",$31" : "";
 		const proposalColumn = invocation.agentProposal !== void 0 ? ",agent_proposal" : "";
-		const proposalValue = invocation.agentProposal !== void 0 ? `,$${admitted ? 31 : 30}::jsonb` : "";
+		const proposalValue = invocation.agentProposal !== void 0 ? `,$${admitted ? 32 : 31}::jsonb` : "";
 		const values = [
 			invocation.id,
 			invocation.tenantId,
@@ -5776,6 +5816,7 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			invocation.runtimeEvidence ? JSON.stringify(invocation.runtimeEvidence) : null,
 			invocation.stagedOrigin.parentInvocationId,
 			invocation.stagedOrigin.stageKey,
+			invocation.stagedOrigin.principal ?? null,
 			input.stageId,
 			input.workerId,
 			input.leaseToken,
@@ -5788,10 +5829,11 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			result = await this.sql.query(`WITH fence AS (
 					SELECT stage.id
 					FROM fabric_platform.staged_invocations AS stage
-					WHERE stage.id=$26 AND stage.tenant_id=$2 AND stage.space_id=$3
+					WHERE stage.id=$27 AND stage.tenant_id=$2 AND stage.space_id=$3
 					  AND stage.parent_invocation_id=$24 AND stage.stage_key=$25 AND stage.action_id=$4
-					  AND stage.status='pending' AND stage.lease_owner=$27 AND stage.lease_token=$28
-					  AND stage.lease_expires_at IS NOT NULL AND stage.lease_expires_at > $29
+					  AND stage.principal IS NOT DISTINCT FROM $26
+					  AND stage.status='pending' AND stage.lease_owner=$28 AND stage.lease_token=$29
+					  AND stage.lease_expires_at IS NOT NULL AND stage.lease_expires_at > $30
 					FOR SHARE
 				)
 				 INSERT INTO fabric_platform.action_invocations
@@ -5799,17 +5841,19 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				  parameters,result,correlation_id,causation_id,idempotency_key,parameter_digest,
 				  parameter_digest_algorithm,idempotency_actor_id,idempotency_authorization_binding_id,
 				  invocation_provenance,authorization_binding,execution_reason,authorization_binding_id,error,
-				  runtime_evidence,staged_parent_invocation_id,staged_stage_key${admittedColumn}${proposalColumn},created_at,updated_at)
+				  runtime_evidence,staged_parent_invocation_id,staged_stage_key,staged_origin_principal${admittedColumn}${proposalColumn},created_at,updated_at)
 				 SELECT $1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$16,$17,
-				        $18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,$24,$25${admittedValue}${proposalValue},$29,$29
+				        $18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,$24,$25,$26${admittedValue}${proposalValue},$30,$30
 				 FROM fence
 				 ON CONFLICT (tenant_id,space_id,staged_parent_invocation_id,staged_stage_key)
 				 WHERE staged_parent_invocation_id IS NOT NULL AND staged_stage_key IS NOT NULL
 				 DO UPDATE SET id=fabric_platform.action_invocations.id
 				 RETURNING *`, values);
 		} catch (error) {
-			if (invocation.agentProposal !== void 0 && error?.code === "42703") throw new Error("Agent proposals require PostgreSQL migration 13 (agent_proposal); run ensureSchema().", { cause: error });
-			if (error?.code === "42703" || error?.code === "42P01") throw new Error("A staged child needs PostgreSQL migration 11 (staged_descendant_invocations); run ensureSchema() before dispatching staged invocations.", { cause: error });
+			const databaseError = error;
+			if (invocation.agentProposal !== void 0 && databaseError?.code === "42703" && typeof databaseError.message === "string" && /\bagent_proposal\b/.test(databaseError.message)) throw new Error("Agent proposals require PostgreSQL migration 13 (agent_proposal); run ensureSchema().", { cause: error });
+			if (databaseError?.code === "42703") throw new Error("A staged child needs PostgreSQL migration 14 (staged_invocation_principals); run ensureSchema() before dispatching staged invocations.", { cause: error });
+			if (databaseError?.code === "42P01") throw new Error("A staged child needs PostgreSQL migration 11 (staged_descendant_invocations); run ensureSchema() before dispatching staged invocations.", { cause: error });
 			throw error;
 		}
 		if (result.rows[0]) {
@@ -5851,33 +5895,39 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		}
 		for (const record of records) {
 			if (record.tenantId !== first.tenantId || record.spaceId !== first.spaceId || record.parentInvocationId !== first.parentInvocationId || record.batchDigest !== first.batchDigest) throw new Error(`Invalid staged invocation batch for parent ${first.parentInvocationId}.`);
-			await this.sql.query(`INSERT INTO fabric_platform.staged_invocations
-				 (id,tenant_id,space_id,parent_invocation_id,parent_action_id,stage_key,action_id,
+			try {
+				await this.sql.query(`INSERT INTO fabric_platform.staged_invocations
+				 (id,tenant_id,space_id,parent_invocation_id,parent_action_id,stage_key,action_id,principal,
 				  expected_action_version,parameters,parameter_digest,batch_digest,status,child_invocation_id,
 				  attempt_count,available_at,lease_owner,lease_expires_at,lease_token,last_error,created_at,updated_at)
-				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21)`, [
-				record.id,
-				record.tenantId,
-				record.spaceId,
-				record.parentInvocationId,
-				record.parentActionId,
-				record.key,
-				record.actionId,
-				record.expectedActionVersion,
-				JSON.stringify(record.parameters),
-				record.parameterDigest,
-				record.batchDigest,
-				record.status,
-				record.childInvocationId ?? null,
-				record.attemptCount,
-				record.availableAt,
-				record.leaseOwner ?? null,
-				record.leaseExpiresAt ?? null,
-				record.leaseToken,
-				record.lastError ?? null,
-				record.createdAt,
-				record.updatedAt
-			]);
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22)`, [
+					record.id,
+					record.tenantId,
+					record.spaceId,
+					record.parentInvocationId,
+					record.parentActionId,
+					record.key,
+					record.actionId,
+					record.principal ?? null,
+					record.expectedActionVersion,
+					JSON.stringify(record.parameters),
+					record.parameterDigest,
+					record.batchDigest,
+					record.status,
+					record.childInvocationId ?? null,
+					record.attemptCount,
+					record.availableAt,
+					record.leaseOwner ?? null,
+					record.leaseExpiresAt ?? null,
+					record.leaseToken,
+					record.lastError ?? null,
+					record.createdAt,
+					record.updatedAt
+				]);
+			} catch (error) {
+				if (error?.code === "42703") throw new Error("Staging an invocation needs PostgreSQL migration 14 (staged_invocation_principals); run ensureSchema() before staging invocations.", { cause: error });
+				throw error;
+			}
 		}
 	}
 	async getActionInvocation(id, tenantId, spaceId) {
@@ -6898,7 +6948,8 @@ function toActionRecord(row) {
 		...row.idempotency_authorization_binding_id ? { idempotencyAuthorizationBindingId: String(row.idempotency_authorization_binding_id) } : {},
 		...row.staged_parent_invocation_id && row.staged_stage_key ? { stagedOrigin: {
 			parentInvocationId: String(row.staged_parent_invocation_id),
-			stageKey: String(row.staged_stage_key)
+			stageKey: String(row.staged_stage_key),
+			...row.staged_origin_principal ? { principal: String(row.staged_origin_principal) } : {}
 		} } : {},
 		...row.invocation_provenance ? { provenance: row.invocation_provenance } : {},
 		...row.authorization_binding ? { authorizationBinding: row.authorization_binding } : {},
@@ -6944,6 +6995,7 @@ function toStagedInvocationRecord(row) {
 		parentActionId: String(row.parent_action_id),
 		key: String(row.stage_key),
 		actionId: String(row.action_id),
+		...row.principal ? { principal: String(row.principal) } : {},
 		expectedActionVersion: Number(row.expected_action_version),
 		parameters: row.parameters,
 		parameterDigest: String(row.parameter_digest),
@@ -8425,6 +8477,6 @@ async function runEventAppendChecks(subject) {
 	};
 }
 //#endregion
-export { APPROVAL_DECIDED_EVENT, APPROVAL_EXPIRED_EVENT, APPROVAL_REQUESTED_EVENT, ActionAdmissionError, ExternalCompletionError, IdempotencyConflictError, MAX_APPROVAL_EVIDENCE_BYTES, MAX_STAGED_INVOCATIONS, MAX_STAGED_INVOCATION_BATCH_BYTES, MAX_STAGED_INVOCATION_BYTES, MAX_STAGED_INVOCATION_KEY_LENGTH, MemoryPlatformHostStore, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, PostgresPlatformHostStore, STAGED_INVOCATION_KEY_PATTERN, SubmissionRefusalError, applyPostgresMigrations, asStagedInvocationStore, canonicalJson, cloneOutboxRecord, cloneStagedInvocationRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, eventAppendChecks, getPlatformHostHealthSnapshot, outboxActorDisclosure, prepareStagedInvocationBatch, runEventAppendChecks, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, runTenantIsolationChecks, stagedInvocationRequestIdentity, tenantIsolationChecks, toEnterpriseEventEnvelope };
+export { APPROVAL_DECIDED_EVENT, APPROVAL_EXPIRED_EVENT, APPROVAL_REQUESTED_EVENT, ActionAdmissionError, ExternalCompletionError, IdempotencyConflictError, MAX_APPROVAL_EVIDENCE_BYTES, MAX_STAGED_INVOCATIONS, MAX_STAGED_INVOCATION_BATCH_BYTES, MAX_STAGED_INVOCATION_BYTES, MAX_STAGED_INVOCATION_KEY_LENGTH, MemoryPlatformHostStore, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, PLATFORM_HOST_HEALTH_CONTRACT_VERSION, PLATFORM_HOST_METRIC_NAMES, PostgresPlatformHostStore, STAGED_INVOCATION_KEY_PATTERN, STAGED_INVOCATION_PRINCIPAL_PATTERN, SubmissionRefusalError, applyPostgresMigrations, asStagedInvocationStore, canonicalJson, cloneOutboxRecord, cloneStagedInvocationRecord, createDurableSagaParentLifecycle, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, emitPlatformHostTelemetry, eventAppendChecks, getPlatformHostHealthSnapshot, outboxActorDisclosure, prepareStagedInvocationBatch, runEventAppendChecks, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, runTenantIsolationChecks, stagedInvocationRequestIdentity, tenantIsolationChecks, toEnterpriseEventEnvelope };
 
 //# sourceMappingURL=index.js.map