@spendgraph/graph 0.4.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 spendgraph
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,153 +2,42 @@
 
 Wire nodes into a graph, run it, and get back a rollout with every step.
 
-```sh
+```bash
 npm install @spendgraph/graph
 ```
 
-Four things are exported. Everything else hangs off what they return.
-
-```ts
-import { graph, node, edge, end } from "@spendgraph/graph";
-```
-
-## A node
-
-One unit of work. `input` is what makes it reusable: the node says what it
-needs, the graph says where it comes from. Without that, every node has to know
-about the whole run.
-
 ```ts
-const classify = node({
-  name: "classify",
-  args: [
-    { name: "text", type: "string", required: true },
-    { name: "top_k", type: "number", required: false },
-  ] as const,
-  input: (ctx) => ({ text: ctx.values.question }),
-  run: ({ text, top_k }) => model.classify(text, top_k ?? 3),
-});
-```
-
-**Write `as const` and `run` types itself** from the args — `text` a string,
-`top_k` a number, optionals optional. Rename an argument and the handler stops
-compiling, rather than being handed `undefined` halfway through a graph, which
-is the most expensive place to find a typo.
-
-Args are validated before `run` does any work. A node name must be letters,
-digits and underscores starting with a letter, and that is checked at import
-rather than on the first run.
-
-## Wiring
+import { edge, end, graph, node } from "@spendgraph/graph";
 
-```ts
 const flow = graph({
-  entry: "classify",
-  nodes: [classify, lookup, answer],
-  edges: [
-    edge("classify", "lookup", (ctx) => ctx.outputs.classify === "billing"),
-    edge("classify", "answer"),
-    edge("lookup", "answer"),
-    end("answer"),
-  ],
+  entry: "parse",
+  nodes: [parse, divide, format],
+  edges: [edge("parse", "divide"), edge("divide", "format"), end("format")],
 });
 
-const result = await flow.execute({ question: "Why was I charged twice?" });
-```
-
-An edge says what runs next; a node's `input` says on what.
-
-**Branching is several edges, not one clever edge.** `edge(from, to, when)`
-takes a predicate, and the edges leaving a node are tried in declaration order
-with the first match winning — so an unconditional edge is the default branch
-and belongs last. `end(from)` is `edge(from, null)` said out loud.
-
-Compilation checks the wiring — an edge to a node that does not exist, an entry
-that is not a node, two nodes with the same name, a node nothing reaches —
-before anything runs. Those are the one place this package throws.
-
-## When a node fails
-
-A run never throws. A node that throws, or is handed an argument that does not
-validate, halts the run and comes back as a result:
-
-```ts
-result.status;  // "failed"
-result.error;   // '"lookup" failed: contract MSA 2.4 not found'
-result.steps;   // the steps that did run, with the failed one last
-```
-
-Continuing would leave every later node reading an output that was never
-written. Stopping with the steps intact is what lets a failed run say which
-three nodes ran and where it stopped, which a thrown exception cannot.
-
-`maxSteps` bounds the run and defaults to 25. A backwards edge is a feature and
-also how a graph hangs, and nothing tells the two apart statically, so the guard
-is a count and a clear failure rather than a hung process.
-
-## Watching it run
-
-`stream` is the same run, narrated — a node's start and end, whatever its nodes
-emit while running, and the finished result last.
-
-```ts
-const running = flow.stream({ question });
-
-for await (const event of running) {
-  if (event.type === "token") process.stdout.write(event.text);
-}
-
-const result = await running.result;
-```
-
-A node writes into the stream through the `emit` it is handed, so a node that
-wraps a streaming model call can forward deltas without the graph knowing what a
-token is. The run begins on the call rather than on the first read, so
-`result` is there for a caller who wants the rollout and not the commentary.
-
-## What comes back
-
-```ts
-result.status;    // "completed" | "failed"
-result.output;    // the last node's return, stringified; "" on a failure
-result.steps;     // every node that ran, in order
-result.outputs;   // each node's return, by name
-result.latencyMs;
-result.inputTokens;   // summed across every step, nested ones included
-result.outputTokens;
+const result = await flow.execute({ expression: "12 / 4" });
 ```
 
-A graph run is a rollout with several steps, so `GraphResult` hands straight to
-`@spendgraph/prompt`'s `report` and `call` without being translated first:
-
-```ts
-await prompt.call(values, () => flow.execute(values));
-```
+## What you get
 
-## Context
+- **A run comes back as a rollout** — every step, in order, ready to report.
+- **Compilation refuses what would fail at run time**: an unreachable node, an
+  edge to nothing, a graph with no way out.
+- **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.
 
-`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.
+## Docs
 
