@spendgraph/graph 0.6.0 → 0.7.0

package/dist/types/result.d.ts

@@ -1,11 +1,6 @@
 import type { RolloutStep } from "@spendgraph/sdk";
 import type { Wait } from "./wait.js";
-/**
- * What one run produced, in the shape of a rollout.
- *
- * A graph run is a rollout with several steps, so this hands straight to
- * `report()` rather than being translated first.
- */
+/** What one run produced, in the shape of a rollout. */
 export interface GraphResult {
     status: "completed" | "failed";
     /** The last node's return, stringified the way a tool result is. */
@@ -18,52 +13,17 @@ 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.
-     */
+    /** The question a node stopped to ask, where one did; `status` still says the graph itself ran. */
     waitingOn?: Wait;
     /** The nested run to resume, where it named one. */
     waitingFor?: string;
 }
-/** What a run may be given beyond its values. */
+/** What a run may be given beyond its values, mostly for picking up where an earlier run stopped. */
 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.
-     */
+    /** What nodes that already ran returned; seeded into `outputs`, not re-run, no steps of their own. */
     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 an earlier run already took; `index` carries on from them, `maxSteps` does not count them. */
     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.
-     */
+    /** Where the walk starts instead of the compiled entry; only has to exist, reachability was checked at build. */
     entry?: string;
 }

package/dist/types/spec.d.ts

@@ -5,11 +5,20 @@ export interface GraphSpec {
     entry: string;
     nodes: Node<never>[];
     edges?: Edge[];
+    /** How many nodes a run may visit before it is called a loop; a nested run's steps do not count. */
+    maxSteps?: number;
     /**
-     * How many nodes a run may execute before it is called a loop. Default 25.
+     * Where the walk goes when a node fails, instead of ending the run.
+     *
+     * A node that throws otherwise ends the walk where it stands, which is the
+     * wrong ending for a run that has already done something outside itself: the
+     * seat is held, the card is charged, and nothing is left to put them back.
+     * Naming a node here gives those steps somewhere to be undone, and the
+     * handler reads `ctx.failure` for what fell over and why.
      *
-     * A backwards edge is a feature and also how a graph hangs. Nothing tells the
-     * two apart statically, so the guard is a count and a clear failure.
+     * It does not catch its own failure — a handler that throws ends the run, or
+     * a graph could compensate forever — and it does not catch an edge condition
+     * throwing, since choosing where to go next is the part that is broken there.
      */
-    maxSteps?: number;
+    onFailure?: string;
 }

package/dist/types/wait.d.ts

