nexus-ai-pro 1.7.0 → 1.9.0

package/API_STABILITY.md

@@ -225,6 +225,28 @@ guarantee about how the registry is maintained, not a runtime surface: the resol
 `KNOWN_MODELS`, and a test asserts the two match. Switching the resolver over is a later change, so
 that introducing generation cannot alter pricing behavior in the same release.
 
+## Graph API stage
+
+`createGraph`, `StateGraph`, `CompiledGraph`, the channel constructors, both checkpointers, the error
+classes, and the `nexus-ai-pro/graph` subpath are public and follow the 1.x rules, as are the
+normalized checkpoint, result, and step-event shapes.
+
+Four behaviors are guaranteed. A superstep is atomic with respect to checkpointing: state is reduced
+and written before the next set of nodes is computed. A node that finished is never re-run by a
+resume, so a completed branch's side effect happens once. `interrupt()` returns the supplied value on
+replay rather than throwing again, keyed by node, step, and position, so a node may ask more than one
+question. And `GraphCheckpoint` stays JSON-serializable, because a checkpoint that cannot be written
+to Redis is not a checkpoint.
+
+`GraphCheckpointer` is deliberately not generic over the channel schema: it persists opaque state,
+and threading the schema through it would force an annotation on every construction for no benefit.
+The graph casts at that boundary and hands typed state back through `state()` and `history()`.
+
+Scheduling within a superstep is not a guarantee. Nodes in a fan-out currently run in edge order and
+sequentially; running them concurrently is a valid future change, so a node must not depend on
+observing another node's write within the same superstep — that is what channels are for. The default
+`maxSteps` may change; pass it explicitly when a run depends on the bound.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,66 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [Unreleased]
+
+## [1.9.0] - 2026-09-15
+
+Install weight, made measurable and enforced. Every export subpath now has a size budget that
+CI holds it to, the README publishes what each import costs, and enforcing a cost budget no
+longer loads the model catalogue. No public API changed.
+
+### Added
+
+- **A per-subpath size budget, enforced in CI.** `npm run size:check` measures the transitive import
+  graph of every one of the 70 export subpaths and fails when an entry point grows past its recorded
+  budget. The package already budgeted the whole tarball, which is exactly why per-entry growth went
+  unnoticed across three releases while the total budget was raised three times: a shared module
+  pulled into an otherwise small entry point does not move the tarball at all, it only moves what a
+  consumer pays to import one piece. `npm run size:update` rewrites the budgets and regenerates the
+  README table.
+- **A published size table.** The README now carries what each import actually costs, generated from
+  the build rather than written by hand, and the check fails if it goes stale. The claim is now
+  verifiable before installing.
+
+### Changed
+
+- **Enforcing a cost budget no longer loads the model catalogue.** `assertWithinCostBudget`,
+  `CostBudgetError`, `formatCost`, and `DEFAULT_CURRENCY` moved to `optimizer/cost-budget.ts`, which
+  has no registry dependency; `optimizer/cost.ts` re-exports all four, so no import changes and the
+  error classes stay identical rather than becoming copies. Comparing two numbers had been dragging
+  30 KB of chat-model data along with it.
+- **`nexus-ai-pro/embeddings` is 29% smaller**, 129 KB down to 91 KB, and no longer reaches
+  `types/providers.js` at all. A test pins that, not just the budget.
+
+## [1.8.0] - 2026-09-14
+
+Graphs. Nodes, edges, cycles, fan-out and subgraphs over typed state, with every superstep
+checkpointed so a run is resumable, inspectable and interruptible by construction rather than
+after opting in, on a subpath that costs 5% of the root import.
+
+### Added
+
+- **Typed state graphs.** `nexus-ai-pro/graph` adds nodes, edges, conditional edges, cycles, fan-out,
+  and subgraphs over typed state channels: explicit nodes and edges, persistent graph state,
+  checkpoint and resume, human-in-the-loop interrupts, and complex branching.
+- **Durable by construction.** Every superstep is checkpointed, so a run is resumable without opting
+  into a checkpointer first. `MemoryGraphCheckpointer` covers a single process;
+  `OperationStoreCheckpointer` persists through the `OperationStore` that already backs durable
+  operations, which makes a Redis-backed thread a one-line change and lets a different worker resume
+  what another suspended. The store is imported as a type only, so the graph subpath stays small.
+- **Human in the loop.** A node calls `context.interrupt()`; the graph checkpoints and reports
+  `awaiting_input`, and `resume()` supplies the value. On replay the same call returns that value
+  instead of throwing, keyed by node, step, and position, so one node can ask several questions
+  across several resumes. A sibling branch that already completed is not re-run.
+- **Channels with reducers** — `lastValue`, `appendList`, `appendSet`, `mergeObject`, `counter`, and
+  `reducerChannel` — so two branches writing the same slot in one superstep combine rather than
+  clobber.
+- **Time travel.** `state()`, `history()`, and `resumeFrom(step)` read and rewind a thread.
+- **Compile-time validation.** An edge to an unknown node, a node nothing routes to, a duplicate node
+  name, and a reserved name are all refused at `compile()` rather than at run time.
+- New subpath `nexus-ai-pro/graph`. It is deliberately absent from the root import, so a user who
+  does not build graphs pays nothing for it.
+
 ## [1.7.0] - 2026-09-08
 
 Batch economics, distributed limits, and durable assets: the rest of the theme *work that
