Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-156: search gates its supersession stage on SUPERSEDE_EDGE_PROBE_SQL. On a brain with no `supersedes` edge (the
* common case) the probe returns no row, so without a matching index it reads every entry of the composite links index
* (link_type is not its leading column) or the whole table. Cold, under load, that one statement stalled a warm search
* for seconds. The links_supersedes_index migration's partial index idx_links_supersedes_to holds only supersedes edges, so the probe reads
* an index with no entries. This pins the planner's choice for the exact probe text on a populated links table.
* Regression that fails it: the probe binds link_type as a parameter, or the partial index is dropped (the control).
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import postgres from '#postgres';
import type { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { SUPERSEDE_EDGE_PROBE_SQL } from '../../src/core/search/hybrid.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { seedPage } from '../helpers/keyword-paging-fixture.ts';
const run = process.env.DATABASE_URL ? describe : describe.skip;
let engine: PostgresEngine;
let databaseUrl = '';
let close: () => Promise<void> = async () => {};
interface PlanNode { 'Node Type': string; 'Index Name'?: string; 'Relation Name'?: string; Plans?: PlanNode[] }
const nodes = (node: PlanNode): PlanNode[] => [node, ...(node.Plans ?? []).flatMap(nodes)];
async function plan(sql: ReturnType<typeof postgres>, statement: string): Promise<PlanNode[]> {
const rows = await sql.unsafe(`EXPLAIN (FORMAT JSON) ${statement}`) as Array<{ 'QUERY PLAN': Array<{ Plan: PlanNode }> }>;
return nodes(rows[0]!['QUERY PLAN'][0]!.Plan);
}
const usesPartialIndex = (plan: PlanNode[]) => plan.some(n => /^Index (Only )?Scan$/.test(n['Node Type']) && n['Index Name'] === 'idx_links_supersedes_to');
const readsLinksOtherwise = (plan: PlanNode[]) => plan.some(n => n['Index Name'] === 'links_from_to_type_source_origin_unique' || (n['Node Type'] === 'Seq Scan' && n['Relation Name'] === 'links'));
run('the supersede-edge probe reads the supersedes partial index, never the composite links index', () => {
beforeAll(async () => {
const isolated = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
engine = isolated.engine;
databaseUrl = isolated.databaseUrl;
close = isolated.close;
for (let i = 0; i < 40; i++) await seedPage(engine, `notes/ledger-${i}`, `Ledger entry ${i}.`);
await engine.executeRaw(`INSERT INTO links (from_page_id, to_page_id, link_type, link_source)
SELECT f.id, t.id, ty, 's' || s FROM pages f, pages t, unnest(ARRAY['mentions', 'relates_to', 'works_at']) AS ty, generate_series(1, 10) AS s
WHERE f.id <> t.id`);
await engine.executeRaw('ANALYZE links');
}, 300_000);
afterAll(async () => { await close(); });
test('with no supersedes edge, and with a few, the exact probe text plans an index scan on idx_links_supersedes_to', async () => {
const sql = postgres(databaseUrl, { max: 1, prepare: false, onnotice: () => {} });
try {
expect(Number((await sql.unsafe('SELECT count(*)::int AS n FROM links') as Array<{ n: number }>)[0]!.n)).toBeGreaterThan(40_000);
const empty = await plan(sql, SUPERSEDE_EDGE_PROBE_SQL);
expect(usesPartialIndex(empty)).toBe(true);
expect(readsLinksOtherwise(empty)).toBe(false);
expect(await engine.executeRaw(SUPERSEDE_EDGE_PROBE_SQL)).toEqual([]);
await sql.unsafe(`INSERT INTO links (from_page_id, to_page_id, link_type, link_source)
SELECT f.id, t.id, 'supersedes', 's1' FROM pages f JOIN pages t ON t.id = f.id + 1 LIMIT 5`);
await sql.unsafe('ANALYZE links');
const some = await plan(sql, SUPERSEDE_EDGE_PROBE_SQL);
expect(usesPartialIndex(some)).toBe(true);
expect(readsLinksOtherwise(some)).toBe(false);
expect(await engine.executeRaw(SUPERSEDE_EDGE_PROBE_SQL)).toEqual([{ one: 1 }]);
await sql.unsafe(`DELETE FROM links WHERE link_type = 'supersedes'`);
} finally { await sql.end(); }
});
test('control: without the partial index the same probe reads the composite index or the table (the stall shape)', async () => {
const sql = postgres(databaseUrl, { max: 1, prepare: false, onnotice: () => {} });
try {
await sql.unsafe('BEGIN');
await sql.unsafe('DROP INDEX idx_links_supersedes_to');
const without = await plan(sql, SUPERSEDE_EDGE_PROBE_SQL);
await sql.unsafe('ROLLBACK');
expect(usesPartialIndex(without)).toBe(false);
expect(readsLinksOtherwise(without)).toBe(true);
expect(usesPartialIndex(await plan(sql, SUPERSEDE_EDGE_PROBE_SQL))).toBe(true);
} finally { await sql.end(); }
});
});