alepha 0.19.2 → 0.19.4

package/dist/api/workflows/index.js

@@ -0,0 +1,1504 @@
+import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, Primitive, createPrimitive, t } from "alepha";
+import { $job, AlephaApiJobs } from "alepha/api/jobs";
+import { AlephaLock, LockProvider } from "alepha/lock";
+import { $secure } from "alepha/security";
+import { $action, NotFoundError, okSchema } from "alepha/server";
+import { $entity, $repository, DatabaseProvider, db, pageQuerySchema, sql } from "alepha/orm";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger, logEntrySchema } from "alepha/logger";
+//#region ../../src/api/workflows/schemas/workflowActivitySchema.ts
+const workflowActivityPointSchema = t.object({
+	date: t.text(),
+	completed: t.integer(),
+	failed: t.integer()
+});
+const workflowActivityQuerySchema = t.object({ days: t.optional(t.integer({
+	minimum: 1,
+	maximum: 90
+})) });
+//#endregion
+//#region ../../src/api/workflows/entities/workflowExecutions.ts
+const workflowExecutions = $entity({
+	name: "workflow_executions",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		workflowName: t.text(),
+		tags: t.optional(t.array(t.text())),
+		payload: t.optional(t.record(t.text(), t.any())),
+		status: db.default(t.enum([
+			"pending",
+			"running",
+			"waiting_for_signal",
+			"completed",
+			"failed",
+			"timed_out",
+			"compensating",
+			"compensated",
+			"compensation_failed",
+			"cancelled"
+		]), "pending"),
+		currentStep: t.optional(t.text()),
+		startedAt: t.optional(t.datetime()),
+		completedAt: t.optional(t.datetime()),
+		deadlineAt: t.optional(t.datetime()),
+		error: t.optional(t.text()),
+		errorStep: t.optional(t.text()),
+		triggeredBy: t.optional(t.text()),
+		triggeredByName: t.optional(t.text()),
+		cancelledBy: t.optional(t.text()),
+		cancelledByName: t.optional(t.text()),
+		key: t.optional(t.nullable(t.text())),
+		priority: db.default(t.integer({
+			minimum: 0,
+			maximum: 3
+		}), 2)
+	}),
+	indexes: [
+		{ columns: ["workflowName", "status"] },
+		{ columns: [
+			"workflowName",
+			"status",
+			"createdAt"
+		] },
+		{
+			columns: ["workflowName", "key"],
+			unique: true,
+			where: sql`status NOT IN ('completed', 'failed', 'compensated', 'compensation_failed', 'cancelled')`
+		},
+		{ columns: ["status", "deadlineAt"] },
+		{ columns: ["completedAt"] }
+	]
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowExecutionResourceSchema.ts
+const workflowExecutionCanSchema = t.object({
+	retry: t.boolean(),
+	cancel: t.boolean(),
+	compensate: t.boolean(),
+	restart: t.boolean(),
+	signal: t.optional(t.object({
+		stepName: t.text(),
+		schema: t.optional(t.any())
+	}))
+});
+const workflowExecutionResourceSchema = t.extend(workflowExecutions.schema, { can: workflowExecutionCanSchema }, {
+	title: "WorkflowExecutionResource",
+	description: "A workflow execution resource."
+});
+//#endregion
+//#region ../../src/api/workflows/entities/workflowStepExecutions.ts
+const workflowStepExecutions = $entity({
+	name: "workflow_step_executions",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		createdAt: db.createdAt(),
+		updatedAt: db.updatedAt(),
+		workflowExecutionId: db.ref(t.uuid(), () => workflowExecutions.cols.id, { onDelete: "cascade" }),
+		stepName: t.text(),
+		stepIndex: t.integer(),
+		stepType: db.default(t.enum([
+			"handler",
+			"signal",
+			"parallel"
+		]), "handler"),
+		parentStepId: t.optional(t.uuid()),
+		branchName: t.optional(t.text()),
+		status: db.default(t.enum([
+			"pending",
+			"running",
+			"completed",
+			"failed",
+			"skipped",
+			"waiting",
+			"compensating",
+			"compensated",
+			"compensation_failed",
+			"cancelled"
+		]), "pending"),
+		attempt: db.default(t.integer(), 0),
+		maxAttempts: db.default(t.integer(), 1),
+		result: t.optional(t.record(t.text(), t.any())),
+		error: t.optional(t.text()),
+		startedAt: t.optional(t.datetime()),
+		completedAt: t.optional(t.datetime()),
+		deadlineAt: t.optional(t.datetime()),
+		signalPayload: t.optional(t.record(t.text(), t.any())),
+		signalledBy: t.optional(t.text()),
+		signalledAt: t.optional(t.datetime())
+	}),
+	indexes: [
+		{ columns: ["workflowExecutionId", "stepName"] },
+		{ columns: ["workflowExecutionId", "stepIndex"] },
+		{ columns: ["workflowExecutionId", "status"] },
+		{ columns: ["status", "deadlineAt"] }
+	]
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowStepExecutionResourceSchema.ts
+const workflowStepExecutionResourceSchema = t.extend(workflowStepExecutions.schema, {}, {
+	title: "WorkflowStepExecutionResource",
+	description: "A workflow step execution resource."
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowExecutionDetailSchema.ts
+const workflowExecutionDetailSchema = t.extend(workflowExecutionResourceSchema, { steps: t.array(workflowStepExecutionResourceSchema) }, {
+	title: "WorkflowExecutionDetail",
+	description: "A workflow execution with step details."
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowExecutionQuerySchema.ts
+const workflowExecutionQuerySchema = t.extend(pageQuerySchema, {
+	workflow: t.optional(t.text({ description: "Filter by workflow name" })),
+	status: t.optional(t.enum([
+		"pending",
+		"running",
+		"waiting_for_signal",
+		"completed",
+		"failed",
+		"timed_out",
+		"compensating",
+		"compensated",
+		"compensation_failed",
+		"cancelled"
+	])),
+	from: t.optional(t.datetime({ description: "From date (ISO)" })),
+	to: t.optional(t.datetime({ description: "To date (ISO)" }))
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowRegistrationSchema.ts
+const workflowRegistrationSchema = t.object({
+	name: t.text(),
+	stepCount: t.integer(),
+	steps: t.array(t.object({
+		name: t.text(),
+		type: t.enum([
+			"handler",
+			"signal",
+			"parallel"
+		]),
+		hasCompensate: t.boolean(),
+		hasRetry: t.boolean(),
+		timeout: t.optional(t.text())
+	})),
+	onError: t.enum(["compensate", "fail"]),
+	timeout: t.optional(t.text()),
+	priority: t.text(),
+	tags: t.optional(t.array(t.text())),
+	paused: t.boolean(),
+	running: t.integer(),
+	pending: t.integer(),
+	waiting: t.integer(),
+	failed: t.integer()
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowStatsSchema.ts
+const workflowStatsSchema = t.object({
+	registered: t.integer(),
+	running: t.integer(),
+	pending: t.integer(),
+	waiting: t.integer(),
+	completed: t.integer(),
+	failed: t.integer(),
+	compensated: t.integer(),
+	compensationFailed: t.integer(),
+	cancelled: t.integer(),
+	timedOut: t.integer()
+});
+//#endregion
+//#region ../../src/api/workflows/entities/workflowStepLogs.ts
+const workflowStepLogs = $entity({
+	name: "workflow_step_logs",
+	schema: t.object({
+		id: db.primaryKey(t.uuid()),
+		logs: t.array(logEntrySchema)
+	})
+});
+//#endregion
+//#region ../../src/api/workflows/schemas/workflowConfigAtom.ts
+const workflowConfig = $atom({
+	name: "alepha.workflows",
+	description: "Configuration for the workflow engine.",
+	schema: t.object({
+		defaultStepTimeout: t.integer({ description: "Default step timeout (ms). Used when no per-step timeout is set." }),
+		retentionDays: t.integer({ description: "Days to keep completed/failed workflow executions." }),
+		recovery: t.object({ staleThreshold: t.integer({ description: "Running step age (ms) before assumed crashed." }) }),
+		maxConcurrentWorkflows: t.integer({ description: "Max concurrent running instances per workflow name." }),
+		maxStepsPerWorkflow: t.integer({ description: "Safety limit on step count." }),
+		drainTimeout: t.integer({ description: "Max time (ms) to wait for in-flight steps during shutdown." }),
+		logMaxEntries: t.integer({ description: "Max log entries captured per step execution." })
+	}),
+	default: {
+		defaultStepTimeout: 3e5,
+		retentionDays: 30,
+		recovery: { staleThreshold: 18e5 },
+		maxConcurrentWorkflows: 50,
+		maxStepsPerWorkflow: 100,
+		drainTimeout: 3e4,
+		logMaxEntries: 100
+	}
+});
+//#endregion
+//#region ../../src/api/workflows/providers/WorkflowProvider.ts
+const PRIORITY_MAP = {
+	critical: 0,
+	high: 1,
+	normal: 2,
+	low: 3
+};
+var WorkflowProvider = class {
+	alepha = $inject(Alepha);
+	dt = $inject(DateTimeProvider);
+	lockProvider = $inject(LockProvider);
+	config = $state(workflowConfig);
+	log = $logger();
+	executions = $repository(workflowExecutions);
+	stepExecutions = $repository(workflowStepExecutions);
+	stepLogs = $repository(workflowStepLogs);
+	workflows = /* @__PURE__ */ new Map();
+	pausedWorkflows = /* @__PURE__ */ new Set();
+	inFlight = /* @__PURE__ */ new Set();
+	abortControllers = /* @__PURE__ */ new Map();
+	logs = /* @__PURE__ */ new Map();
+	stopping = false;
+	/**
+	* When set, step dispatches go through a queue.
+	* Set by WorkflowJobs on start.
+	*/
+	stepDispatch = null;
+	register(primitive) {
+		if (this.workflows.has(primitive.name)) throw new AlephaError(`Workflow already registered: ${primitive.name}`);
+		this.workflows.set(primitive.name, {
+			name: primitive.name,
+			options: primitive.options
+		});
+		this.log.debug(`Registered workflow '${primitive.name}'`, { steps: primitive.options.steps.length });
+	}
+	getRegisteredWorkflows() {
+		return this.workflows;
+	}
+	async start(workflowName, payload, options) {
+		const opts = this.getRegistration(workflowName).options;
+		const validated = this.alepha.codec.validate(opts.schema, payload);
+		const priority = PRIORITY_MAP[options?.priority ?? opts.priority ?? "normal"];
+		const status = options?.delay ? "pending" : "running";
+		let deadlineAt;
+		if (opts.timeout) deadlineAt = this.dt.now().add(this.dt.duration(opts.timeout)).toISOString();
+		if (options?.key) {
+			const existing = await this.executions.findMany({
+				where: {
+					workflowName: { eq: workflowName },
+					key: { eq: options.key },
+					status: { inArray: [
+						"pending",
+						"running",
+						"waiting_for_signal",
+						"compensating"
+					] }
+				},
+				limit: 1
+			});
+			if (existing.length > 0) return existing[0].id;
+		}
+		const execution = await this.executions.create({
+			workflowName,
+			payload: validated,
+			status,
+			priority,
+			deadlineAt,
+			key: options?.key,
+			triggeredBy: options?.triggeredBy,
+			triggeredByName: options?.triggeredByName,
+			tags: options?.tags ?? opts.tags,
+			startedAt: status === "running" ? this.dt.nowISOString() : void 0
+		});
+		for (let i = 0; i < opts.steps.length; i++) {
+			const step = opts.steps[i];
+			const retryOpts = step.retry;
+			await this.stepExecutions.create({
+				workflowExecutionId: execution.id,
+				stepName: step.name,
+				stepIndex: i,
+				stepType: step.type ?? "handler",
+				status: "pending",
+				maxAttempts: (retryOpts?.retries ?? 0) + 1
+			});
+		}
+		this.log.info(`Started workflow '${workflowName}'`, {
+			workflowId: execution.id,
+			steps: opts.steps.length
+		});
+		await this.alepha.events.emit("workflow:started", {
+			workflowName,
+			workflowId: execution.id
+		}, { catch: true });
+		if (status === "running" && !this.stopping) {
+			const firstStep = opts.steps[0];
+			if (firstStep) await this.dispatchStep(execution.id, firstStep.name, priority);
+			else await this.executions.updateById(execution.id, {
+				status: "completed",
+				completedAt: this.dt.nowISOString()
+			});
+		}
+		return execution.id;
+	}
+	async processStep(workflowId, stepName) {
+		const promise = this.processStepInner(workflowId, stepName);
+		this.inFlight.add(promise);
+		try {
+			await promise;
+		} finally {
+			this.inFlight.delete(promise);
+		}
+	}
+	async processStepInner(workflowId, stepName) {
+		const lockKey = `workflow:${workflowId}`;
+		const lockValue = `${crypto.randomUUID()},${this.dt.nowISOString()}`;
+		const [lockId] = (await this.lockProvider.set(lockKey, lockValue, true, 6e5)).split(",");
+		if (lockId !== lockValue.split(",")[0]) {
+			this.log.debug(`Workflow ${workflowId} locked by another worker, skipping`);
+			return;
+		}
+		try {
+			const workflow = await this.executions.findById(workflowId);
+			if (!workflow) return;
+			if (workflow.status !== "running" && workflow.status !== "pending") return;
+			if (workflow.status === "pending") await this.executions.updateById(workflowId, {
+				status: "running",
+				startedAt: this.dt.nowISOString()
+			});
+			const stepDef = this.getRegistration(workflow.workflowName).options.steps.find((s) => s.name === stepName);
+			if (!stepDef) return;
+			const stepExec = await this.findStepExecution(workflowId, stepName);
+			if (!stepExec) return;
+			if (stepExec.status !== "pending") return;
+			if (stepDef.when) {
+				const results = await this.assembleResults(workflowId);
+				if (!await stepDef.when({
+					payload: workflow.payload,
+					results
+				})) {
+					await this.stepExecutions.updateById(stepExec.id, {
+						status: "skipped",
+						completedAt: this.dt.nowISOString()
+					});
+					await this.alepha.events.emit("workflow:step:skipped", {
+						workflowName: workflow.workflowName,
+						workflowId,
+						stepName
+					}, { catch: true });
+					await this.advance(workflowId);
+					return;
+				}
+			}
+			await this.executeHandlerStep(workflow, stepExec, stepDef);
+		} finally {
+			await this.lockProvider.del(lockKey);
+		}
+	}
+	async executeHandlerStep(workflow, stepExec, stepDef) {
+		const workflowId = workflow.id;
+		const stepName = stepExec.stepName;
+		await this.stepExecutions.updateById(stepExec.id, {
+			status: "running",
+			attempt: stepExec.attempt + 1,
+			startedAt: this.dt.nowISOString()
+		});
+		await this.executions.updateById(workflowId, { currentStep: stepName });
+		await this.alepha.events.emit("workflow:step:begin", {
+			workflowName: workflow.workflowName,
+			workflowId,
+			stepName
+		}, { catch: true });
+		const abortController = new AbortController();
+		const abortKey = `${workflowId}:${stepName}`;
+		this.abortControllers.set(abortKey, abortController);
+		const timeoutMs = stepDef.timeout ? this.dt.duration(stepDef.timeout).as("milliseconds") : this.config.defaultStepTimeout;
+		const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+		const context = this.alepha.context.createContextId();
+		this.logs.set(context, []);
+		try {
+			await this.alepha.context.run(async () => {
+				const results = await this.assembleResults(workflowId);
+				const handlerResult = await stepDef.handler({
+					payload: workflow.payload,
+					results,
+					context: {
+						workflowId,
+						executionId: stepExec.id,
+						stepName,
+						attempt: stepExec.attempt + 1
+					},
+					signal: abortController.signal
+				});
+				await this.stepExecutions.updateById(stepExec.id, {
+					status: "completed",
+					result: handlerResult != null ? handlerResult : void 0,
+					completedAt: this.dt.nowISOString()
+				});
+				await this.writeLogs(stepExec.id, context);
+				this.log.info(`Workflow step '${stepName}' completed`, { workflowId });
+				await this.alepha.events.emit("workflow:step:completed", {
+					workflowName: workflow.workflowName,
+					workflowId,
+					stepName,
+					result: handlerResult
+				}, { catch: true });
+				await this.advance(workflowId);
+			}, { context });
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			await this.writeLogs(stepExec.id, context);
+			if (abortController.signal.aborted) await this.handleStepFailure(workflow, stepExec, stepDef, /* @__PURE__ */ new Error("Step timed out"), context);
+			else await this.handleStepFailure(workflow, stepExec, stepDef, err, context);
+		} finally {
+			clearTimeout(timeoutId);
+			this.abortControllers.delete(abortKey);
+			this.logs.delete(context);
+		}
+	}
+	async handleStepFailure(workflow, stepExec, stepDef, error, _context) {
+		const retryOpts = stepDef.retry;
+		if (retryOpts && stepExec.attempt + 1 < stepExec.maxAttempts && (retryOpts.when ? retryOpts.when(error) : true)) {
+			const nextScheduledAt = this.computeBackoff(retryOpts, stepExec.attempt + 1);
+			this.log.info(`Workflow step '${stepExec.stepName}' failed, scheduling retry`, {
+				workflowId: workflow.id,
+				error: error.message
+			});
+			await this.stepExecutions.updateById(stepExec.id, {
+				status: "pending",
+				error: error.message,
+				deadlineAt: nextScheduledAt
+			});
+			const delayMs = Math.max(0, new Date(nextScheduledAt).getTime() - this.dt.nowMillis());
+			this.dt.createTimeout(() => void this.dispatchStep(workflow.id, stepExec.stepName, workflow.priority), delayMs);
+		} else {
+			this.log.info(`Workflow step '${stepExec.stepName}' failed permanently`, {
+				workflowId: workflow.id,
+				error: error.message
+			});
+			await this.stepExecutions.updateById(stepExec.id, {
+				status: "failed",
+				error: error.message,
+				completedAt: this.dt.nowISOString()
+			});
+			await this.alepha.events.emit("workflow:step:failed", {
+				workflowName: workflow.workflowName,
+				workflowId: workflow.id,
+				stepName: stepExec.stepName,
+				error
+			}, { catch: true });
+			if ((this.getRegistration(workflow.workflowName).options.onError ?? "compensate") === "compensate") await this.compensate(workflow.id, {
+				failedStep: stepExec.stepName,
+				error
+			});
+			else {
+				await this.executions.updateById(workflow.id, {
+					status: "failed",
+					error: error.message,
+					errorStep: stepExec.stepName,
+					completedAt: this.dt.nowISOString()
+				});
+				await this.alepha.events.emit("workflow:failed", {
+					workflowName: workflow.workflowName,
+					workflowId: workflow.id,
+					error,
+					stepName: stepExec.stepName
+				}, { catch: true });
+			}
+		}
+	}
+	async advance(workflowId) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow || workflow.status !== "running") return;
+		this.getRegistration(workflow.workflowName);
+		const nextStep = (await this.stepExecutions.findMany({
+			where: { workflowExecutionId: { eq: workflowId } },
+			orderBy: {
+				column: "stepIndex",
+				direction: "asc"
+			}
+		})).find((s) => s.status === "pending");
+		if (nextStep) {
+			await this.executions.updateById(workflowId, { currentStep: nextStep.stepName });
+			await this.dispatchStep(workflowId, nextStep.stepName, workflow.priority);
+		} else {
+			await this.executions.updateById(workflowId, {
+				status: "completed",
+				currentStep: void 0,
+				completedAt: this.dt.nowISOString(),
+				key: null
+			});
+			this.log.info(`Workflow '${workflow.workflowName}' completed`, { workflowId });
+			await this.alepha.events.emit("workflow:completed", {
+				workflowName: workflow.workflowName,
+				workflowId
+			}, { catch: true });
+		}
+	}
+	async compensate(workflowId, context) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		const registration = this.getRegistration(workflow.workflowName);
+		await this.executions.updateById(workflowId, {
+			status: "compensating",
+			error: context?.error?.message,
+			errorStep: context?.failedStep
+		});
+		await this.alepha.events.emit("workflow:compensating", {
+			workflowName: workflow.workflowName,
+			workflowId,
+			stepName: context?.failedStep ?? ""
+		}, { catch: true });
+		const completedSteps = await this.stepExecutions.findMany({
+			where: {
+				workflowExecutionId: { eq: workflowId },
+				status: { eq: "completed" }
+			},
+			orderBy: {
+				column: "stepIndex",
+				direction: "desc"
+			}
+		});
+		const results = await this.assembleResults(workflowId);
+		for (const stepExec of completedSteps) {
+			const stepDef = registration.options.steps.find((s) => s.name === stepExec.stepName);
+			if (!stepDef?.compensate) continue;
+			await this.stepExecutions.updateById(stepExec.id, { status: "compensating" });
+			try {
+				await stepDef.compensate({
+					payload: workflow.payload,
+					result: stepExec.result,
+					results,
+					context: {
+						workflowId,
+						executionId: stepExec.id,
+						stepName: stepExec.stepName,
+						error: context?.error ?? /* @__PURE__ */ new Error("Compensation triggered")
+					}
+				});
+				await this.stepExecutions.updateById(stepExec.id, {
+					status: "compensated",
+					completedAt: this.dt.nowISOString()
+				});
+			} catch (compError) {
+				const err = compError instanceof Error ? compError : new Error(String(compError));
+				this.log.error(`Compensation failed for step '${stepExec.stepName}'`, {
+					workflowId,
+					error: err.message
+				});
+				await this.stepExecutions.updateById(stepExec.id, {
+					status: "compensation_failed",
+					error: err.message
+				});
+				await this.executions.updateById(workflowId, {
+					status: "compensation_failed",
+					completedAt: this.dt.nowISOString(),
+					key: null
+				});
+				await this.alepha.events.emit("workflow:compensation:failed", {
+					workflowName: workflow.workflowName,
+					workflowId,
+					stepName: stepExec.stepName,
+					error: err
+				}, { catch: true });
+				return;
+			}
+		}
+		await this.executions.updateById(workflowId, {
+			status: "compensated",
+			completedAt: this.dt.nowISOString(),
+			key: null
+		});
+		this.log.info(`Workflow '${workflow.workflowName}' compensated`, { workflowId });
+		await this.alepha.events.emit("workflow:compensated", {
+			workflowName: workflow.workflowName,
+			workflowId
+		}, { catch: true });
+	}
+	async cancel(workflowId, options) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		if (workflow.status !== "pending" && workflow.status !== "running" && workflow.status !== "waiting_for_signal") throw new AlephaError(`Cannot cancel workflow in '${workflow.status}' status`);
+		for (const [key, controller] of this.abortControllers) if (key.startsWith(`${workflowId}:`)) controller.abort();
+		const pendingSteps = await this.stepExecutions.findMany({ where: {
+			workflowExecutionId: { eq: workflowId },
+			status: { inArray: ["pending", "waiting"] }
+		} });
+		for (const step of pendingSteps) await this.stepExecutions.updateById(step.id, { status: "cancelled" });
+		if (options?.compensate) {
+			await this.compensate(workflowId, { error: /* @__PURE__ */ new Error("Cancelled with compensation") });
+			await this.executions.updateById(workflowId, {
+				status: "cancelled",
+				cancelledBy: options?.cancelledBy,
+				cancelledByName: options?.cancelledByName
+			});
+		} else await this.executions.updateById(workflowId, {
+			status: "cancelled",
+			cancelledBy: options?.cancelledBy,
+			cancelledByName: options?.cancelledByName,
+			completedAt: this.dt.nowISOString(),
+			key: null
+		});
+		this.log.info(`Workflow cancelled`, { workflowId });
+		await this.alepha.events.emit("workflow:cancelled", {
+			workflowName: workflow.workflowName,
+			workflowId
+		}, { catch: true });
+	}
+	/**
+	* Send a signal to a waiting workflow step.
+	*/
+	async signal(workflowId, stepName, payload, signalledBy) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		if (workflow.status !== "waiting_for_signal") throw new AlephaError(`Cannot signal workflow in '${workflow.status}' status`);
+		const stepExec = await this.findStepExecution(workflowId, stepName);
+		if (!stepExec) throw new AlephaError(`Step '${stepName}' not found on workflow ${workflowId}`);
+		if (stepExec.status !== "waiting") throw new AlephaError(`Step '${stepName}' is in '${stepExec.status}' status, expected 'waiting'`);
+		await this.stepExecutions.updateById(stepExec.id, {
+			status: "completed",
+			signalPayload: payload != null ? payload : void 0,
+			signalledBy,
+			signalledAt: this.dt.nowISOString(),
+			completedAt: this.dt.nowISOString()
+		});
+		await this.executions.updateById(workflowId, { status: "running" });
+		this.log.info(`Workflow signalled step '${stepName}'`, { workflowId });
+		await this.advance(workflowId);
+	}
+	async retry(workflowId) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		if (workflow.status !== "failed" && workflow.status !== "timed_out") throw new AlephaError(`Cannot retry workflow in '${workflow.status}' status. Use restart() for compensated workflows.`);
+		const failedStep = await this.stepExecutions.findMany({
+			where: {
+				workflowExecutionId: { eq: workflowId },
+				status: { eq: "failed" }
+			},
+			limit: 1
+		});
+		if (failedStep.length === 0) throw new AlephaError("No failed step found to retry");
+		await this.stepExecutions.updateById(failedStep[0].id, {
+			status: "pending",
+			error: void 0,
+			startedAt: void 0,
+			completedAt: void 0
+		});
+		await this.executions.updateById(workflowId, {
+			status: "running",
+			error: void 0,
+			errorStep: void 0,
+			completedAt: void 0
+		});
+		await this.dispatchStep(workflowId, failedStep[0].stepName, workflow.priority);
+	}
+	async restart(workflowId) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		if (workflow.status !== "compensated" && workflow.status !== "compensation_failed" && workflow.status !== "failed") throw new AlephaError(`Cannot restart workflow in '${workflow.status}' status`);
+		return this.start(workflow.workflowName, workflow.payload);
+	}
+	async getExecution(workflowId) {
+		const workflow = await this.executions.findById(workflowId);
+		if (!workflow) throw new AlephaError(`Workflow not found: ${workflowId}`);
+		const steps = await this.stepExecutions.findMany({
+			where: { workflowExecutionId: { eq: workflowId } },
+			orderBy: {
+				column: "stepIndex",
+				direction: "asc"
+			}
+		});
+		return {
+			...workflow,
+			steps
+		};
+	}
+	pauseWorkflow(name) {
+		this.getRegistration(name);
+		this.pausedWorkflows.add(name);
+		this.log.info(`Paused workflow '${name}'`);
+	}
+	async resumeWorkflow(name) {
+		this.getRegistration(name);
+		this.pausedWorkflows.delete(name);
+		this.log.info(`Resumed workflow '${name}'`);
+	}
+	isWorkflowPaused(name) {
+		return this.pausedWorkflows.has(name);
+	}
+	getPausedWorkflows() {
+		return [...this.pausedWorkflows];
+	}
+	async dispatchStep(workflowId, stepName, priority) {
+		if (this.stopping) return;
+		if (this.stepDispatch) await this.stepDispatch(workflowId, stepName, priority);
+		else await this.processStep(workflowId, stepName);
+	}
+	async assembleResults(workflowId) {
+		const completed = await this.stepExecutions.findMany({
+			where: {
+				workflowExecutionId: { eq: workflowId },
+				status: { eq: "completed" }
+			},
+			orderBy: {
+				column: "stepIndex",
+				direction: "asc"
+			}
+		});
+		const results = {};
+		for (const step of completed) if (step.result) results[step.stepName] = step.result;
+		return results;
+	}
+	async findStepExecution(workflowId, stepName) {
+		return (await this.stepExecutions.findMany({
+			where: {
+				workflowExecutionId: { eq: workflowId },
+				stepName: { eq: stepName }
+			},
+			limit: 1
+		}))[0];
+	}
+	computeBackoff(retryOpts, attempt) {
+		const now = this.dt.now();
+		if (!retryOpts.backoff) return now.add(1, "second").toISOString();
+		if (Array.isArray(retryOpts.backoff)) {
+			const delay = this.dt.duration(retryOpts.backoff);
+			return now.add(delay).toISOString();
+		}
+		const backoff = retryOpts.backoff;
+		let delayMs = this.dt.duration(backoff.initial).as("milliseconds") * (backoff.factor ?? 2) ** (attempt - 1);
+		if (backoff.max) {
+			const maxMs = this.dt.duration(backoff.max).as("milliseconds");
+			delayMs = Math.min(delayMs, maxMs);
+		}
+		if (backoff.jitter) delayMs = delayMs * (.75 + Math.random() * .5);
+		return now.add(delayMs, "millisecond").toISOString();
+	}
+	async writeLogs(stepExecutionId, context) {
+		const entries = this.logs.get(context);
+		if (!entries || entries.length === 0) return;
+		const maxEntries = this.config.logMaxEntries;
+		if (maxEntries === 0) return;
+		let logs = entries;
+		if (logs.length > maxEntries) {
+			logs = logs.slice(0, maxEntries);
+			logs.push({
+				level: "WARN",
+				message: `Log entries truncated at ${maxEntries}`,
+				timestamp: this.dt.nowMillis(),
+				service: "alepha.workflows",
+				module: "WorkflowProvider"
+			});
+		}
+		try {
+			await this.stepLogs.create({
+				id: stepExecutionId,
+				logs
+			});
+		} catch {
+			this.log.warn(`Failed to write logs for step ${stepExecutionId}`);
+		}
+	}
+	getRegistration(name) {
+		const reg = this.workflows.get(name);
+		if (!reg) throw new AlephaError(`Workflow not registered: ${name}`);
+		return reg;
+	}
+	async recoverySweep() {
+		if (this.stopping) return;
+		const lockValue = `${crypto.randomUUID()},${this.dt.nowISOString()}`;
+		if ((await this.lockProvider.set("_alepha:workflows:recovery-lock", lockValue, true, 3e5)).split(",")[0] !== lockValue.split(",")[0]) return;
+		try {
+			const staleThreshold = this.dt.now().subtract(this.config.recovery.staleThreshold, "millisecond").toISOString();
+			const staleSteps = await this.stepExecutions.findMany({ where: {
+				status: { eq: "running" },
+				startedAt: { lte: staleThreshold }
+			} });
+			for (const step of staleSteps) {
+				if (this.abortControllers.has(`${step.workflowExecutionId}:${step.stepName}`)) continue;
+				this.log.warn(`Recovery sweep: marking stale step '${step.stepName}' as failed`, { workflowId: step.workflowExecutionId });
+				await this.stepExecutions.updateById(step.id, {
+					status: "failed",
+					error: "Step assumed crashed (recovered by sweep)",
+					completedAt: this.dt.nowISOString()
+				});
+				const workflow = await this.executions.findById(step.workflowExecutionId);
+				if (!workflow) continue;
+				const registration = this.workflows.get(workflow.workflowName);
+				if (!registration) continue;
+				if ((registration.options.onError ?? "compensate") === "compensate") await this.compensate(workflow.id, {
+					failedStep: step.stepName,
+					error: /* @__PURE__ */ new Error("Step assumed crashed")
+				});
+				else await this.executions.updateById(workflow.id, {
+					status: "failed",
+					error: "Step assumed crashed",
+					errorStep: step.stepName,
+					completedAt: this.dt.nowISOString()
+				});
+			}
+			const runningWorkflows = await this.executions.findMany({ where: { status: { eq: "running" } } });
+			for (const wf of runningWorkflows) if ((await this.stepExecutions.findMany({
+				where: {
+					workflowExecutionId: { eq: wf.id },
+					status: { inArray: ["running", "pending"] }
+				},
+				limit: 1
+			})).length === 0) {
+				this.log.warn("Recovery sweep: re-advancing inconsistent workflow", { workflowId: wf.id });
+				await this.advance(wf.id);
+			}
+		} catch (e) {
+			this.log.error("Recovery sweep failed", { error: e });
+		} finally {
+			await this.lockProvider.del("_alepha:workflows:recovery-lock");
+		}
+	}
+	async timeoutSweep() {
+		if (this.stopping) return;
+		const lockValue = `${crypto.randomUUID()},${this.dt.nowISOString()}`;
+		if ((await this.lockProvider.set("_alepha:workflows:timeout-lock", lockValue, true, 6e4)).split(",")[0] !== lockValue.split(",")[0]) return;
+		try {
+			const now = this.dt.nowISOString();
+			const timedOutWorkflows = await this.executions.findMany({ where: {
+				status: { inArray: ["running", "waiting_for_signal"] },
+				deadlineAt: { lte: now }
+			} });
+			for (const wf of timedOutWorkflows) {
+				this.log.warn(`Timeout sweep: workflow timed out`, { workflowId: wf.id });
+				for (const [key, controller] of this.abortControllers) if (key.startsWith(`${wf.id}:`)) controller.abort();
+				await this.stepExecutions.updateMany({
+					workflowExecutionId: { eq: wf.id },
+					status: { inArray: ["running", "waiting"] }
+				}, {
+					status: "failed",
+					error: "Workflow timed out",
+					completedAt: now
+				});
+				await this.executions.updateById(wf.id, {
+					status: "timed_out",
+					completedAt: now
+				});
+				await this.alepha.events.emit("workflow:timed_out", {
+					workflowName: wf.workflowName,
+					workflowId: wf.id
+				}, { catch: true });
+				if (this.workflows.get(wf.workflowName)?.options.onError === "compensate") await this.compensate(wf.id, { error: /* @__PURE__ */ new Error("Workflow timed out") });
+			}
+		} catch (e) {
+			this.log.error("Timeout sweep failed", { error: e });
+		} finally {
+			await this.lockProvider.del("_alepha:workflows:timeout-lock");
+		}
+	}
+	async purge() {
+		if (this.stopping) return;
+		try {
+			const cutoff = this.dt.now().subtract(this.config.retentionDays, "day").toISOString();
+			const old = await this.executions.findMany({ where: {
+				status: { inArray: [
+					"completed",
+					"failed",
+					"compensated",
+					"compensation_failed",
+					"cancelled",
+					"timed_out"
+				] },
+				completedAt: { lte: cutoff }
+			} });
+			if (old.length > 0) {
+				const ids = old.map((e) => e.id);
+				await this.executions.deleteMany({ id: { inArray: ids } });
+				this.log.info(`Purge: deleted ${ids.length} old workflow executions`);
+			}
+		} catch (e) {
+			this.log.error("Purge failed", { error: e });
+		}
+	}
+	onStart = $hook({
+		on: "start",
+		handler: async () => {
+			this.log.info("Workflow engine OK", {
+				dispatch: this.stepDispatch ? "queue" : "inline",
+				workflows: this.workflows.size
+			});
+			this.alepha.events.on("log", ({ entry }) => {
+				const ctx = entry.context;
+				if (!ctx) return;
+				const entries = this.logs.get(ctx);
+				if (!entries) return;
+				entries.push(entry);
+			});
+		}
+	});
+	onStop = $hook({
+		on: "stop",
+		handler: async () => {
+			this.stopping = true;
+			if (this.inFlight.size > 0) {
+				this.log.info(`Draining ${this.inFlight.size} in-flight step(s)...`);
+				await Promise.race([Promise.allSettled([...this.inFlight]), this.dt.wait([this.config.drainTimeout, "millisecond"])]);
+			}
+			if (this.abortControllers.size > 0) {
+				this.log.warn(`Aborting ${this.abortControllers.size} remaining step(s)`);
+				for (const controller of this.abortControllers.values()) controller.abort();
+			}
+		}
+	});
+};
+//#endregion
+//#region ../../src/api/workflows/services/WorkflowService.ts
+var WorkflowService = class {
+	alepha = $inject(Alepha);
+	dt = $inject(DateTimeProvider);
+	log = $logger();
+	workflowProvider = $inject(WorkflowProvider);
+	database = $inject(DatabaseProvider);
+	executions = $repository(workflowExecutions);
+	stepExecutions = $repository(workflowStepExecutions);
+	/**
+	* Compute available actions for a workflow execution based on its status.
+	*/
+	computeCan(status, signalStepName) {
+		return {
+			retry: status === "failed" || status === "timed_out",
+			cancel: status === "pending" || status === "running" || status === "waiting_for_signal",
+			compensate: status === "failed" || status === "timed_out",
+			restart: status === "failed" || status === "compensated" || status === "compensation_failed",
+			signal: signalStepName ? { stepName: signalStepName } : void 0
+		};
+	}
+	/**
+	* Convert an ISO date string to the raw SQL parameter format
+	* expected by the current database dialect.
+	*
+	* - PostgreSQL: ISO string (timestamp comparison)
+	* - SQLite: epoch milliseconds (integer comparison)
+	*/
+	toRawDate(iso) {
+		return this.database.dialect === "sqlite" ? new Date(iso).getTime() : iso;
+	}
+	/**
+	* Get aggregate stats for the workflow engine.
+	*/
+	async getStats(days) {
+		const workflows = this.workflowProvider.getRegisteredWorkflows();
+		const periodAgo = this.toRawDate(this.dt.now().subtract(days ?? 1, "day").toISOString());
+		const row = (await this.executions.query((e) => sql`
+        SELECT
+          COUNT(*) FILTER (WHERE ${e.status} = 'running') AS running,
+          COUNT(*) FILTER (WHERE ${e.status} = 'pending') AS pending,
+          COUNT(*) FILTER (WHERE ${e.status} = 'waiting_for_signal') AS waiting,
+          COUNT(*) FILTER (WHERE ${e.status} = 'completed' AND ${e.completedAt} >= ${periodAgo}) AS completed,
+          COUNT(*) FILTER (WHERE ${e.status} = 'failed' AND ${e.completedAt} >= ${periodAgo}) AS failed,
+          COUNT(*) FILTER (WHERE ${e.status} = 'compensated' AND ${e.completedAt} >= ${periodAgo}) AS compensated,
+          COUNT(*) FILTER (WHERE ${e.status} = 'compensation_failed' AND ${e.completedAt} >= ${periodAgo}) AS compensation_failed,
+          COUNT(*) FILTER (WHERE ${e.status} = 'cancelled' AND ${e.completedAt} >= ${periodAgo}) AS cancelled,
+          COUNT(*) FILTER (WHERE ${e.status} = 'timed_out' AND ${e.completedAt} >= ${periodAgo}) AS timed_out
+        FROM ${e}
+      `, t.object({
+			running: t.string(),
+			pending: t.string(),
+			waiting: t.string(),
+			completed: t.string(),
+			failed: t.string(),
+			compensated: t.string(),
+			compensation_failed: t.string(),
+			cancelled: t.string(),
+			timed_out: t.string()
+		})))[0];
+		return {
+			registered: workflows.size,
+			running: Number(row.running),
+			pending: Number(row.pending),
+			waiting: Number(row.waiting),
+			completed: Number(row.completed),
+			failed: Number(row.failed),
+			compensated: Number(row.compensated),
+			compensationFailed: Number(row.compensation_failed),
+			cancelled: Number(row.cancelled),
+			timedOut: Number(row.timed_out)
+		};
+	}
+	/**
+	* Get the full workflow registry with live counts.
+	*/
+	async getRegistry() {
+		const workflows = this.workflowProvider.getRegisteredWorkflows();
+		const names = [...workflows.keys()];
+		const countRows = names.length > 0 ? await this.executions.query((e) => sql`
+              SELECT
+                ${e.workflowName} AS workflow_name,
+                COUNT(*) FILTER (WHERE ${e.status} = 'running') AS running,
+                COUNT(*) FILTER (WHERE ${e.status} = 'pending') AS pending,
+                COUNT(*) FILTER (WHERE ${e.status} = 'waiting_for_signal') AS waiting,
+                COUNT(*) FILTER (WHERE ${e.status} = 'failed') AS failed
+              FROM ${e}
+              WHERE ${e.workflowName} IN (${sql.join(names.map((n) => sql`${n}`), sql`, `)})
+              GROUP BY ${e.workflowName}
+            `, t.object({
+			workflow_name: t.string(),
+			running: t.string(),
+			pending: t.string(),
+			waiting: t.string(),
+			failed: t.string()
+		})) : [];
+		const countsByName = new Map(countRows.map((r) => [r.workflow_name, r]));
+		const result = [];
+		for (const [name, reg] of workflows) {
+			const opts = reg.options;
+			const counts = countsByName.get(name);
+			result.push({
+				name,
+				stepCount: opts.steps.length,
+				steps: opts.steps.map((step) => ({
+					name: step.name,
+					type: step.type ?? "handler",
+					hasCompensate: Boolean(step.compensate),
+					hasRetry: Boolean(step.retry),
+					timeout: step.timeout ? String(step.timeout) : void 0
+				})),
+				onError: opts.onError ?? "compensate",
+				timeout: opts.timeout ? String(opts.timeout) : void 0,
+				priority: opts.priority ?? "normal",
+				tags: opts.tags,
+				paused: this.workflowProvider.isWorkflowPaused(name),
+				running: Number(counts?.running ?? 0),
+				pending: Number(counts?.pending ?? 0),
+				waiting: Number(counts?.waiting ?? 0),
+				failed: Number(counts?.failed ?? 0)
+			});
+		}
+		return result;
+	}
+	/**
+	* Paginated query for workflow executions.
+	*/
+	async findExecutions(query = {}) {
+		query.sort ??= "-createdAt";
+		const where = this.executions.createQueryWhere();
+		if (query.workflow) where.workflowName = { eq: query.workflow };
+		if (query.status) where.status = { eq: query.status };
+		if (query.from) where.createdAt = { gte: query.from };
+		if (query.to) where.createdAt = {
+			...where.createdAt,
+			lte: query.to
+		};
+		const page = await this.executions.paginate(query, { where }, { count: true });
+		return {
+			...page,
+			content: page.content.map((exec) => ({
+				...exec,
+				can: this.computeCan(exec.status)
+			}))
+		};
+	}
+	/**
+	* Get a single workflow execution with step details.
+	*/
+	async getExecution(id) {
+		const execution = await this.executions.findById(id);
+		if (!execution) throw new NotFoundError(`Workflow execution not found: ${id}`);
+		const steps = await this.stepExecutions.findMany({
+			where: { workflowExecutionId: { eq: id } },
+			orderBy: {
+				column: "stepIndex",
+				direction: "asc"
+			}
+		});
+		let signalStepName;
+		if (execution.status === "waiting_for_signal") {
+			const waitingStep = steps.find((s) => s.status === "waiting");
+			if (waitingStep) signalStepName = waitingStep.stepName;
+		}
+		return {
+			...execution,
+			can: this.computeCan(execution.status, signalStepName),
+			steps
+		};
+	}
+	/**
+	* Get daily activity (completed/failed) over a date range.
+	*/
+	async getActivity(days = 14) {
+		return (await this.executions.query((e) => sql`
+        WITH date_series AS (
+          SELECT generate_series(
+            CURRENT_DATE - ${days - 1}::int,
+            CURRENT_DATE,
+            '1 day'::interval
+          )::date AS date
+        )
+        SELECT
+          ds.date::text AS date,
+          COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'completed'), 0) AS completed,
+          COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'failed'), 0) AS failed
+        FROM date_series ds
+        LEFT JOIN ${e} ON DATE(${e.completedAt}) = ds.date
+          AND ${e.status} IN ('completed', 'failed')
+        GROUP BY ds.date
+        ORDER BY ds.date ASC
+      `, t.object({
+			date: t.string(),
+			completed: t.string(),
+			failed: t.string()
+		}))).map((row) => ({
+			date: row.date,
+			completed: Number(row.completed),
+			failed: Number(row.failed)
+		}));
+	}
+	/**
+	* Start a new workflow execution by name.
+	*/
+	async triggerWorkflow(name, payload, options) {
+		this.log.info(`Triggering workflow '${name}'`, { triggeredBy: options?.triggeredByName ?? options?.triggeredBy });
+		return { id: await this.workflowProvider.start(name, payload ?? {}, {
+			key: options?.key,
+			tags: options?.tags,
+			triggeredBy: options?.triggeredBy,
+			triggeredByName: options?.triggeredByName
+		}) };
+	}
+	/**
+	* Cancel a running workflow execution.
+	*/
+	async cancelExecution(id, context) {
+		this.log.info(`Cancelling workflow execution ${id}`, { cancelledBy: context?.cancelledByName ?? context?.cancelledBy });
+		await this.workflowProvider.cancel(id, {
+			compensate: context?.compensate,
+			cancelledBy: context?.cancelledBy,
+			cancelledByName: context?.cancelledByName
+		});
+		return { ok: true };
+	}
+	/**
+	* Retry a failed/timed-out workflow from the failed step.
+	*/
+	async retryExecution(id) {
+		this.log.info(`Retrying workflow execution ${id}`);
+		await this.workflowProvider.retry(id);
+		return { ok: true };
+	}
+	/**
+	* Restart a terminal workflow as a new execution.
+	*/
+	async restartExecution(id) {
+		this.log.info(`Restarting workflow execution ${id}`);
+		return { id: await this.workflowProvider.restart(id) };
+	}
+	/**
+	* Trigger compensation on a failed/timed-out workflow.
+	*/
+	async compensateExecution(id) {
+		this.log.info(`Compensating workflow execution ${id}`);
+		await this.workflowProvider.compensate(id);
+		return { ok: true };
+	}
+	/**
+	* Send a signal to a waiting workflow step.
+	*/
+	async signalExecution(id, stepName, payload, signalledBy) {
+		this.log.info(`Signalling workflow execution ${id} step '${stepName}'`, { signalledBy });
+		await this.workflowProvider.signal(id, stepName, payload);
+		return { ok: true };
+	}
+};
+//#endregion
+//#region ../../src/api/workflows/controllers/AdminWorkflowController.ts
+var AdminWorkflowController = class {
+	url = "/workflows";
+	group = "admin:workflows";
+	workflowService = $inject(WorkflowService);
+	getRegistry = $action({
+		path: this.url,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:read"] })],
+		schema: { response: t.array(workflowRegistrationSchema) },
+		handler: () => this.workflowService.getRegistry()
+	});
+	getStats = $action({
+		path: `${this.url}/stats`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:read"] })],
+		schema: {
+			query: workflowActivityQuerySchema,
+			response: workflowStatsSchema
+		},
+		handler: ({ query }) => this.workflowService.getStats(query.days)
+	});
+	getActivity = $action({
+		path: `${this.url}/activity`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:read"] })],
+		schema: {
+			query: workflowActivityQuerySchema,
+			response: t.array(workflowActivityPointSchema)
+		},
+		handler: ({ query }) => this.workflowService.getActivity(query.days)
+	});
+	findExecutions = $action({
+		path: `${this.url}/executions`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:read"] })],
+		schema: {
+			query: workflowExecutionQuerySchema,
+			response: t.page(workflowExecutionResourceSchema)
+		},
+		handler: ({ query }) => this.workflowService.findExecutions(query)
+	});
+	getExecution = $action({
+		path: `${this.url}/executions/:id`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:read"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: workflowExecutionDetailSchema
+		},
+		handler: ({ params }) => this.workflowService.getExecution(params.id)
+	});
+	startWorkflow = $action({
+		method: "POST",
+		path: `${this.url}/start`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:create"] })],
+		schema: {
+			body: t.object({
+				name: t.text(),
+				payload: t.optional(t.record(t.text(), t.any())),
+				key: t.optional(t.text()),
+				tags: t.optional(t.array(t.text()))
+			}),
+			response: t.object({ id: t.uuid() })
+		},
+		handler: async ({ body, user }) => {
+			return this.workflowService.triggerWorkflow(body.name, body.payload, {
+				key: body.key,
+				tags: body.tags,
+				triggeredBy: user?.id,
+				triggeredByName: user?.name
+			});
+		}
+	});
+	signalStep = $action({
+		method: "POST",
+		path: `${this.url}/executions/:id/signal`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:update"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			body: t.object({
+				stepName: t.text(),
+				payload: t.optional(t.record(t.text(), t.any()))
+			}),
+			response: okSchema
+		},
+		handler: async ({ params, body, user }) => {
+			return this.workflowService.signalExecution(params.id, body.stepName, body.payload, user?.id);
+		}
+	});
+	cancelExecution = $action({
+		method: "POST",
+		path: `${this.url}/executions/:id/cancel`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:update"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: okSchema
+		},
+		handler: async ({ params, user }) => {
+			return this.workflowService.cancelExecution(params.id, {
+				cancelledBy: user?.id,
+				cancelledByName: user?.name
+			});
+		}
+	});
+	retryExecution = $action({
+		method: "POST",
+		path: `${this.url}/executions/:id/retry`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:update"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: okSchema
+		},
+		handler: async ({ params }) => {
+			return this.workflowService.retryExecution(params.id);
+		}
+	});
+	restartExecution = $action({
+		method: "POST",
+		path: `${this.url}/executions/:id/restart`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:create"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: t.object({ id: t.uuid() })
+		},
+		handler: async ({ params }) => {
+			return this.workflowService.restartExecution(params.id);
+		}
+	});
+	compensateExecution = $action({
+		method: "POST",
+		path: `${this.url}/executions/:id/compensate`,
+		group: this.group,
+		use: [$secure({ permissions: ["admin:workflow:update"] })],
+		schema: {
+			params: t.object({ id: t.uuid() }),
+			response: okSchema
+		},
+		handler: async ({ params }) => {
+			return this.workflowService.compensateExecution(params.id);
+		}
+	});
+};
+//#endregion
+//#region ../../src/api/workflows/jobs/WorkflowJobs.ts
+var WorkflowJobs = class {
+	workflowProvider = $inject(WorkflowProvider);
+	dispatchStep = $job({
+		schema: t.object({
+			workflowId: t.uuid(),
+			stepName: t.text()
+		}),
+		retry: {
+			retries: 2,
+			backoff: [1, "second"]
+		},
+		timeout: [10, "minute"],
+		concurrency: 10,
+		handler: async ({ items }) => {
+			for (const item of items) await this.workflowProvider.processStep(item.payload.workflowId, item.payload.stepName);
+		}
+	});
+	timeoutSweep = $job({
+		cron: "* * * * *",
+		lock: true,
+		handler: async () => {
+			await this.workflowProvider.timeoutSweep();
+		}
+	});
+	purge = $job({
+		cron: "0 3 * * *",
+		lock: true,
+		handler: async () => {
+			await this.workflowProvider.purge();
+		}
+	});
+	recoverySweep = $job({
+		cron: "*/5 * * * *",
+		lock: true,
+		handler: async () => {
+			await this.workflowProvider.recoverySweep();
+		}
+	});
+	onStart = $hook({
+		on: "start",
+		handler: async () => {
+			this.workflowProvider.stepDispatch = async (workflowId, stepName, priority) => {
+				await this.dispatchStep.push({
+					workflowId,
+					stepName
+				}, { priority: {
+					0: "critical",
+					1: "high",
+					2: "normal",
+					3: "low"
+				}[priority] ?? "normal" });
+			};
+		}
+	});
+};
+//#endregion
+//#region ../../src/api/workflows/primitives/$workflow.ts
+var WorkflowPrimitive = class extends Primitive {
+	workflowProvider = $inject(WorkflowProvider);
+	get name() {
+		return `${this.config.service.name}.${this.config.propertyKey}`;
+	}
+	onInit() {
+		this.workflowProvider.register(this);
+	}
+	/**
+	* Start a new workflow execution.
+	*/
+	async start(payload, options) {
+		return this.workflowProvider.start(this.name, payload, options);
+	}
+	/**
+	* Send a signal to a waiting step on a specific execution.
+	*/
+	async signal(executionId, stepName, payload) {
+		return this.workflowProvider.signal(executionId, stepName, payload);
+	}
+	/**
+	* Cancel a running execution.
+	*/
+	async cancel(executionId, options) {
+		return this.workflowProvider.cancel(executionId, { compensate: options?.compensate });
+	}
+	/**
+	* Retry a failed/timed-out execution from the failed step.
+	*/
+	async retry(executionId) {
+		return this.workflowProvider.retry(executionId);
+	}
+	/**
+	* Restart a terminal execution from the beginning (new execution).
+	*/
+	async restart(executionId) {
+		return this.workflowProvider.restart(executionId);
+	}
+	/**
+	* Get the status of an execution.
+	*/
+	async status(executionId) {
+		return this.workflowProvider.getExecution(executionId);
+	}
+};
+const $workflow = (options) => {
+	return createPrimitive(WorkflowPrimitive, options);
+};
+$workflow[KIND] = WorkflowPrimitive;
+//#endregion
+//#region ../../src/api/workflows/index.ts
+/**
+* Durable workflow engine for long-running business processes.
+*
+* **Features:**
+* - Declarative, multi-step workflows with typed payloads
+* - Saga-pattern compensation for failure recovery
+* - Per-step retry with exponential backoff
+* - Workflow-level timeout and cancellation
+* - Deduplication via unique keys
+* - Per-execution log capture
+*
+* @module alepha.api.workflows
+*/
+const AlephaApiWorkflows = $module({
+	name: "alepha.api.workflows",
+	primitives: [$workflow],
+	services: [
+		AlephaApiJobs,
+		AlephaLock,
+		WorkflowProvider,
+		WorkflowService,
+		WorkflowJobs,
+		AdminWorkflowController
+	],
+	register: (alepha) => {
+		alepha.with(AlephaApiJobs);
+		alepha.with(AlephaLock);
+		alepha.with(WorkflowProvider);
+		alepha.with(WorkflowService);
+		alepha.with(WorkflowJobs);
+		alepha.with(AdminWorkflowController);
+	}
+});
+//#endregion
+export { $workflow, AdminWorkflowController, AlephaApiWorkflows, WorkflowPrimitive, WorkflowProvider, WorkflowService, workflowActivityPointSchema, workflowActivityQuerySchema, workflowConfig, workflowExecutionCanSchema, workflowExecutionDetailSchema, workflowExecutionQuerySchema, workflowExecutionResourceSchema, workflowExecutions, workflowRegistrationSchema, workflowStatsSchema, workflowStepExecutionResourceSchema, workflowStepExecutions, workflowStepLogs };
+
+//# sourceMappingURL=index.js.map