@spendgraph/graph 0.6.0 → 0.7.0

package/README.md

@@ -26,6 +26,8 @@ const result = await flow.execute({ expression: "12 / 4" });
 - **Handlers typed from their args**, the same inference `tools` uses.
 - **A node can stop to ask a person**, and the graph reports the question rather
   than walking past it.
+- **A failed node can route somewhere** — `onFailure` names the node that runs
+  instead of the run ending, for a workflow whose earlier steps have to be undone.
 
 ## Docs
 

package/dist/compile/ceiling.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_MAX_STEPS = 25;
+/** How many nodes a run may visit, refusing NaN and Infinity since a run would never stop at either. */
+export declare function ceilingFor(maxSteps: number | undefined): number;

package/dist/compile/ceiling.js

@@ -0,0 +1 @@
+import{notACeiling as n}from"./errors.js";const r=25;function t(i){if(i===void 0)return r;if(!Number.isFinite(i))throw n(i,r);return Math.max(1,Math.floor(i))}export{r as DEFAULT_MAX_STEPS,t as ceilingFor};

package/dist/compile/compile.d.ts

@@ -1,4 +1,4 @@
-import { type GraphStream } from "../execute/index.js";
+import { type GraphStream } from "../stream/index.js";
 import type { Edge, GraphResult, GraphRunOptions, GraphSpec, Node } from "../types/index.js";
 export interface GraphOptions {
     /** Injectable clock, so tests do not measure real time. */
@@ -12,18 +12,9 @@ export declare function graph(spec: GraphSpec, opts?: GraphOptions): {
     nodes: () => Node<never>[];
     /** Edges leaving a node, in the order they will be tried. */
     edgesFrom: (name: string) => Edge[];
-    /**
-     * Runs it once. Never throws — the result carries every step taken, so a
-     * run that stopped at node three still says which three and why.
-     */
-    execute: (values?: Record<string, unknown>, opts?: GraphRunOptions) => Promise<GraphResult>;
-    /**
-     * The same run, narrated. Yields a node's start and end, whatever its nodes
-     * emit while running, and the finished result last.
-     *
-     * The run begins on the call, not on the first read, so `result` is there
-     * for the caller who wants the rollout and not the commentary.
-     */
-    stream: (values?: Record<string, unknown>, opts?: GraphRunOptions) => GraphStream;
+    /** Runs it once. Never throws — the result carries every step taken. */
+    execute: (values?: Record<string, unknown>, runOpts?: GraphRunOptions) => Promise<GraphResult>;
+    /** The same run, narrated as it goes; `result` is there whether or not anyone reads. */
+    stream: (values?: Record<string, unknown>, runOpts?: GraphRunOptions) => GraphStream;
 };
 export type Graph = ReturnType<typeof graph>;

package/dist/compile/compile.js

@@ -1 +1 @@
-import{executeGraph as m,streamGraph as i}from"../execute/index.js";import{assertAllReachable as g,assertEveryBranchIsCovered as x,ceilingFor as y,indexEdges as u,indexNodes as h}from"./validate.js";function f(e,d={}){const s=d.now??(()=>Date.now()),o=y(e.maxSteps),r=h(e),t=u(e.edges??[],r);return g(e.entry,r,t),x(t),{entry:e.entry,maxSteps:o,nodes:()=>[...r.values()],edgesFrom:n=>[...t.get(n)??[]],execute:(n={},a={})=>m(r,t,e.entry,o,n,s,void 0,a),stream:(n={},a={})=>i(r,t,e.entry,o,n,s,a)}}export{f as graph};
+import{executeGraph as i}from"../execute/index.js";import{streamGraph as l}from"../stream/index.js";import{ceilingFor as s}from"./ceiling.js";import{assertEveryBranchIsCovered as u}from"./covered.js";import{indexEdges as d}from"./edges.js";import{unknownFailureNode as F}from"./errors.js";import{indexNodes as f}from"./nodes.js";import{assertAllReachable as x}from"./reachable.js";function E(r,m={}){const e=f(r),t=d(r.edges??[],e);if(r.onFailure&&!e.has(r.onFailure))throw F(r.onFailure,[...e.keys()]);x(r.entry,e,t,r.onFailure),u(t);const n={entry:r.entry,maxSteps:s(r.maxSteps),nodes:e,edgesFrom:t,...r.onFailure?{onFailure:r.onFailure}:{},now:m.now??(()=>Date.now())};return{entry:n.entry,maxSteps:n.maxSteps,nodes:()=>[...e.values()],edgesFrom:o=>[...t.get(o)??[]],execute:(o={},a={})=>i(n,o,a),stream:(o={},a={})=>l(n,o,a)}}export{E as graph};

package/dist/compile/covered.d.ts

@@ -0,0 +1,3 @@
+import type { EdgesFrom } from "./edges.js";
+/** Refuses a node whose edges are all conditional: a run where none match would stop and report success. */
+export declare function assertEveryBranchIsCovered(edgesFrom: EdgesFrom): void;

package/dist/compile/covered.js

@@ -0,0 +1 @@
+import{onlyConditionalEdges as o}from"./errors.js";function f(r){const n=[...r.entries()].filter(([,e])=>e.length>0&&e.every(t=>t.when)).map(([e])=>e);if(n.length>0)throw o(n)}export{f as assertEveryBranchIsCovered};

package/dist/compile/edges.d.ts

@@ -0,0 +1,5 @@
+import type { Edge } from "../types/index.js";
+import { type NodesByName } from "./nodes.js";
+export type EdgesFrom = Map<string, Edge[]>;
+/** Edges grouped by the node they leave, in the order they will be tried. */
+export declare function indexEdges(edges: Edge[], nodes: NodesByName): EdgesFrom;

package/dist/compile/edges.js

@@ -0,0 +1 @@
+import{edgeAfterDefault as i,edgeFromUnknown as a,edgeToUnknown as g}from"./errors.js";import{namesOf as m}from"./nodes.js";function h(s,e){const t=new Map,f=new Map;for(const o of s){if(!e.has(o.from))throw a(o.from,m(e));if(o.to!==null&&!e.has(o.to))throw g(o.from,o.to,m(e));const r=f.get(o.from);if(r)throw i(o.from,r.to,o.to);o.when||f.set(o.from,o);const n=t.get(o.from);n?n.push(o):t.set(o.from,[o])}return t}export{h as indexEdges};

package/dist/compile/errors.d.ts

@@ -0,0 +1,14 @@
+/** A graph refused at compile time: something about its shape cannot run as written. */
+export declare class GraphSpecError extends Error {
+    constructor(message: string);
+}
+export declare const noNodes: () => GraphSpecError;
+export declare const duplicateNode: (name: string) => GraphSpecError;
+export declare const unknownEntry: (entry: string, known: string[]) => GraphSpecError;
+export declare const edgeFromUnknown: (from: string, known: string[]) => GraphSpecError;
+export declare const edgeToUnknown: (from: string, to: string, known: string[]) => GraphSpecError;
+export declare const edgeAfterDefault: (from: string, defaultTo: string | null, to: string | null) => GraphSpecError;
+export declare const notACeiling: (maxSteps: number, fallback: number) => GraphSpecError;
+export declare const onlyConditionalEdges: (names: string[]) => GraphSpecError;
+export declare const unreachable: (orphans: string[], entry: string) => GraphSpecError;
+export declare const unknownFailureNode: (name: string, known: string[]) => GraphSpecError;

package/dist/compile/errors.js

@@ -0,0 +1 @@
+class o extends Error{constructor(n){super(n),this.name="GraphSpecError"}}const r=e=>e.map(n=>`"${n}"`).join(", "),a=()=>new o("A graph needs at least one node."),s=e=>new o(`Two nodes are called "${e}".`),i=(e,n)=>new o(`The entry node "${e}" is not in this graph. Known: ${n.join(", ")}.`),d=(e,n)=>new o(`An edge starts at "${e}", which is not a node in this graph. Known: ${n.join(", ")}.`),h=(e,n,t)=>new o(`An edge from "${e}" points at "${n}", which is not a node in this graph. Known: ${t.join(", ")}.`),c=(e,n,t)=>new o(`The edge from "${e}" to "${n??"the end"}" has no condition, so the edge to "${t??"the end"}" declared after it can never be taken. Put the unconditional edge last.`),p=(e,n)=>new o(`maxSteps is ${e}, which is not a ceiling \u2014 a run would never stop at it. Give it a finite number, or leave it out for the default of ${n}.`),w=e=>new o(`${r(e)} ${e.length===1?"has":"have"} only conditional edges, so a run where none of them match stops there and reports success. Add an unconditional edge as the default, or end("${e[0]}") to stop there on purpose.`),l=(e,n)=>new o(`Nothing reaches ${r(e)} from "${n}". Add an edge, or take the node out.`),u=(e,n)=>new o(`onFailure names "${e}", which is not a node in this graph. Known: ${n.join(", ")}.`);export{o as GraphSpecError,s as duplicateNode,c as edgeAfterDefault,d as edgeFromUnknown,h as edgeToUnknown,a as noNodes,p as notACeiling,w as onlyConditionalEdges,i as unknownEntry,u as unknownFailureNode,l as unreachable};

package/dist/compile/index.d.ts

@@ -1 +1,3 @@
+export { ceilingFor, DEFAULT_MAX_STEPS } from "./ceiling.js";
 export { type Graph, type GraphOptions, graph } from "./compile.js";
+export { GraphSpecError } from "./errors.js";

package/dist/compile/index.js

@@ -1 +1 @@
-import{graph as p}from"./compile.js";export{p as graph};
+import{ceilingFor as p,DEFAULT_MAX_STEPS as e}from"./ceiling.js";import{graph as m}from"./compile.js";import{GraphSpecError as x}from"./errors.js";export{e as DEFAULT_MAX_STEPS,x as GraphSpecError,p as ceilingFor,m as graph};

package/dist/compile/nodes.d.ts

@@ -0,0 +1,4 @@
+import type { GraphSpec, Node } from "../types/index.js";
+export type NodesByName = Map<string, Node<never>>;
+export declare const namesOf: (nodes: NodesByName) => string[];
+export declare function indexNodes(spec: GraphSpec): NodesByName;

package/dist/compile/nodes.js

@@ -0,0 +1 @@
+import{duplicateNode as t,noNodes as r,unknownEntry as s}from"./errors.js";const d=n=>[...n.keys()];function f(n){if(n.nodes.length===0)throw r();const o=new Map;for(const e of n.nodes){if(o.has(e.name))throw t(e.name);o.set(e.name,e)}if(!o.has(n.entry))throw s(n.entry,d(o));return o}export{f as indexNodes,d as namesOf};

package/dist/compile/reachable.d.ts

@@ -0,0 +1,9 @@
+import type { EdgesFrom } from "./edges.js";
+import { type NodesByName } from "./nodes.js";
+/**
+ * Refuses a node nothing reaches from the entry, since the usual cause is a typo in an edge.
+ *
+ * A failure node is a second root: nothing points an edge at it, and the walk
+ * still reaches it from anywhere that falls over.
+ */
+export declare function assertAllReachable(entry: string, nodes: NodesByName, edgesFrom: EdgesFrom, onFailure?: string): void;

package/dist/compile/reachable.js

@@ -0,0 +1 @@
+import{unreachable as l}from"./errors.js";import{namesOf as i}from"./nodes.js";function d(e,h,c,a){const f=a?[e,a]:[e],r=new Set(f),s=[...f];for(let o=0;o<s.length;o++)for(const t of c.get(s[o])??[])t.to&&!r.has(t.to)&&(r.add(t.to),s.push(t.to));const n=i(h).filter(o=>!r.has(o));if(n.length)throw l(n,e)}export{d as assertAllReachable};

package/dist/execute/context.d.ts

@@ -0,0 +1,4 @@
+import type { GraphContext } from "../types/index.js";
+import type { Run } from "./run.js";
+/** What a node sees: the run so far, with a copy of the steps and an emit tagged with its name. */
+export declare function contextFor(run: Run, node: string): GraphContext;

package/dist/execute/context.js

@@ -0,0 +1 @@
+function a(t,o){return{values:t.values,outputs:t.outputs,from:t.cameFrom,failure:t.failure,steps:[...t.steps],emit:e=>t.narrate({type:"token",node:o,text:e}),note:e=>t.narrate({type:"note",node:o,data:e})}}export{a as contextFor};

package/dist/execute/errors.d.ts

@@ -0,0 +1,6 @@
+export declare const nowhereToStart: (start: string, known: string[]) => string;
+export declare const hitTheCeiling: (maxSteps: number, at: string) => string;
+export declare const inputThrew: (node: string, why: string) => string;
+export declare const givenBadArgs: (node: string, why: string) => string;
+export declare const nodeFailed: (node: string, why: string) => string;
+export declare const choosingThrew: (node: string, why: string) => string;

package/dist/execute/errors.js

@@ -0,0 +1 @@
+const n=(e,t)=>`No node is called "${e}", so there is nowhere to start. \`entry\` names where a resumed run picks up. Known: ${t.join(", ")}.`,o=(e,t)=>`Ran ${e} nodes without reaching an end, stopping at "${t}". Raising the ceiling is the last thing to try: a cycle that never exits is what it is here to stop. Otherwise a conditional edge never turns false, or the graph is genuinely longer than ${e} nodes.`,i=(e,t)=>`Building the input for "${e}" threw: ${t}`,r=(e,t)=>`"${e}" was given ${t}`,s=(e,t)=>`"${e}" failed: ${t}`,h=(e,t)=>`Choosing what runs after "${e}" threw: ${t}`;export{h as choosingThrew,r as givenBadArgs,o as hitTheCeiling,i as inputThrew,s as nodeFailed,n as nowhereToStart};

package/dist/execute/index.d.ts

@@ -1,4 +1,4 @@
-export { executeGraph } from "./execute.js";
 export type { NodeOutcome } from "./outcome.js";
-export type { GraphStream } from "./stream.js";
-export { streamGraph } from "./stream.js";
+export { resumingAt } from "./resume.js";
+export type { Compiled, Narrator } from "./run.js";
+export { executeGraph } from "./walk.js";

package/dist/execute/index.js

@@ -1 +1 @@
-import{executeGraph as o}from"./execute.js";import{streamGraph as t}from"./stream.js";export{o as executeGraph,t as streamGraph};
+import{resumingAt as o}from"./resume.js";import{executeGraph as m}from"./walk.js";export{m as executeGraph,o as resumingAt};

package/dist/execute/outcome.d.ts

@@ -1,13 +1,4 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-/**
- * What a node returned, when it returned the shape a model call produces.
- *
- * Recognised structurally rather than declared: a node may return anything, and
- * a plain object is the common case. But a node that called a model, ran a
- * prompt or nested another workflow returns tokens and sometimes its own steps,
- * and both used to be flattened into the output string and lost — which made a
- * graph run report as costing nothing.
- */
 export interface NodeOutcome {
     output?: string;
     model?: string;
@@ -17,26 +8,14 @@ export interface NodeOutcome {
     outputTokens?: number;
     cacheReadTokens?: number;
     cacheWriteTokens?: number;
-    /** A nested run's own steps, spliced in rather than stringified away. */
+    citationTokens?: number;
+    reasoningTokens?: number;
     steps?: RolloutStep[];
 }
-/** The text a step should carry: an outcome's own output, or the whole value. */
 export declare function outputOf(value: unknown): string;
-/**
- * The token counts a node reported, or nothing when it reported none.
- *
- * A node that also returns nested steps reports none here: its own totals are
- * the sum of those steps, and counting both makes a graph inside a graph cost
- * exactly twice what it did.
- */
-export declare function tokensOf(value: unknown): Pick<RolloutStep, "inputTokens" | "outputTokens"> & {
+export declare function tokensOf(value: unknown): Pick<RolloutStep, "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "citationTokens" | "reasoningTokens"> & {
     model?: string;
 };
-/**
- * A nested run's steps, renumbered to sit in this run's sequence.
- *
- * Prefixed with the node that produced them, so a step from a refine loop
- * inside a router still says which branch it came from.
- */
+/** A nested run's steps, renumbered into this run and named for the node they came from. */
 export declare function nestedSteps(value: unknown, from: number, source: string): RolloutStep[];
 export { totalTokens } from "@spendgraph/sdk";

package/dist/execute/outcome.js

@@ -1 +1 @@
-import{stringify as u}from"./step.js";function r(t){if(!t||typeof t!="object"||Array.isArray(t))return!1;const n=t;return typeof n.output=="string"||typeof n.inputTokens=="number"||typeof n.outputTokens=="number"||Array.isArray(n.steps)}function f(t){const n=r(t)?t:void 0;return n&&typeof n.output=="string"?n.output:u(t)}function s(t){if(!(typeof t!="number"||!Number.isFinite(t)||t<0))return Math.trunc(t)}function d(t){if(!r(t))return{};const n=Array.isArray(t.steps)&&t.steps.length>0,o=n?void 0:s(t.inputTokens),e=n?void 0:s(t.outputTokens);return{...o===void 0?{}:{inputTokens:o},...e===void 0?{}:{outputTokens:e},...t.model?{model:t.model}:{}}}function c(t,n,o){return!r(t)||!Array.isArray(t.steps)?[]:t.steps.filter(e=>!!e&&typeof e=="object").map((e,i)=>({...e,index:n+i,source:`${o}.${e.source??"step"}`}))}import{totalTokens as k}from"@spendgraph/sdk";export{c as nestedSteps,f as outputOf,d as tokensOf,k as totalTokens};
+import{sealed as u,stringify as f}from"./steps.js";function r(t){if(!t||typeof t!="object"||Array.isArray(t))return!1;const n=t;return typeof n.output=="string"||typeof n.inputTokens=="number"||typeof n.outputTokens=="number"||Array.isArray(n.steps)}function k(t){return r(t)&&typeof t.output=="string"?t.output:f(t)}function s(t){if(!(typeof t!="number"||!Number.isFinite(t)||t<0))return Math.trunc(t)}const p=["cacheReadTokens","cacheWriteTokens","citationTokens","reasoningTokens"];function c(t){const n={};for(const o of p)t[o]!==void 0&&(n[o]=s(t[o])??0);return n}function m(t){if(!r(t))return{};const n=Array.isArray(t.steps)&&t.steps.length>0,o=n?void 0:s(t.inputTokens),e=n?void 0:s(t.outputTokens);return{...o===void 0?{}:{inputTokens:o},...e===void 0?{}:{outputTokens:e},...n?{}:c(t),...t.model?{model:t.model}:{}}}const d=t=>!!t&&typeof t=="object"&&!Array.isArray(t);function A(t,n,o){return!r(t)||!Array.isArray(t.steps)?[]:t.steps.filter(d).map((e,i)=>u({...e,index:n+i,source:`${o}.${e.source??"step"}`}))}import{totalTokens as g}from"@spendgraph/sdk";export{A as nestedSteps,k as outputOf,m as tokensOf,g as totalTokens};

package/dist/execute/resume.d.ts

@@ -0,0 +1,16 @@
+import type { GraphResult, GraphRunOptions } from "../types/index.js";
+/**
+ * How to re-enter a graph at the node that stopped to ask.
+ *
+ * The steps it hands back stop short of that node: a nested run resumed by its
+ * own id comes back carrying its whole history, the half before the pause
+ * included, so seeding that half again would record it twice. What the outer
+ * run owns is everything before the node; what the node did is the node's to
+ * report.
+ *
+ * The **last** time the node ran, not the first. A cycle visits it more than
+ * once, and a run that went round three times before stopping paused on the
+ * third — cutting at the first would throw away every round it had already
+ * paid for.
+ */
+export declare function resumingAt(result: GraphResult, node: string): GraphRunOptions;

package/dist/execute/resume.js

@@ -0,0 +1 @@
+function n(t,e){for(let s=t.steps.length-1;s>=0;s--)if(t.steps[s].source===e)return s;return-1}function p(t,e){const s=n(t,e);return{entry:e,steps:s<0?t.steps:t.steps.slice(0,s),outputs:t.outputs}}export{p as resumingAt};

package/dist/execute/run.d.ts

@@ -0,0 +1,33 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Edge, GraphEvent, GraphResult, GraphRunOptions, Node, Paused } from "../types/index.js";
+export type Narrator = (event: GraphEvent) => void;
+/** A graph as compiled: what `execute` and `stream` walk. */
+export interface Compiled {
+    entry: string;
+    maxSteps: number;
+    nodes: Map<string, Node<never>>;
+    edgesFrom: Map<string, Edge[]>;
+    onFailure?: string;
+    now: () => number;
+}
+export interface Run {
+    compiled: Compiled;
+    values: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    steps: RolloutStep[];
+    visited: number;
+    /** The node the walk arrived from, kept on the run so every context reads the same one. */
+    cameFrom: string | null;
+    /** What sent the walk to the failure node, or null while nothing has fallen over. */
+    failure: {
+        node: string;
+        error: string;
+    } | null;
+    lastOutput: string;
+    startedAt: number;
+    narrate: Narrator;
+}
+export declare function beginRun(compiled: Compiled, values: Record<string, unknown>, opts: GraphRunOptions, narrate: Narrator): Run;
+export declare function finished(run: Run, status: "completed" | "failed", error?: string): GraphResult;
+/** A run stopped at a node that asked something: said once for the stream, once on the result. */
+export declare function parked(run: Run, asked: Paused, node: string, index: number): GraphResult;

package/dist/execute/run.js

@@ -0,0 +1 @@
+import{totalTokens as p}from"./outcome.js";import{sealed as i}from"./steps.js";function l(t,n,e,o){const u=(e.steps??[]).map(i);return{compiled:t,values:n,outputs:{...e.outputs},steps:u,visited:0,cameFrom:null,failure:null,lastOutput:"",startedAt:t.now(),narrate:o}}function r(t,n,e){return{status:n,output:n==="completed"?t.lastOutput:"",error:e,steps:t.steps,outputs:t.outputs,latencyMs:t.compiled.now()-t.startedAt,...p(t.steps)}}function d(t,n,e,o){return t.narrate({type:"paused",node:e,index:o,waitingOn:n.waitingOn,...n.runId?{runId:n.runId}:{}}),{...r(t,"completed"),waitingOn:n.waitingOn,...n.runId?{waitingFor:n.runId}:{}}}export{l as beginRun,r as finished,d as parked};

package/dist/execute/steps.d.ts

@@ -0,0 +1,7 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+/** A string is itself, anything else is JSON; what cannot be written says so rather than reading as nothing. */
+export declare function stringify(value: unknown): string;
+export declare function reasonOf(err: unknown): string;
+export declare function failedStep(index: number, source: string, input: Record<string, unknown>, latencyMs: number, error: string): RolloutStep;
+/** Frozen, so a node handed the record cannot rewrite an earlier step's output or cost. */
+export declare function sealed(step: RolloutStep): RolloutStep;

package/dist/execute/steps.js

@@ -0,0 +1 @@
+function f(t){if(t==null)return"";if(typeof t=="string")return t;try{const n=JSON.stringify(t);return n===void 0?`[not recordable: ${typeof t}]`:n}catch(n){return`[not recordable: ${i(n)}]`}}function i(t){return t instanceof Error?t.message:String(t)}function u(t,n,r,e,o){return{index:t,source:n,input:r,output:"",status:"failed",error:o,latencyMs:e}}function c(t){return Object.freeze(t)}export{u as failedStep,i as reasonOf,c as sealed,f as stringify};

package/dist/execute/visit.d.ts

@@ -0,0 +1,10 @@
+import type { Node } from "../types/index.js";
+import type { Run } from "./run.js";
+export type Visited = {
+    value: unknown;
+} | {
+    error: string;
+    why: string;
+};
+/** Runs one node: builds its input, checks its args, runs it, and records a step whichever way it went. */
+export declare function visit(run: Run, node: Node<never>): Promise<Visited>;

package/dist/execute/visit.js

@@ -0,0 +1 @@
+import{FieldValidationError as l,validateFields as m}from"@spendgraph/sdk";import{contextFor as f}from"./context.js";import{givenBadArgs as g,inputThrew as x,nodeFailed as h}from"./errors.js";import{nestedSteps as y,outputOf as O,tokensOf as A}from"./outcome.js";import{failedStep as F,reasonOf as u,sealed as d}from"./steps.js";function M(e,r){if(!e.args?.length)return null;const t=m(r,e.args);return t.length>0?new l(t).message:null}const c=e=>e.run.compiled.now()-e.startedAt;function p(e,r,t,s){const{run:n,node:o,index:a}=e,i=c(e);return n.steps.push(d(F(a,o.name,r,i,t))),n.narrate({type:"node_end",node:o.name,index:a,status:"failed",error:t,latencyMs:i}),{error:s(o.name,t),why:t}}function _(e,r,t){const{run:s,node:n,index:o}=e,a=c(e);s.outputs[n.name]=t,s.lastOutput=O(t),s.steps.push(d({index:o,source:n.name,input:r,output:s.lastOutput,status:"completed",latencyMs:a,...A(t)}));for(const i of y(t,s.steps.length,n.name))s.steps.push(i);return s.narrate({type:"node_end",node:n.name,index:o,status:"completed",output:t,latencyMs:a}),{value:t}}async function B(e,r){e.visited+=1;const t={run:e,node:r,index:e.steps.length,startedAt:e.compiled.now()},s=f(e,r.name);let n;try{n=r.input?r.input(s):e.values}catch(a){return p(t,{},u(a),x)}e.narrate({type:"node_start",node:r.name,index:t.index,input:n});const o=M(r,n);if(o)return p(t,n,o,g);try{return _(t,n,await r.run(n,s))}catch(a){return p(t,n,u(a),h)}}export{B as visit};

package/dist/execute/walk.d.ts

@@ -0,0 +1,4 @@
+import type { GraphResult, GraphRunOptions } from "../types/index.js";
+import { type Compiled, type Narrator } from "./run.js";
+/** Walks a compiled graph. Never throws: every exit is a result carrying the steps taken. */
+export declare function executeGraph(compiled: Compiled, values: Record<string, unknown>, opts?: GraphRunOptions, narrate?: Narrator): Promise<GraphResult>;

package/dist/execute/walk.js

@@ -0,0 +1 @@
+import{pausedInside as x}from"../types/index.js";import{contextFor as g}from"./context.js";import{choosingThrew as p,hitTheCeiling as w,nowhereToStart as y}from"./errors.js";import{beginRun as F,finished as a,parked as v}from"./run.js";import{reasonOf as k}from"./steps.js";import{visit as S}from"./visit.js";function T(e,t){let n;for(const o of e)if(!o.when||(n??=t(),o.when(n)))return o.to;return null}function A(e,t){try{const n=e.compiled.edgesFrom.get(t.name)??[];return{next:T(n,()=>g(e,t.name))}}catch(n){return{error:p(t.name,k(n))}}}async function j(e,t,n={},o=()=>{}){const r=F(e,t,n,o),u=n.entry??e.entry;if(!e.nodes.has(u))return a(r,"failed",y(u,[...e.nodes.keys()]));let i=u,c=null;for(;i;){if(r.visited>=e.maxSteps)return a(r,"failed",w(e.maxSteps,i));const s=e.nodes.get(i),l=r.steps.length;r.cameFrom=c;const f=await S(r,s);if("error"in f){const h=e.onFailure;if(!h||s.name===h)return a(r,"failed",f.error);r.failure={node:s.name,error:f.why},c=s.name,i=h;continue}const d=x(f.value);if(d)return v(r,d,s.name,l);const m=A(r,s);if("error"in m)return a(r,"failed",m.error);c=i,i=m.next}return a(r,"completed")}export{j as executeGraph};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { type Graph, type GraphOptions, graph } from "./compile/index.js";
-export type { GraphStream } from "./execute/index.js";
+export { type Graph, type GraphOptions, GraphSpecError, graph } from "./compile/index.js";
+export { resumingAt } from "./execute/index.js";
 export type { NodeSpec } from "./node/index.js";
 export { edge, end, node } from "./node/index.js";
-export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphRunOptions, GraphSpec, Node, Paused, Wait, } from "./types/index.js";
+export type { GraphStream } from "./stream/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphRunOptions, GraphSpec, Node, Note, Paused, Wait, } from "./types/index.js";
 export { pausedInside } from "./types/index.js";

