automategraph 1.5.1 → 1.5.3

package/tests/edges.test.ts

@@ -0,0 +1,848 @@
+/* ============================================================
+ * TYPED EDGES & EXPLICIT ROUTING PACK (v1.3)
+ * ------------------------------------------------------------
+ * Pins the new `next` contract:
+ *
+ *   string                        → parallel edge (v1.0 behaviour)
+ *   { nextNode, result }          → exclusive, deep-equality matcher
+ *   { nextNode, test }            → exclusive, predicate matcher
+ *   { nextNode }                  → exclusive else edge
+ *   { nextNode, parallel: true }  → unconditional, out of the chain
+ *   return new Next(target, value)→ explicit route for the whole activation
+ *   context.goto(target) + return value → same, for void/imperative nodes
+ *
+ * Plus the three new lint codes and the validation rules.
+ * ============================================================ */
+
+import {
+  AutomateGraphError,
+  GraphExecutionEngine,
+  GraphValidationError,
+  Next,
+  deepEquals,
+  lintGraph,
+  normalizeNextEdges
+} from "../src/automategraph";
+
+import { capture, constNode, g, logCollector, node, sleep } from "./helpers";
+import { suite } from "./harness";
+
+const edges = suite("edges", "Typed edges & routing");
+
+const BIG = { timeoutMs: 20_000 };
+
+/* ------------------------------ 1. compatibility ------------------------------ */
+
+edges.t(
+  "string edges keep the v1.0 meaning: unconditional fan-out",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, { next: ["b", "c"] }),
+        constNode("b", "B"),
+        constNode("c", "C")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b") || !ran.includes("c")) throw new Error(ran.join(","));
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+
+    const normalized = normalizeNextEdges(definition.nodes.a.next);
+    if (normalized.length !== 2) throw new Error(`normalized=${normalized.length}`);
+    if (!normalized.every(edge => edge.parallel)) throw new Error("strings must normalize to parallel");
+
+    t.log("finding: `next: [\"b\",\"c\"]` normalizes to two parallel edges — every existing graph keeps its behaviour");
+  },
+  BIG
+);
+
+/* ------------------------------ 2. exclusive conditionals ------------------------------ */
+
+edges.t(
+  "result matches by deep equality and only the first matching edge fires",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            { result: 1, nextNode: "b" },
+            { result: 2, nextNode: "c" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B", { next: ["end"] }),
+        constNode("c", "C", { next: ["end"] }),
+        constNode("d", "D", { next: ["end"] }),
+        constNode("end", "END")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["end"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error("result: 1 did not route to b");
+    if (ran.includes("c") || ran.includes("d")) throw new Error(`extra branches ran: ${ran.join(",")}`);
+    if (report.outputs.end !== "END") throw new Error("end never ran");
+  },
+  BIG
+);
+
+edges.t(
+  "deep equality matches nested objects regardless of key order",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => ({ tags: ["x", "y"], id: 7 }), {
+          next: [
+            { result: { id: 7, tags: ["x", "y"] }, nextNode: "b" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error(`deep-equality match failed: ${ran.join(",")}`);
+    if (ran.includes("d")) throw new Error("else edge fired although a result matched");
+
+    t.log("finding: result uses structural equality (key order, nesting and array order aware)");
+  },
+  BIG
+);
+
+edges.t(
+  "result: NaN matches a NaN output (Object.is semantics)",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => Number.NaN, {
+          next: [
+            { result: Number.NaN, nextNode: "b" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error(`NaN did not match: ${ran.join(",")}`);
+    if (ran.includes("d")) throw new Error("else fired too");
+
+    if (!deepEquals(Number.NaN, Number.NaN)) throw new Error("deepEquals(NaN, NaN) is false");
+    if (deepEquals(0, -0)) throw new Error("deepEquals(0, -0) should be false (Object.is)");
+  },
+  BIG
+);
+
+edges.t(
+  "result: undefined matches an undefined output (presence, not truthiness)",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => undefined, {
+          next: [
+            { result: undefined, nextNode: "b" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error(`undefined did not match: ${ran.join(",")}`);
+    if (ran.includes("d")) throw new Error("else fired too");
+
+    t.log("finding: hasResult tracks key presence, so an undefined output is matchable");
+  },
+  BIG
+);
+
+edges.t(
+  "test predicate routes the activation",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 20, {
+          next: [
+            { test: value => typeof value === "number" && value > 10, nextNode: "b" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b") || ran.includes("d")) throw new Error(ran.join(","));
+  },
+  BIG
+);
+
+edges.t(
+  "two matching conditionals: declaration order wins",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            { test: () => true, nextNode: "b" },
+            { test: () => true, nextNode: "c" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("c", "C"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error("first matching edge did not win");
+    if (ran.includes("c") || ran.includes("d")) throw new Error(`later edges fired: ${ran.join(",")}`);
+  },
+  BIG
+);
+
+edges.t(
+  "result + test on one edge must both pass (AND)",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 5, {
+          next: [
+            { result: 5, test: value => typeof value === "number" && value > 10, nextNode: "b" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (ran.includes("b")) throw new Error("AND failed: b ran although test() was false");
+    if (!ran.includes("d")) throw new Error("else edge should have fired");
+  },
+  BIG
+);
+
+edges.t(
+  "the else edge (no matcher) fires when nothing earlier matched",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 3, {
+          next: [
+            { result: 1, nextNode: "b" },
+            { test: value => value === 2, nextNode: "c" },
+            { nextNode: "d" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("c", "C"),
+        constNode("d", "D")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c", "d"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("d") || ran.includes("b") || ran.includes("c")) {
+      throw new Error(ran.join(","));
+    }
+  },
+  BIG
+);
+
+edges.t(
+  "no match is silent: nothing is scheduled, no routing error is recorded",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 42, {
+          next: [
+            { result: 1, nextNode: "b" },
+            { test: value => value === 2, nextNode: "c" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("c", "C")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+
+    if (report.results.length !== 1) throw new Error(`results=${report.results.length}`);
+    if (report.status !== "FAILED") throw new Error(report.status);
+    if (report.errors.length !== 1) throw new Error(`errors=${report.errors.length}`);
+    if (report.errors[0].code !== "GRAPH_TERMINAL_NOT_REACHED") throw new Error(report.errors[0].code);
+
+    t.log("finding: an unmatched conditional chain is silent by design (no NO_EDGE_MATCHED error)");
+  },
+  BIG
+);
+
+/* ------------------------------ 3. parallel edges ------------------------------ */
+
+edges.t(
+  "parallel edges fire alongside the winning conditional",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            { result: 1, nextNode: "b" },
+            "audit"
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("audit", "AUDITED")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "audit"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error("conditional branch missing");
+    if (!ran.includes("audit")) throw new Error("parallel edge was suppressed by the conditional");
+  },
+  BIG
+);
+
+edges.t(
+  "a parallel edge is never blocked, even after a conditional match",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 7, {
+          next: [
+            { test: () => true, nextNode: "b" },
+            "audit",
+            { test: () => true, nextNode: "c" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("c", "C"),
+        constNode("audit", "AUDITED")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c", "audit"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error("first conditional must win");
+    if (!ran.includes("audit")) throw new Error("parallel edge blocked by exclusivity");
+    if (ran.includes("c")) throw new Error("second conditional should be skipped");
+  },
+  BIG
+);
+
+edges.t(
+  "a parallel edge with a matcher is still unconditional (matcher ignored, lint warns)",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            "audit",
+            { result: 999, parallel: true, nextNode: "b" }
+          ]
+        }),
+        constNode("b", "B"),
+        constNode("audit", "AUDITED")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "audit"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b") || !ran.includes("audit")) throw new Error(ran.join(","));
+
+    const issues = lintGraph(definition);
+    const warning = issues.find(issue => issue.code === "PARALLEL_EDGE_MATCHER_IGNORED");
+    if (!warning) throw new Error(`lint codes: ${issues.map(i => i.code).join(",")}`);
+    if (warning.level !== "warn") throw new Error(warning.level);
+    if (warning.nodeId !== "a") throw new Error(String(warning.nodeId));
+  },
+  BIG
+);
+
+/* ------------------------------ 4. explicit routing ------------------------------ */
+
+edges.t(
+  "returning new Next(target, value) routes and successors see the unwrapped value",
+  async t => {
+    let seen: unknown;
+    const definition = g({
+      nodes: [
+        node("a", () => new Next("b", { k: 2 })),
+        node("b", context => { seen = context.outputs.a; return "B"; })
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b"]
+    });
+
+    const engine = new GraphExecutionEngine(definition);
+    const succeeded = capture(engine, ["node.succeeded"]);
+    const report = await engine.run();
+
+    if (report.outputs.a === undefined) throw new Error("a produced no output");
+    if (!deepEquals(seen, { k: 2 })) throw new Error(`successor saw ${JSON.stringify(seen)}`);
+    if (report.outputs.b !== "B") throw new Error("b did not run");
+
+    const payload = succeeded.find(entry => (entry.payload as { nodeId: string }).nodeId === "a")!
+      .payload as { output: unknown; route?: { nextNode: string; via: string } };
+
+    if (!deepEquals(payload.output, { k: 2 })) throw new Error("event output was not unwrapped");
+    if (payload.route?.nextNode !== "b" || payload.route.via !== "next-class") {
+      throw new Error(`route payload wrong: ${JSON.stringify(payload.route)}`);
+    }
+
+    t.log("finding: Next carries both destination and payload — successors and matchers see the payload");
+  },
+  BIG
+);
+
+edges.t(
+  "context.goto(target) + return value routes for void/imperative nodes",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", context => {
+          context.goto("f");
+          return "payload"; // stays a's output
+        }),
+        constNode("f", "F")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["f"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+
+    if (report.outputs.a !== "payload") throw new Error(String(report.outputs.a));
+    if (report.outputs.f !== "F") throw new Error("goto target did not run");
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+  },
+  BIG
+);
+
+edges.t(
+  "a void node can route with goto alone",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("b", context => { context.goto("f"); return undefined; }),
+        constNode("f", "F")
+      ],
+      entryNodes: ["b"],
+      terminalNodes: ["f"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    if (report.outputs.f !== "F") throw new Error("f never ran");
+    if (report.outputs.b !== undefined) throw new Error("void node recorded an output");
+  },
+  BIG
+);
+
+edges.t(
+  "an explicit route replaces the whole edge list, parallel edges included",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => new Next("c", 1), {
+          next: ["audit", { result: 1, nextNode: "b" }]
+        }),
+        constNode("b", "B"),
+        constNode("c", "C"),
+        constNode("audit", "AUDITED")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c", "audit"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("c")) throw new Error("explicit target did not run");
+    if (ran.includes("b") || ran.includes("audit")) {
+      throw new Error(`edge list still fired: ${ran.join(",")}`);
+    }
+
+    t.log("finding: an explicit route is authoritative — declared edges (and parallel ones) are ignored");
+  },
+  BIG
+);
+
+edges.t(
+  "return new Next wins over context.goto when both are used",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", context => {
+          context.goto("c");
+          return new Next("b", 1);
+        }),
+        constNode("b", "B"),
+        constNode("c", "C")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["b", "c"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (!ran.includes("b")) throw new Error("Next should take precedence");
+    if (ran.includes("c")) throw new Error(`goto also fired: ${ran.join(",")}`);
+  },
+  BIG
+);
+
+edges.t(
+  "goto works per attempt: the route is taken by the successful attempt",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", context => {
+          if (context.attempt === 1) throw new Error("transient");
+          context.goto("f");
+          return `ok-after-${context.attempt}`;
+        }, { retry: { maxAttempts: 2, delayMs: 5 }, errorPolicy: "RETRY", next: [] }),
+        constNode("f", "F")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["f"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const result = report.results.find(entry => entry.nodeId === "a")!;
+
+    if (result.attempt !== 2) throw new Error(`attempt=${result.attempt}`);
+    if (report.outputs.a !== "ok-after-2") throw new Error(String(report.outputs.a));
+    if (report.outputs.f !== "F") throw new Error("f never ran");
+  },
+  BIG
+);
+
+edges.t(
+  "routing to an unknown node records INVALID_GOTO_TARGET and schedules nothing",
+  async t => {
+    for (const [label, definition] of [
+      ["goto", g({
+        nodes: [
+          node("a", context => { context.goto("nowhere"); return 1; }),
+          constNode("end", "END")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      })],
+      ["Next", g({
+        nodes: [
+          node("a", () => new Next("nowhere", 1)),
+          constNode("end", "END")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      })]
+    ] as const) {
+      const report = await new GraphExecutionEngine(definition).run();
+      const error = report.errors.find(entry => entry.code === "INVALID_GOTO_TARGET");
+
+      if (!error) throw new Error(`[${label}] missing INVALID_GOTO_TARGET`);
+      if (error.handled) throw new Error(`[${label}] routing bug must stay unhandled`);
+      if (report.results.length !== 1) throw new Error(`[${label}] successors were scheduled`);
+      if (report.status !== "FAILED") throw new Error(`[${label}] ${report.status}`);
+      if ((error.details as { to: string }).to !== "nowhere") throw new Error(`[${label}] details`);
+    }
+  },
+  BIG
+);
+
+edges.t(
+  "new Next with an empty target throws INVALID_NEXT_TARGET immediately",
+  () => {
+    try {
+      new Next("   ", 1);
+      throw new Error("expected throw");
+    } catch (error) {
+      if (!(error instanceof AutomateGraphError)) throw error;
+      if (error.code !== "INVALID_NEXT_TARGET") throw new Error(error.code);
+    }
+  }
+);
+
+/* ------------------------------ 5. terminals & lint ------------------------------ */
+
+edges.t(
+  "a terminal node ignores its edges and its routing, and lint warns about it",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => new Next("b", 1), { next: ["b"] }),
+        constNode("b", "B")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["a", "b"] // "a" is terminal on purpose
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+
+    if (ran.includes("b")) throw new Error("terminal node routed anyway");
+    if (!report.logicallyCompleted) throw new Error("terminal did not latch completion");
+
+    const issues = lintGraph(definition);
+    const warning = issues.find(issue => issue.code === "TERMINAL_EDGE_IGNORED");
+    if (!warning) throw new Error(`lint codes: ${issues.map(i => i.code).join(",")}`);
+    if (warning.level !== "warn" || warning.nodeId !== "a") throw new Error(JSON.stringify(warning));
+
+    t.log("finding: terminal detection happens before routing — a terminal node never schedules successors");
+  },
+  BIG
+);
+
+edges.t(
+  "lint flags an exclusive edge declared after an else edge as unreachable",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            { nextNode: "d" },                  // else: always matches
+            { result: 1, nextNode: "b" }        // dead
+          ]
+        }),
+        constNode("b", "B", { next: ["end"] }),
+        constNode("d", "D", { next: ["end"] }),
+        constNode("end", "END")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["end"]
+    });
+
+    const issues = lintGraph(definition);
+    const dead = issues.find(issue => issue.code === "UNREACHABLE_EDGE");
+
+    if (!dead) throw new Error(`lint codes: ${issues.map(i => i.code).join(",")}`);
+    if (dead.level !== "error") throw new Error(dead.level);
+    if (dead.nodeId !== "a" || !dead.message.includes('"b"')) throw new Error(dead.message);
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const ran = report.results.map(result => result.nodeId);
+    if (!ran.includes("d") || ran.includes("b")) throw new Error(ran.join(","));
+
+    t.log("finding: an else edge shadows every exclusive edge declared after it — runtime agrees with lint");
+  },
+  BIG
+);
+
+/* ------------------------------ 6. validation ------------------------------ */
+
+edges.t(
+  "malformed edge entries are rejected at construction time",
+  () => {
+    const cases: Array<[unknown, RegExp]> = [
+      [42, /malformed next edge/],
+      [{ nextNode: "" }, /non-empty string/],
+      // v1.3 shape rule, extended in v1.4: a STRING test is a registry
+      // name, so only a non-callable, non-string value is malformed here.
+      [{ nextNode: "b", test: 42 }, /test must be a function/],
+      [{ nextNode: "b", test: "not a name!" }, /invalid test function name/],
+      [{ nextNode: "b", parallel: "yes" }, /parallel flag must be a boolean/],
+      [{ nextNode: "ghost" }, /unknown next Node "ghost"/],
+      ["", /empty next Node reference/]
+    ];
+
+    for (const [entry, pattern] of cases) {
+      try {
+        new GraphExecutionEngine(g({
+          nodes: [
+            node("a", () => 1, { next: [entry as never] }),
+            constNode("b", "B")
+          ],
+          entryNodes: ["a"],
+          terminalNodes: ["b"]
+        }));
+        throw new Error(`expected throw for ${JSON.stringify(entry)}`);
+      } catch (error) {
+        if (!(error instanceof GraphValidationError)) throw error;
+        if (!pattern.test(error.message)) {
+          throw new Error(`got "${error.message}", expected ${pattern}`);
+        }
+      }
+    }
+  }
+);
+
+/* ------------------------------ 7. the payoff: one execution ------------------------------ */
+
+edges.t(
+  "the a → b/c/d/e/f picture runs as ONE execution — the router is no longer needed",
+  async t => {
+    type Seed = 1 | 2 | 3 | "throw" | "retry";
+
+    const build = (seed: Seed) => g({
+      id: "branching-edges",
+      version: "1.3.0",
+      nodes: [
+        node("a", context => {
+          if (seed === "throw") throw new Error("a: upstream exploded");
+          if (seed === "retry" && context.attempt === 1) throw new Error("a: transient");
+
+          const result = seed === "retry" ? 2 : seed;
+
+          // "on retry → f": only the node knows the attempt number
+          if (context.attempt > 1) return new Next("f", result);
+
+          return result;
+        }, {
+          next: [
+            { result: 1, nextNode: "b" },
+            { test: value => typeof value === "number" && value === 2, nextNode: "c" },
+            { nextNode: "d" }
+          ],
+          onThrow: "e",
+          retry: { maxAttempts: 2, delayMs: 5 },
+          errorPolicy: "RETRY"
+        }),
+
+        // b returns void and forces f; the declared edge keeps f reachable
+        // for static linting (runtime routing wins, the edge stays a fallback)
+        node("b", context => {
+          context.goto("f");
+          return undefined;
+        }, { next: ["f"] }),
+
+        constNode("c", "C"),
+        constNode("d", "D"),
+        constNode("e", "E"),
+        constNode("f", "F")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["c", "d", "e", "f"],
+      completionPolicy: "FIRST_TERMINAL"
+    });
+
+    const expectations: Array<[Seed, string[], number]> = [
+      [1, ["a", "b", "f"], 1],
+      [2, ["a", "c"], 1],
+      [3, ["a", "d"], 1],
+      ["throw", ["a", "e"], 2],
+      ["retry", ["a", "f"], 2]
+    ];
+
+    for (const [seed, path, attempts] of expectations) {
+      const engine = new GraphExecutionEngine(build(seed), { lint: "error" });
+      const captured = capture(engine, ["activation.dropped"]);
+
+      let flaky = false;
+      engine.events.on("node.failed", () => { flaky = true; });
+
+      const report = await engine.run();
+      const ran = report.results.map(result => result.nodeId).join(",");
+      const a = report.results.find(result => result.nodeId === "a")!;
+
+      if (ran !== path.join(",")) throw new Error(`seed ${JSON.stringify(seed)}: ${ran} ≠ ${path.join(",")}`);
+      if (report.status !== "COMPLETED") throw new Error(`seed ${seed}: ${report.status}`);
+      if (a.attempt !== attempts) throw new Error(`seed ${seed}: attempt=${a.attempt}`);
+      if (captured.length !== 0) throw new Error(`seed ${seed}: work was dropped`);
+
+      t.log(`seed ${JSON.stringify(seed)}`, `${ran}  (attempts ${a.attempt})`);
+    }
+
+    t.log(
+      "finding: with typed edges the whole picture is ONE execution and lint-clean — " +
+      "no router, no gate, no DRAIN policy needed"
+    );
+  },
+  BIG
+);
+
+edges.t(
+  "lint is clean for the payoff graph (routes declared, no dead edges)",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("a", () => 1, {
+          next: [
+            { result: 1, nextNode: "b" },
+            { test: () => false, nextNode: "c" },
+            { nextNode: "d" }
+          ],
+          onThrow: "e"
+        }),
+        node("b", context => { context.goto("f"); return undefined; }, { next: ["f"] }),
+        constNode("c", "C", { next: ["f"] }),
+        constNode("d", "D", { next: ["f"] }),
+        constNode("e", "E", { next: ["f"] }),
+        constNode("f", "F")
+      ],
+      entryNodes: ["a"],
+      terminalNodes: ["f"]
+    });
+
+    const issues = lintGraph(definition);
+    if (issues.length !== 0) {
+      throw new Error(`lint issues: ${issues.map(issue => `${issue.code}@${issue.nodeId}`).join(",")}`);
+    }
+
+    const engine = new GraphExecutionEngine(definition, { lint: "error" });
+    const report = await engine.run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (!report.results.some(result => result.nodeId === "f")) throw new Error("f never ran");
+
+    t.log("graph linted clean and ran under lint: \"error\"");
+  },
+  BIG
+);