@particle-academy/fancy-flow 0.71.0 → 0.72.1

package/dist/durable.cjs

@@ -52,8 +52,10 @@ var InMemoryClaimStore = class {
   }
   skip(runKey, nodeId) {
     const entry = this.entry(runKey, nodeId);
+    if (entry.status === NodeRunStatus.SKIPPED) return false;
     entry.status = NodeRunStatus.SKIPPED;
     entry.ports = [];
+    return true;
   }
   fail(runKey, nodeId, error) {
     const entry = this.entry(runKey, nodeId);
@@ -242,24 +244,6 @@ function resolveNodePorts(node, kind) {
   };
 }
 
-// src/expressions/variables.ts
-function outputFieldsFor(node) {
-  const kindName = node.data?.kind ?? node.type;
-  if (!kindName) return [];
-  const kind = getNodeKind(kindName);
-  const shape = kind?.outputShape;
-  if (!shape) return [];
-  if (typeof shape === "function") {
-    try {
-      const config = node.data?.config ?? {};
-      return shape(config) ?? [];
-    } catch {
-      return [];
-    }
-  }
-  return shape;
-}
-
 // src/runtime/run-identity.ts
 function escapeSegment(value) {
   return value.replace(/%/g, "%25").replace(/\//g, "%2F").replace(/#/g, "%23");
@@ -603,6 +587,81 @@ function specForLane(lane) {
   };
 }
 
+// src/expressions/variables.ts
+function outputFieldsFor(node) {
+  const kindName = node.data?.kind ?? node.type;
+  if (!kindName) return [];
+  const kind = getNodeKind(kindName);
+  const shape = kind?.outputShape;
+  if (!shape) return [];
+  if (typeof shape === "function") {
+    try {
+      const config = node.data?.config ?? {};
+      return shape(config) ?? [];
+    } catch {
+      return [];
+    }
+  }
+  return shape;
+}
+
+// src/runtime/undelivered-edges.ts
+function undeliveredEdgeWarnings(target, incoming, portValues, completed, nodesById) {
+  const events = [];
+  for (const e of incoming) {
+    const handle = e.sourceHandle ?? "out";
+    if (portValues.has(`${e.source}:${handle}`) || !completed.has(e.source)) continue;
+    if (possiblePortIds(nodesById.get(e.source)).includes(handle)) continue;
+    events.push({
+      type: "log",
+      nodeId: target.id,
+      level: "warn",
+      message: undeliveredEdgeMessage(e, target, portValues, nodesById),
+      detail: { edge: e.id, source: e.source, sourceHandle: handle }
+    });
+  }
+  return events;
+}
+function possiblePortIds(node) {
+  if (!node) return ["out"];
+  const own = node.data?.outputs;
+  if (Array.isArray(own)) return own.map((p) => p.id);
+  const kind = getNodeKind(node.data?.kind ?? node.type ?? "");
+  if (!kind) return ["out"];
+  const config = nodeConfig(node);
+  const representative = typeof kind.outputs === "function" && !configDeclaresPorts(kind.name, config);
+  const ids = (resolvePortSpec(kind.outputs, representative ? defaultConfigFor(kind) : config) ?? []).map((p) => p.id);
+  return ids.length > 0 ? ids : ["out"];
+}
+function configDeclaresPorts(kindName, config) {
+  const bare = kindName.startsWith("@") ? kindName.slice(kindName.lastIndexOf("/") + 1) : kindName;
+  if (bare === "switch_case") {
+    const cases = config.cases;
+    return !!cases && typeof cases === "object" && Object.values(cases).some((port) => typeof port === "string" && port !== "");
+  }
+  if (bare === "llm_router") {
+    const routes = config.routes;
+    return Array.isArray(routes) && routes.some((route) => route?.port != null && route.port !== "");
+  }
+  return true;
+}
+function undeliveredEdgeMessage(edge, target, portValues, nodesById) {
+  const handle = edge.sourceHandle ?? "out";
+  const prefix = `${edge.source}:`;
+  const available = [];
+  for (const key of portValues.keys()) {
+    if (key.startsWith(prefix)) available.push(key.slice(prefix.length));
+  }
+  let message = `Edge ${edge.id} reads port "${handle}" from node ${edge.source}, which never publishes it \u2014 nothing would reach ${target.id} at run time.`;
+  if (available.length > 0) message += ` Available: ${available.join(", ")}.`;
+  const source = nodesById.get(edge.source);
+  if (source && outputFieldsFor(source).some((field) => field?.path === handle)) {
+    message += ` Note: "${handle}" is a FIELD this node emits, not a port \u2014 read it downstream as {{ in.${handle} }} rather than naming it as a source handle.`;
+  }
+  if (edge.sourceHandle != null) message += " Leave sourceHandle off to read the node's output.";
+  return message;
+}
+
 // src/runtime/workflow-props.ts
 function typeOf(value) {
   if (value === null) return "null";
@@ -661,7 +720,7 @@ function resolveWorkflowProps(declared, passed) {
 // src/runtime/run-flow.ts
 async function runFlow(graph, executors, onEvent = () => {
 }, options = {}) {
-  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes } = options;
+  const { signal, initialInputs = {}, timeoutMs, depth = 0, resumeOutputs = {}, entryNodes, nodeExecutors } = options;
   const run = options.run === void 0 ? void 0 : RunIdentity.from(options.run);
   const outputs = {};
   const portValues = /* @__PURE__ */ new Map();
@@ -724,17 +783,8 @@ async function runFlow(graph, executors, onEvent = () => {
         onEvent({ type: "node-status", nodeId: node.id, status: "idle", text: "skipped" });
         continue;
       }
-      for (const e of incoming) {
-        const handle = e.sourceHandle ?? "out";
-        if (portValues.has(`${e.source}:${handle}`) || !completed.has(e.source)) continue;
-        if (possiblePortIds(nodesById.get(e.source)).includes(handle)) continue;
-        onEvent({
-          type: "log",
-          nodeId: node.id,
-          level: "warn",
-          message: undeliveredEdgeMessage(e, node, portValues, nodesById),
-          detail: { edge: e.id, source: e.source, sourceHandle: handle }
-        });
+      for (const warning of undeliveredEdgeWarnings(node, incoming, portValues, completed, nodesById)) {
+        onEvent(warning);
       }
       if (incoming.length > 0) {
         const anyActive = incoming.some((e) => portValues.has(`${e.source}:${e.sourceHandle ?? "out"}`));
@@ -758,7 +808,7 @@ async function runFlow(graph, executors, onEvent = () => {
       onEvent({ type: "node-status", nodeId: node.id, status: "running" });
       announce(onEvent, node, "start");
       const inputs = collectInputs(node, incoming, portValues, initialInputs, props, declaresProps);
-      const exec = pickExecutor(executors, node);
+      const exec = pickExecutor(executors, node, nodeExecutors);
       if (!exec) {
         const tried = executorLookupIds(node);
         const msg = `No executor registered for kind=${node.type} \u2014 tried ${tried.map((id) => `"${id}"`).join(", ")}. Key your registry by one of those.`;
@@ -878,7 +928,9 @@ function executorLookupIds(node) {
   ids.push("*");
   return [...new Set(ids)];
 }
-function pickExecutor(executors, node) {
+function pickExecutor(executors, node, nodeExecutors) {
+  const pinned = nodeExecutors && Object.prototype.hasOwnProperty.call(nodeExecutors, node.id) ? nodeExecutors[node.id] : void 0;
+  if (pinned) return pinned;
   for (const id of executorLookupIds(node)) {
     if (executors[id]) return executors[id];
   }
@@ -898,45 +950,6 @@ function activatedPorts(node, result) {
   const declared = resolveNodePorts(node, kind).outputs?.map((p) => p.id);
   return { ports: declared?.length ? declared : ["out"], value: result };
 }
-function possiblePortIds(node) {
-  if (!node) return ["out"];
-  const own = node.data?.outputs;
-  if (Array.isArray(own)) return own.map((p) => p.id);
-  const kind = getNodeKind(node.data?.kind ?? node.type ?? "");
-  if (!kind) return ["out"];
-  const config = nodeConfig(node);
-  const representative = typeof kind.outputs === "function" && !configDeclaresPorts(kind.name, config);
-  const ids = (resolvePortSpec(kind.outputs, representative ? defaultConfigFor(kind) : config) ?? []).map((p) => p.id);
-  return ids.length > 0 ? ids : ["out"];
-}
-function configDeclaresPorts(kindName, config) {
-  const bare = kindName.startsWith("@") ? kindName.slice(kindName.lastIndexOf("/") + 1) : kindName;
-  if (bare === "switch_case") {
-    const cases = config.cases;
-    return !!cases && typeof cases === "object" && Object.values(cases).some((port) => typeof port === "string" && port !== "");
-  }
-  if (bare === "llm_router") {
-    const routes = config.routes;
-    return Array.isArray(routes) && routes.some((route) => route?.port != null && route.port !== "");
-  }
-  return true;
-}
-function undeliveredEdgeMessage(edge, target, portValues, nodesById) {
-  const handle = edge.sourceHandle ?? "out";
-  const prefix = `${edge.source}:`;
-  const available = [];
-  for (const key of portValues.keys()) {
-    if (key.startsWith(prefix)) available.push(key.slice(prefix.length));
-  }
-  let message = `Edge ${edge.id} reads port "${handle}" from node ${edge.source}, which never publishes it \u2014 nothing would reach ${target.id} at run time.`;
-  if (available.length > 0) message += ` Available: ${available.join(", ")}.`;
-  const source = nodesById.get(edge.source);
-  if (source && outputFieldsFor(source).some((field) => field?.path === handle)) {
-    message += ` Note: "${handle}" is a FIELD this node emits, not a port \u2014 read it downstream as {{ in.${handle} }} rather than naming it as a source handle.`;
-  }
-  if (edge.sourceHandle != null) message += " Leave sourceHandle off to read the node's output.";
-  return message;
-}
 function announce(onEvent, node, phase) {
   const data = node.data;
   const raw = phase === "start" ? data?.startingMsg : data?.stoppingMsg;
@@ -2704,20 +2717,35 @@ var Frontier = {
       (entry) => entry.status === NodeRunStatus.CLAIMED || entry.status === NodeRunStatus.PAUSED
     );
   },
-  /** Persist the skip cascade so the next pass does not recompute it. */
+  /**
+   * Persist the skip cascade so the next pass does not recompute it.
+   *
+   * Resolves to the ids THIS call settled, in cascade order. A node another
+   * caller had already settled is left out — its store reported `false` — so a
+   * caller acting on "I skipped this" acts once per node, not once per racer. A
+   * store whose `skip` returns nothing counts every id as settled here.
+   */
   async settleSkips(store, runKey, skipped) {
-    for (const nodeId of skipped) await store.skip(runKey, nodeId);
+    const settled = [];
+    for (const nodeId of skipped) {
+      if (await store.skip(runKey, nodeId) !== false) settled.push(nodeId);
+    }
+    return settled;
   }
 };
 
 // src/durable/replay.ts
 var BOUNDARY = "fancy-flow:node-boundary";
+var FENCE_PORT = "fancy-flow:fenced";
 async function replayUpTo(graph, nodeId, executors, options = {}) {
-  const fenced = { ...executors };
+  const fencedOff = /* @__PURE__ */ new Set();
+  const fence = (ctx) => {
+    fencedOff.add(ctx.node.id);
+    return { __port: FENCE_PORT, value: null };
+  };
+  const fences = {};
   for (const node of graph.nodes) {
-    if (node.id !== nodeId) {
-      fenced[node.id] = (ctx) => ctx.abort(BOUNDARY);
-    }
+    if (node.id !== nodeId) fences[node.id] = fence;
   }
   const ports = {};
   const collect = (event) => {
@@ -2727,12 +2755,17 @@ async function replayUpTo(graph, nodeId, executors, options = {}) {
     }
     options.onEvent?.(event);
   };
-  const result = await runFlow(graph, fenced, collect, {
+  const result = await runFlow(graph, executors, collect, {
     initialInputs: options.initialInputs ?? {},
     resumeOutputs: options.resumeOutputs ?? {},
     depth: options.depth ?? 0,
-    run: options.run
+    run: options.run,
+    nodeExecutors: fences
   });
+  for (const id of fencedOff) {
+    delete result.outputs[id];
+    delete ports[id];
+  }
   return {
     result,
     ports,
@@ -2911,10 +2944,19 @@ var Coordinator = class {
    *
    * Also settles the skip cascade, because a skip is a decision the frontier
    * just made and a second caller must not make it again.
+   *
+   * And it is where a skipped node's undelivered-edge warnings are emitted. A
+   * skipped node never gets a job, so it never replays to warn for itself: its
+   * warning used to be raised inside OTHER jobs' replays, carrying its node id,
+   * and {@link forward} filtered it out. Asking at the skip decision — the one
+   * place that knows the node will never run — delivers it, and asking only for
+   * the nodes this call actually settled delivers it once.
    */
   async advance() {
-    const frontier = Frontier.compute(this.graph, await this.store.state(this.runKey));
-    await Frontier.settleSkips(this.store, this.runKey, frontier.skipped);
+    const state = await this.store.state(this.runKey);
+    const frontier = Frontier.compute(this.graph, state);
+    const settled = await Frontier.settleSkips(this.store, this.runKey, frontier.skipped);
+    this.warnForSkipped(settled, state);
     return frontier.ready;
   }
   /**
@@ -2954,12 +2996,12 @@ var Coordinator = class {
       await this.store.pause(this.runKey, nodeId, result.error ?? "");
       return { nodeId, status: "paused", pause, claimed: true, attempt };
     }
-    if (isBoundary(result.error)) {
+    if (isBoundary(result.error) || result.ok) {
       await this.store.skip(this.runKey, nodeId);
       return {
         nodeId,
         status: "skipped",
-        error: "replay stopped before reaching this node",
+        error: "the engine found no live inbound edge for this node",
         claimed: true,
         attempt
       };
@@ -3070,6 +3112,40 @@ var Coordinator = class {
     if (!row) return this.run;
     return this.run.withAttempt(row.attempts, row.firstAttemptAt);
   }
+  /**
+   * Send `runFlow`'s undelivered-edge warnings for nodes the frontier skipped.
+   *
+   * The check is `undeliveredEdgeWarnings` — the SAME function `runFlow` calls —
+   * fed the durable equivalent of the engine's own bookkeeping: a port key for
+   * every port a COMPLETED node's claim row stored, in stored order, and the set
+   * of COMPLETED ids. `state` is the snapshot the frontier decided from, and
+   * every predecessor of a skipped node had settled in it, so it holds all a
+   * target's sources.
+   *
+   * Only skipped nodes. A target that RUNS (it had another live inbound edge)
+   * already gets its warning from its own job's replay, whose events carry its
+   * node id and are forwarded — asking here too would send it twice.
+   */
+  warnForSkipped(skipped, state) {
+    const sink = this.onEvent;
+    if (!sink || skipped.length === 0) return;
+    const portValues = /* @__PURE__ */ new Map();
+    const completed = /* @__PURE__ */ new Set();
+    for (const [nodeId, entry] of Object.entries(state)) {
+      if (entry.status !== NodeRunStatus.COMPLETED) continue;
+      completed.add(nodeId);
+      for (const portId of entry.ports) portValues.set(`${nodeId}:${portId}`, entry.output);
+    }
+    const nodesById = new Map(this.graph.nodes.map((n) => [n.id, n]));
+    for (const nodeId of skipped) {
+      const target = nodesById.get(nodeId);
+      if (!target) continue;
+      const incoming = this.graph.edges.filter((e) => e.target === nodeId);
+      for (const warning of undeliveredEdgeWarnings(target, incoming, portValues, completed, nodesById)) {
+        sink(warning);
+      }
+    }
+  }
   async completedOutputs() {
     const state = await this.store.state(this.runKey);
     const out = {};
@@ -3101,6 +3177,7 @@ function cryptoRandom() {
 
 exports.BOUNDARY = BOUNDARY;
 exports.Coordinator = Coordinator;
+exports.FENCE_PORT = FENCE_PORT;
 exports.Frontier = Frontier;
 exports.InMemoryClaimStore = InMemoryClaimStore;
 exports.NodeRunStatus = NodeRunStatus;