onbuzz 5.0.2 → 5.1.0

package/src/services/embeddings/indexers/__tests__/documentIndexer.test.js

@@ -0,0 +1,211 @@
+/**
+ * Tests for DocumentIndexer (Stage 2 of web-content offload). Uses the REAL
+ * InMemoryJsonStore (the actual cosine/hybrid ranking engine) plus a fake
+ * embedding service that returns deterministic basis vectors, so search
+ * ranking is asserted against real machinery. Error branches use stub stores
+ * / throwing services.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import { DocumentIndexer } from '../documentIndexer.js';
+import { InMemoryJsonStore } from '../../vectorStore/inMemoryJsonStore.js';
+
+const AGENT = 'agent-doc-1';
+
+// Deterministic 3-dim embedding (Float32Array, as the real service returns):
+// alpha→x axis, beta→y axis, else→z axis.
+function vecFor(text) {
+  const t = String(text).toLowerCase();
+  if (t.includes('alpha')) return Float32Array.from([1, 0, 0]);
+  if (t.includes('beta')) return Float32Array.from([0, 1, 0]);
+  return Float32Array.from([0, 0, 1]);
+}
+
+let tmp;
+let store;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'docidx-'));
+  store = new InMemoryJsonStore({
+    filePath: path.join(tmp, 'documents.vec.json'),
+    dimensions: 3,
+    modelFingerprint: 'test:dim3',
+  });
+  await store.load();
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+function makeSvc(over = {}) {
+  return {
+    isEnabled: over.enabled ?? true,
+    embedDocuments: over.embedDocuments || (async (texts) => texts.map(vecFor)),
+    embedQuery: over.embedQuery || (async (q) => vecFor(q)),
+    getStore: over.getStore || (async () => store),
+  };
+}
+
+function makeIndexer(over = {}, indexerOpts = {}) {
+  return new DocumentIndexer({ embeddingService: makeSvc(over), now: () => '2026-06-17T00:00:00.000Z', ...indexerOpts });
+}
+
+// ── isEnabled ───────────────────────────────────────────────────────────
+test('isEnabled mirrors the embedding service', () => {
+  expect(makeIndexer().isEnabled).toBe(true);
+  expect(makeIndexer({ enabled: false }).isEnabled).toBe(false);
+});
+
+// ── indexDocument ───────────────────────────────────────────────────────
+describe('indexDocument', () => {
+  test('disabled service → reason disabled', async () => {
+    const r = await makeIndexer({ enabled: false }).indexDocument(AGENT, { docId: 'doc-1', content: 'alpha' });
+    expect(r).toEqual({ indexed: false, reason: 'disabled' });
+  });
+
+  test('invalid input → reason invalid-input', async () => {
+    const idx = makeIndexer();
+    expect((await idx.indexDocument(AGENT, { docId: '', content: 'a' })).reason).toBe('invalid-input');
+    expect((await idx.indexDocument(AGENT, { docId: 'd', content: '' })).reason).toBe('invalid-input');
+    expect((await idx.indexDocument('', { docId: 'd', content: 'a' })).reason).toBe('invalid-input');
+    expect((await idx.indexDocument(AGENT, { docId: 'd', content: 123 })).reason).toBe('invalid-input');
+    expect((await idx.indexDocument(AGENT)).reason).toBe('invalid-input'); // no doc object (default param)
+  });
+
+  test('indexes chunks and records line metadata', async () => {
+    const content = 'alpha line one\nalpha line two\nalpha line three\nalpha line four';
+    const idx = makeIndexer({}, { chunkMaxChars: 20, chunkOverlapChars: 5 });
+    const r = await idx.indexDocument(AGENT, { docId: 'doc-1', source: 'https://x/a', title: 'A', content });
+    expect(r.indexed).toBe(true);
+    expect(r.chunks).toBeGreaterThan(1);
+
+    const { hits } = await idx.search(AGENT, 'alpha', { topK: 50, hybrid: false, boost: false });
+    expect(hits.length).toBe(r.chunks);
+    // Some chunk starts beyond line 1, and every hit has a sane line range.
+    expect(hits.some((h) => h.lineStart > 1)).toBe(true);
+    for (const h of hits) {
+      expect(h.lineEnd).toBeGreaterThanOrEqual(h.lineStart);
+      expect(h.docId).toBe('doc-1');
+      expect(h.source).toBe('https://x/a');
+    }
+  });
+
+  test('re-indexing a shrunk doc drops orphan tail chunks', async () => {
+    // chunkText clamps maxChars to a 50-char floor, so big content must
+    // exceed that to split into multiple chunks.
+    const idx = makeIndexer({}, { chunkMaxChars: 50, chunkOverlapChars: 5 });
+    const bigContent = Array.from({ length: 8 }, (_, i) => `alpha line number ${i} with some words`).join('\n');
+    const big = await idx.indexDocument(AGENT, { docId: 'doc-1', content: bigContent });
+    expect(big.chunks).toBeGreaterThan(1);
+    const small = await idx.indexDocument(AGENT, { docId: 'doc-1', content: 'alpha' });
+    expect(small.chunks).toBe(1);
+    const { hits } = await idx.search(AGENT, 'alpha', { topK: 50, hybrid: false, boost: false, docId: 'doc-1' });
+    expect(hits.length).toBe(1); // old chunks gone
+  });
+
+  test('embed failure → reason error', async () => {
+    const idx = makeIndexer({ embedDocuments: async () => { throw new Error('embed boom'); } });
+    const r = await idx.indexDocument(AGENT, { docId: 'doc-1', content: 'alpha' });
+    expect(r.reason).toBe('error');
+    expect(r.error).toBe('embed boom');
+  });
+
+  test('store upsert failure → reason error', async () => {
+    const badStore = { deleteWhere: async () => 0, upsertBatch: async () => { throw new Error('upsert boom'); } };
+    const idx = makeIndexer({ getStore: async () => badStore });
+    const r = await idx.indexDocument(AGENT, { docId: 'doc-1', content: 'alpha' });
+    expect(r.reason).toBe('error');
+    expect(r.error).toBe('upsert boom');
+  });
+});
+
+// ── removeDocument ──────────────────────────────────────────────────────
+describe('removeDocument', () => {
+  test('removes all chunks for a doc', async () => {
+    const idx = makeIndexer();
+    await idx.indexDocument(AGENT, { docId: 'doc-1', content: 'alpha alpha' });
+    const r = await idx.removeDocument(AGENT, 'doc-1');
+    expect(r.ok).toBe(true);
+    expect(r.removed).toBeGreaterThan(0);
+    const { hits } = await idx.search(AGENT, 'alpha', { topK: 10, hybrid: false, boost: false });
+    expect(hits.length).toBe(0);
+  });
+
+  test('disabled / invalid-input / error branches', async () => {
+    expect((await makeIndexer({ enabled: false }).removeDocument(AGENT, 'd')).reason).toBe('disabled');
+    expect((await makeIndexer().removeDocument(AGENT, '')).reason).toBe('invalid-input');
+    const badStore = { deleteWhere: async () => { throw new Error('del boom'); } };
+    const r = await makeIndexer({ getStore: async () => badStore }).removeDocument(AGENT, 'doc-1');
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe('del boom');
+  });
+});
+
+// ── search ──────────────────────────────────────────────────────────────
+describe('search', () => {
+  async function seed(idx) {
+    await idx.indexDocument(AGENT, { docId: 'doc-alpha', source: 'https://x/alpha', content: 'alpha alpha alpha' });
+    await idx.indexDocument(AGENT, { docId: 'doc-beta', source: 'https://x/beta', content: 'beta beta beta' });
+  }
+
+  test('ranks the semantically-closest doc first (vector, no boost)', async () => {
+    const idx = makeIndexer();
+    await seed(idx);
+    const { enabled, hits } = await idx.search(AGENT, 'find me alpha things', { hybrid: false, boost: false });
+    expect(enabled).toBe(true);
+    expect(hits[0].docId).toBe('doc-alpha');
+  });
+
+  test('docId filter restricts to one document', async () => {
+    const idx = makeIndexer();
+    await seed(idx);
+    const { hits } = await idx.search(AGENT, 'alpha', { hybrid: false, boost: false, docId: 'doc-beta' });
+    expect(hits.length).toBeGreaterThan(0);
+    expect(hits.every((h) => h.docId === 'doc-beta')).toBe(true);
+  });
+
+  test('hybrid + boost path returns results', async () => {
+    const idx = makeIndexer();
+    await seed(idx);
+    const { hits } = await idx.search(AGENT, 'alpha', { hybrid: true, boost: true });
+    expect(hits.length).toBeGreaterThan(0);
+  });
+
+  test('disabled → enabled:false', async () => {
+    const { enabled, hits } = await makeIndexer({ enabled: false }).search(AGENT, 'alpha');
+    expect(enabled).toBe(false);
+    expect(hits).toEqual([]);
+  });
+
+  test('empty / whitespace query / missing agent → no hits', async () => {
+    const idx = makeIndexer();
+    await seed(idx);
+    expect((await idx.search(AGENT, '')).hits).toEqual([]);
+    expect((await idx.search(AGENT, '   ')).hits).toEqual([]);
+    expect((await idx.search('', 'alpha')).hits).toEqual([]);
+  });
+
+  test('embedQuery failure → error field, empty hits', async () => {
+    const idx = makeIndexer({ embedQuery: async () => { throw new Error('q boom'); } });
+    const r = await idx.search(AGENT, 'alpha');
+    expect(r.error).toBe('q boom');
+    expect(r.hits).toEqual([]);
+  });
+
+  test('sparse metadata rows resolve via defensive fallbacks', async () => {
+    // Row with ONLY docId — source/title/chunkIndex/lineStart/lineEnd/text absent.
+    await store.upsertBatch([{ id: 'doc-x#0', vector: vecFor('alpha'), metadata: { docId: 'doc-x' } }]);
+    const idx = makeIndexer();
+    const { hits } = await idx.search(AGENT, 'alpha', { hybrid: false, boost: false });
+    const hit = hits.find((h) => h.docId === 'doc-x');
+    expect(hit).toMatchObject({ docId: 'doc-x', source: '', title: '', chunkIndex: 0, lineStart: 1, lineEnd: 1, text: '' });
+  });
+});
+
+test('uses a default timestamp clock when none injected', async () => {
+  const idx = new DocumentIndexer({ embeddingService: makeSvc() });
+  const r = await idx.indexDocument(AGENT, { docId: 'doc-1', content: 'alpha content here' });
+  expect(r.indexed).toBe(true);
+});

package/src/services/embeddings/indexers/__tests__/memoryIndexer.test.js

@@ -68,6 +68,7 @@ function makeIndexer({ tmpDir, enabled = true } = {}) {
   const apiKeyManager = { getEmbeddingApiKey: jest.fn(() => 'stub-key') };
   if (!enabled) {
     const svc = new EmbeddingService({
+      config: { provider: 'disabled' },
       apiKeyManager,
       baseUrl: 'https://x',
       stateDir: tmpDir,

package/src/services/embeddings/indexers/__tests__/reminisceIndexer.test.js

@@ -61,6 +61,7 @@ function makeIndexer({ tmpDir, enabled = true, chunkMaxChars, chunkOverlapChars
   const apiKeyManager = { getEmbeddingApiKey: jest.fn(() => 'stub-key') };
   if (!enabled) {
     const svc = new EmbeddingService({
+      config: { provider: 'disabled' },
       apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir,
     });
     return { indexer: new ReminisceIndexer({ embeddingService: svc, chunkMaxChars, chunkOverlapChars }), svc };

package/src/services/embeddings/indexers/__tests__/skillsIndexer.test.js

@@ -44,7 +44,7 @@ class StubProvider extends EmbeddingProvider {
 function makeIndexer({ tmpDir, enabled = true } = {}) {
   const apiKeyManager = { getEmbeddingApiKey: () => 'k' };
   if (!enabled) {
-    const svc = new EmbeddingService({ apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir });
+    const svc = new EmbeddingService({ config: { provider: 'disabled' }, apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir });
     return { indexer: new SkillsIndexer({ embeddingService: svc }), svc };
   }
   const svc = new EmbeddingService({

package/src/services/embeddings/indexers/__tests__/taskIndexer.test.js

@@ -44,7 +44,7 @@ class StubProvider extends EmbeddingProvider {
 function makeIndexer({ tmpDir, enabled = true } = {}) {
   const apiKeyManager = { getEmbeddingApiKey: () => 'k' };
   if (!enabled) {
-    const svc = new EmbeddingService({ apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir });
+    const svc = new EmbeddingService({ config: { provider: 'disabled' }, apiKeyManager, baseUrl: 'https://x', stateDir: tmpDir });
     return { indexer: new TaskIndexer({ embeddingService: svc }), svc };
   }
   const svc = new EmbeddingService({

package/src/services/embeddings/indexers/documentIndexer.js

@@ -0,0 +1,206 @@
+/**
+ * DocumentIndexer — keeps the per-agent `documents` vector surface in sync
+ * with externalized large content (web fetches first) and serves semantic /
+ * hybrid recall across it.
+ *
+ * Mirror of ReminisceIndexer, with three differences:
+ *   1. UNIT = a document (not a conversation message). Chunk ids follow
+ *      `${docId}#${chunkIndex}`; re-indexing a doc deletes its old chunks
+ *      first so a shrunk doc never leaves orphan tail chunks.
+ *   2. LINE METADATA. The chunker yields CHAR offsets; we map them to 1-based
+ *      LINE ranges so a recall hit points the agent straight at a code-map
+ *      `read-range` target (filePath + startLine/endLine) for the full passage.
+ *   3. NO PER-UNIT DEDUP ON SEARCH. Different chunks of the same doc are
+ *      distinct passages — we want them all rankable (optionally filtered to
+ *      a single docId), not collapsed to one row per doc.
+ *
+ * Pure w.r.t. persistence: the indexer only needs the embedding service +
+ * the content to chunk. File persistence + eviction live in DocumentStore;
+ * the wiring layer purges vectors (removeDocument) for evicted/removed docs.
+ *
+ * Failure policy: best-effort, structured result, never throws.
+ */
+
+import { chunkText, DEFAULT_MAX_CHARS, DEFAULT_OVERLAP_CHARS } from '../utilities/textChunker.js';
+import { makeScoringFn } from '../vectorStore/scoring.js';
+
+const SURFACE = 'documents';
+
+/**
+ * Build an ascending list of newline character offsets, then resolve a char
+ * offset to a 1-based line number via binary search. Computed once per doc.
+ * @private
+ */
+function makeOffsetToLine(content) {
+  const newlines = [];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') newlines.push(i);
+  }
+  return (offset) => {
+    // Number of newlines strictly before `offset` == 0-based line; +1 → 1-based.
+    let lo = 0;
+    let hi = newlines.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (newlines[mid] < offset) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo + 1;
+  };
+}
+
+export class DocumentIndexer {
+  /**
+   * @param {object} opts
+   * @param {import('../embeddingService.js').EmbeddingService} opts.embeddingService
+   * @param {object} [opts.logger]
+   * @param {number} [opts.chunkMaxChars]
+   * @param {number} [opts.chunkOverlapChars]
+   */
+  constructor({
+    embeddingService,
+    logger = null,
+    chunkMaxChars = DEFAULT_MAX_CHARS,
+    chunkOverlapChars = DEFAULT_OVERLAP_CHARS,
+    now = () => new Date().toISOString(),
+  }) {
+    this._svc = embeddingService;
+    this._logger = logger;
+    this._chunkMaxChars = chunkMaxChars;
+    this._chunkOverlapChars = chunkOverlapChars;
+    this._now = now;
+  }
+
+  get isEnabled() {
+    return !!(this._svc && this._svc.isEnabled);
+  }
+
+  /**
+   * Index (or re-index) a single document. Replaces any existing chunks for
+   * the same docId.
+   *
+   * @param {string} agentId
+   * @param {object} doc
+   * @param {string} doc.docId
+   * @param {string} doc.content
+   * @param {string} [doc.source]
+   * @param {string} [doc.title]
+   * @returns {Promise<{indexed: boolean, chunks?: number, reason?: string, error?: string}>}
+   */
+  async indexDocument(agentId, { docId, content, source = '', title = '' } = {}) {
+    if (!this.isEnabled) return { indexed: false, reason: 'disabled' };
+    if (!agentId || !docId || typeof content !== 'string' || content.length === 0) {
+      return { indexed: false, reason: 'invalid-input' };
+    }
+
+    // content is guaranteed non-empty above, so chunkText always returns ≥1.
+    const chunks = chunkText(content, {
+      maxChars: this._chunkMaxChars,
+      overlapChars: this._chunkOverlapChars,
+    });
+
+    const offsetToLine = makeOffsetToLine(content);
+    const indexedAt = this._now();
+    const texts = chunks.map((c) => c.text);
+
+    let vectors;
+    try {
+      vectors = await this._svc.embedDocuments(texts, 'document');
+    } catch (err) {
+      this._logger?.warn?.('[documentIndexer] embed failed', { agentId, docId, error: err?.message });
+      return { indexed: false, reason: 'error', error: err?.message };
+    }
+
+    const rows = chunks.map((c, i) => ({
+      id: `${docId}#${c.index}`,
+      vector: vectors[i],
+      metadata: {
+        docId,
+        source,
+        title,
+        chunkIndex: c.index,
+        charStart: c.start,
+        charEnd: c.end,
+        lineStart: offsetToLine(c.start),
+        lineEnd: offsetToLine(Math.max(c.start, c.end - 1)),
+        text: c.text,
+        indexedAt,
+      },
+    }));
+
+    try {
+      const store = await this._svc.getStore({ agentId, surface: SURFACE });
+      await store.deleteWhere((m) => m?.docId === docId);
+      await store.upsertBatch(rows);
+      return { indexed: true, chunks: rows.length };
+    } catch (err) {
+      this._logger?.warn?.('[documentIndexer] upsert failed', { agentId, docId, error: err?.message });
+      return { indexed: false, reason: 'error', error: err?.message };
+    }
+  }
+
+  /**
+   * Remove every chunk belonging to a document. Best-effort.
+   * @returns {Promise<{removed: number, ok: boolean, reason?: string}>}
+   */
+  async removeDocument(agentId, docId) {
+    if (!this.isEnabled) return { ok: false, removed: 0, reason: 'disabled' };
+    if (!agentId || !docId) return { ok: false, removed: 0, reason: 'invalid-input' };
+    try {
+      const store = await this._svc.getStore({ agentId, surface: SURFACE });
+      const removed = await store.deleteWhere((m) => m?.docId === docId);
+      return { ok: true, removed };
+    } catch (err) {
+      this._logger?.warn?.('[documentIndexer] removeDocument failed', { agentId, docId, error: err?.message });
+      return { ok: false, removed: 0, reason: 'error', error: err?.message };
+    }
+  }
+
+  /**
+   * Semantic / hybrid recall across the agent's documents. Returns ranked
+   * CHUNKS (passages), each with the docId + line range so the caller can
+   * read the full passage via code-map read-range.
+   *
+   * @param {string} agentId
+   * @param {string} query
+   * @param {object} [opts]
+   * @param {number}  [opts.topK=8]
+   * @param {boolean} [opts.hybrid=true]
+   * @param {boolean} [opts.boost=true]   Recency/access scoring.
+   * @param {string}  [opts.docId]        Restrict to a single document.
+   * @returns {Promise<{enabled: boolean, hits: Array, error?: string}>}
+   */
+  async search(agentId, query, { topK = 8, hybrid = true, boost = true, docId = null } = {}) {
+    if (!this.isEnabled) return { enabled: false, hits: [] };
+    if (!agentId || typeof query !== 'string' || !query.trim()) {
+      return { enabled: true, hits: [] };
+    }
+    try {
+      const store = await this._svc.getStore({ agentId, surface: SURFACE });
+      const queryVec = await this._svc.embedQuery(query);
+      const scoring = boost ? makeScoringFn({ recency: true }) : null;
+      const filter = docId ? ((m) => m?.docId === docId) : null;
+      const raw = hybrid
+        ? await store.hybridQuery(queryVec, query, { topK, filter, scoring })
+        : await store.query(queryVec, { topK, filter, scoring });
+
+      const hits = raw.map((r) => ({
+        docId: r.metadata?.docId,
+        source: r.metadata?.source || '',
+        title: r.metadata?.title || '',
+        chunkIndex: r.metadata?.chunkIndex ?? 0,
+        lineStart: r.metadata?.lineStart ?? 1,
+        lineEnd: r.metadata?.lineEnd ?? 1,
+        score: r.score,
+        similarity: r.similarity, // raw cosine for relevance gating (AR3)
+        text: r.metadata?.text || '',
+      }));
+      return { enabled: true, hits };
+    } catch (err) {
+      this._logger?.warn?.('[documentIndexer] search failed', { agentId, error: err?.message });
+      return { enabled: true, hits: [], error: err?.message };
+    }
+  }
+}
+
+export default DocumentIndexer;

