@spendgraph/graph 0.6.0 → 0.7.0

package/dist/compile/validate.d.ts

@@ -1,49 +0,0 @@
-import type { Edge, GraphSpec, Node } from "../types/index.js";
-/**
- * Everything about a graph that is wrong without running it.
- *
- * The argument for a graph over a hand-written loop: the shape is data, so it
- * can be wrong at build time rather than on the branch nobody exercised. What
- * no static check catches is a loop that never exits — that is `maxSteps`.
- */
-export declare function indexNodes(spec: GraphSpec): Map<string, Node<never>>;
-export declare function indexEdges(edges: Edge[], byName: Map<string, Node<never>>): Map<string, Edge[]>;
-/** The default when a spec names no ceiling. */
-export declare const DEFAULT_MAX_STEPS = 25;
-/**
- * The step ceiling, refusing one that would not be a ceiling.
- *
- * `NaN` is the case worth catching: `Math.max(1, NaN)` is `NaN`, and
- * `steps.length >= NaN` is false forever, so the one guard against a runaway
- * quietly turns off. A cyclic graph then spins with no way to interrupt it —
- * a synchronous node starves the event loop with microtasks, so not even a
- * timer fires. `Number(process.env.MAX_STEPS)` on an unset variable is `NaN`,
- * which is how a config gets here without anyone writing it.
- *
- * `Infinity` is refused too, and deliberately. It reads as "no limit", and the
- * limit is the point: a graph is a DAG whose ceiling exists to stop a cycle.
- */
-export declare function ceilingFor(maxSteps: number | undefined): number;
-/**
- * Refuses a node whose way out is only half specified.
- *
- * A node with **no** edges is the end of a run — the author wrote none, and
- * meant it. A node with edges that are **all conditional** is a different thing:
- * a run arriving there with every condition false has nowhere to go, stops, and
- * reports `completed`. The graph skipped the rest of its work and called it
- * success, which is the answer nobody wants and nobody asked for.
- *
- * So the line is between saying nothing and saying half of it. Declaring where a
- * run goes is a decision; declaring it only for some cases is the decision left
- * unfinished, and this is the same argument as `assertAllReachable` one step
- * later — a node nothing reaches is a typo caught at build time, a node nothing
- * *leaves* is the same typo caught on the branch nobody exercised.
- */
-export declare function assertEveryBranchIsCovered(edgesFrom: Map<string, Edge[]>): void;
-/**
- * Refuses a node nothing reaches.
- *
- * Refused rather than warned about: the usual cause is a typo in an edge, and
- * the usual symptom is a branch that quietly never runs.
- */
-export declare function assertAllReachable(entry: string, byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>): void;

package/dist/compile/validate.js

@@ -1 +0,0 @@
-function d(e){if(e.nodes.length===0)throw new Error("A graph needs at least one node.");const n=new Map;for(const o of e.nodes){if(n.has(o.name))throw new Error(`Two nodes are called "${o.name}".`);n.set(o.name,o)}if(!n.has(e.entry))throw new Error(`The entry node "${e.entry}" is not in this graph. Known: ${s(n)}.`);return n}function s(e){return[...e.keys()].join(", ")}function f(e,n){const o=new Map;for(const t of e){if(!n.has(t.from))throw new Error(`An edge starts at "${t.from}", which is not a node in this graph. Known: ${s(n)}.`);if(t.to!==null&&!n.has(t.to))throw new Error(`An edge from "${t.from}" points at "${t.to}", which is not a node in this graph. Known: ${s(n)}.`);const i=o.get(t.from)??[],h=i.find(r=>!r.when);if(h)throw new Error(`The edge from "${t.from}" to "${h.to??"the end"}" has no condition, so the edge to "${t.to??"the end"}" declared after it can never be taken. Put the unconditional edge last.`);i.push(t),o.set(t.from,i)}return o}const a=25;function c(e){if(e===void 0)return a;if(!Number.isFinite(e))throw new Error(`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 25.`);return Math.max(1,Math.floor(e))}function w(e){const n=[...e.entries()].filter(([,o])=>o.length>0&&o.every(t=>t.when)).map(([o])=>o);if(n.length!==0)throw new Error(`${n.map(o=>`"${o}"`).join(", ")} ${n.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("${n[0]}") to stop there on purpose.`)}function l(e,n,o){const t=new Set([e]),i=[e];for(;i.length;)for(const r of o.get(i.shift())??[])r.to&&!t.has(r.to)&&(t.add(r.to),i.push(r.to));const h=[...n.keys()].filter(r=>!t.has(r));if(h.length)throw new Error(`Nothing reaches ${h.map(r=>`"${r}"`).join(", ")} from "${e}". Add an edge, or take the node out.`)}export{a as DEFAULT_MAX_STEPS,l as assertAllReachable,w as assertEveryBranchIsCovered,c as ceilingFor,f as indexEdges,d as indexNodes};

