@theokit/sdk 4.23.0 → 4.25.0

package/dist/executor-Y4MKPIUD.cjs

@@ -0,0 +1,985 @@
+'use strict';
+
+var chunkBWT67BI4_cjs = require('./chunk-BWT67BI4.cjs');
+var chunkBUUUWQMB_cjs = require('./chunk-BUUUWQMB.cjs');
+var chunk7S7KKUO6_cjs = require('./chunk-7S7KKUO6.cjs');
+require('./chunk-TIZ4TS5V.cjs');
+var chunkA44COQJJ_cjs = require('./chunk-A44COQJJ.cjs');
+var chunkBEURCLDV_cjs = require('./chunk-BEURCLDV.cjs');
+
+// src/internal/workflow/ctx.ts
+var WorkflowSuspendedSentinel = class extends Error {
+  constructor(payload) {
+    super("__workflow_suspended__");
+    this.payload = payload;
+  }
+  payload;
+  name = "WorkflowSuspendedSentinel";
+};
+function makeStepContext(runId, signal, state) {
+  return {
+    runId,
+    signal,
+    log: {
+      debug: (msg, attrs) => emit("debug", runId, msg, attrs),
+      info: (msg, attrs) => emit("info", runId, msg, attrs),
+      warn: (msg, attrs) => emit("warn", runId, msg, attrs)
+    },
+    suspend: async (payload) => {
+      throw new WorkflowSuspendedSentinel(payload);
+    },
+    // SE29 — read reflects the current shared state; write goes through the
+    // controller (which validates against `stateSchema`).
+    get state() {
+      return state.getState();
+    },
+    setState: (next) => state.setState(next)
+  };
+}
+function emit(level, runId, msg, attrs) {
+  const tag = `[workflow ${runId}]`;
+  if (attrs !== void 0) {
+    if (level === "warn") console.warn(tag, msg, attrs);
+    else console.log(tag, msg, attrs);
+  } else {
+    if (level === "warn") console.warn(tag, msg);
+    else console.log(tag, msg);
+  }
+}
+function combineSignals(...signals) {
+  const valid = signals.filter((s) => s !== void 0);
+  if (valid.length === 0) return new AbortController().signal;
+  if (valid.length === 1) return valid[0];
+  const ctrl = new AbortController();
+  for (const s of valid) {
+    if (s.aborted) {
+      ctrl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+  }
+  return ctrl.signal;
+}
+
+// src/internal/workflow/error-shape.ts
+function errToShape(err) {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message };
+  }
+  return { name: "Error", message: String(err) };
+}
+
+// src/internal/workflow/executor-helpers.ts
+function assembleRun(params) {
+  return {
+    id: params.runId,
+    name: params.name,
+    status: params.status,
+    startedAt: params.startedAt,
+    endedAt: Date.now(),
+    stepResults: params.stepResults,
+    ...params.output !== void 0 ? { output: params.output } : {},
+    ...params.error !== void 0 ? { error: params.error } : {}
+  };
+}
+function abortRun(name, runId, startedAt, stepResults, signal) {
+  return assembleRun({
+    runId,
+    name,
+    status: "cancelled",
+    stepResults,
+    startedAt,
+    error: { name: "AbortError", message: String(signal.reason ?? "Aborted") }
+  });
+}
+function validateWorkflowSchema(schema, value) {
+  if (schema === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = schema.safeParse(value);
+  } catch {
+    return "schema uses async refinements, which whole-workflow validation does not support (use a synchronous Zod schema)";
+  }
+  if (parsed.success) return void 0;
+  return parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+}
+function makeStateController(options, initial) {
+  let current = initial;
+  return {
+    getState: () => current,
+    setState: (next) => {
+      const issues = validateWorkflowSchema(options.stateSchema, next);
+      if (issues !== void 0) throw new chunkBWT67BI4_cjs.WorkflowStateError(options.name, issues);
+      current = next;
+    }
+  };
+}
+
+// src/internal/workflow/run-id.ts
+function mintRunId() {
+  return `wfr-${globalThis.crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+
+// src/internal/workflow/single-flight.ts
+var registry = /* @__PURE__ */ new Map();
+function key(workflowId, runId) {
+  return `${workflowId}:${runId}`;
+}
+function acquireSingleFlight(workflowId, runId, workflowName) {
+  const k = key(workflowId, runId);
+  if (registry.has(k)) {
+    throw new chunkBWT67BI4_cjs.WorkflowAlreadyRunningError(workflowName, runId);
+  }
+  const controller = new AbortController();
+  registry.set(k, { controller });
+  return {
+    signal: controller.signal,
+    release: () => {
+      registry.delete(k);
+    }
+  };
+}
+
+// src/internal/workflow/retry-policy.ts
+var DEFAULT_NON_RETRYABLE = ["AbortError", "WorkflowSnapshotNotFoundError", "ConfigurationError"];
+function backoffConfigFromPolicy(policy) {
+  return {
+    max: policy.maxAttempts,
+    init: policy.initialBackoffMs ?? 1e3,
+    coef: policy.backoffCoefficient ?? 2,
+    cap: policy.maximumBackoffMs ?? 3e4,
+    nonRetryable: new Set(policy.nonRetryableErrors ?? DEFAULT_NON_RETRYABLE)
+  };
+}
+function throwIfAborted(signal) {
+  if (signal.aborted) {
+    throw new DOMException(String(signal.reason ?? "Aborted"), "AbortError");
+  }
+}
+function shouldRethrow(err, attempt, cfg) {
+  const errName = err instanceof Error ? err.name : "Error";
+  return cfg.nonRetryable.has(errName) || attempt === cfg.max;
+}
+async function tryOnce(fn, attempt, cfg, signal) {
+  try {
+    const value = await fn();
+    return { value, attempts: attempt };
+  } catch (err) {
+    if (shouldRethrow(err, attempt, cfg)) throw err;
+    await abortableSleep(Math.min(cfg.init * cfg.coef ** (attempt - 1), cfg.cap), signal);
+    return { kind: "retry" };
+  }
+}
+async function withRetry(fn, policy, signal) {
+  const cfg = backoffConfigFromPolicy(policy);
+  for (let attempt = 1; attempt <= cfg.max; attempt += 1) {
+    throwIfAborted(signal);
+    const result = await tryOnce(fn, attempt, cfg, signal);
+    if ("value" in result) return result;
+  }
+  throw new Error("withRetry: exhausted attempts without throwing");
+}
+async function abortableSleep(ms, signal) {
+  if (signal.aborted) {
+    throw new DOMException(String(signal.reason ?? "Aborted"), "AbortError");
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(new DOMException(String(signal.reason ?? "Aborted"), "AbortError"));
+    };
+    const cleanup = () => {
+      signal.removeEventListener("abort", onAbort);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/internal/workflow/step-agent.ts
+async function runAgentStep(step, input, ctx) {
+  const startedAt = Date.now();
+  const agentId = step.agent.agentId;
+  if (typeof agentId === "string" && agentId.startsWith("bc-")) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new chunkA44COQJJ_cjs.UnsupportedRunOperationError(
+          `Workflow agent steps not supported on CloudAgent yet (D244). agent="${agentId}", step="${step.id}"`,
+          "workflow"
+        )
+      )
+    };
+  }
+  let prompt;
+  try {
+    prompt = typeof step.promptTemplate === "string" ? step.promptTemplate : step.promptTemplate(input);
+  } catch (err) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+  if (typeof prompt !== "string" || prompt.length === 0) {
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(`agentStep "${step.id}": rendered prompt must be a non-empty string`)
+      )
+    };
+  }
+  const exec = async () => {
+    const run = await step.agent.send(
+      prompt,
+      step.origin !== void 0 ? { origin: step.origin } : void 0
+    );
+    const result = await run.wait();
+    if (result.status === "finished") {
+      return result.result ?? "";
+    }
+    if (result.status === "error") {
+      throw result.error ?? new Error("agent.send errored");
+    }
+    throw new Error(`Unexpected agent status: ${result.status}`);
+  };
+  try {
+    const { value, attempts } = step.retry !== void 0 ? await withRetry(exec, step.retry, ctx.signal) : { value: await exec(), attempts: 1 };
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "completed",
+      attempts,
+      durationMs: Date.now() - startedAt,
+      output: value
+    };
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) throw err;
+    return {
+      stepId: step.id,
+      kind: "agent",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+}
+
+// src/internal/workflow/step-branch.ts
+async function runBranchStep(step, input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  for (let i = 0; i < step.predicates.length; i += 1) {
+    const pair = step.predicates[i];
+    const [predicate, branch] = pair;
+    let matched = false;
+    try {
+      matched = await Promise.resolve(predicate(input));
+    } catch (err) {
+      const errText = err instanceof Error ? err.message : String(err);
+      console.warn(
+        chunkBEURCLDV_cjs.redactSecrets(
+          `[workflow] branch "${step.id}" predicate ${i} threw, treating as no-match: ${errText}`
+        )
+      );
+    }
+    if (matched) {
+      const r = await runInnerSequence(branch, input, ctx, options, prevStepResults, dispatch);
+      return {
+        ...r,
+        stepId: step.id,
+        kind: "branch",
+        durationMs: Date.now() - startedAt
+      };
+    }
+  }
+  if (step.fallback !== void 0) {
+    const r = await runInnerSequence(step.fallback, input, ctx, options, prevStepResults, dispatch);
+    return {
+      ...r,
+      stepId: step.id,
+      kind: "branch",
+      durationMs: Date.now() - startedAt
+    };
+  }
+  return {
+    stepId: step.id,
+    kind: "branch",
+    status: "skipped",
+    attempts: 0,
+    durationMs: Date.now() - startedAt,
+    output: input
+  };
+}
+async function runInnerSequence(branch, input, ctx, options, prevStepResults, dispatch) {
+  let acc = input;
+  let lastAttempts = 1;
+  for (const inner of branch) {
+    const r = await dispatch(inner, acc, ctx, options, prevStepResults);
+    lastAttempts = r.attempts;
+    if (r.status === "failed") {
+      return {
+        stepId: inner.id,
+        kind: "branch",
+        status: "failed",
+        attempts: r.attempts,
+        durationMs: 0,
+        error: r.error ?? errToShape(new Error("branch inner step failed"))
+      };
+    }
+    acc = r.output;
+  }
+  return {
+    stepId: "__branch-completed__",
+    kind: "branch",
+    status: "completed",
+    attempts: lastAttempts,
+    durationMs: 0,
+    output: acc
+  };
+}
+
+// src/internal/workflow/step-dowhile.ts
+async function runDowhileStep(step, input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const maxIter = step.maxIterations ?? 100;
+  let acc = input;
+  let i = 0;
+  while (true) {
+    if (i >= maxIter) {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(new chunkBWT67BI4_cjs.WorkflowMaxIterationsExceededError(step.id, maxIter))
+      };
+    }
+    const r = await dispatch(step.step, acc, ctx, options, prevStepResults);
+    if (r.status === "failed") {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i + 1,
+        durationMs: Date.now() - startedAt,
+        error: r.error
+      };
+    }
+    acc = r.output;
+    i += 1;
+    let shouldContinue = false;
+    try {
+      shouldContinue = await Promise.resolve(step.condFn(acc, i));
+    } catch (err) {
+      return {
+        stepId: step.id,
+        kind: "dowhile",
+        status: "failed",
+        attempts: i,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(err)
+      };
+    }
+    if (!shouldContinue) break;
+  }
+  return {
+    stepId: step.id,
+    kind: "dowhile",
+    status: "completed",
+    attempts: i,
+    durationMs: Date.now() - startedAt,
+    output: acc
+  };
+}
+
+// src/internal/workflow/step-fn.ts
+function failedFnResult(stepId, attempts, startedAt, err) {
+  return {
+    stepId,
+    kind: "fn",
+    status: "failed",
+    attempts,
+    durationMs: Date.now() - startedAt,
+    error: errToShape(err)
+  };
+}
+function validate(schema, value) {
+  if (schema === void 0) return void 0;
+  schema.parse(value);
+  return void 0;
+}
+async function execWithRetry(step, input, ctx) {
+  const exec = async () => step.fn(input, ctx);
+  if (step.retry !== void 0) return withRetry(exec, step.retry, ctx.signal);
+  return { value: await exec(), attempts: 1 };
+}
+async function runFnStep(step, input, ctx) {
+  const startedAt = Date.now();
+  if (step.compensate !== void 0) {
+    return failedFnResult(
+      step.id,
+      0,
+      startedAt,
+      new chunkBWT67BI4_cjs.WorkflowCompensateNotImplementedError(step.id)
+    );
+  }
+  try {
+    validate(step.inputSchema, input);
+  } catch (err) {
+    return failedFnResult(step.id, 0, startedAt, err);
+  }
+  try {
+    const { value, attempts } = await execWithRetry(step, input, ctx);
+    try {
+      validate(step.outputSchema, value);
+    } catch (err) {
+      return failedFnResult(step.id, attempts, startedAt, err);
+    }
+    return {
+      stepId: step.id,
+      kind: "fn",
+      status: "completed",
+      attempts,
+      durationMs: Date.now() - startedAt,
+      output: value
+    };
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) throw err;
+    return failedFnResult(step.id, 1, startedAt, err);
+  }
+}
+
+// src/internal/workflow/step-foreach.ts
+async function runForeachStep(step, _input, ctx, options, prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const sourceResult = prevStepResults.find((r) => r.stepId === step.iterableFrom);
+  if (sourceResult === void 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(
+          `foreach.iterableFrom "${step.iterableFrom}" not found in top-level steps. It must reference an earlier top-level step ID \u2014 nested step IDs inside parallel/branch/foreach blocks are not visible here.`
+        )
+      )
+    };
+  }
+  const items = sourceResult.output;
+  if (!Array.isArray(items)) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 0,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new Error(
+          `foreach.iterableFrom "${step.iterableFrom}" output must be Array, got ${typeof items}.`
+        )
+      )
+    };
+  }
+  if (items.length === 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: []
+    };
+  }
+  const concurrency = step.concurrency ?? 4;
+  const sem = chunk7S7KKUO6_cjs.createSemaphore(Math.max(1, Math.min(concurrency, items.length)));
+  const failures = [];
+  const outputs = new Array(items.length);
+  await Promise.all(
+    items.map(async (item, idx) => {
+      const release = await sem.acquire();
+      try {
+        const r = await dispatch(step.step, item, ctx, options, prevStepResults);
+        if (r.status === "failed") {
+          failures.push(new Error(`foreach item ${idx} failed: ${r.error?.message ?? "unknown"}`));
+        } else {
+          outputs[idx] = r.output;
+        }
+      } finally {
+        release();
+      }
+    })
+  );
+  if (failures.length > 0) {
+    return {
+      stepId: step.id,
+      kind: "foreach",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(
+        new AggregateError(failures, `foreach "${step.id}" had ${failures.length} failure(s)`)
+      )
+    };
+  }
+  return {
+    stepId: step.id,
+    kind: "foreach",
+    status: "completed",
+    attempts: 1,
+    durationMs: Date.now() - startedAt,
+    output: outputs
+  };
+}
+
+// src/internal/workflow/step-parallel.ts
+async function runParallelStep(step, input, ctx, options, _prevStepResults, dispatch) {
+  const startedAt = Date.now();
+  const policy = step.errorPolicy ?? "fail-fast";
+  const branchCount = step.branches.length;
+  if (branchCount === 0) {
+    return {
+      stepId: step.id,
+      kind: "parallel",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: []
+    };
+  }
+  const concurrency = step.concurrency ?? branchCount;
+  const sem = chunk7S7KKUO6_cjs.createSemaphore(Math.max(1, Math.min(concurrency, branchCount)));
+  const failFastCtrl = policy === "fail-fast" ? new AbortController() : void 0;
+  const branchSignal = policy === "fail-fast" ? mergeSignals(ctx.signal, failFastCtrl.signal) : ctx.signal;
+  const semBranchPromises = step.branches.map(async (branch, branchIdx) => {
+    const release = await sem.acquire();
+    try {
+      return await runBranch(
+        branch,
+        input,
+        { ...ctx, signal: branchSignal },
+        options,
+        dispatch,
+        branchIdx
+      );
+    } finally {
+      release();
+    }
+  });
+  if (policy === "fail-fast") {
+    try {
+      const outputs2 = await Promise.all(semBranchPromises);
+      return {
+        stepId: step.id,
+        kind: "parallel",
+        status: "completed",
+        attempts: 1,
+        durationMs: Date.now() - startedAt,
+        output: outputs2
+      };
+    } catch (err) {
+      failFastCtrl?.abort(err);
+      const settled2 = await Promise.allSettled(semBranchPromises);
+      const errors = settled2.filter((s) => s.status === "rejected").map((s) => s.reason instanceof Error ? s.reason : new Error(String(s.reason)));
+      return {
+        stepId: step.id,
+        kind: "parallel",
+        status: "failed",
+        attempts: 1,
+        durationMs: Date.now() - startedAt,
+        error: errToShape(new chunkBWT67BI4_cjs.WorkflowParallelError(errors, step.id)),
+        output: void 0
+      };
+    }
+  }
+  const settled = await Promise.allSettled(semBranchPromises);
+  const outputs = settled.map(
+    (s) => s.status === "fulfilled" ? { ok: true, value: s.value } : { ok: false, error: errToShape(s.reason) }
+  );
+  return {
+    stepId: step.id,
+    kind: "parallel",
+    status: "completed",
+    attempts: 1,
+    durationMs: Date.now() - startedAt,
+    output: outputs
+  };
+}
+async function runBranch(branch, input, ctx, options, dispatch, branchIdx) {
+  let acc = input;
+  for (const inner of branch) {
+    const r = await dispatch(inner, acc, ctx, options, []);
+    if (r.status === "failed") {
+      throw new Error(
+        `parallel branch ${branchIdx} step "${inner.id}" failed: ${r.error?.message ?? "unknown"}`
+      );
+    }
+    acc = r.output;
+  }
+  return acc;
+}
+function mergeSignals(a, b) {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const ctrl = new AbortController();
+  const onAbortA = () => ctrl.abort(a.reason);
+  const onAbortB = () => ctrl.abort(b.reason);
+  a.addEventListener("abort", onAbortA, { once: true });
+  b.addEventListener("abort", onAbortB, { once: true });
+  return ctrl.signal;
+}
+
+// src/internal/workflow/step-sleep.ts
+async function runSleepStep(step, input, ctx) {
+  const startedAt = Date.now();
+  try {
+    await abortableSleep(step.durationMs, ctx.signal);
+    return {
+      stepId: step.id,
+      kind: "sleep",
+      status: "completed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      output: input
+      // sleep is a pass-through
+    };
+  } catch (err) {
+    return {
+      stepId: step.id,
+      kind: "sleep",
+      status: "failed",
+      attempts: 1,
+      durationMs: Date.now() - startedAt,
+      error: errToShape(err)
+    };
+  }
+}
+
+// src/internal/workflow/telemetry.ts
+var TRACER_NAME = "@theokit/sdk/workflow";
+function startWorkflowRunSpan(info) {
+  const tracer = chunkBUUUWQMB_cjs.getTracer(TRACER_NAME);
+  if (tracer === void 0) return chunkBUUUWQMB_cjs.noopSpan;
+  return tracer.startSpan("workflow.run", {
+    attributes: {
+      "workflow.name": info.workflowName,
+      "workflow.run_id": info.runId
+    }
+  });
+}
+function startWorkflowStepSpan(info) {
+  const tracer = chunkBUUUWQMB_cjs.getTracer(TRACER_NAME);
+  if (tracer === void 0) return chunkBUUUWQMB_cjs.noopSpan;
+  return tracer.startSpan(`workflow.step.${info.stepId}`, {
+    attributes: {
+      "step.id": info.stepId,
+      "step.kind": info.kind,
+      "step.attempt": info.attempt
+    }
+  });
+}
+
+// src/internal/workflow/executor.ts
+async function handleSuspend(err, ctx) {
+  try {
+    await saveSnapshot({
+      runId: ctx.runId,
+      workflowName: ctx.options.name,
+      currentStepId: ctx.step.id,
+      suspendedPayload: err.payload,
+      stepResults: ctx.stepResults,
+      accumulatedInput: ctx.acc,
+      state: ctx.stepCtx.state,
+      // SE29 — capture the shared state at suspend
+      options: ctx.options
+    });
+  } catch (snapErr) {
+    ctx.stepSpan.setAttribute("step.status", "failed");
+    ctx.stepSpan.end();
+    return {
+      kind: "failed",
+      run: assembleRun({
+        runId: ctx.runId,
+        name: ctx.name,
+        status: "failed",
+        stepResults: ctx.stepResults,
+        startedAt: ctx.startedAt,
+        error: errToShape(snapErr)
+      })
+    };
+  }
+  ctx.stepSpan.setAttribute("step.status", "suspended");
+  ctx.stepSpan.end();
+  return {
+    kind: "suspended",
+    run: assembleRun({
+      runId: ctx.runId,
+      name: ctx.name,
+      status: "suspended",
+      stepResults: [
+        ...ctx.stepResults,
+        {
+          stepId: ctx.step.id,
+          kind: ctx.step.kind,
+          status: "suspended",
+          attempts: 1,
+          durationMs: 0,
+          output: void 0
+        }
+      ],
+      startedAt: ctx.startedAt
+    })
+  };
+}
+async function runOneStep(args) {
+  const stepSpan = startWorkflowStepSpan({
+    stepId: args.step.id,
+    kind: args.step.kind,
+    attempt: 1
+  });
+  let result;
+  try {
+    result = await dispatchStep(args.step, args.acc, args.ctx, args.options, args.stepResults);
+  } catch (err) {
+    if (err instanceof WorkflowSuspendedSentinel) {
+      const outcome = await handleSuspend(err, { ...args, stepSpan, stepCtx: args.ctx });
+      return { kind: "terminal", run: outcome.run };
+    }
+    result = {
+      stepId: args.step.id,
+      kind: args.step.kind,
+      status: "failed",
+      attempts: 1,
+      durationMs: 0,
+      error: errToShape(err)
+    };
+  }
+  stepSpan.setAttribute("step.status", result.status);
+  stepSpan.setAttribute("step.attempts", result.attempts);
+  stepSpan.end();
+  return { kind: "ok", result };
+}
+function handleStepOutcome(outcome, step, loop, onStepEvent) {
+  if (outcome.kind === "terminal") {
+    if (outcome.run.status === "suspended") {
+      onStepEvent?.({ type: "workflow_suspended", stepId: step.id });
+    }
+    return { terminal: outcome.run };
+  }
+  loop.stepResults.push(outcome.result);
+  if (outcome.result.status === "failed") {
+    onStepEvent?.({
+      type: "step_failed",
+      stepId: step.id,
+      error: outcome.result.error ?? { name: "WorkflowStepError", message: "step failed" }
+    });
+    return {
+      terminal: assembleRun({
+        runId: loop.runId,
+        name: loop.name,
+        status: "failed",
+        stepResults: loop.stepResults,
+        startedAt: loop.startedAt,
+        error: outcome.result.error
+      })
+    };
+  }
+  onStepEvent?.({ type: "step_completed", stepId: step.id, output: outcome.result.output });
+  return { acc: outcome.result.output };
+}
+async function runStepsLoop(params) {
+  const { options, steps, ctx, runId, startedAt, signal, onStepEvent } = params;
+  const stepResults = [...params.initialStepResults ?? []];
+  const loop = { stepResults, runId, name: options.name, startedAt };
+  let acc = params.input;
+  for (const step of steps) {
+    if (signal.aborted) return abortRun(options.name, runId, startedAt, stepResults, signal);
+    onStepEvent?.({ type: "step_started", stepId: step.id });
+    const outcome = await runOneStep({
+      step,
+      acc,
+      ctx,
+      options,
+      stepResults,
+      runId,
+      name: options.name,
+      startedAt
+    });
+    const handled = handleStepOutcome(outcome, step, loop, onStepEvent);
+    if ("terminal" in handled) return handled.terminal;
+    acc = handled.acc;
+  }
+  const outputIssues = validateWorkflowSchema(options.outputSchema, acc);
+  if (outputIssues !== void 0) {
+    return assembleRun({
+      runId,
+      name: options.name,
+      status: "failed",
+      stepResults,
+      startedAt,
+      error: errToShape(new chunkBWT67BI4_cjs.WorkflowOutputError(options.name, outputIssues))
+    });
+  }
+  onStepEvent?.({ type: "workflow_completed" });
+  return assembleRun({
+    runId,
+    name: options.name,
+    status: "completed",
+    output: acc,
+    stepResults,
+    startedAt
+  });
+}
+async function executeWorkflow(options, steps, input, runOpts) {
+  const runId = runOpts?.runId ?? mintRunId();
+  const workflowId = options.workflowId ?? `wf-anon`;
+  const flight = acquireSingleFlight(workflowId, runId, options.name);
+  const startedAt = Date.now();
+  const signal = combineSignals(runOpts?.signal, flight.signal);
+  const runSpan = startWorkflowRunSpan({ workflowName: options.name, runId });
+  if (signal.aborted) {
+    flight.release();
+    runSpan.setAttribute("workflow.status", "cancelled");
+    runSpan.end();
+    return abortRun(options.name, runId, startedAt, [], signal);
+  }
+  const internal = runOpts;
+  const seededState = internal?.restoredState !== void 0 ? internal.restoredState : options.initialState;
+  const stateController = makeStateController(options, seededState);
+  const ctx = makeStepContext(runId, signal, stateController);
+  try {
+    const inputIssues = validateWorkflowSchema(options.inputSchema, input);
+    if (inputIssues !== void 0) {
+      return assembleRun({
+        runId,
+        name: options.name,
+        status: "failed",
+        stepResults: [],
+        startedAt,
+        error: errToShape(new chunkBWT67BI4_cjs.WorkflowInputError(options.name, inputIssues))
+      });
+    }
+    const stateIssues = seededState !== void 0 ? validateWorkflowSchema(options.stateSchema, seededState) : void 0;
+    if (stateIssues !== void 0) {
+      return assembleRun({
+        runId,
+        name: options.name,
+        status: "failed",
+        stepResults: [],
+        startedAt,
+        error: errToShape(new chunkBWT67BI4_cjs.WorkflowStateError(options.name, stateIssues))
+      });
+    }
+    return await runStepsLoop({
+      options,
+      steps,
+      input,
+      ctx,
+      runId,
+      startedAt,
+      signal,
+      ...internal?.initialStepResults !== void 0 ? { initialStepResults: internal.initialStepResults } : {},
+      ...internal?.onStepEvent !== void 0 ? { onStepEvent: internal.onStepEvent } : {}
+    });
+  } finally {
+    runSpan.end();
+    flight.release();
+  }
+}
+async function dispatchStep(step, input, ctx, options, prevStepResults) {
+  switch (step.kind) {
+    case "fn":
+      return runFnStep(step, input, ctx);
+    case "agent":
+      return runAgentStep(step, input, ctx);
+    case "parallel":
+      return runParallelStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "branch":
+      return runBranchStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "foreach":
+      return runForeachStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "dowhile":
+      return runDowhileStep(step, input, ctx, options, prevStepResults, dispatchStep);
+    case "sleep":
+      return runSleepStep(step, input, ctx);
+    case "suspend":
+      throw new WorkflowSuspendedSentinel(void 0);
+    default: {
+      const _exhaustive = step;
+      throw new Error(`Unknown step kind: ${_exhaustive.kind}`);
+    }
+  }
+}
+async function saveSnapshot(p) {
+  const snapshot = {
+    _schemaVersion: 2,
+    // SE29 — carries `state`
+    runId: p.runId,
+    workflowName: p.workflowName,
+    currentStepId: p.currentStepId,
+    suspendedPayload: p.suspendedPayload,
+    stepResults: p.stepResults,
+    accumulatedInput: p.accumulatedInput,
+    ...p.state !== void 0 ? { state: p.state } : {},
+    suspendedAt: Date.now()
+  };
+  const store = chunkBWT67BI4_cjs.getSnapshotStoreFor(p.options);
+  await store.save(snapshot);
+}
+async function resumeWorkflow(opts) {
+  const wfInternal = opts.workflow;
+  const options = wfInternal.__options;
+  const steps = wfInternal.__steps;
+  if (options === void 0 || steps === void 0) {
+    throw new Error("Workflow.resume requires an instance from Workflow.create().commit()");
+  }
+  const store = chunkBWT67BI4_cjs.getSnapshotStoreFor(options);
+  const snapshot = await store.load(opts.runId);
+  if (snapshot === void 0) {
+    throw new chunkBWT67BI4_cjs.WorkflowSnapshotNotFoundError(opts.runId);
+  }
+  const stepIdx = steps.findIndex((s) => s.id === snapshot.currentStepId);
+  if (stepIdx < 0) {
+    throw new chunkBWT67BI4_cjs.WorkflowResumeStepNotFoundError(snapshot.currentStepId, snapshot.workflowName);
+  }
+  const suspendStep = steps[stepIdx];
+  if (suspendStep !== void 0 && suspendStep.kind === "suspend" && suspendStep.payloadSchema !== void 0) {
+    suspendStep.payloadSchema.parse(opts.payload);
+  }
+  const resumeInput = opts.payload !== void 0 ? opts.payload : snapshot.accumulatedInput;
+  const remainingSteps = steps.slice(stepIdx + 1);
+  await store.delete(opts.runId);
+  return executeWorkflow(options, remainingSteps, resumeInput, {
+    signal: opts.signal,
+    runId: opts.runId,
+    // M3 #62 — restore prior step outputs so the resumed run is not lossy (internal seam).
+    initialStepResults: snapshot.stepResults,
+    // SE29 — restore shared state (v2 snapshot). A v1 snapshot has no `state` →
+    // executeWorkflow falls back to `options.initialState`.
+    ...snapshot.state !== void 0 ? { restoredState: snapshot.state } : {}
+  });
+}
+
+exports.dispatchStep = dispatchStep;
+exports.executeWorkflow = executeWorkflow;
+exports.resumeWorkflow = resumeWorkflow;
+//# sourceMappingURL=executor-Y4MKPIUD.cjs.map
+//# sourceMappingURL=executor-Y4MKPIUD.cjs.map