Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
86.8 KB
Raw Blame
/**
 * v0.32.2 — extract_facts cycle phase tests.
 *
 * Covers the reconciliation contract: parse fence → deleteFactsForPage
 * → insertFacts. Plus the empty-fence guard (Codex R2-#7) that refuses
 * to reconcile while unfenced rows the phase could not fence remain.
 *
 * Uses a real PGLite engine. Pages seeded via engine.putPage so
 * compiled_truth + frontmatter are realistic.
 */

import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import { parseFactsFence } from '../src/core/facts-fence.ts';
import { emptyFenceBlock } from '../src/core/generations/fence.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { acquirePageLock } from '../src/core/page-lock.ts';
import { _resetWriteThroughCacheForTest } from '../src/core/write-through.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  await (engine as any).db.query('DELETE FROM facts');
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  await (engine as any).db.query('DELETE FROM pages');
  // #2763: the legacy-row guard only counts rows the v0_32_2 Phase B
  // backfill could actually fence, which requires the source to carry a
  // local_path. The guard tests here simulate a migrated v0.31 brain,
  // whose default source inherits local_path from sync.repo_path
  // (migration v14) — mirror that. A fresh PGLite seed leaves it NULL.
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  await (engine as any).db.query(
    `UPDATE sources SET local_path = '/tmp/gbrain-extract-facts-phase-test' WHERE id = 'default'`,
  );
});

async function putPage(slug: string, body: string): Promise<void> {
  await engine.putPage(slug, {
    title: slug,
    type: 'person',
    compiled_truth: body,
    frontmatter: {},
    timeline: '',
  });
}

// #3625: writes compiled_truth and timeline as SEPARATE columns, mirroring
// what splitBody() produces when a `## Facts` fence sits below the
// `<!-- timeline -->` sentinel — the fence text lands in `timeline`, not
// `compiled_truth`, exactly as MCP put_page would store it.
async function putPageWithTimeline(slug: string, compiledTruth: string, timeline: string): Promise<void> {
  await engine.putPage(slug, {
    title: slug,
    type: 'person',
    compiled_truth: compiledTruth,
    frontmatter: {},
    timeline,
  });
}

const FACT_FENCE = (rows: string): string => `# Page

Body.

## Facts

<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
${rows}
<!--- gbrain:facts:end -->
`;


/**
 * GBRA-161 PR 2 (D4): a page whose facts fence is absent keeps its rows (the fact generation holds `fence_absent` and the
 * owner decides); writing the empty fence is the deletion, and it retires every row (`fenceParsedEmpty`).
 */
async function expectAbsentHoldsThenEmptyFenceRetires(slug: string, write: (body: string) => Promise<void>, body: string): Promise<void> {
  await write(body);
  const held = await runExtractFacts(engine, { slugs: [slug] });
  expect(held.factsDeleted).toBe(0);
  expect(held.warnings.some(w => w.includes('FACTS_FENCE_BELOW_SENTINEL'))).toBe(false);
  expect(held.warnings.filter(w => w.includes('FACTS_FENCE_HELD: fence_absent'))).toHaveLength(1);
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const kept = await (engine as any).db.query(`SELECT COUNT(*) AS n FROM facts WHERE source_markdown_slug = $1 AND expired_at IS NULL AND row_num IS NOT NULL`, [slug]);
  expect(Number(kept.rows[0].n)).toBe(1);
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const holds = await (engine as any).db.query(`SELECT held_reason FROM derived_generations WHERE kind = 'fact_fence' AND owner_key = $1 AND state = 'held'`, ['page:' + slug]);
  expect(holds.rows.map((row: { held_reason: string }) => row.held_reason)).toEqual(['fence_absent']);
  await write(body + '\n' + emptyFenceBlock('facts'));
  const retired = await runExtractFacts(engine, { slugs: [slug] });
  expect(retired.factsDeleted).toBe(1);
  expect(retired.warnings).toEqual([]);
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const rows = await (engine as any).db.query(`SELECT COUNT(*) AS n FROM facts WHERE source_markdown_slug = $1 AND (expired_at IS NULL OR row_num IS NOT NULL)`, [slug]);
  expect(Number(rows.rows[0].n)).toBe(0);
}

