@duckflux/core 0.6.8

package/src/engine/output.ts

@@ -0,0 +1,109 @@
+import type { InputDefinition } from "../model/index";
+
+export function validateOutputSchema(
+  schema: Record<string, InputDefinition>,
+  result: Record<string, unknown>,
+): void {
+  for (const [fieldName, fieldDef] of Object.entries(schema)) {
+    const value = result[fieldName];
+
+    if (value === undefined || value === null) {
+      if (fieldDef.required) {
+        throw new Error(`output validation failed: required field '${fieldName}' is missing`);
+      }
+      continue;
+    }
+
+    validateValueAgainstField(fieldName, value, fieldDef);
+  }
+}
+
+function validateValueAgainstField(
+  fieldName: string,
+  value: unknown,
+  fieldDef: InputDefinition,
+): void {
+  if (fieldDef.type) {
+    validateType(fieldName, value, fieldDef.type);
+  }
+
+  if (fieldDef.enum !== undefined) {
+    if (!fieldDef.enum.some((e) => e === value)) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' value ${JSON.stringify(value)} is not in enum [${fieldDef.enum.map((e) => JSON.stringify(e)).join(", ")}]`,
+      );
+    }
+  }
+
+  if (typeof value === "string") {
+    if (fieldDef.minLength !== undefined && value.length < fieldDef.minLength) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' length ${value.length} is less than minLength ${fieldDef.minLength}`,
+      );
+    }
+    if (fieldDef.maxLength !== undefined && value.length > fieldDef.maxLength) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' length ${value.length} exceeds maxLength ${fieldDef.maxLength}`,
+      );
+    }
+    if (fieldDef.pattern !== undefined && !new RegExp(fieldDef.pattern).test(value)) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' does not match pattern '${fieldDef.pattern}'`,
+      );
+    }
+  }
+
+  if (typeof value === "number") {
+    if (fieldDef.minimum !== undefined && value < fieldDef.minimum) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' value ${value} is less than minimum ${fieldDef.minimum}`,
+      );
+    }
+    if (fieldDef.maximum !== undefined && value > fieldDef.maximum) {
+      throw new Error(
+        `output validation failed: field '${fieldName}' value ${value} exceeds maximum ${fieldDef.maximum}`,
+      );
+    }
+  }
+
+  if (Array.isArray(value) && fieldDef.items) {
+    for (let i = 0; i < value.length; i++) {
+      validateValueAgainstField(`${fieldName}[${i}]`, value[i], fieldDef.items);
+    }
+  }
+}
+
+function validateType(fieldName: string, value: unknown, expectedType: string): void {
+  switch (expectedType) {
+    case "string":
+      if (typeof value !== "string") {
+        throw new Error(`output validation failed: field '${fieldName}' expected string, got ${typeof value}`);
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        throw new Error(`output validation failed: field '${fieldName}' expected boolean, got ${typeof value}`);
+      }
+      break;
+    case "integer":
+      if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error(`output validation failed: field '${fieldName}' expected integer, got ${typeof value === "number" ? value : typeof value}`);
+      }
+      break;
+    case "number":
+      if (typeof value !== "number") {
+        throw new Error(`output validation failed: field '${fieldName}' expected number, got ${typeof value}`);
+      }
+      break;
+    case "array":
+      if (!Array.isArray(value)) {
+        throw new Error(`output validation failed: field '${fieldName}' expected array, got ${typeof value}`);
+      }
+      break;
+    case "object":
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`output validation failed: field '${fieldName}' expected object, got ${Array.isArray(value) ? "array" : typeof value}`);
+      }
+      break;
+  }
+}

package/src/engine/sequential.ts

