Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.32.2 fence backfill on a managed brain.
*
* Protects: on a managed brain the backfill publishes each entity page's
* facts fence through the coordinator and adopts the legacy fact rows in
* place (managed_maintenance_adopt_fact_fence), for file-backed and
* database-only pages alike, and verify reads a page holding a duplicate
* active fence row as in sync whether the publication or extract_facts
* indexed it last (#5814).
* Fails when: the phase writes fence files into the managed worktree or
* runs a raw `UPDATE facts` (the managed writer guard refuses it and the
* orchestrator chain wedges), when adoption inserts duplicate rows instead
* of keeping the legacy ids and vectors, or when it expires a
* conversation-extractor row on the same page, or when verify counts every
* fence row against the index although extract_facts indexes a duplicate once.
* Seams: none; `managedBrain` and the migration's exported `__testing` phases.
*
* #6278 (2.1, 2.6): a page whose timeline repeats the facts fence marker is
* skipped before submission with the fence reason (no request is admitted,
* so no preparation refusal and no consumed request id) while the other
* page still adopts; a legacy row the codec cannot render is reported with
* the stable `FACTS_FENCE_FAILED: <slug> (fence_unrenderable: …)` token in
* the phase detail while the page's other rows adopt. Fails when: the
* adoption is admitted and fails at preparation (`invalid_params`, the
* reporter's two repeated_marker refusals), or the unrenderable row refuses
* the whole page.
*/
import { expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { __testing } from '../src/commands/migrations/v0_32_2.ts';
import type { OrchestratorOpts } from '../src/commands/migrations/types.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { parseFactsFence, renderFactsTable, replaceOrInsertFactsFence } from '../src/core/facts-fence.ts';
import { serializePageToMarkdown } from '../src/core/markdown.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { maintenancePreflight, submitFactFenceAdoption } from '../src/core/persistence/prepared-maintenance.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { LEGACY_DB_ONLY_SLUG, LEGACY_FILE_SLUG, seedLegacyManagedContent, type LegacySeed } from './helpers/managed-legacy-fixture.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
const OPTS: OrchestratorOpts = { yes: true, dryRun: false, noAutopilotInstall: true };
async function factRows(engine: BrainEngine, ids: number[]) {
return engine.executeRaw<Record<string, unknown>>(
`SELECT id, row_num, source_markdown_slug, fact, expired_at, embedding::text AS embedding, embedded_at::text AS embedded_at,
source_session, confidence, notability, context, (extract(epoch FROM valid_from))::bigint AS valid_from_epoch FROM facts WHERE id = ANY($1::integer[]) ORDER BY id`, [ids]);
}
for (const backend of testBackends()) {
const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
test(`${backend}: legacy facts are fenced through the coordinator and adopted in place`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine, root }) => {
const adopted = [...seed.legacyFactIds, ...seed.dbOnlyFactIds];
const before = await factRows(engine, [...adopted, seed.extractorFactId]);
const [{ n: factCount }] = await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM facts');
const phase = await __testing.phaseBFenceFacts(engine, OPTS);
expect(phase).toMatchObject({ name: 'fence_facts', status: 'complete' });
expect(phase.detail).toContain('scanned=3 fenced=3 pages=2');
expect(await __testing.phaseCVerify(engine, OPTS)).toMatchObject({ status: 'complete', detail: 'pages_checked=2' });
const after = await factRows(engine, [...adopted, seed.extractorFactId]);
expect(after.map(r => [Number(r.id), r.row_num, r.source_markdown_slug, r.expired_at])).toEqual([
[seed.legacyFactIds[0], 2, LEGACY_FILE_SLUG, null],
[seed.legacyFactIds[1], 3, LEGACY_FILE_SLUG, null],
[seed.dbOnlyFactIds[0], 1, LEGACY_DB_ONLY_SLUG, null],
[seed.extractorFactId, 1, LEGACY_FILE_SLUG, null],
]);
for (let i = 0; i < after.length; i++) {
for (const key of ['fact', 'embedding', 'embedded_at', 'source_session', 'confidence', 'notability', 'context', 'valid_from_epoch']) {
expect(after[i][key]).toEqual(before[i][key]);
}
}
expect((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM facts'))[0].n).toBe(factCount);
const file = readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8');
expect(parseFactsFence(file).facts.map(f => [f.rowNum, f.claim])).toEqual([
[2, 'Alice example founded Acme example'], [3, 'Alice example moved to Lisbon']]);
const dbOnly = (await engine.readPageSnapshot(LEGACY_DB_ONLY_SLUG, { sourceId: 'default' }))!;
expect(parseFactsFence(dbOnly.page.compiled_truth).facts.map(f => f.rowNum)).toEqual([1]);
expect(existsSync(join(root, `${LEGACY_DB_ONLY_SLUG}.md`))).toBe(false);
expect(await engine.executeRaw('SELECT row_num, resolved_quality, resolved_by FROM takes t JOIN pages p ON p.id=t.page_id WHERE p.slug=$1 ORDER BY row_num',
[LEGACY_FILE_SLUG])).toEqual([{ row_num: 1, resolved_quality: 'correct', resolved_by: 'people/alice-example' },
{ row_num: 2, resolved_quality: null, resolved_by: null }]);
const authority = (await maintenancePreflight(engine, 'default'))!;
const page = (await engine.readPageSnapshot(LEGACY_FILE_SLUG, { sourceId: 'default' }))!;
const readopt = replaceOrInsertFactsFence(serializePageToMarkdown(page.page, page.tags), renderFactsTable([...parseFactsFence(file).facts,
{ rowNum: 9, claim: 'Alice example founded Acme example', kind: 'fact', confidence: 0.9, visibility: 'world', notability: 'high', active: true }]));
await expect(submitFactFenceAdoption(engine, authority, LEGACY_FILE_SLUG, { content: readopt, expectedRevision: page.revision,
assignments: [{ id: seed.legacyFactIds[0], row_num: 9 }], file: true })).rejects.toMatchObject({ code: 'revision_conflict' });
const rerun = await __testing.phaseBFenceFacts(engine, OPTS);
expect(rerun).toMatchObject({ status: 'complete' });
expect(rerun.detail).toContain('scanned=0 fenced=0 pages=0');
expect(await factRows(engine, [...adopted, seed.extractorFactId])).toEqual(after);
}, { databaseUrl, setup: async ({ engine, root }) => {
seed = await seedLegacyManagedContent(engine, root);
// A take graded only in the database, as a pre-activation grader left it.
const [{ id }] = await engine.executeRaw<{ id: number }>('SELECT id FROM pages WHERE slug=$1', [LEGACY_FILE_SLUG]);
await engine.addTakesBatch([{ page_id: id, row_num: 1, claim: 'Acme example raised a seed round', kind: 'fact', holder: 'world',
weight: 1, since_date: '2026-01', source: 'press note', active: true, superseded_by: null }]);
await engine.resolveTake(id, 1, { quality: 'correct', source: 'grader note', resolvedBy: 'people/alice-example' });
} });
}, 120_000);
test(`${backend}: a page whose timeline repeats the facts fence marker is skipped before submission; the other page adopts (#6278 2.6)`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine, root }) => {
const before = await factRows(engine, seed.legacyFactIds);
const file = readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8');
const phase = await __testing.phaseBFenceFacts(engine, OPTS);
expect(phase.status).toBe('failed');
expect(phase.detail).toContain('scanned=3 fenced=1 pages=1');
expect(phase.detail).toContain(`FACTS_FENCE_FAILED: ${LEGACY_FILE_SLUG} (Fence repeated_marker: in the facts fence (timeline)`);
// Skipped before admission: no request for the page exists, nothing changed on it.
expect(await engine.executeRaw('SELECT request_id FROM persistence_requests WHERE slug = $1', [LEGACY_FILE_SLUG])).toEqual([]);
expect(await factRows(engine, seed.legacyFactIds)).toEqual(before);
expect(readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8')).toBe(file);
// The database-only page adopted its row in the same pass.
const [dana] = await factRows(engine, seed.dbOnlyFactIds);
expect(dana).toMatchObject({ row_num: 1, source_markdown_slug: LEGACY_DB_ONLY_SLUG, expired_at: null });
}, { databaseUrl, setup: async ({ engine, root }) => {
seed = await seedLegacyManagedContent(engine, root);
const fence = (n: number, claim: string) => renderFactsTable([{ rowNum: n, claim, kind: 'fact', confidence: 1, visibility: 'world', notability: 'high', active: true, source: 'notes' }]);
const snapshot = (await engine.readPageSnapshot(LEGACY_FILE_SLUG, { sourceId: 'default' }))!;
await engine.putPage(LEGACY_FILE_SLUG, { ...snapshot.page, compiled_truth: snapshot.page.compiled_truth,
timeline: `## Facts\n\n${fence(1, 'Alice example keeps bees')}\n\n## Facts\n\n${fence(2, 'Alice example keeps bees too')}\n` });
const updated = (await engine.readPageSnapshot(LEGACY_FILE_SLUG, { sourceId: 'default' }))!;
writeFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), serializePageToMarkdown(updated.page, updated.tags));
} });
}, 120_000);
test(`${backend}: a legacy row the fence codec cannot render is reported with the stable token while the page's other rows adopt (#6278 2.1)`, async () => {
let seed!: LegacySeed;
let struckId!: number;
await managedBrain(async ({ engine, root }) => {
const [struckBefore] = await factRows(engine, [struckId]);
const phase = await __testing.phaseBFenceFacts(engine, OPTS);
expect(phase.status).toBe('failed');
expect(phase.detail).toContain('scanned=4 fenced=3 pages=2 ');
expect(phase.detail).toContain(`FACTS_FENCE_FAILED: ${LEGACY_FILE_SLUG} (fence_unrenderable: 1 row(s), struck)`);
expect(phase.detail).not.toContain('left Acme');
const after = await factRows(engine, [...seed.legacyFactIds, struckId]);
expect(after.map(r => [Number(r.id), r.row_num, r.source_markdown_slug])).toEqual([
[seed.legacyFactIds[0], 2, LEGACY_FILE_SLUG], [seed.legacyFactIds[1], 3, LEGACY_FILE_SLUG], [struckId, null, null]]);
expect(after[2]).toEqual(struckBefore);
expect(parseFactsFence(readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8')).facts.map(f => f.claim)).toEqual([
'Alice example founded Acme example', 'Alice example moved to Lisbon']);
}, { databaseUrl, setup: async ({ engine, root }) => {
seed = await seedLegacyManagedContent(engine, root);
const [row] = await engine.executeRaw<{ id: number }>(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability, valid_from, source, confidence)
VALUES ('default', $1, '~~Alice example left Acme example~~', 'fact', 'world', 'medium', '2026-03-01', 'mcp:remember', 0.8) RETURNING id`, [LEGACY_FILE_SLUG]);
struckId = Number(row.id);
} });
}, 120_000);
test(`${backend}: a refused adoption is retried under a new request identity once the file is restored`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine, root }) => {
const path = join(root, `${LEGACY_FILE_SLUG}.md`);
const file = readFileSync(path, 'utf8');
writeFileSync(path, `${file}\nAn uncoordinated local edit.\n`);
const refused = await __testing.phaseBFenceFacts(engine, OPTS);
expect(refused.status).toBe('failed');
expect(refused.detail).toContain('uncoordinated local edit');
writeFileSync(path, file);
const retried = await __testing.phaseBFenceFacts(engine, OPTS);
expect(retried).toMatchObject({ status: 'complete' });
expect(retried.detail).toContain('scanned=2 fenced=2 pages=1');
}, { databaseUrl, setup: async ({ engine, root }) => { seed = await seedLegacyManagedContent(engine, root); } });
}, 120_000);
test(`${backend}: the adoption intent refuses a taken position and a duplicate assignment, changing nothing`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine, root }) => {
const authority = (await maintenancePreflight(engine, 'default'))!;
const snapshot = (await engine.readPageSnapshot(LEGACY_FILE_SLUG, { sourceId: 'default' }))!;
const file = readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8');
const before = await factRows(engine, [...seed.legacyFactIds, seed.extractorFactId]);
const content = replaceOrInsertFactsFence(serializePageToMarkdown(snapshot.page, snapshot.tags), renderFactsTable([
{ rowNum: 1, claim: 'Alice example founded Acme example', kind: 'fact', confidence: 0.9, visibility: 'world', notability: 'high', active: true }]));
const attempt = (assignments: Array<{ id: number; row_num: number }>) => submitFactFenceAdoption(engine, authority, LEGACY_FILE_SLUG,
{ content, expectedRevision: snapshot.revision, assignments, file: true });
await expect(attempt([{ id: seed.legacyFactIds[0], row_num: 1 }])).rejects.toMatchObject({ code: 'revision_conflict' });
// #6278: a fence row that does not read back as its legacy fact is a planning defect (class server), not caller input.
await expect(attempt([{ id: seed.legacyFactIds[1], row_num: 1 }])).rejects.toMatchObject({ code: 'fence_unrenderable' });
await expect(attempt([{ id: seed.legacyFactIds[0], row_num: 1 }, { id: seed.legacyFactIds[1], row_num: 1 }]))
.rejects.toMatchObject({ code: 'invalid_params' });
expect(await factRows(engine, [...seed.legacyFactIds, seed.extractorFactId])).toEqual(before);
expect(readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8')).toBe(file);
}, { databaseUrl, setup: async ({ engine, root }) => { seed = await seedLegacyManagedContent(engine, root); } });
}, 120_000);
test(`${backend}: exhausted request IDs refuse the adoption up front with the capacity command`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine, root }) => {
const before = await factRows(engine, [...seed.legacyFactIds, ...seed.dbOnlyFactIds]);
const file = readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8');
const phase = await __testing.phaseBFenceFacts(engine, OPTS);
expect(phase).toMatchObject({ name: 'fence_facts', status: 'failed' });
expect(phase.detail).toStartWith('write_quota_exhausted: Write capacity exhausted: principal permanent request IDs (0 used of 0).');
expect(phase.detail).toContain('gbrain config set persistence.limits.principal_lifetime_ids ');
expect(await factRows(engine, [...seed.legacyFactIds, ...seed.dbOnlyFactIds])).toEqual(before);
expect(readFileSync(join(root, `${LEGACY_FILE_SLUG}.md`), 'utf8')).toBe(file);
expect(await engine.executeRaw("SELECT id FROM persistence_requests WHERE operation='submit_job'")).toEqual([]);
}, { databaseUrl, setup: async ({ engine, root }) => {
seed = await seedLegacyManagedContent(engine, root);
await engine.setConfig('persistence.limits.principal_lifetime_ids', '0');
} });
}, 120_000);
test(`${backend}: an archived source's legacy facts are skipped and never block the active source`, async () => {
let seed!: LegacySeed;
await managedBrain(async ({ engine }) => {
const phase = await __testing.phaseBFenceFacts(engine, OPTS);
expect(phase).toMatchObject({ name: 'fence_facts', status: 'complete' });
expect(phase.detail).toContain('fenced=3 pages=2');
expect(phase.detail).toContain('skipped_archived=1');
expect((await factRows(engine, seed.legacyFactIds)).map(r => r.row_num)).toEqual([2, 3]);
}, { databaseUrl, setup: async ({ engine, root }) => {
seed = await seedLegacyManagedContent(engine, root);
await engine.executeRaw("INSERT INTO sources (id, name, archived) VALUES ('archived-example', 'Archived example', true)");
await engine.putPage('people/erin-example', { type: 'person', title: 'Erin Example', compiled_truth: '# Erin Example' }, { sourceId: 'archived-example' });
await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability, valid_from, source, confidence)
VALUES ('archived-example', 'people/erin-example', 'Erin example left Acme example', 'fact', 'world', 'medium', now(), 'mcp:put_page', 0.8)`);
} });
}, 120_000);
// #6685: fenced rows left in the index after their page was deleted.
test.each([
['all expired: skipped, not drift', [true, true], { status: 'complete', detail: 'pages_checked=0 skipped_expired_no_page=1' }],
['one live row: still drift', [true, false], { status: 'failed', detail: '1 pages drifted: projects/gone-example (page missing)' }],
])(`${backend}: verify on a deleted page's fenced rows, %s (#6685)`, async (_case, expired, expected) => {
await managedBrain(async ({ engine }) => {
expect(await __testing.phaseCVerify(engine, OPTS)).toMatchObject(expected);
}, { databaseUrl, setup: async ({ engine }) => {
for (const [index, isExpired] of expired.entries()) {
await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability, valid_from, source, confidence,
row_num, source_markdown_slug, expired_at)
VALUES ('default', 'projects/gone-example', $1, 'fact', 'private', 'medium', now(), 'manual', 1.0, $2, 'projects/gone-example',
CASE WHEN $3::boolean THEN now() ELSE NULL END)`, [`Claim ${index + 1}`, index + 1, isExpired]);
}
} });
}, 120_000);
test(`${backend}: a duplicate active fence row reads in sync whichever writer indexed the page last (#5814)`, async () => {
await managedBrain(async ({ ctx, engine }) => {
const slug = 'people/dana-example';
const row = (rowNum: number, claim: string) => ({ rowNum, claim, kind: 'fact' as const, confidence: 1, visibility: 'private' as const,
notability: 'medium' as const, validFrom: '2026-01-01', source: 'manual', active: true });
const body = replaceOrInsertFactsFence('# Dana Example\n', renderFactsTable([row(1, 'Lives in Paris'), row(2, 'Lives in Paris'), row(3, 'Works at Acme example')]));
const receipt = await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: randomUUID(),
content: `---\ntype: person\ntitle: Dana Example\n---\n\n${body}` } }) as { state: string };
expect(receipt.state).toBe('committed');
const indexed = async () => (await engine.executeRaw<{ row_num: number }>(
'SELECT row_num FROM facts WHERE source_markdown_slug = $1 AND row_num IS NOT NULL ORDER BY row_num', [slug])).map(r => Number(r.row_num));
// The publication projects every fence row; extract_facts indexes the duplicate once.
expect(await indexed()).toEqual([1, 2, 3]);
expect(await __testing.phaseCVerify(engine, OPTS)).toMatchObject({ status: 'complete', detail: 'pages_checked=1' });
await runExtractFacts(engine, { sourceId: 'default' });
expect(await indexed()).toEqual([1, 3]);
expect(await __testing.phaseCVerify(engine, OPTS)).toMatchObject({ status: 'complete', detail: 'pages_checked=1' });
}, { databaseUrl });
}, 120_000);
}