Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.1 KB
Raw Blame
/**
 * v0.32.x search-lite \u2014 semantic query cache.
 *
 * PGLite-backed test. Confirms:
 *   - migration v51 creates the query_cache table
 *   - store + lookup roundtrip with EXACT same embedding \u2192 hit
 *   - lookup with a similar embedding (cosine > 0.92) \u2192 hit
 *   - lookup with a far embedding \u2192 miss
 *   - TTL expiration: a stale row is skipped at read time
 *   - clear / prune / stats work as advertised
 *   - source_id isolation: brain A's cache doesn't leak to brain B
 *   - disabled cache is a pure no-op
 *
 * Uses synthetic Float32Array embeddings so the test doesn't depend on
 * any external embedding provider.
 */

import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { SemanticQueryCache, cacheRowId, cacheTextGuard } from '../src/core/search/query-cache.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import type { SearchResult, HybridSearchMeta } from '../src/core/types.ts';

let engine: PGLiteEngine;

// Build a stable, normalized embedding. PGLite ships pgvector with 1536-dim
// support (the default); a smaller test dim won't match the column. We
// truncate / pad to 1536 to match the migration's resolved dim.
const DIM = 1536;

function makeEmbedding(seed: number, dim = DIM): Float32Array {
  const e = new Float32Array(dim);
  // Simple deterministic generator with a unique fingerprint per seed
  // so similar seeds produce similar (cosine > 0.95) vectors and distinct
  // seeds produce orthogonal-ish ones.
  for (let i = 0; i < dim; i++) {
    e[i] = Math.sin(seed * 0.001 + i * 0.01);
  }
  // L2-normalize so cosine = dot product.
  let mag = 0;
  for (let i = 0; i < dim; i++) mag += e[i] * e[i];
  mag = Math.sqrt(mag);
  if (mag > 0) for (let i = 0; i < dim; i++) e[i] /= mag;
  return e;
}

function makeOrthogonalEmbedding(seed: number, dim = DIM): Float32Array {
  // Use a totally different basis so cosine is near-zero.
  const e = new Float32Array(dim);
  for (let i = 0; i < dim; i++) {
    e[i] = Math.cos(seed * 13.7 + i * 0.97);
  }
  let mag = 0;
  for (let i = 0; i < dim; i++) mag += e[i] * e[i];
  mag = Math.sqrt(mag);
  if (mag > 0) for (let i = 0; i < dim; i++) e[i] /= mag;
  return e;
}

function makeResult(slug: string): SearchResult {
  return {
    slug,
    page_id: 1,
    title: `Title for ${slug}`,
    type: 'concept',
    chunk_text: `chunk text for ${slug}`,
    chunk_source: 'compiled_truth',
    chunk_id: 1,
    chunk_index: 0,
    score: 1.0,
    stale: false,
  };
}

const META: HybridSearchMeta = {
  vector_enabled: true,
  detail_resolved: 'medium',
  expansion_applied: false,
  intent: 'general',
};

beforeAll(async () => {
  // v0.36.2.0: DEFAULT_EMBEDDING_DIMENSIONS flipped to 1024 (Voyage Matryoshka).
  // This test hardcodes DIM=1536 in its embeddings. If another test file in
  // the same shard configured the gateway before us, initSchema() would size
  // query_cache.embedding at vector(1024) and every insert below would fail
  // with "expected 1024 dimensions, not 1536". Pin the gateway to 1536d
  // explicitly so this file is hermetic regardless of cross-file state.
  resetGateway();
  configureGateway({
    embedding_model: 'openai:text-embedding-3-large',
    embedding_dimensions: 1536,
    env: { OPENAI_API_KEY: 'sk-fake' },
  });
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  try { await engine.disconnect(); } catch { /* ignore */ }
  resetGateway();
});

beforeEach(async () => {
  // Wipe the cache between tests so ordering doesn't matter.
  await engine.executeRaw(`DELETE FROM query_cache`);
});

describe('migration v51 \u2014 query_cache table exists', () => {
  test('table is present and has expected columns', async () => {
    const rows = await engine.executeRaw<{ column_name: string }>(
      `SELECT column_name FROM information_schema.columns
        WHERE table_name = 'query_cache'`,
    );
    const names = rows.map(r => r.column_name);
    expect(names).toContain('id');
    expect(names).toContain('query_text');
    expect(names).toContain('source_id');
    expect(names).toContain('embedding');
    expect(names).toContain('results');
    expect(names).toContain('meta');
    expect(names).toContain('ttl_seconds');
    expect(names).toContain('created_at');
    expect(names).toContain('hit_count');
  });
});

