@particle-academy/fancy-flow 0.71.0 → 0.72.1

package/dist/{chunk-KQCX6KN7.js.map → chunk-VAF2SWTC.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/analysis/graph-connectivity.ts"],"names":[],"mappings":";;;AAsCO,SAAS,uBAAuB,KAAA,EAAiC;AACtE,EAAA,MAAM,EAAE,KAAA,EAAO,KAAA,EAAM,GAAI,KAAA;AACzB,EAAA,MAAM,SAAwB,EAAC;AAE/B,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AACpC,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AACpC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,WAAA,CAAY,GAAA,CAAI,KAAK,MAAM,CAAA;AAC3B,IAAA,WAAA,CAAY,GAAA,CAAI,KAAK,MAAM,CAAA;AAAA,EAC7B;AAMA,EAAA,MAAM,MAAA,GAAS,MAAM,MAAA,KAAW,CAAA;AAEhC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI,MAAA,IAAU,QAAA,CAAS,IAAI,CAAA,EAAG;AAE9B,IAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,IAAK,CAAC,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,EAAG;AAC1D,MAAA,MAAA,CAAO,IAAA,CAAK;AAAA,QACV,KAAA,EAAO,OAAA;AAAA,QACP,QAAQ,IAAA,CAAK,EAAA;AAAA,QACb,OAAA,EACE,CAAA,MAAA,EAAS,IAAA,CAAK,EAAE,CAAA,oSAAA;AAAA,OAInB,CAAA;AAAA,IACH;AAAA,EACF;AAEA,EAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,EAAA,EAAI,CAAC,CAAC,CAAC,CAAA;AAEhD,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA;AACnC,IAAA,IAAI,CAAC,MAAA,IAAU,CAAC,YAAA,CAAa,MAAM,CAAA,EAAG;AAEtC,IAAA,MAAA,CAAO,IAAA,CAAK;AAAA,MACV,KAAA,EAAO,OAAA;AAAA,MACP,QAAQ,IAAA,CAAK,EAAA;AAAA,MACb,OAAA,EACE,SAAS,IAAA,CAAK,EAAE,iBAAiB,IAAA,CAAK,MAAM,CAAA,6JAAA,EAET,IAAA,CAAK,MAAM,CAAA,kCAAA;AAAA,KACjD,CAAA;AAAA,EACH;AAEA,EAAA,OAAO,MAAA;AACT;AAyBO,SAAS,SAAS,IAAA,EAAyB;AAChD,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAClB,EAAA,IAAI,CAAC,MAAM,OAAO,KAAA;AAClB,EAAA,IAAI,IAAA,KAAS,QAAQ,OAAO,IAAA;AAE5B,EAAA,MAAM,IAAA,GAAO,YAAY,IAAI,CAAA;AAC7B,EAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAElB,EAAA,OAAO,OAAA,CAAQ,IAAI,CAAA,CAAE,QAAA,CAAS,MAAM,KAAK,IAAA,CAAK,QAAA,KAAa,YAAA,IAAgB,IAAA,CAAK,QAAA,KAAa,QAAA;AAC/F;AAWA,SAAS,aAAa,IAAA,EAAyB;AAM7C,EAAA,MAAM,GAAA,GAAO,KAAK,IAAA,EAA8C,OAAA;AAChE,EAAA,IAAI,MAAM,OAAA,CAAQ,GAAG,CAAA,EAAG,OAAO,IAAI,MAAA,KAAW,CAAA;AAE9C,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA,GAAO,WAAA,CAAY,IAAA,CAAK,IAAI,CAAA,GAAI,IAAA;AAKlD,EAAA,IAAI,CAAC,MAAM,OAAO,KAAA;AAElB,EAAA,OAAO,MAAM,OAAA,CAAQ,IAAA,CAAK,OAAO,CAAA,IAAK,IAAA,CAAK,QAAQ,MAAA,KAAW,CAAA;AAChE","file":"chunk-KQCX6KN7.js","sourcesContent":["import { getNodeKind, kindIds } from \"../registry/registry\";\nimport type { FlowGraph, FlowNode } from \"../types\";\nimport type { ImportIssue } from \"../schema/workflow-schema\";\n\n/**\n * Refuse a graph whose nodes cannot take part in the workflow's dataflow.\n *\n * Two shapes, both of which import cleanly and then quietly do nothing. Neither\n * FAILS — which is what makes them worth refusing at authoring time, because a\n * run that reports success is the worst way for a workflow to be wrong. Both\n * were measured against the PHP twin's engine before this was written, and both\n * behave the same way here:\n *\n * ## 1. A FLOATING node — no inbound and no outbound edge\n *\n * It is NOT skipped. A node with no incoming edge is a root, so the topo sort\n * runs it: a three-node graph with one floating `log` executed `t,lonely,o`. It\n * runs disconnected — receiving nothing from the graph and reaching nobody in\n * it — which is precisely the state an author cannot see on a canvas.\n *\n * ## 2. An edge leaving a TERMINATOR\n *\n * A terminal kind — `output`, `log` — declares an EMPTY output port list. It\n * ends a chain. Measured: `t -> output -> log` imported clean and the `log` DID\n * run, with `{{ input }}` resolving to `\"\"`. `collectInputs` binds a payload\n * only when `\"<sourceId>:<handle>\"` exists, and a node publishing no ports never\n * creates that key — so the edge does not fail, it delivers nothing, and the\n * node downstream operates on a hole.\n *\n * That is the same silent-nothing the undelivered-edge diagnostic reports at run\n * time, but this one is decidable FROM THE DOCUMENT ALONE.\n *\n * ## What may float\n *\n * See {@link mayFloat}. Not only `note`: any `annotation` or `layout` kind (a\n * swimlane is never wired to anything — that is what a lane IS), and any kind\n * the registry does not know.\n */\nexport function checkGraphConnectivity(graph: FlowGraph): ImportIssue[] {\n  const { nodes, edges } = graph;\n  const issues: ImportIssue[] = [];\n\n  const hasIncoming = new Set<string>();\n  const hasOutgoing = new Set<string>();\n  for (const edge of edges) {\n    hasIncoming.add(edge.target);\n    hasOutgoing.add(edge.source);\n  }\n\n  // A single-node graph is not \"floating\" — it is a graph with one step, which\n  // is a legitimate (if small) workflow and what every graph looks like on the\n  // way to a bigger one. Refusing it would make the editor unusable from the\n  // first node placed.\n  const single = nodes.length === 1;\n\n  for (const node of nodes) {\n    if (single || mayFloat(node)) continue;\n\n    if (!hasIncoming.has(node.id) && !hasOutgoing.has(node.id)) {\n      issues.push({\n        level: \"error\",\n        nodeId: node.id,\n        message:\n          `Node \"${node.id}\" is connected to nothing — no inbound edge and no outbound edge. ` +\n          `It still RUNS (a node with no inbound edge is a root), but it receives nothing from ` +\n          `the graph and reaches nobody in it, so it is either unwired or left behind by a ` +\n          `deletion. Only a note, an annotation or a lane may float.`,\n      });\n    }\n  }\n\n  const byId = new Map(nodes.map((n) => [n.id, n]));\n\n  for (const edge of edges) {\n    const source = byId.get(edge.source);\n    if (!source || !isTerminator(source)) continue;\n\n    issues.push({\n      level: \"error\",\n      edgeId: edge.id,\n      message:\n        `Edge \"${edge.id}\" reads from \"${edge.source}\", which is a TERMINAL node and publishes ` +\n        `no output ports at all. Nothing can ever travel this edge: it does not fail at run ` +\n        `time, it delivers nothing, and \"${edge.target}\" runs anyway with an empty input.`,\n    });\n  }\n\n  return issues;\n}\n\n/**\n * Which nodes are allowed to sit unconnected.\n *\n * Three answers, and the third is the one that took a second pass — it was\n * missed in the PHP twin's first release and shipped as 0.48.1:\n *\n * 1. **`note`**, across every id the kind answers to, so a graph saved with the\n *    canonical `@particle-academy/note` stays an annotation rather than becoming\n *    an unwireable node.\n * 2. **Any `annotation` or `layout` kind.** A host may register its own note,\n *    and `@particle-academy/lane` is a swimlane the engine walks straight past.\n *    Neither is a step and neither is ever wired.\n * 3. **A kind the registry has never heard of.** Not a loophole — the honest\n *    answer. An unknown kind already produces its own issue, and we cannot know\n *    whether it is a step, an annotation or a lane. Claiming it must be wired\n *    would assert something unverifiable, and it lands hardest on the graphs\n *    that deserve it least: a laned graph loaded by a runtime without `lane`\n *    registered would report every swimlane twice, the second time wrongly.\n *\n * The note/annotation/layout half matches the test `run-flow` uses to skip a\n * node. The unknown-kind half deliberately does NOT — see the closing comment in\n * this file for why the two must not become one helper.\n */\nexport function mayFloat(node: FlowNode): boolean {\n  const type = node.type;\n  if (!type) return false;\n  if (type === \"note\") return true;\n\n  const kind = getNodeKind(type);\n  if (!kind) return true;\n\n  return kindIds(kind).includes(\"note\") || kind.category === \"annotation\" || kind.category === \"layout\";\n}\n\n/**\n * A kind that declares an EMPTY output list ends a chain.\n *\n * `[]` and `undefined` are different answers and only the first means this.\n * `undefined` is \"nobody declared what this publishes\", which resolves to `out`\n * and is most nodes in most graphs; `[]` is an explicit claim that there is\n * nothing to connect from. Reading them alike would refuse nearly every\n * workflow ever written.\n */\nfunction isTerminator(node: FlowNode): boolean {\n  // A node carrying its own ports overrides its kind — the engine reads these\n  // first, so an author who has said what this node publishes is believed.\n  // (The PHP twin's importer DROPS node-level ports, so this branch is reachable\n  // there only for a hand-built graph. Noted rather than smoothed over: the two\n  // importers genuinely differ here.)\n  const own = (node.data as { outputs?: unknown[] } | undefined)?.outputs;\n  if (Array.isArray(own)) return own.length === 0;\n\n  const kind = node.type ? getNodeKind(node.type) : null;\n\n  // An unregistered kind falls back to `out` in the engine, so it is not a\n  // terminator. Refusing here would break a host mid-registration, and would\n  // use \"I do not know\" as evidence.\n  if (!kind) return false;\n\n  return Array.isArray(kind.outputs) && kind.outputs.length === 0;\n}\n\n/**\n * NOT shared with `frontier`'s / `run-flow`'s annotation test, deliberately.\n *\n * The two predicates look identical and have OPPOSITE safe defaults, which is\n * exactly how a shared helper becomes a bug:\n *\n * - **Here** an unknown kind may float. Being permissive costs nothing — the\n *   unknown-kind issue already fires, and we would otherwise assert something\n *   unverifiable.\n * - **In the engine** an unknown kind must NOT be treated as an annotation.\n *   Being permissive there means SKIPPING a node the host meant to run, which\n *   is silent and unrecoverable.\n *\n * So the note/annotation/layout half is the same question and the unknown half\n * is a different one. Collapsing them into one function would read as tidier and\n * would make a host's unregistered kind stop executing.\n */\n"]}
+{"version":3,"sources":["../src/analysis/graph-connectivity.ts"],"names":[],"mappings":";;;AAsCO,SAAS,uBAAuB,KAAA,EAAiC;AACtE,EAAA,MAAM,EAAE,KAAA,EAAO,KAAA,EAAM,GAAI,KAAA;AACzB,EAAA,MAAM,SAAwB,EAAC;AAE/B,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AACpC,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AACpC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,WAAA,CAAY,GAAA,CAAI,KAAK,MAAM,CAAA;AAC3B,IAAA,WAAA,CAAY,GAAA,CAAI,KAAK,MAAM,CAAA;AAAA,EAC7B;AAMA,EAAA,MAAM,MAAA,GAAS,MAAM,MAAA,KAAW,CAAA;AAEhC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI,MAAA,IAAU,QAAA,CAAS,IAAI,CAAA,EAAG;AAE9B,IAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,IAAK,CAAC,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA,EAAG;AAC1D,MAAA,MAAA,CAAO,IAAA,CAAK;AAAA,QACV,KAAA,EAAO,OAAA;AAAA,QACP,QAAQ,IAAA,CAAK,EAAA;AAAA,QACb,OAAA,EACE,CAAA,MAAA,EAAS,IAAA,CAAK,EAAE,CAAA,oSAAA;AAAA,OAInB,CAAA;AAAA,IACH;AAAA,EACF;AAEA,EAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,EAAA,EAAI,CAAC,CAAC,CAAC,CAAA;AAEhD,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA;AACnC,IAAA,IAAI,CAAC,MAAA,IAAU,CAAC,YAAA,CAAa,MAAM,CAAA,EAAG;AAEtC,IAAA,MAAA,CAAO,IAAA,CAAK;AAAA,MACV,KAAA,EAAO,OAAA;AAAA,MACP,QAAQ,IAAA,CAAK,EAAA;AAAA,MACb,OAAA,EACE,SAAS,IAAA,CAAK,EAAE,iBAAiB,IAAA,CAAK,MAAM,CAAA,6JAAA,EAET,IAAA,CAAK,MAAM,CAAA,kCAAA;AAAA,KACjD,CAAA;AAAA,EACH;AAEA,EAAA,OAAO,MAAA;AACT;AAyBO,SAAS,SAAS,IAAA,EAAyB;AAChD,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAClB,EAAA,IAAI,CAAC,MAAM,OAAO,KAAA;AAClB,EAAA,IAAI,IAAA,KAAS,QAAQ,OAAO,IAAA;AAE5B,EAAA,MAAM,IAAA,GAAO,YAAY,IAAI,CAAA;AAC7B,EAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAElB,EAAA,OAAO,OAAA,CAAQ,IAAI,CAAA,CAAE,QAAA,CAAS,MAAM,KAAK,IAAA,CAAK,QAAA,KAAa,YAAA,IAAgB,IAAA,CAAK,QAAA,KAAa,QAAA;AAC/F;AAWA,SAAS,aAAa,IAAA,EAAyB;AAM7C,EAAA,MAAM,GAAA,GAAO,KAAK,IAAA,EAA8C,OAAA;AAChE,EAAA,IAAI,MAAM,OAAA,CAAQ,GAAG,CAAA,EAAG,OAAO,IAAI,MAAA,KAAW,CAAA;AAE9C,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA,GAAO,WAAA,CAAY,IAAA,CAAK,IAAI,CAAA,GAAI,IAAA;AAKlD,EAAA,IAAI,CAAC,MAAM,OAAO,KAAA;AAElB,EAAA,OAAO,MAAM,OAAA,CAAQ,IAAA,CAAK,OAAO,CAAA,IAAK,IAAA,CAAK,QAAQ,MAAA,KAAW,CAAA;AAChE","file":"chunk-VAF2SWTC.js","sourcesContent":["import { getNodeKind, kindIds } from \"../registry/registry\";\nimport type { FlowGraph, FlowNode } from \"../types\";\nimport type { ImportIssue } from \"../schema/workflow-schema\";\n\n/**\n * Refuse a graph whose nodes cannot take part in the workflow's dataflow.\n *\n * Two shapes, both of which import cleanly and then quietly do nothing. Neither\n * FAILS — which is what makes them worth refusing at authoring time, because a\n * run that reports success is the worst way for a workflow to be wrong. Both\n * were measured against the PHP twin's engine before this was written, and both\n * behave the same way here:\n *\n * ## 1. A FLOATING node — no inbound and no outbound edge\n *\n * It is NOT skipped. A node with no incoming edge is a root, so the topo sort\n * runs it: a three-node graph with one floating `log` executed `t,lonely,o`. It\n * runs disconnected — receiving nothing from the graph and reaching nobody in\n * it — which is precisely the state an author cannot see on a canvas.\n *\n * ## 2. An edge leaving a TERMINATOR\n *\n * A terminal kind — `output`, `log` — declares an EMPTY output port list. It\n * ends a chain. Measured: `t -> output -> log` imported clean and the `log` DID\n * run, with `{{ input }}` resolving to `\"\"`. `collectInputs` binds a payload\n * only when `\"<sourceId>:<handle>\"` exists, and a node publishing no ports never\n * creates that key — so the edge does not fail, it delivers nothing, and the\n * node downstream operates on a hole.\n *\n * That is the same silent-nothing the undelivered-edge diagnostic reports at run\n * time, but this one is decidable FROM THE DOCUMENT ALONE.\n *\n * ## What may float\n *\n * See {@link mayFloat}. Not only `note`: any `annotation` or `layout` kind (a\n * swimlane is never wired to anything — that is what a lane IS), and any kind\n * the registry does not know.\n */\nexport function checkGraphConnectivity(graph: FlowGraph): ImportIssue[] {\n  const { nodes, edges } = graph;\n  const issues: ImportIssue[] = [];\n\n  const hasIncoming = new Set<string>();\n  const hasOutgoing = new Set<string>();\n  for (const edge of edges) {\n    hasIncoming.add(edge.target);\n    hasOutgoing.add(edge.source);\n  }\n\n  // A single-node graph is not \"floating\" — it is a graph with one step, which\n  // is a legitimate (if small) workflow and what every graph looks like on the\n  // way to a bigger one. Refusing it would make the editor unusable from the\n  // first node placed.\n  const single = nodes.length === 1;\n\n  for (const node of nodes) {\n    if (single || mayFloat(node)) continue;\n\n    if (!hasIncoming.has(node.id) && !hasOutgoing.has(node.id)) {\n      issues.push({\n        level: \"error\",\n        nodeId: node.id,\n        message:\n          `Node \"${node.id}\" is connected to nothing — no inbound edge and no outbound edge. ` +\n          `It still RUNS (a node with no inbound edge is a root), but it receives nothing from ` +\n          `the graph and reaches nobody in it, so it is either unwired or left behind by a ` +\n          `deletion. Only a note, an annotation or a lane may float.`,\n      });\n    }\n  }\n\n  const byId = new Map(nodes.map((n) => [n.id, n]));\n\n  for (const edge of edges) {\n    const source = byId.get(edge.source);\n    if (!source || !isTerminator(source)) continue;\n\n    issues.push({\n      level: \"error\",\n      edgeId: edge.id,\n      message:\n        `Edge \"${edge.id}\" reads from \"${edge.source}\", which is a TERMINAL node and publishes ` +\n        `no output ports at all. Nothing can ever travel this edge: it does not fail at run ` +\n        `time, it delivers nothing, and \"${edge.target}\" runs anyway with an empty input.`,\n    });\n  }\n\n  return issues;\n}\n\n/**\n * Which nodes are allowed to sit unconnected.\n *\n * Three answers, and the third is the one that took a second pass — it was\n * missed in the PHP twin's first release and shipped as 0.48.1:\n *\n * 1. **`note`**, across every id the kind answers to, so a graph saved with the\n *    canonical `@particle-academy/note` stays an annotation rather than becoming\n *    an unwireable node.\n * 2. **Any `annotation` or `layout` kind.** A host may register its own note,\n *    and `@particle-academy/lane` is a swimlane the engine walks straight past.\n *    Neither is a step and neither is ever wired.\n * 3. **A kind the registry has never heard of.** Not a loophole — the honest\n *    answer. An unknown kind already produces its own issue, and we cannot know\n *    whether it is a step, an annotation or a lane. Claiming it must be wired\n *    would assert something unverifiable, and it lands hardest on the graphs\n *    that deserve it least: a laned graph loaded by a runtime without `lane`\n *    registered would report every swimlane twice, the second time wrongly.\n *\n * The note/annotation/layout half matches the test `run-flow` uses to skip a\n * node. The unknown-kind half deliberately does NOT — see the closing comment in\n * this file for why the two must not become one helper.\n */\nexport function mayFloat(node: FlowNode): boolean {\n  const type = node.type;\n  if (!type) return false;\n  if (type === \"note\") return true;\n\n  const kind = getNodeKind(type);\n  if (!kind) return true;\n\n  return kindIds(kind).includes(\"note\") || kind.category === \"annotation\" || kind.category === \"layout\";\n}\n\n/**\n * A kind that declares an EMPTY output list ends a chain.\n *\n * `[]` and `undefined` are different answers and only the first means this.\n * `undefined` is \"nobody declared what this publishes\", which resolves to `out`\n * and is most nodes in most graphs; `[]` is an explicit claim that there is\n * nothing to connect from. Reading them alike would refuse nearly every\n * workflow ever written.\n */\nfunction isTerminator(node: FlowNode): boolean {\n  // A node carrying its own ports overrides its kind — the engine reads these\n  // first, so an author who has said what this node publishes is believed.\n  // (The PHP twin's importer DROPS node-level ports, so this branch is reachable\n  // there only for a hand-built graph. Noted rather than smoothed over: the two\n  // importers genuinely differ here.)\n  const own = (node.data as { outputs?: unknown[] } | undefined)?.outputs;\n  if (Array.isArray(own)) return own.length === 0;\n\n  const kind = node.type ? getNodeKind(node.type) : null;\n\n  // An unregistered kind falls back to `out` in the engine, so it is not a\n  // terminator. Refusing here would break a host mid-registration, and would\n  // use \"I do not know\" as evidence.\n  if (!kind) return false;\n\n  return Array.isArray(kind.outputs) && kind.outputs.length === 0;\n}\n\n/**\n * NOT shared with `frontier`'s / `run-flow`'s annotation test, deliberately.\n *\n * The two predicates look identical and have OPPOSITE safe defaults, which is\n * exactly how a shared helper becomes a bug:\n *\n * - **Here** an unknown kind may float. Being permissive costs nothing — the\n *   unknown-kind issue already fires, and we would otherwise assert something\n *   unverifiable.\n * - **In the engine** an unknown kind must NOT be treated as an annotation.\n *   Being permissive there means SKIPPING a node the host meant to run, which\n *   is silent and unrecoverable.\n *\n * So the note/annotation/layout half is the same question and the unknown half\n * is a different one. Collapsing them into one function would read as tidier and\n * would make a host's unregistered kind stop executing.\n */\n"]}

