nexus-ai-pro 1.4.0 → 1.6.0

package/API_STABILITY.md

@@ -106,6 +106,58 @@ exactly-once provider execution. Those capabilities will use additive adapters a
 `MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
 tenant state.
 
+## Embeddings API stage
+
+The `nexus-ai-pro/embeddings` family is public and follows the 1.x rules, including the explicit
+`embeddings/adapters`, `embeddings/mock`, and `embeddings/models` subpaths. This covers
+`EmbeddingManager`, `ai.embed()` and `ai.embedOne()`, the `EmbeddingsProvider` contract, the
+normalized request, embedding, and meta shapes, the error subclasses, and `toEmbeddingFunction()`.
+
+`EmbeddingsProvider` is a distinct contract from the pre-existing `EmbeddingProvider` function type
+used by `MemoryVectorStore`, the semantic cache, and RAG ingestion. That function type is unchanged
+and remains supported; `toEmbeddingFunction()` converts one into the other.
+
+Two behaviors are guaranteed and differ deliberately from completions. Vectors are returned in input
+order regardless of how the request was split, deduplicated, or served from cache. And an option the
+target model or adapter declares it cannot honor is **refused**, not dropped, because a vector built
+with different dimensions or a different input type is silently incompatible with vectors already in
+a store. An option nothing in the registry describes is still passed through, on the same
+absence-means-unknown rule the completion path uses.
+
+Embedding model entries are registry data, not compatibility guarantees. Bundled dimensions, input
+limits, batch limits, and prices can change in a minor release when a provider changes its lineup,
+and are overridable through `embeddings.models.registry`. Which concrete model an alias such as
+`embed-quality` resolves to can also change in a minor release: the vectors two targets produce are
+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.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,126 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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,
+retry, audit, and metrics that until now only completions had, so embedding spend is visible next to
+completion spend instead of leaving the platform entirely. Everything here is additive.
+
+### Added
+
+- **`ai.embed()` and `ai.embedOne()`.** A provider-neutral embeddings operation family behind
+  `EmbeddingManager`, reached through `ai.embeddings` or the new `nexus-ai-pro/embeddings` subpath.
+  The manager is built on first access, so a runtime that never embeds pays nothing for it.
+- **Adapters for OpenAI, Google, Cohere, Mistral, and Ollama**, plus any OpenAI-compatible
+  `/embeddings` server through `OpenAIEmbeddingProvider`'s `baseUrl` and `providerName`. They are
+  registered automatically from the provider credentials already in `providers`, so a configured
+  chat provider makes `ai.embedOne('text')` work with no embedding-specific configuration. Explicit
+  registration through `registerEmbeddingProvider()` always wins, and auto-registration can be
+  turned off with `embeddings.autoRegisterProviders: false`.
+- **Batching, deduplication, and per-input caching.** A batch larger than the model's limit is split
+  and run with bounded concurrency, and the vectors still come back in input order. Repeated texts
+  within one request are answered by a single provider call, and caching is keyed per input, so a
+  partially repeated batch only sends the texts it has not seen. `meta.batches`, `meta.cachedInputs`,
+  and `meta.deduplicatedInputs` report what actually happened.
+- **Structured usage and numeric cost for embeddings.** `meta.usage` and `meta.cost` reuse the same
+  `TokenUsage` and `ResponseCost` shapes as completions, priced from a new embedding model registry.
+  When a provider reports no token counts — Google's `batchEmbedContents` does not — tokens are
+  estimated locally rather than reported as zero, so a call is never priced at nothing.
+- **An embedding model registry** with dimensions, supported truncation sizes, input limits, batch
+  limits, and prices for eleven models across five providers, with aliases (`auto`, `embed-fast`,
+  `embed-quality`, `embed-multilingual`, `embed-local`) and full override through
+  `embeddings.models.registry`. It is deliberately separate from `KNOWN_MODELS`, because completion
+  routing scores models on context window, output price, and tool support, none of which an
+  embedding model has.
+- **Capability refusal.** An unsupported `dimensions`, `inputType`, `encodingFormat`, or `truncate`
+  value throws `EmbeddingCapabilityError` before the provider call. Embeddings refuse rather than
+  drop: a vector built with different dimensions is silently incompatible with the vectors already
+  in a store, and the mismatch only surfaces later as unexplained retrieval quality loss. An option
+  the registry says nothing about is still passed through, and `providerOptions` reaches the
+  provider body untouched.
+- **`toEmbeddingFunction()`**, which adapts the family to the plain `EmbeddingProvider` function that
+  `MemoryVectorStore`, the semantic cache, and RAG ingestion already accept. An existing vector store
+  gains routing, caching, retry, and metrics without changing its own contract.
+- **`normalize`** for unit-length vectors, applied locally when the provider does not already return
+  them, and reapplied after a locally truncated vector loses its length.
+- **A deterministic `MockEmbeddingProvider`** and `runEmbeddingProviderConformance()`, which checks
+  one vector per input, input order, consistent width, optional determinism, and an honored abort.
+- New subpaths `nexus-ai-pro/embeddings`, `embeddings/adapters`, `embeddings/mock`, and
+  `embeddings/models`.
+
+### Changed
+
+- `RateLimiter.check()` accepts the new structural `RateLimitedRequest` instead of a
+  `CompletionRequest`, so one limiter instance and one budget cover every operation family.
+  `CompletionRequest` still satisfies it, so no call site changes.
+- Coverage rose from 82.6% lines / 68.9% branches / 78.2% functions to 85.7% / 70.9% / 80.8%, with
+  65 new tests. `embeddings/providers.ts`, previously the weakest file in the package at 37% lines,
+  is now at 99%.
+
+### Notes
+
+- Bundled embedding dimensions and prices are defaults, not financial truth; override them through
+  `embeddings.models.registry` when exact numbers matter.
+- Which concrete model an embedding alias resolves to can change in a minor release. Two targets do
+  not produce interchangeable vectors, so pin a concrete model when a stored index must stay valid
+  across upgrades.
+
 ## [1.4.0] - 2026-08-25
 
 Request parity and cost truth: the completion request can now express what current models actually
@@ -201,7 +321,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.4.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...HEAD
+[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
 [1.2.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.0...v1.2.1

package/README.md

@@ -83,6 +83,8 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - estimate tokens and cost before provider calls
 - 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
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
 - keep TypeScript types around every request and response
 
@@ -416,6 +418,188 @@ const response = await ai.completeVerified(
 );
 ```
 
