@context-action/core 0.8.4 → 0.8.8

package/dist/index.cjs

@@ -1,5 +1,9 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#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
 * 
@@ -59,12 +63,15 @@ async function executeSequential(context, createController) {
 				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 = result instanceof Promise ? await result : result;
+				const handlerResult = trackedResult ? await trackedResult : result;
 				if (handlerResult !== void 0 && !context.terminated) context.results.push(handlerResult);
-			} else if (result instanceof Promise) {
-				const promiseWithErrorHandling = result.then((asyncResult) => {
+			} else if (trackedResult) {
+				const promiseWithErrorHandling = trackedResult.then((asyncResult) => {
 					if (asyncResult !== void 0 && !context.terminated) context.results.push(asyncResult);
 					return asyncResult;
 				}).catch((error) => {
@@ -162,10 +169,9 @@ async function executeParallel(context, createController) {
 					skipped: true
 				};
 			}
+			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
 			const result = registration.handler(context.payload, controller);
-			let handlerResult;
-			if (result instanceof Promise) handlerResult = await result;
-			else handlerResult = result;
+			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 {
@@ -184,8 +190,9 @@ async function executeParallel(context, createController) {
 			};
 		}
 	});
+	const trackedHandlerPromises = context.trackHandlerPromise ? handlerPromises.map((promise) => context.trackHandlerPromise(promise)) : handlerPromises;
 	/** Wait for all handlers to complete */
-	const results = await Promise.allSettled(handlerPromises);
+	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;
@@ -204,8 +211,10 @@ async function executeParallel(context, createController) {
 * 
 * Executes all qualifying handlers simultaneously using Promise.race, where
 * the first handler to complete determines the pipeline result. Other handlers
-* are effectively cancelled. Useful for scenarios where you want the fastest
-* response from multiple equivalent 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
@@ -246,10 +255,9 @@ async function executeRace(context, createController) {
 					skipped: true
 				};
 			}
+			(context.executedHandlers ?? (context.executedHandlers = [])).push(registration);
 			const result = registration.handler(context.payload, controller);
-			let handlerResult;
-			if (result instanceof Promise) handlerResult = await result;
-			else handlerResult = result;
+			const handlerResult = isPromiseLike(result) ? await Promise.resolve(result) : result;
 			return {
 				success: true,
 				handlerId: registration.id,
@@ -267,8 +275,9 @@ async function executeRace(context, createController) {
 			};
 		}
 	});
-	/** Race all handlers */
-	const winner = await Promise.race(handlerPromises);
+	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 */
@@ -317,7 +326,11 @@ var ActionGuard = class {
 		this.cleanupIntervalMs = 3e4;
 		this.maxGuards = 1e3;
 		this.accessOrder = [];
-		if (autoCleanup) this.startAutoCleanup();
+		this.autoCleanupEnabled = autoCleanup;
+	}
+	/** Start cleanup only after the first guard is used. */
+	ensureAutoCleanup() {
+		if (this.autoCleanupEnabled && !this.cleanupInterval) this.startAutoCleanup();
 	}
 	/**
 	* Start automatic cleanup of idle guard states
@@ -325,9 +338,17 @@ var ActionGuard = class {
 	* @internal
 	*/
 	startAutoCleanup() {
+		if (this.cleanupInterval) return;
 		this.cleanupInterval = setInterval(() => {
 			this.performCleanup();
 		}, this.cleanupIntervalMs);
+		this.cleanupInterval.unref?.();
+	}
+	stopAutoCleanup() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = void 0;
+		}
 	}
 	/**
 	* 🔧 Optimized cleanup with early exit and batched operations
@@ -336,7 +357,10 @@ var ActionGuard = class {
 	*/
 	performCleanup() {
 		const guardCount = this.guards.size;
-		if (guardCount === 0) return;
+		if (guardCount === 0) {
+			this.stopAutoCleanup();
+			return;
+		}
 		const now = Date.now();
 		const keysToDelete = [];
 		if (guardCount <= 10) this.guards.forEach((state, key) => {
@@ -366,6 +390,7 @@ var ActionGuard = class {
 				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();
 		}
 	}
 	/**
@@ -424,6 +449,7 @@ var ActionGuard = class {
 	* @internal
 	*/
 	async debounce(actionKey, debounceMs) {
+		this.ensureAutoCleanup();
 		this.evictIfNeeded();
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
@@ -484,6 +510,7 @@ var ActionGuard = class {
 	* @internal
 	*/
 	throttle(actionKey, throttleMs) {
+		this.ensureAutoCleanup();
 		this.evictIfNeeded();
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
@@ -551,6 +578,9 @@ var ActionGuard = class {
 				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();
 		}
 	}
 	/**
@@ -575,6 +605,8 @@ var ActionGuard = class {
 		});
 		/** Remove all guard states from memory */
 		this.guards.clear();
+		this.accessOrder = [];
+		this.stopAutoCleanup();
 	}
 	/**
 	* Get current guard state for debugging purposes
@@ -612,12 +644,7 @@ var ActionGuard = class {
 	* @internal
 	*/
 	destroy() {
-		if (this.cleanupInterval) {
-			clearInterval(this.cleanupInterval);
-			this.cleanupInterval = void 0;
-		}
 		this.clearAll();
-		this.accessOrder = [];
 	}
 	/**
 	* 🆕 Get statistics about active guards
@@ -670,27 +697,42 @@ var OperationQueue = class {
 	* @returns Promise로 래핑된 작업 결과
 	*/
 	enqueue(operation, priority = 0) {
-		return new Promise((resolve, reject) => {
-			const queuedOperation = {
-				id: `${this.name}-${++this.operationCounter}`,
-				operation,
-				resolve,
-				reject,
-				priority,
-				timestamp: Date.now()
-			};
-			let insertIndex = this.queue.length;
-			for (let i = 0; i < this.queue.length; i++) {
-				const item = this.queue[i];
-				if (item && (item.priority || 0) < priority) {
-					insertIndex = i;
-					break;
+		return this.enqueueWithHandle(operation, priority).promise;
+	}
+	/** Enqueue an operation and retain a handle for pre-start cancellation. */
+	enqueueWithHandle(operation, priority = 0) {
+		let queuedOperation;
+		return {
+			promise: new Promise((resolve, reject) => {
+				queuedOperation = {
+					id: `${this.name}-${++this.operationCounter}`,
+					operation,
+					resolve,
+					reject,
+					priority,
+					timestamp: Date.now()
+				};
+				let insertIndex = this.queue.length;
+				for (let i = 0; i < this.queue.length; i++) {
+					const item = this.queue[i];
+					if (item && (item.priority || 0) < priority) {
+						insertIndex = i;
+						break;
+					}
 				}
+				this.queue.splice(insertIndex, 0, queuedOperation);
+				if (this.processingPromise) this.notifyNewOperation();
+				this.processQueue();
+			}),
+			cancel: (reason = /* @__PURE__ */ new Error("Queue operation cancelled")) => {
+				const index = this.queue.indexOf(queuedOperation);
+				if (index === -1) return false;
+				this.queue.splice(index, 1);
+				queuedOperation.reject(reason);
+				this.notifyNewOperation();
+				return true;
 			}
-			this.queue.splice(insertIndex, 0, queuedOperation);
-			if (this.processingPromise) this.notifyNewOperation();
-			this.processQueue();
-		});
+		};
 	}
 	/**
 	* 🆕 큐 처리 메인 로직 - 동시성 제어 및 비동기 지원
@@ -796,12 +838,14 @@ var OperationQueue = class {
 	/**
 	* 큐 비우기 (테스트용)
 	*/
-	clear() {
+	clear(options = {}) {
+		const rejectPending = options.rejectPending ?? true;
+		const reason = options.reason ?? /* @__PURE__ */ new Error("Queue cleared");
 		this.queue.forEach((operation) => {
-			operation.reject(/* @__PURE__ */ new Error("Queue cleared"));
+			if (rejectPending) operation.reject(reason);
+			else operation.resolve(void 0);
 		});
 		this.queue = [];
-		this.processingPromise = null;
 		this.pendingResolvers.splice(0).forEach((resolve) => resolve());
 	}
 	/**
@@ -818,8 +862,179 @@ var OperationQueue = class {
 	}
 };
 
+//#endregion
+//#region src/errors.ts
+/**
+* Action payload 검증 실패 에러
+*
+* dispatch 시 Zod 스키마 검증이 실패하면 발생합니다.
+* (validationMode가 'strict'일 때만 throw)
+*
+* @example
+* ```typescript
+* try {
+*   dispatch('updateUser', { id: '', name: 'John' });
+* } catch (error) {
+*   if (error instanceof ActionValidationError) {
+*     console.log('Action:', error.action);
+*     console.log('Issues:', error.issues);
+*     console.log('Formatted:', error.formattedErrors);
+*   }
+* }
+* ```
+*/
+var ActionValidationError = class ActionValidationError extends Error {
+	/**
+	* @param action - 검증 실패한 action 이름
+	* @param zodError - Zod 검증 에러 객체 (ZodError compatible)
+	*/
+	constructor(action, zodError) {
+		const message = `Action "${action}" payload validation failed: ${zodError && typeof zodError === "object" && "message" in zodError ? String(zodError.message) : "Validation failed"}`;
+		super(message);
+		this.name = "ActionValidationError";
+		this.action = action;
+		this.zodError = zodError;
+		Object.setPrototypeOf(this, ActionValidationError.prototype);
+	}
+	/**
+	* Zod 검증 이슈 목록
+	*/
+	get issues() {
+		if (this.zodError && typeof this.zodError === "object" && "issues" in this.zodError && Array.isArray(this.zodError.issues)) return this.zodError.issues;
+		return [];
+	}
+	/**
+	* 포맷된 에러 객체 (필드별 에러 메시지)
+	*/
+	get formattedErrors() {
+		if (this.zodError && typeof this.zodError === "object" && "format" in this.zodError && typeof this.zodError.format === "function") return this.zodError.format();
+		return {};
+	}
+	/**
+	* 플랫 에러 맵 (필드명 → 에러 메시지 배열)
+	*/
+	get flattenedErrors() {
+		if (this.zodError && typeof this.zodError === "object" && "flatten" in this.zodError && typeof this.zodError.flatten === "function") return this.zodError.flatten();
+		return {
+			fieldErrors: {},
+			formErrors: []
+		};
+	}
+	/**
+	* 첫 번째 에러 메시지
+	*/
+	get firstError() {
+		return this.issues[0]?.message;
+	}
+	/**
+	* 에러 발생 필드 경로 목록
+	*/
+	get errorPaths() {
+		return this.issues.map((issue) => issue.path.map((p) => String(p)).join("."));
+	}
+	/**
+	* JSON 직렬화
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			action: this.action,
+			message: this.message,
+			issues: this.issues
+		};
+	}
+};
+/**
+* Raised when a dispatch exceeds its configured wall-clock timeout.
+* The underlying handler receives an aborted controller signal and the internal
+* queue keeps draining it safely, while the caller is released immediately with
+* this error.
+*/
+var ActionTimeoutError = class ActionTimeoutError extends Error {
+	constructor(action, timeout) {
+		super(`Action "${action}" timed out after ${timeout}ms`);
+		this.action = action;
+		this.timeout = timeout;
+		this.name = "ActionTimeoutError";
+		Object.setPrototypeOf(this, ActionTimeoutError.prototype);
+	}
+};
+/** Raised when work is submitted after an ActionRegister begins shutdown. */
+var ActionRegisterDestroyedError = class ActionRegisterDestroyedError extends Error {
+	constructor(registerName, state) {
+		super(`ActionRegister "${registerName}" is ${state} and cannot accept new work`);
+		this.registerName = registerName;
+		this.state = state;
+		this.name = "ActionRegisterDestroyedError";
+		Object.setPrototypeOf(this, ActionRegisterDestroyedError.prototype);
+	}
+};
+/**
+* ActionValidationError 타입 가드
+*/
+function isActionValidationError(error) {
+	return error instanceof ActionValidationError;
+}
+/** ActionTimeoutError type guard. */
+function isActionTimeoutError(error) {
+	return error instanceof ActionTimeoutError;
+}
+/** ActionRegisterDestroyedError type guard. */
+function isActionRegisterDestroyedError(error) {
+	return error instanceof ActionRegisterDestroyedError;
+}
+
 //#endregion
 //#region src/ActionRegister.ts
+const dispatchOptionKeys = /* @__PURE__ */ new Set([
+	"autoAbort",
+	"debounce",
+	"executionMode",
+	"filter",
+	"immediate",
+	"queuePriority",
+	"result",
+	"retryOnError",
+	"signal",
+	"throttle",
+	"timeout"
+]);
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isOptionalNumber(value) {
+	return value === void 0 || typeof value === "number";
+}
+function isOptionalBoolean(value) {
+	return value === void 0 || typeof value === "boolean";
+}
+/**
+* Recognize the deprecated options-first void-action proxy call.
+*
+* Every supplied field is validated so ordinary payloads that merely overlap
+* one option name are not silently reinterpreted as dispatch options.
+*/
+function isDispatchOptions(value) {
+	if (!isRecord(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 0 || keys.some((key) => !dispatchOptionKeys.has(key))) return false;
+	return keys.every((key) => {
+		const optionValue = value[key];
+		switch (key) {
+			case "debounce":
+			case "queuePriority":
+			case "throttle":
+			case "timeout": return isOptionalNumber(optionValue);
+			case "immediate": return isOptionalBoolean(optionValue);
+			case "executionMode": return optionValue === void 0 || optionValue === "sequential" || optionValue === "parallel" || optionValue === "race";
+			case "signal": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.aborted === "boolean" && typeof optionValue.addEventListener === "function";
+			case "retryOnError": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.maxAttempts === "number" && typeof optionValue.delay === "number";
+			case "autoAbort": return optionValue === void 0 || isRecord(optionValue) && typeof optionValue.enabled === "boolean" && isOptionalBoolean(optionValue.allowHandlerAbort) && (optionValue.onControllerCreated === void 0 || typeof optionValue.onControllerCreated === "function");
+			case "filter": return optionValue === void 0 || isRecord(optionValue) && (optionValue.handlerIds === void 0 || Array.isArray(optionValue.handlerIds) && optionValue.handlerIds.every((item) => typeof item === "string")) && (optionValue.excludeHandlerIds === void 0 || Array.isArray(optionValue.excludeHandlerIds) && optionValue.excludeHandlerIds.every((item) => typeof item === "string")) && (optionValue.priority === void 0 || isRecord(optionValue.priority)) && (optionValue.custom === void 0 || typeof optionValue.custom === "function");
+			case "result": return optionValue === void 0 || isRecord(optionValue) && (optionValue.strategy === void 0 || optionValue.strategy === "first" || optionValue.strategy === "last" || optionValue.strategy === "all" || optionValue.strategy === "merge" || optionValue.strategy === "custom") && (optionValue.merger === void 0 || typeof optionValue.merger === "function") && isOptionalBoolean(optionValue.collect) && isOptionalNumber(optionValue.maxResults) && isOptionalBoolean(optionValue.includeErrors);
+		}
+	});
+}
 /**
 * Action Register for managing action handlers with priority-based execution
 * 
@@ -835,35 +1050,6 @@ var OperationQueue = class {
 * 
 * @public
 */
-/**
-* Type guard to determine if an object is DispatchOptions
-* Extracted as utility function for reuse and performance
-* 
-* @param obj - Object to check
-* @returns True if object is DispatchOptions
-* @internal
-*/
-function isDispatchOptions(obj) {
-	if (!obj || typeof obj !== "object") return false;
-	if ("debounce" in obj && typeof obj.debounce === "number") return true;
-	if ("throttle" in obj && typeof obj.throttle === "number") return true;
-	if ("executionMode" in obj) return true;
-	if ("signal" in obj && obj.signal instanceof AbortSignal) return true;
-	if ("immediate" in obj && typeof obj.immediate === "boolean") return true;
-	if ("queuePriority" in obj && typeof obj.queuePriority === "number") return true;
-	if ("timeout" in obj && typeof obj.timeout === "number") return true;
-	if ("retryOnError" in obj && typeof obj.retryOnError === "object") return true;
-	if ("autoAbort" in obj && typeof obj.autoAbort === "object") return true;
-	if ("filter" in obj && typeof obj.filter === "object" && obj.filter !== null) {
-		const filter = obj.filter;
-		if ("handlerIds" in filter || "excludeHandlerIds" in filter || "priority" in filter || "custom" in filter) return true;
-	}
-	if ("result" in obj && typeof obj.result === "object" && obj.result !== null) {
-		const result = obj.result;
-		if ("strategy" in result || "merger" in result || "collect" in result || "maxResults" in result || "includeErrors" in result) return true;
-	}
-	return false;
-}
 var ActionRegister = class {
 	constructor(config = {}) {
 		this.pipelines = /* @__PURE__ */ new Map();
@@ -875,6 +1061,11 @@ var ActionRegister = class {
 		this.handlerIdCounter = 0;
 		this.controllerPool = [];
 		this.maxControllerPoolSize = 10;
+		this.lifecycleState = "active";
+		this.lifecycleController = new AbortController();
+		this.activeDispatches = /* @__PURE__ */ new Set();
+		this.activeHandlerPromises = /* @__PURE__ */ new Set();
+		this.dispatchConstructionDepth = 0;
 		this.name = config.name || "ActionRegister";
 		this.registryConfig = config.registry;
 		this.maxHandlersPerAction = config.registry?.maxHandlersPerAction ?? 1e3;
@@ -891,10 +1082,10 @@ var ActionRegister = class {
 	}
 	/**
 	* 🆕 Action-based dispatcher
-	* 
+	*
 	* Provides function-based access to actions for more convenient dispatching.
 	* Each action becomes a callable function that can be invoked directly.
-	* 
+	*
 	* @example
 	* ```typescript
 	* interface MyActions extends ActionPayloadMap {
@@ -907,19 +1098,19 @@ var ActionRegister = class {
 	* // Function-based dispatching
 	* await registry.actions.userLogin({ userId: '123', email: 'test@example.com' });
 	* await registry.actions.resetApp();
+	* await registry.actions.resetApp({ debounce: 100 }); // Legacy options-first form
+	* await registry.actions.resetApp(undefined, { debounce: 100 });
 	* ```
 	* 
 	* @public
 	*/
 	get actions() {
 		if (!this._actionsProxy) this._actionsProxy = new Proxy({}, { get: (_target, prop) => {
-			if (typeof prop === "string" && this.pipelines.has(prop)) {
-				const actionKey = prop;
-				return (payloadOrOptions, options) => {
-					if (payloadOrOptions && isDispatchOptions(payloadOrOptions)) return this.dispatch(actionKey, void 0, payloadOrOptions);
-					else return this.dispatch(actionKey, payloadOrOptions, options);
-				};
-			}
+			const actionKey = prop;
+			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payloadOrOptions, options) => {
+				if (isDispatchOptions(payloadOrOptions)) return this.dispatch(actionKey, void 0, payloadOrOptions);
+				return this.dispatch(actionKey, payloadOrOptions, options);
+			};
 		} });
 		return this._actionsProxy;
 	}
@@ -936,6 +1127,10 @@ var ActionRegister = class {
 	* 
 	* // Actions without payload
 	* const result = await registry.actionsWithResult.userLogout();
+	* const debouncedResult = await registry.actionsWithResult.userLogout(
+	*   undefined,
+	*   { debounce: 100 }
+	* );
 	* 
 	* // With options
 	* const result = await registry.actionsWithResult.processData(
@@ -948,13 +1143,11 @@ var ActionRegister = class {
 	*/
 	get actionsWithResult() {
 		if (!this._actionsWithResultProxy) this._actionsWithResultProxy = new Proxy({}, { get: (_target, prop) => {
-			if (typeof prop === "string" && this.pipelines.has(prop)) {
-				const actionKey = prop;
-				return (payloadOrOptions, options) => {
-					if (payloadOrOptions && isDispatchOptions(payloadOrOptions)) return this.dispatchWithResult(actionKey, void 0, payloadOrOptions);
-					else return this.dispatchWithResult(actionKey, payloadOrOptions, options);
-				};
-			}
+			const actionKey = prop;
+			if (typeof prop === "string" && this.pipelines.has(actionKey)) return (payloadOrOptions, options) => {
+				if (isDispatchOptions(payloadOrOptions)) return this.dispatchWithResult(actionKey, void 0, payloadOrOptions);
+				return this.dispatchWithResult(actionKey, payloadOrOptions, options);
+			};
 		} });
 		return this._actionsWithResultProxy;
 	}
@@ -974,6 +1167,7 @@ var ActionRegister = class {
 	* @public
 	*/
 	register(action, handler, config = {}) {
+		this.assertAcceptingWork();
 		const handlerId = config.id || this.generateHandlerId(action);
 		return this._performRegistrationSync(action, handler, config, handlerId);
 	}
@@ -986,6 +1180,15 @@ var ActionRegister = class {
 			console[level](`🎯 [${timestamp}] [${this.name}] ${message}`, data || "");
 		}
 	}
+	assertAcceptingWork() {
+		if (this.lifecycleState !== "active") throw new ActionRegisterDestroyedError(this.name, this.lifecycleState);
+	}
+	rejectedLifecyclePromise() {
+		const error = new ActionRegisterDestroyedError(this.name, this.lifecycleState === "active" ? "destroyed" : this.lifecycleState);
+		const rejected = Promise.reject(error);
+		rejected.catch(() => {});
+		return rejected;
+	}
 	/**
 	* 🔧 Generate unique handler ID using optimized counter-based approach
 	*/
@@ -1124,16 +1327,245 @@ var ActionRegister = class {
 		});
 		return unregister;
 	}
-	async dispatch(action, payload, options) {
-		if (options?.immediate || !this.dispatchQueue) return this._performDispatch(action, payload, options);
-		else return this.dispatchQueue.enqueue(async () => {
-			return this._performDispatch(action, payload, options);
+	dispatch(action, payload, options) {
+		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 executedHandlers = [];
+				try {
+					return await this._performDispatch(action, payload, timeoutScope.options, attemptState.count > 1, executedHandlers, dispatchHandlerPromises);
+				} finally {
+					this.cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises);
+				}
+			}, timeoutScope.options, attemptState, void 0, () => this.getHandlerCount(action) > 0);
+		};
+		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;
+		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);
+		} finally {
+			this.dispatchConstructionDepth -= 1;
+		}
+		const observedPromise = this.raceWithTimeout(dispatchPromise, timeoutScope, dispatchHandlerPromises).catch((error) => {
+			this.invokeErrorHandler(error, action, payload, options, attemptState.count);
+			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) {
+		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;
+			try {
+				const result = await operation();
+				if (!(shouldRetryResult?.(result) ?? false) || attemptState.count >= maxAttempts || options?.signal?.aborted || !canRetry()) return result;
+			} catch (error) {
+				if (error instanceof ActionValidationError || attemptState.count >= maxAttempts || options?.signal?.aborted || !canRetry()) throw error;
+			}
+			await this.waitForRetry(retryDelay, options?.signal);
+		}
+		return operation();
+	}
+	trackDispatchPromise(promise) {
+		this.activeDispatches.add(promise);
+		const remove = () => this.activeDispatches.delete(promise);
+		promise.then(remove, remove);
+		return promise;
+	}
+	trackHandlerPromise(promise, dispatchHandlerPromises) {
+		this.activeHandlerPromises.add(promise);
+		dispatchHandlerPromises.add(promise);
+		const remove = () => {
+			this.activeHandlerPromises.delete(promise);
+			dispatchHandlerPromises.delete(promise);
+		};
+		promise.then(remove, remove);
+		return promise;
+	}
+	trackGlobalHandlerPromise(promise) {
+		this.activeHandlerPromises.add(promise);
+		const remove = () => this.activeHandlerPromises.delete(promise);
+		promise.then(remove, remove);
+		return promise;
+	}
+	/** Abort-aware retry delay so cancellation does not wait for the full backoff. */
+	waitForRetry(delay, signal) {
+		if (delay <= 0 || signal?.aborted) return Promise.resolve();
+		return new Promise((resolve) => {
+			const timer = setTimeout(finish, delay);
+			const abort = () => finish();
+			function finish() {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", abort);
+				resolve();
+			}
+			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 timeoutController = hasTimeout ? new AbortController() : void 0;
+		const signalCleanups = [];
+		const timeoutCallbacks = /* @__PURE__ */ new Set();
+		const signals = [
+			this.lifecycleController.signal,
+			options?.signal,
+			timeoutController?.signal
+		].filter((candidate) => Boolean(candidate));
+		let signal = signals[0];
+		if (signals.length > 1) if (typeof AbortSignal.any === "function") signal = AbortSignal.any(signals);
+		else {
+			const mergedController = new AbortController();
+			const forwardAbort = (source) => {
+				if (!mergedController.signal.aborted) mergedController.abort(source.reason);
+			};
+			for (const source of signals) {
+				if (source.aborted) {
+					forwardAbort(source);
+					break;
+				}
+				const listener = () => forwardAbort(source);
+				source.addEventListener("abort", listener, { once: true });
+				signalCleanups.push(() => source.removeEventListener("abort", listener));
+			}
+			signal = mergedController.signal;
+		}
+		let timer;
+		const timeoutPromise = timeoutController && timeout !== void 0 ? new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				const error = new ActionTimeoutError(String(action), timeout);
+				timeoutController.abort(error);
+				timeoutCallbacks.forEach((callback) => callback(error));
+				reject(error);
+			}, timeout);
+		}) : void 0;
+		return {
+			options: {
+				...options,
+				signal
+			},
+			timeoutPromise,
+			onTimeout: (callback) => timeoutCallbacks.add(callback),
+			cleanup: () => {
+				if (timer !== void 0) clearTimeout(timer);
+				timeoutCallbacks.clear();
+			},
+			cleanupSignals: () => signalCleanups.forEach((cleanup) => cleanup())
+		};
+	}
+	/** Expose timeout failure while allowing the queued operation to drain safely. */
+	raceWithTimeout(operation, scope, dispatchHandlerPromises) {
+		const exposed = scope.timeoutPromise ? Promise.race([operation, scope.timeoutPromise]) : operation;
+		const cleanupAfterStartedHandlers = () => {
+			scope.cleanup();
+			this.cleanupSignalsAfterStartedHandlers(scope.cleanupSignals, dispatchHandlerPromises);
+		};
+		exposed.then(cleanupAfterStartedHandlers, cleanupAfterStartedHandlers);
+		return exposed;
+	}
+	cleanupSignalsAfterStartedHandlers(cleanup, dispatchHandlerPromises) {
+		const handlersStillRunning = [...dispatchHandlerPromises];
+		if (handlersStillRunning.length === 0) {
+			cleanup();
+			return;
+		}
+		Promise.allSettled(handlersStillRunning).then(cleanup);
+	}
+	/** Invoke the configured error handler without allowing it to replace the dispatch error. */
+	invokeErrorHandler(error, action, payload, options, attempts) {
+		const errorHandler = this.registryConfig?.errorHandler;
+		if (!errorHandler) return;
+		const normalizedError = error instanceof Error ? error : new Error(String(error));
+		try {
+			const handlerResult = errorHandler(normalizedError, {
+				action: String(action),
+				payload,
+				options,
+				attempts,
+				phase: normalizedError instanceof ActionTimeoutError ? "timeout" : normalizedError instanceof ActionValidationError ? "validation" : "execution"
+			});
+			if (handlerResult && typeof handlerResult.then === "function") Promise.resolve(handlerResult).catch((handlerError) => {
+				this.log("Global async error handler failed", handlerError, "warn");
+			});
+		} catch (handlerError) {
+			this.log("Global error handler failed", handlerError, "warn");
+		}
+	}
+	/**
+	* Validate an action payload against the configured schema.
+	* Shared by all dispatch paths so result collection cannot bypass validation.
+	*/
+	validatePayload(action, payload) {
+		if (!this.registryConfig?.schema || this.registryConfig.validateOnDispatch === false) return;
+		const actionName = String(action);
+		const actionSchema = this.registryConfig.schema[actionName];
+		if (!actionSchema) return;
+		let result;
+		try {
+			result = actionSchema.safeParse(payload);
+		} catch (error) {
+			throw new ActionValidationError(actionName, error);
+		}
+		if (result.success) return {
+			passed: true,
+			errors: []
+		};
+		const mode = this.registryConfig.validationMode ?? "strict";
+		if (mode === "strict") throw new ActionValidationError(actionName, result.error);
+		if (mode === "warn") {
+			console.warn(`Action "${actionName}" payload validation failed:`, result.error.message);
+			this.log(`Validation warning for action '${actionName}'`, { issues: result.error.issues }, "warn");
+		}
+		return {
+			passed: false,
+			errors: result.error.issues.map((issue) => issue.message)
+		};
+	}
+	createAbortedExecutionResult(startTime, handlersSkipped = 0, validation) {
+		const endTime = Date.now();
+		return {
+			success: false,
+			aborted: true,
+			abortReason: "Action dispatch aborted by signal",
+			terminated: false,
+			validation,
+			result: void 0,
+			successResults: [],
+			results: [],
+			failedResults: [],
+			execution: {
+				duration: endTime - startTime,
+				handlersExecuted: 0,
+				handlersSkipped,
+				handlersFailed: 0,
+				startTime,
+				endTime
+			},
+			handlers: [],
+			errors: []
+		};
+	}
 	/**
 	* 🆕 실제 디스패치 작업 수행 (큐에서 호출됨)
 	*/
-	async _performDispatch(action, payload, options) {
+	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,
@@ -1145,6 +1577,7 @@ var ActionRegister = class {
 		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);
@@ -1162,6 +1595,7 @@ var ActionRegister = class {
 				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;
@@ -1182,17 +1616,32 @@ var ActionRegister = class {
 				break;
 			}
 		}
-		if (debounceMs !== void 0) {
-			if (!await this.actionGuard.debounce(actionKey, debounceMs)) return;
+		if (!skipGuards && debounceMs !== void 0) {
+			if (!await this.actionGuard.debounce(actionKey, debounceMs)) {
+				cleanup();
+				return;
+			}
 		}
-		if (throttleMs !== void 0) {
-			if (!this.actionGuard.throttle(actionKey, throttleMs)) return;
+		if (!skipGuards && throttleMs !== void 0) {
+			if (!this.actionGuard.throttle(actionKey, throttleMs)) {
+				cleanup();
+				return;
+			}
+		}
+		if (effectiveSignal?.aborted) {
+			this.log(`Dispatch aborted during guard processing for '${String(action)}'`);
+			cleanup();
+			return;
 		}
 		const currentExecutionMode = options?.executionMode || this.actionExecutionModes.get(action) || this.executionMode;
 		const context = {
 			action: String(action),
 			payload,
-			handlers: filteredHandlers,
+			handlers: [...filteredHandlers],
+			executedHandlers: [],
+			deferOnceCleanup: true,
+			signal: effectiveSignal ?? this.lifecycleController.signal,
+			trackHandlerPromise: (promise) => this.trackHandlerPromise(promise, dispatchHandlerPromises),
 			aborted: false,
 			abortReason: void 0,
 			currentIndex: 0,
@@ -1206,17 +1655,19 @@ var ActionRegister = class {
 		};
 		const abortHandler = effectiveSignal ? () => {
 			context.aborted = true;
-			context.abortReason = "Action dispatch aborted by signal";
+			context.abortReason = typeof effectiveSignal.reason === "string" ? effectiveSignal.reason : "Action dispatch aborted by signal";
 		} : void 0;
-		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
+		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler, { once: true });
 		try {
-			await this.executePipeline(context, autoAbortController, options?.autoAbort);
+			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;
 		} finally {
-			cleanup();
+			executedHandlers?.push(...context.executedHandlers ?? []);
+			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+			this.cleanupSignalsAfterStartedHandlers(cleanup, dispatchHandlerPromises);
 		}
 	}
 	/**
@@ -1232,30 +1683,57 @@ var ActionRegister = class {
 	* 
 	* @public
 	*/
-	async dispatchWithResult(action, payload, options) {
+	dispatchWithResult(action, payload, options) {
+		if (this.lifecycleState !== "active") return this.rejectedLifecyclePromise();
+		const timeoutScope = this.createTimeoutScope(action, options);
+		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 () => {
+				const executedHandlers = [];
+				try {
+					return await this._performDispatchWithResult(action, payload, timeoutScope.options, validation, attemptState.count > 1, executedHandlers, dispatchHandlerPromises);
+				} finally {
+					this.cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises);
+				}
+			}, timeoutScope.options, attemptState, (result) => !result.success && !result.aborted && this.getHandlerCount(action) > 0, () => this.getHandlerCount(action) > 0);
+		};
+		const shouldQueue = !timeoutScope.options?.immediate && Boolean(this.dispatchQueue) && timeoutScope.options?.queuePriority !== void 0;
+		let dispatchPromise;
+		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);
+		} 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);
+			throw error;
+		});
+		observedPromise.catch(() => {});
+		return observedPromise;
+	}
+	async _performDispatchWithResult(action, payload, options, validation, skipGuards, 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) return {
-			success: false,
-			aborted: true,
-			abortReason: "Action dispatch aborted by signal",
-			terminated: false,
-			result: void 0,
-			successResults: [],
-			results: [],
-			failedResults: [],
-			execution: {
-				duration: 0,
-				handlersExecuted: 0,
-				handlersSkipped: 0,
-				handlersFailed: 0,
-				startTime: _startTime,
-				endTime: _startTime
-			},
-			handlers: [],
-			errors: []
-		};
+		if (effectiveSignal?.aborted) {
+			cleanup();
+			return this.createAbortedExecutionResult(_startTime, 0, validation);
+		}
 		const pipeline = this.pipelines.get(action);
 		if (!pipeline || pipeline.length === 0) {
 			const warningMessage = `⚠️ Action '${String(action)}' has no registered handlers. This action will be ignored.`;
@@ -1264,11 +1742,13 @@ var ActionRegister = class {
 				console.warn("💡 Tip: Register a handler using registry.register() before dispatching this action.");
 				console.warn("📋 Available actions:", Array.from(this.pipelines.keys()));
 			}
+			cleanup();
 			return {
 				success: true,
 				aborted: false,
 				abortReason: void 0,
 				terminated: false,
+				validation,
 				result: void 0,
 				successResults: [],
 				results: [],
@@ -1287,13 +1767,27 @@ var ActionRegister = class {
 		}
 		const filteredHandlers = options?.filter ? this.filterHandlers(pipeline, options.filter) : pipeline;
 		const actionKey = String(action);
-		const guardResult = await this.applyActionGuardControlsWithResult(actionKey, filteredHandlers, options, _startTime, pipeline.length);
-		if (guardResult) return guardResult;
+		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 context = {
 			action: String(action),
 			payload,
-			handlers: filteredHandlers,
+			handlers: [...filteredHandlers],
+			executedHandlers: [],
+			deferOnceCleanup: true,
+			signal: effectiveSignal ?? this.lifecycleController.signal,
+			trackHandlerPromise: (promise) => this.trackHandlerPromise(promise, dispatchHandlerPromises),
 			aborted: false,
 			abortReason: void 0,
 			currentIndex: 0,
@@ -1319,12 +1813,12 @@ var ActionRegister = class {
 		});
 		const abortHandler = effectiveSignal ? () => {
 			context.aborted = true;
-			context.abortReason = "Action dispatch aborted by signal";
+			context.abortReason = typeof effectiveSignal.reason === "string" ? effectiveSignal.reason : "Action dispatch aborted by signal";
 		} : void 0;
-		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler);
+		if (effectiveSignal && abortHandler) effectiveSignal.addEventListener("abort", abortHandler, { once: true });
 		let errors = [];
 		try {
-			await this.executePipeline(context, autoAbortController, options?.autoAbort);
+			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++) {
@@ -1350,7 +1844,9 @@ var ActionRegister = class {
 				if (handlerResult) handlerResult.executed = true;
 			}
 		} finally {
-			cleanup();
+			executedHandlers.push(...context.executedHandlers ?? []);
+			if (effectiveSignal && abortHandler) effectiveSignal.removeEventListener("abort", abortHandler);
+			this.cleanupSignalsAfterStartedHandlers(cleanup, dispatchHandlerPromises);
 		}
 		const endTime = Date.now();
 		const processedResult = this.processResults(context, options?.result);
@@ -1360,11 +1856,12 @@ var ActionRegister = class {
 			error: err.error,
 			expectedType: typeof processedResult
 		}));
-		const executionResult = {
+		return {
 			success: !executionError && !context.aborted,
 			aborted: context.aborted,
 			abortReason: context.abortReason,
 			terminated: context.terminated,
+			validation,
 			result: processedResult,
 			successResults,
 			results: context.results,
@@ -1385,9 +1882,6 @@ var ActionRegister = class {
 				severity: "non-blocking"
 			}))
 		};