package/dist/execute/execute.d.ts

@@ -1,16 +0,0 @@
-import type { Edge, GraphEvent, GraphResult, GraphRunOptions, Node } from "../types/index.js";
-/**
- * Runs a compiled graph.
- *
- * Never throws, for the reason `invoke` never throws: an exception discards the
- * two steps that worked along with the evidence of where it stopped. Every exit
- * here is a `GraphResult` carrying the steps taken.
- *
- * A failed node halts the run. Continuing would leave every later node reading
- * `outputs` for something that is not there.
- *
- * `sink` is how a run narrates itself. It is called as the run proceeds and its
- * absence changes nothing, so the streamed and unstreamed paths stay one piece
- * of code rather than two that drift.
- */
-export declare function executeGraph(byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>, entry: string, maxSteps: number, values: Record<string, unknown>, now: () => number, sink?: (event: GraphEvent) => void, opts?: GraphRunOptions): Promise<GraphResult>;

package/dist/execute/execute.js

@@ -1 +0,0 @@
-import{FieldValidationError as _,validateFields as j}from"@spendgraph/sdk";import{pausedInside as B}from"../types/index.js";import{nestedSteps as C,outputOf as G,tokensOf as K,totalTokens as R}from"./outcome.js";import{failedStep as F,message as m,sealed as g}from"./step.js";function w(r,t,i,u,h,n){return{type:"node_end",node:r,index:t,status:i,output:h,error:n,latencyMs:u}}function T(r,t){if(!r.args?.length)return null;const i=j(t,r.args);return i.length>0?new _(i).message:null}function V(r,t){let i;for(const u of r)if(!u.when||(i??=t(),u.when(i)))return u.to;return null}function q(r,t,i,u,h){return h({type:"paused",node:i,index:u,waitingOn:t.waitingOn,...t.runId?{runId:t.runId}:{}}),{...r,waitingOn:t.waitingOn,...t.runId?{waitingFor:t.runId}:{}}}async function L(r,t,i,u,h,n,c=()=>{},x={}){const S=n(),v=(x.steps??[]).map(g),a=[...v],I={...x.outputs},E=e=>({values:h,outputs:I,steps:[...a],emit:o=>c({type:"token",node:e,text:o})}),l=(e,o)=>({status:e,output:e==="completed"?a.at(-1)?.output??"":"",error:o,steps:a,outputs:I,latencyMs:n()-S,...R(a)}),O=x.entry??i;if(!r.has(O))return l("failed",`No node is called "${O}", so there is nowhere to start. \`entry\` names where a resumed run picks up. Known: ${[...r.keys()].join(", ")}.`);let $=O;for(;$;){if(a.length-v.length>=u)return l("failed",`Ran ${u} steps without reaching an end, stopping at "${$}". Either a conditional edge never turns false, or maxSteps is too low for this graph.`);const e=r.get($),o=n(),A=E($),s=a.length;let p;try{p=e.input?e.input(A):h}catch(d){return a.push(g(F(s,e.name,{},n()-o,m(d)))),c(w(e.name,s,"failed",n()-o,void 0,m(d))),l("failed",`Building the input for "${e.name}" threw: ${m(d)}`)}c({type:"node_start",node:e.name,index:s,input:p});const y=T(e,p);if(y)return a.push(g(F(s,e.name,p,n()-o,y))),c(w(e.name,s,"failed",n()-o,void 0,y)),l("failed",`"${e.name}" was given ${y}`);let f;try{f=await e.run(p,A)}catch(d){return a.push(g(F(s,e.name,p,n()-o,m(d)))),c(w(e.name,s,"failed",n()-o,void 0,m(d))),l("failed",`"${e.name}" failed: ${m(d)}`)}I[e.name]=f,a.push(g({index:s,source:e.name,input:p,output:G(f),status:"completed",latencyMs:n()-o,...K(f)})),a.push(...C(f,a.length,e.name).map(g)),c(w(e.name,s,"completed",n()-o,f));const M=B(f);if(M)return q(l("completed"),M,e.name,s,c);try{$=V(t.get(e.name)??[],()=>E(e.name))}catch(d){return l("failed",`Choosing what runs after "${e.name}" threw: ${m(d)}`)}}return l("completed")}export{L as executeGraph};