+## 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 { 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,
+budget, retry, audit, and metrics as a completion, so embedding spend shows up next to completion
+spend instead of being invisible.
+
+The smallest call is one line, and needs no embedding-specific configuration — adapters are derived
+from the provider credentials already in `providers`:
+
+```ts
+import { NexusAI } from 'nexus-ai-pro';
+
+const ai = new NexusAI({ providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } } });
+
+const vector = await ai.embedOne('Provider-neutral embeddings.');
+```
+
+A batch returns vectors in input order regardless of how many provider calls the model's batch
+limit required, and reports what the call cost:
+
+```ts
+const response = await ai.embed({
+  input: documents.map((document) => document.text),
+  model: 'embed-quality',
+  inputType: 'document',
+  normalize: true,
+});
+
+response.vectors;                  // number[][], in input order
+response.meta.batches;             // provider calls the split required
+response.meta.usage.inputTokens;   // reported by the provider, or estimated when it reports none
+response.meta.cost.amount;         // numeric, priced from the embedding registry
+response.meta.cachedInputs;        // inputs answered from cache
+response.meta.deduplicatedInputs;  // repeated inputs answered from one call
+```
+
+Caching is per input rather than per request, so a partially repeated batch only sends the texts it
+has not seen. Repeated texts inside one batch are collapsed into a single provider call:
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  embeddings: {
+    cache: { enabled: true, ttlSeconds: 86_400 },
+    costBudget: { enabled: true, maxEstimatedCost: 5 },
+    retry: { enabled: true, maxRetries: 2 },
+    fallback: [{ provider: 'cohere', model: 'embed-v4.0' }],
+  },
+});
+```
+
+Unlike a completion, an unsupported embedding option is **refused rather than dropped**. A vector
+built with different dimensions or a different input type is silently incompatible with the vectors
+already in a store, and the mismatch only surfaces later as unexplained retrieval quality loss:
+
+```ts
+await ai.embed({ input: 'x', model: 'embed-english-v3.0', dimensions: 512 });
+// EmbeddingCapabilityError: model has a fixed size of 1024 dimensions
+```
+
+An option the registry says nothing about is still passed through, because an undeclared capability
+means unknown rather than unsupported, and `providerOptions` reaches the provider body untouched for
+anything the neutral contract does not model yet.
+
+Existing vector stores keep their contract. `toEmbeddingFunction()` adapts the family to the plain
+function `MemoryVectorStore`, the semantic cache, and RAG ingestion already accept:
+
+```ts
+import { MemoryVectorStore, toEmbeddingFunction } from 'nexus-ai-pro';
+
+const store = new MemoryVectorStore(toEmbeddingFunction(ai, { inputType: 'document' }));
+```
+
+Bundled adapters cover OpenAI (and any OpenAI-compatible `/embeddings` server), Google, Cohere,
+Mistral, and Ollama. A custom adapter implements `EmbeddingsProvider` and is checked against the
+neutral contract by `runEmbeddingProviderConformance()`:
+
+```ts
+import { OpenAIEmbeddingProvider } from 'nexus-ai-pro/embeddings/adapters';
+import { MockEmbeddingProvider } from 'nexus-ai-pro/embeddings/mock';
+
+ai.registerEmbeddingProvider('gateway', new OpenAIEmbeddingProvider({
+  apiKey: process.env.GATEWAY_KEY!,
+  baseUrl: 'https://gateway.internal/v1',
+  providerName: 'gateway',
+}));
+ai.registerEmbeddingProvider('mock', new MockEmbeddingProvider());
+```
+
+Bundled embedding dimensions and prices are defaults, not financial truth. Override them through
+`embeddings.models.registry` when exact numbers matter.
+
 ## Image Generation and Editing (Experimental)
 
 Image operations use a separate provider-neutral manager because generated assets have different
@@ -1133,6 +1317,13 @@ 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';
+import { KNOWN_EMBEDDING_MODELS } from 'nexus-ai-pro/embeddings/models';
 import { ImageManager } from 'nexus-ai-pro/images';
 import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
 import { MockImageProvider } from 'nexus-ai-pro/images/mock';

package/ROADMAP.md

@@ -3,10 +3,11 @@
 This roadmap is a design proposal, not a compatibility promise. Stable and experimental
 surfaces are defined in [API_STABILITY.md](./API_STABILITY.md).
 
-Status baseline: **1.4.0**. 55 export subpaths, 12 completion providers, 99 registry models plus 63
-aliases. 163 unit tests pass; coverage sits at **82.6% lines / 68.9% branches / 78.2% functions**
-against gates of 80/68/75. CI verifies lint, format, build, tests, coverage, mock conformance,
-packed-package smoke, API contract, consumer type resolution, and clean install on Node 22 and 24.
+Status baseline: **1.6.0**. 62 export subpaths, 12 completion providers, 5 embedding providers, 99
+completion registry models plus 63 aliases, and 11 embedding models plus 5 aliases. 292 unit tests
+pass; coverage sits at **86.3% lines / 71.6% branches / 81.4% functions** against gates of
+82/67/73. CI verifies lint, format, build, tests, coverage, mock conformance, packed-package smoke,
+API contract, consumer type resolution, and clean install on Node 22 and 24.
 
 ---
 
@@ -91,7 +92,26 @@ parallel-tool-call, seed, top-k, and penalty controls; structured `usage` with c
 cached-write, and reasoning token counts; numeric `cost` priced per token class; and capability
 negotiation under a `strict`, `warn`, or `off` policy with registry provenance and a freshness check.
 
-### 1.8 Operations, evaluation, and packaging
+### 1.8 Embeddings
+
+Delivered in 1.5.0. `ai.embed()` and `ai.embedOne()` over a provider-neutral `EmbeddingsProvider`
+contract with adapters for OpenAI (and any OpenAI-compatible server), Google, Cohere, Mistral, and
+Ollama, auto-registered from existing provider credentials. Around them: model-registry routing with
+aliases and per-provider fallback, batch splitting with bounded concurrency, within-request
+deduplication, per-input caching, cost budgets, retry, structured usage and numeric cost, capability
+refusal rather than silent option dropping, `toEmbeddingFunction()` for existing vector stores, a
+deterministic mock, and a conformance harness.
+
+### 1.9 Durable operations
+
+Delivered in 1.6.0. `OperationRunner` over an `OperationStore` contract, with a checked state
+machine, leases and heartbeats, delayed retry with backoff and jitter, dead-lettering, progress
+events, idempotency replay, crash recovery, and HMAC-signed webhooks with a matching verifier.
+`MemoryOperationStore` keeps the single-process case dependency-free; `RedisOperationStore` and
+`BullMQOperationDispatcher` make the same code survive a restart. Persisting raw bytes is refused
+so binary media cannot end up in a queue payload.
+
+### 1.10 Operations, evaluation, and packaging
 
 Rate limiting, audit logging, in-memory and OpenTelemetry metrics sinks, Prometheus export, an
 OpenTelemetry trace exporter, provider health monitoring, `EvalRunner` with LLM-as-judge and a
@@ -107,21 +127,27 @@ trusted publishing with provenance.
 
 Ordered by how much each one costs a consumer today.
 
-### 2.1 Only completions get the platform
+### 2.1 Media families still do not get the platform
 
-The pipeline, rate limiter, audit log, metrics collector, and cost budget are wired into
-`complete()` and `stream()` only. `ImageManager`, `VoiceManager`, `TelephonyManager`, and
-`RealtimeSession` emit nothing to `MetricsCollector` and pass through no rate limit or audit stage.
-An application running phone agents and image generation has observability for the smallest part of
-its spend. `PipelineContext` is also typed strictly around `CompletionRequest`/`NexusResponse`, so
-other families cannot reuse it without a refactor, and `PipelineStepName` ends in `| string`, which
-erases the union it defines.
+Narrowed in 1.5.0: `EmbeddingManager` shares the runtime's rate limiter, audit log, and metrics
+collector, and `RateLimiter` now buckets on a structural request rather than a `CompletionRequest`,
+so a family no longer has to be a completion to be governed. `ImageManager`, `VoiceManager`,
+`TelephonyManager`, and `RealtimeSession` still emit nothing to `MetricsCollector` and pass through
+no rate limit or audit stage, so an application running phone agents and image generation has
+observability for only part of its spend.
 
-### 2.2 No first-class embeddings operation
+The traced pipeline itself remains completion-only. `PipelineContext` is typed strictly around
+`CompletionRequest`/`NexusResponse`, so other families cannot reuse it without a refactor, and
+`PipelineStepName` ends in `| string`, which erases the union it defines. Embeddings therefore share
+the observability primitives but not the step trace.
 
-`src/embeddings/providers.ts` exports OpenAI/Gemini/Cohere factory functions used only by the
-semantic cache and vector store. There is no `ai.embed()`, so embeddings get no routing, caching,
-budget, retry, audit, or metrics — and no provider-neutral batch contract.
+### 2.2 Embeddings beyond text retrieval
+
+Closed for text in 1.5.0: `ai.embed()` is an operation family with routing, per-input caching,
+batching, deduplication, budget, retry, audit, and metrics, over five adapters and its own model
+registry. What remains is everything the family does not yet cover: a provider batch-API tier for
+large asynchronous ingestion jobs, image and multimodal embeddings, a distributed cache adapter for
+vectors shared across processes, and reranking as a sibling operation.
 
 ### 2.3 The model registry is still hand-maintained
 
@@ -130,13 +156,17 @@ visible. The data itself is still a hand-written TypeScript literal of 99 models
 Generation from versioned provider data remains outstanding, and the Claude 5 reasoning bug 1.4.0
 fixed is the kind of error generation would have prevented.
 
-### 2.4 Durable-execution primitives are process-local
+### 2.4 Durable execution is only half distributed
+
+Closed in 1.6.0 for operations: `OperationHandle` is no longer process-bound, cross-process recovery
+works through lapsed leases, and idempotency keys deduplicate across workers.
 
-`RateLimiter` is an in-memory token bucket with no distributed adapter. There is no circuit breaker
-(health monitoring exists, but nothing opens a circuit). `OperationHandle` is process-bound;
-`MemoryAssetStore` is process-local. Realtime conversation snapshots and exports live in memory.
-Cross-process recovery, distributed deduplication, and provider-state replay remain application
-responsibilities.
+Still process-local: `RateLimiter` is an in-memory token bucket with no distributed adapter, there is
+no circuit breaker (health monitoring exists, but nothing opens a circuit), `MemoryAssetStore` holds
+assets in one process, and realtime conversation snapshots and exports live in memory. Provider-state
+replay remains an application responsibility. One caveat on what did land: `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.
 
 ### 2.5 Image family blockers
 
