automategraph 1.5.1 → 1.5.3

package/examples/branching-router.ts

@@ -0,0 +1,475 @@
+/* ============================================================
+ * Branching router example — the a → b/c/d/e/f picture
+ * ------------------------------------------------------------
+ * The graph under discussion:
+ *
+ *   a ── result === 1 ────────────────▶ b ──(forces)──▶ f
+ *   a ── test(result) === true ───────▶ c
+ *   a ── otherwise ───────────────────▶ d
+ *   a ── on throw ────────────────────▶ e
+ *   a ── on retry ────────────────────▶ f
+ *
+ * WHY THIS IS NOT A SINGLE GraphDefinition
+ * GraphDefinition.next is an UNCONDITIONAL fan-out: every target is
+ * scheduled, every time. The engine also has no "goto" and no
+ * per-attempt transition. So the arrows above cannot be encoded in
+ * the definition — they are routing *decisions*, and decisions need
+ * a place to run. This file keeps src/automategraph.ts untouched and
+ * puts the decisions in a small host-side router: one engine
+ * execution per step, the router inspects the finished execution
+ * (output / attempts / errors / control events) and chooses the next
+ * hop.
+ *
+ * Arrow            → mechanism used here (all engine-native)
+ * ------------------------------------------------------------------
+ * result === 1     → returned value + ordered `routes` predicate
+ * test(...) === true→ returned value + ordered `routes` predicate
+ * otherwise        → `otherwise` fallback target
+ * on throw         → report.status / unhandled error → `onThrow`
+ * on retry         → context.attempt > 1 (seen via node.started) → `onRetry`
+ * b forces f       → b returns void and emits "router.goto" on the
+ *                    public event bus; the router honours the request
+ *
+ * Decision precedence (first match wins): goto → throw → retry →
+ * routes → otherwise → stop. Flip `onRetry` before `onThrow` in
+ * decide() if you prefer "any retry goes to f, even a failed one".
+ *
+ * Run it:  npm run example:branching
+ * Exits non-zero if any scenario deviates from its expected path, so
+ * it doubles as a smoke test.
+ * ============================================================ */
+
+import {
+  AutomateGraphError,
+  ErrorPolicy,
+  ExecutionReport,
+  GraphDefinition,
+  GraphStatus,
+  InMemoryStorage,
+  NodeContext,
+  NodeDefinition,
+  RetryPolicy,
+  GraphExecutionEngine
+} from "../src/automategraph";
+
+/* =========================
+ * 1. The graph as data
+ * ========================= */
+
+/** What node `a` may return: 1, 2 or 3 — or it may fail at runtime. */
+export type ScenarioSeed = 1 | 2 | 3 | "throw" | "retry";
+
+/** The spec's `test(result)`: decides between c and d. */
+export const test = (result: number): boolean => result === 2;
+
+/** Mutable context threaded through the whole walk. */
+export interface WalkState {
+  seed: ScenarioSeed;
+  visited: string[];
+  lastError?: { nodeId: string; code: string; message: string };
+  notes: string[];
+}
+
+export interface RouteTable {
+  /** Ordered conditional arrows, evaluated against the returned value. */
+  readonly routes?: ReadonlyArray<{
+    readonly when: (value: unknown) => boolean;
+    readonly to: string;
+  }>;
+  /** The `else` arrow. */
+  readonly otherwise?: string;
+  /** Arrow taken when the step failed with no attempts left. */
+  readonly onThrow?: string;
+  /** Arrow taken when the step needed more than one attempt. */
+  readonly onRetry?: string;
+}
+
+/** One node in the picture: a callback plus its outgoing arrows. */
+export interface StepDefinition {
+  readonly run: (state: WalkState, context: NodeContext) => unknown | Promise<unknown>;
+  readonly retry?: RetryPolicy;
+  readonly errorPolicy?: ErrorPolicy;
+  readonly routes?: RouteTable;
+}
+
+/** Event a node emits when it wants to force the next hop from inside. */
+export const GOTO_EVENT = "router.goto";
+
+export interface GotoRequest {
+  to: string;
+  reason?: string;
+}
+
+/* =========================
+ * 2. The nodes
+ * ========================= */
+
+export function buildSteps(state: WalkState): Record<string, StepDefinition> {
+  return {
+    /**
+     * a — produces 1 | 2 | 3, or throws.
+     * It carries the whole arrow table from the picture.
+     */
+    a: {
+      run: (_state, context) => {
+        if (state.seed === "throw") {
+          throw new Error("a: upstream exploded");
+        }
+
+        if (state.seed === "retry" && context.attempt === 1) {
+          throw new Error(`a: transient failure on attempt ${context.attempt}`);
+        }
+
+        // On the retry path, attempt 2 succeeds with value 2.
+        return state.seed === "retry" ? 2 : state.seed;
+      },
+      retry: { maxAttempts: 2, delayMs: 10 },
+      errorPolicy: "RETRY",
+      routes: {
+        routes: [
+          { when: value => value === 1, to: "b" },
+          { when: value => typeof value === "number" && test(value), to: "c" }
+        ],
+        otherwise: "d",
+        onThrow: "e",
+        onRetry: "f"
+      }
+    },
+
+    /**
+     * b — returns void, but forces the walk to f *from inside its own
+     * execution* by emitting a control message. The engine never
+     * schedules the jump; the router (host code) performs it.
+     */
+    b: {
+      run: async (_state, context) => {
+        await context.emit(GOTO_EVENT, {
+          to: "f",
+          reason: "b short-circuits to f"
+        } satisfies GotoRequest);
+
+        return undefined; // void, as specified
+      },
+      // Belt and braces: also true if a goto is ever ignored.
+      routes: { otherwise: "f" }
+    },
+
+    c: { run: () => "c: even result handled" },
+    d: { run: () => "d: fallback branch handled" },
+
+    /** e — the throw route; can read the failure the router recorded. */
+    e: {
+      run: () => `e: recovered from ${state.lastError?.nodeId ?? "?"} (${state.lastError?.code ?? "?"})`
+    },
+
+    f: { run: () => "f: retry/forced path handled" }
+  };
+}
+
+/* =========================
+ * 3. One step = one execution
+ * ========================= */
+
+/**
+ * Build the single-node graph for a hop. The node is BOTH the entry
+ * and the terminal, which keeps the graph lint-clean (the v1.2
+ * SUCCESS_DEAD_END rule needs each non-terminal node to have a
+ * `next`) and guarantees the engine schedules nothing on its own.
+ *
+ * `onThrow` is deliberately NOT declared on the engine node: its
+ * target would have to exist inside this one-node graph, and error
+ * routing is the router's job here (see decide()).
+ */
+function stepGraph(id: string, step: StepDefinition, state: WalkState): GraphDefinition {
+  const definition: NodeDefinition = {
+    id,
+    run: (context: NodeContext) => step.run(state, context),
+    retry: step.retry,
+    errorPolicy: step.errorPolicy
+  };
+
+  return {
+    id: `branching-step:${id}`,
+    version: "1.0.0",
+    entryNodes: [id],
+    terminalNodes: [id],
+    nodes: { [id]: definition }
+  };
+}
+
+export type DecisionBy = "goto" | "throw" | "retry" | "return" | "otherwise" | "none";
+
+export interface HopRecord {
+  step: number;
+  nodeId: string;
+  executionId: string;
+  status: GraphStatus;
+  attempts: number;
+  output: unknown;
+  errorCode?: string;
+  decision: { by: DecisionBy; to?: string; reason: string };
+  durationMs: number;
+}
+
+interface RawRun {
+  report: ExecutionReport;
+  attempts: number;
+  gotoRequests: GotoRequest[];
+}
+
+function isGotoRequest(value: unknown): value is GotoRequest {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as GotoRequest).to === "string"
+  );
+}
+
+async function runOne(
+  nodeId: string,
+  step: StepDefinition,
+  state: WalkState,
+  storage: InMemoryStorage
+): Promise<RawRun> {
+  const engine = new GraphExecutionEngine(stepGraph(nodeId, step, state), {
+    storage,
+    maxActivations: 1 // a hop starts exactly one activation
+  });
+
+  let attempts = 0;
+  const gotoRequests: GotoRequest[] = [];
+
+  // Required listeners are awaited by the bus, so by the time run()
+  // resolves we have the true attempt count and every goto request.
+  engine.events.on(
+    "node.started",
+    payload => {
+      const { attempt } = payload as { attempt: number };
+      attempts = Math.max(attempts, attempt);
+    },
+    { required: true }
+  );
+
+  engine.events.on(
+    GOTO_EVENT,
+    payload => {
+      if (isGotoRequest(payload)) gotoRequests.push(payload);
+    },
+    { required: true }
+  );
+
+  const report = await engine.run();
+  return { report, attempts, gotoRequests };
+}
+
+/* =========================
+ * 4. The router
+ * ========================= */
+
+export interface WalkOptions {
+  readonly maxSteps?: number;
+  readonly storage?: InMemoryStorage;
+  readonly onHop?: (hop: HopRecord) => void;
+}
+
+export interface WalkResult {
+  hops: HopRecord[];
+  path: string[];
+  executionIds: string[];
+}
+
+/**
+ * Decision precedence: goto → throw → retry → returned value → stop.
+ * A *failed* step goes to `onThrow` even when it consumed retries;
+ * `onRetry` is for a step that recovered on a later attempt.
+ */
+export function decide(
+  routes: RouteTable | undefined,
+  run: RawRun
+): { by: DecisionBy; to?: string; reason: string } {
+  const { report, attempts, gotoRequests } = run;
+
+  if (gotoRequests.length > 0) {
+    const request = gotoRequests[0];
+    return {
+      by: "goto",
+      to: request.to,
+      reason: `forced from inside the node (${request.reason ?? "no reason given"})`
+    };
+  }
+
+  const failed = report.status !== "COMPLETED";
+
+  if (failed) {
+    if (routes?.onThrow) {
+      return { by: "throw", to: routes.onThrow, reason: `step ended ${report.status}` };
+    }
+    return { by: "none", reason: `step ended ${report.status} and no onThrow is declared` };
+  }
+
+  if (attempts > 1 && routes?.onRetry) {
+    return { by: "retry", to: routes.onRetry, reason: `recovered on attempt ${attempts}` };
+  }
+
+  const output = report.results[0]?.output;
+
+  for (const route of routes?.routes ?? []) {
+    if (route.when(output)) {
+      return { by: "return", to: route.to, reason: "value route matched" };
+    }
+  }
+
+  if (routes?.otherwise) {
+    return { by: "otherwise", to: routes.otherwise, reason: "no value route matched" };
+  }
+
+  return { by: "none", reason: "no transition declared; walk complete" };
+}
+
+/* =========================
+ * 5. The walk factory (public entry point)
+ * ========================= */
+
+/**
+ * Seeds the walk, builds the steps against the shared state, and runs
+ * the router loop. This is the whole "interpreter": run one node, read
+ * its outcome, follow the matching arrow.
+ */
+export async function runWalk(
+  seed: ScenarioSeed,
+  options: WalkOptions = {}
+): Promise<{ result: WalkResult; state: WalkState }> {
+  const storage = options.storage ?? new InMemoryStorage();
+  const maxSteps = options.maxSteps ?? 64;
+
+  const state: WalkState = { seed, visited: [], notes: [] };
+  const steps = buildSteps(state);
+  const hops: HopRecord[] = [];
+  const executionIds: string[] = [];
+
+  let current: string | undefined = "a";
+
+  while (current !== undefined) {
+    if (hops.length >= maxSteps) {
+      throw new AutomateGraphError(
+        `Walk exceeded maxSteps=${maxSteps} (possible cycle)`,
+        "WALK_STEP_LIMIT",
+        { visited: [...state.visited] }
+      );
+    }
+
+    const step: StepDefinition | undefined = steps[current];
+
+    if (!step) {
+      throw new AutomateGraphError(
+        `Route target "${current}" has no node definition`,
+        "ROUTE_TARGET_UNKNOWN",
+        { visited: [...state.visited] }
+      );
+    }
+
+    const startedAt = Date.now();
+    const run = await runOne(current, step, state, storage);
+    const { report, attempts, gotoRequests } = run;
+
+    // Record the failure so the next hop (e) can read it.
+    const unhandled = report.errors.find(error => !error.handled);
+    if (unhandled) {
+      state.lastError = {
+        nodeId: unhandled.nodeId ?? current,
+        code: unhandled.code,
+        message: unhandled.message
+      };
+    }
+
+    const decision = decide(step.routes, run);
+
+    const hop: HopRecord = {
+      step: hops.length + 1,
+      nodeId: current,
+      executionId: report.executionId,
+      status: report.status,
+      attempts,
+      output: report.results[0]?.output,
+      errorCode: report.errors[0]?.code,
+      decision,
+      durationMs: Date.now() - startedAt
+    };
+
+    hops.push(hop);
+    executionIds.push(report.executionId);
+    state.visited.push(current);
+    options.onHop?.(hop);
+
+    if (gotoRequests.length > 1) {
+      state.notes.push(`${current} requested ${gotoRequests.length} jumps; using the first`);
+    }
+
+    current = decision.to;
+  }
+
+  return { result: { hops, path: state.visited, executionIds }, state };
+}
+
+/* =========================
+ * 6. Demo — proves the picture
+ * ========================= */
+
+const SCENARIOS: ReadonlyArray<{ label: string; seed: ScenarioSeed; expected: string[] }> = [
+  { label: "result === 1                → b, then b forces f", seed: 1, expected: ["a", "b", "f"] },
+  { label: "test(result) === true       → c", seed: 2, expected: ["a", "c"] },
+  { label: "otherwise                   → d", seed: 3, expected: ["a", "d"] },
+  { label: "on throw                    → e", seed: "throw", expected: ["a", "e"] },
+  { label: "on retry (recovered)        → f", seed: "retry", expected: ["a", "f"] }
+];
+
+function show(value: unknown): string {
+  return value === undefined ? "undefined" : JSON.stringify(value);
+}
+
+async function main(): Promise<void> {
+  const storage = new InMemoryStorage();
+  let failures = 0;
+
+  console.log("=".repeat(96));
+  console.log("Branching router — engine untouched, arrows resolved by the host-side router");
+  console.log("=".repeat(96));
+
+  for (const scenario of SCENARIOS) {
+    const { result } = await runWalk(scenario.seed, { storage });
+    const path = result.path.join(" → ");
+    const expected = scenario.expected.join(" → ");
+    const ok = path === expected;
+    if (!ok) failures += 1;
+
+    console.log(`\n▶ seed = ${JSON.stringify(scenario.seed)}   ${scenario.label}`);
+
+    for (const hop of result.hops) {
+      const target = hop.decision.to ? `→ ${hop.decision.to}` : "stop";
+      console.log(
+        `   hop ${hop.step}  ${hop.nodeId}  ${hop.status.padEnd(9)}` +
+          `  attempts=${hop.attempts}  output=${show(hop.output).padEnd(42)}` +
+          `  ${hop.decision.by.padEnd(9)} ${target}  (${hop.decision.reason})`
+      );
+    }
+
+    console.log(`   path: ${path}   ${ok ? "✓ as expected" : `✗ expected ${expected}`}`);
+  }
+
+  const snapshotIds = await storage.listExecutionIds();
+
+  console.log(`\n${"-".repeat(96)}`);
+  console.log(
+    `scenarios: ${SCENARIOS.length - failures}/${SCENARIOS.length} matched · ` +
+      `engine executions (one per hop): ${snapshotIds.length} · ` +
+      `checkpoints retrievable via storage.load(executionId)`
+  );
+
+  if (failures > 0) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  void main();
+}