describe('cacheRowId', () => {
  test('is deterministic across same input', () => {
    expect(cacheRowId('hello', 'default')).toBe(cacheRowId('hello', 'default'));
  });
  test('differs across source_id', () => {
    expect(cacheRowId('hello', 'a')).not.toBe(cacheRowId('hello', 'b'));
  });
});

describe('SemanticQueryCache \u2014 store + lookup', () => {
  test('roundtrip: exact embedding match returns a hit', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(1);
    const results = [makeResult('a'), makeResult('b')];

    await cache.store('what is foo', emb, results, META);
    const hit = await cache.lookup(emb);

    expect(hit.hit).toBe(true);
    expect(hit.results).toHaveLength(2);
    expect(hit.results?.[0].slug).toBe('a');
    expect(hit.similarity).toBeGreaterThan(0.99);
  });

  test('similar embedding (cosine > 0.92) is a hit', async () => {
    const cache = new SemanticQueryCache(engine);
    const base = makeEmbedding(100);

    // Construct a near-neighbor: tweak a few dims so cosine stays > 0.92.
    const near = new Float32Array(base);
    for (let i = 0; i < 10; i++) near[i] += 0.005;
    // Re-normalize.
    let mag = 0;
    for (let i = 0; i < DIM; i++) mag += near[i] * near[i];
    mag = Math.sqrt(mag);
    for (let i = 0; i < DIM; i++) near[i] /= mag;

    await cache.store('what is foo', base, [makeResult('a')], META);
    const hit = await cache.lookup(near);

    expect(hit.hit).toBe(true);
    expect(hit.similarity).toBeGreaterThan(0.92);
  });

  test('orthogonal embedding is a miss', async () => {
    const cache = new SemanticQueryCache(engine);
    const a = makeEmbedding(1);
    const b = makeOrthogonalEmbedding(2);
    await cache.store('q1', a, [makeResult('a')], META);
    const hit = await cache.lookup(b);
    expect(hit.hit).toBe(false);
  });
});

describe('SemanticQueryCache \u2014 TTL', () => {
  test('stale row (past TTL) is not returned', async () => {
    const cache = new SemanticQueryCache(engine, { ttlSeconds: 1 });
    const emb = makeEmbedding(42);
    await cache.store('q', emb, [makeResult('a')], META, { ttlSeconds: 1 });

    // Manually rewind created_at to simulate expiration.
    await engine.executeRaw(
      `UPDATE query_cache SET created_at = now() - interval '10 seconds'`,
    );
    const hit = await cache.lookup(emb);
    expect(hit.hit).toBe(false);
  });
});

describe('SemanticQueryCache \u2014 source isolation', () => {
  test('different source_id cannot read each other\u2019s rows', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(7);
    await cache.store('q', emb, [makeResult('a')], META, { sourceId: 'src-A' });
    const hitB = await cache.lookup(emb, { sourceId: 'src-B' });
    expect(hitB.hit).toBe(false);
    const hitA = await cache.lookup(emb, { sourceId: 'src-A' });
    expect(hitA.hit).toBe(true);
  });
});

describe('SemanticQueryCache \u2014 management', () => {
  test('clear() wipes all rows', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(9);
    await cache.store('q1', emb, [makeResult('a')], META);
    await cache.store('q2', makeEmbedding(10), [makeResult('b')], META);
    const removed = await cache.clear();
    expect(removed).toBeGreaterThanOrEqual(2);
    const stats = await cache.stats();
    expect(stats.total_rows).toBe(0);
  });

  test('prune() deletes only stale rows', async () => {
    const cache = new SemanticQueryCache(engine);
    await cache.store('fresh', makeEmbedding(11), [makeResult('a')], META);
    await cache.store('stale', makeEmbedding(12), [makeResult('b')], META, { ttlSeconds: 1 });
    await engine.executeRaw(
      `UPDATE query_cache SET created_at = now() - interval '10 seconds' WHERE query_text = 'stale'`,
    );
    const removed = await cache.prune();
    expect(removed).toBe(1);
    const stats = await cache.stats();
    expect(stats.total_rows).toBe(1);
    expect(stats.fresh_rows).toBe(1);
  });

  test('stats() reports fresh / stale / total / hit counters', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(13);
    await cache.store('q', emb, [makeResult('a')], META);
    await cache.lookup(emb);  // bump hit
    // Hit bump is async/fire-and-forget; give it a moment to land.
    await new Promise(r => setTimeout(r, 50));
    const stats = await cache.stats();
    expect(stats.total_rows).toBe(1);
    expect(stats.fresh_rows).toBe(1);
    expect(stats.stale_rows).toBe(0);
    expect(stats.total_hits).toBeGreaterThanOrEqual(1);
  });
});