package/src/services/embeddings/indexers/reminisceIndexer.js

@@ -303,6 +303,7 @@ export class ReminisceIndexer {
           byMessage.set(mid, {
             messageId: mid,
             score: r.score,
+            similarity: r.similarity, // raw cosine for relevance gating (AR3)
             chunkIndex: r.metadata?.chunkIndex ?? 0,
             chunkText: r.metadata?.text || '',
             metadata: r.metadata,

package/src/services/embeddings/utilities/__tests__/decayingCounter.test.js

@@ -0,0 +1,107 @@
+/**
+ * Tests for decayingCounter — the aging-LFU access counter. Verifies the two
+ * guarantees (bounded + aging) and every defensive branch.
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  decayedValue,
+  touch,
+  DEFAULT_HALF_LIFE_MS,
+  MAX_VALUE,
+} from '../decayingCounter.js';
+
+const NOW = 1_000_000_000_000;
+
+describe('decayedValue', () => {
+  test('absent / invalid state → 0', () => {
+    expect(decayedValue(null, NOW)).toBe(0);
+    expect(decayedValue(undefined, NOW)).toBe(0);
+    expect(decayedValue({}, NOW)).toBe(0);
+    expect(decayedValue({ v: 'x' }, NOW)).toBe(0);
+    expect(decayedValue({ v: NaN }, NOW)).toBe(0);
+    expect(decayedValue({ v: 0 }, NOW)).toBe(0);
+    expect(decayedValue({ v: -3 }, NOW)).toBe(0);
+  });
+
+  test('now/future timestamp → no decay (returns v)', () => {
+    expect(decayedValue({ v: 10, t: NOW }, NOW)).toBe(10);
+    expect(decayedValue({ v: 10, t: NOW + 5000 }, NOW)).toBe(10); // clock skew
+  });
+
+  test('missing t is treated as now (no decay)', () => {
+    expect(decayedValue({ v: 8 }, NOW)).toBe(8);
+  });
+
+  test('halves every half-life', () => {
+    expect(decayedValue({ v: 16, t: NOW - DEFAULT_HALF_LIFE_MS }, NOW)).toBeCloseTo(8, 6);
+    expect(decayedValue({ v: 16, t: NOW - 2 * DEFAULT_HALF_LIFE_MS }, NOW)).toBeCloseTo(4, 6);
+  });
+
+  test('a custom half-life is honoured', () => {
+    const hl = 1000;
+    expect(decayedValue({ v: 100, t: NOW - 1000 }, NOW, hl)).toBeCloseTo(50, 6);
+  });
+
+  test('non-positive half-life falls back to the default', () => {
+    const oneDefault = decayedValue({ v: 16, t: NOW - DEFAULT_HALF_LIFE_MS }, NOW, 0);
+    expect(oneDefault).toBeCloseTo(8, 6);
+    expect(decayedValue({ v: 16, t: NOW - DEFAULT_HALF_LIFE_MS }, NOW, -5)).toBeCloseTo(8, 6);
+  });
+
+  test('decays toward (but never below) zero over many half-lives', () => {
+    const v = decayedValue({ v: 255, t: NOW - 40 * DEFAULT_HALF_LIFE_MS }, NOW);
+    expect(v).toBeGreaterThan(0);
+    expect(v).toBeLessThan(0.001);
+  });
+});
+
+describe('touch', () => {
+  test('first access starts at the increment, stamps now', () => {
+    const s = touch(null, NOW);
+    expect(s.v).toBe(1);
+    expect(s.t).toBe(NOW);
+  });
+
+  test('decays the prior value THEN adds the increment', () => {
+    // prior 16, one half-life old → 8, +1 = 9
+    const s = touch({ v: 16, t: NOW - DEFAULT_HALF_LIFE_MS }, NOW);
+    expect(s.v).toBeCloseTo(9, 6);
+    expect(s.t).toBe(NOW);
+  });
+
+  test('repeated immediate accesses accumulate (no time gap → no decay)', () => {
+    let s = touch(null, NOW);
+    s = touch(s, NOW);
+    s = touch(s, NOW);
+    expect(s.v).toBe(3);
+  });
+
+  test('clamps to MAX_VALUE', () => {
+    const s = touch({ v: MAX_VALUE, t: NOW }, NOW); // already at cap
+    expect(s.v).toBe(MAX_VALUE);
+  });
+
+  test('custom increment + custom max', () => {
+    const s = touch({ v: 4, t: NOW }, NOW, { increment: 10, max: 12 });
+    expect(s.v).toBe(12); // 4 + 10 = 14, clamped to 12
+  });
+
+  test('non-finite increment falls back to 1; non-finite max falls back to MAX_VALUE', () => {
+    expect(touch(null, NOW, { increment: NaN }).v).toBe(1);
+    const s = touch({ v: 300, t: NOW }, NOW, { max: undefined }); // 300+1 clamps to default cap
+    expect(s.v).toBe(MAX_VALUE);
+  });
+
+  test('custom half-life affects the pre-increment decay', () => {
+    // prior 100, 1000ms old, half-life 1000 → 50, +1 = 51
+    const s = touch({ v: 100, t: NOW - 1000 }, NOW, { halfLifeMs: 1000 });
+    expect(s.v).toBeCloseTo(51, 6);
+  });
+});
+
+describe('exported constants', () => {
+  test('sane defaults', () => {
+    expect(DEFAULT_HALF_LIFE_MS).toBe(7 * 24 * 60 * 60 * 1000);
+    expect(MAX_VALUE).toBe(255);
+  });
+});

package/src/services/embeddings/utilities/__tests__/textChunker.test.js

@@ -215,3 +215,43 @@ describe('chunkText — no regex usage', () => {
     expect(foundRegex).toBe(false);
   });
 });
+
+describe('chunkText — packing & separator edge cases', () => {
+  test('packs multiple atoms into one chunk (appends to a non-empty buffer)', () => {
+    // Three ~20-char paragraphs, total > maxChars(50): atoms 0 and 1 pack
+    // into chunk 0 (the second append hits a non-empty buffer), atom 2 spills.
+    const text = `${'a'.repeat(18)}\n\n${'b'.repeat(18)}\n\n${'c'.repeat(18)}`;
+    const chunks = chunkText(text, { maxChars: 50 });
+    expect(chunks.length).toBeGreaterThanOrEqual(2);
+    expect(chunks[0].text).toContain('a'.repeat(18));
+    expect(chunks[0].text).toContain('b'.repeat(18)); // two atoms in one chunk
+    const recon = chunks.map((c) => text.slice(c.start, c.end)).join('');
+    expect(recon).toBe(text);
+  });
+
+  test('text ending exactly on a \\n\\n separator leaves no trailing atom', () => {
+    const text = `${'a'.repeat(60)}\n\n`; // > maxChars, ends with the separator
+    const chunks = chunkText(text, { maxChars: 50 });
+    expect(chunks.length).toBeGreaterThan(0);
+    const recon = chunks.map((c) => text.slice(c.start, c.end)).join('');
+    expect(recon).toBe(text);
+  });
+});
+
+describe('chunkText — pathological single oversized sentence', () => {
+  test('first sentence longer than maxChars is emitted then hard-sliced, reconstructs exactly', () => {
+    // A long boundary-less run (> maxChars) followed by a real sentence
+    // boundary drives splitLongAtomBySentence down the "no safe boundary AND
+    // this sentence exceeds maxChars" path, then chunkText hard-slices it.
+    const longRun = 'a'.repeat(140);          // no '. ' / '\n' inside → one giant "sentence"
+    const text = `${longRun}. tail sentence here`;
+    const chunks = chunkText(text, { maxChars: 50 });
+
+    expect(chunks.length).toBeGreaterThan(1);
+    // Every chunk respects the cap (overlap collapses to 0 at this maxChars).
+    expect(chunks.every((c) => c.text.length <= 50)).toBe(true);
+    // Offsets reconstruct the original exactly — the chunker's core contract.
+    const recon = chunks.map((c) => text.slice(c.start, c.end)).join('');
+    expect(recon).toBe(text);
+  });
+});