Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { randomBytes, randomUUID } from 'node:crypto';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { localHostId, withVerifiedLocalRegistration, type LocalGrant, type LocalRegistration } from '../src/core/persistence/identity.ts';
import { submissionAuthority } from '../src/core/persistence/authority.ts';
import { admitWrite, getWriteRequest } from '../src/core/persistence/journal.ts';
import { sha256 } from '../src/core/persistence/digest.ts';
const RECEIPTS = ['get_write_request', 'list_write_requests', 'cancel_write_request'];
let engine: PGLiteEngine;
let source: string;
let otherSource: string;
let owner: LocalRegistration;
let foreign: LocalRegistration;
let sequence = 0;
const grant = (): LocalGrant => ({ sourceIds: ['*'], operations: ['put_page', ...RECEIPTS], scopes: ['read', 'write'], slugPrefixes: null });
const context = (target: BrainEngine = engine, sourceId = source): OperationContext => ({
engine: target, config: { engine: 'pglite' }, remote: false, sourceId, dryRun: false,
logger: { info() {}, warn() {}, error() {} },
});
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 60_000);
afterAll(async () => { await engine?.disconnect(); });
async function registration(): Promise<LocalRegistration> {
const local: LocalRegistration = { id: randomUUID(), credential: randomBytes(32).toString('hex'), lane: 'cli' };
await engine.executeRaw('INSERT INTO persistence_local_writers(id,lane,credential_hash,grant_ceiling) VALUES($1,$2,$3,$4::jsonb)',
[local.id, local.lane, sha256(local.credential), JSON.stringify(grant())]);
return local;
}
beforeEach(async () => {
source = `receipt-op-${++sequence}`;
otherSource = `receipt-other-${sequence}`;
await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1),($2,$2)', [source, otherSource]);
owner = await registration(); foreign = await registration();
});
async function setGrant(local: LocalRegistration, patch: Partial<LocalGrant>) {
const [row] = await engine.executeRaw<{ grant_ceiling: LocalGrant }>('SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1', [local.id]);
await engine.executeRaw('UPDATE persistence_local_writers SET grant_ceiling=$2::jsonb WHERE id=$1', [local.id, JSON.stringify({ ...row.grant_ceiling, ...patch })]);
}
async function accept(local = owner, slug = 'allowed/page', sourceId = source, requestId = randomUUID()) {
return withVerifiedLocalRegistration(engine, local, async () => {
const [s] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation FROM sources WHERE id=$1', [sourceId]);
const authority = await submissionAuthority(context(engine, sourceId), 'put_page', sourceId, s.incarnation, slug);
return admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId,
sourceIncarnation: s.incarnation, slug, requestId,
callerIntent: { content: 'PRIVATE_INPUT_MARKER' }, intent: { content: 'PRIVATE_INPUT_MARKER' } });
});
}
async function call(name: string, params: Record<string, unknown>, local = owner, ctx = context()): Promise<any> {
const op = operations.find(operation => operation.name === name)!;
return withVerifiedLocalRegistration(ctx.engine, local, () => op.handler(ctx, params));
}
describe('own-principal write receipt operations', () => {
test('one hundred authorized receipts use one projected diagnostic query', async () => {
for (let i = 0; i < 100; i++) await accept(owner, `allowed/batch-${i}`);
let queries = 0;
const proxy = new Proxy(engine, { get(target, key) {
if (key === 'executeRaw') return async (...args: Parameters<typeof engine.executeRaw>) => {
if (args[0].includes('WITH roots AS')) {
queries++;
expect(args[0]).not.toContain('r.*');
expect(args[0]).not.toContain('intent');
expect((args[1]![0] as string[])).toHaveLength(1);
}
return target.executeRaw(...args);
};
const value = Reflect.get(target, key);
return typeof value === 'function' ? value.bind(target) : value;
} });
const result = await call('list_write_requests', { limit: 100 }, owner, context(proxy));
expect(result.requests).toHaveLength(100);
expect(queries).toBe(1);
expect(result.requests.every((row: any) => row.diagnostic.observed_at)).toBe(true);
expect(JSON.stringify(result)).not.toContain('PRIVATE_');
await expect(call('get_write_request', { request_id: randomUUID() }, foreign, context(proxy))).rejects.toMatchObject({ code: 'not_found' });
expect(queries).toBe(1);
});
test('a foreign FIFO head yields only a coarse dependency after own authorization', async () => {
const first = await accept(foreign, 'PRIVATE_FOREIGN_HEAD');
const own = await accept(owner, 'allowed/follower');
const receipt = await call('get_write_request', { request_id: own.request_id });
expect(receipt.diagnostic).toMatchObject({ assessment: 'blocked', reason: 'waiting_on_earlier_write', next_action: 'poll' });
expect(receipt.retry_after_ms).toBe(5000);
expect(JSON.stringify(receipt)).not.toContain(first.request_id);
expect(JSON.stringify(receipt)).not.toContain('PRIVATE_');
});
test('another source sharing a worktree contributes no predecessor identity to health', async () => {
const first = await accept(foreign, 'PRIVATE_OTHER_SOURCE_HEAD', otherSource);
const own = await accept();
const worktree = randomUUID();
await engine.executeRaw('INSERT INTO persistence_worktrees(id,owner_host_id) VALUES($1,$2)', [worktree, localHostId()]);
await engine.executeRaw('UPDATE persistence_requests SET worktree_id=$2 WHERE id=ANY($1::uuid[])', [[first.id, own.id], worktree]);
const result = await call('list_write_requests', {});
expect(result.requests).toHaveLength(1);
expect(result.requests[0].diagnostic.reason).toBe('waiting_on_earlier_write');
for (const hidden of [first.id, first.request_id, otherSource, 'PRIVATE_OTHER_SOURCE_HEAD']) expect(JSON.stringify(result)).not.toContain(hidden);
expect(result.next).toBeNull();
});
test('source incarnation and delegated namespace changes refuse before enrichment', async () => {
const row = await accept();
let queries = 0;
const proxy = new Proxy(engine, { get(target, key) {
if (key === 'executeRaw') return async (...args: Parameters<typeof engine.executeRaw>) => {
if (args[0].includes('WITH roots AS')) queries++;
return target.executeRaw(...args);
};
const value = Reflect.get(target, key);
return typeof value === 'function' ? value.bind(target) : value;
} });
await expect(call('get_write_request', { request_id: row.request_id }, owner,
{ ...context(proxy), viaSubagent: true, allowedSlugPrefixes: ['different/*'] })).rejects.toMatchObject({ code: 'not_found' });
await engine.executeRaw('UPDATE sources SET incarnation=$2 WHERE id=$1', [source, randomUUID()]);
await expect(call('get_write_request', { request_id: row.request_id }, owner, context(proxy))).rejects.toMatchObject({ code: 'not_found' });
expect(queries).toBe(0);
});
test('authorization query failures fail closed rather than using optional diagnostic fallback', async () => {
const row = await accept();
let queries = 0;
const proxy = new Proxy(engine, { get(target, key) {
if (key === 'executeRaw') return async (...args: Parameters<typeof engine.executeRaw>) => {
if (args[0].includes('WITH roots AS')) queries++;
if (args[0].startsWith('SELECT incarnation,archived FROM sources')) throw new Error('AUTHORIZATION_DATABASE_UNAVAILABLE');
return target.executeRaw(...args);
};
const value = Reflect.get(target, key);
return typeof value === 'function' ? value.bind(target) : value;
} });
await expect(call('get_write_request', { request_id: row.request_id }, owner, context(proxy))).rejects.toThrow('AUTHORIZATION_DATABASE_UNAVAILABLE');
expect(queries).toBe(0);
});
test('get_write_request returns public metadata and never journal payload, execution or recovery bytes', async () => {
const row = await accept();
await engine.executeRaw('UPDATE persistence_requests SET execution_token=$2,recovery=$3::jsonb,error_message=$4,error_code=$5 WHERE id=$1',
[row.id, randomUUID(), JSON.stringify({ version: 1, before: 'PRIVATE_RECOVERY_MARKER' }), 'PRIVATE_DRIVER_MARKER', 'revision_conflict']);
const receipt = await call('get_write_request', { request_id: row.request_id });
expect(receipt).toMatchObject({ request_id: row.request_id, state: 'queued', operation: 'put_page', source_id: source, slug: 'allowed/page', write_error: 'revision_conflict' });
expect(JSON.stringify(receipt)).not.toContain('PRIVATE_');
for (const key of ['principal_id', 'authority', 'intent', 'execution_token', 'recovery', 'digest']) expect(receipt).not.toHaveProperty(key);
});
test('foreign and missing UUIDs have the same get/cancel not_found envelope', async () => {
const row = await accept(foreign);
for (const operation of ['get_write_request', 'cancel_write_request']) {
const errors: unknown[] = [];
for (const id of [row.request_id, randomUUID()]) {
try { await call(operation, { request_id: id }); throw new Error('Expected not_found.'); }
catch (error) { expect(error).toMatchObject({ code: 'not_found' }); errors.push((error as { toJSON(): unknown }).toJSON()); }
}
expect(errors[0]).toEqual(errors[1]);
}
});
test('the same UUID under two principals returns each principal’s own request', async () => {
const id = randomUUID();
await accept(owner, 'allowed/own', source, id);
await accept(foreign, 'allowed/foreign', source, id);
expect((await call('get_write_request', { request_id: id })).slug).toBe('allowed/own');
expect((await call('get_write_request', { request_id: id }, foreign)).slug).toBe('allowed/foreign');
});
test('list_write_requests paginates only the principal and selected source', async () => {
const first = await accept(owner, 'allowed/first');
await accept(foreign, 'allowed/foreign');
await accept(owner, 'allowed/other-source', otherSource);
const second = await accept(owner, 'allowed/second');
const page = await call('list_write_requests', { limit: 1 });
expect(page.requests.map((r: any) => r.request_id)).toEqual([second.request_id]);
expect(page.next).toBe(String(second.sequence));
const next = await call('list_write_requests', { limit: 1, before: page.next });
expect(next.requests.map((r: any) => r.request_id)).toEqual([first.request_id]);
expect(next.next).toBeNull();
expect(JSON.stringify(page)).not.toContain('PRIVATE_INPUT_MARKER');
});
test('SQL current prefix filtering reaches old visible history beyond 1000 now-hidden rows', async () => {
const first = await accept(owner, 'allowed/oldest');
await engine.executeRaw(`INSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,
slug,digest,intent,authority,intent_bytes,terminal_reservation,state,outcome)
SELECT principal_kind,principal_id,gen_random_uuid(),operation,source_id,source_incarnation,
'hidden/'||g.n,digest,NULL,authority,0,terminal_reservation,'committed','{}'::jsonb
FROM persistence_requests CROSS JOIN generate_series(1,1100) AS g(n) WHERE id=$1`, [first.id]);
await setGrant(owner, { slugPrefixes: ['allowed/*'] });
const result = await call('list_write_requests', { limit: 25 });
expect(result.requests.map((r: any) => r.request_id)).toEqual([first.request_id]);
expect(result.next).toBeNull();
});
test('regrant adds receipt access without changing the accepted write snapshot', async () => {
await setGrant(owner, { operations: ['put_page'] });
const row = await accept();
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'permission_denied' });
await setGrant(owner, { operations: ['put_page', ...RECEIPTS] });
expect((await call('get_write_request', { request_id: row.request_id })).state).toBe('queued');
const stored = await getWriteRequest(engine, row.authority.principal, row.request_id);
expect(stored!.authority.operations).toEqual(['put_page']);
await setGrant(owner, { operations: [...RECEIPTS] });
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'not_found' });
expect((await call('list_write_requests', {})).requests).toEqual([]);
});
test('read-only grants, narrowed sources, archived sources and revoked principals fail closed', async () => {
const row = await accept();
await setGrant(owner, { scopes: ['read'] });
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'permission_denied' });
await setGrant(owner, { scopes: ['read', 'write'], sourceIds: [otherSource] });
expect((await call('list_write_requests', {})).requests).toEqual([]);
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'not_found' });
await setGrant(owner, { sourceIds: ['*'] });
await engine.executeRaw('UPDATE sources SET archived=true WHERE id=$1', [source]);
expect((await call('list_write_requests', {})).requests).toEqual([]);
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'not_found' });
await engine.executeRaw('UPDATE persistence_local_writers SET revoked_at=now() WHERE id=$1', [owner.id]);
await expect(call('get_write_request', { request_id: row.request_id })).rejects.toMatchObject({ code: 'permission_denied' });
});
test('cancel_write_request cancels before publication and replay reports the same terminal state', async () => {
const row = await accept();
expect((await call('cancel_write_request', { request_id: row.request_id })).state).toBe('cancelled');
expect((await call('cancel_write_request', { request_id: row.request_id })).state).toBe('cancelled');
expect((await call('get_write_request', { request_id: row.request_id })).retry_after_ms).toBeNull();
});
test('cancel does not promise rollback once publication/recovery has started', async () => {
const row = await accept();
await engine.executeRaw("UPDATE persistence_requests SET state='recovering',publication_started=true WHERE id=$1", [row.id]);
expect((await call('cancel_write_request', { request_id: row.request_id })).state).toBe('recovering');
});
test('cancellation rechecks its own operation grant after preflight under the transaction lock', async () => {
const row = await accept();
let narrowed = false;
const proxy = new Proxy(engine, { get(target, property) {
if (property === 'executeRaw') return async (sql: string, params?: unknown[]) => {
const result = await target.executeRaw(sql, params);
if (!narrowed && sql.startsWith('SELECT * FROM persistence_requests WHERE principal_kind=')) {
narrowed = true;
await setGrant(owner, { operations: ['put_page', 'get_write_request', 'list_write_requests'] });
}
return result;
};
const value = Reflect.get(target, property);
return typeof value === 'function' ? value.bind(target) : value;
} });
await expect(call('cancel_write_request', { request_id: row.request_id }, owner, context(proxy))).rejects.toMatchObject({ code: 'permission_denied' });
expect((await getWriteRequest(engine, row.authority.principal, row.request_id))!.state).toBe('queued');
});
test('limits, UUIDs, all-source sentinels and bigint cursors validate before querying history', async () => {
for (const params of [{ limit: 0 }, { limit: 101 }, { limit: 1.5 }, { source_id: '__all__' }, { before: '-1' }, { before: '9999999999999999999' }]) {
await expect(call('list_write_requests', params)).rejects.toMatchObject({ code: 'invalid_params' });
}
// F6: any 1-128 printable ASCII id is a client request id (mapped to its UUIDv5), so only ids outside that set refuse.
for (const request_id of ['', 'two words', 'x'.repeat(129), 42]) {
await expect(call('get_write_request', { request_id })).rejects.toMatchObject({ code: 'invalid_params' });
}
await expect(call('get_write_request', { request_id: '../other' })).rejects.toMatchObject({ code: 'not_found' });
});
});