nexus-ai-pro 1.15.0 → 1.16.0

package/API_STABILITY.md

@@ -210,10 +210,14 @@ What is guaranteed is the state machine — closed, open after a threshold is cr
 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.
+Breaker state is per process unless `circuitBreaker.store` is set (since 1.16.0). With a store,
+workers converge on each other's decisions within about `syncIntervalMs`, and one worker at a time
+holds the probe; this is eventual agreement, not consensus, and two workers may briefly disagree.
+Failure counting stays per worker either way. The `CircuitStateStore` contract and the memory, Redis,
+and Postgres adapters follow the 1.x rules. Since 1.16.0 a caller's cancellation does not count as a
+failure unless `isFailure` says so, and probe limits apply to every attempt the failover executor
+makes. Rate-limit counters are only shared when a store is configured, and the default in-memory
+counter gives each worker its own budget.
 
 ## Batch API stage
 
@@ -328,6 +332,19 @@ Also since 1.12.0, all additive:
 - A subgraph node's thread id is `<parent thread>:<task id>`, which equals the previous
   `<parent thread>:<node>` for any node not reached through `Send`.
 
+Also since 1.16.0, all additive:
+
+- `createGraph({ channels, input, output })`. `StateGraph`, `CompiledGraph`, and `GraphResult` gained
+  defaulted type parameters for the input and output channels, so existing annotations such as
+  `CompiledGraph<S>` keep their meaning. A write to an undeclared input rejects with
+  `GraphValidationError`. Checkpoints and stream events still carry every channel.
+- `NodeOptions.cache` and `CompileOptions.cache`. Guaranteed: a failure, an interrupt, a node that
+  consumed an interrupt's answer, and a `Command.PARENT` result are never served from the cache, and a
+  cache that throws is treated as a miss. Not guaranteed: the default key's exact text, so entries
+  written by one minor release may miss after an upgrade.
+- `task_end` events may carry `cached: true`; `GraphDescription` may carry `input`, `output`, and a
+  node's `cache` flag.
+
 ## Agent, store, MCP, and tracing stages (1.14.0)
 
 The `nexus-ai-pro/agent`, `nexus-ai-pro/store`, `nexus-ai-pro/store/redis`, and `nexus-ai-pro/mcp`
@@ -368,9 +385,32 @@ are normalized; new optional fields and new bundled evaluators may be added in a
   same inputs give the same verdict; the exact interval bounds may change if the method improves, and
   a verdict is a judgement about evidence rather than a compatibility guarantee.
 - `evaluate()` reports a target's failure as a failed example and an evaluator's failure as a failed
-  measurement; neither throws.
-- The existing `EvalRunner` and `MediaEvalRunner` keep their APIs unchanged. Rebuilding them on this
-  entry point is a later, internal change.
+  measurement; neither throws. Since 1.16.0 an aborted evaluation rejects with the abort reason and
+  stores nothing.
+- `EvalRunner` and `MediaEvalRunner` keep their APIs. Since 1.16.0 both run on `evaluate()` and carry
+  the resulting experiment in an optional `experiment` field; their reports are otherwise unchanged.
+- Since 1.16.0, additive: `underCost()`, `FileExperimentStore`, `readExperiment()`, the `cost`
+  option, per-example `repetitions`, and `signal` on the target's context.
+
+## Postgres, command-line, and record-and-replay stages (1.16.0)
+
+The `nexus-ai-pro/postgres` subpaths, `nexus-ai-pro/ops/circuit-store`, and
+`nexus-ai-pro/testing/record` are public and follow the 1.x rules. None is exported from the root.
+
+- Each Postgres adapter implements the same contract as the corresponding in-memory store, and is
+  tested against it. Ordering among rows that tie on a timestamp is not a guarantee.
+- `PostgresLikeClient` is the whole driver contract: `query(text, values)` resolving to `{ rows }`.
+- The schema is guaranteed additive for the 1.x line: a minor release may add a column or an index,
+  never drop or rename one, and `migrate()` stays idempotent. A change that needs a data migration
+  waits for 2.0.
+- Unique idempotency keys in `PostgresOperationStore` are a guarantee, and `OperationDuplicateError`
+  is the signal the runner relies on.
+- The `nexus` commands and flags listed by `nexus help` are public. Human-readable output is not a
+  guarantee and may improve in any release; `--json` output follows the 1.x rules; exit codes are
+  guaranteed — 0 for success, 1 for a failed check, 2 for a usage error.
+- The fixture file format and the default match key of `testing/record` are stable for the 1.x line,
+  so recordings made with one release keep replaying with the next. A change that would invalidate
+  recordings waits for 2.0.
 
 ## Deprecation process
 

package/CHANGELOG.md

