Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.6 KB
Raw Blame
/**
 * #5889 + remote title FTS: the page-grain title arm (engine-sql/titles.ts)
 * on PGLite here and on PostgreSQL through test/e2e/title-arm-postgres.test.ts.
 *
 * #5889: every title holding the query term once ties on ts_rank_cd, ties
 * broke by page id, and the exact-lookup tier only sees the arm's top rows,
 * so an identity page titled exactly "Acme" (created last) was buried under
 * 60+ "Acme weekly sync N" pages for local and remote callers.
 *
 * Remote predicate: safe-chunks callers match weight-A (title) lexemes of
 * pages.search_vector. Parity cases compare against the previous title-only
 * predicate (`to_tsvector(lang, title) @@ websearch_to_tsquery(lang, q)`),
 * so timeline text can never change which titles a remote caller sees.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import type { BrainEngine } from '../../src/core/engine.ts';
import type { SearchOpts } from '../../src/core/types.ts';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { hybridSearch, hybridSearchCached } from '../../src/core/search/hybrid.ts';
import { configureGateway, resetGateway } from '../../src/core/ai/gateway.ts';
import { installFixtureChunks } from '../helpers/page-projection.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { testBackends } from '../helpers/test-backends.ts';

const DIM = 1536;
const LOCAL: SearchOpts = {};
const REMOTE: SearchOpts = { requireSafeChunks: true, excludePrivate: true };
const SYNC_PAGES = 64;

for (const kind of testBackends()) {
  describe(`title arm (${kind})`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;

    beforeAll(async () => {
      // Empty env: no embedding, so hybridSearch takes the keyword + title path.
      configureGateway({ embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: DIM, env: {} });
      if (kind === 'postgres') {
        ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
      } else {
        engine = new PGLiteEngine();
        await engine.connect({});
        await engine.initSchema();
        close = () => engine.disconnect();
      }
    }, 120_000);

    afterAll(async () => {
      await close?.();
      resetGateway(); // R5: restore the preload baseline for later files in this shard
    });

    beforeEach(async () => {
      await engine.executeRaw('DELETE FROM pages');
    });

    async function page(slug: string, title: string, body: string, timeline = '', type = 'note') {
      await engine.putPage(slug, { type, title, compiled_truth: body, timeline });
      await installFixtureChunks(engine, slug, [{ chunk_index: 0, chunk_text: body, chunk_source: 'compiled_truth' }]);
    }

    async function seedSyncPages(prefix: string) {
      for (let i = 1; i <= SYNC_PAGES; i++) {
        await page(`${prefix}/acme-sync-${i}`, `Acme weekly sync ${i}`, `Acme sync ${i} notes: the Acme team reviewed the Acme roadmap.`);
      }
    }

    describe('#5889 exact-title page ranks first', () => {
      for (const prefix of ['notes', 'meetings']) {
        test(`${prefix}/ variant, local and remote callers`, async () => {
          await seedSyncPages(prefix);
          await page('projects/acme', 'Acme', 'Our flagship client project.');
          for (const [label, opts] of [['local', LOCAL], ['remote', REMOTE]] as const) {
            const titles = await engine.searchTitles('Acme', { ...opts, limit: 50 });
            expect({ label, slug: titles[0]?.slug }).toEqual({ label, slug: 'projects/acme' });
            const results = await hybridSearch(engine, 'Acme', { ...opts, limit: 20, expansion: false });
            expect({ label, slug: results[0]?.slug, exact: results[0]?.exact_lookup }).toEqual({ label, slug: 'projects/acme', exact: 'title' });
          }
        }, 120_000);
      }

      test('production cached path (search cache on) ranks it first too', async () => {
        await seedSyncPages('notes');
        await page('projects/acme', 'Acme', 'Our flagship client project.');
        for (const opts of [LOCAL, REMOTE]) {
          const results = await hybridSearchCached(engine, 'Acme', { ...opts, limit: 20, expansion: false, useCache: true });
          expect(results[0]?.slug).toBe('projects/acme');
          expect(results[0]?.exact_lookup).toBe('title');
        }
      }, 120_000);

      for (const [label, title] of [['quoted YAML title', '"Acme"'], ['trailing NBSP', 'Acme\u00a0']] as const) {
        test(`${label} ranks first with exact_lookup: title`, async () => {
          await seedSyncPages('notes');
          await page('projects/acme', title, 'Our flagship client project.');
          for (const opts of [LOCAL, REMOTE]) {
            const results = await hybridSearch(engine, 'Acme', { ...opts, limit: 20, expansion: false });
            expect(results[0]?.slug).toBe('projects/acme');
            expect(results[0]?.exact_lookup).toBe('title');
          }
        }, 120_000);
      }

      test('negative control: "Acme Corp" gets no exact_lookup', async () => {
        await seedSyncPages('notes');
        await page('companies/acme-corp', 'Acme Corp', 'A supplier.');
        for (const opts of [LOCAL, REMOTE]) {
          const results = await hybridSearch(engine, 'Acme', { ...opts, limit: 20, expansion: false });
          expect(results.some((r) => r.exact_lookup !== undefined)).toBe(false);
        }
      }, 120_000);

      test('the OR fallback re-runs the same statement and tags relaxed rows', async () => {
        await seedSyncPages('notes');
        await page('projects/acme-zebra', 'Acme Zebra', 'Unrelated body.');
        // Strict AND matches nothing, so the arm re-runs as OR; no title equals the query.
        const rows = await engine.searchTitles('Acme Zebra Quokka', { limit: 50 });
        expect(rows.length).toBeGreaterThan(0);
        expect(rows.every((r) => r.keyword_relaxed === true)).toBe(true);
      }, 120_000);
    });

    describe('#7471 full-name query with a short first name', () => {
      const SURNAMES = ['Alder', 'Birch', 'Cedar', 'Dunmore', 'Ellery', 'Fairley', 'Garnet', 'Holloway', 'Ingram', 'Jasper',
        'Keswick', 'Lowell', 'Marlow', 'Norwood', 'Oakley', 'Pemberton', 'Quill', 'Radley', 'Sutter', 'Thorne',
        'Upton', 'Vance', 'Whitby', 'Yardley', 'Zeller', 'Ashby', 'Brook', 'Carver', 'Dale', 'Elwood'];
      const CASES = [
        ['Matt Examplesurname', 'people/matthew-examplesurname'],
        ['Bob Samplename', 'people/robert-samplename'],
      ] as const;

      async function seedNamesakes() {
        for (const s of SURNAMES) {
          await page(`people/matt-${s.toLowerCase()}`, `Matt ${s}`, `Matt ${s} works in sales.`, '', 'person');
          await page(`people/bob-${s.toLowerCase()}`, `Bob ${s}`, `Bob ${s} reviews contracts.`, '', 'person');
        }
        for (let i = 1; i <= 20; i++) {
          await page(`archive/email-${i}`, `Re: invoice batch ${i}`, `Thanks, Matt Examplesurname. Regards, Bob Samplename.`);
        }
        await page('companies/acme-example', 'Acme Example', 'Team: Matthew Examplesurname (product), Matt Otherperson (advisor).', '', 'company');
        // The person pages come last, so they hold the highest page ids and lose every page-id tie break.
        await page('people/matthew-examplesurname', 'Matthew Examplesurname', 'Product lead at Acme Example.', '', 'person');
        await page('people/robert-samplename', 'Robert Samplename', 'Runs operations at Beta Example.', '', 'person');
      }

      for (const [query, slug] of CASES) {
        test(`"${query}" finds ${slug} in the title arm and ranks it first`, async () => {
          await seedNamesakes();
          for (const [label, opts] of [['local', LOCAL], ['remote', REMOTE]] as const) {
            const titles = await engine.searchTitles(query, { ...opts, limit: 20 });
            expect({ label, slug: titles[0]?.slug, relaxed: titles[0]?.keyword_relaxed }).toEqual({ label, slug, relaxed: undefined });
            const results = await hybridSearch(engine, query, { ...opts, limit: 5, expansion: false });
            expect({ label, slug: results[0]?.slug }).toEqual({ label, slug });
          }
        }, 120_000);
      }

      test('the formal first name still ranks the person page first', async () => {
        await seedNamesakes();
        const results = await hybridSearch(engine, 'Matthew Examplesurname', { limit: 5, expansion: false });
        expect(results[0]?.slug).toBe('people/matthew-examplesurname');
      }, 120_000);

      test('a page titled exactly like the query outranks the name variant', async () => {
        await seedNamesakes();
        await page('people/matt-examplesurname', 'Matt Examplesurname', 'A different person.', '', 'person');
        for (const opts of [LOCAL, REMOTE]) {
          expect((await engine.searchTitles('Matt Examplesurname', { ...opts, limit: 20 }))[0]?.slug).toBe('people/matt-examplesurname');
          const results = await hybridSearch(engine, 'Matt Examplesurname', { ...opts, limit: 5, expansion: false });
          expect(results[0]?.slug).toBe('people/matt-examplesurname');
          expect(results[0]?.exact_lookup).toBe('title');
          expect(results.map((r) => r.slug)).toContain('people/matthew-examplesurname');
        }
      }, 120_000);

      test('in the OR fallback a title with the rare query word outranks titles with only the common one', async () => {
        await seedSyncPages('notes');
        await page('projects/quokka', 'Quokka', 'Unrelated body.');
        // No title holds both words, so the arm re-runs as OR; 64 titles hold "acme", one holds "quokka".
        for (const opts of [LOCAL, REMOTE]) {
          const rows = await engine.searchTitles('Acme Quokka', { ...opts, limit: 20 });
          expect(rows[0]?.slug).toBe('projects/quokka');
          expect(rows.every((r) => r.keyword_relaxed === true)).toBe(true);
          expect(rows.length).toBe(20);
        }
      }, 120_000);
    });

    describe('remote predicate matches the title alone', () => {
      async function legacyRemoteSlugs(query: string): Promise<string[]> {
        const rows = await engine.executeRaw<{ slug: string }>(
          `SELECT slug FROM pages WHERE to_tsvector('english', COALESCE(title, '')) @@ websearch_to_tsquery('english', $1) ORDER BY slug`,
          [query],
        );
        return rows.map((r) => r.slug);
      }
      async function remoteSlugs(query: string): Promise<string[]> {
        return (await engine.searchTitles(query, { ...REMOTE, limit: 100 })).map((r) => r.slug).sort();
      }

      beforeEach(async () => {
        await page('notes/acme-plan', 'Acme launch plan', 'Body without title words.', '- 2026-01-01: secret kickoff with the zebra team');
        await page('notes/acme-secret', 'Acme secret roadmap', 'Body.');
        await page('notes/globex-sync', 'Globex weekly sync', 'Body.', '- 2026-01-02: Acme mentioned in passing');
        await page('notes/launch-acme', 'Launch the Acme product', 'Body.');
        await page('notes/zebra', 'Zebra crossing', 'Body.');
      });

      const queries = [
        ['negation where only a timeline mentions the term', 'acme -secret'],
        ['phrase', '"acme launch"'],
        ['phrase across title words only', '"launch plan"'],
        ['OR', 'globex or zebra'],
        ['timeline-only term', 'kickoff'],
        ['purely negative', '-acme'],
        ['prefix-style token', 'acme*'],
        ['negated phrase', 'acme -"secret roadmap"'],
      ] as const;
      for (const [label, query] of queries) {
        test(`${label}: \`${query}\` matches the legacy title-only predicate`, async () => {
          expect(await remoteSlugs(query)).toEqual(await legacyRemoteSlugs(query));
        });
      }

      test('negation pins the expected titles', async () => {
        expect(await remoteSlugs('acme -secret')).toEqual(['notes/acme-plan', 'notes/launch-acme']);
        expect(await remoteSlugs('kickoff')).toEqual([]);
      });

      test('order follows the title rank, like the legacy predicate', async () => {
        const rows = await engine.searchTitles('acme', { ...REMOTE, limit: 100 });
        const legacy = await engine.executeRaw<{ slug: string }>(
          `SELECT slug FROM pages WHERE to_tsvector('english', title) @@ websearch_to_tsquery('english', 'acme')
            ORDER BY ts_rank_cd(to_tsvector('english', title), websearch_to_tsquery('english', 'acme')) DESC, id`,
        );
        expect(rows.map((r) => r.slug)).toEqual(legacy.map((r) => r.slug));
      });

      test('a page with a NULL search_vector is absent from the remote arm (accepted)', async () => {
        await engine.executeRaw(`UPDATE pages SET search_vector = NULL WHERE slug = 'notes/zebra'`);
        expect(await legacyRemoteSlugs('zebra')).toEqual(['notes/zebra']);
        expect(await remoteSlugs('zebra')).toEqual([]);
      });

      test('weight A of pages.search_vector is the title alone', async () => {
        await engine.executeRaw(
          `INSERT INTO timeline_entries (page_id, date, summary, detail)
           SELECT id, '2026-01-03', 'Quokka summit', 'quokka detail' FROM pages WHERE slug = 'notes/acme-plan'`,
        );
        await engine.executeRaw(`UPDATE pages SET timeline = timeline || ' more quokka text' WHERE slug = 'notes/acme-plan'`);
        const [row] = await engine.executeRaw<{ a: string; title: string; c: string }>(
          `SELECT strip(ts_filter(search_vector, '{a}'))::text AS a,
                  strip(to_tsvector('english', title))::text AS title,
                  strip(ts_filter(search_vector, '{c}'))::text AS c
             FROM pages WHERE slug = 'notes/acme-plan'`,
        );
        expect(row.a).toBe(row.title);
        expect(row.c).toContain('quokka');
      });
    });
  });
}