automategraph 1.5.1 → 1.5.3

package/tests/registry.test.ts

@@ -0,0 +1,1134 @@
+/* ============================================================
+ * FUNCTION REGISTRY PACK (v1.4)
+ * ------------------------------------------------------------
+ * <name, function> tables and lazy resolution:
+ *
+ *   engine registry   { functions }  +  engine.registerFunction()
+ *   graph registry    GraphDefinition.functions   (wins on collision)
+ *
+ *   NodeDefinition.run  = function | "registeredName"
+ *   NextEdge.test       = function | "registeredName"
+ *
+ * Semantics under test:
+ *   • resolution happens at EVAL time — a name missing at construction
+ *     may still be registered before the node runs
+ *   • a missing name is UNKNOWN_FUNCTION: handled = false, PERMANENT
+ *     (never retried, never routed through onThrow/fallback)
+ *   • an unresolvable edge test records the error ONCE per node+name,
+ *     never matches, and lets the rest of the chain evaluate
+ *   • observability: `fn` on results and events, { fingerprint, names }
+ *     on graph.ready, the report and every checkpoint
+ * ============================================================ */
+
+import {
+  FunctionRegistry,
+  GraphExecutionEngine,
+  GraphValidationError,
+  Next,
+  NodeContext,
+  RegisteredFunction,
+  createFunctionRegistry,
+  edgeTests,
+  nodeFunctions
+} from "../src/automategraph";
+
+import {
+  BIG,
+  SpyStorage,
+  capture,
+  constNode,
+  g,
+  logCollector,
+  node,
+  sleep
+} from "./helpers";
+import { suite } from "./harness";
+
+const registry = suite("registry", "Function registry");
+
+/* ------------------------------ assertion helpers ------------------------------ */
+
+function show(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "function") return "function";
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function ok(condition: unknown, label: string): void {
+  if (!condition) throw new Error(label);
+}
+
+function eq(actual: unknown, expected: unknown, label: string): void {
+  if (actual !== expected) {
+    throw new Error(`${label}: expected ${show(expected)}, got ${show(actual)}`);
+  }
+}
+
+function neq(actual: unknown, expected: unknown, label: string): void {
+  if (actual === expected) {
+    throw new Error(`${label}: expected a value different from ${show(expected)}`);
+  }
+}
+
+function stable(value: unknown): string {
+  return JSON.stringify(sortKeys(value)) ?? "undefined";
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .sort()
+        .map(key => [key, sortKeys((value as Record<string, unknown>)[key])])
+    );
+  }
+  return value;
+}
+
+function deepEq(actual: unknown, expected: unknown, label: string): void {
+  const a = stable(actual);
+  const b = stable(expected);
+
+  if (a !== b) throw new Error(`${label}: expected ${b}, got ${a}`);
+}
+
+/* ------------------------------ 1. resolution ------------------------------ */
+
+registry.t(
+  "a node whose run is a registered NAME executes that function",
+  async t => {
+    const calls: string[] = [];
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", "greet", { next: ["end"] }),
+          constNode("end", "done")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      {
+        functions: {
+          greet: (context: NodeContext) => {
+            calls.push(`${context.nodeId}@${context.attempt}`);
+            return "hello";
+          }
+        }
+      }
+    );
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    eq(calls.join(","), "a@1", "the registered function ran once");
+    eq(report.outputs.a, "hello", "output");
+    eq(report.results[0].fn, "greet", "NodeResult.fn");
+
+    t.log("finding: report.results[i].fn — not report.results[i].output — is the audit link to the registered source");
+  },
+  BIG
+);
+
+registry.t(
+  "a graph-local function overrides the engine's shared entry",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "shared", { next: ["end"] }), constNode("end", "done")],
+        entryNodes: ["a"],
+        terminalNodes: ["end"],
+        functions: { shared: () => "graph-local" }
+      }),
+      { functions: { shared: () => "engine-level" } }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, "graph-local", "graph entries win on collision");
+    eq(report.status, "COMPLETED", "status");
+    deepEq(report.registry?.names, ["shared"], "one merged table");
+  },
+  BIG
+);
+
+registry.t(
+  "graph-local functions work with no engine registry at all",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "local", { next: ["end"] }), constNode("end", "done")],
+        entryNodes: ["a"],
+        terminalNodes: ["end"],
+        functions: { local: () => 41 + 1 }
+      })
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, 42, "output");
+    deepEq(report.registry?.names, ["local"], "the graph table is the registry");
+  },
+  BIG
+);
+
+registry.t(
+  "registerFunction() after construction is honoured (resolution is lazy)",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "late", { next: ["end"] }), constNode("end", "done")],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      })
+    );
+
+    eq(engine.registry.names.length, 0, "empty before registering");
+
+    const chained = engine.registerFunction("late", () => "registered later");
+
+    ok(chained === engine, "registerFunction returns the engine");
+    eq(engine.registry.names.join(","), "late", "the registry view is invalidated");
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, "registered later", "late registration is used");
+    ok(
+      (report.registry?.fingerprint ?? "").startsWith("fnr1:1:"),
+      `fingerprint format: ${report.registry?.fingerprint}`
+    );
+
+    t.log("finding: an engine with an empty registry reports no `registry` field, but registerFunction() makes it appear");
+  },
+  BIG
+);
+
+registry.t(
+  "inline functions and registered names coexist in one graph",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => "inline", { next: ["b"] }),
+          node("b", "named", { next: ["c"] }),
+          node("c", () => "inline again")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["c"]
+      }),
+      { functions: { named: () => "from registry" } }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, "inline", "a");
+    eq(report.outputs.b, "from registry", "b");
+    eq(report.outputs.c, "inline again", "c");
+    eq(report.results[0].fn, undefined, "inline activation has no fn");
+    eq(report.results[1].fn, "named", "named activation has fn");
+    eq(report.results[2].fn, undefined, "inline activation has no fn");
+  },
+  BIG
+);
+
+registry.t(
+  "a registered node function receives a full NodeContext",
+  async t => {
+    const seen: string[] = [];
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          constNode("a", "A", { next: ["b"] }),
+          node("b", "inspect", { next: ["end"] }),
+          constNode("end", "done")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      {
+        functions: {
+          inspect: (context: NodeContext) => {
+            seen.push(
+              [
+                context.nodeId,
+                context.graphId,
+                context.attempt,
+                context.outputs.a,
+                context.signal.aborted
+              ].join("|")
+            );
+
+            return context.outputs.a;
+          }
+        }
+      }
+    );
+
+    await engine.run();
+
+    eq(seen.join(","), "b|test-graph|1|A|false", "context fields");
+  },
+  BIG
+);
+
+registry.t(
+  "a registered async function is awaited",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "slow", { next: ["end"] }), constNode("end", "done")],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      {
+        functions: {
+          slow: async () => {
+            await sleep(5);
+            return "awaited";
+          }
+        }
+      }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, "awaited", "output");
+    eq(report.status, "COMPLETED", "status");
+  },
+  BIG
+);
+
+registry.t(
+  "a registered node can route explicitly with Next and with context.goto",
+  async t => {
+    const build = () =>
+      g({
+        nodes: [
+          node("a", "router", { next: ["b"] }),
+          node("b", "voidJump", { next: ["c"] }),
+          constNode("c", "C"),
+          constNode("end", "E")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      });
+
+    const engine = new GraphExecutionEngine(build(), {
+      functions: {
+        /* a registered function is real code: it can build a Next */
+        router: () => new Next("end", "routed-by-name"),
+        voidJump: (context: NodeContext) => {
+          context.goto("c");
+          return undefined;
+        }
+      }
+    });
+
+    const captured = capture(engine, ["node.succeeded"]);
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    deepEq(
+      report.results.map(result => `${result.nodeId}:${result.fn ?? "-"}`),
+      ["a:router", "end:-"],
+      "names recorded per activation"
+    );
+    eq(
+      report.outputs.a,
+      "routed-by-name",
+      "the Next value is recorded as the ROUTER's output (matchers see it)"
+    );
+    eq(report.outputs.end, "E", "the target node still runs its own function");
+    eq(
+      (captured[0].payload as { route?: { via: string } }).route?.via,
+      "next-class",
+      "the route is reported for a named function too"
+    );
+
+    /* the goto variant, in its own engine */
+    const gotoEngine = new GraphExecutionEngine(build(), {
+      functions: {
+        router: () => "goes-to-b",
+        voidJump: (context: NodeContext) => {
+          context.goto("end");
+          return undefined;
+        }
+      }
+    });
+
+    const gotoReport = await gotoEngine.run();
+
+    deepEq(
+      gotoReport.results.map(result => result.nodeId),
+      ["a", "b", "end"],
+      "a registered void node can jump with goto"
+    );
+    eq(gotoReport.outputs.end, "E", "the jump reached the terminal");
+
+    t.log("finding: `new Next(target, value)` sets the ROUTER's output to `value` (that is what edge matchers and context.outputs see); the target node still executes its own function");
+  },
+  BIG
+);
+
+registry.t(
+  "timeouts and retries apply to registered functions exactly as to inline ones",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", "slow", { next: ["end"], timeoutMs: 20 }),
+          constNode("end", "done")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      {
+        functions: {
+          slow: async () => {
+            await sleep(150);
+            return "too late";
+          }
+        }
+      }
+    );
+
+    const report = await engine.run();
+
+    eq(report.results[0].status, "TIMED_OUT", "status");
+    eq(report.results[0].fn, "slow", "fn is recorded on a failed result too");
+    eq(report.errors[0].code, "NODE_TIMEOUT", "error code");
+    eq(report.status, "FAILED", "no terminal reached");
+  },
+  BIG
+);
+
+/* ------------------------------ 2. missing names ------------------------------ */
+
+registry.t(
+  "a missing run name records UNKNOWN_FUNCTION (unhandled) and schedules nothing",
+  async t => {
+    const log = logCollector();
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "ghost", { next: ["end"] }), constNode("end", "done")],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      { onLog: log.onLog }
+    );
+
+    const captured = capture(engine, [
+      "node.started",
+      "node.succeeded",
+      "node.failed"
+    ]);
+
+    const report = await engine.run();
+
+    eq(report.status, "FAILED", "status");
+    eq(report.results.length, 1, "only the failing activation exists");
+
+    const failure = report.results[0];
+
+    eq(failure.nodeId, "a", "nodeId");
+    eq(failure.status, "FAILED", "status");
+    eq(failure.attempt, 1, "attempt");
+    eq(failure.fn, "ghost", "fn");
+
+    const error = report.errors[0];
+
+    eq(error.code, "UNKNOWN_FUNCTION", "code");
+    eq(error.handled, false, "handled");
+    eq(error.nodeId, "a", "nodeId");
+    deepEq(
+      (error.details as { available: string[] }).available,
+      [],
+      "the error carries the available names"
+    );
+
+    deepEq(
+      captured.map(entry => entry.event),
+      ["node.started", "node.failed"],
+      "the activation starts and fails — never succeeds"
+    );
+    eq(
+      (captured[0].payload as { fn?: string }).fn,
+      "ghost",
+      "node.started names the function"
+    );
+    eq((captured[1].payload as { fn?: string }).fn, "ghost", "node.failed too");
+    ok(
+      log.lines.some(line => line.message.includes("unregistered function")),
+      "the defect is logged"
+    );
+  },
+  BIG
+);
+
+registry.t(
+  "a missing run name is PERMANENT: no retry, no onThrow, no fallback",
+  async t => {
+    const ran: string[] = [];
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", "ghost", {
+            onThrow: "rescue",
+            fallback: "rescue",
+            retry: { maxAttempts: 3, delayMs: 1 },
+            errorPolicy: "RETRY"
+          }),
+          node("rescue", () => {
+            ran.push("rescue");
+            return "rescued";
+          })
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["rescue"]
+      })
+    );
+
+    const report = await engine.run();
+
+    eq(report.results[0].attempt, 1, "UNKNOWN_FUNCTION is not retried");
+    eq(
+      report.errors.filter(error => error.code === "UNKNOWN_FUNCTION").length,
+      1,
+      "exactly one error record"
+    );
+    eq(ran.length, 0, "neither onThrow nor fallback ran");
+    eq(report.results.length, 1, "nothing was scheduled");
+    eq(report.status, "FAILED", "status");
+
+    t.log("finding: retry/onThrow/fallback are error RECOVERY; a name that was never registered is a wiring defect, so the engine refuses to recover from it");
+  },
+  BIG
+);
+
+registry.t(
+  "a missing run name ignores FALLBACK policy as well",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "ghost", { fallback: "rescue" }), constNode("rescue", "rescued")],
+        entryNodes: ["a"],
+        terminalNodes: ["rescue"],
+        errorPolicy: "FALLBACK"
+      })
+    );
+
+    const report = await engine.run();
+
+    eq(report.errors[0].code, "UNKNOWN_FUNCTION", "code");
+    eq(report.errors[0].handled, false, "handled");
+    eq(report.results.length, 1, "the fallback target was not activated");
+    eq(report.status, "FAILED", "status");
+  },
+  BIG
+);
+
+registry.t(
+  "registering the missing name mid-run lets the next activation succeed",
+  async t => {
+    const engine: GraphExecutionEngine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", "first", { next: ["b"] }),
+          node("b", "second", { next: ["end"] }),
+          constNode("end", "done")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["end"]
+      }),
+      {
+        functions: {
+          first: () => {
+            /* `second` has not been resolved yet — resolution is per eval */
+            engine.registerFunction("second", () => "registered in flight");
+            return "A";
+          }
+        }
+      }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.b, "registered in flight", "output");
+    eq(report.registry?.names.join(","), "first,second", "names");
+    eq(report.status, "COMPLETED", "status");
+  },
+  BIG
+);
+
+/* ------------------------------ 3. edge tests by name ------------------------------ */
+
+registry.t(
+  "a named edge test decides the branch, and result + test still AND",
+  async t => {
+    const parts = (test: string) => [
+      node("a", () => "high", {
+        next: [
+          { test, nextNode: "yes" },
+          { nextNode: "no" }
+        ]
+      }),
+      constNode("yes", "YES"),
+      constNode("no", "NO")
+    ];
+
+    const yes = await new GraphExecutionEngine(
+      g({
+        nodes: parts("isHigh"),
+        entryNodes: ["a"],
+        terminalNodes: ["yes", "no"]
+      }),
+      { functions: { isHigh: (value: unknown) => value === "high" } }
+    ).run();
+
+    eq(yes.outputs.yes, "YES", "the named test matched");
+    eq(yes.results.length, 2, "one branch only");
+
+    const and = await new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => "low", {
+            next: [
+              { result: "high", test: "isLow", nextNode: "yes" },
+              { nextNode: "no" }
+            ]
+          }),
+          constNode("yes", "YES"),
+          constNode("no", "NO")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["yes", "no"]
+      }),
+      { functions: { isLow: (value: unknown) => value === "low" } }
+    ).run();
+
+    eq(and.outputs.no, "NO", "result must AND with the named test");
+    eq(and.results.length, 2, "one branch only");
+  },
+  BIG
+);
+
+registry.t(
+  "inline and named tests mix in one chain, in declaration order",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => 7, {
+            next: [
+              { test: "isSeven", nextNode: "named" },
+              { test: (value: unknown) => value === 7, nextNode: "inline" },
+              { nextNode: "else" }
+            ]
+          }),
+          constNode("named", "NAMED"),
+          constNode("inline", "INLINE"),
+          constNode("else", "ELSE")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["named", "inline", "else"]
+      }),
+      { functions: { isSeven: (value: unknown) => value === 7 } }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.named, "NAMED", "first match wins");
+    eq(report.results.length, 2, "one branch only");
+  },
+  BIG
+);
+
+registry.t(
+  "an unresolvable edge test never matches, is recorded once, and lets the else edge run",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => "value", {
+            next: [
+              { test: "missing", nextNode: "never" },
+              { nextNode: "else" }
+            ]
+          }),
+          constNode("never", "NEVER"),
+          constNode("else", "ELSE")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["never", "else"]
+      })
+    );
+
+    const report = await engine.run();
+
+    const unknown = report.errors.filter(
+      error => error.code === "UNKNOWN_FUNCTION"
+    );
+
+    eq(unknown.length, 1, "one record for the missing test");
+    eq(unknown[0].handled, false, "handled");
+    eq(
+      (unknown[0].details as { kind: string }).kind,
+      "test",
+      "the record identifies the position"
+    );
+    eq(unknown[0].nodeId, "a", "the defect is attributed to the source node");
+
+    eq(report.outputs.else, "ELSE", "the else edge still fires");
+    eq(report.results.length, 2, "the unresolvable edge scheduled nothing");
+    eq(report.status, "FAILED", "the unhandled defect fails the run");
+
+    t.log("finding: an unresolvable test is loud but not fatal to ROUTING — the rest of the chain still evaluates; the run itself settles FAILED because the error stays unhandled (terminal-reached + unhandled error = FAILED, as in v1.2)");
+  },
+  BIG
+);
+
+registry.t(
+  "a repeated evaluation reports a missing test only once (retry path)",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        id: "retry-with-missing-test",
+        nodes: [
+          node("a", "looper", {
+            next: [{ test: "missing", nextNode: "b" }, { nextNode: "b" }],
+            retry: { maxAttempts: 3 },
+            errorPolicy: "RETRY"
+          }),
+          constNode("b", "B")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["b"]
+      }),
+      {
+        functions: {
+          looper: (context: NodeContext) => {
+            if (context.attempt === 1) throw new Error("transient");
+            return "ok";
+          }
+        }
+      }
+    );
+
+    const report = await engine.run();
+
+    eq(report.results[0].attempt, 2, "the node really retried");
+    eq(
+      report.errors.filter(error => error.code === "UNKNOWN_FUNCTION").length,
+      1,
+      "still exactly one record for node a + missing"
+    );
+    eq(
+      report.status,
+      "FAILED",
+      "the retry recovered, but the unhandled defect still fails the run"
+    );
+  },
+  BIG
+);
+
+registry.t(
+  "lint treats a NAMED test as conditional — no false UNREACHABLE_EDGE",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => "x", {
+            next: [
+              { test: "isHigh", nextNode: "b" },
+              { nextNode: "c" }
+            ]
+          }),
+          constNode("b", "B"),
+          constNode("c", "C")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["b", "c"]
+      }),
+      { functions: { isHigh: () => false }, lint: "error" }
+    );
+
+    const report = await engine.run();
+
+    deepEq(report.lintIssues, [], "no lint issue for a named matcher");
+    eq(report.status, "COMPLETED", "status");
+    eq(report.outputs.c, "C", "the else edge is reachable");
+
+    t.log("finding: regression guard — before edgeHasMatcher() was shared, a named test looked like an else edge to the lint and every later edge was reported UNREACHABLE_EDGE");
+  },
+  BIG
+);
+
+registry.t(
+  "a PARALLEL edge with a named test still warns PARALLEL_EDGE_MATCHER_IGNORED",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", () => "x", {
+            next: [
+              { test: "isHigh", nextNode: "b", parallel: true },
+              { nextNode: "c" }
+            ]
+          }),
+          constNode("b", "B"),
+          constNode("c", "C")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["b", "c"],
+        completionPolicy: "DRAIN"
+      }),
+      { functions: { isHigh: () => false }, lint: "warn" }
+    );
+
+    const report = await engine.run();
+    const codes = report.lintIssues.map(issue => issue.code);
+
+    ok(codes.includes("PARALLEL_EDGE_MATCHER_IGNORED"), codes.join(","));
+    eq(report.outputs.b, "B", "the parallel edge fires despite the false test");
+    eq(report.outputs.c, "C", "the exclusive chain still ran");
+  },
+  BIG
+);
+
+/* ------------------------------ 4. observability ------------------------------ */
+
+registry.t(
+  "graph.ready and the report carry { fingerprint, names }; both are absent without a registry",
+  async t => {
+    const withRegistry = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "fn2", { next: ["b"] }), constNode("b", "B")],
+        entryNodes: ["a"],
+        terminalNodes: ["b"]
+      }),
+      { functions: { fn1: () => 1, fn2: () => 2 } }
+    );
+
+    const captured = capture(withRegistry, ["graph.ready"]);
+    const report = await withRegistry.run();
+
+    const readyRegistry = (
+      captured[0].payload as { registry?: { names: string[] } }
+    ).registry;
+
+    deepEq(readyRegistry?.names, ["fn1", "fn2"], "names are sorted");
+    deepEq(report.registry?.names, ["fn1", "fn2"], "report names");
+    eq(
+      report.registry?.fingerprint,
+      withRegistry.registry.fingerprint,
+      "one merged identity everywhere"
+    );
+
+    const bare = new GraphExecutionEngine(
+      g({
+        nodes: [constNode("a", "A")],
+        entryNodes: ["a"],
+        terminalNodes: ["a"]
+      })
+    );
+
+    const bareReport = await bare.run();
+
+    eq(bareReport.registry, undefined, "no registry configured ⇒ no field");
+    eq(bare.registry.names.length, 0, "empty registry");
+    eq(bare.registry.fingerprint.startsWith("fnr1:0:"), true, "empty fingerprint");
+  },
+  BIG
+);
+
+registry.t(
+  "every checkpoint carries the registry identity",
+  async t => {
+    const storage = new SpyStorage();
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "one", { next: ["b"] }), node("b", "two")],
+        entryNodes: ["a"],
+        terminalNodes: ["b"]
+      }),
+      { functions: { one: () => 1, two: () => 2 }, storage }
+    );
+
+    const report = await engine.run();
+    const snapshot = await storage.load(report.executionId);
+
+    deepEq(snapshot?.registry?.names, ["one", "two"], "checkpoint names");
+    eq(
+      snapshot?.registry?.fingerprint,
+      report.registry?.fingerprint,
+      "checkpoint and report agree"
+    );
+    deepEq(
+      snapshot?.results.map(result => result.fn),
+      ["one", "two"],
+      "checkpoint results carry fn"
+    );
+  },
+  BIG
+);
+
+/* ------------------------------ 5. registry object + validation ------------------------------ */
+
+registry.t(
+  "FunctionRegistry: register/extend/has/get/names/snapshot stay consistent",
+  async t => {
+    const table = createFunctionRegistry({ beta: () => 1 });
+
+    eq(table.size, 1, "size");
+    eq(table.has("beta"), true, "has");
+    eq(table.has("gamma"), false, "has (absent)");
+
+    table.register("alpha", () => 2).extend({ gamma: () => 3 });
+
+    deepEq(table.names(), ["alpha", "beta", "gamma"], "names sorted");
+    eq(table.size, 3, "size after extend");
+    deepEq(
+      Object.keys(table.snapshot()).sort(),
+      ["alpha", "beta", "gamma"],
+      "snapshot keys"
+    );
+    eq(typeof table.get("alpha"), "function", "get");
+    eq(table.get("nope"), undefined, "get (absent)");
+    ok(FunctionRegistry.from(table) === table, "from() passes instances through");
+    eq(FunctionRegistry.from({ z: () => 1 }).names().join(","), "z", "from() builds");
+
+    table.extend({ beta: () => 99 });
+    eq((table.get("beta") as () => number)(), 99, "later registration wins");
+    eq(table.size, 3, "extend does not duplicate keys");
+  },
+  BIG
+);
+
+registry.t(
+  "the fingerprint is stable, order-independent, and source-sensitive",
+  async t => {
+    const source = () => "same";
+    const sameTextElsewhere = () => "same";
+    const differentBody = () => "same!";
+
+    const first = createFunctionRegistry({ a: source, b: () => 2 });
+    const reordered = createFunctionRegistry({ b: () => 2, a: source });
+    const otherLiteral = createFunctionRegistry({
+      a: sameTextElsewhere,
+      b: () => 2
+    });
+    const changedBody = createFunctionRegistry({ a: differentBody, b: () => 2 });
+    const changedValue = createFunctionRegistry({ a: source, b: () => 3 });
+
+    eq(
+      first.fingerprint(),
+      reordered.fingerprint(),
+      "input key order does not matter"
+    );
+    eq(first.fingerprint(), first.fingerprint(), "stable in-process");
+    eq(
+      first.fingerprint(),
+      otherLiteral.fingerprint(),
+      "identical SOURCE TEXT fingerprints identically (closures are not inspected)"
+    );
+    neq(
+      first.fingerprint(),
+      changedBody.fingerprint(),
+      "a different source changes the identity"
+    );
+    neq(
+      first.fingerprint(),
+      changedValue.fingerprint(),
+      "a different implementation changes the identity"
+    );
+    eq(first.info().names.join(","), "a,b", "info names");
+
+    t.log("finding: the fingerprint covers names + function SOURCE TEXT — two closures of the same source share it, while a captured value that changes at runtime does not show up");
+  },
+  BIG
+);
+
+registry.t(
+  "invalid registrations fail immediately",
+  async t => {
+    const table = createFunctionRegistry();
+
+    const cases: Array<[string, unknown, RegExp]> = [
+      ["", () => 1, /identifier-like string/],
+      ["1bad", () => 1, /identifier-like string/],
+      ["has space", () => 1, /identifier-like string/],
+      ["ok", 42, /must be a function/]
+    ];
+
+    for (const [name, value, pattern] of cases) {
+      try {
+        table.register(name, value as RegisteredFunction);
+        throw new Error(`expected a throw for ${JSON.stringify(name)}`);
+      } catch (error) {
+        if (!(error instanceof GraphValidationError)) throw error;
+        if (!pattern.test(error.message)) {
+          throw new Error(`got "${error.message}", expected ${pattern}`);
+        }
+      }
+    }
+
+    table.register("vendor:retry", () => 1);
+    table.register("order.chargeCard", () => 2);
+
+    deepEq(table.names(), ["order.chargeCard", "vendor:retry"], "namespaced keys");
+  },
+  BIG
+);
+
+registry.t(
+  "malformed run values and graph tables are rejected at construction",
+  async t => {
+    const cases: Array<[unknown, RegExp]> = [
+      [42, /requires a run function/],
+      ["not a name!", /invalid registered function name/]
+    ];
+
+    for (const [run, pattern] of cases) {
+      try {
+        new GraphExecutionEngine(
+          g({
+            nodes: [node("a", run as never), constNode("end", "E")],
+            entryNodes: ["a"],
+            terminalNodes: ["end"]
+          })
+        );
+        throw new Error(`expected a throw for run=${JSON.stringify(run)}`);
+      } catch (error) {
+        if (!(error instanceof GraphValidationError)) throw error;
+        if (!pattern.test(error.message)) {
+          throw new Error(`got "${error.message}", expected ${pattern}`);
+        }
+      }
+    }
+
+    try {
+      new GraphExecutionEngine(
+        g({
+          nodes: [constNode("a", "A")],
+          entryNodes: ["a"],
+          terminalNodes: ["a"],
+          functions: { bad: "not a function" as never }
+        })
+      );
+      throw new Error("expected a throw for a non-function graph entry");
+    } catch (error) {
+      if (!(error instanceof GraphValidationError)) throw error;
+      ok(/must be a function/.test(error.message), error.message);
+    }
+  },
+  BIG
+);
+
+registry.t(
+  "nodeFunctions()/edgeTests() restore per-signature inference",
+  async t => {
+    const functions = {
+      ...nodeFunctions({
+        /* `context` infers as NodeContext — no annotation needed */
+        reportAttempt: context => `attempt ${context.attempt}`
+      }),
+      ...edgeTests({
+        /* `value` infers as unknown */
+        isHigh: value => value === "high"
+      })
+    };
+
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [
+          node("a", "reportAttempt", {
+            next: [
+              { test: "isHigh", nextNode: "yes" },
+              { nextNode: "no" }
+            ]
+          }),
+          constNode("yes", "YES"),
+          constNode("no", "NO")
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["yes", "no"]
+      }),
+      { functions }
+    );
+
+    const report = await engine.run();
+
+    eq(report.outputs.a, "attempt 1", "the node function ran");
+    eq(report.outputs.no, "NO", "the named test matched nothing");
+    deepEq(report.registry?.names, ["isHigh", "reportAttempt"], "names merged");
+
+    t.log("finding: one table holds both signatures; a bare literal cannot infer a parameter type from the union, hence nodeFunctions()/edgeTests()");
+  },
+  BIG
+);
+
+registry.t(
+  "the report stays JSON-serializable with a registry configured",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "boom", { next: ["b"] }), constNode("b", "B")],
+        entryNodes: ["a"],
+        terminalNodes: ["b"]
+      }),
+      { functions: { boom: () => ({ ok: true }) } }
+    );
+
+    const report = await engine.run();
+    const roundTrip = JSON.parse(JSON.stringify(report)) as typeof report;
+
+    deepEq(roundTrip.registry, report.registry, "registry survives JSON");
+    deepEq(
+      roundTrip.results.map(result => result.fn),
+      ["boom", null],
+      "fn survives JSON (an inline activation serializes as null)"
+    );
+    eq(roundTrip.status, "COMPLETED", "status");
+  },
+  BIG
+);
+
+registry.t(
+  "the UNKNOWN_FUNCTION record is self-describing",
+  async t => {
+    const engine = new GraphExecutionEngine(
+      g({
+        nodes: [node("a", "ghost"), constNode("b", "B")],
+        entryNodes: ["a"],
+        terminalNodes: ["b"]
+      }),
+      { functions: { present: () => 1 } }
+    );
+
+    const report = await engine.run();
+    const error = report.errors[0];
+    const details = error.details as {
+      kind: string;
+      name: string;
+      nodeId: string;
+      available: string[];
+    };
+
+    eq(error.code, "UNKNOWN_FUNCTION", "code");
+    eq(details.kind, "run", "kind");
+    eq(details.name, "ghost", "name");
+    eq(details.nodeId, "a", "nodeId");
+    deepEq(details.available, ["present"], "available names");
+    ok(error.message.includes("ghost"), error.message);
+  },
+  BIG
+);