automategraph 1.5.0 → 1.5.3

package/examples/README.md

@@ -0,0 +1,206 @@
+# Examples
+
+| Path | What | Run |
+|---|---|---|
+| `json-scripts.ts` + `order-flow.scripted.graph.json` + `order-flow.functions.cjs` | **v1.5** — the document brings its own code: a path script + an inline self-registering script, then the namespace freeze | `npm run example:scripts` |
+| `json-graph.ts` + `order-flow.graph.json` | **v1.4** — the same document (no JS) against four registries, incl. a missing name | `npm run example:graphjson` |
+| `branching-edges.ts` | v1.3 — typed edges, one execution | `npm run example:edges` |
+| `branching-graph.ts` | v1.2 — guarded fan-out, gate + DRAIN, engine untouched | `npm run build && node js/examples/branching-graph.js` |
+| `branching-router.ts` | v1.2 — host-side router, engine untouched | `npm run example:branching` |
+
+## The `a → b / c / d / e / f` picture, three ways
+
+The same branching graph, solved with three different levels of engine support. All three are
+runnable and self-verifying; all three end with `5/5 matched`.
+
+| # | Example | Engine version | Cost |
+|---|---|---|---|
+| 1 | `branching-router.ts` — host-side router | v1.2, **untouched** | 10 executions (one per hop), control plane in host code |
+| 2 | `branching-graph.ts` — pure graph, guards + gate | v1.2, **untouched** | 1 execution, but 4 branch activations + one closure gate + `DRAIN` |
+| 3 | **`branching-edges.ts` — typed edges** | **v1.3** | 1 execution, 1 branch activation, no gate, `FIRST_TERMINAL` |
+
+```bash
+npm run example:edges        # 3 — typed edges, the recommended version
+node js/examples/branching-graph.js   # 2 — guards + gate
+npm run example:branching    # 1 — host-side router
+```
+
+## 3. Typed edges (v1.3) — the arrows, declared
+
+v1.3 lifts routing into the engine, so every arrow is one `next` entry and the rest of the diagram
+is plain node code:
+
+| Arrow in the picture | Typed-edge declaration |
+|---|---|
+| `result === 1` → b | `{ result: 1, nextNode: "b" }` |
+| `test(result)` → c | `{ test: r => r === 2, nextNode: "c" }` |
+| `else` → d | `{ nextNode: "d" }` (no matcher — evaluated last, in order) |
+| `on throw` → e | `onThrow: "e"` + `errorPolicy: "RETRY"` (unchanged) |
+| `on retry` → f | `if (context.attempt > 1) return new Next("f", result)` |
+| b **forces** f | `context.goto("f"); return undefined;` inside `b` |
+
+Exclusive edges are ordered and first-match-wins, `result` matches by deep equality, and no match
+schedules nothing. One execution per seed, one activation per branch, `lint: "error"` clean under
+`FIRST_TERMINAL`. `b` also declares `next: ["f"]` — the explicit `goto` wins at runtime, but the
+declared edge is what makes `f` reachable to static lint, and it is the fallback if `b` ever
+returns a value (case 24 of `tests/edges.test.ts` records this as a finding).
+
+The remaining sections document the two v1.2 approaches and why typed edges made them obsolete.
+
+---
+
+# Branching router — `a → b / c / d / e / f`
+
+Runnable translation of this graph, **without touching `src/automategraph.ts`** (v1.2):
+
+```
+a ── result === 1 ────────────────▶ b ──(forces)──▶ f
+a ── test(result) === true ───────▶ c
+a ── otherwise ───────────────────▶ d
+a ── on throw ────────────────────▶ e
+a ── on retry ────────────────────▶ f
+```
+
+```bash
+npm run example:branching     # 5 scenarios, exits non-zero on any deviation
+```
+
+## Why this is not a single `GraphDefinition`
+
+Two engine facts make the picture inexpressible as one definition:
+
+1. **`next` is an unconditional fan-out.** Every target listed is scheduled, every time — there
+   is no conditional edge, so `if result === 1 → b` cannot be declared.
+2. **There is no `goto` and no per-attempt transition.** A node cannot schedule work from inside
+   its own execution, and retries are internal (`errorPolicy: "RETRY"` loops *inside* one
+   activation), so "on retry → f" is not a state transition the engine knows about.
+
+Routing is therefore a **decision**, and a decision needs somewhere to run. This example puts it
+in a host-side router that drives the engine one step at a time and reads each finished execution.
+
+```mermaid
+flowchart LR
+    subgraph R["Router (host code — examples/branching-router.ts)"]
+        D{"decide()"}
+        S["WalkState<br/>seed · visited · lastError"]
+    end
+
+    subgraph E["GraphExecutionEngine (untouched)"]
+        H1["execution #1<br/>a"]
+        H2["execution #2<br/>b"]
+        H3["execution #3<br/>f"]
+    end
+
+    D -->|"step graph: one node,<br/>entry = terminal"| H1
+    H1 -->|"report: output / attempts / errors<br/>+ router.goto event"| D
+    D --> H2 --> D
+    D --> H3 --> D
+    S -.->|"state shared by all step callbacks"| H1 & H2 & H3
+```
+
+Each hop is a one-node graph (`entryNodes: [id]`, `terminalNodes: [id]`, `maxActivations: 1`), so
+the engine schedules nothing on its own and the walk stays lint-clean (the v1.2 `SUCCESS_DEAD_END`
+rule is satisfied because the step *is* the terminal).
+
+## Arrow → mechanism
+
+| Arrow in the picture | Mechanism | Engine feature used |
+|---|---|---|
+| `if result === 1` → b | ordered `routes` predicate on the returned value | `NodeResult.output` |
+| `if test(result) === true` → c | second predicate, evaluated in order | `NodeResult.output` |
+| `else` → d | `otherwise` fallback target | — |
+| `on throw` → e | failed hop ⇒ `onThrow` target | `ExecutionReport.status` + `errors[]` |
+| `on retry` → f | hop needed > 1 attempt ⇒ `onRetry` target | `node.started` event → `payload.attempt` |
+| b **forces** f | b returns `undefined` and emits `router.goto` | `context.emit` on the public `EventBus` |
+| retries on `a` | `retry: { maxAttempts: 2 }` + `errorPolicy: "RETRY"` | engine-native retry loop |
+
+Decision precedence, first match wins:
+
+```
+goto → throw → retry → value routes → otherwise → stop
+```
+
+A **failed** step goes to `onThrow` even after consuming retries; `onRetry` fires for a step that
+*recovered* on a later attempt. Flip those two in `decide()` if you want "any retry goes to f".
+
+## The forced jump, honestly
+
+`b` cannot schedule `f` — no node can schedule anything in this engine. What `b` does is **ask**:
+
+```ts
+run: async (_state, context) => {
+  await context.emit(GOTO_EVENT, { to: "f", reason: "b short-circuits to f" });
+  return undefined;                     // void, as specified
+}
+```
+
+The router registers a *required* listener (so the bus awaits it and the request is guaranteed to
+be visible before `run()` resolves), then performs the jump itself with a fresh execution starting
+at `f`. The engine stays a pure executor; the control plane lives in host code.
+
+Alternatives that also work without engine changes, and why they were not used:
+
+- **Return a marker** (`return { goto: "f" }`) — works, but `b` must then return an object instead
+  of `void`, contradicting the spec.
+- **Throw and use `onThrow`** — a real engine transition, but it records `b` as `FAILED` with an
+  error, which is the wrong semantics for a deliberate jump.
+- **`fallback` + `errorPolicy: "FALLBACK"`** — same objection, plus the fallback target must exist
+  inside the same graph.
+
+## The single-execution alternative (and its catch)
+
+If you need **one** execution spanning the whole graph, express the branch as **guarded fan-out**:
+
+```ts
+node("a", runA, {
+  next: ["b", "c", "d", "f"],      // unconditional: all four are activated
+  onThrow: "e",                     // engine-native error arrow
+  errorPolicy: "RETRY", retry: { maxAttempts: 2 }
+})
+// each of b/c/d/f starts with a guard:
+node("b", ctx => ctx.outputs.a === 1 ? runB(ctx) : SKIPPED)
+```
+
+Caveats, all demonstrated by the `complex` pack:
+
+- every candidate is **activated** (results, events, checkpoints) even when it is a no-op;
+- `FIRST_TERMINAL` completion can drop a not-yet-scheduled branch — you want
+  `completionPolicy: "DRAIN"`;
+- the **forced jump from `b` to `f` becomes racy**, because fan-out activates siblings
+  concurrently: `f`'s guard may run before `b` decided. Making it deterministic needs an explicit
+  gate — exactly the `releaseFast()` / `fallbackDone` trick used in the C-19 fixture
+  (`docs/diagrams/c19-resilience-scenario.md`).
+
+Trade-off summary: **router = true routing, N executions**; **guards = one execution, all branches
+activated, needs gates for cross-branch jumps**.
+
+## Files
+
+| Path | What |
+|---|---|
+| `branching-edges.ts` | **v1.3**: the picture as one `GraphDefinition` — `npm run example:edges` |
+| `branching-graph.ts` | v1.2, engine untouched: guarded fan-out + `DRAIN` + closure gate |
+| `branching-router.ts` | v1.2, engine untouched: steps as data + `runWalk()` + self-verifying demo |
+| `npm run example:branching` | builds and runs the router's five scenarios |
+
+Verified output (each hop is a real engine execution with its own `executionId` and checkpoint):
+
+```
+▶ seed = 1   result === 1                → b, then b forces f
+   hop 1  a  COMPLETED  attempts=1  output=1          return    → b
+   hop 2  b  COMPLETED  attempts=1  output=undefined  goto      → f
+   hop 3  f  COMPLETED  attempts=1  output="f: …"     none      stop
+   path: a → b → f   ✓ as expected
+```
+
+## 3 (typed edges) — verified output
+
+```
+▶ seed = 1   result === 1    → b, and b forces f
+   COMPLETED  path: a → b → f  ✓
+     a  output=1
+     b  output=undefined (void)     ⤳ routed to f (via goto)
+     f  output="f: reached by retry or by b's forced jump"
+...
+scenarios: 5/5 matched
+```

