@particle-academy/fancy-flow 0.72.0 → 0.73.0

package/dist/{chunk-6TC44VCY.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-6TC44VCY.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';
 
@@ -108,6 +108,10 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     /**
      * Drop a paused node's claim so a recorded answer can re-run it.
      *
+     * A PAUSED row holds one of the run's dispatch slots (see `selectDispatch`),
+     * so this is also what frees the slot: until the row is released, a serial
+     * run's `advance()` hands out nothing, the gate included.
+     *
      * 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.
@@ -180,6 +184,57 @@ declare const Frontier: {
     settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
+/**
+ * How many of ONE run's nodes may be held at once, and which ready nodes go next.
+ *
+ * ## Serial is the default
+ *
+ * A queued run hands a node to the queue only once the node before it has
+ * settled: one node of a run held at a time, in the graph's own declaration
+ * order. Parallel dispatch of a ready frontier is something a host ASKS for,
+ * with `maxConcurrent` on the {@link Coordinator}.
+ *
+ * | `maxConcurrent` | meaning |
+ * |---|---|
+ * | unset | **1**: serial |
+ * | `N >= 1` | up to N of the run's nodes held at once |
+ * | {@link UNLIMITED_CONCURRENCY} (`0`) | the whole ready frontier |
+ * | anything else | refused, by name |
+ *
+ * A negative number is refused rather than read as "unlimited". Under a serial
+ * default, a typo that silently turned a run parallel is the failure to avoid.
+ *
+ * ## Held means claimed OR paused
+ *
+ * A node parked on a person keeps its slot. A pause does not park the whole run
+ * in this runtime: `advance()` is called whenever any job settles, and without
+ * this rule it would hand out the gate's siblings while the person is still
+ * deciding.
+ *
+ * ## Measured against held work, not the batch
+ *
+ * Two nodes settling at once each trigger an `advance()` on a real queue. A cap
+ * applied to one batch would let each of them dispatch its own quota, so the
+ * budget is `maxConcurrent - held`, counted off the claim rows.
+ *
+ * This is the TypeScript member of a three-runtime contract. The
+ * `flow/durable-dispatch` conformance suite pins it, and names
+ * `fancy-flow-php`'s `DispatchLimit` and the Python runtime's
+ * `fancy_flow.durable.select_dispatch` as the other two implementations.
+ */
+
+/** Dispatch the whole ready frontier. Named so a host never writes a bare `0`. */
+declare const UNLIMITED_CONCURRENCY = 0;
+/**
+ * The ready nodes that may be dispatched now, in the order given.
+ *
+ * `ready` comes from `Frontier.compute`, in declaration order, and that order is
+ * kept: this slices, it never sorts. `state` must already include any skips the
+ * frontier just settled. Skips are never held, so that changes no count, but the
+ * state must describe the run as it is after the decision.
+ */
+declare function selectDispatch(ready: readonly string[], state: Record<string, NodeState>, maxConcurrent: number): string[];
+
 /**
  * Run ONE node of a graph — through the real engine, not around it.
  *
@@ -199,12 +254,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
@@ -220,12 +301,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. */
@@ -243,8 +331,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>;
@@ -363,7 +451,10 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  *
  * `advance()`
  *   Ask the frontier what is unblocked, settle the skip cascade, and report the
- *   ready node ids. A queue adapter dispatches one job per id.
+ *   node ids that may be dispatched NOW. A queue adapter dispatches one job per
+ *   id. By default that is at most one id: a run holds one node at a time, and
+ *   the next node is handed out only when the one before it settles. See
+ *   {@link CoordinatorOptions.maxConcurrent}.
  *
  * `runNode()`
  *   Claim one node, replay the graph through the real engine fenced to that
@@ -387,6 +478,12 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  * A human gate returns `paused`. `runToCompletion` returns immediately when it
  * sees one — it does not spin, sleep or poll. The run is parked in the store,
  * the process is free, and a recorded answer is what starts the next job.
+ *
+ * A paused node keeps its dispatch slot, so under any finite `maxConcurrent`
+ * (serial, by default) a queue adapter's `advance()` hands out nothing
+ * alongside a gate while the person decides. Resuming releases the row — see
+ * `InMemoryClaimStore.release` — which frees the slot for the gate to run
+ * again.
  */
 
 /** What happened to one node. */
@@ -434,6 +531,19 @@ type CoordinatorOptions = {
     initialInputs?: Record<string, Record<string, unknown>>;
     retry?: RetryPolicy;
     onEvent?: (event: RunEvent) => void;
+    /**
+     * How many of this run's nodes may be HELD at once. Held means CLAIMED by a
+     * worker or PAUSED on a person: a paused gate keeps its slot.
+     *
+     * **Defaults to `1`: serial.** `advance()` hands out one node, and the next
+     * only once that one has settled, in the graph's declaration order.
+     *
+     * A positive integer raises the cap. `UNLIMITED_CONCURRENCY` (`0`) hands out
+     * the whole ready frontier at once, which is what every queued run did before
+     * this option existed. A negative, fractional or non-numeric value throws
+     * here, at construction.
+     */
+    maxConcurrent?: number;
 };
 declare class Coordinator {
     readonly graph: FlowGraph;
@@ -442,12 +552,21 @@ declare class Coordinator {
     readonly store: NodeClaimStore;
     readonly initialInputs: Record<string, Record<string, unknown>>;
     readonly retry: RetryPolicy;
+    /** The dispatch cap `advance()` applies. `0` is unlimited. */
+    readonly maxConcurrent: number;
     private readonly onEvent?;
     constructor(options: CoordinatorOptions);
     get runKey(): string;
     /**
      * Which nodes may be dispatched right now.
      *
+     * The ready frontier, cut to the run's {@link maxConcurrent} budget: the
+     * first `maxConcurrent - held` ready ids in declaration order, where `held`
+     * counts CLAIMED and PAUSED rows. Under the serial default that is at most one
+     * id, and none while a node is still running or a gate is waiting on a person.
+     * An empty result with work held is a throttled run, not a stalled one: the
+     * held node's settle is what calls this again.
+     *
      * Also settles the skip cascade, because a skip is a decision the frontier
      * just made and a second caller must not make it again.
      *
@@ -474,6 +593,12 @@ declare class Coordinator {
     /**
      * Drive the graph here, in this process, one node at a time.
      *
+     * It asks `advance()` exactly as a queue adapter does, so it runs nodes in the
+     * order a queued run under the same `maxConcurrent` would dispatch them. A run
+     * that finishes produces the same outputs under every limit. A run that stops
+     * on a pause or a failure can have run a different set of nodes before it
+     * stopped, because the order among nodes that are ready together differs.
+     *
      * 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.
      *
@@ -528,4 +653,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, UNLIMITED_CONCURRENCY, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo, selectDispatch };

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';
 
@@ -108,6 +108,10 @@ declare class InMemoryClaimStore implements NodeClaimStore {
     /**
      * Drop a paused node's claim so a recorded answer can re-run it.
      *
+     * A PAUSED row holds one of the run's dispatch slots (see `selectDispatch`),
+     * so this is also what frees the slot: until the row is released, a serial
+     * run's `advance()` hands out nothing, the gate included.
+     *
      * 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.
@@ -180,6 +184,57 @@ declare const Frontier: {
     settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<string[]>;
 };
 
+/**
+ * How many of ONE run's nodes may be held at once, and which ready nodes go next.
+ *
+ * ## Serial is the default
+ *
+ * A queued run hands a node to the queue only once the node before it has
+ * settled: one node of a run held at a time, in the graph's own declaration
+ * order. Parallel dispatch of a ready frontier is something a host ASKS for,
+ * with `maxConcurrent` on the {@link Coordinator}.
+ *
+ * | `maxConcurrent` | meaning |
+ * |---|---|
+ * | unset | **1**: serial |
+ * | `N >= 1` | up to N of the run's nodes held at once |
+ * | {@link UNLIMITED_CONCURRENCY} (`0`) | the whole ready frontier |
+ * | anything else | refused, by name |
+ *
+ * A negative number is refused rather than read as "unlimited". Under a serial
+ * default, a typo that silently turned a run parallel is the failure to avoid.
+ *
+ * ## Held means claimed OR paused
+ *
+ * A node parked on a person keeps its slot. A pause does not park the whole run
+ * in this runtime: `advance()` is called whenever any job settles, and without
+ * this rule it would hand out the gate's siblings while the person is still
+ * deciding.
+ *
+ * ## Measured against held work, not the batch
+ *
+ * Two nodes settling at once each trigger an `advance()` on a real queue. A cap
+ * applied to one batch would let each of them dispatch its own quota, so the
+ * budget is `maxConcurrent - held`, counted off the claim rows.
+ *
+ * This is the TypeScript member of a three-runtime contract. The
+ * `flow/durable-dispatch` conformance suite pins it, and names
+ * `fancy-flow-php`'s `DispatchLimit` and the Python runtime's
+ * `fancy_flow.durable.select_dispatch` as the other two implementations.
+ */
+
+/** Dispatch the whole ready frontier. Named so a host never writes a bare `0`. */
+declare const UNLIMITED_CONCURRENCY = 0;
+/**
+ * The ready nodes that may be dispatched now, in the order given.
+ *
+ * `ready` comes from `Frontier.compute`, in declaration order, and that order is
+ * kept: this slices, it never sorts. `state` must already include any skips the
+ * frontier just settled. Skips are never held, so that changes no count, but the
+ * state must describe the run as it is after the decision.
+ */
+declare function selectDispatch(ready: readonly string[], state: Record<string, NodeState>, maxConcurrent: number): string[];
+
 /**
  * Run ONE node of a graph — through the real engine, not around it.
  *
@@ -199,12 +254,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
@@ -220,12 +301,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. */
@@ -243,8 +331,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>;
@@ -363,7 +451,10 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  *
  * `advance()`
  *   Ask the frontier what is unblocked, settle the skip cascade, and report the
- *   ready node ids. A queue adapter dispatches one job per id.
+ *   node ids that may be dispatched NOW. A queue adapter dispatches one job per
+ *   id. By default that is at most one id: a run holds one node at a time, and
+ *   the next node is handed out only when the one before it settles. See
+ *   {@link CoordinatorOptions.maxConcurrent}.
  *
  * `runNode()`
  *   Claim one node, replay the graph through the real engine fenced to that
@@ -387,6 +478,12 @@ declare function durableApproval(submissions: Submissions): NodeExecutor;
  * A human gate returns `paused`. `runToCompletion` returns immediately when it
  * sees one — it does not spin, sleep or poll. The run is parked in the store,
  * the process is free, and a recorded answer is what starts the next job.
+ *
+ * A paused node keeps its dispatch slot, so under any finite `maxConcurrent`
+ * (serial, by default) a queue adapter's `advance()` hands out nothing
+ * alongside a gate while the person decides. Resuming releases the row — see
+ * `InMemoryClaimStore.release` — which frees the slot for the gate to run
+ * again.
  */
 
 /** What happened to one node. */
@@ -434,6 +531,19 @@ type CoordinatorOptions = {
     initialInputs?: Record<string, Record<string, unknown>>;
     retry?: RetryPolicy;
     onEvent?: (event: RunEvent) => void;
+    /**
+     * How many of this run's nodes may be HELD at once. Held means CLAIMED by a
+     * worker or PAUSED on a person: a paused gate keeps its slot.
+     *
+     * **Defaults to `1`: serial.** `advance()` hands out one node, and the next
+     * only once that one has settled, in the graph's declaration order.
+     *
+     * A positive integer raises the cap. `UNLIMITED_CONCURRENCY` (`0`) hands out
+     * the whole ready frontier at once, which is what every queued run did before
+     * this option existed. A negative, fractional or non-numeric value throws
+     * here, at construction.
+     */
+    maxConcurrent?: number;
 };
 declare class Coordinator {
     readonly graph: FlowGraph;
@@ -442,12 +552,21 @@ declare class Coordinator {
     readonly store: NodeClaimStore;
     readonly initialInputs: Record<string, Record<string, unknown>>;
     readonly retry: RetryPolicy;
+    /** The dispatch cap `advance()` applies. `0` is unlimited. */
+    readonly maxConcurrent: number;
     private readonly onEvent?;
     constructor(options: CoordinatorOptions);
     get runKey(): string;
     /**
      * Which nodes may be dispatched right now.
      *
+     * The ready frontier, cut to the run's {@link maxConcurrent} budget: the
+     * first `maxConcurrent - held` ready ids in declaration order, where `held`
+     * counts CLAIMED and PAUSED rows. Under the serial default that is at most one
+     * id, and none while a node is still running or a gate is waiting on a person.
+     * An empty result with work held is a throttled run, not a stalled one: the
+     * held node's settle is what calls this again.
+     *
      * Also settles the skip cascade, because a skip is a decision the frontier
      * just made and a second caller must not make it again.
      *
@@ -474,6 +593,12 @@ declare class Coordinator {
     /**
      * Drive the graph here, in this process, one node at a time.
      *
+     * It asks `advance()` exactly as a queue adapter does, so it runs nodes in the
+     * order a queued run under the same `maxConcurrent` would dispatch them. A run
+     * that finishes produces the same outputs under every limit. A run that stops
+     * on a pause or a failure can have run a different set of nodes before it
+     * stopped, because the order among nodes that are ready together differs.
+     *
      * 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.
      *
@@ -528,4 +653,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, UNLIMITED_CONCURRENCY, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo, selectDispatch };