@@ -160,14 +190,14 @@ local estimate, and a published latency benchmark methodology remain follow-on w
 ### 2.7 Test coverage weak spots
 
 1.4.0 closed the worst of these: the agent loop went from 40% to 95% line coverage, the rules router
-from 34% to 91%, and the evaluation metric library from 40% (5% of functions) to 99%. What is still
-thin:
+from 34% to 91%, and the evaluation metric library from 40% (5% of functions) to 99%. 1.5.0 took
+`embeddings/providers.ts` from 37% to 99% and landed the new embeddings family at 95–100% across its
+seven files. What is still thin:
 
 | Area | Lines | Note |
 | --- | --- | --- |
 | `hallucination/rag.ts`, `verification.ts` | 38% / 47% | Grounding claims deserve tests. |
 | `workflow/chains.ts`, `domain.ts` | 51% / 50% | |
-| `embeddings/providers.ts` | 37% | Should be covered as part of the embeddings operation family. |
 | `security/pii-detector.ts`, `semantic-injection-classifier.ts` | 49% / 49% | Security-relevant. |
 | `jobs/queue.ts`, `batch.ts` | 47% / 53% | |
 | `rag/file-ingestion.ts` | 43% | |
@@ -219,15 +249,44 @@ policy vocabulary is in place for a later release that revisits this.
 
 ---
 