@@ -0,0 +1,379 @@
+import { resolve as resolvePath, isAbsolute } from "node:path";
+import { evaluateCel, evalMaybeCel } from "../cel/index";
+import type { EventHub } from "../eventhub/types";
+import type {
+  ErrorStrategy,
+  Participant,
+  StepResult,
+  Workflow,
+} from "../model/index";
+import { executeParticipant } from "../participant/index";
+import type { WorkflowEngineExecutor } from "../participant/workflow";
+import { executeWithRetry, resolveErrorStrategy } from "./errors";
+import { validateOutputSchema } from "./output";
+import type { WorkflowState } from "./state";
+import { resolveTimeout, withTimeout } from "./timeout";
+
+function isControlFlowStep(step: unknown): boolean {
+  if (typeof step !== "object" || step == null || Array.isArray(step)) {
+    return false;
+  }
+
+  const keys = Object.keys(step as Record<string, unknown>);
+  return keys.length === 1 && ["loop", "parallel", "if", "wait"].includes(keys[0]);
+}
+
+function isInlineParticipant(step: unknown): boolean {
+  if (typeof step !== "object" || step == null || Array.isArray(step)) {
+    return false;
+  }
+  return "type" in (step as Record<string, unknown>);
+}
+
+function resolveParticipantInput(
+  participantInput: string | Record<string, string> | undefined,
+  state: WorkflowState,
+): unknown {
+  if (participantInput === undefined) {
+    return undefined;
+  }
+
+  if (typeof participantInput === "string") {
+    return evaluateCel(participantInput, state.toCelContext());
+  }
+
+  const resolved: Record<string, unknown> = {};
+  for (const [key, expr] of Object.entries(participantInput)) {
+    resolved[key] = evaluateCel(expr, state.toCelContext());
+  }
+  return resolved;
+}
+
+export function mergeChainedInput(chain: unknown, explicit: unknown): unknown {
+  if (explicit === undefined || explicit === null) return chain;
+  if (chain === undefined || chain === null) return explicit;
+
+  const chainIsMap = typeof chain === "object" && !Array.isArray(chain);
+  const explicitIsMap = typeof explicit === "object" && !Array.isArray(explicit);
+
+  if (chainIsMap && explicitIsMap) {
+    return { ...(chain as Record<string, unknown>), ...(explicit as Record<string, unknown>) };
+  }
+
+  if (typeof chain === "string" && typeof explicit === "string") {
+    return explicit;
+  }
+
+  // Spec §5.7: incompatible types (string vs map or vice versa) must raise an error
+  throw new Error(
+    `I/O chain type conflict: cannot merge ${Array.isArray(chain) ? "array" : typeof chain} chain with ${Array.isArray(explicit) ? "array" : typeof explicit} input`,
+  );
+}
+
+type FlowOverride = {
+  timeout?: string;
+  onError?: ErrorStrategy;
+  when?: string;
+  input?: string | Record<string, string>;
+  retry?: {
+    max: number;
+    backoff?: string;
+    factor?: number;
+  };
+};
+
+export async function executeStep(
+  workflow: Workflow,
+  state: WorkflowState,
+  step: unknown,
+  basePath = process.cwd(),
+  engineExecutor?: WorkflowEngineExecutor,
+  fallbackStack: string[] = [],
+  chain?: unknown,
+  hub?: EventHub,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  if (signal?.aborted) {
+    throw new Error("execution aborted");
+  }
+
+  if (isControlFlowStep(step)) {
+    throw new Error("control-flow construct passed to executeStep");
+  }
+
+  let stepName: string | undefined;
+  let participant: Participant;
+  let override: FlowOverride | undefined;
+
+  if (typeof step === "string") {
+    // Named participant reference
+    stepName = step;
+    const p = workflow.participants?.[stepName];
+    if (!p) {
+      throw new Error(`participant '${stepName}' not found`);
+    }
+    participant = p;
+  } else if (isInlineParticipant(step)) {
+    // Inline participant
+    const inline = step as Participant & { as?: string; when?: string };
+    stepName = inline.as;
+    participant = inline;
+  } else if (typeof step === "object" && step != null && !Array.isArray(step)) {
+    // Participant override
+    const keys = Object.keys(step);
+    if (keys.length !== 1) {
+      throw new Error("invalid flow step override");
+    }
+    stepName = keys[0];
+    override = (step as Record<string, FlowOverride>)[stepName];
+    const p = workflow.participants?.[stepName];
+    if (!p) {
+      throw new Error(`participant '${stepName}' not found`);
+    }
+    participant = p;
+  } else {
+    throw new Error("invalid flow step");
+  }
+
+  const mergedParticipant: Participant = {
+    ...participant,
+    ...(override ?? {}),
+  } as Participant;
+
+  // When guard - boolean strictness
+  const whenExpression = override?.when ?? participant.when;
+  if (whenExpression) {
+    const shouldRun = evaluateCel(whenExpression, state.toCelContext());
+    if (shouldRun !== true) {
+      if (stepName) {
+        state.setResult(stepName, {
+          status: "skipped",
+          output: "",
+          duration: 0,
+        });
+      }
+      return chain; // Skipped steps preserve chain
+    }
+  }
+
+  // Resolve participant base input and flow override input separately,
+  // then merge per v0.5 spec: chain < participant base input < flow override input.
+  const baseInput = resolveParticipantInput(participant.input, state);
+  const overrideInput = override?.input !== undefined
+    ? resolveParticipantInput(override.input, state)
+    : undefined;
+  const mergedWithBase = mergeChainedInput(chain, baseInput);
+  const mergedInput = mergeChainedInput(mergedWithBase, overrideInput);
+
+  // Set participant-scoped input in state
+  state.currentInput = mergedInput;
+
+  const strategy = resolveErrorStrategy(override ?? null, participant, workflow.defaults ?? null);
+  const timeoutMs = resolveTimeout(override ?? null, participant, workflow.defaults ?? null);
+  const retryConfig = strategy === "retry" ? mergedParticipant.retry : undefined;
+
+  const startedAt = new Date().toISOString();
+
+  // Build CEL context for participants that need it (e.g. emit, http CEL fields)
+  const celContext = state.toCelContext();
+
+  // Resolve CEL expressions in HTTP participant fields (url, headers, body)
+  if (mergedParticipant.type === "http") {
+    const http = mergedParticipant as import("../model/index").HttpParticipant;
+    http.url = String(evalMaybeCel(http.url, celContext));
+    if (http.headers) {
+      const resolvedHeaders: Record<string, string> = {};
+      for (const [k, v] of Object.entries(http.headers)) {
+        resolvedHeaders[k] = String(evalMaybeCel(v, celContext));
+      }
+      http.headers = resolvedHeaders;
+    }
+    if (http.body !== undefined) {
+      http.body = evalMaybeCel(http.body, celContext) as string | Record<string, unknown>;
+    }
+  }
+
+  // Resolve CEL expressions in CWD (exec participant)
+  // Spec §8.1: participant.cwd > defaults.cwd > CLI --cwd > process cwd
+  if (mergedParticipant.type === "exec") {
+    const exec = mergedParticipant as import("../model/index").ExecParticipant;
+    let resolvedCwd: string | undefined;
+    if (exec.cwd) {
+      resolvedCwd = String(evalMaybeCel(exec.cwd, celContext));
+    } else if (workflow.defaults?.cwd) {
+      resolvedCwd = String(evalMaybeCel(workflow.defaults.cwd, celContext));
+    } else if (state.executionMeta.cwd && state.executionMeta.cwd !== process.cwd()) {
+      // Fall back to CLI --cwd (stored in execution.cwd)
+      resolvedCwd = state.executionMeta.cwd;
+    }
+    if (resolvedCwd && !isAbsolute(resolvedCwd)) {
+      resolvedCwd = resolvePath(basePath, resolvedCwd);
+    }
+    if (resolvedCwd) {
+      exec.cwd = resolvedCwd;
+    }
+  }
+
+  const executeOnce = async (): Promise<StepResult> => {
+    const invoke = async (): Promise<StepResult> => {
+      const result = await executeParticipant(
+        mergedParticipant,
+        mergedInput,
+        {},
+        basePath,
+        engineExecutor,
+        hub,
+        celContext,
+        state.ancestorPaths,
+      );
+
+      if (result.status === "failure") {
+        throw new Error(
+          result.error ||
+          `participant '${stepName ?? "anonymous"}' (type: ${mergedParticipant.type}) failed`,
+        );
+      }
+
+      return result;
+    };
+
+    if (timeoutMs === undefined) {
+      return invoke();
+    }
+
+    return withTimeout(invoke, timeoutMs);
+  };
+
+  try {
+    let result: StepResult;
+    let retries = 0;
+    if (strategy === "retry") {
+      const retryResult = await executeWithRetry(executeOnce, retryConfig, stepName ?? "<anonymous>");
+      result = retryResult.result;
+      retries = retryResult.attempts;
+    } else {
+      result = await executeOnce();
+    }
+
+    result.startedAt = result.startedAt ?? startedAt;
+    result.finishedAt = result.finishedAt ?? new Date().toISOString();
+    result.retries = retries;
+
+    // Validate participant output schema (§5.6)
+    const outputSchema = mergedParticipant.output as Record<string, import("../model/index").InputDefinition> | undefined;
+    if (outputSchema && Object.keys(outputSchema).length > 0) {
+      const outputData = result.parsedOutput ?? result.output;
+      if (typeof outputData === "object" && outputData !== null) {
+        validateOutputSchema(outputSchema, outputData as Record<string, unknown>);
+      } else {
+        // Scalar output but schema expects object fields — validation error
+        throw new Error(
+          `output validation failed: expected object with fields [${Object.keys(outputSchema).join(", ")}] but got ${typeof outputData}`,
+        );
+      }
+    }
+
+    if (stepName) {
+      state.setResult(stepName, result);
+    }
+
+    // Update participant-scoped output and chain
+    const outputValue = result.parsedOutput ?? result.output;
+    state.currentOutput = outputValue;
+    return outputValue;
+  } catch (error) {
+    const message = String((error as Error)?.message ?? error);
+    const finishedAt = new Date().toISOString();
+    // Capture HTTP metadata from error if available
+    const httpMeta: { httpStatus?: number; responseBody?: string } = {};
+    if (error && typeof error === "object") {
+      const errObj = error as Record<string, unknown>;
+      if (typeof errObj.httpStatus === "number") httpMeta.httpStatus = errObj.httpStatus;
+      if (typeof errObj.responseBody === "string") httpMeta.responseBody = errObj.responseBody;
+    }
+
+    if (strategy === "skip") {
+      const skipResult: StepResult = {
+        status: "skipped",
+        output: "",
+        error: message,
+        duration: 0,
+        startedAt,
+        finishedAt,
+        ...httpMeta,
+      };
+      if (stepName) {
+        state.setResult(stepName, skipResult);
+      }
+      return chain; // Skipped steps preserve chain
+    }
+
+    if (strategy !== "fail" && strategy !== "retry") {
+      // Fallback to another participant
+      const fallbackName = strategy;
+      if (fallbackStack.includes(fallbackName)) {
+        throw new Error(`fallback cycle detected on participant '${fallbackName}'`);
+      }
+
+      // Keep original step as failure (Go runner behavior)
+      if (stepName) {
+        state.setResult(stepName, {
+          status: "failure",
+          output: "",
+          error: message,
+          duration: 0,
+          startedAt,
+          finishedAt,
+          ...httpMeta,
+        });
+      }
+
+      // Execute fallback
+      const fallbackResult = await executeStep(
+        workflow,
+        state,
+        fallbackName,
+        basePath,
+        engineExecutor,
+        [...fallbackStack, stepName ?? "<anonymous>"],
+        chain,
+        hub,
+      );
+
+      return fallbackResult;
+    }
+
+    if (stepName) {
+      state.setResult(stepName, {
+        status: "failure",
+        output: "",
+        error: message,
+        duration: 0,
+        startedAt,
+        finishedAt,
+        ...httpMeta,
+      });
+    }
+
+    throw error;
+  }
+}
+
+export async function executeSequential(
+  workflow: Workflow,
+  state: WorkflowState,
+  steps: unknown[],
+  basePath = process.cwd(),
+  engineExecutor?: WorkflowEngineExecutor,
+  chain?: unknown,
+  hub?: EventHub,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  let currentChain = chain;
+  for (const step of steps) {
+    // Import executeControlStep dynamically to avoid circular dependency
+    const { executeControlStep } = await import("./control");
+    currentChain = await executeControlStep(workflow, state, step, basePath, engineExecutor, currentChain, hub, signal);
+  }
+  return currentChain;
+}