package/dist/index.js

@@ -1 +1 @@
-import{graph as r}from"./compile/index.js";import{edge as p,end as f,node as m}from"./node/index.js";import{pausedInside as t}from"./types/index.js";export{p as edge,f as end,r as graph,m as node,t as pausedInside};
+import{GraphSpecError as o,graph as p}from"./compile/index.js";import{resumingAt as m}from"./execute/index.js";import{edge as f,end as n,node as x}from"./node/index.js";import{pausedInside as g}from"./types/index.js";export{o as GraphSpecError,f as edge,n as end,p as graph,x as node,g as pausedInside,m as resumingAt};

package/dist/node/edge.d.ts

@@ -1,10 +1,5 @@
 import type { Edge } from "../types/index.js";
-/**
- * An edge from one node to the next, or to the end of the run.
- *
- * A helper so the argument order is fixed by something other than memory:
- * `edge("a", "b")` reads in the direction the run travels.
- */
+/** An edge from one node to the next, or to the end of the run. */
 export declare function edge(from: string, to: string | null, when?: Edge["when"]): Edge;
 /** Ends the run after `from`. The same as `edge(from, null)`, said out loud. */
 export declare function end(from: string, when?: Edge["when"]): Edge;

package/dist/node/node.d.ts

@@ -5,11 +5,5 @@ export interface NodeSpec<T extends readonly ArgSpec[]> {
     input?: (ctx: GraphContext) => Record<string, unknown>;
     run(input: ArgsOf<T>, ctx: GraphContext): Promise<unknown> | unknown;
 }
