@contractspec/lib.contracts-spec 2.0.0

package/dist/workflow/runner.js

@@ -0,0 +1,532 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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;
+    const left = resolveRoot(root, ctx, path);
+    const right = parseLiteral(rawRight);
+    return compare(left, right, 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;
+  return trimmed;
+}
+function resolveRoot(root, ctx, path) {
+  const source = root === "data" ? ctx.data : root === "input" ? ctx.input : ctx.output;
+  return resolvePath(source, path);
+}
+function resolvePath(source, path) {
+  if (source == null)
+    return;
+  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;
+    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;
+}
+
+// src/workflow/runner.ts
+import { randomUUID } from "crypto";
+class WorkflowRunner {
+  config;
+  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 = 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) : undefined;
+    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);
+    const guardOk = await this.evaluateGuard(step, state, input);
+    if (!guardOk)
+      throw new Error(`GuardRejected: ${state.workflowName} -> ${step.id}`);
+    const execution = {
+      stepId: step.id,
+      startedAt: 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 = new Date;
+      workingState.history.push(execution);
+      workingState.updatedAt = 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 = new Date;
+      execution.error = error instanceof Error ? error.message : String(error);
+      workingState.history.push(execution);
+      workingState.updatedAt = 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 ?? 1000;
+          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) : undefined;
+          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: 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 = 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.`
+          });
+        }
+      }
+    }
+    const canStart = issues.every((issue) => issue.severity !== "error");
+    return { canStart, 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) : undefined;
+      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";
+}
+
+class WorkflowPreFlightError extends Error {
+  issues;
+  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}`;
+}
+export {
+  WorkflowRunner,
+  WorkflowPreFlightError
+};

package/dist/workflow/runner.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+import type { WorkflowState } from './state';
+import type { WorkflowSpec } from './spec';
+export interface SLABreachEvent {
+    workflowId: string;
+    workflowName: string;
+    type: 'workflow_duration' | 'step_duration';
+    stepId?: string;
+    expectedMs: number;
+    actualMs: number;
+    breachedAt: Date;
+}
+export declare class SLAMonitor {
+    private readonly eventEmitter;
+    constructor(eventEmitter: (event: string, payload: SLABreachEvent) => void);
+    check(state: WorkflowState, spec: WorkflowSpec): void;
+}

package/dist/workflow/sla-monitor.js

@@ -0,0 +1,84 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/workflow/sla-monitor.ts
+class SLAMonitor {
+  eventEmitter;
+  constructor(eventEmitter) {
+    this.eventEmitter = eventEmitter;
+  }
+  check(state, spec) {
+    const sla = spec.definition.sla;
+    if (!sla)
+      return;
+    const now = 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: 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: new Date
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+}
+export {
+  SLAMonitor
+};