package/src/engine/state.ts

@@ -0,0 +1,185 @@
+import { env } from "node:process";
+import type { StepResult } from "../model/index";
+
+export type { StepResult };
+
+export class WorkflowState {
+  readonly inputs: Record<string, unknown>;
+  private results: Map<string, StepResult>;
+  private loopStack: Array<{ index: number; as?: string; last?: boolean }>;
+
+  // v0.3 fields
+  workflowInputs: Record<string, unknown>;
+  workflowMeta: { id?: string; name?: string; version?: string | number };
+  executionMeta: {
+    id: string;
+    number?: number;
+    startedAt: string;
+    status: string;
+    context?: Record<string, unknown>;
+    cwd: string;
+  };
+  currentInput: unknown;
+  currentOutput: unknown;
+  chainValue: unknown;
+  eventPayload: unknown;
+  /** @internal Tracks ancestor workflow paths for circular sub-workflow detection */
+  ancestorPaths: Set<string>;
+
+  constructor(inputs: Record<string, unknown> = {}) {
+    this.inputs = { ...inputs };
+    this.workflowInputs = { ...inputs };
+    this.workflowMeta = {};
+    this.executionMeta = {
+      id: crypto.randomUUID(),
+      startedAt: new Date().toISOString(),
+      status: "running",
+      cwd: process.cwd(),
+    };
+    this.currentInput = undefined;
+    this.currentOutput = undefined;
+    this.chainValue = undefined;
+    this.eventPayload = undefined;
+    this.ancestorPaths = new Set();
+    this.results = new Map();
+    this.loopStack = [];
+  }
+
+  setResult(stepName: string, result: StepResult): void {
+    this.results.set(stepName, result);
+  }
+
+  getResult(stepName: string): StepResult | undefined {
+    return this.results.get(stepName);
+  }
+
+  getAllResults(): Record<string, StepResult> {
+    const out: Record<string, StepResult> = {};
+    for (const [k, v] of this.results.entries()) out[k] = v;
+    return out;
+  }
+
+  pushLoop(as?: string): void {
+    this.loopStack.push({ index: 0, as });
+  }
+
+  incrementLoop(): void {
+    const top = this.loopStack[this.loopStack.length - 1];
+    if (top) top.index += 1;
+  }
+
+  popLoop(): void {
+    this.loopStack.pop();
+  }
+
+  currentLoopIndex(): number {
+    const top = this.loopStack[this.loopStack.length - 1];
+    return top ? top.index : 0;
+  }
+
+  setLoopLast(last: boolean): void {
+    const top = this.loopStack[this.loopStack.length - 1];
+    if (top) top.last = last;
+  }
+
+  currentLoopContext(): { index: number; iteration: number; first: boolean; last: boolean; as?: string } {
+    const top = this.loopStack[this.loopStack.length - 1];
+    if (!top) return { index: 0, iteration: 1, first: true, last: false };
+    return {
+      index: top.index,
+      iteration: top.index + 1,
+      first: top.index === 0,
+      last: top.last ?? false,
+      as: top.as,
+    };
+  }
+
+  toCelContext(): Record<string, unknown> {
+    const ctx: Record<string, unknown> = {};
+
+    // Step results (v0.3: <step>.output, <step>.status, etc.)
+    for (const [name, res] of this.results.entries()) {
+      ctx[name] = {
+        output: res.parsedOutput ?? res.output,
+        status: res.status,
+        startedAt: res.startedAt,
+        finishedAt: res.finishedAt,
+        duration: res.duration,
+        retries: res.retries ?? 0,
+        error: res.error,
+        cwd: res.cwd,
+      };
+    }
+
+    // v0.3 namespaces
+    ctx["workflow"] = {
+      id: this.workflowMeta.id,
+      name: this.workflowMeta.name,
+      version: this.workflowMeta.version,
+      inputs: this.workflowInputs,
+      output: null, // resolved at end
+    };
+
+    ctx["execution"] = { ...this.executionMeta };
+
+    // Participant-scoped input/output
+    ctx["input"] = this.currentInput ?? {};
+    ctx["output"] = this.currentOutput ?? {};
+
+    // Environment
+    ctx["env"] = { ...env };
+
+    // Loop context
+    const loopCtx = this.currentLoopContext();
+    const loopObj = {
+      index: loopCtx.index,
+      iteration: loopCtx.iteration,
+      first: loopCtx.first,
+      last: loopCtx.last,
+    };
+
+    // If loop has custom `as`, expose under that name; also keep `loop` for compat
+    if (loopCtx.as) {
+      ctx[`_${loopCtx.as}`] = loopObj;
+    }
+    ctx["_loop"] = loopObj;
+    ctx["loop"] = loopObj;
+
+    // Event payload
+    ctx["event"] = this.eventPayload ?? {};
+
+    // Now — epoch seconds to match timestamp() and Go runner behavior (Spec §12.9)
+    ctx["now"] = Math.floor(Date.now() / 1000);
+
+    return ctx;
+  }
+
+  resolveOutput(
+    outputDef: string | Record<string, string> | { schema: Record<string, unknown>; map: Record<string, string> },
+    celEvaluator: (expr: string, ctx: Record<string, unknown>) => unknown,
+  ): unknown {
+    const ctx = this.toCelContext();
+
+    // schema+map variant
+    if (typeof outputDef === "object" && "map" in outputDef && "schema" in outputDef) {
+      const result: Record<string, unknown> = {};
+      for (const [k, expr] of Object.entries(outputDef.map)) {
+        result[k] = celEvaluator(expr, ctx);
+      }
+      return result;
+    }
+
+    if (typeof outputDef === "string") {
+      return celEvaluator(outputDef, ctx);
+    }
+
+    const result: Record<string, unknown> = {};
+    for (const k of Object.keys(outputDef)) {
+      const expr = (outputDef as Record<string, string>)[k];
+      result[k] = celEvaluator(expr, ctx);
+    }
+    return result;
+  }
+}
+
+export default WorkflowState;