-/**
- * Declares a node, checking what a graph cannot check later.
- *
- * The same argument as `tool()`: a duplicated argument silently loses one, and a
- * hyphenated name reads badly in the step record that is the only trace of a
- * failed run.
- */
+/** Declares a node, checking what a graph cannot check later. */
 export declare function node<const T extends readonly ArgSpec[]>(spec: NodeSpec<T>): Node<ArgsOf<T>>;

package/dist/node/node.js

@@ -1 +1 @@
-const o=/^[A-Za-z_][A-Za-z0-9_]*$/;function r(e){if(!o.test(e.name))throw new Error(`Node name "${e.name}" must be letters, digits and underscores, starting with a letter.`);const t=new Set;for(const n of e.args??[]){if(!o.test(n.name))throw new Error(`Node "${e.name}" argument "${n.name}" is not a usable name.`);if(t.has(n.name))throw new Error(`Node "${e.name}" declares "${n.name}" twice.`);if(t.add(n.name),n.type==="enum"&&!n.options?.length)throw new Error(`Node "${e.name}" argument "${n.name}" is an enum with no options, so nothing can satisfy it.`)}return{name:e.name,args:e.args?.map(n=>({...n,options:n.options?[...n.options]:void 0})),input:e.input,run:e.run}}export{r as node};
+const o=/^[A-Za-z_][A-Za-z0-9_]*$/;function a(e){if(!o.test(e.name))throw new Error(`Node name "${e.name}" must be letters, digits and underscores, starting with a letter.`);const t=new Set;for(const n of e.args??[]){if(!o.test(n.name))throw new Error(`Node "${e.name}" argument "${n.name}" is not a usable name.`);if(t.has(n.name))throw new Error(`Node "${e.name}" declares "${n.name}" twice.`);if(t.add(n.name),n.type==="enum"&&!n.options?.length)throw new Error(`Node "${e.name}" argument "${n.name}" is an enum with no options, so nothing can satisfy it.`)}return{name:e.name,args:e.args?.map(n=>({...n,options:n.options?[...n.options]:void 0})),input:e.input,run:e.run}}export{a as node};

