@lssm/lib.contracts 1.41.1 → 1.42.1

package/dist/workflow/runner.js

@@ -1 +1,337 @@
-import{evaluateExpression as e}from"./expression.js";import{randomUUID as t}from"node:crypto";var n=class{constructor(e){this.config=e}async preFlightCheck(e,t,n){let r=this.getSpec(e,t);return this.performPreFlight(r,n)}async start(e,n,i){let a=this.getSpec(e,n),o=r(a),s=new Date,l=t(),u={workflowId:l,workflowName:a.meta.name,workflowVersion:a.meta.version,currentStep:o,data:{...i??{}},retryCounts:{},history:[],status:`running`,createdAt:s,updatedAt:s},d=this.config.appConfigProvider?await this.config.appConfigProvider(u):void 0,f=await this.performPreFlight(a,d);if(!f.canStart)throw new c(f.issues);return await this.config.stateStore.create(u),this.emit(`workflow.started`,{workflowId:l,workflowName:a.meta.name,workflowVersion:a.meta.version,currentStep:o}),l}async executeStep(e,t){let n=await this.getStateOrThrow(e);if(s(n.status))throw Error(`Workflow ${e} is in terminal status "${n.status}".`);let r=this.getSpec(n.workflowName,n.workflowVersion),c=i(r,n.currentStep);if(!await this.evaluateGuard(c,n,t))throw Error(`GuardRejected: ${n.workflowName} -> ${c.id}`);let l={stepId:c.id,startedAt:new Date,status:`running`,input:t},u={...n,data:{...n.data},history:[...n.history]};try{let i=await this.runStepAction(c,u,t);l.output=i,l.status=`completed`,l.completedAt=new Date,u.history.push(l),u.updatedAt=new Date,o(t)&&(u.data={...u.data,...t}),o(i)&&(u.data={...u.data,...i});let s=this.pickNextStepId(r,u,c,t,i);if(s)u.currentStep=s,u.status=`running`;else if(!a(r,c.id))u.status=`completed`;else throw Error(`No transition matched after executing step "${c.id}".`);await this.config.stateStore.update(e,()=>u),this.emit(`workflow.step_completed`,{workflowId:e,workflowName:n.workflowName,stepId:c.id,status:u.status})}catch(i){if(l.status=`failed`,l.completedAt=new Date,l.error=i instanceof Error?i.message:String(i),u.history.push(l),u.updatedAt=new Date,c.retry){let r=n.retryCounts?.[c.id]??0;if(r<c.retry.maxAttempts){let i=c.retry.backoff??`exponential`,a=c.retry.delayMs??1e3,o=i===`exponential`?a*2**r:a,s=Math.min(o,c.retry.maxDelayMs??1/0);return u.retryCounts={...n.retryCounts??{},[c.id]:r+1},u.status=`running`,await this.config.stateStore.update(e,()=>u),this.emit(`workflow.step_retrying`,{workflowId:e,workflowName:n.workflowName,stepId:c.id,attempt:r+1,delay:s,error:l.error}),await new Promise(e=>setTimeout(e,s)),this.executeStep(e,t)}}throw u.status=`failed`,await this.config.stateStore.update(e,()=>u),this.emit(`workflow.step_failed`,{workflowId:e,workflowName:n.workflowName,stepId:c.id,error:l.error??`unknown`}),r.definition.compensation?.trigger===`on_failure`&&await this.rollback(e),i}}async rollback(e){let t=await this.getStateOrThrow(e),n=this.getSpec(t.workflowName,t.workflowVersion);if(!n.definition.compensation)return;this.emit(`workflow.rollback_started`,{workflowId:e});let r=t.history.filter(e=>e.status===`completed`).reverse();for(let a of r){let r=n.definition.compensation.steps.find(e=>e.stepId===a.stepId);if(r){let o={stepId:a.stepId,originalInput:a.input,originalOutput:a.output,workflowData:t.data};try{let s=i(n,a.stepId),c=this.config.appConfigProvider?await this.config.appConfigProvider(t):void 0,l={workflow:t,step:s,resolvedAppConfig:c,integrations:c?.integrations??[],knowledge:c?.knowledge??[],branding:c?.branding,translation:c?.translation,translationResolver:this.config.translationResolver,secretProvider:this.config.secretProvider};await this.config.opExecutor(r.operation,o,l),this.emit(`workflow.compensation_step_completed`,{workflowId:e,stepId:a.stepId,compensationOp:r.operation.name})}catch(t){let n=t instanceof Error?t.message:String(t);this.emit(`workflow.compensation_step_failed`,{workflowId:e,stepId:a.stepId,compensationOp:r.operation.name,error:n})}}}this.emit(`workflow.rollback_completed`,{workflowId:e})}async getState(e){return this.getStateOrThrow(e)}async cancel(e){let t=await this.getStateOrThrow(e);if(t.status===`cancelled`)return;let n={...t,status:`cancelled`,updatedAt:new Date};await this.config.stateStore.update(e,()=>n),this.emit(`workflow.cancelled`,{workflowId:e,workflowName:t.workflowName})}async performPreFlight(e,t){if(!t)return{canStart:!0,issues:[]};let n=[],r=new Map;for(let e of t.integrations)r.set(e.slot.slotId,e);for(let t of e.definition.steps)for(let e of t.requiredIntegrations??[]){let i=r.get(e);if(!i){n.push({stepId:t.id,type:`integration`,identifier:e,severity:`error`,reason:`Integration slot "${e}" is not bound in the resolved app config.`});continue}let a=i.connection.status;a===`disconnected`||a===`error`?n.push({stepId:t.id,type:`integration`,identifier:e,severity:`error`,reason:`Integration slot "${e}" is in status "${a}".`}):a===`unknown`&&n.push({stepId:t.id,type:`integration`,identifier:e,severity:`warning`,reason:`Integration slot "${e}" reports unknown health status.`})}let i=new Set(t.capabilities.enabled.map(l));for(let t of e.definition.steps)for(let e of t.requiredCapabilities??[])i.has(l(e))||n.push({stepId:t.id,type:`capability`,identifier:l(e),severity:`error`,reason:`Capability "${e.key}@${e.version}" is not enabled.`});return{canStart:n.every(e=>e.severity!==`error`),issues:n}}async evaluateGuard(t,n,r){return t.guard?this.config.guardEvaluator?this.config.guardEvaluator(t.guard,{workflow:n,step:t,input:r}):t.guard.type===`expression`?e(t.guard.value,{data:n.data,input:r}):!0:!0}async runStepAction(e,t,n){if(e.type===`automation`){let r=e.action?.operation;if(!r)throw Error(`Automation step "${e.id}" requires an operation.`);let i=this.config.appConfigProvider?await this.config.appConfigProvider(t):void 0,a={workflow:t,step:e,resolvedAppConfig:i,integrations:i?.integrations??[],knowledge:i?.knowledge??[],branding:i?.branding,translation:i?.translation,translationResolver:this.config.translationResolver,secretProvider:this.config.secretProvider};return this.config.enforceCapabilities&&await this.config.enforceCapabilities(r,a),this.config.opExecutor(r,n,a)}return e.type,n}pickNextStepId(t,n,r,i,a){let o=t.definition.transitions.filter(e=>e.from===r.id);for(let r of o)if(e(r.condition,{data:n.data,input:i,output:a})){let e=t.definition.steps.find(e=>e.id===r.to);if(!e)throw Error(`Transition ${r.from} -> ${r.to} points to missing step.`);return e.id}return null}getSpec(e,t){let n=this.config.registry.get(e,t);if(!n)throw Error(`Workflow spec not found for ${e}${t?`.v${t}`:``}`);return n}async getStateOrThrow(e){let t=await this.config.stateStore.get(e);if(!t)throw Error(`Workflow state not found for ${e}`);return t}emit(e,t){this.config.eventEmitter?.(e,t)}};function r(e){let t=e.definition.entryStepId??e.definition.steps[0]?.id??null;if(!t)throw Error(`Workflow ${e.meta.name}.v${e.meta.version} has no entry step.`);return t}function i(e,t){let n=e.definition.steps.find(e=>e.id===t);if(!n)throw Error(`Step "${t}" not found in workflow ${e.meta.name}.v${e.meta.version}.`);return n}function a(e,t){return e.definition.transitions.some(e=>e.from===t)}function o(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function s(e){return e===`completed`||e===`failed`||e===`cancelled`}var c=class extends Error{constructor(e){super(`Workflow pre-flight failed: ${e.filter(e=>e.severity===`error`).map(e=>`${e.type}:${e.identifier}`).join(`, `)}`),this.issues=e,this.name=`WorkflowPreFlightError`}};function l(e){return`${e.key}@${e.version}`}export{c as WorkflowPreFlightError,n as WorkflowRunner};
+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

@@ -1 +1,47 @@
-var e=class{constructor(e){this.eventEmitter=e}check(e,t){let n=t.definition.sla;if(!n)return;let r=new Date().getTime();if(n.totalDurationMs){let t=r-e.createdAt.getTime();t>n.totalDurationMs&&(e.status===`running`||e.status===`paused`)&&this.eventEmitter(`workflow.sla_breach`,{workflowId:e.workflowId,workflowName:e.workflowName,type:`workflow_duration`,expectedMs:n.totalDurationMs,actualMs:t,breachedAt:new Date})}if(n.stepDurationMs&&e.status===`running`&&e.currentStep){let t=e.history.find(t=>t.stepId===e.currentStep&&t.status===`running`);if(t){let i=n.stepDurationMs[e.currentStep];if(i){let n=r-t.startedAt.getTime();n>i&&this.eventEmitter(`workflow.sla_breach`,{workflowId:e.workflowId,workflowName:e.workflowName,type:`step_duration`,stepId:e.currentStep,expectedMs:i,actualMs:n,breachedAt:new Date})}}}}};export{e as SLAMonitor};
+//#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 };

package/dist/workflow/spec.d.ts

@@ -0,0 +1,105 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { CapabilityRef } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { ExperimentRef } from "../experiments/spec.js";
+import { OpRef } from "../features.js";
+
+//#region src/workflow/spec.d.ts
+/**
+ * Reference to a form spec declared in {@link FormRegistry}.
+ */
+interface FormRef {
+  key: string;
+  version: number;
+}
+type StepType = 'human' | 'automation' | 'decision';
+type WorkflowStatus = 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type GuardConditionKind = 'policy' | 'expression';
+interface GuardCondition {
+  type: GuardConditionKind;
+  /** Policy name or expression string depending on the type. */
+  value: string;
+}
+interface RetryPolicy {
+  maxAttempts: number;
+  backoff: 'linear' | 'exponential';
+  delayMs: number;
+  /** Optional max delay cap for exponential backoff. */
+  maxDelayMs?: number;
+}
+interface StepAction {
+  /** Operation executed for automation steps. */
+  operation?: OpRef;
+  /** Form rendered for human input steps. */
+  form?: FormRef;
+}
+interface Step {
+  id: string;
+  type: StepType;
+  label: string;
+  description?: string;
+  action?: StepAction;
+  guard?: GuardCondition;
+  timeoutMs?: number;
+  retry?: RetryPolicy;
+  /** Integration slot identifiers required before this step can execute. */
+  requiredIntegrations?: string[];
+  /** Capabilities that must be enabled for this step to execute. */
+  requiredCapabilities?: CapabilityRef[];
+}
+interface Transition {
+  from: string;
+  to: string;
+  label?: string;
+  /** Expression evaluated against workflow data (e.g., `data.approved === true`). */
+  condition?: string;
+}
+interface SLA {
+  totalDurationMs?: number;
+  stepDurationMs?: Record<string, number>;
+}
+interface CompensationStep {
+  stepId: string;
+  operation: OpRef;
+  description?: string;
+}
+interface CompensationStrategy {
+  trigger?: 'on_failure' | 'manual';
+  steps: CompensationStep[];
+}
+interface WorkflowDefinition {
+  steps: Step[];
+  transitions: Transition[];
+  /** Optional explicit entry step. Defaults to the first step when omitted. */
+  entryStepId?: string;
+  sla?: SLA;
+  compensation?: CompensationStrategy;
+}
+type WorkflowMeta = OwnerShipMeta;
+interface WorkflowSpec {
+  meta: WorkflowMeta;
+  definition: WorkflowDefinition;
+  policy?: {
+    flags?: string[];
+  };
+  experiments?: ExperimentRef[];
+}
+declare class WorkflowRegistry {
+  private readonly items;
+  register(spec: WorkflowSpec): this;
+  list(): WorkflowSpec[];
+  get(name: string, version?: number): WorkflowSpec | undefined;
+  /** Filter workflows by criteria. */
+  filter(criteria: RegistryFilter): WorkflowSpec[];
+  /** List workflows with specific tag. */
+  listByTag(tag: string): WorkflowSpec[];
+  /** List workflows by owner. */
+  listByOwner(owner: string): WorkflowSpec[];
+  /** Group workflows by key function. */
+  groupBy(keyFn: GroupKeyFn<WorkflowSpec>): Map<string, WorkflowSpec[]>;
+  /** Get unique tags from all workflows. */
+  getUniqueTags(): string[];
+}
+//#endregion
+export { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus };

package/dist/workflow/spec.js

@@ -1 +1,55 @@
-function e(e){return`${e.name}.v${e.version}`}var t=class{items=new Map;register(t){let n=e(t.meta);if(this.items.has(n))throw Error(`Duplicate workflow ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let t of this.items.values())t.meta.name===e&&t.meta.version>r&&(r=t.meta.version,n=t);return n}};export{t as WorkflowRegistry};
+import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
+
+//#region src/workflow/spec.ts
+init_registry_utils();
+function workflowKey(meta) {
+	return `${meta.key}.v${meta.version}`;
+}
+var WorkflowRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = workflowKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate workflow ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.key !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+	/** Filter workflows by criteria. */
+	filter(criteria) {
+		return filterBy(this.list(), criteria);
+	}
+	/** List workflows with specific tag. */
+	listByTag(tag) {
+		return this.list().filter((w) => w.meta.tags?.includes(tag));
+	}
+	/** List workflows by owner. */
+	listByOwner(owner) {
+		return this.list().filter((w) => w.meta.owners?.includes(owner));
+	}
+	/** Group workflows by key function. */
+	groupBy(keyFn) {
+		return groupBy(this.list(), keyFn);
+	}
+	/** Get unique tags from all workflows. */
+	getUniqueTags() {
+		return getUniqueTags(this.list());
+	}
+};
+
+//#endregion
+export { WorkflowRegistry };

package/dist/workflow/state.d.ts

@@ -0,0 +1,35 @@
+import { WorkflowStatus } from "./spec.js";
+
+//#region src/workflow/state.d.ts
+interface StepExecution {
+  stepId: string;
+  startedAt: Date;
+  completedAt?: Date;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+}
+interface WorkflowState {
+  workflowId: string;
+  workflowName: string;
+  workflowVersion: number;
+  currentStep: string;
+  data: Record<string, unknown>;
+  retryCounts?: Record<string, number>;
+  history: StepExecution[];
+  status: WorkflowStatus;
+  createdAt: Date;
+  updatedAt: Date;
+}
+interface WorkflowStateFilters {
+  status?: WorkflowStatus;
+}
+interface StateStore {
+  create(state: WorkflowState): Promise<void>;
+  get(workflowId: string): Promise<WorkflowState | undefined>;
+  update(workflowId: string, updater: (current: WorkflowState) => WorkflowState): Promise<WorkflowState>;
+  list(filters?: WorkflowStateFilters): Promise<WorkflowState[]>;
+}
+//#endregion
+export { StateStore, StepExecution, WorkflowState, WorkflowStateFilters };

package/dist/workflow/validation.d.ts

@@ -0,0 +1,29 @@
+import { WorkflowSpec } from "./spec.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { FormRegistry } from "../forms/forms.js";
+import "../forms/index.js";
+
+//#region src/workflow/validation.d.ts
+type WorkflowValidationLevel = 'error' | 'warning';
+interface WorkflowValidationIssue {
+  level: WorkflowValidationLevel;
+  message: string;
+  context?: Record<string, unknown>;
+}
+interface ValidateWorkflowSpecOptions {
+  operations?: OperationSpecRegistry;
+  forms?: FormRegistry;
+}
+declare class WorkflowValidationError extends Error {
+  readonly issues: WorkflowValidationIssue[];
+  constructor(message: string, issues: WorkflowValidationIssue[]);
+}
+/**
+ * Validate workflow structure, references, and reachability.
+ * Returns the collected issues. Consumers may call {@link assertWorkflowSpecValid}
+ * to throw on validation errors.
+ */
+declare function validateWorkflowSpec(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): WorkflowValidationIssue[];
+declare function assertWorkflowSpecValid(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): void;
+//#endregion
+export { ValidateWorkflowSpecOptions, WorkflowValidationError, WorkflowValidationIssue, WorkflowValidationLevel, assertWorkflowSpecValid, validateWorkflowSpec };