package/dist/durable/index.d.cts

@@ -1,5 +1,5 @@
 import { F as FlowGraph, R as RunEvent, c as RunIdentity, E as ExecutorRegistry, a as FlowNode, N as NodeExecutor, d as RunIdentityJson } from '../types-B-Syk9-M.cjs';
-import { a as RunResult } from '../run-flow-B_8hgO5_.cjs';
+import { a as RunResult } from '../run-flow-pW0PllaZ.cjs';
 import { b as PauseSignal } from '../pause-9iT4tCEV.cjs';
 import '@xyflow/react';
 
@@ -73,7 +73,19 @@ interface NodeClaimStore {
     claim(runKey: string, nodeId: string, owner: string): boolean | Promise<boolean>;
     state(runKey: string): Record<string, NodeState> | Promise<Record<string, NodeState>>;
     complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void | Promise<void>;
-    skip(runKey: string, nodeId: string): void | Promise<void>;
+    /**
+     * Settle one node as skipped.
+     *
+     * Return whether THIS call moved the row to skipped: `false` when the row was
+     * already skipped — another caller's frontier made the same decision first.
+     * The coordinator emits a skipped node's diagnostics only for a call that
+     * settled it, so a warning arrives once however many callers race.
+     *
+     * Returning nothing is still allowed, for stores written before the boolean,
+     * and counts as "settled now". Such a store can report a skip twice under a
+     * race, and nothing worse.
+     */
+    skip(runKey: string, nodeId: string): boolean | void | Promise<boolean | void>;
     fail(runKey: string, nodeId: string, error: string): void | Promise<void>;
     pause(runKey: string, nodeId: string, reason: string): void | Promise<void>;
 }
