onbuzz 4.8.3 → 4.9.1

package/src/services/embeddings/__tests__/inMemoryJsonStore.test.js

@@ -0,0 +1,207 @@
+/**
+ * Conformance tests for InMemoryJsonStore. Most of the test surface lives
+ * in `runStoreContractTests`, which any future VectorStore implementation
+ * also has to pass (e.g. sqliteVecStore later). This file adds a few
+ * implementation-specific tests on top: atomic-write behavior, the
+ * substring path, and the RRF fusion helper directly.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import os from 'os';
+import fsp from 'fs/promises';
+import path from 'path';
+import { InMemoryJsonStore } from '../vectorStore/inMemoryJsonStore.js';
+import { reciprocalRankFusion } from '../vectorStore/storeInterface.js';
+import { runStoreContractTests } from '../vectorStore/storeContractTests.js';
+
+// Shared conformance contract — every VectorStore impl runs through these.
+runStoreContractTests((opts) => new InMemoryJsonStore(opts));
+
+describe('reciprocalRankFusion', () => {
+  test('items present in both lists rank higher than items in only one', () => {
+    const out = reciprocalRankFusion([
+      [{ id: 'both' }, { id: 'only-semantic' }],
+      [{ id: 'both' }, { id: 'only-substring' }],
+    ]);
+    expect(out[0].id).toBe('both');
+  });
+
+  test('preserves input ranking when only one list has results', () => {
+    const out = reciprocalRankFusion([
+      [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+      [],
+    ]);
+    expect(out.map(x => x.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  test('topK trims output', () => {
+    const out = reciprocalRankFusion(
+      [[{ id: 'a' }, { id: 'b' }, { id: 'c' }]],
+      { topK: 2 },
+    );
+    expect(out).toHaveLength(2);
+  });
+
+  test('empty input lists produce empty output', () => {
+    expect(reciprocalRankFusion([])).toEqual([]);
+    expect(reciprocalRankFusion([[], []])).toEqual([]);
+  });
+
+  test('ignores non-array entries gracefully', () => {
+    expect(() => reciprocalRankFusion([null, undefined, [{ id: 'x' }]])).not.toThrow();
+    const out = reciprocalRankFusion([null, undefined, [{ id: 'x' }]]);
+    expect(out.map(o => o.id)).toEqual(['x']);
+  });
+});
+
+describe('InMemoryJsonStore — atomic persistence', () => {
+  let tmpDir, filePath, store;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-vec-atomic-'));
+    filePath = path.join(tmpDir, 'store.vec.json');
+    store = new InMemoryJsonStore({
+      filePath,
+      dimensions: 4,
+      modelFingerprint: 'test:fp',
+    });
+    await store.load();
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('writes via .tmp + rename (no partial file on disk after success)', async () => {
+    await store.upsert('a', Float32Array.from([1, 0, 0, 0]), { text: 'a' });
+    const entries = await fsp.readdir(tmpDir);
+    expect(entries).toContain('store.vec.json');
+    expect(entries.filter(e => e.endsWith('.tmp'))).toEqual([]);
+  });
+
+  test('drop() removes the file from disk', async () => {
+    await store.upsert('a', Float32Array.from([1, 0, 0, 0]), {});
+    await store.drop();
+    await expect(fsp.access(filePath)).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+
+  test('writes parent directory if missing', async () => {
+    const nested = path.join(tmpDir, 'nested', 'dirs', 'store.vec.json');
+    const nestedStore = new InMemoryJsonStore({
+      filePath: nested,
+      dimensions: 4,
+      modelFingerprint: 'test:fp',
+    });
+    await nestedStore.load();
+    await nestedStore.upsert('a', Float32Array.from([1, 0, 0, 0]), {});
+    await expect(fsp.access(nested)).resolves.toBeUndefined();
+  });
+
+  test('corrupt JSON on load → starts empty, no throw', async () => {
+    await fsp.writeFile(filePath, 'not json{{');
+    const broken = new InMemoryJsonStore({
+      filePath,
+      dimensions: 4,
+      modelFingerprint: 'test:fp',
+    });
+    await expect(broken.load()).resolves.toBeUndefined();
+    expect((await broken.stats()).count).toBe(0);
+  });
+
+  test('upsert before load() throws', async () => {
+    const noLoad = new InMemoryJsonStore({
+      filePath: path.join(tmpDir, 'other.vec.json'),
+      dimensions: 4,
+      modelFingerprint: 'test:fp',
+    });
+    await expect(
+      noLoad.upsert('a', Float32Array.from([1, 0, 0, 0]), {}),
+    ).rejects.toThrow(/not loaded/);
+  });
+});
+
+describe('InMemoryJsonStore — substring matches', () => {
+  let tmpDir, store;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-vec-substr-'));
+    store = new InMemoryJsonStore({
+      filePath: path.join(tmpDir, 'store.vec.json'),
+      dimensions: 2,
+      modelFingerprint: 'test:fp',
+    });
+    await store.load();
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('hybridQuery surfaces a row that matches ONLY on substring', async () => {
+    await store.upsertBatch([
+      { id: 'a', vector: Float32Array.from([1, 0]), metadata: { text: 'banana' } },
+      { id: 'b', vector: Float32Array.from([0, 1]), metadata: { text: 'apple pie' } },
+    ]);
+    // Query vector orthogonal to 'a' (cosine=0) but text matches 'apple'.
+    const hits = await store.hybridQuery(Float32Array.from([1, 0]), 'apple');
+    expect(hits.find(h => h.id === 'b')).toBeDefined();
+  });
+
+  test('case-insensitive substring', async () => {
+    await store.upsert('a', Float32Array.from([1, 0]), { text: 'Telegram Errors' });
+    const hits = await store.hybridQuery(Float32Array.from([0, 0]), 'telegram');
+    expect(hits.find(h => h.id === 'a')).toBeDefined();
+  });
+
+  test('rows missing metadata.text are skipped on substring side', async () => {
+    await store.upsertBatch([
+      { id: 'a', vector: Float32Array.from([1, 0]), metadata: {} },
+      { id: 'b', vector: Float32Array.from([0, 1]), metadata: { text: null } },
+      { id: 'c', vector: Float32Array.from([0.5, 0.5]), metadata: { text: 'matches' } },
+    ]);
+    const hits = await store.hybridQuery(Float32Array.from([0, 0]), 'matches');
+    // Only 'c' should appear from the substring side — the semantic side
+    // adds 'a' and 'b' but their substring rank is empty.
+    expect(hits.map(h => h.id)).toContain('c');
+  });
+});
+
+describe('InMemoryJsonStore — drift recovery', () => {
+  let tmpDir, filePath;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-vec-drift-'));
+    filePath = path.join(tmpDir, 'store.vec.json');
+    const initial = new InMemoryJsonStore({
+      filePath, dimensions: 4, modelFingerprint: 'azure:text-embedding-3-small',
+    });
+    await initial.load();
+    await initial.upsert('a', Float32Array.from([1, 0, 0, 0]), { text: 'kept?' });
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  test('switching provider (fingerprint mismatch) presents empty corpus', async () => {
+    const swapped = new InMemoryJsonStore({
+      filePath, dimensions: 4, modelFingerprint: 'local:Xenova/nomic-embed-text-v1.5',
+    });
+    await swapped.load();
+    expect((await swapped.stats()).count).toBe(0);
+  });
+
+  test('after re-embed, new fingerprint persists', async () => {
+    const swapped = new InMemoryJsonStore({
+      filePath, dimensions: 768, modelFingerprint: 'local:Xenova/nomic-embed-text-v1.5',
+    });
+    await swapped.load();
+    await swapped.upsert('a', Float32Array.from(Array(768).fill(0.01)), { text: 're-embedded' });
+    const re = new InMemoryJsonStore({
+      filePath, dimensions: 768, modelFingerprint: 'local:Xenova/nomic-embed-text-v1.5',
+    });
+    await re.load();
+    expect((await re.stats()).count).toBe(1);
+    expect((await re.stats()).modelFingerprint).toBe('local:Xenova/nomic-embed-text-v1.5');
+  });
+});

package/src/services/embeddings/__tests__/localProvider.test.js

@@ -0,0 +1,263 @@
+/**
+ * Tests for LocalEmbeddingProvider.
+ *
+ * Key design: tests inject a `pipelineFactory` instead of letting the
+ * provider load real ONNX models — we'd otherwise download ~250 MB
+ * on every CI run. The factory returns a stub pipeline that mirrors
+ * the Transformers.js return shape (Tensor with .tolist()).
+ *
+ * Real model loading is covered by an opt-in integration test that
+ * runs only when LOXIA_RUN_LOCAL_EMBED_E2E=1.
+ *
+ * What this pins:
+ *   - Lazy model load (no work at construction; first embed triggers it)
+ *   - Load failure is sticky — repeated calls don't retry forever
+ *   - Concurrent first-calls dedup the load (no double download)
+ *   - nomic prefix applied to query vs document
+ *   - BGE prefix applied to query only
+ *   - 1-D pipeline output gets wrapped back into 2-D (Transformers.js
+ *     versioning quirk we defend against)
+ *   - getModelFingerprint changes when model changes
+ *   - warmup() forces the load + can be called repeatedly safely
+ */
+
+import { describe, test, expect, jest } from '@jest/globals';
+import {
+  LocalEmbeddingProvider,
+  LOCAL_MODELS,
+  DEFAULT_LOCAL_MODEL,
+} from '../providers/localProvider.js';
+import { EmbeddingError, EMBEDDING_ERROR_CODES } from '../providerInterface.js';
+
+/**
+ * Build a stub pipeline that records every call and returns a
+ * Transformers.js-shape Tensor-like.
+ */
+function makeStubPipeline({ dimensions, returnShape = '2d' } = {}) {
+  const calls = [];
+  const pipe = jest.fn(async (input, options) => {
+    calls.push({ input, options });
+    const inputs = Array.isArray(input) ? input : [input];
+    const matrix = inputs.map((text, i) =>
+      // Distinct, non-zero vectors per input so order can be verified.
+      Array.from({ length: dimensions }, (_, j) => (i + 1) * (j + 1) * 0.1 + text.length * 0.001),
+    );
+    if (returnShape === '1d' && matrix.length === 1) {
+      // Simulate a Transformers.js version that returns 1-D for single input.
+      return { tolist: () => matrix[0] };
+    }
+    return { tolist: () => matrix };
+  });
+  pipe._calls = calls;
+  return pipe;
+}
+
+describe('LocalEmbeddingProvider — defaults + info', () => {
+  test('default model is nomic-embed-text-v1.5', () => {
+    const p = new LocalEmbeddingProvider();
+    const info = p.getInfo();
+    expect(info.name).toBe('local');
+    expect(info.modelId).toBe(DEFAULT_LOCAL_MODEL);
+    expect(info.dimensions).toBe(768);
+    expect(info.isLocal).toBe(true);
+    expect(info.distinguishesQueryAndDocument).toBe(true);
+  });
+
+  test('known models auto-discover their dimensions', () => {
+    const bge = new LocalEmbeddingProvider({ modelId: 'Xenova/bge-small-en-v1.5' });
+    expect(bge.getInfo().dimensions).toBe(384);
+    const mini = new LocalEmbeddingProvider({ modelId: 'Xenova/all-MiniLM-L6-v2' });
+    expect(mini.getInfo().dimensions).toBe(384);
+  });
+
+  test('unknown models default to 768 dims (safe fallback)', () => {
+    const p = new LocalEmbeddingProvider({ modelId: 'Custom/some-unknown' });
+    expect(p.getInfo().dimensions).toBe(768);
+    expect(p.getInfo().distinguishesQueryAndDocument).toBe(false);
+  });
+
+  test('LOCAL_MODELS table includes all three sanctioned models', () => {
+    expect(Object.keys(LOCAL_MODELS).sort()).toEqual([
+      'Xenova/all-MiniLM-L6-v2',
+      'Xenova/bge-small-en-v1.5',
+      'Xenova/nomic-embed-text-v1.5',
+    ]);
+  });
+
+  test('getModelFingerprint includes modelId', () => {
+    const a = new LocalEmbeddingProvider();
+    const b = new LocalEmbeddingProvider({ modelId: 'Xenova/bge-small-en-v1.5' });
+    expect(a.getModelFingerprint()).toBe('local:Xenova/nomic-embed-text-v1.5');
+    expect(b.getModelFingerprint()).toBe('local:Xenova/bge-small-en-v1.5');
+    expect(a.getModelFingerprint()).not.toBe(b.getModelFingerprint());
+  });
+});
+
+describe('LocalEmbeddingProvider — health + lazy load', () => {
+  test('health() reports not-loaded BEFORE first embed call', async () => {
+    const factory = jest.fn(async () => makeStubPipeline({ dimensions: 768 }));
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    const h = await p.health();
+    expect(h.ok).toBe(false);
+    expect(h.reason).toMatch(/not loaded/);
+    expect(factory).not.toHaveBeenCalled();   // construction is free
+  });
+
+  test('health() reports ok after model loads', async () => {
+    const factory = jest.fn(async () => makeStubPipeline({ dimensions: 768 }));
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await p.warmup();
+    expect(await p.health()).toEqual({ ok: true });
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  test('concurrent first-calls dedup the load (factory called once)', async () => {
+    const factory = jest.fn(async () => makeStubPipeline({ dimensions: 768 }));
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    // Fire 3 concurrent loads; they should all settle on the same pipeline.
+    const [a, b, c] = await Promise.all([
+      p.embedDocuments(['x']),
+      p.embedDocuments(['y']),
+      p.embedDocuments(['z']),
+    ]);
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(a).toHaveLength(1);
+    expect(b).toHaveLength(1);
+    expect(c).toHaveLength(1);
+  });
+
+  test('load failure surfaces as NOT_INITIALIZED with remediation', async () => {
+    const factory = jest.fn(async () => { throw new Error('disk full'); });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await expect(p.embedDocuments(['x'])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.NOT_INITIALIZED,
+      transient: false,
+    });
+  });
+
+  test('load failure is sticky — second call does NOT re-attempt', async () => {
+    const factory = jest.fn(async () => { throw new Error('disk full'); });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await expect(p.embedDocuments(['x'])).rejects.toThrow();
+    await expect(p.embedDocuments(['y'])).rejects.toThrow();
+    // Only one load attempt — failure caches.
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  test('factory must return a callable', async () => {
+    const factory = jest.fn(async () => 'not-callable');
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await expect(p.embedDocuments(['x'])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.NOT_INITIALIZED,
+    });
+  });
+});
+
+describe('LocalEmbeddingProvider — task prefixes', () => {
+  test('nomic applies search_query: / search_document: prefixes', async () => {
+    const pipe = makeStubPipeline({ dimensions: 768 });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: async () => pipe });
+    await p.embedDocuments(['hello world'], 'document');
+    await p.embedQuery('hello world');
+    expect(pipe._calls[0].input).toEqual(['search_document: hello world']);
+    expect(pipe._calls[1].input).toEqual(['search_query: hello world']);
+  });
+
+  test('BGE applies query prefix only — documents stay raw', async () => {
+    const pipe = makeStubPipeline({ dimensions: 384 });
+    const p = new LocalEmbeddingProvider({
+      modelId: 'Xenova/bge-small-en-v1.5',
+      pipelineFactory: async () => pipe,
+    });
+    await p.embedDocuments(['raw document'], 'document');
+    await p.embedQuery('question');
+    expect(pipe._calls[0].input).toEqual(['raw document']);
+    expect(pipe._calls[1].input).toEqual([
+      'Represent this sentence for searching relevant passages: question',
+    ]);
+  });
+
+  test('MiniLM applies no prefix in either direction', async () => {
+    const pipe = makeStubPipeline({ dimensions: 384 });
+    const p = new LocalEmbeddingProvider({
+      modelId: 'Xenova/all-MiniLM-L6-v2',
+      pipelineFactory: async () => pipe,
+    });
+    await p.embedDocuments(['a doc'], 'document');
+    await p.embedQuery('a query');
+    expect(pipe._calls[0].input).toEqual(['a doc']);
+    expect(pipe._calls[1].input).toEqual(['a query']);
+  });
+});
+
+describe('LocalEmbeddingProvider — pipeline output handling', () => {
+  test('pools mean and skips normalize (base class will normalize)', async () => {
+    const pipe = makeStubPipeline({ dimensions: 768 });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: async () => pipe });
+    await p.embedQuery('x');
+    expect(pipe._calls[0].options).toEqual({ pooling: 'mean', normalize: false });
+  });
+
+  test('1-D output (single input quirk) gets wrapped to 2-D', async () => {
+    // Simulate the Transformers.js version that flattens single-input output.
+    const pipe = makeStubPipeline({ dimensions: 768, returnShape: '1d' });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: async () => pipe });
+    const [v] = await p.embedDocuments(['just one']);
+    expect(v).toBeInstanceOf(Float32Array);
+    expect(v.length).toBe(768);
+  });
+
+  test('batches respect maxBatchSize across underlying calls', async () => {
+    const pipe = makeStubPipeline({ dimensions: 768 });
+    const p = new LocalEmbeddingProvider({
+      maxBatchSize: 2,
+      pipelineFactory: async () => pipe,
+    });
+    await p.embedDocuments(['a', 'b', 'c', 'd', 'e']);
+    expect(pipe).toHaveBeenCalledTimes(3);
+    expect(pipe._calls[0].input).toHaveLength(2);
+    expect(pipe._calls[2].input).toHaveLength(1);
+  });
+
+  test('returned vectors are L2-normalized (base-class contract)', async () => {
+    const pipe = makeStubPipeline({ dimensions: 8 });
+    const p = new LocalEmbeddingProvider({
+      modelId: 'Xenova/bge-small-en-v1.5',  // 384-dim known, but stub returns 8
+      pipelineFactory: async () => pipe,
+    });
+    // Override dims so the test isn't blocked by the 384-vs-8 mismatch.
+    p._dimensions = 8;
+    const [v] = await p.embedDocuments(['x']);
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) sum += v[i] * v[i];
+    expect(Math.sqrt(sum)).toBeCloseTo(1, 6);
+  });
+
+  test('pipeline inference error → PROVIDER_UNAVAILABLE (transient)', async () => {
+    const failingPipe = jest.fn(async () => { throw new Error('OOM'); });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: async () => failingPipe });
+    await expect(p.embedQuery('hi')).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      transient: true,
+    });
+  });
+});
+
+describe('LocalEmbeddingProvider — warmup', () => {
+  test('warmup() is idempotent', async () => {
+    const factory = jest.fn(async () => makeStubPipeline({ dimensions: 768 }));
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await p.warmup();
+    await p.warmup();
+    await p.warmup();
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  test('warmup() throws when load fails', async () => {
+    const factory = jest.fn(async () => { throw new Error('no internet'); });
+    const p = new LocalEmbeddingProvider({ pipelineFactory: factory });
+    await expect(p.warmup()).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.NOT_INITIALIZED,
+    });
+  });
+});

