@spendgraph/graph 0.7.0 → 0.8.1

package/dist/types/result.d.ts

@@ -13,6 +13,15 @@ export interface GraphResult {
     /** Summed across every step, nested ones included. */
     inputTokens: number;
     outputTokens: number;
+    /**
+     * The counts a provider bills apart from input and output, summed the same
+     * way — each present only where some node actually reported it, so absence
+     * is the claim that nothing was billed under it rather than a zero.
+     */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    citationTokens?: number;
+    reasoningTokens?: number;
     /** 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. */

package/docs/nodes.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Nodes — spendgraph docs",
+  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.",
 };
@@ -22,7 +22,7 @@ const classify = node({
 
 ## `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.
+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
@@ -40,7 +40,7 @@ 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.
+**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.
@@ -56,4 +56,4 @@ A node name must be letters, digits and underscores starting with a letter, and
 
 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.
+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

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Graph — spendgraph docs",
+  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.",
 };
@@ -8,12 +8,14 @@ export const meta = {
 
 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.
+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
 ```
 
+<GraphToRollout />
+
 Four things are exported. Everything else hangs off what they return.
 
 ```ts
@@ -76,21 +78,21 @@ 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).
+**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](/spendgraph/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).
+**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](/spendgraph/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.
+**`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.
+  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 |
+| [Nodes](/spendgraph/graph/nodes) | declaring one, and the types you get for free |
+| [Wiring](/spendgraph/graph/wiring) | edges, branching, and what compilation refuses |
+| [Running a graph](/spendgraph/graph/running) | failure, the step ceiling, and what comes back |
+| [Streaming](/spendgraph/graph/streaming) | the same run, narrated |

package/docs/pausing.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Pausing a graph — spendgraph docs",
+  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.",
 };
@@ -29,7 +29,7 @@ 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
+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
@@ -44,7 +44,7 @@ paused?.runId;                         // the inner run to resume, where there i
 ```
 
 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
+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.
 
@@ -56,18 +56,18 @@ for await (const event of flow.stream(values)) {
 }
 ```
 
-The event carries the `Wait` whole — the question, and whatever answering it
+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.
+  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
+thinks, and handing the answer back is `@spendgraph/harness`'s job: it has the
 store, the expiry and the resume.
 
 ## Picking it back up
@@ -103,7 +103,7 @@ 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.
+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

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Running a graph — spendgraph docs",
+  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.",
 };
@@ -20,7 +20,7 @@ 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.
+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
 
@@ -32,10 +32,10 @@ A backwards edge is a feature and also how a graph hangs, and nothing tells the
 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.
+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.
+  `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
@@ -60,7 +60,7 @@ 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.
+`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

package/docs/streaming.mdx

@@ -1,12 +1,12 @@
 export const meta = {
-  title: "Streaming a graph — spendgraph docs",
+  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.
+`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 });
@@ -29,7 +29,7 @@ const answer = node({
 });
 ```
 
-`emit` takes the text and nothing else — the graph tags it with the node it came
+`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.
@@ -44,7 +44,7 @@ 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.
+  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
@@ -53,10 +53,10 @@ A caller who wants the rollout and not the commentary gets it. Nothing is deferr
 | --- | --- |
 | 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) |
+| 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](/spendgraph/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
+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

@@ -1,7 +1,7 @@
 export const meta = {
-  title: "Wiring — spendgraph docs",
+  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.",
+    "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
@@ -23,7 +23,7 @@ const flow = graph({
 
 ## 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.
+`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"),
@@ -46,14 +46,14 @@ Compilation happens once, when you call `graph()`, and it is the one place this
 | 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.
+  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:
+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: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/graph",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,9 +36,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/sdk": "^0.7.0"
+    "@spendgraph/sdk": "^0.8.1"
   },
   "devDependencies": {
+    "@spendgraph/config": "0.8.1",
     "typescript": "^5"
   },
   "engines": {