-```ts
-ctx.values;   // what execute() was called with
-ctx.outputs;  // what each finished node returned, by name
-ctx.steps;    // the steps so far; a copy, so writing to it does nothing
-```
-
-## Inspecting one
-
-A compiled graph answers questions about itself, which is what the workflows in
-`@spendgraph/harness` build on.
-
-```ts
-flow.entry;               // where a run starts
-flow.maxSteps;
-flow.nodes();             // every node, in declaration order
-flow.edgesFrom("classify"); // the edges leaving it, in the order they are tried
-```
+| | |
+| --- | --- |
+| [Overview](https://spendgraph.locusgraph.com/docs/graph/overview) | Four exports, and the whole thing in one example |
+| [Nodes](https://spendgraph.locusgraph.com/docs/graph/nodes) | One unit of work, typed from its args |
+| [Wiring](https://spendgraph.locusgraph.com/docs/graph/wiring) | Edges, branching, and what compilation refuses |
+| [Running a graph](https://spendgraph.locusgraph.com/docs/graph/running) | Failure, the step ceiling, what comes back |
+| [Streaming](https://spendgraph.locusgraph.com/docs/graph/streaming) | The same run, narrated |
+| [Pausing](https://spendgraph.locusgraph.com/docs/graph/pausing) | Stopping to ask a person, and picking it back up |
 
 ## License
 
-MIT
+Apache-2.0

package/dist/compile/compile.d.ts

@@ -1,5 +1,5 @@
 import { type GraphStream } from "../execute/index.js";
-import type { Edge, GraphResult, GraphSpec, Node } from "../types/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. */
     now?: () => number;
@@ -16,7 +16,7 @@ export declare function graph(spec: GraphSpec, opts?: GraphOptions): {
      * 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>) => Promise<GraphResult>;
+    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.
@@ -24,6 +24,6 @@ export declare function graph(spec: GraphSpec, opts?: GraphOptions): {
      * 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>) => GraphStream;
+    stream: (values?: Record<string, unknown>, opts?: GraphRunOptions) => GraphStream;
 };
 export type Graph = ReturnType<typeof graph>;

package/dist/compile/compile.js

@@ -1,17 +1 @@
-import { executeGraph, streamGraph } from "../execute/index.js";
-import { assertAllReachable, indexEdges, indexNodes } from "./validate.js";
-export function graph(spec, opts = {}) {
-    const now = opts.now ?? (() => Date.now());
-    const maxSteps = Math.max(1, spec.maxSteps ?? 25);
-    const byName = indexNodes(spec);
-    const edgesFrom = indexEdges(spec.edges ?? [], byName);
-    assertAllReachable(spec.entry, byName, edgesFrom);
-    return {
-        entry: spec.entry,
-        maxSteps,
-        nodes: () => [...byName.values()],
-        edgesFrom: (name) => [...(edgesFrom.get(name) ?? [])],
-        execute: (values = {}) => executeGraph(byName, edgesFrom, spec.entry, maxSteps, values, now),
-        stream: (values = {}) => streamGraph(byName, edgesFrom, spec.entry, maxSteps, values, now),
-    };
-}
+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};

package/dist/compile/index.js

@@ -1 +1 @@
-export { graph } from "./compile.js";
+import{graph as p}from"./compile.js";export{p as graph};

package/dist/compile/validate.d.ts

@@ -8,6 +8,38 @@ import type { Edge, GraphSpec, Node } from "../types/index.js";
  */
 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.
  *

package/dist/compile/validate.js

@@ -1,51 +1 @@
-export function indexNodes(spec) {
-    if (spec.nodes.length === 0)
-        throw new Error("A graph needs at least one node.");
-    const byName = new Map();
-    for (const n of spec.nodes) {
-        if (byName.has(n.name))
-            throw new Error(`Two nodes are called "${n.name}".`);
-        byName.set(n.name, n);
-    }
-    if (!byName.has(spec.entry)) {
-        throw new Error(`The entry node "${spec.entry}" is not in this graph. Known: ${[...byName.keys()].join(", ")}.`);
-    }
-    return byName;
-}
-export function indexEdges(edges, byName) {
-    const edgesFrom = new Map();
-    for (const e of edges) {
-        if (!byName.has(e.from)) {
-            throw new Error(`An edge starts at "${e.from}", which is not a node in this graph.`);
-        }
-        if (e.to !== null && !byName.has(e.to)) {
-            throw new Error(`An edge from "${e.from}" points at "${e.to}", which is not a node in this graph.`);
-        }
-        const list = edgesFrom.get(e.from) ?? [];
-        const open = list.find((prior) => !prior.when);
-        if (open) {
-            throw new Error(`The edge from "${e.from}" to "${open.to ?? "the end"}" has no condition, so the edge ` +
-                `to "${e.to ?? "the end"}" declared after it can never be taken. Put the unconditional edge last.`);
-        }
-        list.push(e);
-        edgesFrom.set(e.from, list);
-    }
-    return edgesFrom;
-}
-export function assertAllReachable(entry, byName, edgesFrom) {
-    const reached = new Set([entry]);
-    const queue = [entry];
-    while (queue.length) {
-        for (const e of edgesFrom.get(queue.shift()) ?? []) {
-            if (e.to && !reached.has(e.to)) {
-                reached.add(e.to);
-                queue.push(e.to);
-            }
-        }
-    }
-    const orphans = [...byName.keys()].filter((n) => !reached.has(n));
-    if (orphans.length) {
-        throw new Error(`Nothing reaches ${orphans.map((n) => `"${n}"`).join(", ")} from "${entry}". ` +
-            `Add an edge, or take the node out.`);
-    }
-}
+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,4 +1,4 @@
-import type { Edge, GraphEvent, GraphResult, Node } from "../types/index.js";
+import type { Edge, GraphEvent, GraphResult, GraphRunOptions, Node } from "../types/index.js";
 /**
  * Runs a compiled graph.
  *
@@ -13,4 +13,4 @@ import type { Edge, GraphEvent, GraphResult, Node } from "../types/index.js";
  * 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): Promise<GraphResult>;
+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,92 +1 @@
-import { FieldValidationError, validateFields } from "@spendgraph/sdk";
-import { nestedSteps, outputOf, tokensOf, totalTokens } from "./outcome.js";
-import { failedStep, message } from "./step.js";
-function ended(node, index, status, latencyMs, output, error) {
-    return { type: "node_end", node, index, status, output, error, latencyMs };
-}
-export async function executeGraph(byName, edgesFrom, entry, maxSteps, values, now, sink = () => { }) {
-    const startedAt = now();
-    const steps = [];
-    const outputs = {};
-    const context = (node) => ({
-        values,
-        outputs,
-        steps: [...steps],
-        emit: (text) => sink({ type: "token", node, text }),
-    });
-    const finish = (status, error) => ({
-        status,
-        output: status === "completed" ? (steps.at(-1)?.output ?? "") : "",
-        error,
-        steps,
-        outputs,
-        latencyMs: now() - startedAt,
-        ...totalTokens(steps),
-    });
-    let current = entry;
-    while (current) {
-        if (steps.length >= maxSteps) {
-            return finish("failed", `Ran ${maxSteps} steps without reaching an end, stopping at "${current}". ` +
-                `Either a conditional edge never turns false, or maxSteps is too low for this graph.`);
-        }
-        const node = byName.get(current);
-        const startedNode = now();
-        const ctx = context(current);
-        const index = steps.length;
-        let input;
-        try {
-            input = node.input ? node.input(ctx) : values;
-        }
-        catch (err) {
-            steps.push(failedStep(index, node.name, {}, now() - startedNode, message(err)));
-            sink(ended(node.name, index, "failed", now() - startedNode, undefined, message(err)));
-            return finish("failed", `Building the input for "${node.name}" threw: ${message(err)}`);
-        }
-        sink({ type: "node_start", node: node.name, index, input });
-        if (node.args?.length) {
-            const errors = validateFields(input, node.args);
-            if (errors.length > 0) {
-                const detail = new FieldValidationError(errors).message;
-                steps.push(failedStep(index, node.name, input, now() - startedNode, detail));
-                sink(ended(node.name, index, "failed", now() - startedNode, undefined, detail));
-                return finish("failed", `"${node.name}" was given ${detail}`);
-            }
-        }
-        let value;
-        try {
-            value = await node.run(input, ctx);
-        }
-        catch (err) {
-            steps.push(failedStep(index, node.name, input, now() - startedNode, message(err)));
-            sink(ended(node.name, index, "failed", now() - startedNode, undefined, message(err)));
-            return finish("failed", `"${node.name}" failed: ${message(err)}`);
-        }
-        outputs[node.name] = value;
-        steps.push({
-            index,
-            source: node.name,
-            input,
-            output: outputOf(value),
-            status: "completed",
-            latencyMs: now() - startedNode,
-            ...tokensOf(value),
-        });
-        steps.push(...nestedSteps(value, steps.length, node.name));
-        sink(ended(node.name, index, "completed", now() - startedNode, value));
-        let next = null;
-        try {
-            const after = context(node.name);
-            for (const e of edgesFrom.get(node.name) ?? []) {
-                if (e.when && !e.when(after))
-                    continue;
-                next = e.to;
-                break;
-            }
-        }
-        catch (err) {
-            return finish("failed", `Choosing what runs after "${node.name}" threw: ${message(err)}`);
-        }
-        current = next;
-    }
-    return finish("completed");
-}
+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/index.js

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

package/dist/execute/outcome.d.ts

@@ -39,8 +39,4 @@ export declare function tokensOf(value: unknown): Pick<RolloutStep, "inputTokens
  * inside a router still says which branch it came from.
  */
 export declare function nestedSteps(value: unknown, from: number, source: string): RolloutStep[];
-/** What every step in a run adds up to. */
-export declare function totalTokens(steps: RolloutStep[]): {
-    inputTokens: number;
-    outputTokens: number;
-};
+export { totalTokens } from "@spendgraph/sdk";

package/dist/execute/outcome.js

@@ -1,44 +1 @@
-import { stringify } from "./step.js";
-function isOutcome(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const v = value;
-    return (typeof v.output === "string" ||
-        typeof v.inputTokens === "number" ||
-        typeof v.outputTokens === "number" ||
-        Array.isArray(v.steps));
-}
-export function outputOf(value) {
-    const outcome = isOutcome(value) ? value : undefined;
-    return outcome && typeof outcome.output === "string" ? outcome.output : stringify(value);
-}
-export function tokensOf(value) {
-    if (!isOutcome(value))
-        return {};
-    const nested = Array.isArray(value.steps) && value.steps.length > 0;
-    return {
-        ...(!nested && typeof value.inputTokens === "number" ? { inputTokens: value.inputTokens } : {}),
-        ...(!nested && typeof value.outputTokens === "number"
-            ? { outputTokens: value.outputTokens }
-            : {}),
-        ...(value.model ? { model: value.model } : {}),
-    };
-}
-export function nestedSteps(value, from, source) {
-    if (!isOutcome(value) || !Array.isArray(value.steps))
-        return [];
-    return value.steps.map((step, at) => ({
-        ...step,
-        index: from + at,
-        source: `${source}.${step.source}`,
-    }));
-}
-export function totalTokens(steps) {
-    let inputTokens = 0;
-    let outputTokens = 0;
-    for (const step of steps) {
-        inputTokens += step.inputTokens ?? 0;
-        outputTokens += step.outputTokens ?? 0;
-    }
-    return { inputTokens, outputTokens };
-}
+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};

package/dist/execute/step.d.ts

@@ -1,5 +1,37 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-/** Same convention as a tool result: a string is itself, anything else is JSON. */
+/**
+ * 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,19 +1 @@
-export function stringify(value) {
-    if (value === undefined || value === null)
-        return "";
-    return typeof value === "string" ? value : JSON.stringify(value);
-}
-export function failedStep(index, source, input, latencyMs, error) {
-    return {
-        index,
-        source,
-        input,
-        output: "",
-        status: "failed",
-        error,
-        latencyMs,
-    };
-}
-export function message(err) {
-    return err instanceof Error ? err.message : String(err);
-}
+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,5 +1,11 @@
-import type { Edge, GraphEvent, GraphResult, Node } from "../types/index.js";
-/** A run as it happens, and the same run once it is over. */
+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.
@@ -16,4 +22,4 @@ export interface GraphStream extends AsyncIterable<GraphEvent> {
  * 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): GraphStream;
+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,49 +1 @@
-import { executeGraph } from "./execute.js";
-class Events {
-    waiting = [];
-    wake = null;
-    closed = false;
-    push(event) {
-        this.waiting.push(event);
-        this.release();
-    }
-    close() {
-        this.closed = true;
-        this.release();
-    }
-    release() {
-        const wake = this.wake;
-        this.wake = null;
-        wake?.();
-    }
-    async *drain() {
-        while (true) {
-            while (this.waiting.length > 0) {
-                yield this.waiting.shift();
-            }
-            if (this.closed)
-                return;
-            await new Promise((resolve) => {
-                this.wake = resolve;
-            });
-        }
-    }
-}
-export function streamGraph(byName, edgesFrom, entry, maxSteps, values, now) {
-    const events = new Events();
-    const result = (async () => {
-        try {
-            const finished = await executeGraph(byName, edgesFrom, entry, maxSteps, values, now, (e) => events.push(e));
-            events.push({ type: "result", result: finished });
-            return finished;
-        }
-        finally {
-            events.close();
-        }
-    })();
-    void result.catch(() => { });
-    return {
-        result,
-        [Symbol.asyncIterator]: () => events.drain(),
-    };
-}
+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};

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { type Graph, type GraphOptions, graph } from "./compile/index.js";
 export type { GraphStream } 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, GraphSpec, Node, } from "./types/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphRunOptions, GraphSpec, Node, Paused, Wait, } from "./types/index.js";
+export { pausedInside } from "./types/index.js";

package/dist/index.js

@@ -1,2 +1 @@
-export { graph } from "./compile/index.js";
-export { edge, end, node } from "./node/index.js";
+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};

