@context-action/core 0.9.2 → 1.0.0

package/dist/index.js

@@ -1,292 +1,3 @@
-//#region src/execution-modes.ts
-function isPromiseLike(value) {
-	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
-}
-/**
-* Create standardized error handling for handlers
-* 
-* @param error - The error that occurred
-* @param registration - The handler registration that failed
-* @returns Standardized HandlerError object
-* 
-* @internal
-*/
-function handleExecutionError(error, registration) {
-	const errorObj = error instanceof Error ? error : new Error(String(error));
-	return {
-		handlerId: registration.id,
-		error: errorObj,
-		timestamp: Date.now(),
-		severity: registration.config.blocking ? "blocking" : "non-blocking"
-	};
-}
-/**
-* Execute handlers in sequential mode (one after another)
-* 
-* Executes action handlers one at a time in priority order (highest first).
-* Supports both blocking and non-blocking handlers, with proper abort and
-* termination handling. Handlers can modify payload for subsequent handlers
-* and jump to different priority levels.
-* 
-* @template T - The payload type for the action
-* @template R - The result type for handlers
-* 
-* @param context - Pipeline execution context containing handlers and state
-* @param createController - Factory function for creating pipeline controllers
-* 
-* @throws {Error} When a blocking handler fails
-* 
-* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns
-* 
-* @public
-*/
-async function executeSequential(context, createController) {
-	let i = 0;
-	const nonBlockingPromises = [];
-	const errors = [];
-	while (i < context.handlers.length) {
-		if (context.aborted || context.terminated) break;
-		const registration = context.handlers[i];
-		if (!registration) continue;
-		context.currentIndex = i;
-		const controller = createController(registration, i);
-		try {
-			if (context.aborted) break;
-			if (registration.config.condition) try {
-				if (!registration.config.condition(context.payload)) {
-					i++;
-					continue;
-				}
-			} catch {
-				i++;
-				continue;
-			}
-			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
-			const result = registration.handler(context.payload, controller);
-			const asyncResult = isPromiseLike(result) ? Promise.resolve(result) : void 0;
-			const trackedResult = asyncResult && context.trackHandlerPromise ? context.trackHandlerPromise(asyncResult) : asyncResult;
-			if (registration.config.blocking) {
-				const handlerResult = trackedResult ? await trackedResult : result;
-				if (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
-			} else if (trackedResult) {
-				const promiseWithErrorHandling = trackedResult.then((asyncResult) => {
-					if (asyncResult !== void 0 && !context.terminated) context.results.push(asyncResult);
-					return asyncResult;
-				}).catch((error) => {
-					const handlerError = handleExecutionError(error, registration);
-					errors.push({
-						handlerId: handlerError.handlerId,
-						error: handlerError.error,
-						timestamp: handlerError.timestamp,
-						severity: "non-blocking"
-					});
-				});
-				nonBlockingPromises.push(promiseWithErrorHandling);
-			} else if (result !== void 0 && !context.terminated) context.results.push(result);
-			/** Check if pipeline was terminated by controller.return() */
-			if (context.terminated) break;
-			/** Handle jump to priority AFTER handler execution */
-			if (context.jumpToPriority !== void 0) {
-				context.jumpCount = (context.jumpCount || 0) + 1;
-				if (context.jumpCount > (context.maxJumps || 10)) {
-					console.error(`[ActionRegister] ERROR: Maximum jump limit (${context.maxJumps || 10}) exceeded. Aborting to prevent infinite loop. Check your jumpToPriority logic and conditions.`);
-					context.aborted = true;
-					context.abortReason = `Maximum jump limit exceeded (${context.jumpCount} jumps)`;
-					context.jumpToPriority = void 0;
-					break;
-				}
-				const jumpIndex = context.handlers.findIndex((handler) => (handler.config.priority || 0) <= context.jumpToPriority);
-				if (jumpIndex !== -1 && jumpIndex !== i) {
-					if (jumpIndex < i) {
-						const targetHandler = context.handlers[jumpIndex];
-						if (targetHandler && !targetHandler.config.condition) console.warn(`[ActionRegister] WARNING: Backward jumpToPriority to handler '${targetHandler.config.id || "unnamed"}' without condition. This may cause infinite loops! Consider adding a condition to prevent re-execution. Jump count: ${context.jumpCount}/${context.maxJumps || 10}`);
-					}
-					i = jumpIndex;
-					context.jumpToPriority = void 0;
-				} else {
-					context.jumpToPriority = void 0;
-					i++;
-				}
-			} else i++;
-		} catch (error) {
-			const handlerError = handleExecutionError(error, registration);
-			errors.push(handlerError);
-			if (registration.config.blocking) throw handlerError.error;
-			i++;
-		}
-	}
-	if (nonBlockingPromises.length > 0) await Promise.allSettled(nonBlockingPromises);
-	if (errors.length > 0) context.collectedErrors = errors.map((err) => ({
-		handlerId: err.handlerId,
-		error: err.error,
-		timestamp: err.timestamp,
-		severity: "non-blocking"
-	}));
-}
-/**
-* Execute handlers in parallel mode (all at once)
-* 
-* Executes all qualifying action handlers simultaneously using Promise.allSettled.
-* Supports both blocking and non-blocking handlers. Blocking handlers can still
-* fail the entire pipeline if they throw errors.
-* 
-* @template T - The payload type for the action
-* @template R - The result type for handlers
-* 
-* @param context - Pipeline execution context containing handlers and state
-* @param createController - Factory function for creating pipeline controllers
-* 
-* @throws {Error} When any blocking handler fails
-* 
-* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#parallel-execution
-* 
-* @public
-*/
-async function executeParallel(context, createController) {
-	/** All handlers are runnable */
-	const runnableHandlers = context.handlers;
-	/** Create promises for all handlers */
-	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
-		const controller = createController(registration, _index);
-		try {
-			if (registration.config.condition) try {
-				if (!registration.config.condition(context.payload)) return {
-					success: true,
-					handlerId: registration.id,
-					result: void 0,
-					terminated: false,
-					skipped: true
-				};
-			} catch {
-				return {
-					success: true,
-					handlerId: registration.id,
-					result: void 0,
-					terminated: false,
-					skipped: true
-				};
-			}
-			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
-			const result = registration.handler(context.payload, controller);
-			const handlerResult = isPromiseLike(result) ? await Promise.resolve(result) : result;
-			/** Collect result if handler returned something and pipeline wasn't terminated */
-			if (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
-			return {
-				success: true,
-				handlerId: registration.id,
-				result: handlerResult,
-				terminated: context.terminated
-			};
-		} catch (error) {
-			const handlerError = handleExecutionError(error, registration);
-			if (handlerError.severity === "blocking") throw handlerError.error;
-			return {
-				success: false,
-				handlerId: registration.id,
-				error: handlerError.error
-			};
-		}
-	});
-	const trackedHandlerPromises = context.trackHandlerPromise ? handlerPromises.map((promise) => context.trackHandlerPromise(promise)) : handlerPromises;
-	/** Wait for all handlers to complete */
-	const results = await Promise.allSettled(trackedHandlerPromises);
-	/** Check for any rejected blocking handlers */
-	const failures = results.filter((result, index) => {
-		if (result.status === "rejected") return runnableHandlers[index]?.config.blocking ?? false;
-		return false;
-	});
-	if (failures.length > 0) throw failures[0].reason;
-	/** Check if any handler terminated the pipeline */
-	const terminatedResults = results.filter((result) => result.status === "fulfilled" && result.value.terminated);
-	if (terminatedResults.length > 0) {
-		context.terminated = true;
-		context.terminationResult = terminatedResults[0].value.result;
-	}
-}
-/**
-* Execute handlers in race mode (first to complete wins)
-* 
-* Executes all qualifying handlers simultaneously using Promise.race, where
-* the first handler to complete determines the pipeline result. Other handlers
-* continue in the background and remain tracked for lifecycle cleanup; handlers
-* must observe the controller signal for cooperative external cancellation.
-* Useful for scenarios where you want the fastest response from multiple
-* equivalent handlers.
-* 
-* @template T - The payload type for the action
-* @template R - The result type for handlers
-* 
-* @param context - Pipeline execution context containing handlers and state
-* @param createController - Factory function for creating pipeline controllers
-* 
-* @throws {Error} When the winning handler fails and is blocking
-* 
-* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#race-execution
-* 
-* @public
-*/
-async function executeRace(context, createController) {
-	/** All handlers are runnable */
-	const runnableHandlers = context.handlers;
-	if (runnableHandlers.length === 0) return;
-	/** Create promises for all handlers */
-	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
-		const controller = createController(registration, _index);
-		try {
-			if (registration.config.condition) try {
-				if (!registration.config.condition(context.payload)) return {
-					success: true,
-					handlerId: registration.id,
-					registration,
-					result: void 0,
-					terminated: false,
-					skipped: true
-				};
-			} catch {
-				return {
-					success: true,
-					handlerId: registration.id,
-					registration,
-					result: void 0,
-					terminated: false,
-					skipped: true
-				};
-			}
-			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
-			const result = registration.handler(context.payload, controller);
-			const handlerResult = isPromiseLike(result) ? await Promise.resolve(result) : result;
-			return {
-				success: true,
-				handlerId: registration.id,
-				registration,
-				result: handlerResult,
-				terminated: context.terminated
-			};
-		} catch (error) {
-			const handlerError = handleExecutionError(error, registration);
-			return {
-				success: false,
-				handlerId: registration.id,
-				error: handlerError.error,
-				registration
-			};
-		}
-	});
-	const trackedHandlerPromises = context.trackHandlerPromise ? handlerPromises.map((promise) => context.trackHandlerPromise(promise)) : handlerPromises;
-	/** Race all handlers while retaining every loser for lifecycle draining. */
-	const winner = await Promise.race(trackedHandlerPromises);
-	/** If the winner failed and was blocking, throw the error */
-	if (!winner.success && winner.registration?.config.blocking) throw winner.error;
-	/** Collect result from the winning handler */
-	if (winner.success && winner.result !== void 0) context.results.push(winner.result);
-	/** Check if the winning handler terminated the pipeline */
-	if (winner.success && winner.terminated) {
-		context.terminated = true;
-		context.terminationResult = winner.result;
-	}
-}
-
-//#endregion
 //#region src/action-guard.ts
 /**
 * Action Guard system for managing action execution timing
@@ -321,8 +32,6 @@ var ActionGuard = class {
 		this.guards = /* @__PURE__ */ new Map();
 		this.maxIdleTime = 6e4;
 		this.cleanupIntervalMs = 3e4;
-		this.maxGuards = 1e3;
-		this.accessOrder = [];
 		this.autoCleanupEnabled = autoCleanup;
 	}
 	/** Start cleanup only after the first guard is used. */
