@contractspec/lib.contracts 1.44.0

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 };

package/dist/workflow/spec.d.ts

@@ -0,0 +1,106 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { CapabilityRef } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { ExperimentRef } from "../experiments/spec.js";
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { OpRef } from "../features/types.js";
+import "../features/index.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

@@ -0,0 +1,55 @@
+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 };