@fabricorg/platform-host 8.4.0 → 8.5.0

package/dist/index.js

@@ -1,8 +1,102 @@
+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 { performance } from "perf_hooks";
 import { assertAssemblyRuntimeCompatible } from "@fabricorg/assembly";
 import { createHash } from "crypto";
-import { types } from "util";
+//#region src/action-finalization.ts
+/** Remove private preparation and restore its compatible protocol on settlement. */
+function finalizationSettlementPatch(record, patch) {
+	const checkpoint = Object.hasOwn(patch, "finalizationCheckpoint") ? patch.finalizationCheckpoint : record.finalizationCheckpoint;
+	if (!checkpoint || !patch.status || ![
+		"completed",
+		"failed",
+		"blocked_by_policy",
+		"validation_failed"
+	].includes(patch.status) || !Object.hasOwn(checkpoint, "adapterPreparation") && checkpoint.protocol !== "atomic-after-adapters-v2") return patch;
+	const { adapterPreparation: _preparation, ...evidence } = checkpoint;
+	return {
+		...patch,
+		finalizationCheckpoint: {
+			...evidence,
+			protocol: "atomic-after-adapters-v1"
+		}
+	};
+}
+/** Strict JSON evidence: reject lossy serialization rather than silently dropping values. */
+function finalizationJson(value) {
+	const ancestors = /* @__PURE__ */ new Set();
+	function check(item) {
+		if (item === null || typeof item === "string" || typeof item === "boolean") return;
+		if (typeof item === "number" && Number.isFinite(item)) return;
+		if (typeof item !== "object" || !item || ancestors.has(item)) throw new Error("Finalization requires JSON-compatible data.");
+		if (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null) throw new Error("Finalization requires plain JSON objects.");
+		if (Object.getOwnPropertySymbols(item).length > 0) throw new Error("Finalization requires JSON string keys.");
+		if (Array.isArray(item)) {
+			const keys = Object.keys(item);
+			if (keys.length !== item.length || keys.some((key, index) => key !== String(index))) throw new Error("Finalization requires dense JSON arrays.");
+		}
+		ancestors.add(item);
+		for (const child of Object.values(item)) check(child);
+		ancestors.delete(item);
+	}
+	check(value);
+	return JSON.parse(JSON.stringify(value));
+}
+/** Match the persisted JSON representation before validating finalization execution input. */
+function normalizeFinalizationJson(value) {
+	return finalizationJson(JSON.parse(JSON.stringify(value)));
+}
+/** Omit only public optional fields; payloads and patch values retain strict JSON validation. */
+function omitUndefinedOptionalFields(value, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return value;
+	const copy = { ...value };
+	for (const key of keys) if (Object.hasOwn(copy, key) && copy[key] === void 0) delete copy[key];
+	return copy;
+}
+function validateFinalization(value, action, privateFields, contracts) {
+	const normalized = omitUndefinedOptionalFields(value, [
+		"events",
+		"resultPatch",
+		"stagedInvocations"
+	]);
+	if (normalized !== value && normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
+		const record = normalized;
+		if (Array.isArray(record.events)) {
+			const events = Object.assign(record.events.slice(), record.events);
+			for (let index = 0; index < events.length; index++) if (Object.hasOwn(events, index)) events[index] = omitUndefinedOptionalFields(events[index], ["eventSchemaVersion"]);
+			record.events = events;
+		}
+	}
+	const result = finalizationJson(normalized);
+	if (!result || typeof result !== "object" || Array.isArray(result) || Object.keys(result).some((key) => key !== "events" && key !== "resultPatch" && key !== "stagedInvocations")) throw new Error("Finalization must return only events, resultPatch and stagedInvocations.");
+	if (result.resultPatch !== void 0) {
+		if (!result.resultPatch || typeof result.resultPatch !== "object" || Array.isArray(result.resultPatch)) throw new Error("Finalization resultPatch must be an object.");
+		if (Object.keys(result.resultPatch).some((key) => privateFields.includes(key))) throw new Error("Finalization resultPatch contains a private result key.");
+	}
+	if (result.events !== void 0) {
+		if (!Array.isArray(result.events)) throw new Error("Finalization events must be an array.");
+		for (const event of result.events) {
+			if (!event || typeof event !== "object" || Array.isArray(event) || Object.keys(event).some((key) => ![
+				"eventType",
+				"subjectType",
+				"subjectId",
+				"payload",
+				"eventSchemaVersion"
+			].includes(key))) throw new Error("Invalid finalization event fields.");
+			for (const key of [
+				"eventType",
+				"subjectType",
+				"subjectId"
+			]) if (typeof event[key] !== "string" || !event[key].trim()) throw new Error("Finalization event identifiers must be non-empty.");
+			if (!Object.hasOwn(event, "payload")) throw new Error("Finalization event requires a JSON payload.");
+			if (event.eventSchemaVersion !== void 0 && (!Number.isInteger(event.eventSchemaVersion) || event.eventSchemaVersion <= 0)) throw new Error("Finalization eventSchemaVersion must be a positive integer.");
+			if (!action.emitsEvents.includes(event.eventType)) throw new Error("Finalization emitted undeclared event type.");
+			if (contracts && (!contracts.hasEventType(event.eventType) || !contracts.hasSubjectType(event.subjectType))) throw new Error("Finalization emitted an unregistered event or subject type.");
+		}
+	}
+	return result;
+}
+//#endregion
 //#region src/types.ts
 /** Durable Host lifecycle generation, independent from the npm package version. */
 const PLATFORM_HOST_CONTRACT_VERSION = 2;
@@ -68,6 +162,139 @@ var ExternalCompletionError = class extends Error {
 		return this.refusal === "still_executing";
 	}
 };
+/** Maximum serialized UTF-8 evidence size. */
+const MAX_APPROVAL_EVIDENCE_BYTES = 16384;
+const APPROVAL_REQUESTED_EVENT = "ApprovalRequested";
+const APPROVAL_DECIDED_EVENT = "ApprovalDecided";
+const APPROVAL_EXPIRED_EVENT = "ApprovalExpired";
+//#endregion
+//#region src/approval-lifecycle.ts
+function validApprovalDate(value) {
+	return value instanceof Date && Number.isFinite(value.getTime());
+}
+/** Snapshot before awaiting application authorization; reject lossy JSON conversions. */
+function snapshotApprovalDecision(decision) {
+	const visit = (value, ancestors, depth) => {
+		if (value === null || typeof value === "string" || typeof value === "boolean") return;
+		if (typeof value === "number" && Number.isFinite(value)) return;
+		if (typeof value !== "object" || types.isProxy(value)) throw new Error("Approval evidence must be plain JSON data.");
+		if (ancestors.includes(value)) throw new Error("Approval evidence must not contain cycles.");
+		if (depth > 64) throw new Error("Approval evidence exceeds maximum depth 64.");
+		const array = Array.isArray(value);
+		if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error("Approval evidence must contain only plain objects and JSON values.");
+		const keys = Reflect.ownKeys(value);
+		if (array && keys.length !== value.length + 1) throw new Error("Approval evidence arrays must be dense JSON arrays.");
+		for (const key of keys) {
+			if (array && key === "length") continue;
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			if (typeof key !== "string" || !descriptor.enumerable || !Object.hasOwn(descriptor, "value") || array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new Error("Approval evidence must contain enumerable JSON data properties only.");
+			visit(descriptor.value, [...ancestors, value], depth + 1);
+		}
+	};
+	if (types.isProxy(decision)) throw new Error("Approval decision must be plain data.");
+	for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(decision))) if (!Object.hasOwn(descriptor, "value")) throw new Error("Approval decision must be plain data.");
+	if (decision.evidence !== void 0) {
+		if (!decision.evidence || typeof decision.evidence !== "object" || Array.isArray(decision.evidence)) throw new Error("Approval evidence must be a JSON object.");
+		visit(decision.evidence, [], 0);
+		if (Buffer.byteLength(JSON.stringify(decision.evidence), "utf8") > 16384) throw new Error(`Approval evidence exceeds ${MAX_APPROVAL_EVIDENCE_BYTES} bytes.`);
+	}
+	if (decision.decidedAt !== void 0 && !validApprovalDate(decision.decidedAt)) throw new Error("decidedAt must be a valid Date.");
+	return structuredClone(decision);
+}
+function approvalSweepLimit(input) {
+	if (!validApprovalDate(input.now)) throw new Error("Approval sweep now must be a valid Date.");
+	const limit = input.limit ?? 100;
+	if (!Number.isInteger(limit) || limit < 1 || limit > 1e3) throw new Error("Approval sweep limit must be an integer from 1 to 1000.");
+	return limit;
+}
+function approvalExpiredPatch(record, now) {
+	return finalizationSettlementPatch(record, {
+		status: "failed",
+		approvalDecision: void 0,
+		approvalExpiry: {
+			expiresAt: new Date(record.approvalExpiresAt),
+			expiredAt: new Date(now)
+		},
+		error: "Approval expired before a decision was applied."
+	});
+}
+/** Both stores serialize this read, event append, and update within their mutation transaction. */
+async function applyApprovalTransition(transaction, input, kind) {
+	if (!transaction.getActionInvocationForUpdate) throw new Error("Approval transitions require locking invocation reads.");
+	const record = await transaction.getActionInvocationForUpdate(input.actionInvocationId, input.tenantId, input.spaceId);
+	if (!record) return { applied: false };
+	if (kind === "decided" && transaction.beginApprovalDecision) {
+		const { lifecycleEvent, ...decisionInput } = input;
+		const result = await transaction.beginApprovalDecision(decisionInput);
+		if (result.applied && result.invocation) await appendLifecycleEvent(transaction, lifecycleEvent, result.invocation, result.invocation.approvalExpiry ? "expired" : "decided");
+		return result;
+	}
+	let patch;
+	if (kind === "requested") {
+		if (!["pending", "running"].includes(record.status) || record.approvalDecision !== void 0 || record.leaseOwner !== void 0 && (record.leaseOwner !== input.leaseOwner || record.leaseToken !== input.leaseToken)) return {
+			applied: false,
+			invocation: record
+		};
+		patch = {
+			status: "waiting_for_approval",
+			...Object.hasOwn(input, "approvalExpiresAt") ? { approvalExpiresAt: input.approvalExpiresAt } : {}
+		};
+	} else {
+		if (record.status !== "waiting_for_approval") return {
+			applied: false,
+			invocation: record
+		};
+		const due = record.approvalExpiresAt !== void 0 && record.approvalExpiresAt.getTime() <= input.now.getTime();
+		if (kind === "expired" && !due) return {
+			applied: false,
+			invocation: record
+		};
+		if (due) {
+			kind = "expired";
+			patch = approvalExpiredPatch(record, input.now);
+		} else {
+			const decisionInput = input;
+			patch = decisionInput.decision.approved ? {
+				status: "running",
+				error: void 0,
+				approvalDecision: structuredClone(decisionInput.decision),
+				leaseOwner: decisionInput.leaseOwner,
+				leaseToken: (record.leaseToken ?? 0) + 1,
+				leaseExpiresAt: new Date(input.now.getTime() + decisionInput.leaseDurationMs),
+				attemptCount: Math.max(record.attemptCount, 1)
+			} : finalizationSettlementPatch(record, {
+				status: "failed",
+				approvalDecision: structuredClone(decisionInput.decision),
+				error: `Approval rejected: ${decisionInput.decision.reason ?? "no reason provided"}`
+			});
+		}
+	}
+	const transitioned = {
+		...record,
+		...patch,
+		updatedAt: new Date(input.now)
+	};
+	if (Object.hasOwn(patch, "approvalDecision") && patch.approvalDecision === void 0) delete transitioned.approvalDecision;
+	if (transitioned.status !== "running") {
+		delete transitioned.leaseOwner;
+		delete transitioned.leaseExpiresAt;
+	}
+	await appendLifecycleEvent(transaction, input.lifecycleEvent, transitioned, kind);
+	await transaction.updateActionInvocation(record.id, record.tenantId, record.spaceId, patch);
+	return {
+		applied: true,
+		invocation: transitioned
+	};
+}
+async function appendLifecycleEvent(transaction, factory, invocation, kind) {
+	if (!factory) return;
+	if (!transaction.appendEventWithOutbox) throw new Error("Approval events require atomic outbox writes.");
+	const { event, metadata } = factory(invocation, kind);
+	await transaction.appendEventWithOutbox({
+		...event,
+		sequence: await transaction.nextEventSequence(invocation.tenantId, invocation.spaceId)
+	}, metadata);
+}
 //#endregion
 //#region src/command-identity.ts
 const PARAMETER_DIGEST_ALGORITHM = "fabric-canonical-json-sha256-v1";
@@ -107,82 +334,6 @@ function normalizeProvenance(input, options) {
 	};
 }
 //#endregion
-//#region src/action-finalization.ts
-/** Strict JSON evidence: reject lossy serialization rather than silently dropping values. */
-function finalizationJson(value) {
-	const ancestors = /* @__PURE__ */ new Set();
-	function check(item) {
-		if (item === null || typeof item === "string" || typeof item === "boolean") return;
-		if (typeof item === "number" && Number.isFinite(item)) return;
-		if (typeof item !== "object" || !item || ancestors.has(item)) throw new Error("Finalization requires JSON-compatible data.");
-		if (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null) throw new Error("Finalization requires plain JSON objects.");
-		if (Object.getOwnPropertySymbols(item).length > 0) throw new Error("Finalization requires JSON string keys.");
-		if (Array.isArray(item)) {
-			const keys = Object.keys(item);
-			if (keys.length !== item.length || keys.some((key, index) => key !== String(index))) throw new Error("Finalization requires dense JSON arrays.");
-		}
-		ancestors.add(item);
-		for (const child of Object.values(item)) check(child);
-		ancestors.delete(item);
-	}
-	check(value);
-	return JSON.parse(JSON.stringify(value));
-}
-/** Match the persisted JSON representation before validating finalization execution input. */
-function normalizeFinalizationJson(value) {
-	return finalizationJson(JSON.parse(JSON.stringify(value)));
-}
-/** Omit only public optional fields; payloads and patch values retain strict JSON validation. */
-function omitUndefinedOptionalFields(value, keys) {
-	if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return value;
-	const copy = { ...value };
-	for (const key of keys) if (Object.hasOwn(copy, key) && copy[key] === void 0) delete copy[key];
-	return copy;
-}
-function validateFinalization(value, action, privateFields, contracts) {
-	const normalized = omitUndefinedOptionalFields(value, [
-		"events",
-		"resultPatch",
-		"stagedInvocations"
-	]);
-	if (normalized !== value && normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
-		const record = normalized;
-		if (Array.isArray(record.events)) {
-			const events = Object.assign(record.events.slice(), record.events);
-			for (let index = 0; index < events.length; index++) if (Object.hasOwn(events, index)) events[index] = omitUndefinedOptionalFields(events[index], ["eventSchemaVersion"]);
-			record.events = events;
-		}
-	}
-	const result = finalizationJson(normalized);
-	if (!result || typeof result !== "object" || Array.isArray(result) || Object.keys(result).some((key) => key !== "events" && key !== "resultPatch" && key !== "stagedInvocations")) throw new Error("Finalization must return only events, resultPatch and stagedInvocations.");
-	if (result.resultPatch !== void 0) {
-		if (!result.resultPatch || typeof result.resultPatch !== "object" || Array.isArray(result.resultPatch)) throw new Error("Finalization resultPatch must be an object.");
-		if (Object.keys(result.resultPatch).some((key) => privateFields.includes(key))) throw new Error("Finalization resultPatch contains a private result key.");
-	}
-	if (result.events !== void 0) {
-		if (!Array.isArray(result.events)) throw new Error("Finalization events must be an array.");
-		for (const event of result.events) {
-			if (!event || typeof event !== "object" || Array.isArray(event) || Object.keys(event).some((key) => ![
-				"eventType",
-				"subjectType",
-				"subjectId",
-				"payload",
-				"eventSchemaVersion"
-			].includes(key))) throw new Error("Invalid finalization event fields.");
-			for (const key of [
-				"eventType",
-				"subjectType",
-				"subjectId"
-			]) if (typeof event[key] !== "string" || !event[key].trim()) throw new Error("Finalization event identifiers must be non-empty.");
-			if (!Object.hasOwn(event, "payload")) throw new Error("Finalization event requires a JSON payload.");
-			if (event.eventSchemaVersion !== void 0 && (!Number.isInteger(event.eventSchemaVersion) || event.eventSchemaVersion <= 0)) throw new Error("Finalization eventSchemaVersion must be a positive integer.");
-			if (!action.emitsEvents.includes(event.eventType)) throw new Error("Finalization emitted undeclared event type.");
-			if (contracts && (!contracts.hasEventType(event.eventType) || !contracts.hasSubjectType(event.subjectType))) throw new Error("Finalization emitted an unregistered event or subject type.");
-		}
-	}
-	return result;
-}
-//#endregion
 //#region src/observability.ts
 /** Version of the vendor-neutral health/readiness contract. */
 const PLATFORM_HOST_HEALTH_CONTRACT_VERSION = 1;
