Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
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 type { OperationContext } from '../src/core/ops/contract.ts';
import { submissionAuthority } from '../src/core/persistence/authority.ts';
import { admitWrite, claimNextWrite, getWriteRequestById } from '../src/core/persistence/journal.ts';
import { localHostId, registerLocalWriter, withVerifiedLocalRegistration } from '../src/core/persistence/identity.ts';
import { preparePageMutation } from '../src/core/persistence/page-prepare.ts';
import { publishMutation } from '../src/core/persistence/coordinator.ts';
import { claimPersistenceEffect, publicEffectsForRequest } from '../src/core/persistence/effect-journal.ts';
import { authorizeFactsBackstop, dispatchFactsBackstopEffect, readFactsBackstopJobPage } from '../src/core/persistence/effect-facts.ts';
import type { WriteRequest } from '../src/core/persistence/model.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { withEnv } from './helpers/with-env.ts';
import { LATEST_SCHEMA_VERSION } from '../src/core/schema-migrations/latest.generated.ts';
let engine: PGLiteEngine;
const config = { engine: 'pglite' as const, embedding_disabled: true };
const content = `---\ntype: note\ntitle: Field notes\n---\n\n${'A useful substantive record of this project and its current status. '.repeat(4)}`;
beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 60_000);
afterAll(async () => { await engine.disconnect(); });
async function fixture(run: () => Promise<void>) {
const home = mkdtempSync(join(tmpdir(), 'gbrain-facts-effect-'));
try { await withEnv({ GBRAIN_HOME: home }, async () => { await resetPgliteState(engine); await engine.setConfig('version', String(LATEST_SCHEMA_VERSION)); await registerLocalWriter(engine, 'cli'); await run(); }); }
finally { rmSync(home, { force: true, recursive: true }); }
}
async function prepare(overrides: Partial<OperationContext> = {}, params: Record<string, unknown> = {}) {
const [source] = await engine.executeRaw<{ incarnation: string }>("SELECT incarnation FROM sources WHERE id='default'");
const ctx: OperationContext = { engine, config, dryRun: false, remote: false, sourceId: 'default', logger: { info() {}, warn() {}, error() {} }, ...overrides };
const authority = await submissionAuthority(ctx, 'put_page', 'default', source.incarnation, 'notes/example');
const intent = { content, ...params };
const current = await engine.readPageSnapshot('notes/example', { sourceId: 'default', includeDeleted: true });
await admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId: 'default',
sourceIncarnation: source.incarnation, slug: 'notes/example', pageId: current?.page.id ?? null, requestId: randomUUID(), callerIntent: intent, intent });
const row = (await claimNextWrite(engine, localHostId()))!;
return { row, prepared: await preparePageMutation(engine, row, config) };
}
async function publish() { const input = await prepare(); return publishMutation(engine, input.row, input.prepared); }
async function claimFacts(row: WriteRequest) {
await engine.executeRaw("UPDATE persistence_effects SET next_attempt_at=now()+interval '1 hour' WHERE kind<>'facts-backstop'");
const effect = (await claimPersistenceEffect(engine, localHostId()))!;
expect(effect.request_id).toBe(row.id); expect(effect.kind).toBe('facts-backstop');
return effect;
}
async function jobs() { return engine.executeRaw<{ id: number; data: Record<string, unknown>; idempotency_key: string }>("SELECT id,data,idempotency_key FROM minion_jobs WHERE name='facts-absorb'"); }
test('page receipt and bounded extraction debt commit together; durable handoff rolls back and replays once', () => fixture(async () => {
const row = await publish(); expect(row.outcome?.facts_backstop).toEqual({ queued: true });
expect(await jobs()).toHaveLength(0);
const effect = await claimFacts(row);
await expect(engine.transaction(async tx => {
await dispatchFactsBackstopEffect(tx, effect, localHostId());
throw new Error('transaction aborted after job insert');
})).rejects.toThrow('transaction aborted');
expect(await jobs()).toHaveLength(0);
await dispatchFactsBackstopEffect(engine, effect, localHostId());
// The first ACK may be lost; a stale execution token cannot insert again.
await dispatchFactsBackstopEffect(engine, effect, localHostId());
const work = await jobs(); expect(work).toHaveLength(1);
expect(work[0].idempotency_key).toBe(`facts-absorb:write:${row.id}`);
expect(work[0].data).toMatchObject({ persistence_request_id: row.id, visibility: 'private', sourceId: 'default' });
expect((await publicEffectsForRequest(engine, row.id)).find(effect => effect.kind === 'facts-backstop')).toEqual({ kind: 'facts-backstop', state: 'dispatched' });
expect('page' in await readFactsBackstopJobPage(engine, work[0].data)).toBe(true);
const current = (await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }))!;
const noop = await prepare({}, { expected_revision: current.revision });
const unchanged = await publishMutation(engine, noop.row, noop.prepared);
expect(unchanged.outcome?.facts_backstop).toEqual({ skipped: 'not_imported' });
expect(await publicEffectsForRequest(engine, unchanged.id)).toEqual([]);
expect((await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }))?.revision).toBe(current.revision);
}));
test('activation between preparation and publication retains durable coordinated extraction debt', () => fixture(async () => {
const input = await prepare();
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
const row = await publishMutation(engine, input.row, input.prepared);
expect(row.state).toBe('committed');
expect(row.outcome?.facts_backstop).toEqual({ queued: true });
expect((await publicEffectsForRequest(engine, row.id)).some(effect => effect.kind === 'facts-backstop')).toBe(true);
expect(await jobs()).toHaveLength(0);
}));
test('activation after publication dispatches coordinated extraction without changing the committed canonical receipt', () => fixture(async () => {
const row = await publish(); const effect = await claimFacts(row);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
await dispatchFactsBackstopEffect(engine, effect, localHostId());
expect(await jobs()).toHaveLength(1);
expect((await getWriteRequestById(engine, row.id))?.outcome).toEqual(row.outcome);
expect((await publicEffectsForRequest(engine, row.id)).find(effect => effect.kind === 'facts-backstop')).toEqual({ kind: 'facts-backstop', state: 'dispatched' });
expect('page' in await readFactsBackstopJobPage(engine, (await jobs())[0].data)).toBe(true);
}));
test('a superseded page cannot enqueue extraction from an obsolete receipt', () => fixture(async () => {
const row = await publish(); const effect = await claimFacts(row);
const snapshot = (await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }))!;
await engine.putPage(row.slug, { ...snapshot.page, compiled_truth: 'Changed by a later writer' }, { sourceId: row.source_id });
await dispatchFactsBackstopEffect(engine, effect, localHostId());
expect(await jobs()).toHaveLength(0);
expect((await publicEffectsForRequest(engine, row.id)).find(effect => effect.kind === 'facts-backstop')).toMatchObject({ state: 'skipped', reason: 'superseded' });
}));
test('durable job execution rechecks revocation, grant narrowing, page revision and activation', () => fixture(async () => {
const row = await publish(); await dispatchFactsBackstopEffect(engine, await claimFacts(row), localHostId());
const data = (await jobs())[0].data;
await engine.executeRaw('UPDATE persistence_local_writers SET revoked_at=now() WHERE id=$1::uuid', [row.principal_id]);
expect(await readFactsBackstopJobPage(engine, data)).toEqual({ skipped: 'permission_denied' });
await engine.executeRaw("UPDATE persistence_local_writers SET revoked_at=NULL,grant_ceiling=jsonb_set(grant_ceiling,'{slugPrefixes}','[\"notes/\"]'::jsonb) WHERE id=$1::uuid", [row.principal_id]);
expect(await readFactsBackstopJobPage(engine, data)).toEqual({ skipped: 'permission_denied' });
await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=jsonb_set(grant_ceiling,'{slugPrefixes}','null'::jsonb) WHERE id=$1::uuid", [row.principal_id]);
const snapshot = (await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }))!;
await engine.putPage(row.slug, { ...snapshot.page, compiled_truth: 'Changed after handoff' }, { sourceId: row.source_id });
expect(await readFactsBackstopJobPage(engine, data)).toEqual({ skipped: 'superseded' });
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
expect(await readFactsBackstopJobPage(engine, data)).toEqual({ skipped: 'superseded' });
}));
test('confined writers and disabled extraction never receive a queued claim', () => fixture(async () => {
const input = await prepare({ viaSubagent: true, allowedSlugPrefixes: ['notes/*'] });
const row = await publishMutation(engine, input.row, input.prepared);
expect(row.outcome?.facts_backstop).toEqual({ skipped: 'slug_bound_client' });
expect((await publicEffectsForRequest(engine, row.id)).some(effect => effect.kind === 'facts-backstop')).toBe(false);
await engine.setConfig('facts.extraction_enabled', 'false');
const current = (await engine.readPageSnapshot(row.slug, { sourceId: row.source_id }))!;
const updated = await prepare({}, { content: `${content}\nAdditional content`, expected_revision: current.revision });
const disabled = await publishMutation(engine, updated.row, updated.prepared);
expect(disabled.outcome?.facts_backstop).toEqual({ skipped: 'extraction_disabled' });
}));
// #6042: a rewrite that keeps compiled_truth (the only text the extractor reads) of an extracted page.
const retitled = (title: string) => content.replace('title: Field notes', `title: ${title}`);
const withTimeline = (body: string) => `${body}\n\n--- timeline ---\n\n- **2026-08-02** | A synthetic dated event.\n`;
/** Hands every pending facts effect to its job, then records the jobs as finished: no extraction of the page is pending. */
async function finishExtractions() {
await engine.executeRaw("UPDATE persistence_effects SET next_attempt_at = now() + interval '1 hour' WHERE kind <> 'facts-backstop'");
for (;;) {
const effect = await claimPersistenceEffect(engine, localHostId());
if (!effect) break;
await dispatchFactsBackstopEffect(engine, effect, localHostId());
}
await engine.executeRaw("UPDATE minion_jobs SET status = 'completed', finished_at = now() WHERE name = 'facts-absorb'");
}
/** Publishes `body` against the page's current revision, deleted pages included. */
async function rewrite(body: string) {
const before = (await engine.readPageSnapshot('notes/example', { sourceId: 'default', includeDeleted: true }))!;
const input = await prepare({}, { content: body, expected_revision: before.revision });
const row = await publishMutation(engine, input.row, input.prepared);
expect(row.state).toBe('committed');
const effectQueued = (await publicEffectsForRequest(engine, row.id)).some(effect => effect.kind === 'facts-backstop');
return { status: row.outcome?.facts_backstop, effectQueued };
}
test('#6042: title-only and timeline-only rewrites of an extracted page record body_unchanged and queue no effect', () => fixture(async () => {
expect((await publish()).outcome?.facts_backstop).toEqual({ queued: true });
await finishExtractions();
expect(await rewrite(retitled('Renamed once'))).toEqual({ status: { skipped: 'body_unchanged' }, effectQueued: false });
expect(await rewrite(withTimeline(retitled('Renamed once')))).toEqual({ status: { skipped: 'body_unchanged' }, effectQueued: false });
expect(await jobs()).toHaveLength(1);
}));
test('#6042 control: a rewrite that changes compiled_truth still queues extraction', () => fixture(async () => {
await publish();
await finishExtractions();
expect(await rewrite(`${content}A further substantive sentence about the project schedule.\n`)).toEqual({ status: { queued: true }, effectQueued: true });
}));
test('#6042: an extraction still in the outbox is superseded by the rewrite, so the rewrite queues in its place', () => fixture(async () => {
await publish();
expect(await rewrite(retitled('Renamed before extraction'))).toEqual({ status: { queued: true }, effectQueued: true });
}));
test.each(['waiting', 'delayed', 'paused', 'waiting-children', 'active'])('#6042: a facts-absorb job that is %s still counts as pending', (status) => fixture(async () => {
await publish();
await finishExtractions();
// A move to active is a claim, which the queue protocol trigger requires to advance claim_generation.
await engine.executeRaw(`UPDATE minion_jobs SET status = $1::text,
claim_generation = claim_generation + CASE WHEN $1::text = 'active' THEN 1 ELSE 0 END WHERE name = 'facts-absorb'`, [status]);
expect(await rewrite(retitled('Renamed during the job'))).toEqual({ status: { queued: true }, effectQueued: true });
}));
test.each(['completed', 'failed', 'dead', 'cancelled'])('#6042: on an extracted page, a later facts-absorb job that is %s no longer blocks the skip', (status) => fixture(async () => {
await publish();
await finishExtractions();
const { page } = (await engine.readPageSnapshot('notes/example', { sourceId: 'default' }))!;
const later = await new MinionQueue(engine).add('facts-absorb', { slug: 'notes/example', sourceId: 'default', page_id: page.id }, { queue: 'default' });
await engine.executeRaw('UPDATE minion_jobs SET status = $1 WHERE id = $2', [status, later.id]);
expect((await rewrite(retitled('Renamed after the job'))).status).toEqual({ skipped: 'body_unchanged' });
}));
test('#6042: only an extraction bound to this page row blocks the skip, not one for the same slug elsewhere', () => fixture(async () => {
await publish();
await finishExtractions();
const { page } = (await engine.readPageSnapshot('notes/example', { sourceId: 'default' }))!;
await new MinionQueue(engine).add('facts-absorb', { slug: 'notes/example', sourceId: 'elsewhere', page_id: page.id + 1000 }, { queue: 'default' });
expect((await rewrite(retitled('Renamed beside a foreign job'))).status).toEqual({ skipped: 'body_unchanged' });
}));
test('#6042: a page that was ineligible before the write is offered when it becomes eligible with the same body', () => fixture(async () => {
await publish();
await finishExtractions();
const asConcept = content.replace('type: note', 'type: concept');
expect((await rewrite(asConcept)).status).toEqual({ skipped: 'kind:concept' });
expect(await rewrite(content)).toEqual({ status: { queued: true }, effectQueued: true });
}));
test('#6042: rewriting a soft-deleted page with its old body queues extraction again', () => fixture(async () => {
await publish();
await finishExtractions();
await engine.softDeletePage('notes/example', { sourceId: 'default' });
expect(await rewrite(content)).toEqual({ status: { queued: true }, effectQueued: true });
}));
test('#6071: a body-preserving rewrite of an extracted page queues no extraction', () => fixture(async () => {
await publish();
await finishExtractions();
const before = (await jobs()).length;
expect(await rewrite(retitled('Renamed after extraction'))).toEqual({ status: { skipped: 'body_unchanged' }, effectQueued: false });
expect(await jobs()).toHaveLength(before);
}));
test('#6071: a body-preserving rewrite of a never-extracted eligible page still queues extraction', () => fixture(async () => {
await engine.setConfig('facts.extraction_enabled', 'false');
expect((await publish()).outcome?.facts_backstop).toEqual({ skipped: 'extraction_disabled' });
await engine.setConfig('facts.extraction_enabled', 'true');
expect(await rewrite(retitled('Renamed after enabling'))).toEqual({ status: { queued: true }, effectQueued: true });
}));
test('#6071: an extraction that did not complete does not count as extracted', () => fixture(async () => {
await publish();
await finishExtractions();
await engine.executeRaw("UPDATE minion_jobs SET status = 'failed' WHERE name = 'facts-absorb'");
expect(await rewrite(retitled('Renamed after a failed extraction'))).toEqual({ status: { queued: true }, effectQueued: true });
}));
test.each(['superseded', 'page_missing', 'extraction_disabled'])('#9248: a completed facts-absorb job whose result is skipped %s does not count as extracted', (reason) => fixture(async () => {
await publish();
await finishExtractions();
await engine.executeRaw("UPDATE minion_jobs SET result = jsonb_build_object('skipped', $1::text) WHERE name = 'facts-absorb'", [reason]);
expect(await rewrite(retitled('Renamed after a skipped extraction'))).toEqual({ status: { queued: true }, effectQueued: true });
}));
test('#9248 control: a completed facts-absorb job with an extraction result still counts as extracted', () => fixture(async () => {
await publish();
await finishExtractions();
await engine.executeRaw(`UPDATE minion_jobs SET result = '{"mode":"inline","inserted":2,"duplicate":0,"superseded":0,"fact_ids":[1,2]}'::jsonb WHERE name = 'facts-absorb'`);
expect(await rewrite(retitled('Renamed after a real extraction'))).toEqual({ status: { skipped: 'body_unchanged' }, effectQueued: false });
}));
test('a slug-bound writer\'s backstop refusal says the page was written and who widens the grant', async () => {
const row = { slug: 'notes/a', authority: { slugPrefixes: ['notes/'] } } as unknown as WriteRequest;
await expect(authorizeFactsBackstop(engine, row)).rejects.toMatchObject({ code: 'permission_denied',
suggestion: expect.stringContaining('the page itself is written') });
});
test.each([
[null, 'all'], ['medium-and-up', 'medium-and-up'], ['high-only', 'high-only'], ['all', 'all'], [' Medium-And-Up ', 'medium-and-up'], ['low', 'all'],
])('#6231: facts.page_write_notability_filter=%p queues the page-write extraction with %p', (setting, expected) => fixture(async () => {
const row = await publish();
const effect = await claimFacts(row);
// Read at dispatch, after the claim: a change before the job is queued still applies.
if (setting !== null) await engine.setConfig('facts.page_write_notability_filter', setting);
await dispatchFactsBackstopEffect(engine, effect, localHostId());
const work = await jobs();
expect(work).toHaveLength(1);
expect(work[0].data.notabilityFilter).toBe(expected);
}));
test('#6232: a page that sets facts_backstop: false queues no extraction, and removing the line queues it with the same body', () => fixture(async () => {
await publish();
await finishExtractions();
const optedOut = content.replace('title: Field notes', 'title: Field notes\nfacts_backstop: false');
expect(await rewrite(optedOut)).toEqual({ status: { skipped: 'opted_out' }, effectQueued: false });
expect(await rewrite(content)).toEqual({ status: { queued: true }, effectQueued: true });
}));
async function publishRemote() {
const registration = await registerLocalWriter(engine, 'stdio', { sourceIds: ['*'], operations: null, scopes: ['read', 'write'], slugPrefixes: null });
return withVerifiedLocalRegistration(engine, registration, async () => {
const input = await prepare({ remote: true, auth: { token: 'fixture', clientId: 'fixture-client', scopes: ['read', 'write'], sourceId: 'default' } } as Partial<OperationContext>,
{ content: content.replace('type: note\n', 'type: note\nvisibility: private\n') });
return publishMutation(engine, input.row, input.prepared);
});
}
test('#6322: a private page the stored remote principal can no longer see settles as skipped page_not_found, at dispatch and at durable job read', () => fixture(async () => {
await engine.setConfig('search.remote_private_pages', 'visible');
const row = await publishRemote();
expect(row.state).toBe('committed');
const effect = await claimFacts(row);
await engine.setConfig('search.remote_private_pages', 'hidden');
await dispatchFactsBackstopEffect(engine, effect, localHostId());
expect(await jobs()).toHaveLength(0);
expect((await publicEffectsForRequest(engine, row.id)).find(e => e.kind === 'facts-backstop')).toMatchObject({ state: 'skipped', reason: 'page_not_found' });
await engine.setConfig('search.remote_private_pages', 'visible');
await engine.executeRaw("DELETE FROM pages WHERE slug='notes/example'");
const visible = await publishRemote();
await dispatchFactsBackstopEffect(engine, await claimFacts(visible), localHostId());
const data = (await jobs())[0].data;
await engine.setConfig('search.remote_private_pages', 'hidden');
expect(await readFactsBackstopJobPage(engine, data)).toEqual({ skipped: 'page_not_found' });
}));