automategraph 1.5.1 → 1.5.3

package/examples/json-scripts.ts

@@ -0,0 +1,152 @@
+/* ============================================================
+ * A document that brings its own code (v1.5)
+ * ------------------------------------------------------------
+ * order-flow.scripted.graph.json declares WHICH functions it needs and
+ * WHERE they come from:
+ *
+ *   scripts: [
+ *     { "namespace": "order", "path": "./order-flow.functions.cjs" },
+ *     { "namespace": "audit", "source": "…registerEngineNamespace('audit', …)" }
+ *   ]
+ *
+ * Two strategies in one document:
+ *   • `order`  — a CommonJS FILE whose export table is the contribution
+ *   • `audit`  — INLINE source that registers itself from inside the
+ *                script through globalThis.GraphEngine (the loader
+ *                installs that global for the duration of the load only)
+ *
+ * The pipeline stays two-step:
+ *
+ *   const { functions } = await loadGraphScripts(document);
+ *   const engine = createEngineFromJSON(document, { functions });
+ *
+ * Run:  npm run example:scripts      (after npm run build)
+ * ============================================================ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import {
+  GraphScriptError,
+  loadGraphScripts,
+  registeredNamespaces,
+  resetGraphScriptNamespaces
+} from "../src/node/graph-scripts";
+import { createEngineFromJSON } from "../src/graph-json";
+
+const EXAMPLES = path.join(__dirname, "..", "..", "examples");
+const DOCUMENT_PATH = path.join(
+  EXAMPLES,
+  "order-flow.scripted.graph.json"
+);
+
+async function main(): Promise<void> {
+  const document = fs.readFileSync(DOCUMENT_PATH, "utf8");
+
+  console.log("=".repeat(96));
+  console.log(
+    `graph with scripts — ${path.basename(DOCUMENT_PATH)} ` +
+      "(functions live in the document's own scripts)"
+  );
+  console.log("=".repeat(96));
+
+  /* ---------- 1. load ---------- */
+
+  const loaded = await loadGraphScripts(document, {
+    baseDir: EXAMPLES,
+    onLog: (level, message) => {
+      if (level === "warn" || level === "error") console.log(`  log[${level}] ${message}`);
+    }
+  });
+
+  for (const script of loaded.scripts) {
+    console.log(`\n▶ namespace "${script.namespace}"  (${script.source}, ${script.format})`);
+    console.log(`   provided: ${script.names.join(", ")}`);
+    if (script.ignoredExports.length > 0) {
+      console.log(`   ignored (not functions): ${script.ignoredExports.join(", ")}`);
+    }
+  }
+
+  console.log(
+    `\nmerged registry: ${loaded.registry.names.length} functions, ` +
+      `fingerprint ${loaded.registry.fingerprint}`
+  );
+
+  /* ---------- 2. run ---------- */
+
+  const engine = createEngineFromJSON(document, {
+    functions: loaded.functions,
+    lint: "error"
+  });
+
+  const report = await engine.run();
+
+  const path2 = report.results
+    .filter(result => result.status === "SUCCEEDED")
+    .map(result => result.nodeId)
+    .join(" → ");
+
+  console.log("\n" + "-".repeat(96));
+  console.log(
+    `run: ${report.status}  path: ${path2}` +
+      `  ${path2 === "classify → audit → charge → ship" ? "✓" : "✗ expected classify → audit → charge → ship"}`
+  );
+
+  for (const result of report.results) {
+    console.log(
+      `   ${result.nodeId.padEnd(9)} fn=${(result.fn ?? "-").padEnd(15)} ` +
+        `attempt=${result.attempt} ${result.status}` +
+        (result.output === undefined ? "" : `  output=${JSON.stringify(result.output)}`)
+    );
+  }
+
+  console.log(
+    `   report.registry: ${report.registry?.fingerprint}  ` +
+      `(${report.registry?.fingerprint === loaded.registry.fingerprint ? "matches the loaded table" : "MISMATCH"})`
+  );
+  console.log(`   lint issues: ${report.lintIssues.length}`);
+  if (report.errors.length > 0) {
+    for (const error of report.errors) {
+      console.log(`   error ${error.code} @${error.nodeId} handled=${error.handled}`);
+    }
+  }
+
+  /* ---------- 3. the freeze ---------- */
+
+  console.log("\n" + "-".repeat(96));
+  console.log("the namespace freeze: one claim per process\n");
+
+  console.log(
+    `   claims now: ${registeredNamespaces()
+      .map(claim => `${claim.namespace} (${claim.names}, from ${claim.source})`)
+      .join("; ")}`
+  );
+
+  try {
+    await loadGraphScripts(document, { baseDir: EXAMPLES });
+    console.log("   ✗ a second load succeeded — the freeze is broken");
+  } catch (error) {
+    const scripted = error as GraphScriptError;
+    console.log(`   second load → ${scripted.code}`);
+    console.log(`   ${scripted.message.split(". ")[0]}.`);
+  }
+
+  console.log(
+    "\n   (resetGraphScriptNamespaces() clears the claims — test/CI hygiene;\n" +
+      "    production code should not need it: a document is loaded once.)"
+  );
+
+  resetGraphScriptNamespaces();
+
+  const reloaded = await loadGraphScripts(document, { baseDir: EXAMPLES });
+  console.log(
+    `   after reset → loaded again: ${reloaded.registry.names.length} functions, ` +
+      `fingerprint ${reloaded.registry.fingerprint}`
+  );
+
+  console.log("\n" + "=".repeat(96));
+}
+
+if (require.main === module) {
+  void main();
+}