package/dist/stream/events.d.ts

@@ -0,0 +1,22 @@
+import type { GraphEvent } from "../types/index.js";
+/** Events queued between the run and its one reader; a run never waits on a slow reader. */
+export declare class Events {
+    private queued;
+    private head;
+    private wake;
+    private closed;
+    private draining;
+    push(event: GraphEvent): void;
+    close(): void;
+    private release;
+    private takeNext;
+    /**
+     * The events, once.
+     *
+     * A second reader is refused rather than served: both take from the same
+     * queue, so each would see roughly half the run — which reads as a graph that
+     * dropped tokens rather than as the mistake it is. Two watchers want one
+     * reader writing into something they can both read, not two readers.
+     */
+    drain(): AsyncGenerator<GraphEvent>;
+}

package/dist/stream/events.js

@@ -0,0 +1 @@
+class s{queued=[];head=0;wake=null;closed=!1;draining=!1;push(e){this.queued.push(e),this.release()}close(){this.closed=!0,this.release()}release(){const e=this.wake;this.wake=null,e?.()}takeNext(){const e=this.queued[this.head++];return this.head===this.queued.length&&(this.queued=[],this.head=0),e}async*drain(){if(this.draining)throw new Error("This stream is already being read. Iterate it once, or await `result` instead \u2014 to show a run to more than one watcher, keep the events somewhere they can both read.");for(this.draining=!0;;){for(;this.head<this.queued.length;)yield this.takeNext();if(this.closed)return;await new Promise(e=>{this.wake=e})}}}export{s as Events};