@@ -353,75 +62,17 @@ var ActionGuard = class {
 	* @internal
 	*/
 	performCleanup() {
-		const guardCount = this.guards.size;
-		if (guardCount === 0) {
+		if (this.guards.size === 0) {
 			this.stopAutoCleanup();
 			return;
 		}
 		const now = Date.now();
-		const keysToDelete = [];
-		if (guardCount <= 10) this.guards.forEach((state, key) => {
-			const isIdle = now - state.lastExecuted > this.maxIdleTime;
+		for (const [key, state] of this.guards) {
+			const isIdle = now - Math.max(state.lastThrottleExecutedAt, state.lastDebounceSettledAt) > this.maxIdleTime;
 			const hasActiveTimers = state.debounceTimer || state.throttleTimer;
-			if (isIdle && !hasActiveTimers) keysToDelete.push(key);
-		});
-		else {
-			const entriesToCheck = Math.min(this.accessOrder.length, Math.ceil(guardCount / 4));
-			for (let i = 0; i < entriesToCheck; i++) {
-				const key = this.accessOrder[i];
-				if (!key) continue;
-				const state = this.guards.get(key);
-				if (!state) {
-					keysToDelete.push(key);
-					continue;
-				}
-				const isIdle = now - state.lastExecuted > this.maxIdleTime;
-				const hasActiveTimers = state.debounceTimer || state.throttleTimer;
-				if (isIdle && !hasActiveTimers) keysToDelete.push(key);
-			}
-		}
-		if (keysToDelete.length > 0) {
-			keysToDelete.forEach((key) => {
-				this.guards.delete(key);
-				const accessIndex = this.accessOrder.indexOf(key);
-				if (accessIndex !== -1) this.accessOrder.splice(accessIndex, 1);
-			});
-			if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Cleaned up ${keysToDelete.length} idle guards`);
-			if (this.guards.size === 0) this.stopAutoCleanup();
-		}
-	}
-	/**
-	* 🔧 Update access order for LRU tracking
-	*
-	* @internal
-	*/
-	updateAccessOrder(key) {
-		const existingIndex = this.accessOrder.indexOf(key);
-		if (existingIndex !== -1) this.accessOrder.splice(existingIndex, 1);
-		this.accessOrder.push(key);
-	}
-	/**
-	* 🔧 Evict oldest guards if max limit exceeded
-	*
-	* @internal
-	*/
-	evictIfNeeded() {
-		if (this.guards.size >= this.maxGuards) {
-			const evictCount = Math.ceil(this.maxGuards * .1);
-			this.accessOrder.slice(0, evictCount).forEach((key) => {
-				const state = this.guards.get(key);
-				if (state) {
-					if (state.debounceTimer) {
-						clearTimeout(state.debounceTimer);
-						if (state.debounceResolve) state.debounceResolve(false);
-					}
-					if (state.throttleTimer) clearTimeout(state.throttleTimer);
-				}
-				this.guards.delete(key);
-			});
-			this.accessOrder = this.accessOrder.slice(evictCount);
-			if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Evicted ${evictCount} oldest guards due to limit`);
+			if (isIdle && !hasActiveTimers) this.guards.delete(key);
 		}
+		if (this.guards.size === 0) this.stopAutoCleanup();
 	}
 	/**
 	* Apply debouncing to an action
@@ -445,24 +96,25 @@ var ActionGuard = class {
 	* 
 	* @internal
 	*/
-	async debounce(actionKey, debounceMs) {
+	async debounce(actionKey, debounceMs, signal) {
 		this.ensureAutoCleanup();
-		this.evictIfNeeded();
+		if (signal?.aborted) return false;
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
 		if (!state) {
 			/** Initialize new guard state with default values */
 			state = {
-				lastExecuted: 0,
+				lastThrottleExecutedAt: 0,
+				lastDebounceSettledAt: 0,
 				isThrottled: false,
 				debounceTimer: void 0,
 				throttleTimer: void 0,
-				debouncePromise: void 0,
-				debounceResolve: void 0
+				debounceResolve: void 0,
+				debounceAbortCleanup: void 0,
+				debounceRequestId: 0
 			};
 			this.guards.set(actionKey, state);
 		}
-		this.updateAccessOrder(actionKey);
 		/** Clear any existing debounce timer to restart the delay period */
 		if (state.debounceTimer) {
 			clearTimeout(state.debounceTimer);
@@ -470,18 +122,35 @@ var ActionGuard = class {
 				state.debounceResolve(false);
 				state.debounceResolve = void 0;
 			}
+			state.debounceAbortCleanup?.();
+			state.debounceAbortCleanup = void 0;
 		}
-		/** Create new debounce promise */
+		const requestId = ++state.debounceRequestId;
+		/** Create a new abort-aware debounce promise. */
 		return new Promise((resolve) => {
-			state.debounceResolve = resolve;
-			state.debounceTimer = setTimeout(() => {
-				/** Clean up timer and resolver references */
-				state.debounceTimer = void 0;
-				state.debounceResolve = void 0;
-				/** Update last execution timestamp */
-				state.lastExecuted = Date.now();
-				resolve(true);
-			}, debounceMs);
+			let settled = false;
+			let abortCleanup;
+			const finish = (allowed) => {
+				if (settled) return;
+				settled = true;
+				if (state.debounceRequestId === requestId) {
+					if (state.debounceTimer) clearTimeout(state.debounceTimer);
+					state.debounceTimer = void 0;
+					state.debounceResolve = void 0;
+					state.debounceAbortCleanup = void 0;
+					if (allowed) state.lastDebounceSettledAt = Date.now();
+				}
+				abortCleanup?.();
+				resolve(allowed);
+			};
+			state.debounceResolve = finish;
+			state.debounceTimer = setTimeout(() => finish(true), debounceMs);
+			if (signal) {
+				const abort = () => finish(false);
+				signal.addEventListener("abort", abort, { once: true });
+				abortCleanup = () => signal.removeEventListener("abort", abort);
+				state.debounceAbortCleanup = abortCleanup;
+			}
 		});
 	}
 	/**
@@ -506,31 +175,32 @@ var ActionGuard = class {
 	* 
 	* @internal
 	*/
-	throttle(actionKey, throttleMs) {
+	throttle(actionKey, throttleMs, signal) {
 		this.ensureAutoCleanup();
-		this.evictIfNeeded();
+		if (signal?.aborted) return false;
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
 		if (!state) {
 			/** Initialize new guard state with default values */
 			state = {
-				lastExecuted: 0,
+				lastThrottleExecutedAt: 0,
+				lastDebounceSettledAt: 0,
 				isThrottled: false,
 				debounceTimer: void 0,
 				throttleTimer: void 0,
-				debouncePromise: void 0,
-				debounceResolve: void 0
+				debounceResolve: void 0,
+				debounceAbortCleanup: void 0,
+				debounceRequestId: 0
 			};
 			this.guards.set(actionKey, state);
 		}
-		this.updateAccessOrder(actionKey);
 		const now = Date.now();
-		const timeSinceLastExecution = now - state.lastExecuted;
+		const timeSinceLastExecution = now - state.lastThrottleExecutedAt;
 		/** Check if enough time has passed since last execution */
 		/** If throttle period has elapsed, allow immediate execution */
 		if (timeSinceLastExecution >= throttleMs) {
 			/** Update execution timestamp and clear throttled state */
-			state.lastExecuted = now;
+			state.lastThrottleExecutedAt = now;
 			state.isThrottled = false;
 			return true;
 		}
@@ -570,13 +240,13 @@ var ActionGuard = class {
 				}
 				state.debounceTimer = void 0;
 			}
+			state.debounceAbortCleanup?.();
+			state.debounceAbortCleanup = void 0;
 			if (state.throttleTimer) {
 				clearTimeout(state.throttleTimer);
 				state.throttleTimer = void 0;
 			}
 			this.guards.delete(actionKey);
-			const accessIndex = this.accessOrder.indexOf(actionKey);
-			if (accessIndex !== -1) this.accessOrder.splice(accessIndex, 1);
 			if (this.guards.size === 0) this.stopAutoCleanup();
 		}
 	}
@@ -597,12 +267,12 @@ var ActionGuard = class {
 				clearTimeout(state.debounceTimer);
 				if (state.debounceResolve) state.debounceResolve(false);
 			}
+			state.debounceAbortCleanup?.();
 			/** Clear any active throttle timers */
 			if (state.throttleTimer) clearTimeout(state.throttleTimer);
 		});
 		/** Remove all guard states from memory */
 		this.guards.clear();