@@ -397,7 +457,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.9.0...HEAD
+[1.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...v1.9.0
+[1.8.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...v1.8.0
 [1.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...v1.7.0
 [1.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.4.0...v1.5.0

package/README.md

@@ -85,6 +85,7 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - add tools, agents, RAG context, evals, batch jobs, and queues
 - embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
 - run long operations that survive a restart, with leases, retries, dead-lettering, and signed webhooks
+- build stateful graphs with cycles, fan-out, subgraphs, human approval, and resumable checkpoints
 - trip routing away from a failing provider, and share one rate-limit budget across workers
 - reach the providers' half-price asynchronous batch tier behind one operation handle
 - persist generated media to disk or S3 with tenant isolation, retention, and checksums
@@ -421,6 +422,90 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Graphs
+
+A graph is nodes, edges, and typed state. Cycles, fan-out, subgraphs, and human approval are
+supported shapes rather than workarounds, and every run is checkpointed, so it is resumable by
+construction rather than after configuring a checkpointer.
+
+```ts
+import { createGraph, appendList, counter, END, MemoryGraphCheckpointer } from 'nexus-ai-pro/graph';
+
+const graph = createGraph({
+  channels: { messages: appendList<string>(), turns: counter() },
+})
+  .addNode('research', async (ctx) => ({ messages: [await search(ctx.state.messages)], turns: 1 }))
+  .addNode('answer', async (ctx) => ({ messages: [await ai.complete(...).then((r) => r.content)] }))
+  .setEntry('research')
+  .addConditionalEdges('research', (state) => (state.turns >= 3 ? 'answer' : 'research'))
+  .addEdge('answer', END)
+  .compile({ checkpointer: new MemoryGraphCheckpointer() });
+
+const result = await graph.invoke({ messages: ['who won?'] }, { threadId: 'q-42' });
+```
+
+**Channels, not assignment.** Each state slot declares how writes combine — `lastValue`,
+`appendList`, `appendSet`, `mergeObject`, `counter`, or your own `reducerChannel`. That is what makes
+fan-out safe: two branches running in the same superstep can both write, and the channel decides
+whether that means overwrite, append, or sum. Assignment would silently drop one branch's work.
+
+**Cycles are first-class**, so `maxSteps` is what stands between a mistaken router and an infinite
+loop. Exceeding it names the nodes still pending rather than hanging.
+
+**Human in the loop.** A node calls `interrupt()`; the graph checkpoints and stops:
+
+```ts
+.addNode('approve', (ctx) => ({
+  approved: ctx.interrupt<boolean>({ reason: 'Publish this draft?', payload: { chars: 1200 } }),
+}))
+```
+
+```ts
+const run = await graph.invoke(input, { threadId });
+if (run.status === 'awaiting_input') {
+  // Hours later, in another process:
+  await graph.resumeWith(threadId, true);
+}
+```
+
+The interrupted node runs again from the top and `interrupt()` returns the supplied value instead of
+throwing, so the node body reads as straight-line code either way. Keep the work before an interrupt
+cheap, because it happens twice. A sibling branch that already finished is **not** re-run — its
+writes were checkpointed before the graph suspended.
+
+**Time travel and inspection.** Every superstep is a checkpoint:
+
+```ts
+await graph.state(threadId);        // latest checkpoint
+await graph.history(threadId);      // newest first
+graph.resumeFrom(threadId, 3);      // rewind and run forward
+```
+
+**Durable by construction.** The default checkpointer is in-process. Point it at the operation store
+that already backs durable operations and a thread survives a restart — a different worker resumes
+what another suspended:
+
+```ts
+import { OperationStoreCheckpointer } from 'nexus-ai-pro/graph';
+import { RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+
+const checkpointer = new OperationStoreCheckpointer(new RedisOperationStore(redis));
+```
+
+Writes are compare-and-set on the record's sequence, so two workers advancing the same thread cannot
+both win.
+
+**Subgraphs.** A compiled graph is a node:
+
+```ts
+parent.addNode('research', researchGraph.asNode());
+```
+
+Channels shared by name are passed in and merged back; anything the parent does not declare stays
+private to the subgraph.
+
+The graph is not in the root import. It costs nothing to a user who does not build graphs.
+
 ## Provider Batch Tiers
 
 Both OpenAI and Anthropic sell an asynchronous tier at roughly half price, in exchange for a
@@ -428,6 +513,7 @@ completion window measured in hours. Local `runBatch()` concurrency cannot reach
 different API. `BatchManager` puts both behind one operation handle.
 
 ```ts
+import { createGraph } from 'nexus-ai-pro/graph';
 import { BatchManager } from 'nexus-ai-pro/batch';
 import { OpenAIBatchProvider } from 'nexus-ai-pro/batch/openai';
 
@@ -1538,6 +1624,90 @@ import { createTelephonyRealtimeBridge } from 'nexus-ai-pro/telephony/realtime-b
 
 Provider SDKs are optional peer dependencies. The package ships ESM and CommonJS builds, supports Node.js 22+, and is marked with `sideEffects: false`. Only the entry points listed in the package export map are public; deep imports into `dist`, `dist-cjs`, or `src` are unsupported.
 
+### What each import actually costs
+
+Importing one piece loads one piece. The figures below are the transitive import graph of each entry
+point, generated from the build by `npm run size:check`, which fails CI when an entry point grows
+past its budget — so the numbers stay true rather than aspirational.
+
+<!-- size-table:start -->
+| Import | Size | Share of root |
+| --- | --- | --- |
+| `nexus-ai-pro` | 606 KB | 100% |
+| `nexus-ai-pro/config` | 465 KB | 77% |
+| `nexus-ai-pro/core` | 459 KB | 76% |
+| `nexus-ai-pro/realtime` | 157 KB | 26% |
+| `nexus-ai-pro/batch` | 118 KB | 19% |
+| `nexus-ai-pro/realtime/session` | 94 KB | 16% |
+| `nexus-ai-pro/embeddings` | 91 KB | 15% |
+| `nexus-ai-pro/providers/groq` | 79 KB | 13% |
+| `nexus-ai-pro/providers/mistral` | 79 KB | 13% |
+| `nexus-ai-pro/providers/azure-openai` | 78 KB | 13% |
+| `nexus-ai-pro/providers/openrouter` | 78 KB | 13% |
+| `nexus-ai-pro/providers/deepseek` | 77 KB | 13% |
+| `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% |
+| `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% |
+| `nexus-ai-pro/providers/openai` | 77 KB | 13% |
+| `nexus-ai-pro/providers/anthropic` | 70 KB | 12% |
+| `nexus-ai-pro/providers/google` | 66 KB | 11% |
+| `nexus-ai-pro/images` | 63 KB | 10% |
+| `nexus-ai-pro/providers/ollama` | 58 KB | 10% |
+| `nexus-ai-pro/batch/openai` | 52 KB | 9% |
+| `nexus-ai-pro/batch/anthropic` | 52 KB | 9% |
+| `nexus-ai-pro/operations` | 49 KB | 8% |
+| `nexus-ai-pro/batch/mock` | 47 KB | 8% |
+| `nexus-ai-pro/providers/cohere` | 46 KB | 8% |
+| `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% |
+| `nexus-ai-pro/security` | 40 KB | 7% |
+| `nexus-ai-pro/models` | 35 KB | 6% |
+| `nexus-ai-pro/graph` | 29 KB | 5% |
+| `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% |
+| `nexus-ai-pro/evals` | 23 KB | 4% |
+| `nexus-ai-pro/images/stores` | 22 KB | 4% |
+| `nexus-ai-pro/telephony/twilio` | 21 KB | 3% |
+| `nexus-ai-pro/telephony` | 20 KB | 3% |
+| `nexus-ai-pro/realtime/mock` | 19 KB | 3% |
+| `nexus-ai-pro/voice` | 18 KB | 3% |
+| `nexus-ai-pro/images/openai` | 18 KB | 3% |
+| `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% |
+| `nexus-ai-pro/realtime/conversation` | 16 KB | 3% |
+| `nexus-ai-pro/images/assets` | 14 KB | 2% |
+| `nexus-ai-pro/context` | 13 KB | 2% |
+| `nexus-ai-pro/operations/adapters` | 13 KB | 2% |
+| `nexus-ai-pro/realtime/tools` | 13 KB | 2% |
+| `nexus-ai-pro/workflows` | 13 KB | 2% |
+| `nexus-ai-pro/images/mock` | 12 KB | 2% |
+| `nexus-ai-pro/optimizer` | 11 KB | 2% |
+| `nexus-ai-pro/voice/session` | 11 KB | 2% |
+| `nexus-ai-pro/providers` | 10 KB | 2% |
+| `nexus-ai-pro/providers/base` | 10 KB | 2% |
+| `nexus-ai-pro/embeddings/models` | 10 KB | 2% |
+| `nexus-ai-pro/voice/openai` | 9 KB | 1% |
+| `nexus-ai-pro/ops/circuit-breaker` | 8 KB | 1% |
+| `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% |
+| `nexus-ai-pro/capabilities` | 8 KB | 1% |
+| `nexus-ai-pro/telephony/realtime-bridge` | 7 KB | 1% |
+| `nexus-ai-pro/providers/errors` | 5 KB | 0.8% |
+| `nexus-ai-pro/embeddings/mock` | 5 KB | 0.8% |
+| `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.8% |
+| `nexus-ai-pro/evals/judge` | 5 KB | 0.8% |
+| `nexus-ai-pro/operations/webhooks` | 4 KB | 0.7% |
+| `nexus-ai-pro/ops/rate-limit-adapters` | 3 KB | 0.5% |
+| `nexus-ai-pro/cache/memory-cache` | 3 KB | 0.5% |
+| `nexus-ai-pro/cache` | 2 KB | 0.3% |
+| `nexus-ai-pro/cache/adapters` | 2 KB | 0.3% |
+| `nexus-ai-pro/rag` | 2 KB | 0.3% |
+| `nexus-ai-pro/jobs` | 2 KB | 0.3% |
+| `nexus-ai-pro/jobs/durable-adapters` | 2 KB | 0.3% |
+| `nexus-ai-pro/jobs/queue` | 2 KB | 0.3% |
+| `nexus-ai-pro/streaming` | 1 KB | 0.2% |
+| `nexus-ai-pro/providers/type-guards` | 1 KB | 0.2% |
+| `nexus-ai-pro/jobs/batch` | 1 KB | 0.2% |
+<!-- size-table:end -->
+
+A capability that only works by importing the whole runtime is treated as a design problem, not an
+acceptable cost.
+
 ## Examples
 
 ```bash

package/dist/embeddings/manager.js

@@ -3,7 +3,7 @@ import { AuditLogger } from '../ops/audit-logger.js';
 import { MetricsCollector } from '../ops/metrics.js';
 import { RateLimiter } from '../ops/rate-limiter.js';
 import { NexusProviderError, createTimeoutProviderError, isAbortError } from '../providers/errors.js';
-import { assertWithinCostBudget } from '../optimizer/cost.js';
+import { assertWithinCostBudget } from '../optimizer/cost-budget.js';
 import { Tokenizer } from '../utils/tokenizer.js';
 import { generateRequestId } from '../utils/ids.js';
 import { EmbeddingCapabilityError, EmbeddingError, EmbeddingProviderError, EmbeddingProviderNotFoundError, EmbeddingProviderResponseError, EmbeddingValidationError, } from './errors.js';

package/dist/embeddings/models.js

@@ -1,4 +1,4 @@
-import { DEFAULT_CURRENCY, formatCost } from '../optimizer/cost.js';
+import { DEFAULT_CURRENCY, formatCost } from '../optimizer/cost-budget.js';
 /**
  * Default provenance for bundled embedding entries.
  *

package/dist/graph/channels.d.ts

@@ -0,0 +1,19 @@
+import type { Channel } from '../types/graph.js';
+/**
+ * The last write wins.
+ *
+ * The right default for a scalar a node computes fresh each time. Under fan-out the winner is
+ * whichever branch reduced last, so prefer an accumulating channel when several branches write the
+ * same slot and the outcome matters.
+ */
+export declare function lastValue<T>(initial?: T): Channel<T>;
+/** Concatenates every write, which is what a message history or an event log wants. */
+export declare function appendList<T>(): Channel<T[]>;
+/** Shallow-merges object writes, so two branches can each contribute their own keys. */
+export declare function mergeObject<T extends Record<string, unknown>>(): Channel<T>;
+/** Sums numeric writes, for a counter several branches increment. */
+export declare function counter(initial?: number): Channel<number>;
+/** Keeps distinct values in first-seen order. */
+export declare function appendSet<T>(): Channel<T[]>;
+/** Builds a channel from a plain reducer, for a rule none of the built-ins covers. */
+export declare function reducerChannel<T>(reduce: (current: T | undefined, update: T) => T, initial?: () => T): Channel<T>;

package/dist/graph/channels.js

@@ -0,0 +1,55 @@
+/**
+ * The last write wins.
+ *
+ * The right default for a scalar a node computes fresh each time. Under fan-out the winner is
+ * whichever branch reduced last, so prefer an accumulating channel when several branches write the
+ * same slot and the outcome matters.
+ */
+export function lastValue(initial) {
+    return {
+        reduce: (_current, update) => update,
+        ...(initial === undefined ? {} : { initial: () => initial }),
+    };
+}
+/** Concatenates every write, which is what a message history or an event log wants. */
+export function appendList() {
+    return {
+        reduce: (current, update) => [...(current ?? []), ...update],
+        initial: () => [],
+    };
+}
+/** Shallow-merges object writes, so two branches can each contribute their own keys. */
+export function mergeObject() {
+    return {
+        reduce: (current, update) => ({ ...(current ?? {}), ...update }),
+        initial: () => ({}),
+    };
+}
+/** Sums numeric writes, for a counter several branches increment. */
+export function counter(initial = 0) {
+    return {
+        reduce: (current, update) => (current ?? initial) + update,
+        initial: () => initial,
+    };
+}
+/** Keeps distinct values in first-seen order. */
+export function appendSet() {
+    return {
+        reduce: (current, update) => {
+            const seen = new Set(current ?? []);
+            const merged = [...(current ?? [])];
+            for (const value of update) {
+                if (!seen.has(value)) {
+                    seen.add(value);
+                    merged.push(value);
+                }
+            }
+            return merged;
+        },
+        initial: () => [],
+    };
+}
+/** Builds a channel from a plain reducer, for a rule none of the built-ins covers. */
+export function reducerChannel(reduce, initial) {
+    return { reduce, ...(initial ? { initial } : {}) };
+}

package/dist/graph/checkpointer.d.ts

@@ -0,0 +1,62 @@
+import type { GraphCheckpoint, GraphCheckpointer } from '../types/graph.js';
+import type { OperationRecord, OperationStore } from '../types/operations.js';
+export interface MemoryGraphCheckpointerOptions {
+    /** Checkpoints kept per thread, newest first. Defaults to 50. */
+    maxPerThread?: number;
+}
+/**
+ * In-process checkpoint history.
+ *
+ * The default, and enough for a single process that wants interrupts, resume, and time travel
+ * without a store. It does not survive a restart; `OperationStoreCheckpointer` does.
+ */
+export declare class MemoryGraphCheckpointer implements GraphCheckpointer {
+    private readonly threads;
+    private readonly maxPerThread;
+    constructor(options?: MemoryGraphCheckpointerOptions);
+    put(checkpoint: GraphCheckpoint): void;
+    get(threadId: string, step?: number): GraphCheckpoint | undefined;
+    history(threadId: string, limit?: number): GraphCheckpoint[];
+    delete(threadId: string): void;
+    /** Thread ids this checkpointer knows about. */
+    threadIds(): string[];
+}
+export interface OperationStoreCheckpointerOptions {
+    /** Checkpoints kept per thread. Defaults to 50. */
+    maxPerThread?: number;
+}
+/**
+ * Persists checkpoints through the `OperationStore` that already backs durable operations.
+ *
+ * This is what makes a graph durable without the graph module depending on the operations runtime:
+ * the store is imported as a type only, so `nexus-ai-pro/graph` stays small, and handing it a
+ * `RedisOperationStore` is all it takes to make a thread survive a restart.
+ *
+ * Each checkpoint is one record at `<threadId>#<step>`, with a head record at `<threadId>` naming
+ * the latest step. Two records per superstep, in exchange for time travel and a resume point that
+ * another process can read.
+ */
+export declare class OperationStoreCheckpointer implements GraphCheckpointer {
+    private readonly store;
+    private readonly maxPerThread;
+    constructor(store: OperationStore<GraphCheckpoint | ThreadHead>, options?: OperationStoreCheckpointerOptions);
+    put(checkpoint: GraphCheckpoint): Promise<void>;
+    get(threadId: string, step?: number): Promise<GraphCheckpoint | undefined>;
+    history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
+    delete(threadId: string): Promise<void>;
+    private readHead;
+    /**
+     * Writes one record, creating it when absent and otherwise updating in place.
+     *
+     * `update` is a compare-and-set on the record's sequence, so two workers advancing the same
+     * thread cannot both win; the loser simply re-reads on its next step.
+     */
+    private write;
+}
+interface ThreadHead {
+    kind: 'graph-thread';
+    latest: number;
+    steps: number[];
+}
+/** Re-exported for the adapter's signature, so a caller need not import the operations types. */
+export type { OperationRecord, OperationStore };

package/dist/graph/checkpointer.js

@@ -0,0 +1,136 @@
+/**
+ * In-process checkpoint history.
+ *
+ * The default, and enough for a single process that wants interrupts, resume, and time travel
+ * without a store. It does not survive a restart; `OperationStoreCheckpointer` does.
+ */
+export class MemoryGraphCheckpointer {
+    threads = new Map();
+    maxPerThread;
+    constructor(options = {}) {
+        this.maxPerThread = options.maxPerThread ?? 50;
+    }
+    put(checkpoint) {
+        const list = this.threads.get(checkpoint.threadId) ?? [];
+        // A resumed run can rewrite a step it already wrote, so replace rather than append blindly.
+        const existing = list.findIndex((item) => item.step === checkpoint.step);
+        if (existing >= 0)
+            list.splice(existing, 1);
+        list.push(clone(checkpoint));
+        list.sort((a, b) => a.step - b.step);
+        while (list.length > this.maxPerThread)
+            list.shift();
+        this.threads.set(checkpoint.threadId, list);
+    }
+    get(threadId, step) {
+        const list = this.threads.get(threadId);
+        if (!list?.length)
+            return undefined;
+        const found = step === undefined ? list[list.length - 1] : list.find((item) => item.step === step);
+        return found ? clone(found) : undefined;
+    }
+    history(threadId, limit = 20) {
+        const list = this.threads.get(threadId) ?? [];
+        return [...list].reverse().slice(0, limit).map(clone);
+    }
+    delete(threadId) {
+        this.threads.delete(threadId);
+    }
+    /** Thread ids this checkpointer knows about. */
+    threadIds() {
+        return [...this.threads.keys()];
+    }
+}
+/**
+ * Persists checkpoints through the `OperationStore` that already backs durable operations.
+ *
+ * This is what makes a graph durable without the graph module depending on the operations runtime:
+ * the store is imported as a type only, so `nexus-ai-pro/graph` stays small, and handing it a
+ * `RedisOperationStore` is all it takes to make a thread survive a restart.
+ *
+ * Each checkpoint is one record at `<threadId>#<step>`, with a head record at `<threadId>` naming
+ * the latest step. Two records per superstep, in exchange for time travel and a resume point that
+ * another process can read.
+ */
+export class OperationStoreCheckpointer {
+    store;
+    maxPerThread;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.maxPerThread = options.maxPerThread ?? 50;
+    }
+    async put(checkpoint) {
+        await this.write(stepId(checkpoint.threadId, checkpoint.step), checkpoint);
+        const head = await this.readHead(checkpoint.threadId);
+        const steps = [...new Set([...(head?.steps ?? []), checkpoint.step])].sort((a, b) => a - b);
+        while (steps.length > this.maxPerThread) {
+            const dropped = steps.shift();
+            await this.store.delete?.(stepId(checkpoint.threadId, dropped));
+        }
+        await this.write(checkpoint.threadId, { kind: 'graph-thread', latest: checkpoint.step, steps });
+    }
+    async get(threadId, step) {
+        const target = step ?? (await this.readHead(threadId))?.latest;
+        if (target === undefined)
+            return undefined;
+        const record = await this.store.read(stepId(threadId, target));
+        return record?.result && !isHead(record.result) ? record.result : undefined;
+    }
+    async history(threadId, limit = 20) {
+        const head = await this.readHead(threadId);
+        if (!head)
+            return [];
+        const wanted = [...head.steps].reverse().slice(0, limit);
+        const found = [];
+        for (const step of wanted) {
+            const checkpoint = await this.get(threadId, step);
+            if (checkpoint)
+                found.push(checkpoint);
+        }
+        return found;
+    }
+    async delete(threadId) {
+        const head = await this.readHead(threadId);
+        for (const step of head?.steps ?? [])
+            await this.store.delete?.(stepId(threadId, step));
+        await this.store.delete?.(threadId);
+    }
+    async readHead(threadId) {
+        const record = await this.store.read(threadId);
+        return record?.result && isHead(record.result) ? record.result : undefined;
+    }
+    /**
+     * Writes one record, creating it when absent and otherwise updating in place.
+     *
+     * `update` is a compare-and-set on the record's sequence, so two workers advancing the same
+     * thread cannot both win; the loser simply re-reads on its next step.
+     */
+    async write(id, value) {
+        const existing = await this.store.read(id);
+        const now = new Date().toISOString();
+        if (!existing) {
+            await this.store.create({
+                id,
+                status: 'succeeded',
+                attempt: 1,
+                maxAttempts: 1,
+                sequence: 0,
+                createdAt: now,
+                updatedAt: now,
+                kind: 'graph.checkpoint',
+                result: value,
+            });
+            return;
+        }
+        await this.store.update({ ...existing, result: value, sequence: existing.sequence + 1, updatedAt: now }, existing.sequence);
+    }
+}
+function isHead(value) {
+    return typeof value === 'object' && value !== null && value.kind === 'graph-thread';
+}
+function stepId(threadId, step) {
+    return `${threadId}#${step}`;
+}
+function clone(value) {
+    return structuredClone(value);
+}

package/dist/graph/errors.d.ts

@@ -0,0 +1,50 @@
+import type { InterruptRequest, PendingInterrupt } from '../types/graph.js';
+export declare class GraphError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+export declare class GraphValidationError extends GraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown by `context.interrupt()` to suspend the graph.
+ *
+ * Control flow, not a failure: the runtime catches it, checkpoints, and reports `awaiting_input`.
+ * It escapes to the caller only when a node interrupts on a graph compiled without a checkpointer,
+ * where there would be nothing to resume from.
+ */
+export declare class GraphInterrupt extends GraphError {
+    readonly request: InterruptRequest;
+    readonly node: string;
+    readonly step: number;
+    readonly index: number;
+    constructor(request: InterruptRequest, node: string, step: number, index: number);
+}
+/**
+ * Raised when a run exceeds its superstep budget.
+ *
+ * Cycles are a supported shape, so this is the only thing standing between a mistaken router and an
+ * infinite loop. The message names what was still pending.
+ */
+export declare class GraphStepLimitError extends GraphError {
+    readonly maxSteps: number;
+    readonly pending: readonly string[];
+    constructor(maxSteps: number, pending: readonly string[]);
+}
+export declare class GraphNodeError extends GraphError {
+    readonly node: string;
+    readonly step: number;
+    constructor(node: string, step: number, cause: unknown);
+}
+export declare class GraphThreadNotFoundError extends GraphError {
+    readonly threadId: string;
+    constructor(threadId: string);
+}
+export declare class GraphNotInterruptedError extends GraphError {
+    readonly threadId: string;
+    readonly status: string;
+    constructor(threadId: string, status: string);
+}
+/** Stable key for one interrupt, so a replayed node picks up the answer it was given. */
+export declare function interruptKey(pending: Pick<PendingInterrupt, 'node' | 'step' | 'index'>): string;