-## 4. Next release: 1.5.0 — durable operations and batch economics
+## 4. Shipped in 1.5.0 — embeddings as an operation family
+
+`ai.embed()` with routing, per-input caching, batching, deduplication, budget, retry, audit, and
+metrics; the existing factory functions became one adapter shape behind it, and
+`toEmbeddingFunction()` keeps `MemoryVectorStore`, the semantic cache, and RAG ingestion working
+unchanged. Embeddings refuse an unsupported option rather than dropping it, because a mis-sized
+vector is silently incompatible with a populated store rather than merely different.
+
+Deliberately deferred: the provider batch-API tier, which belongs with the durable operation handle
+below rather than with the synchronous path.
+
+## 5. Shipped in 1.6.0 — durable operations
+
+The first half of *work that outlives a process*. One lifecycle now covers every long-running
+family, and it survives a worker crash.
+
+- **Operation state machine.** `queued → running → retrying → succeeded | failed | cancelling |
+  cancelled | expired`, with leases, heartbeats, progress events, delayed retry, dead-letter
+  handling, timestamps, signed webhooks, and trace propagation. The image family runs on it, and the
+  lifecycle types moved to a family-neutral `types/operations.ts` re-exported from their old home.
+- **Durable operation adapters.** `RedisOperationStore` persists records with a compare-and-set on
+  `sequence`, done in one Lua call when the client exposes `eval`. `BullMQOperationDispatcher`
+  queues the operation id only. A record carrying raw bytes is refused rather than serialized.
+- **Idempotency and recovery.** A matching key replays an accepted operation instead of starting a
+  second; `recover()` resumes records whose lease lapsed, expiring those past their deadline and
+  dead-lettering those that used every attempt.
+
+Restart survival comes from leases rather than locks. There is no distributed lock anywhere: every
+store write is a compare-and-set, so a losing writer is told it lost instead of overwriting.
+
+Deliberately deferred: everything below, which needed the operation handle to exist first.
+
+---
+
+## 6. Next release: 1.7.0 — batch economics and distributed limits
 