package/dist/execute/step.d.ts

@@ -1,37 +0,0 @@
-import type { RolloutStep } from "@spendgraph/sdk";
-/**
- * Same convention as a tool result: a string is itself, anything else is JSON.
- *
- * `JSON.stringify` throws on a circular object, on a `BigInt`, and on anything
- * whose own `toJSON` throws — and recording a step happens outside the guard
- * around the node, so that exception escaped `executeGraph`, which is
- * documented never to throw. It took the steps that had worked with it, which
- * is the loss that guard exists to prevent.
- *
- * A circular object is not exotic: any value with a parent backlink is one.
- *
- * What comes back when it cannot be written is a note saying so, never `""` —
- * an empty output reads as a node that produced nothing, and this is a node
- * that produced something unrecordable. The same distinction as a token count
- * that is absent rather than nought.
- */
-export declare function stringify(value: unknown): string;
-export declare function failedStep(index: number, source: string, input: Record<string, unknown>, latencyMs: number, error: string): RolloutStep;
-export declare function message(err: unknown): string;
-/**
- * A step, sealed against the nodes that will be handed it.
- *
- * `GraphContext.steps` is documented as "a copy; writing to it does nothing",
- * and the copy is shallow — so pushing onto the array was ignored while editing
- * a step *object* went straight into the run's record. A node could rewrite an
- * earlier step's output, or its token counts, and the run's totals with them.
- *
- * Frozen once here rather than deep-copied per context: the copy is already
- * O(n) on every node, and deep-copying would make that worse to buy the same
- * property. In an ES module a write to a frozen object throws, so an accident
- * announces itself rather than quietly rewriting history.
- *
- * Nothing edits a step in place — harness replaces one with `{ ...step, … }` —
- * so sealing costs nothing that is being used.
- */
-export declare function sealed(step: RolloutStep): RolloutStep;

package/dist/execute/step.js

@@ -1 +0,0 @@
-function i(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: ${n instanceof Error?n.message:String(n)}]`}}function f(t,n,r,e,o){return{index:t,source:n,input:r,output:"",status:"failed",error:o,latencyMs:e}}function s(t){return t instanceof Error?t.message:String(t)}function c(t){return Object.freeze(t)}export{f as failedStep,s as message,c as sealed,i as stringify};

package/dist/execute/stream.d.ts

@@ -1,25 +0,0 @@
-import type { Edge, GraphEvent, GraphResult, GraphRunOptions, Node } from "../types/index.js";
-/**
- * A run as it happens, and the same run once it is over.
- *
- * One reader. Events are handed out and dropped, so a second iterator takes
- * half of them rather than seeing the same run twice — fan out downstream of
- * this, not by iterating it twice.
- */
-export interface GraphStream extends AsyncIterable<GraphEvent> {
-    /**
-     * The finished run.
-     *
-     * Resolves whether or not anyone iterated, so a caller can pipe the events to
-     * a client and still record the rollout from the same run.
-     */
-    result: Promise<GraphResult>;
-}
-/**
- * Runs a compiled graph, narrating it as it goes.
- *
- * The run starts immediately rather than on the first read: a caller who only
- * wants the result should not have to iterate to get one, and a client that
- * connects late should see what already happened.
- */
-export declare function streamGraph(byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>, entry: string, maxSteps: number, values: Record<string, unknown>, now: () => number, opts?: GraphRunOptions): GraphStream;

package/dist/execute/stream.js

@@ -1 +0,0 @@
-import{executeGraph as u}from"./execute.js";class w{waiting=[];wake=null;closed=!1;push(e){this.waiting.push(e),this.release()}close(){this.closed=!0,this.release()}release(){const e=this.wake;this.wake=null,e?.()}async*drain(){for(;;){for(;this.waiting.length>0;)yield this.waiting.shift();if(this.closed)return;await new Promise(e=>{this.wake=e})}}}function d(s,e,n,r,l,h,c={}){const t=new w,i=(async()=>{try{const a=await u(s,e,n,r,l,h,o=>t.push(o),c);return t.push({type:"result",result:a}),a}finally{t.close()}})();return i.catch(()=>{}),{result:i,[Symbol.asyncIterator]:()=>t.drain()}}export{d as streamGraph};