@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/workflow/expression.js

@@ -0,0 +1,99 @@
+//#region src/workflow/expression.ts
+function evaluateExpression(expression, ctx) {
+	if (!expression) return true;
+	const trimmed = expression.trim();
+	if (!trimmed) return true;
+	const orParts = splitByOperator(trimmed, "||");
+	if (orParts.length > 1) return orParts.some((part) => evaluateExpression(part, ctx));
+	const andParts = splitByOperator(trimmed, "&&");
+	if (andParts.length > 1) return andParts.every((part) => evaluateExpression(part, ctx));
+	return evaluateSingle(trimmed, ctx);
+}
+function evaluateSingle(expr, ctx) {
+	const trimmed = expr.trim();
+	if (!trimmed) return true;
+	if (trimmed.startsWith("!")) return !evaluateSingle(trimmed.slice(1), ctx);
+	const comparisonMatch = trimmed.match(/^(data|input|output)\.([A-Za-z0-9_.[\]]+)\s*(===|==|!==|!=|>=|<=|>|<)\s*(.+)$/);
+	if (comparisonMatch) {
+		const [, root, path, operator, rawRight] = comparisonMatch;
+		return compare(resolveRoot(root, ctx, path), parseLiteral(rawRight), operator);
+	}
+	const truthyMatch = trimmed.match(/^(data|input|output)\.([A-Za-z0-9_.[\]]+)$/);
+	if (truthyMatch) {
+		const [, root, path] = truthyMatch;
+		const value = resolveRoot(root, ctx, path);
+		return Boolean(value);
+	}
+	const literal = parseLiteral(trimmed);
+	return Boolean(literal);
+}
+function compare(left, right, operator) {
+	switch (operator) {
+		case "===":
+		case "==": return left === right;
+		case "!==":
+		case "!=": return left !== right;
+		case ">": return Number(left) > Number(right);
+		case ">=": return Number(left) >= Number(right);
+		case "<": return Number(left) < Number(right);
+		case "<=": return Number(left) <= Number(right);
+		default: return false;
+	}
+}
+function parseLiteral(value) {
+	const trimmed = (value ?? "").trim();
+	if (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1);
+	if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+	if (/^true$/i.test(trimmed)) return true;
+	if (/^false$/i.test(trimmed)) return false;
+	if (/^null$/i.test(trimmed)) return null;
+	if (/^undefined$/i.test(trimmed)) return void 0;
+	return trimmed;
+}
+function resolveRoot(root, ctx, path) {
+	return resolvePath(root === "data" ? ctx.data : root === "input" ? ctx.input : ctx.output, path);
+}
+function resolvePath(source, path) {
+	if (source == null) return void 0;
+	if (!path) return source;
+	const segments = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+	let current = source;
+	for (const segment of segments) {
+		if (current == null) return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+function splitByOperator(expr, operator) {
+	const parts = [];
+	let buffer = "";
+	let inSingleQuote = false;
+	let inDoubleQuote = false;
+	for (let i = 0; i < expr.length; i++) {
+		const char = expr[i];
+		if (!char) continue;
+		const next = expr.slice(i, i + operator.length);
+		if (char === "'" && !inDoubleQuote) {
+			inSingleQuote = !inSingleQuote;
+			buffer += char;
+			continue;
+		}
+		if (char === "\"" && !inSingleQuote) {
+			inDoubleQuote = !inDoubleQuote;
+			buffer += char;
+			continue;
+		}
+		if (!inSingleQuote && !inDoubleQuote && next === operator) {
+			parts.push(buffer.trim());
+			buffer = "";
+			i += operator.length - 1;
+			continue;
+		}
+		buffer += char;
+	}
+	if (buffer.trim().length) parts.push(buffer.trim());
+	return parts;
+}
+
+//#endregion
+export { evaluateExpression };

package/dist/workflow/index.d.ts

@@ -0,0 +1,17 @@
+import { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus } from "./spec.js";
+import { ValidateWorkflowSpecOptions, WorkflowValidationError, WorkflowValidationIssue, WorkflowValidationLevel, assertWorkflowSpecValid, validateWorkflowSpec } from "./validation.js";
+import { StateStore, StepExecution, WorkflowState, WorkflowStateFilters } from "./state.js";
+import { GuardContext, GuardEvaluator, OperationExecutor, OperationExecutorContext, WorkflowPreFlightError, WorkflowPreFlightIssue, WorkflowPreFlightIssueSeverity, WorkflowPreFlightIssueType, WorkflowPreFlightResult, WorkflowRunner, WorkflowRunnerConfig } from "./runner.js";
+import { ExpressionContext, evaluateExpression } from "./expression.js";
+import { InMemoryStateStore } from "./adapters/memory-store.js";
+import { PrismaStateStore } from "./adapters/db-adapter.js";
+import { FileStateStoreOptions, createFileStateStore } from "./adapters/file-adapter.js";
+import "./adapters/index.js";
+
+//#region src/workflow/index.d.ts
+/**
+ * Helper to define a Workflow.
+ */
+declare const defineWorkflow: (spec: WorkflowSpec) => WorkflowSpec;
+//#endregion
+export { CompensationStep, CompensationStrategy, ExpressionContext, FileStateStoreOptions, FormRef, GuardCondition, GuardConditionKind, GuardContext, GuardEvaluator, InMemoryStateStore, OperationExecutor, OperationExecutorContext, PrismaStateStore, RetryPolicy, SLA, StateStore, Step, StepAction, StepExecution, StepType, Transition, ValidateWorkflowSpecOptions, WorkflowDefinition, WorkflowMeta, WorkflowPreFlightError, WorkflowPreFlightIssue, WorkflowPreFlightIssueSeverity, WorkflowPreFlightIssueType, WorkflowPreFlightResult, WorkflowRegistry, WorkflowRunner, WorkflowRunnerConfig, WorkflowSpec, WorkflowState, WorkflowStateFilters, WorkflowStatus, WorkflowValidationError, WorkflowValidationIssue, WorkflowValidationLevel, assertWorkflowSpecValid, createFileStateStore, defineWorkflow, evaluateExpression, validateWorkflowSpec };

package/dist/workflow/index.js

@@ -0,0 +1,16 @@
+import { WorkflowRegistry } from "./spec.js";
+import { WorkflowValidationError, assertWorkflowSpecValid, validateWorkflowSpec } from "./validation.js";
+import { evaluateExpression } from "./expression.js";
+import { WorkflowPreFlightError, WorkflowRunner } from "./runner.js";
+import { InMemoryStateStore } from "./adapters/memory-store.js";
+import { PrismaStateStore } from "./adapters/db-adapter.js";
+import { createFileStateStore } from "./adapters/file-adapter.js";
+
+//#region src/workflow/index.ts
+/**
+* Helper to define a Workflow.
+*/
+const defineWorkflow = (spec) => spec;
+
+//#endregion
+export { InMemoryStateStore, PrismaStateStore, WorkflowPreFlightError, WorkflowRegistry, WorkflowRunner, WorkflowValidationError, assertWorkflowSpecValid, createFileStateStore, defineWorkflow, evaluateExpression, validateWorkflowSpec };

package/dist/workflow/overview.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/workflow/overview.docblock.d.ts
+declare const tech_workflows_overview_DocBlocks: DocBlock[];
+//#endregion
+export { tech_workflows_overview_DocBlocks };

package/dist/workflow/overview.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../docs/registry.js";
+
+//#region src/workflow/overview.docblock.ts
+const tech_workflows_overview_DocBlocks = [{
+	id: "docs.tech.workflows.overview",
+	title: "WorkflowSpec Overview",
+	summary: "WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@contractspec/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/workflows/overview",
+	tags: [
+		"tech",
+		"workflows",
+		"overview"
+	],
+	body: "# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@contractspec/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` → `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@contractspec/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"
+}];
+registerDocBlocks(tech_workflows_overview_DocBlocks);
+
+//#endregion
+export { tech_workflows_overview_DocBlocks };

package/dist/workflow/runner.d.ts

@@ -0,0 +1,77 @@
+import { OpRef } from "../features/types.js";
+import "../features/index.js";
+import { GuardCondition, Step, WorkflowRegistry } from "./spec.js";
+import { ResolvedBranding } from "../app-config/branding.js";
+import { ResolvedAppConfig, ResolvedIntegration, ResolvedKnowledge, ResolvedTranslation } from "../app-config/runtime.js";
+import { SecretProvider } from "../integrations/secrets/provider.js";
+import { TranslationResolver } from "../types.js";
+import { StateStore, WorkflowState } from "./state.js";
+
+//#region src/workflow/runner.d.ts
+interface OperationExecutorContext {
+  workflow: WorkflowState;
+  step: Step;
+  resolvedAppConfig?: ResolvedAppConfig;
+  integrations?: ResolvedIntegration[];
+  knowledge?: ResolvedKnowledge[];
+  branding?: ResolvedBranding;
+  translation?: ResolvedTranslation;
+  translationResolver?: TranslationResolver;
+  secretProvider?: SecretProvider;
+}
+type OperationExecutor = (op: OpRef, input: unknown, context: OperationExecutorContext) => Promise<unknown>;
+type WorkflowPreFlightIssueType = 'integration' | 'capability';
+type WorkflowPreFlightIssueSeverity = 'error' | 'warning';
+interface WorkflowPreFlightIssue {
+  stepId: string;
+  type: WorkflowPreFlightIssueType;
+  identifier: string;
+  severity: WorkflowPreFlightIssueSeverity;
+  reason: string;
+}
+interface WorkflowPreFlightResult {
+  canStart: boolean;
+  issues: WorkflowPreFlightIssue[];
+}
+interface GuardContext {
+  workflow: WorkflowState;
+  step: Step;
+  input?: unknown;
+}
+type GuardEvaluator = (guard: GuardCondition, context: GuardContext) => Promise<boolean> | boolean;
+interface WorkflowRunnerConfig {
+  registry: WorkflowRegistry;
+  stateStore: StateStore;
+  opExecutor: OperationExecutor;
+  guardEvaluator?: GuardEvaluator;
+  eventEmitter?: (event: string, payload: Record<string, unknown>) => void;
+  appConfigProvider?: (state: WorkflowState) => ResolvedAppConfig | undefined | Promise<ResolvedAppConfig | undefined>;
+  enforceCapabilities?: (operation: OpRef, context: OperationExecutorContext) => void | Promise<void>;
+  secretProvider?: SecretProvider;
+  translationResolver?: TranslationResolver;
+}
+declare class WorkflowRunner {
+  private readonly config;
+  constructor(config: WorkflowRunnerConfig);
+  preFlightCheck(workflowName: string, version?: string,
+  // Update to string
+  resolvedConfig?: ResolvedAppConfig): Promise<WorkflowPreFlightResult>;
+  start(workflowName: string, version?: string, initialData?: Record<string, unknown>): Promise<string>;
+  executeStep(workflowId: string, input?: unknown): Promise<void>;
+  rollback(workflowId: string): Promise<void>;
+  getState(workflowId: string): Promise<WorkflowState>;
+  cancel(workflowId: string): Promise<void>;
+  private performPreFlight;
+  private evaluateGuard;
+  private runStepAction;
+  private pickNextStepId;
+  private getSpec;
+  private getStateOrThrow;
+  private emit;
+}
+declare class WorkflowPreFlightError extends Error {
+  readonly issues: WorkflowPreFlightIssue[];
+  constructor(issues: WorkflowPreFlightIssue[]);
+}
+//#endregion
+export { GuardContext, GuardEvaluator, OperationExecutor, OperationExecutorContext, WorkflowPreFlightError, WorkflowPreFlightIssue, WorkflowPreFlightIssueSeverity, WorkflowPreFlightIssueType, WorkflowPreFlightResult, WorkflowRunner, WorkflowRunnerConfig };

package/dist/workflow/runner.js

@@ -0,0 +1,337 @@
+import { evaluateExpression } from "./expression.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/workflow/runner.ts
+var WorkflowRunner = class {
+	constructor(config) {
+		this.config = config;
+	}
+	async preFlightCheck(workflowName, version, resolvedConfig) {
+		const spec = this.getSpec(workflowName, version);
+		return this.performPreFlight(spec, resolvedConfig);
+	}
+	async start(workflowName, version, initialData) {
+		const spec = this.getSpec(workflowName, version);
+		const entryStepId = resolveEntryStepId(spec);
+		const now = /* @__PURE__ */ new Date();
+		const workflowId = randomUUID();
+		const state = {
+			workflowId,
+			workflowName: spec.meta.key,
+			workflowVersion: spec.meta.version,
+			currentStep: entryStepId,
+			data: { ...initialData ?? {} },
+			retryCounts: {},
+			history: [],
+			status: "running",
+			createdAt: now,
+			updatedAt: now
+		};
+		const resolvedAppConfig = this.config.appConfigProvider ? await this.config.appConfigProvider(state) : void 0;
+		const preFlightResult = await this.performPreFlight(spec, resolvedAppConfig);
+		if (!preFlightResult.canStart) throw new WorkflowPreFlightError(preFlightResult.issues);
+		await this.config.stateStore.create(state);
+		this.emit("workflow.started", {
+			workflowId,
+			workflowName: spec.meta.key,
+			workflowVersion: spec.meta.version,
+			currentStep: entryStepId
+		});
+		return workflowId;
+	}
+	async executeStep(workflowId, input) {
+		const state = await this.getStateOrThrow(workflowId);
+		if (isTerminalStatus(state.status)) throw new Error(`Workflow ${workflowId} is in terminal status "${state.status}".`);
+		const spec = this.getSpec(state.workflowName, state.workflowVersion);
+		const step = getCurrentStep(spec, state.currentStep);
+		if (!await this.evaluateGuard(step, state, input)) throw new Error(`GuardRejected: ${state.workflowName} -> ${step.id}`);
+		const execution = {
+			stepId: step.id,
+			startedAt: /* @__PURE__ */ new Date(),
+			status: "running",
+			input
+		};
+		const workingState = {
+			...state,
+			data: { ...state.data },
+			history: [...state.history]
+		};
+		try {
+			const output = await this.runStepAction(step, workingState, input);
+			execution.output = output;
+			execution.status = "completed";
+			execution.completedAt = /* @__PURE__ */ new Date();
+			workingState.history.push(execution);
+			workingState.updatedAt = /* @__PURE__ */ new Date();
+			if (isRecord(input)) workingState.data = {
+				...workingState.data,
+				...input
+			};
+			if (isRecord(output)) workingState.data = {
+				...workingState.data,
+				...output
+			};
+			const nextStepId = this.pickNextStepId(spec, workingState, step, input, output);
+			if (nextStepId) {
+				workingState.currentStep = nextStepId;
+				workingState.status = "running";
+			} else if (!hasOutgoing(spec, step.id)) workingState.status = "completed";
+			else throw new Error(`No transition matched after executing step "${step.id}".`);
+			await this.config.stateStore.update(workflowId, () => workingState);
+			this.emit("workflow.step_completed", {
+				workflowId,
+				workflowName: state.workflowName,
+				stepId: step.id,
+				status: workingState.status
+			});
+		} catch (error) {
+			execution.status = "failed";
+			execution.completedAt = /* @__PURE__ */ new Date();
+			execution.error = error instanceof Error ? error.message : String(error);
+			workingState.history.push(execution);
+			workingState.updatedAt = /* @__PURE__ */ new Date();
+			if (step.retry) {
+				const retries = state.retryCounts?.[step.id] ?? 0;
+				if (retries < step.retry.maxAttempts) {
+					const backoff = step.retry.backoff ?? "exponential";
+					const baseDelay = step.retry.delayMs ?? 1e3;
+					const delay = backoff === "exponential" ? baseDelay * Math.pow(2, retries) : baseDelay;
+					const cappedDelay = Math.min(delay, step.retry.maxDelayMs ?? Infinity);
+					workingState.retryCounts = {
+						...state.retryCounts ?? {},
+						[step.id]: retries + 1
+					};
+					workingState.status = "running";
+					await this.config.stateStore.update(workflowId, () => workingState);
+					this.emit("workflow.step_retrying", {
+						workflowId,
+						workflowName: state.workflowName,
+						stepId: step.id,
+						attempt: retries + 1,
+						delay: cappedDelay,
+						error: execution.error
+					});
+					await new Promise((resolve) => setTimeout(resolve, cappedDelay));
+					return this.executeStep(workflowId, input);
+				}
+			}
+			workingState.status = "failed";
+			await this.config.stateStore.update(workflowId, () => workingState);
+			this.emit("workflow.step_failed", {
+				workflowId,
+				workflowName: state.workflowName,
+				stepId: step.id,
+				error: execution.error ?? "unknown"
+			});
+			if (spec.definition.compensation?.trigger === "on_failure") await this.rollback(workflowId);
+			throw error;
+		}
+	}
+	async rollback(workflowId) {
+		const state = await this.getStateOrThrow(workflowId);
+		const spec = this.getSpec(state.workflowName, state.workflowVersion);
+		if (!spec.definition.compensation) return;
+		this.emit("workflow.rollback_started", { workflowId });
+		const completedSteps = state.history.filter((h) => h.status === "completed").reverse();
+		for (const execution of completedSteps) {
+			const compStep = spec.definition.compensation.steps.find((s) => s.stepId === execution.stepId);
+			if (compStep) {
+				const input = {
+					stepId: execution.stepId,
+					originalInput: execution.input,
+					originalOutput: execution.output,
+					workflowData: state.data
+				};
+				try {
+					const step = getCurrentStep(spec, execution.stepId);
+					const resolvedAppConfig = this.config.appConfigProvider ? await this.config.appConfigProvider(state) : void 0;
+					const executorContext = {
+						workflow: state,
+						step,
+						resolvedAppConfig,
+						integrations: resolvedAppConfig?.integrations ?? [],
+						knowledge: resolvedAppConfig?.knowledge ?? [],
+						branding: resolvedAppConfig?.branding,
+						translation: resolvedAppConfig?.translation,
+						translationResolver: this.config.translationResolver,
+						secretProvider: this.config.secretProvider
+					};
+					await this.config.opExecutor(compStep.operation, input, executorContext);
+					this.emit("workflow.compensation_step_completed", {
+						workflowId,
+						stepId: execution.stepId,
+						compensationOp: compStep.operation.key
+					});
+				} catch (error) {
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					this.emit("workflow.compensation_step_failed", {
+						workflowId,
+						stepId: execution.stepId,
+						compensationOp: compStep.operation.key,
+						error: errorMessage
+					});
+				}
+			}
+		}
+		this.emit("workflow.rollback_completed", { workflowId });
+	}
+	async getState(workflowId) {
+		return this.getStateOrThrow(workflowId);
+	}
+	async cancel(workflowId) {
+		const state = await this.getStateOrThrow(workflowId);
+		if (state.status === "cancelled") return;
+		const nextState = {
+			...state,
+			status: "cancelled",
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		await this.config.stateStore.update(workflowId, () => nextState);
+		this.emit("workflow.cancelled", {
+			workflowId,
+			workflowName: state.workflowName
+		});
+	}
+	async performPreFlight(spec, resolvedConfig) {
+		if (!resolvedConfig) return {
+			canStart: true,
+			issues: []
+		};
+		const issues = [];
+		const integrationBySlot = /* @__PURE__ */ new Map();
+		for (const integration of resolvedConfig.integrations) integrationBySlot.set(integration.slot.slotId, integration);
+		for (const step of spec.definition.steps) for (const slotId of step.requiredIntegrations ?? []) {
+			const integration = integrationBySlot.get(slotId);
+			if (!integration) {
+				issues.push({
+					stepId: step.id,
+					type: "integration",
+					identifier: slotId,
+					severity: "error",
+					reason: `Integration slot "${slotId}" is not bound in the resolved app config.`
+				});
+				continue;
+			}
+			const status = integration.connection.status;
+			if (status === "disconnected" || status === "error") issues.push({
+				stepId: step.id,
+				type: "integration",
+				identifier: slotId,
+				severity: "error",
+				reason: `Integration slot "${slotId}" is in status "${status}".`
+			});
+			else if (status === "unknown") issues.push({
+				stepId: step.id,
+				type: "integration",
+				identifier: slotId,
+				severity: "warning",
+				reason: `Integration slot "${slotId}" reports unknown health status.`
+			});
+		}
+		const enabledCapabilities = new Set(resolvedConfig.capabilities.enabled.map(capabilityKey));
+		for (const step of spec.definition.steps) for (const required of step.requiredCapabilities ?? []) if (!enabledCapabilities.has(capabilityKey(required))) issues.push({
+			stepId: step.id,
+			type: "capability",
+			identifier: capabilityKey(required),
+			severity: "error",
+			reason: `Capability "${required.key}@${required.version}" is not enabled.`
+		});
+		return {
+			canStart: issues.every((issue) => issue.severity !== "error"),
+			issues
+		};
+	}
+	async evaluateGuard(step, state, input) {
+		if (!step.guard) return true;
+		if (this.config.guardEvaluator) return this.config.guardEvaluator(step.guard, {
+			workflow: state,
+			step,
+			input
+		});
+		if (step.guard.type === "expression") return evaluateExpression(step.guard.value, {
+			data: state.data,
+			input
+		});
+		return true;
+	}
+	async runStepAction(step, state, input) {
+		if (step.type === "automation") {
+			const op = step.action?.operation;
+			if (!op) throw new Error(`Automation step "${step.id}" requires an operation.`);
+			const resolvedAppConfig = this.config.appConfigProvider ? await this.config.appConfigProvider(state) : void 0;
+			const executorContext = {
+				workflow: state,
+				step,
+				resolvedAppConfig,
+				integrations: resolvedAppConfig?.integrations ?? [],
+				knowledge: resolvedAppConfig?.knowledge ?? [],
+				branding: resolvedAppConfig?.branding,
+				translation: resolvedAppConfig?.translation,
+				translationResolver: this.config.translationResolver,
+				secretProvider: this.config.secretProvider
+			};
+			if (this.config.enforceCapabilities) await this.config.enforceCapabilities(op, executorContext);
+			return this.config.opExecutor(op, input, executorContext);
+		}
+		if (step.type === "human") return input;
+		return input;
+	}
+	pickNextStepId(spec, state, step, input, output) {
+		const transitions = spec.definition.transitions.filter((t) => t.from === step.id);
+		for (const transition of transitions) if (evaluateExpression(transition.condition, {
+			data: state.data,
+			input,
+			output
+		})) {
+			const target = spec.definition.steps.find((s) => s.id === transition.to);
+			if (!target) throw new Error(`Transition ${transition.from} -> ${transition.to} points to missing step.`);
+			return target.id;
+		}
+		return null;
+	}
+	getSpec(name, version) {
+		const spec = this.config.registry.get(name, version);
+		if (!spec) throw new Error(`Workflow spec not found for ${name}${version ? `.v${version}` : ""}`);
+		return spec;
+	}
+	async getStateOrThrow(workflowId) {
+		const state = await this.config.stateStore.get(workflowId);
+		if (!state) throw new Error(`Workflow state not found for ${workflowId}`);
+		return state;
+	}
+	emit(event, payload) {
+		this.config.eventEmitter?.(event, payload);
+	}
+};
+function resolveEntryStepId(spec) {
+	const entry = spec.definition.entryStepId ?? spec.definition.steps[0]?.id ?? null;
+	if (!entry) throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} has no entry step.`);
+	return entry;
+}
+function getCurrentStep(spec, stepId) {
+	const step = spec.definition.steps.find((s) => s.id === stepId);
+	if (!step) throw new Error(`Step "${stepId}" not found in workflow ${spec.meta.key}.v${spec.meta.version}.`);
+	return step;
+}
+function hasOutgoing(spec, stepId) {
+	return spec.definition.transitions.some((t) => t.from === stepId);
+}
+function isRecord(value) {
+	return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function isTerminalStatus(status) {
+	return status === "completed" || status === "failed" || status === "cancelled";
+}
+var WorkflowPreFlightError = class extends Error {
+	constructor(issues) {
+		super(`Workflow pre-flight failed: ${issues.filter((issue) => issue.severity === "error").map((issue) => `${issue.type}:${issue.identifier}`).join(", ")}`);
+		this.issues = issues;
+		this.name = "WorkflowPreFlightError";
+	}
+};
+function capabilityKey(ref) {
+	return `${ref.key}@${ref.version}`;
+}
+
+//#endregion
+export { WorkflowPreFlightError, WorkflowRunner };

package/dist/workflow/sla-monitor.d.ts

@@ -0,0 +1,20 @@
+import { WorkflowSpec } from "./spec.js";
+import { WorkflowState } from "./state.js";
+
+//#region src/workflow/sla-monitor.d.ts
+interface SLABreachEvent {
+  workflowId: string;
+  workflowName: string;
+  type: 'workflow_duration' | 'step_duration';
+  stepId?: string;
+  expectedMs: number;
+  actualMs: number;
+  breachedAt: Date;
+}
+declare class SLAMonitor {
+  private readonly eventEmitter;
+  constructor(eventEmitter: (event: string, payload: SLABreachEvent) => void);
+  check(state: WorkflowState, spec: WorkflowSpec): void;
+}
+//#endregion
+export { SLABreachEvent, SLAMonitor };

package/dist/workflow/sla-monitor.js

@@ -0,0 +1,47 @@
+//#region src/workflow/sla-monitor.ts
+var SLAMonitor = class {
+	constructor(eventEmitter) {
+		this.eventEmitter = eventEmitter;
+	}
+	check(state, spec) {
+		const sla = spec.definition.sla;
+		if (!sla) return;
+		const now = (/* @__PURE__ */ new Date()).getTime();
+		if (sla.totalDurationMs) {
+			const duration = now - state.createdAt.getTime();
+			if (duration > sla.totalDurationMs) {
+				if (state.status === "running" || state.status === "paused") this.eventEmitter("workflow.sla_breach", {
+					workflowId: state.workflowId,
+					workflowName: state.workflowName,
+					type: "workflow_duration",
+					expectedMs: sla.totalDurationMs,
+					actualMs: duration,
+					breachedAt: /* @__PURE__ */ new Date()
+				});
+			}
+		}
+		if (sla.stepDurationMs) {
+			if (state.status === "running" && state.currentStep) {
+				const currentExecution = state.history.find((h) => h.stepId === state.currentStep && h.status === "running");
+				if (currentExecution) {
+					const stepLimit = sla.stepDurationMs[state.currentStep];
+					if (stepLimit) {
+						const stepDuration = now - currentExecution.startedAt.getTime();
+						if (stepDuration > stepLimit) this.eventEmitter("workflow.sla_breach", {
+							workflowId: state.workflowId,
+							workflowName: state.workflowName,
+							type: "step_duration",
+							stepId: state.currentStep,
+							expectedMs: stepLimit,
+							actualMs: stepDuration,
+							breachedAt: /* @__PURE__ */ new Date()
+						});
+					}
+				}
+			}
+		}
+	}
+};
+
+//#endregion
+export { SLAMonitor };