@@ -589,7 +740,7 @@ function createExternalCompletionLifecycle(deps) {
 				externalCompletion,
 				pendingCompletion: void 0
 			};
-			await writer.update(patch);
+			await writer.update(finalizationSettlementPatch(invocation, patch));
 			if (settles) emitInvocationStatusTelemetry(invocation, "completed", deps.telemetry, now(), invocation.status);
 			return withConsistency(actionResult({
 				...invocation,
@@ -626,7 +777,7 @@ function createExternalCompletionLifecycle(deps) {
 			externalCompletion,
 			pendingCompletion: void 0
 		};
-		await writer.update(patch);
+		await writer.update(finalizationSettlementPatch(invocation, patch));
 		if (settles) emitInvocationStatusTelemetry(invocation, "failed", deps.telemetry, now(), invocation.status);
 		return withConsistency(actionResult({
 			...invocation,
@@ -1322,6 +1473,11 @@ const STAGED_ERROR = Object.freeze({
 	lookup: "Staged child lookup failed."
 });
 function createGovernedActionHost(options) {
+	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);
+		if (!approvalStore || approvalStore.transactionalApprovalLifecycle !== true || typeof approvalStore.parkApproval !== "function" || typeof approvalStore.expireDueApprovals !== "function" || asOutboxStore(options.store)?.transactionalOutbox !== true || !asAtomicMutationStore(options.store)) throw new Error("Approval lifecycle events require transactionalOutbox, transactionWithEvents, and atomic approval lifecycle capabilities.");
+	}
 	const retryableExecutionMaxAttempts = options.retryableExecutionMaxAttempts ?? 5;
 	if (!Number.isInteger(retryableExecutionMaxAttempts) || retryableExecutionMaxAttempts <= 0) throw new Error("retryableExecutionMaxAttempts must be a positive integer.");
 	const recoveryMaxAttempts = options.recoveryMaxAttempts ?? Math.max(5, retryableExecutionMaxAttempts);
@@ -1697,6 +1853,7 @@ function createGovernedActionHost(options) {
 			};
 		}
 		async function persistExecutionInvocation(record, patch) {
+			patch = finalizationSettlementPatch(record, patch);
 			const externalCompletionDigest = record.externalCompletion?.digest;
 			if (await persistInvocation(record, patch, onPreservedReconciliation, executionLease)) rememberVerdict(patch, externalCompletionDigest);
 		}
@@ -2109,7 +2266,7 @@ function createGovernedActionHost(options) {
 		}
 		const replayCheckpoint = action.finalize && (resumingRunningInvocation || invocation.attemptCount > 1) ? invocation.finalizationCheckpoint : void 0;
 		if (replayCheckpoint) {
-			if (replayCheckpoint.protocol !== "atomic-after-adapters-v1" || replayCheckpoint.actionVersion !== action.version || replayCheckpoint.steps.length !== (action.adapterSteps ?? []).length || replayCheckpoint.steps.some((step, index) => step.adapterType !== action.adapterSteps[index]?.adapterType || step.operation !== action.adapterSteps[index]?.operation) || invocation.pendingCompletion) return interruptedNonIdempotent("Finalization checkpoint protocol, action version, step identity or handoff is incompatible with replay.");
+			if (!["atomic-after-adapters-v1", "atomic-after-adapters-v2"].includes(replayCheckpoint.protocol) || replayCheckpoint.protocol === "atomic-after-adapters-v2" !== Object.hasOwn(replayCheckpoint, "adapterPreparation") || replayCheckpoint.actionVersion !== action.version || replayCheckpoint.steps.length !== (action.adapterSteps ?? []).length || replayCheckpoint.steps.some((step, index) => step.adapterType !== action.adapterSteps[index]?.adapterType || step.operation !== action.adapterSteps[index]?.operation) || invocation.pendingCompletion) return interruptedNonIdempotent("Finalization checkpoint protocol, action version, step identity or handoff is incompatible with replay.");
 		}
 		if (action.finalize && !replayCheckpoint && (resumingRunningInvocation || invocation.attemptCount > 1) && hasDurableProviderEffect) return interruptedNonIdempotent("Finalizing action recovery requires a preparation checkpoint; reconciliation is required.");
 		if (action.admitSubmission !== void 0 && !isAdmissionTime(invocation.admittedAt)) return hostOperation(() => failExecution(invocation, "failed", `Invocation of ${action.actionId} was not admitted at submission; an action that declares admitSubmission runs only on invocations its check admitted.`));
@@ -2180,6 +2337,7 @@ function createGovernedActionHost(options) {
 				const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
 				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({
 						actionId: action.actionId,
@@ -2193,6 +2351,8 @@ function createGovernedActionHost(options) {
 						...stringValue(hitlParameters.agentSessionId) ? { agentSessionId: stringValue(hitlParameters.agentSessionId) } : {},
 						...stringValue(hitlParameters.agentRunId) ? { 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);
 					invocation = { ...await hostOperation(() => approvalStore.recordHitlDecision(actionInvocationId, tenantId, spaceId, {
 						...decision,
 						...options.hitlPolicyVersion ? { policyVersion: options.hitlPolicyVersion } : {},
@@ -2201,11 +2361,33 @@ function createGovernedActionHost(options) {
 				}
 				if (invocation.hitlRoute === "rejected") return hostOperation(() => failExecution(invocation, "failed", `HITL rejected: ${invocation.hitlReason ?? "no reason provided"}`));
 				if ((invocation.hitlRoute === "needs-approval" || invocation.hitlRoute === "escalate") && !invocation.approvalDecision?.approved) {
-					await hostOperation(() => persistExecutionInvocation(invocation, { status: "waiting_for_approval" }));
-					return {
-						...actionResult(invocation),
-						status: "waiting_for_approval"
-					};
+					const parkedAt = now();
+					const approvalExpiresAt = invocation.approvalExpiresAt ?? evaluatedApprovalExpiresAt ?? (options.approvalDefaultTtlMs !== void 0 ? new Date(parkedAt.getTime() + options.approvalDefaultTtlMs) : void 0);
+					if (evaluatedApprovalExpiresAt !== void 0 && invocation.approvalExpiresAt === void 0) return hostOperation(() => failExecution(invocation, "failed", "The configured HITL evaluator requires a store with approval deadline persistence support."));
+					if (approvalExpiresAt && !validApprovalDate(approvalExpiresAt)) return hostOperation(() => failExecution(invocation, "failed", "Approval deadline exceeds the supported Date range."));
+					if (approvalExpiresAt && (!approvalStore.expireDueApprovals || !approvalStore.parkApproval)) return hostOperation(() => failExecution(invocation, "failed", "Approval deadlines require a store with approval expiry support."));
+					if (approvalStore.parkApproval) {
+						let transition;
+						try {
+							transition = await approvalStore.parkApproval({
+								actionInvocationId,
+								tenantId,
+								spaceId,
+								now: parkedAt,
+								...approvalExpiresAt ? { approvalExpiresAt } : {},
+								...executionLease,
+								...options.approvalLifecycleEvents ? { lifecycleEvent: approvalLifecycleEvent } : {}
+							});
+						} catch (error) {
+							throw new RecoverableFinalizationError(caughtError({
+								actionId: invocation.actionId,
+								source: "execution"
+							}, error));
+						}
+						invocation = transition.invocation ?? await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId) ?? invocation;
+						if (transition.applied) emitInvocationStatusTelemetry(invocation, "waiting_for_approval", options.telemetry, parkedAt);
+					} else await hostOperation(() => persistExecutionInvocation(invocation, { status: "waiting_for_approval" }));
+					return actionResult(invocation);
 				}
 			}
 			const authorizationInput = toAuthorizationInput(action, invocation);
@@ -2438,13 +2620,23 @@ function createGovernedActionHost(options) {
 							...isAdmissionTime(invocation.admittedAt) ? { admittedAt: invocation.admittedAt } : {},
 							db,
 							services: options.services,
-							...action.finalize ? { finalizationProtocol: "atomic-after-adapters-v1" } : {}
+							...action.finalize ? {
+								finalizationProtocol: "atomic-after-adapters-v1",
+								adapterPreparationProtocol: "v1"
+							} : {}
 						}, parsed.data) : {
 							success: true,
 							data: {}
 						};
 						if (!handlerResult.success) throw handlerResult.error != null ? new Error(handlerResult.error) : new HostError("Action handler failed");
 						const handlerData = handlerResult.data ?? {};
+						let adapterPreparation;
+						if (handlerResult.adapterPreparation !== void 0) {
+							if (!action.finalize) throw new HostError("adapterPreparation requires a finalizing action.");
+							const value = handlerResult.adapterPreparation;
+							if (!value || typeof value !== "object" || Array.isArray(value)) throw new HostError("adapterPreparation must be a plain JSON object.");
+							adapterPreparation = finalizationJson(value);
+						}
 						const rawStagedInvocations = handlerResult.stagedInvocations ?? [];
 						const stagedRecords = prepareStagedInvocationBatch({
 							parent: invocation,
@@ -2498,12 +2690,12 @@ function createGovernedActionHost(options) {
 						if (preparedFinalizationInput) {
 							const skipped = [];
 							for (const [index, step] of (action.adapterSteps ?? []).entries()) {
-								const input = step.getInput(structuredClone(preparedFinalizationInput.params), structuredClone(preparedFinalizationInput.handlerData));
+								const input = step.getInput(structuredClone(preparedFinalizationInput.params), structuredClone(preparedFinalizationInput.handlerData), structuredClone(adapterPreparation));
 								preparedInputs.set(index, input);
 								if (!input) skipped.push(index);
 							}
 							preparation = normalizeFinalizationJson({
-								protocol: "atomic-after-adapters-v1",
+								protocol: adapterPreparation !== void 0 ? "atomic-after-adapters-v2" : "atomic-after-adapters-v1",
 								actionVersion: action.version,
 								steps: (action.adapterSteps ?? []).map(({ adapterType, operation }) => ({
 									adapterType,
@@ -2512,6 +2704,7 @@ function createGovernedActionHost(options) {
 								...preparedFinalizationInput,
 								handlerEvents: events,
 								result: preparedFinalizationInput.handlerData,
+								...adapterPreparation !== void 0 ? { adapterPreparation } : {},
 								...transitionEvent ? { stateTransition: transitionEvent } : {},
 								skipped,
 								...handlerStagedInvocations.length > 0 ? { stagedInvocations: handlerStagedInvocations } : {}
@@ -2661,7 +2854,7 @@ function createGovernedActionHost(options) {
 					}, error));
 				}
 				if (previousAdapterInvocation?.status === "ambiguous") return await settleUnknownOutcome(stepIndex, recordedAdapterReconciliation(previousAdapterInvocation), previousAdapterInvocation.reconciliation?.adapterEventSubject);
-				const input = action.finalize ? preparation.skipped.includes(stepIndex) ? void 0 : replayCheckpoint ? step.getInput(structuredClone(replayCheckpoint.params), structuredClone(replayCheckpoint.handlerData)) : preparedInputs.get(stepIndex) : step.getInput(parsed.data, data);
+				const input = action.finalize ? preparation.skipped.includes(stepIndex) ? void 0 : replayCheckpoint ? step.getInput(structuredClone(replayCheckpoint.params), structuredClone(replayCheckpoint.handlerData), structuredClone(replayCheckpoint.adapterPreparation)) : preparedInputs.get(stepIndex) : step.getInput(parsed.data, data);
 				if (!input) {
 					if (action.finalize) finalizationSteps.push({
 						stepIndex,
@@ -3253,14 +3446,14 @@ function createGovernedActionHost(options) {
 				...pendingHandoff,
 				parkedAt: now()
 			} : void 0;
-			const finalPatch = parked ? {
+			const finalPatch = finalizationSettlementPatch(invocation, parked ? {
 				status: "running",
 				result,
 				pendingCompletion: parked
 			} : {
 				status: "completed",
 				result
-			};
+			});
 			let verdictWritten = true;
 			let finalizationCallbackFailure;
 			try {
@@ -3421,6 +3614,7 @@ function createGovernedActionHost(options) {
 		}
 	}
 	async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
+		decision = snapshotApprovalDecision(decision);
 		if (!decision.approverId.trim()) throw new Error("approverId is required");
 		const invocation = await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
 		if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
@@ -3430,7 +3624,13 @@ function createGovernedActionHost(options) {
 			error: `Invocation is not waiting for approval (status: ${invocation.status})`
 		};
 		const action = actionResolver(invocation.actionId);
-		if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+		if (!action) {
+			const error = `Unknown action: ${invocation.actionId}`;
+			return invocation.approvalExpiresAt === void 0 ? fail(invocation, "failed", error) : {
+				...actionResult(invocation),
+				error
+			};
+		}
 		const approvalAuthorizationInput = toAuthorizationInput(action, {
 			tenantId,
 			spaceId,
@@ -3441,7 +3641,7 @@ function createGovernedActionHost(options) {
 		const authorized = options.authorization.authorizeApproval ? await options.authorization.authorizeApproval({
 			...approvalAuthorizationInput,
 			actionInvocationId,
-			decision,
+			decision: structuredClone(decision),
 			invocation: structuredClone(invocation)
 		}) : await options.authorization.authorize(approvalAuthorizationInput);
 		if (!entitled || !authorized) return {
@@ -3466,14 +3666,15 @@ function createGovernedActionHost(options) {
 			},
 			leaseOwner,
 			leaseDurationMs: options.approvalResumeLeaseDurationMs ?? 3e5,
-			now: transitionStartedAt
+			now: transitionStartedAt,
+			...options.approvalLifecycleEvents ? { lifecycleEvent: approvalLifecycleEvent } : {}
 		});
 		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 withConsistency(actionResult(transitioned), transitioned.actionId);
 		}
-		if (!decision.approved) {
+		if (transitioned.approvalExpiry || !decision.approved) {
 			emitInvocationStatusTelemetry(transitioned, "failed", options.telemetry, now(), "waiting_for_approval");
 			return withConsistency(actionResult(transitioned), transitioned.actionId);
 		}
@@ -3525,9 +3726,73 @@ function createGovernedActionHost(options) {
 			consistency
 		} : result;
 	}
-	async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1, transaction) {
-		const timestamp = now();
-		const envelope = {
+	function eventOutboxMetadata(invocation, envelope) {
+		const traceContext = options.outbox?.traceContext?.(envelope);
+		const payloadClassification = options.outbox?.classifyPayload(envelope) ?? "internal";
+		return {
+			producerModuleVersion: options.outbox?.producerModuleVersion(invocation.actionId, invocation.actionVersion) ?? String(invocation.actionVersion),
+			payloadClassification,
+			includeProvenance: options.outbox?.includeProvenance?.(envelope, payloadClassification) ?? payloadClassification !== "restricted",
+			includeActor: options.outbox?.includeActor?.(envelope, payloadClassification) === true,
+			...traceContext ? { traceContext } : {}
+		};
+	}
+	const approvalLifecycleEvent = (invocation, kind) => {
+		let eventType;
+		let payload;
+		if (kind === "requested") {
+			eventType = APPROVAL_REQUESTED_EVENT;
+			payload = {
+				route: invocation.hitlRoute,
+				riskTier: invocation.hitlRiskTier,
+				reason: invocation.hitlReason ?? "",
+				...invocation.approvalExpiresAt ? { expiresAt: invocation.approvalExpiresAt.toISOString() } : {}
+			};
+		} else if (kind === "decided") {
+			eventType = APPROVAL_DECIDED_EVENT;
+			const decision = invocation.approvalDecision;
+			payload = {
+				approved: decision.approved,
+				approverId: decision.approverId,
+				approverType: decision.approverType,
+				...decision.reason !== void 0 ? { reason: decision.reason } : {},
+				decidedAt: decision.decidedAt.toISOString(),
+				evidencePresent: decision.evidence !== void 0
+			};
+		} else {
+			eventType = APPROVAL_EXPIRED_EVENT;
+			payload = {
+				expiresAt: invocation.approvalExpiry.expiresAt.toISOString(),
+				expiredAt: invocation.approvalExpiry.expiredAt.toISOString()
+			};
+		}
+		const event = buildEventEnvelope(invocation, {
+			eventType,
+			subjectType: "ActionInvocation",
+			subjectId: invocation.id,
+			payload
+		}, `approval:${kind}`, 0, kind === "expired" ? invocation.approvalExpiry.expiredAt : invocation.updatedAt);
+		return {
+			event,
+			metadata: eventOutboxMetadata(invocation, event)
+		};
+	};
+	async function expireDueApprovals(input = {}) {
+		const store = asApprovalStore(options.store);
+		if (!store?.expireDueApprovals) {
+			if (options.approvalDefaultTtlMs !== void 0 || options.approvalLifecycleEvents) throw new HostError("Approval expiry requires a store with approval expiry support.");
+			return { expired: [] };
+		}
+		const expired = await store.expireDueApprovals({
+			...input,
+			now: input.now ?? now(),
+			...options.approvalLifecycleEvents ? { lifecycleEvent: approvalLifecycleEvent } : {}
+		});
+		for (const invocation of expired) emitInvocationStatusTelemetry(invocation, "failed", options.telemetry, invocation.approvalExpiry.expiredAt, "waiting_for_approval");
+		return { expired: expired.map((invocation) => invocation.id) };
+	}
+	function buildEventEnvelope(invocation, event, deduplicationKey, sequence, timestamp, defaultEventSchemaVersion = 1) {
+		return {
 			id: lifecycleId("evt", invocation.id, deduplicationKey),
 			tenantId: invocation.tenantId,
 			spaceId: invocation.spaceId,
@@ -3539,7 +3804,7 @@ function createGovernedActionHost(options) {
 			actorType: invocation.actorType,
 			actionInvocationId: invocation.id,
 			payload: event.payload,
-			sequence: await (transaction ?? options.store).nextEventSequence(invocation.tenantId, invocation.spaceId),
+			sequence,
 			occurredAt: timestamp,
 			recordedAt: timestamp,
 			correlationId: invocation.correlationId,
@@ -3550,6 +3815,10 @@ function createGovernedActionHost(options) {
 			} } : {},
 			...declaredConsistency(invocation.actionId) === "provisional-until-reconciled" ? { consistency: "provisional-until-reconciled" } : {}
 		};
+	}
+	async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1, transaction) {
+		const timestamp = now();
+		const envelope = buildEventEnvelope(invocation, event, deduplicationKey, await (transaction ?? options.store).nextEventSequence(invocation.tenantId, invocation.spaceId), timestamp, defaultEventSchemaVersion);
 		if (options.outbox) {
 			const hostLifecycleEvent = (/* @__PURE__ */ new Set([
 				"AdapterInvocationStarted",
@@ -3565,15 +3834,7 @@ function createGovernedActionHost(options) {
 				await (transaction ?? options.store).appendEvent(envelope);
 				return;
 			}
-			const traceContext = options.outbox.traceContext?.(envelope);
-			const payloadClassification = options.outbox.classifyPayload(envelope);
-			const metadata = {
-				producerModuleVersion: options.outbox.producerModuleVersion(invocation.actionId, invocation.actionVersion),
-				payloadClassification,
-				includeProvenance: options.outbox.includeProvenance?.(envelope, payloadClassification) ?? payloadClassification !== "restricted",
-				includeActor: options.outbox.includeActor?.(envelope, payloadClassification) === true,
-				...traceContext ? { traceContext } : {}
-			};
+			const metadata = eventOutboxMetadata(invocation, envelope);
 			if (transaction) {
 				if (!transaction.appendEventWithOutbox) throw new HostError("Outbox egress requires an atomic transaction with appendEventWithOutbox.");
 				await transaction.appendEventWithOutbox(envelope, metadata);
@@ -3636,6 +3897,7 @@ function createGovernedActionHost(options) {
 		return !evidenceOnly;
 	}
 	async function persistInvocation(invocation, patch, onPreservedReconciliation, lease) {
+		patch = finalizationSettlementPatch(invocation, patch);
 		const previousStatus = invocation.status;
 		const identity = lease ?? (invocation.leaseOwner && invocation.leaseToken !== void 0 ? {
 			leaseOwner: invocation.leaseOwner,
@@ -3951,6 +4213,7 @@ function createGovernedActionHost(options) {
 		...stagedStore ? { dispatchStagedInvocations } : {},
 		executeInvocation,
 		resumeApprovedInvocation,
+		expireDueApprovals,
 		recordExecutionAttestation,
 		recordExternalReconciliation,
 		completeExternalInvocation: externalCompletion.completeExternalInvocation,
@@ -4278,6 +4541,8 @@ function emitRelayTelemetry(telemetry, name, occurredAt, workerId, attributes) {
 var MemoryPlatformHostStore = class {
 	db;
 	transactionalOutbox;
+	transactionalApprovalLifecycle;
+	approvalTransactionProvider;
 	transactionalStagedInvocations;
 	adapterCommit;
 	transactionTail = Promise.resolve();
@@ -4300,6 +4565,11 @@ var MemoryPlatformHostStore = class {
 	constructor(db, transactionProvider) {
 		this.db = db;
 		this.transactionalOutbox = transactionProvider !== void 0;
+		this.transactionalApprovalLifecycle = transactionProvider !== void 0;
+		this.approvalTransactionProvider = transactionProvider ?? {
+			snapshot: (db) => db,
+			restore: () => void 0
+		};
 		this.transactionalStagedInvocations = transactionProvider !== void 0;
 		if (transactionProvider) this.transactionWithEvents = (run) => this.runTransactionWithEvents(run, transactionProvider);
 	}
@@ -4546,6 +4816,15 @@ var MemoryPlatformHostStore = class {
 		const record = this.invocations.find((row) => row.id === id && row.tenantId === tenantId && row.spaceId === spaceId);
 		if (!record) throw new Error(`ActionInvocation not found: ${id}`);
 		Object.assign(record, patch, { updatedAt: /* @__PURE__ */ new Date() });
+		for (const key of [
+			"approvalExpiresAt",
+			"approvalExpiry",
+			"approvalDecision"
+		]) {
+			if (!Object.hasOwn(patch, key)) continue;
+			if (patch[key] === void 0) delete record[key];
+			else Object.assign(record, { [key]: structuredClone(patch[key]) });
+		}
 		if (Object.hasOwn(patch, "finalizationCheckpoint")) {
 			if (patch.finalizationCheckpoint) record.finalizationCheckpoint = structuredClone(patch.finalizationCheckpoint);
 			else delete record.finalizationCheckpoint;
@@ -4570,6 +4849,8 @@ var MemoryPlatformHostStore = class {
 	async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
 		const record = await this.getActionInvocation(actionInvocationId, tenantId, spaceId);
 		if (!record) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+		if (record.hitlRoute || !["pending", "running"].includes(record.status)) return record;
+		if (decision.approvalExpiresAt) record.approvalExpiresAt = new Date(decision.approvalExpiresAt);
 		record.hitlRoute = decision.route;
 		record.hitlRiskTier = decision.riskTier;
 		record.hitlReason = decision.reason;
@@ -4577,34 +4858,34 @@ var MemoryPlatformHostStore = class {
 		record.updatedAt = decision.evaluatedAt;
 		return record;
 	}
+	runApprovalTransaction(run) {
+		return this.transactionWithEvents ? this.transactionWithEvents(run) : this.runTransactionWithEvents(run, this.approvalTransactionProvider);
+	}
+	async parkApproval(input) {
+		if (input.lifecycleEvent && !this.transactionalApprovalLifecycle) throw new Error("Approval events require transactional approval support.");
+		return this.runApprovalTransaction((tx) => applyApprovalTransition(tx, input, "requested"));
+	}
 	async beginApprovalDecision(input) {
-		const record = await this.getActionInvocation(input.actionInvocationId, input.tenantId, input.spaceId);
-		if (!record || record.status !== "waiting_for_approval") return {
-			applied: false,
-			...record ? { invocation: record } : {}
-		};
-		record.approvalDecision = input.decision;
-		record.updatedAt = input.now;
-		if (!input.decision.approved) {
-			record.status = "failed";
-			record.error = `Approval rejected: ${input.decision.reason ?? "no reason provided"}`;
-			delete record.leaseOwner;
-			delete record.leaseExpiresAt;
-			return {
-				applied: true,
-				invocation: record
-			};
-		}
-		record.status = "running";
-		record.error = void 0;
-		record.leaseOwner = input.leaseOwner;
-		record.leaseExpiresAt = new Date(input.now.getTime() + input.leaseDurationMs);
-		record.leaseToken = (record.leaseToken ?? 0) + 1;
-		record.attemptCount = Math.max(record.attemptCount, 1);
-		return {
-			applied: true,
-			invocation: record
-		};
+		if (input.lifecycleEvent && !this.transactionalApprovalLifecycle) throw new Error("Approval events require transactional approval support.");
+		return this.runApprovalTransaction((tx) => applyApprovalTransition(tx, input, "decided"));
+	}
+	async expireDueApprovals(input) {
+		const limit = approvalSweepLimit(input);
+		if (input.lifecycleEvent && !this.transactionalApprovalLifecycle) throw new Error("Approval events require transactional approval support.");
+		const candidates = this.invocations.filter((row) => row.status === "waiting_for_approval" && row.approvalExpiresAt && row.approvalExpiresAt <= input.now && (input.tenantId === void 0 || row.tenantId === input.tenantId) && (input.spaceId === void 0 || row.spaceId === input.spaceId)).sort((a, b) => a.approvalExpiresAt.getTime() - b.approvalExpiresAt.getTime() || a.id.localeCompare(b.id)).slice(0, limit);
+		return this.runApprovalTransaction(async (tx) => {
+			const expired = [];
+			for (const row of candidates) {
+				const transition = await applyApprovalTransition(tx, {
+					...input,
+					actionInvocationId: row.id,
+					tenantId: row.tenantId,
+					spaceId: row.spaceId
+				}, "expired");
+				if (transition.applied) expired.push(transition.invocation);
+			}
+			return expired;
+		});
 	}
 	async appendPolicyEvaluation(record) {
 		if (this.policyEvaluations.some((candidate) => candidate.id === record.id)) return;
@@ -5054,16 +5335,19 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 	sql;
 	transactionWithEvents;
 	transactionalOutbox;
+	transactionalApprovalLifecycle;
 	transactionalStagedInvocations;
 	constructor(db, sql, transactionProvider) {
 		this.db = db;
 		this.sql = sql;
 		this.transactionalOutbox = transactionProvider !== void 0;
+		this.transactionalApprovalLifecycle = transactionProvider !== void 0;
 		this.transactionalStagedInvocations = transactionProvider !== void 0;
 		if (transactionProvider) this.transactionWithEvents = async (run) => transactionProvider.run(async ({ db, sql }) => {
 			const scoped = new PostgresPlatformHostStore(db, sql);
 			return run({
 				db,
+				beginApprovalDecision: (input) => scoped.beginApprovalDecision(input),
 				getActionInvocationForUpdate: async (id, tenantId, spaceId) => {
 					const result = await sql.query(`SELECT * FROM fabric_platform.action_invocations
 								 WHERE id=$1 AND tenant_id=$2 AND space_id=$3
@@ -5322,6 +5606,18 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				CREATE INDEX IF NOT EXISTS staged_invocations_parent_idx
 					ON fabric_platform.staged_invocations (tenant_id, space_id, parent_invocation_id, created_at);
 			`
+			},
+			{
+				version: 12,
+				name: "approval_lifecycle_expiry",
+				sql: `
+				ALTER TABLE fabric_platform.action_invocations
+					ADD COLUMN IF NOT EXISTS approval_expires_at timestamptz,
+					ADD COLUMN IF NOT EXISTS approval_expiry jsonb;
+				CREATE INDEX IF NOT EXISTS action_invocations_approval_expiry_idx
+					ON fabric_platform.action_invocations (approval_expires_at, id)
+					WHERE status='waiting_for_approval' AND approval_expires_at IS NOT NULL;
+			`
 			}
 		]);
 	}
@@ -5532,7 +5828,9 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		return result.rows[0] ? toActionRecord(result.rows[0]) : void 0;
 	}
 	async updateActionInvocation(id, tenantId, spaceId, patch) {
+		const approvalFields = approvalPatchSql(patch, 18 + (Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? 2 : 0) + (Object.hasOwn(patch, "finalizationCheckpoint") ? 1 : 0));
 		await this.sql.query(`UPDATE fabric_platform.action_invocations SET
+			 ${approvalFields.sql}
 			 status=COALESCE($4,status), result=COALESCE($5::jsonb,result),
 			 error=CASE WHEN $6::boolean THEN $7 ELSE error END,
 			 authorization_reconciliation=CASE WHEN $8::boolean THEN $9::jsonb ELSE authorization_reconciliation END,
@@ -5543,10 +5841,10 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			 ${Object.hasOwn(patch, "finalizationCheckpoint") ? `finalization_checkpoint=$${18 + (Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? 2 : 0)}::jsonb,` : ""}
 			 ${Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? "deferred_before_effect_attempt=CASE WHEN $18::boolean THEN $19::integer ELSE deferred_before_effect_attempt END," : ""}
 			 pending_state_transition=CASE WHEN $16::boolean THEN $17::jsonb ELSE pending_state_transition END,
-			 lease_owner=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
-			                  THEN NULL ELSE lease_owner END,
-			 lease_expires_at=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
-			                       THEN NULL ELSE lease_expires_at END,
+			 ${Object.hasOwn(patch, "leaseOwner") ? "" : `lease_owner=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
+			                  THEN NULL ELSE lease_owner END,`}
+			 ${Object.hasOwn(patch, "leaseExpiresAt") ? "" : `lease_expires_at=CASE WHEN ($13::jsonb IS NOT NULL AND $4='running') OR $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
+			                       THEN NULL ELSE lease_expires_at END,`}
 			 updated_at=now()
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3`, [
 			id,
@@ -5567,14 +5865,15 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			Object.hasOwn(patch, "pendingStateTransition"),
 			patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null,
 			...Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? [true, patch.deferredBeforeEffectAttempt ?? null] : [],
-			...Object.hasOwn(patch, "finalizationCheckpoint") ? [patch.finalizationCheckpoint ? JSON.stringify(patch.finalizationCheckpoint) : null] : []
+			...Object.hasOwn(patch, "finalizationCheckpoint") ? [patch.finalizationCheckpoint ? JSON.stringify(patch.finalizationCheckpoint) : null] : [],
+			...approvalFields.values
 		]);
 	}
 	async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
 		const row = (await this.sql.query(`UPDATE fabric_platform.action_invocations SET
 			 hitl_route=$4, hitl_risk_tier=$5, hitl_reason=$6,
-			 hitl_policy_version=$7, updated_at=$8
-			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3
+			 hitl_policy_version=$7, updated_at=$8, approval_expires_at=$9
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND hitl_route IS NULL AND status IN ('pending','running')
 			 RETURNING *`, [
 			actionInvocationId,
 			tenantId,
@@ -5583,20 +5882,93 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			decision.riskTier,
 			decision.reason,
 			decision.policyVersion ?? null,
-			decision.evaluatedAt
+			decision.evaluatedAt,
+			decision.approvalExpiresAt ?? null
 		])).rows[0];
-		if (!row) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
-		return toActionRecord(row);
+		if (row) return toActionRecord(row);
+		const existing = await this.getActionInvocation(actionInvocationId, tenantId, spaceId);
+		if (!existing) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+		return existing;
+	}
+	async parkApproval(input) {
+		if (this.transactionWithEvents) return this.transactionWithEvents((tx) => applyApprovalTransition(tx, input, "requested"));
+		if (input.lifecycleEvent) throw new Error("Approval events require transactional approval support.");
+		const result = await this.sql.query(`UPDATE fabric_platform.action_invocations SET status='waiting_for_approval',
+			 approval_expires_at=COALESCE($4::timestamptz,approval_expires_at), lease_owner=NULL, lease_expires_at=NULL, updated_at=$5
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND status IN ('pending','running') AND approval_decision IS NULL
+			 AND (lease_owner IS NULL OR (lease_owner=$6 AND lease_token=$7)) RETURNING *`, [
+			input.actionInvocationId,
+			input.tenantId,
+			input.spaceId,
+			input.approvalExpiresAt ?? null,
+			input.now,
+			input.leaseOwner ?? null,
+			input.leaseToken ?? 0
+		]);
+		return result.rows[0] ? {
+			applied: true,
+			invocation: toActionRecord(result.rows[0])
+		} : { applied: false };
+	}
+	async expireDueApprovals(input) {
+		const limit = approvalSweepLimit(input);
+		if (input.lifecycleEvent && !this.transactionWithEvents) throw new Error("Approval events require transactional approval support.");
+		if (!this.transactionWithEvents) return (await this.sql.query(`WITH due AS (
+				 SELECT id FROM fabric_platform.action_invocations WHERE status='waiting_for_approval' AND approval_expires_at <= $1
+				 AND ($2::text IS NULL OR tenant_id=$2) AND ($3::text IS NULL OR space_id=$3)
+				 ORDER BY approval_expires_at,id LIMIT $4 FOR UPDATE SKIP LOCKED
+				) UPDATE fabric_platform.action_invocations AS invocation SET status='failed', approval_decision=NULL,
+				 approval_expiry=jsonb_build_object('expiresAt',approval_expires_at,'expiredAt',$1::timestamptz),
+				 error='Approval expired before a decision was applied.', lease_owner=NULL, lease_expires_at=NULL,
+				 finalization_checkpoint=CASE WHEN finalization_checkpoint ? 'adapterPreparation' OR finalization_checkpoint->>'protocol'='atomic-after-adapters-v2'
+				 THEN (finalization_checkpoint - 'adapterPreparation') || '{"protocol":"atomic-after-adapters-v1"}'::jsonb ELSE finalization_checkpoint END,
+				 updated_at=$1 FROM due WHERE invocation.id=due.id RETURNING invocation.*`, [
+			input.now,
+			input.tenantId ?? null,
+			input.spaceId ?? null,
+			limit
+		])).rows.map(toActionRecord);
+		const candidates = await this.sql.query(`SELECT * FROM fabric_platform.action_invocations WHERE status='waiting_for_approval' AND approval_expires_at <= $1
+			 AND ($2::text IS NULL OR tenant_id=$2) AND ($3::text IS NULL OR space_id=$3)
+			 ORDER BY approval_expires_at,id LIMIT $4`, [
+			input.now,
+			input.tenantId ?? null,
+			input.spaceId ?? null,
+			limit
+		]);
+		return this.transactionWithEvents(async (tx) => {
+			if (!tx.getActionInvocationForUpdate) throw new Error("Approval expiry requires locking invocation reads.");
+			for (const row of candidates.rows) await tx.getActionInvocationForUpdate(String(row.id), String(row.tenant_id), String(row.space_id));
+			const expired = [];
+			for (const row of candidates.rows) {
+				const record = toActionRecord(row);
+				const transition = await applyApprovalTransition(tx, {
+					...input,
+					actionInvocationId: record.id,
+					tenantId: record.tenantId,
+					spaceId: record.spaceId
+				}, "expired");
+				if (transition.applied) expired.push(transition.invocation);
+			}
+			return expired;
+		});
 	}
 	async beginApprovalDecision(input) {
+		if (this.transactionWithEvents) return this.transactionWithEvents((tx) => applyApprovalTransition(tx, input, "decided"));
+		if (input.lifecycleEvent) throw new Error("Approval events require transactional approval support.");
 		const result = await this.sql.query(`UPDATE fabric_platform.action_invocations SET
-			 approval_decision=$4::jsonb,
-			 status=CASE WHEN $5::boolean THEN 'running' ELSE 'failed' END,
-			 error=CASE WHEN $5::boolean THEN NULL ELSE $6 END,
-			 lease_owner=CASE WHEN $5::boolean THEN $7 ELSE NULL END,
-			 lease_expires_at=CASE WHEN $5::boolean THEN $8::timestamptz ELSE NULL END,
-			 lease_token=CASE WHEN $5::boolean THEN lease_token+1 ELSE lease_token END,
-			 attempt_count=CASE WHEN $5::boolean THEN GREATEST(attempt_count,1) ELSE attempt_count END,
+			 approval_expiry=CASE WHEN approval_expires_at <= $9 THEN jsonb_build_object('expiresAt',approval_expires_at,'expiredAt',$9::timestamptz) ELSE approval_expiry END,
+			 approval_decision=CASE WHEN approval_expires_at <= $9 THEN NULL ELSE $4::jsonb END,
+			 status=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN 'running' ELSE 'failed' END,
+			 finalization_checkpoint=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN finalization_checkpoint
+			   WHEN finalization_checkpoint ? 'adapterPreparation' OR finalization_checkpoint->>'protocol'='atomic-after-adapters-v2'
+			   THEN (finalization_checkpoint - 'adapterPreparation') || '{"protocol":"atomic-after-adapters-v1"}'::jsonb
+			   ELSE finalization_checkpoint END,
+			 error=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN NULL WHEN approval_expires_at <= $9 THEN 'Approval expired before a decision was applied.' ELSE $6 END,
+			 lease_owner=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN $7 ELSE NULL END,
+			 lease_expires_at=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN $8::timestamptz ELSE NULL END,
+			 lease_token=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN lease_token+1 ELSE lease_token END,
+			 attempt_count=CASE WHEN $5::boolean AND (approval_expires_at IS NULL OR approval_expires_at > $9) THEN GREATEST(attempt_count,1) ELSE attempt_count END,
 			 updated_at=$9
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND status='waiting_for_approval'
 			 RETURNING *`, [
@@ -6322,7 +6694,9 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 	}
 	async updateLeasedActionInvocation(input) {
 		const patch = input.patch;
+		const approvalFields = approvalPatchSql(patch, 20 + (Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? 2 : 0) + (Object.hasOwn(patch, "finalizationCheckpoint") ? 1 : 0));
 		return (await this.sql.query(`UPDATE fabric_platform.action_invocations SET
+			 ${approvalFields.sql}
 			 status=COALESCE($6,status), result=COALESCE($7::jsonb,result),
 			 error=CASE WHEN $8::boolean THEN $9 ELSE error END,
 			 authorization_reconciliation=CASE WHEN $10::boolean THEN $11::jsonb ELSE authorization_reconciliation END,
@@ -6333,10 +6707,10 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			 ${Object.hasOwn(patch, "finalizationCheckpoint") ? `finalization_checkpoint=$${20 + (Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? 2 : 0)}::jsonb,` : ""}
 			 ${Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? "deferred_before_effect_attempt=CASE WHEN $20::boolean THEN $21::integer ELSE deferred_before_effect_attempt END," : ""}
 			 pending_state_transition=CASE WHEN $18::boolean THEN $19::jsonb ELSE pending_state_transition END,
-			 lease_owner=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
-			                  THEN NULL ELSE lease_owner END,
-			 lease_expires_at=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
-			                       THEN NULL ELSE lease_expires_at END,
+			 ${Object.hasOwn(patch, "leaseOwner") ? "" : `lease_owner=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
+			                  THEN NULL ELSE lease_owner END,`}
+			 ${Object.hasOwn(patch, "leaseExpiresAt") ? "" : `lease_expires_at=CASE WHEN ($15::jsonb IS NOT NULL AND $6='running') OR $6 IN ('waiting_for_approval','completed','failed','blocked_by_policy','reconciliation_required','validation_failed')
+			                       THEN NULL ELSE lease_expires_at END,`}
 			 updated_at=now()
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3
 			   AND status='running' AND lease_owner=$4 AND lease_token=$5
@@ -6361,7 +6735,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			Object.hasOwn(patch, "pendingStateTransition"),
 			patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null,
 			...Object.hasOwn(patch, "deferredBeforeEffectAttempt") ? [true, patch.deferredBeforeEffectAttempt ?? null] : [],
-			...Object.hasOwn(patch, "finalizationCheckpoint") ? [patch.finalizationCheckpoint ? JSON.stringify(patch.finalizationCheckpoint) : null] : []
+			...Object.hasOwn(patch, "finalizationCheckpoint") ? [patch.finalizationCheckpoint ? JSON.stringify(patch.finalizationCheckpoint) : null] : [],
+			...approvalFields.values
 		])).rows.length === 1;
 	}
 	async renewActionInvocationLease(input) {
@@ -6471,6 +6846,11 @@ function toActionRecord(row) {
 		...row.hitl_risk_tier ? { hitlRiskTier: String(row.hitl_risk_tier) } : {},
 		...row.hitl_reason ? { hitlReason: String(row.hitl_reason) } : {},
 		...row.hitl_policy_version ? { hitlPolicyVersion: String(row.hitl_policy_version) } : {},
+		...row.approval_expires_at ? { approvalExpiresAt: new Date(row.approval_expires_at) } : {},
+		...row.approval_expiry ? { approvalExpiry: {
+			expiresAt: new Date(row.approval_expiry.expiresAt),
+			expiredAt: new Date(row.approval_expiry.expiredAt)
+		} } : {},
 		...row.approval_decision ? { approvalDecision: toApprovalDecision(row.approval_decision) } : {},
 		...row.mutation_footprint ? { mutationFootprint: row.mutation_footprint } : {},
 		...row.execution_principal ? { executionPrincipal: row.execution_principal } : {},
@@ -6536,6 +6916,7 @@ function toAttestationRecord(row) {
 function toApprovalDecision(value) {
 	const decision = value;
 	return {
+		...decision.evidence !== void 0 ? { evidence: structuredClone(decision.evidence) } : {},
 		approved: Boolean(decision.approved),
 		approverId: String(decision.approverId),
 		approverType: String(decision.approverType),
@@ -6629,6 +7010,30 @@ function toOutboxRequeueRecord(row, prefix) {
 		priorLeaseToken: Number(field("prior_lease_token"))
 	};
 }
+/** Additional approval-only patch bindings; omitted fields do not touch older columns. */
+function approvalPatchSql(patch, start) {
+	const columns = {
+		approvalExpiresAt: "approval_expires_at",
+		approvalExpiry: "approval_expiry",
+		approvalDecision: "approval_decision",
+		leaseOwner: "lease_owner",
+		leaseExpiresAt: "lease_expires_at",
+		leaseToken: "lease_token",
+		attemptCount: "attempt_count"
+	};
+	const values = [];
+	const assignments = [];
+	for (const key of Object.keys(columns)) {
+		if (!Object.hasOwn(patch, key)) continue;
+		const json = key === "approvalExpiry" || key === "approvalDecision";
+		values.push(patch[key] === void 0 ? null : json ? JSON.stringify(patch[key]) : patch[key]);
+		assignments.push(`${columns[key]}=$${start + values.length - 1}${json ? "::jsonb" : ""},`);
+	}
+	return {
+		sql: assignments.join("\n"),
+		values
+	};
+}
 //#endregion
 //#region src/worker.ts
 const DEFAULT_BATCH_SIZE = 10;
@@ -6670,6 +7075,16 @@ async function runPlatformActionWorkerCycle(options) {
 	} catch (error) {
 		options.onError?.(error);
 	}
+	let expiredApprovals = 0;
+	if (typeof options.host.expireDueApprovals === "function") try {
+		expiredApprovals = (await options.host.expireDueApprovals({
+			...options.tenantId !== void 0 ? { tenantId: options.tenantId } : {},
+			...options.spaceId !== void 0 ? { spaceId: options.spaceId } : {},
+			limit: options.batchSize ?? DEFAULT_BATCH_SIZE
+		})).expired.length;
+	} catch (error) {
+		options.onError?.(error);
+	}
 	let claimed;
 	try {
 		claimed = await options.store.claimActionInvocations({
@@ -6718,6 +7133,7 @@ async function runPlatformActionWorkerCycle(options) {
 		claimed: claimed.length,
 		completed,
 		failed,
+		...expiredApprovals > 0 ? { expiredApprovals } : {},
 		...waitingForApproval > 0 ? { waitingForApproval } : {},
 		...deferred > 0 ? { deferred } : {},
 		...staged && Object.values(staged).some((value) => value > 0) ? { staged } : {}
@@ -6726,6 +7142,7 @@ async function runPlatformActionWorkerCycle(options) {
 		claimed: result.claimed,
 		completed: result.completed,
 		failed: result.failed,
+		...result.expiredApprovals !== void 0 ? { expiredApprovals: result.expiredApprovals } : {},
 		...result.waitingForApproval !== void 0 ? { waitingForApproval: result.waitingForApproval } : {},
 		...result.deferred !== void 0 ? { deferred: result.deferred } : {},
 		...result.staged ? {
@@ -6855,7 +7272,7 @@ function createDurableSagaParentLifecycle(options) {
 				correlationId: input.parentInvocationId,
 				causationId: lifecycleId
 			});
-			if (patch) await transaction.updateActionInvocation(input.parentInvocationId, input.tenantId, input.spaceId, patch);
+			if (patch) await transaction.updateActionInvocation(input.parentInvocationId, input.tenantId, input.spaceId, finalizationSettlementPatch(parent, patch));
 		});
 	}
 	return {
@@ -7934,6 +8351,6 @@ async function runEventAppendChecks(subject) {
 	};
 }
 //#endregion
-export { ActionAdmissionError, ExternalCompletionError, IdempotencyConflictError, 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, 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