describe('runExtractFacts — happy path', () => {
  test('reconciles fence facts into DB for a single page', async () => {
    const body = FACT_FENCE(
      `| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 |  | linkedin |  |
| 2 | Prefers async | preference | 0.85 | private | medium | 2026-04-29 |  | OH |  |`,
    );
    await putPage('people/alice', body);

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.pagesScanned).toBe(1);
    expect(r.pagesWithFacts).toBe(1);
    expect(r.factsInserted).toBe(2);
    expect(r.guardTriggered).toBe(false);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const dbRows = await (engine as any).db.query(
      `SELECT fact, row_num, source_markdown_slug FROM facts ORDER BY row_num`,
    );
    expect(dbRows.rows).toEqual([
      expect.objectContaining({ fact: 'Founded Acme', row_num: 1, source_markdown_slug: 'people/alice' }),
      expect.objectContaining({ fact: 'Prefers async', row_num: 2, source_markdown_slug: 'people/alice' }),
    ]);
  });

  test('idempotent: running twice produces the same final DB state', async () => {
    const body = FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | B | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    );
    await putPage('people/alice', body);

    await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const after1 = await (engine as any).db.query(
      `SELECT fact, row_num FROM facts ORDER BY row_num`,
    );

    const r2 = await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const after2 = await (engine as any).db.query(
      `SELECT fact, row_num FROM facts ORDER BY row_num`,
    );

    expect(r2.guardTriggered).toBe(false);
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);
    expect(after2.rows.map((r: { fact: string }) => r.fact))
      .toEqual(after1.rows.map((r: { fact: string }) => r.fact));
    expect(after2.rows).toHaveLength(2);
  });

  test('dedupes duplicate fence rows by claim and source without rewriting the fence', async () => {
    const body = FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    );
    await putPage('people/alice', body);

    const r1 = await runExtractFacts(engine, { slugs: ['people/alice'] });
    const r2 = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r1.factsInserted).toBe(1);
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);

    // The cycle dedups the derived DB index; it does not destructively
    // rewrite user-authored markdown fence rows.
    const page = await engine.getPage('people/alice', { sourceId: 'default' });
    expect(parseFactsFence(page?.compiled_truth ?? '').facts).toHaveLength(2);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, source FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(rows.rows).toHaveLength(1);
    expect(rows.rows[0]).toMatchObject({ fact: 'A', source: 's' });
  });

  test('same claim with a different source is not treated as duplicate', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Same claim | fact | 1.0 | world | medium | 2026-01-01 |  | source-a |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    await putPage('people/alice', FACT_FENCE(
      `| 1 | Same claim | fact | 1.0 | world | medium | 2026-01-01 |  | source-a |  |
| 2 | Same claim | fact | 1.0 | world | medium | 2026-01-01 |  | source-b |  |`,
    ));
    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.factsInserted).toBe(1);
    expect(r.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, source FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );
    expect(rows.rows).toEqual([
      expect.objectContaining({ fact: 'Same claim', source: 'source-a' }),
      expect.objectContaining({ fact: 'Same claim', source: 'source-b' }),
    ]);
  });

  test('new fact added to the fence is inserted once without re-appending existing facts', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    await putPage('people/alice', FACT_FENCE(
      `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | New | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.factsInserted).toBe(1);
    expect(r.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );
    expect(rows.rows.map((row: { fact: string }) => row.fact)).toEqual(['Existing', 'New']);
  });

  test('refuses destructive reconcile when canonical Markdown is newer than the pages cache', async () => {
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-stale-cache-'));
    try {
      // Point the default source at a real canonical tree for this case.
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );

      const cachedBody = FACT_FENCE(
        `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
      );
      const canonicalBody = FACT_FENCE(
        `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | Newly remembered | event | 1.0 | world | medium | 2026-09-02 |  | remember:test |  |`,
      );
      await putPage('people/alice', cachedBody);
      await runExtractFacts(engine, { slugs: ['people/alice'] });

      // Reproduce the real ordering: remember writes canonical Markdown and
      // stamps the new facts row before page sync refreshes compiled_truth.
      mkdirSync(join(root, 'people'), { recursive: true });
      writeFileSync(join(root, 'people', 'alice.md'), canonicalBody, 'utf-8');
      await engine.insertFacts(
        [{
          fact: 'Newly remembered',
          kind: 'event',
          source: 'remember:test',
          row_num: 2,
          source_markdown_slug: 'people/alice',
        }],
        { source_id: 'default' },
      );

      const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
      expect(r.factsDeleted).toBe(0);
      expect(r.factsInserted).toBe(0);
      expect(r.warnings).toContainEqual(expect.stringContaining('FACTS_PAGE_CACHE_STALE'));

      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
      );
      expect(rows.rows.map((row: { fact: string }) => row.fact))
        .toEqual(['Existing', 'Newly remembered']);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });

  test('page lock closes the empty-fence delete race with a concurrent canonical writer', async () => {
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-empty-race-'));
    const lockRoot = join(root, '.locks');
    const slug = 'people/empty-race';
    try {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );
      await putPage(slug, '');
      await engine.insertFacts(
        [{ fact: 'Previously indexed', kind: 'fact', source: 'old', row_num: 1, source_markdown_slug: slug }],
        { source_id: 'default' },
      );

      const held = await acquirePageLock(slug, { lockRoot });
      expect(held).not.toBeNull();
      let settled = false;
      const reconcile = runExtractFacts(engine, { slugs: [slug], pageLockRoot: lockRoot })
        .finally(() => { settled = true; });
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(settled).toBe(false);

      const canonicalBody = FACT_FENCE(
        `| 1 | Previously indexed | fact | 1.0 | world | medium | 2026-01-01 |  | old |  |\n` +
        `| 2 | Concurrent remember | event | 1.0 | world | medium | 2026-09-02 |  | remember:test |  |`,
      );
      mkdirSync(join(root, 'people'), { recursive: true });
      writeFileSync(join(root, 'people', 'empty-race.md'), canonicalBody, 'utf-8');
      await engine.insertFacts(
        [{ fact: 'Concurrent remember', kind: 'event', source: 'remember:test', row_num: 2, source_markdown_slug: slug }],
        { source_id: 'default' },
      );
      await held!.release();

      const r = await reconcile;
      expect(r.factsDeleted).toBe(0);
      expect(r.warnings).toContainEqual(expect.stringContaining('FACTS_PAGE_CACHE_STALE'));
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = $1 ORDER BY row_num`,
        [slug],
      );
      expect(rows.rows.map((row: { fact: string }) => row.fact))
        .toEqual(['Previously indexed', 'Concurrent remember']);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  }, 15_000);

  test('page lock closes the transactional drift-replace race with a concurrent canonical writer', async () => {
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-drift-race-'));
    const lockRoot = join(root, '.locks');
    const slug = 'people/drift-race';
    try {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );
      const cachedBody = FACT_FENCE(
        `| 1 | Canonical cached | fact | 1.0 | world | medium | 2026-01-01 |  | cached |  |`,
      );
      await putPage(slug, cachedBody);
      await engine.insertFacts(
        [{ fact: 'Stale indexed row', kind: 'fact', source: 'stale', row_num: 1, source_markdown_slug: slug }],
        { source_id: 'default' },
      );

      const held = await acquirePageLock(slug, { lockRoot });
      expect(held).not.toBeNull();
      let settled = false;
      const reconcile = runExtractFacts(engine, { slugs: [slug], pageLockRoot: lockRoot })
        .finally(() => { settled = true; });
      await new Promise(resolve => setTimeout(resolve, 50));
      expect(settled).toBe(false);

      const canonicalBody = FACT_FENCE(
        `| 1 | Canonical cached | fact | 1.0 | world | medium | 2026-01-01 |  | cached |  |\n` +
        `| 2 | Concurrent remember | event | 1.0 | world | medium | 2026-09-02 |  | remember:test |  |`,
      );
      mkdirSync(join(root, 'people'), { recursive: true });
      writeFileSync(join(root, 'people', 'drift-race.md'), canonicalBody, 'utf-8');
      await engine.insertFacts(
        [{ fact: 'Concurrent remember', kind: 'event', source: 'remember:test', row_num: 2, source_markdown_slug: slug }],
        { source_id: 'default' },
      );
      await held!.release();

      const r = await reconcile;
      expect(r.factsDeleted).toBe(0);
      expect(r.factsInserted).toBe(0);
      expect(r.warnings).toContainEqual(expect.stringContaining('FACTS_PAGE_CACHE_STALE'));
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = $1 ORDER BY row_num, id`,
        [slug],
      );
      expect(rows.rows.map((row: { fact: string }) => row.fact))
        .toEqual(['Stale indexed row', 'Concurrent remember']);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  }, 15_000);

  test('fresh cache: canonical Markdown equal to the pages cache lets destructive reconcile proceed', async () => {
    // Twin of the stale-refusal test above with ONE difference: the on-disk
    // file carries the same body as the pages row. Pins the comparison itself,
    // so a normally synced page is never mistaken for a stale one.
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-fresh-cache-'));
    try {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );
      const body = FACT_FENCE(
        `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
      );
      await putPage('people/alice-fresh', body);
      mkdirSync(join(root, 'people'), { recursive: true });
      writeFileSync(join(root, 'people', 'alice-fresh.md'), body, 'utf-8');
      // DB drift the fence does not carry: the reconcile must wipe it.
      await engine.insertFacts(
        [{ fact: 'Stale indexed row', kind: 'fact', source: 'stale', row_num: 7, source_markdown_slug: 'people/alice-fresh' }],
        { source_id: 'default' },
      );

      const r = await runExtractFacts(engine, { slugs: ['people/alice-fresh'] });
      expect(r.warnings.some(w => w.includes('FACTS_PAGE_CACHE_STALE'))).toBe(false);
      expect(r.factsDeleted).toBeGreaterThan(0);
      expect(r.factsInserted).toBe(1);
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice-fresh' AND expired_at IS NULL ORDER BY row_num`,
      );
      expect(rows.rows.map((row: { fact: string }) => row.fact)).toEqual(['Existing']);
      // B-5: the stale row is expired and detached from the fence, never deleted.
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const stale = await (engine as any).db.query(
        `SELECT row_num, expired_at IS NOT NULL AS expired FROM facts WHERE source_markdown_slug = 'people/alice-fresh' AND fact = 'Stale indexed row'`,
      );
      expect(stale.rows).toEqual([{ row_num: null, expired: true }]);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });

  test('sync.write_through=off: a stale mirror file never blocks destructive reconcile', async () => {
    // With write-through off the fence writers already treat the file as
    // non-canonical (fence-write.ts legacy fallback), so the staleness check
    // must not hold the DB hostage to a mirror nobody maintains.
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-wt-off-'));
    try {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );
      await engine.setConfig('sync.write_through', 'off');
      _resetWriteThroughCacheForTest();
      await putPage('people/alice-wt-off', FACT_FENCE(
        `| 1 | Existing | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
      ));
      mkdirSync(join(root, 'people'), { recursive: true });
      writeFileSync(join(root, 'people', 'alice-wt-off.md'), '# Stale mirror\n\nNothing like the DB body.\n', 'utf-8');
      await engine.insertFacts(
        [{ fact: 'Stale indexed row', kind: 'fact', source: 'stale', row_num: 7, source_markdown_slug: 'people/alice-wt-off' }],
        { source_id: 'default' },
      );

      const r = await runExtractFacts(engine, { slugs: ['people/alice-wt-off'] });
      expect(r.warnings.some(w => w.includes('FACTS_PAGE_CACHE_STALE'))).toBe(false);
      expect(r.factsDeleted).toBeGreaterThan(0);
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice-wt-off' AND expired_at IS NULL ORDER BY row_num`,
      );
      expect(rows.rows.map((row: { fact: string }) => row.fact)).toEqual(['Existing']);
      // B-5: the stale row is expired and detached from the fence, never deleted.
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const stale = await (engine as any).db.query(
        `SELECT row_num, expired_at IS NOT NULL AS expired FROM facts WHERE source_markdown_slug = 'people/alice-wt-off' AND fact = 'Stale indexed row'`,
      );
      expect(stale.rows).toEqual([{ row_num: null, expired: true }]);
    } finally {
      await engine.unsetConfig('sync.write_through');
      _resetWriteThroughCacheForTest();
      rmSync(root, { recursive: true, force: true });
    }
  });

  test('a page lock held past the deadline degrades to FACTS_PAGE_LOCK_TIMEOUT and the run continues', async () => {
    // One wedged page must cost a warning, not the rest of the phase run.
    const root = mkdtempSync(join(tmpdir(), 'gbrain-facts-lock-timeout-'));
    const lockRoot = join(root, '.locks');
    try {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query(
        `UPDATE sources SET local_path = $1 WHERE id = 'default'`,
        [root],
      );
      // Wedged page: empty fence + a fence-owned row → the destructive delete path.
      await putPage('people/wedged', '');
      await engine.insertFacts(
        [{ fact: 'Survives the wedge', kind: 'fact', source: 'old', row_num: 1, source_markdown_slug: 'people/wedged' }],
        { source_id: 'default' },
      );
      // Healthy sibling later in the same run: must still reconcile.
      await putPage('people/healthy', FACT_FENCE(
        `| 1 | Healthy fact | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
      ));

      const held = await acquirePageLock('people/wedged', { lockRoot });
      expect(held).not.toBeNull();
      try {
        const r = await runExtractFacts(engine, { slugs: ['people/wedged', 'people/healthy'], pageLockRoot: lockRoot });
        expect(r.warnings).toContainEqual(expect.stringContaining('people/wedged: FACTS_PAGE_LOCK_TIMEOUT'));
        expect(r.factsDeleted).toBe(0);
        expect(r.factsInserted).toBe(1);
      } finally {
        await held!.release();
      }
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      const rows = await (engine as any).db.query(
        `SELECT fact FROM facts WHERE source_markdown_slug = 'people/wedged'`,
      );
      expect(rows.rows).toHaveLength(1);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  }, 20_000);

  test('cli:-origin conversation facts (#1928) neither break idempotency nor get wiped', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Fence fact | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    // A conversation fact on the same page coordinate — NOT fence-owned.
    await engine.insertFacts(
      [{ fact: 'conversation fact', kind: 'fact', source: 'cli:extract-conversation-facts', row_num: 99, source_markdown_slug: 'people/alice' }],
      { source_id: 'default' },
    );

    const r1 = await runExtractFacts(engine, { slugs: ['people/alice'] });
    const r2 = await runExtractFacts(engine, { slugs: ['people/alice'] });

    // The cli: row must not count as "stale" — a wipe/reinsert every cycle
    // would defeat idempotency (and churn factsDeleted/factsInserted).
    expect(r1.factsInserted).toBe(1);
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );
    expect(rows.rows.map((row: { fact: string }) => row.fact))
      .toEqual(['Fence fact', 'conversation fact']);
  });

  test('removed-from-fence row is expired and detached, the kept row keeps its id (B-5)', async () => {
    // Seed: 2 facts.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | B | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const before = await (engine as any).db.query(
      `SELECT id, fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );

    // Edit the page to remove row 2.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.factsDeleted).toBe(1);
    expect(r.factsInserted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT id, fact, row_num, expired_at IS NOT NULL AS expired FROM facts
        WHERE source_markdown_slug = 'people/alice' ORDER BY id`,
    );
    expect(rows.rows).toEqual([
      { id: before.rows[0].id, fact: 'A', row_num: 1, expired: false },
      { id: before.rows[1].id, fact: 'B', row_num: null, expired: true },
    ]);
    const active = await engine.listFactsByEntity('default', 'people/alice', { activeOnly: true });
    expect(active.map(f => f.fact)).toEqual(['A']);
  });

  // #4870 — visibility / notability are fence cells (parsed + validated as
  // mandatory enums, transported by the wipe+reinsert), but the reconcile
  // never read them back from the DB, so editing one on an existing row was
  // a silent no-op: identical content key + row_num + struck-state -> the
  // short-circuit `continue`. The DB must follow the fence; a third run
  // after the re-heal must NOT churn.
  test('visibility edit on an existing fence row re-heals the DB row (#4870)', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Alice likes tea | preference | 0.9 | world | medium |  |  | fence |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    let rows = await (engine as any).db.query(
      `SELECT visibility, notability FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(rows.rows).toEqual([{ visibility: 'world', notability: 'medium' }]);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const [{ id }] = (await (engine as any).db.query(`SELECT id FROM facts WHERE source_markdown_slug = 'people/alice'`)).rows;
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Alice likes tea | preference | 0.9 | private | medium |  |  | fence |  |`,
    ));
    const second = await runExtractFacts(engine, { slugs: ['people/alice'] });
    // B-5: updated in place, the fact id survives.
    expect(second.factsUpdated).toBe(1);
    expect(second.factsInserted).toBe(0);
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    rows = await (engine as any).db.query(
      `SELECT id, visibility, notability FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(rows.rows).toEqual([{ id, visibility: 'private', notability: 'medium' }]);

    const third = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(third.factsInserted).toBe(0);
    expect(third.factsUpdated).toBe(0);
    expect(third.factsDeleted).toBe(0);
  });

  test('notability edit on an existing fence row re-heals the DB row (#4870)', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Alice likes tea | preference | 0.9 | world | medium |  |  | fence |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const [{ id }] = (await (engine as any).db.query(`SELECT id FROM facts WHERE source_markdown_slug = 'people/alice'`)).rows;
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Alice likes tea | preference | 0.9 | world | high |  |  | fence |  |`,
    ));
    const second = await runExtractFacts(engine, { slugs: ['people/alice'] });
    // B-5: updated in place, the fact id survives.
    expect(second.factsUpdated).toBe(1);
    expect(second.factsInserted).toBe(0);
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT id, visibility, notability FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(rows.rows).toEqual([{ id, visibility: 'world', notability: 'high' }]);

    const third = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(third.factsInserted).toBe(0);
    expect(third.factsDeleted).toBe(0);
  });

  test('malformed fence rows make the page non-authoritative and preserve its indexed facts', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | B | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // A hand edit corrupts row 2. The parser can still recover row 1, but
    // that partial result is not an authoritative replacement for the page.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |
| 2 | B | bogus | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await putPage('people/bob', FACT_FENCE(
      `| 1 | Clean | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice', 'people/bob'] });

    expect(r.warnings.some(w => w.includes('FACTS_TABLE_MALFORMED'))).toBe(true);
    expect(r.pagesScanned).toBe(2);
    expect(r.factsInserted).toBe(1);
    expect(r.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );
    expect(rows.rows.map((row: { fact: string }) => row.fact)).toEqual(['A', 'B']);

    // A warning is page-local: clean pages in the same cycle still reconcile.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const cleanRows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/bob'`,
    );
    expect(cleanRows.rows.map((row: { fact: string }) => row.fact)).toEqual(['Clean']);
  });

  test('#3625 / #6686: a lone Facts fence below the timeline sentinel is read as the page fence, never treated as absence', async () => {
    await putPage('people/carol', FACT_FENCE(
      `| 1 | Seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/carol'] });

    // splitBody() would route a fence placed below the timeline sentinel
    // into page.timeline instead of compiled_truth (the LLM-composed shape
    // the issue describes). Simulate that post-split state directly: the
    // fence is present on the page, just in the wrong column.
    await engine.putPage('people/carol', {
      title: 'people/carol',
      type: 'person',
      compiled_truth: '# Page\n\nBody.\n\n<!-- timeline -->\n',
      frontmatter: {},
      timeline: FACT_FENCE(
        `| 1 | Seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
      ),
    });

    const r = await runExtractFacts(engine, { slugs: ['people/carol'] });

    // #6686 (D8): the managed writers keep and edit a lone timeline fence in place, so reconcile reads it there.
    expect(r.warnings).toEqual([]);
    expect(r.factsDeleted).toBe(0);
    expect(r.factsInserted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/carol'`,
    );
    expect(rows.rows.map((row: { fact: string }) => row.fact)).toEqual(['Seeded']);
  });

  test('page with no facts fence → its fence rows are kept (held fence_absent); an empty fence reconciles to an empty active index', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // Now write a fact-less version of the page: GBRA-161 PR 2 holds it; the empty fence is the deletion.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice', body => putPage('people/alice', body), '# Just a page\n\nNo fence.\n');
  });

  test('#3625 / #6686: a lone Facts fence below the timeline sentinel reconciles from where it lives, not as a deleted fence', async () => {
    // Seed the page with the fence in its normal place (above the sentinel)
    // and let it index normally.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 |  | linkedin |  |
| 2 | Prefers async | preference | 0.85 | private | medium | 2026-04-29 |  | OH |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const seeded = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY row_num`,
    );
    expect(seeded.rows).toHaveLength(2);

    // #3625 repro: rewrite the page so the SAME fence content now lives in
    // `timeline` (below the sentinel) instead of `compiled_truth` — exactly
    // what splitBody() produces for a page whose `## Facts` fence was
    // written below `<!-- timeline -->`. compiled_truth carries none of the
    // fence text, so parseFactsFence(compiled_truth) sees zero facts.
    await putPageWithTimeline(
      'people/alice',
      '# Page\n\nBody.\n',
      FACT_FENCE(
        `| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 |  | linkedin |  |
| 2 | Prefers async | preference | 0.85 | private | medium | 2026-04-29 |  | OH |  |`,
      ),
    );

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    // This must NOT read as "fence removed": #6686 (D8) reads the lone timeline fence as the page's fence, so the
    // two rows the page write already projected from it stay indexed and the reconcile finds them in sync.
    expect(r.warnings).toEqual([]);
    expect(r.factsDeleted).toBe(0);
    expect(r.factsInserted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, row_num FROM facts WHERE source_markdown_slug = 'people/alice' AND expired_at IS NULL ORDER BY row_num`,
    );
    expect(rows.rows.map((row: { fact: string; row_num: number }) => [row.fact, Number(row.row_num)])).toEqual([['Founded Acme', 1], ['Prefers async', 2]]);
  });

  test('#3625 control: a genuinely fence-less page (no fence anywhere in the body) still wipes as before', async () => {
    // Same shape as the misplaced-fence case above, but this time the fence
    // is truly absent from BOTH compiled_truth and timeline — the existing
    // "user deleted the fence" contract must still hold; the #3625 guard
    // must not swallow genuine deletions.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // GBRA-161 PR 2: a truly absent fence now holds (fence_absent) instead of wiping; the empty fence is the deletion.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice',
      body => putPageWithTimeline('people/alice', body, 'Some unrelated timeline prose.\n'), '# Just a page\n\nNo fence.\n');
  });

  test('#3625 adversarial review finding: the marker merely mentioned inside a ```code block``` does not block a genuine deletion', async () => {
    // A naive `.includes(FACTS_FENCE_BEGIN)` check false-positives here — the
    // marker text is present in timeline, but only as documentation, not as
    // a real fence. The real fence was genuinely removed and must delete.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // GBRA-161 PR 2: the mention is still not a fence (no FACTS_FENCE_BELOW_SENTINEL), so the page's fence is absent and
    // holds; the empty fence, written beside the same mention, is the genuine deletion and is not blocked by it.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice',
      body => putPageWithTimeline('people/alice', body, '## Docs\n\n```markdown\n<!--- gbrain:facts:begin -->\nexample only\n```\n'), '# Alice\n\nThe real Facts fence was removed.\n');
  });

  test('#3625 adversarial review finding: the marker merely quoted in prose does not block a genuine deletion', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // GBRA-161 PR 2: the mention is still not a fence (no FACTS_FENCE_BELOW_SENTINEL), so the page's fence is absent and
    // holds; the empty fence, written beside the same mention, is the genuine deletion and is not blocked by it.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice',
      body => putPageWithTimeline('people/alice', body, '> Historical docs mention the token <!--- gbrain:facts:begin -->, but this is not a fence.\n'), '# Alice\n\nThe real Facts fence was removed.\n');
  });

  test('#3625 control: a genuine unbalanced marker (own line, not inside a code block) still blocks deletion', async () => {
    // Contrast with the two false-positive tests above — this marker IS a
    // real (if malformed/unbalanced) fence occurrence and must still guard.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    await putPageWithTimeline(
      'people/alice',
      '# Alice\n\nNo compiled fence.\n',
      '<!--- gbrain:facts:begin -->\nPRIVATE_UNBALANCED_ROW\n',
    );
    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.factsDeleted).toBe(0);
    expect(r.warnings.some(w => w.includes('FACTS_FENCE_BELOW_SENTINEL'))).toBe(true);
  });

  test('#3625 adversarial review round 2: a CRLF-line-ending code block mentioning the marker does not false-positive', async () => {
    // Round-1 fix (scanFencedBlocks + string removal) normalized line
    // endings internally but tried to remove fence text from the
    // UN-normalized original string, silently failing to strip a CRLF code
    // block and leaving the false positive in place. The round-2 fix
    // (single-pass line scanner, one \r\n|\r|\n split applied throughout)
    // must handle this correctly.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // GBRA-161 PR 2: the mention is still not a fence (no FACTS_FENCE_BELOW_SENTINEL), so the page's fence is absent and
    // holds; the empty fence, written beside the same mention, is the genuine deletion and is not blocked by it.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice',
      body => putPageWithTimeline('people/alice', body, '## Docs\r\n\r\n```markdown\r\n<!--- gbrain:facts:begin -->\r\nexample only\r\n```\r\n'), '# Alice\n\nThe real Facts fence was removed.\n');
  });

  test('#3625 adversarial review round 2: two identical code-block mentions of the marker do not false-positive', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | seeded | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    const codeBlock = '```markdown\n<!--- gbrain:facts:begin -->\nexample only\n```\n';
    // GBRA-161 PR 2: the mention is still not a fence (no FACTS_FENCE_BELOW_SENTINEL), so the page's fence is absent and
    // holds; the empty fence, written beside the same mention, is the genuine deletion and is not blocked by it.
    await expectAbsentHoldsThenEmptyFenceRetires('people/alice',
      body => putPageWithTimeline('people/alice', body, `${codeBlock}\n${codeBlock}`), '# Alice\n\nThe real Facts fence was removed.\n');
  });

  test('#3625 via the real MCP write path: a stray fence below the sentinel is preserved even when import-file.ts is in play', async () => {
    // Codex review finding: the two tests above write compiled_truth/timeline
    // directly via engine.putPage, bypassing importFromContent's own #2044
    // remote-preservation logic (restores an old fence into compiled_truth
    // when an incoming remote write's compiled half has ZERO facts — which
    // would otherwise mask a below-sentinel duplicate by never even letting
    // this test reach the state it wants to prove: confirmed by running the
    // simpler "compiled_truth ends up with zero facts" version of this test
    // first — #2044 fired and restored the OLD fence, so compiled_truth
    // never went empty and this guard was never exercised).
    //
    // Reproduce a case #2044 does NOT swallow: the incoming remote write's
    // compiled_truth keeps ONE valid fact above the sentinel (so
    // incomingFacts.facts.length > 0 — #2044's restore condition requires
    // exactly 0 and does not fire) while ALSO carrying a stray duplicate
    // fence below the sentinel (e.g. an agent re-appending a "## Facts"
    // section near new content it's adding at the bottom of the page).
    // splitBody() (inside putPage, called by importFromContent) does the
    // real fence/sentinel split — no direct column poking.
    const seed = `---
title: alice
type: person
---

Some body content.

## Facts

<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 |  |  linkedin |  |
| 2 | Prefers async | preference | 0.85 | world | medium | 2026-04-29 |  |  OH |  |
<!--- gbrain:facts:end -->

<!-- timeline -->
`;
    await importFromContent(engine, 'people/alice', seed, { noEmbed: true, remote: true });
    await runExtractFacts(engine, { slugs: ['people/alice'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const seeded = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(seeded.rows).toHaveLength(2);

    // A malformed remote rewrite: row 1 stays correctly placed above the
    // sentinel (so #2044's restore never fires — incomingFacts.facts.length
    // is 1, not 0), but row 2 got duplicated into a second fence below it.
    const misplaced = `---
title: alice
type: person
---

Some body content.

## Facts

<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
| 1 | Founded Acme | fact | 1.0 | world | high | 2017-01-01 |  |  linkedin |  |
<!--- gbrain:facts:end -->

<!-- timeline -->

## Facts

<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
| 1 | Prefers async | preference | 0.85 | world | medium | 2026-04-29 |  |  OH |  |
<!--- gbrain:facts:end -->
`;
    await importFromContent(engine, 'people/alice', misplaced, { noEmbed: true, remote: true });

    const page = await engine.getPage('people/alice');
    // Sanity: confirm the real write path actually reproduces the #3625
    // precondition (#2044 did NOT restore anything away, and a fence marker
    // really did land in timeline) before trusting the assertions below.
    expect(parseFactsFence(page!.compiled_truth ?? '').facts).toHaveLength(1);
    expect((page!.timeline ?? '')).toContain('gbrain:facts:begin');

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.factsDeleted).toBe(0);
    expect(r.warnings.some(w => w.includes('FACTS_FENCE_BELOW_SENTINEL'))).toBe(true);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/alice'`,
    );
    expect(rows.rows).toHaveLength(2);
  });

  test('dry-run does not touch DB', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    const r = await runExtractFacts(engine, { slugs: ['people/alice'], dryRun: true });
    expect(r.pagesScanned).toBe(1);
    expect(r.pagesWithFacts).toBe(1);
    expect(r.factsInserted).toBe(0);
    expect(r.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query('SELECT COUNT(*) AS n FROM facts');
    expect(Number(rows.rows[0].n)).toBe(0);
  });

  test('walks every brain page when no slugs filter is provided', async () => {
    await putPage('people/alice', FACT_FENCE(
      `| 1 | A1 | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));
    await putPage('companies/acme', FACT_FENCE(
      `| 1 | C1 | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine);  // no slugs filter
    expect(r.pagesScanned).toBe(2);
    expect(r.factsInserted).toBe(2);
  });
});

