Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.32.2 — migration orchestrator tests.
*
* Covers phaseASchema (asserts v51 ran), phaseBFenceFacts (legacy
* row → fence backfill happy path, idempotent re-run, dry-run, NULL
* entity_slug skip, missing local_path skip), and phaseCVerify
* (mismatch detection).
*
* Real PGLite + real tempdir filesystem. Engine injected via
* __setTestEngineOverride so we don't need a configured brain.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from 'bun:test';
import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { v0_32_2, __setTestEngineOverride, __testing } from '../src/commands/migrations/v0_32_2.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import { parseFactsFence, renderFactsTable, replaceOrInsertFactsFence, upsertFactRow, type ParsedFact } from '../src/core/facts-fence.ts';
let engine: PGLiteEngine;
let brainDir: string;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
__setTestEngineOverride(engine);
});
afterAll(async () => {
__setTestEngineOverride(null);
await engine.disconnect();
});
beforeEach(async () => {
brainDir = mkdtempSync(join(tmpdir(), 'mig-v0_32_2-test-'));
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query('DELETE FROM facts');
await engine.executeRaw('DELETE FROM pages');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`UPDATE sources SET local_path = $1 WHERE id = 'default'`,
[brainDir],
);
});
const OPTS = { yes: true, dryRun: false, noAutopilotInstall: true };
const DRY_OPTS = { ...OPTS, dryRun: true };
async function seedLegacyFact(input: {
entity_slug: string | null;
fact: string;
source_id?: string;
visibility?: 'private' | 'world';
notability?: 'high' | 'medium' | 'low';
withPage?: boolean;
}): Promise<number> {
const sourceId = input.source_id ?? 'default';
if (input.entity_slug && input.withPage !== false &&
!await engine.getPage(input.entity_slug, { sourceId })) {
await engine.putPage(input.entity_slug, {
type: 'note', title: input.entity_slug, compiled_truth: '# Existing page\n', frontmatter: {},
}, { sourceId });
const sources = await engine.executeRaw<{ local_path: string | null }>(
'SELECT local_path FROM sources WHERE id = $1', [sourceId],
);
const root = sources[0]?.local_path;
if (root) {
const path = join(root, `${input.entity_slug}.md`);
mkdirSync(join(path, '..'), { recursive: true });
if (!existsSync(path)) writeFileSync(path, '# Existing page\n');
}
}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const r = await (engine as any).db.query(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence)
VALUES ($1, $2, $3, 'fact', $4, $5, now(), 'mcp:put_page', 1.0)
RETURNING id`,
[
input.source_id ?? 'default',
input.entity_slug,
input.fact,
input.visibility ?? 'private',
input.notability ?? 'medium',
],
);
return r.rows[0].id;
}
describe('phaseASchema', () => {
test('passes when schema is at v51', async () => {
// initSchema ran v51, so the version config + columns are set.
const r = await __testing.phaseASchema(engine, OPTS);
expect(r.status).toBe('complete');
});
test('skipped under dry-run', async () => {
const r = await __testing.phaseASchema(engine, DRY_OPTS);
expect(r.status).toBe('skipped');
expect(r.detail).toBe('dry-run');
});
test('skipped when no engine is available', async () => {
const r = await __testing.phaseASchema(null, OPTS);
expect(r.status).toBe('skipped');
expect(r.detail).toBe('no_brain_configured');
});
});
describe('phaseBFenceFacts — dry-run reporting', () => {
test('reports counts without writing FS or updating DB', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Founded Acme' });
await seedLegacyFact({ entity_slug: 'people/bob', fact: 'Met at YC W22' });
await seedLegacyFact({ entity_slug: null, fact: 'Unparented claim' });
const r = await __testing.phaseBFenceFacts(engine, DRY_OPTS);
expect(r.status).toBe('skipped');
expect(r.detail).toContain('dry-run');
expect(r.detail).toContain('would fence 2 rows'); // 3 total - 1 unparented
expect(r.detail).toContain('1 unfenceable');
expect(readFileSync(join(brainDir, 'people/alice.md'), 'utf8')).toBe('# Existing page\n');
expect(readFileSync(join(brainDir, 'people/bob.md'), 'utf8')).toBe('# Existing page\n');
// DB rows still have NULL row_num.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num FROM facts WHERE entity_slug IS NOT NULL',
);
expect(rows.rows.every((r: { row_num: number | null }) => r.row_num === null)).toBe(true);
});
});
describe('phaseBFenceFacts — happy path backfill', () => {
test('fences legacy DB rows into entity pages + updates row_num', async () => {
const id1 = await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Founded Acme in 2017' });
const id2 = await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Prefers async over meetings' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('fenced=2');
expect(r.detail).toContain('pages=1');
// Existing page now has fence content.
const filePath = join(brainDir, 'people/alice.md');
expect(existsSync(filePath)).toBe(true);
const body = readFileSync(filePath, 'utf-8');
expect(body).toContain('## Facts');
expect(body).toContain('Founded Acme in 2017');
expect(body).toContain('Prefers async over meetings');
// DB rows now have row_num + source_markdown_slug populated.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT id, row_num, source_markdown_slug FROM facts ORDER BY id',
);
expect(rows.rows[0]).toMatchObject({ id: id1, row_num: 1, source_markdown_slug: 'people/alice' });
expect(rows.rows[1]).toMatchObject({ id: id2, row_num: 2, source_markdown_slug: 'people/alice' });
});
test('groups by entity page — multi-entity batch touches multiple files', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'A1' });
await seedLegacyFact({ entity_slug: 'companies/acme', fact: 'C1' });
await seedLegacyFact({ entity_slug: 'deals/seed', fact: 'D1' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('fenced=3');
expect(r.detail).toContain('pages=3');
expect(existsSync(join(brainDir, 'people/alice.md'))).toBe(true);
expect(existsSync(join(brainDir, 'companies/acme.md'))).toBe(true);
expect(existsSync(join(brainDir, 'deals/seed.md'))).toBe(true);
});
test('appends to existing entity page without overwriting body', async () => {
mkdirSync(join(brainDir, 'people'), { recursive: true });
writeFileSync(
join(brainDir, 'people/alice.md'),
'---\ntype: person\ntitle: Alice\nslug: people/alice\n---\n\n# Alice\n\nNotes about Alice.\n',
'utf-8',
);
// #6982: the page's database body is the file's, as an import leaves it; a differing body is held, not overwritten.
await engine.putPage('people/alice', { type: 'person', title: 'Alice', compiled_truth: '# Alice\n\nNotes about Alice.', frontmatter: {} });
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Founded Acme' });
await __testing.phaseBFenceFacts(engine, OPTS);
const body = readFileSync(join(brainDir, 'people/alice.md'), 'utf-8');
expect(body).toContain('Notes about Alice.'); // preserved
expect(body).toContain('## Facts');
expect(body).toContain('Founded Acme');
});
test('idempotent: re-running after partial completion does NOT duplicate rows', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'First' });
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Second' });
await __testing.phaseBFenceFacts(engine, OPTS);
// Manually clear one row's row_num to simulate a partial state.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`UPDATE facts SET row_num = NULL, source_markdown_slug = NULL
WHERE fact = 'Second'`,
);
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
// The re-run should reuse the existing row_num=2 (matched by claim
// content) rather than appending a new row_num=3.
const body = readFileSync(join(brainDir, 'people/alice.md'), 'utf-8');
const parsed = parseFactsFence(body);
expect(parsed.facts).toHaveLength(2);
expect(parsed.facts.map(f => f.claim).sort()).toEqual(['First', 'Second']);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
'SELECT row_num FROM facts WHERE row_num IS NOT NULL ORDER BY row_num',
);
expect(rows.rows.map((r: { row_num: number }) => r.row_num)).toEqual([1, 2]);
});
test('skips facts with NULL entity_slug (unfenceable)', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Fenceable' });
await seedLegacyFact({ entity_slug: null, fact: 'Unfenceable' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('fenced=1');
expect(r.detail).toContain('skipped_no_entity=1');
// The unparented fact's row_num remains NULL.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query(
`SELECT entity_slug, row_num FROM facts ORDER BY id`,
);
expect(rows.rows[0]).toMatchObject({ entity_slug: 'people/alice', row_num: 1 });
expect(rows.rows[1]).toMatchObject({ entity_slug: null, row_num: null });
});
test('skips when source has no local_path', async () => {
// Wipe default source's local_path.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`UPDATE sources SET local_path = NULL WHERE id = 'default'`);
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Whatever' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('skipped_no_local_path=1');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT row_num FROM facts');
expect(rows.rows[0].row_num).toBeNull();
});
});
describe('phaseBFenceFacts — missing pages and occupied fence rows', () => {
const slug = 'people/alice-example';
async function page(body = '# Existing notes\n', sourcePath = `${slug}.md`): Promise<string> {
await engine.putPage(slug, {
type: 'person', title: 'Alice Example', compiled_truth: body, frontmatter: {}, source_path: sourcePath,
}, { sourceId: 'default' });
const filePath = join(brainDir, sourcePath);
mkdirSync(join(filePath, '..'), { recursive: true });
writeFileSync(filePath, body);
return filePath;
}
test('skips unresolved root slugs and missing page files without creating stubs or deleting facts', async () => {
const existingPath = await page();
await seedLegacyFact({ entity_slug: slug, fact: 'Existing page fact' });
await seedLegacyFact({ entity_slug: 'missing-example', fact: 'Unresolved root fact', withPage: false });
await seedLegacyFact({ entity_slug: 'projects/missing-example', fact: 'Missing prefixed fact', withPage: false });
await engine.putPage('projects/missing-example', {
type: 'project', title: 'Missing Example', compiled_truth: 'DB-only page', frontmatter: {},
}, { sourceId: 'default' });
const result = await __testing.phaseBFenceFacts(engine, OPTS);
expect(result.status).toBe('complete');
expect(result.detail).toContain('skipped_no_page=2');
expect(result.detail).toContain('fenced=1');
expect(existsSync(join(brainDir, 'missing-example.md'))).toBe(false);
expect(existsSync(join(brainDir, 'projects/missing-example.md'))).toBe(false);
expect(readFileSync(existingPath, 'utf8')).toContain('# Existing notes');
const rows = await engine.executeRaw<{ fact: string; row_num: number | null }>(
`SELECT fact, row_num FROM facts ORDER BY id`,
);
expect(rows).toEqual([
{ fact: 'Existing page fact', row_num: 1 },
{ fact: 'Unresolved root fact', row_num: null },
{ fact: 'Missing prefixed fact', row_num: null },
]);
});
test('requires a live entity page in the fact source even when an orphan file exists', async () => {
await engine.executeRaw(`INSERT INTO sources (id, name) VALUES ('migration-other', 'Other') ON CONFLICT DO NOTHING`);
await engine.putPage('foreign-example', {
type: 'note', title: 'Foreign Example', compiled_truth: 'Other source', frontmatter: {},
}, { sourceId: 'migration-other' });
const orphan = join(brainDir, 'foreign-example.md');
writeFileSync(orphan, '# Local orphan file\n');
await seedLegacyFact({ entity_slug: 'foreign-example', fact: 'Keep unparented', withPage: false });
const result = await __testing.phaseBFenceFacts(engine, OPTS);
expect(result.detail).toContain('skipped_no_page=1');
expect(readFileSync(orphan, 'utf8')).toBe('# Local orphan file\n');
});
test('dry-run reports missing pages and a dirty source containing only unfenceable facts is a no-op', async () => {
execFileSync('git', ['-C', brainDir, 'init', '-q']);
writeFileSync(join(brainDir, 'unrelated.md'), '# Uncommitted notes\n');
await seedLegacyFact({ entity_slug: 'missing-example', fact: 'No target', withPage: false });
const dry = await __testing.phaseBFenceFacts(engine, DRY_OPTS);
expect(dry.status).toBe('skipped');
expect(dry.detail).toContain('would fence 0 rows');
expect(dry.detail).toContain('skipped_no_page=1');
const write = await __testing.phaseBFenceFacts(engine, OPTS);
expect(write.status).toBe('complete');
expect(write.detail).toContain('skipped_no_page=1');
expect(existsSync(join(brainDir, 'missing-example.md'))).toBe(false);
});
test('writes and verifies the recorded page path instead of creating a slug-named twin', async () => {
const path = await page('# Existing notes\n', 'People/Alice Example.md');
await seedLegacyFact({ entity_slug: slug, fact: 'Recorded file fact' });
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('complete');
expect(parseFactsFence(readFileSync(path, 'utf8')).facts[0]?.claim).toBe('Recorded file fact');
expect(existsSync(join(brainDir, `${slug}.md`))).toBe(false);
expect((await __testing.phaseCVerify(engine, OPTS)).status).toBe('complete');
});
test('allocates above DB-owned numbers after a markdown fence disappeared', async () => {
await page();
await engine.executeRaw(
`INSERT INTO facts (source_id, entity_slug, fact, kind, source, row_num, source_markdown_slug)
VALUES ('default', $1, 'Already indexed', 'fact', 'mcp:put_page', 7, $1)`, [slug],
);
await seedLegacyFact({ entity_slug: slug, fact: 'Needs fencing' });
const result = await __testing.phaseBFenceFacts(engine, OPTS);
expect(result.status).toBe('complete');
expect(await engine.executeRaw(`SELECT fact, row_num FROM facts ORDER BY row_num`)).toEqual([
{ fact: 'Already indexed', row_num: 7 }, { fact: 'Needs fencing', row_num: 8 },
]);
});
test('moves a stranded colliding row without dropping an earlier appended fact', async () => {
const body = upsertFactRow('# Existing notes\n', {
rowNum: 1, claim: 'Stranded fact', kind: 'fact', confidence: 1, visibility: 'private',
notability: 'medium', source: 'mcp:put_page',
}).body;
const path = await page(body);
await engine.executeRaw(
`INSERT INTO facts (source_id, entity_slug, fact, kind, source, row_num, source_markdown_slug)
VALUES ('default', $1, 'Already indexed', 'fact', 'mcp:put_page', 1, $1)`, [slug],
);
await seedLegacyFact({ entity_slug: slug, fact: 'Append before stranded' });
await seedLegacyFact({ entity_slug: slug, fact: 'Stranded fact' });
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('complete');
const facts = parseFactsFence(readFileSync(path, 'utf8')).facts;
expect(facts.map(f => [f.claim, f.rowNum])).toEqual([
['Stranded fact', 3], ['Append before stranded', 2],
]);
expect(await engine.executeRaw(`SELECT fact, row_num FROM facts ORDER BY row_num`)).toEqual([
{ fact: 'Already indexed', row_num: 1 },
{ fact: 'Append before stranded', row_num: 2 },
{ fact: 'Stranded fact', row_num: 3 },
]);
});
test('never lets two legacy rows claim the same stranded fence row', async () => {
const path = await page(upsertFactRow('# Notes\n', {
rowNum: 5, claim: 'Same claim', kind: 'fact', confidence: 1, visibility: 'private',
notability: 'medium', source: 'mcp:put_page',
}).body);
await seedLegacyFact({ entity_slug: slug, fact: 'Same claim' });
await seedLegacyFact({ entity_slug: slug, fact: 'Same claim', visibility: 'world' });
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('complete');
expect(parseFactsFence(readFileSync(path, 'utf8')).facts.map(f => f.rowNum)).toEqual([5, 6]);
expect((await __testing.phaseCVerify(engine, OPTS)).status).toBe('complete');
});
test('preserves a legitimate DB-owned matching fence row and appends the separate legacy fact', async () => {
const path = await page(upsertFactRow('# Notes\n', {
rowNum: 4, claim: 'Shared claim', kind: 'fact', confidence: 0.8, visibility: 'private',
notability: 'high', source: 'mcp:put_page', context: 'Original provenance',
claimMetric: 'count', claimValue: 8,
}).body);
await engine.executeRaw(
`INSERT INTO facts (source_id, entity_slug, fact, kind, source, row_num, source_markdown_slug)
VALUES ('default', $1, 'Shared claim', 'fact', 'mcp:put_page', 4, $1)`, [slug],
);
await seedLegacyFact({ entity_slug: slug, fact: 'Shared claim', visibility: 'world' });
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('complete');
const facts = parseFactsFence(readFileSync(path, 'utf8')).facts;
expect(facts).toHaveLength(2);
expect(facts[0]).toMatchObject({
rowNum: 4, claim: 'Shared claim', confidence: 0.8, visibility: 'private',
notability: 'high', context: 'Original provenance', claimMetric: 'count', claimValue: 8,
});
expect(facts[1]).toMatchObject({ rowNum: 5, claim: 'Shared claim', visibility: 'world' });
expect((await __testing.phaseCVerify(engine, OPTS)).status).toBe('complete');
});
test('does not re-fence soft-expired facts or rewrite a malformed existing fence', async () => {
const path = await page();
const id = await seedLegacyFact({ entity_slug: slug, fact: 'Withdrawn fact' });
await engine.executeRaw('UPDATE facts SET expired_at = now() WHERE id = $1', [id]);
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('complete');
expect(readFileSync(path, 'utf8')).toBe('# Existing notes\n');
expect((await engine.executeRaw<{ row_num: number | null }>(
'SELECT row_num FROM facts WHERE id = $1', [id],
))[0].row_num).toBeNull();
const malformed = '# Notes\n\n## Facts\n<!--- gbrain:facts:begin -->\n| not a valid header |\n<!--- gbrain:facts:end -->\n';
writeFileSync(path, malformed);
await seedLegacyFact({ entity_slug: slug, fact: 'New fact' });
expect((await __testing.phaseBFenceFacts(engine, OPTS)).status).toBe('failed');
expect(readFileSync(path, 'utf8')).toBe(malformed);
});
});
describe('subdirectory source dirty check', () => {
test('ignores sibling changes but refuses changes inside the source', async () => {
execFileSync('git', ['-C', brainDir, 'init', '-q']);
const sourcePath = join(brainDir, 'source');
mkdirSync(sourcePath);
writeFileSync(join(brainDir, 'sibling.md'), 'Unrelated change');
expect(__testing.isLocalPathDirty(sourcePath)).toBe(false);
writeFileSync(join(sourcePath, 'local.md'), 'Local change');
expect(__testing.isLocalPathDirty(sourcePath)).toBe(true);
});
});
describe('phaseBFenceFacts — dirty-tree refusal scoping (#927)', () => {
let dirtyDir: string;
beforeEach(async () => {
// A second source whose local_path is a git repo with uncommitted changes.
dirtyDir = mkdtempSync(join(tmpdir(), 'mig-v0_32_2-dirty-'));
execFileSync('git', ['-C', dirtyDir, 'init', '-q']);
writeFileSync(join(dirtyDir, 'uncommitted.md'), 'dirty', 'utf-8');
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO sources (id, name, local_path) VALUES ('other', 'other', $1)`,
[dirtyDir],
);
});
afterEach(async () => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(`DELETE FROM sources WHERE id = 'other'`);
rmSync(dirtyDir, { recursive: true, force: true });
});
test('no legacy facts at all → complete, dirty unrelated source ignored', async () => {
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('scanned=0');
});
test('facts scoped to a clean source fence despite dirty unrelated source', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Founded Acme' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('fenced=1');
expect(existsSync(join(brainDir, 'people/alice.md'))).toBe(true);
});
test('still refuses when the TARGETED source is dirty', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F1', source_id: 'other' });
const r = await __testing.phaseBFenceFacts(engine, OPTS);
expect(r.status).toBe('failed');
expect(r.detail).toContain('"other"');
expect(r.detail).toContain('uncommitted changes');
});
});
describe('phaseCVerify', () => {
test('returns complete when fence + DB row counts match', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F1' });
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F2' });
await __testing.phaseBFenceFacts(engine, OPTS);
const r = await __testing.phaseCVerify(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('pages_checked=1');
});
test('returns failed when fence row count drifts from DB', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F1' });
await __testing.phaseBFenceFacts(engine, OPTS);
// Corrupt the fence: append a row manually that's not in the DB.
const path = join(brainDir, 'people/alice.md');
const body = readFileSync(path, 'utf-8');
const corrupted = body.replace(
'<!--- gbrain:facts:end -->',
'| 99 | extra row | fact | 1.0 | world | medium | 2026-01-01 | | manual | |\n<!--- gbrain:facts:end -->',
);
writeFileSync(path, corrupted, 'utf-8');
const r = await __testing.phaseCVerify(engine, OPTS);
expect(r.status).toBe('failed');
expect(r.detail).toContain('drifted');
expect(r.detail).toContain('people/alice');
});
test('ignores conversation-miner facts that have no markdown fence', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F1' });
await __testing.phaseBFenceFacts(engine, OPTS);
const slug = 'cursor-sessions/chat-1';
mkdirSync(join(brainDir, 'cursor-sessions'), { recursive: true });
writeFileSync(
join(brainDir, `${slug}.md`),
'---\ntype: conversation\n---\n\n# chat\n\nhello\n',
'utf-8',
);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
await (engine as any).db.query(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence, row_num, source_markdown_slug)
VALUES ('default', NULL, 'Said hello', 'fact', 'private', 'medium',
now(), 'cli:extract-conversation-facts:seg', 1.0, 1, $1)`,
[slug],
);
const r = await __testing.phaseCVerify(engine, OPTS);
expect(r.status).toBe('complete');
expect(r.detail).toContain('pages_checked=1');
});
// #6685: rows that stay fenced in the index after their page was deleted.
// Every row expired: nothing is left to compare, so the page is skipped (like
// the backfill's skipped_no_page), not drift. A live row is still drift.
async function seedFencedRowOfDeletedPage(slug: string, rowNum: number, expired: boolean): Promise<void> {
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', $1, $2, 'fact', 'private', 'medium', now(), 'manual', 1.0, $3, $1,
CASE WHEN $4::boolean THEN now() ELSE NULL END)`,
[slug, `Claim ${rowNum}`, rowNum, expired],
);
}
test('skips a deleted page whose fenced rows are all expired (#6685)', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'F1' });
await __testing.phaseBFenceFacts(engine, OPTS);
await seedFencedRowOfDeletedPage('projects/gone-example', 1, true);
await seedFencedRowOfDeletedPage('projects/gone-example', 2, true);
expect(await __testing.phaseCVerify(engine, OPTS))
.toMatchObject({ status: 'complete', detail: 'pages_checked=1 skipped_expired_no_page=1' });
});
test('still reports a deleted page that keeps a live fenced row (#6685)', async () => {
await seedFencedRowOfDeletedPage('projects/gone-example', 1, true);
await seedFencedRowOfDeletedPage('projects/gone-example', 2, false);
const r = await __testing.phaseCVerify(engine, OPTS);
expect(r.status).toBe('failed');
expect(r.detail).toBe('1 pages drifted: projects/gone-example (file missing)');
});
// #5814: extract_facts indexes a duplicate ACTIVE fence row (same claim and
// source) once (#1781), so the fence legitimately holds one row more than
// the index. Verify must read that page as in sync, and still catch a fence
// row or an indexed row the other side lacks.
const SLUG = 'people/alice-example';
const fenceRow = (rowNum: number, claim: string): ParsedFact => ({
rowNum, claim, kind: 'fact', confidence: 1, visibility: 'private', notability: 'medium',
validFrom: '2026-01-01', source: 'manual', active: true,
});
const DUPLICATE_FENCE = [fenceRow(1, 'Lives in Paris'), fenceRow(2, 'Lives in Paris'), fenceRow(3, 'Works at Acme example')];
async function writeFencedPage(rows: ParsedFact[]): Promise<void> {
const body = replaceOrInsertFactsFence('# Alice Example\n', renderFactsTable(rows));
mkdirSync(join(brainDir, 'people'), { recursive: true });
writeFileSync(join(brainDir, `${SLUG}.md`), `---\ntype: person\ntitle: Alice Example\n---\n\n${body}`);
await engine.putPage(SLUG, { type: 'person', title: 'Alice Example', compiled_truth: body, frontmatter: {} });
}
async function indexedRowNums(): Promise<number[]> {
const rows = 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]);
return rows.map(r => Number(r.row_num));
}
test('a duplicate active row that extract_facts indexes once is in sync (#5814)', async () => {
await writeFencedPage(DUPLICATE_FENCE);
await runExtractFacts(engine, { slugs: [SLUG] });
expect(await indexedRowNums()).toEqual([1, 3]);
expect(await __testing.phaseCVerify(engine, OPTS)).toMatchObject({ status: 'complete', detail: 'pages_checked=1' });
});
test.each([
['a non-duplicate fence row is not indexed', [1, 2], 'not indexed: 3'],
['an indexed row number is not in the fence', [1, 3, 4], 'not in fence: 4'],
['each side holds a row number the other lacks', [1, 4], 'not indexed: 3; not in fence: 4'],
['more row numbers are missing than the detail lists', [1, 3, 4, 5, 6, 7, 8, 9, 10], 'not in fence: 4, 5, 6, 7, 8, +2 more'],
])('reports drift on a page with a duplicate active row when %s (#5814)', async (_case, indexed, missing) => {
await writeFencedPage(DUPLICATE_FENCE);
for (const rowNum of indexed) {
await engine.executeRaw(
`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, notability,
valid_from, source, confidence, row_num, source_markdown_slug)
VALUES ('default', $1, $2, 'fact', 'private', 'medium', now(), 'manual', 1.0, $3, $1)`,
[SLUG, DUPLICATE_FENCE[rowNum - 1]?.claim ?? `Visited city ${rowNum}`, rowNum],
);
}
const r = await __testing.phaseCVerify(engine, OPTS);
expect(r.status).toBe('failed');
expect(r.detail).toBe(`1 pages drifted: ${SLUG} (fence=3, db=${indexed.length}; ${missing})`);
});
});
describe('orchestrator end-to-end', () => {
test('clean run returns status:complete with 3 phases', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Founded Acme' });
const result = await v0_32_2.orchestrator(OPTS);
expect(result.version).toBe('0.32.2');
expect(result.status).toBe('complete');
expect(result.phases.map(p => p.name)).toEqual(['schema', 'fence_facts', 'verify']);
expect(result.phases.every(p => p.status === 'complete')).toBe(true);
});
test('dry-run returns 3 phases all skipped (no FS or DB changes)', async () => {
await seedLegacyFact({ entity_slug: 'people/alice', fact: 'Should not get fenced', withPage: false });
const result = await v0_32_2.orchestrator(DRY_OPTS);
expect(result.status).toBe('complete');
expect(result.phases.every(p => p.status === 'skipped')).toBe(true);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const rows = await (engine as any).db.query('SELECT row_num FROM facts');
expect(rows.rows[0].row_num).toBeNull();
expect(existsSync(join(brainDir, 'people/alice.md'))).toBe(false);
});
});
afterAll(() => {
try {
if (brainDir) rmSync(brainDir, { recursive: true, force: true });
} catch { /* best-effort */ }
});