Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #7147: a one-shot read verb through a transaction-mode pooler pays one
* network round trip per statement, so startup statements are the wall clock
* of every `gbrain entity` / `gbrain get` call. This pins the statements a cold
* read spends on the config table and on managed-writer maintenance, counted
* at the socket by the wire trace (`GBRAIN_SQL_TRACE`), never in milliseconds.
*
* Protects: a read verb reads the config table through one snapshot per phase
* (startup, then the context build and the operation) instead of one
* statement per key, skips the
* retired-marker cleanup a read never depends on, and shows the pooler banner
* once per database. Regressions it catches: a new per-key `getConfig` on the
* read path outside a snapshot, the cleanup running for reads again, or the
* banner printing on every call. Existing budget tests cover page writes and
* imports, not CLI read startup. The second half pins the statements the
* follow-up folded: one config snapshot shared by startup and the read, one
* sources read, the custody row without a table probe, the search-statistics
* guard as one statement, and a two-connection pool for a one-shot read.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runCli } from '../helpers/cli-spawn.ts';
import { readSqlTrace, type StatementRecord } from '../helpers/statement-counter.ts';
import { getEngine, hasDatabase, setupDB, teardownDB } from './helpers.ts';
const describeDatabase = hasDatabase() ? describe : describe.skip;
const BANNER = 'Prepared statements and statement pipelining disabled';
function poolerUrl(): string {
const url = new URL(process.env.DATABASE_URL!);
url.searchParams.set('prepare', 'false');
return url.toString();
}
let home: string;
async function tracedRead(args: string[], name: string): Promise<{ stderr: string; statements: StatementRecord[] }> {
const trace = join(home, `${name}.ndjson`);
const r = await runCli(args, { home, cwd: home, timeoutMs: 90_000, env: { GBRAIN_SQL_TRACE: trace } });
expect(r.exitCode, r.stderr).toBe(0);
return { stderr: r.stderr, statements: readSqlTrace(trace).filter(s => s.kind === 'execute' || s.kind === 'simple' || s.kind === 'describe') };
}
/** Config-table statements, leaving out the pool's connection check (db.ts checkPoolAndLoadSharedTypes reads the schema version with it). */
const configStatements = (statements: StatementRecord[]) =>
statements.filter(s => /\bFROM\s+config\b/i.test(s.sql) && !s.sql.includes('server_version_num'));
describeDatabase('cold read verb startup through a transaction pooler (#7147)', () => {
beforeAll(async () => {
await setupDB();
await getEngine().putPage('people/alice-example', {
type: 'person', title: 'Alice Example', compiled_truth: 'Alice Example works at Acme Example.', timeline: '',
});
home = mkdtempSync(join(tmpdir(), 'gbrain-cold-read-'));
mkdirSync(join(home, '.gbrain'), { recursive: true });
writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'postgres', database_url: poolerUrl(), embedding_disabled: true }));
});
afterAll(async () => {
await teardownDB();
rmSync(home, { recursive: true, force: true });
});
test('the pooler banner prints on the first call only', async () => {
const first = await tracedRead(['entity', 'Alice Example'], 'banner-1');
expect(first.stderr).toContain(BANNER);
const second = await tracedRead(['entity', 'Alice Example'], 'banner-2');
expect(second.stderr).not.toContain(BANNER);
}, 180_000);
for (const args of [['entity', 'Alice Example'], ['get', 'people/alice-example']]) {
test(`gbrain ${args[0]}: config reads come from snapshots, and no retired-marker cleanup runs`, async () => {
const { statements } = await tracedRead(args, `budget-${args[0]}`);
const config = configStatements(statements);
expect(config.length, config.map(s => s.sql).join('\n')).toBeLessThanOrEqual(2);
expect(statements.filter(s => s.sql.includes('persistence_topology_changes'))).toEqual([]);
}, 120_000);
}
/**
* #7147 follow-up: each statement below was a round trip every cold read paid. A read shares one config snapshot
* between startup and the operation (one bulk read, no per-key read), reads the sources table once for tier 4,
* tier 5.5 and the federated set, reads the graduation custody row without a to_regclass probe first, and opens at
* most two pooled connections. Each assertion fails on the base branch.
*/
const sql = (s: StatementRecord) => s.sql.replace(/\s+/g, ' ').trim();
const show = (rows: StatementRecord[]) => rows.map(sql).join('\n');
for (const args of [['search', 'Acme'], ['query', 'who works at Acme'], ['get', 'people/alice-example'], ['entity', 'Alice Example'], ['recall', 'Alice Example']]) {
test(`gbrain ${args[0]}: one config read, one sources read, one custody read, two connections`, async () => {
const { statements } = await tracedRead(args, `folded-${args[0]}`);
const config = configStatements(statements);
expect(config.map(sql), show(config)).toEqual(['SELECT key, value FROM config']);
const sources = statements.filter(s => /\bFROM\s+sources\b/i.test(s.sql) && !/\bJOIN\s+sources\b/i.test(s.sql) && /^\s*SELECT\s+id\b/i.test(s.sql));
expect(sources.length, show(sources)).toBe(1);
expect(statements.filter(s => s.sql.includes("to_regclass('persistence_graduation')"))).toEqual([]);
expect(statements.filter(s => /\bFROM\s+persistence_graduation\b/.test(s.sql)).length).toBe(1);
expect(statements.filter(s => s.sql.includes('persistence_topology_changes'))).toEqual([]);
const connects = readSqlTrace(join(home, `folded-${args[0]}.ndjson`)).filter(s => s.kind === 'connect');
expect(connects.length).toBeLessThanOrEqual(2);
}, 120_000);
}
test('gbrain search: the search-statistics guard is one statement', async () => {
const { statements } = await tracedRead(['search', 'Acme'], 'folded-statistics');
const probes = statements.filter(s => s.sql.includes('pg_stats') || /reltuples::float8 AS reltuples FROM pg_class WHERE oid = 'pages'/.test(s.sql) || s.sql.includes('pg_statistic_ext'));
expect(probes.length, show(probes)).toBe(1);
}, 120_000);
test('GBRAIN_POOL_SIZE still sizes a one-shot read pool', async () => {
const trace = join(home, 'pool-size-1.ndjson');
const r = await runCli(['search', 'Acme'], { home, cwd: home, timeoutMs: 90_000, env: { GBRAIN_SQL_TRACE: trace, GBRAIN_POOL_SIZE: '1' } });
expect(r.exitCode, r.stderr).toBe(0);
expect(readSqlTrace(trace).filter(s => s.kind === 'connect').length).toBe(1);
}, 120_000);
});