package/dist/node/edge.js

@@ -1,6 +1 @@
-export function edge(from, to, when) {
-    return when ? { from, to, when } : { from, to };
-}
-export function end(from, when) {
-    return edge(from, null, when);
-}
+function t(n,e,r){return r?{from:n,to:e,when:r}:{from:n,to:e}}function u(n,e){return t(n,null,e)}export{t as edge,u as end};

package/dist/node/index.js

@@ -1,2 +1 @@
-export { edge, end } from "./edge.js";
-export { node } from "./node.js";
+import{edge as r,end as d}from"./edge.js";import{node as m}from"./node.js";export{r as edge,d as end,m as node};

package/dist/node/node.js

@@ -1,25 +1 @@
-const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export function node(spec) {
-    if (!VALID_NAME.test(spec.name)) {
-        throw new Error(`Node name "${spec.name}" must be letters, digits and underscores, starting with a letter.`);
-    }
-    const seen = new Set();
-    for (const arg of spec.args ?? []) {
-        if (!VALID_NAME.test(arg.name)) {
-            throw new Error(`Node "${spec.name}" argument "${arg.name}" is not a usable name.`);
-        }
-        if (seen.has(arg.name)) {
-            throw new Error(`Node "${spec.name}" declares "${arg.name}" twice.`);
-        }
-        seen.add(arg.name);
-        if (arg.type === "enum" && !arg.options?.length) {
-            throw new Error(`Node "${spec.name}" argument "${arg.name}" is an enum with no options, so nothing can satisfy it.`);
-        }
-    }
-    return {
-        name: spec.name,
-        args: spec.args?.map((a) => ({ ...a, options: a.options ? [...a.options] : undefined })),
-        input: spec.input,
-        run: spec.run,
-    };
-}
+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};

