Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.1 KB
Raw Blame
/**
 * GBRA-156: the projection-readiness probe runs on every search and query and
 * a cold CLI process cannot reuse a cached answer. The planner has no
 * statistics for `text_projection_revision IS DISTINCT FROM knowledge_revision`,
 * so an EXISTS over it chose a sequential scan of pages that expected to stop
 * at the first row; on a sealed brain it read every page (~600 ms at 600k
 * pages). Pins the plan on real Postgres with analyzed, fully sealed filler
 * pages: the probe walks a partial index and no sequential scan of pages runs.
 * Since #9192 that index is idx_pages_projection_waiting (v317), which also
 * leaves out pages still served from their pre-upgrade index.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { BrainEngine } from '../../src/core/engine.ts';
import { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { probeProjectionReadiness, type ProjectionReadinessScope } from '../../src/core/search/projection-readiness.ts';
import { ACTIVATION_SERVED_REVISION } from '../../src/core/search/safe-chunks.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { withEnv } from '../helpers/with-env.ts';
import { hasDatabase } from './helpers.ts';

const describePostgres = hasDatabase() ? describe : describe.skip;

describePostgres('projection readiness probe plan on Postgres (GBRA-156)', () => {
  let engine: BrainEngine;
  let close: () => Promise<void>;
  let databaseUrl: string;

  beforeAll(async () => {
    ({ engine, close, databaseUrl } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
    await engine.executeRaw("INSERT INTO sources(id,name) VALUES ('source-a','source-a'),('source-b','source-b') ON CONFLICT DO NOTHING");
    await engine.executeRaw(`INSERT INTO pages(source_id,slug,title,type,page_kind,compiled_truth,chunker_version,frontmatter)
      SELECT CASE WHEN i % 2 = 0 THEN 'source-a' ELSE 'source-b' END, 'filler-' || i, 'Filler ' || i, 'concept',
        CASE WHEN i % 5 = 0 THEN 'code' ELSE 'markdown' END, 'filler body ' || i, 999, '{}'::jsonb
      FROM generate_series(1, 20000) AS i`);
    await engine.executeRaw('UPDATE pages SET text_projection_revision=knowledge_revision');
    await engine.executeRaw('ANALYZE pages');
    await engine.executeRaw('ANALYZE sources');
  }, 120_000);

  afterAll(async () => { await close?.(); });

  async function probeStatement(scope: ProjectionReadinessScope) {
    const captured: Array<{ sql: string; params?: unknown[] }> = [];
    const recording = { executeRaw: (sql: string, params?: unknown[]) => {
      captured.push({ sql, params });
      return engine.executeRaw(sql, params);
    } } as unknown as BrainEngine;
    const result = await withEnv({ GBRAIN_PROJECTION_READINESS_CACHE: '0' }, () => probeProjectionReadiness(recording, scope));
    const probe = captured.find(call => call.sql.includes('IS DISTINCT FROM'));
    expect(probe).toBeDefined();
    return { result, probe: probe! };
  }

  async function plan(sql: string, params?: unknown[]): Promise<string> {
    return (await engine.executeRaw<Record<string, string>>(`EXPLAIN (ANALYZE, COSTS OFF) ${sql}`, params)).map(row => Object.values(row)[0]).join('\n');
  }

  for (const [name, scope] of [
    ['every source', {}],
    ['one source', { sourceId: 'source-a' }],
    ['a source grant without private pages', { sourceIds: ['source-a', 'source-b'], excludePrivate: true }],
  ] as Array<[string, ProjectionReadinessScope]>) {
    test(`a sealed brain answers ready from the partial index without scanning pages (${name})`, async () => {
      const { result, probe } = await probeStatement(scope);
      expect(result).toEqual({ status: 'ready', ready: true });
      const text = await plan(probe.sql, probe.params);
      expect(text).toMatch(/Index Scan using idx_pages_projection_waiting on pages p\b/);
      // The private-visibility clause carries lazily evaluated subplans over pages; none may run.
      expect(text.split('\n').filter(line => line.includes('Seq Scan on pages') && !line.includes('never executed'))).toEqual([]);
    });
  }

  test('one unsealed page among the sealed filler is still found', async () => {
    await engine.executeRaw("UPDATE pages SET text_projection_revision=NULL WHERE slug='filler-7'");
    try {
      expect((await probeStatement({ sourceId: 'source-b' })).result.status).toBe('projection_pending');
      expect((await probeStatement({ sourceId: 'source-a' })).result.status).toBe('ready');
      expect((await probeStatement({})).result.status).toBe('projection_pending');
    } finally {
      await engine.executeRaw("UPDATE pages SET text_projection_revision=knowledge_revision WHERE slug='filler-7'");
    }
  });

  // #8033: a remote caller's private-visibility subplans lift the estimate past jit_above_cost, and compiling them
  // cost nearly all of the probe's time. The session below compiles every statement that keeps JIT on.
  test('the probe runs with JIT off for a remote scope (#8033)', async () => {
    const reader = new PostgresEngine();
    await reader.connect({ database_url: databaseUrl, poolSize: 1 });
    try {
      await reader.executeRaw('SET jit = on');
      await reader.executeRaw('SET jit_above_cost = 0');
      const explain = async (sql: string, params?: unknown[], opts?: Parameters<BrainEngine['executeRaw']>[2]) =>
        JSON.stringify((await reader.executeRaw<Record<string, unknown>>(`EXPLAIN (ANALYZE, FORMAT JSON) ${sql}`, params, opts))[0]);
      const plans: Array<{ asRun: string; jitOn: string }> = [];
      const recording = { executeRaw: async (sql: string, params?: unknown[], opts?: Parameters<BrainEngine['executeRaw']>[2]) => {
        if (sql.includes('IS DISTINCT FROM')) plans.push({ asRun: await explain(sql, params, opts), jitOn: await explain(sql, params) });
        return reader.executeRaw(sql, params, opts);
      } } as unknown as BrainEngine;
      const result = await withEnv({ GBRAIN_PROJECTION_READINESS_CACHE: '0' }, () =>
        probeProjectionReadiness(recording, { sourceIds: ['source-a', 'source-b'], excludePrivate: true, requireSafeChunks: true }));
      expect(result).toEqual({ status: 'ready', ready: true });
      expect(plans).toHaveLength(1);
      expect(plans[0].jitOn.includes('"JIT"')).toBe(true);
      expect(plans[0].asRun.includes('"JIT"')).toBe(false);
    } finally {
      await reader.disconnect();
    }
  });

  // #9192: pages v153 left serving their pre-upgrade index are unsealed but not pending. The probe reads
  // idx_pages_projection_waiting, which leaves them out, instead of stepping over each one in idx_pages_projection_pending.
  test('a brain of pages still served from their pre-upgrade index answers ready without walking them (#9192)', async () => {
    await engine.executeRaw(`UPDATE pages SET text_projection_revision='${ACTIVATION_SERVED_REVISION}'::uuid`);
    try {
      await engine.executeRaw('ANALYZE pages');
      const { result, probe } = await probeStatement({});
      expect(result).toEqual({ status: 'ready', ready: true });
      const text = await plan(probe.sql, probe.params);
      expect(text).toMatch(/Index Scan using idx_pages_projection_waiting on pages p\b/);
      expect(text).not.toContain('Rows Removed by Filter');
    } finally {
      await engine.executeRaw('UPDATE pages SET text_projection_revision=knowledge_revision');
      await engine.executeRaw('ANALYZE pages');
    }
  });

  test('a brain with many pending pages answers pending without the by_design walk (#8000)', async () => {
    await engine.executeRaw("UPDATE pages SET text_projection_revision=NULL WHERE source_id='source-a'");
    try {
      await engine.executeRaw('ANALYZE pages');
      const { result, probe } = await probeStatement({ sourceId: 'source-a' });
      expect(result.status).toBe('projection_pending');
      const text = await plan(probe.sql, probe.params);
      expect(text.split('\n').filter(line => / on pages p(_\d+)? /.test(line) && !line.includes('never executed'))).toHaveLength(1);
    } finally {
      await engine.executeRaw("UPDATE pages SET text_projection_revision=knowledge_revision WHERE source_id='source-a'");
      await engine.executeRaw('ANALYZE pages');
    }
  });
});