@@ -1,11 +1,4 @@
-/**
- * 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.
- */
+/** A run that stopped to ask something. Structural, so `harness`'s own `Wait` satisfies it without an import. */
 export interface Wait {
     question: string;
     /** Whatever answering it needs — options to pick from, a diff, an id. */
@@ -18,15 +11,14 @@ export interface Paused {
     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.
+ * A node's return that is really a question, recognised by its shape rather than
+ * a marker.
  *
- * 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.
+ * The id is read from `runId` or from `waitingFor`, which are the same thing
+ * under two names: a stored run calls it `runId`, and a graph that parked on one
+ * reports it as `waitingFor`. Reading only the first lost it at the second level
+ * of nesting — a graph inside a graph surfaced the question and not the run to
+ * answer it against, which is the one part of a pause a caller cannot work out
+ * for itself.
  */
 export declare function pausedInside(value: unknown): Paused | null;

package/dist/types/wait.js

@@ -1 +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};
+function o(r){if(!r||typeof r!="object")return null;const n=r,t=n.waitingOn;if(!t||typeof t!="object"||typeof t.question!="string")return null;const i=typeof n.runId=="string"?n.runId:n.waitingFor;return{waitingOn:t,...typeof i=="string"?{runId:i}:{}}}export{o as pausedInside};

package/docs/nodes.mdx

@@ -0,0 +1,59 @@
+export const meta = {
+  title: "Nodes — spendgraph docs",
+  description:
+    "One unit of work. Declare its arguments with `as const` and the handler types itself; say where they come from with `input`, and the node stays reusable.",
+};
+
+# Nodes
+
+A node is one unit of work: a name, the arguments it needs, where they come from, and what to do with them.
+
+```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),
+});
+```
+
+## `input` is what makes it reusable
+
+The node says what it **needs**; the graph says where it **comes from**. Without that split, every node has to know about the whole run — and a node that reads `ctx.values.question` directly is a node you cannot drop into a second graph where the question is called something else.
+
+```ts
+input: (ctx) => ({ text: ctx.values.question });        // from the run's values
+input: (ctx) => ({ text: String(ctx.outputs.draft) });  // from an earlier node
+```
+
+Leave `input` off and the node is handed the run's values as they are.
+
+## Write `as const`
+
+```ts
+args: [{ name: "text", type: "string", required: true }] as const,
+run: ({ text }) => text.toUpperCase(),   // `text` is a string, here and now
+```
+
+The handler types itself from the args: `text` a string, a `number` arg a number, an optional one optional. Rename an argument and the handler stops compiling.
+
+**Without `as const` inference falls back to `Record<string, unknown>` silently.** Nothing errors; the types simply stop meaning anything, and a typo that used to be a compile error becomes `undefined` halfway through a graph — the most expensive place to find one.
+
+<Callout tone="trap" title="A node cannot rewrite what an earlier node did">
+  The steps a node is handed are a frozen copy: writing to one changes nothing, and it will not throw to tell you so. Pass what the next node needs through the return value, which is what `input` reads.
+</Callout>
+
+## What is checked, and when
+
+Arguments are validated **before `run` does any work**, against the same `FieldSpec` types the SDK, tools and prompts all use. A node handed something that does not validate fails the run rather than being let through to fail further in.
+
+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.
+
+## Returning something
+
+Whatever `run` returns becomes the node's output: a string is itself, anything else is JSON.
+
+A value that cannot be written down — a circular object, a `BigInt`, something whose own `toJSON` throws — is recorded as `[not recordable: …]` rather than `""`. An empty output reads as a node that produced nothing, and this is a node that produced something the record could not hold. The two are different facts and the step keeps them apart.

package/docs/overview.mdx

@@ -0,0 +1,96 @@
+export const meta = {
+  title: "Graph — spendgraph docs",
+  description:
+    "Wire nodes into a graph, run it, and get back a rollout with every step priced. Four exports, compilation that catches the wiring mistakes, and a run that never throws.",
+};
+
+# Graph
+
+Multi-step work hand-rolled in `if`/`await` runs fine and leaves nothing behind: when step four fails at 2am, what ran, in what order, and what it cost are all gone.
+
+A graph is nodes and the edges between them. You describe the units of work and where control goes next; running it hands back a rollout — every step, in order, with what each one cost.
+
+```sh
+npm install @spendgraph/graph
+```
+
+Four things are exported. Everything else hangs off what they return.
+
+```ts
+import { graph, node, edge, end } from "@spendgraph/graph";
+```
+
+## The whole thing
+
+```ts
+const classify = node({
+  name: "classify",
+  args: [{ name: "text", type: "string", required: true }] as const,
+  input: (ctx) => ({ text: ctx.values.question }),
+  run: ({ text }) => model.classify(text),
+});
+
+const lookup = node({
+  name: "lookup",
+  args: [{ name: "ref", type: "string", required: true }] as const,
+  input: (ctx) => ({ ref: ctx.values.question }),
+  run: ({ ref }) => contracts.find(ref),
+});
+
+const answer = node({
+  name: "answer",
+  run: (values) => llm.call([{ role: "user", content: String(values.question) }]),
+});
+
+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"),
+  ],
+});
+
+const result = await flow.execute({ question: "Why was I charged twice?" });
+```
+
+## What you get 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;
+```
+
+A graph run **is** a rollout with several steps, so it hands straight to `@spendgraph/prompt` without being translated first:
+
+```ts
+await prompt.call(values, () => flow.execute(values));
+```
+
+## Three things worth knowing up front
+
+**Compilation is the one place this package throws.** 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, a node whose edges are all conditional — all of it is checked before anything runs. See [wiring](/docs/graph/wiring).
+
+**A run never throws.** A node that fails halts the run and comes back as a result with the steps that did run and the failed one last. A thrown exception cannot tell you which three nodes ran; a result can. See [running a graph](/docs/graph/running).
+
+**`outputs` is the only channel between nodes.** No shared mutable bag, so node four cannot come to depend on a key node two happens to set — a dependency the graph does not declare and compilation cannot check.
+
+<Callout tone="trap" title="Compilation is the only place mistakes are cheap">
+  An edge pointing at a node that does not exist, an entry that is not a node, a node nothing reaches — all refused by `graph()`, before a single model call. The same mistakes found at run time are found on the branch that reaches them, which may be the one that only runs at month end.
+</Callout>
+
+## Where to go next
+
+| | |
+| --- | --- |
+| [Nodes](/docs/graph/nodes) | declaring one, and the types you get for free |
+| [Wiring](/docs/graph/wiring) | edges, branching, and what compilation refuses |
+| [Running a graph](/docs/graph/running) | failure, the step ceiling, and what comes back |
+| [Streaming](/docs/graph/streaming) | the same run, narrated |

package/docs/pausing.mdx

@@ -0,0 +1,109 @@
+export const meta = {
+  title: "Pausing a graph — spendgraph docs",
+  description:
+    "A node that runs something needing a person stops the graph rather than walking past the question. The pause arrives as an event, and `entry` picks the run back up where it stopped.",
+};
+
+# Stopping to ask
+
+Some work needs a person: an approval, a choice between plans, a number nobody
+can infer. A node that runs something like that comes back with a **question
+rather than an answer**, and the graph stops there.
+
+```ts
+const stopped = await flow.execute({ expression: "12 / 0" });
+
+stopped.waitingOn;   // { question: "12 / 0 — what should this return?", detail }
+stopped.waitingFor;  // the nested run to resume, where it named one
+```
+
+Nothing downstream runs. Walking on would put every later node to work against a
+value nobody has supplied, and report the run as done while it is parked.
+
+## Recognised by shape, not by a marker
+
+A node returning a value that carries `waitingOn` **is** a pause. There is no
+wrapper to remember.
+
+That is the same argument as reading a node's outcome structurally: a node may
+return anything, and a rule to wrap a paused run is one you learn by having the
+graph walk past the question and call it success. Every node's return goes
+through it, so a `waitingOn` that is data rather than a question stops the run
+too — nothing else in a reply has that shape, and the alternative fails the
+other way, silently.
+
+The check itself is exported, so your own code can ask the same question the
+graph asks:
+
+```ts
+import { pausedInside } from "@spendgraph/graph";
+
+const paused = pausedInside(result);   // Paused, or null
+paused?.waitingOn.question;
+paused?.runId;                         // the inner run to resume, where there is one
+```
+
+Reach for it inside a node that runs a nested graph, or in a harness of your
+own. `Wait` is declared here rather than imported for the same reason — harness
+owns durability and depends on this package, so the shape lives on this side and
+harness's own `Wait` satisfies it.
+
+## Streaming, it is an event
+
+```ts
+for await (const event of flow.stream(values)) {
+  if (event.type === "paused") ask(event.waitingOn, event.node);
+}
+```
+
+The event carries the `Wait` whole — the question, and whatever answering it
+needs. A thrown error would carry only its message, which is why this is an
+event and not an exception.
+
+<Callout tone="trap" title="Whatever a node returned has to survive JSON">
+  A paused run is stored and handed back to running code. A `Date` comes back a string, a `Map` comes back `{}`, and neither throws — so the refusal happens at the pause, naming the node whose return would not survive, rather than three days later in whatever read it.
+</Callout>
+
+## The graph owns no durability
+
+It reports the pause and stops. Storing the run, holding it while somebody
+thinks, and handing the answer back is `@spendgraph/harness`'s job — it has the
+store, the expiry and the resume.
+
+## Picking it back up
+
+`entry` starts the walk somewhere other than the compiled entry, and `outputs`
+seeds what already ran. The `paused` event says which node stopped; this says
+where to start again.
+
+```ts
+await flow.execute(values, {
+  entry: "divide",             // the node that asked
+  outputs: stopped.outputs,    // what already ran, so nothing runs twice
+  steps: stopped.steps,        // the run so far, so it comes back as one rollout
+});
+```
+
+`steps` is the history rather than the values. Leave it out and the resumed run
+numbers its steps from 0 and shows a node an empty `ctx.steps`, so an edge like
+`(ctx) => ctx.steps.length < 3` is true all over again and two halves of one run
+cannot be stitched without renumbering them.
+
+Only existence is checked. Reachability was settled from the compiled entry at
+build time, and whatever a resume entry leaves unreachable has already run.
+
+```ts
+result.status;  // "failed"
+result.error;   // 'No node is called "divid", so there is nowhere to start. Known: parse, divide, format.'
+```
+
+**`maxSteps` counts one run**, so a resumed one starts its budget over. A caller
+resuming a cyclic graph again and again is the one holding the ceiling.
+
+## A run that paused still ran
+
+`status` says whether the graph itself ran, and a paused run ran correctly as
+far as it got — so it comes back `completed`, carrying the question.
+
+Every workflow in this repo signals a pause the same way: not with a status, but
+by carrying what it stopped to ask.

package/docs/running.mdx

@@ -0,0 +1,71 @@
+export const meta = {
+  title: "Running a graph — spendgraph docs",
+  description:
+    "A run never throws: a failed node halts it and comes back as a result with the steps that did run. The step ceiling, the context between nodes, and what a rollout carries.",
+};
+
+# Running a graph
+
+```ts
+const result = await flow.execute({ question: "Why was I charged twice?" });
+```
+
+## 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.
+
+## The step ceiling
+
+`maxSteps` bounds the run and defaults to **25**. It counts the nodes a run visits: a node that returns a nested run folds that run's steps into the rollout, and none of those count against the ceiling.
+
+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.
+
+```ts
+graph({ entry: "draft", nodes, edges, maxSteps: 50 });
+```
+
+A ceiling that is not finite is **refused at compile time**. `NaN` would make the count never fire, and `Number(process.env.MAX_STEPS)` on an unset variable is `NaN` — which is how an unbounded run arrives without anyone typing one.
+
+<Callout tone="trap" title="The ceiling counts nodes, and defaults to 25">
+  `maxSteps` bounds how many nodes a run may visit, not how many tokens it may spend — a cycle between two cheap nodes hits it, an expensive straight line never does. It defaults to 25, and a run that reaches it comes back as a *failed* result rather than a truncated success.
+</Callout>
+
+## 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;
+result.waitingOn;     // the question a node stopped to ask, where one did
+result.waitingFor;    // the nested run to resume, where it named one
+```
+
+A graph run is a rollout with several steps, so `GraphResult` hands straight to `@spendgraph/prompt`'s `report` and `call` without being translated:
+
+```ts
+await prompt.call(values, () => flow.execute(values));
+```
+
+## Context
+
+`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.
+
+```ts
+ctx.values;   // what execute() was called with
+ctx.outputs;  // what each finished node returned, by name
+ctx.steps;    // the steps so far
+```
+
+Both halves of `steps` are sealed: the array is a copy, so pushing to it changes nothing, and each step is frozen, so a node cannot rewrite what an earlier one produced or what it cost.

package/docs/streaming.mdx

@@ -0,0 +1,62 @@
+export const meta = {
+  title: "Streaming a graph — spendgraph docs",
+  description:
+    "The same run, narrated: each node's start and end, whatever its nodes emit while running, and the finished rollout last.",
+};
+
+# Streaming
+
+`stream` is the same run as `execute`, 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 emits without knowing what a token is
+
+A node is handed an `emit`, and writes into the stream through it. A node wrapping a streaming model call forwards deltas that way, and the graph never has to know what it is forwarding.
+
+```ts
+const answer = node({
+  name: "answer",
+  run: (values, ctx) => llm.stream(messages, { onText: ctx.emit }),
+});
+```
+
+`emit` takes the text and nothing else — the graph tags it with the node it came
+from, because a stream carrying tokens from four nodes is unreadable without it.
+It is always present and does nothing when nobody is listening, so a node never
+has to ask whether anyone is.
+
+## The run starts on the call, not the first read
+
+```ts
+const running = flow.stream(values);
+const result = await running.result;   // no iteration, and it still ran
+```
+
+A caller who wants the rollout and not the commentary gets it. Nothing is deferred until somebody reads the stream, so a run cannot sit there un-started because a `for await` was never reached.
+
+<Callout tone="trap" title="One stream has one reader">
+  Two `for await` loops over the same `graph.stream()` take from the same queue, so each sees roughly half the run — which reads as a graph dropping tokens rather than as the mistake it is. A second reader is refused. More than one watcher wants one reader writing into something they can both read.
+</Callout>
+
+## What the events are
+
+| | |
+| --- | --- |
+| a node starting | its name, and the step it is |
+| a node finishing | what it returned, what it cost, how long it took |
+| whatever a node emitted | passed through untouched — tokens, progress, anything |
+| a node stopping to ask | the question, and the nested run to resume — see [pausing](/docs/graph/pausing) |
+| the result | last, and the same object `execute` would have returned |
+
+One reader. Events are handed out and dropped, so a second `for await` over the
+same stream takes half of them rather than seeing the run twice — fan out
+downstream of it, not by iterating it twice.

package/docs/wiring.mdx

@@ -0,0 +1,76 @@
+export const meta = {
+  title: "Wiring — spendgraph docs",
+  description:
+    "Edges say what runs next. Branching is several edges tried in order, not one clever edge — and compilation refuses the wiring mistakes before anything runs.",
+};
+
+# Wiring
+
+An edge says what runs **next**. A node's `input` says on **what**. Keeping those separate is what lets the same node sit in two graphs.
+
+```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"),
+  ],
+});
+```
+
+## Branching is several edges, not one clever edge
+
+`edge(from, to, when)` takes a predicate. The edges leaving a node are tried **in declaration order**, and the first match wins — so an unconditional edge is the default branch and belongs last.
+
+```ts
+edge("triage", "refund", (ctx) => ctx.outputs.triage === "billing"),
+edge("triage", "escalate", (ctx) => ctx.outputs.triage === "abuse"),
+edge("triage", "answer"),   // the default, and it goes last
+```
+
+`end(from)` is `edge(from, null)` said out loud: the run finishes here.
+
+## What compilation refuses
+
+Compilation happens once, when you call `graph()`, and it is the one place this package throws. Everything it catches is a wiring mistake that would otherwise show up as a run that quietly did the wrong thing.
+
+| | |
+| --- | --- |
+| an edge to a node that does not exist | usually a typo, so the message lists the names that do |
+| an entry that is not a node | the run would have nowhere to start |
+| two nodes with the same name | one of them silently shadows the other |
+| a node nothing reaches | a branch that never runs, and nothing would say so |
+| a node whose edges are **all conditional** | the half-specified case, below |
+
+<Callout tone="trap" title="A second default edge is refused, not ignored">
+  Edges are tried in order and a default matches everything, so a second one after it can never be taken. That reads as a branch you wired and never see fire — compilation refuses it instead, naming the node.
+</Callout>
+
+## The half-specified node
+
+A node with **no** edges is the end of the run: the author wrote none and meant it.
+
+A node whose edges are *all* conditional is different. A run arriving there when no condition matches has nowhere to go — so it would stop, and report **success**, having skipped every node after it. Saying half of it is the mistake, and compilation refuses it:
+
+```ts
+edges: [
+  edge("triage", "refund", (ctx) => ctx.outputs.triage === "billing"),
+  // and nothing else leaving "triage" — refused
+];
+```
+
+Add the default edge, or add `end("triage")` if stopping there is what you meant. Either is a decision; the missing one was not.
+
+## Inspecting a compiled graph
+
+A graph answers questions about itself, which is what the workflows in `@spendgraph/harness` are built 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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/graph",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
   "license": "Apache-2.0",
   "repository": {
@@ -27,19 +27,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "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.6.0"
+    "@spendgraph/sdk": "^0.7.0"
   },
   "devDependencies": {
     "typescript": "^5"
@@ -49,5 +46,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.tests.json"
   }
-}
+}