describe('runExtractFacts — empty-fence guard (Codex R2-#7)', () => {
  test('refuses to run when legacy v0.31 rows are pending the v0_32_2 backfill', async () => {
    // Seed a legacy fact (row_num NULL, entity_slug NOT NULL — the
    // v0.31 hot-memory shape pre-backfill).
    // 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)
       VALUES ('default', 'people/alice', 'legacy claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );

    // Seed a real page with a fence.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | new fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.guardTriggered).toBe(true);
    expect(r.legacyRowsPending).toBe(1);
    expect(r.factsInserted).toBe(0);
    expect(r.factsDeleted).toBe(0);
    // The page's canonical file is not on this host, so the phase's own fence
    // step could not fence the row; the warning names the page and why.
    expect(r.warnings.some(w => w.startsWith('FACTS_FENCE_FAILED: people/alice ('))).toBe(true);
    expect(r.warnings.some(w => w.includes('unfenced fact row(s)') && !w.includes('v0.31'))).toBe(true);

    // Legacy row was NOT touched.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, row_num FROM facts WHERE row_num IS NULL`,
    );
    expect(rows.rows[0].fact).toBe('legacy claim');
  });

  test('guard releases when all legacy rows have been backfilled', async () => {
    // Seed a backfilled (v51) row — row_num + source_markdown_slug set.
    // 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', 'people/alice', 'already fenced', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0, 5, 'people/alice')`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | F1 | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.guardTriggered).toBe(false);
    expect(r.legacyRowsPending).toBe(0);
    expect(r.factsInserted).toBe(1);
  });

  test('soft-expired legacy rows do NOT trigger the guard (#2646 — forget_fact drains the backlog)', async () => {
    // A legacy row that forget_fact already soft-expired. Before #2646
    // the guard counted it forever: apply-migrations no-ops (migration
    // marked applied) and forget_fact only sets expired_at, so the
    // phase was permanently blocked with no sanctioned way out.
    // 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, expired_at)
       VALUES ('default', 'people/alice', 'forgotten legacy claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0, now())`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | new fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.guardTriggered).toBe(false);
    expect(r.legacyRowsPending).toBe(0);
    expect(r.factsInserted).toBe(1);

    // The expired legacy row itself is untouched (soft-expire is the
    // record of the forget; the phase must not hard-delete it).
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE row_num IS NULL AND expired_at IS NOT NULL`,
    );
    expect(rows.rows).toHaveLength(1);
    expect(rows.rows[0].fact).toBe('forgotten legacy claim');
  });

  test('expired legacy row WITH source_markdown_slug set survives reconcile untouched (#2646 codex P2)', async () => {
    // Hybrid shape: row_num NULL (legacy — never fence-owned) but
    // source_markdown_slug matching a live page. Without the
    // preserveExpiredLegacy filter, the reconcile pass would count it
    // as "stale", trigger a wipe, hard-delete the forget record, and
    // reinsert the fence's rows fresh — reviving a forgotten claim as
    // an active fact.
    // 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, expired_at, source_markdown_slug)
       VALUES ('default', 'people/alice', 'forgotten hybrid claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0, now(), 'people/alice')`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | fence fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r1 = await runExtractFacts(engine, { slugs: ['people/alice'] });
    const r2 = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r1.guardTriggered).toBe(false);
    // The expired hybrid row is invisible to the reconcile: the fence
    // fact inserts normally, nothing is wiped, and re-running stays
    // idempotent (the hybrid row must not read as perpetually stale).
    expect(r1.factsInserted).toBe(1);
    expect(r1.factsDeleted).toBe(0);
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, expired_at FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY id`,
    );
    expect(rows.rows).toHaveLength(2);
    expect(rows.rows[0].fact).toBe('forgotten hybrid claim');
    expect(rows.rows[0].expired_at).not.toBeNull();
    expect(rows.rows[1].fact).toBe('fence fact');
    expect(rows.rows[1].expired_at).toBeNull();
  });

  test('expired legacy hybrid row survives even a stale-row wipe on the same page (#2646 codex P2)', async () => {
    // Force the wipe path: seed a fence, reconcile, then change the
    // fence so the old DB row goes stale. The wipe must delete the
    // stale fence-owned row but preserve the expired legacy hybrid.
    // 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, expired_at, source_markdown_slug)
       VALUES ('default', 'people/alice', 'forgotten hybrid claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0, now(), 'people/alice')`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | old fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/alice'] });

    // Replace the fence content — 'old fact' is now stale in the DB.
    await putPage('people/alice', FACT_FENCE(
      `| 1 | replacement fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));
    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.factsDeleted).toBe(1); // only the stale fence-owned row
    expect(r.factsInserted).toBe(1);

    // B-5: the stale fence row is expired and detached; the hybrid row is untouched.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, row_num, expired_at IS NOT NULL AS expired FROM facts WHERE source_markdown_slug = 'people/alice' ORDER BY id`,
    );
    expect(rows.rows).toEqual([
      { fact: 'forgotten hybrid claim', row_num: null, expired: true },
      { fact: 'old fact', row_num: null, expired: true },
      { fact: 'replacement fact', row_num: 1, expired: false },
    ]);
  });

  test('fence claim matching an expired legacy row is inserted active — fence is canonical (#2646)', async () => {
    // Deliberate semantics, pinned: legacy DB-only forgets are
    // documented NOT to survive rebuild (forget.ts header — the
    // explicit DB-only exception). When the fence still carries the
    // same (claim, source), the reconcile inserts a fresh active
    // fence-owned row; the expired legacy row survives alongside as
    // the record of the earlier forget. Suppressing the insert would
    // create silent fence↔DB divergence ("0 facts" while the fence
    // says otherwise) — the exact failure mode the guard prevents.
    // To durably forget, forget the fence-owned row (fence path).
    // 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, expired_at, source_markdown_slug)
       VALUES ('default', 'people/alice', 'shared claim', 'fact', 'private', 'medium',
               now(), 's', 1.0, now(), 'people/alice')`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | shared claim | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r1 = await runExtractFacts(engine, { slugs: ['people/alice'] });
    const r2 = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r1.factsInserted).toBe(1);
    expect(r1.factsDeleted).toBe(0);
    // Idempotent thereafter — the coexisting pair is stable state.
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const rows = await (engine as any).db.query(
      `SELECT fact, row_num, expired_at FROM facts
        WHERE source_markdown_slug = 'people/alice' ORDER BY id`,
    );
    expect(rows.rows).toHaveLength(2);
    expect(rows.rows[0]).toMatchObject({ fact: 'shared claim', row_num: null });
    expect(rows.rows[0].expired_at).not.toBeNull();   // forget record preserved
    expect(rows.rows[1]).toMatchObject({ fact: 'shared claim', row_num: 1 });
    expect(rows.rows[1].expired_at).toBeNull();       // fence-canonical active row
  });

  test('mixed active + expired legacy rows: guard counts only the active ones (#2646)', async () => {
    // One active legacy row + one soft-expired legacy row. The guard
    // must still trigger (an active row is pending backfill) but the
    // pending count must exclude the expired row — so each forget_fact
    // visibly drains the counter toward release.
    // 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, expired_at)
       VALUES
         ('default', 'people/alice', 'active legacy claim', 'fact', 'private', 'medium',
          now(), 'mcp:put_page', 1.0, NULL),
         ('default', 'people/alice', 'expired legacy claim', 'fact', 'private', 'medium',
          now(), 'mcp:put_page', 1.0, now())`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | new fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    expect(r.guardTriggered).toBe(true);
    expect(r.legacyRowsPending).toBe(1);
    expect(r.factsInserted).toBe(0);
    expect(r.factsDeleted).toBe(0);
  });

  test('NULL entity_slug legacy rows do NOT trigger the guard (they are structurally unfenceable)', async () => {
    // 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)
       VALUES ('default', NULL, 'unparented', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );

    await putPage('people/alice', FACT_FENCE(
      `| 1 | F | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.guardTriggered).toBe(false);
    expect(r.factsInserted).toBe(1);
  });

  // ── #2484: structurally-unfenceable hot-memory rows ───────────
  // The inline facts writer (backstop.ts) keeps producing
  // `row_num IS NULL, entity_slug IS NOT NULL` rows AFTER the v0_32_2
  // migration completes: when a resolved slug has no fenceable page
  // (slugify-floor / stub-guard-blocked unprefixed slugs like
  // `wingman` or `people-jane-doe`), it falls through to a DB-only
  // insert with row_num NULL. The OLD guard predicate
  // (`row_num IS NULL AND entity_slug IS NOT NULL`) matched these and
  // jammed the phase forever (~16/day) — they can never be fenced (no
  // page to fence onto; the ledger-complete migration won't re-run).
  // The fix requires a LIVE backing page, so these rows no longer gate.
  test('#2484: unfenceable inline-writer rows (entity_slug set, NO backing page) do NOT trigger the guard', async () => {
    // Two unfenceable rows whose entity_slug has no page row at all.
    // 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)
       VALUES
         ('default', 'wingman',          'handoff note A', 'fact', 'private', 'medium', now(), 'mcp:extract_facts', 1.0),
         ('default', 'people-jane-doe',  'handoff note B', 'fact', 'private', 'medium', now(), 'mcp:extract_facts', 1.0)`,
    );

    // A real page with a fence that SHOULD reconcile (proves the phase
    // converges past the guard rather than early-returning).
    await putPage('people/alice', FACT_FENCE(
      `| 1 | real fenced fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });

    // Guard must NOT trip — the unfenceable rows are permanent by
    // construction, not a migration blocker.
    expect(r.guardTriggered).toBe(false);
    expect(r.legacyRowsPending).toBe(0);
    // The phase ran its reconcile pass (did not early-return).
    expect(r.factsInserted).toBe(1);

    // The unfenceable rows survive untouched (still row_num NULL).
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const survivors = await (engine as any).db.query(
      `SELECT entity_slug FROM facts WHERE row_num IS NULL ORDER BY entity_slug`,
    );
    expect(survivors.rows.map((x: { entity_slug: string }) => x.entity_slug))
      .toEqual(['people-jane-doe', 'wingman']);
  });

  test('#2484: a genuine legacy row WITH a backing page still triggers the guard (discriminator stays sharp)', async () => {
    // Same shape as the unfenceable row above (row_num NULL, entity_slug
    // set) — the ONLY difference is a live backing page exists, so the
    // migration's Phase B could fence it. This MUST still gate.
    await putPage('people/bob', FACT_FENCE(
      `| 1 | fence fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));
    // 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)
       VALUES ('default', 'people/bob', 'genuine legacy claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );

    const r = await runExtractFacts(engine, { slugs: ['people/bob'] });

    expect(r.guardTriggered).toBe(true);
    expect(r.legacyRowsPending).toBe(1);
    expect(r.factsInserted).toBe(0);
    expect(r.factsDeleted).toBe(0);
    expect(r.warnings.some(w => w.startsWith('FACTS_FENCE_FAILED: people/bob ('))).toBe(true);
  });

  test('#2484: a soft-deleted backing page makes its legacy row unfenceable (does NOT gate)', async () => {
    // Page exists then gets soft-deleted (deleted_at set). The migration
    // can't fence onto a deleted page, so the row must not gate.
    await putPage('people/carol', FACT_FENCE(
      `| 1 | live fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));
    // 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)
       VALUES ('default', 'people/carol', 'orphaned legacy claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );
    // Soft-delete the page.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `UPDATE pages SET deleted_at = now() WHERE slug = 'people/carol' AND source_id = 'default'`,
    );

    // Reconcile a DIFFERENT live page so the phase has work to do.
    await putPage('people/dave', FACT_FENCE(
      `| 1 | dave fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    const r = await runExtractFacts(engine, { slugs: ['people/dave'] });
    expect(r.guardTriggered).toBe(false);
    expect(r.legacyRowsPending).toBe(0);
    expect(r.factsInserted).toBe(1);
  });
});

describe('runExtractFacts — guard requires a fenceable source (#2763)', () => {
  const seedLegacyRow = async (): Promise<void> => {
    // NULL-row_num fact whose entity_slug maps to a LIVE page — the shape
    // the guard gates on.
    // 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)
       VALUES ('default', 'people/alice', 'db-only claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );
    await putPage('people/alice', FACT_FENCE(
      `| 1 | new fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));
  };

  test('a local_path-less source does NOT trip the guard (thin-client rows are unfenceable)', async () => {
    // Thin-client / DB-only source: the backstop writer keeps producing
    // row_num-NULL rows with a live backing page, but the v0_32_2 Phase B
    // backfill SKIPS sources without local_path (skipped_no_local_path)
    // while returning complete — those rows can never drain, so they must
    // not jam the phase forever.
    // 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 seedLegacyRow();

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.guardTriggered).toBe(false);
    expect(r.legacyRowsPending).toBe(0);
    expect(r.factsInserted).toBe(1);
  });

  test('the same row on a source WITH local_path still trips the guard', async () => {
    // beforeEach set default.local_path (the migrated v0.31 brain shape);
    // Phase B CAN fence this row, so the guard must keep gating.
    await seedLegacyRow();

    const r = await runExtractFacts(engine, { slugs: ['people/alice'] });
    expect(r.guardTriggered).toBe(true);
    expect(r.legacyRowsPending).toBe(1);
    expect(r.factsInserted).toBe(0);
  });
});

describe('runExtractFacts — multi-source isolation', () => {
  test('a pending legacy row in source A does NOT jam extraction for source B (#2646 source-scope)', async () => {
    // local_path set: 'work' simulates a fenceable (migrated) source, so
    // its pending legacy row must still gate work's own cycle (#2763).
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `INSERT INTO sources (id, name, local_path, config)
       VALUES ('work', 'work', '/tmp/gbrain-extract-facts-work-src', '{}'::jsonb)
       ON CONFLICT (id) DO UPDATE SET local_path = EXCLUDED.local_path`,
    );

    // Source "work": a genuine pending legacy row (row_num NULL, active,
    // live backing page) — the exact shape that must gate work's cycle.
    await engine.putPage('people/alice', {
      title: 'people/alice', type: 'person',
      compiled_truth: FACT_FENCE(`| 1 | work fence fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`),
      frontmatter: {}, timeline: '',
    }, { sourceId: 'work' });
    // 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)
       VALUES ('work', 'people/alice', 'work legacy claim', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0)`,
    );

    // Source "default": clean — no legacy rows, one fenced page.
    await putPage('people/bob', FACT_FENCE(
      `| 1 | default fact | fact | 1.0 | world | high | 2026-01-01 |  | s |  |`,
    ));

    // default's run must NOT be jammed by work's pending backlog.
    const rDefault = await runExtractFacts(engine, { slugs: ['people/bob'], sourceId: 'default' });
    expect(rDefault.guardTriggered).toBe(false);
    expect(rDefault.legacyRowsPending).toBe(0);
    expect(rDefault.factsInserted).toBe(1);

    // work's own run still gates (discriminator stays sharp).
    const rWork = await runExtractFacts(engine, { slugs: ['people/alice'], sourceId: 'work' });
    expect(rWork.guardTriggered).toBe(true);
    expect(rWork.legacyRowsPending).toBe(1);
    expect(rWork.factsInserted).toBe(0);
    // The advice names the page the phase's own fence step could not fence.
    expect(rWork.warnings.some(w => w.startsWith('FACTS_FENCE_FAILED: people/alice ('))).toBe(true);
    expect(rWork.warnings.some(w => w.includes('forget_fact'))).toBe(true);
    expect(rWork.warnings.some(w => w.includes('source "work"'))).toBe(true);
  });

  test('deleteFactsForPage scoping does not affect other sources', async () => {
    // Seed sources work + home.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `INSERT INTO sources (id, name, config) VALUES
         ('work', 'work', '{}'::jsonb),
         ('home', 'home', '{}'::jsonb)
       ON CONFLICT (id) DO NOTHING`,
    );

    // Seed v51-shape facts in both sources for the same slug.
    // 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 ('home', 'people/alice', 'home fact', 'fact', 'private', 'medium',
               now(), 'mcp:put_page', 1.0, 1, 'people/alice')`,
    );

    // Seed default source's fence-only page (the cycle will reconcile this).
    await putPage('people/alice', FACT_FENCE(
      `| 1 | default fact | fact | 1.0 | world | medium | 2026-01-01 |  | s |  |`,
    ));

    await runExtractFacts(engine, { slugs: ['people/alice'], sourceId: 'default' });

    // The home-source row should survive — deleteFactsForPage('people/alice', 'default')
    // never matched it.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const homeRows = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_id = 'home'`,
    );
    expect(homeRows.rows).toHaveLength(1);
    expect(homeRows.rows[0].fact).toBe('home fact');
  });
});

describe('runExtractFacts — empty-slugs guard (v0.36.x #1096 regression)', () => {
  test('slugs:[] returns immediately without a full-brain walk', async () => {
    // Seed many pages; full-walk over them would be slow and would
    // populate pagesScanned > 0. With the bug, slugs:[] fell through
    // to engine.getAllSlugs() and walked every seed page.
    for (let i = 0; i < 5; i++) {
      await putPage(`people/seed-${i}`, FACT_FENCE(`| 1 | Seed ${i} | fact | 1.0 | world | high | 2017-01-01 |  | seed |  |`));
    }
    const r = await runExtractFacts(engine, { slugs: [] });
    expect(r.pagesScanned).toBe(0);
    expect(r.factsInserted).toBe(0);
  });

  test('slugs:undefined still triggers full-brain walk (regression guard for the other side of the bug)', async () => {
    await putPage('people/unscoped-walk', FACT_FENCE(`| 1 | Unscoped fact | fact | 1.0 | world | high | 2017-01-01 |  | seed |  |`));
    const r = await runExtractFacts(engine, {});
    expect(r.pagesScanned).toBeGreaterThan(0);
    // The unscoped fact should be seen at least once
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const seen = await (engine as any).db.query(
      `SELECT fact FROM facts WHERE source_markdown_slug = 'people/unscoped-walk' AND fact = 'Unscoped fact'`,
    );
    expect(seen.rows.length).toBeGreaterThan(0);
  });

  test('slugs:["a"] walks just the one slug, no full-brain fallback', async () => {
    await putPage('people/just-this-one', FACT_FENCE(`| 1 | Just one fact | fact | 1.0 | world | high | 2017-01-01 |  | seed |  |`));
    await putPage('people/sibling', FACT_FENCE(`| 1 | Sibling fact | fact | 1.0 | world | high | 2017-01-01 |  | seed |  |`));
    const r = await runExtractFacts(engine, { slugs: ['people/just-this-one'] });
    expect(r.pagesScanned).toBe(1);
  });
});

describe('runExtractFacts — v0.46 (#3014) supersession transport + heal', () => {
  // Row 1 struck + "superseded by #2"; row 2 the live superseding fact.
  const SUPERSEDE_FENCE = FACT_FENCE(
    `| 1 | ~~Will close by Q2~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #2 |
| 2 | Closed in Q3 | fact | 1.0 | world | high | 2026-07-01 |  | call |  |`,
  );

  const readSupersessionCols = async () => {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const r = await (engine as any).db.query(
      `SELECT row_num, superseded_by, expired_at FROM facts WHERE source_markdown_slug = 'people/deal' ORDER BY row_num`,
    );
    return r.rows as Array<{ row_num: number; superseded_by: number | null; expired_at: unknown }>;
  };

  const readIds = async (): Promise<number[]> => {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const r = await (engine as any).db.query(
      `SELECT id FROM facts WHERE source_markdown_slug = 'people/deal' ORDER BY row_num, id`,
    );
    return (r.rows as Array<{ id: number }>).map(x => Number(x.id));
  };

  test('reconcile transports superseded_by (resolved to the target row id) + expired_at', async () => {
    await putPage('people/deal', SUPERSEDE_FENCE);
    const r = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(r.factsInserted).toBe(2);
    // The only expected warning is the NULL-embedding notice (#2821) — no
    // supersession-resolution warning for a clean #2 reference.
    expect(r.warnings.filter(w => w.includes('superseded'))).toEqual([]);

    const rows = await readSupersessionCols();
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const ids = await (engine as any).db.query(
      `SELECT row_num, id FROM facts WHERE source_markdown_slug = 'people/deal' ORDER BY row_num`,
    );
    const row2Id = ids.rows.find((x: { row_num: number; id: number }) => x.row_num === 2).id;
    const row1 = rows.find(x => x.row_num === 1)!;
    expect(Number(row1.superseded_by)).toBe(Number(row2Id));
    expect(row1.expired_at).not.toBeNull();

    const sup = await engine.listSupersessions('default');
    expect(sup.some(s => s.superseded_by === Number(row2Id))).toBe(true);
  });

  test('idempotent: a second reconcile with the struck row already healed is a no-op', async () => {
    await putPage('people/deal', SUPERSEDE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    const r2 = await runExtractFacts(engine, { slugs: ['people/deal'] });
    // Columns already match the fence-desired state → no drift → no churn.
    expect(r2.factsInserted).toBe(0);
    expect(r2.factsDeleted).toBe(0);
  });

  test('heal: a struck row with NULL supersession columns re-populates on re-reconcile', async () => {
    await putPage('people/deal', SUPERSEDE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });

    // Simulate the pre-#3014 mis-transport: struck row inserted with NULL
    // columns. The fence text is unchanged, so only the supersession-column
    // drift check can trigger a re-heal.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `UPDATE facts SET superseded_by = NULL, expired_at = NULL WHERE source_markdown_slug = 'people/deal' AND row_num = 1`,
    );
    const drifted = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(drifted.superseded_by).toBeNull();
    expect(drifted.expired_at).toBeNull();

    const idsBefore = await readIds();
    const healRun = await runExtractFacts(engine, { slugs: ['people/deal'] });
    // Drift detected → the row is healed in place (B-5: ids kept).
    expect(healRun.factsUpdated).toBeGreaterThan(0);
    expect(await readIds()).toEqual(idsBefore);

    const healed = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(healed.superseded_by).not.toBeNull();
    expect(healed.expired_at).not.toBeNull();
  });

  // #9069: only a struck row may carry the link. A live row whose context
  // cell happens to read "superseded by #N" stays live and unlinked.
  const LIVE_NOTE_FENCE = FACT_FENCE(
    `| 1 | Will close by Q2 | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #2 |
| 2 | Closed in Q3 | fact | 1.0 | world | high | 2026-07-01 |  | call |  |`,
  );
  const row1Of = async () => (await readSupersessionCols()).find(x => x.row_num === 1)!;

  test('#9069: a live row with a "superseded by #2" context lands unlinked and stays out of supersessions', async () => {
    await putPage('people/deal', LIVE_NOTE_FENCE);
    const r = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(r.factsInserted).toBe(2);
    expect(r.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    const row1 = await row1Of();
    expect(row1.superseded_by).toBeNull();
    expect(row1.expired_at).toBeNull();
    expect((await engine.listSupersessions('default')).length).toBe(0);
  });

  test('#9069: removing the strikethrough from a superseded row clears its link', async () => {
    await putPage('people/deal', SUPERSEDE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect((await row1Of()).superseded_by).not.toBeNull();

    await putPage('people/deal', LIVE_NOTE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    const row1 = await row1Of();
    expect(row1.superseded_by).toBeNull();
    expect(row1.expired_at).toBeNull();
  });

  // Existing data: the full walk that `gbrain dream --phase extract_facts` runs clears it without a page edit.
  test('#9069: a live row stored with a wrong link by an older build is cleared by a full reconcile, page unchanged', async () => {
    await putPage('people/deal', LIVE_NOTE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `UPDATE facts SET superseded_by = (SELECT id FROM facts WHERE source_markdown_slug = 'people/deal' AND row_num = 2)
        WHERE source_markdown_slug = 'people/deal' AND row_num = 1`,
    );
    expect((await row1Of()).superseded_by).not.toBeNull();
    const idsBefore = await readIds();

    await runExtractFacts(engine, {});
    const row1 = await row1Of();
    expect(row1.superseded_by).toBeNull();
    expect(row1.expired_at).toBeNull();
    expect(await readIds()).toEqual(idsBefore);
    expect((await engine.listSupersessions('default')).length).toBe(0);
  });

  test('dangling reference (#N absent from fence) → warning, superseded_by NULL, expired_at set', async () => {
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Retired claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #9 |`,
    ));
    const r = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(r.warnings.some(w => w.includes('absent from the fence'))).toBe(true);

    const row1 = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(row1.superseded_by).toBeNull();
    expect(row1.expired_at).not.toBeNull();
  });

  // A permanently-unresolvable reference must NOT re-drift every cycle. A
  // naive drift term keyed off "the fence has a reference" vs "the DB
  // resolved one" would see self / dangling / chain (which correctly stay
  // NULL) drift forever — a full wipe+reinsert + duplicate warning each
  // cycle, with the fact ids advancing 1→2→3→…
  test('idempotent: a dangling reference does not churn — second reconcile is a no-op', async () => {
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Retired claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #9 |`,
    ));
    const first = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(first.factsInserted).toBeGreaterThan(0);
    const idsAfterFirst = await readIds();

    const second = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(second.factsInserted).toBe(0);
    expect(second.factsDeleted).toBe(0);
    expect(second.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    expect(await readIds()).toEqual(idsAfterFirst);
  });

  test('idempotent: a self-reference does not churn — second reconcile is a no-op', async () => {
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Ouroboros claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #1 |`,
    ));
    const first = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(first.warnings.some(w => w.includes('references itself'))).toBe(true);
    const idsAfterFirst = await readIds();

    const second = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(second.factsInserted).toBe(0);
    expect(second.factsDeleted).toBe(0);
    expect(second.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    expect(await readIds()).toEqual(idsAfterFirst);
  });

  test('a chain (struck → struck) links every hop and does not churn — second reconcile is a no-op (B-13)', async () => {
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Link a~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #2 |
| 2 | ~~Link b~~ | commitment | 0.6 | world | medium | 2026-02-01 |  | call | superseded by #3 |
| 3 | Live tail | fact | 1.0 | world | high | 2026-03-01 |  | call |  |`,
    ));
    const first = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(first.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    const idsAfterFirst = await readIds();
    const links = (await readSupersessionCols()).map(x => (x.superseded_by == null ? null : Number(x.superseded_by)));
    expect(links).toEqual([idsAfterFirst[1], idsAfterFirst[2], null]);

    const second = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(second.factsInserted).toBe(0);
    expect(second.factsDeleted).toBe(0);
    expect(second.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    expect(await readIds()).toEqual(idsAfterFirst);
  });

  // The no-churn drift term must not mask a genuine reference change.
  test('changed reference re-attempts: dangling → resolvable re-resolves superseded_by', async () => {
    // Cycle 1: row 1 struck, superseded by #9 (dangling); row 2 live.
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Old claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #9 |
| 2 | New claim | fact | 1.0 | world | high | 2026-07-01 |  | call |  |`,
    ));
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect((await readSupersessionCols()).find(x => x.row_num === 1)!.superseded_by).toBeNull();

    // Cycle 2: the operator fixes the reference to #2. The claim text and
    // row_num are unchanged, so only the supersession-drift term can catch
    // it — and it must, keying off the now-resolvable reference.
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Old claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #2 |
| 2 | New claim | fact | 1.0 | world | high | 2026-07-01 |  | call |  |`,
    ));
    const r = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(r.factsUpdated).toBeGreaterThan(0);

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const ids = await (engine as any).db.query(
      `SELECT row_num, id FROM facts WHERE source_markdown_slug = 'people/deal' ORDER BY row_num`,
    );
    const row2Id = Number(ids.rows.find((x: { row_num: number }) => Number(x.row_num) === 2).id);
    const row1 = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(Number(row1.superseded_by)).toBe(row2Id);

    // And it settles: a third cycle is a no-op.
    const third = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(third.factsInserted).toBe(0);
    expect(third.factsDeleted).toBe(0);
  });

  // Pre-fix, the reconcile deleted the page in a self-committing transaction
  // BEFORE the separate insertFacts transaction; an insert throw left the
  // page permanently emptied. The caller now defers the wipe into
  // insertFacts' own transaction, so a failing insert can never empty it.
  test('a failing write during reconcile rolls back and leaves the page intact', async () => {
    await putPage('people/deal', SUPERSEDE_FENCE);
    await runExtractFacts(engine, { slugs: ['people/deal'] });
    const before = await readIds();
    expect(before).toHaveLength(2);

    // Force a drift so the reconcile takes the wipe+reinsert path.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(
      `UPDATE facts SET superseded_by = NULL, expired_at = NULL WHERE source_markdown_slug = 'people/deal' AND row_num = 1`,
    );

    // Make the reconcile's final write throw. Every write of one page's
    // reconcile runs in a single transaction, so the heal above it rolls back.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query(`CREATE OR REPLACE FUNCTION test_reject_link() RETURNS trigger LANGUAGE plpgsql AS $fn$
      BEGIN RAISE EXCEPTION 'simulated write failure'; END $fn$`);
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await (engine as any).db.query('CREATE TRIGGER test_reject_link BEFORE UPDATE OF superseded_by ON facts FOR EACH ROW EXECUTE FUNCTION test_reject_link()');
    try {
      // The failure is isolated to this page and reported, not thrown out of
      // the phase (a thrown error aborted every later page).
      const result = await runExtractFacts(engine, { slugs: ['people/deal'] });
      expect(result.pagesFailed).toBe(1);
      expect(result.warnings.some(w => w.startsWith('people/deal: FACTS_RECONCILE_FAILED') && w.includes('simulated write failure'))).toBe(true);
    } finally {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      await (engine as any).db.query('DROP TRIGGER IF EXISTS test_reject_link ON facts');
    }

    // The page keeps its rows, and the in-place heal rolled back with the failure.
    expect(await readIds()).toEqual(before);
    const row1 = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(row1.expired_at).toBeNull();
  });

  // An int4-overflowing #N in the fence must be treated as a dangling
  // reference, never overflow the resolution SELECT and abort the cycle.
  test('int4-overflow reference in the fence → warning, cycle completes, second cycle no-op', async () => {
    await putPage('people/deal', FACT_FENCE(
      `| 1 | ~~Retired claim~~ | commitment | 0.6 | world | medium | 2026-01-01 |  | call | superseded by #99999999999 |`,
    ));
    const first = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(first.warnings.some(w => w.includes('absent from the fence'))).toBe(true);
    const row1 = (await readSupersessionCols()).find(x => x.row_num === 1)!;
    expect(row1.superseded_by).toBeNull();
    expect(row1.expired_at).not.toBeNull();
    const idsAfterFirst = await readIds();

    const second = await runExtractFacts(engine, { slugs: ['people/deal'] });
    expect(second.factsInserted).toBe(0);
    expect(second.factsDeleted).toBe(0);
    expect(second.warnings.filter(w => w.includes('superseded'))).toEqual([]);
    expect(await readIds()).toEqual(idsAfterFirst);
  });
});