package/dist/types/args.js

@@ -1 +0,0 @@
-export {};

package/dist/types/context.js

@@ -1 +0,0 @@
-export {};

package/dist/types/edge.js

@@ -1 +0,0 @@
-export {};

package/dist/types/event.d.ts

@@ -1,4 +1,5 @@
 import type { GraphResult } from "./result.js";
+import type { Wait } from "./wait.js";
 /**
  * What a run says about itself while it is still running.
  *
@@ -24,6 +25,17 @@ export type GraphEvent = {
     output?: unknown;
     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.
+     */
+    type: "paused";
+    node: string;
+    index: number;
+    waitingOn: Wait;
+    /** The nested run to resume, where it named one. */
+    runId?: string;
 } | {
     type: "result";
     result: GraphResult;

package/dist/types/event.js

@@ -1 +0,0 @@
-export {};

package/dist/types/index.d.ts

@@ -3,5 +3,6 @@ export type { GraphContext } from "./context.js";
 export type { Edge } from "./edge.js";
 export type { Emit, GraphEvent } from "./event.js";
 export type { Node } from "./node.js";
-export type { GraphResult } from "./result.js";
+export type { GraphResult, GraphRunOptions } from "./result.js";
 export type { GraphSpec } from "./spec.js";
+export { type Paused, pausedInside, type Wait } from "./wait.js";

package/dist/types/index.js

@@ -1 +1 @@
-export {};
+import{pausedInside as o}from"./wait.js";export{o as pausedInside};

package/dist/types/node.js

@@ -1 +0,0 @@
-export {};

package/dist/types/result.d.ts

@@ -1,4 +1,5 @@
 import type { RolloutStep } from "@spendgraph/sdk";
+import type { Wait } from "./wait.js";
 /**
  * What one run produced, in the shape of a rollout.
  *
@@ -17,4 +18,52 @@ export interface GraphResult {
     /** Summed across every step, nested ones included. */
     inputTokens: number;
     outputTokens: number;
+    /**
+     * The question a node stopped to ask, where one did.
+     *
+     * Carried rather than said with a status: `status` reports whether the graph
+     * itself ran, and a paused run ran correctly as far as it got. Every workflow
+     * in this repo signals a pause the same way, by carrying the question.
+     */
+    waitingOn?: Wait;
+    /** The nested run to resume, where it named one. */
+    waitingFor?: string;
+}
+/** What a run may be given beyond its values. */
+export interface GraphRunOptions {
+    /**
+     * What nodes that already ran returned, for a graph picking up where an
+     * earlier run left off.
+     *
+     * Seeded into `outputs` before the entry node, so a node resuming mid-flow
+     * reads what came before it rather than an empty bag. The seeded nodes are
+     * not re-run and record no steps of their own — they already did.
+     */
+    outputs?: Record<string, unknown>;
+    /**
+     * Steps an earlier run already took, for the same graph picking up again.
+     *
+     * Seeded into `steps` before the entry node, so `ctx.steps` reads the whole
+     * run rather than only what has happened since the resume: an edge counting
+     * steps counts them all, `index` carries on instead of restarting at 0, and
+     * the result comes back as one rollout a caller need not renumber.
+     *
+     * `maxSteps` still counts this run alone — seeded steps are history, not
+     * budget.
+     */
+    steps?: RolloutStep[];
+    /**
+     * Where the walk starts, instead of the compiled entry.
+     *
+     * For resuming: a run that stopped to ask says which node it stopped at, and
+     * without this that node name is a resume point nobody can use — the walk
+     * would begin at the entry again and re-run everything before it.
+     *
+     * Reachability is checked from the compiled entry at build time. A node this
+     * names only has to exist: whatever it made unreachable has already run.
+     *
+     * `maxSteps` counts this run alone, so a resumed one starts its budget over.
+     * A caller resuming a cyclic graph repeatedly is the one holding the ceiling.
+     */
+    entry?: string;
 }