describe('cacheTextGuard (#1469)', () => {
  test('verbatim equality after NFKC / case / whitespace normalization', () => {
    expect(cacheTextGuard('what is foo', 'what is foo')).toBe(true);
    expect(cacheTextGuard('What  is\tFoo ', 'what is foo')).toBe(true);
    // NFKC folds full-width Latin to half-width.
    expect(cacheTextGuard('\uff57\uff48\uff41\uff54 \uff49\uff53 \uff46\uff4f\uff4f', 'what is foo')).toBe(true);
  });

  test('unrelated queries fail the guard', () => {
    expect(cacheTextGuard('quarterly revenue projections', 'kimchi fried rice recipe')).toBe(false);
  });

  test('near-paraphrase passes via char-bigram Dice >= 0.5', () => {
    expect(cacheTextGuard('what is the foo bar', 'what is foo bar')).toBe(true);
  });

  test('distinct Korean queries fail the guard (CJK-safe, no token boundary needed)', () => {
    expect(cacheTextGuard('\uae40\uce58 \ub9cc\ub4dc\ub294 \ubc29\ubc95', '\uc11c\uc6b8 \ub0a0\uc528 \uc608\ubcf4')).toBe(false);
  });

  test('near-identical Korean queries pass the guard', () => {
    // "how to make kimchi" vs the shorter "\ubc95" form \u2014 high bigram overlap.
    expect(cacheTextGuard('\uae40\uce58 \ub9cc\ub4dc\ub294 \ubc29\ubc95', '\uae40\uce58 \ub9cc\ub4dc\ub294 \ubc95')).toBe(true);
  });

  test('degenerate short strings: equality only, no spurious Dice pass', () => {
    expect(cacheTextGuard('a', 'a')).toBe(true);
    expect(cacheTextGuard('a', 'b')).toBe(false);
    expect(cacheTextGuard('', '')).toBe(true);
    expect(cacheTextGuard('', 'foo')).toBe(false);
  });
});

describe('SemanticQueryCache \u2014 text guard on lookup (#1469)', () => {
  test('degenerate embedding space: unrelated query text is a MISS even at cosine ~1.0', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(200);
    await cache.store('quarterly revenue projections', emb, [makeResult('finance')], META);
    // Same (collapsed) embedding, totally different query \u2014 must NOT be served.
    const hit = await cache.lookup(emb, { queryText: 'kimchi fried rice recipe' });
    expect(hit.hit).toBe(false);
  });

  test('verbatim query text is a hit through the guard', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(201);
    await cache.store('quarterly revenue projections', emb, [makeResult('finance')], META);
    const hit = await cache.lookup(emb, { queryText: 'Quarterly  Revenue Projections' });
    expect(hit.hit).toBe(true);
    expect(hit.results?.[0].slug).toBe('finance');
  });

  test('paraphrase (bigram Dice >= 0.5) is a hit', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(202);
    await cache.store('what is foo bar', emb, [makeResult('foobar')], META);
    const hit = await cache.lookup(emb, { queryText: 'what is the foo bar' });
    expect(hit.hit).toBe(true);
    expect(hit.results?.[0].slug).toBe('foobar');
  });

  test('legacy path: no queryText preserves pre-guard behavior', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(203);
    await cache.store('some cached query', emb, [makeResult('legacy')], META);
    const hit = await cache.lookup(emb);
    expect(hit.hit).toBe(true);
    expect(hit.results?.[0].slug).toBe('legacy');
  });

  test('Korean distinct queries do not collapse; guard scans past the closest candidate', async () => {
    const cache = new SemanticQueryCache(engine);
    const embA = makeEmbedding(300);
    // Near-neighbor for the second row: cosine > 0.92 vs embA but strictly
    // farther than embA itself, so the WRONG row sorts first.
    const embB = new Float32Array(embA);
    for (let i = 0; i < 10; i++) embB[i] += 0.005;
    let mag = 0;
    for (let i = 0; i < DIM; i++) mag += embB[i] * embB[i];
    mag = Math.sqrt(mag);
    for (let i = 0; i < DIM; i++) embB[i] /= mag;

    // "Seoul weather forecast" (closest to lookup emb) vs "how to make kimchi".
    await cache.store('\uc11c\uc6b8 \ub0a0\uc528 \uc608\ubcf4', embA, [makeResult('weather')], META);
    await cache.store('\uae40\uce58 \ub9cc\ub4dc\ub294 \ubc29\ubc95', embB, [makeResult('kimchi')], META);

    // Lookup with the kimchi TEXT but an embedding closest to the weather row:
    // the guard must skip the closer non-matching candidate and serve kimchi.
    const hit = await cache.lookup(embA, { queryText: '\uae40\uce58 \ub9cc\ub4dc\ub294 \ubc29\ubc95' });
    expect(hit.hit).toBe(true);
    expect(hit.results?.[0].slug).toBe('kimchi');

    // A third, unrelated Korean query matches NEITHER cached text \u2192 miss.
    const miss = await cache.lookup(embA, { queryText: '\uc8fc\uc2dd \uc2dc\uc7a5 \ubd84\uc11d' });
    expect(miss.hit).toBe(false);
  });
});

