Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* BrainEngine parity — pages family (CRUD, soft delete, listing, slugs, tags).
*
* Authoring gate (docs/TESTING.md#authoring-gate):
* - Contract: every page read/write method returns the same observable
* result on every engine arm (PGLite always; Postgres with DATABASE_URL;
* a Rust arm later through test/engine-parity/harness.ts).
* - Regression: an engine that drifts on page round-trip, soft-delete
* visibility, slug resolution, listing order or tag sets — the read
* paths every brain query starts from.
* - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips
* entirely without Postgres and covers mostly search/graph; the
* per-engine unit tests never compare two engines on one scenario.
* - Seam: none. Real engines, typed methods only (no executeRaw: D18).
*/
import { describe, expect } from 'bun:test';
import type { BrainEngine } from '../../src/core/engine.ts';
import { parseFindPattern } from '../../src/core/page-find.ts';
import type { Page, PageInput } from '../../src/core/types.ts';
import { createSource, parityArms, pick, sorted } from './harness.ts';
import { testBackends } from '../helpers/test-backends.ts';
const { parityTest } = parityArms(testBackends());
const PAGE_KEYS = ['slug', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter'] as const;
function view(page: Page | null) {
return page ? pick(page, PAGE_KEYS) : null;
}
async function seed(engine: BrainEngine, pages: Array<[string, PageInput]>, opts?: { sourceId?: string }) {
for (const [slug, input] of pages) await engine.putPage(slug, input, opts);
}
const ALICE: PageInput = {
type: 'person',
title: 'Alice Example',
compiled_truth: 'Alice runs product at acme-example.',
timeline: '- 2026-01-02: joined acme-example',
frontmatter: { role: 'pm', tags: ['founder'] },
};
const ACME: PageInput = { type: 'company', title: 'Acme Example', compiled_truth: 'Acme builds widgets.', timeline: '' };
const NOTE: PageInput = { type: 'note', title: 'Weekly note', compiled_truth: 'Met alice-example about widgets.', timeline: '' };
describe('engine parity: pages', () => {
parityTest('putPage then getPage round-trips the page', { methods: ['putPage', 'getPage'] }, async (engine) => {
const written = await engine.putPage('people/alice-example', ALICE);
expect(written.slug).toBe('people/alice-example');
const read = await engine.getPage('people/alice-example');
expect(read?.title).toBe('Alice Example');
expect(read?.frontmatter.role).toBe('pm');
const missing = await engine.getPage('people/nobody');
expect(missing).toBeNull();
return { written: view(written), read: view(read), missing };
});
parityTest('putPage on an existing slug updates in place', { methods: ['putPage', 'getPage', 'listPages'] }, async (engine) => {
const first = await engine.putPage('companies/acme-example', ACME);
const second = await engine.putPage('companies/acme-example', { ...ACME, compiled_truth: 'Acme builds better widgets.' });
expect(second.id).toBe(first.id);
const read = await engine.getPage('companies/acme-example');
expect(read?.compiled_truth).toBe('Acme builds better widgets.');
const all = await engine.listPages();
expect(all.map((p) => p.slug)).toEqual(['companies/acme-example']);
return { read: view(read), count: all.length };
});
parityTest(
'softDeletePage hides a page; restorePage brings it back',
{ methods: ['softDeletePage', 'restorePage', 'getPage', 'listPages', 'getAllSlugs'] },
async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);
const deleted = await engine.softDeletePage('people/alice-example');
expect(deleted).toEqual({ slug: 'people/alice-example' });
const again = await engine.softDeletePage('people/alice-example');
const hidden = await engine.getPage('people/alice-example');
expect(hidden).toBeNull();
const visibleWithFlag = await engine.getPage('people/alice-example', { includeDeleted: true });
expect(visibleWithFlag?.deleted_at).toBeInstanceOf(Date);
const listed = (await engine.listPages()).map((p) => p.slug);
const slugsWhileDeleted = sorted(await engine.getAllSlugs());
const restored = await engine.restorePage('people/alice-example');
expect(restored).toBe(true);
const restoredAgain = await engine.restorePage('people/alice-example');
expect(restoredAgain).toBe(false);
const back = await engine.getPage('people/alice-example');
expect(back?.deleted_at ?? null).toBeNull();
return { again, listed, slugsWhileDeleted, back: view(back) };
},
);
parityTest('deletePage removes the page for good', { methods: ['deletePage', 'getPage', 'getAllSlugs'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);
await engine.deletePage('people/alice-example');
const gone = await engine.getPage('people/alice-example', { includeDeleted: true });
expect(gone).toBeNull();
const slugs = sorted(await engine.getAllSlugs());
expect(slugs).toEqual(['companies/acme-example']);
return { slugs };
});
parityTest('listPages filters by type, tag, prefix and limit', { methods: ['listPages', 'addTag'] }, async (engine) => {
await seed(engine, [
['people/alice-example', ALICE],
['people/charlie-example', { ...ALICE, title: 'Charlie Example', frontmatter: {} }],
['companies/acme-example', ACME],
['notes/weekly', NOTE],
]);
await engine.addTag('companies/acme-example', 'portfolio');
const byType = sorted((await engine.listPages({ type: 'person' })).map((p) => p.slug));
expect(byType).toEqual(['people/alice-example', 'people/charlie-example']);
const byTag = (await engine.listPages({ tag: 'portfolio' })).map((p) => p.slug);
expect(byTag).toEqual(['companies/acme-example']);
const byPrefix = sorted((await engine.listPages({ slugPrefix: 'people/' })).map((p) => p.slug));
expect(byPrefix).toEqual(byType);
const limited = await engine.listPages({ limit: 2 });
expect(limited.length).toBe(2);
return { byType, byTag, byPrefix, limitedCount: limited.length };
});
parityTest('resolveSlugs matches exact and partial slugs', { methods: ['resolveSlugs'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME], ['notes/weekly', NOTE]]);
const exact = await engine.resolveSlugs('people/alice-example');
expect(exact).toEqual(['people/alice-example']);
const partial = sorted(await engine.resolveSlugs('example'));
const none = await engine.resolveSlugs('zzz-no-such-page');
return { exact, partial, none };
});
parityTest('addTag, getTags and removeTag keep a set per page', { methods: ['addTag', 'getTags', 'removeTag'] }, async (engine) => {
await seed(engine, [['companies/acme-example', ACME]]);
await engine.addTag('companies/acme-example', 'portfolio');
await engine.addTag('companies/acme-example', 'b2b');
await engine.addTag('companies/acme-example', 'portfolio');
const tags = sorted(await engine.getTags('companies/acme-example'));
expect(tags).toEqual(['b2b', 'portfolio']);
await engine.removeTag('companies/acme-example', 'b2b');
const after = await engine.getTags('companies/acme-example');
expect(after).toEqual(['portfolio']);
return { tags, after };
});
parityTest('pages are scoped per source', { methods: ['putPage', 'getPage', 'getAllSlugs', 'listAllSources'] }, async (engine) => {
const sources = (await engine.listAllSources()).map((s) => s.id);
expect(sources).toContain('default');
await seed(engine, [['people/alice-example', ALICE]]);
const defaultSlugs = sorted(await engine.getAllSlugs({ sourceId: 'default' }));
const otherSlugs = sorted(await engine.getAllSlugs({ sourceId: 'no-such-source' }));
expect(otherSlugs).toEqual([]);
const scopedMiss = await engine.getPage('people/alice-example', { sourceId: 'no-such-source' });
expect(scopedMiss).toBeNull();
return { sources: sorted(sources), defaultSlugs, otherSlugs };
});
parityTest(
'readPageSnapshot and readPageSnapshotsBatch return page, tags and a revision',
{ methods: ['readPageSnapshot', 'readPageSnapshotsBatch'] },
async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);
await engine.addTag('people/alice-example', 'founder');
const snap = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });
expect(snap?.page.slug).toBe('people/alice-example');
expect(typeof snap?.revision).toBe('string');
const missing = await engine.readPageSnapshot('people/nobody', { sourceId: 'default' });
expect(missing).toBeNull();
const batch = await engine.readPageSnapshotsBatch([
{ slug: 'people/alice-example', sourceId: 'default' },
{ slug: 'people/nobody', sourceId: 'default' },
{ slug: 'companies/acme-example', sourceId: 'default' },
]);
expect(batch.covered).toBe(3);
const keys = sorted([...batch.snapshots.values()].map((v) => v.page.slug));
expect(keys).toEqual(['companies/acme-example', 'people/alice-example']);
const sameRevision = [...batch.snapshots.values()].find((v) => v.page.slug === 'people/alice-example')?.revision === snap?.revision;
expect(sameRevision).toBe(true);
await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'Alice now runs design.' }, { expectedRevision: snap!.revision });
const after = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });
expect(after?.revision).not.toBe(snap?.revision);
return { page: view(snap!.page), tags: snap!.tags, withdrawals: snap!.withdrawals, keys, covered: batch.covered, sameRevision };
},
);
parityTest('putPage refuses a stale expectedRevision', { methods: ['putPage', 'readPageSnapshot'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE]]);
const snap = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });
await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'first edit' }, { expectedRevision: snap!.revision });
let code: string | null = null;
try {
await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'second edit' }, { expectedRevision: snap!.revision });
} catch (error) {
code = (error as { code?: string }).code ?? 'threw';
}
expect(code).toBe('revision_conflict');
const read = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });
expect(read?.page.compiled_truth).toBe('first edit');
return { code, body: read?.page.compiled_truth };
});
parityTest('lockPageKeys holds keys inside a transaction', { methods: ['lockPageKeys', 'transaction'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE]]);
const result = await engine.transaction(async (tx) => {
await tx.lockPageKeys([{ sourceId: 'default', slug: 'people/alice-example' }, { sourceId: 'default', slug: 'people/absent' }]);
return (await tx.getPage('people/alice-example'))?.title ?? null;
});
// The recorded call must be on the handle too: lock nothing outside a transaction is a refusal.
let outside: string | null = null;
try {
await engine.lockPageKeys([{ sourceId: 'default', slug: 'people/alice-example' }]);
outside = 'ok';
} catch {
outside = 'refused';
}
expect(result).toBe('Alice Example');
return { result, outside };
});
parityTest(
'findDuplicatePage(s) match by content hash or frontmatter id, never the page itself',
{ methods: ['findDuplicatePage', 'findDuplicatePages'] },
async (engine) => {
const a = await engine.putPage('notes/a', { ...NOTE, frontmatter: { id: 'ext-1' } });
await engine.putPage('notes/b', { ...NOTE, title: 'Other', compiled_truth: 'different body' });
const byHash = await engine.findDuplicatePage!('default', { hash: a.content_hash! });
expect(byHash?.slug).toBe('notes/a');
const self = await engine.findDuplicatePage!('default', { hash: a.content_hash!, excludeSlug: 'notes/a' });
expect(self).toBeNull();
const byId = await engine.findDuplicatePage!('default', { hash: 'no-such-hash', frontmatterId: 'ext-1' });
expect(byId?.slug).toBe('notes/a');
const many = await engine.findDuplicatePages!('default', [
{ hash: a.content_hash! },
{ hash: 'no-such-hash' },
{ hash: 'no-such-hash', frontmatterId: 'ext-1', excludeSlug: 'notes/a' },
]);
expect(many.map((m) => m?.slug ?? null)).toEqual(['notes/a', null, null]);
return { byHash: byHash?.slug, self, byId: byId?.slug, many: many.map((m) => m?.slug ?? null) };
},
);
parityTest('deletePages and softDeletePages report only real transitions', { methods: ['deletePages', 'softDeletePages', 'getAllSlugs'] }, async (engine) => {
await seed(engine, [['notes/a', NOTE], ['notes/b', NOTE], ['notes/c', NOTE], ['notes/d', NOTE]]);
const soft = sorted(await engine.softDeletePages(['notes/a', 'notes/b', 'notes/missing'], { sourceId: 'default' }));
expect(soft).toEqual(['notes/a', 'notes/b']);
const softAgain = await engine.softDeletePages(['notes/a'], { sourceId: 'default' });
expect(softAgain).toEqual([]);
const softEmpty = await engine.softDeletePages([], { sourceId: 'default' });
const hard = sorted(await engine.deletePages(['notes/a', 'notes/c', 'notes/missing'], { sourceId: 'default' }));
expect(hard).toEqual(['notes/a', 'notes/c']);
const remaining = sorted(await engine.getAllSlugs());
return { soft, softAgain, softEmpty, hard, remaining };
});
parityTest('purgeDeletedPages only purges tombstones past the cutoff', { methods: ['purgeDeletedPages', 'softDeletePage'] }, async (engine) => {
await seed(engine, [['notes/a', NOTE], ['notes/b', NOTE]]);
await engine.softDeletePage('notes/a');
const notYet = await engine.purgeDeletedPages(72);
expect(notYet.count).toBe(0);
const dry = await engine.purgeDeletedPages(0, { dryRun: true });
expect(dry.slugs).toEqual(['notes/a']);
const stillThere = (await engine.getPage('notes/a', { includeDeleted: true }))?.slug ?? null;
const real = await engine.purgeDeletedPages(0);
expect(real.slugs).toEqual(['notes/a']);
const gone = await engine.getPage('notes/a', { includeDeleted: true });
expect(gone).toBeNull();
return {
notYet: { slugs: notYet.slugs, count: notYet.count },
dry: { slugs: dry.slugs, count: dry.count, pages: dry.pages?.map((p) => ({ slug: p.slug, source_id: p.source_id })) },
stillThere,
real: { slugs: real.slugs, count: real.count },
};
});
parityTest('resolveSlugsByPaths maps stored source paths to slugs', { methods: ['resolveSlugsByPaths'] }, async (engine) => {
await seed(engine, [['notes/a', { ...NOTE, source_path: 'Notes/A File.md' }], ['notes/b', NOTE]]);
const empty = await engine.resolveSlugsByPaths([], { sourceId: 'default' });
expect(empty.size).toBe(0);
const found = await engine.resolveSlugsByPaths(['Notes/A File.md', 'notes/zzz.md'], { sourceId: 'default' });
expect([...found]).toEqual([['Notes/A File.md', 'notes/a']]);
const otherSource = await engine.resolveSlugsByPaths(['Notes/A File.md'], { sourceId: 'no-such-source' });
expect(otherSource.size).toBe(0);
return { empty: [...empty], found: [...found], otherSource: [...otherSource] };
});
parityTest('findPages matches name, prefix and glob patterns', { methods: ['findPages'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['people/charlie-example', { ...ALICE, title: 'Charlie Example' }], ['companies/acme-example', ACME]]);
const run = async (raw: string, types?: string[]) => {
const found = await engine.findPages({ pattern: parseFindPattern(raw), limit: 10, types, excludeSlugPrefixes: [] });
return { total: found.total, rows: sorted(found.rows.map((r) => `${r.source_id}:${r.slug}:${r.type}`)) };
};
const name = await run('alice');
expect(name.rows).toEqual(['default:people/alice-example:person']);
const prefix = await run('people/');
expect(prefix.total).toBe(2);
const glob = await run('*example', ['company']);
expect(glob.rows).toEqual(['default:companies/acme-example:company']);
return { name, prefix, glob };
});
parityTest('countPagesBy counts live pages per source and type', { methods: ['countPagesBy'] }, async (engine) => {
await seed(engine, [['people/alice-example', ALICE], ['people/charlie-example', ALICE], ['companies/acme-example', ACME], ['notes/a', NOTE]]);
await engine.softDeletePage('notes/a');
const plain = await engine.countPagesBy({});
const grouped = await engine.countPagesBy({}, (types) => types.map((t) => (t === 'person' ? 'people' : 'other')));
expect(plain.total).toEqual({ pages: 3, distinct_slugs: 3 });
return {
bySourceType: sorted(plain.bySourceType, (r) => `${r.source_id}:${r.type}`),
total: plain.total,
byTypeGroup: sorted(grouped.byTypeGroup, (r) => r.group),
};
});
parityTest('listAllPageRefs lists every (source, slug) pair in order', { methods: ['listAllPageRefs'] }, async (engine, backend) => {
await createSource(engine, backend, 'work');
await seed(engine, [['notes/b', NOTE], ['notes/a', NOTE]]);
await seed(engine, [['notes/a', NOTE]], { sourceId: 'work' });
const refs = (await engine.listAllPageRefs()).map((r) => ({ source_id: r.source_id, slug: r.slug, dated: r.updated_at instanceof Date }));
expect(refs.map((r) => `${r.source_id}:${r.slug}`)).toEqual(['default:notes/a', 'default:notes/b', 'work:notes/a']);
return refs;
});
parityTest('listAllSources and updateSourceConfig merge config', { methods: ['listAllSources', 'updateSourceConfig'] }, async (engine, backend) => {
await createSource(engine, backend, 'work', { keep: 1 });
const updated = await engine.updateSourceConfig('work', { last_full_cycle_at: '2026-11-01T00:00:00Z' });
expect(updated).toBe(true);
const unknown = await engine.updateSourceConfig('no-such-source', { a: 1 });
expect(unknown).toBe(false);
const work = (await engine.listAllSources()).find((s) => s.id === 'work');
expect(work?.config).toMatchObject({ keep: 1, last_full_cycle_at: '2026-11-01T00:00:00Z' });
const ids = sorted((await engine.listAllSources()).map((s) => s.id));
const localOnly = (await engine.listAllSources({ localPathOnly: true })).map((s) => s.id);
return { ids, config: work?.config, localOnly };
});
parityTest('same slug in two sources stays separate', { methods: ['putPage', 'getPage', 'deletePage', 'resolveSlugs'] }, async (engine, backend) => {
await createSource(engine, backend, 'work');
await engine.putPage('notes/a', NOTE);
await engine.putPage('notes/a', { ...NOTE, title: 'Work note' }, { sourceId: 'work' });
const home = await engine.getPage('notes/a', { sourceId: 'default' });
const work = await engine.getPage('notes/a', { sourceId: 'work' });
expect(home?.title).toBe('Weekly note');
expect(work?.title).toBe('Work note');
const scoped = await engine.resolveSlugs('notes/a', { sourceId: 'work' });
await engine.deletePage('notes/a', { sourceId: 'work' });
const afterDelete = { home: (await engine.getPage('notes/a', { sourceId: 'default' }))?.title ?? null, work: await engine.getPage('notes/a', { sourceId: 'work' }) };
expect(afterDelete).toEqual({ home: 'Weekly note', work: null });
return { scoped, afterDelete };
});
parityTest('listPrefixSampledPages and listCorpusSample sample live pages', { methods: ['listPrefixSampledPages', 'listCorpusSample'] }, async (engine) => {
await seed(engine, [
['wiki/vc/one', NOTE], ['wiki/vc/two', NOTE], ['wiki/bio/one', NOTE], ['notes/a', NOTE],
]);
await engine.softDeletePage('wiki/vc/two');
const prefixed = await engine.listPrefixSampledPages({ prefixes: ['wiki/vc', 'wiki/bio'] });
const prefixedView = sorted(prefixed.map((r) => `${r.prefix}:${r.slug}:${r.connection_count}`));
expect(prefixedView).toEqual(['wiki/bio:wiki/bio/one:0', 'wiki/vc:wiki/vc/one:0']);
const sample = await engine.listCorpusSample({ n: 10, excludeSlugs: ['notes/a'], seed: 7 });
const sampleSlugs = sorted(sample.map((r) => r.slug));
expect(sampleSlugs).toEqual(['wiki/bio/one', 'wiki/vc/one']);
return { prefixedView, sampleSlugs };
});
});