-		this.accessOrder = [];
 		this.stopAutoCleanup();
 	}
 	/**
@@ -861,11 +531,31 @@ var OperationQueue = class {
 
 //#endregion
 //#region src/errors.ts
-/**
-* Action payload 검증 실패 에러
-*
-* dispatch 시 Zod 스키마 검증이 실패하면 발생합니다.
-* (validationMode가 'strict'일 때만 throw)
+/** Raised when dispatch result aggregation options cannot be processed. */
+var ActionResultProcessingError = class ActionResultProcessingError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ActionResultProcessingError";
+		Object.setPrototypeOf(this, ActionResultProcessingError.prototype);
+	}
+};
+/** Signals work from a completed race attempt to stop before the next retry. */
+var ActionAttemptSupersededError = class ActionAttemptSupersededError extends Error {
+	constructor(attempt) {
+		super(`Action attempt ${attempt} was superseded by a retry.`);
+		this.attempt = attempt;
+		this.name = "ActionAttemptSupersededError";
+		Object.setPrototypeOf(this, ActionAttemptSupersededError.prototype);
+	}
+};
+function isActionResultProcessingError(error) {
+	return error instanceof ActionResultProcessingError;
+}
+/**
+* Action payload 검증 실패 에러
+*
+* dispatch 시 Zod 스키마 검증이 실패하면 발생합니다.
+* (validationMode가 'strict'일 때만 throw)
 *
 * @example
 * ```typescript
@@ -981,8 +671,443 @@ function isActionRegisterDestroyedError(error) {
 	return error instanceof ActionRegisterDestroyedError;
 }
 
+//#endregion
+//#region src/execution-modes.ts
+function isPromiseLike(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+function beginOutcome(registration) {
+	return {
+		id: registration.id,
+		status: "running",
+		executed: true,
+		duration: void 0,
+		result: void 0,
+		error: void 0,
+		metadata: registration.config.metadata ? { ...registration.config.metadata } : void 0
+	};
+}
+function createSkippedOutcome(registration) {
+	return {
+		id: registration.id,
+		status: "skipped",
+		executed: false,
+		duration: 0,
+		result: void 0,
+		error: void 0,
+		metadata: registration.config.metadata ? { ...registration.config.metadata } : void 0
+	};
+}
+function finishOutcome(outcome, startedAt, status, result, error) {
+	outcome.status = status;
+	outcome.duration = Date.now() - startedAt;
+	outcome.result = result;
+	outcome.error = error;
+}
+function appendLocalResults(context, state, returnedResult, registration, target = context.results) {
+	if (registration.role === "guard") return;
+	if (state.results.length > 0) target.push(...state.results);
+	if (returnedResult !== void 0 && !state.terminated) target.push(returnedResult);
+}
+/**
+* Create standardized error handling for handlers
+* 
+* @param error - The error that occurred
+* @param registration - The handler registration that failed
+* @returns Standardized HandlerError object
+* 
+* @internal
+*/
+function handleExecutionError(error, registration) {
+	const errorObj = error instanceof Error ? error : new Error(String(error));
+	return {
+		handlerId: registration.id,
+		error: errorObj,
+		timestamp: Date.now(),
+		severity: registration.config.errorPolicy === "fatal" ? "blocking" : "non-blocking"
+	};
+}
+/**
+* Execute handlers in sequential mode (one after another)
+* 
+* Executes action handlers one at a time in priority order (highest first).
+* Supports both blocking and non-blocking handlers, with proper abort and
+* termination handling. Handlers can modify payload for subsequent handlers
+* and jump to different priority levels.
+* 
+* @template T - The payload type for the action
+* @template R - The result type for handlers
+* 
+* @param context - Pipeline execution context containing handlers and state
+* @param createController - Factory function for creating pipeline controllers
+* 
+* @throws {Error} When a blocking handler fails
+* 
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns
+* 
+* @public
+*/
+async function executeSequential(context, createController) {
+	let i = 0;
+	const nonBlockingPromises = [];
+	const errors = [];
+	while (i < context.handlers.length) {
+		if (context.aborted || context.terminated) break;
+		const registration = context.handlers[i];
+		if (!registration) continue;
+		context.currentIndex = i;
+		const controller = createController(registration, i);
+		if (registration.config.condition) {
+			if (!registration.config.condition(context.payload)) {
+				(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+				i++;
+				continue;
+			}
+		}
+		if (context.claimOnce && !context.claimOnce(registration)) {
+			(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+			i++;
+			continue;
+		}
+		const outcome = beginOutcome(registration);
+		const startedAt = Date.now();
+		(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(outcome);
+		try {
+			if (context.aborted) {
+				outcome.status = "cancelled";
+				outcome.executed = false;
+				outcome.duration = 0;
+				break;
+			}
+			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
+			const result = registration.handler(context.payload, controller);
+			const asyncResult = isPromiseLike(result) ? Promise.resolve(result) : void 0;
+			const trackedResult = asyncResult && context.trackHandlerPromise ? context.trackHandlerPromise(asyncResult) : asyncResult;
+			if (registration.config.scheduling === "await-before-next") {
+				const handlerResult = trackedResult ? await trackedResult : result;
+				finishOutcome(outcome, startedAt, "succeeded", registration.role === "guard" ? void 0 : handlerResult);
+				if (registration.role !== "guard" && handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
+			} else if (trackedResult) {
+				const promiseWithErrorHandling = trackedResult.then((asyncResult) => {
+					finishOutcome(outcome, startedAt, "succeeded", registration.role === "guard" ? void 0 : asyncResult);
+					if (registration.role !== "guard" && asyncResult !== void 0 && !context.terminated) context.results.push(asyncResult);
+					return asyncResult;
+				}).catch((error) => {
+					const handlerError = handleExecutionError(error, registration);
+					errors.push(handlerError);
+					finishOutcome(outcome, startedAt, "failed", void 0, handlerError.error);
+				});
+				nonBlockingPromises.push(promiseWithErrorHandling);
+			} else if (registration.role !== "guard" && result !== void 0 && !context.terminated) {
+				finishOutcome(outcome, startedAt, "succeeded", result);
+				context.results.push(result);
+			} else finishOutcome(outcome, startedAt, "succeeded", registration.role === "guard" ? void 0 : result);
+			outcome.terminationRequested = context.terminated;
+			if (context.terminated) outcome.terminationResult = context.terminationResult;
+			/** Check if pipeline was terminated by controller.return() */
+			if (context.terminated) break;
+			/** Handle jump to priority AFTER handler execution */
+			if (context.jumpToPriority !== void 0) {
+				context.jumpCount = (context.jumpCount || 0) + 1;
+				if (context.jumpCount > (context.maxJumps || 10)) {
+					context.aborted = true;
+					context.abortReason = `Maximum jump limit exceeded (${context.jumpCount} jumps)`;
+					context.jumpToPriority = void 0;
+					break;
+				}
+				const jumpIndex = context.handlers.findIndex((handler) => (handler.config.priority || 0) <= context.jumpToPriority);
+				if (jumpIndex !== -1 && jumpIndex !== i) {
+					i = jumpIndex;
+					context.jumpToPriority = void 0;
+				} else {
+					context.jumpToPriority = void 0;
+					i++;
+				}
+			} else i++;
+		} catch (error) {
+			const handlerError = handleExecutionError(error, registration);
+			finishOutcome(outcome, startedAt, "failed", void 0, handlerError.error);
+			errors.push(handlerError);
+			(context.collectedErrors ?? (context.collectedErrors = [])).push(handlerError);
+			if (registration.config.errorPolicy === "fatal") throw handlerError.error;
+			i++;
+		}
+	}
+	if (nonBlockingPromises.length > 0) await Promise.allSettled(nonBlockingPromises);
+	if (errors.length > 0) context.collectedErrors = errors;
+	const fatalError = errors.find((error) => error.severity === "blocking");
+	if (fatalError) throw fatalError.error;
+}
+/**
+* Execute handlers in parallel mode (all at once)
+* 
+* Executes all qualifying action handlers simultaneously using Promise.allSettled.
+* Supports both blocking and non-blocking handlers. Blocking handlers can still
+* fail the entire pipeline if they throw errors.
+* 
+* @template T - The payload type for the action
+* @template R - The result type for handlers
+* 
+* @param context - Pipeline execution context containing handlers and state
+* @param createController - Factory function for creating pipeline controllers
+* 
+* @throws {Error} When any blocking handler fails
+* 
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#parallel-execution
+* 
+* @public
+*/
+async function executeParallel(context, createController) {
+	/**
+	* Conditions are dispatch preconditions in concurrent modes. Evaluate them
+	* before any handler starts so a predicate error rejects the dispatch rather
+	* than being mistaken for a non-blocking handler failure.
+	*/
+	const runnableHandlers = [];
+	for (const registration of context.handlers) {
+		if (registration.config.condition && !registration.config.condition(context.payload)) {
+			(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+			continue;
+		}
+		if (context.claimOnce && !context.claimOnce(registration)) {
+			(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+			continue;
+		}
+		runnableHandlers.push(registration);
+	}
+	const terminationSlots = runnableHandlers.map(() => ({
+		requested: false,
+		result: void 0
+	}));
+	const resultSlots = runnableHandlers.map(() => []);
+	/** Create promises for all handlers */
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const state = {
+			payload: context.payload,
+			aborted: false,
+			abortReason: void 0,
+			jumpToPriority: void 0,
+			terminated: false,
+			terminationResult: void 0,
+			results: []
+		};
+		const controller = createController(registration, _index, state);
+		const outcome = beginOutcome(registration);
+		const startedAt = Date.now();
+		(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(outcome);
+		try {
+			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
+			const result = registration.handler(state.payload, controller);
+			const handlerResult = isPromiseLike(result) ? await Promise.resolve(result) : result;
+			finishOutcome(outcome, startedAt, "succeeded", registration.role === "guard" ? void 0 : handlerResult);
+			outcome.terminationRequested = state.terminated;
+			if (state.terminated && registration.role !== "guard") {
+				outcome.terminationResult = state.terminationResult;
+				terminationSlots[_index] = {
+					requested: true,
+					result: state.terminationResult
+				};
+			}
+			appendLocalResults(context, state, handlerResult, registration, resultSlots[_index]);
+			return {
+				success: true,
+				handlerId: registration.id,
+				result: handlerResult,
+				terminated: state.terminated,
+				state,
+				outcome
+			};
+		} catch (error) {
+			const handlerError = handleExecutionError(error, registration);
+			finishOutcome(outcome, startedAt, "failed", void 0, handlerError.error);
+			(context.collectedErrors ?? (context.collectedErrors = [])).push(handlerError);
+			if (handlerError.severity === "blocking") throw handlerError.error;
+			return {
+				success: false,
+				handlerId: registration.id,
+				error: handlerError.error,
+				state,
+				outcome,
+				registration
+			};
+		}
+	});
+	const trackedHandlerPromises = context.trackHandlerPromise ? handlerPromises.map((promise) => context.trackHandlerPromise(promise)) : handlerPromises;
+	/** Wait for all handlers to complete */
+	const results = await Promise.allSettled(trackedHandlerPromises);
+	context.results.push(...resultSlots.flat());
+	/** Check for any rejected blocking handlers */
+	const failures = results.filter((result, index) => {
+		if (result.status === "rejected") return runnableHandlers[index]?.config.errorPolicy === "fatal";
+		return false;
+	});
+	if (failures.length > 0) throw failures[0].reason;
+	/** Check if any handler terminated the pipeline */
+	const firstTerminated = terminationSlots.find((slot) => slot.requested);
+	if (firstTerminated) {
+		context.terminated = true;
+		context.terminationResult = firstTerminated.result;
+	}
+}
+/**
+* Execute handlers in race mode (first to complete wins)
+* 
+* Executes all qualifying handlers simultaneously using Promise.race, where
+* the first handler to complete determines the pipeline result. Other handlers
+* continue in the background and remain tracked for lifecycle cleanup; handlers
+* must observe the controller signal for cooperative external cancellation.
+* Useful for scenarios where you want the fastest response from multiple
+* equivalent handlers.
+* 
+* @template T - The payload type for the action
+* @template R - The result type for handlers
+* 
+* @param context - Pipeline execution context containing handlers and state
+* @param createController - Factory function for creating pipeline controllers
+* 
+* @throws {Error} When the winning handler fails and is blocking
+* 
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#race-execution
+* 
+* @public
+*/
+async function executeRace(context, createController) {
+	/** See executeParallel: condition errors are dispatch errors in concurrent modes. */
+	const runnableHandlers = [];
+	for (const registration of context.handlers) {
+		if (registration.config.condition && !registration.config.condition(context.payload)) {
+			(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+			continue;
+		}
+		if (context.claimOnce && !context.claimOnce(registration)) {
+			(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(createSkippedOutcome(registration));
+			continue;
+		}
+		runnableHandlers.push(registration);
+	}
+	if (runnableHandlers.length === 0) return;
+	/** Create promises for all handlers */
+	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
+		const state = {
+			payload: context.payload,
+			aborted: false,
+			abortReason: void 0,
+			jumpToPriority: void 0,
+			terminated: false,
+			terminationResult: void 0,
+			results: []
+		};
+		const controller = createController(registration, _index, state);
+		const outcome = beginOutcome(registration);
+		const startedAt = Date.now();
+		(context.handlerOutcomes ?? (context.handlerOutcomes = [])).push(outcome);
+		try {
+			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
+			const result = registration.handler(state.payload, controller);
+			const handlerResult = isPromiseLike(result) ? await Promise.resolve(result) : result;
+			finishOutcome(outcome, startedAt, "succeeded", registration.role === "guard" ? void 0 : handlerResult);
+			outcome.terminationRequested = state.terminated;
+			if (state.terminated) outcome.terminationResult = state.terminationResult;
+			return {
+				success: true,
+				handlerId: registration.id,
+				registration,
+				result: handlerResult,
+				terminated: state.terminated,
+				state,
+				outcome
+			};
+		} catch (error) {
+			const handlerError = handleExecutionError(error, registration);
+			finishOutcome(outcome, startedAt, "failed", void 0, handlerError.error);
+			return {
+				success: false,
+				handlerId: registration.id,
+				error: handlerError.error,
+				registration,
+				state,
+				outcome
+			};
+		}
+	});
+	const trackedHandlerPromises = context.trackHandlerPromise ? handlerPromises.map((promise) => context.trackHandlerPromise(promise)) : handlerPromises;
+	const winnerCandidates = runnableHandlers.some((handler) => handler.role !== "guard") ? trackedHandlerPromises.filter((_, index) => runnableHandlers[index]?.role !== "guard") : trackedHandlerPromises;
+	/** Race all handlers while retaining every loser for lifecycle draining. */
+	const winner = await Promise.race(winnerCandidates);
+	context.raceWinnerId = winner.handlerId;
+	context.raceLoserOutcomes = (context.handlerOutcomes ?? []).filter((outcome) => outcome.id !== winner.handlerId).map((outcome) => ({
+		...outcome,
+		metadata: outcome.metadata ? { ...outcome.metadata } : void 0
+	}));
+	/** If the winner failed and was blocking, throw the error */
+	if (!winner.success && winner.registration?.config.errorPolicy === "fatal") {
+		(context.collectedErrors ?? (context.collectedErrors = [])).push(handleExecutionError(winner.error, winner.registration));
+		throw winner.error;
+	}
+	if (!winner.success) (context.collectedErrors ?? (context.collectedErrors = [])).push(handleExecutionError(winner.error, winner.registration));
+	/** Only the winner contributes results to the race snapshot. */
+	if (winner.success) {
+		appendLocalResults(context, winner.state, winner.result, winner.registration);
+		if (winner.state.aborted) {
+			context.aborted = true;
+			context.abortReason = winner.state.abortReason;
+		}
+	}
+	/** Check if the winning handler terminated the pipeline */
+	if (winner.success && winner.terminated) {
+		context.terminated = true;
+		context.terminationResult = winner.state.terminationResult;
+	}
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* Resolve the supported `blocking` shorthand and all registration
+* defaults in one place. Adapters should pass their original config to the
+* registry and use this helper only when they need to expose resolved values.
+*/
+function resolveHandlerConfig(config, handlerId) {
+	return {
+		priority: config?.priority ?? 0,
+		id: handlerId,
+		blocking: config?.errorPolicy === "fatal" || config?.blocking === true,
+		scheduling: config?.scheduling ?? (config?.blocking === false ? "start-and-continue" : "await-before-next"),
+		errorPolicy: config?.errorPolicy ?? (config?.blocking === true ? "fatal" : "collect"),
+		once: config?.once ?? false,
+		debounce: config?.debounce,
+		throttle: config?.throttle,
+		replaceExisting: config?.replaceExisting ?? true,
+		cleanup: config?.cleanup,
+		condition: config?.condition,
+		metadata: config?.metadata
+	};
+}
+
 //#endregion
 //#region src/ActionRegister.ts
+const RESERVED_PROXY_KEYS = /* @__PURE__ */ new Set([
+	"then",
+	"catch",
+	"finally",
+	"toJSON",
+	"constructor",
+	"__proto__",
+	"prototype"
+]);
+const ATTEMPT_SIGNAL_CLEANUP = Symbol("attemptSignalCleanup");
+function snapshotHandlerOutcome(outcome) {
+	return {
+		...outcome,
+		metadata: outcome.metadata ? { ...outcome.metadata } : void 0
+	};
+}
+function normalizePositiveLimit(value, fallback, label) {
+	const limit = value ?? fallback;
+	if (limit === Infinity) return limit;
+	if (!Number.isSafeInteger(limit) || limit <= 0) throw new RangeError(`${label} must be a positive safe integer or Infinity.`);
+	return limit;
+}
 /**
 * Action Register for managing action handlers with priority-based execution
 * 
@@ -1001,23 +1126,27 @@ function isActionRegisterDestroyedError(error) {
 var ActionRegister = class {
 	constructor(config = {}) {
 		this.pipelines = /* @__PURE__ */ new Map();
+		this.observerHandlers = /* @__PURE__ */ new Map();
+		this.claimedOnceHandlers = /* @__PURE__ */ new WeakSet();
 		this.executionMode = "sequential";
 		this.actionExecutionModes = /* @__PURE__ */ new Map();
 		this.unregisterFunctions = /* @__PURE__ */ new Map();
 		this.lastRegisteredTimestamps = /* @__PURE__ */ new Map();
 		this.handlerIdCounter = 0;
-		this.controllerPool = [];
 		this.lifecycleState = "active";
 		this.lifecycleController = new AbortController();
 		this.activeDispatches = /* @__PURE__ */ new Set();
 		this.activeHandlerPromises = /* @__PURE__ */ new Set();
 		this.dispatchConstructionDepth = 0;
+		this.actionDispatchers = /* @__PURE__ */ new Map();
+		this.actionResultDispatchers = /* @__PURE__ */ new Map();
 		this.name = config.name || "ActionRegister";
 		this.registryConfig = config.registry;
-		this.maxHandlersPerAction = config.registry?.maxHandlersPerAction ?? 1e3;
-		this.isDebugMode = Boolean(this.registryConfig?.debug && true);
+		this.maxHandlersPerAction = normalizePositiveLimit(config.registry?.maxHandlersPerAction, Infinity, "maxHandlersPerAction");
+		this.maxJumps = normalizePositiveLimit(config.registry?.maxJumps, 10, "maxJumps");
+		this.isDebugMode = this.registryConfig?.debug === true;
 		this.actionGuard = new ActionGuard(this.registryConfig?.autoCleanup !== false);
-		if (config.registry?.useConcurrencyQueue !== false) this.dispatchQueue = new OperationQueue(`${this.name}-Dispatch`);
+		if (config.registry?.useConcurrencyQueue === true) this.dispatchQueue = new OperationQueue(`${this.name}-Dispatch`);
 		if (this.registryConfig?.defaultExecutionMode) this.executionMode = this.registryConfig.defaultExecutionMode;
 		this.log("ActionRegister initialized", {
 			defaultExecutionMode: this.executionMode,
@@ -1051,10 +1180,15 @@ var ActionRegister = class {
 	*/
 	get actions() {
 		if (!this._actionsProxy) this._actionsProxy = new Proxy({}, { get: (_target, prop) => {
+			if (typeof prop !== "string") return void 0;
+			if (RESERVED_PROXY_KEYS.has(prop)) return void 0;
 			const actionKey = prop;
-			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payload, options) => {
-				return this.dispatch(actionKey, payload, options);
-			};
+			let dispatcher = this.actionDispatchers.get(prop);
+			if (!dispatcher) {
+				dispatcher = (payload, options) => this.dispatch(actionKey, ...[payload, options]);
+				this.actionDispatchers.set(prop, dispatcher);
+			}
+			return dispatcher;
 		} });
 		return this._actionsProxy;
 	}
@@ -1087,32 +1221,76 @@ var ActionRegister = class {
 	*/
 	get actionsWithResult() {
 		if (!this._actionsWithResultProxy) this._actionsWithResultProxy = new Proxy({}, { get: (_target, prop) => {
+			if (typeof prop !== "string") return void 0;
+			if (RESERVED_PROXY_KEYS.has(prop)) return void 0;
 			const actionKey = prop;
-			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payload, options) => {
-				return this.dispatchWithResult(actionKey, payload, options);
-			};
+			let dispatcher = this.actionResultDispatchers.get(prop);
+			if (!dispatcher) {
+				const dispatchAction = this.dispatchWithResult.bind(this);
+				dispatcher = (payload, options) => dispatchAction(actionKey, ...[payload, options]);
+				this.actionResultDispatchers.set(prop, dispatcher);
+			}
+			return dispatcher;
 		} });
 		return this._actionsWithResultProxy;
 	}
+	register(action, handler, config = {}) {
+		return this.registerWithRole(action, handler, config, "legacy");
+	}
+	registerEffect(action, handler, config) {
+		if (config.effectKind === "guard") return this.registerGuard(action, handler, config);
+		return this.registerObserver(action, (event) => handler(event.payload, {
+			signal: event.signal,
+			getPayload: () => event.payload
+		}), config);
+	}
+	/** Register an authorization or validation guard that always runs before
+	* concurrent result arbitration. */
+	registerGuard(action, handler, config = {}) {
+		return this.registerWithRole(action, handler, {
+			...config,
+			scheduling: "await-before-next",
+			errorPolicy: "fatal"
+		}, "guard");
+	}
+	/** Register a terminal observer. It runs after result aggregation and has
+	* no controller, result, payload, or winner-selection capabilities. */
+	registerObserver(action, handler, config = {}) {
+		const handlerId = config.id ?? this.generateHandlerId(action);
+		const existing = this.pipelines.get(action)?.find((item) => item.id === handlerId);
+		if (existing && (existing.role ?? "legacy") !== "observer") throw new Error(`Action handler role conflict for "${String(action)}" and id "${handlerId}": cannot replace ${existing.role ?? "legacy"} with observer.`);
+		if (existing && config.replaceExisting === false) return () => {};
+		const unregister = this.registerWithRole(action, (() => void 0), {
+			...config,
+			id: handlerId
+		}, "observer");
+		const registration = this.pipelines.get(action)?.find((item) => item.id === handlerId);
+		if (!registration) {
+			unregister();
+			throw new Error(`Observer registration "${handlerId}" was not retained.`);
+		}
+		this.observerHandlers.set(registration, {
+			handler,
+			when: config.when ?? "always"
+		});
+		return () => {
+			this.observerHandlers.delete(registration);
+			unregister();
+		};
+	}
 	/**
-	* Register an action handler with optional configuration
-	* 
-	* @param action - The action type to register handler for
-	* @param handler - The handler function to execute
-	* @param config - Optional handler configuration including priority, tags, etc.
-	* 
-	* @returns Unregister function to remove this handler
-	* 
-	* @throws {Error} When maximum handlers limit is reached
-	* 
-	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
-	* 
+	* Register a handler that contributes the result declared for an action.
+	*
 	* @public
 	*/
-	register(action, handler, config = {}) {
+	registerResult(action, handler, config) {
+		return this.registerWithRole(action, handler, config ?? {}, "result");
+	}
+	registerWithRole(action, handler, config, role) {
+		this.assertStringActionKey(action);
 		this.assertAcceptingWork();
 		const handlerId = config.id || this.generateHandlerId(action);
-		return this._performRegistrationSync(action, handler, config, handlerId);
+		return this._performRegistrationSync(action, handler, config, handlerId, role);
 	}
 	/**
 	* 🆕 Unified logging method with cached debug mode check
@@ -1126,6 +1304,9 @@ var ActionRegister = class {
 	assertAcceptingWork() {
 		if (this.lifecycleState !== "active") throw new ActionRegisterDestroyedError(this.name, this.lifecycleState);
 	}
+	assertStringActionKey(action) {
+		if (typeof action !== "string") throw new TypeError("Action keys must be strings.");
+	}
 	rejectedLifecyclePromise() {
 		const error = new ActionRegisterDestroyedError(this.name, this.lifecycleState === "active" ? "destroyed" : this.lifecycleState);
 		const rejected = Promise.reject(error);
@@ -1195,44 +1376,35 @@ var ActionRegister = class {
 	/**
 	* 🆕 Perform synchronous handler registration
 	*/
-	_performRegistrationSync(action, handler, config, handlerId) {
+	_performRegistrationSync(action, handler, config, handlerId, role = "legacy") {
 		const registration = {
 			handler,
-			config: {
-				priority: config.priority ?? 0,
-				id: handlerId,
-				blocking: config.blocking ?? false,
-				once: config.once ?? false,
-				debounce: config.debounce ?? void 0,
-				throttle: config.throttle ?? void 0,
-				replaceExisting: config.replaceExisting ?? true,
-				cleanup: config.cleanup,
-				condition: config.condition
-			},
-			id: handlerId
+			config: resolveHandlerConfig(config, handlerId),
+			id: handlerId,
+			role
 		};
 		if (!this.pipelines.has(action)) this.pipelines.set(action, []);
 		const pipeline = this.pipelines.get(action);
-		if (pipeline.length >= this.maxHandlersPerAction) {
-			console.warn(`Handler limit (${this.maxHandlersPerAction}) reached for action "${String(action)}". Registration ignored.`);
-			return () => {};
-		}
+		const actionUnregisterFunctions = this.getUnregisterFunctions(action);
 		const existingIndex = pipeline.findIndex((reg) => reg.id === handlerId);
+		if (existingIndex === -1 && pipeline.length >= this.maxHandlersPerAction) throw new RangeError(`Handler limit (${this.maxHandlersPerAction}) reached for action "${String(action)}".`);
 		if (existingIndex !== -1) {
 			const existing = pipeline[existingIndex];
-			const existingUnregister = this.unregisterFunctions.get(handlerId);
+			const existingUnregister = actionUnregisterFunctions.get(handlerId);
+			if (existing && (existing.role ?? "legacy") !== role) throw new Error(`Action handler role conflict for "${String(action)}" and id "${handlerId}": cannot replace ${existing.role ?? "legacy"} with ${role}.`);
 			if (registration.config.replaceExisting) {
 				if (existing?.config.cleanup && typeof existing.config.cleanup === "function") try {
 					existing.config.cleanup();
 				} catch (cleanupError) {
 					this.log(`Cleanup error for replaced handler: ${String(action)}`, cleanupError, "warn");
 				}
-				if (existingUnregister) this.unregisterFunctions.delete(handlerId);
+				if (existing) this.observerHandlers.delete(existing);
+				if (existingUnregister) actionUnregisterFunctions.delete(handlerId);
 				pipeline[existingIndex] = registration;
 				pipeline.sort((a, b) => b.config.priority - a.config.priority);
 				this.lastRegisteredTimestamps.set(action, /* @__PURE__ */ new Date());
 				const newUnregister = this.createUnregisterFunction(action, handlerId, registration);
-				this.unregisterFunctions.set(handlerId, newUnregister);
+				actionUnregisterFunctions.set(handlerId, newUnregister);
 				this.log(`Handler replaced: ${String(action)}`, {
 					handlerId,
 					priority: config.priority,
@@ -1253,7 +1425,7 @@ var ActionRegister = class {
 				if (existingUnregister) return existingUnregister;
 				else {
 					const newUnregister = this.createUnregisterFunction(action, handlerId, existing);
-					this.unregisterFunctions.set(handlerId, newUnregister);
+					actionUnregisterFunctions.set(handlerId, newUnregister);
 					return newUnregister;
 				}
 			}
@@ -1262,7 +1434,7 @@ var ActionRegister = class {
 		pipeline.sort((a, b) => b.config.priority - a.config.priority);
 		this.lastRegisteredTimestamps.set(action, /* @__PURE__ */ new Date());
 		const unregister = this.createUnregisterFunction(action, handlerId, registration);
-		this.unregisterFunctions.set(handlerId, unregister);
+		actionUnregisterFunctions.set(handlerId, unregister);
 		this.log(`Handler registered: ${String(action)}`, {
 			handlerId,
 			priority: config.priority,
@@ -1270,59 +1442,233 @@ var ActionRegister = class {
 		});
 		return unregister;
 	}
-	dispatch(action, payload, options) {
+	dispatch(action, ...args) {
+		this.assertStringActionKey(action);
+		const [payload, options] = args;
 		if (this.lifecycleState !== "active") return this.rejectedLifecyclePromise();
 		const timeoutScope = this.createTimeoutScope(action, options);
 		const dispatchHandlerPromises = /* @__PURE__ */ new Set();
 		const attemptState = { count: 0 };
-		const operation = async () => {
-			if (!timeoutScope.options?.signal?.aborted) this.validatePayload(action, payload);
-			return this.executeWithRetry(async () => {
+		const plan = this.resolveDispatchPlan(action, options);
+		const hasTimingGuard = plan.debounceMs !== void 0 || plan.throttleMs !== void 0;
+		let observerNotified = false;
+		let terminalErrorReported = false;
+		const reportTerminalError = (error) => {
+			if (terminalErrorReported) return;
+			terminalErrorReported = true;
+			this.invokeErrorHandler(error, action, payload, options, attemptState.count);
+		};
+		const notifyObservers = async (event) => {
+			if (observerNotified) return;
+			observerNotified = true;
+			await this.executeObservers(action, plan, event);
+		};
+		const pipelineOperation = async () => {
+			const guard = plan.guards.length > 0 ? await this.executeGuardPhase(action, payload, timeoutScope.options, plan, dispatchHandlerPromises) : {
+				allowed: true,
+				payload,
+				aborted: false,
+				abortReason: void 0,
+				error: void 0,
+				errors: [],
+				outcomes: [],
+				executedHandlers: [],
+				duration: 0
+			};
+			this.cleanupOneTimeHandlers(action, guard.executedHandlers, dispatchHandlerPromises);
+			if (!guard.allowed) {
+				await notifyObservers({
+					action: String(action),
+					payload: guard.payload,
+					outcome: guard.aborted ? "cancelled" : "failed",
+					result: void 0,
+					errors: guard.errors,
+					signal: timeoutScope.options?.signal
+				});
+				if (!guard.aborted && guard.errors.length > 0) throw guard.error ?? guard.errors[0]?.error ?? /* @__PURE__ */ new Error(`Guard phase failed for "${String(action)}"`);
+				return;
+			}
+			const execution = await this.executeWithRetry(async (attemptSignal) => {
 				const executedHandlers = [];
 				try {
-					return await this._performDispatch(action, payload, timeoutScope.options, attemptState.count > 1, executedHandlers, dispatchHandlerPromises);
+					return await this._performDispatchWithResult(action, guard.payload, this.withAttemptSignal(timeoutScope.options, attemptSignal), void 0, plan, executedHandlers, dispatchHandlerPromises);
 				} finally {
 					this.cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises);
 				}
-			}, timeoutScope.options, attemptState, void 0, () => this.getHandlerCount(action) > 0);
+			}, timeoutScope.options, attemptState, (result) => result.outcome === "failed", () => this.getAttemptHandlers(action, plan).length > 0, void 0, this.shouldDrainBeforeRetry(plan, timeoutScope.options) ? () => this.drainAttemptHandlers(dispatchHandlerPromises) : void 0);
+			if (execution.outcome === "failed") throw execution.errors[execution.errors.length - 1]?.error ?? /* @__PURE__ */ new Error(`Action "${String(action)}" failed`);
+			const result = this.processResults(execution.results, execution.terminated, execution.terminated ? execution.result : void 0, options?.result);
+			await notifyObservers({
+				action: String(action),
+				payload: guard.payload,
+				outcome: execution.outcome,
+				result,
+				errors: execution.errors,
+				signal: timeoutScope.options?.signal
+			});
+		};
+		const operation = async () => {
+			if (timeoutScope.options?.signal?.aborted) {
+				await notifyObservers({
+					action: String(action),
+					payload,
+					outcome: "cancelled",
+					result: void 0,
+					errors: [],
+					signal: timeoutScope.options?.signal
+				});
+				return;
+			}
+			this.validatePayload(action, payload);
+			this.validateResultOptions(options?.result);
+			if (timeoutScope.options?.signal?.aborted) {
+				await notifyObservers({
+					action: String(action),
+					payload,
+					outcome: "cancelled",
+					result: void 0,
+					errors: [],
+					signal: timeoutScope.options?.signal
+				});
+				return;
+			}
+			if (hasTimingGuard) {
+				const admission = await this.evaluateTimingGuards(String(action), plan, timeoutScope.options?.signal);
+				if (admission.aborted || timeoutScope.options?.signal?.aborted || admission.reason) {
+					await notifyObservers({
+						action: String(action),
+						payload,
+						outcome: admission.aborted || timeoutScope.options?.signal?.aborted ? "cancelled" : admission.reason === "Debounced execution" ? "debounced" : "throttled",
+						result: void 0,
+						errors: admission.reason ? [{
+							handlerId: "admission",
+							error: new Error(admission.reason),
+							timestamp: Date.now(),
+							severity: "blocking"
+						}] : [],
+						signal: timeoutScope.options?.signal
+					});
+					return;
+				}
+			}
+			if (timeoutScope.options?.signal?.aborted) {
+				await notifyObservers({
+					action: String(action),
+					payload,
+					outcome: "cancelled",
+					result: void 0,
+					errors: [],
+					signal: timeoutScope.options?.signal
+				});
+				return;
+			}
+			if (timeoutScope.options?.immediate || !this.dispatchQueue) return pipelineOperation();
+			const queued = this.dispatchQueue.enqueueWithHandle(pipelineOperation, timeoutScope.options?.queuePriority ?? 0);
+			timeoutScope.onTimeout((error) => queued.cancel(error));
+			return queued.promise;
 		};
-		const hasTimingGuard = options?.debounce !== void 0 || options?.throttle !== void 0 || this.pipelines.get(action)?.some((handler) => handler.config.debounce !== void 0 || handler.config.throttle !== void 0) === true;
 		let dispatchPromise;
+		let observedDispatchPromise;
 		this.dispatchConstructionDepth += 1;
 		try {
-			if (timeoutScope.options?.immediate || hasTimingGuard || !this.dispatchQueue) dispatchPromise = operation();
-			else {
-				const queued = this.dispatchQueue.enqueueWithHandle(operation, timeoutScope.options?.queuePriority ?? 0);
-				timeoutScope.onTimeout((error) => queued.cancel(error));
-				dispatchPromise = queued.promise;
-			}
-			this.trackDispatchPromise(dispatchPromise);
+			dispatchPromise = operation();
+			observedDispatchPromise = dispatchPromise.catch(async (error) => {
+				reportTerminalError(error);
+				await notifyObservers({
+					action: String(action),
+					payload,
+					outcome: "failed",
+					result: void 0,
+					errors: [{
+						handlerId: "dispatch",
+						error: error instanceof Error ? error : new Error(String(error)),
+						timestamp: Date.now(),
+						severity: "blocking"
+					}],
+					signal: timeoutScope.options?.signal
+				});
+				throw error;
+			});
+			this.trackDispatchPromise(observedDispatchPromise);
 		} finally {
 			this.dispatchConstructionDepth -= 1;
 		}
-		const observedPromise = this.raceWithTimeout(dispatchPromise, timeoutScope, dispatchHandlerPromises).catch((error) => {
-			this.invokeErrorHandler(error, action, payload, options, attemptState.count);
+		const observedPromise = this.raceWithTimeout(observedDispatchPromise, timeoutScope, dispatchHandlerPromises).catch(async (error) => {
+			reportTerminalError(error);
+			if (!observerNotified) await this.trackGlobalHandlerPromise(notifyObservers({
+				action: String(action),
+				payload,
+				outcome: "failed",
+				result: void 0,
+				errors: [{
+					handlerId: "dispatch",
+					error: error instanceof Error ? error : new Error(String(error)),
+					timestamp: Date.now(),
+					severity: "blocking"
+				}],
+				signal: timeoutScope.options?.signal
+			}));
 			throw error;
 		});
 		observedPromise.catch(() => {});
 		return observedPromise;
 	}
 	/** Execute a dispatch operation with an optional whole-action retry policy. */
-	async executeWithRetry(operation, options, attemptState, shouldRetryResult, canRetry = () => true) {
+	async executeWithRetry(operation, options, attemptState, shouldRetryResult, canRetry = () => true, telemetry, beforeRetry) {
 		const configuredAttempts = options?.retryOnError?.maxAttempts ?? 1;
 		const maxAttempts = Number.isFinite(configuredAttempts) ? Math.max(1, Math.floor(configuredAttempts)) : 1;
 		const retryDelay = Math.max(0, options?.retryOnError?.delay ?? 0);
 		while (attemptState.count < maxAttempts) {
 			attemptState.count += 1;
+			const attemptStartedAt = Date.now();
+			const attemptController = new AbortController();
 			try {
-				const result = await operation();
-				if (!(shouldRetryResult?.(result) ?? false) || attemptState.count >= maxAttempts || options?.signal?.aborted || !canRetry()) return result;
+				const result = await operation(attemptController.signal);
+				const shouldRetry = shouldRetryResult?.(result) ?? false;
+				const canRetryAttempt = shouldRetry && attemptState.count < maxAttempts && !options?.signal?.aborted && canRetry();
+				const attemptEndedAt = Date.now();
+				telemetry?.attempts.push({
+					startTime: attemptStartedAt,
+					endTime: attemptEndedAt,
+					duration: attemptEndedAt - attemptStartedAt,
+					outcome: shouldRetry ? canRetryAttempt ? "retried" : "failed" : "succeeded"
+				});
+				if (telemetry) telemetry.pipelineDuration += attemptEndedAt - attemptStartedAt;
+				if (!canRetryAttempt) return result;
+				attemptController.abort(new ActionAttemptSupersededError(attemptState.count));
+				await beforeRetry?.();
+				const retryStartedAt = Date.now();
+				const shouldContinue = await this.waitForRetry(retryDelay, options?.signal);
+				if (telemetry) telemetry.retryDelayDuration += Date.now() - retryStartedAt;
+				if (!shouldContinue) {
+					telemetry?.attempts.push({
+						startTime: Date.now(),
+						endTime: Date.now(),
+						duration: 0,
+						outcome: "cancelled"
+					});
+					return result;
+				}
 			} catch (error) {
-				if (error instanceof ActionValidationError || attemptState.count >= maxAttempts || options?.signal?.aborted || !canRetry()) throw error;
+				const attemptEndedAt = Date.now();
+				const canRetryAttempt = !(error instanceof ActionValidationError || attemptState.count >= maxAttempts || options?.signal?.aborted || !canRetry());
+				telemetry?.attempts.push({
+					startTime: attemptStartedAt,
+					endTime: attemptEndedAt,
+					duration: attemptEndedAt - attemptStartedAt,
+					outcome: canRetryAttempt ? "retried" : "failed"
+				});
+				if (telemetry) telemetry.pipelineDuration += attemptEndedAt - attemptStartedAt;
+				if (!canRetryAttempt) throw error;
+				attemptController.abort(new ActionAttemptSupersededError(attemptState.count));
+				await beforeRetry?.();
+				const retryStartedAt = Date.now();
+				const shouldContinue = await this.waitForRetry(retryDelay, options?.signal);
+				if (telemetry) telemetry.retryDelayDuration += Date.now() - retryStartedAt;
+				if (!shouldContinue) throw error;
 			}
-			await this.waitForRetry(retryDelay, options?.signal);
 		}
-		return operation();
+		return operation(new AbortController().signal);
 	}
 	trackDispatchPromise(promise) {
 		this.activeDispatches.add(promise);
@@ -1340,6 +1686,43 @@ var ActionRegister = class {
 		promise.then(remove, remove);
 		return promise;
 	}
+	withAttemptSignal(options, attemptSignal) {
+		const outerSignal = options?.signal;
+		if (!outerSignal) return {
+			...options,
+			signal: attemptSignal
+		};
+		if (typeof AbortSignal.any === "function") return {
+			...options,
+			signal: AbortSignal.any([outerSignal, attemptSignal])
+		};
+		const controller = new AbortController();
+		const forwardOuter = () => controller.abort(outerSignal.reason);
+		const forwardAttempt = () => controller.abort(attemptSignal.reason);
+		if (outerSignal.aborted) forwardOuter();
+		else outerSignal.addEventListener("abort", forwardOuter, { once: true });
+		if (attemptSignal.aborted) forwardAttempt();
+		else attemptSignal.addEventListener("abort", forwardAttempt, { once: true });
+		const cleanup = () => {
+			outerSignal.removeEventListener("abort", forwardOuter);
+			attemptSignal.removeEventListener("abort", forwardAttempt);
+		};
+		controller.signal.addEventListener("abort", cleanup, { once: true });
+		return {
+			...options,
+			signal: controller.signal,
+			[ATTEMPT_SIGNAL_CLEANUP]: cleanup
+		};
+	}
+	shouldDrainBeforeRetry(plan, options) {
+		return (options?.retryOnError?.attemptBarrier ?? (plan.executionMode === "race" ? "abort-and-drain" : "abort-and-overlap")) === "abort-and-drain";
+	}
+	/** Do not begin a whole-action retry while a previous race loser is still
+	* running. Handlers should still observe their signal for cancellation. */
+	async drainAttemptHandlers(dispatchHandlerPromises) {
+		const pending = [...dispatchHandlerPromises];
+		if (pending.length > 0) await Promise.allSettled(pending);
+	}
 	trackGlobalHandlerPromise(promise) {
 		this.activeHandlerPromises.add(promise);
 		const remove = () => this.activeHandlerPromises.delete(promise);
@@ -1348,22 +1731,25 @@ var ActionRegister = class {
 	}
 	/** Abort-aware retry delay so cancellation does not wait for the full backoff. */
 	waitForRetry(delay, signal) {
-		if (delay <= 0 || signal?.aborted) return Promise.resolve();
+		if (signal?.aborted) return Promise.resolve(false);
+		if (delay <= 0) return Promise.resolve(true);
 		return new Promise((resolve) => {
 			const timer = setTimeout(finish, delay);
-			const abort = () => finish();
-			function finish() {
+			const abort = () => finish(false);
+			function finish(shouldContinue = true) {
 				clearTimeout(timer);
 				signal?.removeEventListener("abort", abort);
-				resolve();
+				resolve(shouldContinue);
 			}
 			signal?.addEventListener("abort", abort, { once: true });
 		});
 	}
 	/** Build a wall-clock timeout that also participates in pipeline cancellation. */
 	createTimeoutScope(action, options) {
-		const hasTimeout = options?.timeout !== void 0 && Number.isFinite(options.timeout);
-		const timeout = hasTimeout ? Math.max(0, options.timeout) : void 0;
+		const configuredTimeout = options?.timeout;
+		if (configuredTimeout !== void 0 && (!Number.isFinite(configuredTimeout) || configuredTimeout < 0)) throw new RangeError("timeout must be a non-negative finite number.");
+		const hasTimeout = configuredTimeout !== void 0;
+		const timeout = configuredTimeout;
 		const timeoutController = hasTimeout ? new AbortController() : void 0;
 		const signalCleanups = [];
 		const timeoutCallbacks = /* @__PURE__ */ new Set();
@@ -1481,13 +1867,23 @@ var ActionRegister = class {
 			errors: result.error.issues.map((issue) => issue.message)
 		};
 	}
-	createAbortedExecutionResult(startTime, handlersSkipped = 0, validation) {
+	createAbortedExecutionResult(startTime, skippedRegistrations = [], validation) {
 		const endTime = Date.now();
+		const handlers = skippedRegistrations.map((registration) => ({
+			id: registration.id,
+			status: "skipped",
+			executed: false,
+			duration: 0,
+			result: void 0,
+			error: void 0,
+			metadata: registration.config.metadata ? { ...registration.config.metadata } : void 0
+		}));
 		return {
 			success: false,
 			aborted: true,
 			abortReason: "Action dispatch aborted by signal",
 			terminated: false,
+			outcome: "cancelled",
 			validation,
 			result: void 0,
 			successResults: [],
@@ -1495,198 +1891,524 @@ var ActionRegister = class {
 			failedResults: [],
 			execution: {
 				duration: endTime - startTime,
+				admissionDuration: endTime - startTime,
+				queueWaitDuration: 0,
+				pipelineDuration: 0,
 				handlersExecuted: 0,
-				handlersSkipped,
+				handlersSkipped: handlers.length,
 				handlersFailed: 0,
 				startTime,
 				endTime
 			},
-			handlers: [],
+			handlers,
 			errors: []
 		};
 	}
+	resolveDispatchPlan(action, options) {
+		const pipelineSnapshot = [...this.pipelines.get(action) ?? []];
+		const guards = pipelineSnapshot.filter((handler) => handler.role === "guard");
+		const filterableHandlers = pipelineSnapshot.filter((handler) => handler.role !== "guard");
+		const filteredHandlers = options?.filter ? this.filterHandlers(filterableHandlers, options.filter) : filterableHandlers;
+		const eligibleHandlers = [...guards, ...filteredHandlers];
+		const admissionHandlers = eligibleHandlers.filter((handler) => handler.role !== "observer");
+		const debounceMs = options?.debounce ?? admissionHandlers.find((handler) => handler.config.debounce !== void 0)?.config.debounce;
+		const throttleMs = options?.throttle ?? admissionHandlers.find((handler) => handler.config.throttle !== void 0)?.config.throttle;
+		return {
+			pipelineSnapshot,
+			eligibleHandlers,
+			guards,
+			results: filteredHandlers.filter((handler) => handler.role !== "observer"),
+			observers: filteredHandlers.filter((handler) => handler.role === "observer"),
+			debounceMs,
+			throttleMs,
+			executionMode: options?.executionMode ?? this.actionExecutionModes.get(action) ?? this.executionMode
+		};
+	}
+	async evaluateTimingGuards(actionKey, plan, signal) {
+		const { debounceMs, throttleMs } = plan;
+		if (signal?.aborted) return { aborted: true };
+		if (debounceMs !== void 0 && !await this.actionGuard.debounce(actionKey, debounceMs, signal)) return signal?.aborted ? { aborted: true } : {
+			aborted: false,
+			reason: "Debounced execution"
+		};
+		if (throttleMs !== void 0 && !this.actionGuard.throttle(actionKey, throttleMs, signal)) return signal?.aborted ? { aborted: true } : {
+			aborted: false,
+			reason: "Throttled execution"
+		};
+		return { aborted: false };
+	}
 	/**
-	* 🆕 실제 디스패치 작업 수행 (큐에서 호출됨)
+	* Keep the dispatch plan stable across retries while honoring handlers that
+	* were consumed by the `once` lifecycle after an earlier attempt.
 	*/
-	async _performDispatch(action, payload, options, skipGuards, executedHandlers, dispatchHandlerPromises) {
-		this.log(`Starting dispatch for action '${String(action)}'`, {
-			hasPayload: payload !== void 0,
-			payloadType: payload?.constructor?.name || typeof payload,
-			options: options ? Object.keys(options) : "none",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		if (payload instanceof Event && true) console.warn(`Event object passed to action "${String(action)}"`, payload.type);
-		const [effectiveSignal, autoAbortController, cleanup] = this.createAbortSignal(options);
-		if (options?.autoAbort?.onControllerCreated && autoAbortController) options.autoAbort.onControllerCreated(autoAbortController);
-		if (effectiveSignal?.aborted) {
-			this.log(`Dispatch aborted before execution for '${String(action)}'`);
-			cleanup();
-			return;
-		}
-		const pipeline = this.pipelines.get(action);
-		this.log(`Pipeline lookup for '${String(action)}'`, {
-			pipelineExists: Boolean(pipeline),
-			handlersCount: pipeline?.length || 0,
-			allRegisteredActions: Array.from(this.pipelines.keys()),
-			pipelineMap: Object.fromEntries(Array.from(this.pipelines.entries()).map(([k, v]) => [k, v.length]))
+	getAttemptHandlers(action, plan) {
+		const activePipeline = this.pipelines.get(action) ?? [];
+		return plan.results.filter((handler) => !handler.config.once || activePipeline.includes(handler));
+	}
+	getObservers(action, plan) {
+		const activePipeline = this.pipelines.get(action) ?? [];
+		return plan.observers.flatMap((registration) => {
+			const observer = this.observerHandlers.get(registration);
+			return registration.role === "observer" && activePipeline.includes(registration) && observer ? [[registration, observer]] : [];
 		});
-		if (!pipeline || pipeline.length === 0) {
-			const warningMessage = `⚠️ Action '${String(action)}' has no registered handlers. This action will be ignored.`;
-			console.warn(warningMessage);
-			console.warn("💡 Tip: Register a handler using registry.register() before dispatching this action.");
-			console.warn("📋 Available actions:", Array.from(this.pipelines.keys()));
-			this.log(`No handlers found for action '${String(action)}', dispatch cancelled`, {}, "warn");
-			cleanup();
-			return;
-		}
-		const filteredHandlers = options?.filter ? this.filterHandlers(pipeline, options.filter) : pipeline;
-		const actionKey = String(action);
-		let throttleMs;
-		let debounceMs;
-		if (options?.throttle !== void 0) throttleMs = options.throttle;
-		else if (filteredHandlers.length > 0) {
-			for (const handler of filteredHandlers) if (handler.config.throttle !== void 0) {
-				throttleMs = handler.config.throttle;
-				break;
-			}
-		}
-		if (options?.debounce !== void 0) debounceMs = options.debounce;
-		else if (filteredHandlers.length > 0) {
-			for (const handler of filteredHandlers) if (handler.config.debounce !== void 0) {
-				debounceMs = handler.config.debounce;
-				break;
-			}
-		}
-		if (!skipGuards && debounceMs !== void 0) {
-			if (!await this.actionGuard.debounce(actionKey, debounceMs)) {
-				cleanup();
-				return;
+	}
+	/** Observers run after the canonical result has been constructed. Their
+	* failures are isolated from that immutable result; detached observers are
+	* still tracked for registry shutdown. */
+	async executeObservers(action, plan, event) {
+		const observerEvent = this.safeSnapshotObserverEvent(event);
+		for (const [registration, observerEntry] of this.getObservers(action, plan)) {
+			const successful = observerEvent.outcome === "completed" || observerEvent.outcome === "completed_with_errors";
+			if (observerEntry.when === "success" && !successful) continue;
+			if (observerEntry.when === "failure" && successful) continue;
+			let shouldRun = true;
+			try {
+				shouldRun = registration.config.condition?.(observerEvent.payload) ?? true;
+			} catch (error) {
+				this.log(`Observer condition failed for ${String(action)}`, error, "warn");
+				continue;
 			}
-		}
-		if (!skipGuards && throttleMs !== void 0) {
-			if (!this.actionGuard.throttle(actionKey, throttleMs)) {
-				cleanup();
-				return;
+			if (!shouldRun) continue;
+			const detachedOnce = registration.config.once && this.removeRegistration(action, registration, false);
+			const cleanupOnce = () => {
+				if (detachedOnce) this.runRegistrationCleanup(action, registration);
+			};
+			const invocation = Promise.resolve().then(() => observerEntry.handler(observerEvent));
+			if (registration.config.scheduling === "start-and-continue") this.trackGlobalHandlerPromise(invocation).then(cleanupOnce, (error) => {
+				this.log(`Observer failed for ${String(action)}`, error, "warn");
+				cleanupOnce();
+			});
+			else try {
+				await invocation;
+			} catch (error) {
+				this.log(`Observer failed for ${String(action)}`, error, "warn");
+			} finally {
+				cleanupOnce();
 			}
 		}
-		if (effectiveSignal?.aborted) {
-			this.log(`Dispatch aborted during guard processing for '${String(action)}'`);
-			cleanup();
-			return;
+	}
+	/** Give JavaScript observers an isolated, shallowly immutable terminal view.
+	* Result payloads are intentionally not deep-cloned: arbitrary result values
+	* may be class instances, streams, or identity-bearing domain objects. */
+	snapshotObserverEvent(event) {
+		const freezeValue = (value) => {
+			if (Array.isArray(value)) return Object.freeze([...value]);
+			if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) return Object.freeze({ ...value });
+			return value;
+		};
+		return Object.freeze({
+			...event,
+			payload: freezeValue(event.payload),
+			result: freezeValue(event.result),
+			errors: Object.freeze(event.errors.map((error) => Object.freeze({ ...error })))
+		});
+	}
+	/** A diagnostic observer must never make an already constructed canonical
+	* result reject, including when shallow-copying a Proxy/getter throws. */
+	safeSnapshotObserverEvent(event) {
+		try {
+			return this.snapshotObserverEvent(event);
+		} catch (error) {
+			this.log("Observer snapshot failed", error, "warn");
+			return Object.freeze({
+				action: event.action,
+				payload: event.payload,
+				outcome: event.outcome,
+				result: void 0,
+				errors: Object.freeze([]),
+				...event.signal === void 0 ? {} : { signal: event.signal }
+			});
 		}
-		const currentExecutionMode = options?.executionMode || this.actionExecutionModes.get(action) || this.executionMode;
+	}
+	/** Execute the selected guard snapshot once for the whole dispatch. Guards
+	* are deliberately outside the retry loop: authorization and normalization
+	* belong to admission, not to each provider attempt. */
+	async executeGuardPhase(action, payload, options, plan, dispatchHandlerPromises) {
+		if (plan.guards.length === 0) return {
+			allowed: true,
+			payload,
+			aborted: false,
+			abortReason: void 0,
+			error: void 0,
+			errors: [],
+			outcomes: [],
+			executedHandlers: [],
+			duration: 0
+		};
+		const [signal, autoAbortController, cleanup] = this.createAbortSignal(options);
 		const context = {
 			action: String(action),
 			payload,
-			handlers: [...filteredHandlers],
+			handlers: [...plan.guards],
 			executedHandlers: [],
-			deferOnceCleanup: true,
-			signal: effectiveSignal ?? this.lifecycleController.signal,
+			handlerOutcomes: [],
+			claimOnce: (registration) => this.claimOnceRegistration(action, registration),
+			signal: signal ?? this.lifecycleController.signal,
 			trackHandlerPromise: (promise) => this.trackHandlerPromise(promise, dispatchHandlerPromises),
 			aborted: false,
 			abortReason: void 0,
 			currentIndex: 0,
 			jumpToPriority: void 0,
 			jumpCount: 0,
-			maxJumps: 10,
-			executionMode: currentExecutionMode,
+			maxJumps: this.maxJumps,
+			executionMode: "sequential",
 			results: [],
 			terminated: false,
 			terminationResult: void 0
 		};
-		const abortHandler = effectiveSignal ? () => {
+		const abortHandler = signal ? () => {
 			context.aborted = true;
-			context.abortReason = typeof effectiveSignal.reason === "string" ? effectiveSignal.reason : "Action dispatch aborted by signal";
+			context.abortReason = typeof signal.reason === "string" ? signal.reason : "Action dispatch aborted by signal";
 		} : void 0;
-		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler, { once: true });
+		signal?.addEventListener("abort", abortHandler, { once: true });
+		let error;
 		try {
-			await this.executePipeline(context, dispatchHandlerPromises, autoAbortController, options?.autoAbort);
-			this.log(`Pipeline execution succeeded for ${String(action)}`);
-		} catch (error) {
-			this.log(`Pipeline execution failed for ${String(action)}`, error, "error");
-			throw error;
+			await executeSequential(context, (registration, _index) => {
+				const controller = this.createController(context, autoAbortController, options?.autoAbort, void 0, false);
+				return {
+					signal: controller.signal,
+					getPayload: controller.getPayload,
+					modifyPayload: controller.modifyPayload,
+					abort: controller.abort
+				};
+			});
+		} catch (caught) {
+			error = caught instanceof Error ? caught : new Error(String(caught));
 		} finally {
-			executedHandlers?.push(...context.executedHandlers ?? []);
-			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
-			this.cleanupSignalsAfterStartedHandlers(cleanup, dispatchHandlerPromises);
+			if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
+			this.cleanupSignalsAfterStartedHandlers(() => {
+				cleanup();
+				options?.[ATTEMPT_SIGNAL_CLEANUP]?.();
+			}, dispatchHandlerPromises);
 		}
+		const errors = [...context.collectedErrors ?? []];
+		if (error && !errors.some((entry) => entry.error === error)) errors.push({
+			handlerId: "guard",
+			error,
+			timestamp: Date.now(),
+			severity: "blocking"
+		});
+		return {
+			allowed: !context.aborted && error === void 0 && errors.length === 0,
+			payload: context.payload,
+			aborted: context.aborted,
+			abortReason: context.abortReason,
+			error,
+			errors,
+			outcomes: (context.handlerOutcomes ?? []).map(snapshotHandlerOutcome),
+			executedHandlers: context.executedHandlers ?? [],
+			duration: (context.handlerOutcomes ?? []).reduce((total, outcome) => total + (outcome.duration ?? 0), 0)
+		};
 	}
-	/**
-	* Dispatch an action and return detailed execution results
-	* 
-	* @param action - The action type to dispatch
-	* @param payload - The action payload data
-	* @param options - Optional dispatch options including result collection strategy
-	* 
-	* @returns Promise resolving to comprehensive execution results
-	* 
-	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
-	* 
-	* @public
-	*/
-	dispatchWithResult(action, payload, options) {
+	createGuardRejectedResult(startTime, validation, guard, selectedHandlers) {
+		const endTime = Date.now();
+		const outcomeById = new Map(guard.outcomes.map((outcome) => [outcome.id, outcome]));
+		const handlers = selectedHandlers.map((registration) => {
+			const outcome = outcomeById.get(registration.id);
+			return outcome ? {
+				...snapshotHandlerOutcome(outcome),
+				result: void 0
+			} : {
+				id: registration.id,
+				status: "skipped",
+				executed: false,
+				duration: 0,
+				result: void 0,
+				error: void 0,
+				metadata: registration.config.metadata ? { ...registration.config.metadata } : void 0
+			};
+		});
+		return {
+			success: false,
+			aborted: guard.aborted,
+			abortReason: guard.abortReason ?? guard.error?.message,
+			terminated: false,
+			outcome: guard.aborted ? "cancelled" : "failed",
+			validation,
+			result: void 0,
+			successResults: [],
+			results: [],
+			failedResults: guard.errors.map((error) => ({
+				handlerId: error.handlerId,
+				error: error.error,
+				expectedType: "unknown"
+			})),
+			execution: {
+				duration: endTime - startTime,
+				admissionDuration: 0,
+				queueWaitDuration: 0,
+				pipelineDuration: endTime - startTime,
+				handlersExecuted: handlers.filter((handler) => handler.executed).length,
+				handlersSkipped: handlers.filter((handler) => !handler.executed).length,
+				handlersFailed: handlers.filter((handler) => handler.status === "failed").length,
+				startTime,
+				endTime
+			},
+			handlers,
+			errors: guard.errors
+		};
+	}
+	createTimingGuardResult(reason, startTime, handlers, validation) {
+		const endTime = Date.now();
+		return {
+			success: false,
+			aborted: false,
+			abortReason: reason,
+			terminated: false,
+			outcome: reason === "Debounced execution" ? "debounced" : "throttled",
+			validation,
+			result: void 0,
+			successResults: [],
+			results: [],
+			failedResults: [],
+			execution: {
+				duration: endTime - startTime,
+				admissionDuration: endTime - startTime,
+				queueWaitDuration: 0,
+				pipelineDuration: 0,
+				handlersExecuted: 0,
+				handlersSkipped: handlers.length,
+				handlersFailed: 0,
+				startTime,
+				endTime
+			},
+			handlers: handlers.map((handler) => ({
+				id: handler.id,
+				status: "skipped",
+				executed: false,
+				duration: 0,
+				result: void 0,
+				error: void 0,
+				metadata: handler.config.metadata ? { ...handler.config.metadata } : void 0
+			})),
+			errors: []
+		};
+	}
+	dispatchWithResult(action, ...args) {
+		this.assertStringActionKey(action);
+		const [payload, options] = args;
 		if (this.lifecycleState !== "active") return this.rejectedLifecyclePromise();
 		const timeoutScope = this.createTimeoutScope(action, options);
+		const dispatchStartTime = Date.now();
 		const dispatchHandlerPromises = /* @__PURE__ */ new Set();
 		const attemptState = { count: 0 };
 		let validation;
-		const operation = async () => {
-			if (!timeoutScope.options?.signal?.aborted) validation = this.validatePayload(action, payload);
-			return this.executeWithRetry(async () => {
+		let observerPayload = payload;
+		let admissionEndedAt = dispatchStartTime;
+		let pipelineStartedAt;
+		const retryTelemetry = {
+			pipelineDuration: 0,
+			retryDelayDuration: 0,
+			attempts: []
+		};
+		const plan = this.resolveDispatchPlan(action, options);
+		const hasTimingGuard = plan.debounceMs !== void 0 || plan.throttleMs !== void 0;
+		const pipelineOperation = async () => {
+			pipelineStartedAt = Date.now();
+			const guard = plan.guards.length > 0 ? await this.executeGuardPhase(action, payload, timeoutScope.options, plan, dispatchHandlerPromises) : {
+				allowed: true,
+				payload,
+				aborted: false,
+				abortReason: void 0,
+				error: void 0,
+				errors: [],
+				outcomes: [],
+				executedHandlers: [],
+				duration: 0
+			};
+			this.cleanupOneTimeHandlers(action, guard.executedHandlers, dispatchHandlerPromises);
+			observerPayload = guard.payload;
+			if (!guard.allowed) return this.createGuardRejectedResult(pipelineStartedAt, validation, guard, [...plan.guards, ...plan.results]);
+			const rawExecution = await this.executeWithRetry(async (attemptSignal) => {
 				const executedHandlers = [];
 				try {
-					return await this._performDispatchWithResult(action, payload, timeoutScope.options, validation, attemptState.count > 1, executedHandlers, dispatchHandlerPromises);
+					return await this._performDispatchWithResult(action, guard.payload, this.withAttemptSignal(timeoutScope.options, attemptSignal), validation, plan, executedHandlers, dispatchHandlerPromises);
 				} finally {
 					this.cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises);
 				}
-			}, timeoutScope.options, attemptState, (result) => !result.success && !result.aborted && this.getHandlerCount(action) > 0, () => this.getHandlerCount(action) > 0);
+			}, timeoutScope.options, attemptState, (result) => result.outcome === "failed", () => this.getAttemptHandlers(action, plan).length > 0, retryTelemetry, this.shouldDrainBeforeRetry(plan, timeoutScope.options) ? () => this.drainAttemptHandlers(dispatchHandlerPromises) : void 0);
+			if (timeoutScope.options?.signal?.aborted) return {
+				...rawExecution,
+				success: false,
+				aborted: true,
+				abortReason: typeof timeoutScope.options.signal.reason === "string" ? timeoutScope.options.signal.reason : "Action dispatch aborted by signal",
+				outcome: "cancelled"
+			};
+			const executionWithGuards = {
+				...rawExecution,
+				handlers: [...guard.outcomes.map((outcome) => ({
+					...outcome,
+					result: void 0
+				})), ...rawExecution.handlers],
+				execution: {
+					...rawExecution.execution,
+					handlersExecuted: guard.outcomes.filter((outcome) => outcome.executed).length + rawExecution.execution.handlersExecuted,
+					handlersSkipped: guard.outcomes.filter((outcome) => !outcome.executed).length + rawExecution.execution.handlersSkipped,
+					handlersFailed: guard.outcomes.filter((outcome) => outcome.status === "failed").length + rawExecution.execution.handlersFailed
+				}
+			};
+			const resultProcessingStartedAt = Date.now();
+			const result = this.processResults(executionWithGuards.results, executionWithGuards.terminated, executionWithGuards.terminated ? executionWithGuards.result : void 0, options?.result);
+			const resultProcessingDuration = Date.now() - resultProcessingStartedAt;
+			return {
+				...executionWithGuards,
+				result,
+				execution: {
+					...executionWithGuards.execution,
+					pipelineDuration: guard.duration + retryTelemetry.pipelineDuration,
+					retryDelayDuration: retryTelemetry.retryDelayDuration,
+					resultProcessingDuration,
+					attempts: retryTelemetry.attempts
+				}
+			};
+		};
+		const operation = async () => {
+			if (timeoutScope.options?.signal?.aborted) {
+				admissionEndedAt = Date.now();
+				return this.createAbortedExecutionResult(dispatchStartTime, [...plan.guards, ...plan.results]);
+			}
+			validation = this.validatePayload(action, payload);
+			if (timeoutScope.options?.signal?.aborted) {
+				admissionEndedAt = Date.now();
+				return this.createAbortedExecutionResult(dispatchStartTime, [...plan.guards, ...plan.results], validation);
+			}
+			this.validateResultOptions(options?.result);
+			if (hasTimingGuard) {
+				const admission = await this.evaluateTimingGuards(String(action), plan, timeoutScope.options?.signal);
+				if (admission.aborted || timeoutScope.options?.signal?.aborted) {
+					admissionEndedAt = Date.now();
+					return this.createAbortedExecutionResult(dispatchStartTime, [...plan.guards, ...plan.results], validation);
+				}
+				if (admission.reason) {
+					admissionEndedAt = Date.now();
+					return this.createTimingGuardResult(admission.reason, dispatchStartTime, [...plan.guards, ...plan.results], validation);
+				}
+			}
+			if (timeoutScope.options?.signal?.aborted) {
+				admissionEndedAt = Date.now();
+				return this.createAbortedExecutionResult(dispatchStartTime, [...plan.guards, ...plan.results], validation);
+			}
+			admissionEndedAt = Date.now();
+			if (timeoutScope.options?.immediate || !this.dispatchQueue) return pipelineOperation();
+			const queued = this.dispatchQueue.enqueueWithHandle(pipelineOperation, timeoutScope.options?.queuePriority ?? 0);
+			timeoutScope.onTimeout((error) => queued.cancel(error));
+			return queued.promise;
+		};
+		let observerNotified = false;
+		let terminalErrorReported = false;
+		const reportTerminalError = (error) => {
+			if (terminalErrorReported) return;
+			terminalErrorReported = true;
+			this.invokeErrorHandler(error, action, payload, options, attemptState.count);
+		};
+		const notifyObservers = async (event) => {
+			if (observerNotified) return;
+			observerNotified = true;
+			await this.executeObservers(action, plan, event);
 		};
-		const shouldQueue = !timeoutScope.options?.immediate && Boolean(this.dispatchQueue) && timeoutScope.options?.queuePriority !== void 0;
 		let dispatchPromise;
+		let observedDispatchPromise;
 		this.dispatchConstructionDepth += 1;
 		try {
-			if (shouldQueue) {
-				const queued = this.dispatchQueue.enqueueWithHandle(operation, timeoutScope.options.queuePriority);
-				timeoutScope.onTimeout((error) => queued.cancel(error));
-				dispatchPromise = queued.promise;
-			} else dispatchPromise = operation();
-			this.trackDispatchPromise(dispatchPromise);
+			dispatchPromise = operation();
+			observedDispatchPromise = dispatchPromise.then(async (result) => {
+				const dispatchEndedAt = Date.now();
+				const pipelineDuration = pipelineStartedAt === void 0 ? 0 : result.execution.pipelineDuration;
+				const completedResult = {
+					...result,
+					execution: {
+						...result.execution,
+						duration: dispatchEndedAt - dispatchStartTime,
+						admissionDuration: Math.max(0, admissionEndedAt - dispatchStartTime),
+						queueWaitDuration: pipelineStartedAt === void 0 ? 0 : Math.max(0, pipelineStartedAt - admissionEndedAt),
+						pipelineDuration,
+						startTime: dispatchStartTime,
+						endTime: dispatchEndedAt
+					}
+				};
+				if (completedResult.outcome === "failed") {
+					const terminalError = completedResult.errors[completedResult.errors.length - 1]?.error ?? /* @__PURE__ */ new Error(`Action "${String(action)}" failed`);
+					reportTerminalError(terminalError);
+				}
+				await notifyObservers({
+					action: String(action),
+					payload: observerPayload,
+					outcome: completedResult.outcome,
+					result: completedResult.result,
+					errors: completedResult.errors,
+					signal: timeoutScope.options?.signal
+				});
+				return completedResult;
+			}, async (error) => {
+				reportTerminalError(error);
+				await notifyObservers({
+					action: String(action),
+					payload: observerPayload,
+					outcome: "failed",
+					result: void 0,
+					errors: [{
+						handlerId: "dispatch",
+						error: error instanceof Error ? error : new Error(String(error)),
+						timestamp: Date.now(),
+						severity: "blocking"
+					}],
+					signal: timeoutScope.options?.signal
+				});
+				throw error;
+			});
+			this.trackDispatchPromise(observedDispatchPromise);
 		} finally {
 			this.dispatchConstructionDepth -= 1;
 		}
-		const observedPromise = this.raceWithTimeout(dispatchPromise, timeoutScope, dispatchHandlerPromises).then((result) => {
-			if (!result.success && !result.aborted) {
-				const terminalError = result.errors[result.errors.length - 1]?.error ?? /* @__PURE__ */ new Error(`Action "${String(action)}" failed`);
-				this.invokeErrorHandler(terminalError, action, payload, options, attemptState.count);
-			}
-			return result;
-		}, (error) => {
-			this.invokeErrorHandler(error, action, payload, options, attemptState.count);
+		const observedPromise = this.raceWithTimeout(observedDispatchPromise, timeoutScope, dispatchHandlerPromises).catch(async (error) => {
+			reportTerminalError(error);
+			if (!observerNotified) await this.trackGlobalHandlerPromise(notifyObservers({
+				action: String(action),
+				payload: observerPayload,
+				outcome: "failed",
+				result: void 0,
+				errors: [{
+					handlerId: "dispatch",
+					error: error instanceof Error ? error : new Error(String(error)),
+					timestamp: Date.now(),
+					severity: "blocking"
+				}],
+				signal: timeoutScope.options?.signal
+			}));
 			throw error;
 		});
 		observedPromise.catch(() => {});
 		return observedPromise;
 	}
-	async _performDispatchWithResult(action, payload, options, validation, skipGuards, executedHandlers, dispatchHandlerPromises) {
+	async _performDispatchWithResult(action, payload, options, validation, plan, executedHandlers, dispatchHandlerPromises) {
 		const _startTime = Date.now();
 		const [effectiveSignal, autoAbortController, cleanup] = this.createAbortSignal(options);
 		if (options?.autoAbort?.onControllerCreated && autoAbortController) options.autoAbort.onControllerCreated(autoAbortController);
 		if (effectiveSignal?.aborted) {
 			cleanup();
-			return this.createAbortedExecutionResult(_startTime, 0, validation);
+			return this.createAbortedExecutionResult(_startTime, plan.results, validation);
 		}
-		const pipeline = this.pipelines.get(action);
+		const pipeline = plan.pipelineSnapshot;
 		if (!pipeline || pipeline.length === 0) {
+			this.log(`Pipeline lookup for '${String(action)}'`, {
+				pipelineExists: false,
+				handlersCount: 0,
+				allRegisteredActions: Array.from(this.pipelines.keys())
+			});
 			const warningMessage = `⚠️ Action '${String(action)}' has no registered handlers. This action will be ignored.`;
-			console.warn(warningMessage);
-			console.warn("💡 Tip: Register a handler using registry.register() before dispatching this action.");
-			console.warn("📋 Available actions:", Array.from(this.pipelines.keys()));
+			if (this.isDebugMode) {
+				console.warn(warningMessage);
+				console.warn("💡 Tip: Register a handler using registry.register() before dispatching this action.");
+				console.warn("📋 Available actions:", Array.from(this.pipelines.keys()));
+			}
+			this.log(`No handlers found for action '${String(action)}', dispatch cancelled`, {}, "warn");
 			cleanup();
 			return {
 				success: true,
 				aborted: false,
 				abortReason: void 0,
 				terminated: false,
+				outcome: "completed",
 				validation,
 				result: void 0,
 				successResults: [],
@@ -1694,6 +2416,9 @@ var ActionRegister = class {
 				failedResults: [],
 				execution: {
 					duration: 0,
+					admissionDuration: 0,
+					queueWaitDuration: 0,
+					pipelineDuration: 0,
 					handlersExecuted: 0,
 					handlersSkipped: 0,
 					handlersFailed: 0,
@@ -1704,27 +2429,15 @@ var ActionRegister = class {
 				errors: []
 			};
 		}
-		const filteredHandlers = options?.filter ? this.filterHandlers(pipeline, options.filter) : pipeline;
-		const actionKey = String(action);
-		const guardResult = skipGuards ? null : await this.applyActionGuardControlsWithResult(actionKey, filteredHandlers, options, _startTime, pipeline.length);
-		if (effectiveSignal?.aborted) {
-			cleanup();
-			return this.createAbortedExecutionResult(_startTime, pipeline.length, validation);
-		}
-		if (guardResult) {
-			cleanup();
-			return {
-				...guardResult,
-				validation
-			};
-		}
-		const currentExecutionMode = options?.executionMode || this.actionExecutionModes.get(action) || this.executionMode;
+		const filteredHandlers = this.getAttemptHandlers(action, plan);
 		const context = {
 			action: String(action),
 			payload,
 			handlers: [...filteredHandlers],
 			executedHandlers: [],
+			handlerOutcomes: [],
 			deferOnceCleanup: true,
+			claimOnce: (registration) => this.claimOnceRegistration(action, registration),
 			signal: effectiveSignal ?? this.lifecycleController.signal,
 			trackHandlerPromise: (promise) => this.trackHandlerPromise(promise, dispatchHandlerPromises),
 			aborted: false,
@@ -1732,24 +2445,13 @@ var ActionRegister = class {
 			currentIndex: 0,
 			jumpToPriority: void 0,
 			jumpCount: 0,
-			maxJumps: 10,
-			executionMode: currentExecutionMode,
+			maxJumps: this.maxJumps,
+			executionMode: plan.executionMode,
 			results: [],
 			terminated: false,
 			terminationResult: void 0
 		};
 		let executionError;
-		const handlerResults = [];
-		filteredHandlers.forEach((handler) => {
-			handlerResults.push({
-				id: handler.config.id,
-				executed: false,
-				duration: void 0,
-				result: void 0,
-				error: void 0,
-				metadata: void 0
-			});
-		});
 		const abortHandler = effectiveSignal ? () => {
 			context.aborted = true;
 			context.abortReason = typeof effectiveSignal.reason === "string" ? effectiveSignal.reason : "Action dispatch aborted by signal";
@@ -1759,13 +2461,6 @@ var ActionRegister = class {
 		try {
 			await this.executePipeline(context, dispatchHandlerPromises, autoAbortController, options?.autoAbort);
 			errors = context.collectedErrors || [];
-			const executedCount = Math.min(context.currentIndex + (context.aborted ? 0 : 1), filteredHandlers.length);
-			for (let i = 0; i < executedCount; i++) {
-				const handler = filteredHandlers[i];
-				if (!handler) continue;
-				const handlerResult = handlerResults.find((hr) => hr.id === handler.config.id);
-				if (handlerResult) handlerResult.executed = true;
-			}
 		} catch (error) {
 			errors = context.collectedErrors || [];
 			executionError = error instanceof Error ? error : new Error(String(error));
@@ -1775,156 +2470,118 @@ var ActionRegister = class {
 				timestamp: Date.now(),
 				severity: "blocking"
 			});
-			const executedCount = Math.min(context.currentIndex + 1, filteredHandlers.length);
-			for (let i = 0; i < executedCount; i++) {
-				const handler = filteredHandlers[i];
-				if (!handler) continue;
-				const handlerResult = handlerResults.find((hr) => hr.id === handler.config.id);
-				if (handlerResult) handlerResult.executed = true;
-			}
 		} finally {
 			executedHandlers.push(...context.executedHandlers ?? []);
 			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
-			this.cleanupSignalsAfterStartedHandlers(cleanup, dispatchHandlerPromises);
+			this.cleanupSignalsAfterStartedHandlers(() => {
+				cleanup();
+				options?.[ATTEMPT_SIGNAL_CLEANUP]?.();
+			}, dispatchHandlerPromises);
 		}
 		const endTime = Date.now();
-		const processedResult = this.processResults(context, options?.result);
+		const recordedOutcomes = context.handlerOutcomes ?? [];
+		const outcomesById = new Map(recordedOutcomes.map((outcome) => [outcome.id, outcome]));
+		const handlerResults = filteredHandlers.map((handler) => {
+			const outcome = outcomesById.get(handler.id);
+			return outcome ? snapshotHandlerOutcome(outcome) : {
+				id: handler.id,
+				status: "skipped",
+				executed: false,
+				duration: 0,
+				result: void 0,
+				error: void 0,
+				metadata: handler.config.metadata ? { ...handler.config.metadata } : void 0
+			};
+		});
+		const handlerErrors = errors.filter((error) => error.handlerId !== "pipeline");
+		const reportedErrors = executionError ? errors.filter((error) => error.handlerId === "pipeline") : errors;
+		const executionHandlersCount = handlerResults.filter((handler) => handler.executed).length;
 		const successResults = context.results.filter((result) => result !== void 0);
-		const failedResults = errors.map((err) => ({
+		const failedResults = handlerErrors.map((err) => ({
 			handlerId: err.handlerId,
 			error: err.error,
-			expectedType: typeof processedResult
+			expectedType: "unknown"
 		}));
 		return {
 			success: !executionError && !context.aborted,
 			aborted: context.aborted,
 			abortReason: context.abortReason,
 			terminated: context.terminated,
+			outcome: context.aborted ? "cancelled" : executionError ? "failed" : handlerErrors.length > 0 ? "completed_with_errors" : "completed",
 			validation,
-			result: processedResult,
+			result: context.terminated ? context.terminationResult : void 0,
 			successResults,
 			results: context.results,
 			failedResults,
 			execution: {
 				duration: endTime - _startTime,
-				handlersExecuted: filteredHandlers.length === 0 ? 0 : context.currentIndex + (context.aborted ? 0 : 1),
-				handlersSkipped: Math.max(0, filteredHandlers.length - (context.currentIndex + 1)),
-				handlersFailed: errors.length,
+				admissionDuration: 0,
+				queueWaitDuration: 0,
+				pipelineDuration: endTime - _startTime,
+				handlersExecuted: executionHandlersCount,
+				handlersSkipped: Math.max(0, filteredHandlers.length - executionHandlersCount),
+				handlersFailed: context.executionMode === "race" ? context.raceWinnerId && outcomesById.get(context.raceWinnerId)?.status === "failed" ? 1 : 0 : handlerResults.filter((handler) => handler.status === "failed").length,
 				startTime: _startTime,
 				endTime
 			},
 			handlers: handlerResults,
-			errors: errors.map((err) => ({
+			...context.executionMode !== "race" ? {} : { raceDiagnostics: {
+				...context.raceWinnerId === void 0 ? {} : { winnerId: context.raceWinnerId },
+				...context.raceWinnerId === void 0 ? {} : { winner: snapshotHandlerOutcome(outcomesById.get(context.raceWinnerId)) },
+				loserSnapshots: (context.raceLoserOutcomes ?? []).map(snapshotHandlerOutcome),
+				pendingLosersAtReturn: (context.raceLoserOutcomes ?? []).filter((outcome) => outcome.status === "running").length,
+				observedLoserFailures: (context.raceLoserOutcomes ?? []).filter((outcome) => outcome.status === "failed").length
+			} },
+			errors: reportedErrors.map((err) => ({
 				handlerId: err.handlerId,
 				error: err.error,
 				timestamp: err.timestamp,
-				severity: "non-blocking"
+				severity: err.severity
 			}))
 		};
 	}
-	/**
-	* 🔧 Unified method for dispatchWithResult that returns ExecutionResult on guard rejection
-	*/
-	async applyActionGuardControlsWithResult(actionKey, filteredHandlers, options, startTime, pipelineLength) {
-		let throttleMs;
-		let debounceMs;
-		if (options?.throttle !== void 0) throttleMs = options.throttle;
-		else if (filteredHandlers.length > 0) {
-			for (const handler of filteredHandlers) if (handler.config.throttle !== void 0) {
-				throttleMs = handler.config.throttle;
-				break;
-			}
-		}
-		if (options?.debounce !== void 0) debounceMs = options.debounce;
-		else if (filteredHandlers.length > 0) {
-			for (const handler of filteredHandlers) if (handler.config.debounce !== void 0) {
-				debounceMs = handler.config.debounce;
-				break;
-			}
-		}
-		if (debounceMs !== void 0) {
-			if (!await this.actionGuard.debounce(actionKey, debounceMs)) return {
-				success: false,
-				aborted: true,
-				abortReason: "Debounced execution",
-				terminated: false,
-				result: void 0,
-				successResults: [],
-				results: [],
-				failedResults: [],
-				execution: {
-					duration: Date.now() - startTime,
-					handlersExecuted: 0,
-					handlersSkipped: pipelineLength,
-					handlersFailed: 0,
-					startTime,
-					endTime: Date.now()
-				},
-				handlers: [],
-				errors: []
-			};
-		}
-		if (throttleMs !== void 0) {
-			if (!this.actionGuard.throttle(actionKey, throttleMs)) return {
-				success: false,
-				aborted: true,
-				abortReason: "Throttled execution",
-				terminated: false,
-				result: void 0,
-				successResults: [],
-				results: [],
-				failedResults: [],
-				execution: {
-					duration: Date.now() - startTime,
-					handlersExecuted: 0,
-					handlersSkipped: pipelineLength,
-					handlersFailed: 0,
-					startTime,
-					endTime: Date.now()
-				},
-				handlers: [],
-				errors: []
-			};
-		}
-		return null;
-	}
-	/**
-	* 🔧 Create or reuse PipelineController from pool for better performance
-	*/
-	getControllerFromPool(context, autoAbortController, autoAbortOptions) {
-		let controller = this.controllerPool.pop();
-		if (!controller) controller = {};
+	/** Create a pipeline controller for one handler execution. */
+	createController(context, autoAbortController, autoAbortOptions, isolatedState, collectResults = true) {
+		const controller = {};
 		controller.signal = context.signal ?? this.lifecycleController.signal;
+		const state = isolatedState ?? context;
 		controller.abort = (reason) => {
-			context.aborted = true;
-			context.abortReason = reason;
-			if (autoAbortController && autoAbortOptions?.allowHandlerAbort) autoAbortController.abort(reason);
+			state.aborted = true;
+			state.abortReason = reason;
+			const propagateAbort = !isolatedState || context.executionMode !== "race";
+			if (propagateAbort) {
+				context.aborted = true;
+				context.abortReason = reason;
+			}
+			if (propagateAbort && autoAbortController && autoAbortOptions?.allowHandlerAbort) autoAbortController.abort(reason);
 		};
 		controller.modifyPayload = (modifier) => {
-			try {
-				context.payload = modifier(context.payload);
-			} catch (modificationError) {
-				this.log("Payload modification error", modificationError, "warn");
-			}
+			state.payload = modifier(state.payload);
 		};
-		controller.getPayload = () => context.payload;
+		controller.getPayload = () => state.payload;
 		controller.jumpToPriority = (priority) => {
-			context.jumpToPriority = priority;
+			state.jumpToPriority = priority;
 		};
 		controller.return = (result) => {
-			context.terminated = true;
-			context.terminationResult = result;
+			state.terminated = true;
+			state.terminationResult = collectResults ? result : void 0;
+			if (!isolatedState) {
+				context.terminated = true;
+				context.terminationResult = collectResults ? result : void 0;
+			}
+			return result;
 		};
 		controller.setResult = (result) => {
-			context.results.push(result);
+			if (collectResults) state.results.push(result);
 		};
 		controller.getResults = () => {
-			return [...context.results];
+			return [...state.results];
 		};
 		controller.mergeResult = (merger) => {
-			const currentResult = context.results[context.results.length - 1];
-			const mergedResult = merger(context.results.slice(0, -1), currentResult);
-			context.results[context.results.length - 1] = mergedResult;
+			if (!collectResults) return;
+			const currentResult = state.results[state.results.length - 1];
+			const mergedResult = merger(state.results.slice(0, -1), currentResult);
+			state.results[state.results.length - 1] = mergedResult;
 		};
 		return controller;
 	}
@@ -1941,17 +2598,32 @@ var ActionRegister = class {
 				if (filterOptions.priority.min !== void 0 && priority < filterOptions.priority.min) return false;
 				if (filterOptions.priority.max !== void 0 && priority > filterOptions.priority.max) return false;
 			}
-			if (filterOptions.custom && !filterOptions.custom(config)) return false;
+			if (filterOptions.custom) {
+				const configSnapshot = Object.freeze({
+					...config,
+					metadata: config.metadata ? Object.freeze({ ...config.metadata }) : void 0
+				});
+				if (!filterOptions.custom(configSnapshot)) return false;
+			}
 			return true;
 		});
 	}
-	processResults(context, resultOptions) {
-		const results = context.results;
-		if (context.terminated && context.terminationResult !== void 0) return context.terminationResult;
+	validateResultOptions(resultOptions) {
+		if (!resultOptions) return;
+		if (resultOptions.strategy === "custom" && typeof resultOptions.merger !== "function") throw new ActionResultProcessingError("Custom result strategy requires a merger function");
+		if (resultOptions.maxResults !== void 0 && (!Number.isSafeInteger(resultOptions.maxResults) || resultOptions.maxResults < 0)) throw new RangeError("maxResults must be a non-negative safe integer.");
+	}
+	processResults(results, terminated, terminationResult, resultOptions) {
+		if (terminated && terminationResult !== void 0) return terminationResult;
 		if (!resultOptions) return results.length > 0 ? results[results.length - 1] : void 0;
 		if (!resultOptions.collect && !resultOptions.strategy) return;
-		const limitedResults = resultOptions.maxResults ? results.slice(0, resultOptions.maxResults) : results;
-		if (limitedResults.length === 0) return;
+		const collectedResults = results.filter((result) => result !== void 0);
+		const limitedResults = resultOptions.maxResults !== void 0 ? collectedResults.slice(0, resultOptions.maxResults) : collectedResults;
+		if (limitedResults.length === 0) {
+			if (resultOptions.strategy === "all" || resultOptions.collect && !resultOptions.strategy) return [];
+			if (resultOptions.strategy === "custom" || resultOptions.strategy === "merge" && resultOptions.merger) return resultOptions.merger(limitedResults);
+			return;
+		}
 		switch (resultOptions.strategy) {
 			case "first": return limitedResults[0];
 			case "last": return limitedResults[limitedResults.length - 1];
@@ -1968,9 +2640,36 @@ var ActionRegister = class {
 		}
 	}
 	async executePipeline(context, dispatchHandlerPromises, autoAbortController, autoAbortOptions) {
-		const createController = (_registration, _index) => {
-			return this.getControllerFromPool(context, autoAbortController, autoAbortOptions);
+		const createController = (registration, _index, state) => {
+			const controller = this.createController(context, autoAbortController, autoAbortOptions, state, registration.role !== "guard");
+			if (registration.role === "guard") return {
+				signal: controller.signal,
+				getPayload: controller.getPayload,
+				modifyPayload: controller.modifyPayload,
+				abort: controller.abort
+			};
+			if (registration.role === "result") return {
+				signal: controller.signal,
+				getPayload: controller.getPayload,
+				abort: controller.abort,
+				return: controller.return,
+				setResult: controller.setResult,
+				getResults: controller.getResults,
+				mergeResult: controller.mergeResult
+			};
+			return controller;
 		};
+		const originalHandlers = context.handlers;
+		const preflightHandlers = originalHandlers.filter((handler) => handler.role === "guard");
+		if (preflightHandlers.length > 0) {
+			context.handlers = preflightHandlers;
+			await executeSequential(context, createController);
+			if (context.aborted || context.terminated) {
+				context.handlers = originalHandlers;
+				return;
+			}
+		}
+		context.handlers = originalHandlers.filter((handler) => !preflightHandlers.includes(handler) && handler.role !== "observer");
 		switch (context.executionMode) {
 			case "sequential":
 				await executeSequential(context, createController);
@@ -1983,6 +2682,7 @@ var ActionRegister = class {
 				break;
 			default: throw new Error(`Unknown execution mode: ${context.executionMode}`);
 		}
+		context.handlers = originalHandlers;
 		if (!context.deferOnceCleanup) this.cleanupOneTimeHandlers(context.action, context.executedHandlers ?? [], dispatchHandlerPromises);
 	}
 	cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises) {
@@ -1991,7 +2691,9 @@ var ActionRegister = class {
 		const handlersStillRunning = [...dispatchHandlerPromises];
 		const shouldDeferCleanup = handlersStillRunning.length > 0;
 		oneTimeHandlers.forEach((registration) => {
-			if (this.removeRegistration(action, registration, !shouldDeferCleanup)) {
+			const claimed = this.claimedOnceHandlers.delete(registration);
+			if (claimed || this.removeRegistration(action, registration, !shouldDeferCleanup)) {
+				if (claimed && !shouldDeferCleanup) this.runRegistrationCleanup(action, registration);
 				if (shouldDeferCleanup && typeof registration.config.cleanup === "function") {
 					const cleanupPromise = Promise.allSettled(handlersStillRunning).then(() => {
 						this.runRegistrationCleanup(action, registration);
@@ -2000,11 +2702,20 @@ var ActionRegister = class {
 				}
 				this.log(`One-time handler removed: ${String(action)}`, {
 					handlerId: registration.id,
-					remainingHandlers: this.getHandlerCount(action)
+					remainingHandlers: this.pipelines.get(action)?.length ?? 0
 				});
 			}
 		});
 	}
+	/** Reserve a once registration before user code starts. This is synchronous,
+	* so independent dispatches cannot both invoke the same registration. */
+	claimOnceRegistration(action, registration) {
+		if (!registration.config.once) return true;
+		if (this.claimedOnceHandlers.has(registration)) return false;
+		if (!this.removeRegistration(action, registration, false)) return false;
+		this.claimedOnceHandlers.add(registration);
+		return true;
+	}
 	/**
 	* Get the number of registered handlers for an action
 	* 
@@ -2077,8 +2788,10 @@ var ActionRegister = class {
 		});
 		this.pipelines.clear();
 		this.lastRegisteredTimestamps.clear();
+		this.unregisterFunctions.forEach((unregisters) => unregisters.clear());
 		this.unregisterFunctions.clear();
 		this.actionGuard.clearAll();
+		this.observerHandlers.clear();
 	}
 	/**
 	* Get the name of this action register
@@ -2150,7 +2863,7 @@ var ActionRegister = class {
 	*/
 	setExecutionMode(mode) {
 		this.executionMode = mode;
-		if (this.registryConfig?.debug && true) console.log(`🎯 Global execution mode set to: ${mode}`);
+		if (this.isDebugMode) console.log(`🎯 Global execution mode set to: ${mode}`);
 	}
 	/**
 	* Set execution mode for a specific action
@@ -2160,7 +2873,7 @@ var ActionRegister = class {
 	*/
 	setActionExecutionMode(action, mode) {
 		this.actionExecutionModes.set(action, mode);
-		if (this.registryConfig?.debug && true) console.log(`🎯 Execution mode set for action '${String(action)}': ${mode}`);
+		if (this.isDebugMode) console.log(`🎯 Execution mode set for action '${String(action)}': ${mode}`);
 	}
 	/**
 	* Get execution mode for a specific action
@@ -2178,7 +2891,7 @@ var ActionRegister = class {
 	*/
 	removeActionExecutionMode(action) {
 		this.actionExecutionModes.delete(action);
-		if (this.registryConfig?.debug && true) console.log(`🎯 Execution mode reset for action '${String(action)}' to default: ${this.executionMode}`);
+		if (this.isDebugMode) console.log(`🎯 Execution mode reset for action '${String(action)}' to default: ${this.executionMode}`);
 	}
 	/**
 	* Get registry configuration (for debugging and inspection)
@@ -2209,11 +2922,19 @@ var ActionRegister = class {
 		return () => {
 			if (this.removeRegistration(action, registration)) this.log(`Handler unregistered: ${String(action)}`, {
 				handlerId,
-				remainingHandlers: this.getHandlerCount(action),
+				remainingHandlers: this.pipelines.get(action)?.length ?? 0,
 				actionRemoved: !this.pipelines.has(action)
 			});
 		};
 	}
+	getUnregisterFunctions(action) {
+		let unregisters = this.unregisterFunctions.get(action);
+		if (!unregisters) {
+			unregisters = /* @__PURE__ */ new Map();
+			this.unregisterFunctions.set(action, unregisters);
+		}
+		return unregisters;
+	}
 	/** Remove a registration and release every resource owned by it exactly once. */
 	removeRegistration(action, registration, runCleanup = true) {
 		const pipeline = this.pipelines.get(action);
@@ -2221,11 +2942,13 @@ var ActionRegister = class {
 		const index = pipeline.indexOf(registration);
 		if (index === -1) return false;
 		pipeline.splice(index, 1);
-		this.unregisterFunctions.delete(registration.id);
+		this.observerHandlers.delete(registration);
+		this.unregisterFunctions.get(action)?.delete(registration.id);
 		if (runCleanup) this.runRegistrationCleanup(action, registration);
 		if (pipeline.length === 0) {
 			this.pipelines.delete(action);
 			this.lastRegisteredTimestamps.delete(action);
+			this.unregisterFunctions.delete(action);
 		}
 		return true;
 	}
@@ -2244,7 +2967,11 @@ var ActionRegister = class {
 	* @public
 	*/
 	getUnregisterFunctionCount() {
-		return this.unregisterFunctions.size;
+		let count = 0;
+		this.unregisterFunctions.forEach((unregisters) => {
+			count += unregisters.size;
+		});
+		return count;
 	}
 	/**
 	* Checks if an unregister function exists for the given handler ID
@@ -2254,7 +2981,8 @@ var ActionRegister = class {
 	* @public
 	*/
 	hasUnregisterFunction(handlerId) {
-		return this.unregisterFunctions.has(handlerId);
+		for (const unregisters of this.unregisterFunctions.values()) if (unregisters.has(handlerId)) return true;
+		return false;
 	}
 	/** Reject queued dispatches without releasing registered handlers. */
 	cancelPendingDispatches() {
@@ -2299,7 +3027,6 @@ var ActionRegister = class {
 		if (this.lifecycleState === "destroyed") return;
 		this.clearAll();
 		this.actionExecutionModes.clear();
-		this.controllerPool.length = 0;
 		this.lifecycleState = "destroyed";
 		this.log("ActionRegister destroyed");
 	}
@@ -2330,5 +3057,5 @@ var ActionRegister = class {
 };
 
 //#endregion
-export { ActionGuard, ActionRegister, ActionRegisterDestroyedError, ActionTimeoutError, ActionValidationError, executeParallel, executeRace, executeSequential, isActionRegisterDestroyedError, isActionTimeoutError, isActionValidationError };
+export { ActionAttemptSupersededError, ActionGuard, ActionRegister, ActionRegisterDestroyedError, ActionResultProcessingError, ActionTimeoutError, ActionValidationError, executeParallel, executeRace, executeSequential, isActionRegisterDestroyedError, isActionResultProcessingError, isActionTimeoutError, isActionValidationError, resolveHandlerConfig };
 //# sourceMappingURL=index.js.map