describe('SemanticQueryCache \u2014 disabled', () => {
  test('disabled cache is a pure no-op on lookup', async () => {
    const cache = new SemanticQueryCache(engine, { enabled: false });
    const emb = makeEmbedding(99);
    await cache.store('q', emb, [makeResult('a')], META);
    // Even after a store call, lookup must miss because enabled=false.
    const hit = await cache.lookup(emb);
    expect(hit.hit).toBe(false);
  });
});

/**
 * Wrap the real engine so every executeRaw SQL string is recorded (and
 * optionally intercepted) while all other methods delegate untouched.
 */
function spyExecuteRaw(
  onCall: (sql: string, params?: unknown[]) => Promise<void> | void,
): PGLiteEngine {
  return new Proxy(engine, {
    get(target, prop) {
      const v = Reflect.get(target, prop, target);
      if (prop === 'executeRaw' && typeof v === 'function') {
        return async (sql: string, params?: unknown[], o?: { signal?: AbortSignal }) => {
          await onCall(sql, params);
          return v.call(target, sql, params, o);
        };
      }
      return typeof v === 'function' ? v.bind(target) : v;
    },
  }) as unknown as PGLiteEngine;
}

describe('SemanticQueryCache \u2014 light candidates, winner-only payload fetch (D2)', () => {
  test('lookup ships ONE heavy payload: candidate select carries no results/meta; winner fetched by id', async () => {
    // Three near-identical embeddings so the candidate query returns
    // multiple rows within the 0.92 threshold \u2014 pre-D2, all of their
    // results/meta JSONB payloads shipped just to keep one.
    const cache = new SemanticQueryCache(engine);
    const winnerEmb = makeEmbedding(4200);
    await cache.store('who is alice-example', winnerEmb, [makeResult('people/alice-example')], META);
    await cache.store('who is alice example', makeEmbedding(4201), [makeResult('people/alice-two')], META);
    await cache.store('who was alice-example', makeEmbedding(4202), [makeResult('people/alice-three')], META);

    const calls: string[] = [];
    const spyCache = new SemanticQueryCache(spyExecuteRaw((sql) => void calls.push(sql)));
    const hit = await spyCache.lookup(winnerEmb, { queryText: 'who is alice-example' });

    expect(hit.hit).toBe(true);
    expect(hit.results?.[0]?.slug).toBe('people/alice-example');
    expect(hit.meta?.intent).toBe('general');

    const selects = calls.filter((q) => q.trimStart().toUpperCase().startsWith('SELECT'));
    expect(selects.length).toBe(2);
    // Candidate query is LIGHT: id/query_text/distance/age only.
    expect(selects[0]).toContain('qc.id, qc.query_text');
    expect(selects[0]).not.toContain('qc.results');
    expect(selects[0]).not.toContain('qc.meta');
    // Exactly one heavy fetch, keyed by the winner's id.
    expect(selects[1]).toContain('SELECT results, meta FROM query_cache WHERE id = $1');
  });

  test('winner row deleted between the two statements is a miss, not a throw', async () => {
    const cache = new SemanticQueryCache(engine);
    const emb = makeEmbedding(4300);
    await cache.store('race window query', emb, [makeResult('race/window')], META);

    // Simulate a concurrent prune/clear landing between the candidate
    // select and the payload fetch: delete the winner right before its
    // by-id payload query executes.
    const racing = new SemanticQueryCache(
      spyExecuteRaw(async (sql, params) => {
        if (sql.includes('SELECT results, meta FROM query_cache')) {
          await engine.executeRaw(`DELETE FROM query_cache WHERE id = $1`, [params![0]]);
        }
      }),
    );
    const res = await racing.lookup(emb, { queryText: 'race window query' });
    expect(res.hit).toBe(false);
  });
});