automategraph 1.5.1 → 1.5.3

package/tests/unit.test.ts

@@ -0,0 +1,1192 @@
+/* ============================================================
+ * 100 UNIT TESTS
+ * Categories:
+ *   U-VAL  Validation (12)      U-ERR  Errors (9)
+ *   U-UTL  Utilities (10)       U-BUS  EventBus (12)
+ *   U-MEM  InMemoryStorage (8)  U-FRZ  Graph freezing (8)
+ *   U-LIF  Engine lifecycle (10) U-SCH  Execution / scheduler (20)
+ *   U-RTY  Retry (6)            U-CAN  Cancellation (5)
+ * ============================================================ */
+
+import {
+  AutomateGraphError,
+  EventBus,
+  GraphValidationError,
+  GraphExecutionEngine,
+  InMemoryStorage,
+  PluginInitializationError,
+  TimeoutError,
+  ErrorPolicy,
+  GraphDefinition,
+  NodeContext,
+  NodeDefinition,
+  StoragePlugin
+} from "../src/automategraph";
+
+import {
+  capture,
+  closeOnlyPlugin,
+  constNode,
+  g,
+  linear,
+  logCollector,
+  node,
+  plugin,
+  sleep,
+  SpyStorage,
+  tick
+} from "./helpers";
+
+import { suite } from "./harness";
+
+/* =========================================================
+ * 1. Graph validation — 12
+ * ========================================================= */
+
+const val = suite("unit", "Graph validation");
+
+val.t("throws GraphValidationError when graph.id is empty", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["a"], terminalNodes: ["a"], id: "" }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.code !== "GRAPH_VALIDATION_ERROR") throw new Error(error.code);
+    if (error.message !== "Graph id is required") throw new Error(error.message);
+  }
+});
+
+val.t("throws when graph.id is only whitespace", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["a"], terminalNodes: ["a"], id: "   " }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== "Graph id is required") throw new Error(error.message);
+  }
+});
+
+val.t("throws when graph.version is empty", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["a"], terminalNodes: ["a"], version: "" }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== "Graph version is required") throw new Error(error.message);
+  }
+});
+
+val.t("throws when there are no entry nodes", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: [], terminalNodes: ["a"] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== "At least one entry Node is required") throw new Error(error.message);
+  }
+});
+
+val.t("throws when there are no terminal nodes", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["a"], terminalNodes: [] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== "At least one terminal Node is required") throw new Error(error.message);
+  }
+});
+
+val.t("throws when a node key does not match Node.id", () => {
+  const definition: GraphDefinition = {
+    id: "mismatch",
+    version: "1",
+    entryNodes: ["key"],
+    terminalNodes: ["key"],
+    nodes: { key: { id: "other", run: () => 1 } }
+  };
+  try {
+    new GraphExecutionEngine(definition);
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (!/does not match Node\.id/.test(error.message)) throw new Error(error.message);
+  }
+});
+
+val.t("throws when next references an unknown node", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1, { next: ["ghost"] })], entryNodes: ["a"], terminalNodes: ["a"] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Node "a" references unknown next Node "ghost"') throw new Error(error.message);
+  }
+});
+
+val.t("throws when onThrow references an unknown node", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1, { onThrow: "doom" })], entryNodes: ["a"], terminalNodes: ["a"] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Node "a" references unknown ONTHROW target "doom"') throw new Error(error.message);
+  }
+});
+
+val.t("throws when node timeoutMs is zero", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1, { timeoutMs: 0 })], entryNodes: ["a"], terminalNodes: ["a"] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Node "a" timeout must be positive') throw new Error(error.message);
+  }
+});
+
+val.t("throws when node timeoutMs is negative", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1, { timeoutMs: -5 })], entryNodes: ["a"], terminalNodes: ["a"] }));
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Node "a" timeout must be positive') throw new Error(error.message);
+  }
+});
+
+val.t("throws when retry.maxAttempts is not an integer", () => {
+  try {
+    new GraphExecutionEngine(
+      g({ nodes: [node("a", () => 1, { retry: { maxAttempts: 1.5 } })], entryNodes: ["a"], terminalNodes: ["a"] })
+    );
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Node "a" retry.maxAttempts must be >= 1') throw new Error(error.message);
+  }
+});
+
+val.t("throws when entry or terminal node is unknown", () => {
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["nope"], terminalNodes: ["a"] }));
+    throw new Error("expected throw for entry");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Unknown entry Node "nope"') throw new Error(error.message);
+  }
+
+  try {
+    new GraphExecutionEngine(g({ nodes: [node("a", () => 1)], entryNodes: ["a"], terminalNodes: ["nope"] }));
+    throw new Error("expected throw for terminal");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (error.message !== 'Unknown terminal Node "nope"') throw new Error(error.message);
+  }
+});
+
+/* =========================================================
+ * 2. Error classes & utilities — 9 + 10 = 19
+ * ========================================================= */
+
+const err = suite("unit", "Error classes & utilities");
+
+err.t("AutomateGraphError carries message, code and details", () => {
+  const error = new AutomateGraphError("boom", "BOOM", { a: 1 });
+  if (error.name !== "AutomateGraphError") throw new Error(error.name);
+  if (error.code !== "BOOM") throw new Error(error.code);
+  if (error.message !== "boom") throw new Error(error.message);
+  if (!(error instanceof Error)) throw new Error("not an Error");
+  if ((error.details as { a: number }).a !== 1) throw new Error("details lost");
+});
+
+err.t("GraphValidationError uses the GRAPH_VALIDATION_ERROR code", () => {
+  const error = new GraphValidationError("bad graph", { hint: true });
+  if (error.code !== "GRAPH_VALIDATION_ERROR") throw new Error(error.code);
+  if (error.name !== "GraphValidationError") throw new Error(error.name);
+  if (!(error instanceof GraphValidationError)) throw new Error("instanceof");
+});
+
+err.t("TimeoutError composes a readable message and details", () => {
+  const error = new TimeoutError("slow", 250);
+  if (error.name !== "TimeoutError") throw new Error(error.name);
+  if (error.code !== "NODE_TIMEOUT") throw new Error(error.code);
+  if (error.message !== 'Node "slow" exceeded timeout of 250ms') throw new Error(error.message);
+  const details = error.details as { nodeId: string; timeoutMs: number };
+  if (details.nodeId !== "slow" || details.timeoutMs !== 250) throw new Error("bad details");
+});
+
+err.t("PluginInitializationError reports the plugin id and keeps the cause", () => {
+  const cause = new Error("db down");
+  const error = new PluginInitializationError("billing", cause);
+  if (error.code !== "PLUGIN_INITIALIZATION_ERROR") throw new Error(error.code);
+  if (error.message !== 'Required plugin "billing" failed to initialize') throw new Error(error.message);
+  if (error.details !== cause) throw new Error("cause not preserved");
+});
+
+err.t("inheritance chain: TimeoutError -> AutomateGraphError -> Error", () => {
+  const error = new TimeoutError("n", 1);
+  if (!(error instanceof TimeoutError)) throw new Error("self");
+  if (!(error instanceof AutomateGraphError)) throw new Error("parent");
+  if (!(error instanceof Error)) throw new Error("root");
+});
+
+err.t("PluginInitializationError is an AutomateGraphError", () => {
+  const error = new PluginInitializationError("p", new Error("x"));
+  if (!(error instanceof AutomateGraphError)) throw new Error("not graph error");
+  if (!(error instanceof Error)) throw new Error("not error");
+});
+
+err.t("AutomateGraphError is not a GraphValidationError (distinct subclass)", () => {
+  const error = new AutomateGraphError("x", "X");
+  if (error instanceof GraphValidationError) throw new Error("unexpected subtype");
+});
+
+err.t("AutomateGraphError allows optional details to be omitted", () => {
+  const error = new AutomateGraphError("x", "X");
+  if (error.details !== undefined) throw new Error("details should be undefined");
+});
+
+err.t("Error classes expose stable constructor.name values", () => {
+  if (AutomateGraphError.name !== "AutomateGraphError") throw new Error("1");
+  if (GraphValidationError.name !== "GraphValidationError") throw new Error("2");
+  if (TimeoutError.name !== "TimeoutError") throw new Error("3");
+  if (PluginInitializationError.name !== "PluginInitializationError") throw new Error("4");
+});
+
+const util = suite("unit", "Utilities");
+
+util.t("engine executionId is a stable 36-char UUID-ish string", () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const id = engine.getExecutionId();
+  if (typeof id !== "string") throw new Error("type");
+  if (id.length !== 36) throw new Error(`length ${id.length}`);
+  if (engine.getExecutionId() !== id) throw new Error("unstable");
+});
+
+util.t("executionIds are unique across engines", () => {
+  const a = new GraphExecutionEngine(linear(["a"])).getExecutionId();
+  const b = new GraphExecutionEngine(linear(["a"])).getExecutionId();
+  if (a === b) throw new Error("collision");
+});
+
+util.t("report.startedAt is an ISO-8601 timestamp", async () => {
+  const report = await new GraphExecutionEngine(linear(["a"])).run();
+  const parsed = Date.parse(report.startedAt);
+  if (Number.isNaN(parsed)) throw new Error("not a date");
+  if (new Date(report.startedAt).toISOString() !== report.startedAt) throw new Error("not ISO");
+});
+
+util.t("report.finishedAt >= report.startedAt", async () => {
+  const report = await new GraphExecutionEngine(linear(["a"])).run();
+  if (Date.parse(report.finishedAt) < Date.parse(report.startedAt)) throw new Error("time travel");
+});
+
+util.t("node result startedAt <= finishedAt", async () => {
+  const report = await new GraphExecutionEngine(linear(["a"])).run();
+  const result = report.results[0];
+  if (Date.parse(result.finishedAt!) < Date.parse(result.startedAt!)) throw new Error("time travel");
+});
+
+util.t("error records carry ISO timestamps", async () => {
+  const definition = linear(["a", "t"], (id) => {
+    if (id === "a") throw new Error("x");
+    return id;
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  for (const record of report.errors) {
+    if (new Date(record.timestamp).toISOString() !== record.timestamp) throw new Error("bad ts");
+  }
+});
+
+util.t("string throws are converted to Error instances", async () => {
+  const definition = g({
+    nodes: [node("a", () => { throw "plain-string-failure"; })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.errors[0].message !== "plain-string-failure") throw new Error(report.errors[0].message);
+  if (report.errors[0].code !== "NODE_EXECUTION_ERROR") throw new Error(report.errors[0].code);
+});
+
+util.t("throwing a non-Error object stringifies via toError", async () => {
+  const definition = g({
+    nodes: [node("a", () => { throw { weird: true }; })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.errors[0].message !== "[object Object]") throw new Error(report.errors[0].message);
+});
+
+util.t("error records expose a stack trace for real errors", async () => {
+  const definition = g({
+    nodes: [node("a", () => { throw new Error("with stack"); })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (!report.errors[0].stack || !report.errors[0].stack!.includes("with stack")) {
+    throw new Error("missing stack");
+  }
+});
+
+util.t("graph id/version of the report mirror the definition", async () => {
+  const definition = g({
+    id: "billing-flow",
+    version: "2.3.4",
+    nodes: [constNode("a", 1)],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.graphId !== "billing-flow") throw new Error(report.graphId);
+  if (report.graphVersion !== "2.3.4") throw new Error(report.graphVersion);
+});
+
+/* =========================================================
+ * 3. EventBus — 12
+ * ========================================================= */
+
+const bus = suite("unit", "EventBus");
+
+bus.t("emit with no listeners resolves", async () => {
+  const target = new EventBus();
+  await target.emit("nothing");
+});
+
+bus.t("required listeners receive the payload and are awaited", async () => {
+  const target = new EventBus();
+  const seen: unknown[] = [];
+  target.on("e", async payload => {
+    await sleep(5);
+    seen.push(payload);
+  }, { required: true });
+
+  await target.emit("e", { n: 1 });
+  if (seen.length !== 1) throw new Error("not awaited");
+  if ((seen[0] as { n: number }).n !== 1) throw new Error("payload lost");
+});
+
+bus.t("required listeners run in registration order", async () => {
+  const target = new EventBus();
+  const order: number[] = [];
+  for (const index of [1, 2, 3]) {
+    target.on("e", async () => { order.push(index); }, { required: true });
+  }
+  await target.emit("e");
+  if (order.join(",") !== "1,2,3") throw new Error(order.join(","));
+});
+
+bus.t("plain listeners are NOT awaited — emit resolves first", async () => {
+  const target = new EventBus();
+  let handled = false;
+  target.on("e", async () => {
+    await sleep(30);
+    handled = true;
+  });
+  await target.emit("e");
+  if (handled) throw new Error("emit wrongly awaited a non-required listener");
+  await sleep(60);
+  if (!handled) throw new Error("listener never ran");
+});
+
+bus.t("unsubscribe stops delivery", async () => {
+  const target = new EventBus();
+  let count = 0;
+  const off = target.on("e", () => { count += 1; }, { required: true });
+  await target.emit("e");
+  off();
+  await target.emit("e");
+  if (count !== 1) throw new Error(`count=${count}`);
+});
+
+bus.t("unsubscribing the last listener removes the event key", () => {
+  const target = new EventBus();
+  const off = target.on("e", () => undefined);
+  off();
+  // @ts-expect-error — inspecting private state intentionally
+  const listeners: Map<string, unknown> = target.listeners;
+  if (listeners.has("e")) throw new Error("key retained");
+});
+
+bus.t("duplicate handlers registered as distinct listeners both fire", async () => {
+  const target = new EventBus();
+  let count = 0;
+  const handler = () => { count += 1; };
+  target.on("e", handler, { required: true });
+  target.on("e", handler, { required: true });
+  await target.emit("e");
+  if (count !== 2) throw new Error(`count=${count}`);
+});
+
+bus.t("a throwing plain listener does not reject emit (isolated)", async () => {
+  const { lines, onLog } = logCollector();
+  const target = new EventBus(onLog);
+  target.on("e", () => { throw new Error("listener blew up"); });
+  await target.emit("e");
+  await tick();
+  await sleep(10);
+});
+
+bus.t("a failing plain listener is reported through onLog", async () => {
+  const { lines, onLog } = logCollector();
+  const target = new EventBus(onLog);
+  target.on("e", () => { throw new Error("kaboom"); });
+  await target.emit("e");
+  await sleep(15);
+  const found = lines.find(line => line.message === "Non-critical event listener failed: e");
+  if (!found) throw new Error("not reported");
+  if (found.level !== "error") throw new Error(found.level);
+  if ((found.details as Error).message !== "kaboom") throw new Error("cause lost");
+});
+
+bus.t("a throwing REQUIRED listener propagates to the emitter", async () => {
+  const target = new EventBus();
+  target.on("e", () => { throw new Error("required-fail"); }, { required: true });
+  try {
+    await target.emit("e");
+    throw new Error("expected rejection");
+  } catch (error) {
+    if ((error as Error).message !== "required-fail") throw error;
+  }
+});
+
+bus.t("mixed required/plain: required first, plain afterwards (async)", async () => {
+  const target = new EventBus();
+  const order: string[] = [];
+  target.on("e", async () => { order.push("plain"); });
+  target.on("e", async () => { order.push("required"); }, { required: true });
+  await target.emit("e");
+  await sleep(20);
+  if (order.join(",") !== "required,plain") throw new Error(order.join(","));
+});
+
+bus.t("clear() removes every listener", async () => {
+  const target = new EventBus();
+  let count = 0;
+  target.on("a", () => { count += 1; }, { required: true });
+  target.on("b", () => { count += 1; }, { required: true });
+  target.clear();
+  await target.emit("a");
+  await target.emit("b");
+  if (count !== 0) throw new Error(`count=${count}`);
+});
+
+/* =========================================================
+ * 4. InMemoryStorage — 8
+ * ========================================================= */
+
+const mem = suite("unit", "InMemoryStorage");
+
+function sampleSnapshot(overrides: Partial<Parameters<InMemoryStorage["saveAtomic"]>[0]> = {}) {
+  return {
+    executionId: "exec-1",
+    graphId: "graph-1",
+    graphVersion: "1.0.0",
+    status: "RUNNING" as const,
+    outputs: { a: 1 },
+    results: [{ nodeId: "a", activationId: "act", status: "SUCCEEDED" as const, attempt: 1 }],
+    errors: [],
+    pluginVersions: { p: "1.0.0" },
+    timestamp: new Date().toISOString(),
+    ...overrides
+  };
+}
+
+mem.t("storage advertises a stable id and version", () => {
+  const storage = new InMemoryStorage();
+  if (storage.id !== "automategraph.memory-storage") throw new Error(storage.id);
+  // v1.1: the reference adapter gained list/delete/close and capabilities.
+  if (storage.version !== "1.1.0") throw new Error(storage.version);
+});
+
+mem.t("load returns null for an unknown executionId", async () => {
+  const storage = new InMemoryStorage();
+  const loaded = await storage.load("missing");
+  if (loaded !== null) throw new Error("expected null");
+});
+
+mem.t("saveAtomic then load returns the snapshot", async () => {
+  const storage = new InMemoryStorage();
+  await storage.saveAtomic(sampleSnapshot());
+  const loaded = await storage.load("exec-1");
+  if (!loaded) throw new Error("not found");
+  if (loaded.graphId !== "graph-1") throw new Error(loaded.graphId);
+});
+
+mem.t("saveAtomic deep-copies the incoming snapshot (caller later mutates)", async () => {
+  const storage = new InMemoryStorage();
+  const snapshot = sampleSnapshot();
+  await storage.saveAtomic(snapshot);
+
+  snapshot.outputs.a = 999;
+  snapshot.results.push({ nodeId: "b", activationId: "x", status: "FAILED", attempt: 1 });
+
+  const loaded = await storage.load("exec-1");
+  if (!loaded) throw new Error("not found");
+  if (loaded.outputs.a !== 1) throw new Error("outputs aliased");
+  if (loaded.results.length !== 1) throw new Error("results aliased");
+});
+
+mem.t("load returns an isolated copy (mutation of the returned object is inert)", async () => {
+  const storage = new InMemoryStorage();
+  await storage.saveAtomic(sampleSnapshot());
+  const first = await storage.load("exec-1");
+  first!.results.length = 0;
+  first!.outputs.a = -1;
+
+  const second = await storage.load("exec-1");
+  if (second!.results.length !== 1) throw new Error("results not isolated");
+  if (second!.outputs.a !== 1) throw new Error("outputs not isolated");
+});
+
+mem.t("repeated saves replace the previous snapshot", async () => {
+  const storage = new InMemoryStorage();
+  await storage.saveAtomic(sampleSnapshot({ outputs: { a: 1 } }));
+  await storage.saveAtomic(sampleSnapshot({ outputs: { a: 2 }, status: "COMPLETED" as never }));
+  const loaded = await storage.load("exec-1");
+  if (loaded!.outputs.a !== 2) throw new Error("not replaced");
+  if (loaded!.status !== "COMPLETED") throw new Error("status stale");
+});
+
+mem.t("snapshots for different executions stay isolated", async () => {
+  const storage = new InMemoryStorage();
+  await storage.saveAtomic(sampleSnapshot({ executionId: "e1" }));
+  await storage.saveAtomic(sampleSnapshot({ executionId: "e2", graphId: "other" }));
+  const one = await storage.load("e1");
+  const two = await storage.load("e2");
+  if (one!.graphId !== "graph-1") throw new Error("e1 crossed");
+  if (two!.graphId !== "other") throw new Error("e2 crossed");
+});
+
+mem.t("concurrent saveAtomic calls never interleave partial data", async () => {
+  const storage = new InMemoryStorage();
+  await Promise.all(
+    Array.from({ length: 50 }, (_, index) =>
+      storage.saveAtomic(sampleSnapshot({ outputs: { marker: index } }))
+    )
+  );
+  const loaded = await storage.load("exec-1");
+  if (typeof loaded!.outputs.marker !== "number") throw new Error("torn snapshot");
+});
+
+/* =========================================================
+ * 5. Graph freezing — 8
+ * ========================================================= */
+
+const frz = suite("unit", "Graph freezing");
+
+function frozenGraph(): GraphDefinition {
+  return linear(["a", "b"]);
+}
+
+frz.t("getGraphDefinition returns a frozen object", () => {
+  const engine = new GraphExecutionEngine(frozenGraph());
+  if (!Object.isFrozen(engine.getGraphDefinition())) throw new Error("not frozen");
+});
+
+frz.t("entryNodes and terminalNodes arrays are frozen", () => {
+  const engine = new GraphExecutionEngine(frozenGraph());
+  const graph = engine.getGraphDefinition();
+  if (!Object.isFrozen(graph.entryNodes)) throw new Error("entryNodes");
+  if (!Object.isFrozen(graph.terminalNodes)) throw new Error("terminalNodes");
+});
+
+frz.t("the nodes record is frozen", () => {
+  const engine = new GraphExecutionEngine(frozenGraph());
+  if (!Object.isFrozen(engine.getGraphDefinition().nodes)) throw new Error("nodes not frozen");
+});
+
+frz.t("mutating the definition after construction does not affect the engine", async () => {
+  const definition = linear(["a", "b"]);
+  const engine = new GraphExecutionEngine(definition);
+  (definition.nodes as Record<string, unknown>).c = constNode("c", "injected");
+  definition.entryNodes as unknown as string[]; // (frozen copy) — no-op
+  const report = await engine.run();
+  if (report.outputs.c !== undefined) throw new Error("injection took effect");
+  if (report.results.some(result => result.nodeId === "c")) throw new Error("ghost node ran");
+});
+
+frz.t("mutating a node's next array after construction is ignored", async () => {
+  const definition = linear(["a", "b"]);
+  const engine = new GraphExecutionEngine(definition);
+  (definition.nodes.a.next as unknown as string[]).push("b");
+  const report = await engine.run();
+  if (report.results.length !== 2) throw new Error(`results=${report.results.length}`);
+});
+
+frz.t("getGraphDefinition is referentially identical across calls", () => {
+  const engine = new GraphExecutionEngine(frozenGraph());
+  if (engine.getGraphDefinition() !== engine.getGraphDefinition()) throw new Error("not identical");
+});
+
+frz.t("deep-frozen graphs are accepted (idempotent freezing)", async () => {
+  const definition = linear(["a"]);
+  Object.freeze(definition);
+  Object.freeze(definition.nodes);
+  const engine = new GraphExecutionEngine(definition);
+  const report = await engine.run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+});
+
+frz.t("frozen node objects reject mutation at runtime (strict mode)", () => {
+  const engine = new GraphExecutionEngine(frozenGraph());
+  const target = engine.getGraphDefinition().nodes.a as { id: string };
+  try {
+    target.id = "hacked";
+  } catch {
+    /* expected in strict mode, ESM emit is strict */
+  }
+  if (target.id !== "a") throw new Error("mutation succeeded");
+});
+
+/* =========================================================
+ * 6. Engine lifecycle — 10
+ * ========================================================= */
+
+const life = suite("unit", "Engine lifecycle");
+
+life.t("getState() is CREATED before run()", () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  if (engine.getState() !== "CREATED") throw new Error(engine.getState());
+});
+
+life.t("calling run() twice throws EXECUTION_ALREADY_STARTED", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const promise = engine.run();
+  try {
+    engine.run();
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof AutomateGraphError)) throw error;
+    if (error.code !== "EXECUTION_ALREADY_STARTED") throw new Error(error.code);
+  }
+  await promise;
+});
+
+life.t("run() returns a Promise", () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const promise = engine.run();
+  if (typeof (promise as Promise<unknown>).then !== "function") throw new Error("not a promise");
+  return promise;
+});
+
+life.t("read-only accessors return defensive copies of errors", async () => {
+  const definition = g({
+    nodes: [node("a", () => { throw new Error("x"); })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const engine = new GraphExecutionEngine(definition);
+  await engine.run();
+  const first = engine.getErrors();
+  if (first.length !== 1) throw new Error("expected one error");
+  (first as Array<unknown>).length = 0;
+  if (engine.getErrors().length !== 1) throw new Error("internal array leaked");
+});
+
+life.t("read-only accessors return defensive copies of results", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  await engine.run();
+  const first = engine.getResults();
+  first[0].nodeId = "tampered";
+  if (engine.getResults()[0].nodeId !== "a") throw new Error("internal object leaked");
+});
+
+life.t("duplicate plugin ids are rejected with DUPLICATE_PLUGIN", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]), {
+    plugins: [plugin({ id: "dup" }), plugin({ id: "dup", onInitialize: () => undefined })]
+  });
+  const report = await engine.run();
+  if (report.status !== "REJECTED") throw new Error(report.status);
+  if (report.errors[0].code !== "DUPLICATE_PLUGIN") throw new Error(report.errors[0].code);
+});
+
+life.t("a plugin reusing the storage id is rejected in the constructor", () => {
+  const storage = new InMemoryStorage();
+  try {
+    new GraphExecutionEngine(linear(["a"]), {
+      storage,
+      plugins: [plugin({ id: storage.id })]
+    });
+    throw new Error("expected throw");
+  } catch (error) {
+    if (!(error instanceof GraphValidationError)) throw error;
+    if (!/already reserved by Storage/.test(error.message)) throw new Error(error.message);
+  }
+});
+
+life.t("optional plugin failure is tolerated and logged", async () => {
+  const { lines, onLog } = logCollector();
+  const events: string[] = [];
+  const engine = new GraphExecutionEngine(linear(["a"]), {
+    onLog,
+    plugins: [
+      plugin({
+        id: "optional-broken",
+        required: false,
+        onInitialize: () => { throw new Error("no creds"); }
+      }),
+      plugin({ id: "healthy", onInitialize: () => { events.push("healthy-up"); } })
+    ]
+  });
+  const report = await engine.run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+  if (!lines.some(line => line.message === "Plugin initialization failed: optional-broken")) {
+    throw new Error("not logged");
+  }
+  if (events.includes("healthy-up") !== true) throw new Error("healthy plugin skipped");
+});
+
+life.t("a required plugin failure REJECTS the run and shuts down initialized plugins", async () => {
+  const events: string[] = [];
+  const engine = new GraphExecutionEngine(linear(["a"]), {
+    plugins: [
+      plugin({ id: "first", onInitialize: () => { events.push("first-up"); }, onClose: () => { events.push("first-down"); } }),
+      plugin({ id: "second", required: true, onInitialize: () => { throw new Error("fatal"); } })
+    ]
+  });
+  const report = await engine.run();
+  if (report.status !== "REJECTED") throw new Error(report.status);
+  if (report.errors[0].code !== "PLUGIN_INITIALIZATION_ERROR") throw new Error(report.errors[0].code);
+  if (!events.includes("first-down")) throw new Error("prior plugin not closed");
+  if (report.results.length !== 0) throw new Error("nodes ran after rejection");
+});
+
+life.t("plugins close in reverse initialization order after a successful run", async () => {
+  const events: string[] = [];
+  const engine = new GraphExecutionEngine(linear(["a"]), {
+    plugins: [
+      plugin({ id: "p1", onClose: () => { events.push("close-1"); } }),
+      plugin({ id: "p2", onClose: () => { events.push("close-2"); } }),
+      plugin({ id: "p3", onClose: () => { events.push("close-3"); } })
+    ]
+  });
+  await engine.run();
+  const closes = events.filter(event => event.startsWith("close-"));
+  if (closes.join(",") !== "close-3,close-2,close-1") throw new Error(closes.join(","));
+});
+
+/* =========================================================
+ * 7. Execution & scheduler — 20
+ * ========================================================= */
+
+const sch = suite("unit", "Execution & scheduler");
+
+sch.t("single-node graph completes and stores its output", async () => {
+  const report = await new GraphExecutionEngine(linear(["a"], () => 42)).run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+  if (report.outputs.a !== 42) throw new Error(String(report.outputs.a));
+  if (!report.logicallyCompleted) throw new Error("logicallyCompleted=false");
+});
+
+sch.t("linear graph runs every node in order", async () => {
+  const order: string[] = [];
+  const report = await new GraphExecutionEngine(linear(["a", "b", "c"], id => { order.push(id); return id; })).run();
+  if (order.join(",") !== "a,b,c") throw new Error(order.join(","));
+  if (report.results.length !== 3) throw new Error(`results=${report.results.length}`);
+});
+
+sch.t("diamond graph fans out and converges", async () => {
+  const definition = g({
+    nodes: [
+      node("a", () => "A", { next: ["b", "c"] }),
+      constNode("b", "B", { next: ["d"] }),
+      constNode("c", "C", { next: ["d"] }),
+      constNode("d", "D")
+    ],
+    entryNodes: ["a"],
+    terminalNodes: ["d"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+  const dRuns = report.results.filter(result => result.nodeId === "d").length;
+  if (dRuns !== 2) throw new Error(`d ran ${dRuns} times (expected per-activation fan-in)`);
+});
+
+sch.t("independent entry nodes both execute", async () => {
+  const definition = g({
+    nodes: [constNode("a", "A"), constNode("b", "B")],
+    entryNodes: ["a", "b"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  const ran = new Set(report.results.map(result => result.nodeId));
+  if (!ran.has("a") || !ran.has("b")) throw new Error([...ran].join(","));
+});
+
+sch.t("multiple terminal nodes are both recognized", async () => {
+  const definition = g({
+    nodes: [node("a", () => "A", { next: ["b", "c"] }), constNode("b", "B"), constNode("c", "C")],
+    entryNodes: ["a"],
+    terminalNodes: ["b", "c"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+});
+
+sch.t("node context exposes execution metadata", async () => {
+  let seen: Record<string, unknown> = {};
+  const definition = g({
+    nodes: [
+      node("a", context => {
+        seen = {
+          executionId: context.executionId,
+          graphId: context.graphId,
+          nodeId: context.nodeId,
+          attempt: context.attempt,
+          hasSignal: context.signal instanceof AbortSignal
+        };
+        return "ok";
+      })
+    ],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const engine = new GraphExecutionEngine(definition);
+  await engine.run();
+  if (seen.executionId !== engine.getExecutionId()) throw new Error("executionId");
+  if (seen.graphId !== "test-graph") throw new Error(String(seen.graphId));
+  if (seen.nodeId !== "a") throw new Error(String(seen.nodeId));
+  if (seen.attempt !== 1) throw new Error(String(seen.attempt));
+  if (seen.hasSignal !== true) throw new Error("signal missing");
+});
+
+sch.t("activationId is unique per activation", async () => {
+  const definition = g({
+    nodes: [node("a", () => 1, { next: ["b"] }), constNode("b", 2)],
+    entryNodes: ["a"],
+    terminalNodes: ["b"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  const ids = report.results.map(result => result.activationId);
+  if (new Set(ids).size !== ids.length) throw new Error("duplicate activationIds");
+});
+
+sch.t("node output can be read from a successor's context.outputs", async () => {
+  let observed: unknown;
+  const definition = g({
+    nodes: [
+      constNode("a", { value: 7 }, { next: ["b"] }),
+      node("b", context => { observed = context.outputs.a; return null; })
+    ],
+    entryNodes: ["a"],
+    terminalNodes: ["b"]
+  });
+  await new GraphExecutionEngine(definition).run();
+  if ((observed as { value: number }).value !== 7) throw new Error("output not propagated");
+});
+
+sch.t("context.outputs freezing blocks mutation (strict runtime)", async () => {
+  let threw = false;
+  const definition = g({
+    nodes: [
+      constNode("a", 1, { next: ["b"] }),
+      node("b", context => {
+        try {
+          (context.outputs as Record<string, unknown>).b = 2;
+        } catch {
+          threw = true;
+        }
+        return null;
+      })
+    ],
+    entryNodes: ["a"],
+    terminalNodes: ["b"]
+  });
+  await new GraphExecutionEngine(definition).run();
+  if (!threw) throw new Error("outputs not frozen");
+});
+
+sch.t("async node functions are awaited", async () => {
+  const definition = g({
+    nodes: [node("a", async () => { await sleep(15); return "late"; })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.outputs.a !== "late") throw new Error(String(report.outputs.a));
+});
+
+sch.t("reaching the terminal marks logicallyCompleted and stops scheduling", async () => {
+  const definition = g({
+    nodes: [node("a", () => "A", { next: ["b"] }), constNode("b", "B", { next: ["c"] }), constNode("c", "C")],
+    entryNodes: ["a"],
+    terminalNodes: ["b"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (!report.logicallyCompleted) throw new Error("not completed logically");
+  if (report.results.some(result => result.nodeId === "c")) throw new Error("c ran past the terminal");
+});
+
+sch.t("the graph exhausts without a terminal => FAILED + GRAPH_TERMINAL_NOT_REACHED", async () => {
+  const definition = g({
+    // "sink" is a declared terminal node that nothing ever routes to;
+    // "a" runs with no successor, so executable work is exhausted.
+    nodes: [constNode("a", "dead-end"), constNode("sink", "unreachable")],
+    entryNodes: ["a"],
+    terminalNodes: ["sink"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.status !== "FAILED") throw new Error(report.status);
+  const codes = report.errors.map(error => error.code);
+  if (!codes.includes("GRAPH_TERMINAL_NOT_REACHED")) throw new Error(codes.join(","));
+});
+
+sch.t("node.started / node.succeeded events fire with payloads", async () => {
+  const definition = linear(["a", "b"]);
+  const engine = new GraphExecutionEngine(definition);
+  const captured = capture(engine, ["graph.ready", "node.started", "node.succeeded", "graph.logicallyCompleted", "graph.finished"]);
+  await engine.run();
+  const names = captured.map(entry => entry.event);
+  if (names[0] !== "graph.ready") throw new Error(names[0]);
+  if (!names.includes("node.started") || !names.includes("node.succeeded")) throw new Error(names.join(","));
+  if (names[names.length - 1] !== "graph.finished") throw new Error(names[names.length - 1]);
+  const started = captured.find(entry => entry.event === "node.started")!.payload as { attempt: number };
+  if (started.attempt !== 1) throw new Error("bad attempt");
+});
+
+sch.t("node.started precedes node.succeeded per node", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const captured = capture(engine, ["node.started", "node.succeeded"]);
+  await engine.run();
+  if (captured[0].event !== "node.started" || captured[1].event !== "node.succeeded") {
+    throw new Error(captured.map(c => c.event).join(","));
+  }
+});
+
+sch.t("context.emit() forwards to the bus", async () => {
+  const seen: unknown[] = [];
+  const definition = g({
+    nodes: [node("a", async context => { await context.emit("custom.event", { hi: true }); return 1; })],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const engine = new GraphExecutionEngine(definition);
+  engine.events.on("custom.event", payload => { seen.push(payload); }, { required: true });
+  await engine.run();
+  if ((seen[0] as { hi: boolean }).hi !== true) throw new Error("payload lost");
+});
+
+sch.t("checkpoints are written once per successful node by default", async () => {
+  const storage = new SpyStorage();
+  const definition = linear(["a", "b", "c"]);
+  await new GraphExecutionEngine(definition, { storage }).run();
+  if (storage.calls !== 3) throw new Error(`checkpoints=${storage.calls}`);
+});
+
+sch.t("checkpointEveryNode: false disables node checkpoints", async () => {
+  const storage = new SpyStorage();
+  const definition = linear(["a", "b", "c"], undefined, { checkpointEveryNode: false });
+  await new GraphExecutionEngine(definition, { storage }).run();
+  if (storage.calls !== 0) throw new Error(`checkpoints=${storage.calls}`);
+});
+
+sch.t("snapshots record outputs, plugin versions and the execution id", async () => {
+  const storage = new SpyStorage();
+  const engine = new GraphExecutionEngine(linear(["a", "b"], (id) => `${id}!`), {
+    storage,
+    plugins: [plugin({ id: "metrics-plugin", version: "4.5.6" })]
+  });
+  const report = await engine.run();
+  const snapshot = storage.snapshots[storage.snapshots.length - 1];
+  if (snapshot.executionId !== report.executionId) throw new Error("executionId");
+  if (snapshot.outputs.a !== "a!" || snapshot.outputs.b !== "b!") throw new Error("outputs missing");
+  if (snapshot.pluginVersions["metrics-plugin"] !== "4.5.6") throw new Error("plugin versions missing");
+  if (snapshot.status !== "RUNNING") throw new Error(`status=${snapshot.status}`);
+});
+
+sch.t("successful run yields zero errors and cloneable outputs", async () => {
+  const report = await new GraphExecutionEngine(linear(["a", "b"])).run();
+  if (report.errors.length !== 0) throw new Error(String(report.errors.length));
+  const clone = JSON.parse(JSON.stringify(report.outputs));
+  if (clone.a !== "a-out") throw new Error("clone failed");
+});
+
+sch.t("node.started listener sees the context emitted by NodeContext.emit", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const captured = capture(engine, ["node.started"]);
+  await engine.run();
+  const payload = captured[0].payload as { executionId: string; activationId: string };
+  if (payload.executionId !== engine.getExecutionId()) throw new Error("bad executionId");
+  if (typeof payload.activationId !== "string") throw new Error("bad activationId");
+});
+
+/* =========================================================
+ * 8. Retry — 6
+ * ========================================================= */
+
+const rty = suite("unit", "Retry");
+
+rty.t("errorPolicy RETRY re-runs until success and records the final attempt", async () => {
+  let attempts = 0;
+  const definition = g({
+    nodes: [
+      node("flaky", () => {
+        attempts += 1;
+        if (attempts < 3) throw new Error(`fail-${attempts}`);
+        return "recovered";
+      }, { retry: { maxAttempts: 3, delayMs: 1 }, errorPolicy: "RETRY" })
+    ],
+    entryNodes: ["flaky"],
+    terminalNodes: ["flaky"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (attempts !== 3) throw new Error(`attempts=${attempts}`);
+  if (report.results[0].attempt !== 3) throw new Error(`attempt=${report.results[0].attempt}`);
+  if (report.results[0].status !== "SUCCEEDED") throw new Error(report.results[0].status);
+  if (report.errors.length !== 0) throw new Error("errors recorded despite recovery");
+});
+
+rty.t("RETRY respects delayMs between attempts", async () => {
+  const marks: number[] = [];
+  const definition = g({
+    nodes: [
+      node("flaky", () => {
+        marks.push(Date.now());
+        if (marks.length < 3) throw new Error("again");
+        return "ok";
+      }, { retry: { maxAttempts: 3, delayMs: 40 }, errorPolicy: "RETRY" })
+    ],
+    entryNodes: ["flaky"],
+    terminalNodes: ["flaky"]
+  });
+  await new GraphExecutionEngine(definition).run();
+  const firstGap = marks[1] - marks[0];
+  if (firstGap < 30) throw new Error(`gap=${firstGap}ms (delay ignored)`);
+});
+
+rty.t("exhausting maxAttempts records one unhandled error and terminates", async () => {
+  let attempts = 0;
+  const definition = g({
+    nodes: [
+      node("always-fails", () => { attempts += 1; throw new Error("nope"); },
+        { retry: { maxAttempts: 3 }, errorPolicy: "RETRY" })
+    ],
+    entryNodes: ["always-fails"],
+    terminalNodes: ["always-fails"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (attempts !== 3) throw new Error(`attempts=${attempts}`);
+  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].handled) throw new Error("should be unhandled");
+});
+
+rty.t("RETRY without delayMs retries without added latency", async () => {
+  let attempts = 0;
+  const definition = g({
+    nodes: [
+      node("flaky", () => {
+        attempts += 1;
+        if (attempts < 2) throw new Error("once");
+        return "fine";
+      }, { retry: { maxAttempts: 2 }, errorPolicy: "RETRY" })
+    ],
+    entryNodes: ["flaky"],
+    terminalNodes: ["flaky"]
+  });
+  const started = Date.now();
+  const report = await new GraphExecutionEngine(definition).run();
+  if (Date.now() - started > 200) throw new Error("unexpected delay");
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+});
+
+rty.t("retry maxAttempts=1 means a single execution", async () => {
+  let attempts = 0;
+  const definition = g({
+    nodes: [
+      node("one-shot", () => { attempts += 1; throw new Error("x"); },
+        { retry: { maxAttempts: 1 } })
+    ],
+    entryNodes: ["one-shot"],
+    terminalNodes: ["one-shot"]
+  });
+  await new GraphExecutionEngine(definition).run();
+  if (attempts !== 1) throw new Error(`attempts=${attempts}`);
+});
+
+rty.t("once retries succeed the successor nodes are scheduled", async () => {
+  let attempts = 0;
+  const definition = g({
+    nodes: [
+      node("flaky", () => {
+        attempts += 1;
+        if (attempts === 1) throw new Error("first");
+        return "second-wins";
+      }, { retry: { maxAttempts: 2 }, errorPolicy: "RETRY", next: ["tail"] }),
+      constNode("tail", "done")
+    ],
+    entryNodes: ["flaky"],
+    terminalNodes: ["tail"]
+  });
+  const report = await new GraphExecutionEngine(definition).run();
+  if (report.status !== "COMPLETED") throw new Error(report.status);
+  if (report.outputs.flaky !== "second-wins") throw new Error("stale output");
+});
+
+/* =========================================================
+ * 9. Cancellation — 5
+ * ========================================================= */
+
+const can = suite("unit", "Cancellation");
+
+can.t("cancel() on a CREATED engine produces CANCELLED", async () => {
+  const engine = new GraphExecutionEngine(linear(["a", "b"]));
+  await engine.cancel();
+  const report = await engine.run();
+  if (report.status !== "CANCELLED") throw new Error(report.status);
+  if (report.results.length !== 0) throw new Error("nodes ran");
+});
+
+can.t("cancel() aborts the execution signal exposed to running nodes", async () => {
+  let observed = false;
+  const definition = g({
+    nodes: [
+      node("a", async context => {
+        await sleep(30);
+        observed = context.signal.aborted;
+        return "late";
+      })
+    ],
+    entryNodes: ["a"],
+    terminalNodes: ["a"]
+  });
+  const engine = new GraphExecutionEngine(definition);
+  const promise = engine.run();
+  await sleep(5);
+  await engine.cancel();
+  const report = await promise;
+  if (report.status !== "CANCELLED") throw new Error(report.status);
+  if (!observed) throw new Error("signal never aborted");
+});
+
+can.t("cancel() emits graph.cancellationRequested", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  const captured = capture(engine, ["graph.cancellationRequested"]);
+  await engine.cancel();
+  if (captured.length !== 1) throw new Error("not emitted");
+  const payload = captured[0].payload as { executionId: string };
+  if (payload.executionId !== engine.getExecutionId()) throw new Error("bad payload");
+});
+
+can.t("nodes in flight when cancelling settle as CANCELLED", async () => {
+  const definition = g({
+    nodes: [node("slow", async () => { await sleep(40); return "x"; })],
+    entryNodes: ["slow"],
+    terminalNodes: ["slow"]
+  });
+  const engine = new GraphExecutionEngine(definition);
+  const promise = engine.run();
+  await sleep(5);
+  await engine.cancel();
+  const report = await promise;
+  if (report.results[0].status !== "CANCELLED") throw new Error(report.results[0].status);
+});
+
+can.t("cancel() after COMPLETED is a no-op", async () => {
+  const engine = new GraphExecutionEngine(linear(["a"]));
+  await engine.run();
+  await engine.cancel();
+  if (engine.getState() !== "COMPLETED") throw new Error(engine.getState());
+});