Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
41.1 KB
Raw Blame
/**
 * `gbrain repair extractor-facts` (#5731, CEO-A9, ENG-O8, DX-O4, DX-T1), on
 * PGLite and, with a safe DATABASE_URL, Postgres
 * (test/e2e/repair-extractor-facts-postgres.test.ts).
 *
 * Protects: facts the pre-fix canonical projection expired come back only
 * with receipt evidence (a committed write of the page completed in the same
 * transaction, by a consumer older than v0.60.11.0); compacted receipts still
 * count; separate-transaction, post-fix, fence-history and unmanaged rows are
 * ambiguous and need --include-ambiguous with that preview's hash;
 * superseded, withdrawn and duplicated rows are never restored; the apply
 * restores exactly the previewed set, rechecks each fact, and a resumed apply
 * restores no new candidate.
 * Seams: the pre-fix projection's expiry is reproduced by its SQL effect (a
 * real committed page write, then `expired_at` and the receipt's completion
 * set in one transaction); the crash replaces the handler's apply for one run.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { serializePageToMarkdown } from '../src/core/markdown.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { VERSION } from '../src/version.ts';
import { operations } from '../src/core/operations.ts';
import { runRepairCommand } from '../src/commands/repair.ts';
import { extractorFactsRepair, EXTRACTOR_FACTS_INTENT } from '../src/core/repair/extractor-facts.ts';
import { extractorFactsCheck } from '../src/commands/doctor/checks/extractor-facts.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { compactWriteReceipts } from '../src/core/persistence/journal.ts';
import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';
import { runExtractConversationFactsCore } from '../src/commands/extract-conversation-facts.ts';
import { writeSingleFact } from '../src/core/facts/write-single.ts';
import { installFaultHook } from '../src/core/persistence/fault-points.ts';
import { __setMaintenanceWriteWaitForTests } from '../src/core/persistence/maintenance-wait.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { startPersistenceConsumer } from '../src/core/persistence/service.ts';
import { LEGACY_EMBEDDING_CONFIG } from './helpers/legacy-embedding-config.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';

const EXTRACTOR = 'cli:extract-conversation-facts:sess';
const ENTITY = 'people/alice-example';

interface RepairJson { results: Array<{ affected: number; residuals: Record<string, number>; apply_command: string; applied: number; skipped: number;
  warnings?: string[]; listing?: Array<{ item: string; class: string; detail?: string }>; outcomes?: Record<string, number>;
  outcome_items?: Array<{ item: string; outcome: string; reason?: string }> }> }

async function refusal(run: () => Promise<unknown>): Promise<OperationError> {
  try { await run(); } catch (error) { if (error instanceof OperationError) return error; throw error; }
  throw new Error('expected a refusal');
}

/** `home` only outside a managed brain, whose helper already set GBRAIN_HOME (the owner's host identity). */
async function repair(engine: BrainEngine, home: string | null, args: string[]): Promise<RepairJson> {
  const lines: string[] = [];
  const original = console.log;
  console.log = (...parts: unknown[]) => { lines.push(parts.map(String).join(' ')); };
  const run = () => runRepairCommand(engine, ['extractor-facts', ...args, '--json']);
  try { await (home ? withEnv({ GBRAIN_HOME: home }, run) : run()); } finally { console.log = original; }
  return JSON.parse(lines.join('\n')) as RepairJson;
}
const hashOf = (json: RepairJson) => json.results[0].apply_command.match(/--expect ([0-9a-f]+)/)![1];