package/examples/branching-edges.ts

@@ -0,0 +1,192 @@
+/* ============================================================
+ * Branching graph with TYPED EDGES (v1.3) — one execution
+ * ------------------------------------------------------------
+ * The same picture as examples/branching-graph.ts, but the arrows
+ * are now declared where they belong — on the node — and the whole
+ * thing runs as ONE GraphExecutionEngine execution:
+ *
+ *   a ── result === 1 ────────────▶ b ──(forces)──▶ f
+ *   a ── test(result) === true ───▶ c
+ *   a ── else ────────────────────▶ d
+ *   a ── on throw ────────────────▶ e
+ *   a ── on retry ────────────────▶ f
+ *
+ * What replaced what (see CHANGELOG 1.3.0):
+ *   guards + skip markers   → { result } / { test } / { nextNode } edges
+ *   the b → f gate          → context.goto("f") inside b
+ *   "on retry → f" route    → return new Next("f", result) when attempt > 1
+ *   completionPolicy DRAIN  → not needed: exclusive edges schedule one branch
+ *
+ * Run:  node js/examples/branching-edges.js      (after npm run build)
+ * ============================================================ */
+
+import {
+  GraphDefinition,
+  GraphExecutionEngine,
+  Next,
+  NodeContext,
+  NodeDefinition
+} from "../src/automategraph";
+
+/* ---------------------------------------------------------------
+ * Edge semantics used here
+ * ---------------------------------------------------------------
+ * next: [
+ *   { result: 1, nextNode: "b" }           exclusive, deep equality
+ *   { test: r => r === 2, nextNode: "c" }  exclusive, predicate
+ *   { nextNode: "d" }                      else edge (no matcher)
+ * ]
+ * First match wins, in declaration order. No match ⇒ nothing is
+ * scheduled (silent). A string entry would be a parallel edge that
+ * always fires, alongside the winning conditional.
+ * ------------------------------------------------------------- */
+
+export type ScenarioSeed = 1 | 2 | 3 | "throw" | "retry";
+
+/** `test(result)` from the picture. */
+export const test = (result: number): boolean => result === 2;
+
+const node = (
+  id: string,
+  run: NodeDefinition["run"],
+  extra: Partial<NodeDefinition> = {}
+): NodeDefinition => ({ id, run, ...extra });
+
+export function buildGraph(seed: ScenarioSeed): GraphDefinition {
+  return {
+    id: "branching-edges",
+    version: "1.3.0",
+
+    nodes: {
+      /* ---------------------------- a ---------------------------- */
+      a: node("a", (context: NodeContext) => {
+        // on throw → e   (a real engine transition, declared below)
+        if (seed === "throw") throw new Error("a: upstream exploded");
+
+        // retry: attempt 1 fails, attempt 2 succeeds
+        if (seed === "retry" && context.attempt === 1) {
+          throw new Error(`a: transient failure on attempt ${context.attempt}`);
+        }
+
+        const result = seed === "retry" ? 2 : seed;
+
+        // on retry → f   (only the node knows the attempt number)
+        if (context.attempt > 1) return new Next("f", result);
+
+        return result;
+      }, {
+        next: [
+          { result: 1, nextNode: "b" },
+          { test: value => typeof value === "number" && test(value), nextNode: "c" },
+          { nextNode: "d" } // else
+        ],
+        onThrow: "e",
+        retry: { maxAttempts: 2, delayMs: 5 },
+        errorPolicy: "RETRY"
+      }),
+
+      /* ---------------------------- b ---------------------------- */
+      // returns void, then forces f from inside the execution
+      b: node("b", (context: NodeContext) => {
+        context.goto("f");
+        return undefined; // void
+      }, {
+        // declared so static reachability sees f; at runtime the explicit
+        // route wins and this edge stays a fallback if b ever returns a value
+        next: ["f"]
+      }),
+
+      /* ---------------------------- c / d / e / f ---------------------------- */
+      c: node("c", () => "c: handled result 2"),
+      d: node("d", () => "d: handled anything else"),
+      e: node("e", () => "e: failure route"),
+      f: node("f", () => "f: reached by retry or by b's forced jump")
+    },
+
+    entryNodes: ["a"],
+    terminalNodes: ["c", "d", "e", "f"],
+    completionPolicy: "FIRST_TERMINAL" // exclusive edges ⇒ one branch only
+  };
+}
+
+/* ============================= demo ============================= */
+
+const SCENARIOS: ReadonlyArray<{
+  label: string;
+  seed: ScenarioSeed;
+  path: string[];
+}> = [
+  { label: "result === 1    → b, and b forces f", seed: 1, path: ["a", "b", "f"] },
+  { label: "test(result)    → c", seed: 2, path: ["a", "c"] },
+  { label: "else            → d", seed: 3, path: ["a", "d"] },
+  { label: "on throw        → e", seed: "throw", path: ["a", "e"] },
+  { label: "on retry        → f", seed: "retry", path: ["a", "f"] }
+];
+
+function show(value: unknown): string {
+  return value === undefined ? "undefined (void)" : JSON.stringify(value);
+}
+
+export interface Visited {
+  nodeId: string;
+  attempt: number;
+  output: unknown;
+  route?: { nextNode: string; via: string };
+}
+
+/** Collects what each node produced / routed to, in execution order. */
+function instrument(engine: GraphExecutionEngine): Visited[] {
+  const visited: Visited[] = [];
+
+  engine.events.on("node.succeeded", payload => {
+    const info = payload as {
+      nodeId: string;
+      output: unknown;
+      route?: { nextNode: string; via: string };
+    };
+    visited.push({ nodeId: info.nodeId, attempt: 1, output: info.output, route: info.route });
+  });
+
+  return visited;
+}
+
+async function main(): Promise<void> {
+  console.log("=".repeat(100));
+  console.log("typed edges (v1.3) — the whole picture as ONE execution, lint: \"error\"");
+  console.log("=".repeat(100));
+
+  let failures = 0;
+
+  for (const scenario of SCENARIOS) {
+    const engine = new GraphExecutionEngine(buildGraph(scenario.seed), { lint: "error" });
+    const visited = instrument(engine);
+
+    const report = await engine.run();
+    const path = report.results.map(result => result.nodeId);
+    const ok = path.join(",") === scenario.path.join(",") && report.status === "COMPLETED";
+    if (!ok) failures += 1;
+
+    console.log(`\n▶ seed = ${JSON.stringify(scenario.seed)}   ${scenario.label}`);
+    console.log(
+      `   ${report.status}  path: ${path.join(" → ")}  ` +
+        `${ok ? "✓" : `✗ expected ${scenario.path.join(" → ")}`}`
+    );
+
+    for (const step of visited) {
+      const route = step.route ? `  ⤳ routed to ${step.route.nextNode} (via ${step.route.via})` : "";
+      console.log(`     ${step.nodeId.padEnd(2)} output=${show(step.output).padEnd(40)}${route}`);
+    }
+
+    for (const error of report.errors) {
+      console.log(`   error: ${error.code}@${error.nodeId} handled=${error.handled}`);
+    }
+  }
+
+  console.log(`\n${"-".repeat(100)}`);
+  console.log(`scenarios: ${SCENARIOS.length - failures}/${SCENARIOS.length} matched`);
+  if (failures > 0) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  void main();
+}