Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Lane: unit. Run: `bun test test/fact-backfill-resident.test.ts`. Moved from test/e2e/
* by the 2026-09 lane-move pilot (PGLite-only, no DATABASE_URL); see
* docs/test-audit/2026-09-29/implementation/lane-pilot.md.
*/
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { createHash } from 'node:crypto';
import { once } from 'node:events';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { saveConfig, type GBrainConfig } from '../src/core/config.ts';
import { createPersistenceIpcProvider } from '../src/core/persistence/provider.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { readLocalWriter, registerLocalWriter, revokeLocalWriter, type LocalRegistration, type LocalGrant } from '../src/core/persistence/identity.ts';
import { startPersistenceIpcServer, requestPersistenceAdministration, requestPersistenceCapabilities, persistenceSocketPathForConfig, type PersistenceIpcBinding } from '../src/core/persistence/ipc.ts';
import { withEnv } from './helpers/with-env.ts';
const sourceId = 'resident-facts-example';
const foreignSource = 'resident-facts-foreign';
let root: string;
let engine: PGLiteEngine;
let binding: PersistenceIpcBinding;
let registration: LocalRegistration;
let brainId: string;
let calls: number;
let selectedConfig: GBrainConfig;
const inHome = <T>(run: () => Promise<T>) => withEnv({
GBRAIN_HOME: root, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: undefined,
DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined,
}, run);
const config = () => ({ engine: 'pglite' as const, database_path: join(root, 'db'), embedding_disabled: false });
beforeAll(async () => {
root = mkdtempSync(join(tmpdir(), 'gbrain-facts-resident-'));
await inHome(async () => {
configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: {} });
engine = new PGLiteEngine();
await engine.connect({ database_path: config().database_path });
await engine.initSchema();
for (const id of [sourceId, foreignSource]) await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [id]);
});
});
beforeEach(async () => inHome(async () => {
saveConfig(config());
configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'test-key' } });
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
await engine.executeRaw('DELETE FROM facts');
await engine.setConfig('embedding_model', 'openai:text-embedding-3-small');
await engine.setConfig('embedding_dimensions', '1536');
await engine.setConfig('embedding_disabled', 'false');
for (const [claim, source] of [['one', sourceId], ['two', sourceId], ['foreign', foreignSource]]) {
await engine.insertFact({ fact: claim, source: 'notes', visibility: 'private', kind: 'fact', confidence: 1 }, { source_id: source });
}
registration = await registerLocalWriter(engine, 'cli', undefined, true);
selectedConfig = config();
const provider = await createPersistenceIpcProvider(engine, selectedConfig);
brainId = provider.brainId;
binding = (await startPersistenceIpcServer(persistenceSocketPathForConfig(config())!, provider))!;
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
calls = 0;
__setEmbedTransportForTests(async ({ values }) => {
calls++;
return { values, usage: { tokens: values.length }, warnings: [], embeddings: values.map(() => Array(1536).fill(0.25)) };
});
}));
afterEach(async () => inHome(async () => {
const closed = once(binding.server, 'close');
binding.close();
await closed;
await disposePersistenceConsumer(engine);
__setEmbedTransportForTests(null);
resetGateway();
}));
afterAll(async () => {
await inHome(() => engine.disconnect());
rmSync(root, { recursive: true, force: true });
});
const request = (options: Record<string, unknown>, credentials = registration) => requestPersistenceAdministration(binding.socketPath, {
version: 1, kind: 'administration', brain_id: brainId, operation: 'writer_embed_facts',
params: { options }, registration: credentials,
});
const countEmbedded = async () => Number((await engine.executeRaw<{ count: string }>('SELECT count(*)::text AS count FROM facts WHERE embedding IS NOT NULL'))[0].count);
describe('resident managed fact-vector repair', () => {
test('resident selected off-switch cannot be enabled by host or caller configuration', () => inHome(async () => {
selectedConfig.embedding_disabled = true;
await expect(request({ sourceId, yes: true, maxCostUsd: 1 })).rejects.toThrow('no-embedding');
await expect(request({ sourceId, yes: true, maxCostUsd: 1, config: { embedding_disabled: false } })).rejects.toMatchObject({ code: 'invalid_params' });
await expect(requestPersistenceAdministration(binding.socketPath, {
version: 1, kind: 'administration', brain_id: brainId, operation: 'writer_embed_facts',
params: { options: { sourceId, yes: true, maxCostUsd: 1 }, config: { embedding_disabled: false } }, registration,
})).rejects.toMatchObject({ code: 'invalid_params' });
expect(await request({ sourceId, dryRun: true })).toMatchObject({ dryRun: true, would_embed: 2 });
expect(calls).toBe(0);
expect(await countEmbedded()).toBe(0);
}));
test('authenticated preview and bounded execution work without canonical mutations', () => inHome(async () => {
const canonical = async () => Array.from(await engine.executeRaw("SELECT to_jsonb(f)-ARRAY['embedding','embedded_at','embedding_model','embedded_text_hash'] AS row FROM facts f ORDER BY id"));
const before = await canonical();
const metadata = () => engine.executeRaw<{
source_id: string; fact: string; embedding_model: string | null;
embedded_text_hash: string | null; embedded_at: Date | null; has_embedding: boolean;
}>('SELECT source_id, fact, embedding_model, embedded_text_hash, embedded_at, embedding IS NOT NULL AS has_embedding FROM facts ORDER BY id');
for (const row of await metadata()) {
expect(row).toMatchObject({ embedding_model: null, embedded_text_hash: null, embedded_at: null, has_embedding: false });
}
expect(await request({ sourceId })).toMatchObject({ dryRun: true, would_embed: 2, embedded: 0 });
expect(calls).toBe(0);
expect(await request({ sourceId, yes: true, maxCostUsd: 1, maxFacts: 1 })).toMatchObject({ embedded: 1, remaining: 1, failures: 0 });
expect(await request({ sourceId, yes: true, maxCostUsd: 1 })).toMatchObject({ embedded: 1, remaining: 0, failures: 0 });
expect(await request({ sourceId, yes: true, maxCostUsd: 1 })).toMatchObject({ embedded: 0, remaining: 0, failures: 0 });
expect(await canonical()).toEqual(before);
const repaired = await metadata();
expect(repaired.filter(row => row.source_id === sourceId)).toHaveLength(2);
expect(repaired.filter(row => row.source_id === foreignSource)).toHaveLength(1);
for (const row of repaired) {
if (row.source_id === sourceId) {
expect(row.embedding_model).toBe('openai:text-embedding-3-small');
expect(row.embedded_text_hash).toBe(createHash('md5').update(row.fact).digest('hex'));
expect(row.embedded_at).not.toBeNull();
expect(row.has_embedding).toBe(true);
} else {
expect(row).toMatchObject({ embedding_model: null, embedded_text_hash: null, embedded_at: null, has_embedding: false });
}
}
expect(await countEmbedded()).toBe(2);
expect(calls).toBe(2);
await expect(engine.executeRaw("UPDATE facts SET visibility='world' WHERE source_id=$1", [sourceId])).rejects.toThrow('writer_coordinator_required');
}));
test('the private operation is absent from public operations and rejects stdio or forged consent', () => inHome(async () => {
const capabilities = await requestPersistenceCapabilities(binding.socketPath);
expect(capabilities.administration).toContain('writer_embed_facts');
expect(capabilities.operations).not.toContain('writer_embed_facts');
const stdio = await readLocalWriter(engine, 'stdio');
await expect(request({ sourceId }, stdio)).rejects.toMatchObject({ code: 'invalid_params' });
await expect(request({ sourceId }, { ...stdio, lane: 'cli' })).rejects.toMatchObject({ code: 'permission_denied' });
for (const options of [
{ sourceId, yes: 'true', maxCostUsd: 1 }, { sourceId, yes: true },
{ sourceId, yes: true, maxCostUsd: 1, remote: false }, { sourceId, yes: true, maxCostUsd: -1 },
]) await expect(request(options)).rejects.toMatchObject({ code: 'invalid_params' });
expect(calls).toBe(0);
expect(await countEmbedded()).toBe(0);
}));
test('source, operation, scope and slug ceilings are checked before spending', () => inHome(async () => {
const grant: LocalGrant = { sourceIds: ['*'], operations: null, scopes: ['read', 'write'], slugPrefixes: null };
for (const narrowed of [
{ ...grant, sourceIds: [foreignSource] }, { ...grant, operations: ['get_page'] },
{ ...grant, scopes: ['read'] }, { ...grant, slugPrefixes: ['people/*'] },
]) {
registration = await registerLocalWriter(engine, 'cli', narrowed, true);
await expect(request({ sourceId, yes: true, maxCostUsd: 1 })).rejects.toMatchObject({ code: 'permission_denied' });
}
expect(calls).toBe(0);
expect(await countEmbedded()).toBe(0);
}));
test('revocation during provider work prevents vector installation', () => inHome(async () => {
__setEmbedTransportForTests(async ({ values }) => {
calls++;
await revokeLocalWriter(engine, registration.id);
return { values, usage: { tokens: 1 }, warnings: [], embeddings: values.map(() => Array(1536).fill(0.25)) };
});
expect(await request({ sourceId, yes: true, maxCostUsd: 1 })).toMatchObject({ embedded: 0, failures: 2, stopped: 'failed' });
expect(await countEmbedded()).toBe(0);
await expect(request({ sourceId })).rejects.toMatchObject({ code: 'permission_denied' });
expect(calls).toBe(1);
}));
test('a mid-flight source grant narrowing prevents vector installation', () => inHome(async () => {
__setEmbedTransportForTests(async ({ values }) => {
await engine.executeRaw(`UPDATE persistence_local_writers SET grant_ceiling=grant_ceiling ||
jsonb_build_object('sourceIds',ARRAY[$2]::text[]) WHERE id=$1::uuid`, [registration.id, foreignSource]);
return { values, usage: { tokens: 1 }, warnings: [], embeddings: values.map(() => Array(1536).fill(0.25)) };
});
expect(await request({ sourceId, yes: true, maxCostUsd: 1 })).toMatchObject({ embedded: 0, failures: 2, stopped: 'failed' });
expect(await countEmbedded()).toBe(0);
}));
test('the actual CLI delegates before opening the owner-held PGLite database', () => inHome(async () => {
const run = async (extra: string[], expectedStatus = 0) => {
const child = Bun.spawn([process.execPath, join(import.meta.dir, '../src/cli.ts'),
'embed', '--stale', '--facts', '--source', sourceId, '--json', ...extra], {
cwd: root, env: { ...process.env, GBRAIN_NO_BANNER: '1', GBRAIN_BACKUP_CHECK: '0' }, stdout: 'pipe', stderr: 'pipe',
});
const [stdout, stderr, status] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
expect({ status, stderr }).toMatchObject({ status: expectedStatus });
return JSON.parse(stdout);
};
expect(await run([])).toMatchObject({ dryRun: true, would_embed: 2 });
expect(calls).toBe(0);
expect(await run(['--yes', '--max-cost-usd', '0'], 1)).toMatchObject({ embedded: 0, failures: 2, stopped: 'failed' });
expect(calls).toBe(0);
expect(await run(['--yes', '--max-cost-usd', '1', '--max-facts', '1'])).toMatchObject({ embedded: 1, remaining: 1 });
expect(await run(['--yes', '--max-cost-usd', '1'])).toMatchObject({ embedded: 1, remaining: 0 });
expect(await countEmbedded()).toBe(2);
expect(calls).toBe(2);
}));
});