/** A conversation page with extractor facts at row numbers 1..n, as `extract-conversation-facts` leaves it. */
async function conversation(engine: BrainEngine, slug: string, facts: string[], root?: string, sourceId = 'default'): Promise<number[]> {
  const page = await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: 'Alice: I will send the deck on Friday.\nBob: Thanks.' }, { sourceId });
  if (root) {
    await engine.executeRaw('UPDATE pages SET source_path=$1 WHERE id=$2', [`${slug}.md`, page.id]);
    const snapshot = (await engine.readPageSnapshot(slug, { sourceId }))!;
    mkdirSync(dirname(join(root, `${slug}.md`)), { recursive: true });
    writeFileSync(join(root, `${slug}.md`), serializePageToMarkdown(snapshot.page, snapshot.tags));
  }
  const ids: number[] = [];
  for (const [i, fact] of facts.entries()) {
    const [row] = await engine.executeRaw<{ id: number }>(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, source_session,
      row_num, source_markdown_slug) VALUES ($1, $2, $3, 'commitment', 'private', $4, 'sess', $5, $6) RETURNING id`, [sourceId, ENTITY, fact, EXTRACTOR, i + 1, slug]);
    ids.push(Number(row.id));
  }
  return ids;
}

async function factState(engine: BrainEngine, ids: number[]) {
  return engine.executeRaw<{ id: number; active: boolean; row_num: number | null }>(
    'SELECT id::int AS id, expired_at IS NULL AS active, row_num FROM facts WHERE id=ANY($1::bigint[]) ORDER BY id', [ids]);
}
const activeIds = async (engine: BrainEngine, ids: number[]) => (await factState(engine, ids)).filter(row => row.active).map(row => row.id);

describe('extractor-facts is CLI-only (ENG-O13)', () => {
  test('no operation exposes it over MCP', () => {
    expect(operations.map(op => op.name).filter(name => /repair|extractor/.test(name))).toEqual([]);
  });
});

for (const backend of testBackends()) {
  const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
  const home = mkdtempSync(join(tmpdir(), 'gbrain-repair-extractor-facts-'));
  afterAll(() => rmSync(home, { recursive: true, force: true }));

  /** A real managed write of the page, then the pre-fix projection's effect on its extractor facts. */
  async function prefixExpire(engine: BrainEngine, ctx: OperationContext, slug: string,
    opts: { transaction?: 'same' | 'separate'; consumer?: string | null; ids?: number[] } = {}): Promise<string> {
    const receipt = await submitPageMutation(ctx, { operation: 'add_timeline_entry',
      params: { request_id: randomUUID(), slug, date: '2026-03-01', summary: `note ${randomUUID().slice(0, 8)}`, source: 'operator' } }) as { request_id: string };
    const [row] = await engine.executeRaw<{ id: string }>('SELECT id::text AS id FROM persistence_requests WHERE request_id=$1::uuid', [receipt.request_id]);
    const expire = (tx: BrainEngine) => tx.executeRaw(`UPDATE facts SET expired_at=now(), row_num=NULL WHERE source_id='default'
      AND source_markdown_slug=$1 AND source LIKE 'cli:extract-conversation-facts%' AND expired_at IS NULL ${opts.ids ? 'AND id=ANY($2::bigint[])' : ''}`,
    opts.ids ? [slug, opts.ids] : [slug]);
    const complete = async (tx: BrainEngine) => {
      await declarePersistenceProtocol(tx);
      await tx.executeRaw('UPDATE persistence_requests SET completed_at=now(), consumer_version=$2 WHERE id=$1::uuid', [row.id, opts.consumer === undefined ? null : opts.consumer]);
    };
    if ((opts.transaction ?? 'same') === 'same') {
      await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], async () => { await complete(tx); await expire(tx); }, TEST_WRITE_ATTRIBUTION));
    } else {
      await engine.transaction(tx => complete(tx));
      // PGLite's now() has millisecond resolution: a later transaction is at least one tick later.
      await new Promise(resolve => setTimeout(resolve, 5));
      await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => expire(tx), TEST_WRITE_ATTRIBUTION));
    }
    return row.id;
  }

  describe(`gbrain repair extractor-facts, managed (${backend})`, () => {
    test('the fix holds: a managed write to a conversation page leaves its extractor facts active', async () => {
      let ids: number[] = [];
      await managedBrain(async ({ engine, ctx }) => {
        await submitPageMutation(ctx, { operation: 'add_timeline_entry',
          params: { request_id: randomUUID(), slug: 'conversations/fixed', date: '2026-03-01', summary: 'after the fix', source: 'operator' } });
        expect(await activeIds(engine, ids)).toEqual(ids);
        expect((await repair(engine, null, [])).results[0].residuals).toEqual({ evidenced: 0, ambiguous: 0, excluded: 0 });
      }, { databaseUrl, setup: async ({ engine, root }) => { ids = await conversation(engine, 'conversations/fixed', ['Alice sends the deck'], root); } });
    }, 120_000);

    test('retained, compacted and ambiguous histories: preview, hash-bound apply, recall, then --include-ambiguous', async () => {
      const seeded: Record<string, number[]> = {};
      await managedBrain(async ({ engine, ctx }) => {
        const [retainedA, retainedB, superseded, withdrawn, duplicated] = seeded.retained;
        // An active copy of one claim and a withdrawal of another, then one pre-fix publication expires the page.
        await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], async () => {
          await tx.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug)
            VALUES ('default', $1, 'Alice sends the deck on Friday', 'commitment', 'private', $2, 9, 'conversations/retained')`, [ENTITY, EXTRACTOR]);
          await tx.executeRaw("INSERT INTO fact_withdrawals (source_id, visibility, subject, fact_hash) VALUES ('default', 'private', '*', gbrain_fact_fingerprint('Alice withdrew this claim'))");
        }, TEST_WRITE_ATTRIBUTION));
        await prefixExpire(engine, ctx, 'conversations/retained', { ids: [retainedA, retainedB, superseded, withdrawn, duplicated] });
        await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () =>
          tx.executeRaw('UPDATE facts SET superseded_by=$1 WHERE id=$2', [retainedA, superseded]), TEST_WRITE_ATTRIBUTION));
        const compacted = await prefixExpire(engine, ctx, 'conversations/compacted');
        // Older than the 30-day receipt retention, so compaction drops its intent but keeps its completion.
        await engine.transaction(async tx => {
          await declarePersistenceProtocol(tx);
          await tx.executeRaw("UPDATE persistence_effects SET state='committed' WHERE request_id=$1::uuid", [compacted]);
          await tx.executeRaw("UPDATE persistence_requests SET completed_at=completed_at-interval '40 days' WHERE id=$1::uuid", [compacted]);
        });
        await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () =>
          tx.executeRaw("UPDATE facts SET expired_at=expired_at-interval '40 days' WHERE source_markdown_slug='conversations/compacted'"), TEST_WRITE_ATTRIBUTION));
        expect(await compactWriteReceipts(engine, 30)).toBeGreaterThanOrEqual(1);
        expect((await engine.executeRaw<{ compacted: boolean }>('SELECT compacted FROM persistence_requests WHERE id=$1::uuid', [compacted]))[0].compacted).toBe(true);
        await prefixExpire(engine, ctx, 'conversations/separate', { transaction: 'separate' });
        await prefixExpire(engine, ctx, 'conversations/post-fix', { consumer: VERSION });
        await prefixExpire(engine, ctx, 'conversations/fenced');

        const preview = await repair(engine, null, []);
        const classes = Object.fromEntries(preview.results[0].listing!.map(entry => [Number(entry.item.split('#')[1]), entry.class]));
        expect(classes).toEqual({
          [retainedA]: 'evidenced', [retainedB]: 'evidenced', [superseded]: 'excluded:superseded', [withdrawn]: 'excluded:withdrawn',
          [duplicated]: 'excluded:active_duplicate', [seeded.compacted[0]]: 'evidenced',
          [seeded.separate[0]]: 'ambiguous', [seeded['post-fix'][0]]: 'ambiguous', [seeded.fenced[0]]: 'ambiguous',
        });
        const details = Object.fromEntries(preview.results[0].listing!.map(entry => [Number(entry.item.split('#')[1]), entry.detail]));
        expect(details[seeded.separate[0]]).toContain('no committed write of the page completed at the exact expiry instant');
        expect(details[seeded['post-fix'][0]]).toContain('fixed consumer');
        expect(details[seeded.fenced[0]]).toContain('fence facts');
        expect(details[retainedA]).toContain('unstamped');
        expect(preview.results[0].residuals).toEqual({ evidenced: 3, ambiguous: 3, excluded: 3 });
        expect(preview.results[0].affected).toBe(2);
        const hash = hashOf(preview);
        expect(preview.results[0].apply_command).toBe(`gbrain repair extractor-facts --apply --expect ${hash}`);
        const everything = Object.values(seeded).flat();
        const activeBefore = await activeIds(engine, everything);

        const unbound = await refusal(() => repair(engine, null, ['--apply']));
        expect(unbound.toJSON()).toMatchObject({ error: 'invalid_params', docs: 'docs/guides/repair.md#explicit-only-repair-kinds',
          suggestion: 'Preview first: gbrain repair extractor-facts — then run the apply command it prints: gbrain repair extractor-facts --apply --expect <preview-hash>' });
        const stale = await refusal(() => repair(engine, null, ['--apply', '--expect', 'f'.repeat(64)]));
        expect(stale.toJSON()).toMatchObject({ error: 'preview_changed', docs: 'docs/guides/repair.md#preview-changed',
          message: `The preview changed since ${'f'.repeat(64)}; re-run gbrain repair extractor-facts and use the new hash.` });
        expect(await activeIds(engine, everything)).toEqual(activeBefore);

        const applied = await repair(engine, null, ['--apply', '--expect', hash]);
        expect(applied.results[0]).toMatchObject({ applied: 2, skipped: 0, outcomes: { restored: 2 } });
        const restored = [retainedA, retainedB, seeded.compacted[0]];
        expect(await activeIds(engine, everything)).toEqual([...activeBefore, ...restored].sort((a, b) => a - b));
        // Per-history counts (CEO-A9 completion criteria): restored, ambiguous (left for --include-ambiguous), excluded, unresolved.
        const activeNow = new Set(await activeIds(engine, everything));
        const report = Object.fromEntries(Object.entries(seeded).map(([history, ids]) => {
          const mine = ids.filter(id => classes[id] !== undefined);
          const restoredHere = mine.filter(id => activeNow.has(id)).length;
          return [history, { restored: restoredHere, ambiguous: mine.filter(id => classes[id] === 'ambiguous').length,
            excluded: mine.filter(id => classes[id].startsWith('excluded')).length,
            unresolved: mine.filter(id => classes[id] === 'evidenced' && !activeNow.has(id)).length }];
        }));
        expect(report).toEqual({
          retained: { restored: 2, ambiguous: 0, excluded: 3, unresolved: 0 },
          compacted: { restored: 1, ambiguous: 0, excluded: 0, unresolved: 0 },
          separate: { restored: 0, ambiguous: 1, excluded: 0, unresolved: 0 },
          'post-fix': { restored: 0, ambiguous: 1, excluded: 0, unresolved: 0 },
          fenced: { restored: 0, ambiguous: 1, excluded: 0, unresolved: 0 },
        });
        const rows = await factState(engine, [retainedA, retainedB]);
        expect(rows.map(row => row.row_num)).toEqual([10, 11]);
        const requests = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM persistence_requests WHERE intent->>'kind'=$1 AND state='committed'", [EXTRACTOR_FACTS_INTENT]);
        expect(requests[0].n).toBe(2);
        const recall = operations.find(op => op.name === 'recall')!;
        const recalled = await recall.handler({ ...ctx, remote: false }, { entity: ENTITY }) as { facts: Array<{ fact_id: string }> };
        for (const id of restored) expect(recalled.facts.map(fact => Number(fact.fact_id))).toContain(id);
        expect(await engine.executeRaw("SELECT 1 FROM op_checkpoints WHERE op='repair-approval' AND fingerprint=$1", [`extractor-facts:${hash}`])).toEqual([]);

        const wide = await repair(engine, null, ['--include-ambiguous']);
        expect(wide.results[0].residuals).toEqual({ evidenced: 0, ambiguous: 3, excluded: 3 });
        const wideHash = hashOf(wide);
        expect(wide.results[0].apply_command).toBe(`gbrain repair extractor-facts --include-ambiguous --apply --expect ${wideHash}`);
        expect((await refusal(() => repair(engine, null, ['--apply', '--expect', wideHash]))).code).toBe('preview_changed');
        const wideApplied = await repair(engine, null, ['--include-ambiguous', '--apply', '--expect', wideHash]);
        expect(wideApplied.results[0].outcomes).toEqual({ restored: 3 });
        expect(await activeIds(engine, [superseded, withdrawn])).toEqual([]);
        const after = await repair(engine, null, []);
        expect(after.results[0].residuals).toEqual({ evidenced: 0, ambiguous: 0, excluded: 3 });
      }, { databaseUrl, setup: async ({ engine, root }) => {
        seeded.retained = await conversation(engine, 'conversations/retained', ['Alice sends the deck', 'Alice books the venue',
          'Alice hires a designer', 'Alice withdrew this claim', 'Alice sends the deck on Friday'], root);
        seeded.compacted = await conversation(engine, 'conversations/compacted', ['Alice reviews the budget'], root);
        seeded.separate = await conversation(engine, 'conversations/separate', ['Alice calls the bank'], root);
        seeded['post-fix'] = await conversation(engine, 'conversations/post-fix', ['Alice drafts the memo'], root);
        seeded.fenced = await conversation(engine, 'conversations/fenced', ['Alice signs the lease'], root);
        await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug, expired_at)
          VALUES ('default', 'conversations/fenced', 'A fence row on this page', 'fact', 'private', 'fence', 7, 'conversations/fenced', now())`);
      } });
    }, 180_000);

    test('a fact edited between preview and apply reports changed_since_preview and stays expired; the rest restore', async () => {
      let ids: number[] = [];
      await managedBrain(async ({ engine, ctx }) => {
        await prefixExpire(engine, ctx, 'conversations/edited');
        const preview = await repair(engine, null, []);
        expect(preview.results[0].residuals).toEqual({ evidenced: 2, ambiguous: 0, excluded: 0 });
        await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () =>
          tx.executeRaw("UPDATE facts SET fact='Alice sends the revised deck' WHERE id=$1", [ids[1]]), TEST_WRITE_ATTRIBUTION));
        const applied = await repair(engine, null, ['--apply', '--expect', hashOf(preview)]);
        expect(applied.results[0]).toMatchObject({ applied: 1, outcomes: { partially_restored: 1 } });
        expect(applied.results[0].outcome_items![0].reason).toBe(`1 of 2 restored; changed since the preview: ${ids[1]}`);
        expect(await activeIds(engine, ids)).toEqual([ids[0]]);
      }, { databaseUrl, setup: async ({ engine, root }) => { ids = await conversation(engine, 'conversations/edited', ['Alice sends the deck', 'Alice books the venue'], root); } });
    }, 120_000);

    test('within a duplicate group the evidenced row is restored, not an older ambiguous one (Codex review)', async () => {
      let ids: number[] = [];
      await managedBrain(async ({ engine, ctx }) => {
        await prefixExpire(engine, ctx, 'conversations/dupes', { transaction: 'separate' });
        const [{ id: later }] = await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw<{ id: number }>(
          `INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug)
           VALUES ('default', $1, 'Alice sends the deck', 'commitment', 'private', $2, 5, 'conversations/dupes') RETURNING id::int AS id`, [ENTITY, EXTRACTOR]), TEST_WRITE_ATTRIBUTION));
        await prefixExpire(engine, ctx, 'conversations/dupes', { ids: [Number(later)] });
        const preview = await repair(engine, null, []);
        expect(preview.results[0].listing!.map(entry => [Number(entry.item.split('#')[1]), entry.class])).toEqual([
          [ids[0], 'excluded:duplicate_candidate'], [Number(later), 'evidenced']]);
        const applied = await repair(engine, null, ['--apply', '--expect', hashOf(preview)]);
        expect(applied.results[0].outcomes).toEqual({ restored: 1 });
        expect(await activeIds(engine, [ids[0], Number(later)])).toEqual([Number(later)]);
      }, { databaseUrl, setup: async ({ engine, root }) => { ids = await conversation(engine, 'conversations/dupes', ['Alice sends the deck'], root); } });
    }, 120_000);

    test('crash after a publication, before the cursor: the resumed apply replays its receipt and restores no new candidate (ENG-O8)', async () => {
      const seeded: Record<string, number[]> = {};
      await managedBrain(async ({ engine, ctx }) => {
        await prefixExpire(engine, ctx, 'conversations/a', { ids: [seeded.a[0]] });
        await prefixExpire(engine, ctx, 'conversations/b');
        const preview = await repair(engine, null, []);
        const hash = hashOf(preview);
        expect(preview.results[0].affected).toBe(2);
        const original = extractorFactsRepair.apply;
        extractorFactsRepair.apply = async (...args) => { await original(...args); throw new Error('simulated crash after publication'); };
        try { await expect(repair(engine, null, ['--apply', '--expect', hash])).rejects.toThrow('simulated crash after publication'); }
        finally { extractorFactsRepair.apply = original; }
        expect(await activeIds(engine, [...seeded.a, ...seeded.b])).toEqual(seeded.a);
        // A new defect-evidenced candidate appears on the half-applied page after the preview.
        await prefixExpire(engine, ctx, 'conversations/a', { ids: [seeded.a[1]] });
        const resumed = await repair(engine, null, ['--apply', '--expect', hash]);
        expect(resumed.results[0]).toMatchObject({ affected: 1, applied: 1, residuals: { already_restored_pages: 1 }, outcomes: { restored: 1 } });
        expect(await activeIds(engine, [...seeded.a, ...seeded.b])).toEqual([seeded.a[0], ...seeded.b]);
        const requests = await engine.executeRaw<{ slug: string; n: number }>(`SELECT slug, count(*)::int AS n FROM persistence_requests
          WHERE intent->>'kind'=$1 AND state='committed' GROUP BY slug ORDER BY slug`, [EXTRACTOR_FACTS_INTENT]);
        expect(requests).toEqual([{ slug: 'conversations/a', n: 1 }, { slug: 'conversations/b', n: 1 }]);
        expect((await refusal(() => repair(engine, null, ['--apply', '--expect', hash]))).code).toBe('preview_changed');
        expect((await repair(engine, null, [])).results[0].residuals).toEqual({ evidenced: 1, ambiguous: 0, excluded: 0 });
      }, { databaseUrl, setup: async ({ engine, root }) => {
        seeded.a = await conversation(engine, 'conversations/a', ['Alice sends the deck', 'Alice books the venue'], root);
        seeded.b = await conversation(engine, 'conversations/b', ['Bob reviews the budget'], root);
      } });
    }, 120_000);

    test('#6185: a resumed apply replays a still-pending restore with the CLI write wait, not the 5 s agent wait', async () => {
      const seeded: Record<string, number[]> = {};
      await managedBrain(async ({ engine, ctx }) => {
        await prefixExpire(engine, ctx, 'conversations/slow');
        const hash = hashOf(await repair(engine, null, []));
        let release!: () => void;
        const gate = new Promise<void>(resolve => { release = resolve; });
        installFaultHook(async point => { if (point === 'consumer:prepared') await gate; });
        try {
          const restoreWait = __setMaintenanceWriteWaitForTests(0);
          let first: RepairJson;
          try { first = await repair(engine, null, ['--apply', '--expect', hash]); } finally { restoreWait(); }
          expect((first.results[0] as { stopped?: { reason: string } }).stopped?.reason).toBe('write_pending');
          // A stopped run sets the CLI exit verdict (and process.exitCode) to 1; this file must still exit 0.
          expect(currentExitCode()).toBe(1);
          _resetCliExitVerdictForTests(); process.exitCode = 0;
          expect(await activeIds(engine, seeded.slow)).toEqual([]);
          // The publication is still held when the rerun starts and commits 5.5 s into its replay wait.
          setTimeout(release, 5_500);
          const resumed = await repair(engine, null, ['--apply', '--expect', hash]);
          expect((resumed.results[0] as { stopped?: unknown }).stopped).toBeUndefined();
          expect(resumed.results[0]).toMatchObject({ applied: 1, outcomes: { restored: 1 } });
          expect(await activeIds(engine, seeded.slow)).toEqual(seeded.slow);
        } finally { release(); installFaultHook(undefined); }
      }, { databaseUrl, setup: async ({ engine, root }) => {
        seeded.slow = await conversation(engine, 'conversations/slow', ['Alice sends the deck'], root);
      } });
    }, 120_000);

    test('the preview warns, naming the host, when a consumer older than this release published after the cutoff', async () => {
      await managedBrain(async ({ engine, ctx }) => {
        const request = await prefixExpire(engine, ctx, 'conversations/mixed');
        // The host upgraded after the pre-fix write: writer-version observation starts here.
        await new Promise(resolve => setTimeout(resolve, 5));
        await engine.executeRaw('UPDATE persistence_brain SET writer_version_cutoff=now() WHERE singleton=1');
        const quiet = await repair(engine, null, []);
        expect(quiet.results[0].warnings ?? []).toEqual([]);
        const host = randomUUID();
        await engine.transaction(async tx => {
          await declarePersistenceProtocol(tx);
          // A host still running v0.60.10.0 publishes after the upgrade cutoff.
          await tx.executeRaw(`UPDATE persistence_requests SET consumer_version='0.60.10.0', consumer_host_id=$2::uuid, published_at=now()
            WHERE id=$1::uuid`, [request, host]);
        });
        const warned = await repair(engine, null, []);
        expect(warned.results[0].warnings).toEqual([expect.stringContaining(`host ${host} still published writes with a consumer older than this release (0.60.10.0`)]);
      }, { databaseUrl, setup: async ({ engine, root }) => { await conversation(engine, 'conversations/mixed', ['Alice sends the deck'], root); } });
    }, 120_000);

    test('recovery journey: doctor, preview, apply, doctor, running the printed commands verbatim (DX-O15d)', async () => {
      await managedBrain(async ({ engine, ctx }) => {
        await prefixExpire(engine, ctx, 'conversations/journey');
        const before = await extractorFactsCheck(engine);
        expect(before).toMatchObject({ name: 'extractor_facts_expired', status: 'warn', details: { evidenced: 3, ambiguous: 0 } });
        const printed = before.message.match(/gbrain repair extractor-facts(?= )/)![0];
        const preview = await repair(engine, null, printed.split(' ').slice(3));
        const applied = await repair(engine, null, preview.results[0].apply_command.split(' ').slice(3));
        expect(applied.results[0].outcomes).toEqual({ restored: 1 });
        expect(await extractorFactsCheck(engine)).toMatchObject({ status: 'ok', details: { evidenced: 0, ambiguous: 0 } });
      }, { databaseUrl, setup: async ({ engine, root }) => {
        await conversation(engine, 'conversations/journey', ['Alice sends the deck', 'Alice books the venue', 'Alice hires a designer'], root);
      } });
    }, 120_000);
  });

  describe(`cross-lane journey (ENG-O14): #5731 restore with managed writeSingleFact and a re-extraction (${backend})`, () => {
    const CHAT = `---\ntitle: Synthetic chat\ntype: conversation\n---\n${[
      '**Alice Example** (2024-03-15 9:00 AM): I will send the signed contract by Friday.',
      '**Bob Demo** (2024-03-15 9:01 AM): Great, thanks.',
    ].join('\n')}\n`;
    const CLAIM = 'Alice Example will send the signed contract by Friday.';
    const extractor = async () => [{ fact: CLAIM, kind: 'commitment' as const, entity_slug: ENTITY,
      confidence: 1, notability: 'high' as const, source: 'test', visibility: 'private' as const }];

    test('extract, pre-fix expiry, doctor, preview, apply, recall, remember, re-extract, doctor', async () => {
      await managedBrain(async ({ engine, ctx }) => {
        const slug = 'conversations/synthetic-chat';
        const extracted = await runExtractConversationFactsCore(engine, { sourceId: 'default', overrideDisabled: true, extractor, types: ['conversation'] });
        expect(extracted.facts_inserted).toBe(1);
        const rows = () => engine.executeRaw<{ id: number; fact: string; active: boolean; row_num: number | null }>(
          "SELECT id::int AS id, fact, expired_at IS NULL AS active, row_num FROM facts WHERE source_id='default' AND source_markdown_slug=$1 ORDER BY id", [slug]);
        const original = await rows();
        expect(original.map(row => [row.fact, row.active])).toEqual([[CLAIM, true], ['EXTRACTION_COMPLETE', true]]);
        await prefixExpire(engine, ctx, slug);
        expect((await rows()).every(row => !row.active && row.row_num === null)).toBe(true);

        expect((await extractorFactsCheck(engine)).details).toMatchObject({ evidenced: 2, ambiguous: 0 });
        const preview = await repair(engine, null, []);
        const applied = await repair(engine, null, preview.results[0].apply_command.split(' ').slice(3));
        expect(applied.results[0].outcomes).toEqual({ restored: 1 });
        const restored = await rows();
        expect(restored.map(row => [row.id, row.active])).toEqual(original.map(row => [row.id, true]));
        const recalled = await operations.find(op => op.name === 'recall')!.handler(ctx, { entity: ENTITY }) as { facts: Array<{ fact_id: string }> };
        expect(recalled.facts.map(fact => Number(fact.fact_id))).toContain(original[0].id);

        // writeSingleFact dedups against the restored fact for the same entity and keeps an absent entity's claim apart.
        const same = await writeSingleFact(engine, 'default', { fact: CLAIM, provenance: 'fixture', entity: ENTITY, kind: 'commitment' });
        expect(same).toMatchObject({ status: 'duplicate', id: original[0].id, entity_slug: ENTITY });
        const other = await writeSingleFact(engine, 'default', { fact: CLAIM, provenance: 'fixture', entity: 'Carol Absent', kind: 'commitment' });
        expect(other).toMatchObject({ status: 'inserted', entity_slug: 'carol-absent' });

        // A forced re-extraction replaces the restored batch, active, with nothing expired left behind on the page.
        const rerun = await runExtractConversationFactsCore(engine, { sourceId: 'default', overrideDisabled: true, extractor, types: ['conversation'], force: true });
        expect([rerun.facts_inserted, rerun.orphan_facts_cleaned]).toEqual([1, 2]);
        expect((await rows()).map(row => [row.fact, row.active])).toEqual([[CLAIM, true], ['EXTRACTION_COMPLETE', true]]);
        expect((await extractorFactsCheck(engine)).status).toBe('ok');
        expect((await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM facts WHERE entity_slug='carol-absent' AND expired_at IS NULL"))[0].n).toBe(1);
      }, { databaseUrl, setup: async ({ engine, root }) => {
        await engine.setConfig('conversation_parser.llm_fallback_enabled', 'false');
        const person = await engine.putPage(ENTITY, { type: 'person', title: 'Alice Example', compiled_truth: '# Alice Example' }, { sourceId: 'default' });
        await engine.executeRaw('UPDATE pages SET source_path=$1 WHERE id=$2', [`${ENTITY}.md`, person.id]);
        const personSnapshot = (await engine.readPageSnapshot(ENTITY, { sourceId: 'default' }))!;
        mkdirSync(join(root, 'people'), { recursive: true });
        writeFileSync(join(root, `${ENTITY}.md`), serializePageToMarkdown(personSnapshot.page, personSnapshot.tags));
        const page = await engine.putPage('conversations/synthetic-chat', { type: 'conversation', title: 'Synthetic chat',
          compiled_truth: CHAT.split('---\n')[2].trim() }, { sourceId: 'default' });
        await engine.executeRaw('UPDATE pages SET source_path=$1 WHERE id=$2', ['conversations/synthetic-chat.md', page.id]);
        const snapshot = (await engine.readPageSnapshot('conversations/synthetic-chat', { sourceId: 'default' }))!;
        mkdirSync(join(root, 'conversations'), { recursive: true });
        writeFileSync(join(root, 'conversations/synthetic-chat.md'), serializePageToMarkdown(snapshot.page, snapshot.tags));
      } });
    }, 180_000);

    // Nightly full-corpus lane (run 37273083933): with an embedding key in the environment, writeSingleFact embedded
    // the claim and admitted it under a stub config while the running consumer was keyless, so preparation refused it
    // with embedding_configuration. A deterministic fake embedder stands in for the key here.
    test('a keyless consumer admits writeSingleFact without vectors even when the gateway can embed', async () => {
      const embedded: string[] = [];
      try {
        configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: { OPENAI_API_KEY: 'fixture-key' } });
        __setEmbedTransportForTests((async ({ values }: { values: string[] }) => {
          embedded.push(...values);
          return { embeddings: values.map(() => [1, ...Array(LEGACY_EMBEDDING_CONFIG.embedding_dimensions - 1).fill(0)]) };
        }) as never);
        await managedBrain(async ({ engine, ctx }) => {
          expect(ctx.config.embedding_disabled).toBe(true);
          startPersistenceConsumer(engine, ctx.config);
          const written = await writeSingleFact(engine, 'default', { fact: CLAIM, provenance: 'fixture', entity: ENTITY, kind: 'commitment' });
          expect(written).toMatchObject({ status: 'inserted', entity_slug: ENTITY });
          // The keyless consumer's config is the effective config: the claim never reaches the embedder.
          expect(embedded).toEqual([]);
          const [row] = await engine.executeRaw<{ has_vector: boolean }>('SELECT embedding IS NOT NULL AS has_vector FROM facts WHERE id=$1', [written.id]);
          expect(row.has_vector).toBe(false);
        }, { databaseUrl, setup: async ({ engine, root }) => {
          const person = await engine.putPage(ENTITY, { type: 'person', title: 'Alice Example', compiled_truth: '# Alice Example' }, { sourceId: 'default' });
          await engine.executeRaw('UPDATE pages SET source_path=$1 WHERE id=$2', [`${ENTITY}.md`, person.id]);
          const snapshot = (await engine.readPageSnapshot(ENTITY, { sourceId: 'default' }))!;
          mkdirSync(join(root, 'people'), { recursive: true });
          writeFileSync(join(root, `${ENTITY}.md`), serializePageToMarkdown(snapshot.page, snapshot.tags));
        } });
      } finally {
        __setEmbedTransportForTests(null);
        resetGateway(); // R5: restore the preload baseline for later tests and files in this shard
      }
    }, 180_000);
  });

  describe(`gbrain repair extractor-facts, unmanaged (${backend})`, () => {
    let engine: BrainEngine;
    let close: (() => Promise<void>) | undefined;
    beforeAll(async () => {
      if (backend === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(databaseUrl!));
      else { const pglite = new PGLiteEngine(); await pglite.connect({}); await pglite.initSchema(); engine = pglite; }
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    }, 120_000);
    afterAll(async () => { if (close) await close(); else await engine.disconnect(); });

    test('every candidate is ambiguous; only --include-ambiguous with its own hash restores them', async () => {
      const sourceId = `ef-u-${randomUUID().slice(0, 8)}`;
      await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
      const ids = await conversation(engine, 'conversations/unmanaged', ['Alice sends the deck', 'Alice books the venue'], undefined, sourceId);
      const superseded = (await conversation(engine, 'conversations/unmanaged-2', ['Alice hires a designer'], undefined, sourceId))[0];
      // The same claim about another entity on the same page is a distinct fact, not a duplicate (Codex review).
      const [{ id: bobs }] = await engine.executeRaw<{ id: number }>(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug)
        VALUES ($1, 'people/bob-example', 'Alice sends the deck', 'commitment', 'private', $2, 3, 'conversations/unmanaged') RETURNING id::int AS id`, [sourceId, EXTRACTOR]);
      ids.push(Number(bobs));
      await engine.executeRaw("UPDATE facts SET expired_at=now(), row_num=NULL WHERE source_id=$1", [sourceId]);
      await engine.executeRaw('UPDATE facts SET superseded_by=$1 WHERE id=$2', [ids[0], superseded]);
      const preview = await repair(engine, home, ['--source', sourceId]);
      expect(preview.results[0].residuals).toEqual({ evidenced: 0, ambiguous: 3, excluded: 1 });
      expect(preview.results[0].affected).toBe(0);
      expect(preview.results[0].listing!.map(entry => entry.detail)).toContain('unmanaged brain: no write receipt can prove the expiry');
      expect((await refusal(() => repair(engine, home, ['--source', sourceId, '--apply', '--expect', hashOf(preview)]))).code).toBe('preview_changed');
      const wide = await repair(engine, home, ['--source', sourceId, '--include-ambiguous']);
      expect(wide.results[0].affected).toBe(1);
      // The hash is bound to the preview's source scope: applying it brain-wide refuses (Codex review).
      expect((await refusal(() => repair(engine, home, ['--include-ambiguous', '--apply', '--expect', hashOf(wide)]))).code).toBe('preview_changed');
      const applied = await repair(engine, home, ['--source', sourceId, '--include-ambiguous', '--apply', '--expect', hashOf(wide)]);
      expect(applied.results[0].outcomes).toEqual({ restored: 1 });
      expect(await factState(engine, [...ids, superseded])).toEqual([
        { id: ids[0], active: true, row_num: 1 }, { id: ids[1], active: true, row_num: 2 }, { id: superseded, active: false, row_num: null },
        { id: ids[2], active: true, row_num: 3 }]);
      expect((await repair(engine, home, ['--source', sourceId])).results[0].residuals).toEqual({ evidenced: 0, ambiguous: 0, excluded: 1 });
    }, 60_000);

    test('a --limit run always advances: a partially restored page is not retried by the next run (Codex review)', async () => {
      const sourceId = `ef-l-${randomUUID().slice(0, 8)}`;
      await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
      const first = await conversation(engine, 'conversations/limit-a', ['Alice sends the deck', 'Alice books the venue'], undefined, sourceId);
      const second = await conversation(engine, 'conversations/limit-b', ['Bob reviews the budget'], undefined, sourceId);
      await engine.executeRaw('UPDATE facts SET expired_at=now(), row_num=NULL WHERE source_id=$1', [sourceId]);
      const wide = await repair(engine, home, ['--source', sourceId, '--include-ambiguous']);
      await engine.executeRaw("UPDATE facts SET fact='Alice sends the revised deck' WHERE id=$1", [first[1]]);
      const apply = ['--source', sourceId, '--include-ambiguous', '--apply', '--expect', hashOf(wide), '--limit', '1'];
      expect((await repair(engine, home, apply)).results[0].outcomes).toEqual({ partially_restored: 1 });
      const next = await repair(engine, home, apply);
      expect(next.results[0]).toMatchObject({ affected: 1, outcomes: { restored: 1 } });
      expect(await activeIds(engine, [...first, ...second])).toEqual([first[0], second[0]]);
      expect((await refusal(() => repair(engine, home, apply))).code).toBe('preview_changed');
    }, 60_000);

    test('a page deleted and recreated at the same slug since the preview restores nothing (Codex review)', async () => {
      const sourceId = `ef-r-${randomUUID().slice(0, 8)}`;
      await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
      const ids = await conversation(engine, 'conversations/recreated', ['Alice sends the deck'], undefined, sourceId);
      await engine.executeRaw('UPDATE facts SET expired_at=now(), row_num=NULL WHERE source_id=$1', [sourceId]);
      const wide = await repair(engine, home, ['--source', sourceId, '--include-ambiguous']);
      await engine.deletePage('conversations/recreated', { sourceId });
      await engine.putPage('conversations/recreated', { type: 'note', title: 'Another page', compiled_truth: 'Unrelated.' }, { sourceId });
      const applied = await repair(engine, home, ['--source', sourceId, '--include-ambiguous', '--apply', '--expect', hashOf(wide)]);
      expect(applied.results[0].outcomes).toEqual({ changed_since_preview: 1 });
      expect(await activeIds(engine, ids)).toEqual([]);
    }, 60_000);
  });
}