@@ -90,7 +102,7 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     claim(runKey: string, nodeId: string, owner: string): boolean;
     state(runKey: string): Record<string, NodeState>;
     complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void;
-    skip(runKey: string, nodeId: string): void;
+    skip(runKey: string, nodeId: string): boolean;
     fail(runKey: string, nodeId: string, error: string): void;
     pause(runKey: string, nodeId: string, reason: string): void;
     /**
@@ -157,8 +169,15 @@ declare const Frontier: {
      * waited on.
      */
     hasWorkInFlight(state: Record<string, NodeState>): boolean;
-    /** Persist the skip cascade so the next pass does not recompute it. */
-    settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
 /**
@@ -180,12 +199,38 @@ declare const Frontier: {
  * - every node already completed is fed back as `resumeOutputs`, so the engine
  *   republishes it on the same ports and routes exactly as it did the first
  *   time;
- * - every node EXCEPT the target is bound, by node id, to a boundary executor
- *   that aborts — and a node-id binding outranks every kind binding and the
- *   `*` fallback, so the fence holds whatever a host registered;
+ * - every node EXCEPT the target is bound, through `RunOptions.nodeExecutors`,
+ *   to a FENCE that runs nothing and publishes only a port no edge reads;
  * - so the engine walks its own topological order, skips its own dead branches,
- *   collects the target's inputs its own way, runs the target — and stops at
- *   the next thing it would have run.
+ *   collects the target's inputs its own way, and runs the target.
+ *
+ * ## Why the fence does not stop the walk
+ *
+ * It used to abort the run. The target's own inputs never depend on a fenced
+ * node -- the frontier dispatches a node only once every source is settled, and
+ * settled sources are resumed, not fenced -- but an UNRELATED node can precede
+ * the target in topological order. Two siblings dispatched together are exactly
+ * that: when `b`'s job started while `a` was still running, the replay aborted
+ * at `a`, never reached `b`, and the coordinator read "the replay ended without
+ * running me" as "the engine decided I am unreachable". `b` was recorded
+ * skipped, never ran, and the run completed as a success. It did not even take
+ * two workers: the frontier lists ready nodes in NODE order and the engine walks
+ * EDGE order, so a graph where those disagree about siblings sent in-process
+ * `runToCompletion` down the same path.
+ *
+ * Walking past fences makes that inference honest again: when the replay
+ * finishes without an output for the target, it is because the engine found
+ * every inbound edge dead.
+ *
+ * ## Why the fences are not registry entries
+ *
+ * The registry is one flat object, and a key in it is tried as a node's id AND
+ * as its kind. Fencing the node called `host_kind` by writing
+ * `executors["host_kind"]` fenced every node of kind `host_kind` too, so a
+ * durable run of that graph ran nothing and reported success. And the registry
+ * is what `ctx.executors` hands a `subflow` child, so a child node sharing an id
+ * with any parent node ran the parent's fence. `nodeExecutors` matches node ids
+ * only and is never handed down; the registry reaches the engine untouched.
  *
  * The target's output is `result.outputs[nodeId]`, and the ports it activated
  * arrive as the engine's own `node-output` events. Nothing about routing is
@@ -201,12 +246,19 @@ declare const Frontier: {
  */
 
 /**
- * The abort reason the boundary executor uses.
+ * The abort reason a boundary used to report.
  *
- * Not a failure: it is the engine telling us it reached a node this job is not
- * responsible for.
+ * Nothing aborts with it any more (see "Why the fence does not stop the walk");
+ * {@link isBoundary} still recognises it so a caller that checks for it keeps
+ * working.
  */
 declare const BOUNDARY = "fancy-flow:node-boundary";
