nexus-ai-pro 1.5.0 → 1.7.0

package/API_STABILITY.md

@@ -131,6 +131,100 @@ and are overridable through `embeddings.models.registry`. Which concrete model a
 not interchangeable, so pin a concrete model whenever a stored index must stay valid across
 upgrades. Provider payloads under `raw` and reported token counts are controlled by the provider.
 
+## Operations API stage
+
+The `nexus-ai-pro/operations` family is public and follows the 1.x rules, including the
+`operations/adapters` and `operations/webhooks` subpaths. This covers `OperationRunner`,
+`LocalOperationHandle`, `MemoryOperationStore`, the `OperationStore` and `OperationDispatcher`
+contracts, the Redis and BullMQ adapters, the webhook signing and verification helpers, the state
+machine predicates, and the normalized record, event, and error shapes.
+
+The lifecycle types moved out of `types/images.ts` and are re-exported from it, so existing image
+imports of `OperationStatus`, `OperationEvent`, `OperationHandle`, `OperationEventBase`, and
+`OperationErrorDescriptor` resolve unchanged. `OperationStatus` gained `retrying`, and
+`OperationEvent` gained `progress` and `retrying` variants and an `attempt` field on `running` —
+additive changes this policy permits in a minor release. Code that switches exhaustively on either
+union should add the new members.
+
+Three behaviors are guaranteed. Terminal statuses are final, so a late provider callback cannot
+resurrect a settled operation. Store writes are compare-and-set on `sequence`, so a losing writer
+is told it lost rather than silently overwriting. And a record carrying raw bytes is refused with
+`OperationSerializationError` rather than persisted, because a base64 round trip through a queue
+payload is a failure mode that otherwise appears only as a truncated job.
+
+Durability is a property of the configured store, not of the runner. `MemoryOperationStore` does
+not survive a restart and does not promise cross-process recovery. `RedisOperationStore` is atomic
+only when the client exposes `eval`; without it the compare-and-set degrades to a read-compare-write
+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.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,137 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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
+runs through one lifecycle that survives a worker crash. Everything here is additive.
+
+The rest of the theme — provider batch APIs, distributed rate limiting and circuit breaking,
+filesystem and S3 asset stores, a generated model registry, and cross-family observability — moves to
+1.7.0. The operation handle they all sit behind ships here, which is what unblocks them.
+
+### Added
+
+- **`OperationRunner` and a shared operation lifecycle.** `queued → running → succeeded | failed`,
+  with `retrying`, `cancelling`, `cancelled`, and `expired` covering the rest, exposed through the
+  new `nexus-ai-pro/operations` subpath. The runner persists a record before doing any work, claims
+  a lease, heartbeats while the executor runs, retries with backoff and jitter, dead-letters what
+  never succeeds, and emits signed webhooks.
+- **Restart survival through leases rather than locks.** A worker that dies leaves a record whose
+  lease lapses; another worker's `recover()` sweep resumes it. Every store write is a compare-and-set
+  on the record's `sequence`, so two workers racing on one operation cannot both win, and the loser
+  is told it lost instead of silently overwriting.
+- **`RedisOperationStore` and `BullMQOperationDispatcher`.** Redis persists records, with the
+  compare-and-set done in one Lua call when the client exposes `eval`. BullMQ dispatch queues the
+  operation id and its routing metadata only, never a payload.
+- **Idempotency keys.** A key matching an existing record replays that operation instead of starting
+  a second one, so an ambiguous timeout cannot produce a duplicate charge.
+- **Progress and cancellation.** An executor reports progress through `context.report()`, which
+  reaches both `handle.events()` and the persisted record. `runner.cancel()` settles an operation
+  owned by another worker, observed there through its heartbeat.
+- **Signed webhooks, with the verifying half included.** Deliveries are HMAC-SHA256 over
+  `${timestamp}.${body}`, so a captured delivery cannot be replayed indefinitely.
+  `verifyOperationWebhook()` ships alongside `signOperationWebhook()` rather than leaving every
+  receiver to hand-roll a constant-time comparison. A failed delivery is reported and never fails
+  the operation it describes.
+- **A binary-payload guard.** Persisting a result carrying a `Uint8Array`, `Buffer`, `Blob`, or
+  stream throws `OperationSerializationError` naming the exact path and pointing at `AssetStore`.
+  Base64 in a job payload inflates it by a third and most queue backends cap job size well below one
+  image, so this fails loudly at the boundary instead of appearing later as a truncated job.
+- New subpaths `nexus-ai-pro/operations`, `operations/adapters`, and `operations/webhooks`.
+
+### Changed
+
+- The operation lifecycle types moved from `types/images.ts` to a family-neutral `types/operations.ts`
+  and are re-exported from their old home, so existing image imports resolve unchanged. The image
+  family's private handle was replaced by the shared `LocalOperationHandle`, which is told to reject
+  with `ImageOperationCancelledError` so callers catching that error see no difference.
+- `OperationStatus` gained `retrying`; `OperationEvent` gained `progress` and `retrying` variants and
+  an `attempt` field on `running`. Additive, but code switching exhaustively on either union should
+  add the new members.
+
+### Fixed
+
+- A handle driven by the runner stayed in `queued` for the whole run, so no `running` event was
+  emitted and every `context.report()` call was silently dropped. Found while testing the runner's
+  event sequence; the handle now exposes `markRunning()` and the runner calls it before each attempt.
+
 ## [1.5.0] - 2026-08-31
 
 Embeddings become a first-class operation. `ai.embed()` gets the routing, caching, batching, budget,