package/examples/order-flow.functions.cjs

@@ -0,0 +1,32 @@
+/* ============================================================
+ * The functions referenced by examples/order-flow.scripted.graph.json
+ * ------------------------------------------------------------
+ * A plain CommonJS module: the export table IS the contribution. Names
+ * keep their exported spelling — the declared namespace ("order") is a
+ * claim slot, not a prefix.
+ *
+ * `ENGINE_VERSION` is deliberately not a function: the loader skips it
+ * and reports it under `ignoredExports`.
+ * ============================================================ */
+
+const ENGINE_VERSION = "1.5.0";
+
+module.exports = {
+  classifyOrder: () => "priority",
+
+  isPriority: value => value === "priority",
+
+  chargeCard: context => {
+    if (context.attempt === 1) {
+      throw new Error("chargeCard: gateway timeout (transient)");
+    }
+
+    return "charged";
+  },
+
+  shipOrder: () => "shipped",
+  manualReview: () => "queued for a human",
+  rejectOrder: () => "rejected",
+
+  ENGINE_VERSION
+};

package/examples/order-flow.graph.json

@@ -0,0 +1,27 @@
+{
+  "id": "order-flow",
+  "version": "1.0.0",
+  "entryNodes": ["classify"],
+  "terminalNodes": ["ship", "manual", "reject"],
+  "completionPolicy": "FIRST_TERMINAL",
+  "nodes": {
+    "classify": {
+      "run": "classifyOrder",
+      "next": [
+        { "test": "isPriority", "nextNode": "charge" },
+        { "result": "manual", "nextNode": "manual" },
+        { "nextNode": "reject" }
+      ]
+    },
+    "charge": {
+      "run": "chargeCard",
+      "next": ["ship"],
+      "onThrow": "manual",
+      "errorPolicy": "RETRY",
+      "retry": { "maxAttempts": 2, "delayMs": 5 }
+    },
+    "ship": { "run": "shipOrder" },
+    "manual": { "run": "manualReview" },
+    "reject": { "run": "rejectOrder" }
+  }
+}

package/examples/order-flow.scripted.graph.json

@@ -0,0 +1,68 @@
+{
+  "id": "order-flow-scripted",
+  "version": "1.5.0",
+  "entryNodes": [
+    "classify"
+  ],
+  "terminalNodes": [
+    "ship",
+    "manual",
+    "reject"
+  ],
+  "completionPolicy": "FIRST_TERMINAL",
+  "scripts": [
+    {
+      "namespace": "order",
+      "path": "./order-flow.functions.cjs"
+    },
+    {
+      "namespace": "audit",
+      "source": "globalThis.GraphEngine.registerEngineNamespace('audit', { auditDecision: context => `audited ${JSON.stringify(context.outputs.classify)} on attempt ${context.attempt}` });"
+    }
+  ],
+  "nodes": {
+    "classify": {
+      "run": "classifyOrder",
+      "next": [
+        {
+          "test": "isPriority",
+          "nextNode": "audit"
+        },
+        {
+          "result": "manual",
+          "nextNode": "manual"
+        },
+        {
+          "nextNode": "reject"
+        }
+      ]
+    },
+    "audit": {
+      "run": "auditDecision",
+      "next": [
+        "charge"
+      ]
+    },
+    "charge": {
+      "run": "chargeCard",
+      "next": [
+        "ship"
+      ],
+      "onThrow": "manual",
+      "errorPolicy": "RETRY",
+      "retry": {
+        "maxAttempts": 2,
+        "delayMs": 5
+      }
+    },
+    "ship": {
+      "run": "shipOrder"
+    },
+    "manual": {
+      "run": "manualReview"
+    },
+    "reject": {
+      "run": "rejectOrder"
+    }
+  }
+}