-The theme is work that outlives a process.
+The rest of the theme, now that the handle they sit behind exists.
 
-- **Operation state machine.** `queued → running → succeeded | failed | cancelling | cancelled | expired`,
-  with leases, heartbeats, progress events, delayed retry, dead-letter handling, timestamps, signed
-  webhooks, and trace propagation. Applies to images first, then to any long-running family.
-- **Durable operation adapters.** Redis and BullMQ-backed handles so `submit()` survives a restart.
-  Queue asset references only; never JSON-serialize binary media into job payloads.
 - **Provider batch APIs.** OpenAI Batch and Anthropic Message Batches behind the same operation
   handle, exposing the discounted asynchronous tier that local `runBatch()` concurrency cannot reach.
   Idempotency keys replay an accepted operation; ambiguous timeouts must not produce duplicate
@@ -235,19 +294,17 @@ The theme is work that outlives a process.
 - **Distributed rate limiting and circuit breaking.** Redis-backed limiter adapter, plus a breaker
   that consumes existing `ProviderHealthMonitor` signals and trips routing away from a failing
   provider.
-- **Embeddings as an operation family.** `ai.embed()` with routing, caching, batching, budget, retry,
-  audit, and metrics; existing factories become adapters behind it.
 - **Filesystem and S3-compatible asset stores** implementing the existing `AssetStore` interface,
   with retention, tenant ownership, checksums, streaming, and signing. Provider URLs remain temporary
   delivery locations, never durable storage.
 - **Generated model registry** from versioned provider data, consuming the 1.4.0 provenance fields.
 - **Cross-family observability.** Route image, voice, telephony, and realtime operations through the