+/**
+ * The port a fenced node publishes on. No edge reads it, so everything
+ * downstream of a fenced node is dark in the replay -- which never matters to
+ * the target, whose sources are all settled.
+ */
+declare const FENCE_PORT = "fancy-flow:fenced";
 type ReplayResult = {
     result: RunResult;
     /** node id -> the ports its output activated, from the engine's own events. */
@@ -224,8 +276,8 @@ type ReplayOptions = {
 /**
  * Replay `graph` up to and through `nodeId`.
  *
- * Pass `nodeId = null` to PROBE: every node is a boundary, so nothing executes
- * and the engine reports only what it can determine structurally — a cycle, and
+ * Pass `nodeId = null` to PROBE: every node is fenced, so nothing executes and
+ * the engine reports only what it can determine structurally — a cycle, and
  * the ports each resumed output republishes on.
  */
 declare function replayUpTo(graph: FlowGraph, nodeId: string | null, executors: ExecutorRegistry, options?: ReplayOptions): Promise<ReplayResult>;
@@ -431,6 +483,13 @@ declare class Coordinator {
      *
      * 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.
      */
     advance(): Promise<string[]>;
     /**
@@ -476,6 +535,21 @@ declare class Coordinator {
      * exact instead of conservative.
      */
     private identityFor;
+    /**
+     * 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.
+     */
+    private warnForSkipped;
     private completedOutputs;
     /**
      * Forward only the events the target node produced.
@@ -487,4 +561,4 @@ declare class Coordinator {
     private forward;
 }
 
-export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };
+export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };

package/dist/durable/index.d.ts

@@ -1,5 +1,5 @@
 import { F as FlowGraph, R as RunEvent, c as RunIdentity, E as ExecutorRegistry, a as FlowNode, N as NodeExecutor, d as RunIdentityJson } from '../types-B-Syk9-M.js';
-import { a as RunResult } from '../run-flow-CxEGBOxd.js';
+import { a as RunResult } from '../run-flow-BLP9rXfO.js';
 import { b as PauseSignal } from '../pause-9iT4tCEV.js';
 import '@xyflow/react';
 
@@ -73,7 +73,19 @@ interface NodeClaimStore {
     claim(runKey: string, nodeId: string, owner: string): boolean | Promise<boolean>;
     state(runKey: string): Record<string, NodeState> | Promise<Record<string, NodeState>>;
     complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void | Promise<void>;
-    skip(runKey: string, nodeId: string): void | Promise<void>;
+    /**
+     * Settle one node as skipped.
+     *
+     * Return whether THIS call moved the row to skipped: `false` when the row was
+     * already skipped — another caller's frontier made the same decision first.
+     * The coordinator emits a skipped node's diagnostics only for a call that
+     * settled it, so a warning arrives once however many callers race.
+     *
+     * Returning nothing is still allowed, for stores written before the boolean,
+     * and counts as "settled now". Such a store can report a skip twice under a
+     * race, and nothing worse.
+     */
+    skip(runKey: string, nodeId: string): boolean | void | Promise<boolean | void>;
     fail(runKey: string, nodeId: string, error: string): void | Promise<void>;
     pause(runKey: string, nodeId: string, reason: string): void | Promise<void>;
 }
@@ -90,7 +102,7 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     claim(runKey: string, nodeId: string, owner: string): boolean;
     state(runKey: string): Record<string, NodeState>;
     complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void;
-    skip(runKey: string, nodeId: string): void;
+    skip(runKey: string, nodeId: string): boolean;
     fail(runKey: string, nodeId: string, error: string): void;
     pause(runKey: string, nodeId: string, reason: string): void;
     /**
@@ -157,8 +169,15 @@ declare const Frontier: {
      * waited on.
      */
     hasWorkInFlight(state: Record<string, NodeState>): boolean;
-    /** Persist the skip cascade so the next pass does not recompute it. */
-    settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
 /**
@@ -180,12 +199,38 @@ declare const Frontier: {
  * - every node already completed is fed back as `resumeOutputs`, so the engine
  *   republishes it on the same ports and routes exactly as it did the first
  *   time;
- * - every node EXCEPT the target is bound, by node id, to a boundary executor
- *   that aborts — and a node-id binding outranks every kind binding and the
- *   `*` fallback, so the fence holds whatever a host registered;
+ * - every node EXCEPT the target is bound, through `RunOptions.nodeExecutors`,
+ *   to a FENCE that runs nothing and publishes only a port no edge reads;
  * - so the engine walks its own topological order, skips its own dead branches,
- *   collects the target's inputs its own way, runs the target — and stops at
- *   the next thing it would have run.
+ *   collects the target's inputs its own way, and runs the target.
+ *
+ * ## Why the fence does not stop the walk
+ *
+ * It used to abort the run. The target's own inputs never depend on a fenced
+ * node -- the frontier dispatches a node only once every source is settled, and
+ * settled sources are resumed, not fenced -- but an UNRELATED node can precede
+ * the target in topological order. Two siblings dispatched together are exactly
+ * that: when `b`'s job started while `a` was still running, the replay aborted
+ * at `a`, never reached `b`, and the coordinator read "the replay ended without
+ * running me" as "the engine decided I am unreachable". `b` was recorded
+ * skipped, never ran, and the run completed as a success. It did not even take
+ * two workers: the frontier lists ready nodes in NODE order and the engine walks
+ * EDGE order, so a graph where those disagree about siblings sent in-process
+ * `runToCompletion` down the same path.
+ *
+ * Walking past fences makes that inference honest again: when the replay
+ * finishes without an output for the target, it is because the engine found
+ * every inbound edge dead.
+ *
+ * ## Why the fences are not registry entries
+ *
+ * The registry is one flat object, and a key in it is tried as a node's id AND
+ * as its kind. Fencing the node called `host_kind` by writing
+ * `executors["host_kind"]` fenced every node of kind `host_kind` too, so a
+ * durable run of that graph ran nothing and reported success. And the registry
+ * is what `ctx.executors` hands a `subflow` child, so a child node sharing an id
+ * with any parent node ran the parent's fence. `nodeExecutors` matches node ids
+ * only and is never handed down; the registry reaches the engine untouched.
  *
  * The target's output is `result.outputs[nodeId]`, and the ports it activated
  * arrive as the engine's own `node-output` events. Nothing about routing is
@@ -201,12 +246,19 @@ declare const Frontier: {
  */
 
 /**
- * The abort reason the boundary executor uses.
+ * The abort reason a boundary used to report.
  *
- * Not a failure: it is the engine telling us it reached a node this job is not
- * responsible for.
+ * Nothing aborts with it any more (see "Why the fence does not stop the walk");
+ * {@link isBoundary} still recognises it so a caller that checks for it keeps
+ * working.
  */
 declare const BOUNDARY = "fancy-flow:node-boundary";
+/**
+ * The port a fenced node publishes on. No edge reads it, so everything
+ * downstream of a fenced node is dark in the replay -- which never matters to
+ * the target, whose sources are all settled.
+ */
+declare const FENCE_PORT = "fancy-flow:fenced";
 type ReplayResult = {
     result: RunResult;
     /** node id -> the ports its output activated, from the engine's own events. */
@@ -224,8 +276,8 @@ type ReplayOptions = {
 /**
  * Replay `graph` up to and through `nodeId`.
  *
- * Pass `nodeId = null` to PROBE: every node is a boundary, so nothing executes
- * and the engine reports only what it can determine structurally — a cycle, and
+ * Pass `nodeId = null` to PROBE: every node is fenced, so nothing executes and
+ * the engine reports only what it can determine structurally — a cycle, and
  * the ports each resumed output republishes on.
  */
 declare function replayUpTo(graph: FlowGraph, nodeId: string | null, executors: ExecutorRegistry, options?: ReplayOptions): Promise<ReplayResult>;
@@ -431,6 +483,13 @@ declare class Coordinator {
      *
      * 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.
      */
     advance(): Promise<string[]>;
     /**
@@ -476,6 +535,21 @@ declare class Coordinator {
      * exact instead of conservative.
      */
     private identityFor;
+    /**
+     * 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.
+     */
+    private warnForSkipped;
     private completedOutputs;
     /**
      * Forward only the events the target node produced.
@@ -487,4 +561,4 @@ declare class Coordinator {
     private forward;
 }
 
-export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };
+export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, FENCE_PORT, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };