octaflow 0.14.0

package/dist/index.js

@@ -0,0 +1,1426 @@
+import { S as ok, _ as markRetryable, a as WORKFLOW_STATUS_SCHEMA, b as noopLogger, c as toPublicWorkflow, d as defineSleepStep, f as defineStep, g as isRetryableError, h as explicitRetryability, i as STEP_DISPLAY_STATUS_SCHEMA, l as buildWorkflow, m as defineWaitStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, o as toDisplayStepStatus, p as defineSubWorkflowStep, r as STEP_DISPLAY_STATUS, s as toPublicStep, t as PUBLIC_WORKFLOW_SCHEMA, u as defineMapStep, v as nonRetryableError, x as err, y as retryableError } from "./core-ERYGlYsS.js";
+//#region src/core/gate.ts
+/**
+* A per-process {@link StepGate}: per-stepType concurrency caps (held slots) plus
+* per-stepType token-bucket rate limits (throughput). Both are optional and checked
+* per step type; a step type with no rule is always admitted.
+*
+* Concurrency is reserved first, then the rate token — so a rate denial does not waste
+* a concurrency slot. Good for single-worker deployments; swap in a shared-store gate
+* for multi-worker concurrency control.
+*/
+function createInMemoryStepGate(config = {}) {
+	const now = config.now ?? (() => Date.now());
+	const concurrencyRetry = Math.max(1, config.concurrencyRetrySeconds ?? 1);
+	const running = /* @__PURE__ */ new Map();
+	const buckets = /* @__PURE__ */ new Map();
+	function rateCheck(stepType) {
+		const rule = config.rateLimit?.[stepType];
+		if (!rule) return { ok: true };
+		const capacity = rule.burst ?? Math.max(1, Math.ceil(rule.perSecond));
+		const tNow = now();
+		let b = buckets.get(stepType);
+		if (!b) {
+			b = {
+				tokens: capacity,
+				updatedMs: tNow
+			};
+			buckets.set(stepType, b);
+		}
+		const elapsedSec = Math.max(0, (tNow - b.updatedMs) / 1e3);
+		b.tokens = Math.min(capacity, b.tokens + elapsedSec * rule.perSecond);
+		b.updatedMs = tNow;
+		if (b.tokens >= 1) {
+			b.tokens -= 1;
+			return { ok: true };
+		}
+		const needed = 1 - b.tokens;
+		return {
+			ok: false,
+			retryAfterSeconds: Math.max(1, Math.ceil(needed / rule.perSecond))
+		};
+	}
+	return { async acquire(req) {
+		let release = () => {};
+		const cRule = config.concurrency?.[req.stepType];
+		if (cRule) {
+			const current = running.get(req.stepType) ?? 0;
+			if (current >= cRule.maxConcurrent) return {
+				admitted: false,
+				retryAfterSeconds: concurrencyRetry
+			};
+			running.set(req.stepType, current + 1);
+			let released = false;
+			release = () => {
+				if (released) return;
+				released = true;
+				running.set(req.stepType, Math.max(0, (running.get(req.stepType) ?? 1) - 1));
+			};
+		}
+		const rate = rateCheck(req.stepType);
+		if (!rate.ok) {
+			release();
+			return {
+				admitted: false,
+				retryAfterSeconds: rate.retryAfterSeconds
+			};
+		}
+		return {
+			admitted: true,
+			release
+		};
+	} };
+}
+//#endregion
+//#region src/core/observability.ts
+const noopObserver = { record() {} };
+function createRecordingObserver() {
+	const events = [];
+	return {
+		events,
+		record(event) {
+			events.push(event);
+		},
+		clear() {
+			events.length = 0;
+		}
+	};
+}
+const noopSpan = {
+	setAttribute() {},
+	recordError() {},
+	end() {}
+};
+const noopTracer = { startSpan: () => noopSpan };
+function createRecordingTracer() {
+	const spans = [];
+	return {
+		spans,
+		startSpan(name, attributes = {}) {
+			const rec = {
+				name,
+				attributes: { ...attributes },
+				ended: false
+			};
+			spans.push(rec);
+			return {
+				setAttribute(key, value) {
+					rec.attributes[key] = value;
+				},
+				recordError(error) {
+					rec.error = error.message;
+				},
+				end() {
+					rec.ended = true;
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/core/registry.ts
+/**
+* Creates an in-memory step handler registry.
+* Populate it at application startup (e.g. by registering every workflow's steps).
+* Each registration carries the handler plus its optional retry/timeout policy.
+*/
+function createStepHandlerRegistry() {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		register(type, handler, options) {
+			entries.set(type, {
+				handler,
+				retry: options?.retry,
+				timeoutMs: options?.timeoutMs,
+				delayMs: options?.delayMs,
+				waitForEvent: options?.waitForEvent,
+				map: options?.map,
+				childType: options?.childType,
+				subWorkflowDefinition: options?.subWorkflowDefinition,
+				compensate: options?.compensate
+			});
+		},
+		get(type) {
+			return entries.get(type)?.handler;
+		},
+		getRegistration(type) {
+			return entries.get(type);
+		},
+		has(type) {
+			return entries.has(type);
+		},
+		types() {
+			return Array.from(entries.keys());
+		}
+	};
+}
+//#endregion
+//#region src/core/engine.ts
+/**
+* Run a handler under an optional wall-clock timeout. On expiry the abort signal
+* is fired (cooperative handlers stop) and a retryable timeout error is returned —
+* the engine then applies the step's retry policy.
+*/
+async function runWithTimeout(handler, ctx, timeoutMs, abort) {
+	if (!timeoutMs || timeoutMs <= 0) return handler(ctx);
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			abort.abort();
+			resolve({
+				ok: false,
+				error: {
+					key: "step_error",
+					message: `Step timed out after ${timeoutMs}ms`,
+					retryable: true,
+					retryableFrom: "explicit"
+				}
+			});
+		}, timeoutMs);
+	});
+	try {
+		return await Promise.race([handler(ctx), timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+/** Backoff delay (in whole seconds) before the next attempt, given the just-failed attempt number. */
+function backoffDelaySeconds(retry, failedAttemptNo) {
+	const initialMs = retry?.initialDelayMs ?? 1e3;
+	const maxMs = retry?.maxDelayMs ?? 6e4;
+	const baseMs = retry?.backoff === "exponential" ? initialMs * 2 ** (failedAttemptNo - 1) : initialMs;
+	return Math.max(0, Math.ceil(Math.min(baseMs, maxMs) / 1e3));
+}
+/**
+* Reverse topological order: a step appears before its dependencies, so saga
+* compensation undoes effects in the opposite order they were produced. Pure / deterministic.
+*/
+function reverseTopologicalOrder(steps) {
+	const inSet = new Set(steps.map((s) => s.key));
+	const placed = /* @__PURE__ */ new Set();
+	const topo = [];
+	let guard = 0;
+	while (placed.size < steps.length && guard++ <= steps.length) for (const s of steps) {
+		if (placed.has(s.key)) continue;
+		if ((s.dependencies ?? []).filter((d) => inSet.has(d)).every((d) => placed.has(d))) {
+			topo.push(s);
+			placed.add(s.key);
+		}
+	}
+	for (const s of steps) if (!placed.has(s.key)) topo.push(s);
+	return topo.reverse();
+}
+function createWorkflowEngine(deps) {
+	const { store, dispatcher, registry, partitionKey } = deps;
+	const gate = deps.gate;
+	const logger = deps.logger ?? noopLogger;
+	const hooks = deps.hooks ?? {};
+	const observer = deps.observer ?? noopObserver;
+	const tracer = deps.tracer ?? noopTracer;
+	const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+	const stepExpirySeconds = deps.config?.stepExpirySeconds ?? 600;
+	const stuckStepBufferSeconds = deps.config?.stuckStepBufferSeconds ?? 300;
+	const defaultRetryable = deps.config?.defaultRetryable;
+	const nowIso = () => now().toISOString();
+	/** Emit a run-history / metrics event. Guarded — a faulty observer never breaks a run. */
+	function emit(event) {
+		try {
+			observer.record({
+				...event,
+				partitionKey,
+				at: nowIso()
+			});
+		} catch (e) {
+			logger.error("Observer threw", e instanceof Error ? e : new Error(String(e)), { workflowId: event.workflowId });
+		}
+	}
+	/** Durable start delay for a ready step, from its registered `delayMs`. */
+	function readyStepDelay(stepType) {
+		const delayMs = registry.getRegistration(stepType)?.delayMs;
+		if (!delayMs || delayMs <= 0) return void 0;
+		return { startAfterSeconds: Math.ceil(delayMs / 1e3) };
+	}
+	/** Whether a step type suspends on readiness instead of dispatching. */
+	function isWaitStep(stepType) {
+		return registry.getRegistration(stepType)?.waitForEvent === true;
+	}
+	/**
+	* Make a newly-ready step runnable: a `waitForEvent` step suspends (status `waiting`)
+	* and awaits `resumeStep`; everything else is enqueued (with any durable delay).
+	* Returns whether the step was enqueued.
+	*/
+	async function dispatchReadyStep(workflowId, stepId, stepKey, stepType) {
+		if (isWaitStep(stepType)) {
+			await store.markStepWaiting(stepId);
+			logger.info("Step is waiting for an event", {
+				workflowId,
+				stepId,
+				stepKey
+			});
+			emit({
+				type: "step.waiting",
+				workflowId,
+				stepId,
+				stepKey,
+				stepType
+			});
+			return false;
+		}
+		const result = await dispatcher.enqueueStep({
+			workflowId,
+			stepId,
+			stepKey,
+			stepType
+		}, readyStepDelay(stepType));
+		if (!result.ok) {
+			logger.error("Failed to enqueue step", new Error(result.error.message), {
+				workflowId,
+				stepKey
+			});
+			return false;
+		}
+		logger.info("Enqueued step", {
+			workflowId,
+			stepKey
+		});
+		return true;
+	}
+	function validateDefinition(definition) {
+		const { steps } = definition;
+		if (steps.length === 0) return {
+			ok: false,
+			error: {
+				key: "invalid_workflow_definition",
+				message: "Workflow must have at least one step"
+			}
+		};
+		const keys = /* @__PURE__ */ new Set();
+		for (const step of steps) {
+			if (keys.has(step.key)) return {
+				ok: false,
+				error: {
+					key: "invalid_workflow_definition",
+					message: `Duplicate step key: ${step.key}`
+				}
+			};
+			keys.add(step.key);
+		}
+		for (const step of steps) for (const dep of step.dependencies ?? []) {
+			if (!keys.has(dep)) return {
+				ok: false,
+				error: {
+					key: "invalid_workflow_definition",
+					message: `Step '${step.key}' depends on unknown step '${dep}'`
+				}
+			};
+			if (dep === step.key) return {
+				ok: false,
+				error: {
+					key: "invalid_workflow_definition",
+					message: `Step '${step.key}' cannot depend on itself`
+				}
+			};
+		}
+		const inDegree = /* @__PURE__ */ new Map();
+		const adjacency = /* @__PURE__ */ new Map();
+		for (const step of steps) {
+			inDegree.set(step.key, (step.dependencies ?? []).length);
+			adjacency.set(step.key, []);
+		}
+		for (const step of steps) for (const dep of step.dependencies ?? []) adjacency.get(dep).push(step.key);
+		const queue = [];
+		for (const [key, deg] of inDegree) if (deg === 0) queue.push(key);
+		let visited = 0;
+		while (queue.length > 0) {
+			const current = queue.shift();
+			visited++;
+			for (const neighbor of adjacency.get(current) ?? []) {
+				const newDeg = inDegree.get(neighbor) - 1;
+				inDegree.set(neighbor, newDeg);
+				if (newDeg === 0) queue.push(neighbor);
+			}
+		}
+		if (visited !== steps.length) return {
+			ok: false,
+			error: {
+				key: "invalid_workflow_definition",
+				message: "Workflow contains circular dependencies"
+			}
+		};
+		for (const step of steps) if (!registry.has(step.type)) return {
+			ok: false,
+			error: {
+				key: "step_handler_not_found",
+				message: `No handler registered for step type '${step.type}'`,
+				stepType: step.type
+			}
+		};
+		return {
+			ok: true,
+			value: void 0
+		};
+	}
+	async function startWorkflow(definition, input, options) {
+		const validation = validateDefinition(definition);
+		if (!validation.ok) return validation;
+		let metadata = options?.metadata;
+		if (hooks.onBeforeStart) {
+			const guard = await hooks.onBeforeStart({
+				definition,
+				input,
+				options
+			});
+			if (!guard.ok) return guard;
+			if (guard.value.metadata) metadata = {
+				...metadata ?? {},
+				...guard.value.metadata
+			};
+		}
+		const { steps } = definition;
+		const created = await store.createWorkflow({
+			type: definition.type,
+			input,
+			entityRef: options?.entityRef,
+			metadata,
+			idempotencyKey: options?.idempotencyKey,
+			parentWorkflowId: options?.parentWorkflowId,
+			parentStepId: options?.parentStepId,
+			startedAt: nowIso(),
+			steps: steps.map((s) => ({
+				key: s.key,
+				type: s.type,
+				dependencies: s.dependencies ?? [],
+				input: s.input ?? null
+			}))
+		});
+		const workflowId = created.workflowId;
+		if (created.alreadyExisted) {
+			logger.info("Idempotent start: returning existing workflow", {
+				workflowId,
+				idempotencyKey: options?.idempotencyKey
+			});
+			return {
+				ok: true,
+				value: {
+					workflowId,
+					totalSteps: created.steps.length,
+					enqueuedSteps: []
+				}
+			};
+		}
+		emit({
+			type: "workflow.started",
+			workflowId,
+			workflowType: definition.type
+		});
+		const readySteps = steps.filter((s) => !s.dependencies || s.dependencies.length === 0);
+		const enqueuedStepKeys = [];
+		for (const readyStep of readySteps) {
+			const dbStep = created.steps.find((s) => s.key === readyStep.key);
+			if (!dbStep) continue;
+			if (await dispatchReadyStep(workflowId, dbStep.id, readyStep.key, readyStep.type)) enqueuedStepKeys.push(readyStep.key);
+		}
+		logger.info("Workflow started", {
+			workflowId,
+			type: definition.type,
+			totalSteps: steps.length,
+			enqueuedSteps: enqueuedStepKeys
+		});
+		return {
+			ok: true,
+			value: {
+				workflowId,
+				totalSteps: steps.length,
+				enqueuedSteps: enqueuedStepKeys
+			}
+		};
+	}
+	/** Type-safe start: duck-types on `{ inputSchema, definition }`. */
+	function start(workflow, input, options) {
+		return startWorkflow(workflow.definition, workflow.inputSchema.parse(input), options);
+	}
+	async function executeStep(workflowId, stepId) {
+		const workflow = await store.getWorkflow(workflowId);
+		if (!workflow) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Workflow ${workflowId} not found`
+			}
+		};
+		if (workflow.status === "cancelled" || workflow.status === "failed") {
+			logger.info("Skipping step for non-active workflow", {
+				workflowId,
+				stepId,
+				status: workflow.status
+			});
+			return {
+				ok: true,
+				value: void 0
+			};
+		}
+		const step = await store.getStep(stepId);
+		if (!step || step.workflowId !== workflowId) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Step ${stepId} not found`
+			}
+		};
+		if (step.status !== "pending") {
+			logger.info("Skipping already-processed step", {
+				workflowId,
+				stepId,
+				stepKey: step.key,
+				status: step.status
+			});
+			return {
+				ok: true,
+				value: void 0
+			};
+		}
+		let releaseSlot;
+		if (gate) {
+			const decision = await gate.acquire({
+				partitionKey,
+				workflowId,
+				stepId,
+				stepKey: step.key,
+				stepType: step.type
+			});
+			if (!decision.admitted) {
+				logger.info("Step deferred by gate", {
+					workflowId,
+					stepId,
+					stepKey: step.key,
+					retryAfterSeconds: decision.retryAfterSeconds
+				});
+				const re = await dispatcher.enqueueStep({
+					workflowId,
+					stepId,
+					stepKey: step.key,
+					stepType: step.type
+				}, { startAfterSeconds: decision.retryAfterSeconds });
+				if (!re.ok) logger.error("Failed to re-enqueue gated step", new Error(re.error.message), {
+					workflowId,
+					stepId
+				});
+				return {
+					ok: true,
+					value: void 0
+				};
+			}
+			releaseSlot = decision.release;
+		}
+		const startMs = now().getTime();
+		try {
+			if (!await store.markStepRunning(stepId, nowIso())) {
+				logger.info("Lost the step claim to a concurrent worker", {
+					workflowId,
+					stepId,
+					stepKey: step.key
+				});
+				return {
+					ok: true,
+					value: void 0
+				};
+			}
+			const dependencyOutputs = {};
+			const stepDeps = step.dependencies ?? [];
+			if (stepDeps.length > 0) {
+				const allSteps = await store.listSteps(workflowId);
+				for (const depKey of stepDeps) {
+					const depStep = allSteps.find((s) => s.key === depKey);
+					if (!depStep || depStep.status !== "completed") {
+						logger.error("Step dependency not completed", /* @__PURE__ */ new Error(`Dependency '${depKey}' is ${depStep?.status ?? "missing"}`), {
+							workflowId,
+							stepId
+						});
+						return {
+							ok: false,
+							error: {
+								key: "step_error",
+								message: `Dependency '${depKey}' is not completed`
+							}
+						};
+					}
+					dependencyOutputs[depKey] = depStep.output ?? void 0;
+				}
+			}
+			const registration = registry.getRegistration(step.type);
+			if (!registration) {
+				await markStepFailed(stepId, workflowId, `No handler for step type '${step.type}'`);
+				return {
+					ok: false,
+					error: {
+						key: "step_handler_not_found",
+						message: `No handler for '${step.type}'`,
+						stepType: step.type
+					}
+				};
+			}
+			const { handler, retry, timeoutMs } = registration;
+			const maxAttempts = retry?.maxAttempts ?? 1;
+			const attemptNo = step.attempts + 1;
+			emit({
+				type: "step.started",
+				workflowId,
+				workflowType: workflow.type,
+				stepId,
+				stepKey: step.key,
+				stepType: step.type,
+				attempt: attemptNo
+			});
+			const span = tracer.startSpan("flow.step", {
+				"flow.workflow_id": workflowId,
+				"flow.workflow_type": workflow.type,
+				"flow.step_key": step.key,
+				"flow.step_type": step.type,
+				"flow.attempt": attemptNo,
+				"flow.partition": partitionKey
+			});
+			try {
+				const context = hooks.buildStepContext ? await hooks.buildStepContext({
+					workflowId,
+					stepId,
+					stepKey: step.key,
+					partitionKey,
+					workflow,
+					step
+				}) : void 0;
+				const abort = new AbortController();
+				const handlerResult = await runWithTimeout(handler, {
+					workflowId,
+					stepId,
+					stepKey: step.key,
+					partitionKey,
+					workflowInput: workflow.input ?? {},
+					stepInput: step.input ?? {},
+					dependencyOutputs,
+					signal: abort.signal,
+					context
+				}, timeoutMs, abort);
+				if (handlerResult.ok) {
+					if (registration.map) {
+						emit({
+							type: "step.mapping",
+							workflowId,
+							workflowType: workflow.type,
+							stepId,
+							stepKey: step.key,
+							stepType: step.type,
+							attempt: attemptNo
+						});
+						await spawnMapChildren(workflowId, step, registration.childType ?? `${step.type}__item`, handlerResult.value);
+						return {
+							ok: true,
+							value: void 0
+						};
+					}
+					if (registration.subWorkflowDefinition) {
+						await startSubWorkflow(workflowId, step, registration.subWorkflowDefinition, handlerResult.value);
+						return {
+							ok: true,
+							value: void 0
+						};
+					}
+					if (hooks.onAfterStep) await hooks.onAfterStep({
+						workflowId,
+						stepId,
+						partitionKey,
+						workflow,
+						step,
+						output: handlerResult.value,
+						context
+					});
+					emit({
+						type: "step.completed",
+						workflowId,
+						workflowType: workflow.type,
+						stepId,
+						stepKey: step.key,
+						stepType: step.type,
+						attempt: attemptNo,
+						durationMs: now().getTime() - startMs
+					});
+					if (step.parentStepId != null) await onChildCompleted(workflowId, step, handlerResult.value);
+					else await onStepCompleted(workflowId, stepId, handlerResult.value);
+					return {
+						ok: true,
+						value: void 0
+					};
+				}
+				if ((handlerResult.error.retryableFrom === "heuristic" && defaultRetryable !== void 0 ? defaultRetryable : handlerResult.error.retryable) && attemptNo < maxAttempts) {
+					const delaySeconds = backoffDelaySeconds(retry, attemptNo);
+					logger.info("Retrying step", {
+						workflowId,
+						stepId,
+						stepKey: step.key,
+						attempt: attemptNo,
+						maxAttempts,
+						delaySeconds,
+						reason: handlerResult.error.message
+					});
+					emit({
+						type: "step.retrying",
+						workflowId,
+						workflowType: workflow.type,
+						stepId,
+						stepKey: step.key,
+						stepType: step.type,
+						attempt: attemptNo,
+						durationMs: now().getTime() - startMs,
+						error: handlerResult.error.message
+					});
+					await store.markStepPending(stepId);
+					const re = await dispatcher.enqueueStep({
+						workflowId,
+						stepId,
+						stepKey: step.key,
+						stepType: step.type
+					}, { startAfterSeconds: delaySeconds });
+					if (!re.ok) await failStepTerminal(workflowId, step, `${handlerResult.error.message} (retry enqueue failed: ${re.error.message})`);
+					return {
+						ok: true,
+						value: void 0
+					};
+				}
+				span.recordError(new Error(handlerResult.error.message));
+				emit({
+					type: "step.failed",
+					workflowId,
+					workflowType: workflow.type,
+					stepId,
+					stepKey: step.key,
+					stepType: step.type,
+					attempt: attemptNo,
+					durationMs: now().getTime() - startMs,
+					error: handlerResult.error.message
+				});
+				await failStepTerminal(workflowId, step, handlerResult.error.message);
+				return {
+					ok: true,
+					value: void 0
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Unknown step execution error";
+				logger.error("Step execution threw", error instanceof Error ? error : new Error(message), {
+					workflowId,
+					stepId
+				});
+				span.recordError(error instanceof Error ? error : new Error(message));
+				emit({
+					type: "step.failed",
+					workflowId,
+					workflowType: workflow.type,
+					stepId,
+					stepKey: step.key,
+					stepType: step.type,
+					attempt: attemptNo,
+					durationMs: now().getTime() - startMs,
+					error: message
+				});
+				await failStepTerminal(workflowId, step, message);
+				throw error;
+			} finally {
+				span.end();
+			}
+		} finally {
+			if (releaseSlot) await releaseSlot();
+		}
+	}
+	/**
+	* Deliver an external event to a `waiting` step: completes it with `payload`
+	* as its output and advances the DAG. Idempotent — resuming a non-waiting step (e.g. a
+	* re-delivered event) is a logged no-op. The host correlates the event to `stepKey`.
+	*/
+	async function resumeStep(workflowId, stepKey, payload = {}) {
+		const workflow = await store.getWorkflow(workflowId);
+		if (!workflow) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Workflow ${workflowId} not found`
+			}
+		};
+		if (workflow.status !== "running" && workflow.status !== "pending") {
+			logger.info("Ignoring resume for non-active workflow", {
+				workflowId,
+				stepKey,
+				status: workflow.status
+			});
+			return {
+				ok: true,
+				value: void 0
+			};
+		}
+		const step = (await store.listSteps(workflowId)).find((s) => s.key === stepKey);
+		if (!step) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Step '${stepKey}' not found in workflow ${workflowId}`
+			}
+		};
+		if (step.status !== "waiting") {
+			logger.info("Ignoring resume for non-waiting step", {
+				workflowId,
+				stepKey,
+				status: step.status
+			});
+			return {
+				ok: true,
+				value: void 0
+			};
+		}
+		emit({
+			type: "step.resumed",
+			workflowId,
+			stepId: step.id,
+			stepKey,
+			stepType: step.type
+		});
+		await onStepCompleted(workflowId, step.id, payload);
+		logger.info("Resumed waiting step", {
+			workflowId,
+			stepKey
+		});
+		return {
+			ok: true,
+			value: void 0
+		};
+	}
+	async function onStepCompleted(workflowId, stepId, output) {
+		const completedAt = nowIso();
+		await store.completeStep({
+			workflowId,
+			stepId,
+			output,
+			completedAt
+		});
+		const keyedSteps = (await store.listSteps(workflowId)).filter((s) => s.parentStepId == null);
+		const completedKeys = new Set(keyedSteps.filter((s) => s.status === "completed").map((s) => s.key));
+		const newlyReady = keyedSteps.filter((s) => {
+			if (s.status !== "pending") return false;
+			return (s.dependencies ?? []).every((dep) => completedKeys.has(dep));
+		});
+		for (const readyStep of newlyReady) await dispatchReadyStep(workflowId, readyStep.id, readyStep.key, readyStep.type);
+		if (keyedSteps.some((s) => s.id !== stepId && s.status === "failed")) {
+			await checkWorkflowFailure(workflowId);
+			return;
+		}
+		if (keyedSteps.every((s) => s.id === stepId || s.status === "completed" || s.status === "skipped") && newlyReady.length === 0) {
+			const aggregatedOutput = {};
+			for (const s of keyedSteps) if (s.status === "completed" || s.id === stepId) aggregatedOutput[s.key] = s.id === stepId ? output : s.output ?? null;
+			await store.finishWorkflow({
+				workflowId,
+				status: "completed",
+				output: aggregatedOutput,
+				completedAt
+			});
+			logger.info("Workflow completed", { workflowId });
+			emit({
+				type: "workflow.completed",
+				workflowId
+			});
+			if (hooks.onWorkflowCompleted) {
+				const finalWorkflow = await store.getWorkflow(workflowId);
+				if (finalWorkflow) Promise.resolve(hooks.onWorkflowCompleted({
+					workflowId,
+					partitionKey,
+					workflow: finalWorkflow
+				})).catch((e) => logger.error("onWorkflowCompleted hook failed", e instanceof Error ? e : new Error(String(e)), { workflowId }));
+			}
+			await bridgeSubWorkflow(workflowId);
+		}
+	}
+	/** A map parent produced its item list — spawn one child per item and suspend it. */
+	async function spawnMapChildren(workflowId, parentStep, childType, itemsOutput) {
+		const items = Array.isArray(itemsOutput.items) ? itemsOutput.items : [];
+		if (items.length === 0) {
+			await onStepCompleted(workflowId, parentStep.id, { items: [] });
+			return;
+		}
+		const children = items.map((item, index) => ({
+			key: `${parentStep.key}#${index}`,
+			type: childType,
+			input: {
+				item,
+				index
+			}
+		}));
+		const created = await store.addChildSteps(workflowId, parentStep.id, children);
+		await store.markStepMapping(parentStep.id);
+		for (const child of created) {
+			const result = await dispatcher.enqueueStep({
+				workflowId,
+				stepId: child.id,
+				stepKey: child.key,
+				stepType: child.type
+			}, readyStepDelay(child.type));
+			if (!result.ok) logger.error("Failed to enqueue map child", new Error(result.error.message), {
+				workflowId,
+				stepKey: child.key
+			});
+		}
+		logger.info("Map step spawned children", {
+			workflowId,
+			parentKey: parentStep.key,
+			count: created.length
+		});
+	}
+	/** A map child completed — complete the parent (with aggregated outputs) once all siblings finish. */
+	async function onChildCompleted(workflowId, childStep, output) {
+		await store.completeStep({
+			workflowId,
+			stepId: childStep.id,
+			output,
+			completedAt: nowIso()
+		});
+		const parentId = childStep.parentStepId;
+		const children = await store.listChildSteps(parentId);
+		if (children.some((c) => c.status === "failed")) {
+			await checkWorkflowFailure(workflowId);
+			return;
+		}
+		if (children.every((c) => c.status === "completed")) await onStepCompleted(workflowId, parentId, { items: children.map((c) => c.output ?? null) });
+	}
+	/** Fail a map parent and skip its still-pending children (a sibling item errored). */
+	async function failMapParent(workflowId, parentStepId, message) {
+		const parent = await store.getStep(parentStepId);
+		if (!parent || parent.status === "failed" || parent.status === "completed") return;
+		await markStepFailed(parentStepId, workflowId, message);
+		for (const child of await store.listChildSteps(parentStepId)) if (child.status === "pending") await store.skipStep(child.id, "Skipped: sibling map item failed");
+	}
+	/** Terminal failure of a step — fails the parent map too if the step is a map child. */
+	async function failStepTerminal(workflowId, step, message) {
+		await markStepFailed(step.id, workflowId, message);
+		if (step.parentStepId != null) await failMapParent(workflowId, step.parentStepId, `Map item failed: ${message}`);
+		await checkWorkflowFailure(workflowId);
+	}
+	/** A sub-workflow step ran — start the child workflow and suspend the parent step. */
+	async function startSubWorkflow(workflowId, parentStep, childDefinition, childInput) {
+		await store.markStepWaiting(parentStep.id);
+		emit({
+			type: "step.waiting",
+			workflowId,
+			stepId: parentStep.id,
+			stepKey: parentStep.key,
+			stepType: parentStep.type
+		});
+		const started = await startWorkflow(childDefinition, childInput, {
+			parentWorkflowId: workflowId,
+			parentStepId: parentStep.id
+		});
+		if (!started.ok) {
+			logger.error("Failed to start sub-workflow", new Error(started.error.message), {
+				workflowId,
+				stepKey: parentStep.key
+			});
+			await failStepTerminal(workflowId, parentStep, `Sub-workflow start failed: ${started.error.message}`);
+			return;
+		}
+		logger.info("Sub-workflow started", {
+			workflowId,
+			parentKey: parentStep.key,
+			childWorkflowId: started.value.workflowId
+		});
+	}
+	/**
+	* A workflow reached a terminal state — if it's a sub-workflow child, settle its parent
+	* step: complete it with the child's output, or fail it (and cascade) on failure/cancel.
+	* Idempotent — a no-op unless the parent step is still `waiting`.
+	*/
+	async function bridgeSubWorkflow(childWorkflowId) {
+		const child = await store.getWorkflow(childWorkflowId);
+		if (!child || child.parentWorkflowId == null || child.parentStepId == null) return;
+		const parentStep = await store.getStep(child.parentStepId);
+		if (!parentStep || parentStep.status !== "waiting") return;
+		if (child.status === "completed") await onStepCompleted(child.parentWorkflowId, child.parentStepId, child.output ?? {});
+		else {
+			await markStepFailed(child.parentStepId, child.parentWorkflowId, `Sub-workflow ${child.status}${child.error ? `: ${child.error}` : ""}`);
+			await checkWorkflowFailure(child.parentWorkflowId);
+		}
+		logger.info("Bridged sub-workflow to parent step", {
+			childWorkflowId,
+			parentWorkflowId: child.parentWorkflowId,
+			status: child.status
+		});
+	}
+	/**
+	* Run each completed step's `compensate` handler in reverse dependency order to undo side
+	* effects after the workflow failed. Best-effort: one attempt per step, throws are logged and
+	* surfaced on the step (status `compensated` with the error). Steps without a handler are left.
+	*/
+	async function compensateWorkflow(workflowId) {
+		const workflow = await store.getWorkflow(workflowId);
+		if (!workflow) return;
+		const steps = await store.listSteps(workflowId);
+		const compensatable = steps.filter((s) => s.status === "completed" && registry.getRegistration(s.type)?.compensate);
+		if (compensatable.length === 0) return;
+		const byKey = new Map(steps.map((s) => [s.key, s]));
+		for (const step of reverseTopologicalOrder(compensatable)) {
+			const compensate = registry.getRegistration(step.type)?.compensate;
+			if (!compensate) continue;
+			await store.markStepCompensating(step.id);
+			emit({
+				type: "step.compensating",
+				workflowId,
+				workflowType: workflow.type,
+				stepId: step.id,
+				stepKey: step.key,
+				stepType: step.type
+			});
+			try {
+				const dependencyOutputs = {};
+				for (const depKey of step.dependencies ?? []) dependencyOutputs[depKey] = byKey.get(depKey)?.output ?? void 0;
+				const context = hooks.buildStepContext ? await hooks.buildStepContext({
+					workflowId,
+					stepId: step.id,
+					stepKey: step.key,
+					partitionKey,
+					workflow,
+					step
+				}) : void 0;
+				await compensate({
+					workflowId,
+					stepId: step.id,
+					stepKey: step.key,
+					partitionKey,
+					workflowInput: workflow.input ?? {},
+					stepInput: step.input ?? {},
+					dependencyOutputs,
+					context,
+					output: step.output ?? {}
+				});
+				await store.markStepCompensated(step.id);
+				logger.info("Compensated step", {
+					workflowId,
+					stepKey: step.key
+				});
+				emit({
+					type: "step.compensated",
+					workflowId,
+					workflowType: workflow.type,
+					stepId: step.id,
+					stepKey: step.key,
+					stepType: step.type
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "Unknown compensation error";
+				logger.error("Compensation failed", error instanceof Error ? error : new Error(message), {
+					workflowId,
+					stepKey: step.key
+				});
+				await store.markStepCompensated(step.id, `Compensation failed: ${message}`);
+				emit({
+					type: "step.compensated",
+					workflowId,
+					workflowType: workflow.type,
+					stepId: step.id,
+					stepKey: step.key,
+					stepType: step.type,
+					error: message
+				});
+			}
+		}
+	}
+	async function markStepFailed(stepId, workflowId, errorMessage) {
+		await store.failStep({
+			workflowId,
+			stepId,
+			error: errorMessage,
+			completedAt: nowIso()
+		});
+	}
+	async function checkWorkflowFailure(workflowId) {
+		for (;;) {
+			const steps = await store.listSteps(workflowId);
+			const blockedKeys = new Set(steps.filter((s) => s.status === "failed" || s.status === "skipped").map((s) => s.key));
+			const toSkip = steps.filter((s) => s.status === "pending" && (s.dependencies ?? []).some((dep) => blockedKeys.has(dep)));
+			if (toSkip.length === 0) break;
+			for (const s of toSkip) {
+				await store.skipStep(s.id, "Skipped due to failed dependency");
+				emit({
+					type: "step.skipped",
+					workflowId,
+					stepId: s.id,
+					stepKey: s.key,
+					stepType: s.type
+				});
+			}
+		}
+		const refreshed = await store.listSteps(workflowId);
+		if (refreshed.every((s) => [
+			"completed",
+			"failed",
+			"skipped"
+		].includes(s.status))) {
+			const firstFailed = refreshed.find((s) => s.status === "failed");
+			await store.finishWorkflow({
+				workflowId,
+				status: "failed",
+				error: firstFailed?.error ?? "One or more steps failed",
+				completedAt: nowIso()
+			});
+			logger.info("Workflow failed", { workflowId });
+			emit({
+				type: "workflow.failed",
+				workflowId,
+				error: firstFailed?.error ?? "One or more steps failed"
+			});
+			await compensateWorkflow(workflowId);
+			await bridgeSubWorkflow(workflowId);
+		}
+	}
+	async function cancelWorkflow(workflowId) {
+		const workflow = await store.getWorkflow(workflowId);
+		if (!workflow) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Workflow ${workflowId} not found`
+			}
+		};
+		if (workflow.status !== "pending" && workflow.status !== "running") return {
+			ok: true,
+			value: void 0
+		};
+		await store.skipPendingSteps(workflowId, "Workflow cancelled");
+		await store.finishWorkflow({
+			workflowId,
+			status: "cancelled",
+			completedAt: nowIso()
+		});
+		logger.info("Workflow cancelled", { workflowId });
+		emit({
+			type: "workflow.cancelled",
+			workflowId
+		});
+		await bridgeSubWorkflow(workflowId);
+		return {
+			ok: true,
+			value: void 0
+		};
+	}
+	async function getWorkflowStatus(workflowId) {
+		const workflow = await store.getWorkflow(workflowId);
+		if (!workflow) return {
+			ok: false,
+			error: {
+				key: "workflow_not_found",
+				message: `Workflow ${workflowId} not found`
+			}
+		};
+		const steps = await store.listSteps(workflowId);
+		return {
+			ok: true,
+			value: {
+				...workflow,
+				steps
+			}
+		};
+	}
+	async function listWorkflows(filters) {
+		return {
+			ok: true,
+			value: await store.listWorkflows({
+				...filters,
+				limit: filters?.limit ?? 50
+			})
+		};
+	}
+	async function handleStepExhausted(workflowId, stepId, errorMessage) {
+		const step = await store.getStep(stepId);
+		if (!step || step.workflowId !== workflowId || [
+			"completed",
+			"failed",
+			"skipped"
+		].includes(step.status)) return;
+		await markStepFailed(stepId, workflowId, errorMessage);
+		await checkWorkflowFailure(workflowId);
+	}
+	/**
+	* Recover workflows whose step is stuck in `running` past the dispatcher expiry
+	* (worker crashed between marking `running` and completing). Marks such steps
+	* failed and cascades the workflow to `failed`.
+	*/
+	async function recoverStuckWorkflows() {
+		const stuckThresholdSeconds = stepExpirySeconds + stuckStepBufferSeconds;
+		const cutoff = (/* @__PURE__ */ new Date(now().getTime() - stuckThresholdSeconds * 1e3)).toISOString();
+		const runningWorkflows = await store.listRunningWorkflows();
+		if (runningWorkflows.length === 0) return {
+			recoveredSteps: 0,
+			recoveredWorkflows: 0
+		};
+		let recoveredSteps = 0;
+		const affectedWorkflowIds = /* @__PURE__ */ new Set();
+		for (const workflow of runningWorkflows) {
+			const stuckSteps = await store.findStuckSteps(workflow.id, cutoff);
+			for (const step of stuckSteps) {
+				logger.warn("Recovering stuck workflow step", {
+					workflowId: workflow.id,
+					stepId: step.id,
+					stepKey: step.key,
+					startedAt: step.startedAt
+				});
+				await markStepFailed(step.id, workflow.id, `Step exceeded ${stuckThresholdSeconds}s without completion (worker likely crashed)`);
+				recoveredSteps++;
+				affectedWorkflowIds.add(workflow.id);
+			}
+		}
+		for (const workflowId of affectedWorkflowIds) await checkWorkflowFailure(workflowId);
+		return {
+			recoveredSteps,
+			recoveredWorkflows: affectedWorkflowIds.size
+		};
+	}
+	return {
+		validateDefinition,
+		startWorkflow,
+		start,
+		executeStep,
+		resumeStep,
+		handleStepExhausted,
+		recoverStuckWorkflows,
+		cancelWorkflow,
+		getWorkflowStatus,
+		listWorkflows
+	};
+}
+//#endregion
+//#region src/core/in-memory-store.ts
+/**
+* Reference `WorkflowStore` backed by plain Maps. Intended for tests and single-
+* process experimentation — NOT durable. Partition-scoped at construction to
+* mirror real adapters (the partition value is recorded but isolation is trivial
+* since each instance owns its own maps).
+*/
+function createInMemoryWorkflowStore(partitionKey = "default") {
+	const workflows = /* @__PURE__ */ new Map();
+	const steps = /* @__PURE__ */ new Map();
+	const byIdempotency = /* @__PURE__ */ new Map();
+	let workflowSeq = 0;
+	let stepSeq = 0;
+	const clone = (v) => v == null ? v : JSON.parse(JSON.stringify(v));
+	function stepsOf(workflowId) {
+		return Array.from(steps.values()).filter((s) => s.workflowId === workflowId);
+	}
+	async function createWorkflow(params) {
+		if (params.idempotencyKey != null) {
+			const existingId = byIdempotency.get(params.idempotencyKey);
+			if (existingId != null) return {
+				workflowId: existingId,
+				steps: stepsOf(existingId).map(clone),
+				alreadyExisted: true
+			};
+		}
+		const id = ++workflowSeq;
+		const record = {
+			id,
+			type: params.type,
+			status: "running",
+			partitionKey,
+			input: clone(params.input),
+			output: null,
+			error: null,
+			entityRef: params.entityRef ?? null,
+			idempotencyKey: params.idempotencyKey ?? null,
+			parentWorkflowId: params.parentWorkflowId ?? null,
+			parentStepId: params.parentStepId ?? null,
+			totalSteps: params.steps.length,
+			completedSteps: 0,
+			failedSteps: 0,
+			metadata: params.metadata ? clone(params.metadata) : null,
+			createdAt: params.startedAt,
+			startedAt: params.startedAt,
+			completedAt: null
+		};
+		workflows.set(id, record);
+		if (params.idempotencyKey != null) byIdempotency.set(params.idempotencyKey, id);
+		return {
+			workflowId: id,
+			steps: params.steps.map((s) => {
+				const stepId = ++stepSeq;
+				const stepRecord = {
+					id: stepId,
+					workflowId: id,
+					key: s.key,
+					type: s.type,
+					status: "pending",
+					dependencies: [...s.dependencies],
+					input: s.input ? clone(s.input) : null,
+					output: null,
+					error: null,
+					metadata: null,
+					attempts: 0,
+					parentStepId: null,
+					startedAt: null,
+					completedAt: null
+				};
+				steps.set(stepId, stepRecord);
+				return clone(stepRecord);
+			}),
+			alreadyExisted: false
+		};
+	}
+	async function getWorkflow(workflowId) {
+		const w = workflows.get(workflowId);
+		return w ? clone(w) : null;
+	}
+	async function getStep(stepId) {
+		const s = steps.get(stepId);
+		return s ? clone(s) : null;
+	}
+	async function listSteps(workflowId) {
+		return stepsOf(workflowId).map(clone);
+	}
+	async function markStepRunning(stepId, startedAt) {
+		const s = steps.get(stepId);
+		if (!s || s.status !== "pending") return false;
+		s.status = "running";
+		s.startedAt = startedAt;
+		s.attempts += 1;
+		return true;
+	}
+	async function markStepPending(stepId) {
+		const s = steps.get(stepId);
+		if (s) s.status = "pending";
+	}
+	async function markStepWaiting(stepId) {
+		const s = steps.get(stepId);
+		if (s) s.status = "waiting";
+	}
+	async function markStepMapping(stepId) {
+		const s = steps.get(stepId);
+		if (s) s.status = "mapping";
+	}
+	async function markStepCompensating(stepId) {
+		const s = steps.get(stepId);
+		if (s) s.status = "compensating";
+	}
+	async function markStepCompensated(stepId, error) {
+		const s = steps.get(stepId);
+		if (s) {
+			s.status = "compensated";
+			if (error != null) s.error = error;
+		}
+	}
+	async function addChildSteps(workflowId, parentStepId, children) {
+		const created = children.map((c) => {
+			const stepId = ++stepSeq;
+			const stepRecord = {
+				id: stepId,
+				workflowId,
+				key: c.key,
+				type: c.type,
+				status: "pending",
+				dependencies: [],
+				input: c.input ? clone(c.input) : null,
+				output: null,
+				error: null,
+				metadata: null,
+				attempts: 0,
+				parentStepId,
+				startedAt: null,
+				completedAt: null
+			};
+			steps.set(stepId, stepRecord);
+			return clone(stepRecord);
+		});
+		const w = workflows.get(workflowId);
+		if (w) w.totalSteps += created.length;
+		return created;
+	}
+	async function listChildSteps(parentStepId) {
+		return Array.from(steps.values()).filter((s) => s.parentStepId === parentStepId).sort((a, b) => a.id - b.id).map(clone);
+	}
+	async function completeStep(params) {
+		const s = steps.get(params.stepId);
+		if (s) {
+			s.status = "completed";
+			s.output = clone(params.output);
+			s.completedAt = params.completedAt;
+		}
+		const w = workflows.get(params.workflowId);
+		if (w) w.completedSteps += 1;
+	}
+	async function failStep(params) {
+		const s = steps.get(params.stepId);
+		if (s) {
+			s.status = "failed";
+			s.error = params.error;
+			s.completedAt = params.completedAt;
+		}
+		const w = workflows.get(params.workflowId);
+		if (w) w.failedSteps += 1;
+	}
+	async function skipStep(stepId, reason) {
+		const s = steps.get(stepId);
+		if (s) {
+			s.status = "skipped";
+			s.error = reason;
+		}
+	}
+	async function skipPendingSteps(workflowId, reason) {
+		for (const s of stepsOf(workflowId)) if (s.status === "pending" || s.status === "waiting") {
+			s.status = "skipped";
+			s.error = reason;
+		}
+	}
+	async function finishWorkflow(params) {
+		const w = workflows.get(params.workflowId);
+		if (!w) return;
+		w.status = params.status;
+		w.completedAt = params.completedAt;
+		if (params.output !== void 0) w.output = clone(params.output);
+		if (params.error !== void 0) w.error = params.error;
+	}
+	async function listWorkflows(filters) {
+		let result = Array.from(workflows.values());
+		if (filters.status) result = result.filter((w) => w.status === filters.status);
+		if (filters.type) result = result.filter((w) => w.type === filters.type);
+		if (filters.entityRef) result = result.filter((w) => w.entityRef === filters.entityRef);
+		result = result.sort((a, b) => b.id - a.id).slice(0, filters.limit ?? 50);
+		return result.map((w) => ({
+			...clone(w),
+			steps: stepsOf(w.id).map(clone)
+		}));
+	}
+	async function listRunningWorkflows() {
+		return Array.from(workflows.values()).filter((w) => w.status === "running").map(clone);
+	}
+	async function findStuckSteps(workflowId, cutoff) {
+		return stepsOf(workflowId).filter((s) => s.status === "running" && s.startedAt != null && s.startedAt < cutoff).map(clone);
+	}
+	return {
+		createWorkflow,
+		getWorkflow,
+		getStep,
+		listSteps,
+		markStepRunning,
+		markStepPending,
+		markStepWaiting,
+		markStepMapping,
+		markStepCompensating,
+		markStepCompensated,
+		addChildSteps,
+		listChildSteps,
+		completeStep,
+		failStep,
+		skipStep,
+		skipPendingSteps,
+		finishWorkflow,
+		listWorkflows,
+		listRunningWorkflows,
+		findStuckSteps,
+		_dump() {
+			return {
+				workflows: Array.from(workflows.values()).map(clone),
+				steps: Array.from(steps.values()).map(clone)
+			};
+		}
+	};
+}
+//#endregion
+export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, createInMemoryStepGate, createInMemoryWorkflowStore, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };