Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6278 (plan item 1.4): `boundedReads`, the engine view a preparer reads
* through. Protects: a raw statement runs with `timeoutMs` set to the clock's
* remaining budget and the clock's signal (which ends only the wait for a
* connection); a caller's own signal keeps its statement unbounded; the view
* is the engine itself without a deadline or on PGLite; a statement the
* server ends at the bound (57014, or a 55P03 lock timeout) surfaces as the
* member's `preparation_deadline` (the signal's reason once it aborted, the
* typed error naming the step before that), which `preparationAbortReason`
* classifies as the deadline, never a terminal failure; any other error
* passes through; and a group's shared read (`preparationReads`) answers a
* bounded read once with the bound and signal dropped. Fails when the bound
* stops reaching the statement, when a server timeout is left as a raw
* Postgres error (a `storage_error` receipt), or when a member's bound leaks
* into a sibling's shared read.
*/
import { expect, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import { boundedReads, isStatementTimeout, PreparationDeadlineError } from '../src/core/persistence/bounded-reads.ts';
import { startClaimPhase, enterClaimStep } from '../src/core/persistence/claim-phase.ts';
import { preparationAbortReason } from '../src/core/persistence/coordinator.ts';
import { preparationReads } from '../src/core/persistence/group-publish.ts';
type Call = { sql: string; opts?: { signal?: AbortSignal; timeoutMs?: number } };
function fakeEngine(kind: 'postgres' | 'pglite', respond: (call: Call) => Promise<unknown[]>) {
const calls: Call[] = [];
const engine = { kind, executeRaw: (sql: string, _params?: unknown[], opts?: Call['opts']) => { const call = { sql, opts }; calls.push(call); return respond(call); },
getConfig: async () => null } as unknown as BrainEngine;
return { engine, calls };
}
const pgError = (code: string, message: string) => Object.assign(new Error(message), { code });
test('a raw statement runs with the remaining budget and the clock\'s signal; a caller\'s signal keeps it unbounded', async () => {
const { engine, calls } = fakeEngine('postgres', async () => [{ ok: true }]);
const cancel = new AbortController();
const clock = startClaimPhase(Date.now(), cancel.signal, 10_000);
const reads = boundedReads(engine, clock);
expect(await reads.executeRaw('SELECT 1 FROM pages')).toEqual([{ ok: true }]);
expect(calls[0]!.opts!.timeoutMs).toBeGreaterThan(9_000);
expect(calls[0]!.opts!.timeoutMs).toBeLessThanOrEqual(10_000);
expect(calls[0]!.opts!.signal).toBe(cancel.signal);
const own = new AbortController();
await reads.executeRaw('SELECT 1 FROM pages', [], { signal: own.signal });
expect(calls[1]!.opts).toEqual({ signal: own.signal });
// Other members are the engine's own.
expect(typeof reads.getConfig).toBe('function');
});
test('a read issued after the deadline is refused before it is sent: the deadline, never a fast read that finished inside the 1 ms floor', async () => {
const { engine, calls } = fakeEngine('postgres', async () => [{ ok: true }]);
const clock = startClaimPhase(Date.now() - 5_000, undefined, 1_000);
enterClaimStep(clock, 'journal_sweep');
const error = await boundedReads(engine, clock).executeRaw('SELECT 1 FROM persistence_requests').then(() => null, (e: unknown) => e);
expect(error).toBeInstanceOf(PreparationDeadlineError);
expect(preparationAbortReason(error)).toBe('preparation_deadline');
expect((error as PreparationDeadlineError).sqlstate).toBeNull();
expect((error as PreparationDeadlineError).message).toContain('at step journal_sweep was not sent');
expect(calls).toHaveLength(0);
const cancel = new AbortController();
const aborted = startClaimPhase(Date.now() - 5_000, cancel.signal, 1_000);
cancel.abort(new Error('claim released'));
await expect(boundedReads(engine, aborted).executeRaw('SELECT 1 FROM persistence_requests')).rejects.toThrow('claim released');
expect(calls).toHaveLength(0);
});
test('without a deadline, or on PGLite, the view is the engine itself', () => {
const { engine } = fakeEngine('postgres', async () => []);
expect(boundedReads(engine, undefined)).toBe(engine);
expect(boundedReads(engine, startClaimPhase(Date.now(), new AbortController().signal))).toBe(engine);
const pglite = fakeEngine('pglite', async () => []).engine;
expect(boundedReads(pglite, startClaimPhase(Date.now(), undefined, 5_000))).toBe(pglite);
});
test('a statement the server ends at the bound is the member\'s preparation_deadline; the signal\'s reason once it aborted; other errors pass through', async () => {
let fail: unknown = pgError('57014', 'canceling statement due to statement timeout');
const { engine } = fakeEngine('postgres', async () => { throw fail; });
const cancel = new AbortController();
const clock = startClaimPhase(Date.now(), cancel.signal, 10_000);
enterClaimStep(clock, 'origin_check', undefined, 'db');
const reads = boundedReads(engine, clock);
const error = await reads.executeRaw('SELECT id FROM pages').catch(e => e);
expect(error).toBeInstanceOf(PreparationDeadlineError);
expect(error).toMatchObject({ code: 'preparation_deadline', step: 'origin_check', sqlstate: '57014' });
expect(error.message).toContain('step origin_check');
expect(preparationAbortReason(error, cancel.signal)).toBe('preparation_deadline');
// A shorter session lock_timeout raised by the same lock wait is the same deadline.
fail = pgError('55P03', 'canceling statement due to lock timeout');
expect(await reads.executeRaw('SELECT id FROM pages').catch(e => e)).toMatchObject({ code: 'preparation_deadline', sqlstate: '55P03' });
// Any other failure is the preparer's own.
fail = pgError('42P01', 'relation "pages" does not exist');
expect(await reads.executeRaw('SELECT id FROM pages').catch(e => e)).toBe(fail);
expect(isStatementTimeout(fail)).toBe(false);
// The budget passed on this side first: the error is the abort reason the consumer already knows.
fail = pgError('57014', 'canceling statement due to statement timeout');
cancel.abort({ code: 'group_member_waiting' });
expect(await reads.executeRaw('SELECT id FROM pages').catch(e => e)).toEqual({ code: 'group_member_waiting' });
});
test('a group\'s shared read answers a bounded read once, with the member\'s bound and signal dropped', async () => {
const STABLE = 'SELECT local_path FROM sources WHERE id=$1';
const { engine, calls } = fakeEngine('postgres', async () => [{ local_path: '/brain' }]);
const shared = preparationReads(engine);
const a = startClaimPhase(Date.now(), new AbortController().signal, 10_000), b = startClaimPhase(Date.now(), new AbortController().signal, 10_000);
const [readA, readB] = await Promise.all([boundedReads(shared, a).executeRaw(STABLE, ['default']), boundedReads(shared, b).executeRaw(STABLE, ['default'])]);
expect(readA).toEqual([{ local_path: '/brain' }]);
expect(readB).toEqual([{ local_path: '/brain' }]);
expect(calls).toEqual([{ sql: STABLE, opts: undefined }]);
// An unmemoized read keeps its own bound.
await boundedReads(shared, a).executeRaw('SELECT id FROM pages WHERE source_id=$1', ['default']);
expect(calls[1]!.opts!.timeoutMs).toBeGreaterThan(0);
expect(calls[1]!.opts!.signal).toBe(a.signal);
});