package/js/examples/branching-edges.js

@@ -0,0 +1,133 @@
+"use strict";
+/* ============================================================
+ * 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)
+ * ============================================================ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+exports.buildGraph = buildGraph;
+const automategraph_1 = require("../src/automategraph");
+/** `test(result)` from the picture. */
+const test = (result) => result === 2;
+exports.test = test;
+const node = (id, run, extra = {}) => ({ id, run, ...extra });
+function buildGraph(seed) {
+    return {
+        id: "branching-edges",
+        version: "1.3.0",
+        nodes: {
+            /* ---------------------------- a ---------------------------- */
+            a: node("a", (context) => {
+                // 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 automategraph_1.Next("f", result);
+                return result;
+            }, {
+                next: [
+                    { result: 1, nextNode: "b" },
+                    { test: value => typeof value === "number" && (0, exports.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) => {
+                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 = [
+    { 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) {
+    return value === undefined ? "undefined (void)" : JSON.stringify(value);
+}
+/** Collects what each node produced / routed to, in execution order. */
+function instrument(engine) {
+    const visited = [];
+    engine.events.on("node.succeeded", payload => {
+        const info = payload;
+        visited.push({ nodeId: info.nodeId, attempt: 1, output: info.output, route: info.route });
+    });
+    return visited;
+}
+async function main() {
+    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 automategraph_1.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();
+}
+//# sourceMappingURL=branching-edges.js.map

package/js/examples/branching-edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branching-edges.js","sourceRoot":"","sources":["../../examples/branching-edges.ts"],"names":[],"mappings":"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"}

package/js/examples/branching-graph.js

@@ -0,0 +1,232 @@
+"use strict";
+/* ============================================================
+ * Branching graph — a → b / c / d / e / f
+ * ------------------------------------------------------------
+ * ONE GraphDefinition. No router, no walk loop, no engine change.
+ * Built with the same tiny builders the fixtures use:
+ *
+ *   node(id, run, extra)      → { id, run, ...extra }
+ *   constNode(id, output, x)  → node(id, () => output, x)
+ *   g(spec)                   → GraphDefinition
+ *
+ * The picture:
+ *
+ *   a ── result === 1 ────────────▶ b ──(forces)──▶ f
+ *   a ── test(result) === true ───▶ c
+ *   a ── else ────────────────────▶ d
+ *   a ── on throw ────────────────▶ e
+ *   a ── on retry ────────────────▶ f
+ *
+ * HOW EACH ARROW IS EXPRESSED (engine-native only)
+ * ---------------------------------------------------------------
+ * fan-out + guards   `next` is an UNCONDITIONAL fan-out, so a lists
+ *                    every candidate and each one starts with a guard
+ *                    that reads a's output: the acting branch does its
+ *                    work, the others return a SKIP marker.
+ * result === 1 → b   guard: a.route === "b"
+ * test(result) → c   guard: a.route === "c"      (test(r) = r === 2)
+ * else → d           guard: a.route === "d"      (a computed "else")
+ * on throw → e       real transition: a.onThrow = "e"
+ * on retry → f       a returns route "f" when context.attempt > 1
+ *                    (the retry loop is internal, so the attempt
+ *                    number is the only per-attempt signal a node has)
+ * b forces f         b returns void, then releases a gate that f is
+ *                    waiting on — f cannot act before b finished.
+ *
+ * WHY THE GATE FOR "b FORCES f"
+ * ---------------------------------------------------------------
+ * A node cannot schedule work. The only in-node state transition the
+ * engine offers is `throw` + `onThrow`, and here it cannot be used:
+ *   • f must stay in a's fan-out, otherwise the retry arrow has no way
+ *     to reach it (a recovered attempt succeeds, it cannot also throw);
+ *   • if b threw to f, f would be activated a SECOND time, and f
+ *     cannot tell that arrival apart from the fan-out one — both see
+ *     the same outputs (b threw, so it has no output to check);
+ *   • and b would be recorded FAILED, which is wrong for a jump.
+ * So b forces f by ORDER, not by scheduling: f is already activated by
+ * the fan-out, but it blocks on a gate that only b releases. The
+ * observable result is exactly "b runs, then f runs — because of b".
+ *
+ * COMPLETION
+ * ---------------------------------------------------------------
+ * b, c, d, e and f are declared terminal and the graph uses
+ * completionPolicy: "DRAIN", because skipping nodes also succeed and
+ * FIRST_TERMINAL could otherwise latch on a SKIP and drop real work.
+ *
+ * Run:  node js/examples/branching-graph.js     (after npm run build)
+ * ============================================================ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORCE_EVENT = exports.test = void 0;
+exports.buildGraph = buildGraph;
+exports.summarise = summarise;
+const automategraph_1 = require("../src/automategraph");
+const node = (id, run, extra = {}) => ({ id, run, ...extra });
+const constNode = (id, output, extra = {}) => node(id, () => output, extra);
+const g = (spec) => ({
+    id: spec.id ?? "branching-graph",
+    version: spec.version ?? "1.0.0",
+    entryNodes: spec.entryNodes,
+    terminalNodes: spec.terminalNodes,
+    errorPolicy: spec.errorPolicy,
+    completionPolicy: spec.completionPolicy,
+    nodes: Object.fromEntries(spec.nodes.map(definition => [definition.id, definition]))
+});
+/** `test(result)` from the picture. */
+const test = (result) => result === 2;
+exports.test = test;
+const SKIPPED = (nodeId) => ({ skipped: true, nodeId });
+const routeOf = (context) => context.outputs.a;
+/** Observation only — nobody acts on this event; it just records the intent. */
+exports.FORCE_EVENT = "graph.force";
+/* =========================
+ * 3. The graph
+ * ========================= */
+/**
+ * Builds the graph for one run. A fresh gate per run is what makes
+ * "b forces f" deterministic without a router.
+ */
+function buildGraph(seed) {
+    /* --- the b → f gate (closure state, not engine state) --- */
+    let released = false;
+    let release = () => { };
+    const gate = new Promise(resolve => { release = () => { released = true; resolve(); }; });
+    return g({
+        id: "branching-graph",
+        version: "1.0.0",
+        nodes: [
+            /* ---------------- a: produces the value, owns every arrow ---------------- */
+            node("a", (context) => {
+                // on throw → e (engine transition, declared as a.onThrow below)
+                if (seed === "throw") {
+                    throw new Error("a: upstream exploded");
+                }
+                // on retry → f: the retry loop is internal, so a sees its own attempt
+                if (seed === "retry" && context.attempt === 1) {
+                    throw new Error(`a: transient failure on attempt ${context.attempt}`);
+                }
+                const result = seed === "retry" ? 2 : seed;
+                if (context.attempt > 1) {
+                    // recovered on a later attempt → the "on retry" arrow points at f
+                    return { route: "f", result, attempts: context.attempt };
+                }
+                if (result === 1)
+                    return { route: "b", result, attempts: context.attempt };
+                if ((0, exports.test)(result))
+                    return { route: "c", result, attempts: context.attempt };
+                return { route: "d", result, attempts: context.attempt }; // else
+            }, {
+                // unconditional fan-out: every candidate is activated, guards pick one
+                next: ["b", "c", "d", "f"],
+                onThrow: "e",
+                retry: { maxAttempts: 2, delayMs: 5 },
+                errorPolicy: "RETRY"
+            }),
+            /* ---------------- b: returns void, then forces f ---------------- */
+            node("b", async (context) => {
+                if (routeOf(context)?.route !== "b")
+                    return SKIPPED("b");
+                // b's work ... whatever it needs to do, it returns nothing
+                await context.emit(exports.FORCE_EVENT, { from: "b", to: "f", reason: "b short-circuits to f" });
+                release(); // ← this is the force: f is unblocked by b, after b
+                return undefined; // void
+            }),
+            /* ---------------- c: test(result) === true ---------------- */
+            node("c", (context) => routeOf(context)?.route === "c"
+                ? `c: handled result ${routeOf(context).result}`
+                : SKIPPED("c")),
+            /* ---------------- d: else ---------------- */
+            node("d", (context) => routeOf(context)?.route === "d"
+                ? `d: handled result ${routeOf(context).result}`
+                : SKIPPED("d")),
+            /* ---------------- e: on throw ---------------- */
+            constNode("e", "e: failure route"),
+            /* ---------------- f: on retry, or forced by b ---------------- */
+            node("f", async (context) => {
+                const route = routeOf(context)?.route;
+                if (route === "f")
+                    return "f: reached after a retry (on retry arrow)";
+                if (route !== "b")
+                    return SKIPPED("f");
+                // route === "b": f only acts once b has forced it
+                if (!released)
+                    await gate;
+                return "f: forced by b (ran after b completed)";
+            })
+        ],
+        entryNodes: ["a"],
+        terminalNodes: ["b", "c", "d", "e", "f"],
+        // skipping nodes succeed too, so let the graph drain instead of
+        // latching on the first success (FIRST_TERMINAL would drop work)
+        completionPolicy: "DRAIN"
+    });
+}
+/* =========================
+ * 4. Demo — one engine run per seed, no router
+ * ========================= */
+const SCENARIOS = [
+    { label: "result === 1      → b, then b forces f", seed: 1, expectedActed: ["b", "f"] },
+    { label: "test(result)      → c", seed: 2, expectedActed: ["c"] },
+    { label: "else              → d", seed: 3, expectedActed: ["d"] },
+    { label: "on throw          → e", seed: "throw", expectedActed: ["e"] },
+    { label: "on retry          → f", seed: "retry", expectedActed: ["f"] }
+];
+const isSkipped = (output) => typeof output === "object" && output !== null && output.skipped === true;
+const show = (output) => output === undefined ? "undefined (void)" : JSON.stringify(output);
+const BRANCHES = ["b", "c", "d", "e", "f"];
+/** `acted` = the branch nodes that did real work (a is the dispatcher, not a branch). */
+function summarise(report) {
+    const dispatcher = report.results.find(result => result.nodeId === "a");
+    return {
+        acted: report.results
+            .filter(result => BRANCHES.includes(result.nodeId) &&
+            result.status === "SUCCEEDED" &&
+            !isSkipped(result.output))
+            .map(result => result.nodeId),
+        status: report.status,
+        attempts: dispatcher?.attempt ?? 0
+    };
+}
+async function main() {
+    console.log("=".repeat(104));
+    console.log("branching graph — one GraphDefinition, no router, engine untouched");
+    console.log("=".repeat(104));
+    let failures = 0;
+    for (const scenario of SCENARIOS) {
+        const engine = new automategraph_1.GraphExecutionEngine(buildGraph(scenario.seed), { lint: "error" });
+        const forces = [];
+        engine.events.on(exports.FORCE_EVENT, payload => { forces.push(payload); });
+        const report = await engine.run();
+        const summary = summarise(report);
+        const actedOk = summary.acted.join(",") === scenario.expectedActed.join(",");
+        const statusOk = summary.status === "COMPLETED";
+        if (!actedOk || !statusOk)
+            failures += 1;
+        console.log(`\n▶ seed = ${JSON.stringify(scenario.seed)}   ${scenario.label}`);
+        console.log(`   status=${summary.status}  a.attempt=${summary.attempts}  ` +
+            `acted: ${summary.acted.join(" → ")}  ${actedOk && statusOk ? "✓" : "✗"}`);
+        for (const result of report.results) {
+            const tag = result.status === "SUCCEEDED" && !isSkipped(result.output)
+                ? "ACTS "
+                : result.status === "SUCCEEDED"
+                    ? "skip "
+                    : result.status.padEnd(5);
+            console.log(`     ${tag} ${result.nodeId}  attempt=${result.attempt}  output=${show(result.output)}`);
+        }
+        if (report.errors.length > 0) {
+            console.log(`   errors: ${report.errors
+                .map(error => `${error.code}@${error.nodeId ?? "-"}(handled=${error.handled})`)
+                .join(", ")}`);
+        }
+        if (forces.length > 0) {
+            console.log(`   ${exports.FORCE_EVENT}: ${JSON.stringify(forces[0])}`);
+        }
+    }
+    console.log(`\n${"-".repeat(104)}`);
+    console.log(`scenarios: ${SCENARIOS.length - failures}/${SCENARIOS.length} matched`);
+    if (failures > 0)
+        process.exitCode = 1;
+}
+if (require.main === module) {
+    void main();
+}
+//# sourceMappingURL=branching-graph.js.map