package/src/services/embeddings/__tests__/providerInterface.test.js

@@ -0,0 +1,209 @@
+/**
+ * Base-class contract tests for EmbeddingProvider.
+ *
+ * These tests pin the invariants every concrete provider relies on:
+ *   1. Input validation surfaces typed EmbeddingError (no raw throws).
+ *   2. Batching respects maxBatchSize and preserves order across batches.
+ *   3. Returned vectors are L2-normalized — the VectorStore depends on
+ *      this so cosine reduces to dot-product on read.
+ *   4. Provider-side dimension drift surfaces as DIMENSION_MISMATCH,
+ *      and inconsistent batch sizes as PROVIDER_UNAVAILABLE (transient).
+ *
+ * Concrete provider tests (azure, openai, local) plug into the same
+ * StubProvider pattern so we don't repeat these invariants there.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  EmbeddingProvider,
+  EmbeddingError,
+  EMBEDDING_ERROR_CODES,
+  normalizeInPlace,
+} from '../providerInterface.js';
+
+class StubProvider extends EmbeddingProvider {
+  constructor({ dimensions = 4, maxBatchSize = 2, name = 'stub' } = {}) {
+    super();
+    this._info = {
+      name,
+      modelId: 'stub-model',
+      dimensions,
+      maxBatchSize,
+      maxTokensPerText: 1000,
+      distinguishesQueryAndDocument: false,
+      isLocal: true,
+    };
+    this._calls = [];
+  }
+  getInfo() { return this._info; }
+  async _embed(texts, kind) {
+    this._calls.push({ texts: [...texts], kind });
+    // Produce distinct non-zero vectors per input so order can be verified.
+    return texts.map((_, i) =>
+      Array.from({ length: this._info.dimensions }, (_, j) => (i + 1) * (j + 1) * 0.1),
+    );
+  }
+}
+
+describe('EmbeddingProvider — base class', () => {
+  test('embedQuery rejects empty / non-string with INVALID_INPUT', async () => {
+    const p = new StubProvider();
+    for (const bad of ['', null, undefined, 42, {}]) {
+      await expect(p.embedQuery(bad)).rejects.toMatchObject({
+        code: EMBEDDING_ERROR_CODES.INVALID_INPUT,
+      });
+    }
+  });
+
+  test('embedDocuments rejects empty array / empty entries', async () => {
+    const p = new StubProvider();
+    await expect(p.embedDocuments([])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.INVALID_INPUT,
+    });
+    await expect(p.embedDocuments(['ok', ''])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.INVALID_INPUT,
+    });
+    await expect(p.embedDocuments(['ok', null])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.INVALID_INPUT,
+    });
+  });
+
+  test('embedQuery passes kind:"query" to _embed', async () => {
+    const p = new StubProvider();
+    await p.embedQuery('hello');
+    expect(p._calls).toHaveLength(1);
+    expect(p._calls[0].kind).toBe('query');
+  });
+
+  test('embedDocuments defaults kind to "document"', async () => {
+    const p = new StubProvider();
+    await p.embedDocuments(['a']);
+    expect(p._calls[0].kind).toBe('document');
+  });
+
+  test('embedDocuments forwards explicit kind', async () => {
+    const p = new StubProvider();
+    await p.embedDocuments(['a'], 'query');
+    expect(p._calls[0].kind).toBe('query');
+  });
+
+  test('batches input through _embed in chunks of maxBatchSize, preserving order', async () => {
+    const p = new StubProvider({ maxBatchSize: 2 });
+    const out = await p.embedDocuments(['a', 'b', 'c', 'd', 'e']);
+    expect(p._calls.map(c => c.texts.length)).toEqual([2, 2, 1]);
+    expect(p._calls[0].texts).toEqual(['a', 'b']);
+    expect(p._calls[1].texts).toEqual(['c', 'd']);
+    expect(p._calls[2].texts).toEqual(['e']);
+    expect(out).toHaveLength(5);
+    for (const v of out) expect(v).toBeInstanceOf(Float32Array);
+  });
+
+  test('result vectors are L2-normalized to unit length', async () => {
+    const p = new StubProvider({ dimensions: 4 });
+    const vecs = await p.embedDocuments(['x', 'y', 'z']);
+    for (const v of vecs) {
+      let sum = 0;
+      for (let i = 0; i < v.length; i++) sum += v[i] * v[i];
+      expect(Math.sqrt(sum)).toBeCloseTo(1, 6);
+    }
+  });
+
+  test('DIMENSION_MISMATCH when provider returns the wrong shape', async () => {
+    class BadDimProvider extends StubProvider {
+      async _embed(texts) { return texts.map(() => [1, 2, 3]); }
+    }
+    const p = new BadDimProvider({ dimensions: 4 });
+    await expect(p.embedDocuments(['x'])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.DIMENSION_MISMATCH,
+    });
+  });
+
+  test('PROVIDER_UNAVAILABLE (transient) when result count mismatches batch size', async () => {
+    class WrongCountProvider extends StubProvider {
+      async _embed() { return [[1, 0, 0, 0]]; }
+    }
+    const p = new WrongCountProvider({ maxBatchSize: 5 });
+    await expect(p.embedDocuments(['a', 'b'])).rejects.toMatchObject({
+      code: EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      transient: true,
+    });
+  });
+
+  test('getModelFingerprint = name:modelId by default', () => {
+    const p = new StubProvider({ name: 'azure' });
+    expect(p.getModelFingerprint()).toBe('azure:stub-model');
+  });
+
+  test('base health() returns ok:true by default', async () => {
+    const p = new StubProvider();
+    expect(await p.health()).toEqual({ ok: true });
+  });
+
+  test('subclass that does not implement getInfo() throws', () => {
+    class Incomplete extends EmbeddingProvider {}
+    expect(() => new Incomplete().getInfo()).toThrow(/getInfo/);
+  });
+
+  test('subclass that does not implement _embed() throws', async () => {
+    class Incomplete extends EmbeddingProvider {
+      getInfo() {
+        return { name: 'x', modelId: 'm', dimensions: 4, maxBatchSize: 1,
+                 maxTokensPerText: 100, distinguishesQueryAndDocument: false, isLocal: true };
+      }
+    }
+    await expect(new Incomplete().embedDocuments(['hi'])).rejects.toThrow(/_embed/);
+  });
+});
+
+describe('normalizeInPlace', () => {
+  test('3-4-5 triangle → 0.6, 0.8', () => {
+    const v = Float32Array.from([3, 4]);
+    normalizeInPlace(v);
+    expect(v[0]).toBeCloseTo(0.6, 6);
+    expect(v[1]).toBeCloseTo(0.8, 6);
+  });
+
+  test('already-normalized vector stays the same', () => {
+    const v = Float32Array.from([1, 0, 0, 0]);
+    normalizeInPlace(v);
+    expect(Array.from(v)).toEqual([1, 0, 0, 0]);
+  });
+
+  test('zero vector is left untouched (no NaN division)', () => {
+    const v = Float32Array.from([0, 0, 0]);
+    normalizeInPlace(v);
+    expect(Array.from(v)).toEqual([0, 0, 0]);
+  });
+
+  test('negative components are preserved', () => {
+    const v = Float32Array.from([-3, 4]);
+    normalizeInPlace(v);
+    expect(v[0]).toBeCloseTo(-0.6, 6);
+    expect(v[1]).toBeCloseTo(0.8, 6);
+  });
+});
+
+describe('EmbeddingError', () => {
+  test('code + provider + transient flag surface on error', () => {
+    const err = new EmbeddingError(
+      EMBEDDING_ERROR_CODES.RATE_LIMITED,
+      'too fast',
+      { provider: 'azure', transient: true },
+    );
+    expect(err.code).toBe('RATE_LIMITED');
+    expect(err.provider).toBe('azure');
+    expect(err.transient).toBe(true);
+    expect(err.name).toBe('EmbeddingError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  test('cause is preserved when supplied', () => {
+    const underlying = new Error('socket reset');
+    const err = new EmbeddingError(
+      EMBEDDING_ERROR_CODES.NETWORK_ERROR,
+      'wrapped',
+      { provider: 'openai', transient: true, cause: underlying },
+    );
+    expect(err.cause).toBe(underlying);
+  });
+});