@@ -266,7 +397,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.5.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...HEAD
+[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
 [1.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.1...v1.3.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
 
@@ -84,6 +84,10 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - cache exact or semantically similar prompts
 - 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
+- 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
 
@@ -417,6 +421,294 @@ const response = await ai.completeVerified(
 );
 ```
 
+## 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 { 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:
+`queued → running → succeeded | failed`, with `retrying`, `cancelling`, `cancelled`, and `expired`
+covering the rest. `OperationRunner` owns it end to end, so a crashed worker does not lose work.
+
+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 } });
+
+const handle = await runner.submit(async (context) => {
+  context.report({ completed: 1, total: 3 });
+  return doTheWork(context.signal);
+});
+
+for await (const event of handle.events()) {
+  console.log(event.type, event.sequence);
+}
+
+const value = await handle.result();
+```
+
+Swapping the store makes the same code survive a restart. Nothing else changes:
+
+```ts
+import { OperationRunner } from 'nexus-ai-pro/operations';
+import { BullMQOperationDispatcher, RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+
+const runner = new OperationRunner({
+  store: new RedisOperationStore(redis),
+  dispatcher: new BullMQOperationDispatcher(queue),
+  owner: process.env.HOSTNAME,
+  leaseMs: 30_000,
+  webhook: { url: 'https://app.example/hooks/operations', secret: process.env.HOOK_SECRET! },
+});
+```
+
+**How restart survival actually works.** A worker claims a lease before running and heartbeats
+while it works. If the process dies, the lease simply lapses; another worker's `recover()` sweep
+finds the record and resumes it. There is no distributed lock — every store write is a
+compare-and-set on the record's `sequence`, so two workers racing on the same operation cannot both
+win.
+
+```ts
+// On startup, in each worker.
+const resumed = await runner.recover(executor);
+```
+
+Recovery is deliberately conservative: a record past its `expiresAt` is **expired** rather than
+re-run, and one that has used every attempt is **dead-lettered** and parked for inspection, so a
+permanently failing operation cannot be recovered forever.
+
+**Idempotency.** An `idempotencyKey` that matches an existing record replays that operation instead
+of starting a second one, which is what stops an ambiguous timeout from double-charging:
+
+```ts
+const handle = await runner.submit(chargeAndRender, { idempotencyKey: `render:${orderId}` });
+```
+
+**Webhooks** are signed with HMAC-SHA256 over `${timestamp}.${body}`, so a captured delivery cannot
+be replayed indefinitely. The verifying half ships too — a receiver should never have to hand-roll a
+constant-time comparison:
+
+```ts
+import { OPERATION_WEBHOOK_SIGNATURE_HEADER, verifyOperationWebhook } from 'nexus-ai-pro/operations/webhooks';
+
+app.post('/hooks/operations', (request, response) => {
+  const ok = verifyOperationWebhook(
+    request.rawBody,
+    request.header(OPERATION_WEBHOOK_SIGNATURE_HEADER),
+    process.env.HOOK_SECRET!,
+  );
+  response.sendStatus(ok ? 204 : 400);
+});
+```
+
+A failed delivery is reported through `onWebhookError` and never turns a completed operation into a
+failed one.
+
+**Binary payloads are refused, not truncated.** Persisting a result that carries a `Uint8Array`,
+`Buffer`, or `Blob` throws `OperationSerializationError` naming the exact path. Base64 in a job
+payload inflates it by a third and most queue backends cap job size well below one image, so the
+bytes belong in an `AssetStore` with only a reference on the record. The BullMQ dispatcher likewise
+queues the operation id and nothing else.
+
+The image family already runs on this lifecycle, so `ai.images.submit()` reports the same events.
+
 ## Embeddings
 
 `ai.embed()` is a first-class operation, not a helper: it gets the same routing, caching, batching,
@@ -1226,6 +1518,9 @@ import { negotiateCompletionRequest } from 'nexus-ai-pro/capabilities';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
+import { OperationRunner } from 'nexus-ai-pro/operations';
+import { RedisOperationStore } from 'nexus-ai-pro/operations/adapters';
+import { verifyOperationWebhook } from 'nexus-ai-pro/operations/webhooks';
 import { EmbeddingManager } from 'nexus-ai-pro/embeddings';
 import { OpenAIEmbeddingProvider } from 'nexus-ai-pro/embeddings/adapters';
 import { MockEmbeddingProvider } from 'nexus-ai-pro/embeddings/mock';
@@ -1291,12 +1586,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;
+}