automategraph 1.5.1 → 1.5.3

package/tests/upgrade.test.ts

@@ -0,0 +1,725 @@
+/* ============================================================
+ * WAVE 1 — upgrade feature pack (v1.1)
+ * ------------------------------------------------------------
+ * One suite per finding that Wave 1 addressed, so each former
+ * "surprise" now has an executable guarantee:
+ *
+ *   A1  cancellation symmetry          A2  drain deadline / ABANDONED
+ *   A3  completionPolicy + drops       A4  sticky FAIL_FAST
+ *   A5  FALLBACK routing               A6  NodeResult.error
+ *   A8  maxConcurrency / step budget   A9  lintGraph + lint modes
+ *   A10 lifecycle hygiene              IP  isomorphic build proof
+ * ============================================================ */
+
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+
+import {
+  AutomateGraphError,
+  GraphExecutionEngine,
+  GraphValidationError,
+  lintGraph
+} from "../src/automategraph";
+
+import {
+  capture,
+  constNode,
+  g,
+  linear,
+  logCollector,
+  node,
+  sleep,
+  tick
+} from "./helpers";
+
+import { suite } from "./harness";
+
+const a1 = suite("upgrade", "A1 · cancellation symmetry");
+const a2 = suite("upgrade", "A2 · drain deadline");
+const a3 = suite("upgrade", "A3 · completion policy");
+const a45 = suite("upgrade", "A4/A5 · FAIL_FAST & FALLBACK");
+const a6 = suite("upgrade", "A6/A10 · results & hygiene");
+const a8 = suite("upgrade", "A8 · concurrency & budget");
+const a9 = suite("upgrade", "A9 · graph linting");
+const ip = suite("upgrade", "Isomorphic build");
+
+const BIG = { timeoutMs: 20_000 };
+
+/* ========================= A2 — drain deadline ========================= */
+
+a2.t(
+  "cancellationTimeoutMs bounds the drain and abandons in-flight work",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("stubborn", async () => { await sleep(400); return "late"; })
+      ],
+      entryNodes: ["stubborn"],
+      terminalNodes: ["stubborn"]
+    });
+
+    const engine = new GraphExecutionEngine(definition, {
+      cancellationTimeoutMs: 40
+    });
+
+    const startedAt = Date.now();
+    const running = engine.run();
+    await sleep(10);
+    await engine.cancel();
+    const report = await running;
+    const durationMs = Date.now() - startedAt;
+
+    if (report.status !== "CANCELLED") throw new Error(report.status);
+    if (!report.drainTimedOut) throw new Error("drainTimedOut must be true");
+    if (durationMs > 300) throw new Error(`drain was not bounded (${durationMs}ms)`);
+    if (durationMs < 35) throw new Error(`settled before the drain deadline (${durationMs}ms)`);
+
+    const result = report.results[0];
+    if (result.status !== "ABANDONED") throw new Error(result.status);
+    if (result.output !== undefined) throw new Error("abandoned work must not adopt output");
+
+    if (report.abandonedActivations.length !== 1) {
+      throw new Error(`abandonedActivations=${report.abandonedActivations.length}`);
+    }
+    if (report.abandonedActivations[0] !== result.activationId) {
+      throw new Error("abandoned activation id mismatch");
+    }
+
+    const drainError = report.errors.find(error => error.code === "DRAIN_TIMEOUT");
+    if (!drainError) throw new Error("DRAIN_TIMEOUT not recorded");
+    if (!drainError.handled) throw new Error("DRAIN_TIMEOUT is informational, not a failure");
+    if (!(drainError.details as { abandoned: string[] }).abandoned.includes(result.activationId)) {
+      throw new Error("DRAIN_TIMEOUT details missing the abandoned activation");
+    }
+
+    // the abandoned node keeps running; its late output must never appear
+    const outputs = { ...report.outputs };
+    await sleep(430);
+    if (outputs.stubborn !== undefined) throw new Error("late output leaked into the report");
+
+    t.log("run duration", `${durationMs}ms (node sleeps 400ms)`);
+    t.log("finding: without cancellationTimeoutMs the engine still waits forever (v1.0 behaviour); " +
+      "setting it converts an unbounded drain into a bounded, reported one");
+  },
+  BIG
+);
+
+a2.t(
+  "without cancellationTimeoutMs the run waits for cooperative drain",
+  async t => {
+    const definition = g({
+      nodes: [node("slow", async () => { await sleep(60); return "done"; })],
+      entryNodes: ["slow"],
+      terminalNodes: ["slow"]
+    });
+
+    const engine = new GraphExecutionEngine(definition);
+    const startedAt = Date.now();
+    const running = engine.run();
+    await sleep(10);
+    await engine.cancel();
+    const report = await running;
+    const durationMs = Date.now() - startedAt;
+
+    if (report.drainTimedOut) throw new Error("drainTimedOut must be false when unbounded");
+    if (durationMs < 45) throw new Error(`settled too early (${durationMs}ms)`);
+    if (report.results[0].status !== "CANCELLED") throw new Error(report.results[0].status);
+  },
+  BIG
+);
+
+/* ========================= A3 — completion policies ========================= */
+
+function twoTerminalGraph(slowMs: number) {
+  return g({
+    nodes: [
+      node("entry", () => "E", { next: ["fast-branch", "slow-branch"] }),
+      node("fast-branch", () => "FAST", { next: ["t1"] }),
+      node("slow-branch", async () => { await sleep(slowMs); return "SLOW"; }, { next: ["t2"] }),
+      constNode("t1", "T1"),
+      constNode("t2", "T2")
+    ],
+    entryNodes: ["entry"],
+    terminalNodes: ["t1", "t2"]
+  });
+}
+
+a3.t(
+  "ALL_TERMINALS waits for every declared terminal before latching completion",
+  async t => {
+    const definition = { ...twoTerminalGraph(25), completionPolicy: "ALL_TERMINALS" as const };
+    const engine = new GraphExecutionEngine(definition);
+    const captured = capture(engine, ["graph.logicallyCompleted"]);
+    const report = await engine.run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (!report.logicallyCompleted) throw new Error("not logically completed");
+    if (!report.results.some(result => result.nodeId === "t2")) throw new Error("t2 never ran");
+
+    if (captured.length !== 1) throw new Error(`logicallyCompleted events=${captured.length}`);
+    const payload = captured[0].payload as { terminalNodeId: string };
+    if (payload.terminalNodeId !== "t2") {
+      throw new Error(`latching terminal=${payload.terminalNodeId} (expected the last one, t2)`);
+    }
+
+    t.log("finding: ALL_TERMINALS gives fan-in style completion semantics without extra plumbing");
+  },
+  BIG
+);
+
+a3.t(
+  "DRAIN keeps scheduling after a terminal, so ONTHROW recovery is no longer dropped",
+  async t => {
+    const definition = {
+      ...g({
+        nodes: [
+          node("entry", () => "E", { next: ["fast-branch", "slow-branch"] }),
+          node("fast-branch", () => "FAST", { next: ["t1"] }),
+          node("slow-branch", async () => { await sleep(25); throw new Error("late-failure"); }, {
+            onThrow: "recovery"
+          }),
+          node("recovery", () => "RECOVERED", { next: ["t2"] }),
+          constNode("t1", "T1"),
+          constNode("t2", "T2")
+        ],
+        entryNodes: ["entry"],
+        terminalNodes: ["t1", "t2"]
+      }),
+      completionPolicy: "DRAIN" as const
+    };
+
+    const report = await new GraphExecutionEngine(definition).run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (report.outputs.recovery !== "RECOVERED") {
+      throw new Error("recovery was dropped in DRAIN mode");
+    }
+    if (!report.results.some(result => result.nodeId === "t2")) throw new Error("t2 never ran");
+    if (!report.errors[0].handled) throw new Error("recovery error should be handled");
+
+    t.log(
+      "finding: DRAIN is the opt-in fix for the v1.0 silent-drop behaviour (finding C-15/C-19) — " +
+      "the run executes every reachable activation before settling"
+    );
+  },
+  BIG
+);
+
+a3.t(
+  "FIRST_TERMINAL (default) drops pending work but now reports it via activation.dropped",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("entry", () => "E", { next: ["fast-branch", "slow-branch"] }),
+        node("fast-branch", () => "FAST", { next: ["t1"] }),
+        node("slow-branch", async () => { await sleep(25); throw new Error("late-failure"); }, {
+          onThrow: "recovery"
+        }),
+        node("recovery", () => "RECOVERED", { next: ["t2"] }),
+        constNode("t1", "T1"),
+        constNode("t2", "T2")
+      ],
+      entryNodes: ["entry"],
+      terminalNodes: ["t1", "t2"]
+    });
+
+    const engine = new GraphExecutionEngine(definition);
+    const captured = capture(engine, ["activation.dropped"]);
+    const report = await engine.run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (report.outputs.recovery !== undefined) throw new Error("recovery unexpectedly ran");
+
+    if (captured.length !== 1) throw new Error(`activation.dropped events=${captured.length}`);
+    const payload = captured[0].payload as {
+      reason: string;
+      dropped: Array<{ nodeId: string }>;
+    };
+
+    if (payload.reason !== "logical-completion") throw new Error(payload.reason);
+    if (!payload.dropped.some(entry => entry.nodeId === "recovery")) {
+      throw new Error(`dropped=${payload.dropped.map(entry => entry.nodeId).join(",")}`);
+    }
+
+    t.log("finding: dropped work is now observable, so silent data loss in the default mode is detectable");
+  },
+  BIG
+);
+
+a3.t(
+  "an unknown completionPolicy is rejected at construction time",
+  () => {
+    try {
+      new GraphExecutionEngine({
+        ...linear(["a"]),
+        completionPolicy: "WHENEVER" as never
+      });
+      throw new Error("expected throw");
+    } catch (error) {
+      if (!(error instanceof GraphValidationError)) throw error;
+      if (!/Unknown completionPolicy/.test(error.message)) throw new Error(error.message);
+    }
+  }
+);
+
+/* ========================= A4 / A5 — policies ========================= */
+
+a45.t(
+  "node-level FAIL_FAST is sticky and drops successors via activation.dropped",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("root", () => "R", { next: ["worker", "breaker"] }),
+        node("worker", async () => { await sleep(30); return "WORKED"; }, { next: ["tail"] }),
+        node("breaker", () => { throw new Error("policy-violation"); }, { errorPolicy: "FAIL_FAST" }),
+        constNode("tail", "TAIL")
+      ],
+      entryNodes: ["root"],
+      terminalNodes: ["tail"]
+    });
+
+    const engine = new GraphExecutionEngine(definition);
+    const captured = capture(engine, ["activation.dropped"]);
+    const report = await engine.run();
+
+    if (report.status !== "FAILED") throw new Error(report.status);
+    if (report.results.some(result => result.nodeId === "tail")) {
+      throw new Error("sticky FAIL_FAST failed to stop the successor");
+    }
+    if (!report.results.some(result => result.nodeId === "worker" && result.status === "SUCCEEDED")) {
+      throw new Error("in-flight sibling must still drain");
+    }
+
+    const drop = captured.find(entry => (entry.payload as { reason: string }).reason === "fail-fast");
+    if (!drop) throw new Error("no fail-fast drop event");
+    const dropped = (drop.payload as { dropped: Array<{ nodeId: string }> }).dropped;
+    if (!dropped.some(entry => entry.nodeId === "tail")) {
+      throw new Error(`dropped=${dropped.map(entry => entry.nodeId).join(",")}`);
+    }
+  },
+  BIG
+);
+
+a45.t(
+  "FALLBACK routes to the fallback node and marks the error handled",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("primary", () => { throw new Error("vendor-down"); }, {
+          errorPolicy: "FALLBACK",
+          fallback: "cached"
+        }),
+        node("cached", () => "CACHED-RESULT", { next: ["finish"] }),
+        constNode("finish", "DONE")
+      ],
+      entryNodes: ["primary"],
+      terminalNodes: ["finish"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (report.outputs.cached !== "CACHED-RESULT") throw new Error("fallback node did not run");
+    if (report.errors.length !== 1) throw new Error(`errors=${report.errors.length}`);
+    if (!report.errors[0].handled) throw new Error("fallback error must be handled");
+    if (report.errors[0].message !== "vendor-down") throw new Error(report.errors[0].message);
+  },
+  BIG
+);
+
+a45.t(
+  "a fallback target is ignored unless the effective policy is FALLBACK",
+  async t => {
+    const definition = g({
+      nodes: [
+        node("primary", () => { throw new Error("boom"); }, {
+          errorPolicy: "CONTINUE",
+          fallback: "cached"
+        }),
+        constNode("cached", "CACHED")
+      ],
+      entryNodes: ["primary"],
+      terminalNodes: ["cached"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+
+    if (report.status !== "FAILED") throw new Error(report.status);
+    if (report.outputs.cached !== undefined) throw new Error("fallback ran under CONTINUE");
+    if (report.errors[0].handled) throw new Error("error must stay unhandled under CONTINUE");
+  },
+  BIG
+);
+
+a45.t(
+  "an unknown fallback target is rejected at construction time",
+  () => {
+    try {
+      new GraphExecutionEngine(g({
+        nodes: [node("a", () => 1, { fallback: "nowhere" })],
+        entryNodes: ["a"],
+        terminalNodes: ["a"]
+      }));
+      throw new Error("expected throw");
+    } catch (error) {
+      if (!(error instanceof GraphValidationError)) throw error;
+      if (!/unknown FALLBACK target "nowhere"/.test(error.message)) throw new Error(error.message);
+    }
+  }
+);
+
+/* ========================= A6 / A10 — results & hygiene ========================= */
+
+a6.t(
+  "NodeResult.error carries the failure record and matches the report errors",
+  async t => {
+    const definition = g({
+      nodes: [node("broken", () => { throw new Error("attached-error"); })],
+      entryNodes: ["broken"],
+      terminalNodes: ["broken"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const result = report.results[0];
+
+    if (!result.error) throw new Error("result.error missing");
+    if (result.error.id !== report.errors[0].id) throw new Error("record mismatch");
+    if (result.error.message !== "attached-error") throw new Error(result.error.message);
+    if (result.error.code !== "NODE_EXECUTION_ERROR") throw new Error(result.error.code);
+  },
+  BIG
+);
+
+a6.t(
+  "a timed-out node exposes NODE_TIMEOUT on its own result",
+  async t => {
+    const definition = g({
+      nodes: [node("slow", async () => { await sleep(80); return "late"; }, { timeoutMs: 15 })],
+      entryNodes: ["slow"],
+      terminalNodes: ["slow"]
+    });
+
+    const report = await new GraphExecutionEngine(definition).run();
+    const result = report.results[0];
+
+    if (result.status !== "TIMED_OUT") throw new Error(result.status);
+    if (!result.error) throw new Error("result.error missing for TIMED_OUT");
+    if (result.error.code !== "NODE_TIMEOUT") throw new Error(result.error.code);
+
+    await sleep(100);
+  },
+  BIG
+);
+
+a6.t(
+  "in-flight activation tracking is empty before and after a run",
+  async t => {
+    const definition = g({
+      nodes: [node("slow", async () => { await sleep(30); return "ok"; })],
+      entryNodes: ["slow"],
+      terminalNodes: ["slow"]
+    });
+
+    const engine = new GraphExecutionEngine(definition);
+    if (engine.getInFlightActivationIds().length !== 0) throw new Error("dirty before run");
+
+    const running = engine.run();
+    await sleep(10);
+    if (engine.getInFlightActivationIds().length !== 1) {
+      throw new Error(`in-flight=${engine.getInFlightActivationIds().length}`);
+    }
+
+    const report = await running;
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (engine.getInFlightActivationIds().length !== 0) throw new Error("leaked after settle");
+  },
+  BIG
+);
+
+/* ========================= A8 — concurrency & budget ========================= */
+
+function fanOutGraph(width: number, sleepMs: number, tracker: { active: number; max: number }) {
+  // A dedicated terminal node keeps FIRST_TERMINAL completion from
+  // dropping leaves that were not scheduled yet.
+
+  const leaves = Array.from({ length: width }, (_, index) =>
+    node(`leaf-${index}`, async () => {
+      tracker.active += 1;
+      tracker.max = Math.max(tracker.max, tracker.active);
+      try {
+        await sleep(sleepMs);
+        return index;
+      } finally {
+        tracker.active -= 1;
+      }
+    }, { next: ["sink"] })
+  );
+
+  return g({
+    nodes: [
+      node("root", () => "R", { next: leaves.map(leaf => leaf.id) }),
+      ...leaves,
+      constNode("sink", "SINK")
+    ],
+    entryNodes: ["root"],
+    terminalNodes: ["sink"]
+  });
+}
+
+a8.t(
+  "maxConcurrency bounds parallelism and preserves completion",
+  async t => {
+    const tracker = { active: 0, max: 0 };
+    const report = await new GraphExecutionEngine(
+      fanOutGraph(8, 5, tracker),
+      { maxConcurrency: 2 }
+    ).run();
+
+    if (report.status !== "COMPLETED") throw new Error(report.status);
+    if (tracker.max !== 2) throw new Error(`observed concurrency ${tracker.max}, expected 2`);
+    const leaves = report.results.filter(result => result.nodeId.startsWith("leaf-"));
+    if (leaves.length !== 8) throw new Error(`leaf results=${leaves.length}`);
+    if (leaves.some(result => result.status !== "SUCCEEDED")) throw new Error("a leaf failed");
+
+    const unlimited = { active: 0, max: 0 };
+    await new GraphExecutionEngine(fanOutGraph(8, 5, unlimited)).run();
+    if (unlimited.max !== 8) throw new Error(`unbounded default regressed: ${unlimited.max}`);
+
+    t.log("bounded", tracker.max, "| unbounded default", unlimited.max);
+  },
+  BIG
+);
+
+a8.t(
+  "maxActivations stops a runaway cycle with STEP_BUDGET_EXCEEDED",
+  async t => {
+    const definition = g({
+      // "exit" is declared but unreachable: the cycle can never terminate
+      // on its own, so only the budget can stop it.
+      nodes: [
+        node("spinner", () => "again", { next: ["spinner2"] }),
+        node("spinner2", () => "again", { next: ["spinner"] }),
+        constNode("exit", "EXIT")
+      ],
+      entryNodes: ["spinner"],
+      terminalNodes: ["exit"]
+    });
+
+    const startedAt = Date.now();
+    const report = await new GraphExecutionEngine(definition, { maxActivations: 6 }).run();
+    const durationMs = Date.now() - startedAt;
+
+    if (durationMs > 5000) throw new Error("budget did not stop the cycle");
+    if (report.status !== "FAILED") throw new Error(report.status);
+
+    const budgetError = report.errors.find(error => error.code === "STEP_BUDGET_EXCEEDED");
+    if (!budgetError) throw new Error("STEP_BUDGET_EXCEEDED not recorded");
+    if (budgetError.handled) throw new Error("budget exhaustion must be unhandled");
+
+    if (report.results.length > 6) {
+      throw new Error(`ran ${report.results.length} activations despite a budget of 6`);
+    }
+    if (report.results.length === 0) throw new Error("no activation ran");
+
+    t.log("activations executed", report.results.length, "| duration", `${durationMs}ms`);
+  },
+  BIG
+);
+
+a8.t(
+  "invalid concurrency and budget options are rejected",
+  () => {
+    const definition = linear(["a"]);
+    for (const options of [
+      { maxConcurrency: 0 },
+      { maxConcurrency: 1.5 },
+      { maxActivations: 0 },
+      { maxActivations: -3 },
+      { lint: "sometimes" as never }
+    ]) {
+      try {
+        new GraphExecutionEngine(definition, options as never);
+        throw new Error(`expected throw for ${JSON.stringify(options)}`);
+      } catch (error) {
+        if (!(error instanceof GraphValidationError)) throw error;
+      }
+    }
+  }
+);
+
+/* ========================= A9 — linting ========================= */
+
+a9.t(
+  "lintGraph reports unreachable nodes, unreachable terminals, dead ends and duplicates",
+  () => {
+    const definition = g({
+      nodes: [
+        constNode("entry", "E", { next: ["finish"] }),
+        constNode("finish", "F"),
+        constNode("orphan", "O"),
+        constNode("dead", "D")
+      ],
+      entryNodes: ["entry", "entry"],
+      terminalNodes: ["finish", "ghost-terminal"]
+    });
+
+    // "ghost-terminal" is not part of nodes: lint is standalone, the
+    // engine's validateGraph would reject it before linting.
+    const issues = lintGraph({
+      ...definition,
+      nodes: { ...definition.nodes, "ghost-terminal": constNode("ghost-terminal", "G") }
+    });
+
+    const codes = new Set(issues.map(issue => issue.code));
+    for (const expected of [
+      "DUPLICATE_ENTRY",
+      "UNREACHABLE_NODE",
+      "DEAD_END_NODE"
+    ]) {
+      if (!codes.has(expected as never)) throw new Error(`missing ${expected}: ${[...codes].join(",")}`);
+    }
+
+    const orphan = issues.find(issue => issue.nodeId === "orphan");
+    if (!orphan || orphan.code !== "UNREACHABLE_NODE") throw new Error("orphan not flagged");
+    if (orphan.level !== "warn") throw new Error("unreachable nodes are warnings");
+
+    const dead = issues.find(
+      issue => issue.code === "DEAD_END_NODE" && issue.nodeId === "dead"
+    );
+    if (!dead || dead.level !== "error") {
+      throw new Error(`dead end must be an error; got ${issues.map(i => `${i.code}@${i.nodeId}`).join(",")}`);
+    }
+  }
+);
+
+a9.t(
+  "lint: \"warn\" logs issues, lint: \"error\" rejects only on error-level issues",
+  async t => {
+    const { lines, onLog } = logCollector();
+
+    const withWarning = g({
+      nodes: [
+        constNode("entry", "E", { next: ["finish"] }),
+        constNode("finish", "F"),
+        // reachable-if-wired but nothing points at it: a pure warning
+        constNode("orphan", "O", { next: ["finish"] })
+      ],
+      entryNodes: ["entry"],
+      terminalNodes: ["finish"]
+    });
+
+    const warned = await new GraphExecutionEngine(withWarning, {
+      lint: "warn",
+      onLog
+    }).run();
+
+    if (warned.status !== "COMPLETED") throw new Error(warned.status);
+    if (warned.lintIssues.length !== 1) throw new Error(`lintIssues=${warned.lintIssues.length}`);
+    if (!lines.some(line => line.message.includes("Graph lint [UNREACHABLE_NODE]"))) {
+      throw new Error("lint warning not logged");
+    }
+
+    // warnings alone never reject, even in "error" mode
+    const tolerant = await new GraphExecutionEngine(withWarning, { lint: "error" }).run();
+    if (tolerant.status !== "COMPLETED") throw new Error(`(warn-only) ${tolerant.status}`);
+
+    // a dead-end node is an error-level issue
+    const withError = g({
+      nodes: [
+        constNode("entry", "E", { next: ["dead", "finish"] }),
+        constNode("dead", "D"),
+        constNode("finish", "F")
+      ],
+      entryNodes: ["entry"],
+      terminalNodes: ["finish"]
+    });
+
+    const rejected = await new GraphExecutionEngine(withError, { lint: "error" }).run();
+
+    if (rejected.status !== "REJECTED") throw new Error(rejected.status);
+    if (rejected.results.length !== 0) throw new Error("work ran despite lint failure");
+    if (!rejected.lintIssues.some(issue => issue.code === "DEAD_END_NODE")) {
+      throw new Error("lint issues missing from the report");
+    }
+    if (!rejected.errors[0].message.includes("Graph lint reported")) {
+      throw new Error(rejected.errors[0].message);
+    }
+
+    t.log("lint issues in the rejected report", rejected.lintIssues.map(issue => issue.code).join(","));
+  },
+  BIG
+);
+
+/* ========================= Isomorphic build proof ========================= */
+
+ip.t(
+  "the engine core compiles with DOM-only libs and no Node types (browser-safe)",
+  async t => {
+    const root = path.resolve(__dirname, "..", "..");
+    const fs = await import("node:fs");
+    const tsc = path.join(
+      root,
+      "node_modules",
+      ".bin",
+      process.platform === "win32" ? "tsc.cmd" : "tsc"
+    );
+
+    /* The guard config must keep its teeth: DOM only, no Node types, and
+     * the Node-only loader outside the isomorphic surface. */
+    const config = fs.readFileSync(path.join(root, "tsconfig.browser.json"), "utf8");
+    if (!config.includes('"types": []')) throw new Error("browser config lost its Node-free guard");
+    if (!config.includes('"DOM"')) throw new Error("browser config lost the DOM lib");
+    if (!config.includes("src/node")) throw new Error("browser config should exclude the Node-only loader");
+
+    if (fs.existsSync(tsc)) {
+      const result = spawnSync(tsc, ["-p", "tsconfig.browser.json"], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: 60_000
+      });
+
+      if (result.error) throw result.error;
+      if (result.status !== 0) {
+        throw new Error(`browser build failed:\n${result.stdout}\n${result.stderr}`);
+      }
+    } else {
+      /*
+       * An installed copy of the published package has no devDependencies,
+       * so the compiler proof cannot run. The property is still checked —
+       * statically, over the isomorphic core (src/node/** is Node-only by
+       * definition and excluded).
+       */
+      const FORBIDDEN =
+        /(?:^|[^\w.$])(require\s*\(|process\.|Buffer\.|__dirname|__filename|setImmediate\s*\()|from\s*["']node:/m;
+
+      const core = [
+        "src/automategraph.ts",
+        "src/graph-json.ts",
+        "src/storage-adapter.ts",
+        "src/storage-conformance.ts"
+      ];
+
+      for (const file of core) {
+        const source = fs
+          .readFileSync(path.join(root, file), "utf8")
+          .replace(/\/\*[\s\S]*?\*\//g, "")
+          .replace(/(^|[^:])\/\/.*$/gm, "$1");
+
+        const match = FORBIDDEN.exec(source);
+
+        if (match) {
+          throw new Error(
+            `${file} references Node-only ${JSON.stringify(match[0])} — the isomorphic core must stay free of Node APIs`
+          );
+        }
+      }
+    }
+
+    t.log(
+      fs.existsSync(tsc)
+        ? "finding: the engine core is isomorphic — no Node APIs, no Buffers, timers via setTimeout only"
+        : "note: typescript is not installed in this copy, so the DOM-only tsc proof was replaced by a static scan of the four isomorphic core files (all clean)"
+    );
+  },
+  BIG
+);