automategraph 1.5.0 → 1.5.3

package/tests/scripts.test.ts

@@ -0,0 +1,970 @@
+/* ============================================================
+ * SCRIPT LOADER PACK (v1.5)
+ * ------------------------------------------------------------
+ * A document may declare scripts that PROVIDE the functions its nodes
+ * and edges name:
+ *
+ *   "scripts": [
+ *     { "namespace": "order", "path": "./order.cjs" },
+ *     { "namespace": "inline", "source": "module.exports = { … }" },
+ *     { "namespace": "remote", "url": "https://host/fns.mjs", "format": "esm" }
+ *   ]
+ *
+ * Two-step API (the loader is Node-only, the core stays isomorphic):
+ *
+ *   const { functions, namespaces } = await loadGraphScripts(document);
+ *   const engine = createEngineFromJSON(document, { functions });
+ *
+ * Under test:
+ *   • strategies — EXPORTS (cjs / esm / default-object) and SELF-REGISTRATION
+ *     through globalThis.GraphEngine.registerEngineNamespace(namespace, fns),
+ *     including both in one script
+ *   • format auto-detection (.cjs → require, .mjs → import, .js → hint +
+ *     fallback) and the explicit "format" override, which is never retried
+ *   • the freeze — a namespace is claimed once per PROCESS; a second claim
+ *     throws, from inside the script when the script registers itself
+ *   • plain names: the namespace is a claim slot, never a name prefix
+ *   • validation runs before any code executes
+ * ============================================================ */
+
+import * as path from "path";
+
+import { GraphExecutionEngine } from "../src/automategraph";
+import {
+  GraphJSONError,
+  createEngineFromJSON,
+  parseGraphJSON,
+  parseGraphJSONDocument
+} from "../src/graph-json";
+import {
+  GraphScriptError,
+  loadGraphScripts,
+  registeredNamespaces,
+  resetGraphScriptNamespaces
+} from "../src/node/graph-scripts";
+
+import { BIG, logCollector } from "./helpers";
+import { suite } from "./harness";
+
+const scripts = suite("scripts", "Script loading");
+
+/* ------------------------------ helpers ------------------------------ */
+
+const FIXTURES = path.join(
+  __dirname,
+  "..",
+  "..",
+  "tests",
+  "fixtures",
+  "scripts"
+);
+
+function doc(declarations: unknown[]): Record<string, unknown> {
+  return {
+    id: "scripted",
+    version: "1.5.0",
+    entryNodes: ["a"],
+    terminalNodes: ["end"],
+    scripts: declarations,
+    nodes: {
+      a: { run: "start", next: ["end"] },
+      end: { run: "finish" }
+    }
+  };
+}
+
+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 ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+    );
+  }
+}
+
+function deepEq(actual: unknown, expected: unknown, label: string): void {
+  const a = JSON.stringify(actual ?? null);
+  const b = JSON.stringify(expected ?? null);
+
+  if (a !== b) throw new Error(`${label}: expected ${b}, got ${a}`);
+}
+
+async function loadError(
+  declaration: unknown
+): Promise<GraphScriptError> {
+  try {
+    await loadGraphScripts(doc([declaration]), { baseDir: FIXTURES });
+  } catch (error) {
+    if (error instanceof GraphScriptError) return error;
+    throw error;
+  }
+
+  throw new Error("expected a GraphScriptError");
+}
+
+/** Claims are process-global: every test starts from a clean slate. */
+function fresh(): void {
+  resetGraphScriptNamespaces();
+}
+
+/* ------------------------------ 1. media & formats ------------------------------ */
+
+scripts.t(
+  "a .cjs script is required and its export table becomes the registry",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "order", path: "./order.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    deepEq(
+      loaded.registry.names,
+      [
+        "chargeCard",
+        "classifyOrder",
+        "isPriority",
+        "manualReview",
+        "rejectOrder",
+        "shipOrder"
+      ],
+      "names: sorted, non-function export excluded"
+    );
+    deepEq(loaded.namespaces, ["order"], "namespaces");
+    eq(loaded.scripts[0].format, "cjs", "format");
+    eq(loaded.scripts[0].source, "path:./order.cjs", "source label");
+    deepEq(loaded.scripts[0].ignoredExports, ["STATUS"], "ignored exports");
+    eq(Object.isFrozen(loaded.functions), true, "the table is frozen");
+    ok(
+      loaded.registry.fingerprint.startsWith("fnr1:6:"),
+      loaded.registry.fingerprint
+    );
+
+    /* the functions are the real things, callable with real contexts */
+    eq((loaded.functions.classifyOrder as () => string)(), "priority", "call");
+    eq(
+      (loaded.functions.isPriority as (v: unknown) => boolean)("priority"),
+      true,
+      "matcher"
+    );
+
+    t.log("finding: a registered name is not rewritten — `classifyOrder` stays `classifyOrder`, the namespace only owns the claim");
+  },
+  BIG
+);
+
+scripts.t(
+  "an .mjs script is imported as an ES module",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "esm", path: "./esm-functions.mjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(loaded.scripts[0].format, "esm", "format");
+    eq((loaded.functions.shipOrder as () => string)(), "shipped", "named export works");
+    deepEq(loaded.scripts[0].ignoredExports, ["version"], "non-function export ignored");
+  },
+  BIG
+);
+
+scripts.t(
+  "a .js script with ESM syntax is detected as ESM; without it, as CommonJS",
+  async t => {
+    fresh();
+
+    const esm = await loadGraphScripts(
+      doc([{ namespace: "detected", path: "./esm-syntax.js" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(esm.scripts[0].format, "esm", ".js with export syntax");
+    eq((esm.functions.greetFromJs as () => string)(), "hello from .js ESM", "works");
+
+    fresh();
+
+    const cjs = await loadGraphScripts(
+      doc([{ namespace: "defaulted", path: "./cjs-default.js" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(cjs.scripts[0].format, "cjs", ".js without export syntax");
+    eq((cjs.functions.plainCjs as () => string)(), "plain cjs", "works");
+
+    t.log("finding: .js detection is a source hint with a fallback — the other format is attempted before failing, so a mis-hint costs one retry, never a failed load");
+  },
+  BIG
+);
+
+scripts.t(
+  "an explicit format is honoured and never retried in the other format",
+  async t => {
+    fresh();
+
+    /* CJS import() of a CJS file is legal: the override to ESM succeeds */
+    const forcedEsm = await loadGraphScripts(
+      doc([{ namespace: "forcedEsm", path: "./cjs-default.js", format: "esm" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(forcedEsm.scripts[0].format, "esm", "forced esm");
+    ok("plainCjs" in forcedEsm.functions, Object.keys(forcedEsm.functions).join(","));
+
+    fresh();
+
+    /* .mjs forced to CJS cannot work — and must fail WITHOUT trying ESM */
+    const error = await loadError({
+      namespace: "forcedCjs",
+      path: "./esm-functions.mjs",
+      format: "cjs"
+    });
+
+    eq(error.code, "SCRIPT_LOAD_FAILED", "code");
+    deepEq(
+      (error.details as { attempts: string[] }).attempts.length,
+      1,
+      "exactly one attempt: no fallback for an explicit format"
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "inline CommonJS source runs with a real require and module",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([
+        {
+          namespace: "inlineCjs",
+          source:
+            "module.exports = { inlineCjs: () => 'inline cjs', " +
+            "isInline: value => value === 'inline cjs' };"
+        }
+      ]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(loaded.scripts[0].format, "cjs", "format");
+    eq(loaded.scripts[0].source, "inline source", "label");
+    eq((loaded.functions.inlineCjs as () => string)(), "inline cjs", "works");
+  },
+  BIG
+);
+
+scripts.t(
+  "inline ESM source is evaluated from a data URL",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([
+        {
+          namespace: "inlineEsm",
+          source: "export const inlineEsm = () => 'inline esm';"
+        }
+      ]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(loaded.scripts[0].format, "esm", "format");
+    eq((loaded.functions.inlineEsm as () => string)(), "inline esm", "works");
+  },
+  BIG
+);
+
+scripts.t(
+  "URL scripts are fetched and evaluated (CJS by default, ESM by hint)",
+  async t => {
+    fresh();
+
+    const cjsText = "module.exports = { fromUrl: () => 'url cjs' };";
+
+    const cjs = await loadGraphScripts(
+      doc([{ namespace: "remoteCjs", url: "https://example.test/fns.cjs" }]),
+      {
+        baseDir: FIXTURES,
+        fetchText: async url => {
+          eq(url, "https://example.test/fns.cjs", "the loader fetched the declared URL");
+          return cjsText;
+        }
+      }
+    );
+
+    eq(cjs.scripts[0].format, "cjs", "format");
+    eq((cjs.functions.fromUrl as () => string)(), "url cjs", "works");
+
+    fresh();
+
+    const esm = await loadGraphScripts(
+      doc([{ namespace: "remoteEsm", url: "https://example.test/thing.mjs" }]),
+      {
+        baseDir: FIXTURES,
+        fetchText: async () => "export const fromUrlEsm = () => 'url esm';"
+      }
+    );
+
+    eq(esm.scripts[0].format, "esm", ".mjs URL");
+    eq((esm.functions.fromUrlEsm as () => string)(), "url esm", "works");
+  },
+  BIG
+);
+
+/* ------------------------------ 2. the global channel ------------------------------ */
+
+scripts.t(
+  "a script can register itself through globalThis.GraphEngine",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "billing", path: "./global-channel.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    deepEq(loaded.registry.names, ["invoiceOrder", "isBillable"], "registered names");
+    eq((loaded.functions.invoiceOrder as () => string)(), "invoiced", "works");
+
+    const claim = registeredNamespaces().find(entry => entry.namespace === "billing");
+
+    ok(claim !== undefined, "the claim is recorded");
+    deepEq(claim?.names, ["invoiceOrder", "isBillable"], "claim names, sorted");
+    eq(claim?.source, "path:./global-channel.cjs", "claim source");
+
+    t.log("finding: the engine global is a per-CALL slot (registerEngineNamespace), not a shared mutable table — a script can only ever add its own namespace, and only once");
+  },
+  BIG
+);
+
+scripts.t(
+  "the realm is restored after the load — the engine global does not leak",
+  async t => {
+    fresh();
+
+    const marker = { marker: "pre-existing" };
+    (globalThis as Record<string, unknown>).GraphEngine = marker;
+
+    await loadGraphScripts(
+      doc([{ namespace: "billing", path: "./global-channel.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    const after = (globalThis as Record<string, unknown>)
+      .GraphEngine as Record<string, unknown>;
+
+    ok(after === marker, "the previous global object is restored by identity");
+    eq(
+      typeof after.registerEngineNamespace,
+      "undefined",
+      "our registrar is gone"
+    );
+
+    delete (globalThis as Record<string, unknown>).GraphEngine;
+
+    await loadGraphScripts(
+      doc([{ namespace: "restoreTest", path: "./order.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(
+      (globalThis as Record<string, unknown>).GraphEngine,
+      undefined,
+      "with no previous global, the loader removes what it installed"
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "a script can both self-register and export; both land in the namespace",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "telemetry", path: "./global-channel.mjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    deepEq(
+      loaded.registry.names,
+      ["recordRun", "traceId"],
+      "registered + exported names"
+    );
+    eq((loaded.functions.traceId as () => string)(), "trace-1", "exported");
+    eq((loaded.functions.recordRun as () => string)(), "recorded", "registered");
+  },
+  BIG
+);
+
+scripts.t(
+  "the declared namespace must match what the script registers",
+  async t => {
+    fresh();
+
+    const error = await loadError({
+      namespace: "declared-here",
+      path: "./mismatch.cjs"
+    });
+
+    eq(error.code, "NAMESPACE_MISMATCH", "code");
+    deepEq(
+      (error.details as { declared: string; received: string }).declared,
+      "declared-here",
+      "declared"
+    );
+    deepEq(
+      (error.details as { received: string }).received,
+      "other",
+      "received"
+    );
+    ok(error.message.includes("declared-here"), error.message);
+  },
+  BIG
+);
+
+scripts.t(
+  "a registration error from inside the script surfaces unwrapped",
+  async t => {
+    fresh();
+
+    const error = await loadError({
+      namespace: "badmin",
+      path: "./bad-registration.cjs"
+    });
+
+    /* NOT SCRIPT_LOAD_FAILED: the script's verdict is preserved */
+    eq(error.code, "SCRIPT_EXPORT_INVALID", "code");
+    ok(error.message.includes("notAFunction"), error.message);
+    eq(
+      (error.details as { name: string }).name,
+      "notAFunction",
+      "the offending name"
+    );
+  },
+  BIG
+);
+
+/* ------------------------------ 3. the freeze ------------------------------ */
+
+scripts.t(
+  "a namespace can be claimed only once per process (exports path)",
+  async t => {
+    fresh();
+
+    const document = doc([{ namespace: "once", path: "./order.cjs" }]);
+
+    const first = await loadGraphScripts(document, { baseDir: FIXTURES });
+    eq(first.namespaces[0], "once", "first load");
+
+    let second: GraphScriptError | undefined;
+
+    try {
+      await loadGraphScripts(document, { baseDir: FIXTURES });
+    } catch (error) {
+      second = error as GraphScriptError;
+    }
+
+    ok(second instanceof GraphScriptError, "the second load throws");
+    eq(second?.code, "NAMESPACE_ALREADY_REGISTERED", "code");
+    eq(
+      (second?.details as { claimedBy: string; requestedBy: string }).claimedBy,
+      "path:./order.cjs",
+      "the error names the original claim"
+    );
+    ok(
+      second?.message.includes("once per process") === true,
+      second?.message ?? "no message"
+    );
+
+    resetGraphScriptNamespaces();
+
+    const third = await loadGraphScripts(document, { baseDir: FIXTURES });
+    eq(third.namespaces[0], "once", "after reset it loads again");
+
+    t.log("finding: the freeze is PROCESS-global by design — one document, one engine per namespace. Loading the same graph file into a second engine throws until the claims are reset");
+  },
+  BIG
+);
+
+scripts.t(
+  "a self-registering script throws on the duplicate claim FROM INSIDE the script",
+  async t => {
+    fresh();
+
+    await loadGraphScripts(
+      doc([{ namespace: "billing", path: "./global-channel.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    /* a second document declaring the same namespace: the script itself
+     * calls the registrar and the registrar refuses */
+    const error = await loadError({
+      namespace: "billing",
+      path: "./global-channel.cjs"
+    });
+
+    eq(error.code, "NAMESPACE_ALREADY_REGISTERED", "code");
+    eq(
+      (error.details as { requestedBy: string }).requestedBy,
+      "path:./global-channel.cjs",
+      "requestedBy"
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "a claim made before a crashing script survives; the load still fails",
+  async t => {
+    fresh();
+
+    const error = await loadError({
+      namespace: "halfway",
+      path: "./throwing-global.mjs"
+    });
+
+    eq(error.code, "SCRIPT_LOAD_FAILED", "the load failed");
+    ok(error.message.includes("exploded after registering"), error.message);
+
+    deepEq(
+      registeredNamespaces().map(claim => claim.namespace),
+      ["halfway"],
+      "the claim was already made when the script threw"
+    );
+
+    t.log("finding: claims are made at registration time, not at load end — a script that registers and then throws leaves its namespace claimed (reload needs resetGraphScriptNamespaces)");
+  },
+  BIG
+);
+
+scripts.t(
+  "a script that throws is not replayed in the other format",
+  async t => {
+    fresh();
+
+    let executions = 0;
+
+    /* self-registration makes a replay detectable: the second run would
+     * hit the namespace freeze, and the counter proves the first */
+    const source = [
+      "globalThis.__replayProbe = (globalThis.__replayProbe || 0) + 1;",
+      "globalThis.GraphEngine.registerEngineNamespace('replayProbe', { probe: () => 1 });",
+      "throw new Error('fixture: fails after side effects');"
+    ].join("\n");
+
+    /* run the real probe: inline source, format auto (cjs → esm fallback
+     * would be attempted for a FORMAT error only) */
+    fresh();
+
+    let caught: GraphScriptError | undefined;
+
+    try {
+      await loadGraphScripts(doc([{ namespace: "replayProbe", source }]), {
+        baseDir: FIXTURES
+      });
+    } catch (thrown) {
+      caught = thrown as GraphScriptError;
+    }
+
+    executions = Number(
+      (globalThis as Record<string, unknown>).__replayProbe ?? 0
+    );
+
+    delete (globalThis as Record<string, unknown>).__replayProbe;
+
+    eq(caught?.code, "SCRIPT_LOAD_FAILED", "the load failed");
+    eq(executions, 1, "the script body ran EXACTLY once");
+
+    t.log("finding: format fallback replays the script body, so it is reserved for module-format failures (ERR_REQUIRE_ESM, ESM syntax in CJS). A script that throws — or registers and then throws — is never re-executed; it ran once and its claim stands");
+  },
+  BIG
+);
+
+/* ------------------------------ 4. merging & collisions ------------------------------ */
+
+scripts.t(
+  "two scripts providing the same name collide; override is opt-in",
+  async t => {
+    fresh();
+
+    const document = doc([
+      { namespace: "teamA", path: "./collide-a.cjs" },
+      { namespace: "teamB", path: "./collide-b.cjs" }
+    ]);
+
+    let error: GraphScriptError | undefined;
+
+    try {
+      await loadGraphScripts(document, { baseDir: FIXTURES });
+    } catch (thrown) {
+      error = thrown as GraphScriptError;
+    }
+
+    ok(error instanceof GraphScriptError, "a collision throws by default");
+    eq(error?.code, "FUNCTION_NAME_COLLISION", "code");
+    deepEq(
+      error?.details as { name: string; first: string; second: string },
+      { name: "shared", first: "teamA", second: "teamB" },
+      "the error names both sides"
+    );
+
+    /* claims made before the collision stay — that is the freeze working */
+    fresh();
+
+    const log = logCollector();
+
+    const loaded = await loadGraphScripts(document, {
+      baseDir: FIXTURES,
+      collisions: "override",
+      onLog: log.onLog
+    });
+
+    eq(
+      (loaded.functions.shared as () => string)(),
+      "from B",
+      "with override, the later script wins"
+    );
+    eq((loaded.functions.onlyA as () => string)(), "A", "the first script still contributed");
+    eq((loaded.functions.onlyB as () => string)(), "B", "and so did the second");
+    ok(
+      log.lines.some(line => line.message.includes("overrides")),
+      "the override is logged"
+    );
+
+    t.log("finding: claims and name collisions are separate gates — the freeze stops the namespace, collisions stop the merged table, and only the second one has an override");
+  },
+  BIG
+);
+
+/* ------------------------------ 5. validation ------------------------------ */
+
+scripts.t(
+  "script declarations are validated, with JSON paths",
+  async t => {
+    const cases: Array<[unknown, string]> = [
+      [{ namespace: "a" }, "scripts[0]"],
+      [
+        { namespace: "b", path: "./x.cjs", url: "https://x" },
+        "scripts[0]"
+      ],
+      [{ namespace: "c", path: "" }, "scripts[0].path"],
+      [{ namespace: "d", path: "./x.cjs", format: "wasm" }, "scripts[0].format"],
+      [{ namespace: "has space", path: "./x.cjs" }, "scripts[0].namespace"],
+      [{ namespace: "e", path: "./x.cjs", loader: "y" }, "scripts[0].loader"]
+    ];
+
+    for (const [declaration, expectedPath] of cases) {
+      try {
+        parseGraphJSONDocument(doc([declaration]));
+        throw new Error(`expected an issue for ${JSON.stringify(declaration)}`);
+      } catch (error) {
+        if (!(error instanceof GraphJSONError)) throw error;
+
+        ok(
+          error.issues.some(issue => issue.path === expectedPath),
+          `${expectedPath} missing from ${error.issues
+            .map(issue => issue.path)
+            .join(",")}`
+        );
+      }
+    }
+  },
+  BIG
+);
+
+scripts.t(
+  "the same namespace twice in one document is a parse issue",
+  async t => {
+    try {
+      parseGraphJSONDocument(
+        doc([
+          { namespace: "twice", path: "./a.cjs" },
+          { namespace: "twice", source: "module.exports = {};" }
+        ])
+      );
+      throw new Error("expected a GraphJSONError");
+    } catch (error) {
+      if (!(error instanceof GraphJSONError)) throw error;
+
+      eq(error.issues.length, 1, "one issue");
+      eq(error.issues[0].path, "scripts[1].namespace", "path");
+      ok(error.issues[0].message.includes("twice in this document"), error.issues[0].message);
+    }
+  },
+  BIG
+);
+
+scripts.t(
+  "a scripted document still parses with the v1.4 entry point",
+  async t => {
+    const document = doc([{ namespace: "parseOnly", path: "./order.cjs" }]);
+
+    const definition = parseGraphJSON(document);
+    const parsed = parseGraphJSONDocument(document);
+
+    deepEq(definition, parsed.definition, "parseGraphJSON is the definition alone");
+    eq(parsed.scripts.length, 1, "the declaration is surfaced");
+    deepEq(
+      parsed.scripts[0],
+      { namespace: "parseOnly", path: "./order.cjs" },
+      "declaration shape"
+    );
+    eq(Object.isFrozen(parsed.scripts), true, "scripts are frozen");
+
+    t.log("finding: `scripts` is validated by the isomorphic parser and executed by the Node loader — parseGraphJSON (sync, v1.4) keeps working on scripted documents");
+  },
+  BIG
+);
+
+scripts.t(
+  "the document is validated BEFORE any script executes",
+  async t => {
+    fresh();
+
+    const broken = doc([{ namespace: "neverRuns", path: "./order.cjs" }]);
+
+    /* break the graph, not the script */
+    (broken.nodes as Record<string, { next: string[] }>).a.next = ["ghost"];
+
+    let error: GraphJSONError | undefined;
+
+    try {
+      await loadGraphScripts(broken, { baseDir: FIXTURES });
+    } catch (thrown) {
+      error = thrown as GraphJSONError;
+    }
+
+    ok(error instanceof GraphJSONError, "the document is rejected");
+    ok(
+      error?.issues.some(issue => issue.path === "nodes.a.next[0]"),
+      error?.issues.map(issue => issue.path).join(",") ?? "no issues"
+    );
+    deepEq(
+      registeredNamespaces(),
+      [],
+      "no namespace was claimed: no code ran"
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "a missing file, a crashing script and a function-less script fail clearly",
+  async t => {
+    fresh();
+
+    const missing = await loadError({
+      namespace: "missing",
+      path: "./does-not-exist.cjs"
+    });
+    eq(missing.code, "SCRIPT_LOAD_FAILED", "missing code");
+    ok(missing.message.includes("not found"), missing.message);
+    ok(
+      (missing.details as { resolved: string }).resolved.includes("does-not-exist.cjs"),
+      "the resolved path is reported"
+    );
+
+    fresh();
+
+    const broken = await loadError({
+      namespace: "broken",
+      path: "./broken.cjs"
+    });
+    eq(broken.code, "SCRIPT_LOAD_FAILED", "broken code");
+    ok(broken.message.includes("fixture-broken"), "the cause message is kept");
+
+    fresh();
+
+    const empty = await loadError({
+      namespace: "empty",
+      path: "./empty.cjs"
+    });
+    eq(empty.code, "SCRIPT_NO_FUNCTIONS", "empty code");
+    ok(empty.message.includes("only non-function exports: answer"), empty.message);
+
+    fresh();
+
+    const silent = await loadError({
+      namespace: "silent",
+      source: "/* nothing at all */"
+    });
+    eq(silent.code, "SCRIPT_NO_FUNCTIONS", "silent code");
+    ok(silent.message.includes("never called registerEngineNamespace"), silent.message);
+  },
+  BIG
+);
+
+/* ------------------------------ 6. end to end ------------------------------ */
+
+scripts.t(
+  "a scripted document runs: the script provides the node and edge functions",
+  async t => {
+    fresh();
+
+    const document = {
+      id: "order-flow-scripted",
+      version: "1.5.0",
+      entryNodes: ["classify"],
+      terminalNodes: ["ship", "manual"],
+      completionPolicy: "FIRST_TERMINAL",
+      scripts: [{ namespace: "order", path: "./order.cjs" }],
+      nodes: {
+        classify: {
+          run: "classifyOrder",
+          next: [
+            { test: "isPriority", nextNode: "charge" },
+            { nextNode: "manual" }
+          ]
+        },
+        charge: {
+          run: "chargeCard",
+          next: ["ship"],
+          onThrow: "manual"
+        },
+        ship: { run: "shipOrder" },
+        manual: { run: "manualReview" }
+      }
+    };
+
+    const loaded = await loadGraphScripts(document, { baseDir: FIXTURES });
+    const engine = createEngineFromJSON(document, {
+      functions: loaded.functions,
+      lint: "error"
+    });
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "status");
+    deepEq(
+      report.results.map(result => result.nodeId),
+      ["classify", "charge", "ship"],
+      "path"
+    );
+    deepEq(
+      report.results.map(result => result.fn),
+      ["classifyOrder", "chargeCard", "shipOrder"],
+      "every activation names its script function"
+    );
+    eq(report.outputs.ship, "shipped", "output from the script");
+    deepEq(report.lintIssues, [], "lint-clean under lint: \"error\"");
+    eq(
+      report.registry?.fingerprint,
+      loaded.registry.fingerprint,
+      "the engine reports the identity of the loaded table"
+    );
+
+    t.log(
+      `finding: end-to-end, ${loaded.registry.names.length} functions arrive from ${loaded.scripts[0].source} and the engine reports ${loaded.registry.fingerprint}`
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "a script's own sibling requires resolve from the script's directory",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "sibling", path: "./needs-sibling.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(
+      (loaded.functions.usesSibling as () => string)(),
+      "sibling said hi",
+      "real require() with real relative resolution"
+    );
+  },
+  BIG
+);
+
+scripts.t(
+  "inline scripts compose with path scripts in one document",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([
+        { namespace: "filePart", path: "./cjs-default.js" },
+        {
+          namespace: "inlinePart",
+          source:
+            "globalThis.GraphEngine.registerEngineNamespace('inlinePart', " +
+            "{ inlineRegistered: () => 'via global' });"
+        }
+      ]),
+      { baseDir: FIXTURES }
+    );
+
+    deepEq(
+      loaded.namespaces,
+      ["filePart", "inlinePart"],
+      "declaration order"
+    );
+    deepEq(
+      loaded.registry.names,
+      ["inlineRegistered", "plainCjs"],
+      "merged table"
+    );
+    eq((loaded.functions.plainCjs as () => string)(), "plain cjs", "file part");
+    eq((loaded.functions.inlineRegistered as () => string)(), "via global", "inline part");
+
+    t.log("finding: the three media (path, source, url) are interchangeable — one pipeline merges them into a single table with one fingerprint");
+  },
+  BIG
+);
+
+scripts.t(
+  "the loaded table is frozen and the engine can be built from it directly",
+  async t => {
+    fresh();
+
+    const loaded = await loadGraphScripts(
+      doc([{ namespace: "frozen", path: "./order.cjs" }]),
+      { baseDir: FIXTURES }
+    );
+
+    eq(Object.isFrozen(loaded.functions), true, "frozen");
+    eq(Object.isFrozen(loaded.scripts), true, "scripts frozen");
+    eq(Object.isFrozen(loaded.namespaces), true, "namespaces frozen");
+
+    let mutated = false;
+
+    try {
+      (loaded.functions as Record<string, unknown>).sneaky = () => 1;
+    } catch {
+      mutated = true;
+    }
+
+    eq(
+      mutated || !("sneaky" in loaded.functions),
+      true,
+      "the table cannot be extended"
+    );
+
+    const engine = new GraphExecutionEngine(
+      {
+        id: "direct",
+        version: "1.0.0",
+        entryNodes: ["a"],
+        terminalNodes: ["a"],
+        nodes: { a: { id: "a", run: () => "direct" } }
+      },
+      { functions: loaded.functions }
+    );
+
+    const report = await engine.run();
+
+    eq(report.status, "COMPLETED", "engine built from the loaded table");
+    eq(report.registry?.fingerprint, loaded.registry.fingerprint, "same identity");
+  },
+  BIG
+);