@particle-academy/fancy-flow 0.45.0 → 0.46.0

package/dist/durable.cjs

@@ -0,0 +1,927 @@
+'use strict';
+
+// src/durable/state.ts
+var NodeRunStatus = {
+  CLAIMED: "claimed",
+  COMPLETED: "completed",
+  SKIPPED: "skipped",
+  FAILED: "failed",
+  PAUSED: "paused"
+};
+var SETTLED = [
+  NodeRunStatus.COMPLETED,
+  NodeRunStatus.SKIPPED,
+  NodeRunStatus.FAILED
+];
+var InMemoryClaimStore = class {
+  constructor() {
+    this.runs = /* @__PURE__ */ new Map();
+  }
+  claim(runKey, nodeId, owner) {
+    const run = this.run(runKey);
+    const existing = run.get(nodeId);
+    if (!existing) {
+      run.set(nodeId, {
+        status: NodeRunStatus.CLAIMED,
+        ports: [],
+        owner,
+        attempts: 1,
+        firstAttemptAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return true;
+    }
+    const ownClaim = (existing.status === NodeRunStatus.CLAIMED || existing.status === NodeRunStatus.PAUSED) && existing.owner === owner;
+    if (ownClaim) {
+      existing.attempts += 1;
+      existing.status = NodeRunStatus.CLAIMED;
+      return true;
+    }
+    return false;
+  }
+  state(runKey) {
+    const out = {};
+    for (const [nodeId, entry] of this.run(runKey)) out[nodeId] = { ...entry, ports: [...entry.ports] };
+    return out;
+  }
+  complete(runKey, nodeId, output, ports) {
+    const entry = this.entry(runKey, nodeId);
+    entry.status = NodeRunStatus.COMPLETED;
+    entry.output = output;
+    entry.ports = [...ports];
+    entry.error = null;
+  }
+  skip(runKey, nodeId) {
+    const entry = this.entry(runKey, nodeId);
+    entry.status = NodeRunStatus.SKIPPED;
+    entry.ports = [];
+  }
+  fail(runKey, nodeId, error) {
+    const entry = this.entry(runKey, nodeId);
+    entry.status = NodeRunStatus.FAILED;
+    entry.error = error;
+    entry.ports = [];
+  }
+  pause(runKey, nodeId, reason) {
+    const entry = this.entry(runKey, nodeId);
+    entry.status = NodeRunStatus.PAUSED;
+    entry.error = reason;
+    entry.ports = [];
+  }
+  /**
+   * Drop a paused node's claim so a recorded answer can re-run it.
+   *
+   * Not part of the interface: resuming a human gate is the host's decision and
+   * its storage's business. Provided here because the in-memory store is also
+   * what the tests resume through.
+   */
+  release(runKey, nodeId) {
+    this.run(runKey).delete(nodeId);
+  }
+  run(runKey) {
+    let run = this.runs.get(runKey);
+    if (!run) {
+      run = /* @__PURE__ */ new Map();
+      this.runs.set(runKey, run);
+    }
+    return run;
+  }
+  /** The row for one node, created as CLAIMED if a driver never claimed it. */
+  entry(runKey, nodeId) {
+    const run = this.run(runKey);
+    let entry = run.get(nodeId);
+    if (!entry) {
+      entry = {
+        status: NodeRunStatus.CLAIMED,
+        ports: [],
+        attempts: 1,
+        firstAttemptAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      run.set(nodeId, entry);
+    }
+    return entry;
+  }
+};
+function isSettled(status) {
+  return status !== void 0 && SETTLED.includes(status);
+}
+
+// src/registry/registry.ts
+var kinds = /* @__PURE__ */ new Map();
+var aliases = /* @__PURE__ */ new Map();
+var overrides = /* @__PURE__ */ new Map();
+function resolveKindId(id) {
+  if (kinds.has(id)) return id;
+  const canonical = aliases.get(id);
+  return canonical && kinds.has(canonical) ? canonical : null;
+}
+function withOverride(kind) {
+  if (!kind) return null;
+  const patch = overrides.get(kind.name);
+  return patch ? { ...kind, ...patch } : kind;
+}
+function getNodeKind(name) {
+  const canonical = resolveKindId(name);
+  return canonical ? withOverride(kinds.get(canonical)) : null;
+}
+function kindIds(kind) {
+  return [kind.name, ...kind.aliases ?? []];
+}
+
+// src/durable/frontier.ts
+function isNote(type) {
+  if (!type) return false;
+  if (type === "note") return true;
+  const kind = getNodeKind(type);
+  return kind ? kindIds(kind).includes("note") || kind.category === "annotation" : false;
+}
+var Frontier = {
+  compute(graph, state) {
+    const incoming = /* @__PURE__ */ new Map();
+    for (const edge of graph.edges) {
+      const list = incoming.get(edge.target) ?? [];
+      list.push(edge);
+      incoming.set(edge.target, list);
+    }
+    const settled = /* @__PURE__ */ new Map();
+    const held = /* @__PURE__ */ new Set();
+    for (const [nodeId, entry] of Object.entries(state)) {
+      if (entry.status === NodeRunStatus.COMPLETED) settled.set(nodeId, entry.ports);
+      else if (isSettled(entry.status)) settled.set(nodeId, []);
+      else held.add(nodeId);
+    }
+    const ready = [];
+    const skipped = [];
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const node of graph.nodes) {
+        const nodeId = node.id;
+        if (settled.has(nodeId) || held.has(nodeId) || ready.includes(nodeId)) continue;
+        const edges = incoming.get(nodeId) ?? [];
+        let blocked = false;
+        let active = false;
+        for (const edge of edges) {
+          if (!settled.has(edge.source)) {
+            blocked = true;
+            break;
+          }
+          if (settled.get(edge.source).includes(edge.sourceHandle ?? "out")) active = true;
+        }
+        if (blocked) continue;
+        if (edges.length > 0 && !active) {
+          settled.set(nodeId, []);
+          skipped.push(nodeId);
+          changed = true;
+          continue;
+        }
+        if (isNote(node.type) || getNodeKind(node.type ?? "")?.category === "layout") {
+          settled.set(nodeId, []);
+          skipped.push(nodeId);
+          changed = true;
+          continue;
+        }
+        ready.push(nodeId);
+      }
+    }
+    return { ready, skipped };
+  },
+  /** Has every node settled? The run is finished when it has. */
+  isComplete(graph, state) {
+    return graph.nodes.every((node) => isSettled(state[node.id]?.status));
+  },
+  /**
+   * Is any node still held by a worker, or parked for a person?
+   *
+   * An empty frontier means something different depending on this: with work in
+   * flight the run is simply waiting, and whichever job finishes will advance
+   * it. With nothing in flight and nodes still unsettled, the graph cannot
+   * progress at all — which is a stuck run, and must be reported rather than
+   * waited on.
+   */
+  hasWorkInFlight(state) {
+    return Object.values(state).some(
+      (entry) => entry.status === NodeRunStatus.CLAIMED || entry.status === NodeRunStatus.PAUSED
+    );
+  },
+  /** Persist the skip cascade so the next pass does not recompute it. */
+  async settleSkips(store, runKey, skipped) {
+    for (const nodeId of skipped) await store.skip(runKey, nodeId);
+  }
+};
+
+// src/registry/ports.ts
+function resolvePortSpec(spec, config) {
+  if (spec === void 0) return void 0;
+  if (typeof spec !== "function") return spec;
+  try {
+    const resolved = spec(config);
+    return Array.isArray(resolved) ? resolved : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function nodeConfig(node) {
+  return node.data?.config ?? {};
+}
+function resolveNodePorts(node, kind) {
+  const config = nodeConfig(node);
+  const data = node.data;
+  return {
+    inputs: data?.inputs ?? resolvePortSpec(kind?.inputs, config),
+    outputs: data?.outputs ?? resolvePortSpec(kind?.outputs, config)
+  };
+}
+
+// src/runtime/run-identity.ts
+function escapeSegment(value) {
+  return value.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/#/g, "%23");
+}
+function renderSegment(value, occurrence) {
+  const escaped = escapeSegment(value);
+  return occurrence === void 0 || occurrence === null ? escaped : `${escaped}#${occurrence}`;
+}
+function instant(value) {
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new Error(
+      `RunIdentity: firstAttemptAt is not a parseable timestamp: ${JSON.stringify(value)}`
+    );
+  }
+  return ms;
+}
+var RunIdentity = class _RunIdentity {
+  constructor(runKey, path = [], attempt = 1, firstAttemptAt = (/* @__PURE__ */ new Date()).toISOString()) {
+    if (!runKey || runKey.trim() === "") {
+      throw new Error("RunIdentity: runKey must be a non-empty string.");
+    }
+    this.runKey = runKey;
+    this.path = Object.freeze([...path]);
+    this.attempt = Math.max(1, Math.trunc(attempt));
+    this.firstAttemptAt = firstAttemptAt;
+    Object.freeze(this);
+  }
+  /**
+   * The identity of one execution of one node — stable across retries of that
+   * execution, distinct from every other execution of the same node.
+   *
+   * Pass `occurrence` when an executor runs the same node more than once at the
+   * same level (a loop body, one item of a fan-out it drives itself).
+   */
+  stepKey(nodeId, occurrence) {
+    return `${this.runKey}:${[...this.path, renderSegment(nodeId, occurrence)].join("/")}`;
+  }
+  /**
+   * A child identity for work nested inside this step.
+   *
+   * `subflow` pushes the invoking node's id, so a node inside the child graph
+   * cannot collide with a same-named node in the parent. Attempt and
+   * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+   * this step's attempt, and shares its clock.
+   */
+  descend(segment, occurrence) {
+    return new _RunIdentity(
+      this.runKey,
+      [...this.path, renderSegment(segment, occurrence)],
+      this.attempt,
+      this.firstAttemptAt
+    );
+  }
+  /** A copy on a different attempt, first-attempt clock preserved. */
+  withAttempt(attempt, firstAttemptAt) {
+    return new _RunIdentity(
+      this.runKey,
+      this.path,
+      attempt,
+      firstAttemptAt ?? this.firstAttemptAt
+    );
+  }
+  /**
+   * May this attempt reuse the step key and still be deduplicated?
+   *
+   * Providers forget idempotency keys — Stripe after 24 hours. Past that
+   * window, resending the key creates a second charge and sending a fresh one
+   * creates a second charge, so **the caller must refuse rather than pick
+   * between them**: a loud stuck run beats a silent double write.
+   *
+   * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+   * earlier attempt, so there is nothing for the provider to have forgotten.
+   * That is what lets a run park on a human gate for a week and then write.
+   *
+   * `windowSeconds: null` means the provider does not expire keys. `0` means
+   * it does not dedupe at all, so no retry may reuse a key — it is a real
+   * window, not an absent one, and the two must not be conflated: reading `0`
+   * as `null` turns "this provider does not dedupe" into "this provider
+   * dedupes forever", which is the more dangerous of the two by a distance.
+   */
+  isReplaySafe(windowSeconds, now = /* @__PURE__ */ new Date()) {
+    if (this.attempt <= 1) return true;
+    if (windowSeconds === null || windowSeconds === void 0) return true;
+    if (windowSeconds <= 0) return false;
+    const nowMs = typeof now === "string" ? instant(now) : now.getTime();
+    const elapsedSeconds = Math.max(0, (nowMs - instant(this.firstAttemptAt)) / 1e3);
+    return elapsedSeconds <= windowSeconds;
+  }
+  toJSON() {
+    return {
+      runKey: this.runKey,
+      path: [...this.path],
+      attempt: this.attempt,
+      firstAttemptAt: this.firstAttemptAt
+    };
+  }
+  /** Rebuild from a queue payload. */
+  static from(value) {
+    if (value instanceof _RunIdentity) return value;
+    if (typeof value === "string") return new _RunIdentity(value);
+    return new _RunIdentity(
+      value.runKey,
+      value.path ?? [],
+      value.attempt ?? 1,
+      value.firstAttemptAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    );
+  }
+};
+
+// src/runtime/run-flow.ts
+async function runFlow(graph, executors, onEvent = () => {
+}, options = {}) {
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {} } = options;
+  const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
+  const outputs = {};
+  const portValues = /* @__PURE__ */ new Map();
+  const completed = /* @__PURE__ */ new Set();
+  const errors = [];
+  const order = topoSort(graph);
+  if (order === null) {
+    const msg = "Cycle detected in flow graph \u2014 aborting.";
+    onEvent({ type: "run-error", error: msg });
+    return { ok: false, outputs, error: msg };
+  }
+  const incomingByNode = indexIncoming(graph.edges);
+  const timer = timeoutMs ? setTimeout(() => errors.push(`Run timed out after ${timeoutMs}ms`), timeoutMs) : null;
+  onEvent({ type: "run-start" });
+  try {
+    for (const node of order) {
+      if (signal?.aborted) throw new Error("aborted");
+      if (errors.length) break;
+      if (Object.prototype.hasOwnProperty.call(resumeOutputs, node.id)) {
+        const stored = resumeOutputs[node.id];
+        outputs[node.id] = stored;
+        const activated = activatedPorts(node, stored);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done", text: "resumed" });
+        continue;
+      }
+      const incoming = incomingByNode.get(node.id) ?? [];
+      if (incoming.length > 0) {
+        const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
+        if (!anyActive) {
+          onEvent({ type: "node-status", nodeId: node.id, status: "idle", text: "skipped" });
+          continue;
+        }
+      }
+      const visualKind = getNodeKind(node.type ?? "");
+      const isLayout = visualKind?.category === "layout";
+      const isAnnotation = node.type === "note" || visualKind?.category === "annotation";
+      if (isLayout || isAnnotation) {
+        onEvent({
+          type: "node-status",
+          nodeId: node.id,
+          status: "idle",
+          text: isLayout ? "lane" : "annotation"
+        });
+        continue;
+      }
+      onEvent({ type: "node-status", nodeId: node.id, status: "running" });
+      const inputs = collectInputs(node, incoming, portValues, initialInputs);
+      const exec = pickExecutor(executors, node);
+      if (!exec) {
+        const msg = `No executor registered for kind=${node.type}`;
+        errors.push(msg);
+        onEvent({ type: "node-status", nodeId: node.id, status: "error", text: msg });
+        onEvent({ type: "log", nodeId: node.id, level: "error", message: msg });
+        break;
+      }
+      try {
+        const result = await Promise.resolve(
+          exec({
+            node,
+            inputs,
+            abort: (reason) => {
+              throw new Error(reason ?? "aborted");
+            },
+            emit: onEvent,
+            depth,
+            run
+          })
+        );
+        outputs[node.id] = result;
+        const activated = activatedPorts(node, result);
+        for (const portId of activated.ports) {
+          portValues.set(`${node.id}:${portId}`, activated.value);
+          onEvent({ type: "node-output", nodeId: node.id, portId, value: activated.value });
+        }
+        completed.add(node.id);
+        onEvent({ type: "node-status", nodeId: node.id, status: "done" });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        errors.push(msg);
+        onEvent({ type: "node-status", nodeId: node.id, status: "error", text: msg });
+        onEvent({ type: "log", nodeId: node.id, level: "error", message: msg });
+        break;
+      }
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  const ok = errors.length === 0;
+  onEvent({ type: "run-end", ok });
+  return ok ? { ok, outputs } : { ok, outputs, error: errors[0] };
+}
+function indexIncoming(edges) {
+  const map = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const list = map.get(e.target) ?? [];
+    list.push(e);
+    map.set(e.target, list);
+  }
+  return map;
+}
+function topoSort(graph) {
+  const inDegree = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) inDegree.set(n.id, 0);
+  for (const e of graph.edges) inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
+  const queue = [];
+  for (const [id, d] of inDegree) if (d === 0) queue.push(id);
+  const ordered = [];
+  while (queue.length) {
+    const id = queue.shift();
+    ordered.push(id);
+    for (const e of graph.edges) {
+      if (e.source !== id) continue;
+      const next = (inDegree.get(e.target) ?? 0) - 1;
+      inDegree.set(e.target, next);
+      if (next === 0) queue.push(e.target);
+    }
+  }
+  if (ordered.length !== graph.nodes.length) return null;
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  return ordered.map((id) => byId.get(id)).filter(Boolean);
+}
+function collectInputs(node, incoming, portValues, initial) {
+  const inputs = { ...initial[node.id] ?? {} };
+  for (const e of incoming) {
+    const portId = e.targetHandle ?? "in";
+    const key = `${e.source}:${e.sourceHandle ?? "out"}`;
+    if (!portValues.has(key)) continue;
+    inputs[portId] = portValues.get(key);
+  }
+  return inputs;
+}
+function pickExecutor(executors, node) {
+  if (executors[node.id]) return executors[node.id];
+  if (node.type && executors[node.type]) return executors[node.type];
+  const kind = node.type ? getNodeKind(node.type) : null;
+  if (kind) {
+    for (const id of kindIds(kind)) {
+      if (executors[id]) return executors[id];
+    }
+  }
+  return executors["*"];
+}
+function activatedPorts(node, result) {
+  if (result && typeof result === "object") {
+    const r = result;
+    if (typeof r.__port === "string") {
+      return { ports: [r.__port], value: r.value };
+    }
+    if (typeof r.branch === "string") {
+      return { ports: [r.branch], value: r.value ?? r };
+    }
+  }
+  const kind = getNodeKind(node.data?.kind ?? node.type ?? "") ?? void 0;
+  const declared = resolveNodePorts(node, kind).outputs?.map((p) => p.id);
+  return { ports: declared?.length ? declared : ["out"], value: result };
+}
+
+// src/durable/replay.ts
+var BOUNDARY = "fancy-flow:node-boundary";
+async function replayUpTo(graph, nodeId, executors, options = {}) {
+  const fenced = { ...executors };
+  for (const node of graph.nodes) {
+    if (node.id !== nodeId) {
+      fenced[node.id] = (ctx) => ctx.abort(BOUNDARY);
+    }
+  }
+  const ports = {};
+  const collect = (event) => {
+    var _a;
+    if (event.type === "node-output") {
+      (ports[_a = event.nodeId] ?? (ports[_a] = [])).push(event.portId);
+    }
+    options.onEvent?.(event);
+  };
+  const result = await runFlow(graph, fenced, collect, {
+    initialInputs: options.initialInputs ?? {},
+    resumeOutputs: options.resumeOutputs ?? {},
+    depth: options.depth ?? 0,
+    run: options.run
+  });
+  return {
+    result,
+    ports,
+    outputOf: (id) => result.outputs[id],
+    portsOf: (id) => ports[id] ?? []
+  };
+}
+function isBoundary(error) {
+  return error === BOUNDARY;
+}
+
+// src/durable/retry.ts
+var UNSAFE_TO_REPLAY = "unsafe-to-replay";
+var RetryPolicy = class _RetryPolicy {
+  constructor(options = {}) {
+    this.tries = options.tries ?? 1;
+    this.backoffSeconds = options.backoffSeconds ?? 0;
+    this.perKind = options.perKind ?? {};
+  }
+  triesFor(node) {
+    if (_RetryPolicy.isUnsafeToReplay(node)) return 1;
+    for (const id of idsFor(node)) {
+      if (id in this.perKind) return Math.max(1, Math.trunc(this.perKind[id]));
+    }
+    return Math.max(1, Math.trunc(this.tries));
+  }
+  backoffFor(node) {
+    if (_RetryPolicy.isUnsafeToReplay(node)) return 0;
+    return Math.max(0, this.backoffSeconds);
+  }
+  static isUnsafeToReplay(node) {
+    if (!node.type) return false;
+    return getNodeKind(node.type)?.sideEffects === UNSAFE_TO_REPLAY;
+  }
+};
+function idsFor(node) {
+  if (!node.type) return [];
+  const kind = getNodeKind(node.type);
+  const canonical = resolveKindId(node.type);
+  const ordered = [node.type, ...canonical ? [canonical] : [], ...kind ? kindIds(kind) : []];
+  return [...new Set(ordered)];
+}
+
+// src/registry/pause.ts
+var PAUSE_PREFIX = "fancy-flow:pause:";
+var LEGACY_PAUSE_PREFIXES = [
+  ["awaiting-approval:", "approval"],
+  ["awaiting-input:", "input"]
+];
+function encodePause(signal) {
+  const { nodeId, awaiting, detail } = signal;
+  return PAUSE_PREFIX + JSON.stringify(detail === void 0 ? { nodeId, awaiting } : { nodeId, awaiting, detail });
+}
+function decodePause(reason) {
+  if (typeof reason !== "string") return null;
+  if (reason.startsWith(PAUSE_PREFIX)) {
+    const body = reason.slice(PAUSE_PREFIX.length);
+    try {
+      const parsed = JSON.parse(body);
+      if (typeof parsed?.nodeId !== "string" || typeof parsed?.awaiting !== "string") return null;
+      return "detail" in parsed ? { nodeId: parsed.nodeId, awaiting: parsed.awaiting, detail: parsed.detail } : { nodeId: parsed.nodeId, awaiting: parsed.awaiting };
+    } catch {
+      return null;
+    }
+  }
+  for (const [prefix, awaiting] of LEGACY_PAUSE_PREFIXES) {
+    if (reason.startsWith(prefix)) {
+      return { nodeId: reason.slice(prefix.length), awaiting };
+    }
+  }
+  return null;
+}
+function pauseForHuman(ctx, awaiting, detail) {
+  return ctx.abort(encodePause({ nodeId: ctx.node.id, awaiting, detail }));
+}
+
+// src/expressions/expr.ts
+var FALSY_STRINGS = /* @__PURE__ */ new Set(["", "0", "false", "no", "off", "null"]);
+function truthy(value) {
+  if (typeof value === "boolean") return value;
+  if (value === null || value === void 0) return false;
+  if (typeof value === "string") return !FALSY_STRINGS.has(value.trim().toLowerCase());
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "number") return value !== 0;
+  return Boolean(value);
+}
+
+// src/durable/human.ts
+var NotAwaitingHuman = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotAwaitingHuman";
+  }
+};
+var Submissions = class {
+  constructor() {
+    this.answers = /* @__PURE__ */ new Map();
+    /** The node the run is currently parked on, if any. */
+    this.awaiting = null;
+  }
+  /**
+   * Record an answer for the node the run is parked on.
+   *
+   * Throws when the run is not waiting on that node. A queued answer for a node
+   * that never paused is a write nobody reads — and it looks, from the outside,
+   * exactly like a submission that worked.
+   */
+  record(nodeId, value) {
+    if (this.awaiting !== null && this.awaiting !== nodeId) {
+      throw new NotAwaitingHuman(
+        `This run is waiting on "${this.awaiting}", not "${nodeId}". Recording an answer for a node the run is not parked on would be stored and never read.`
+      );
+    }
+    if (this.awaiting === null) {
+      throw new NotAwaitingHuman(
+        `This run is not waiting for anyone, so an answer for "${nodeId}" has nothing to resume.`
+      );
+    }
+    this.answers.set(nodeId, value);
+    this.awaiting = null;
+  }
+  answered(nodeId) {
+    return this.answers.has(nodeId);
+  }
+  answer(nodeId) {
+    return this.answers.get(nodeId);
+  }
+  park(nodeId) {
+    this.awaiting = nodeId;
+  }
+};
+function option(ctx, key, fallback) {
+  const config = ctx.node.data?.config ?? {};
+  return config[key] ?? fallback;
+}
+function durableUserInput(submissions) {
+  return (ctx) => {
+    if (submissions.answered(ctx.node.id)) return submissions.answer(ctx.node.id);
+    if (option(ctx, "autoAnswerFromInput") === true) {
+      const values = ctx.inputs.values;
+      if (values !== void 0) return values;
+    }
+    submissions.park(ctx.node.id);
+    return pauseForHuman(ctx, "input", {
+      title: option(ctx, "title", "Need your input"),
+      fields: option(ctx, "fields", [])
+    });
+  };
+}
+function durableApproval(submissions) {
+  return (ctx) => {
+    const passthrough = ctx.inputs.in ?? ctx.inputs;
+    if (submissions.answered(ctx.node.id)) {
+      return { branch: truthy(submissions.answer(ctx.node.id)) ? "approved" : "denied", value: passthrough };
+    }
+    if (option(ctx, "autoAnswerFromInput") === true) {
+      const decision = ctx.inputs.approved;
+      if (decision !== void 0) {
+        return { branch: truthy(decision) ? "approved" : "denied", value: passthrough };
+      }
+    }
+    submissions.park(ctx.node.id);
+    return pauseForHuman(ctx, "approval", {
+      title: option(ctx, "title", "Approve action"),
+      description: option(ctx, "description")
+    });
+  };
+}
+
+// src/durable/coordinator.ts
+var Coordinator = class {
+  constructor(options) {
+    this.graph = options.graph;
+    this.executors = options.executors;
+    this.run = RunIdentity.from(options.run);
+    this.store = options.store ?? new InMemoryClaimStore();
+    this.initialInputs = options.initialInputs ?? {};
+    this.retry = options.retry ?? new RetryPolicy();
+    this.onEvent = options.onEvent;
+  }
+  get runKey() {
+    return this.run.runKey;
+  }
+  // -- the two operations ----------------------------------------------
+  /**
+   * Which nodes may be dispatched right now.
+   *
+   * Also settles the skip cascade, because a skip is a decision the frontier
+   * just made and a second caller must not make it again.
+   */
+  async advance() {
+    const frontier = Frontier.compute(this.graph, await this.store.state(this.runKey));
+    await Frontier.settleSkips(this.store, this.runKey, frontier.skipped);
+    return frontier.ready;
+  }
+  /**
+   * Claim, execute and checkpoint one node.
+   *
+   * The claim is taken FIRST. Two workers racing for the same node produce one
+   * execution and one no-op, and the loser learns that from the store rather
+   * than from a duplicate side effect.
+   *
+   * `owner` is the token that lets a job's own retry re-enter its claim instead
+   * of deadlocking against the row it wrote itself — pass the SAME token across
+   * a job's attempts.
+   */
+  async runNode(nodeId, owner) {
+    const token = owner ?? cryptoRandom();
+    if (!await this.store.claim(this.runKey, nodeId, token)) {
+      return { nodeId, status: "not-claimed", claimed: false, attempt: 0 };
+    }
+    const row = (await this.store.state(this.runKey))[nodeId];
+    const identity = this.identityFor(row);
+    const replay = await replayUpTo(this.graph, nodeId, this.executors, {
+      resumeOutputs: await this.completedOutputs(),
+      initialInputs: this.initialInputs,
+      onEvent: this.forward(nodeId),
+      run: identity
+    });
+    const result = replay.result;
+    const attempt = identity.attempt;
+    if (Object.prototype.hasOwnProperty.call(result.outputs, nodeId)) {
+      const output = result.outputs[nodeId];
+      const ports = replay.portsOf(nodeId);
+      await this.store.complete(this.runKey, nodeId, output, ports);
+      return { nodeId, status: "completed", output, ports, claimed: true, attempt };
+    }
+    const pause = decodePause(result.error);
+    if (pause && pause.nodeId === nodeId) {
+      await this.store.pause(this.runKey, nodeId, result.error ?? "");
+      return { nodeId, status: "paused", pause, claimed: true, attempt };
+    }
+    if (isBoundary(result.error)) {
+      await this.store.skip(this.runKey, nodeId);
+      return {
+        nodeId,
+        status: "skipped",
+        error: "replay stopped before reaching this node",
+        claimed: true,
+        attempt
+      };
+    }
+    const error = result.error ?? `node ${nodeId} produced no output and no error`;
+    const node = this.graph.nodes.find((n) => n.id === nodeId);
+    const tries = node ? this.retry.triesFor(node) : 1;
+    if (attempt < tries) {
+      return { nodeId, status: "failed", error, claimed: true, attempt, retryable: true };
+    }
+    await this.store.fail(this.runKey, nodeId, error);
+    return { nodeId, status: "failed", error, claimed: true, attempt, retryable: false };
+  }
+  // -- an in-process driver over the two ------------------------------
+  /**
+   * Drive the graph here, in this process, one node at a time.
+   *
+   * Every checkpoint is written exactly as a queued run writes it, so a crash
+   * mid-loop resumes from the same place a crashed worker would.
+   *
+   * Retries honour {@link RetryPolicy}: a node declaring `unsafe-to-replay`
+   * gets one attempt whatever the policy says, and the retry re-enters the same
+   * claim with the same owner token — so the step key it derives is unchanged,
+   * which is what makes the retry idempotent rather than duplicative.
+   */
+  async runToCompletion(maxPasses = 1e4) {
+    for (let pass = 0; pass < maxPasses; pass++) {
+      const ready = await this.advance();
+      if (ready.length === 0) break;
+      for (const nodeId of ready) {
+        const outcome = await this.runNodeWithRetries(nodeId);
+        if (outcome.status === "paused") {
+          return {
+            ok: false,
+            outputs: await this.outputs(),
+            pause: outcome.pause,
+            paused: true
+          };
+        }
+        if (outcome.status === "failed") {
+          return { ok: false, outputs: await this.outputs(), error: outcome.error, paused: false };
+        }
+      }
+    }
+    const state = await this.store.state(this.runKey);
+    if (!Frontier.isComplete(this.graph, state)) {
+      if (Frontier.hasWorkInFlight(state)) {
+        return {
+          ok: false,
+          outputs: await this.outputs(),
+          error: "the run is waiting on work held elsewhere",
+          paused: false
+        };
+      }
+      const unsettled = this.graph.nodes.filter((n) => !["completed", "skipped", "failed"].includes(state[n.id]?.status ?? "")).map((n) => n.id);
+      return {
+        ok: false,
+        outputs: await this.outputs(),
+        error: `the run cannot progress; unsettled nodes: ${unsettled.join(", ")}`,
+        paused: false
+      };
+    }
+    const failed = Object.values(state).filter((e) => e.status === NodeRunStatus.FAILED).map((e) => e.error ?? "node failed");
+    return {
+      ok: failed.length === 0,
+      outputs: await this.outputs(),
+      error: failed[0],
+      paused: false
+    };
+  }
+  /**
+   * Checkpointed outputs, in the graph's own node order.
+   *
+   * Ordered by the graph rather than by completion so two runs of the same
+   * workflow produce comparable output maps even when nodes finished in a
+   * different order.
+   */
+  async outputs() {
+    const state = await this.store.state(this.runKey);
+    const out = {};
+    for (const node of this.graph.nodes) {
+      if (state[node.id]?.status === NodeRunStatus.COMPLETED) out[node.id] = state[node.id].output;
+    }
+    return out;
+  }
+  /** The checkpointed run, in the shape a single-process run returns. */
+  async asRunResult() {
+    const outcome = await this.runToCompletion();
+    return outcome.error === void 0 ? { ok: outcome.ok, outputs: outcome.outputs } : { ok: outcome.ok, outputs: outcome.outputs, error: outcome.error };
+  }
+  // -- internals -------------------------------------------------------
+  async runNodeWithRetries(nodeId) {
+    const owner = cryptoRandom();
+    let outcome = await this.runNode(nodeId, owner);
+    while (outcome.retryable) {
+      outcome = await this.runNode(nodeId, owner);
+    }
+    return outcome;
+  }
+  /**
+   * The identity handed to the node about to execute.
+   *
+   * `attempt` and `firstAttemptAt` come off the CLAIM ROW, so they describe
+   * this step rather than the run — which is what makes the retry window check
+   * exact instead of conservative.
+   */
+  identityFor(row) {
+    if (!row) return this.run;
+    return this.run.withAttempt(row.attempts, row.firstAttemptAt);
+  }
+  async completedOutputs() {
+    const state = await this.store.state(this.runKey);
+    const out = {};
+    for (const [nodeId, entry] of Object.entries(state)) {
+      if (entry.status === NodeRunStatus.COMPLETED) out[nodeId] = entry.output;
+    }
+    return out;
+  }
+  /**
+   * Forward only the events the target node produced.
+   *
+   * A replay re-emits the whole completed prefix. Passing that through would
+   * show a consumer every node running again on every job — the run feed would
+   * report a 20-node workflow as 200 status changes.
+   */
+  forward(nodeId) {
+    const sink = this.onEvent;
+    if (!sink) return void 0;
+    return (event) => {
+      const id = "nodeId" in event ? event.nodeId : void 0;
+      if (id === void 0 || id === nodeId) sink(event);
+    };
+  }
+};
+function cryptoRandom() {
+  const g = globalThis;
+  return g.crypto?.randomUUID?.() ?? `own_${Math.random().toString(36).slice(2)}${Date.now()}`;
+}
+
+exports.BOUNDARY = BOUNDARY;
+exports.Coordinator = Coordinator;
+exports.Frontier = Frontier;
+exports.InMemoryClaimStore = InMemoryClaimStore;
+exports.NodeRunStatus = NodeRunStatus;
+exports.NotAwaitingHuman = NotAwaitingHuman;
+exports.RetryPolicy = RetryPolicy;
+exports.SETTLED = SETTLED;
+exports.Submissions = Submissions;
+exports.UNSAFE_TO_REPLAY = UNSAFE_TO_REPLAY;
+exports.durableApproval = durableApproval;
+exports.durableUserInput = durableUserInput;
+exports.isBoundary = isBoundary;
+exports.isSettled = isSettled;
+exports.replayUpTo = replayUpTo;
+//# sourceMappingURL=durable.cjs.map
+//# sourceMappingURL=durable.cjs.map