package/examples/json-graph.ts

@@ -0,0 +1,231 @@
+/* ============================================================
+ * Graph as a DATA FILE (v1.4)
+ * ------------------------------------------------------------
+ * examples/order-flow.graph.json declares nodes and edges, but no
+ * JavaScript. Every function is referenced by name and supplied to the
+ * engine at construction, so the SAME document runs against different
+ * implementations:
+ *
+ *   classify ── isPriority ──▶ charge ──▶ ship
+ *            ── "manual" ────▶ manual
+ *            ── else ────────▶ reject
+ *
+ * Scenario D runs the document with a registry that is missing
+ * `shipOrder` — nothing throws at build time; the activation fails with
+ * UNKNOWN_FUNCTION and the run settles FAILED.
+ *
+ * Run:  npm run example:graphjson      (after npm run build)
+ * ============================================================ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import {
+  FunctionRegistryInput,
+  NodeContext
+} from "../src/automategraph";
+import {
+  createEngineFromJSON,
+  parseGraphJSON
+} from "../src/graph-json";
+
+const DOCUMENT_PATH = path.join(
+  __dirname,
+  "..",
+  "..",
+  "examples",
+  "order-flow.graph.json"
+);
+
+/* ---------------------------------------------------------------
+ * The implementations, keyed by the names the document uses.
+ * ------------------------------------------------------------- */
+
+function isPriority(value: unknown): boolean {
+  return value === "priority";
+}
+
+function chargeCard(context: NodeContext): string {
+  if (context.attempt === 1) {
+    throw new Error("chargeCard: gateway timeout (transient)");
+  }
+
+  return "charged";
+}
+
+function shipOrder(): string {
+  return "shipped";
+}
+
+function manualReview(): string {
+  return "queued for a human";
+}
+
+function rejectOrder(): string {
+  return "rejected";
+}
+
+/*
+ * Three classifier IMPLEMENTATIONS — the document itself never changes.
+ * Each has its own source, so the registry fingerprint moves with it.
+ */
+function classifyAsPriority(): string {
+  return "priority";
+}
+
+function classifyAsManual(): string {
+  return "manual";
+}
+
+function classifyAsStandard(): string {
+  return "standard";
+}
+
+const SCENARIOS: ReadonlyArray<{
+  label: string;
+  registry: FunctionRegistryInput;
+  expect: string;
+  expectStatus: string;
+}> = [
+  {
+    label: "priority order → charge → ship",
+    registry: {
+      classifyOrder: classifyAsPriority,
+      isPriority,
+      chargeCard,
+      shipOrder,
+      manualReview,
+      rejectOrder
+    },
+    expect: "classify → charge → ship",
+    expectStatus: "COMPLETED"
+  },
+  {
+    label: 'returned "manual" → manual review',
+    registry: {
+      classifyOrder: classifyAsManual,
+      isPriority,
+      chargeCard,
+      shipOrder,
+      manualReview,
+      rejectOrder
+    },
+    expect: "classify → manual",
+    expectStatus: "COMPLETED"
+  },
+  {
+    label: "anything else → else edge → reject",
+    registry: {
+      classifyOrder: classifyAsStandard,
+      isPriority,
+      chargeCard,
+      shipOrder,
+      manualReview,
+      rejectOrder
+    },
+    expect: "classify → reject",
+    expectStatus: "COMPLETED"
+  },
+  {
+    label: "registry missing shipOrder → UNKNOWN_FUNCTION",
+    registry: {
+      classifyOrder: classifyAsPriority,
+      isPriority,
+      chargeCard,
+      manualReview,
+      rejectOrder
+    },
+    expect: "classify → charge",
+    expectStatus: "FAILED"
+  }
+];
+
+async function main(): Promise<void> {
+  const document = fs.readFileSync(DOCUMENT_PATH, "utf8");
+
+  console.log("=".repeat(96));
+  console.log(`graph as a data file — ${path.basename(DOCUMENT_PATH)}`);
+  console.log("=".repeat(96));
+
+  /* Parsing needs no registry at all: names resolve lazily. */
+  const definition = parseGraphJSON(document);
+  console.log(
+    `parsed: ${definition.id} v${definition.version}, ` +
+      `${Object.keys(definition.nodes).length} nodes, ` +
+      `${definition.entryNodes.join(",")} → ${definition.terminalNodes.join(",")}\n`
+  );
+
+  let failures = 0;
+  let previousFingerprint: string | undefined;
+
+  for (const scenario of SCENARIOS) {
+    const engine = createEngineFromJSON(document, {
+      functions: scenario.registry,
+      lint: "error",
+      onLog: (level, message) => {
+        if (level === "warn" || level === "error") {
+          console.log(`     log[${level}] ${message}`);
+        }
+      }
+    });
+
+    const report = await engine.run();
+
+    const path2 = report.results
+      .filter(result => result.status === "SUCCEEDED")
+      .map(result => result.nodeId)
+      .join(" → ");
+
+    const ok =
+      report.status === scenario.expectStatus &&
+      path2 === scenario.expect;
+
+    if (!ok) failures += 1;
+
+    const fingerprint = report.registry?.fingerprint ?? "(none)";
+    const drift =
+      previousFingerprint !== undefined &&
+      previousFingerprint !== fingerprint
+        ? "  ← registry changed (fingerprint moved)"
+        : "";
+
+    previousFingerprint = fingerprint;
+
+    console.log(`▶ ${scenario.label}`);
+    console.log(
+      `   ${report.status}  path: ${path2 || "(none)"}  ` +
+        `${ok ? "✓" : `✗ expected ${scenario.expectStatus} / ${scenario.expect}`}`
+    );
+    console.log(`   registry ${fingerprint}${drift}`);
+    console.log(`            names: ${(report.registry?.names ?? []).join(", ")}`);
+
+    for (const result of report.results) {
+      if (result.fn) {
+        console.log(
+          `     ${result.nodeId.padEnd(9)} fn=${result.fn} ` +
+            `attempt=${result.attempt} ${result.status}`
+        );
+      }
+    }
+
+    for (const error of report.errors) {
+      console.log(
+        `     error ${error.code} @${error.nodeId ?? "?"} ` +
+          `handled=${error.handled}  ${error.message}`
+      );
+    }
+
+    console.log("");
+  }
+
+  console.log("-".repeat(96));
+  console.log(
+    `scenarios: ${SCENARIOS.length - failures}/${SCENARIOS.length} matched`
+  );
+
+  if (failures > 0) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  void main();
+}