onbuzz 4.8.3 → 4.9.1

package/src/services/embeddings/vectorStore/inMemoryJsonStore.js

@@ -0,0 +1,356 @@
+/**
+ * InMemoryJsonStore — concrete VectorStore backed by a single JSON file.
+ *
+ * Design choices:
+ *   - Vectors held in memory as Float32Array (~3 KB each at 768 dims).
+ *     At our scale (~10K vectors per agent) that's <30 MB resident.
+ *   - Cosine similarity reduces to a dot product because the base-class
+ *     normalizes every stored + queried vector. Tight loop in V8.
+ *   - Single-file persistence with atomic write (write to `.tmp`, then
+ *     fs.rename — atomic on the same filesystem). No partial reads.
+ *   - File format is human-inspectable JSON (verbose but debuggable).
+ *     The 4× size penalty vs binary is fine until we hit 100K+ vectors,
+ *     at which point sqlite-vec is the planned drop-in.
+ *   - Substring search is plain `String.includes()` on `metadata.text`
+ *     after lowercasing both sides. No regex, matches the codebase's
+ *     "native string ops" preference.
+ *   - Fingerprint/dimension drift on load: silently empties the store
+ *     (we treat the on-disk file as garbage). The orchestrator's
+ *     responsibility is to backfill from source.
+ *
+ * Concurrency: not safe for multiple writers on the same file from
+ * different processes. Loxia is single-process per agent state, so
+ * this is fine. If we ever multiprocess, switch to sqlite-vec.
+ */
+
+import fsp from 'fs/promises';
+import path from 'path';
+import { reciprocalRankFusion } from './storeInterface.js';
+
+const FILE_VERSION = 1;
+
+export class InMemoryJsonStore {
+  /**
+   * @param {object} opts
+   * @param {string} opts.filePath         - Absolute path to the .vec.json file.
+   * @param {number} opts.dimensions       - Expected vector dimensionality.
+   * @param {string} opts.modelFingerprint - From EmbeddingProvider.getModelFingerprint().
+   * @param {object} [opts.logger]
+   */
+  constructor({ filePath, dimensions, modelFingerprint, logger = null }) {
+    if (!filePath) throw new Error('InMemoryJsonStore requires filePath');
+    if (!Number.isInteger(dimensions) || dimensions <= 0) {
+      throw new Error('InMemoryJsonStore requires positive integer dimensions');
+    }
+    if (!modelFingerprint) throw new Error('InMemoryJsonStore requires modelFingerprint');
+
+    this._filePath = filePath;
+    this._dimensions = dimensions;
+    this._modelFingerprint = modelFingerprint;
+    this._logger = logger;
+
+    /** @type {Array<{id: string, vector: Float32Array, metadata: object}>} */
+    this._rows = [];
+    /** @type {Map<string, number>} id → index into _rows */
+    this._idIndex = new Map();
+    this._loaded = false;
+  }
+
+  /**
+   * Load from disk. Idempotent; safe to call repeatedly. If the file
+   * doesn't exist, or its fingerprint / dimensions don't match the
+   * constructor args, the store starts empty (caller re-embeds).
+   */
+  async load() {
+    if (this._loaded) return;
+    this._loaded = true;
+
+    let raw;
+    try {
+      raw = await fsp.readFile(this._filePath, 'utf8');
+    } catch (err) {
+      if (err?.code === 'ENOENT') return; // first run, file doesn't exist
+      this._logger?.warn?.('[vectorStore] failed to read store; starting empty', { path: this._filePath, err: err.message });
+      return;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      this._logger?.warn?.('[vectorStore] corrupt JSON; starting empty', { path: this._filePath, err: err.message });
+      return;
+    }
+
+    if (parsed?.version !== FILE_VERSION) {
+      this._logger?.info?.('[vectorStore] file version mismatch; starting empty', {
+        path: this._filePath, found: parsed?.version, expected: FILE_VERSION,
+      });
+      return;
+    }
+    if (parsed.dimensions !== this._dimensions) {
+      this._logger?.info?.('[vectorStore] dimension mismatch; starting empty (re-embed required)', {
+        path: this._filePath, fileDims: parsed.dimensions, expectedDims: this._dimensions,
+      });
+      return;
+    }
+    if (parsed.modelFingerprint !== this._modelFingerprint) {
+      this._logger?.info?.('[vectorStore] fingerprint mismatch; starting empty (re-embed required)', {
+        path: this._filePath, fileFp: parsed.modelFingerprint, expectedFp: this._modelFingerprint,
+      });
+      return;
+    }
+    if (!Array.isArray(parsed.rows)) return;
+
+    for (const r of parsed.rows) {
+      if (!r || typeof r.id !== 'string' || !Array.isArray(r.vector)) continue;
+      if (r.vector.length !== this._dimensions) continue;
+      this._rows.push({
+        id: r.id,
+        vector: Float32Array.from(r.vector),
+        metadata: r.metadata || {},
+      });
+      this._idIndex.set(r.id, this._rows.length - 1);
+    }
+  }
+
+  async stats() {
+    let newestTs = null;
+    for (const r of this._rows) {
+      const ts = r.metadata?.createdAt;
+      if (typeof ts === 'string' && (!newestTs || ts > newestTs)) {
+        newestTs = ts;
+      }
+    }
+    return {
+      count: this._rows.length,
+      dimensions: this._dimensions,
+      modelFingerprint: this._modelFingerprint,
+      lastIndexedAt: newestTs,
+    };
+  }
+
+  async upsert(id, vector, metadata = {}) {
+    this._assertLoaded();
+    this._validateVector(vector);
+    if (typeof id !== 'string' || !id) throw new Error('upsert: id must be a non-empty string');
+
+    const existing = this._idIndex.get(id);
+    if (existing !== undefined) {
+      this._rows[existing] = { id, vector, metadata };
+    } else {
+      this._rows.push({ id, vector, metadata });
+      this._idIndex.set(id, this._rows.length - 1);
+    }
+    await this._flush();
+  }
+
+  async upsertBatch(rows) {
+    this._assertLoaded();
+    if (!Array.isArray(rows)) throw new Error('upsertBatch: rows must be an array');
+    for (const r of rows) {
+      this._validateVector(r?.vector);
+      if (typeof r?.id !== 'string' || !r.id) throw new Error('upsertBatch: each row needs an id');
+      const existing = this._idIndex.get(r.id);
+      if (existing !== undefined) {
+        this._rows[existing] = { id: r.id, vector: r.vector, metadata: r.metadata || {} };
+      } else {
+        this._rows.push({ id: r.id, vector: r.vector, metadata: r.metadata || {} });
+        this._idIndex.set(r.id, this._rows.length - 1);
+      }
+    }
+    await this._flush();
+  }
+
+  async delete(id) {
+    this._assertLoaded();
+    const idx = this._idIndex.get(id);
+    if (idx === undefined) return;
+    // Swap-remove for O(1). Update the moved row's index.
+    const last = this._rows.length - 1;
+    if (idx !== last) {
+      this._rows[idx] = this._rows[last];
+      this._idIndex.set(this._rows[idx].id, idx);
+    }
+    this._rows.pop();
+    this._idIndex.delete(id);
+    await this._flush();
+  }
+
+  /**
+   * Delete every row whose metadata satisfies `predicate`. Used when a
+   * single source object (e.g. a conversation message) produced multiple
+   * chunks under the convention `${sourceId}#${chunkIndex}` — calling
+   * `delete()` per chunk would require N round-trips and N flushes.
+   *
+   * Returns the number of rows removed. One atomic flush at the end.
+   *
+   * @param {(metadata: object) => boolean} predicate
+   * @returns {Promise<number>}
+   */
+  async deleteWhere(predicate) {
+    this._assertLoaded();
+    if (typeof predicate !== 'function') {
+      throw new Error('deleteWhere: predicate must be a function');
+    }
+    let removed = 0;
+    // Walk from the tail so swap-remove indices stay valid as we splice.
+    for (let i = this._rows.length - 1; i >= 0; i--) {
+      const row = this._rows[i];
+      let match = false;
+      try { match = !!predicate(row.metadata); } catch { match = false; }
+      if (!match) continue;
+      const last = this._rows.length - 1;
+      if (i !== last) {
+        this._rows[i] = this._rows[last];
+        this._idIndex.set(this._rows[i].id, i);
+      }
+      this._rows.pop();
+      this._idIndex.delete(row.id);
+      removed++;
+    }
+    if (removed > 0) await this._flush();
+    return removed;
+  }
+
+  /**
+   * Cosine query. Vectors are normalized, so cosine = dot product.
+   * Linear scan — fine up to ~100K rows. For larger corpora we swap
+   * to sqlite-vec (HNSW) without changing this interface.
+   *
+   * @param {Float32Array} queryVector
+   * @param {object} [opts]
+   * @param {number} [opts.topK=10]
+   * @param {(metadata: object) => boolean} [opts.filter]
+   * @param {(baseScore: number, metadata: object) => number} [opts.scoring]
+   *        Optional per-row score adjuster — used by the multi-signal
+   *        ranking layer (recency + access boosts). See
+   *        `vectorStore/scoring.js`. Identity when omitted.
+   */
+  async query(queryVector, { topK = 10, filter = null, scoring = null } = {}) {
+    this._assertLoaded();
+    this._validateVector(queryVector);
+    const adjust = typeof scoring === 'function' ? scoring : null;
+
+    const scored = [];
+    for (const row of this._rows) {
+      if (filter && !filter(row.metadata)) continue;
+      const base = dot(queryVector, row.vector);
+      const score = adjust ? adjust(base, row.metadata) : base;
+      scored.push({ id: row.id, score, metadata: row.metadata });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+
+  /**
+   * Hybrid query: rank-fuse semantic results with substring matches
+   * over `metadata.text`. RRF is used because raw scores live on
+   * different scales (cosine vs boolean) and RRF only needs ranks.
+   *
+   * @param {Float32Array} queryVector
+   * @param {string}       queryText  - For substring matching.
+   * @param {object}       [opts]
+   * @param {number}       [opts.topK=10]
+   * @param {Function}     [opts.filter] - Same shape as query().
+   * @returns {Promise<Array<{id, score, metadata}>>}
+   */
+  async hybridQuery(queryVector, queryText, { topK = 10, filter = null, scoring = null } = {}) {
+    this._assertLoaded();
+    // The semantic candidate set is the one that benefits from scoring
+    // adjustments. The substring path is rank-only, so reweighting
+    // wouldn't affect RRF anyway.
+    const semantic = await this.query(queryVector, { topK: topK * 4, filter, scoring });
+    const substring = await this._substringMatches(queryText, { topK: topK * 4, filter });
+    const fused = reciprocalRankFusion([semantic, substring], { topK });
+    // Hydrate ids back to full rows.
+    return fused.map(({ id, score }) => {
+      const idx = this._idIndex.get(id);
+      const row = idx !== undefined ? this._rows[idx] : null;
+      return { id, score, metadata: row?.metadata || {} };
+    });
+  }
+
+  /** @private */
+  async _substringMatches(queryText, { topK, filter }) {
+    if (typeof queryText !== 'string' || !queryText) return [];
+    const needle = queryText.toLowerCase();
+    const matches = [];
+    for (const row of this._rows) {
+      if (filter && !filter(row.metadata)) continue;
+      const haystack = String(row.metadata?.text || '').toLowerCase();
+      if (haystack.length === 0) continue;
+      const idx = haystack.indexOf(needle);
+      if (idx === -1) continue;
+      // Score = inverse position (earlier matches rank higher). Used only
+      // for ordering inside this list — final fusion ignores raw scores.
+      matches.push({ id: row.id, score: 1 / (1 + idx) });
+    }
+    matches.sort((a, b) => b.score - a.score);
+    return matches.slice(0, topK);
+  }
+
+  async drop() {
+    this._assertLoaded();
+    this._rows = [];
+    this._idIndex.clear();
+    try {
+      await fsp.unlink(this._filePath);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') {
+        this._logger?.warn?.('[vectorStore] drop(): could not unlink file', { path: this._filePath, err: err.message });
+      }
+    }
+  }
+
+  /**
+   * Force a flush. Public because callers occasionally want to ensure
+   * persistence before a critical handoff (e.g. shutdown).
+   */
+  async flush() {
+    await this._flush();
+  }
+
+  /** @private */
+  _assertLoaded() {
+    if (!this._loaded) {
+      throw new Error('VectorStore not loaded — call await store.load() first');
+    }
+  }
+
+  /** @private */
+  _validateVector(v) {
+    if (!(v instanceof Float32Array)) {
+      throw new Error('vector must be a Float32Array');
+    }
+    if (v.length !== this._dimensions) {
+      throw new Error(`vector has wrong dimensions (got ${v.length}, expected ${this._dimensions})`);
+    }
+  }
+
+  /** @private */
+  async _flush() {
+    const payload = {
+      version: FILE_VERSION,
+      dimensions: this._dimensions,
+      modelFingerprint: this._modelFingerprint,
+      savedAt: new Date().toISOString(),
+      rows: this._rows.map(r => ({
+        id: r.id,
+        vector: Array.from(r.vector),  // JSON can't hold typed arrays
+        metadata: r.metadata,
+      })),
+    };
+    const tmpPath = `${this._filePath}.tmp`;
+    await fsp.mkdir(path.dirname(this._filePath), { recursive: true });
+    await fsp.writeFile(tmpPath, JSON.stringify(payload));
+    await fsp.rename(tmpPath, this._filePath);
+  }
+}
+
+/** Dot product over two equal-length Float32Arrays. Hot path — no allocation. */
+function dot(a, b) {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}

package/src/services/embeddings/vectorStore/scoring.js

@@ -0,0 +1,128 @@
+/**
+ * scoring.js — multiplicative score adjusters for VectorStore.query().
+ *
+ * Why this exists: pure cosine similarity is "topical proximity" but
+ * misses signals that turn out to matter a lot in production —
+ * particularly recency (a 6-day-old memory is usually more relevant
+ * than an 18-month-old one with the same cosine) and access frequency
+ * (memories the agent has called up before tend to be useful again).
+ *
+ * Design (lit-aligned, 2025–2026 consensus):
+ *   - SIGMOID recency with a 1-week half-life. This is what production
+ *     systems (Mem0, ChatGPT memory) have converged on. Old exponential
+ *     decays are too aggressive on medium-old items; sigmoid keeps
+ *     "two weeks old" close to neutral, "two months old" softly damped.
+ *   - LOG access boost: 1 + weight * ln(1 + accessCount). Saturating so
+ *     a single hot memory doesn't dominate everything.
+ *   - Multiplicative composition, clamped to a sane range so signals
+ *     can't blow up the score or drive it to zero. Range
+ *     [minFactor, maxFactor] = [0.3, 1.5] in production-tested defaults.
+ *
+ * Backwards compatible: `makeScoringFn()` with no args returns the
+ * identity scorer. Indexers opt in to recency / access boost per surface.
+ *
+ * Citations + numbers come from the literature review above:
+ *   - Mem0 (2026): "production setup weights semantic similarity at 60%,
+ *     recency at 10%, access frequency at 10%"
+ *   - Mem0: "168-hour (1-week) half-life sigmoid"
+ *   - Mem0: "access boost = 1 + 0.1 × ln(1 + access_count_30d)"
+ *   - Mem0: "scaling factor between 0.3× and 1.5×"
+ *   - FadeMem (arXiv 2601.18642): biologically-inspired decay is a
+ *     soft demotion, not deletion — we treat it that way too.
+ */
+
+/**
+ * Build a scoring function that adjusts base cosine scores.
+ *
+ * @param {object} [opts]
+ * @param {object|boolean} [opts.recency]  Recency boost config. Pass `true` for
+ *        defaults, an object to customise, or omit to disable.
+ *        Defaults: { halfLifeDays: 7, minFactor: 0.3, maxFactor: 1.5 }
+ * @param {object|boolean} [opts.access]   Access-frequency boost config.
+ *        Defaults: { weight: 0.1, maxFactor: 1.5 }
+ *        Reads `metadata.accessCount`; defaults to 0 if absent.
+ * @param {number} [opts.now]              Override Date.now() for deterministic tests.
+ * @returns {(baseScore: number, metadata: object) => number}
+ */
+export function makeScoringFn(opts = {}) {
+  const recencyOpts = _normalizeRecency(opts.recency);
+  const accessOpts = _normalizeAccess(opts.access);
+  const nowMs = Number.isFinite(opts.now) ? opts.now : Date.now();
+
+  // Identity if nothing's enabled — keeps `scoring` a no-cost option.
+  if (!recencyOpts && !accessOpts) {
+    return (baseScore) => baseScore;
+  }
+
+  return function score(baseScore, metadata) {
+    if (!metadata) return baseScore;
+    let factor = 1;
+
+    if (recencyOpts) {
+      const tsRaw = metadata.updatedAt || metadata.createdAt || metadata.indexedAt;
+      if (tsRaw) {
+        const ts = Date.parse(tsRaw);
+        if (Number.isFinite(ts)) {
+          const ageDays = Math.max(0, (nowMs - ts) / DAY_MS);
+          factor *= sigmoidRecencyFactor(ageDays, recencyOpts);
+        }
+      }
+    }
+
+    if (accessOpts) {
+      const c = Number(metadata.accessCount) || 0;
+      if (c > 0) {
+        const boost = 1 + accessOpts.weight * Math.log(1 + c);
+        factor *= Math.min(boost, accessOpts.maxFactor);
+      }
+    }
+
+    return baseScore * factor;
+  };
+}
+
+/**
+ * Sigmoid recency factor mapped to [minFactor, maxFactor].
+ *
+ * Shape:
+ *   age = 0           → ~maxFactor   (very recent → strongly boost)
+ *   age = halfLife    → midpoint     (neutral)
+ *   age = 2*halfLife  → ~minFactor   (old → strongly damp)
+ *   age → ∞           →  minFactor
+ *
+ * The sharpness of the transition is controlled by `halfLife/4` so the
+ * curve isn't too gentle. Exported for tests.
+ *
+ * @param {number} ageDays
+ * @param {{halfLifeDays:number,minFactor:number,maxFactor:number}} opts
+ * @returns {number}
+ */
+export function sigmoidRecencyFactor(ageDays, opts) {
+  const k = opts.halfLifeDays;
+  const scale = Math.max(0.5, k / 4);
+  // s ∈ (0,1); 1 when very recent, 0.5 at half-life, ~0 when very old.
+  const u = (k - ageDays) / scale;
+  const s = 1 / (1 + Math.exp(-u));
+  return opts.minFactor + (opts.maxFactor - opts.minFactor) * s;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function _normalizeRecency(input) {
+  if (!input) return null;
+  const r = input === true ? {} : input;
+  return {
+    halfLifeDays: Number.isFinite(r.halfLifeDays) && r.halfLifeDays > 0 ? r.halfLifeDays : 7,
+    minFactor:    Number.isFinite(r.minFactor) ? r.minFactor : 0.3,
+    maxFactor:    Number.isFinite(r.maxFactor) ? r.maxFactor : 1.5,
+  };
+}
+
+function _normalizeAccess(input) {
+  if (!input) return null;
+  const a = input === true ? {} : input;
+  return {
+    weight:    Number.isFinite(a.weight) ? a.weight : 0.1,
+    maxFactor: Number.isFinite(a.maxFactor) ? a.maxFactor : 1.5,
+  };
+}

package/src/services/embeddings/vectorStore/storeContractTests.js

@@ -0,0 +1,179 @@
+/**
+ * Shared VectorStore conformance tests.
+ *
+ * Every concrete VectorStore implementation (today: inMemoryJsonStore;
+ * tomorrow: sqliteVecStore) re-runs this suite to prove it meets the
+ * contract defined in `storeInterface.js`. The concrete store's test
+ * file does:
+ *
+ *     describe('inMemoryJsonStore conforms to VectorStore', () => {
+ *       runStoreContractTests((opts) => new InMemoryJsonStore(opts));
+ *     });
+ *
+ * Keeping this in a separate file (not in `storeInterface.js`) means
+ * production callers of the interface — which only need the RRF helper
+ * and JSDoc types — don't transitively import `@jest/globals`.
+ *
+ * `makeStore` is a factory taking `{ filePath, dimensions, modelFingerprint }`
+ * and returning a fresh store. The helper supplies temp file paths so
+ * stores can be exercised against real disk.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import os from 'os';
+import fsp from 'fs/promises';
+import path from 'path';
+
+export function runStoreContractTests(makeStore) {
+  describe('VectorStore contract', () => {
+    let tmpDir, filePath, store;
+
+    beforeEach(async () => {
+      tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-vec-test-'));
+      filePath = path.join(tmpDir, 'store.vec.json');
+      store = makeStore({
+        filePath,
+        dimensions: 4,
+        modelFingerprint: 'test:fp-v1',
+      });
+      await store.load();
+    });
+
+    afterEach(async () => {
+      await fsp.rm(tmpDir, { recursive: true, force: true });
+    });
+
+    test('starts empty', async () => {
+      const s = await store.stats();
+      expect(s.count).toBe(0);
+      expect(s.dimensions).toBe(4);
+      expect(s.modelFingerprint).toBe('test:fp-v1');
+    });
+
+    test('upsert + query: returns the inserted vector as top hit', async () => {
+      const v = Float32Array.from([1, 0, 0, 0]);
+      await store.upsert('a', v, { text: 'apple' });
+      const hits = await store.query(v, { topK: 5 });
+      expect(hits[0]).toMatchObject({ id: 'a' });
+      expect(hits[0].score).toBeCloseTo(1, 6);
+      expect(hits[0].metadata.text).toBe('apple');
+    });
+
+    test('upsert overwrites existing id', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), { text: 'v1' });
+      await store.upsert('a', Float32Array.from([0, 1, 0, 0]), { text: 'v2' });
+      const s = await store.stats();
+      expect(s.count).toBe(1);
+      const hits = await store.query(Float32Array.from([0, 1, 0, 0]), { topK: 1 });
+      expect(hits[0].metadata.text).toBe('v2');
+    });
+
+    test('delete removes the row', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), { text: 'a' });
+      await store.upsert('b', Float32Array.from([0, 1, 0, 0]), { text: 'b' });
+      expect((await store.stats()).count).toBe(2);
+      await store.delete('a');
+      expect((await store.stats()).count).toBe(1);
+      const hits = await store.query(Float32Array.from([1, 0, 0, 0]), { topK: 5 });
+      expect(hits.map(h => h.id)).not.toContain('a');
+    });
+
+    test('query ranks by cosine similarity (desc)', async () => {
+      await store.upsert('north', Float32Array.from([0, 1, 0, 0]), {});
+      await store.upsert('east',  Float32Array.from([1, 0, 0, 0]), {});
+      await store.upsert('south', Float32Array.from([0, -1, 0, 0]), {});
+      const hits = await store.query(Float32Array.from([0, 1, 0, 0]), { topK: 3 });
+      expect(hits.map(h => h.id)).toEqual(['north', 'east', 'south']);
+      expect(hits[0].score).toBeCloseTo(1, 5);
+      expect(hits[2].score).toBeCloseTo(-1, 5);
+    });
+
+    test('query respects topK', async () => {
+      await store.upsertBatch([
+        { id: 'a', vector: Float32Array.from([1, 0, 0, 0]), metadata: {} },
+        { id: 'b', vector: Float32Array.from([0, 1, 0, 0]), metadata: {} },
+        { id: 'c', vector: Float32Array.from([0, 0, 1, 0]), metadata: {} },
+      ]);
+      const hits = await store.query(Float32Array.from([1, 0, 0, 0]), { topK: 2 });
+      expect(hits).toHaveLength(2);
+    });
+
+    test('query applies metadata filter (function form)', async () => {
+      await store.upsertBatch([
+        { id: 'a', vector: Float32Array.from([1, 0, 0, 0]), metadata: { agentId: 'A' } },
+        { id: 'b', vector: Float32Array.from([0.9, 0.1, 0, 0]), metadata: { agentId: 'B' } },
+      ]);
+      const hits = await store.query(Float32Array.from([1, 0, 0, 0]), {
+        topK: 5,
+        filter: m => m.agentId === 'A',
+      });
+      expect(hits.map(h => h.id)).toEqual(['a']);
+    });
+
+    test('persists across reload', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), { text: 'first' });
+      const fresh = makeStore({ filePath, dimensions: 4, modelFingerprint: 'test:fp-v1' });
+      await fresh.load();
+      const hits = await fresh.query(Float32Array.from([1, 0, 0, 0]), { topK: 1 });
+      expect(hits[0]).toMatchObject({ id: 'a' });
+      expect(hits[0].metadata.text).toBe('first');
+    });
+
+    test('drop() empties the store + clears disk', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), {});
+      await store.drop();
+      expect((await store.stats()).count).toBe(0);
+      const fresh = makeStore({ filePath, dimensions: 4, modelFingerprint: 'test:fp-v1' });
+      await fresh.load();
+      expect((await fresh.stats()).count).toBe(0);
+    });
+
+    test('rejects load when stored fingerprint differs (forces re-embed)', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), {});
+      // Open the same file with a different fingerprint — store should
+      // refuse and present an empty corpus (caller re-embeds from source).
+      const swapped = makeStore({ filePath, dimensions: 4, modelFingerprint: 'test:fp-v2' });
+      await swapped.load();
+      expect((await swapped.stats()).count).toBe(0);
+    });
+
+    test('rejects load when stored dimensions differ', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), {});
+      const wrongDim = makeStore({ filePath, dimensions: 8, modelFingerprint: 'test:fp-v1' });
+      await wrongDim.load();
+      expect((await wrongDim.stats()).count).toBe(0);
+    });
+
+    test('rejects upsert with wrong-dim vector', async () => {
+      await expect(
+        store.upsert('a', Float32Array.from([1, 0]), {}),
+      ).rejects.toThrow(/dim/i);
+    });
+
+    test('stats.lastIndexedAt tracks the newest createdAt in metadata', async () => {
+      await store.upsert('a', Float32Array.from([1, 0, 0, 0]), { createdAt: '2026-01-01T00:00:00Z' });
+      await store.upsert('b', Float32Array.from([0, 1, 0, 0]), { createdAt: '2026-05-01T00:00:00Z' });
+      const s = await store.stats();
+      expect(s.lastIndexedAt).toBe('2026-05-01T00:00:00Z');
+    });
+
+    test('hybridQuery merges semantic + substring rankings via RRF', async () => {
+      await store.upsertBatch([
+        // 'a' loses on semantic (orthogonal to query) but wins on substring.
+        { id: 'a', vector: Float32Array.from([0, 0, 1, 0]), metadata: { text: 'telegram dedup floods' } },
+        // 'b' wins on semantic but no substring overlap.
+        { id: 'b', vector: Float32Array.from([1, 0, 0, 0]), metadata: { text: 'completely unrelated content' } },
+        // 'c' is mediocre on both.
+        { id: 'c', vector: Float32Array.from([0.7, 0, 0.7, 0]), metadata: { text: 'telegram error' } },
+      ]);
+      const queryVec = Float32Array.from([1, 0, 0, 0]);
+      const hits = await store.hybridQuery(queryVec, 'telegram', { topK: 3 });
+      // Hybrid: 'c' (both signals) typically wins, 'a' and 'b' close behind.
+      // We don't pin exact order — just that 'c' beats one of the unbalanced
+      // candidates, validating fusion is doing something.
+      const ids = hits.map(h => h.id);
+      expect(ids).toContain('c');
+      expect(ids.indexOf('c')).toBeLessThan(2);  // c is in top-2
+    });
+  });
+}