Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.8 KB
Raw Blame
/**
 * #6281: an alias-resolving snapshot read never scans every page.
 *
 * Protects: `readPageSnapshot` with `resolveAlias` (get_page's alias hit and miss, fetch's `requireUnambiguous`
 * exact hit), scoped to the caller's readable sources as every caller scopes it, visits only a handful of `pages` rows
 * on a brain with thousands of pages, measured from
 * EXPLAIN (ANALYZE, FORMAT JSON) of each statement it sends, on PGLite and Postgres; and the alias semantics hold
 * (exact outranks alias, source preference, ambiguity across sources, preserveExactIdentity, deleted target,
 * archived alias source, includeDeleted). Regression it catches: `slug=$1 OR EXISTS(alias)`, which reads every page.
 * No wall-clock thresholds.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { readPageSnapshot } from '../src/core/page-state/snapshot.ts';
import { PageSnapshotAmbiguousError } from '../src/core/page-state/types.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';

const FILLER = 12_000;

type PlanNode = { 'Relation Name'?: string; 'Actual Rows'?: number; 'Actual Loops'?: number; 'Rows Removed by Filter'?: number; 'Rows Removed by Index Recheck'?: number; Plans?: PlanNode[] };
function pagesVisited(node: PlanNode): number {
  const own = node['Relation Name'] === 'pages'
    ? ((node['Actual Rows'] ?? 0) + (node['Rows Removed by Filter'] ?? 0) + (node['Rows Removed by Index Recheck'] ?? 0)) * (node['Actual Loops'] ?? 1) : 0;
  return own + (node.Plans ?? []).reduce((sum, child) => sum + pagesVisited(child), 0);
}

for (const kind of testBackends()) {
  describe(`alias snapshot reads use the indexes (${kind})`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    beforeAll(async () => {
      if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
      else { const lite = new PGLiteEngine(); await lite.connect({}); await lite.initSchema(); engine = lite; close = () => lite.disconnect(); }
      await engine.executeRaw("INSERT INTO sources(id,name) VALUES ('alt','alt'),('gone','gone') ON CONFLICT (id) DO NOTHING");
      for (const source of ['default', 'alt']) {
        await engine.executeRaw(`INSERT INTO pages(source_id,slug,type,title,compiled_truth)
          SELECT $1, 'filler/p-' || g, 'note', 'Filler ' || g, 'filler body' FROM generate_series(1, $2::int) g`, [source, FILLER / 2]);
      }
      const put = (slug: string, sourceId: string, frontmatter: Record<string, unknown> = {}) =>
        engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `${slug} body`, frontmatter }, { sourceId });
      await put('people/alice-example', 'default');
      await put('people/alice-example', 'alt');
      await put('people/bob-example', 'default');
      await put('people/ann-example', 'default');
      await put('people/private-example', 'default', { visibility: 'private' });
      await put('people/carol-example', 'default');
      await put('people/carol-example', 'gone');
      await engine.executeRaw(`INSERT INTO slug_aliases(source_id,alias_slug,canonical_slug) VALUES
        ('default','bob','people/bob-example'),
        ('default','alice','people/alice-example'),('alt','alice','people/alice-example'),
        ('default','people/ann-example','people/bob-example'),
        ('default','people/private-example','people/carol-example'),
        ('gone','carol','people/carol-example')`);
      await engine.executeRaw("UPDATE sources SET archived=true WHERE id='gone'");
      await engine.executeRaw('ANALYZE pages');
      await engine.executeRaw('ANALYZE slug_aliases');
    }, 180_000);
    afterAll(async () => { await close?.(); });

    async function visits(slug: string, opts: Parameters<typeof readPageSnapshot>[2]) {
      const counts: number[] = [];
      const query = async <T,>(sql: string, params?: unknown[]): Promise<T[]> => {
        if (sql.trimStart().startsWith('WITH chosen')) {
          const [plan] = await engine.executeRaw<{ 'QUERY PLAN': unknown }>(`EXPLAIN (ANALYZE, FORMAT JSON) ${sql}`, params);
          const parsed = (typeof plan!['QUERY PLAN'] === 'string' ? JSON.parse(plan!['QUERY PLAN'] as string) : plan!['QUERY PLAN']) as Array<{ Plan: PlanNode }>;
          counts.push(pagesVisited(parsed[0]!.Plan));
        }
        return engine.executeRaw<T>(sql, params);
      };
      const snapshot = await readPageSnapshot(query as Parameters<typeof readPageSnapshot>[0], slug, opts).catch((error: unknown) => error);
      return { counts, snapshot };
    }

    test.each([
      ['get_page alias hit', 'bob', { resolveAlias: true, sourceIds: ['default', 'alt'] }],
      ['get_page alias hit in one source', 'bob', { resolveAlias: true, sourceId: 'default' }],
      ['get_page miss', 'nobody-example', { resolveAlias: true, sourceIds: ['default', 'alt'] }],
      ['fetch exact hit across sources', 'people/bob-example', { resolveAlias: true, requireUnambiguous: true, sourceIds: ['default', 'alt'] }],
      ['fetch exact hit in one source', 'people/bob-example', { resolveAlias: true, requireUnambiguous: true, sourceId: 'default' }],
      ['private exact with preserveExactIdentity', 'people/private-example', { resolveAlias: true, excludePrivate: true, preserveExactIdentity: true, sourceIds: ['default', 'alt'] }],
    ] as Array<[string, string, NonNullable<Parameters<typeof readPageSnapshot>[2]>]>)('%s visits fewer than 100 pages rows per statement', async (_name, slug, opts) => {
      const { counts } = await visits(slug, opts);
      expect(counts.length).toBeGreaterThan(0);
      for (const count of counts) expect(count).toBeLessThan(100);
    });

    test('semantics: exact outranks alias, alias resolves, source preference, ambiguity, preserveExactIdentity, archived alias source', async () => {
      const read = (slug: string, opts: Parameters<typeof readPageSnapshot>[2]) => readPageSnapshot((sql, params) => engine.executeRaw(sql, params), slug, opts);
      expect((await read('people/ann-example', { resolveAlias: true }))?.page.slug).toBe('people/ann-example');
      expect((await read('bob', { resolveAlias: true }))?.page.slug).toBe('people/bob-example');
      expect((await read('alice', { resolveAlias: true, sourceIds: ['alt', 'default'] }))?.page.source_id).toBe('alt');
      expect((await read('alice', { resolveAlias: true }))?.page.source_id).toBe('default');
      await expect(read('alice', { resolveAlias: true, requireUnambiguous: true })).rejects.toBeInstanceOf(PageSnapshotAmbiguousError);
      expect((await read('people/bob-example', { resolveAlias: true, requireUnambiguous: true, sourceId: 'default' }))?.page.slug).toBe('people/bob-example');
      expect(await read('people/private-example', { resolveAlias: true, excludePrivate: true, preserveExactIdentity: true })).toBeNull();
      expect((await read('people/private-example', { resolveAlias: true, excludePrivate: true }))?.page.slug).toBe('people/carol-example');
      expect(await read('carol', { resolveAlias: true })).toBeNull();
      expect((await read('carol', { resolveAlias: true, includeDeleted: true }))?.page.source_id).toBe('gone');
      expect(await read('nobody-example', { resolveAlias: true })).toBeNull();
      await engine.executeRaw("UPDATE pages SET deleted_at=now() WHERE slug='people/bob-example' AND source_id='default'");
      try {
        expect(await read('bob', { resolveAlias: true })).toBeNull();
        expect((await read('bob', { resolveAlias: true, includeDeleted: true }))?.page.slug).toBe('people/bob-example');
      } finally { await engine.executeRaw("UPDATE pages SET deleted_at=NULL WHERE slug='people/bob-example' AND source_id='default'"); }
    });
  });
}