package/dist/stream/index.d.ts

@@ -0,0 +1,2 @@
+export type { GraphStream } from "./stream.js";
+export { streamGraph } from "./stream.js";

package/dist/stream/index.js

@@ -0,0 +1 @@
+import{streamGraph as e}from"./stream.js";export{e as streamGraph};

package/dist/stream/stream.d.ts

@@ -0,0 +1,9 @@
+import { type Compiled } from "../execute/index.js";
+import type { GraphEvent, GraphResult, GraphRunOptions } from "../types/index.js";
+/** A run as it happens, and the same run once it is over. Iterable once. */
+export interface GraphStream extends AsyncIterable<GraphEvent> {
+    /** Resolves whether or not anyone iterated. */
+    result: Promise<GraphResult>;
+}
+/** Runs a compiled graph, narrating it; the run starts on the call, not on the first read. */
+export declare function streamGraph(compiled: Compiled, values: Record<string, unknown>, opts?: GraphRunOptions): GraphStream;

package/dist/stream/stream.js

@@ -0,0 +1 @@
+import{executeGraph as c}from"../execute/index.js";import{Events as u}from"./events.js";function l(n,o,s={}){const t=new u,r=(async()=>{try{const e=await c(n,o,s,a=>t.push(a));return t.push({type:"result",result:e}),e}finally{t.close()}})();return r.catch(()=>{}),{result:r,[Symbol.asyncIterator]:()=>t.drain()}}export{l as streamGraph};

