Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #5280 remainder: the facts-family maintenance writers publish through the
* persistence coordinator on a managed brain instead of refusing with
* writer_coordinator_required.
*
* 1. Protects: extract_facts reconcile (and its soft-deleted-page expiry),
* phantom redirect, direct fence writes, Google loops extraction and bulk
* conversation fact extraction (core, CLI, cycle phase) each land their
* intended rows/files on a managed brain.
* 2. Fails when: any of these writers takes the legacy path (the managed
* writer guard trigger refuses it) or keeps its early refusal.
* 3. Existing coverage only pinned the refusals
* (managed-unsupported-preflight.serial.test.ts).
* 4. No production seam: model calls use the gateway's test transports and
* the conversation core's existing extractor injection.
*
* Journaled writers assert a committed persistence request; DB-only derived
* rows (fence reconcile, conversation facts) assert the committed rows
* while the managed guard is armed (an uncoordinated write refuses).
*/
import { afterAll, afterEach, beforeAll, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { serializePageToMarkdown } from '../src/core/markdown.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { configureGateway, resetGateway, __setChatTransportForTests, __setEmbedTransportForTests, type ChatResult } from '../src/core/ai/gateway.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import { runExtractConversationFactsCore, runExtractConversationFacts, type ExtractConversationFactsResult } from '../src/commands/extract-conversation-facts.ts';
import { runPhaseConversationFactsBackfill } from '../src/core/cycle/conversation-facts-backfill.ts';
import { writeFactsToFence } from '../src/core/facts/fence-write.ts';
import { writeSingleFact } from '../src/core/facts/write-single.ts';
import { runLoopsExtract } from '../src/core/google/loops-extract.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { withEnv } from './helpers/with-env.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { testBackends } from './helpers/test-backends.ts';
const backends = testBackends();
const engines: BrainEngine[] = [];
const dataDir = mkdtempSync(join(tmpdir(), 'gbrain-managed-facts-writers-db-'));
let closePostgres: (() => Promise<void>) | undefined;
let chatReply = '{"facts":[]}';
const usage = { input_tokens: 10, output_tokens: 10, cache_read_tokens: 0, cache_creation_tokens: 0 };
beforeAll(async () => {
configureGateway({ chat_model: 'anthropic:claude-sonnet-4-6', embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: 1536,
env: { ANTHROPIC_API_KEY: 'sk-ant-test', OPENAI_API_KEY: 'sk-test' } });
__setChatTransportForTests(async (): Promise<ChatResult> => ({ text: chatReply, blocks: [], stopReason: 'end', usage,
model: 'anthropic:claude-sonnet-4-6', providerId: 'anthropic' }));
__setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(() => Array(1536).fill(0.01)) })) as never);
if (backends.includes('pglite')) {
const engine = new PGLiteEngine();
await engine.connect({ database_path: dataDir }); await engine.initSchema(); engines.push(engine);
}
if (backends.includes('postgres')) {
const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
engines.push(pg.engine); closePostgres = pg.close;
}
}, 120_000);
afterEach(() => { chatReply = '{"facts":[]}'; });
afterAll(async () => {
__setChatTransportForTests(null); __setEmbedTransportForTests(null);
for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
await closePostgres?.(); resetGateway(); rmSync(dataDir, { recursive: true, force: true });
});
interface Fixture { engine: BrainEngine; sourceId: string; root: string; put(slug: string, content: string): Promise<void>; }
/** Seeds through ordinary coordinated page writes while unmanaged, then enables managed mode. */
async function managed(seed: (f: Fixture) => Promise<void>, run: (f: Fixture) => Promise<void>) {
for (const engine of engines) {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-managed-facts-writers-'));
const root = join(dir, 'brain'); mkdirSync(root);
const sourceId = `facts-${randomUUID().slice(0, 8)}`;
try {
await withEnv({ GBRAIN_HOME: join(dir, 'home'), GBRAIN_AUDIT_DIR: join(dir, 'audit') }, async () => {
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, root]);
await engine.setConfig('sync.write_through', 'true');
await engine.setConfig('facts.extraction_enabled', 'true');
await engine.setConfig('conversation_parser.llm_fallback_enabled', 'false');
await claimWorktree(engine, sourceId, root);
const ctx = { engine, sourceId, remote: false as const, config: { engine: engine.kind, embedding_disabled: true },
dryRun: false, logger: { info() {}, warn() {}, error() {} } };
const fixture: Fixture = { engine, sourceId, root, put: async (slug, content) => {
const prior = await engine.readPageSnapshot(slug, { sourceId });
await submitPageMutation(ctx, { operation: 'put_page', params: { slug, content, request_id: randomUUID(),
...(prior ? { expected_revision: prior.revision } : {}) } });
} };
await seed(fixture);
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
await expect(engine.executeRaw(`INSERT INTO facts(source_id,fact,kind,source,visibility) VALUES($1,'uncoordinated','fact','test','private')`,
[sourceId])).rejects.toThrow(/writer_coordinator_required/);
await run(fixture);
});
} finally {
await disposePersistenceConsumer(engine);
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
rmSync(dir, { recursive: true, force: true });
}
}
}
const FENCE = (rows: string) => `## Facts
<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
${rows}
<!--- gbrain:facts:end -->
`;
const PERSON = (title: string, body = '') => `---\ntitle: ${title}\ntype: person\n---\n# ${title}\n\n${body}`;
const CONVERSATION = `---\ntitle: Synthetic chat\ntype: conversation\n---\n${[
'**Alice Example** (2024-03-15 9:00 AM): I just signed the offer letter for Acme Corp.',
'**Bob Demo** (2024-03-15 9:01 AM): Congrats! What is the title?',
'**Alice Example** (2024-03-15 9:02 AM): Staff engineer on the platform team.',
].join('\n')}\n`;
async function facts(engine: BrainEngine, sourceId: string, slug: string) {
return (await engine.executeRaw<{ id: number; fact: string; row_num: number | null; expired_at: unknown; source: string }>(
'SELECT id,fact,row_num,expired_at,source FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 ORDER BY row_num NULLS LAST,id', [sourceId, slug])).map(f => ({ ...f, id: Number(f.id), row_num: f.row_num == null ? null : Number(f.row_num) }));
}
async function committed(engine: BrainEngine, sourceId: string, slug: string) {
return engine.executeRaw<{ state: string; operation: string; kind: string | null }>(
"SELECT state,operation,intent->>'kind' AS kind FROM persistence_requests WHERE source_id=$1 AND slug=$2 AND state='committed' ORDER BY sequence",
[sourceId, slug]);
}
test('managed extract_facts reconciles a drifted fence and expires a deleted page\'s facts inside the coordinator capability', async () => {
await managed(async ({ engine, sourceId, put }) => {
await put('people/alice-example', PERSON('Alice Example', FENCE([
'| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |',
'| 2 | Lives in Paris | fact | 1.0 | world | medium | 2018-01-01 | | chat | |'].join('\n'))));
await put('people/bob-demo', PERSON('Bob Demo', FENCE('| 1 | Plays chess | fact | 1.0 | world | low | 2019-01-01 | | chat | |')));
expect(await facts(engine, sourceId, 'people/alice-example')).toHaveLength(2);
// Drift: the index lost the fence rows; the other page is deleted with active rows.
await engine.executeRaw('DELETE FROM facts WHERE source_id=$1 AND source_markdown_slug=$2', [sourceId, 'people/alice-example']);
await engine.softDeletePage('people/bob-demo', { sourceId });
}, async ({ engine, sourceId }) => {
const result = await runExtractFacts(engine, { sourceId, slugs: ['people/alice-example'] });
expect(result.factsInserted).toBe(2);
expect(result.factsExpiredForDeletedPages).toBe(1);
expect((await facts(engine, sourceId, 'people/alice-example')).map(f => [f.row_num, f.fact, f.expired_at])).toEqual([
[1, 'Founded Acme', null], [2, 'Lives in Paris', null]]);
expect((await facts(engine, sourceId, 'people/bob-demo'))[0].expired_at).not.toBeNull();
expect((await runExtractFacts(engine, { sourceId, slugs: ['people/alice-example'] })).factsInserted).toBe(0);
});
}, 120_000);
test('managed phantom redirect merges the phantom fence into the canonical page and deletes the phantom through the coordinator', async () => {
await managed(async ({ engine, sourceId, root, put }) => {
await put('people/alice-example', PERSON('Alice Example'));
// A legacy stub phantom: written without put_page provenance stamps, which the residue gate treats as content.
await engine.putPage('alice', { type: 'person', title: 'alice', compiled_truth: `# alice\n\n${FENCE('| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |')}`.trim(),
timeline: '', frontmatter: {} }, { sourceId });
const phantom = (await engine.readPageSnapshot('alice', { sourceId }))!;
writeFileSync(join(root, 'alice.md'), serializePageToMarkdown(phantom.page, phantom.tags));
await runExtractFacts(engine, { sourceId, slugs: ['alice'] });
}, async ({ engine, sourceId, root }) => {
const [before] = await facts(engine, sourceId, 'alice');
expect(before?.fact).toBe('Founded Acme');
const result = await runExtractFacts(engine, { sourceId, brainDir: root });
expect(result.phantomsRedirected).toBe(1);
expect(result.warnings.filter(w => w.startsWith('phantom_redirect'))).toEqual([]);
const moved = await facts(engine, sourceId, 'people/alice-example');
expect(moved.map(f => [f.id, f.fact, f.expired_at])).toEqual([[before.id, 'Founded Acme', null]]);
expect(readFileSync(join(root, 'people/alice-example.md'), 'utf8')).toContain('Founded Acme');
expect(existsSync(join(root, 'alice.md'))).toBe(false);
expect((await engine.readPageSnapshot('alice', { sourceId, includeDeleted: true }))?.page.deleted_at).not.toBeNull();
expect(await engine.resolveSlugWithAlias('alice', sourceId)).toBe('people/alice-example');
expect((await committed(engine, sourceId, 'people/alice-example')).map(r => r.kind)).toContain('managed_maintenance_phantom_merge');
expect((await committed(engine, sourceId, 'alice')).map(r => r.kind)).toContain('managed_maintenance_phantom_delete');
});
}, 120_000);
test('managed phantom redirect rechecks eligibility against the snapshot it merges', async () => {
await managed(async ({ engine, sourceId, root, put }) => {
await put('people/alice-example', PERSON('Alice Example'));
await engine.putPage('alice', { type: 'person', title: 'alice', compiled_truth: `# alice\n\n${FENCE('| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |')}`.trim(),
timeline: '', frontmatter: {} }, { sourceId });
const phantom = (await engine.readPageSnapshot('alice', { sourceId }))!;
writeFileSync(join(root, 'alice.md'), serializePageToMarkdown(phantom.page, phantom.tags));
await runExtractFacts(engine, { sourceId, slugs: ['alice'] });
}, async ({ engine, sourceId, root, put }) => {
// After the pass judged the phantom residue-free, an edit adds timeline
// text and metadata but leaves compiled_truth unchanged.
const read = engine.readPageSnapshot;
let edited = false;
engine.readPageSnapshot = (async function (this: BrainEngine, slug: string, opts?: Parameters<BrainEngine['readPageSnapshot']>[1]) {
if (this === engine && slug === 'alice' && !edited && new Error().stack?.includes('redirectManagedPhantom')) {
edited = true;
const current = (await read.call(this, slug, opts))!;
await put('alice', serializePageToMarkdown({ ...current.page, frontmatter: { owner_note: 'keep me' },
timeline: '- **2026-01-01** | Met at the offsite' }, current.tags));
}
return read.call(this, slug, opts);
}) as BrainEngine['readPageSnapshot'];
let result: Awaited<ReturnType<typeof runExtractFacts>>;
try { result = await runExtractFacts(engine, { sourceId, brainDir: root }); }
finally { delete (engine as { readPageSnapshot?: unknown }).readPageSnapshot; }
expect(edited).toBe(true);
const alive = await engine.readPageSnapshot('alice', { sourceId, includeDeleted: true });
expect(alive?.page.deleted_at ?? null).toBeNull();
expect(alive?.page.timeline).toContain('Met at the offsite');
expect([result.phantomsRedirected, result.phantomsSkippedDrift]).toEqual([0, 1]);
expect((await committed(engine, sourceId, 'people/alice-example')).map(r => r.kind)).not.toContain('managed_maintenance_phantom_merge');
});
}, 120_000);
test('managed direct fence writes publish the fence row and index through the coordinator', async () => {
await managed(async ({ put }) => { await put('people/alice-example', PERSON('Alice Example')); }, async ({ engine, sourceId, root }) => {
const result = await writeFactsToFence(engine, { sourceId, localPath: root, slug: 'people/alice-example', resolutionSource: 'exact_page' }, [
{ fact: 'Prefers weekly status reports.', kind: 'preference', source: 'fixture', visibility: 'private', notability: 'medium', embedding: null, sessionId: null }]);
expect(result.inserted).toBe(1);
const rows = await facts(engine, sourceId, 'people/alice-example');
expect(rows.map(f => [f.id, f.fact, f.row_num])).toEqual([[result.ids[0], 'Prefers weekly status reports.', 1]]);
expect(readFileSync(join(root, 'people/alice-example.md'), 'utf8')).toContain('Prefers weekly status reports.');
expect((await committed(engine, sourceId, 'people/alice-example')).map(r => r.kind)).toContain('managed_facts_entity');
});
}, 120_000);
test('managed fence writes keep a fact\'s explicit context in the fence and the index', async () => {
await managed(async ({ put }) => { await put('people/alice-example', PERSON('Alice Example')); }, async ({ engine, sourceId, root }) => {
const write = (context: string) => writeFactsToFence(engine, { sourceId, localPath: root, slug: 'people/alice-example', resolutionSource: 'exact_page' }, [
{ fact: 'Prefers weekly status reports.', kind: 'preference', source: 'fixture', context, visibility: 'private', notability: 'medium', embedding: null, sessionId: null }]);
const first = await write('meetings/review');
const [row] = await engine.executeRaw<{ context: string | null }>('SELECT context FROM facts WHERE id=$1', [first.ids[0]]);
expect(row.context).toBe('meetings/review');
expect(readFileSync(join(root, 'people/alice-example.md'), 'utf8')).toContain('meetings/review');
// Context is part of the write's identity: a different context is a new write, not a replay.
expect((await committed(engine, sourceId, '__managed_facts_complete__')).length).toBe(1);
await write('meetings/other');
expect((await committed(engine, sourceId, '__managed_facts_complete__')).length).toBe(2);
});
}, 120_000);
test('managed writeSingleFact supersedes a near-duplicate of the same kind like the unmanaged path', async () => {
await managed(async ({ engine, put }) => {
await engine.setConfig('embedding_model', 'openai:text-embedding-3-large');
await engine.setConfig('embedding_dimensions', '1536');
// Calibrate the test embedder: an uncalibrated model never supersedes by cosine (supersession-threshold.ts).
await engine.setConfig('facts.supersession_thresholds', JSON.stringify({ 'openai:text-embedding-3-large@1536': 0.95 }));
await put('people/alice-example', PERSON('Alice Example'));
}, async ({ engine, sourceId, root }) => {
const remember = (fact: string) => writeSingleFact(engine, sourceId, { fact, provenance: 'fixture', entity: 'people/alice-example', visibility: 'world' });
const first = await remember('Alice Example works at Acme.');
expect(first.status).toBe('inserted');
const second = await remember('Alice Example works at Beta.');
expect(second.status).toBe('superseded');
expect(second.id).not.toBe(first.id);
const [old] = await engine.executeRaw<{ expired_at: unknown; superseded_by: number | null }>('SELECT expired_at,superseded_by FROM facts WHERE id=$1', [first.id]);
expect(old.expired_at).not.toBeNull();
expect(Number(old.superseded_by)).toBe(second.id);
expect((await facts(engine, sourceId, 'people/alice-example')).filter(f => f.expired_at === null).map(f => f.fact)).toEqual(['Alice Example works at Beta.']);
expect(readFileSync(join(root, 'people/alice-example.md'), 'utf8')).toMatch(/~~Alice Example works at Acme\.~~/);
});
}, 120_000);
test('managed Google loops extraction lands its commitment fact through the coordinator', async () => {
await managed(async ({ engine, put }) => {
await engine.setConfig('loops.extraction_enabled', 'true');
await put('people/alice-example', PERSON('Alice Example'));
await put('emails/example', `---\ntitle: Synthetic exchange\ntype: email\nthread_id: example\nfrom: [email protected]\n---\nI will send the deck by Friday.\n`);
}, async ({ engine, sourceId, root }) => {
chatReply = JSON.stringify({ commitments: [{ text: 'Send the deck by Friday', direction: 'owed_by_me',
counterparty_name: 'people/alice-example', counterparty_email: '', due_iso: '2026-10-02', quote: 'I will send the deck by Friday.' }], decisions_pending: [] });
const result = await runLoopsExtract(engine, { slug: 'emails/example', sourceId });
expect(result).toMatchObject({ status: 'extracted', commitments: 1 });
const [loop] = await engine.executeRaw<{ fact_id: number | null }>('SELECT fact_id FROM open_loops WHERE source_id=$1', [sourceId]);
const rows = await facts(engine, sourceId, 'people/alice-example');
expect(rows.map(f => [f.id, f.fact])).toEqual([[Number(loop.fact_id), 'Send the deck by Friday']]);
expect(readFileSync(join(root, 'people/alice-example.md'), 'utf8')).toContain('Send the deck by Friday');
expect((await committed(engine, sourceId, 'people/alice-example')).map(r => r.kind)).toContain('managed_facts_entity');
});
}, 120_000);
const extractor = async () => [{ fact: 'Alice Example joined Acme Corp as a staff engineer.', kind: 'event' as const, entity_slug: null,
confidence: 1, notability: 'high' as const, source: 'test', visibility: 'private' as const }];
test('managed bulk conversation extraction writes its facts and terminal audit row inside the coordinator capability', async () => {
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId }) => {
const result = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
expect(result.facts_inserted).toBe(1);
expect(result.pages_failed).toBe(0);
expect((await facts(engine, sourceId, 'conversations/synthetic-chat')).map(f => [f.fact, f.source])).toEqual([
['Alice Example joined Acme Corp as a staff engineer.', 'cli:extract-conversation-facts'],
['EXTRACTION_COMPLETE', 'cli:extract-conversation-facts:terminal:v2']]);
// A forced replay deletes the prior rows first, also inside the capability.
const replay = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'], force: true });
expect(replay.orphan_facts_cleaned).toBe(2);
expect(await facts(engine, sourceId, 'conversations/synthetic-chat')).toHaveLength(2);
});
}, 120_000);
test('managed conversation extraction honors facts.default_visibility=world on extracted rows; both audit rows stay private', async () => {
const single = `---\ntitle: Single message\ntype: conversation\n---\n**Alice Example** (2024-03-15 9:00 AM): Only one message here.\n`;
await managed(async ({ put }) => {
await put('conversations/synthetic-chat', CONVERSATION);
await put('conversations/single-message', single);
}, async ({ engine, sourceId }) => {
await engine.setConfig('facts.default_visibility', 'world');
try {
const result = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
expect(result).toMatchObject({ facts_inserted: 1, pages_marked_non_extractable: 1, pages_failed: 0 });
const rows = await engine.executeRaw<{ slug: string; source: string; visibility: string }>(
'SELECT source_markdown_slug AS slug, source, visibility FROM facts WHERE source_id=$1 ORDER BY source_markdown_slug, row_num', [sourceId]);
expect(rows).toEqual([
{ slug: 'conversations/single-message', source: 'cli:extract-conversation-facts:non-extractable:v2', visibility: 'private' },
{ slug: 'conversations/synthetic-chat', source: 'cli:extract-conversation-facts', visibility: 'world' },
{ slug: 'conversations/synthetic-chat', source: 'cli:extract-conversation-facts:terminal:v2', visibility: 'private' },
]);
} finally {
await engine.unsetConfig('facts.default_visibility');
}
});
}, 120_000);
test('managed conversation extraction preserves the prior batch when a replacement extraction fails', async () => {
const slug = 'conversations/synthetic-chat';
await managed(async ({ engine, sourceId, put }) => {
await put(slug, CONVERSATION);
await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
await put(slug, CONVERSATION.replace('Staff engineer', 'Principal engineer'));
}, async ({ engine, sourceId }) => {
const failed = async () => { throw new Error('synthetic provider failure'); };
const result = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor: failed, types: ['conversation'] });
expect(result.pages_failed).toBe(1);
expect((await facts(engine, sourceId, slug)).map(row => row.fact)).toEqual([
'Alice Example joined Acme Corp as a staff engineer.', 'EXTRACTION_COMPLETE']);
});
}, 120_000);
test('managed conversation extraction keeps the prior batch when the page is edited while the model runs, then replaces it', async () => {
const slug = 'conversations/synthetic-chat';
await managed(async ({ engine, sourceId, put }) => {
await put(slug, CONVERSATION);
await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
await put(slug, CONVERSATION.replace('Staff engineer', 'Senior engineer'));
}, async ({ engine, sourceId, put }) => {
const editing = async () => {
await put(slug, CONVERSATION.replace('Staff engineer', 'Principal engineer'));
return [{ ...(await extractor())[0]!, fact: 'Alice Example joined Acme Corp as a principal engineer.' }];
};
const raced = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor: editing, types: ['conversation'] });
expect(raced.pages_failed).toBe(1);
expect((await facts(engine, sourceId, slug)).map(row => row.fact)).toEqual([
'Alice Example joined Acme Corp as a staff engineer.', 'EXTRACTION_COMPLETE']);
const principal = async () => [{ ...(await extractor())[0]!, fact: 'Alice Example joined Acme Corp as a principal engineer.' }];
const replay = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor: principal, types: ['conversation'] });
expect(replay).toMatchObject({ pages_failed: 0, facts_inserted: 1, orphan_facts_cleaned: 2 });
expect((await facts(engine, sourceId, slug)).map(row => [row.fact, row.row_num])).toEqual([
['Alice Example joined Acme Corp as a principal engineer.', 0], ['EXTRACTION_COMPLETE', 1]]);
});
}, 120_000);
test('republishing a managed conversation page keeps its extracted facts active and the page complete', async () => {
// Conversation rows are numbered on the page coordinate but carry no fence;
// like the legacy fence reconcile (#1928), the canonical projection must not
// expire them as rows that left a fence.
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId, put }) => {
await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
await put('conversations/synthetic-chat', CONVERSATION.replace('Staff engineer', 'A staff engineer'));
expect((await facts(engine, sourceId, 'conversations/synthetic-chat')).map(f => [f.fact, f.row_num, f.expired_at])).toEqual([
['Alice Example joined Acme Corp as a staff engineer.', 0, null], ['EXTRACTION_COMPLETE', 1, null]]);
// The edit changed the snapshot, so the next run replays the page delete-first.
const rerun = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
expect([rerun.facts_inserted, rerun.orphan_facts_cleaned]).toEqual([1, 2]);
expect((await facts(engine, sourceId, 'conversations/synthetic-chat')).filter(f => f.expired_at === null).map(f => f.fact)).toEqual([
'Alice Example joined Acme Corp as a staff engineer.', 'EXTRACTION_COMPLETE']);
});
}, 120_000);
test('managed phantom redirect defers the phantom delete when the phantom is edited after the merge', async () => {
await managed(async ({ engine, sourceId, root, put }) => {
await put('people/alice-example', PERSON('Alice Example'));
await engine.putPage('alice', { type: 'person', title: 'alice', compiled_truth: `# alice\n\n${FENCE('| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |')}`.trim(),
timeline: '', frontmatter: {} }, { sourceId });
const phantom = (await engine.readPageSnapshot('alice', { sourceId }))!;
writeFileSync(join(root, 'alice.md'), serializePageToMarkdown(phantom.page, phantom.tags));
await runExtractFacts(engine, { sourceId, slugs: ['alice'] });
}, async ({ engine, sourceId, root, put }) => {
// A coordinated edit to the phantom lands right after the merge commits,
// before the redirect rereads the phantom to delete it.
const read = engine.readPageSnapshot;
let edited = false;
engine.readPageSnapshot = (async function (this: BrainEngine, slug: string, opts?: Parameters<BrainEngine['readPageSnapshot']>[1]) {
// Transactions inherit this method; only the redirect's own read on the engine triggers the edit.
if (this === engine && slug === 'alice' && !edited && new Error().stack?.includes('redirectManagedPhantom') && (await engine.executeRaw(
"SELECT 1 FROM persistence_requests WHERE source_id=$1 AND intent->>'kind'='managed_maintenance_phantom_merge' AND state='committed'", [sourceId])).length) {
edited = true;
await put('alice', `---\ntitle: alice\ntype: person\n---\n# alice\n\n${FENCE([
'| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |',
'| 2 | Moved to Lisbon | fact | 1.0 | world | high | 2020-01-01 | | chat | |'].join('\n'))}`);
}
return read.call(this, slug, opts);
}) as BrainEngine['readPageSnapshot'];
let result: Awaited<ReturnType<typeof runExtractFacts>>;
try { result = await runExtractFacts(engine, { sourceId, brainDir: root }); }
finally { delete (engine as { readPageSnapshot?: unknown }).readPageSnapshot; }
expect(edited).toBe(true);
const alive = await engine.readPageSnapshot('alice', { sourceId, includeDeleted: true });
expect(alive?.page.deleted_at ?? null).toBeNull();
expect([result.phantomsRedirected, result.phantomsSkippedDrift]).toEqual([0, 1]);
expect(alive?.page.compiled_truth).toContain('Moved to Lisbon');
expect(readFileSync(join(root, 'alice.md'), 'utf8')).toContain('Moved to Lisbon');
expect(await committed(engine, sourceId, 'alice').then(rows => rows.filter(r => r.kind === 'managed_maintenance_phantom_delete'))).toEqual([]);
});
}, 120_000);
const localCtx = (engine: BrainEngine, sourceId: string) => ({ engine, sourceId, remote: false as const,
config: { engine: engine.kind, embedding_disabled: true }, dryRun: false, logger: { info() {}, warn() {}, error() {} } });
test('managed conversation extraction publishes nothing for a page purged while the model runs', async () => {
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId }) => {
const purging = async () => {
const page = (await engine.readPageSnapshot('conversations/synthetic-chat', { sourceId }))!;
await submitPageMutation(localCtx(engine, sourceId), { operation: 'delete_page', params: { slug: 'conversations/synthetic-chat',
purge: true, expected_revision: page.revision, request_id: randomUUID() } });
return extractor();
};
const result = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor: purging, types: ['conversation'] });
expect(await engine.readPageSnapshot('conversations/synthetic-chat', { sourceId, includeDeleted: true })).toBeNull();
expect(await facts(engine, sourceId, 'conversations/synthetic-chat')).toEqual([]);
expect(result.pages_failed).toBe(1);
});
}, 120_000);
test('managed conversation extraction publishes nothing into a source archived while the model runs', async () => {
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId }) => {
const archiving = async () => {
await engine.transaction(async tx => {
await tx.executeRaw("SELECT set_config('gbrain.topology_change','on',true)");
await tx.executeRaw('UPDATE sources SET archived=true WHERE id=$1', [sourceId]);
});
return extractor();
};
try {
const result = await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor: archiving, types: ['conversation'] });
expect(await facts(engine, sourceId, 'conversations/synthetic-chat')).toEqual([]);
expect(result.pages_failed).toBe(1);
} finally {
await engine.transaction(async tx => {
await tx.executeRaw("SELECT set_config('gbrain.topology_change','on',true)");
await tx.executeRaw('UPDATE sources SET archived=false WHERE id=$1', [sourceId]);
});
}
});
}, 120_000);
test('a Facts fence published on an extracted conversation takes its row numbers from colliding conversation rows', async () => {
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId, put }) => {
await runExtractConversationFactsCore(engine, { sourceId, overrideDisabled: true, extractor, types: ['conversation'] });
await put('conversations/synthetic-chat', `${CONVERSATION}\n${FENCE('| 1 | Acme hired a platform team | fact | 1.0 | world | high | 2024-03-15 | | chat | |')}`);
const rows = await facts(engine, sourceId, 'conversations/synthetic-chat');
expect(rows.filter(f => f.expired_at === null).map(f => [f.fact, f.row_num, f.source])).toEqual([
['Alice Example joined Acme Corp as a staff engineer.', 0, 'cli:extract-conversation-facts'],
['Acme hired a platform team', 1, 'chat']]);
expect(rows.find(f => f.fact === 'EXTRACTION_COMPLETE')).toMatchObject({ row_num: null, source: 'cli:extract-conversation-facts:terminal:v2' });
});
}, 120_000);
test('managed phantom delete moves an edge added to the phantom after its merge', async () => {
await managed(async ({ engine, sourceId, root, put }) => {
await put('people/alice-example', PERSON('Alice Example'));
await put('meetings/offsite', '---\ntitle: Offsite\ntype: meeting\n---\nA planning meeting.');
await engine.putPage('alice', { type: 'person', title: 'alice', compiled_truth: `# alice\n\n${FENCE('| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 | | chat | |')}`.trim(),
timeline: '', frontmatter: {} }, { sourceId });
const phantom = (await engine.readPageSnapshot('alice', { sourceId }))!;
writeFileSync(join(root, 'alice.md'), serializePageToMarkdown(phantom.page, phantom.tags));
await runExtractFacts(engine, { sourceId, slugs: ['alice'] });
}, async ({ engine, sourceId, root }) => {
const read = engine.readPageSnapshot;
let linked = false;
engine.readPageSnapshot = (async function (this: BrainEngine, slug: string, opts?: Parameters<BrainEngine['readPageSnapshot']>[1]) {
if (this === engine && slug === 'alice' && !linked && new Error().stack?.includes('redirectManagedPhantom') && (await engine.executeRaw(
"SELECT 1 FROM persistence_requests WHERE source_id=$1 AND intent->>'kind'='managed_maintenance_phantom_merge' AND state='committed'", [sourceId])).length) {
linked = true;
await engine.addLink('meetings/offsite', 'alice', 'met', 'mentions', 'manual', undefined, undefined, { fromSourceId: sourceId, toSourceId: sourceId });
}
return read.call(this, slug, opts);
}) as BrainEngine['readPageSnapshot'];
let result: Awaited<ReturnType<typeof runExtractFacts>>;
try { result = await runExtractFacts(engine, { sourceId, brainDir: root }); }
finally { delete (engine as { readPageSnapshot?: unknown }).readPageSnapshot; }
expect(linked).toBe(true);
expect(result.phantomsRedirected).toBe(1);
const edges = await engine.executeRaw<{ slug: string }>(`SELECT t.slug FROM links l JOIN pages f ON f.id=l.from_page_id JOIN pages t ON t.id=l.to_page_id
WHERE f.source_id=$1 AND f.slug='meetings/offsite'`, [sourceId]);
expect(edges.map(e => e.slug)).toEqual(['people/alice-example']);
});
}, 120_000);
test('managed deleted-page expiry waits for a concurrent restore of that page (Postgres)', async () => {
await managed(async ({ put }) => {
await put('people/bob-demo', PERSON('Bob Demo', FENCE('| 1 | Plays chess | fact | 1.0 | world | low | 2019-01-01 | | chat | |')));
}, async ({ engine, sourceId }) => {
if (engine.kind !== 'postgres') return;
await engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], () => tx.softDeletePage('people/bob-demo', { sourceId }), TEST_WRITE_ATTRIBUTION));
let release!: () => void;
const gate = new Promise<void>(resolve => { release = resolve; });
let locked!: () => void;
const holding = new Promise<void>(resolve => { locked = resolve; });
const restore = engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], async () => {
await tx.lockPageKeys([{ sourceId, slug: 'people/bob-demo' }]);
await tx.executeRaw('UPDATE pages SET deleted_at=NULL WHERE source_id=$1 AND slug=$2', [sourceId, 'people/bob-demo']);
locked();
await gate;
}, TEST_WRITE_ATTRIBUTION));
await holding;
const run = runExtractFacts(engine, { sourceId, slugs: [] });
await new Promise(resolve => setTimeout(resolve, 500));
release();
await restore;
expect((await run).factsExpiredForDeletedPages).toBe(0);
expect((await facts(engine, sourceId, 'people/bob-demo'))[0].expired_at).toBeNull();
});
}, 120_000);
test('managed writeSingleFact reports the entity it persisted for an unresolved reference', async () => {
await managed(async () => {}, async ({ engine, sourceId }) => {
const written = await writeSingleFact(engine, sourceId, { fact: 'Carol Unknown owns a sailboat.', provenance: 'fixture', entity: 'Carol Unknown' });
const [row] = await engine.executeRaw<{ entity_slug: string | null }>('SELECT entity_slug FROM facts WHERE id=$1', [written.id]);
expect(written.entity_slug).toBe(row.entity_slug);
});
}, 120_000);
test('#7068: an interrupted managed extraction hands back the counts of the pages it published', async () => {
const later = `---\ntitle: Synthetic follow-up\ntype: conversation\n---\n${[
'**Bob Demo** (2024-03-16 9:00 AM): Did the move to the platform team go through?',
'**Alice Example** (2024-03-16 9:01 AM): Yes, I start on Monday.',
].join('\n')}\n`;
await managed(async ({ put }) => {
await put('conversations/first-chat', CONVERSATION);
await put('conversations/second-chat', later);
}, async ({ engine, sourceId }) => {
const caller = new AbortController();
const replies = ['Alice Example signed an offer with Acme Corp.', 'Alice Example starts on the platform team on Monday.'];
let call = 0;
const factFor = (text: string) => [{ fact: text, kind: 'event' as const, entity_slug: null, confidence: 1,
notability: 'high' as const, source: 'test', visibility: 'private' as const }];
const interruptSecond = async () => {
if (++call === 2) { caller.abort(new Error('per-source walltime cap hit')); throw caller.signal.reason; }
return factFor(replies[0]!);
};
const handed: ExtractConversationFactsResult[] = [];
const thrown = await runExtractConversationFactsCore(engine, { sourceId, types: ['conversation'], sleepMs: 0,
extractor: interruptSecond, onInterrupted: partial => { handed.push(partial); } }, caller.signal).then(() => null, (err: Error) => err);
expect(thrown?.message).toBe('per-source walltime cap hit');
expect(handed).toHaveLength(1);
expect(handed[0]).toMatchObject({ pages_processed: 1, facts_inserted: 1, pages_failed: 0 });
expect((await facts(engine, sourceId, 'conversations/first-chat')).map(f => f.fact)).toEqual([replies[0], 'EXTRACTION_COMPLETE']);
expect(await facts(engine, sourceId, 'conversations/second-chat')).toEqual([]);
const resumed = await runExtractConversationFactsCore(engine, { sourceId, types: ['conversation'], sleepMs: 0,
extractor: async () => factFor(replies[1]!) });
expect(resumed).toMatchObject({ pages_skipped_completed: 1, pages_processed: 1, facts_inserted: 1 });
expect((await facts(engine, sourceId, 'conversations/second-chat')).map(f => f.fact)).toEqual([replies[1], 'EXTRACTION_COMPLETE']);
});
}, 120_000);
test('managed extract-conversation-facts CLI extracts instead of refusing', async () => {
await managed(async ({ put }) => { await put('conversations/synthetic-chat', CONVERSATION); }, async ({ engine, sourceId }) => {
chatReply = JSON.stringify({ facts: [{ fact: 'Alice Example joined Acme Corp.', kind: 'event', entity: null, confidence: 1, notability: 'high' }] });
await runExtractConversationFacts(engine, ['--source-id', sourceId, '--slug', 'conversations/synthetic-chat', '--override-disabled']);
expect((await facts(engine, sourceId, 'conversations/synthetic-chat')).map(f => f.fact)).toEqual(['Alice Example joined Acme Corp.', 'EXTRACTION_COMPLETE']);
});
}, 120_000);
test('managed conversation_facts_backfill phase extracts instead of refusing', async () => {
await managed(async ({ engine, put }) => {
await engine.setConfig('cycle.conversation_facts_backfill.enabled', 'true');
await put('conversations/synthetic-chat', CONVERSATION);
}, async ({ engine, sourceId }) => {
chatReply = JSON.stringify({ facts: [{ fact: 'Alice Example joined Acme Corp.', kind: 'event', entity: null, confidence: 1, notability: 'high' }] });
const phase = await runPhaseConversationFactsBackfill(engine);
expect(phase.status).toBe('ok');
expect((phase.details.per_source as Record<string, { facts_inserted: number }>)[sourceId].facts_inserted).toBe(1);
expect((await facts(engine, sourceId, 'conversations/synthetic-chat')).map(f => f.fact)).toEqual(['Alice Example joined Acme Corp.', 'EXTRACTION_COMPLETE']);
});
}, 120_000);