package/dist/types/result.js

@@ -1 +0,0 @@
-export {};

package/dist/types/spec.d.ts

@@ -1,7 +1,7 @@
 import type { Edge } from "./edge.js";
 import type { Node } from "./node.js";
 export interface GraphSpec {
-    /** Where a run starts. */
+    /** Where a run starts, unless `GraphRunOptions.entry` names somewhere else. */
     entry: string;
     nodes: Node<never>[];
     edges?: Edge[];

package/dist/types/spec.js

@@ -1 +0,0 @@
-export {};

package/dist/types/wait.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A run that stopped to ask something, and what it asked.
+ *
+ * Structural rather than imported: `@spendgraph/harness` owns durability and
+ * depends on this package, so the shape is declared here and its `Wait`
+ * satisfies it. The same arrangement as `llms`' `LlmReply` and the
+ * `TraceOutcome` that `prompt` accepts.
+ */
+export interface Wait {
+    question: string;
+    /** Whatever answering it needs — options to pick from, a diff, an id. */
+    detail?: unknown;
+}
+/** A paused run found inside a node's return. */
+export interface Paused {
+    waitingOn: Wait;
+    /** The id the inner run is stored under — the one a caller has to resume. */
+    runId?: string;
+}
+/**
+ * A node's return that is really a question, recognised by its shape.
+ *
+ * Structural because a node may return anything: asking callers to wrap a
+ * paused nested run in a marker would be a rule they learn by having the graph
+ * walk on past the question and report the run as done.
+ *
+ * Every node's return is put through this, so a node returning a `waitingOn`
+ * that is data rather than a question stops the run. Nothing else in a reply
+ * has that shape, and the alternative — trusting a marker — fails the other
+ * way, silently.
+ */
+export declare function pausedInside(value: unknown): Paused | null;

package/dist/types/wait.js

@@ -0,0 +1 @@
+function e(t){if(!t||typeof t!="object")return null;const r=t,n=r.waitingOn;return!n||typeof n!="object"||typeof n.question!="string"?null:{waitingOn:n,...typeof r.runId=="string"?{runId:r.runId}:{}}}export{e as pausedInside};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@spendgraph/graph",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fnLog0/spendgraph.git",
@@ -34,11 +34,12 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
-    "test": "vitest run"
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "npm run build && vitest run",
+    "typecheck": "tsc -p tsconfig.tests.json"
   },
   "dependencies": {
-    "@spendgraph/sdk": "^0.4.0"
+    "@spendgraph/sdk": "^0.6.0"
   },
   "devDependencies": {
     "typescript": "^5"