Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6712 PR 3 (L6): `gbrain sync status` costs a fixed number of statements
* however many request rows the source has.
*
* Protects: the plain status (and the --detail status) of a source with 61,000
* terminal write receipts sends exactly as many statements as with 1,000, and
* the plain status stays within its round-trip budget, so its latency is
* bounded by round trips times RTT (the 5 s target at 57 ms leaves room for
* about 87), not by the size of the journal.
* Fails when: a status read turns per row (or per receipt), or the plain
* status grows past its budget.
* GBRA-135: a stored `sync.admission` other than `normal` (left by another test
* on a shared local database) cost the plain status a 16th statement, its
* `effective` probe; the probe now rides the source read. The second test
* stores `imports_only` and fails with that statement (16 on Postgres before).
* Seams: the PGLite statement counter; Postgres through the wire trace in
* test/e2e/sync-status-statement-budget-postgres.test.ts.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { PostgresEngine } from '../src/core/postgres-engine.ts';
import { vacuumPersistenceQueues } from '../src/core/persistence/journal.ts';
import { SYNC_ADMISSION_KEY, SYNC_ADMISSION_SET_OP, syncAdmissionStatus, writeSyncAdmission } from '../src/core/persistence/sync-admission.ts';
import { readSyncStatus } from '../src/core/persistence/sync-status.ts';
import { countPgliteStatements, readSqlTrace, type StatementRecord } from './helpers/statement-counter.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
/** About 10% over the measured plain status (#6712 L6 measured 10 statements on PGLite, 14 on Postgres). */
const PLAIN_BUDGET = { pglite: 11, postgres: 15 } as const;
const home = mkdtempSync(join(tmpdir(), 'gbrain-status-budget-'));
afterAll(() => rmSync(home, { recursive: true, force: true }));
const statements = (records: StatementRecord[]) => records.filter(record => record.kind === 'execute' || record.kind === 'simple').length;
/** `rows` terminal receipts of managed imports: most committed, one in fifty failed, the newest within the last ten minutes. */
async function seed(engine: BrainEngine, sourceId: string, rows: number) {
await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
await engine.executeRaw(`INSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,slug,digest,authority,intent_bytes,
terminal_reservation,state,error_code,error_message,intent,completed_at,updated_at,admitter_version)
SELECT 'local_cli','fixture',gen_random_uuid(),'put_page',$1,(SELECT incarnation FROM sources WHERE id=$1),'notes/n'||g,md5(g::text),'{}'::jsonb,0,0,
CASE WHEN g % 50 = 0 THEN 'failed' ELSE 'committed' END, CASE WHEN g % 50 = 0 THEN 'storage_error' END, CASE WHEN g % 50 = 0 THEN 'fixture failure' END,
jsonb_build_object('kind','managed_sync_import','path','notes/n'||g||'.md'),
now() - make_interval(secs => g), now() - make_interval(secs => g), '0.60.267.0'
FROM generate_series(1,$2::int) AS g`, [sourceId, rows]);
// PGLite has no autovacuum: the resident owner keeps the queue's planner statistics current as it grows, so the
// fixture does what that owner does (without statistics the --detail summary plans a nested loop over every receipt).
await vacuumPersistenceQueues(engine);
}
for (const backend of testBackends()) {
describe(`sync status statement budget (${backend})`, () => {
const trace = join(home, `trace-${backend}.jsonl`);
let engine: BrainEngine;
let counted: <T>(run: () => Promise<T>) => Promise<StatementRecord[]>;
const sources: string[] = [];
beforeAll(async () => {
await withEnv(backend === 'postgres' ? { GBRAIN_SQL_TRACE: trace, GBRAIN_SQL_TRACE_LABEL: 'status-budget' } : {}, async () => {
if (backend === 'pglite') {
const lite = new PGLiteEngine(); await lite.connect({}); await lite.initSchema(); engine = lite;
counted = async run => { const counter = countPgliteStatements(lite); try { await run(); } finally { counter.stop(); } return counter.records; };
} else {
const pg = new PostgresEngine(); await pg.connect({ database_url: requirePostgresTestDatabase(), poolSize: 1 }); await pg.initSchema(); engine = pg;
counted = async run => {
const started = performance.timeOrigin + performance.now();
await run();
const ended = performance.timeOrigin + performance.now();
// The trace flushes every second; one more flush lands the window.
await Bun.sleep(1200);
return readSqlTrace(trace).filter(record => record.t >= started && record.t <= ended);
};
}
});
});
afterAll(async () => {
if (backend === 'postgres') for (const id of sources) await engine.executeRaw('DELETE FROM sources WHERE id=$1', [id]);
await engine?.disconnect();
});
test('a 61,000-receipt source costs the same statements as a 1,000-receipt one, within budget', async () => {
const measured: Record<string, { plain: number; detail: number }> = {};
for (const rows of [1_000, 61_000]) {
const sourceId = `status-budget-${backend}-${rows}`;
sources.push(sourceId);
await seed(engine, sourceId, rows);
const plain = await counted(() => readSyncStatus(engine, sourceId, { detail: false }));
const detail = await counted(() => readSyncStatus(engine, sourceId, { detail: true }));
measured[rows] = { plain: statements(plain), detail: statements(detail) };
}
expect(measured[61_000]).toEqual(measured[1_000]!);
expect(measured[61_000]!.plain).toBeLessThanOrEqual(PLAIN_BUDGET[backend]);
}, 300_000);
test('a restricted sync.admission costs the plain status no statement of its own', async () => {
const sourceId = `status-budget-${backend}-admission`;
sources.push(sourceId);
await seed(engine, sourceId, 1_000);
const normal = statements(await counted(() => readSyncStatus(engine, sourceId, { detail: false })));
await writeSyncAdmission(engine, 'imports_only');
try {
let admission: Awaited<ReturnType<typeof readSyncStatus>>['admission'] | undefined;
const restricted = statements(await counted(async () => { admission = (await readSyncStatus(engine, sourceId, { detail: false })).admission; }));
const [{ incarnation }] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
expect(admission).toEqual(await syncAdmissionStatus(engine, sourceId, incarnation!));
expect(admission).toMatchObject({ value: 'imports_only', effective: true });
expect(restricted).toBe(normal);
} finally {
await engine.unsetConfig(SYNC_ADMISSION_KEY);
await engine.executeRaw('DELETE FROM op_checkpoints WHERE op=$1', [SYNC_ADMISSION_SET_OP]);
}
}, 300_000);
});
}