automategraph 1.5.0 → 1.5.3

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

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

package/js/examples/branching-router.js

@@ -0,0 +1,305 @@
+"use strict";
+/* ============================================================
+ * 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.
+ * ============================================================ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GOTO_EVENT = exports.test = void 0;
+exports.buildSteps = buildSteps;
+exports.decide = decide;
+exports.runWalk = runWalk;
+const automategraph_1 = require("../src/automategraph");
+/** The spec's `test(result)`: decides between c and d. */
+const test = (result) => result === 2;
+exports.test = test;
+/** Event a node emits when it wants to force the next hop from inside. */
+exports.GOTO_EVENT = "router.goto";
+/* =========================
+ * 2. The nodes
+ * ========================= */
+function buildSteps(state) {
+    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" && (0, exports.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(exports.GOTO_EVENT, {
+                    to: "f",
+                    reason: "b short-circuits to f"
+                });
+                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, step, state) {
+    const definition = {
+        id,
+        run: (context) => 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 }
+    };
+}
+function isGotoRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.to === "string");
+}
+async function runOne(nodeId, step, state, storage) {
+    const engine = new automategraph_1.GraphExecutionEngine(stepGraph(nodeId, step, state), {
+        storage,
+        maxActivations: 1 // a hop starts exactly one activation
+    });
+    let attempts = 0;
+    const gotoRequests = [];
+    // 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;
+        attempts = Math.max(attempts, attempt);
+    }, { required: true });
+    engine.events.on(exports.GOTO_EVENT, payload => {
+        if (isGotoRequest(payload))
+            gotoRequests.push(payload);
+    }, { required: true });
+    const report = await engine.run();
+    return { report, attempts, gotoRequests };
+}
+/**
+ * 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.
+ */
+function decide(routes, run) {
+    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.
+ */
+async function runWalk(seed, options = {}) {
+    const storage = options.storage ?? new automategraph_1.InMemoryStorage();
+    const maxSteps = options.maxSteps ?? 64;
+    const state = { seed, visited: [], notes: [] };
+    const steps = buildSteps(state);
+    const hops = [];
+    const executionIds = [];
+    let current = "a";
+    while (current !== undefined) {
+        if (hops.length >= maxSteps) {
+            throw new automategraph_1.AutomateGraphError(`Walk exceeded maxSteps=${maxSteps} (possible cycle)`, "WALK_STEP_LIMIT", { visited: [...state.visited] });
+        }
+        const step = steps[current];
+        if (!step) {
+            throw new automategraph_1.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 = {
+            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 = [
+    { 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) {
+    return value === undefined ? "undefined" : JSON.stringify(value);
+}
+async function main() {
+    const storage = new automategraph_1.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();
+}
+//# sourceMappingURL=branching-router.js.map

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

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

package/js/examples/json-graph.js

@@ -0,0 +1,197 @@
+"use strict";
+/* ============================================================
+ * 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)
+ * ============================================================ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const graph_json_1 = require("../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) {
+    return value === "priority";
+}
+function chargeCard(context) {
+    if (context.attempt === 1) {
+        throw new Error("chargeCard: gateway timeout (transient)");
+    }
+    return "charged";
+}
+function shipOrder() {
+    return "shipped";
+}
+function manualReview() {
+    return "queued for a human";
+}
+function rejectOrder() {
+    return "rejected";
+}
+/*
+ * Three classifier IMPLEMENTATIONS — the document itself never changes.
+ * Each has its own source, so the registry fingerprint moves with it.
+ */
+function classifyAsPriority() {
+    return "priority";
+}
+function classifyAsManual() {
+    return "manual";
+}
+function classifyAsStandard() {
+    return "standard";
+}
+const SCENARIOS = [
+    {
+        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() {
+    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 = (0, graph_json_1.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;
+    for (const scenario of SCENARIOS) {
+        const engine = (0, graph_json_1.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();
+}
+//# sourceMappingURL=json-graph.js.map

package/js/examples/json-graph.js.map

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