@fabricorg/platform-host 8.6.0 → 8.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @fabricorg/platform-host
 
+## 8.7.0
+
+### Minor Changes
+
+- a28154f: Register Host-owned staged invocation principals, persist their names through recovery, and dispatch children through entitlement, admission, and authorization as the registered actor. PostgreSQL migration 14 adds nullable principal evidence columns and is required before deploying 8.7.0 anywhere staged invocations are used, including principal-less stages. Run `ensureSchema()`, deploy 8.7.0 or later to every process that runs the Host (executes staging parent actions, dispatches stages, or runs the Platform worker) without principal declarations, and only then ship modules that declare principals. An older worker can claim a principal-bearing stage and dispatch it as the parent's actor because it does not read or fence the new principal column.
+
 ## 8.6.0
 
 ### Minor Changes

package/README.md

@@ -1478,6 +1478,17 @@ child schema before the parent transaction commits. `redactActionParameters` run
 the redacted, schema-valid parameters are the only parameters written to the stage record and later
 used to create the child invocation.
 
+A parent action may select a Host-owned dispatch identity by declaring
+`stagedInvocationPrincipals`, which maps an allowlisted child action ID to a principal name. Host
+composition registers those names through `PlatformHostOptions.stagedInvocationPrincipals` with an
+`actorId` and Platform `ActorType`. A registry-backed Host refuses construction when a referenced
+name is absent; a resolve-only Host refuses the stage when it encounters an absent registration.
+The request allowlist remains exactly `key`, `actionId`, and `parameters`, so a handler or finalizer
+cannot supply `principal`, `actorId`, `actorType`, or an authorization binding. Host snapshots its
+registration at construction, records the principal name in the staged row, and resolves that
+durable name at dispatch. If a later Host no longer registers it, dispatch definitively rejects the
+stage instead of using the parent actor.
+
 Staging requires `transactionWithEvents`, a transaction-scoped `stageInvocations`, and a store whose
 `transactionalStagedInvocations` flag is true. Host construction checks the advertised staged-store
 operations and atomic-store capability: scoped origin lookup, lease-fenced child creation, claim,
@@ -1487,8 +1498,9 @@ execution preflight and interrupts that invocation. For `before_adapters`, the h
 commits with the handler mutation. For `after_adapters`, handler and finalizer requests commit with
 events and the completed parent verdict. A finalizing action retains its handler requests in the
 durable finalization checkpoint. Replaying an identical parent batch is a no-op; any changed key,
-action, version evidence, parameter digest, parameter value, batch size, or batch digest moves the
-parent to reconciliation without changing stored requests.
+action, version evidence, parameter digest, parameter value, principal name, batch size, or batch
+digest moves the parent to reconciliation without changing stored requests. Principal-less batches
+retain their earlier canonical identity and digest.
 
 A pending stage is claimable only while its immutable parent scope matches and the parent is
 `completed`. Parents ending `failed`, `blocked_by_policy`, or `validation_failed` have pending stages