-  rate limiter, audit log, and metrics collector, closing gap 2.3 without waiting for the full
+  rate limiter, audit log, and metrics collector, closing gap 2.1 without waiting for the full
   lifecycle refactor.
 
 ---
 
-## 5. 1.6.0 — image portability, then promotion
+## 7. 1.8.0 — image portability, then promotion
 
 Images cannot leave experimental until the neutral contract survives a second wire protocol.
 
@@ -275,7 +332,7 @@ label come off.
 
 ---
 
-## 6. 2.0 candidate — one lifecycle for every operation
+## 8. 2.0 candidate — one lifecycle for every operation
 
 Create an internal typed lifecycle and adapt every family to it:
 
@@ -298,7 +355,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 7. Longer-term backlog
+## 9. Longer-term backlog
 
 1. MCP client and server adapters with asset and tool interoperability.
 2. Video generation through the same asynchronous operation, job, and asset contracts.
@@ -323,7 +380,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 8. Design notes carried forward
+## 10. Design notes carried forward
 
 These decisions predate this revision and still hold.
 
@@ -375,7 +432,7 @@ await ai.images.edit({
 
 ---
 
-## 9. How an item graduates
+## 11. How an item graduates
 
 1. Provider-neutral types and a deterministic mock land first.
 2. One real adapter proves the contract; conformance fixtures cover it.