-		/** Clean up one-time handlers after execution */
-		this.cleanupOneTimeHandlers(action, context.handlers);
-		return executionResult;
 	}
 	/**
 	* 🔧 Unified method for dispatchWithResult that returns ExecutionResult on guard rejection
@@ -1476,6 +1970,7 @@ var ActionRegister = class {
 	getControllerFromPool(context, autoAbortController, autoAbortOptions) {
 		let controller = this.controllerPool.pop();
 		if (!controller) controller = {};
+		controller.signal = context.signal ?? this.lifecycleController.signal;
 		controller.abort = (reason) => {
 			context.aborted = true;
 			context.abortReason = reason;
@@ -1554,7 +2049,7 @@ var ActionRegister = class {
 				return limitedResults[limitedResults.length - 1];
 		}
 	}
-	async executePipeline(context, autoAbortController, autoAbortOptions) {
+	async executePipeline(context, dispatchHandlerPromises, autoAbortController, autoAbortOptions) {
 		const createController = (_registration, _index) => {
 			return this.getControllerFromPool(context, autoAbortController, autoAbortOptions);
 		};
@@ -1570,28 +2065,27 @@ var ActionRegister = class {
 				break;
 			default: throw new Error(`Unknown execution mode: ${context.executionMode}`);
 		}
-		this.cleanupOneTimeHandlers(context.action, context.handlers);
+		if (!context.deferOnceCleanup) this.cleanupOneTimeHandlers(context.action, context.executedHandlers ?? [], dispatchHandlerPromises);
 	}
-	cleanupOneTimeHandlers(action, executedHandlers) {
-		const pipeline = this.pipelines.get(action);
-		if (!pipeline) return;
+	cleanupOneTimeHandlers(action, executedHandlers, dispatchHandlerPromises) {
 		const oneTimeHandlers = executedHandlers.filter((reg) => reg.config.once);
 		if (oneTimeHandlers.length === 0) return;
+		const handlersStillRunning = [...dispatchHandlerPromises];
+		const shouldDeferCleanup = handlersStillRunning.length > 0;
 		oneTimeHandlers.forEach((registration) => {
-			const index = pipeline.findIndex((reg) => reg.id === registration.id);
-			if (index !== -1) {
-				pipeline.splice(index, 1);
-				if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 One-time handler removed: ${String(action)}`, {
+			if (this.removeRegistration(action, registration, !shouldDeferCleanup)) {
+				if (shouldDeferCleanup && typeof registration.config.cleanup === "function") {
+					const cleanupPromise = Promise.allSettled(handlersStillRunning).then(() => {
+						this.runRegistrationCleanup(action, registration);
+					});
+					this.trackGlobalHandlerPromise(cleanupPromise).catch(() => {});
+				}
+				this.log(`One-time handler removed: ${String(action)}`, {
 					handlerId: registration.id,
-					remainingHandlers: pipeline.length,
-					registry: this.name
+					remainingHandlers: this.getHandlerCount(action)
 				});
 			}
 		});
-		if (pipeline.length === 0) {
-			this.pipelines.delete(action);
-			this.lastRegisteredTimestamps.delete(action);
-		}
 	}
 	/**
 	* Get the number of registered handlers for an action
@@ -1644,8 +2138,13 @@ var ActionRegister = class {
 	* @public
 	*/
 	clearAction(action) {
+		const pipeline = this.pipelines.get(action);
+		if (pipeline) [...pipeline].forEach((registration) => {
+			this.removeRegistration(action, registration);
+		});
 		this.pipelines.delete(action);
 		this.lastRegisteredTimestamps.delete(action);
+		this.actionGuard.clearGuards(String(action));
 	}
 	/**
 	* Remove all handlers for all actions
@@ -1655,8 +2154,13 @@ var ActionRegister = class {
 	* @public
 	*/
 	clearAll() {
+		[...this.pipelines.keys()].forEach((action) => {
+			this.clearAction(action);
+		});
 		this.pipelines.clear();
 		this.lastRegisteredTimestamps.clear();
+		this.unregisterFunctions.clear();
+		this.actionGuard.clearAll();
 	}
 	/**
 	* Get the name of this action register
@@ -1785,29 +2289,36 @@ var ActionRegister = class {
 	*/
 	createUnregisterFunction(action, handlerId, registration) {
 		return () => {
-			const pipeline = this.pipelines.get(action);
-			if (!pipeline) return;
-			const index = pipeline.findIndex((reg) => reg.id === handlerId && reg === registration);
-			if (index !== -1) {
-				pipeline.splice(index, 1);
-				this.unregisterFunctions.delete(handlerId);
-				if (pipeline.length === 0) {
-					this.pipelines.delete(action);
-					this.lastRegisteredTimestamps.delete(action);
-				}
-				if (registration.config.cleanup && typeof registration.config.cleanup === "function") try {
-					registration.config.cleanup();
-				} catch (cleanupError) {
-					this.log(`Cleanup error during unregister: ${String(action)}`, cleanupError, "warn");
-				}
-				this.log(`Handler unregistered: ${String(action)}`, {
-					handlerId,
-					remainingHandlers: pipeline.length,
-					actionRemoved: pipeline.length === 0
-				});
-			}
+			if (this.removeRegistration(action, registration)) this.log(`Handler unregistered: ${String(action)}`, {
+				handlerId,
+				remainingHandlers: this.getHandlerCount(action),
+				actionRemoved: !this.pipelines.has(action)
+			});
 		};
 	}