package/dist/types/args.d.ts

@@ -1,12 +1,5 @@
 import type { FieldType } from "@spendgraph/sdk";
-/**
- * A declared argument, as written.
- *
- * Structurally a `FieldSpec` with every field readonly, because that is what an
- * `as const` array produces — and `FieldSpec.options` being a mutable `string[]`
- * is enough to make the whole tuple fail the constraint and inference fall back
- * to nothing, silently.
- */
+/** A declared argument as written: a readonly `FieldSpec`, which is what an `as const` array produces. */
 export interface ArgSpec {
     readonly name: string;
     readonly type: FieldType;
@@ -41,13 +34,7 @@ type Required<T> = T extends {
 type Optional<T> = T extends {
     required: true;
 } ? never : T;
-/**
- * The object `run` is handed, derived from the args you declared.
- *
- * Declare `args` with `as const` and the handler's parameter types follow, so a
- * renamed argument is a compile error rather than an `undefined` discovered
- * halfway through a graph.
- */
+/** The object `run` is handed, derived from the args declared `as const`. */
 export type ArgsOf<T extends readonly ArgSpec[]> = {
     [F in Required<T[number]> as F["name"]]: ArgValue<F>;
 } & {

package/dist/types/context.d.ts

@@ -1,25 +1,50 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-import type { Emit } from "./event.js";
-/**
- * What a node can see while it decides and while it runs.
- *
- * `outputs` is the only channel between nodes. A shared mutable bag would let
- * node four depend on a key node two happens to set — a dependency the graph
- * does not declare and compilation cannot check.
- */
+import type { Emit, Note } from "./event.js";
+/** What a node can see while it decides and while it runs; `outputs` is the only channel between nodes. */
 export interface GraphContext {
     /** The object `execute` was called with. */
     values: Record<string, unknown>;
-    /** What each node that has finished returned, by name. */
+    /**
+     * What each node that has finished returned, by name.
+     *
+     * By name, so a node a cycle comes back to overwrites what it returned last
+     * time — a retry reads the attempt it just made, not the first one. Keeping
+     * every pass would make `outputs` a different shape for a cyclic graph than a
+     * straight one, and every reader would owe a check it usually does not need.
+     */
     outputs: Record<string, unknown>;
+    /**
+     * The node that routed here, or null on the entry node.
+     *
+     * What a node reached from more than one place otherwise has to guess at, by
+     * probing `outputs` for whichever branch's node happens to have run. That
+     * guess is wrong in a graph with a cycle: `outputs` keeps the last value a
+     * node returned for the rest of the run, so a join reached a second time
+     * reads a branch it did not come through this pass.
+     */
+    from: string | null;
+    /**
+     * What failed on the way here, for a node reached by `onFailure`.
+     *
+     * Null everywhere else, and on the failure node itself when the run reached
+     * it through an ordinary edge — which is how a compensating node tells "I am
+     * cleaning up after a crash" from "I was walked through in the normal way".
+     */
+    failure: {
+        node: string;
+        error: string;
+    } | null;
     /** The steps recorded so far, in order. A copy; writing to it does nothing. */
     steps: RolloutStep[];
+    /** Sends a token out of the run, tagged with this node. A no-op unless someone is streaming. */
+    emit: Emit;
     /**
-     * Sends a token out of the run, tagged with the node that emitted it.
+     * Sends structured progress out of the run, tagged with this node.
      *
-     * Hand it straight to a model call as its `onText` and the deltas leave the
-     * graph as they arrive. Always present, and a no-op unless someone is
-     * streaming, so a node never has to ask whether anyone is listening.
+     * `emit` is for what the model is saying; this is for what the run is doing —
+     * which step of how many, what it found, how far along. A node reaches it
+     * through the context rather than closing over the caller's, so a step defined
+     * in another module can report progress without being handed a channel.
      */
-    emit: Emit;
+    note: Note;
 }

package/dist/types/edge.d.ts

@@ -4,9 +4,6 @@ export interface Edge {
     from: string;
     /** The next node, or null to end the run here. */
     to: string | null;
-    /**
-     * Taken only when true. Tried in declaration order, first match wins — so an
-     * unconditional edge is the default branch and belongs last.
-     */
+    /** Taken only when true. */
     when?: (ctx: GraphContext) => boolean;
 }

package/dist/types/event.d.ts

@@ -1,12 +1,6 @@
 import type { GraphResult } from "./result.js";
 import type { Wait } from "./wait.js";
-/**
- * What a run says about itself while it is still running.
- *
- * Every event names the node it came from, because a stream carrying tokens
- * from four nodes is unreadable without it — and which nodes are worth showing
- * is the consumer's decision, not the graph's.
- */
+/** What a run says about itself while it is still running; every event names its node. */
 export type GraphEvent = {
     type: "node_start";
     node: string;
@@ -17,6 +11,11 @@ export type GraphEvent = {
     type: "token";
     node: string;
     text: string;
+} | {
+    /** Whatever a node chose to say about its own progress, as data. */
+    type: "note";
+    node: string;
+    data: unknown;
 } | {
     type: "node_end";
     node: string;
@@ -26,10 +25,7 @@ export type GraphEvent = {
     error?: string;
     latencyMs: number;
 } | {
-    /**
-     * A node returned a run that stopped to ask. The walk stops here, so
-     * nothing downstream runs against an answer nobody has given yet.
-     */
+    /** A node returned a run that stopped to ask; the walk stops here. */
     type: "paused";
     node: string;
     index: number;
@@ -42,3 +38,5 @@ export type GraphEvent = {
 };
 /** Where a node's tokens go. A run that nobody is streaming drops them. */
 export type Emit = (text: string) => void;
+/** Where a node's structured progress goes. Dropped the same way when nobody is listening. */
+export type Note = (data: unknown) => void;

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export type { ArgSpec, ArgsOf, ArgValue } from "./args.js";
 export type { GraphContext } from "./context.js";
 export type { Edge } from "./edge.js";
-export type { Emit, GraphEvent } from "./event.js";
+export type { Emit, GraphEvent, Note } from "./event.js";
 export type { Node } from "./node.js";
 export type { GraphResult, GraphRunOptions } from "./result.js";
 export type { GraphSpec } from "./spec.js";

package/dist/types/node.d.ts

@@ -1,18 +1,10 @@
 import type { FieldSpec } from "@spendgraph/sdk";
 import type { GraphContext } from "./context.js";
-/**
- * One unit of work in a graph.
- *
- * `input` is what makes a node reusable: the node says what it needs, the graph
- * says where it comes from. Without it every node has to know the whole run.
- */
+/** One unit of work in a graph. */
 export interface Node<Args = Record<string, unknown>> {
     /** Unique in the graph, and the key its output is stored under. */
     name: string;
-    /**
-     * What this node needs, validated before `run` does any work. Halfway through
-     * a graph is the most expensive place to discover a typo.
-     */
+    /** What this node needs, validated before `run` does any work. */
     args?: FieldSpec[];
     /** The edge's data half: an edge says what runs next, this says on what. */
     input?: (ctx: GraphContext) => Record<string, unknown>;