@classytic/streamline 1.0.0

package/dist/container-BzpIMrrj.mjs

@@ -0,0 +1,2697 @@
+import { a as StepNotFoundError, c as WorkflowNotFoundError, r as InvalidStateError } from "./errors-BqunvWPz.mjs";
+import { n as globalEventBus, t as WorkflowEventBus } from "./events-B5aTz7kD.mjs";
+import { randomUUID } from "node:crypto";
+import { Repository, methodRegistryPlugin, mongoOperationsPlugin } from "@classytic/mongokit";
+import mongoose, { Schema } from "mongoose";
+
+//#region src/utils/logger.ts
+var Logger = class {
+	minLevel = "info";
+	setLevel(level) {
+		this.minLevel = level;
+	}
+	debug(message, context) {
+		this.log("debug", message, context);
+	}
+	info(message, context) {
+		this.log("info", message, context);
+	}
+	warn(message, context) {
+		this.log("warn", message, context);
+	}
+	error(message, error, context) {
+		const errorContext = error instanceof Error ? {
+			error: {
+				message: error.message,
+				stack: error.stack
+			},
+			...context
+		} : {
+			error,
+			...context
+		};
+		this.log("error", message, errorContext);
+	}
+	log(level, message, context) {
+		if (!this.shouldLog(level)) return;
+		const logEntry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level: level.toUpperCase(),
+			message,
+			...context
+		};
+		this.getLogFunction(level)(JSON.stringify(logEntry));
+	}
+	shouldLog(level) {
+		const levels = [
+			"debug",
+			"info",
+			"warn",
+			"error"
+		];
+		return levels.indexOf(level) >= levels.indexOf(this.minLevel);
+	}
+	getLogFunction(level) {
+		switch (level) {
+			case "error": return console.error;
+			case "warn": return console.warn;
+			case "info": return console.info;
+			default: return console.debug;
+		}
+	}
+};
+const logger = new Logger();
+if (process.env.NODE_ENV === "development") logger.setLevel("debug");
+
+//#endregion
+//#region src/execution/context.ts
+var WaitSignal = class extends Error {
+	constructor(type, reason, data) {
+		super(reason);
+		this.type = type;
+		this.reason = reason;
+		this.data = data;
+		this.name = "WaitSignal";
+	}
+};
+var StepContextImpl = class {
+	signal;
+	constructor(runId, stepId, context, input, attempt, run, repository, eventBus, signal) {
+		this.runId = runId;
+		this.stepId = stepId;
+		this.context = context;
+		this.input = input;
+		this.attempt = attempt;
+		this.run = run;
+		this.repository = repository;
+		this.eventBus = eventBus;
+		this.signal = signal ?? new AbortController().signal;
+	}
+	async set(key, value) {
+		if (this.signal.aborted) throw new Error(`Cannot update context: workflow ${this.runId} has been cancelled`);
+		this.context[key] = value;
+		this.run.context[key] = value;
+		if ((await this.repository.updateOne({
+			_id: this.runId,
+			status: { $ne: "cancelled" }
+		}, { $set: {
+			[`context.${String(key)}`]: value,
+			updatedAt: /* @__PURE__ */ new Date()
+		} }, { bypassTenant: true })).modifiedCount === 0) throw new Error(`Cannot update context: workflow ${this.runId} may have been cancelled`);
+	}
+	getOutput(stepId) {
+		return this.run.steps.find((s) => s.stepId === stepId)?.output;
+	}
+	async wait(reason, data) {
+		throw new WaitSignal("human", reason, data);
+	}
+	async waitFor(eventName, reason) {
+		throw new WaitSignal("event", reason || `Waiting for ${eventName}`, { eventName });
+	}
+	async sleep(ms) {
+		const resumeAt = new Date(Date.now() + ms);
+		throw new WaitSignal("timer", `Sleep ${ms}ms`, { resumeAt });
+	}
+	async heartbeat() {
+		if (this.signal.aborted) return;
+		try {
+			await this.repository.updateOne({
+				_id: this.runId,
+				status: { $ne: "cancelled" }
+			}, { lastHeartbeat: /* @__PURE__ */ new Date() }, { bypassTenant: true });
+		} catch {}
+	}
+	emit(eventName, data) {
+		this.eventBus.emit(eventName, {
+			runId: this.runId,
+			stepId: this.stepId,
+			data
+		});
+	}
+	log(message, data) {
+		logger.info(message, {
+			runId: this.runId,
+			stepId: this.stepId,
+			attempt: this.attempt,
+			...data !== void 0 && { data }
+		});
+	}
+};
+
+//#endregion
+//#region src/core/status.ts
+const STEP_STATUS_VALUES = [
+	"pending",
+	"running",
+	"waiting",
+	"done",
+	"failed",
+	"skipped"
+];
+const RUN_STATUS_VALUES = [
+	"draft",
+	"running",
+	"waiting",
+	"done",
+	"failed",
+	"cancelled"
+];
+function isStepStatus(value) {
+	return typeof value === "string" && STEP_STATUS_VALUES.includes(value);
+}
+function isRunStatus(value) {
+	return typeof value === "string" && RUN_STATUS_VALUES.includes(value);
+}
+function deriveRunStatus(run) {
+	if (run.status === "cancelled") return "cancelled";
+	const hasWaiting = run.steps.some((s) => s.status === "waiting");
+	const hasFailed = run.steps.some((s) => s.status === "failed");
+	const allDone = run.steps.every((s) => s.status === "done" || s.status === "skipped");
+	if (hasFailed) return "failed";
+	if (hasWaiting) return "waiting";
+	if (allDone) return "done";
+	return "running";
+}
+function isValidStepTransition(from, to) {
+	return {
+		pending: ["running", "skipped"],
+		running: [
+			"done",
+			"failed",
+			"waiting",
+			"pending"
+		],
+		waiting: [
+			"pending",
+			"done",
+			"failed"
+		],
+		done: ["pending"],
+		failed: ["pending"],
+		skipped: []
+	}[from]?.includes(to) ?? false;
+}
+function isValidRunTransition(from, to) {
+	return {
+		draft: ["running", "cancelled"],
+		running: [
+			"waiting",
+			"done",
+			"failed",
+			"cancelled"
+		],
+		waiting: ["running", "cancelled"],
+		done: ["running"],
+		failed: ["running"],
+		cancelled: []
+	}[from]?.includes(to) ?? false;
+}
+/**
+* Check if a workflow status represents a terminal (final) state
+*/
+function isTerminalState(status) {
+	return status === "done" || status === "failed" || status === "cancelled";
+}
+
+//#endregion
+//#region src/features/conditional.ts
+function isConditionalStep(step) {
+	const conditionalStep = step;
+	return !!(conditionalStep.condition || conditionalStep.skipIf || conditionalStep.runIf);
+}
+async function shouldSkipStep(step, context, run) {
+	if (step.condition) return !await Promise.resolve(step.condition(context, run));
+	if (step.skipIf) return await Promise.resolve(step.skipIf(context));
+	if (step.runIf) return !await Promise.resolve(step.runIf(context));
+	return false;
+}
+function createCondition(predicate) {
+	return predicate;
+}
+const conditions = {
+	hasValue: (key) => (context) => context[key] !== void 0 && context[key] !== null,
+	equals: (key, value) => (context) => context[key] === value,
+	notEquals: (key, value) => (context) => context[key] !== value,
+	greaterThan: (key, value) => (context) => typeof context[key] === "number" && context[key] > value,
+	lessThan: (key, value) => (context) => typeof context[key] === "number" && context[key] < value,
+	in: (key, values) => (context) => values.includes(context[key]),
+	and: (...predicates) => (context) => predicates.every((p) => p(context)),
+	or: (...predicates) => (context) => predicates.some((p) => p(context)),
+	not: (predicate) => (context) => !predicate(context),
+	custom: (predicate) => predicate
+};
+
+//#endregion
+//#region src/utils/helpers.ts
+/**
+* Calculate retry delay with exponential backoff and jitter
+*
+* Jitter prevents thundering herd problem where many workflows
+* retry at exactly the same time after a system failure.
+*
+* @param baseDelay - Starting delay (e.g., 1000ms)
+* @param attempt - Current attempt number (0-indexed)
+* @param multiplier - Exponential multiplier (e.g., 2 for doubling)
+* @param maxDelay - Cap for maximum delay
+* @param jitterFactor - Randomness factor (0.3 = ±30%)
+* @returns Delay in milliseconds with applied jitter
+*
+* @example
+* // Attempt 0: 1000ms ± 30% = 700-1300ms
+* // Attempt 1: 2000ms ± 30% = 1400-2600ms
+* // Attempt 2: 4000ms ± 30% = 2800-5200ms
+*/
+function calculateRetryDelay(baseDelay, attempt, multiplier, maxDelay, jitterFactor = .3) {
+	const exponentialDelay = baseDelay * Math.pow(multiplier, attempt);
+	const cappedDelay = Math.min(exponentialDelay, maxDelay);
+	const jitter = 1 + (Math.random() * 2 - 1) * jitterFactor;
+	const delayWithJitter = Math.round(cappedDelay * jitter);
+	return Math.max(delayWithJitter, 0);
+}
+
+//#endregion
+//#region src/config/constants.ts
+/**
+* System-wide timing and limit constants
+* Centralized to avoid magic numbers scattered across codebase
+*/
+const TIMING = {
+	HEARTBEAT_INTERVAL_MS: 3e4,
+	SHORT_DELAY_THRESHOLD_MS: 5e3,
+	STALE_WORKFLOW_THRESHOLD_MS: 300 * 1e3,
+	MAX_RETRY_DELAY_MS: 6e4,
+	RETRY_BASE_DELAY_MS: 1e3,
+	RETRY_MULTIPLIER: 2,
+	WEBHOOK_TIMEOUT_MS: 3e4,
+	HOOK_CLEANUP_INTERVAL_MS: 6e4
+};
+const LIMITS = {
+	MAX_CACHE_SIZE: 1e4,
+	DEFAULT_BATCH_SIZE: 100,
+	SCHEDULER_BATCH_SIZE: 100,
+	MAX_ID_LENGTH: 100,
+	MAX_STEPS_PER_WORKFLOW: 1e3,
+	MAX_RETRIES: 20,
+	MAX_STEP_TIMEOUT_MS: 1800 * 1e3
+};
+const RETRY = {
+	DEFAULT_MAX_ATTEMPTS: 3,
+	DEFAULT_TIMEOUT_MS: 3e4,
+	JITTER_FACTOR: .3
+};
+const SCHEDULER = {
+	MIN_POLL_INTERVAL_MS: 1e4,
+	MAX_POLL_INTERVAL_MS: 300 * 1e3,
+	BASE_POLL_INTERVAL_MS: 6e4,
+	IDLE_TIMEOUT_MS: 12e4,
+	MAX_CONSECUTIVE_FAILURES: 5,
+	STALE_CHECK_INTERVAL_MS: 300 * 1e3
+};
+const SCHEDULING = { PAST_SCHEDULE_GRACE_MS: 6e4 };
+/**
+* Computed values derived from base constants.
+* Useful for monitoring, alerting, and capacity planning.
+*/
+const COMPUTED = {
+	CACHE_WARNING_THRESHOLD: Math.floor(LIMITS.MAX_CACHE_SIZE * .8),
+	CACHE_CRITICAL_THRESHOLD: Math.floor(LIMITS.MAX_CACHE_SIZE * .95),
+	MAX_TIMEOUT_SAFE_MS: 2147483647,
+	RETRY_DELAY_SEQUENCE_MS: Array.from({ length: 5 }, (_, i) => Math.min(TIMING.RETRY_BASE_DELAY_MS * Math.pow(TIMING.RETRY_MULTIPLIER, i), TIMING.MAX_RETRY_DELAY_MS))
+};
+
+//#endregion
+//#region src/execution/step-updater.ts
+/**
+* Build MongoDB update operators for step state changes
+* 
+* Automatically handles:
+* - undefined values → $unset (remove from document)
+* - defined values → $set (update document)
+* - Always updates workflow-level updatedAt timestamp
+* 
+* @param stepIndex - Array index of step in workflow.steps[]
+* @param updates - Partial step state with fields to update
+* @param includeStatus - Whether to include derived status in $set
+* @returns MongoDB update operators ready for updateOne()
+*/
+function buildStepUpdateOps(stepIndex, updates, options) {
+	const $set = {};
+	const $unset = {};
+	for (const [key, value] of Object.entries(updates)) {
+		const fieldPath = `steps.${stepIndex}.${key}`;
+		if (value === void 0) $unset[fieldPath] = "";
+		else $set[fieldPath] = value;
+	}
+	if (options?.includeUpdatedAt !== false) $set.updatedAt = /* @__PURE__ */ new Date();
+	if (options?.includeStatus) $set.status = options.includeStatus;
+	return {
+		$set,
+		$unset
+	};
+}
+/**
+* Apply step updates to in-memory workflow run
+* Mirrors MongoDB update operations for consistency
+*/
+function applyStepUpdates(stepId, steps, updates) {
+	return steps.map((step) => {
+		if (step.stepId !== stepId) return step;
+		const updated = {
+			...step,
+			...updates
+		};
+		for (const key in updates) if (updates[key] === void 0) delete updated[key];
+		return updated;
+	});
+}
+/**
+* Convert Mongoose document to plain object (if needed)
+* Preserves context field which Mongoose sometimes drops for empty objects
+*/
+function toPlainRun(run) {
+	if ("toObject" in run && typeof run.toObject === "function") {
+		const savedContext = run.context;
+		const plain = run.toObject();
+		if (plain.context === void 0 && savedContext !== void 0) plain.context = savedContext;
+		return plain;
+	}
+	return run;
+}
+
+//#endregion
+//#region src/execution/executor.ts
+/**
+* Cancelled is the only externally-forced terminal state.
+* 'done' and 'failed' are reached through normal execution flow.
+* We only guard against 'cancelled' to prevent race conditions where
+* a cancelled workflow gets updated by an in-flight handler.
+*/
+const CANCELLED_GUARD = { status: { $ne: "cancelled" } };
+/**
+* Executor for workflow steps.
+*
+* Handles step execution with support for:
+* - Conditional execution (skip steps based on conditions)
+* - Atomic claiming (prevents duplicate execution in multi-worker setups)
+* - Retry with exponential backoff
+* - Timeout handling
+* - Wait states (sleep, human input, events)
+*/
+var StepExecutor = class {
+	/** Track active AbortControllers by runId for cancellation support */
+	activeControllers = /* @__PURE__ */ new Map();
+	constructor(registry, repository, eventBus, cache) {
+		this.registry = registry;
+		this.repository = repository;
+		this.eventBus = eventBus;
+		this.cache = cache;
+	}
+	/**
+	* Abort any in-flight step execution for a workflow.
+	* Called by engine.cancel() to stop long-running handlers.
+	*
+	* **Multi-worker limitation**: This only aborts handlers running in this process.
+	* If another worker is executing the step, the abort signal won't reach it.
+	* However, DB-level guards prevent cancelled workflows from being updated,
+	* so the other worker's updates will be rejected and the workflow stays cancelled.
+	*/
+	abortWorkflow(runId) {
+		const controller = this.activeControllers.get(runId);
+		if (controller) {
+			controller.abort(/* @__PURE__ */ new Error("Workflow cancelled"));
+			this.activeControllers.delete(runId);
+		}
+	}
+	/**
+	* Find a step by ID in a workflow run, throwing if not found
+	*/
+	findStepOrThrow(run, stepId) {
+		const index = run.steps.findIndex((s) => s.stepId === stepId);
+		if (index === -1) {
+			const availableSteps = run.steps.map((s) => s.stepId);
+			throw new StepNotFoundError(stepId, run.workflowId, availableSteps);
+		}
+		return {
+			step: run.steps[index],
+			index
+		};
+	}
+	/**
+	* Check if step should be skipped due to conditions.
+	* Returns updated run if skipped, null otherwise.
+	*/
+	async checkConditionalSkip(run, stepId, step) {
+		if (!isConditionalStep(step)) return null;
+		if (!await shouldSkipStep(step, run.context, run)) return null;
+		run = await this.updateStepState(run, stepId, {
+			status: "skipped",
+			endedAt: /* @__PURE__ */ new Date()
+		});
+		this.eventBus.emit("step:skipped", {
+			runId: run._id,
+			stepId
+		});
+		return await this.moveToNextStep(run);
+	}
+	/**
+	* Check if step is waiting for retry backoff.
+	* Returns updated run if waiting, null otherwise.
+	*/
+	async checkRetryBackoff(run, currentStepState) {
+		if (!currentStepState.retryAfter || /* @__PURE__ */ new Date() >= currentStepState.retryAfter) return null;
+		if (run.status !== "waiting") {
+			const now = /* @__PURE__ */ new Date();
+			if ((await this.repository.updateOne({
+				_id: run._id,
+				...CANCELLED_GUARD
+			}, {
+				status: "waiting",
+				updatedAt: now
+			}, { bypassTenant: true })).modifiedCount > 0) {
+				run.status = "waiting";
+				run.updatedAt = now;
+			} else this.cache.delete(run._id);
+		}
+		return run;
+	}
+	/**
+	* Check if step is already running by another worker.
+	* Returns refreshed run if already running, null otherwise.
+	*/
+	async checkAlreadyRunning(run, currentStepState) {
+		if (currentStepState.status !== "running") return null;
+		const refreshed = await this.repository.getById(run._id);
+		if (!refreshed) throw new WorkflowNotFoundError(run._id);
+		return refreshed;
+	}
+	/**
+	* Main execution method for a single step.
+	* Orchestrates conditional checks, atomic claiming, and handler execution.
+	*/
+	async executeStep(run) {
+		const stepId = run.currentStepId;
+		const step = this.registry.getStep(stepId);
+		const handler = this.registry.getHandler(stepId);
+		if (!step || !handler) {
+			const availableSteps = this.registry.definition.steps.map((s) => s.id);
+			throw new StepNotFoundError(stepId, run.workflowId, availableSteps);
+		}
+		const skippedRun = await this.checkConditionalSkip(run, stepId, step);
+		if (skippedRun) return skippedRun;
+		const currentStepState = run.steps.find((s) => s.stepId === stepId);
+		const waitingRun = await this.checkRetryBackoff(run, currentStepState);
+		if (waitingRun) return waitingRun;
+		const runningRun = await this.checkAlreadyRunning(run, currentStepState);
+		if (runningRun) return runningRun;
+		const claimedRun = await this.claimStepExecution(run, stepId, currentStepState);
+		if (!claimedRun) {
+			const refreshed = await this.repository.getById(run._id);
+			if (!refreshed) throw new WorkflowNotFoundError(run._id);
+			return refreshed;
+		}
+		return await this.executeStepHandler(claimedRun, stepId, step, handler);
+	}
+	/**
+	* Atomically claim a step for execution.
+	* Uses MongoDB atomic update to prevent duplicate execution in multi-worker setups.
+	* Returns updated run if claim succeeded, null if another worker claimed it.
+	*/
+	async claimStepExecution(run, stepId, currentStepState) {
+		const stepIndex = run.steps.findIndex((s) => s.stepId === stepId);
+		if (stepIndex === -1) {
+			const availableSteps = this.registry.definition.steps.map((s) => s.id);
+			throw new StepNotFoundError(stepId, run.workflowId, availableSteps);
+		}
+		const newAttempts = currentStepState.attempts + 1;
+		const now = /* @__PURE__ */ new Date();
+		if ((await this.repository.updateOne({
+			_id: run._id,
+			...CANCELLED_GUARD,
+			[`steps.${stepIndex}.status`]: { $in: ["pending", "failed"] },
+			$or: [{ [`steps.${stepIndex}.retryAfter`]: { $exists: false } }, { [`steps.${stepIndex}.retryAfter`]: { $lte: now } }]
+		}, {
+			$set: {
+				[`steps.${stepIndex}.status`]: "running",
+				[`steps.${stepIndex}.startedAt`]: now,
+				[`steps.${stepIndex}.attempts`]: newAttempts,
+				lastHeartbeat: now
+			},
+			$unset: {
+				[`steps.${stepIndex}.error`]: "",
+				[`steps.${stepIndex}.waitingFor`]: "",
+				[`steps.${stepIndex}.retryAfter`]: ""
+			}
+		}, { bypassTenant: true })).modifiedCount === 0) return null;
+		run = await this.updateStepState(run, stepId, {
+			status: "running",
+			startedAt: now,
+			attempts: newAttempts,
+			error: void 0,
+			waitingFor: void 0,
+			retryAfter: void 0
+		});
+		run.lastHeartbeat = now;
+		this.eventBus.emit("step:started", {
+			runId: run._id,
+			stepId
+		});
+		return run;
+	}
+	/**
+	* Execute the step handler and handle the result.
+	* Handles success, wait signals, and failures.
+	*/
+	async executeStepHandler(run, stepId, step, handler) {
+		const abortController = new AbortController();
+		this.activeControllers.set(run._id, abortController);
+		try {
+			const stepState = run.steps.find((s) => s.stepId === stepId);
+			const ctx = new StepContextImpl(run._id, stepId, run.context, run.input, stepState.attempts, run, this.repository, this.eventBus, abortController.signal);
+			const output = await this.executeWithTimeout(handler, ctx, step.timeout || this.registry.definition.defaults?.timeout, run._id, abortController);
+			run = await this.updateStepState(run, stepId, {
+				status: "done",
+				endedAt: /* @__PURE__ */ new Date(),
+				output,
+				error: void 0,
+				waitingFor: void 0,
+				retryAfter: void 0
+			});
+			this.eventBus.emit("step:completed", {
+				runId: run._id,
+				stepId,
+				data: output
+			});
+			return await this.moveToNextStep(run);
+		} catch (error) {
+			if (error instanceof WaitSignal) return await this.handleWait(run, stepId, error);
+			else if (error instanceof InvalidStateError) throw error;
+			else return await this.handleFailure(run, stepId, error);
+		} finally {
+			this.activeControllers.delete(run._id);
+		}
+	}
+	async executeWithTimeout(handler, ctx, timeout, runId, abortController) {
+		let heartbeatTimer;
+		let timeoutHandle;
+		if (runId) heartbeatTimer = setInterval(async () => {
+			try {
+				await this.repository.updateOne({ _id: runId }, { lastHeartbeat: /* @__PURE__ */ new Date() }, { bypassTenant: true });
+			} catch {}
+		}, TIMING.HEARTBEAT_INTERVAL_MS);
+		const cleanup = () => {
+			if (heartbeatTimer) clearInterval(heartbeatTimer);
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		};
+		try {
+			if (!timeout) {
+				const result = await handler(ctx);
+				cleanup();
+				return result;
+			}
+			const result = await Promise.race([handler(ctx), new Promise((_, reject) => {
+				timeoutHandle = setTimeout(() => {
+					if (abortController) abortController.abort(/* @__PURE__ */ new Error(`Step timeout after ${timeout}ms`));
+					reject(/* @__PURE__ */ new Error(`Step timeout after ${timeout}ms`));
+				}, timeout);
+			})]);
+			cleanup();
+			return result;
+		} catch (error) {
+			cleanup();
+			if (abortController && !abortController.signal.aborted) abortController.abort(error);
+			throw error;
+		}
+	}
+	/**
+	* Handle a wait signal from a step handler.
+	* Updates step state to waiting and emits events.
+	*/
+	async handleWait(run, stepId, signal) {
+		const signalData = signal.data;
+		const stepState = await this.updateStepState(run, stepId, {
+			status: "waiting",
+			waitingFor: {
+				type: signal.type,
+				reason: signal.reason,
+				resumeAt: signalData?.resumeAt,
+				eventName: signalData?.eventName,
+				data: signal.data
+			}
+		});
+		this.eventBus.emit("step:waiting", {
+			runId: run._id,
+			stepId,
+			data: signal.data
+		});
+		this.eventBus.emit("workflow:waiting", {
+			runId: run._id,
+			data: signal.data
+		});
+		return stepState;
+	}
+	/**
+	* Handle step failure with retry logic.
+	* Implements exponential backoff with jitter for retries.
+	* If all retries exhausted, marks step as failed.
+	*/
+	async handleFailure(run, stepId, error) {
+		const step = this.registry.getStep(stepId);
+		const stepState = run.steps.find((s) => s.stepId === stepId);
+		const maxRetries = step?.retries ?? this.registry.definition.defaults?.retries ?? 3;
+		if (error.retriable !== false && stepState.attempts < maxRetries) {
+			const delayMs = calculateRetryDelay(TIMING.RETRY_BASE_DELAY_MS, stepState.attempts - 1, TIMING.RETRY_MULTIPLIER, TIMING.MAX_RETRY_DELAY_MS, RETRY.JITTER_FACTOR);
+			const retryAfter = new Date(Date.now() + delayMs);
+			const stepIndex = run.steps.findIndex((s) => s.stepId === stepId);
+			if ((await this.repository.updateOne({
+				_id: run._id,
+				...CANCELLED_GUARD
+			}, {
+				$set: {
+					status: "waiting",
+					updatedAt: /* @__PURE__ */ new Date(),
+					[`steps.${stepIndex}.status`]: "pending",
+					[`steps.${stepIndex}.retryAfter`]: retryAfter,
+					[`steps.${stepIndex}.error`]: {
+						message: error.message,
+						retriable: true,
+						stack: error.stack
+					}
+				},
+				$unset: { [`steps.${stepIndex}.waitingFor`]: "" }
+			}, { bypassTenant: true })).modifiedCount > 0) {
+				run.status = "waiting";
+				run.steps[stepIndex].status = "pending";
+				run.steps[stepIndex].retryAfter = retryAfter;
+				run.steps[stepIndex].error = {
+					message: error.message,
+					retriable: true,
+					stack: error.stack
+				};
+				run.steps[stepIndex] = {
+					...run.steps[stepIndex],
+					waitingFor: void 0
+				};
+				this.eventBus.emit("step:retry-scheduled", {
+					runId: run._id,
+					stepId,
+					data: {
+						attempt: stepState.attempts,
+						maxRetries,
+						retryAfter
+					}
+				});
+			} else this.cache.delete(run._id);
+			return run;
+		}
+		const errorWithCode = error;
+		const failedRun = await this.updateStepState(run, stepId, {
+			status: "failed",
+			endedAt: /* @__PURE__ */ new Date(),
+			error: {
+				message: error.message,
+				code: errorWithCode.code,
+				retriable: false,
+				stack: error.stack
+			}
+		});
+		this.eventBus.emit("step:failed", {
+			runId: run._id,
+			stepId,
+			data: { error }
+		});
+		this.eventBus.emit("workflow:failed", {
+			runId: run._id,
+			data: { error }
+		});
+		return failedRun;
+	}
+	/**
+	* Update a step's state and derive new workflow status.
+	* Atomically updates both in-memory and database state.
+	*/
+	async updateStepState(run, stepId, updates) {
+		run = toPlainRun(run);
+		const { index: stepIndex } = this.findStepOrThrow(run, stepId);
+		const newStatus = deriveRunStatus({
+			...run,
+			steps: applyStepUpdates(stepId, run.steps, updates)
+		});
+		const updateOps = buildStepUpdateOps(stepIndex, updates, { includeStatus: newStatus });
+		run.steps = applyStepUpdates(stepId, run.steps, updates);
+		run.updatedAt = /* @__PURE__ */ new Date();
+		run.status = newStatus;
+		if ((await this.repository.updateOne({
+			_id: run._id,
+			...CANCELLED_GUARD
+		}, updateOps, { bypassTenant: true })).modifiedCount === 0) {
+			this.cache.delete(run._id);
+			if ((await this.repository.getById(run._id))?.status === "cancelled") throw new InvalidStateError("update step", "cancelled", [
+				"running",
+				"waiting",
+				"draft"
+			], {
+				runId: run._id,
+				stepId
+			});
+		}
+		return run;
+	}
+	/**
+	* Move workflow to the next step or mark as complete.
+	* If no more steps, marks workflow as done and sets final output.
+	*/
+	async moveToNextStep(run) {
+		const nextStep = this.registry.getNextStep(run.currentStepId);
+		const updates = { updatedAt: /* @__PURE__ */ new Date() };
+		if (nextStep) {
+			run.currentStepId = nextStep.id;
+			run.status = "running";
+			updates.currentStepId = nextStep.id;
+			updates.status = "running";
+		} else {
+			run.output = run.steps.find((s) => s.stepId === run.currentStepId)?.output;
+			run.currentStepId = null;
+			run.status = "done";
+			run.endedAt = /* @__PURE__ */ new Date();
+			updates.output = run.output;
+			updates.currentStepId = null;
+			updates.status = "done";
+			updates.endedAt = run.endedAt;
+			this.eventBus.emit("workflow:completed", {
+				runId: run._id,
+				data: run.output
+			});
+		}
+		run.updatedAt = updates.updatedAt;
+		if ((await this.repository.updateOne({
+			_id: run._id,
+			...CANCELLED_GUARD
+		}, updates, { bypassTenant: true })).modifiedCount === 0) {
+			this.cache.delete(run._id);
+			if ((await this.repository.getById(run._id))?.status === "cancelled") throw new InvalidStateError("move to next step", "cancelled", ["running", "waiting"], { runId: run._id });
+		}
+		return run;
+	}
+	/**
+	* Resume a waiting step with payload.
+	* Marks the step as done and continues to next step.
+	* 
+	* @param run - Workflow run to resume
+	* @param payload - Data to pass as step output
+	* @returns Updated workflow run
+	* @throws {InvalidStateError} If step is not in waiting state
+	*/
+	async resumeStep(run, payload) {
+		const stepId = run.currentStepId;
+		const { step: stepState } = this.findStepOrThrow(run, stepId);
+		if (stepState.status !== "waiting") {
+			const { InvalidStateError } = await import("./errors-BqunvWPz.mjs").then((n) => n.l);
+			throw new InvalidStateError("resume step", stepState.status, ["waiting"], {
+				runId: run._id,
+				stepId
+			});
+		}
+		let updatedRun = await this.updateStepState(run, stepId, {
+			status: "done",
+			endedAt: /* @__PURE__ */ new Date(),
+			output: payload,
+			waitingFor: void 0
+		});
+		this.eventBus.emit("workflow:resumed", {
+			runId: run._id,
+			stepId,
+			data: payload
+		});
+		updatedRun = await this.moveToNextStep(updatedRun);
+		return updatedRun;
+	}
+};
+
+//#endregion
+//#region src/execution/smart-scheduler.ts
+/**
+* Intelligent Workflow Scheduler
+*
+* Features:
+* - Lazy start: Only polls when workflows exist
+* - Auto-stop: Stops when no workflows
+* - Adaptive polling: Adjusts interval based on load
+* - Circuit breaker: Handles failures gracefully
+* - Metrics: Tracks performance for monitoring
+*
+* Philosophy: Be smart, not wasteful. Iron Man, not Homer Simpson.
+*/
+var SchedulerMetrics = class {
+	stats = {
+		totalPolls: 0,
+		successfulPolls: 0,
+		failedPolls: 0,
+		avgPollDuration: 0,
+		activeWorkflows: 0,
+		resumedWorkflows: 0,
+		missedResumes: 0,
+		isPolling: false,
+		pollInterval: 0,
+		uptime: 0
+	};
+	pollDurations = [];
+	startTime;
+	maxDurationsToTrack = 100;
+	start(pollInterval) {
+		this.startTime = /* @__PURE__ */ new Date();
+		this.stats.isPolling = true;
+		this.stats.pollInterval = pollInterval;
+	}
+	stop() {
+		this.stats.isPolling = false;
+	}
+	recordPoll(duration, success, workflowsFound) {
+		this.stats.totalPolls++;
+		this.stats.lastPollAt = /* @__PURE__ */ new Date();
+		if (success) this.stats.successfulPolls++;
+		else this.stats.failedPolls++;
+		this.pollDurations.push(duration);
+		if (this.pollDurations.length > this.maxDurationsToTrack) this.pollDurations.shift();
+		this.stats.avgPollDuration = this.pollDurations.reduce((sum, d) => sum + d, 0) / this.pollDurations.length;
+		this.stats.activeWorkflows = workflowsFound;
+	}
+	recordResume(success) {
+		if (success) this.stats.resumedWorkflows++;
+		else this.stats.missedResumes++;
+	}
+	getStats() {
+		if (this.startTime) this.stats.uptime = Date.now() - this.startTime.getTime();
+		return { ...this.stats };
+	}
+	isHealthy() {
+		const stats = this.getStats();
+		if (stats.isPolling && !stats.lastPollAt) return false;
+		if (stats.lastPollAt) {
+			if (Date.now() - stats.lastPollAt.getTime() > stats.pollInterval * 2) return false;
+		}
+		if (stats.totalPolls > 10) {
+			if (stats.successfulPolls / stats.totalPolls < .9) return false;
+		}
+		if (stats.missedResumes > 0) return false;
+		return true;
+	}
+};
+const MAX_SETTIMEOUT_DELAY = 2147483647;
+const DEFAULT_SCHEDULER_CONFIG = {
+	basePollInterval: SCHEDULER.BASE_POLL_INTERVAL_MS,
+	maxPollInterval: SCHEDULER.MAX_POLL_INTERVAL_MS,
+	minPollInterval: SCHEDULER.MIN_POLL_INTERVAL_MS,
+	maxWorkflowsPerPoll: LIMITS.SCHEDULER_BATCH_SIZE,
+	idleTimeout: SCHEDULER.IDLE_TIMEOUT_MS,
+	adaptivePolling: true,
+	maxConsecutiveFailures: SCHEDULER.MAX_CONSECUTIVE_FAILURES,
+	staleCheckInterval: SCHEDULER.STALE_CHECK_INTERVAL_MS,
+	staleThreshold: TIMING.STALE_WORKFLOW_THRESHOLD_MS
+};
+var SmartScheduler = class {
+	timers = /* @__PURE__ */ new Map();
+	pollInterval;
+	idleTimer;
+	staleCheckTimer;
+	isPolling = false;
+	isStaleCheckActive = false;
+	currentInterval;
+	consecutiveFailures = 0;
+	lastWorkflowCount = 0;
+	metrics;
+	staleRecoveryCallback;
+	retryCallback;
+	constructor(repository, resumeCallback, config = DEFAULT_SCHEDULER_CONFIG, eventBus) {
+		this.repository = repository;
+		this.resumeCallback = resumeCallback;
+		this.config = config;
+		this.eventBus = eventBus;
+		this.currentInterval = config.basePollInterval;
+		this.metrics = new SchedulerMetrics();
+	}
+	emitError(context, error, runId) {
+		if (this.eventBus) this.eventBus.emit("scheduler:error", {
+			runId,
+			error: error instanceof Error ? error : new Error(String(error)),
+			context
+		});
+	}
+	/**
+	* Set callback for recovering stale 'running' workflows
+	* Separate from resume because stale recovery requires different atomic claim logic
+	*/
+	setStaleRecoveryCallback(callback) {
+		this.staleRecoveryCallback = callback;
+	}
+	/**
+	* Set callback for retrying failed steps
+	* Separate from resume because retries need execute() (re-run step), not resumeStep() (mark done with payload)
+	*/
+	setRetryCallback(callback) {
+		this.retryCallback = callback;
+	}
+	/**
+	* Intelligent start: Only starts if workflows exist
+	* Checks for both waiting workflows AND running workflows that might need stale recovery
+	*/
+	async startIfNeeded() {
+		this.startStaleCheck();
+		if (this.isPolling) return true;
+		if (await this.hasActiveWorkflows()) {
+			this.startPolling();
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Force start polling immediately
+	*/
+	start() {
+		if (!this.isPolling) this.startPolling();
+		this.startStaleCheck();
+	}
+	/**
+	* Stop polling
+	*/
+	stop() {
+		this.stopPolling();
+		this.stopStaleCheck();
+	}
+	/**
+	* Schedule a workflow to resume at specific time
+	* Handles both short delays (setTimeout) and long delays (MongoDB polling)
+	*/
+	scheduleResume(runId, resumeAt) {
+		const delay = resumeAt.getTime() - Date.now();
+		if (!this.isPolling) this.startPolling();
+		this.resetIdleTimer();
+		if (delay <= 0) {
+			setImmediate(() => this.resumeWorkflow(runId));
+			return;
+		}
+		if (delay >= MAX_SETTIMEOUT_DELAY) {
+			logger.info(`Long delay scheduled - using MongoDB polling`, {
+				runId,
+				delayDays: Math.round(delay / 864e5)
+			});
+			return;
+		}
+		const timer = setTimeout(() => {
+			this.timers.delete(runId);
+			this.resumeWorkflow(runId);
+		}, delay);
+		timer.unref();
+		this.timers.set(runId, timer);
+	}
+	/**
+	* Cancel scheduled resume
+	*/
+	cancelSchedule(runId) {
+		const timer = this.timers.get(runId);
+		if (timer) {
+			clearTimeout(timer);
+			this.timers.delete(runId);
+		}
+	}
+	/**
+	* Get scheduler statistics
+	*/
+	getStats() {
+		return this.metrics.getStats();
+	}
+	/**
+	* Health check
+	*/
+	isHealthy() {
+		return this.metrics.isHealthy();
+	}
+	/**
+	* Get current polling interval
+	*/
+	getCurrentInterval() {
+		return this.currentInterval;
+	}
+	startPolling() {
+		if (this.isPolling) return;
+		this.isPolling = true;
+		this.metrics.start(this.currentInterval);
+		this.schedulePoll();
+		this.resetIdleTimer();
+	}
+	stopPolling() {
+		if (!this.isPolling) return;
+		this.isPolling = false;
+		this.metrics.stop();
+		if (this.pollInterval) {
+			clearTimeout(this.pollInterval);
+			this.pollInterval = void 0;
+		}
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = void 0;
+		}
+		this.timers.forEach((timer) => clearTimeout(timer));
+		this.timers.clear();
+	}
+	/**
+	* Start background stale workflow check
+	* Runs independently of main polling loop to ensure crashed workflows are always recovered
+	*/
+	startStaleCheck() {
+		if (this.isStaleCheckActive) return;
+		this.isStaleCheckActive = true;
+		const scheduleNext = () => {
+			if (!this.isStaleCheckActive) return;
+			this.staleCheckTimer = setTimeout(async () => {
+				await this.checkForStaleWorkflows();
+				scheduleNext();
+			}, this.config.staleCheckInterval);
+			this.staleCheckTimer.unref();
+		};
+		scheduleNext();
+	}
+	/**
+	* Stop background stale workflow check
+	* Guarantees no further checks will be scheduled, even if one is currently running
+	*/
+	stopStaleCheck() {
+		this.isStaleCheckActive = false;
+		if (this.staleCheckTimer) {
+			clearTimeout(this.staleCheckTimer);
+			this.staleCheckTimer = void 0;
+		}
+	}
+	/**
+	* Background check for stale workflows (runs even when scheduler is idle)
+	* If stale workflows found, start the main polling loop
+	*/
+	async checkForStaleWorkflows() {
+		try {
+			const staleWorkflows = await this.repository.getStaleRunningWorkflows(this.config.staleThreshold, 1);
+			if (staleWorkflows.length > 0 && !this.isPolling) {
+				logger.info(`Background check found stale workflows - starting polling`, { count: staleWorkflows.length });
+				this.startPolling();
+			}
+		} catch (error) {
+			this.emitError("stale-check", error);
+		}
+	}
+	schedulePoll() {
+		if (!this.isPolling) return;
+		this.pollInterval = setTimeout(async () => {
+			await this.poll();
+			this.schedulePoll();
+		}, this.currentInterval);
+		this.pollInterval.unref();
+	}
+	async poll() {
+		const startTime = Date.now();
+		try {
+			const now = /* @__PURE__ */ new Date();
+			const limit = this.config.maxWorkflowsPerPoll;
+			const waiting = await this.repository.getReadyToResume(now, limit);
+			const retrying = await this.repository.getReadyForRetry(now, limit);
+			let resumedCount = 0;
+			for (const run of waiting) {
+				if (this.timers.has(run._id)) continue;
+				await this.resumeWorkflow(run._id);
+				resumedCount++;
+			}
+			for (const run of retrying) if (this.retryCallback) try {
+				await this.retryCallback(run._id);
+				resumedCount++;
+			} catch (err) {
+				this.emitError("retry-workflow", err, run._id);
+			}
+			else logger.warn(`Retry workflow detected but no retry callback set`, { runId: run._id });
+			const scheduled = (await this.repository.getScheduledWorkflowsReadyToExecute(now, { limit })).docs || [];
+			for (const run of scheduled) if (this.retryCallback) try {
+				if ((await this.repository.updateOne({
+					_id: run._id,
+					status: "draft",
+					"scheduling.executionTime": { $lte: now },
+					paused: { $ne: true }
+				}, {
+					status: "running",
+					startedAt: now,
+					updatedAt: now,
+					lastHeartbeat: now
+				}, { bypassTenant: true })).modifiedCount === 0) continue;
+				await this.retryCallback(run._id);
+				resumedCount++;
+			} catch (err) {
+				this.emitError("execute-scheduled", err, run._id);
+			}
+			else logger.warn(`Scheduled workflow detected but no execution callback set`, { runId: run._id });
+			const stale = await this.repository.getStaleRunningWorkflows(this.config.staleThreshold, limit);
+			for (const run of stale) if (this.staleRecoveryCallback) try {
+				await this.staleRecoveryCallback(run._id, this.config.staleThreshold);
+				resumedCount++;
+			} catch (err) {
+				this.emitError("recover-stale", err, run._id);
+			}
+			else logger.warn(`Stale workflow detected but no recovery callback set`, { runId: run._id });
+			const duration = Date.now() - startTime;
+			const totalWorkflows = waiting.length + retrying.length + scheduled.length + stale.length;
+			this.metrics.recordPoll(duration, true, totalWorkflows);
+			this.consecutiveFailures = 0;
+			this.lastWorkflowCount = totalWorkflows;
+			if (this.config.adaptivePolling) this.adjustInterval(totalWorkflows);
+			if (totalWorkflows === 0 && resumedCount === 0) {
+				if (!this.idleTimer) this.resetIdleTimer();
+			} else if (this.idleTimer) {
+				clearTimeout(this.idleTimer);
+				this.idleTimer = void 0;
+			}
+		} catch (error) {
+			const duration = Date.now() - startTime;
+			this.metrics.recordPoll(duration, false, 0);
+			this.consecutiveFailures++;
+			this.emitError("poll", error);
+			if (this.consecutiveFailures >= this.config.maxConsecutiveFailures) {
+				if (this.eventBus) this.eventBus.emit("scheduler:circuit-open", {
+					error: /* @__PURE__ */ new Error(`Circuit breaker triggered after ${this.consecutiveFailures} consecutive failures`),
+					context: "circuit-breaker"
+				});
+				this.stopPolling();
+			}
+		}
+	}
+	async resumeWorkflow(runId) {
+		try {
+			await this.resumeCallback(runId);
+			this.metrics.recordResume(true);
+		} catch (error) {
+			this.emitError("resume-workflow", error, runId);
+			this.metrics.recordResume(false);
+		}
+	}
+	async hasWaitingWorkflows() {
+		try {
+			return (await this.repository.getWaitingRuns()).length > 0;
+		} catch (error) {
+			this.emitError("check-waiting", error);
+			return false;
+		}
+	}
+	/**
+	* Check if there are any active workflows that need scheduler attention
+	* Checks for waiting workflows (resume/retry), scheduled workflows, OR stale running workflows
+	* Note: Healthy running workflows don't need the scheduler
+	*/
+	async hasActiveWorkflows() {
+		try {
+			if ((await this.repository.getWaitingRuns()).length > 0) return true;
+			const scheduled = await this.repository.getScheduledWorkflowsReadyToExecute(/* @__PURE__ */ new Date(), { limit: 1 });
+			if (scheduled.docs && scheduled.docs.length > 0) return true;
+			if ((await this.repository.getStaleRunningWorkflows(this.config.staleThreshold, 1)).length > 0) return true;
+			return false;
+		} catch (error) {
+			this.emitError("check-active", error);
+			return false;
+		}
+	}
+	adjustInterval(workflowCount) {
+		const { minPollInterval, maxPollInterval, basePollInterval } = this.config;
+		if (workflowCount === 0) this.currentInterval = maxPollInterval;
+		else if (workflowCount >= 100) this.currentInterval = minPollInterval;
+		else if (workflowCount >= 10) this.currentInterval = basePollInterval / 2;
+		else this.currentInterval = basePollInterval;
+		this.metrics.start(this.currentInterval);
+	}
+	resetIdleTimer() {
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = setTimeout(async () => {
+			if (!await this.hasWaitingWorkflows() && this.timers.size === 0) {
+				logger.info("No workflows for idle timeout - stopping polling");
+				this.stopPolling();
+			}
+		}, this.config.idleTimeout);
+		this.idleTimer.unref();
+	}
+};
+
+//#endregion
+//#region src/utils/validation.ts
+/**
+* Validate workflow/step ID format
+* Must be alphanumeric with hyphens/underscores only
+*/
+function validateId(id, type = "workflow") {
+	if (!id || typeof id !== "string") throw new Error(`${type} ID must be a non-empty string`);
+	if (!/^[a-zA-Z0-9_-]+$/.test(id)) throw new Error(`${type} ID "${id}" contains invalid characters. Only alphanumeric characters, hyphens, and underscores are allowed.`);
+	if (id.length > LIMITS.MAX_ID_LENGTH) throw new Error(`${type} ID "${id}" is too long (max ${LIMITS.MAX_ID_LENGTH} characters)`);
+}
+/**
+* Validate retry configuration
+*/
+function validateRetryConfig(retries, timeout) {
+	if (retries !== void 0 && (!Number.isInteger(retries) || retries < 0)) throw new Error(`retries must be a non-negative integer, got: ${retries}`);
+	if (timeout !== void 0 && (!Number.isInteger(timeout) || timeout <= 0)) throw new Error(`timeout must be a positive integer (milliseconds), got: ${timeout}`);
+}
+/**
+* Validate workflow definition and handlers.
+* Keeps it simple - validates IDs, checks for duplicates, ensures handlers exist.
+*/
+function validateWorkflowDefinition(definition, handlers) {
+	if (!definition.id) throw new Error("Workflow ID is required");
+	if (!definition.name) throw new Error("Workflow name is required");
+	if (!definition.version) throw new Error("Workflow version is required");
+	if (definition.steps.length === 0) throw new Error("Workflow must have at least one step");
+	const stepIds = /* @__PURE__ */ new Set();
+	for (const step of definition.steps) {
+		if (stepIds.has(step.id)) throw new Error(`Duplicate step ID "${step.id}"`);
+		stepIds.add(step.id);
+		if (!handlers[step.id]) throw new Error(`Handler for step "${step.id}" not found`);
+	}
+}
+
+//#endregion
+//#region src/workflow/registry.ts
+/**
+* Registry for workflow definition and handlers.
+* Provides validation and utility methods for workflow execution.
+*/
+var WorkflowRegistry = class {
+	constructor(definition, handlers) {
+		this.definition = definition;
+		this.handlers = handlers;
+		validateWorkflowDefinition(definition, handlers);
+	}
+	/**
+	* Get step definition by ID
+	*/
+	getStep(stepId) {
+		return this.definition.steps.find((s) => s.id === stepId);
+	}
+	/**
+	* Get step handler by ID
+	*/
+	getHandler(stepId) {
+		return this.handlers[stepId];
+	}
+	/**
+	* Get the next step after the given step ID
+	*/
+	getNextStep(currentStepId) {
+		const currentIndex = this.definition.steps.findIndex((s) => s.id === currentStepId);
+		if (currentIndex === -1 || currentIndex === this.definition.steps.length - 1) return;
+		return this.definition.steps[currentIndex + 1];
+	}
+	/**
+	* Create a new workflow run from input
+	*/
+	createRun(input, meta) {
+		const now = /* @__PURE__ */ new Date();
+		const runId = randomUUID();
+		const steps = this.definition.steps.map((step) => ({
+			stepId: step.id,
+			status: "pending",
+			attempts: 0
+		}));
+		return {
+			_id: runId,
+			workflowId: this.definition.id,
+			status: "draft",
+			steps,
+			currentStepId: this.definition.steps[0]?.id || null,
+			context: this.definition.createContext(input),
+			input,
+			createdAt: now,
+			updatedAt: now,
+			meta
+		};
+	}
+	/**
+	* Rewind a workflow run to a previous step
+	*/
+	rewindRun(run, targetStepId) {
+		const targetIndex = this.definition.steps.findIndex((s) => s.id === targetStepId);
+		if (targetIndex === -1) throw new Error(`Step "${targetStepId}" not found in workflow`);
+		run.steps = run.steps.map((stepState, index) => {
+			if (index >= targetIndex) return {
+				stepId: stepState.stepId,
+				status: "pending",
+				attempts: 0
+			};
+			return stepState;
+		});
+		run.currentStepId = targetStepId;
+		run.status = "running";
+		run.updatedAt = /* @__PURE__ */ new Date();
+		run.output = void 0;
+		run.endedAt = void 0;
+		run.error = void 0;
+		return run;
+	}
+};
+
+//#endregion
+//#region src/execution/engine.ts
+/**
+* Registry mapping runId to the engine managing that run.
+* Enables resumeHook() to find the correct engine for resuming.
+*/
+var HookRegistry = class {
+	engines = /* @__PURE__ */ new Map();
+	cleanupInterval = null;
+	register(runId, engine) {
+		this.engines.set(runId, new WeakRef(engine));
+		if (!this.cleanupInterval) {
+			this.cleanupInterval = setInterval(() => this.cleanup(), TIMING.HOOK_CLEANUP_INTERVAL_MS);
+			this.cleanupInterval.unref();
+		}
+	}
+	unregister(runId) {
+		this.engines.delete(runId);
+	}
+	getEngine(runId) {
+		const ref = this.engines.get(runId);
+		if (!ref) return void 0;
+		const engine = ref.deref();
+		if (!engine) {
+			this.engines.delete(runId);
+			return;
+		}
+		return engine;
+	}
+	cleanup() {
+		for (const [runId, ref] of this.engines) if (!ref.deref()) this.engines.delete(runId);
+	}
+	shutdown() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = null;
+		}
+		this.engines.clear();
+	}
+};
+/** Global hook registry instance */
+const hookRegistry = new HookRegistry();
+/**
+* Clean up all event listeners for a specific workflow
+*/
+function cleanupEventListeners(runId, listeners, eventBus) {
+	const prefix = `${runId}:`;
+	const keysToRemove = Array.from(listeners.keys()).filter((key) => key.startsWith(prefix));
+	for (const key of keysToRemove) {
+		const entry = listeners.get(key);
+		if (entry) {
+			eventBus.off(entry.eventName, entry.listener);
+			listeners.delete(key);
+		}
+	}
+}
+/**
+* Handle short delay (< 5s) inline or schedule for later
+*/
+async function handleShortDelayOrSchedule(runId, targetTime, scheduleLongDelay, repository, cache) {
+	const delayMs = targetTime.getTime() - Date.now();
+	if (delayMs > 0 && delayMs <= TIMING.SHORT_DELAY_THRESHOLD_MS) {
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+		const remaining = targetTime.getTime() - Date.now();
+		if (remaining > 0) await new Promise((resolve) => setTimeout(resolve, remaining + 10));
+	}
+	if (delayMs <= TIMING.SHORT_DELAY_THRESHOLD_MS) {
+		if ((await repository.updateOne({
+			_id: runId,
+			status: "waiting",
+			paused: { $ne: true }
+		}, {
+			status: "running",
+			updatedAt: /* @__PURE__ */ new Date(),
+			lastHeartbeat: /* @__PURE__ */ new Date()
+		}, { bypassTenant: true })).modifiedCount > 0) {
+			cache.delete(runId);
+			return true;
+		}
+		return false;
+	}
+	scheduleLongDelay();
+	return false;
+}
+/**
+* Core workflow execution engine.
+* 
+* Manages workflow lifecycle: start, execute, pause, resume, cancel.
+* Handles waiting states, retries, and crash recovery automatically.
+* 
+* @typeParam TContext - Type of workflow context
+* 
+* @example
+* ```typescript
+* const engine = new WorkflowEngine(definition, handlers, container);
+* const run = await engine.start({ orderId: '123' });
+* ```
+*/
+var WorkflowEngine = class {
+	executor;
+	scheduler;
+	registry;
+	options;
+	eventListeners;
+	/** Exposed for hook registry and external access */
+	container;
+	constructor(definition, handlers, container, options = {}) {
+		this.handlers = handlers;
+		this.container = container;
+		this.registry = new WorkflowRegistry(definition, handlers);
+		this.executor = new StepExecutor(this.registry, container.repository, container.eventBus, container.cache);
+		this.eventListeners = /* @__PURE__ */ new Map();
+		const schedulerConfig = {
+			...DEFAULT_SCHEDULER_CONFIG,
+			...options.scheduler
+		};
+		this.scheduler = new SmartScheduler(container.repository, async (runId) => {
+			await this.resume(runId);
+		}, schedulerConfig, container.eventBus);
+		this.scheduler.setStaleRecoveryCallback(async (runId, thresholdMs) => {
+			return this.recoverStale(runId, thresholdMs);
+		});
+		this.scheduler.setRetryCallback(async (runId) => {
+			return this.executeRetry(runId);
+		});
+		this.scheduler.startIfNeeded().catch((err) => {
+			this.container.eventBus.emit("engine:error", {
+				runId: void 0,
+				error: err,
+				context: "scheduler-start"
+			});
+		});
+		this.options = {
+			autoExecute: true,
+			...options
+		};
+	}
+	/** Get the workflow definition */
+	get definition() {
+		return this.registry.definition;
+	}
+	/**
+	* Start a new workflow run.
+	* 
+	* @param input - Input data for the workflow
+	* @param meta - Optional metadata (userId, tags, etc.)
+	* @returns The created workflow run
+	*/
+	async start(input, meta) {
+		const run = this.registry.createRun(input, meta);
+		run.status = "running";
+		run.startedAt = /* @__PURE__ */ new Date();
+		await this.container.repository.create(run);
+		this.container.cache.set(run);
+		hookRegistry.register(run._id, this);
+		this.container.eventBus.emit("workflow:started", { runId: run._id });
+		if (this.options.autoExecute) setImmediate(() => this.execute(run._id).catch((err) => {
+			this.container.eventBus.emit("engine:error", {
+				runId: run._id,
+				error: err,
+				context: "auto-execution"
+			});
+		}));
+		return run;
+	}
+	/**
+	* Get a workflow run by ID.
+	* Returns from cache if available, otherwise fetches from database.
+	* 
+	* @param runId - Workflow run ID
+	* @returns The workflow run or null if not found
+	*/
+	async get(runId) {
+		const cached = this.container.cache.get(runId);
+		if (cached) return cached;
+		return await this.container.repository.getById(runId);
+	}
+	/**
+	* Execute a workflow run to completion.
+	* 
+	* Runs steps sequentially until:
+	* - All steps complete (status: 'done')
+	* - A step fails after retries (status: 'failed')
+	* - A step waits for external input (status: 'waiting')
+	* - The workflow is cancelled (status: 'cancelled')
+	* 
+	* @param runId - Workflow run ID to execute
+	* @returns The updated workflow run
+	*/
+	async execute(runId) {
+		let run = await this.getOrThrow(runId);
+		try {
+			while (this.shouldContinueExecution(run)) {
+				const { run: updatedRun, shouldBreak } = await this.executeNextStep(run);
+				run = updatedRun;
+				if (shouldBreak) break;
+				if (run.status === "waiting") {
+					if (!await this.handleWaitingState(runId, run)) break;
+					run = await this.get(runId);
+				}
+				if (isTerminalState(run.status)) {
+					cleanupEventListeners(runId, this.eventListeners, this.container.eventBus);
+					break;
+				}
+			}
+		} catch (error) {
+			if (error instanceof InvalidStateError) {
+				const cancelled = await this.get(runId);
+				if (cancelled) run = cancelled;
+			} else throw error;
+		}
+		if (isTerminalState(run.status)) {
+			cleanupEventListeners(runId, this.eventListeners, this.container.eventBus);
+			hookRegistry.unregister(runId);
+		}
+		return run;
+	}
+	async getOrThrow(runId) {
+		const run = await this.get(runId);
+		if (!run) throw new WorkflowNotFoundError(runId);
+		return run;
+	}
+	shouldContinueExecution(run) {
+		return run.status === "running" && run.currentStepId !== null;
+	}
+	async executeNextStep(run) {
+		const prevStepId = run.currentStepId;
+		const prevStepStatus = run.steps.find((s) => s.stepId === prevStepId)?.status;
+		const updatedRun = await this.executor.executeStep(run);
+		this.container.cache.set(updatedRun);
+		return {
+			run: updatedRun,
+			shouldBreak: this.checkNoProgress(updatedRun, prevStepId, prevStepStatus)
+		};
+	}
+	checkNoProgress(run, prevStepId, prevStepStatus) {
+		const currentStep = run.steps.find((s) => s.stepId === run.currentStepId);
+		const isRetryPending = currentStep?.status === "pending" && currentStep?.retryAfter;
+		return run.currentStepId === prevStepId && currentStep?.status === prevStepStatus && !isRetryPending;
+	}
+	/**
+	* Handle different waiting states (event, retry, timer, human input)
+	* @returns true if execution should continue, false to break
+	*/
+	async handleWaitingState(runId, run) {
+		const stepState = this.findCurrentStep(run);
+		if (!stepState && run.currentStepId) {
+			await this.failCorruption(runId, run);
+			cleanupEventListeners(runId, this.eventListeners, this.container.eventBus);
+			return false;
+		}
+		if (!stepState) return false;
+		if (stepState.waitingFor?.type === "event" && stepState.waitingFor.eventName) {
+			this.handleEventWait(runId, stepState.waitingFor.eventName);
+			return false;
+		}
+		if (stepState.status === "pending" && stepState.retryAfter) return this.handleRetryWait(runId, stepState.retryAfter);
+		if (stepState.waitingFor?.type === "timer" && stepState.waitingFor.resumeAt) {
+			if (await this.handleTimerWait(runId, stepState.waitingFor.resumeAt)) {
+				const refreshedRun = await this.getOrThrow(runId);
+				const updatedRun = await this.executor.resumeStep(refreshedRun, void 0);
+				this.container.cache.set(updatedRun);
+				return true;
+			}
+			return false;
+		}
+		return false;
+	}
+	findCurrentStep(run) {
+		return run.steps.find((s) => s.stepId === run.currentStepId);
+	}
+	/**
+	* Handle data corruption scenario (missing step state)
+	*/
+	async failCorruption(runId, run) {
+		const errorMsg = `Data corruption: currentStepId '${run.currentStepId}' not found in steps`;
+		this.container.eventBus.emit("engine:error", {
+			runId,
+			error: new Error(errorMsg),
+			context: "data-corruption"
+		});
+		const now = /* @__PURE__ */ new Date();
+		const errorPayload = {
+			message: errorMsg,
+			code: "DATA_CORRUPTION"
+		};
+		await this.container.repository.updateOne({ _id: runId }, {
+			status: "failed",
+			updatedAt: now,
+			endedAt: now,
+			error: errorPayload
+		}, { bypassTenant: true });
+		run.status = "failed";
+		run.updatedAt = now;
+		run.endedAt = now;
+		run.error = errorPayload;
+		this.container.eventBus.emit("workflow:failed", {
+			runId,
+			data: { error: errorPayload }
+		});
+		return run;
+	}
+	/**
+	* Register event listener for event-based waits
+	* IMPORTANT: Paused workflows will NOT be resumed by events until explicitly resumed by user
+	*/
+	handleEventWait(runId, eventName) {
+		const listenerKey = `${runId}:${eventName}`;
+		if (this.eventListeners.has(listenerKey)) return;
+		const listener = async (...args) => {
+			const payload = args[0];
+			try {
+				if (payload && !payload.runId && !payload.broadcast) logger.warn(`Event '${eventName}' emitted without runId or broadcast flag. This will resume ALL workflows waiting on '${eventName}'.`, {
+					runId,
+					eventName
+				});
+				if (!payload || payload.runId === runId || payload.broadcast === true) {
+					if ((await this.get(runId))?.paused) return;
+					const entry = this.eventListeners.get(listenerKey);
+					if (entry) {
+						this.container.eventBus.off(entry.eventName, entry.listener);
+						this.eventListeners.delete(listenerKey);
+					}
+					await this.resume(runId, payload?.data);
+				}
+			} catch (err) {
+				this.container.eventBus.emit("engine:error", {
+					runId,
+					error: err,
+					context: "event-handler"
+				});
+			}
+		};
+		this.container.eventBus.on(eventName, listener);
+		this.eventListeners.set(listenerKey, {
+			listener,
+			eventName
+		});
+	}
+	/**
+	* Handle retry backoff wait with inline execution for short delays
+	* @returns true if workflow should continue execution immediately
+	*/
+	async handleRetryWait(runId, retryAfter) {
+		return handleShortDelayOrSchedule(runId, retryAfter, () => this.scheduler.start(), this.container.repository, this.container.cache);
+	}
+	/**
+	* Handle timer-based wait (sleep) with inline execution for short delays
+	* @returns true if workflow should continue execution immediately
+	*/
+	async handleTimerWait(runId, resumeAt) {
+		return handleShortDelayOrSchedule(runId, resumeAt, () => {
+			this.scheduler.scheduleResume(runId, resumeAt);
+		}, this.container.repository, this.container.cache);
+	}
+	/**
+	* Resume a paused or waiting workflow.
+	* 
+	* For waiting workflows:
+	* - If waiting for human input: payload is passed as the step output
+	* - If waiting for timer/retry: continues execution from current step
+	* 
+	* @param runId - Workflow run ID to resume
+	* @param payload - Data to pass to the waiting step (becomes step output)
+	* @returns The updated workflow run
+	* @throws {InvalidStateError} If workflow is not in waiting/running state
+	*/
+	async resume(runId, payload) {
+		const run = await this.getOrThrow(runId);
+		if (run.paused) {
+			run.paused = false;
+			run.updatedAt = /* @__PURE__ */ new Date();
+			await this.container.repository.update(runId, run, { bypassTenant: true });
+			this.container.cache.set(run);
+		}
+		if (run.status === "waiting") return this.resumeWaitingWorkflow(run, payload);
+		if (run.status === "running") return this.execute(runId);
+		throw new InvalidStateError("resume workflow", run.status, ["waiting", "running"], { runId });
+	}
+	async resumeWaitingWorkflow(run, payload) {
+		const runId = run._id;
+		const currentStepId = run.currentStepId;
+		if (currentStepId) {
+			if (run.steps.find((s) => s.stepId === currentStepId)?.status === "waiting") {
+				cleanupEventListeners(runId, this.eventListeners, this.container.eventBus);
+				const updatedRun = await this.executor.resumeStep(run, payload);
+				this.container.cache.set(updatedRun);
+				return this.execute(runId);
+			}
+		}
+		run.status = "running";
+		run.lastHeartbeat = /* @__PURE__ */ new Date();
+		await this.container.repository.update(runId, run, { bypassTenant: true });
+		this.container.cache.set(run);
+		return this.execute(runId);
+	}
+	/**
+	* Recover a stale 'running' workflow (crashed mid-execution)
+	* Uses atomic claim to prevent multiple servers from recovering the same workflow
+	*/
+	async recoverStale(runId, staleThresholdMs) {
+		const staleTime = new Date(Date.now() - staleThresholdMs);
+		if ((await this.container.repository.updateOne({
+			_id: runId,
+			status: "running",
+			$or: [{ lastHeartbeat: { $lt: staleTime } }, { lastHeartbeat: { $exists: false } }]
+		}, {
+			lastHeartbeat: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		}, { bypassTenant: true })).modifiedCount === 0) return null;
+		this.container.cache.delete(runId);
+		this.container.eventBus.emit("workflow:recovered", { runId });
+		return this.execute(runId);
+	}
+	/**
+	* Execute a retry for a workflow that failed and is waiting for backoff timer
+	* Uses atomic claim to prevent multiple servers from retrying the same workflow
+	*/
+	async executeRetry(runId) {
+		const now = /* @__PURE__ */ new Date();
+		let claimResult = await this.container.repository.updateOne({
+			_id: runId,
+			status: "waiting",
+			paused: { $ne: true },
+			steps: { $elemMatch: {
+				status: "pending",
+				retryAfter: { $lte: now }
+			} }
+		}, { $set: {
+			status: "running",
+			updatedAt: now,
+			lastHeartbeat: now
+		} }, { bypassTenant: true });
+		if (claimResult.modifiedCount === 0) claimResult = await this.container.repository.updateOne({
+			_id: runId,
+			status: "draft",
+			"scheduling.executionTime": { $lte: now },
+			paused: { $ne: true }
+		}, { $set: {
+			status: "running",
+			updatedAt: now,
+			lastHeartbeat: now,
+			startedAt: now
+		} }, { bypassTenant: true });
+		if (claimResult.modifiedCount === 0) return null;
+		this.container.cache.delete(runId);
+		hookRegistry.register(runId, this);
+		this.container.eventBus.emit("workflow:retry", { runId });
+		return this.execute(runId);
+	}
+	/**
+	* Rewind a workflow to a previous step.
+	* Resets all steps from target step onwards to pending state.
+	* 
+	* @param runId - Workflow run ID
+	* @param stepId - Step ID to rewind to
+	* @returns The rewound workflow run
+	*/
+	async rewindTo(runId, stepId) {
+		const run = await this.getOrThrow(runId);
+		const rewoundRun = this.registry.rewindRun(run, stepId);
+		await this.container.repository.update(runId, rewoundRun, { bypassTenant: true });
+		this.container.cache.set(rewoundRun);
+		return rewoundRun;
+	}
+	/**
+	* Cancel a running workflow.
+	* Cleans up all resources and marks workflow as cancelled.
+	* 
+	* @param runId - Workflow run ID to cancel
+	* @returns The cancelled workflow run
+	*/
+	async cancel(runId) {
+		const run = await this.getOrThrow(runId);
+		this.executor.abortWorkflow(runId);
+		const cancelledRun = {
+			...run,
+			status: "cancelled",
+			endedAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		await this.container.repository.update(runId, cancelledRun, { bypassTenant: true });
+		this.scheduler.cancelSchedule(runId);
+		cleanupEventListeners(runId, this.eventListeners, this.container.eventBus);
+		hookRegistry.unregister(runId);
+		this.container.cache.delete(runId);
+		this.container.eventBus.emit("workflow:cancelled", { runId });
+		return cancelledRun;
+	}
+	/**
+	* Pause a workflow run.
+	* 
+	* Sets the `paused` flag to prevent the scheduler from processing this workflow.
+	* Paused workflows can be resumed later with `resume()`.
+	* 
+	* @param runId - Workflow run ID to pause
+	* @returns The paused workflow run
+	*/
+	async pause(runId) {
+		const run = await this.getOrThrow(runId);
+		if (isTerminalState(run.status)) return run;
+		if (run.paused) return run;
+		const pausedRun = {
+			...run,
+			paused: true,
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		await this.container.repository.update(runId, pausedRun, { bypassTenant: true });
+		this.scheduler.cancelSchedule(runId);
+		this.container.cache.set(pausedRun);
+		return pausedRun;
+	}
+	/**
+	* Configure engine options (scheduler settings, etc.)
+	*/
+	configure(options) {
+		if (options.scheduler) {
+			const currentConfig = {
+				...DEFAULT_SCHEDULER_CONFIG,
+				...this.options.scheduler,
+				...options.scheduler
+			};
+			this.scheduler.stop();
+			this.scheduler = new SmartScheduler(this.container.repository, async (runId) => {
+				await this.resume(runId);
+			}, currentConfig, this.container.eventBus);
+			this.scheduler.setStaleRecoveryCallback(async (runId, thresholdMs) => {
+				return this.recoverStale(runId, thresholdMs);
+			});
+			this.scheduler.setRetryCallback(async (runId) => {
+				return this.executeRetry(runId);
+			});
+			this.options.scheduler = currentConfig;
+		}
+	}
+	shutdown() {
+		this.scheduler.stop();
+		for (const [, entry] of this.eventListeners.entries()) this.container.eventBus.off(entry.eventName, entry.listener);
+		this.eventListeners.clear();
+	}
+	/**
+	* Get scheduler statistics for monitoring
+	*/
+	getSchedulerStats() {
+		return this.scheduler.getStats();
+	}
+	/**
+	* Check if scheduler is healthy
+	*/
+	isSchedulerHealthy() {
+		return this.scheduler.isHealthy();
+	}
+};
+
+//#endregion
+//#region src/storage/cache.ts
+/**
+* O(1) LRU cache using Map's insertion-order iteration
+*
+* Map maintains insertion order, so we use delete+set to move items to the end.
+* - set/get/delete: O(1)
+* - eviction: O(1) - just delete first key
+* - Only caches active workflows (running/waiting)
+*/
+var WorkflowCache = class {
+	maxSize;
+	cache = /* @__PURE__ */ new Map();
+	constructor(maxSize = LIMITS.MAX_CACHE_SIZE) {
+		this.maxSize = maxSize;
+	}
+	set(run) {
+		if (!this.isActive(run.status)) {
+			this.cache.delete(run._id);
+			return;
+		}
+		const exists = this.cache.has(run._id);
+		if (exists) this.cache.delete(run._id);
+		if (!exists && this.cache.size >= this.maxSize) {
+			const oldest = this.cache.keys().next().value;
+			if (oldest) this.cache.delete(oldest);
+		}
+		this.cache.set(run._id, run);
+	}
+	get(runId) {
+		const run = this.cache.get(runId);
+		if (!run) return null;
+		this.cache.delete(runId);
+		this.cache.set(runId, run);
+		return run;
+	}
+	delete(runId) {
+		this.cache.delete(runId);
+	}
+	clear() {
+		this.cache.clear();
+	}
+	getActive() {
+		return Array.from(this.cache.values());
+	}
+	size() {
+		return this.cache.size;
+	}
+	getStats() {
+		return {
+			size: this.cache.size,
+			maxSize: this.maxSize,
+			utilizationPercent: Math.round(this.cache.size / this.maxSize * 100)
+		};
+	}
+	/**
+	* Check if cache is approaching capacity.
+	* Useful for monitoring and proactive scaling.
+	*
+	* @param threshold - Utilization ratio (0-1), default 0.8 (80%)
+	*/
+	isNearCapacity(threshold = .8) {
+		return this.cache.size / this.maxSize >= threshold;
+	}
+	/**
+	* Get cache health status for monitoring dashboards.
+	* Returns status and human-readable message.
+	*/
+	getHealth() {
+		const utilization = this.cache.size / this.maxSize;
+		const utilizationPercent = Math.round(utilization * 100);
+		if (this.cache.size < COMPUTED.CACHE_WARNING_THRESHOLD) return {
+			status: "healthy",
+			message: `Cache at ${utilizationPercent}% capacity`,
+			utilizationPercent
+		};
+		if (this.cache.size < COMPUTED.CACHE_CRITICAL_THRESHOLD) return {
+			status: "warning",
+			message: `Cache at ${utilizationPercent}% - consider increasing maxSize`,
+			utilizationPercent
+		};
+		return {
+			status: "critical",
+			message: `Cache at ${utilizationPercent}% - frequent evictions may impact performance`,
+			utilizationPercent
+		};
+	}
+	isActive(status) {
+		return status === "running" || status === "waiting";
+	}
+};
+/** Singleton for test utilities - each workflow creates its own cache via container */
+const workflowCache = new WorkflowCache();
+
+//#endregion
+//#region src/storage/run.model.ts
+const StepStateSchema = new Schema({
+	stepId: {
+		type: String,
+		required: true
+	},
+	status: {
+		type: String,
+		enum: [
+			"pending",
+			"running",
+			"waiting",
+			"done",
+			"failed",
+			"skipped"
+		],
+		required: true
+	},
+	attempts: {
+		type: Number,
+		default: 0
+	},
+	startedAt: Date,
+	endedAt: Date,
+	output: Schema.Types.Mixed,
+	waitingFor: {
+		type: Schema.Types.Mixed,
+		required: false
+	},
+	error: {
+		type: Schema.Types.Mixed,
+		required: false
+	},
+	retryAfter: Date
+}, { _id: false });
+const RecurrencePatternSchema = new Schema({
+	pattern: {
+		type: String,
+		enum: [
+			"daily",
+			"weekly",
+			"monthly",
+			"custom"
+		],
+		required: true
+	},
+	daysOfWeek: [Number],
+	dayOfMonth: Number,
+	cronExpression: String,
+	until: Date,
+	count: Number,
+	occurrences: {
+		type: Number,
+		default: 0
+	}
+}, { _id: false });
+const SchedulingInfoSchema = new Schema({
+	scheduledFor: {
+		type: String,
+		required: true
+	},
+	timezone: {
+		type: String,
+		required: true
+	},
+	localTimeDisplay: {
+		type: String,
+		required: true
+	},
+	executionTime: {
+		type: Date,
+		required: true,
+		index: true
+	},
+	isDSTTransition: {
+		type: Boolean,
+		default: false
+	},
+	dstNote: String,
+	recurrence: RecurrencePatternSchema
+}, { _id: false });
+const WorkflowRunSchema = new Schema({
+	_id: {
+		type: String,
+		required: true
+	},
+	workflowId: {
+		type: String,
+		required: true,
+		index: true
+	},
+	status: {
+		type: String,
+		enum: [
+			"draft",
+			"running",
+			"waiting",
+			"done",
+			"failed",
+			"cancelled"
+		],
+		required: true,
+		index: true
+	},
+	steps: [StepStateSchema],
+	currentStepId: String,
+	context: {
+		type: Schema.Types.Mixed,
+		default: {}
+	},
+	input: Schema.Types.Mixed,
+	output: Schema.Types.Mixed,
+	error: {
+		type: Schema.Types.Mixed,
+		required: false
+	},
+	createdAt: {
+		type: Date,
+		required: true
+	},
+	updatedAt: {
+		type: Date,
+		required: true
+	},
+	startedAt: Date,
+	endedAt: Date,
+	lastHeartbeat: Date,
+	paused: {
+		type: Boolean,
+		default: false
+	},
+	scheduling: SchedulingInfoSchema,
+	userId: {
+		type: String,
+		index: true
+	},
+	tags: [String],
+	meta: Schema.Types.Mixed
+}, {
+	collection: "workflow_runs",
+	timestamps: false
+});
+WorkflowRunSchema.index({
+	workflowId: 1,
+	status: 1
+});
+WorkflowRunSchema.index({
+	status: 1,
+	updatedAt: -1
+});
+WorkflowRunSchema.index({
+	userId: 1,
+	createdAt: -1
+});
+WorkflowRunSchema.index({ "steps.stepId": 1 });
+WorkflowRunSchema.index({
+	status: 1,
+	"steps.status": 1,
+	"steps.waitingFor.resumeAt": 1
+});
+WorkflowRunSchema.index({
+	status: 1,
+	"steps.status": 1,
+	"steps.retryAfter": 1
+});
+WorkflowRunSchema.index({
+	status: 1,
+	lastHeartbeat: 1
+});
+WorkflowRunSchema.index({
+	status: 1,
+	"scheduling.executionTime": 1,
+	paused: 1
+});
+/**
+* MULTI-TENANCY & SCHEDULED WORKFLOWS - COMPOSITE INDEXES
+*
+* For multi-tenant scheduled workflows, add composite indexes with tenantId FIRST.
+* MongoDB can only use indexes if the query matches the prefix pattern.
+*
+* Example: Multi-tenant scheduled workflow polling
+* ```typescript
+* import { WorkflowRunModel } from '@classytic/streamline';
+*
+* // Add composite index: tenantId first, then scheduling fields
+* WorkflowRunModel.collection.createIndex({
+*   'context.tenantId': 1,
+*   status: 1,
+*   'scheduling.executionTime': 1,
+*   paused: 1
+* });
+*
+* // This query will use the index efficiently:
+* const scheduledWorkflows = await WorkflowRunModel.find({
+*   'context.tenantId': 'tenant123',
+*   status: 'draft',
+*   'scheduling.executionTime': { $lte: new Date() },
+*   paused: { $ne: true }
+* }).sort({ 'scheduling.executionTime': 1 }).limit(100);
+* ```
+*
+* Example: List workflows by tenant and time
+* ```typescript
+* WorkflowRunModel.collection.createIndex({
+*   'context.tenantId': 1,
+*   workflowId: 1,
+*   createdAt: -1
+* });
+* ```
+*
+* IMPORTANT: Put tenantId FIRST in all multi-tenant indexes for query efficiency.
+*/
+/**
+* MULTI-TENANCY & CUSTOM INDEXES
+*
+* The engine is unopinionated about multi-tenancy. Add indexes for YOUR needs:
+*
+* Option 1: Add tenantId to metadata and index it
+* ```typescript
+* import { WorkflowRunModel } from '@classytic/streamline';
+*
+* // Add custom index for tenant-scoped queries
+* WorkflowRunModel.collection.createIndex({ 'meta.tenantId': 1, status: 1 });
+* WorkflowRunModel.collection.createIndex({ 'meta.orgId': 1, createdAt: -1 });
+* ```
+*
+* Option 2: Extend the schema (before first use)
+* ```typescript
+* import { WorkflowRunModel } from '@classytic/streamline';
+*
+* WorkflowRunModel.schema.add({
+*   tenantId: { type: String, index: true }
+* });
+* WorkflowRunModel.schema.index({ tenantId: 1, status: 1 });
+* ```
+*
+* Then query: engine.get(runId) and filter by tenantId in your app layer
+*/
+/**
+* Export WorkflowRunModel with hot-reload safety
+* 
+* The pattern checks if the model already exists before creating a new one.
+* This prevents "OverwriteModelError" in development with hot module replacement.
+*/
+let WorkflowRunModel;
+if (mongoose.models.WorkflowRun) WorkflowRunModel = mongoose.models.WorkflowRun;
+else WorkflowRunModel = mongoose.model("WorkflowRun", WorkflowRunSchema);
+
+//#endregion
+//#region src/storage/query-builder.ts
+const RUN_STATUS = {
+	DRAFT: "draft",
+	RUNNING: "running",
+	WAITING: "waiting",
+	DONE: "done",
+	FAILED: "failed",
+	CANCELLED: "cancelled"
+};
+const STEP_STATUS = {
+	PENDING: "pending",
+	RUNNING: "running",
+	WAITING: "waiting",
+	DONE: "done",
+	FAILED: "failed",
+	SKIPPED: "skipped"
+};
+var WorkflowQueryBuilder = class WorkflowQueryBuilder {
+	query = {};
+	static create() {
+		return new WorkflowQueryBuilder();
+	}
+	withStatus(status) {
+		this.query.status = Array.isArray(status) ? { $in: status } : status;
+		return this;
+	}
+	notPaused() {
+		this.query.paused = { $ne: true };
+		return this;
+	}
+	isPaused() {
+		this.query.paused = true;
+		return this;
+	}
+	withWorkflowId(workflowId) {
+		this.query.workflowId = workflowId;
+		return this;
+	}
+	withRunId(runId) {
+		this.query._id = runId;
+		return this;
+	}
+	withUserId(userId) {
+		this.query.userId = userId;
+		return this;
+	}
+	withTags(tags) {
+		this.query.tags = Array.isArray(tags) ? { $all: tags } : tags;
+		return this;
+	}
+	withStepReady(stepStatus, field, beforeTime) {
+		this.query.steps = { $elemMatch: {
+			status: stepStatus,
+			[field]: { $lte: beforeTime }
+		} };
+		return this;
+	}
+	withRetryReady(now = /* @__PURE__ */ new Date()) {
+		return this.withStepReady(STEP_STATUS.PENDING, "retryAfter", now);
+	}
+	withTimerReady(now = /* @__PURE__ */ new Date()) {
+		this.query.steps = { $elemMatch: {
+			status: STEP_STATUS.WAITING,
+			"waitingFor.type": "timer",
+			"waitingFor.resumeAt": { $lte: now }
+		} };
+		return this;
+	}
+	withStaleHeartbeat(thresholdMs) {
+		const staleTime = new Date(Date.now() - thresholdMs);
+		this.query.$or = [{ lastHeartbeat: { $lt: staleTime } }, { lastHeartbeat: { $exists: false } }];
+		return this;
+	}
+	withScheduledBefore(time) {
+		this.query["scheduling.executionTime"] = { $lte: time };
+		return this;
+	}
+	withScheduledAfter(time) {
+		this.query["scheduling.executionTime"] = { $gte: time };
+		return this;
+	}
+	createdBefore(date) {
+		const existing = this.query.createdAt ?? {};
+		this.query.createdAt = {
+			...existing,
+			$lte: date
+		};
+		return this;
+	}
+	createdAfter(date) {
+		const existing = this.query.createdAt ?? {};
+		this.query.createdAt = {
+			...existing,
+			$gte: date
+		};
+		return this;
+	}
+	where(conditions) {
+		Object.assign(this.query, conditions);
+		return this;
+	}
+	build() {
+		return this.query;
+	}
+};
+const CommonQueries = {
+	active: () => WorkflowQueryBuilder.create().withStatus([RUN_STATUS.RUNNING, RUN_STATUS.WAITING]).notPaused().build(),
+	readyForRetry: (now) => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.WAITING).notPaused().withRetryReady(now).build(),
+	readyToResume: (now) => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.WAITING).notPaused().withTimerReady(now).build(),
+	staleRunning: (thresholdMs) => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.RUNNING).notPaused().withStaleHeartbeat(thresholdMs).build(),
+	scheduledReady: (now) => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.DRAFT).notPaused().withScheduledBefore(now ?? /* @__PURE__ */ new Date()).build(),
+	byUser: (userId, status) => {
+		const builder = WorkflowQueryBuilder.create().withUserId(userId);
+		return status ? builder.withStatus(status).build() : builder.build();
+	},
+	failed: () => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.FAILED).build(),
+	completed: () => WorkflowQueryBuilder.create().withStatus(RUN_STATUS.DONE).build()
+};
+
+//#endregion
+//#region src/plugins/tenant-filter.plugin.ts
+/**
+* Tenant filter plugin factory
+*
+* Creates a plugin that automatically injects tenant filters into all queries.
+* Prevents cross-tenant data leaks by enforcing tenant isolation at repository level.
+*
+* @param options - Plugin configuration options
+* @returns MongoKit plugin instance
+*
+* @example Multi-Tenant with Strict Mode
+* ```typescript
+* const plugin = tenantFilterPlugin({
+*   tenantField: 'context.tenantId',
+*   strict: true,
+*   allowBypass: false // No bypasses allowed
+* });
+* ```
+*
+* @example Single-Tenant with Static ID
+* ```typescript
+* const plugin = tenantFilterPlugin({
+*   tenantField: 'context.tenantId',
+*   staticTenantId: process.env.ORGANIZATION_ID
+* });
+* ```
+*/
+function tenantFilterPlugin(options = {}) {
+	const tenantField = options.tenantField || "context.tenantId";
+	const staticTenantId = options.staticTenantId;
+	const strict = options.strict !== false;
+	const allowBypass = options.allowBypass !== false;
+	return {
+		name: "tenantFilter",
+		apply(repo) {
+			/**
+			* Inject tenant filter into context
+			* Validates tenantId presence and builds filter object
+			*/
+			const injectTenantFilter = (context) => {
+				if (context.bypassTenant) {
+					if (!allowBypass) throw new Error("[tenantFilterPlugin] Tenant bypass not allowed (allowBypass: false)");
+					return;
+				}
+				const tenantId = context.tenantId || staticTenantId;
+				if (!tenantId && strict) throw new Error(`[tenantFilterPlugin] Missing tenantId in ${context.operation} operation. Pass 'tenantId' in query options or set 'staticTenantId' in plugin config.`);
+				if (!tenantId) return;
+				const tenantFilter = { [tenantField]: tenantId };
+				if (context.operation === "getAll") context.filters = {
+					...context.filters,
+					...tenantFilter
+				};
+				else if (context.operation === "getById" || context.operation === "getByQuery" || context.operation === "update" || context.operation === "delete") context.query = {
+					...context.query || {},
+					...tenantFilter
+				};
+				else if (context.operation === "aggregatePaginate") {
+					const pipeline = context.pipeline;
+					if (Array.isArray(pipeline)) pipeline.unshift({ $match: tenantFilter });
+					else context.pipeline = [{ $match: tenantFilter }];
+				}
+			};
+			repo.on("before:getAll", injectTenantFilter);
+			repo.on("before:getById", injectTenantFilter);
+			repo.on("before:getByQuery", injectTenantFilter);
+			repo.on("before:update", injectTenantFilter);
+			repo.on("before:delete", injectTenantFilter);
+			repo.on("before:aggregatePaginate", injectTenantFilter);
+			repo.on("before:create", (context) => {
+				if (context.bypassTenant && allowBypass) return;
+				const tenantId = context.tenantId || staticTenantId;
+				if (!tenantId && strict) throw new Error("[tenantFilterPlugin] Missing tenantId in create operation. Pass 'tenantId' in options or set 'staticTenantId' in plugin config.");
+				if (tenantId) {
+					const data = context.data;
+					if (data) {
+						const fieldParts = tenantField.split(".");
+						if (fieldParts.length === 1) data[tenantField] = tenantId;
+						else {
+							let current = data;
+							for (let i = 0; i < fieldParts.length - 1; i++) {
+								const part = fieldParts[i];
+								if (!current[part] || typeof current[part] !== "object") current[part] = {};
+								current = current[part];
+							}
+							current[fieldParts[fieldParts.length - 1]] = tenantId;
+						}
+					}
+				}
+			});
+			repo.on("before:createMany", (context) => {
+				if (context.bypassTenant && allowBypass) return;
+				const tenantId = context.tenantId || staticTenantId;
+				if (!tenantId && strict) throw new Error("[tenantFilterPlugin] Missing tenantId in createMany operation. Pass 'tenantId' in options or set 'staticTenantId' in plugin config.");
+				if (tenantId) {
+					const dataArray = context.dataArray;
+					if (Array.isArray(dataArray)) dataArray.forEach((data) => {
+						const fieldParts = tenantField.split(".");
+						if (fieldParts.length === 1) data[tenantField] = tenantId;
+						else {
+							let current = data;
+							for (let i = 0; i < fieldParts.length - 1; i++) {
+								const part = fieldParts[i];
+								if (!current[part] || typeof current[part] !== "object") current[part] = {};
+								current = current[part];
+							}
+							current[fieldParts[fieldParts.length - 1]] = tenantId;
+						}
+					});
+				}
+			});
+		}
+	};
+}
+/**
+* Helper to create single-tenant repository (syntactic sugar)
+*
+* @param tenantId - Static tenant ID for all operations
+* @param tenantField - Field path for tenant ID (default: 'context.tenantId')
+* @returns Plugin configuration for single-tenant mode
+*
+* @example
+* ```typescript
+* import { singleTenantPlugin } from './plugins/tenant-filter.plugin';
+*
+* const repo = new Repository(Model, [
+*   singleTenantPlugin('my-organization-id')
+* ]);
+* ```
+*/
+function singleTenantPlugin(tenantId, tenantField = "context.tenantId") {
+	return tenantFilterPlugin({
+		tenantField,
+		staticTenantId: tenantId,
+		strict: true,
+		allowBypass: false
+	});
+}
+
+//#endregion
+//#region src/storage/run.repository.ts
+/**
+* Workflow Run Repository
+*
+* MongoKit-powered repository with multi-tenant support and atomic operations.
+*/
+var WorkflowRepository = class {
+	repo;
+	tenantField;
+	isMultiTenant;
+	isStrictTenant;
+	constructor(config = {}) {
+		this.isMultiTenant = !!config.multiTenant;
+		this.isStrictTenant = config.multiTenant?.strict !== false;
+		this.tenantField = config.multiTenant?.tenantField || "context.tenantId";
+		this.repo = new Repository(WorkflowRunModel, [
+			methodRegistryPlugin(),
+			mongoOperationsPlugin(),
+			...config.multiTenant ? [tenantFilterPlugin(config.multiTenant)] : []
+		]);
+	}
+	async create(run) {
+		return this.repo.create(run);
+	}
+	async getById(id) {
+		return this.repo.getById(id);
+	}
+	getAll(...args) {
+		return this.repo.getAll(...args);
+	}
+	async update(id, data, options) {
+		if (options?.bypassTenant) {
+			const result = await WorkflowRunModel.findByIdAndUpdate(id, data, {
+				returnDocument: "after",
+				runValidators: true,
+				lean: true
+			});
+			if (!result) throw new Error(`Workflow run "${id}" not found`);
+			return result;
+		}
+		return this.repo.update(id, data);
+	}
+	delete(...args) {
+		return this.repo.delete(...args);
+	}
+	async updateOne(filter, update, options) {
+		const finalFilter = this.applyTenantFilter(filter, options, "updateOne");
+		const finalUpdate = Object.keys(update).some((k) => k.startsWith("$")) ? update : { $set: update };
+		return { modifiedCount: (await WorkflowRunModel.updateOne(finalFilter, finalUpdate)).modifiedCount };
+	}
+	async getActiveRuns() {
+		return this.queryLean(CommonQueries.active(), "-updatedAt", 1e3);
+	}
+	async getRunsByWorkflow(workflowId, limit = 100) {
+		return this.queryLean({ workflowId }, "-createdAt", limit);
+	}
+	async getWaitingRuns() {
+		return this.queryLean({
+			status: "waiting",
+			paused: { $ne: true }
+		}, "-updatedAt", 1e3);
+	}
+	async getRunningRuns() {
+		return this.queryLean({ status: "running" }, "-updatedAt", 1e3);
+	}
+	async getReadyToResume(now, limit = 100) {
+		return this.queryLean(CommonQueries.readyToResume(now), { updatedAt: 1 }, limit);
+	}
+	async getReadyForRetry(now, limit = 100) {
+		return this.queryLean(CommonQueries.readyForRetry(now), { updatedAt: 1 }, limit);
+	}
+	async getStaleRunningWorkflows(staleThresholdMs, limit = 100) {
+		return this.queryLean(CommonQueries.staleRunning(staleThresholdMs), { updatedAt: 1 }, limit);
+	}
+	async getScheduledWorkflowsReadyToExecute(now, options = {}) {
+		const { page = 1, limit = 100, cursor, tenantId } = options;
+		return await this.repo.getAll({
+			filters: CommonQueries.scheduledReady(now),
+			sort: { "scheduling.executionTime": 1 },
+			page,
+			limit,
+			cursor: cursor ?? void 0,
+			...tenantId && { tenantId }
+		}, { lean: true });
+	}
+	get base() {
+		return this.repo;
+	}
+	get _hooks() {
+		return this.repo._hooks;
+	}
+	async queryLean(filters, sort, limit) {
+		return (await this.repo.getAll({
+			filters,
+			sort,
+			limit
+		}, { lean: true })).docs;
+	}
+	applyTenantFilter(filter, options, operation) {
+		if (!this.isMultiTenant || options?.bypassTenant) return filter;
+		if (this.isStrictTenant && !options?.tenantId) throw new Error(`[WorkflowRepository.${operation}] tenantId required in multi-tenant mode. Pass { tenantId } or { bypassTenant: true }.`);
+		if (!options?.tenantId) return filter;
+		return {
+			...filter,
+			[this.tenantField]: options.tenantId
+		};
+	}
+};
+/**
+* Create a workflow repository instance.
+*
+* @example
+* // Single-tenant:
+* const repo = createWorkflowRepository();
+*
+* // Multi-tenant:
+* const repo = createWorkflowRepository({
+*   multiTenant: { tenantField: 'context.tenantId', strict: true }
+* });
+*/
+function createWorkflowRepository(config = {}) {
+	return new WorkflowRepository(config);
+}
+const workflowRunRepository = createWorkflowRepository();
+
+//#endregion
+//#region src/core/container.ts
+/**
+* Dependency Injection Container
+*
+* Enables testability and multi-instance support by eliminating global singletons.
+* All shared dependencies are passed through this container.
+*/
+/**
+* Create a new container with configurable dependencies.
+*
+* @param options - Optional configuration for container dependencies
+* @returns A container with the specified or default dependencies
+*
+* @example Default container (isolated instances)
+* ```typescript
+* const container = createContainer();
+* ```
+*
+* @example Multi-tenant container
+* ```typescript
+* const container = createContainer({
+*   repository: { multiTenant: { tenantField: 'meta.tenantId', strict: true } }
+* });
+* ```
+*
+* @example Container with global event bus (for telemetry)
+* ```typescript
+* const container = createContainer({ eventBus: 'global' });
+* ```
+*
+* @example Fully custom container
+* ```typescript
+* const container = createContainer({
+*   repository: myCustomRepo,
+*   eventBus: myCustomEventBus,
+*   cache: myCustomCache
+* });
+* ```
+*/
+function createContainer(options = {}) {
+	let repository;
+	if (!options.repository) repository = workflowRunRepository;
+	else if ("create" in options.repository && "getById" in options.repository) repository = options.repository;
+	else repository = createWorkflowRepository(options.repository);
+	let eventBus;
+	if (options.eventBus === "global") eventBus = globalEventBus;
+	else if (options.eventBus instanceof WorkflowEventBus) eventBus = options.eventBus;
+	else eventBus = new WorkflowEventBus();
+	const cache = options.cache ?? new WorkflowCache();
+	return {
+		repository,
+		eventBus,
+		cache
+	};
+}
+/**
+* Type guard to check if an object is a valid StreamlineContainer
+*/
+function isStreamlineContainer(obj) {
+	if (!obj || typeof obj !== "object") return false;
+	const container = obj;
+	return "repository" in container && "eventBus" in container && "cache" in container && container.eventBus instanceof WorkflowEventBus && container.cache instanceof WorkflowCache;
+}
+
+//#endregion
+export { isValidStepTransition as A, RUN_STATUS_VALUES as C, isStepStatus as D, isRunStatus as E, logger as M, isTerminalState as O, shouldSkipStep as S, deriveRunStatus as T, COMPUTED as _, singleTenantPlugin as a, createCondition as b, RUN_STATUS as c, WorkflowRunModel as d, WorkflowCache as f, validateRetryConfig as g, validateId as h, workflowRunRepository as i, WaitSignal as j, isValidRunTransition as k, STEP_STATUS as l, hookRegistry as m, isStreamlineContainer as n, tenantFilterPlugin as o, WorkflowEngine as p, createWorkflowRepository as r, CommonQueries as s, createContainer as t, WorkflowQueryBuilder as u, SCHEDULING as v, STEP_STATUS_VALUES as w, isConditionalStep as x, conditions as y };