+	/** Remove a registration and release every resource owned by it exactly once. */
+	removeRegistration(action, registration, runCleanup = true) {
+		const pipeline = this.pipelines.get(action);
+		if (!pipeline) return false;
+		const index = pipeline.findIndex((candidate) => candidate === registration);
+		if (index === -1) return false;
+		pipeline.splice(index, 1);
+		this.unregisterFunctions.delete(registration.id);
+		if (runCleanup) this.runRegistrationCleanup(action, registration);
+		if (pipeline.length === 0) {
+			this.pipelines.delete(action);
+			this.lastRegisteredTimestamps.delete(action);
+		}
+		return true;
+	}
+	runRegistrationCleanup(action, registration) {
+		if (!registration.config.cleanup) return;
+		try {
+			registration.config.cleanup();
+		} catch (cleanupError) {
+			this.log(`Cleanup error while removing handler: ${String(action)}`, cleanupError, "warn");
+		}
+	}
 	/**
 	* Gets the total count of registered unregister functions
 	* 
@@ -1827,29 +2338,77 @@ var ActionRegister = class {
 	hasUnregisterFunction(handlerId) {
 		return this.unregisterFunctions.has(handlerId);
 	}
-	/**
-	* 🆕 Destroy method for comprehensive cleanup
-	* 
-	* Cleans up all internal resources including pipelines, guards, queues, and statistics.
-	* Should be called when the ActionRegister is no longer needed to prevent memory leaks.
-	* 
-	* @public
-	*/
-	destroy() {
-		this.unregisterFunctions.clear();
-		for (const [action, pipeline] of this.pipelines.entries()) for (const registration of pipeline) if (registration.config.cleanup && typeof registration.config.cleanup === "function") try {
-			registration.config.cleanup();
-		} catch (cleanupError) {
-			this.log(`Cleanup error for handler during destroy: ${String(action)}`, cleanupError, "warn");
+	/** Reject queued dispatches without releasing registered handlers. */
+	cancelPendingDispatches() {
+		this.dispatchQueue?.clear({ rejectPending: true });
+	}
+	beginShutdown() {
+		if (this.destroyAsyncPromise) return this.destroyAsyncPromise;
+		if (this.lifecycleState === "destroyed") {
+			this.destroyAsyncPromise = Promise.resolve();
+			return this.destroyAsyncPromise;
 		}
-		this.pipelines.clear();
-		this.lastRegisteredTimestamps.clear();
+		this.lifecycleState = "closing";
+		const shutdownError = new ActionRegisterDestroyedError(this.name, "closing");
+		let resolveShutdown;
+		let rejectShutdown;
+		this.destroyAsyncPromise = new Promise((resolve, reject) => {
+			resolveShutdown = resolve;
+			rejectShutdown = reject;
+		});
+		if (!this.lifecycleController.signal.aborted) this.lifecycleController.abort(shutdownError);
 		this.actionGuard.destroy();
-		this.dispatchQueue?.clear?.();
+		this.dispatchQueue?.clear({
+			rejectPending: true,
+			reason: shutdownError
+		});
+		if (this.dispatchConstructionDepth === 0 && this.activeDispatches.size === 0 && this.activeHandlerPromises.size === 0) {
+			this.finalizeDestroy();
+			resolveShutdown();
+			return this.destroyAsyncPromise;
+		}
+		const drainAndFinalize = async () => {
+			while (this.activeDispatches.size > 0 || this.activeHandlerPromises.size > 0) await Promise.allSettled([...this.activeDispatches, ...this.activeHandlerPromises]);
+			this.finalizeDestroy();
+		};
+		Promise.resolve().then(drainAndFinalize).then(resolveShutdown, rejectShutdown);
+		this.destroyAsyncPromise.catch((error) => {
+			this.log("ActionRegister async destroy failed", error, "warn");
+		});
+		return this.destroyAsyncPromise;
+	}
+	finalizeDestroy() {
+		if (this.lifecycleState === "destroyed") return;
+		this.clearAll();
 		this.actionExecutionModes.clear();
 		this.controllerPool.length = 0;
+		this.lifecycleState = "destroyed";
 		this.log("ActionRegister destroyed");
 	}
+	/**
+	* 🆕 Destroy method for comprehensive cleanup
+	*
+	* Begins terminal cleanup of pipelines, guards, queues, and statistics. Cleanup
+	* remains synchronous when no work has started; otherwise active handlers drain
+	* in the background. Use destroyAsync() when completion must be observed.
+	*
+	* @public
+	*/
+	destroy() {
+		this.beginShutdown();
+	}
+	/**
+	* Begin terminal shutdown and resolve after all started handlers have settled
+	* and their registered cleanup functions have run.
+	*
+	* Repeated calls return the same promise. New registrations and dispatches are
+	* rejected as soon as shutdown begins.
+	*
+	* @public
+	*/
+	destroyAsync() {
+		return this.beginShutdown();
+	}
 };
 
 //#endregion
@@ -1938,12 +2497,18 @@ function createActionHandler(registry, action, handler, config) {
 	let currentUnregister;
 	let isRegistered = false;
 	return {
+		/**
+		* Register the handler and return cleanup function
+		*/
 		register() {
 			if (isRegistered && currentUnregister) currentUnregister();
 			currentUnregister = registry.register(action, handler, finalConfig);
 			isRegistered = true;
 			return currentUnregister;
 		},
+		/**
+		* Unregister the handler if currently registered
+		*/
 		unregister() {
 			if (isRegistered && currentUnregister) {
 				currentUnregister();
@@ -1951,6 +2516,9 @@ function createActionHandler(registry, action, handler, config) {
 				isRegistered = false;
 			}
 		},
+		/**
+		* Register and return cleanup function (React useEffect pattern)
+		*/
 		registerWithCleanup() {
 			const unregisterFn = this.register();
 			return () => {
@@ -1967,18 +2535,33 @@ function createActionHandler(registry, action, handler, config) {
 * Provides debugging and development helpers specifically for React environments.
 */
 const ReactDevUtils = {
+	/**
+	* Enable detailed React integration debugging
+	*/
 	enableDebugMode() {
 		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = true;
 	},
+	/**
+	* Disable React integration debugging
+	*/
 	disableDebugMode() {
 		if (typeof window !== "undefined") window.__CONTEXT_ACTION_REACT_DEBUG__ = false;
 	},
+	/**
+	* Check if React debug mode is enabled
+	*/
 	isDebugMode() {
 		return typeof window !== "undefined" && Boolean(window.__CONTEXT_ACTION_REACT_DEBUG__);
 	},
+	/**
+	* Log React-specific debugging information
+	*/
 	log(component, action, message, data) {
 		if (this.isDebugMode()) console.log(`🎯 [React-ActionRegister] [${component}] ${action}: ${message}`, data || "");
 	},
+	/**
+	* Get React integration statistics
+	*/
 	getStats(registry) {
 		const registryInfo = registry.getRegistryInfo();
 		let reactHandlers = 0;
@@ -2029,13 +2612,158 @@ function isReactActionError(error) {
 	return error instanceof ReactActionError;
 }
 
+//#endregion
+//#region src/action-schema.ts
+/**
+* Zod 스키마를 JSON Schema로 변환 (Zod 4 네이티브 API)
+*
+* @param schema - Zod 스키마
+* @returns JSON Schema (draft-7)
+*/
+function zodToJsonSchema(schema, zodModule) {
+	return zodModule.toJSONSchema(schema, {
+		target: "draft-7",
+		metadata: zodModule.globalRegistry
+	});
+}
+/**
+* Zod 스키마 기반 Action 정의
+*
+* defineTool 패턴을 기반으로 context-action에 맞게 구현:
+* - Single Source of Truth: Zod 스키마로 타입 + 검증 + 메타데이터 통합
+* - 런타임 검증: validate(), safeParse()
+* - Tool Chain 호환: toMCP(), toOpenAI(), toAnthropic()
+*
+* @param options - Action 정의 옵션
+* @param zodModule - Zod 모듈 (peerDependency로 주입)
+* @returns UnifiedAction 인스턴스
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+* import { defineAction } from '@context-action/core';
+*
+* const updateUserAction = defineAction({
+*   name: 'updateUser',
+*   description: 'Update user profile',
+*   parameters: z.object({
+*     id: z.string().min(1).meta({ description: 'User ID' }),
+*     name: z.string().min(2).max(50).meta({ description: 'User name' }),
+*     email: z.string().email().optional(),
+*   }),
+* }, z);
+*
+* // 검증
+* const validated = updateUserAction.validate({ id: '123', name: 'John' });
+*
+* // Tool chain 변환
+* const mcpTool = updateUserAction.toMCP();
+* ```
+*/
+function defineAction(options, zodModule) {
+	const { name, description, parameters } = options;
+	const jsonSchema = zodToJsonSchema(parameters, zodModule);
+	return {
+		name,
+		description,
+		zodSchema: parameters,
+		jsonSchema,
+		validate: (payload) => {
+			return parameters.parse(payload);
+		},
+		safeParse: (payload) => {
+			return parameters.safeParse(payload);
+		},
+		toJSONSchema: () => jsonSchema,
+		toMCP: () => ({
+			name,
+			description,
+			inputSchema: jsonSchema
+		}),
+		toOpenAI: () => ({
+			type: "function",
+			function: {
+				name,
+				description,
+				parameters: {
+					type: "object",
+					properties: jsonSchema.properties ?? {},
+					required: jsonSchema.required
+				}
+			}
+		}),
+		toAnthropic: () => ({
+			name,
+			description,
+			input_schema: jsonSchema
+		})
+	};
+}
+/**
+* 다중 Action 스키마 생성
+*
+* 여러 defineAction을 묶어서 ActionSchemaMap 생성
+*
+* @param actions - UnifiedAction 맵
+* @returns ActionSchemaMap
+*
+* @example
+* ```typescript
+* const userActionSchema = createActionSchema({
+*   updateUser: defineAction({ ... }, z),
+*   deleteUser: defineAction({ ... }, z),
+* });
+*
+* type UserActions = InferActionPayloadMap<typeof userActionSchema>;
+* ```
+*/
+function createActionSchema(actions) {
+	return actions;
+}
+/**
+* Zod 모듈을 바인딩한 defineAction 팩토리 생성
+*
+* 매번 z 모듈을 전달하지 않아도 되도록 팩토리 패턴 제공
+*
+* @param zodModule - Zod 모듈
+* @returns defineAction 함수 (z 바인딩됨)
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+* import { createActionFactory } from '@context-action/core';
+*
+* const defineAction = createActionFactory(z);
+*
+* const updateUser = defineAction({
+*   name: 'updateUser',
+*   parameters: z.object({ id: z.string() }),
+* });
+* ```
+*/
+function createActionFactory(zodModule) {
+	return (options) => {
+		return defineAction(options, zodModule);
+	};
+}
+
 //#endregion
 exports.ActionGuard = ActionGuard;
 exports.ActionRegister = ActionRegister;
+exports.ActionRegisterDestroyedError = ActionRegisterDestroyedError;
+exports.ActionTimeoutError = ActionTimeoutError;
+exports.ActionValidationError = ActionValidationError;
 exports.ReactActionError = ReactActionError;
 exports.ReactDevUtils = ReactDevUtils;
+exports.createActionFactory = createActionFactory;
 exports.createActionHandler = createActionHandler;
+exports.createActionSchema = createActionSchema;
+exports.defineAction = defineAction;
 exports.executeParallel = executeParallel;
 exports.executeRace = executeRace;
 exports.executeSequential = executeSequential;
-exports.isReactActionError = isReactActionError;
+exports.isActionRegisterDestroyedError = isActionRegisterDestroyedError;
+exports.isActionTimeoutError = isActionTimeoutError;
+exports.isActionValidationError = isActionValidationError;
+exports.isReactActionError = isReactActionError;
+exports.zodToJsonSchema = zodToJsonSchema;