@fabricorg/platform-host 8.1.1 → 8.2.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AdapterCircuitBreakerRegistry, AdapterRegistry, FABRIC_GOVERNANCE_CONTRACT_VERSION, aggregatePolicyOutcomes, assertAdapterCircuitBreakerConfig, assertAdapterOutcomeConsistency, assertGovernanceRuntimeEvidence, assertMutationGovernanceContext, canonicalJson, createFabricId, evaluatePolicyDefinitions, evaluateStateMachineTransition, executeWithAdapterRetry, isAdapterCircuitOpenError, isReconciliationRequiredError, isRetryableExecutionError } from "@fabricorg/platform";
+import { AdapterCircuitBreakerRegistry, AdapterRegistry, FABRIC_GOVERNANCE_CONTRACT_VERSION, 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";
@@ -95,6 +95,78 @@ 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"]);
+	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")) throw new Error("Finalization must return only events and resultPatch.");
+	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;
@@ -1462,6 +1534,7 @@ function createGovernedActionHost(options) {
 			await attemptEvidenceWrites(evidenceWrites);
 		}
 		async function failExecution(record, status, error) {
+			if (record.finalizationCheckpoint && hasDurableProviderEffect) return settleAppliedEffect(error);
 			await persistExecutionInvocation(record, {
 				status,
 				error
@@ -1754,14 +1827,34 @@ function createGovernedActionHost(options) {
 			};
 		}
 		const action = actionResolver(invocation.actionId);
-		if (action && (resumingRunningInvocation || invocation.attemptCount > 1)) try {
-			for (const [stepIndex] of (action.adapterSteps ?? []).entries()) {
+		let hasNonSucceededAdapterRow = false;
+		if ((action || invocation.finalizationCheckpoint) && (resumingRunningInvocation || invocation.attemptCount > 1)) try {
+			let runningCheckpoint;
+			for (const stepIndex of Array.from({ length: Math.max((action?.adapterSteps ?? []).length, invocation.finalizationCheckpoint?.steps.length ?? 0) }, (_, index) => index)) {
 				const record = await options.store.getAdapterInvocation(lifecycleId("adp", actionInvocationId, String(stepIndex)), adapterInvocationScope);
-				if (record) adapterStatuses.set(record.id, record.status);
+				if (record) {
+					adapterStatuses.set(record.id, record.status);
+					hasNonSucceededAdapterRow ||= record.status !== "succeeded";
+				}
 				if (record?.status === "succeeded") hasDurableProviderEffect = true;
+				if (invocation.finalizationCheckpoint && record?.status === "running") runningCheckpoint ??= {
+					stepIndex,
+					record
+				};
 				if (record?.status !== "ambiguous") continue;
 				return await settleUnknownOutcome(stepIndex, recordedAdapterReconciliation(record), record.reconciliation?.adapterEventSubject);
 			}
+			if (runningCheckpoint) {
+				const { stepIndex, record } = runningCheckpoint;
+				return await settleUnknownOutcome(stepIndex, {
+					kind: "adapter_outcome_ambiguous",
+					adapterInvocationId: record.id,
+					adapterType: record.adapterType,
+					operation: record.operation,
+					vendor: record.vendor,
+					message: "Recorded adapter outcome is unknown."
+				});
+			}
 		} catch (error) {
 			if (error instanceof RecoverableFinalizationError) throw error;
 			throw new RecoverableFinalizationError(caughtError({
@@ -1771,6 +1864,30 @@ function createGovernedActionHost(options) {
 		}
 		if (invocation.status === "running" && invocation.pendingCompletion && !invocation.leaseOwner) return withConsistency(actionResult(invocation), invocation.actionId);
 		if (!action) return hostOperation(() => failExecution(invocation, "failed", `Unknown action: ${invocation.actionId}`));
+		if (invocation.finalizationCheckpoint && !action.finalize) return interruptedNonIdempotent("Action no longer declares its checkpointed finalizer.");
+		let hasFencedAdapterWrites = false;
+		try {
+			assertAdapterStepDeadlines(action);
+			assertActionFinalization(action);
+			if (action.finalize) {
+				const store = asAtomicMutationStore(options.store);
+				if (!store) throw new Error("Action finalization requires atomic mutation transactions.");
+				await store.transactionWithEvents(async (transaction) => {
+					if (typeof transaction.getActionInvocationForUpdate !== "function" || typeof transaction.updateLeasedActionInvocation !== "function" || options.outbox && typeof transaction.appendEventWithOutbox !== "function") throw new Error("Action finalization requires atomic invocation locking and transaction-scoped lease fencing.");
+					hasFencedAdapterWrites = typeof options.store.writeAdapterInvocation === "function" && typeof transaction.writeAdapterInvocation === "function";
+				});
+			}
+		} catch (error) {
+			return interruptedNonIdempotent(caughtError({
+				actionId: action.actionId,
+				source: "execution"
+			}, error));
+		}
+		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 (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.`));
 		if (action.kind === "saga") return hostOperation(() => failExecution(invocation, "failed", `Saga action ${invocation.actionId} requires a durable PlatformActionDispatcher and cannot execute as an atomic Host action.`));
 		async function interruptedNonIdempotent(message) {
@@ -1800,8 +1917,9 @@ function createGovernedActionHost(options) {
 			}
 			return hostOperation(() => failExecution(invocation, "failed", message));
 		}
-		if (resumingRunningInvocation && invocation.attemptCount === 0 && !invocation.leaseOwner && !action.idempotent) return interruptedNonIdempotent(`Interrupted inline action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`);
-		if (invocation.attemptCount > 1 && !action.idempotent) return interruptedNonIdempotent(`Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`);
+		const canReplayNonIdempotent = !!replayCheckpoint && !hasNonSucceededAdapterRow && (!executionLease || hasFencedAdapterWrites);
+		if (resumingRunningInvocation && invocation.attemptCount === 0 && !invocation.leaseOwner && !action.idempotent && !canReplayNonIdempotent) return interruptedNonIdempotent(`Interrupted inline action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`);
+		if (invocation.attemptCount > 1 && !action.idempotent && !canReplayNonIdempotent && invocation.deferredBeforeEffectAttempt !== invocation.attemptCount - 1) return interruptedNonIdempotent(`Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`);
 		if (invocation.status !== "running") await hostOperation(() => options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { status: "running" }));
 		emitPlatformHostTelemetry(options.telemetry, {
 			kind: "event",
@@ -2002,144 +2120,209 @@ function createGovernedActionHost(options) {
 					}))));
 				}
 			}
+			const preparedInputs = /* @__PURE__ */ new Map();
+			let preparation = replayCheckpoint;
 			let data;
+			let finalizationInput;
 			let domainEvents = [];
 			let pendingTransitionEvent;
 			try {
-				const runHandler = async (db, transaction) => {
-					if (options.outbox && !transaction?.appendEventWithOutbox) throw new HostError("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
-					const binding = action.stateMachine;
-					let replayedTransition;
-					let pendingStateTransition;
-					let validatedTransition;
-					if (binding) {
-						const machine = stateMachineResolver(binding.entityType);
-						const entityId = binding.getEntityId(parsed.data);
-						const getEntityState = transaction?.getEntityState ? transaction.getEntityState.bind(transaction) : options.store.getEntityState.bind(options.store);
-						const currentState = entityId ? await hostOperation(() => getEntityState(tenantId, spaceId, binding.entityType, entityId)) ?? initialState(machine) : initialState(machine);
-						const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
-						if (targetState !== "") {
-							const transition = await evaluateStateMachineTransition(machine, binding.entityType, currentState, targetState, action.actionId, {
-								entity: {
-									...entityId ? { id: entityId } : {},
-									state: currentState
-								},
-								actionInvocationId,
-								actorId: invocation.actorId,
-								parameters: parsed.data,
-								db
-							});
-							validatedTransition = {
-								entityId,
-								currentState,
-								targetState,
-								valid: transition.valid
-							};
-							let replayingAppliedTransition = false;
-							if (action.idempotent && currentState === targetState && !transition.valid && entityId) {
-								let source;
-								if (transaction?.getEntityStateSource) source = await hostOperation(() => transaction.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId));
-								else if (options.store.getEntityStateSource) source = await hostOperation(() => options.store.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId));
-								else {
-									const eventStore = options.store;
-									const listEvents = transaction?.listEvents?.bind(transaction) ?? eventStore.listEvents?.bind(eventStore);
-									const events = listEvents ? await hostOperation(() => listEvents(tenantId, spaceId)) : [];
-									let latest;
-									for (const event of events) if (event.tenantId === tenantId && event.spaceId === spaceId && event.subjectType === binding.entityType && event.subjectId === entityId && typeof event.payload?.toState === "string" && (!latest || event.sequence > latest.sequence)) latest = event;
-									if (latest && typeof latest.actionInvocationId === "string") source = {
-										state: latest.payload.toState,
-										actionInvocationId: latest.actionInvocationId
+				if (replayCheckpoint) {
+					data = structuredClone(replayCheckpoint.result);
+					finalizationInput = structuredClone({
+						params: replayCheckpoint.params,
+						handlerData: replayCheckpoint.handlerData
+					});
+					domainEvents = structuredClone(replayCheckpoint.handlerEvents);
+					pendingTransitionEvent = structuredClone(replayCheckpoint.stateTransition);
+				} else {
+					const runHandler = async (db, transaction) => {
+						if (options.outbox && !transaction?.appendEventWithOutbox) throw new HostError("Outbox egress requires transactionWithEvents to provide appendEventWithOutbox before handler execution.");
+						if (action.finalize) {
+							const current = await transaction.getActionInvocationForUpdate(actionInvocationId, tenantId, spaceId);
+							if (!current || current.status !== "running" || current.finalizationCheckpoint || (executionLease ? current.leaseOwner !== executionLease.leaseOwner || current.leaseToken !== executionLease.leaseToken : !!current.leaseOwner)) throw new RecoverableFinalizationError(`Invocation preparation ownership changed: ${actionInvocationId}`);
+						}
+						const binding = action.stateMachine;
+						let replayedTransition;
+						let pendingStateTransition;
+						let validatedTransition;
+						if (binding) {
+							const machine = stateMachineResolver(binding.entityType);
+							const entityId = binding.getEntityId(parsed.data);
+							const getEntityState = transaction?.getEntityState ? transaction.getEntityState.bind(transaction) : options.store.getEntityState.bind(options.store);
+							const currentState = entityId ? await hostOperation(() => getEntityState(tenantId, spaceId, binding.entityType, entityId)) ?? initialState(machine) : initialState(machine);
+							const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
+							if (targetState !== "") {
+								const transition = await evaluateStateMachineTransition(machine, binding.entityType, currentState, targetState, action.actionId, {
+									entity: {
+										...entityId ? { id: entityId } : {},
+										state: currentState
+									},
+									actionInvocationId,
+									actorId: invocation.actorId,
+									parameters: parsed.data,
+									db
+								});
+								validatedTransition = {
+									entityId,
+									currentState,
+									targetState,
+									valid: transition.valid
+								};
+								let replayingAppliedTransition = false;
+								if (action.idempotent && currentState === targetState && !transition.valid && entityId) {
+									let source;
+									if (transaction?.getEntityStateSource) source = await hostOperation(() => transaction.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId));
+									else if (options.store.getEntityStateSource) source = await hostOperation(() => options.store.getEntityStateSource(tenantId, spaceId, binding.entityType, entityId));
+									else {
+										const eventStore = options.store;
+										const listEvents = transaction?.listEvents?.bind(transaction) ?? eventStore.listEvents?.bind(eventStore);
+										const events = listEvents ? await hostOperation(() => listEvents(tenantId, spaceId)) : [];
+										let latest;
+										for (const event of events) if (event.tenantId === tenantId && event.spaceId === spaceId && event.subjectType === binding.entityType && event.subjectId === entityId && typeof event.payload?.toState === "string" && (!latest || event.sequence > latest.sequence)) latest = event;
+										if (latest && typeof latest.actionInvocationId === "string") source = {
+											state: latest.payload.toState,
+											actionInvocationId: latest.actionInvocationId
+										};
+									}
+									replayingAppliedTransition = source?.actionInvocationId === actionInvocationId && source.state === currentState;
+								}
+								const pending = invocation.pendingStateTransition;
+								if (replayingAppliedTransition && pending && pending.entityType === binding.entityType && pending.entityId === entityId && pending.toState === currentState) replayedTransition = pending;
+								if (action.idempotent && transition.valid && entityId && action.eventPhase === "after_adapters") {
+									pendingStateTransition = {
+										entityType: binding.entityType,
+										entityId,
+										fromState: currentState,
+										toState: targetState
 									};
+									if (!transaction) await hostOperation(() => options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition }));
 								}
-								replayingAppliedTransition = source?.actionInvocationId === actionInvocationId && source.state === currentState;
+								if (!transition.valid && !replayingAppliedTransition) throw transition.error != null ? new Error(transition.error) : new HostError("Invalid state transition");
 							}
-							const pending = invocation.pendingStateTransition;
-							if (replayingAppliedTransition && pending && pending.entityType === binding.entityType && pending.entityId === entityId && pending.toState === currentState) replayedTransition = pending;
-							if (action.idempotent && transition.valid && entityId && action.eventPhase === "after_adapters") {
-								pendingStateTransition = {
+						}
+						const handlerResult = action.handler ? await action.handler({
+							actionInvocationId,
+							tenantId,
+							spaceId,
+							actorId: invocation.actorId,
+							actorType: invocation.actorType,
+							correlationId: invocation.correlationId,
+							...invocation.causationId ? { causationId: invocation.causationId } : {},
+							...invocation.provenance ? { provenance: invocation.provenance } : {},
+							...isAdmissionTime(invocation.admittedAt) ? { admittedAt: invocation.admittedAt } : {},
+							db,
+							services: options.services,
+							...action.finalize ? { finalizationProtocol: "atomic-after-adapters-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 ?? {};
+						if (action.resultSchema && !action.finalize) {
+							const publicResult = withoutPrivateHostFields(handlerData, eventResultFields);
+							const parsedResult = action.resultSchema.safeParse(publicResult);
+							if (!parsedResult.success) throw new HostError(`Action result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
+						}
+						const preparedFinalizationInput = action.finalize ? {
+							params: normalizeFinalizationJson(parsed.data),
+							handlerData: normalizeFinalizationJson(withoutPrivateHostFields(handlerData, eventResultFields))
+						} : void 0;
+						const extractedEvents = extractEvents(handlerData);
+						const events = action.finalize ? normalizeFinalizationJson(extractedEvents) : extractedEvents;
+						const undeclaredEvent = events.find((event) => !action.emitsEvents.includes(event.eventType));
+						if (undeclaredEvent) throw new HostError(`${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`);
+						if (action.eventPhase !== "after_adapters") for (const [index, event] of events.entries()) await hostOperation(() => appendEvent(invocation, event, `domain:${index}`, action.version, transaction));
+						let transitionEvent;
+						if (binding && validatedTransition?.entityId && (validatedTransition.valid || replayedTransition)) {
+							const { entityId, currentState, targetState } = validatedTransition;
+							if (!events.some((event) => event.eventType === "StateTransitioned" && event.subjectType === binding.entityType && event.subjectId === entityId)) transitionEvent = {
+								eventType: "StateTransitioned",
+								subjectType: binding.entityType,
+								subjectId: entityId,
+								payload: {
 									entityType: binding.entityType,
 									entityId,
-									fromState: currentState,
-									toState: targetState
-								};
-								if (!transaction) await hostOperation(() => options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition }));
-							}
-							if (!transition.valid && !replayingAppliedTransition) throw transition.error != null ? new Error(transition.error) : new HostError("Invalid state transition");
+									fromState: replayedTransition?.fromState ?? currentState,
+									toState: targetState,
+									causedByAction: action.actionId
+								}
+							};
 						}
-					}
-					const handlerResult = action.handler ? await action.handler({
-						actionInvocationId,
-						tenantId,
-						spaceId,
-						actorId: invocation.actorId,
-						actorType: invocation.actorType,
-						correlationId: invocation.correlationId,
-						...invocation.causationId ? { causationId: invocation.causationId } : {},
-						...invocation.provenance ? { provenance: invocation.provenance } : {},
-						...isAdmissionTime(invocation.admittedAt) ? { admittedAt: invocation.admittedAt } : {},
-						db,
-						services: options.services
-					}, 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 ?? {};
-					if (action.resultSchema) {
-						const publicResult = withoutPrivateHostFields(handlerData, eventResultFields);
-						const parsedResult = action.resultSchema.safeParse(publicResult);
-						if (!parsedResult.success) throw new HostError(`Action result validation failed at ${parsedResult.error.issues.map((issue) => issue.path.map(String).join(".") || "result").join(", ")}`);
-					}
-					const events = extractEvents(handlerData);
-					const undeclaredEvent = events.find((event) => !action.emitsEvents.includes(event.eventType));
-					if (undeclaredEvent) throw new HostError(`${action.actionId} emitted undeclared event type ${undeclaredEvent.eventType}`);
-					if (action.eventPhase !== "after_adapters") for (const [index, event] of events.entries()) await hostOperation(() => appendEvent(invocation, event, `domain:${index}`, action.version, transaction));
-					let transitionEvent;
-					if (binding && validatedTransition?.entityId && (validatedTransition.valid || replayedTransition)) {
-						const { entityId, currentState, targetState } = validatedTransition;
-						if (!events.some((event) => event.eventType === "StateTransitioned" && event.subjectType === binding.entityType && event.subjectId === entityId)) transitionEvent = {
-							eventType: "StateTransitioned",
-							subjectType: binding.entityType,
-							subjectId: entityId,
-							payload: {
-								entityType: binding.entityType,
-								entityId,
-								fromState: replayedTransition?.fromState ?? currentState,
-								toState: targetState,
-								causedByAction: action.actionId
+						if (transitionEvent && action.eventPhase !== "after_adapters") await hostOperation(() => appendEvent(invocation, transitionEvent, "state:transition", 1, transaction));
+						if (transaction && pendingStateTransition) await hostOperation(() => transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition }));
+						if (preparedFinalizationInput) {
+							const skipped = [];
+							for (const [index, step] of (action.adapterSteps ?? []).entries()) {
+								const input = step.getInput(structuredClone(preparedFinalizationInput.params), structuredClone(preparedFinalizationInput.handlerData));
+								preparedInputs.set(index, input);
+								if (!input) skipped.push(index);
 							}
+							preparation = normalizeFinalizationJson({
+								protocol: "atomic-after-adapters-v1",
+								actionVersion: action.version,
+								steps: (action.adapterSteps ?? []).map(({ adapterType, operation }) => ({
+									adapterType,
+									operation
+								})),
+								...preparedFinalizationInput,
+								handlerEvents: events,
+								result: preparedFinalizationInput.handlerData,
+								...transitionEvent ? { stateTransition: transitionEvent } : {},
+								skipped
+							});
+							if (new TextEncoder().encode(canonicalJson(preparation)).byteLength > 262144) throw new HostError("Finalization checkpoint exceeds 256 KiB.");
+							if (executionLease) {
+								if (!await transaction.updateLeasedActionInvocation({
+									id: actionInvocationId,
+									tenantId,
+									spaceId,
+									workerId: executionLease.leaseOwner,
+									leaseToken: executionLease.leaseToken,
+									patch: { finalizationCheckpoint: preparation }
+								})) throw new RecoverableFinalizationError(`Invocation lease lost: ${actionInvocationId}`);
+							} else await transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, { finalizationCheckpoint: preparation });
+						}
+						return {
+							data: handlerData,
+							domainEvents: events,
+							pendingTransitionEvent: transitionEvent,
+							finalizationInput: preparedFinalizationInput
 						};
-					}
-					if (transitionEvent && action.eventPhase !== "after_adapters") await hostOperation(() => appendEvent(invocation, transitionEvent, "state:transition", 1, transaction));
-					if (transaction && pendingStateTransition) await hostOperation(() => transaction.updateActionInvocation(actionInvocationId, tenantId, spaceId, { pendingStateTransition }));
-					return {
-						data: handlerData,
-						domainEvents: events,
-						pendingTransitionEvent: transitionEvent
 					};
-				};
-				const atomicStore = asAtomicMutationStore(options.store);
-				let callbackFailure;
-				const run = async (db, transaction) => {
-					callbackFailure = void 0;
-					try {
-						return await runHandler(db, transaction);
-					} catch (error) {
-						callbackFailure = { error };
-						throw error;
-					}
-				};
-				const executed = await (async () => {
-					try {
-						return atomicStore ? await atomicStore.transactionWithEvents((transaction) => run(transaction.db, transaction)) : await options.store.transaction((db) => run(db));
-					} catch (error) {
-						if (callbackFailure) throw callbackFailure.error;
-						return hostOperation(() => Promise.reject(error));
-					}
-				})();
-				data = executed.data;
-				domainEvents = executed.domainEvents;
-				pendingTransitionEvent = executed.pendingTransitionEvent;
+					const atomicStore = asAtomicMutationStore(options.store);
+					let callbackFailure;
+					const run = async (db, transaction) => {
+						callbackFailure = void 0;
+						try {
+							return await runHandler(db, transaction);
+						} catch (error) {
+							callbackFailure = { error };
+							throw error;
+						}
+					};
+					const executed = await (async () => {
+						try {
+							return atomicStore ? await atomicStore.transactionWithEvents((transaction) => run(transaction.db, transaction)) : await options.store.transaction((db) => run(db));
+						} catch (error) {
+							if (callbackFailure) throw callbackFailure.error;
+							if (action.finalize) throw new RecoverableFinalizationError(caughtError({
+								actionId: action.actionId,
+								source: "execution"
+							}, error));
+							return hostOperation(() => Promise.reject(error));
+						}
+					})();
+					data = executed.data;
+					finalizationInput = executed.finalizationInput;
+					domainEvents = executed.domainEvents;
+					pendingTransitionEvent = executed.pendingTransitionEvent;
+					if (preparation) invocation = {
+						...invocation,
+						finalizationCheckpoint: preparation
+					};
+				}
 			} catch (error) {
 				if (error instanceof RecoverableFinalizationError) throw error;
 				if (isReconciliationRequiredError(error)) {
@@ -2164,6 +2347,7 @@ function createGovernedActionHost(options) {
 					source: "handler"
 				}, error)));
 			}
