Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* d4 and items 2, 3, 6 and 7 of the convergence plan's PR A, on a managed brain: a page with no import record converts
* by content evidence (never a timestamp), undecided pages wait on an owner's decisions file, a database write that races
* the recheck is held instead of overwritten, a failed apply reports where it stopped and how to roll back without
* rewriting, and an approval applies across time to the pages unchanged since it was given.
*/
import { describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { installFaultHook } from '../src/core/persistence/fault-points.ts';
import { writeGitHold } from '../src/core/persistence/sync-holds.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { applyApprovedConversion, applyGitConversion, applyMixedConversion, conversionApproval, conversionRecovery, conversionReviewList, planGitConversion,
planMixedConversion, readConversionApproval, readConversionDecisions, writeConversionFile, type ConversionDecision } from '../src/core/persistence/git-conversion.ts';
import { previewReindex, runSourcesReindex } from '../src/commands/sources-reindex.ts';
import { runSourcesCanonical } from '../src/commands/sources-canonical.ts';
import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
import { managedBrain, type ManagedBrain } from './helpers/managed-brain.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, '-c', 'commit.gpgsign=false', ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const note = (slug: string, body: string) => '---\ntype: concept\ntitle: ' + slug + '\n---\n\n' + body + '\n';
const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };
const PROCESSING = { noEmbed: true, noExtract: true };
const SLUGS = ['notes/same', 'notes/db', 'notes/file', 'notes/both', 'notes/none'];
const DB_EDIT = (slug: string) => `Written to the database alone: ${slug}.`;
const GIT_EDIT = (slug: string) => `Edited by a plain git commit: ${slug}.`;
const strict = async (engine: BrainEngine) => (await engine.executeRaw<{ s: boolean }>("SELECT COALESCE(config->>'canonical','')='git' AS s FROM sources WHERE id='default'"))[0]!.s;
const body = async (engine: BrainEngine, slug: string) => (await engine.executeRaw<{ body: string }>("SELECT compiled_truth AS body FROM pages WHERE source_id='default' AND slug=$1 AND deleted_at IS NULL", [slug]))[0]?.body;
const holds = async (engine: BrainEngine) => (await engine.executeRaw<{ r: { path: string; code: string } }>(
"SELECT completed_keys->0 AS r FROM op_checkpoints WHERE op='sync-hold' ORDER BY fingerprint")).map(({ r }) => r.path);
const databaseOnlyEdit = (engine: BrainEngine, slug: string, text: string) => engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw(
"UPDATE pages SET compiled_truth=$1, knowledge_revision=$2::uuid, revision_write_request_id=NULL WHERE source_id='default' AND slug=$3", [text, randomUUID(), slug]), TEST_WRITE_ATTRIBUTION));
async function dropImportRecord(engine: BrainEngine, slug: string): Promise<void> {
const [row] = await engine.executeRaw<{ id: string }>("SELECT id::text FROM pages WHERE source_id='default' AND slug=$1", [slug]);
await engine.executeRaw("DELETE FROM op_checkpoints WHERE op='sync-import-provenance' AND fingerprint LIKE $1", [`default:%:${row!.id}`]);
}
const conversionShas = (root: string, since: string) => git(root, 'log', '--reverse', '--format=%H', `${since}..HEAD`).split('\n').filter(Boolean);
async function cli(engine: BrainEngine, args: string[]): Promise<Record<string, any>> {
const lines: string[] = [];
const log = console.log, priorExitCode = process.exitCode;
console.log = (line: unknown) => { lines.push(String(line)); };
try { await runSourcesCanonical(engine, [...args, '--json']); } finally { console.log = log; _resetCliExitVerdictForTests(); process.exitCode = priorExitCode ?? 0; }
return JSON.parse(lines.at(-1)!);
}
const setup = ({ root }: { root: string }) => {
mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');
git(root, 'config', 'user.name', 'Example Writer'); git(root, 'config', 'user.email', '[email protected]');
for (const slug of SLUGS) writeFileSync(join(root, `${slug}.md`), note(slug, `The committed body of ${slug}.`));
git(root, 'add', '-A'); git(root, 'commit', '-qm', 'notes');
};
/**
* After the first sync every page but notes/same loses its import record, as pages imported before records existed have none:
* notes/db: a writer archived its preimage and edited the row (only the database moved: adopt);
* notes/file: a plain git commit edited the file, and then a non-content updated_at bump (only the file moved: Git wins);
* notes/both: both of the above (both moved: a decision);
* notes/none: a row edit with no archived version (no evidence: a decision).
*/
async function evidenceSource(brain: ManagedBrain): Promise<void> {
const { engine, root } = brain;
expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
for (const slug of ['notes/db', 'notes/both']) { await engine.createVersion(slug, { sourceId: 'default' }); await databaseOnlyEdit(engine, slug, DB_EDIT(slug)); }
await databaseOnlyEdit(engine, 'notes/none', DB_EDIT('notes/none'));
for (const slug of ['notes/db', 'notes/file', 'notes/both', 'notes/none']) await dropImportRecord(engine, slug);
for (const slug of ['notes/file', 'notes/both']) writeFileSync(join(root, `${slug}.md`), note(slug, GIT_EDIT(slug)));
git(root, 'commit', '-qam', 'plain git edit');
await engine.executeRaw("UPDATE pages SET updated_at = now() + interval '30 days' WHERE source_id='default' AND slug IN ('notes/file','notes/both')");
}
/** The owner's decisions for the two undecided pages, written as the review list with "decision" filled in. */
async function decide(brain: ManagedBrain, dir: string, picks: Record<string, ConversionDecision['decision']>): Promise<ConversionDecision[]> {
const list = await conversionReviewList(brain.engine, await planGitConversion(brain.engine, 'default'));
const file = join(dir, 'decisions.json');
await writeConversionFile(brain.engine, file, '--list-out', { ...list, pages: list.pages.map(entry => ({ ...(entry as object), decision: picks[(entry as { slug: string }).slug] ?? null })) });
return readConversionDecisions(brain.engine, file, 'default');
}
for (const backend of testBackends()) describe(`[${backend}] conversion by content evidence (convergence PR A)`, () => {
const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
const outside = () => { const dir = mkdtempSync(join(tmpdir(), 'gbrain-conversion-files-')); return { dir, done: () => rmSync(dir, { recursive: true, force: true }) }; };
test('d4 and the timestamp trap: each page goes to the side that moved, and the undecided ones wait on a decisions file bound into the hash', () => managedBrain(async brain => {
const { engine, root } = brain;
const files = outside();
try {
await evidenceSource(brain);
const plan = await planGitConversion(engine, 'default');
expect(plan.preview).toMatchObject({ evidence: { count: 4, by: { adopt_db_moved: 1, git_wins_file_moved: 1, both_moved: 1, no_evidence: 1 } },
git_wins: { by: { file_moved: 1 } }, discard: { count: 2, by: { no_record_both_moved: 1, no_record_no_evidence: 1 } }, decisions: { digest: null } });
expect(plan.preview.adopt.sample).toEqual(['notes/db.md']);
expect(plan.preview.git_wins.sample).toEqual(['notes/file.md']);
await expect(applyGitConversion(engine, 'default', plan.preview.preview_hash, PROCESSING)).rejects.toMatchObject({ code: 'git_conversion_blocked' });
// Item 2: the review list and decisions are written 0600 and refused under a source root.
await expect(writeConversionFile(engine, join(root, 'review.json'), '--list-out', {})).rejects.toMatchObject({ code: 'conversion_file_in_source_root' });
expect((await cli(engine, ['default', '--to', 'git', '--dry-run', '--list-out', join(root, 'notes', 'review.json')]))).toMatchObject({ status: 'refused', code: 'conversion_file_in_source_root' });
const list = await conversionReviewList(engine, plan);
expect(list.pages.map(entry => (entry as { slug: string }).slug).sort()).toEqual(['notes/both', 'notes/none']);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
expect(statSync(join(files.dir, 'decisions.json')).mode & 0o777).toBe(0o600);
const decided = await planGitConversion(engine, 'default', { decisions });
expect(decided.preview).toMatchObject({ discard: { count: 0 }, decisions: { applied: 2, stale: 0, unused: 0 }, git_wins: { by: { file_moved: 1, decided: 1 } } });
expect(decided.preview.decisions.digest).not.toBeNull();
expect(decided.preview.preview_hash).not.toBe(plan.preview.preview_hash);
await expect(applyGitConversion(engine, 'default', decided.preview.preview_hash, PROCESSING)).rejects.toMatchObject({ code: 'preview_changed' });
// A decision names a page at its revision: once the page moves again, the decision is stale and not applied.
await databaseOnlyEdit(engine, 'notes/none', 'Edited once more.');
expect((await planGitConversion(engine, 'default', { decisions })).preview).toMatchObject({ decisions: { applied: 1, stale: 1 }, discard: { by: { no_record_no_evidence: 1 } } });
await databaseOnlyEdit(engine, 'notes/none', DB_EDIT('notes/none'));
const again = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const final = await planGitConversion(engine, 'default', { decisions: again });
// The printed apply carries the decisions file the hash binds, so running it exactly as printed applies.
const printed = await cli(engine, ['default', '--to', 'git', '--dry-run', '--decisions', join(files.dir, 'decisions.json')]);
expect(printed.apply).toEqual(['gbrain', 'sources', 'canonical', 'default', '--to', 'git', '--apply', '--expect', final.preview.preview_hash, '--decisions', join(files.dir, 'decisions.json')]);
expect(again).toHaveLength(2);
expect(await cli(engine, [...printed.apply.slice(3), '--no-embed', '--no-extract'])).toMatchObject({ status: 'converted', reclassified: [] });
expect(await body(engine, 'notes/file')).toContain(GIT_EDIT('notes/file'));
expect(await body(engine, 'notes/both')).toContain(GIT_EDIT('notes/both'));
expect(await body(engine, 'notes/db')).toContain(DB_EDIT('notes/db'));
expect(readFileSync(join(root, 'notes/db.md'), 'utf8')).toContain(DB_EDIT('notes/db'));
expect(readFileSync(join(root, 'notes/none.md'), 'utf8')).toContain(DB_EDIT('notes/none'));
expect(await strict(engine)).toBe(true);
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 3: a database write that races the recheck is held, never overwritten, and the source stays mixed', () => managedBrain(async brain => {
const { engine, root } = brain;
const files = outside();
try {
await evidenceSource(brain);
const base = git(root, 'rev-parse', 'HEAD');
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const { preview } = await planGitConversion(engine, 'default', { decisions });
installFaultHook(async point => { if (point === 'conversion:after_recheck') await databaseOnlyEdit(engine, 'notes/file', 'A racing database write.'); });
let error: unknown;
try { await applyGitConversion(engine, 'default', preview.preview_hash, { ...PROCESSING, decisions }); } catch (caught) { error = caught; } finally { installFaultHook(undefined); }
expect(error).toMatchObject({ code: 'git_conversion_incomplete', detail: 'changed_since_preview' });
expect(await body(engine, 'notes/file')).toBe('A racing database write.');
expect(await strict(engine)).toBe(false);
expect(await holds(engine)).toContain('notes/file.md');
expect(conversionRecovery(error)).toMatchObject({ mode: 'mixed', reclassified: ['notes/file.md'], commits: conversionShas(root, base), rollback: [] });
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
const staleHold = async (engine: BrainEngine, incarnation: string, slug: string) => {
const [page] = await engine.executeRaw<{ id: string }>("SELECT id::text FROM pages WHERE source_id='default' AND slug=$1", [slug]);
await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation, path: `${slug}.md`, source_path: `${slug}.md`, slug, page_id: Number(page!.id),
code: 'concurrent_write', message: 'A write moved the page during the pass.', upstream_version: '0'.repeat(64), observed_at: new Date().toISOString(),
run_id: null, mode: 'managed', meta: { recovery_version: 1, blob_oid: '0'.repeat(40) } }));
};
test('item 3: a hold written after the plan over a page that moved since is bound, so its re-run never imports over the database', () => managedBrain(async brain => {
const { engine } = brain;
const files = outside();
try {
await evidenceSource(brain);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const plan = await planGitConversion(engine, 'default', { decisions });
installFaultHook(async point => {
if (point !== 'conversion:after_recheck') return;
await databaseOnlyEdit(engine, 'notes/file', 'A racing database write under a hold.');
await staleHold(engine, plan.incarnation, 'notes/file');
});
let error: unknown;
try { await applyGitConversion(engine, 'default', plan.preview.preview_hash, { ...PROCESSING, decisions }); } catch (caught) { error = caught; } finally { installFaultHook(undefined); }
expect(error).toMatchObject({ code: 'git_conversion_incomplete', detail: 'changed_since_preview' });
expect(await body(engine, 'notes/file')).toBe('A racing database write under a hold.');
expect(conversionRecovery(error)).toMatchObject({ mode: 'mixed', reclassified: ['notes/file.md'] });
expect(await strict(engine)).toBe(false);
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 3: a planned hold another run replaced after the plan stops the apply before any strict pass', () => managedBrain(async brain => {
const { engine } = brain;
const files = outside();
try {
await evidenceSource(brain);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
await staleHold(engine, (await planGitConversion(engine, 'default')).incarnation, 'notes/same');
const plan = await planGitConversion(engine, 'default', { decisions });
expect(plan.holds.map(hold => hold.path)).toEqual(['notes/same.md']);
installFaultHook(async point => {
if (point !== 'conversion:after_recheck') return;
await new Promise(resolve => setTimeout(resolve, 5));
await staleHold(engine, plan.incarnation, 'notes/same');
});
let error: unknown;
try { await applyGitConversion(engine, 'default', plan.preview.preview_hash, { ...PROCESSING, decisions }); } catch (caught) { error = caught; } finally { installFaultHook(undefined); }
expect(error).toMatchObject({ code: 'git_conversion_incomplete', detail: 'changed_since_preview' });
expect(conversionRecovery(error)).toMatchObject({ mode: 'mixed', phase: 'holds' });
expect(await strict(engine)).toBe(false);
expect(await holds(engine)).toContain('notes/same.md');
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 6: a failure after the flip reports the mode, commits, push and writes, and the rollback keeps the adopted pages\' live content', () => managedBrain(async brain => {
const { engine, root } = brain;
const files = outside();
try {
await evidenceSource(brain);
const base = git(root, 'rev-parse', 'HEAD');
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const { preview } = await planGitConversion(engine, 'default', { decisions });
let error: unknown;
try {
await applyGitConversion(engine, 'default', preview.preview_hash, { ...PROCESSING, decisions, onProgress: progress => { if (progress.phase === 'strict_pass_2') throw new Error('stopped in the second strict pass'); } });
} catch (caught) { error = caught; }
expect(String(error)).toContain('stopped in the second strict pass');
const recovery = conversionRecovery(error)!;
expect(recovery).toMatchObject({ mode: 'git', phase: 'strict_pass_2', accepted: { adopted: 2, withheld: 0 }, push: { state: expect.any(String) },
rollback: [['gbrain', 'sources', 'reindex', 'default', '--from-git', '--dry-run'], ['gbrain', 'sources', 'canonical', 'default', '--to', 'mixed', '--dry-run']] });
expect(recovery.commits).toEqual(conversionShas(root, base));
expect(recovery.commits.length).toBeGreaterThan(0);
const live = { db: await body(engine, 'notes/db'), none: await body(engine, 'notes/none') };
const reindex = await previewReindex(engine, 'default');
await runSourcesReindex(engine, ['default', '--from-git', '--apply', '--expect', reindex.preview_hash, '--no-embed', '--no-extract', '--json']);
expect(await applyMixedConversion(engine, 'default', (await planMixedConversion(engine, 'default')).preview_hash)).toEqual({ status: 'mixed', source_id: 'default' });
expect(await strict(engine)).toBe(false);
expect(await body(engine, 'notes/db')).toBe(live.db);
expect(await body(engine, 'notes/none')).toBe(live.none);
expect(live.db).toContain(DB_EDIT('notes/db'));
expect(live.none).toContain(DB_EDIT('notes/none'));
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 7: a commit between approval and apply leaves the changed page unapplied and lists the delta with counts', () => managedBrain(async brain => {
const { engine, root } = brain;
const files = outside();
try {
await evidenceSource(brain);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const approvalFile = join(files.dir, 'approval.json');
const written = await cli(engine, ['default', '--to', 'git', '--dry-run', '--decisions', join(files.dir, 'decisions.json'), '--approval-out', approvalFile]);
expect(written.written.approval).toBe(approvalFile);
expect(statSync(approvalFile).mode & 0o777).toBe(0o600);
const approval = await readConversionApproval(engine, approvalFile, 'default');
expect(approval).toMatchObject({ kind: 'gbrain-conversion-approval', decisions: decisions.map(d => ({ slug: d.slug })) });
expect(approval).toEqual(conversionApproval(await planGitConversion(engine, 'default', { decisions })));
writeFileSync(join(root, 'notes/db.md'), note('notes/db', 'A commit that landed after the approval.'));
git(root, 'commit', '-qam', 'a commit after the approval');
const result = await applyApprovedConversion(engine, 'default', approval, PROCESSING);
expect(result).toMatchObject({ status: 'delta', committed: { pages: 1 } });
expect(result.delta!.items).toContainEqual({ item: 'adopt:notes/db.md', reason: 'changed' });
expect(result.delta!.count).toBe(Object.values(result.delta!.by).reduce((a, b) => a + b, 0));
expect(result.delta!.count).toBeGreaterThan(0);
expect(await strict(engine)).toBe(false);
expect(await body(engine, 'notes/db')).toContain(DB_EDIT('notes/db'));
expect(readFileSync(join(root, 'notes/db.md'), 'utf8')).toContain('A commit that landed after the approval.');
expect(readFileSync(join(root, 'notes/none.md'), 'utf8')).toContain(DB_EDIT('notes/none'));
const refused = await cli(engine, ['default', '--to', 'git', '--apply', '--approved', approvalFile, '--no-embed', '--no-extract']);
expect(refused).toMatchObject({ status: 'delta', code: 'git_conversion_delta' });
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 6: a partial approved apply that fails after a commit reports that commit; an approval\'s decisions are checked like a decisions file', () => managedBrain(async brain => {
const { engine, root } = brain;
const files = outside();
try {
await evidenceSource(brain);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const approval = conversionApproval(await planGitConversion(engine, 'default', { decisions }));
const twice = join(files.dir, 'twice.json');
await writeConversionFile(engine, twice, '--approval-out', { ...approval, decisions: [...approval.decisions, approval.decisions[0]] });
await expect(readConversionApproval(engine, twice, 'default')).rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('decided twice') });
const noItems = join(files.dir, 'no-items.json');
await writeConversionFile(engine, noItems, '--approval-out', { ...approval, items: null });
await expect(readConversionApproval(engine, noItems, 'default')).rejects.toMatchObject({ code: 'invalid_params' });
writeFileSync(`${join(files.dir, 'stale.json')}.${process.pid}.tmp`, '');
await expect(writeConversionFile(engine, join(files.dir, 'stale.json'), '--approval-out', approval)).rejects.toMatchObject({ code: 'invalid_params' });
expect(await cli(engine, ['constructor', '--to', 'git', '--dry-run'])).not.toMatchObject({ message: expect.stringContaining('needs a file path') });
writeFileSync(join(root, 'notes/db.md'), note('notes/db', 'A commit that landed after the approval.'));
git(root, 'commit', '-qam', 'a commit after the approval');
const base = git(root, 'rev-parse', 'HEAD');
installFaultHook(async point => { if (point === 'conversion:group_committed') throw new Error('injected after the first group'); });
let error: unknown;
try { await applyApprovedConversion(engine, 'default', approval, PROCESSING); } catch (caught) { error = caught; } finally { installFaultHook(undefined); }
expect(error).toMatchObject({ message: 'injected after the first group' });
expect(conversionShas(root, base)).toHaveLength(1);
expect(conversionRecovery(error)).toMatchObject({ mode: 'mixed', phase: 'adopt', commits: conversionShas(root, base), rollback: [] });
expect(await strict(engine)).toBe(false);
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
test('item 7: an approval nothing moved under applies whole, as its hash would', () => managedBrain(async brain => {
const { engine } = brain;
const files = outside();
try {
await evidenceSource(brain);
const decisions = await decide(brain, files.dir, { 'notes/both': 'git_wins', 'notes/none': 'adopt' });
const incarnation = (await planGitConversion(engine, 'default')).incarnation;
await staleHold(engine, incarnation, 'notes/same');
const approval = conversionApproval(await planGitConversion(engine, 'default', { decisions }));
// A sync re-screening a held path rewrites only its observed_at: the approval still applies whole.
await new Promise(resolve => setTimeout(resolve, 5));
await staleHold(engine, incarnation, 'notes/same');
expect(await applyApprovedConversion(engine, 'default', approval, PROCESSING)).toMatchObject({ status: 'converted', committed: { pages: 2 }, holds_cleared: 1 });
expect(await strict(engine)).toBe(true);
} finally { files.done(); }
}, { databaseUrl, setup }), 240_000);
});