@@ -4,6 +4,101 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-09-22
+
+Shared state and the command line. Everything that has to outlive a process or be shared between
+workers now has a Postgres adapter, circuit decisions are shared across a fleet, the evaluation
+platform has a CI gate, and suites that needed credentials can run from recorded provider traffic.
+
+### Added
+
+- **A Postgres adapter family** (`nexus-ai-pro/postgres`, with one subpath per adapter):
+  `PostgresOperationStore`, `PostgresStore` (long-term memory, ranked by pgvector when
+  `vectorDimensions` is set), `PostgresTraceStore`, `PostgresDatasetStore`, `PostgresExperimentStore`,
+  and `PostgresCircuitStateStore`.
+  - Each takes any client with `query(text, values)` — `pg`, `@neondatabase/serverless`, PGlite — and
+    `fromPostgresJs()` adapts `postgres.js`. No driver becomes a dependency.
+  - Nothing creates a schema at import: `migrate()`, `postgresMigration()`, and `nexus db sql` apply
+    or print it.
+  - Idempotency keys are unique in the operations table, so two workers racing to submit one key run
+    the work once. Graph threads persist across workers through `OperationStoreCheckpointer`.
+- **Shared circuit state.** `circuitBreaker.store` takes a `CircuitStateStore`: memory and Redis
+  adapters in `nexus-ai-pro/ops/circuit-store`, Postgres in `/postgres/circuits`. A provider that
+  fails in one worker is taken out of routing in all of them, and one worker at a time probes it when
+  the cooldown ends. Checks stay synchronous; the coordination code loads only when a store is
+  configured. `ai.syncCircuitBreaker()` loads shared state at startup.
+- **Evaluation from the command line.** `nexus eval run`, `nexus eval compare`, and `nexus eval gate`
+  run an evaluation module to an experiment file and fail a build only on a regression beyond noise,
+  a new failure, or a dataset mismatch. `nexus traces list`, `show`, and `export` read a JSONL file or
+  any trace store a module exports. `nexus db sql` prints the Postgres schema. Every command takes
+  `--json`, and a usage error exits with 2.
+- **Record and replay** (`nexus-ai-pro/testing/record`). `recordingFetch()` writes provider traffic
+  to reviewable fixture files with credentials removed; `replayFetch()` serves it back with no network
+  and throws `FixtureMissingError` for anything unrecorded; `fixtureFetch()` picks the mode from
+  `NEXUS_FIXTURES`; `installFetch()` covers code that calls the global `fetch`. Multipart boundaries
+  and key order do not break matching.
+- **Image conformance from recordings.** `npm run conformance:images:record` records the image suite
+  against every backend with credentials present; `npm run test:conformance:images` replays it in CI
+  and reports any backend without recordings rather than counting it as a pass.
+- **Graph input and output channels.** `createGraph({ channels, input, output })` restricts what a
+  caller may pass in and what comes back, in the types and at run time. As a subgraph, a graph
+  receives only its inputs and merges back only its outputs.
+- **Per-node caching.** `addNode(name, fn, { cache: { key, ttlMs, store } })` reuses a node's result
+  for the same state and input, in a bounded in-process map or any cache adapter
+  (`compile({ cache })` sets a default). Failures, interrupts, human answers, and parent commands are
+  never cached; a failing cache is a miss.
+- **Evaluation additions.** `underCost()` per-example cost gate; `FileExperimentStore` and
+  `readExperiment()`; `repetitions` may be a function per example; the target receives the abort
+  signal.
+- `EvalRunner.run()` and `MediaEvalRunner.evaluate()` return the experiment underneath their report,
+  and accept options to name and store it.
+- `OperationDuplicateError`, raised by stores that enforce unique idempotency keys.
+- **Documentation coverage.** Every public export, and every public member of an exported class,
+  interface, or enum, now has a doc comment: 4,651 declarations across 88 entry points.
+  `npm run docs:check` enforces it and runs as part of `npm test`.
+
+### Changed
+
+- `EvalRunner` and `MediaEvalRunner` now run on `evaluate()`. Their results and errors are unchanged;
+  `evaluate()` is loaded the first time they run, so neither entry point grew.
+- A caller cancelling a request no longer counts against a provider's circuit.
+- Circuit probe limits are enforced on every attempt through the failover executor, so concurrent
+  requests go to a fallback instead of all probing a half-open provider.
+- Comments are stripped from the emitted JavaScript and kept in the type declarations, where editors
+  read them. Every entry point shrinks as a result: the root import is 572 KB, down from 612 KB, even
+  after the breaker fixes, the `EvalRunner` rebuild, and duplicate-key handling. The published size
+  table has the per-entry-point figures.
+- The packed tarball is 666 KB and 4.1 MB unpacked, up from 3.5 MB, almost all of it the doc comments
+  in the type declarations, which are shipped for both ESM and CommonJS.
+
+### Fixed
+
+- `evaluate()` ignored its `signal` option; aborting now stops new examples, reaches targets, and
+  never stores a partial experiment.
+- `evaluate()` never recorded cost, so `totalCost()` always reported 0. Cost is now read from
+  completion and image results or from a `cost` option.
+- A half-open probe slot was never released when an attempt's error did not count as a failure,
+  leaving the circuit refusing traffic until it was reset.
+- The breaker's documented `halfOpenMaxCalls` was not enforced on real requests: the client routed
+  every request to a half-open provider.
+- The context-window summary call could route to a provider whose circuit was open.
+- `routing.fallback` was accepted but never applied. `onError` models are now tried after every
+  route the router chose, `onTimeout` gives the first attempt its own timeout before its fallback,
+  and `onRateLimit` retries a rate-limited first attempt before falling back.
+- Privacy routing ignored a provider's own `isLocal` declaration, so an OpenAI-compatible server
+  configured as local was still scored as hosted.
+
+### Deprecated
+
+These options were accepted but never read. They still type-check, do nothing, and will be removed
+in 2.0.
+
+- `GoogleProviderConfig.projectId`.
+- `OllamaProviderConfig.timeout`.
+- `MetricsConfig.prometheus`: Prometheus text is always available from `getPrometheusMetrics()`.
+- `DensificationConfig.preserveMarkdown`: densification never rewrites Markdown structure.
+- `HealthConfig.latencyHalfLife`: latency is averaged with a fixed weight.
+
 ## [1.15.0] - 2026-09-21
 
 Evaluation. One entry point for evaluating anything, datasets versioned by their content, experiments