+			const finalizationSteps = [];
 			let pendingHandoff = invocation.pendingCompletion;
 			for (const [stepIndex, step] of (action.adapterSteps ?? []).entries()) {
 				const adapterInvocationId = lifecycleId("adp", actionInvocationId, String(stepIndex));
@@ -2233,8 +2417,16 @@ function createGovernedActionHost(options) {
 					}, error));
 				}
 				if (previousAdapterInvocation?.status === "ambiguous") return await settleUnknownOutcome(stepIndex, recordedAdapterReconciliation(previousAdapterInvocation), previousAdapterInvocation.reconciliation?.adapterEventSubject);
-				const input = step.getInput(parsed.data, data);
-				if (!input) continue;
+				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);
+				if (!input) {
+					if (action.finalize) finalizationSteps.push({
+						stepIndex,
+						adapterType: step.adapterType,
+						operation: step.operation,
+						status: "skipped"
+					});
+					continue;
+				}
 				const adapter = adapters.require(step.adapterType, step.operation);
 				const adapterEventSubject = options.adapterEventSubject?.(action.actionId, parsed.data, data) ?? {
 					subjectType: "AdapterInvocation",
@@ -2390,8 +2582,9 @@ function createGovernedActionHost(options) {
 				let thrownOutcome;
 				let adapterDeadlineTimer;
 				try {
-					const adapterController = options.adapterDeadlineMs ? new AbortController() : void 0;
-					const deadlineMs = options.adapterDeadlineMs ? now().getTime() + options.adapterDeadlineMs : void 0;
+					const effectiveDeadlineMs = step.deadlineMs ?? options.adapterDeadlineMs;
+					const adapterController = effectiveDeadlineMs ? new AbortController() : void 0;
+					const deadlineMs = effectiveDeadlineMs ? now().getTime() + effectiveDeadlineMs : void 0;
 					if (adapterController && deadlineMs) {
 						const remaining = deadlineMs - now().getTime();
 						if (remaining <= 0) throw new HostError(`Adapter deadline already expired before execution: ${step.adapterType}:${step.operation}`);
@@ -2576,6 +2769,7 @@ function createGovernedActionHost(options) {
 							...pendingCompletion ? { pendingCompletion } : {}
 						}, action.actionId);
 					}
+					if (action.finalize) output = normalizeFinalizationJson(output);
 					successOutput = output;
 					if (handoff) {
 						const reference = typeof handoff.externalReference === "string" ? handoff.externalReference.trim() : "";
@@ -2809,7 +3003,8 @@ function createGovernedActionHost(options) {
 					return hostOperation(() => failExecution(invocation, "failed", message));
 				}
 			}
-			const result = withoutPrivateHostFields(data, eventResultFields);
+			if (action.finalize && pendingHandoff) return settleAppliedEffect("Finalizing actions cannot finalize accepted external operations.", pendingHandoff);
+			let result = action.finalize ? { ...replayCheckpoint?.result ?? finalizationInput.handlerData } : withoutPrivateHostFields(data, eventResultFields);
 			const parked = pendingHandoff ? {
 				...pendingHandoff,
 				parkedAt: now()
@@ -2823,25 +3018,83 @@ function createGovernedActionHost(options) {
 				result
 			};
 			let verdictWritten = true;
+			let finalizationCallbackFailure;
 			try {
 				const atomicStore = asAtomicMutationStore(options.store);
 				if (action.eventPhase === "after_adapters" && atomicStore) {
-					await hostOperation(() => atomicStore.transactionWithEvents(async (transaction) => {
-						for (const [index, event] of domainEvents.entries()) await appendEvent(invocation, event, `domain:${index}`, action.version, transaction);
-						if (pendingTransitionEvent) await appendEvent(invocation, pendingTransitionEvent, "state:transition", 1, transaction);
-						if (executionLease) {
-							if (!transaction.updateLeasedActionInvocation) throw new HostError("Leased atomic finalization requires transaction-scoped fencing support.");
-							if (!await transaction.updateLeasedActionInvocation({
-								id: actionInvocationId,
-								tenantId,
-								spaceId,
-								workerId: executionLease.leaseOwner,
-								leaseToken: executionLease.leaseToken,
-								patch: finalPatch
-							})) throw new RecoverableFinalizationError(`Invocation lease lost: ${actionInvocationId}`);
-						} else verdictWritten = await writeInlineInvocation(invocation, finalPatch, transaction, onPreservedReconciliation);
-					}));
-					if (!pendingHandoff && verdictWritten) emitInvocationStatusTelemetry(invocation, "completed", options.telemetry, now());
+					if (action.finalize) for (const [stepIndex, step] of (action.adapterSteps ?? []).entries()) {
+						if (finalizationSteps.some((entry) => entry.stepIndex === stepIndex)) continue;
+						const row = await options.store.getAdapterInvocation(lifecycleId("adp", actionInvocationId, String(stepIndex)), adapterInvocationScope);
+						if (row?.status !== "succeeded" || row.output === void 0) {
+							const error = /* @__PURE__ */ new Error("Finalization requires successful stored adapter output.");
+							finalizationCallbackFailure = { error };
+							throw error;
+						}
+						finalizationSteps.push({
+							stepIndex,
+							adapterType: step.adapterType,
+							operation: step.operation,
+							status: "succeeded",
+							adapterInvocationId: row.id,
+							output: finalizationJson(row.output)
+						});
+					}
+					const finalizeSuccess = () => atomicStore.transactionWithEvents(async (transaction) => {
+						try {
+							let finalized;
+							async function assertFinalizationOwner() {
+								const current = await transaction.getActionInvocationForUpdate(actionInvocationId, tenantId, spaceId);
+								if (!current || current.status !== "running" || (executionLease ? current.leaseOwner !== executionLease.leaseOwner || current.leaseToken !== executionLease.leaseToken : !!current.leaseOwner)) throw new RecoverableFinalizationError(`Invocation lease lost or no longer running: ${actionInvocationId}`);
+							}
+							if (action.finalize) {
+								await assertFinalizationOwner();
+								finalized = validateFinalization(await action.finalize({
+									actionInvocationId,
+									tenantId,
+									spaceId,
+									actorId: invocation.actorId,
+									actorType: invocation.actorType,
+									correlationId: invocation.correlationId,
+									causationId: invocation.causationId,
+									provenance: invocation.provenance ? structuredClone(invocation.provenance) : void 0,
+									db: transaction.db
+								}, {
+									...structuredClone(finalizationInput),
+									adapterOutputs: structuredClone(finalizationSteps.sort((a, b) => a.stepIndex - b.stepIndex))
+								}), action, eventResultFields, options.eventContracts);
+								result = withoutPrivateHostFields({
+									...result,
+									...finalized.resultPatch
+								}, eventResultFields);
+								if (action.resultSchema && !action.resultSchema.safeParse(result).success) throw new Error("Finalization merged result does not match resultSchema.");
+								finalPatch.result = result;
+							}
+							for (const [index, event] of domainEvents.entries()) await appendEvent(invocation, event, `domain:${index}`, action.version, transaction);
+							for (const [index, event] of (finalized?.events ?? []).entries()) await appendEvent(invocation, event, `finalize:${index}`, action.version, transaction);
+							if (pendingTransitionEvent) await appendEvent(invocation, pendingTransitionEvent, "state:transition", 1, transaction);
+							if (action.finalize) await assertFinalizationOwner();
+							if (executionLease) {
+								if (!transaction.updateLeasedActionInvocation) throw new HostError("Leased atomic finalization requires transaction-scoped fencing support.");
+								if (!await transaction.updateLeasedActionInvocation({
+									id: actionInvocationId,
+									tenantId,
+									spaceId,
+									workerId: executionLease.leaseOwner,
+									leaseToken: executionLease.leaseToken,
+									patch: finalPatch
+								})) throw new RecoverableFinalizationError(`Invocation lease lost: ${actionInvocationId}`);
+							} else verdictWritten = await writeInlineInvocation(invocation, finalPatch, transaction, onPreservedReconciliation);
+						} catch (error) {
+							finalizationCallbackFailure = { error };
+							throw error;
+						}
+					});
+					if (action.finalize) await finalizeSuccess();
+					else await hostOperation(finalizeSuccess);
+					if (!pendingHandoff && verdictWritten) {
+						if (action.finalize) rememberVerdict(finalPatch);
+						emitInvocationStatusTelemetry(invocation, "completed", options.telemetry, now());
+					}
 				} else {
 					if (action.eventPhase === "after_adapters") {
 						for (const [index, event] of domainEvents.entries()) await hostOperation(() => appendEvent(invocation, event, `domain:${index}`, action.version));
@@ -2850,6 +3103,18 @@ function createGovernedActionHost(options) {
 					await hostOperation(() => persistExecutionInvocation(invocation, finalPatch));
 				}
 			} catch (error) {
+				if (action.finalize) {
+					if (error instanceof RecoverableFinalizationError) throw error;
+					if (!finalizationCallbackFailure || finalizationCallbackFailure.error !== error) throw new RecoverableFinalizationError(caughtError({
+						actionId: action.actionId,
+						source: "execution"
+					}, error));
+					const message = caughtError({
+						actionId: action.actionId,
+						source: "execution"
+					}, error);
+					return hasDurableProviderEffect ? settleAppliedEffect(message) : hostOperation(() => failExecution(invocation, "failed", message));
+				}
 				if (action.eventPhase === "after_adapters") throw new RecoverableFinalizationError(errorMessage(error));
 				throw error;
 			}
@@ -2864,7 +3129,13 @@ function createGovernedActionHost(options) {
 		} catch (error) {
 			if (error instanceof RecoverableFinalizationError) throw error;
 			if (retryableGovernance && isRetryableExecutionError(error)) {
-				const reason = executionReasonOverride === "approval_resume" ? "approval resume" : !invocation.leaseOwner || invocation.leaseToken === void 0 ? "not leased" : !action.idempotent ? "action not idempotent" : invocation.attemptCount >= retryableExecutionMaxAttempts ? `attempts exhausted (${invocation.attemptCount}/${retryableExecutionMaxAttempts})` : void 0;
+				let reason = executionReasonOverride === "approval_resume" ? "approval resume" : !invocation.leaseOwner || invocation.leaseToken === void 0 ? "not leased" : invocation.attemptCount >= retryableExecutionMaxAttempts ? `attempts exhausted (${invocation.attemptCount}/${retryableExecutionMaxAttempts})` : void 0;
+				if (!reason && !action.idempotent) try {
+					await persistExecutionInvocation(invocation, { deferredBeforeEffectAttempt: invocation.attemptCount });
+				} catch (markerError) {
+					if (markerError instanceof RecoverableFinalizationError) throw markerError;
+					reason = "pre-effect marker could not be recorded";
+				}
 				if (!reason) throw error;
 				return hostOperation(() => failExecution(invocation, "failed", caughtError({
 					actionId: invocation.actionId,
@@ -3670,6 +3941,11 @@ 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() });
+		if (Object.hasOwn(patch, "finalizationCheckpoint")) {
+			if (patch.finalizationCheckpoint) record.finalizationCheckpoint = structuredClone(patch.finalizationCheckpoint);
+			else delete record.finalizationCheckpoint;
+		}
+		if (Object.hasOwn(patch, "deferredBeforeEffectAttempt") && patch.deferredBeforeEffectAttempt === void 0) delete record.deferredBeforeEffectAttempt;
 		if (Object.hasOwn(patch, "pendingStateTransition")) {
 			if (patch.pendingStateTransition) record.pendingStateTransition = { ...patch.pendingStateTransition };
 			else delete record.pendingStateTransition;
@@ -4306,6 +4582,16 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				sql: `
 				ALTER TABLE fabric_platform.adapter_invocations ADD COLUMN IF NOT EXISTS reconciliation jsonb;
 			`
+			},
+			{
+				version: 9,
+				name: "pre_effect_governance_deferral",
+				sql: `ALTER TABLE fabric_platform.action_invocations ADD COLUMN IF NOT EXISTS deferred_before_effect_attempt integer;`
+			},
+			{
+				version: 10,
+				name: "finalization_preparation_checkpoint",
+				sql: `ALTER TABLE fabric_platform.action_invocations ADD COLUMN IF NOT EXISTS finalization_checkpoint jsonb;`
 			}
 		]);
 	}
@@ -4379,6 +4665,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			 pending_completion=CASE WHEN $12::boolean THEN $13::jsonb ELSE pending_completion END,
 			 completion_due_at=CASE WHEN $12::boolean THEN ($13::jsonb->>'dueAt')::timestamptz ELSE completion_due_at END,
 			 external_completion=CASE WHEN $14::boolean THEN $15::jsonb ELSE external_completion END,
+			 ${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,
@@ -4402,7 +4690,9 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			Object.hasOwn(patch, "externalCompletion"),
 			patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null,
 			Object.hasOwn(patch, "pendingStateTransition"),
-			patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null
+			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] : []
 		]);
 	}
 	async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
@@ -5032,6 +5322,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			 pending_completion=CASE WHEN $14::boolean THEN $15::jsonb ELSE pending_completion END,
 			 completion_due_at=CASE WHEN $14::boolean THEN ($15::jsonb->>'dueAt')::timestamptz ELSE completion_due_at END,
 			 external_completion=CASE WHEN $16::boolean THEN $17::jsonb ELSE external_completion END,
+			 ${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,
@@ -5059,7 +5351,9 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			Object.hasOwn(patch, "externalCompletion"),
 			patch.externalCompletion ? JSON.stringify(patch.externalCompletion) : null,
 			Object.hasOwn(patch, "pendingStateTransition"),
-			patch.pendingStateTransition ? JSON.stringify(patch.pendingStateTransition) : null
+			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] : []
 		])).rows.length === 1;
 	}
 	async renewActionInvocationLease(input) {
@@ -5151,11 +5445,13 @@ function toActionRecord(row) {
 		...row.execution_reason ? { executionReason: String(row.execution_reason) } : {},
 		...row.authorization_reconciliation ? { authorizationReconciliation: row.authorization_reconciliation } : {},
 		...row.adapter_reconciliation ? { adapterReconciliation: row.adapter_reconciliation } : {},
+		...row.finalization_checkpoint ? { finalizationCheckpoint: row.finalization_checkpoint } : {},
 		...row.pending_state_transition ? { pendingStateTransition: row.pending_state_transition } : {},
 		...row.pending_completion ? { pendingCompletion: toPendingCompletion(row.pending_completion) } : {},
 		...row.external_completion ? { externalCompletion: toExternalCompletion(row.external_completion) } : {},
 		...row.authorization_binding_id ? { authorizationBindingId: String(row.authorization_binding_id) } : {},
 		attemptCount: Number(row.attempt_count ?? 0),
+		...row.deferred_before_effect_attempt == null ? {} : { deferredBeforeEffectAttempt: Number(row.deferred_before_effect_attempt) },
 		leaseToken: Number(row.lease_token ?? 0),
 		...row.lease_owner ? { leaseOwner: String(row.lease_owner) } : {},
 		...row.lease_expires_at ? { leaseExpiresAt: new Date(row.lease_expires_at) } : {},