@@ -1500,29 +1512,56 @@ contains an action with a non-empty `stagesInvocations` allowlist. `dispatchStag
 forces a sweep and `dispatchStagedInvocations: false` disables it. A deployment that has no staging
 declarations therefore does not query the migration-11 tables by default.
 
-The child has a Host-only `stagedOrigin` of parent invocation ID plus stage key, backed by a separate
-unique index. It carries no idempotency key, so a public caller cannot pre-claim its identity with a
-staged-looking string. A crash after parent commit is recovered by a later sweep. A crash after child
-creation but before the stage checkpoint resolves the same child by `stagedOrigin`. PostgreSQL
-migration 11 creates `staged_invocations`, adds the nullable origin columns and partial unique index,
-and adds the claim and parent indexes.
+The child has a Host-only `stagedOrigin` of parent invocation ID plus stage key and, when selected,
+the durable principal name. `authorizeExecution` can inspect `invocation.stagedOrigin.principal`
+alongside the child's durable parameters and actor. Public `SubmitActionInput` has no
+`stagedOrigin`; Host adds it through the internal staged-dispatch path.
+The lookup and unique index intentionally remain keyed by tenant, space, parent invocation ID, and
+stage key: one parent stage key identifies one child, while the principal is evidence for that
+durable intent rather than a second child identity. The child carries no idempotency key, so a public
+caller cannot pre-claim its identity with a staged-looking string. A crash after parent commit is
+recovered by a later sweep. A crash after child creation but before stage settlement resolves the
+same child, including its principal evidence, by `stagedOrigin`. PostgreSQL migration 11 creates the
+staged tables and origin index; migration 14 adds nullable `principal` and
+`staged_origin_principal` columns for the staged record and child invocation.
+
+Migration 14 is a deployment prerequisite for this Host version wherever staged invocations are
+used, including stages that do not select a principal: the staging and fenced child-insert SQL name
+the new nullable columns in both cases. Use this rollout order for a shared PostgreSQL database:
+
+1. Run `ensureSchema()` and confirm migration 14 (`staged_invocation_principals`) is recorded.
+2. Deploy `@fabricorg/platform-host` 8.7.0 or later to every process that runs this Host: processes
+   that execute staging parent actions (including inline execution inside `submitAction`), run
+   `dispatchStagedInvocations`, or run the Platform worker. Keep module principal declarations
+   disabled during this step. An older Host that executes a parent ignores the declaration and
+   stages the child without a principal, so every later dispatch uses the parent's actor.
+3. After those processes are upgraded, ship modules that declare `stagedInvocationPrincipals`.
+
+An older worker can claim a principal-bearing row because its claim query does not filter on the
+new column. It then reads no principal evidence and can submit the child as the parent's actor; its
+older fenced insert also does not compare the principal. Depending on which version handles the stage, it can be
+rejected after its intent is lost or the child can complete under the wrong actor. Running migration
+14 before step 2 also matters for principal-less stages because this Host version names the columns
+when staging and dispatching them.
 
 Each claimed row goes through one settlement sequence (`dispatchStagedRow` in `src/host.ts`):
 
 1. Host renews the claim's lease, skipping the row if the lease is gone, and looks the child up by
-   `stagedOrigin` in the parent's tenant and space. Every claim replaces the lease token, so a
+   `stagedOrigin` in the parent's tenant and space. Each claim replaces the lease token, so a
    creation still in flight from an earlier attempt holds an older token and fails the creation
    fence; this lookup therefore settles what earlier attempts did. A child found here goes to step 4
    without the pre-submission checks or any entitlement, authorization, or admission call.
 2. With no child, Host checks that the parent is still `completed` and that the child action is
    still registered, does not require capture-time authority, and accepts the stored parameters. It
-   then submits through the shared submission pipeline under the claim's lease token, bounded by
-   `submissionTimeoutMs`.
+   resolves any recorded principal against the current Host registration, then submits through the
+   shared submission pipeline under the claim's lease token, bounded by `submissionTimeoutMs`.
+   Entitlement, submission authorization, admission, and execution authorization all evaluate the
+   registered principal just as they do for any other submission.
 3. If that submission's own fenced create returned the child, Host settles with its ID: `dispatched`
    when the handoff succeeded or no dispatcher is configured, otherwise a retry that records the ID
    (`dead_lettered` once the attempt budget is spent). In every other case (a failed pre-submission
    check, a refusal, an error, or a timeout) Host first rotates the lease token with
-   `rotateStagedInvocationLease`. The only other possible creator is this attempt's own timed-out
+   `rotateStagedInvocationLease`. The remaining possible creator is this attempt's own timed-out
    submission, which still holds the old token, so after the rotation it can no longer create the
    child and the lookup that follows is authoritative. A child found there goes to step 4. With none,
    a definitive refusal settles `rejected`, and anything else settles for retry or, at the attempt

package/dist/index.cjs

@@ -1375,6 +1375,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.");
@@ -1394,6 +1395,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}".`);
@@ -1408,24 +1411,27 @@ function prepareStagedInvocationBatch(input) {
 		if (byteLength((0, _fabricorg_platform.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((0, _fabricorg_platform.canonicalJson)(batchIdentity)) > 262144) throw new Error(`stagedInvocations batch exceeds ${MAX_STAGED_INVOCATION_BATCH_BYTES} bytes.`);
 	const batchDigest = digestParameters({
@@ -1460,7 +1466,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) {
@@ -1527,6 +1534,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" || !(0, _fabricorg_platform.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);
@@ -1560,6 +1581,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.");
@@ -2703,6 +2727,7 @@ function createGovernedActionHost(options) {
 							parentAction: action,
 							requests: rawStagedInvocations,
 							resolveAction: actionResolver,
+							stagedInvocationPrincipals,
 							redactParameters: options.redactActionParameters,
 							now: now()
 						});
@@ -3574,6 +3599,7 @@ function createGovernedActionHost(options) {
 									parentAction: action,
 									requests: stagedRequests,
 									resolveAction: actionResolver,
+									stagedInvocationPrincipals,
 									redactParameters: options.redactActionParameters,
 									redactedKeys: handlerStagedInvocations.map((request) => request.key),
 									now: now()
@@ -4144,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({
@@ -4151,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: {
@@ -4166,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,
@@ -4836,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,
@@ -5684,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;
+			`
 			}
 		]);
 	}
@@ -5748,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,
@@ -5777,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,
@@ -5789,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
@@ -5800,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]) {
@@ -5852,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) {
@@ -6899,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 } : {},
@@ -6945,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),
@@ -8444,6 +8495,7 @@ exports.PLATFORM_HOST_HEALTH_CONTRACT_VERSION = PLATFORM_HOST_HEALTH_CONTRACT_VE
 exports.PLATFORM_HOST_METRIC_NAMES = PLATFORM_HOST_METRIC_NAMES;
 exports.PostgresPlatformHostStore = PostgresPlatformHostStore;
 exports.STAGED_INVOCATION_KEY_PATTERN = STAGED_INVOCATION_KEY_PATTERN;
+exports.STAGED_INVOCATION_PRINCIPAL_PATTERN = STAGED_INVOCATION_PRINCIPAL_PATTERN;
 exports.SubmissionRefusalError = SubmissionRefusalError;
 exports.applyPostgresMigrations = applyPostgresMigrations;
 exports.asStagedInvocationStore = asStagedInvocationStore;