nexus-ai-pro 1.6.0 → 1.8.0

package/API_STABILITY.md

@@ -158,6 +158,95 @@ only when the client exposes `eval`; without it the compare-and-set degrades to
 that narrows but does not close the race, and that limitation is documented rather than hidden.
 Webhook delivery is best-effort and never fails the operation it describes.
 
+## Resilience API stage
+
+`CircuitBreaker`, the `RateLimitStore` contract, `MemoryRateLimitStore`, `RedisRateLimitStore`, and
+the `ops/circuit-breaker` and `ops/rate-limit-adapters` subpaths are public and follow the 1.x rules,
+together with `circuitBreaker` and `rateLimit.store` in `NexusAIConfig`.
+
+`RateLimiter.check()` keeps its synchronous signature and in-memory behavior; `checkAsync()` is the
+additive store-aware path. `NexusRateLimitError` gained an optional `resetAt` and a
+`retryAfterSeconds` accessor. `RouterContext` gained an optional `openCircuits`, and `Router.route()`
+an optional trailing parameter, both additive.
+
+Which provider a breaker excludes at a given moment is a runtime decision, not a compatibility
+guarantee: thresholds, scoring, and the exact ordering of candidates can change in a minor release.
+What is guaranteed is the state machine — closed, open after a threshold is crossed, half-open after
+the cooldown, closed again only after the configured probe successes — and that routing still selects
+a provider when every circuit is open rather than failing the request untried.
+
+Breaker state is per process by design. Two workers can disagree about a provider, and neither the
+breaker nor its snapshot promises cluster-wide consensus. Rate-limit counters are the opposite: they
+are only shared when a store is configured, and the default in-memory counter gives each worker its
+own budget.
+
+## Batch API stage
+
+`BatchManager`, the `BatchProvider` contract, the OpenAI and Anthropic adapters, the deterministic
+mock, and the `nexus-ai-pro/batch`, `batch/openai`, `batch/anthropic`, and `batch/mock` subpaths are
+public and follow the 1.x rules, as are the normalized request, ref, state, and result shapes.
+
+`BatchJobRef` is guaranteed to stay JSON-serializable and sufficient on its own to poll, collect, or
+cancel a batch. That is what makes a persisted ref survive a restart, and narrowing it would break
+every stored ref, so it requires a major release.
+
+Two behaviors are guaranteed. Results are matched by `customId`, never by position, and a duplicate
+`customId` is refused before submission. And a failed batch returns no items rather than fabricated
+ones.
+
+Provider vocabulary is not normalized beyond `BatchJobStatus`. Anthropic reports only `in_progress`
+and `ended`, with the real outcome on the per-item results; that adapter maps `ended` to `completed`
+and lets item errors carry the detail rather than inventing a batch-level failure. Payloads under
+`raw`, provider quotas, completion windows, and the discount rate itself are provider-controlled and
+may change without a major release.
+
+## Asset store stage
+
+`FilesystemAssetStore`, `S3AssetStore`, the `S3LikeClient` contract, and the
+`nexus-ai-pro/images/stores` subpath are public under the 1.x rules and implement the existing
+`AssetStore` contract unchanged. The shared contract, errors, and validation moved to an internal
+`asset-support` module and are re-exported from `images/assets`, so every existing import resolves
+as before.
+
+All three stores guarantee that a missing asset and one owned by another tenant are
+indistinguishable, that stored bytes carry a SHA-256 checksum, and that a lapsed asset is unreadable
+before it is purged. `S3AssetStore.purgeExpired()` lists the record prefix on every call; on a large
+bucket prefer the provider lifecycle rules. Neither durable store coordinates concurrent deletes
+across processes.
+
+## Model registry generation stage
+
+`data/models/*.json` is the versioned source of truth in the repository, and
+`scripts/generate-model-registry.mjs` emits `src/models/generated.ts` from it.
+
+Neither is published, and neither is public API. They duplicate `KNOWN_MODELS` exactly, so shipping
+them would add roughly 310KB to every install for data nothing reads. Generation is a build-time
+guarantee about how the registry is maintained, not a runtime surface: the resolver continues to read
+`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,115 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [Unreleased]
+
+## [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. This closes the five capability rows where LangGraph led, 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, closing the five capability rows where LangGraph led:
+  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
+outlives a process*. The half-price asynchronous tier is reachable, one rate-limit budget covers
+every worker, a failing provider leaves routing until it recovers, generated media persists
+outside the process, and every operation family reports into the same metrics and audit log.
+
+### Added
+
+- **Circuit breaking.** `CircuitBreaker` consumes the same attempt signals as `ProviderHealthMonitor`
+  and trips routing away from a failing provider entirely, rather than merely ranking it lower. Two
+  independent triggers: consecutive failures, and a failure rate over a rolling window that catches a
+  provider failing half its calls without ever failing several in a row. After a cooldown the circuit
+  admits a limited number of probes; a success closes it, a failure reopens it and restarts the
+  cooldown. Exposed through `circuitBreaker` config, `ai.getCircuitBreakerStatus()`,
+  `ai.resetCircuitBreaker()`, and the `nexus-ai-pro/ops/circuit-breaker` subpath.
+- **Distributed rate limiting.** A `RateLimitStore` contract with `MemoryRateLimitStore` and
+  `RedisRateLimitStore`, set through `rateLimit.store`, so one budget covers every worker instead of
+  each process getting the full limit. The Redis store does the increment and the expiry in one
+  atomic Lua call when the client exposes `eval`, and re-arms a missing TTL on the fallback path so a
+  crash between `INCR` and `PEXPIRE` cannot block a key forever. Completions and embeddings share the
+  limiter, so they share the budget.
+- `NexusRateLimitError` now carries `resetAt` and a `retryAfterSeconds` accessor, so a gateway can
+  answer with a real `Retry-After` header.
+- New subpaths `nexus-ai-pro/ops/circuit-breaker` and `nexus-ai-pro/ops/rate-limit-adapters`.
+- **Provider batch tiers.** `BatchManager` puts OpenAI Batch and Anthropic Message Batches behind one
+  operation handle, reaching the roughly half-price asynchronous tier that local `runBatch()`
+  concurrency cannot. Results are matched by a required `customId` rather than by position, since a
+  batch provider does not guarantee output order; a duplicate id is refused before submission.
+  Polling backs off up to a configurable ceiling, an idempotency key replays instead of submitting
+  twice, and `resume()` collects a batch from its `BatchJobRef` alone so a restarted worker can
+  finish what another submitted. Ships with a deterministic `MockBatchProvider`.
+- **Filesystem and S3 asset stores.** `FilesystemAssetStore` and `S3AssetStore` implement the
+  existing `AssetStore` contract, with tenant isolation, retention, SHA-256 checksums, and signing.
+  A missing asset and one owned by another tenant are indistinguishable, because a distinguishable
+  error leaks the existence of another tenant asset. Both write bytes and a JSON sidecar per asset
+  rather than a shared index, so concurrent writers do not contend and a torn write loses at most
+  one record. `S3LikeClient` is structural, so S3, R2, and MinIO all work without an SDK dependency.
+- **Generated model registry.** `data/models/*.json` is now the versioned source of truth, and
+  `scripts/generate-model-registry.mjs` emits `src/models/generated.ts` from it. The generator
+  validates required fields, price signs, context bounds, status values, and dangling aliases;
+  `npm run registry:check` runs inside `npm run check` so committed data and output cannot drift.
+  The runtime still reads `KNOWN_MODELS`, and a test asserts the two match exactly. The generated
+  module and its data are build-time artifacts and are not published: they duplicate `KNOWN_MODELS`
+  exactly, so shipping them would add roughly 310KB to every install for data nothing reads.
+- New subpaths `nexus-ai-pro/batch`, `batch/openai`, `batch/anthropic`, `batch/mock`, and
+  `nexus-ai-pro/images/stores`.
+- **Cross-family observability.** Image, voice, and telephony operations now report into the same
+  metrics collector, audit log, and rate limiter as completions and embeddings, closing the gap where
+  an application running phone agents and image generation had observability for only part of its
+  spend. Metrics carry `family` and `operation` labels, and one rate-limit budget now covers every
+  family. `FamilyTelemetry` is exported for a family an application adds itself.
+
+### Changed
+
+- `RateLimiter` gained `checkAsync()` for the store-aware path. `check()` keeps its synchronous
+  signature and behavior, and the runtime only awaits when a store is configured, so a request
+  without one pays no extra microtask.
+- `ImageManager`, `VoiceManager`, and `TelephonyManager` accept an optional second constructor
+  argument carrying the shared observability objects. It defaults to empty, so constructing one
+  standalone is unchanged and simply records nothing.
+- The shared asset contract, errors, and validation moved from `images/assets` to an internal
+  `asset-support` module so the filesystem, S3, and memory stores cannot drift on what a valid asset
+  is. `images/assets` re-exports all of it, so existing imports are unchanged.
+- Documentation consolidated from nine files to seven. `NEXUS.md` and `EXPLANATION.md` were four
+  releases stale and largely restated the README; their unique content moved to `CONTRIBUTING.md`
+  (real-provider test setup, the public-feature checklist, the manual smoke checklist) and to a new
+  README "Known Limitations" section. The published package now carries only `README.md`,
+  `API_STABILITY.md`, `CHANGELOG.md`, `SECURITY.md`, and `LICENSE`; `ROADMAP.md` is a design proposal
+  and stays on GitHub.
+- `SECURITY.md` no longer names a specific supported version line. It claimed `0.9.x` while 1.6.0 was
+  the published release, so the wording is now version-independent and cannot go stale again.
+- `RouterContext` gained an optional `openCircuits`, and `Router.route()` an optional trailing
+  parameter. When every candidate's circuit is open the router routes anyway: that usually means a
+  shared dependency is down, and one attempt beats a certain failure with no attempt at all.
+
 ## [1.6.0] - 2026-09-03
 
 Durable operations, the first half of the theme *work that outlives a process*. Long-running work now
@@ -321,7 +430,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.6.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...HEAD
+[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
 [1.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.3.0...v1.4.0

package/README.md

@@ -6,8 +6,8 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
-- Full technical notes and manual test cases: [NEXUS.md](./NEXUS.md)
-- Image generation status and remaining infrastructure work: [ROADMAP.md](./ROADMAP.md)
+- Contributing, testing, and release procedure: [CONTRIBUTING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CONTRIBUTING.md)
+- Delivered work and what is planned next: [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md)
 
 ## Install
 
@@ -85,6 +85,10 @@ 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
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
 - keep TypeScript types around every request and response
 
@@ -418,6 +422,284 @@ 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
+completion window measured in hours. Local `runBatch()` concurrency cannot reach it — it is a
+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';
+
+const batch = new BatchManager({
+  providers: { openai: new OpenAIBatchProvider({ apiKey: process.env.OPENAI_API_KEY! }) },
+  defaultProvider: 'openai',
+});
+
+const handle = await batch.submit({
+  model: 'gpt-5.4-mini',
+  idempotencyKey: `nightly-${date}`,
+  items: documents.map((document) => ({
+    customId: document.id,
+    request: { model: 'gpt-5.4-mini', messages: [{ role: 'user', content: document.text }] },
+  })),
+});
+
+console.log(handle.id);        // persist this, do not block a request on the result
+```
+
+`customId` is required, not optional. A batch provider does not guarantee output order, and matching
+results by position is exactly the bug that silently mislabels every row. Duplicates are refused
+before submission for the same reason.
+
+The handle settles when the provider finishes, which can be hours later, so treat it as a background
+operation:
+
+```ts
+const result = await handle.result();
+
+result.status;              // completed | failed | expired | cancelled
+result.counts;              // { total, completed, failed }
+result.items;               // one entry per customId, with response or error
+result.cost.amount;         // priced per item, then discounted at the provider's batch rate
+```
+
+A mixed batch is normal: individual items carry their own `error` while the batch still reports
+`completed`. Nothing is invented for a failed batch — `items` comes back empty rather than padded.
+
+**Surviving a restart.** Everything after `submit` takes only a `BatchJobRef`, which is
+JSON-serializable. A worker that never submitted the batch can collect it:
+
+```ts
+const ref = { id: savedBatchId, provider: 'openai' };
+
+await batch.status(ref);     // provider-side state, without waiting
+const result = await batch.resume(ref);
+await batch.cancel(ref);
+```
+
+Polling backs off from the configured interval up to `maxPollIntervalMs`, so a 24-hour batch does
+not generate 2,880 polls while a fast one is still caught by the first few short intervals.
+
+## Asset Stores
+
+`AssetStore` has three implementations. They share one contract, so retention, tenant isolation, and
+checksums behave identically:
+
+```ts
+import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
+import { FilesystemAssetStore, S3AssetStore } from 'nexus-ai-pro/images/stores';
+
+const store = new FilesystemAssetStore({ directory: '/var/lib/app/assets', defaultTtlSeconds: 86_400 });
+
+const s3 = new S3AssetStore({
+  client,                    // structural: S3, R2, MinIO, or a test double
+  bucket: 'generated-media',
+  prefix: 'nexus-assets/',
+});
+```
+
+A missing asset and one owned by another tenant are **indistinguishable** — both return `undefined`
+rather than a permission error, because a distinguishable error leaks the existence of another
+tenant's asset.
+
+Both durable stores write two objects per asset: the bytes, and a JSON sidecar holding the
+descriptor, tenant, and expiry. A single shared index would be a write-contention point and a
+corruption blast radius; per-asset sidecars let concurrent writers proceed and lose at most one
+record. `purgeExpired()` is exact but costs a directory listing, so on a large S3 bucket prefer the
+provider's own lifecycle rules and keep this as the fallback.
+
+## Model Registry Generation
+
+The registry is generated from versioned provider data in `data/models/`, not hand-edited. The
+Claude 5 reasoning bug fixed in 1.4.0 was exactly the kind of error a hand-written literal of 100+
+models invites.
+
+```bash
+npm run registry:generate   # data/models/*.json -> src/models/generated.ts
+npm run registry:check      # fails if the committed output is stale
+```
+
+`registry:check` runs as part of `npm run check`, so committed data and committed output cannot
+drift apart. The generator validates required fields, price signs, context bounds, status values,
+and that every alias points at a model that exists — a dangling alias otherwise fails only when a
+request happens to use it.
+
+The runtime still reads the hand-written `KNOWN_MODELS`; a test asserts the generated registry
+matches it exactly. Swapping the runtime over is deliberately a separate change, so introducing the
+generator cannot quietly alter pricing data in the same release.
+
+`src/models/generated.ts` and `data/` are build-time artifacts and are **not** published. They
+duplicate `KNOWN_MODELS` exactly, and shipping them in both builds would add roughly 310KB to every
+install for data nothing reads. Both live in the repository, where a diff is what you actually want.
+
+## Resilience: Circuit Breaking and Distributed Limits
+
+Health monitoring ranks a struggling provider lower. A circuit breaker is the stronger step: while a
+circuit is open the provider is removed from routing entirely, so a hard-down provider stops
+absorbing one failed attempt per request.
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! }, anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } },
+  health: { enabled: true },
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 5,        // consecutive failures that open the circuit
+    failureRateThreshold: 0.5,  // or half the calls failing in the window
+    minimumThroughput: 10,
+    resetTimeoutMs: 30_000,     // cooldown before a probe
+    halfOpenMaxCalls: 1,
+    onStateChange: (event) => logger.warn('circuit', event),
+  },
+});
+
+ai.getCircuitBreakerStatus();   // state, failure rate, retryAt per provider
+ai.resetCircuitBreaker('openai');
+```
+
+Two independent triggers, because they catch different failures. A consecutive count catches a
+provider that is hard down. A failure *rate* catches one that fails half its calls without ever
+failing several in a row — invisible to a consecutive counter. The rate is only considered once
+`minimumThroughput` calls have been seen, since one failure out of two is not evidence of anything.
+
+After the cooldown the circuit goes half-open and admits a limited number of probes. A successful
+probe closes it; a failed probe reopens it and restarts the cooldown. If *every* circuit is open the
+router routes anyway — that usually means a shared dependency is down, and one attempt beats a
+certain failure with no attempt at all.
+
+`isFailure` keeps errors that are not the provider's fault out of the calculation:
+
+```ts
+circuitBreaker: {
+  enabled: true,
+  isFailure: (error) => !(error instanceof Error && error.name === 'AbortError'),
+}
+```
+
+**Distributed rate limiting.** The built-in limiter is process-local, which multiplies the real
+limit by the number of workers. Pointing it at a shared store fixes that, and the same budget then
+covers completions and embeddings alike:
+
+```ts
+import { RedisRateLimitStore } from 'nexus-ai-pro/ops/rate-limit-adapters';
+
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  rateLimit: {
+    enabled: true,
+    maxRequests: 100,
+    windowMs: 60_000,
+    key: 'userId',
+    store: new RedisRateLimitStore(redis),
+  },
+});
+```
+
+Prefer a client exposing `eval`: the increment and the expiry then happen in one atomic round trip.
+Without it the store falls back to `INCR` plus `PEXPIRE` and re-arms any missing TTL it sees, so a
+crash between the two calls cannot block a key forever.
+
+`NexusRateLimitError` carries `resetAt` and `retryAfterSeconds`, so a gateway can answer with a
+real `Retry-After` header:
+
+```ts
+catch (error) {
+  if (error instanceof NexusRateLimitError) {
+    response.setHeader('Retry-After', String(error.retryAfterSeconds ?? 60));
+  }
+}
+```
+
+Omitting `store` keeps the original synchronous in-memory path, which costs no extra microtask per
+request.
+
 ## Durable Operations
 
 Long-running work — an image render, a batch, anything asynchronous — runs through one lifecycle:
@@ -427,6 +709,11 @@ covering the rest. `OperationRunner` owns it end to end, so a crashed worker doe
 The default store is in-process, so the small case needs no infrastructure:
 
 ```ts
+import { BatchManager } from 'nexus-ai-pro/batch';
+import { OpenAIBatchProvider } from 'nexus-ai-pro/batch/openai';
+import { FilesystemAssetStore, S3AssetStore } from 'nexus-ai-pro/images/stores';
+import { CircuitBreaker } from 'nexus-ai-pro/ops/circuit-breaker';
+import { RedisRateLimitStore } from 'nexus-ai-pro/ops/rate-limit-adapters';
 import { OperationRunner } from 'nexus-ai-pro/operations';
 
 const runner = new OperationRunner<string>({ retry: { maxAttempts: 3, baseDelayMs: 500 } });
@@ -1385,12 +1672,33 @@ npm run test:conformance:real
 
 ## Roadmap
 
+See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what has
+shipped and what is planned. It is a design proposal, not a compatibility promise; the guarantees
+live in [API_STABILITY.md](./API_STABILITY.md).
+
 1.4.0 closed the completion-request gap: prompt caching, reasoning controls, tool and sampling
 controls, structured usage with numeric cost, and capability negotiation with registry provenance.
 
 Next is durable execution — an operation state machine, provider batch APIs, distributed rate
 limiting and circuit breaking, first-class embeddings, and filesystem/S3 asset stores — followed by
-image portability and promotion out of experimental. See [ROADMAP.md](./ROADMAP.md).
+image portability and promotion out of experimental. See
+[ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md).
+
+## Known Limitations
+
+- Voice, telephony, images, local models, and custom providers are optional layers; enable only what
+  you use.
+- Audio and video preprocessing is limited, and provider modality support differs.
+- Bundled model metadata is a routing and estimation convenience, not a pricing contract.
+- Process-memory cache, queues, and asset storage are not enough for a distributed deployment; use
+  the Redis, BullMQ, filesystem, or S3 adapters instead.
+- Default hash embeddings suit tests and demos, not strong semantic search. Register a real
+  embedding provider for production retrieval.
+- NLI verification is an interface; bring a specialized verifier for high-confidence entailment.
+- Guardrails reduce risk but do not replace application authorization, provider-side moderation, or
+  human review of high-impact actions.
+- Circuit-breaker state is per process, and realtime sessions are not yet routed through the metrics,
+  audit, and rate-limit path that every other family uses.
 
 ## Production Notes
 

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published minor release. Users should upgrade to the newest `0.9.x` patch as fixes become available.
+Security fixes are provided for the latest published minor release. Upgrade to the newest patch of that line as fixes become available; older minor releases do not receive backports.
 
 ## Reporting a vulnerability
 

package/dist/batch/anthropic.d.ts

@@ -0,0 +1,26 @@
+import type { BatchJobRef, BatchJobState, BatchOutputItem, BatchProvider, BatchProviderCallContext, BatchProviderInfo, BatchSubmitRequest } from '../types/batch.js';
+export interface AnthropicBatchProviderOptions {
+    apiKey: string;
+    baseUrl?: string;
+    version?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    /** Applied to any item that names no model. */
+    defaultModel?: string;
+    maxTokens?: number;
+}
+/** Anthropic Message Batches: half price, 24-hour window. */
+export declare class AnthropicBatchProvider implements BatchProvider {
+    private readonly options;
+    readonly info: BatchProviderInfo;
+    constructor(options: AnthropicBatchProviderOptions);
+    submit(request: BatchSubmitRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
+    poll(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    results(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchOutputItem[]>;
+    cancel(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    private toState;
+    private toOutputItem;
+    private request;
+    private requestText;
+    private send;
+}