@@ -751,7 +846,8 @@ 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.15.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...HEAD
+[1.16.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.12.0...v1.14.0
 [1.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.11.0...v1.12.0

package/README.md

@@ -105,15 +105,25 @@ nexus scan src --json
 nexus models --provider deepseek
 nexus optimize prompt.txt --model gpt-5.4-mini --max-input-tokens 4000
 nexus eval examples/cli-eval.json
+nexus eval run eval.mjs --out candidate.json --baseline baseline.json --fail-on-regression
+nexus traces list --store runs.jsonl --status error --since 2026-09-20T00:00:00Z
+nexus db sql --adapters operations,traces | psql "$DATABASE_URL"
 ```
 
 CLI commands are intentionally thin wrappers around library modules:
 
 - `nexus scan` checks files for secrets, PII, and prompt-injection patterns.
 - `nexus models` lists the bundled model registry.
-- `nexus eval` runs JSON or JS eval cases.
+- `nexus eval` runs JSON or JS eval cases. `nexus eval run`, `compare`, and `gate` run an evaluation
+  module to an experiment file and fail a build only on a regression beyond noise.
+- `nexus traces list`, `show`, and `export` read a JSONL trace file, or any trace store a module
+  exports — a Postgres store over your own pool, for instance.
+- `nexus db sql` prints the Postgres schema for the adapters you use, for your own migration tooling.
 - `nexus optimize` previews token optimization for a request or prompt file.
 
+Every command takes `--json`. A usage mistake exits with 2 and a failed check with 1, so a CI script
+can tell them apart. The newer commands load their code on demand, so `nexus scan` starts no slower.
+
 ## Core Concepts
 
 ### Providers and Routing
@@ -642,7 +652,7 @@ const checkpointer = new OperationStoreCheckpointer(new RedisOperationStore(redi
 ```
 
 Writes are compare-and-set on the record's sequence, so two workers advancing the same thread cannot
-both win.
+both win. `PostgresOperationStore` works the same way; see [Postgres](#postgres).
 
 **Subgraphs.** A compiled graph is a node:
 
@@ -653,6 +663,37 @@ 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.
 
+**Input and output channels.** Working channels can stay internal:
+
+```ts
+const research = createGraph({
+  channels: { question: lastValue(''), notes: appendList<string>(), answer: lastValue('') },
+  input: ['question'],
+  output: ['answer'],
+});
+```
+
+`invoke()` accepts only `question` and returns only `answer`, in the types as well as at run time. As
+a subgraph it receives only its inputs from the parent and merges back only its outputs, so a parent
+with its own `notes` channel never sees these. Checkpoints, `state()`, and stream events still carry
+the whole state, because they describe the thread rather than answer the caller.
+
+**Caching node results.** An expensive node whose result depends only on what it reads can skip work
+it has already done:
+
+```ts
+graph.addNode('classify', classifyTicket, {
+  cache: { ttlMs: 10 * 60_000, key: ({ state }) => `classify:${(state as Ticket).body}` },
+});
+```
+
+The default key hashes the graph name, the node, the state it sees, and its `Send` input — always
+correct, sometimes too specific, which is what `key` is for. Results live in a bounded in-process map
+by default, or in any cache adapter: `compile({ cache: new RedisCacheAdapter(redis) })` shares them
+across workers. A failure, an interrupt, a node that consumed a human's answer, and a command for a
+parent graph are never cached, and a cache that is down is a miss rather than a failed node. The
+caching code loads the first time a caching node runs.
+
 The graph is not in the root import. It costs nothing to a user who does not build graphs.
 
 ## Agents
@@ -715,7 +756,8 @@ prefix to search. Items can expire with `ttlMs`, be filtered by field, and be ra
 any embedding function you inject — the store never imports the embeddings runtime, and without an
 index a query falls back to matching text. `RedisStore` from `nexus-ai-pro/store/redis` carries the
 same contract across processes through a client-like interface, so no Redis package is a dependency
-here.
+here. `PostgresStore` from `nexus-ai-pro/postgres/store` does the same in Postgres, and ranks in the
+database with pgvector when `vectorDimensions` is set.
 
 ## MCP
 
@@ -723,8 +765,6 @@ The Model Context Protocol, both directions, implemented directly rather than th
 
 ```ts
 import { McpClient, createStdioTransport } from 'nexus-ai-pro/mcp';
-import { Tracer, MemoryTraceStore } from 'nexus-ai-pro/tracing';
-import { evaluate, createDataset, compareExperiments } from 'nexus-ai-pro/evaluate';
 
 const client = new McpClient(createStdioTransport({ command: 'npx', args: ['-y', 'some-mcp-server'] }));
 const agent = createAgent({ client: ai, tools: await client.toNexusTools({ prefix: 'files' }) });
@@ -753,7 +793,7 @@ inputs, outputs, tokens, cost, and errors, stored where you can search it.
 import { Tracer, MemoryTraceStore, traceGraph, traceModelClient } from 'nexus-ai-pro/tracing';
 
 const tracer = new Tracer({
-  store: new MemoryTraceStore(),               // or JsonlTraceStore({ file })
+  store: new MemoryTraceStore(),               // or JsonlTraceStore, or PostgresTraceStore
   sampling: { rate: 0.05, keepErrors: true },  // 5% of traces, plus every failure
   redaction: { hideFields: ['apiKey', 'user.email'] },
 });
@@ -786,6 +826,9 @@ console.log(formatTree(tree));
 await tracer.recordFeedback(runId, { key: 'thumbs', score: 0, source: 'user' });
 ```
 
+The same questions from a terminal: `nexus traces list --store runs.jsonl --status error`, then
+`nexus traces show <traceId>` to print the tree.
+
 `compareTraces(a, b)` lays two runs of the same shape side by side and reports what changed — the
 step that got slower, the tool that stopped being called, the output that differs — which is how
 "it worked yesterday" becomes an answerable question.
@@ -849,6 +892,12 @@ and `trajectory`, which scores *how* an answer was reached — an agent that get
 calling the refund tool three times is not working. The LLM judge from `nexus-ai-pro/evals/judge`
 plugs in as one more evaluator.
 
+**Cost is read from the output**: `meta.cost` on a completion or an image result, or a `cost` field on
+anything else, and a `cost` option reads whatever a custom target returns. `underCost(0.05)` fails an
+example that overspends, and `totalCost()` sums the experiment, so a quality gain that tripled the
+bill is visible. `signal` cancels an evaluation without ever storing a partial experiment, and
+`repetitions` can be a function when some examples are noisier than others.
+
 ### Was the change real?
 
 ```ts
@@ -870,6 +919,21 @@ The report names the examples that moved most, the failures that are new, and th
 fixed. A comparison across different dataset versions says so rather than pretending it is like for
 like.
 
+### In CI
+
+```bash
+nexus eval run eval.mjs --out candidate.json --baseline baseline.json --fail-on-regression
+```
+
+The module exports `{ target, dataset, evaluators, summary? }`. `nexus eval gate baseline.json
+candidate.json` compares two stored experiments on its own. Either fails only when a metric got worse
+beyond noise, a new failure appeared, or the datasets differ; `--allow-dataset-mismatch` accepts the
+last. `FileExperimentStore` keeps experiments as files a pipeline can cache or commit, and
+`PostgresExperimentStore` keeps them in a table.
+
+`EvalRunner` and `MediaEvalRunner` run on `evaluate()` too, and their results carry the experiment
+underneath, so an existing suite can be gated the same way without being rewritten.
+
 ### The runs you did not think of
 
 ```ts
@@ -1046,15 +1110,39 @@ probe closes it; a failed probe reopens it and restarts the cooldown. If *every*
 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:
+A request the caller cancelled never counts against the provider. `isFailure` keeps anything else
+that is not the provider's fault out of the calculation:
 
 ```ts
 circuitBreaker: {
   enabled: true,
-  isFailure: (error) => !(error instanceof Error && error.name === 'AbortError'),
+  isFailure: (error) => !(error instanceof NexusProviderError && error.category === 'bad-response'),
 }
 ```
 
+Probe limits hold on every attempt, retries included: while a probe is in flight, other requests go
+to the next provider instead of piling onto one that has only just come back.
+
+**Sharing circuit state across workers.** By default each worker learns on its own. Give the breaker
+a store and a provider that fails in one worker is taken out of routing in all of them, and when the
+cooldown ends only one worker probes it:
+
+```ts
+import { RedisCircuitStateStore } from 'nexus-ai-pro/ops/circuit-store';
+
+const ai = new NexusAI({
+  providers,
+  circuitBreaker: { enabled: true, store: new RedisCircuitStateStore(redis), workerId: process.env.HOSTNAME },
+});
+await ai.syncCircuitBreaker(); // optional: learn what is open elsewhere before the first request
+```
+
+Only decisions are shared — open, closed, and who may probe. Each worker still counts its own
+failures, and every check stays synchronous: shared state is refreshed in the background at most once
+a second, so the breaker never puts a network call in front of a request. If the store is
+unreachable, each worker decides for itself rather than holding circuits open. `PostgresCircuitStateStore`
+does the same in Postgres, and the coordination code loads only when a store is configured.
+
 **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:
@@ -1187,6 +1275,53 @@ queues the operation id and nothing else.
 
 The image family already runs on this lifecycle, so `ai.images.submit()` reports the same events.
 
+## Postgres
+
+One adapter family for everything that has to outlive a process or be shared between workers, over
+the Postgres client you already have:
+
+```ts
+import pg from 'pg';
+import { PostgresOperationStore, PostgresStore, PostgresTraceStore } from 'nexus-ai-pro/postgres';
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const operations = new PostgresOperationStore(pool);
+await operations.migrate(); // or: nexus db sql | psql "$DATABASE_URL"
+```
+
+| Adapter | Subpath | Serves |
+| --- | --- | --- |
+| `PostgresOperationStore` | `/postgres/operations` | durable operations, and graph checkpoints through `OperationStoreCheckpointer` |
+| `PostgresStore` | `/postgres/store` | long-term memory, ranked by pgvector when `vectorDimensions` is set |
+| `PostgresTraceStore` | `/postgres/traces` | traces, with every query filter in SQL |
+| `PostgresDatasetStore`, `PostgresExperimentStore` | `/postgres/evaluate` | datasets and experiments |
+| `PostgresCircuitStateStore` | `/postgres/circuits` | circuit state shared between workers |
+
+**No driver is a dependency.** Each adapter takes anything with a `query(text, values)` method that
+resolves to `{ rows }`: `pg`'s `Pool` and `Client`, `@neondatabase/serverless`, PGlite.
+`fromPostgresJs(sql)` adapts `postgres.js`. Parameters are only ever strings, numbers, and `null`,
+cast in SQL, so a driver's own conversion of arrays or dates never changes what is stored.
+
+**Nothing creates a schema at import.** `migrate()` applies an adapter's schema when you call it;
+`postgresMigration()` and `nexus db sql` produce the same SQL for the migration tooling you already
+use. Table names are options, schema-qualified if you like.
+
+**What Postgres adds over the other stores.** An operation update is one `UPDATE … WHERE sequence =
+expected`, atomic without a transaction. Idempotency keys are unique in the table, so when two
+workers race to submit the same key the loser attaches to the winner's operation instead of running
+the work twice. Trace feedback is appended in one statement, so two evaluators scoring one run at once
+both land.
+
+A graph thread started on one worker and finished on another is the same code as before, pointed at a
+different store:
+
+```ts
+const graph = builder.compile({ checkpointer: new OperationStoreCheckpointer(new PostgresOperationStore(pool)) });
+```
+
+The adapters are tested on every run against a real Postgres engine — PGlite, PostgreSQL compiled to
+WebAssembly — with the same contract tests the in-memory stores pass.
+
 ## Embeddings
 
 `ai.embed()` is a first-class operation, not a helper: it gets the same routing, caching, batching,
@@ -2153,80 +2288,88 @@ only, so it never appears in an import graph.
 <!-- size-table:start -->
 | Import | Size | Share of root | Third-party install |
 | --- | --- | --- | --- |
-| `nexus-ai-pro` | 612 KB | 100% | +4.7 MB |
-| `nexus-ai-pro/config` | 468 KB | 76% | +4.7 MB |
-| `nexus-ai-pro/core` | 462 KB | 75% | +4.7 MB |
-| `nexus-ai-pro/realtime` | 157 KB | 26% | none |
-| `nexus-ai-pro/batch` | 118 KB | 19% | none |
-| `nexus-ai-pro/realtime/session` | 94 KB | 15% | none |
-| `nexus-ai-pro/embeddings` | 91 KB | 15% | none |
-| `nexus-ai-pro/providers/groq` | 79 KB | 13% | none |
-| `nexus-ai-pro/providers/mistral` | 79 KB | 13% | none |
-| `nexus-ai-pro/providers/azure-openai` | 78 KB | 13% | none |
-| `nexus-ai-pro/providers/openrouter` | 78 KB | 13% | none |
-| `nexus-ai-pro/providers/deepseek` | 77 KB | 13% | none |
-| `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% | none |
-| `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% | none |
-| `nexus-ai-pro/providers/openai` | 77 KB | 13% | none |
-| `nexus-ai-pro/agent` | 76 KB | 12% | none |
-| `nexus-ai-pro/providers/anthropic` | 70 KB | 11% | none |
-| `nexus-ai-pro/providers/google` | 66 KB | 11% | none |
-| `nexus-ai-pro/images` | 65 KB | 11% | none |
-| `nexus-ai-pro/graph` | 60 KB | 10% | none |
-| `nexus-ai-pro/providers/ollama` | 58 KB | 9% | none |
-| `nexus-ai-pro/batch/openai` | 52 KB | 8% | none |
-| `nexus-ai-pro/batch/anthropic` | 52 KB | 8% | none |
-| `nexus-ai-pro/operations` | 49 KB | 8% | none |
-| `nexus-ai-pro/batch/mock` | 47 KB | 8% | none |
-| `nexus-ai-pro/providers/cohere` | 46 KB | 8% | none |
+| `nexus-ai-pro` | 572 KB | 100% | +4.7 MB |
+| `nexus-ai-pro/config` | 441 KB | 77% | +4.7 MB |
+| `nexus-ai-pro/core` | 437 KB | 76% | +4.7 MB |
+| `nexus-ai-pro/realtime` | 156 KB | 27% | none |
+| `nexus-ai-pro/batch` | 101 KB | 18% | none |
+| `nexus-ai-pro/realtime/session` | 94 KB | 16% | none |
+| `nexus-ai-pro/embeddings` | 81 KB | 14% | none |
+| `nexus-ai-pro/providers/groq` | 72 KB | 13% | none |
+| `nexus-ai-pro/providers/mistral` | 72 KB | 13% | none |
+| `nexus-ai-pro/providers/azure-openai` | 71 KB | 12% | none |
+| `nexus-ai-pro/providers/openrouter` | 71 KB | 12% | none |
+| `nexus-ai-pro/providers/deepseek` | 70 KB | 12% | none |
+| `nexus-ai-pro/providers/llamacpp` | 70 KB | 12% | none |
+| `nexus-ai-pro/providers/lmstudio` | 70 KB | 12% | none |
+| `nexus-ai-pro/providers/openai` | 70 KB | 12% | none |
+| `nexus-ai-pro/agent` | 63 KB | 11% | none |
+| `nexus-ai-pro/providers/anthropic` | 62 KB | 11% | none |
+| `nexus-ai-pro/providers/google` | 59 KB | 10% | none |
+| `nexus-ai-pro/images` | 59 KB | 10% | none |
+| `nexus-ai-pro/providers/ollama` | 53 KB | 9% | none |
+| `nexus-ai-pro/graph` | 49 KB | 9% | none |
+| `nexus-ai-pro/batch/openai` | 46 KB | 8% | none |
+| `nexus-ai-pro/batch/anthropic` | 46 KB | 8% | none |
 | `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% | none |
-| `nexus-ai-pro/security` | 40 KB | 7% | +3.4 MB |
-| `nexus-ai-pro/models` | 35 KB | 6% | none |
-| `nexus-ai-pro/evaluate` | 33 KB | 5% | none |
-| `nexus-ai-pro/images/inputs` | 31 KB | 5% | none |
-| `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% | none |
-| `nexus-ai-pro/tracing` | 26 KB | 4% | none |
-| `nexus-ai-pro/evals` | 23 KB | 4% | none |
-| `nexus-ai-pro/images/transform` | 22 KB | 4% | none |
-| `nexus-ai-pro/images/stores` | 22 KB | 4% | none |
-| `nexus-ai-pro/telephony/twilio` | 21 KB | 3% | none |
-| `nexus-ai-pro/telephony` | 20 KB | 3% | none |
+| `nexus-ai-pro/providers/cohere` | 44 KB | 8% | none |
+| `nexus-ai-pro/batch/mock` | 41 KB | 7% | none |
+| `nexus-ai-pro/operations` | 40 KB | 7% | none |
+| `nexus-ai-pro/security` | 39 KB | 7% | +3.4 MB |
+| `nexus-ai-pro/postgres` | 36 KB | 6% | none |
+| `nexus-ai-pro/models` | 32 KB | 6% | none |
+| `nexus-ai-pro/evaluate` | 31 KB | 5% | none |
+| `nexus-ai-pro/realtime/openai-websocket` | 28 KB | 5% | none |
+| `nexus-ai-pro/images/inputs` | 27 KB | 5% | none |
+| `nexus-ai-pro/evals` | 25 KB | 4% | none |
+| `nexus-ai-pro/tracing` | 23 KB | 4% | none |
+| `nexus-ai-pro/images/stores` | 21 KB | 4% | none |
+| `nexus-ai-pro/telephony/twilio` | 21 KB | 4% | none |
+| `nexus-ai-pro/images/transform` | 20 KB | 3% | none |
 | `nexus-ai-pro/images/openai` | 19 KB | 3% | none |
-| `nexus-ai-pro/realtime/mock` | 19 KB | 3% | none |
 | `nexus-ai-pro/voice` | 18 KB | 3% | none |
-| `nexus-ai-pro/mcp` | 18 KB | 3% | none |
-| `nexus-ai-pro/images/comfyui` | 17 KB | 3% | none |
-| `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% | none |
+| `nexus-ai-pro/realtime/mock` | 18 KB | 3% | none |
+| `nexus-ai-pro/telephony` | 18 KB | 3% | none |
+| `nexus-ai-pro/images/evals` | 17 KB | 3% | none |
+| `nexus-ai-pro/images/comfyui` | 16 KB | 3% | none |
+| `nexus-ai-pro/embeddings/adapters` | 16 KB | 3% | none |
 | `nexus-ai-pro/realtime/conversation` | 16 KB | 3% | none |
-| `nexus-ai-pro/images/google` | 15 KB | 2% | none |
-| `nexus-ai-pro/images/evals` | 15 KB | 2% | none |
 | `nexus-ai-pro/images/assets` | 14 KB | 2% | none |
+| `nexus-ai-pro/images/google` | 14 KB | 2% | none |
+| `nexus-ai-pro/mcp` | 14 KB | 2% | none |
 | `nexus-ai-pro/context` | 13 KB | 2% | none |
-| `nexus-ai-pro/operations/adapters` | 13 KB | 2% | none |
 | `nexus-ai-pro/realtime/tools` | 13 KB | 2% | none |
 | `nexus-ai-pro/workflows` | 13 KB | 2% | none |
-| `nexus-ai-pro/images/mock` | 12 KB | 2% | none |
 | `nexus-ai-pro/optimizer` | 11 KB | 2% | none |
 | `nexus-ai-pro/voice/session` | 11 KB | 2% | none |
-| `nexus-ai-pro/store/redis` | 11 KB | 2% | none |
+| `nexus-ai-pro/images/mock` | 11 KB | 2% | none |
+| `nexus-ai-pro/postgres/operations` | 11 KB | 2% | none |
+| `nexus-ai-pro/postgres/store` | 11 KB | 2% | none |
 | `nexus-ai-pro/providers` | 10 KB | 2% | none |
 | `nexus-ai-pro/providers/base` | 10 KB | 2% | none |
-| `nexus-ai-pro/embeddings/models` | 10 KB | 2% | none |
-| `nexus-ai-pro/voice/openai` | 9 KB | 1% | none |
-| `nexus-ai-pro/images/moderation` | 9 KB | 1% | none |
-| `nexus-ai-pro/ops/circuit-breaker` | 8 KB | 1% | none |
+| `nexus-ai-pro/postgres/traces` | 10 KB | 2% | none |
+| `nexus-ai-pro/voice/openai` | 9 KB | 2% | none |
+| `nexus-ai-pro/images/moderation` | 9 KB | 2% | none |
+| `nexus-ai-pro/operations/adapters` | 9 KB | 2% | none |
+| `nexus-ai-pro/testing/record` | 9 KB | 2% | none |
+| `nexus-ai-pro/ops/circuit-breaker` | 9 KB | 2% | none |
+| `nexus-ai-pro/embeddings/models` | 8 KB | 1% | none |
 | `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% | none |
 | `nexus-ai-pro/capabilities` | 8 KB | 1% | none |
-| `nexus-ai-pro/telephony/realtime-bridge` | 7 KB | 1% | none |
-| `nexus-ai-pro/graph/visualize` | 6 KB | 1.0% | none |
-| `nexus-ai-pro/store` | 6 KB | 1.0% | none |
-| `nexus-ai-pro/providers/errors` | 5 KB | 0.8% | none |
-| `nexus-ai-pro/embeddings/mock` | 5 KB | 0.8% | none |
-| `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.8% | none |
-| `nexus-ai-pro/evals/judge` | 5 KB | 0.8% | none |
-| `nexus-ai-pro/operations/webhooks` | 4 KB | 0.7% | none |
-| `nexus-ai-pro/ops/rate-limit-adapters` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/store` | 6 KB | 1% | none |
+| `nexus-ai-pro/store/redis` | 6 KB | 1% | none |
+| `nexus-ai-pro/telephony/realtime-bridge` | 6 KB | 1% | none |
+| `nexus-ai-pro/providers/errors` | 5 KB | 0.9% | none |
+| `nexus-ai-pro/postgres/evaluate` | 5 KB | 0.9% | none |
+| `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.9% | none |
+| `nexus-ai-pro/evals/judge` | 5 KB | 0.9% | none |
+| `nexus-ai-pro/embeddings/mock` | 4 KB | 0.7% | none |
+| `nexus-ai-pro/operations/webhooks` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/graph/visualize` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/postgres/circuits` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/ops/circuit-store` | 3 KB | 0.5% | none |
 | `nexus-ai-pro/cache/memory-cache` | 3 KB | 0.5% | none |
+| `nexus-ai-pro/ops/rate-limit-adapters` | 2 KB | 0.3% | none |
 | `nexus-ai-pro/cache` | 2 KB | 0.3% | none |
 | `nexus-ai-pro/cache/adapters` | 2 KB | 0.3% | none |
 | `nexus-ai-pro/rag` | 2 KB | 0.3% | none |
@@ -2281,12 +2424,40 @@ npm run check:release
 conformance tests, coverage thresholds, package import checks, and an external type-consumer test.
 `check:release` additionally verifies the dry-run tarball and a clean packed-package install.
 
+`npm run docs:check` fails when any public export, or any public member of an exported class,
+interface, or enum, has no doc comment. Every entry point is kept at 100%; `--list` names what is
+missing.
+
 Real provider conformance is opt-in:
 
 ```bash
 npm run test:conformance:real
 ```
 
+### Recorded provider traffic
+
+A suite that needs credentials can run everywhere else from recordings:
+
+```ts
+import { fixtureFetch } from 'nexus-ai-pro/testing/record';
+
+// Replays by default; NEXUS_FIXTURES=record captures, NEXUS_FIXTURES=live bypasses.
+const fetch = fixtureFetch({ directory: 'tests/fixtures/openai' });
+const provider = new OpenAIImageProvider({ apiKey: process.env.OPENAI_API_KEY ?? 'replay', fetch });
+```
+
+Recording writes one reviewable JSON file per exchange. Credential headers and query parameters are
+removed before anything is written, and a `redact` hook handles the rest — personal data in a prompt,
+through a PII detector from `nexus-ai-pro/security`, for instance. Replay serves the files back with
+no network, matches requests by method, URL, and body with object keys sorted and multipart
+boundaries ignored, and throws `FixtureMissingError` for anything unrecorded instead of reaching the
+live API. `installFetch()` covers code that calls the global `fetch`.
+
+```bash
+npm run test:conformance:images       # replays image recordings; needs no credentials
+npm run conformance:images:record     # records them; needs OPENAI_API_KEY, GOOGLE_API_KEY, or COMFYUI_URL
+```
+
 ## Roadmap
 
 See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what has
@@ -2296,13 +2467,15 @@ live in [API_STABILITY.md](./API_STABILITY.md).
 Shipped so far:
 
 - completion controls and capability negotiation;
-- durable operations, provider batch tiers, and distributed resilience;
-- first-class embeddings and graphs;
+- durable operations, provider batch tiers, and distributed resilience, now including shared circuit
+  state and a Postgres adapter family;
+- embeddings, graphs, long-term memory, agents on graphs, and MCP;
+- queryable traces, an evaluation platform, and a CI gate on top of it;
+- record and replay of provider traffic;
 - per-entry-point size budgets.
 
-The current work is image portability: three backends behind one contract, masked edits, validated
-inputs, visual moderation, and media evaluation. Promotion out of experimental waits on live
-conformance.
+Next is prompt and configuration versioning. The image family leaves experimental once recorded live
+conformance passes on all three backends.
 
 ## Known Limitations
 
@@ -2317,8 +2490,10 @@ conformance.
 - 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.
+- Realtime sessions are not yet routed through the metrics, audit, and rate-limit path that every
+  other family uses.
+- The image adapters are verified against documented wire shapes; recorded live conformance for all
+  three backends is still to come, which is why the family is experimental.
 
 ## Production Notes