@particle-academy/fancy-flow 0.45.0 → 0.46.0

package/dist/durable.js

@@ -0,0 +1,552 @@
+import { truthy } from './chunk-BHM5HGXH.js';
+import { pauseForHuman, decodePause } from './chunk-UEOE6B52.js';
+import { runFlow, RunIdentity } from './chunk-L43CWD63.js';
+import './chunk-TITD5W4Y.js';
+import { getNodeKind, resolveKindId, kindIds } from './chunk-PVROYW7C.js';
+
+// 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/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/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/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()}`;
+}
+
+export { BOUNDARY, Coordinator, Frontier, InMemoryClaimStore, NodeRunStatus, NotAwaitingHuman, RetryPolicy, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };
+//# sourceMappingURL=durable.js.map
+//# sourceMappingURL=durable.js.map