@fabricorg/platform-host 8.5.0 → 8.7.0

package/dist/index.cjs

@@ -297,6 +297,52 @@ async function appendLifecycleEvent(transaction, factory, invocation, kind) {
 	}, metadata);
 }
 //#endregion
+//#region src/agent-proposal.ts
+/** Validate without invoking getters or retaining caller-owned evidence. */
+function snapshotAgentProposal(value) {
+	const invalid = () => {
+		throw new Error("Invalid agent proposal.");
+	};
+	if (!value || typeof value !== "object" || Array.isArray(value) || util.types.isProxy(value)) return invalid();
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return invalid();
+	const allowed = [
+		"confidence",
+		"riskTier",
+		"agentSessionId",
+		"agentRunId",
+		"reason",
+		"evidence"
+	];
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (typeof key !== "string" || !allowed.includes(key) || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) return invalid();
+	}
+	if (value.confidence !== void 0 && (typeof value.confidence !== "number" || !Number.isFinite(value.confidence))) return invalid();
+	if (value.riskTier !== void 0 && ![
+		"low",
+		"medium",
+		"high"
+	].includes(value.riskTier)) return invalid();
+	for (const key of [
+		"agentSessionId",
+		"agentRunId",
+		"reason"
+	]) {
+		const field = value[key];
+		if (field !== void 0 && (typeof field !== "string" || field.length > (key === "reason" ? 4096 : 256) || key !== "reason" && field.trim().length === 0)) return invalid();
+	}
+	const evidence = snapshotApprovalDecision({
+		approved: true,
+		approverId: "proposal",
+		approverType: "agent",
+		...value.evidence !== void 0 ? { evidence: value.evidence } : {}
+	}).evidence;
+	return {
+		...value,
+		...evidence !== void 0 ? { evidence } : {}
+	};
+}
+//#endregion
 //#region src/command-identity.ts
 const PARAMETER_DIGEST_ALGORITHM = "fabric-canonical-json-sha256-v1";
 function digestParameters(parameters) {
@@ -1002,7 +1048,11 @@ function snapshotSubmission(input) {
 	const executionReason = scalar("executionReason");
 	const idempotencyKey = scalar("idempotencyKey");
 	const authorizationBindingId = scalar("authorizationBindingId");
+	const proposal = input.agentProposal;
+	if (proposal !== void 0 && actorType !== "agent") throw new Error("Agent proposal requires an agent actor.");
+	const agentProposal = proposal === void 0 ? void 0 : snapshotAgentProposal(proposal);
 	const live = {
+		...agentProposal !== void 0 ? { agentProposal } : {},
 		actionId,
 		tenantId,
 		spaceId,
@@ -1071,6 +1121,7 @@ function privateSubmission(snapshot) {
 	const provenance = provenanceRead ? copyProvenance(provenanceRead) : void 0;
 	const authorizationBinding = bindingRead ? copyBinding(bindingRead) : void 0;
 	return Object.freeze({
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshot.agentProposal } : {},
 		actionId: snapshot.actionId,
 		tenantId: snapshot.tenantId,
 		spaceId: snapshot.spaceId,
@@ -1167,6 +1218,7 @@ function parametersCopy(snapshot) {
 */
 function liveSubmissionView(snapshot, input) {
 	const view = {
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshotAgentProposal(snapshot.agentProposal) } : {},
 		actionId: snapshot.actionId,
 		tenantId: snapshot.tenantId,
 		spaceId: snapshot.spaceId,
@@ -1208,6 +1260,7 @@ function submissionView(snapshot) {
 	const provenance = fresh(snapshot.provenance);
 	const authorizationBinding = fresh(snapshot.authorizationBinding);
 	return {
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshotAgentProposal(snapshot.agentProposal) } : {},
 		actionId: snapshot.actionId,
 		parameters: parametersCopy(snapshot),
 		tenantId: snapshot.tenantId,
@@ -1322,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.");
@@ -1341,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}".`);
@@ -1355,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({
@@ -1407,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) {
@@ -1474,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);
@@ -1507,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.");
@@ -1544,7 +1621,8 @@ function createGovernedActionHost(options) {
 			if (submission.authorizationBinding) validateAuthorizationBinding(submission, parameterDigest, action.execution?.authorityMoment, now());
 			return {
 				durableParameters,
-				parameterDigest
+				parameterDigest,
+				agentProposal: submission.agentProposal === void 0 ? void 0 : snapshotAgentProposal(options.redactAgentProposal ? options.redactAgentProposal(submission.actionId, submission.agentProposal) : submission.agentProposal)
 			};
 		};
 		const early = declaresAdmission ? void 0 : prepare();
@@ -1559,9 +1637,10 @@ function createGovernedActionHost(options) {
 		};
 		(0, _fabricorg_platform.assertGovernanceRuntimeEvidence)(runtimeEvidence);
 		const admission = declaresAdmission ? await admitSubmission(action, submission) : void 0;
-		const { durableParameters, parameterDigest } = early ?? prepare();
+		const { durableParameters, parameterDigest, agentProposal } = early ?? prepare();
 		const invocationInput = {
 			id: actionInvocationId,
+			...agentProposal !== void 0 ? { agentProposal } : {},
 			tenantId: submission.tenantId,
 			spaceId: submission.spaceId,
 			actionId: submission.actionId,
@@ -1615,6 +1694,7 @@ function createGovernedActionHost(options) {
 		});
 		if (durableInvocation.id !== actionInvocationId && submission.idempotencyKey) {
 			const conflict = idempotencyConflict(durableInvocation, {
+				agentProposal,
 				actorId: submission.actorId,
 				authorizationBindingId: submission.authorizationBindingId,
 				actionVersion: action.version,
@@ -2336,21 +2416,24 @@ function createGovernedActionHost(options) {
 			}
 			if (invocation.actorType === "agent" && options.hitlEvaluator) {
 				const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
+				const proposal = invocation.agentProposal;
 				const approvalStore = asApprovalStore(options.store);
 				if (!approvalStore) return hostOperation(() => failExecution(invocation, "failed", "The configured HITL evaluator requires a store with approval persistence support."));
 				let evaluatedApprovalExpiresAt;
 				if (!invocation.hitlRoute) {
 					const decision = await options.hitlEvaluator({
+						actionInvocationId: invocation.id,
+						invocation,
 						actionId: action.actionId,
 						actorId: invocation.actorId,
 						actorType: invocation.actorType,
 						tenantId,
 						spaceId,
 						parameters: hitlParameters,
-						...numberValue(hitlParameters.confidence) !== void 0 ? { confidence: numberValue(hitlParameters.confidence) } : {},
-						...isRiskTier(hitlParameters.riskTier) ? { riskTier: hitlParameters.riskTier } : {},
-						...stringValue(hitlParameters.agentSessionId) ? { agentSessionId: stringValue(hitlParameters.agentSessionId) } : {},
-						...stringValue(hitlParameters.agentRunId) ? { agentRunId: stringValue(hitlParameters.agentRunId) } : {}
+						...(proposal?.confidence ?? numberValue(hitlParameters.confidence)) !== void 0 ? { confidence: proposal?.confidence ?? numberValue(hitlParameters.confidence) } : {},
+						...isRiskTier(proposal?.riskTier ?? hitlParameters.riskTier) ? { riskTier: proposal?.riskTier ?? hitlParameters.riskTier } : {},
+						...proposal?.agentSessionId ?? stringValue(hitlParameters.agentSessionId) ? { agentSessionId: proposal?.agentSessionId ?? stringValue(hitlParameters.agentSessionId) } : {},
+						...proposal?.agentRunId ?? stringValue(hitlParameters.agentRunId) ? { agentRunId: proposal?.agentRunId ?? stringValue(hitlParameters.agentRunId) } : {}
 					});
 					if (decision.approvalExpiresAt !== void 0 && !validApprovalDate(decision.approvalExpiresAt)) return hostOperation(() => failExecution(invocation, "failed", "approvalExpiresAt must be a valid Date."));
 					evaluatedApprovalExpiresAt = decision.approvalExpiresAt === void 0 ? void 0 : new Date(decision.approvalExpiresAt);
@@ -2644,6 +2727,7 @@ function createGovernedActionHost(options) {
 							parentAction: action,
 							requests: rawStagedInvocations,
 							resolveAction: actionResolver,
+							stagedInvocationPrincipals,
 							redactParameters: options.redactActionParameters,
 							now: now()
 						});
@@ -3515,6 +3599,7 @@ function createGovernedActionHost(options) {
 									parentAction: action,
 									requests: stagedRequests,
 									resolveAction: actionResolver,
+									stagedInvocationPrincipals,
 									redactParameters: options.redactActionParameters,
 									redactedKeys: handlerStagedInvocations.map((request) => request.key),
 									now: now()
@@ -4085,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({
@@ -4092,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: {
@@ -4107,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,
@@ -4314,6 +4402,7 @@ function validateAuthorizationBinding(input, parameterDigest, authorityMoment, c
 }
 function idempotencyConflict(existing, incoming) {
 	const reasons = [];
+	if ((0, _fabricorg_platform.canonicalJson)(existing.agentProposal ?? null) !== (0, _fabricorg_platform.canonicalJson)(incoming.agentProposal ?? null)) reasons.push("agent_proposal");
 	if ((existing.idempotencyActorId ?? existing.actorId) !== incoming.actorId) reasons.push("actor");
 	if ((existing.idempotencyAuthorizationBindingId ?? existing.authorizationBindingId) !== incoming.authorizationBindingId) reasons.push("authority_binding");
 	if (existing.actionVersion !== incoming.actionVersion) reasons.push("action_version");
@@ -4776,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,
@@ -5619,6 +5708,21 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 					ON fabric_platform.action_invocations (approval_expires_at, id)
 					WHERE status='waiting_for_approval' AND approval_expires_at IS NOT NULL;
 			`
+			},
+			{
+				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;
+			`
 			}
 		]);
 	}
@@ -5630,6 +5734,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		const admitted = input.admittedAt !== void 0;
 		const admittedColumn = admitted ? "admitted_at," : "";
 		const admittedValue = admitted ? "$25," : "";
+		const proposalColumn = input.agentProposal !== void 0 ? "agent_proposal," : "";
+		const proposalValue = input.agentProposal !== void 0 ? `$${admitted ? 26 : 25}::jsonb,` : "";
 		let result;
 		try {
 			result = await this.sql.query(`INSERT INTO fabric_platform.action_invocations
@@ -5637,8 +5743,8 @@ 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,${admittedColumn}created_at,updated_at)
-				 VALUES ($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,${admittedValue}$24,$24)
+				  authorization_binding_id,error,runtime_evidence,${admittedColumn}${proposalColumn}created_at,updated_at)
+				 VALUES ($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,${admittedValue}${proposalValue}$24,$24)
 				 ON CONFLICT (tenant_id,space_id,action_id,idempotency_key)
 				 WHERE idempotency_key IS NOT NULL DO UPDATE SET id=fabric_platform.action_invocations.id
 				 RETURNING *`, [
@@ -5666,9 +5772,11 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				input.error ?? null,
 				input.runtimeEvidence ? JSON.stringify(input.runtimeEvidence) : null,
 				now,
-				...admitted ? [input.admittedAt] : []
+				...admitted ? [input.admittedAt] : [],
+				...input.agentProposal !== void 0 ? [JSON.stringify(input.agentProposal)] : []
 			]);
 		} catch (error) {
+			if (input.agentProposal !== void 0 && error?.code === "42703") throw new Error("Agent proposals require PostgreSQL migration 13 (agent_proposal); run ensureSchema().", { cause: error });
 			if (admitted && error?.code === "42703") throw new Error("An admitted invocation needs the action_invocations.admitted_at column; run ensureSchema() to apply PostgreSQL migration 6 (invocation_admission) before submitting actions that declare admitSubmission.", { cause: error });
 			throw error;
 		}
@@ -5679,7 +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 ? 32 : 31}::jsonb` : "";
 		const values = [
 			invocation.id,
 			invocation.tenantId,
@@ -5706,21 +5816,24 @@ 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,
 			current,
-			...admitted ? [invocation.admittedAt] : []
+			...admitted ? [invocation.admittedAt] : [],
+			...invocation.agentProposal !== void 0 ? [JSON.stringify(invocation.agentProposal)] : []
 		];
 		let result;
 		try {
 			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
@@ -5728,16 +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},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},$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 (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]) {
@@ -5779,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) {
@@ -6826,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 } : {},
@@ -6856,6 +6979,7 @@ function toActionRecord(row) {
 		...row.mutation_footprint ? { mutationFootprint: row.mutation_footprint } : {},
 		...row.execution_principal ? { executionPrincipal: row.execution_principal } : {},
 		...row.runtime_evidence ? { runtimeEvidence: row.runtime_evidence } : {},
+		...row.agent_proposal != null ? { agentProposal: row.agent_proposal } : {},
 		...row.admitted_at ? { admittedAt: new Date(row.admitted_at) } : {},
 		...row.error ? { error: String(row.error) } : {},
 		createdAt: new Date(row.created_at),
@@ -6871,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),
@@ -8370,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;