Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

56.9 KB
Raw Blame
import {
  mkdirSync,
  mkdtempSync,
  rmSync,
  statSync,
  unlinkSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { BacklinkIndex } from './backlink-index.ts';
import { createContentFilter } from './content-filter.ts';
import {
  DerivedDocumentIndex,
  isDerivedDocumentIndexClosedError,
} from './derived-document-index.ts';
import { LocalTargetIndex } from './local-target-index.ts';
import type { WatcherLocalTargetInventory } from './local-target-inventory.ts';
import { getLogger } from './logger.ts';
import { TagIndex } from './tag-index.ts';

interface Rig {
  projectDir: string;
  contentDir: string;
  contentFilter: ReturnType<typeof createContentFilter>;
  signals: string[];
  index: DerivedDocumentIndex;
}

const cleanups: Array<() => Promise<void>> = [];

function createRig(
  getLocalTargetInventory?: () => WatcherLocalTargetInventory | null,
  onRecoveredFileTarget?: (relativePath: string, exists: boolean) => void,
): Rig {
  const projectDir = mkdtempSync(join(tmpdir(), 'ok-derived-index-'));
  const contentDir = join(projectDir, 'content');
  mkdirSync(contentDir, { recursive: true });
  const signals: string[] = [];
  const contentFilter = createContentFilter({ projectDir, contentDir });
  const index = new DerivedDocumentIndex({
    projectDir,
    contentDir,
    contentFilter,
    getGlobalSkillRoots: () => [],
    signalChannel: (channel) => signals.push(channel),
    ...(getLocalTargetInventory ? { getLocalTargetInventory } : {}),
    ...(onRecoveredFileTarget ? { onRecoveredFileTarget } : {}),
  });
  cleanups.push(async () => {
    await index.close();
    rmSync(projectDir, { recursive: true, force: true });
  });
  return { projectDir, contentDir, contentFilter, signals, index };
}

function writeDoc(rig: Rig, relativePath: string, markdown: string): void {
  const filePath = join(rig.contentDir, relativePath);
  mkdirSync(dirname(filePath), { recursive: true });
  writeFileSync(filePath, markdown);
}

async function settleStartup(rig: Rig): Promise<void> {
  const startup = rig.index.beginStartup('main');
  await startup.backlinksReady;
  await rig.index.settleStartupAfterWatcherSeed();
  rig.signals.length = 0;
}

afterEach(async () => {
  vi.useRealTimers();
  vi.restoreAllMocks();
  for (const cleanup of cleanups.splice(0)) await cleanup();
});

describe('DerivedDocumentIndex', () => {
  test('normal cache saves stay bounded during sustained edits and flush latest state on close', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    for (let i = 0; i < 75; i++) {
      const markdown = `See [[target-${i}]]. #stable\n`;
      writeDoc(rig, 'source.md', markdown);
      switch (i % 4) {
        case 0:
          await rig.index.recordDirectDocument('source', markdown);
          break;
        case 1:
          await rig.index.recordDiskUpsert('source', markdown);
          break;
        case 2:
          await rig.index.recordDurableStore('source', markdown);
          break;
        case 3:
          await rig.index.recordLinkRewrite('source', markdown);
          break;
      }
      expect(await rig.index.getBacklinks(`target-${i}`)).toHaveLength(1);
      await vi.advanceTimersByTimeAsync(1000);
      await rig.index.getIndexedDocNames();
    }

    expect(backlinkSave).toHaveBeenCalledTimes(3);
    expect(tagSave).toHaveBeenCalledTimes(3);
    const warm = new BacklinkIndex(rig);
    expect(await warm.loadFromDisk()).toBe(true);
    expect(warm.getBacklinks('target-59')).toHaveLength(1);
    expect(warm.getBacklinks('target-74')).toEqual([]);

    await vi.advanceTimersByTimeAsync(15_000);
    await rig.index.getIndexedDocNames();
    expect(backlinkSave).toHaveBeenCalledTimes(4);
    const quiet = new BacklinkIndex(rig);
    expect(await quiet.loadFromDisk()).toBe(true);
    expect(quiet.getBacklinks('target-74')).toHaveLength(1);

    writeDoc(rig, 'late.md', '#late-tag\n');
    await rig.index.recordDiskUpsert('late', '#late-tag\n');
    writeDoc(rig, 'source.md', 'See [[close-target]]. #stable\n');
    await rig.index.recordDurableStore('source', 'See [[close-target]]. #stable\n');
    await rig.index.close();
    expect(backlinkSave).toHaveBeenCalledTimes(5);
    expect(tagSave).toHaveBeenCalledTimes(5);
    await vi.advanceTimersByTimeAsync(60_000);
    expect(backlinkSave).toHaveBeenCalledTimes(5);
    expect(tagSave).toHaveBeenCalledTimes(5);

    const closed = new BacklinkIndex(rig);
    expect(await closed.loadFromDisk()).toBe(true);
    expect(closed.getBacklinks('close-target')).toHaveLength(1);
    expect(closed.getBacklinks('target-74')).toEqual([]);
    const tags = new TagIndex(rig);
    expect(await tags.loadFromDisk()).toBe(true);
    expect(tags.getDocsForTagWithMatches('late-tag')).toEqual([
      { docName: 'late', matchingTags: ['late-tag'] },
    ]);
    await tags.close();
  });

  test('a queued cache save checks the minimum interval when it actually executes', async () => {
    vi.useFakeTimers();
    const originalSave = BacklinkIndex.prototype.saveToDisk;
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    const started = Promise.withResolvers<void>();
    const release = Promise.withResolvers<void>();
    backlinkSave.mockImplementationOnce(async function (this: BacklinkIndex, branch) {
      started.resolve();
      await release.promise;
      await originalSave.call(this, branch);
    });

    writeDoc(rig, 'source.md', 'See [[queued-target]].\n');
    await rig.index.recordDiskUpsert('source', 'See [[queued-target]].\n');
    const running = rig.index.recordDirectDocument('running', '# Running\n');
    await started.promise;
    await vi.advanceTimersByTimeAsync(5000);
    release.resolve();
    await running;
    await rig.index.getIndexedDocNames();

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    await vi.advanceTimersByTimeAsync(29_999);
    await rig.index.getIndexedDocNames();
    expect(backlinkSave).toHaveBeenCalledTimes(1);
    await vi.advanceTimersByTimeAsync(1);
    await rig.index.getIndexedDocNames();
    expect(backlinkSave).toHaveBeenCalledTimes(2);
    const cached = new BacklinkIndex(rig);
    expect(await cached.loadFromDisk()).toBe(true);
    expect(cached.getBacklinks('queued-target')).toHaveLength(1);
  });

  test('a queued throttled save cannot rearm an old-branch timer during a switch', async () => {
    vi.useFakeTimers();
    const originalSave = BacklinkIndex.prototype.saveToDisk;
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    const started = Promise.withResolvers<void>();
    const release = Promise.withResolvers<void>();
    backlinkSave.mockImplementationOnce(async function (this: BacklinkIndex, branch) {
      started.resolve();
      await release.promise;
      await originalSave.call(this, branch);
    });

    writeDoc(rig, 'old.md', 'See [[old-target]].\n');
    await rig.index.recordDiskUpsert('old', 'See [[old-target]].\n');
    const running = rig.index.recordDirectDocument('running', '# Running\n');
    await started.promise;
    await vi.advanceTimersByTimeAsync(2000);
    const switching = rig.index.beginBranchSwitch('feature');
    release.resolve();
    await running;
    const transition = await switching;
    unlinkSync(join(rig.contentDir, 'old.md'));
    writeDoc(rig, 'feature.md', 'See [[feature-target]]. #feature\n');
    await rig.index.settleBranchFromDisk(transition);
    backlinkSave.mockClear();
    tagSave.mockClear();
    await vi.advanceTimersByTimeAsync(60_000);
    await rig.index.getIndexedDocNames();
    expect(backlinkSave).not.toHaveBeenCalled();
    expect(tagSave).not.toHaveBeenCalled();

    const cached = new BacklinkIndex(rig);
    expect(await cached.loadFromDisk('feature')).toBe(true);
    expect(cached.getBacklinks('feature-target', 'feature')).toHaveLength(1);
    expect(cached.getBacklinks('old-target', 'feature')).toEqual([]);
    expect(await cached.loadFromDisk('main')).toBe(true);
    expect(cached.getBacklinks('old-target', 'main')).toHaveLength(1);
  });

  test('every body feeder refreshes the resolved graph with unchanged document inventory', async () => {
    const rig = createRig();
    writeDoc(rig, 'notes/beta.md', '# Beta');
    writeDoc(rig, 'notes/gamma.md', '# Gamma');
    writeDoc(rig, 'source.md', '[[beta]]');
    await settleStartup(rig);
    expect(await rig.index.getBacklinkCount('notes/beta')).toBe(1);
    const feed = [
      async (markdown: string) => rig.index.recordDirectDocument('source', markdown),
      async (markdown: string) => {
        const token = rig.index.captureLiveUpdateToken();
        if (token === null) throw new Error('Live token unavailable');
        await rig.index.recordLiveDocument('source', markdown, token);
      },
      async (markdown: string) => rig.index.recordDurableStore('source', markdown),
      async (markdown: string) => rig.index.recordDiskUpsert('source', markdown),
      async (markdown: string) => rig.index.recordLinkRewrite('source', markdown),
    ];
    for (const [i, write] of feed.entries()) {
      const target = i % 2 === 0 ? 'gamma' : 'beta';
      const previous = target === 'beta' ? 'gamma' : 'beta';
      await write(`[[${target.toUpperCase()}.md#section]]`);
      expect(await rig.index.getBacklinkCount(`notes/${target}`)).toBe(1);
      expect(await rig.index.getBacklinkCount(`notes/${previous}`)).toBe(0);
      expect(await rig.index.getForwardLinkEntries('source')).toEqual([
        expect.objectContaining({ kind: 'doc', target: `notes/${target}`, anchor: 'section' }),
      ]);
      expect((await rig.index.getLinkGraph()).links).toEqual([
        { source: 'source', target: `notes/${target}` },
      ]);
      expect(await rig.index.getHubs()).toEqual([{ docName: `notes/${target}`, count: 1 }]);
      expect(await rig.index.getOrphans(['notes/beta', 'notes/gamma'], 'incoming')).toEqual([
        `notes/${previous}`,
      ]);
    }
  });

  test('direct documents update links and tags before returning and signal B/G/T', async () => {
    const rig = createRig();
    await settleStartup(rig);

    await rig.index.recordDirectDocument(
      'source',
      '---\ntags: [project/active]\n---\nSee [[target]].\n',
    );

    expect(await rig.index.getBacklinks('target')).toEqual([
      expect.objectContaining({ source: 'source' }),
    ]);
    expect(await rig.index.getBacklinkCounts(['target', 'missing'])).toEqual({
      target: 1,
      missing: 0,
    });
    expect(await rig.index.getDocsForTagWithMatches('project')).toEqual([
      { docName: 'source', matchingTags: ['project/active'] },
    ]);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('direct batches mutate in order with one cache save and one B/G/T signal set', async () => {
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordDirectMutations([
      { kind: 'upsert', documentName: 'first', markdown: 'See [[old]]. #old\n' },
      {
        kind: 'rename',
        oldDocumentName: 'first',
        newDocumentName: 'second',
        markdown: 'See [[target]]. #moved\n',
      },
      {
        kind: 'link-rewrite',
        documentName: 'second',
        markdown: 'See [[rewritten]]. #ignored\n',
      },
      { kind: 'delete', documentName: 'missing' },
    ]);

    expect(await rig.index.getBacklinks('old')).toEqual([]);
    expect(await rig.index.getBacklinks('target')).toEqual([]);
    expect((await rig.index.getBacklinks('rewritten')).map((entry) => entry.source)).toEqual([
      'second',
    ]);
    expect(await rig.index.getDocsForTagWithMatches('moved')).toEqual([
      { docName: 'second', matchingTags: ['moved'] },
    ]);
    expect(await rig.index.getDocsForTagWithMatches('ignored')).toEqual([]);
    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).toHaveBeenCalledTimes(1);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('empty direct batches are immediate no-ops across readiness, branch, and close gates', async () => {
    const rig = createRig();

    await expect(rig.index.recordDirectMutations([])).resolves.toBeUndefined();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('feature');
    await expect(rig.index.recordDirectMutations([])).resolves.toBeUndefined();
    rig.index.abortBranchSwitch(transition);
    await rig.index.close();
    await expect(rig.index.recordDirectMutations([])).resolves.toBeUndefined();
    expect(rig.signals).toEqual([]);
  });

  test('live documents do not persist caches but preserve backlink-first paired updates', async () => {
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    const token = rig.index.captureLiveUpdateToken();
    expect(token).not.toBeNull();
    await rig.index.recordLiveDocument('source', 'See [[target]]. #live\n', token ?? -1);

    expect(await rig.index.getBacklinks('target')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('live')).toHaveLength(1);
    expect(backlinkSave).not.toHaveBeenCalled();
    expect(tagSave).not.toHaveBeenCalled();
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('an ignored incremental document removes existing link and tag memberships', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('ignored', 'See [[target]]. #hidden\n');
    rig.signals.length = 0;
    writeFileSync(join(rig.projectDir, '.okignore'), 'content/ignored.md\n');
    const rebuilt = await rig.contentFilter.rebuildIgnorePatterns();
    expect(rebuilt.ok).toBe(true);

    await rig.index.recordDirectDocument('ignored', 'See [[target]]. #hidden\n');

    expect(await rig.index.getBacklinks('target')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('hidden')).toEqual([]);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('system and config docs are excluded while managed artifacts remain admitted', async () => {
    const rig = createRig();
    await settleStartup(rig);

    await rig.index.recordDirectDocument('__system__', 'See [[target]]. #internal\n');
    await rig.index.recordDirectDocument('__config__/project', 'See [[target]]. #internal\n');
    await rig.index.recordDirectDocument(
      '__template__/notes/lifecycle',
      'See [[target]]. #managed\n',
    );

    expect((await rig.index.getBacklinks('target')).map((entry) => entry.source)).toEqual([
      '__template__/notes/lifecycle',
    ]);
    expect(await rig.index.getDocsForTagWithMatches('internal')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('managed')).toEqual([
      { docName: '__template__/notes/lifecycle', matchingTags: ['managed'] },
    ]);
    expect(await rig.index.getIndexedDocNames()).not.toContain('__system__');
    expect(await rig.index.getIndexedDocNames()).not.toContain('__config__/project');
  });

  test('durable stores update and persist backlinks without changing tags or signaling', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordDurableStore('source', 'See [[target]]. #durable\n');

    expect(await rig.index.getBacklinks('target')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('durable')).toEqual([]);
    expect(backlinkSave).not.toHaveBeenCalled();
    expect(tagSave).not.toHaveBeenCalled();

    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).not.toHaveBeenCalled();
    expect(rig.signals).toEqual([]);
  });

  test('disk events debounce paired cache saves while applying and signaling immediately', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordDiskUpsert('source', 'See [[first]]. #one\n');
    await rig.index.recordDiskUpsert('source', 'See [[second]]. #two\n');

    expect(await rig.index.getBacklinks('first')).toEqual([]);
    expect(await rig.index.getBacklinks('second')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('two')).toHaveLength(1);
    expect(backlinkSave).not.toHaveBeenCalled();
    expect(tagSave).not.toHaveBeenCalled();

    await rig.index.recordDiskRename('source', 'renamed', 'See [[third]]. #three\n');
    await rig.index.recordDiskDelete('renamed');

    expect(await rig.index.getBacklinks('second')).toEqual([]);
    expect(await rig.index.getBacklinks('third')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('two')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('three')).toEqual([]);

    await vi.advanceTimersByTimeAsync(2000);
    await rig.index.getIndexedDocNames();

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).toHaveBeenCalledTimes(1);
    expect(rig.signals).toEqual([
      'backlinks',
      'graph',
      'tags',
      'backlinks',
      'graph',
      'tags',
      'backlinks',
      'graph',
      'tags',
      'backlinks',
      'graph',
      'tags',
    ]);
  });

  test('link rewrites are backlink-only and retain existing tag membership', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('source', 'See [[old]]. #stable\n');
    rig.signals.length = 0;

    await rig.index.recordLinkRewrite('source', 'See [[new]]. #changed\n');

    expect(await rig.index.getBacklinks('old')).toEqual([]);
    expect(await rig.index.getBacklinks('new')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('stable')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('changed')).toEqual([]);
    expect(rig.signals).toEqual(['backlinks', 'graph']);
  });

  test('link rewrites debounce their backlink cache save instead of saving before returning', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordLinkRewrite('source', 'See [[first]].\n');
    await rig.index.recordLinkRewrite('source', 'See [[second]].\n');

    expect(await rig.index.getBacklinks('second')).toHaveLength(1);
    expect(backlinkSave).not.toHaveBeenCalled();

    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).not.toHaveBeenCalled();
  });

  test('direct rename moves link and tag membership atomically', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('old', 'See [[target]]. #moved\n');
    rig.signals.length = 0;

    await rig.index.recordDirectRename('old', 'new', 'See [[target]]. #moved\n');

    expect((await rig.index.getBacklinks('target')).map((entry) => entry.source)).toEqual(['new']);
    expect(await rig.index.getDocsForTagWithMatches('moved')).toEqual([
      { docName: 'new', matchingTags: ['moved'] },
    ]);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('queries wait for post-watcher startup settlement', async () => {
    const rig = createRig();
    writeDoc(rig, 'source.md', 'See [[target]].\n');
    const startup = rig.index.beginStartup('main');
    let settled = false;
    const query = rig.index.getBacklinks('target').then((entries) => {
      settled = true;
      return entries;
    });

    await startup.backlinksReady;
    await Promise.resolve();
    expect(settled).toBe(false);

    await rig.index.settleStartupAfterWatcherSeed();
    await expect(query).resolves.toHaveLength(1);
  });

  test('branch transitions hold new commands until the replacement indexes settle', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('feature');
    let applied = false;
    let queried = false;
    const pending = rig.index.recordDirectDocument('after-switch', '# branch\n').then(() => {
      applied = true;
    });
    const pendingQuery = rig.index.getIndexedDocNames().then(() => {
      queried = true;
    });

    await Promise.resolve();
    expect(applied).toBe(false);
    expect(queried).toBe(false);

    await rig.index.settleBranchFromDisk(transition);
    await Promise.all([pending, pendingQuery]);
    expect(applied).toBe(true);
    expect(queried).toBe(true);
  });

  test('branch transitions invalidate stale live payloads captured from the old branch', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('old-doc', 'See [[target]]. #old-tag\n');
    const staleToken = rig.index.captureLiveUpdateToken();
    expect(staleToken).not.toBeNull();

    const transition = await rig.index.beginBranchSwitch('feature');
    const targetBranchToken = rig.index.captureLiveUpdateToken();
    expect(targetBranchToken).not.toBeNull();
    expect(targetBranchToken).not.toBe(staleToken);
    await rig.index.settleBranchFromDisk(transition);
    await rig.index.recordLiveDocument('old-doc', 'See [[target]]. #old-tag\n', staleToken ?? -1);

    expect(await rig.index.getBacklinks('target')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('old-tag')).toEqual([]);
  });

  test('live mutations captured during a branch transition wait and apply to the target branch', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('feature');
    const token = rig.index.captureLiveUpdateToken();
    expect(token).not.toBeNull();
    let mutationSettled = false;
    let querySettled = false;
    const mutation = rig.index
      .recordLiveDocument('target-live', 'See [[target]]. #target-live\n', token ?? -1)
      .then(() => {
        mutationSettled = true;
      });
    const query = rig.index.getBacklinks('target').then((entries) => {
      querySettled = true;
      return entries;
    });

    await Promise.resolve();
    expect(mutationSettled).toBe(false);
    expect(querySettled).toBe(false);

    await rig.index.settleBranchFromDisk(transition);
    await expect(mutation).resolves.toBeUndefined();
    await expect(query).resolves.toEqual([expect.objectContaining({ source: 'target-live' })]);
    expect(await rig.index.getDocsForTagWithMatches('target-live')).toHaveLength(1);
  });

  test('backlink failure short-circuits tags and signals without poisoning the queue', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const warn = vi.spyOn(getLogger('derived-document-index'), 'warn');
    const update = vi
      .spyOn(BacklinkIndex.prototype, 'updateDocumentFromMarkdown')
      .mockImplementationOnce(() => {
        throw new Error('injected projection failure');
      });
    const updateTags = vi.spyOn(TagIndex.prototype, 'updateDocumentFromMarkdown');

    await expect(rig.index.recordDirectDocument('failed', '# failed\n')).rejects.toThrow(
      'injected projection failure',
    );
    expect(updateTags).not.toHaveBeenCalled();
    expect(rig.signals).toEqual([]);
    expect(warn).toHaveBeenCalledWith(
      expect.objectContaining({ err: expect.any(Error) }),
      'Derived document index operation failed; queue remains available',
    );
    update.mockRestore();

    await expect(
      rig.index.recordDirectDocument('recovered', 'See [[target]].\n'),
    ).resolves.toBeUndefined();
    expect(updateTags).toHaveBeenCalledTimes(1);
    expect(await rig.index.getBacklinks('target')).toHaveLength(1);
  });

  test('refreshContentScope gates later mutations and queries until both replacements settle', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const backlinksReplacement = Promise.withResolvers<void>();
    const tagsReplacement = Promise.withResolvers<void>();
    vi.spyOn(BacklinkIndex.prototype, 'reconcileWithDisk').mockImplementationOnce(() =>
      backlinksReplacement.promise.then(() => ({
        added: 0,
        updated: 0,
        deleted: 0,
        deletedDocNames: [],
        changedDocs: [],
      })),
    );
    const tagInit = vi
      .spyOn(TagIndex.prototype, 'reconcileWithDisk')
      .mockImplementationOnce(() =>
        tagsReplacement.promise.then(() => ({ added: 0, updated: 0, deleted: 0 })),
      );

    const refresh = rig.index.refreshContentScope();
    let mutationSettled = false;
    let querySettled = false;
    const mutation = rig.index.recordDurableStore('after-refresh', '# refreshed\n').then(() => {
      mutationSettled = true;
    });
    const query = rig.index.getIndexedDocNames().then(() => {
      querySettled = true;
    });

    await Promise.resolve();
    expect(mutationSettled).toBe(false);
    expect(querySettled).toBe(false);
    expect(rig.signals).toEqual([]);

    backlinksReplacement.resolve();
    await vi.waitFor(() => expect(tagInit).toHaveBeenCalledTimes(1));
    expect(mutationSettled).toBe(false);
    expect(querySettled).toBe(false);
    expect(rig.signals).toEqual([]);

    tagsReplacement.resolve();
    await Promise.all([refresh, mutation, query]);
    expect(mutationSettled).toBe(true);
    expect(querySettled).toBe(true);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
  });

  test('content-scope refresh surfaces global ingest failure and the queue recovers', async () => {
    const rig = createRig();
    await settleStartup(rig);
    writeDoc(rig, 'hidden.md', 'See [[target]]. #hidden\n');
    await rig.index.recordDirectDocument('hidden', 'See [[target]]. #hidden\n');
    writeFileSync(join(rig.projectDir, '.okignore'), 'content/hidden.md\n');
    const rebuilt = await rig.contentFilter.rebuildIgnorePatterns();
    expect(rebuilt.ok).toBe(true);
    rig.signals.length = 0;
    vi.spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles').mockRejectedValueOnce(
      new Error('global ingest failed'),
    );

    await expect(rig.index.refreshContentScope()).rejects.toThrow('global ingest failed');
    expect(await rig.index.getBacklinks('target')).toEqual([]);
    expect(await rig.index.getDocsForTagWithMatches('hidden')).toEqual([]);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);

    await expect(
      rig.index.recordDirectDocument('recovered', 'See [[target]]. #recovered\n'),
    ).resolves.toBeUndefined();
    expect(await rig.index.getBacklinks('target')).toHaveLength(1);
    expect(await rig.index.getDocsForTagWithMatches('recovered')).toHaveLength(1);
  });

  test('test rescan surfaces global ingest failure and leaves the queue available', async () => {
    const rig = createRig();
    await settleStartup(rig);
    vi.spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles').mockRejectedValueOnce(
      new Error('rescan global ingest failed'),
    );

    await expect(rig.index.testOnly.rescanBacklinksForTest()).rejects.toThrow(
      'rescan global ingest failed',
    );
    expect(rig.signals).toEqual([]);

    await expect(
      rig.index.recordDirectDocument('recovered', 'See [[target]].\n'),
    ).resolves.toBeUndefined();
    expect(await rig.index.getBacklinks('target')).toHaveLength(1);
  });

  test('branch settlement rebuilds, ingests global nodes, then saves and falls back for tags', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('feature');
    const load = vi.spyOn(BacklinkIndex.prototype, 'loadFromDisk').mockResolvedValueOnce(false);
    const rebuild = vi
      .spyOn(BacklinkIndex.prototype, 'rebuildFromDisk')
      .mockResolvedValueOnce(undefined);
    const ingest = vi
      .spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles')
      .mockResolvedValueOnce(undefined);
    const backlinkSave = vi
      .spyOn(BacklinkIndex.prototype, 'saveToDisk')
      .mockResolvedValueOnce(undefined);
    const reconcileTags = vi
      .spyOn(TagIndex.prototype, 'reconcileWithDisk')
      .mockRejectedValueOnce(new Error('reconcile failed'));
    const rebuildTags = vi.spyOn(TagIndex.prototype, 'init').mockResolvedValueOnce(undefined);
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk').mockResolvedValueOnce(undefined);

    await rig.index.settleBranchFromDisk(transition);

    expect(load).toHaveBeenCalledWith('feature');
    expect(rebuild).toHaveBeenCalledWith('feature');
    expect(ingest).toHaveBeenCalledWith([], 'feature');
    expect(rebuild.mock.invocationCallOrder[0]).toBeLessThan(
      ingest.mock.invocationCallOrder[0] ?? 0,
    );
    expect(ingest.mock.invocationCallOrder[0]).toBeLessThan(
      backlinkSave.mock.invocationCallOrder[0] ?? 0,
    );
    expect(reconcileTags).toHaveBeenCalledTimes(1);
    expect(rebuildTags).toHaveBeenCalledTimes(1);
    expect(tagSave).toHaveBeenCalledTimes(1);
  });

  test('branch settlement reconciles a warm cache before global ingest and save', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('warm');
    vi.spyOn(BacklinkIndex.prototype, 'loadFromDisk').mockResolvedValueOnce(true);
    const reconcile = vi.spyOn(BacklinkIndex.prototype, 'reconcileWithDisk').mockResolvedValueOnce({
      added: 0,
      updated: 0,
      deleted: 0,
      deletedDocNames: [],
    });
    const ingest = vi
      .spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles')
      .mockResolvedValueOnce(undefined);
    const save = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk').mockResolvedValueOnce(undefined);

    await rig.index.settleBranchFromDisk(transition);

    expect(reconcile.mock.invocationCallOrder[0]).toBeLessThan(
      ingest.mock.invocationCallOrder[0] ?? 0,
    );
    expect(ingest.mock.invocationCallOrder[0]).toBeLessThan(save.mock.invocationCallOrder[0] ?? 0);
  });

  test('branch global-ingest failure still replaces local indexes and releases callers', async () => {
    const rig = createRig();
    writeDoc(rig, 'old.md', '# Old\n\n#old-branch\n');
    await settleStartup(rig);
    unlinkSync(join(rig.contentDir, 'old.md'));
    writeDoc(rig, 'target.md', '# Target\n\n#target-branch\n');
    const transition = await rig.index.beginBranchSwitch('feature');
    vi.spyOn(BacklinkIndex.prototype, 'ingestGlobalSkillBundles').mockRejectedValueOnce(
      new Error('branch global ingest failed'),
    );
    const query = rig.index.getDocsForTagWithMatches('target-branch');

    await expect(rig.index.settleBranchFromDisk(transition)).rejects.toThrow(
      'branch global ingest failed',
    );
    await expect(query).resolves.toEqual([{ docName: 'target', matchingTags: ['target-branch'] }]);
    expect(await rig.index.getDocsForTagWithMatches('old-branch')).toEqual([]);
  });

  test('beginBranchSwitch cancels an old-branch save timer before changing scope', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDiskUpsert('old-branch', '# old\n');

    const transition = await rig.index.beginBranchSwitch('feature');
    await rig.index.settleBranchFromDisk(transition);
    backlinkSave.mockClear();
    tagSave.mockClear();
    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).not.toHaveBeenCalled();
    expect(tagSave).not.toHaveBeenCalled();
  });

  test('abortBranchSwitch releases only the transition owned by its caller', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const transition = await rig.index.beginBranchSwitch('aborted');
    const mutation = rig.index.recordDirectDocument('released', '# released\n');
    const query = rig.index.getIndexedDocNames();
    let mutationSettled = false;
    void mutation.then(() => {
      mutationSettled = true;
    });

    rig.index.abortBranchSwitch({ branch: 'other' });
    await Promise.resolve();
    expect(mutationSettled).toBe(false);

    rig.index.abortBranchSwitch(transition);
    await expect(mutation).resolves.toBeUndefined();
    await expect(query).resolves.toBeInstanceOf(Array);
    await expect(rig.index.getIndexedDocNames()).resolves.toContain('released');
  });

  test('recognizes only coordinator close errors as lifecycle rejections', async () => {
    const rig = createRig();
    await rig.index.close();

    const closedError = await rig.index.getIndexedDocNames().catch((err: unknown) => err);

    expect(isDerivedDocumentIndexClosedError(closedError)).toBe(true);
    const sameName = new Error('lookalike');
    sameName.name = 'DerivedDocumentIndexClosedError';
    expect(isDerivedDocumentIndexClosedError(sameName)).toBe(false);
  });

  test('warm startup reports documents deleted while the server was down', async () => {
    const projectDir = mkdtempSync(join(tmpdir(), 'ok-derived-warm-'));
    const contentDir = join(projectDir, 'content');
    mkdirSync(contentDir, { recursive: true });
    writeFileSync(join(contentDir, 'stale.md'), '# stale\n');
    const contentFilter = createContentFilter({ projectDir, contentDir });
    const rawIndex = new BacklinkIndex({ projectDir, contentDir, contentFilter });
    await rawIndex.rebuildFromDisk('main');
    await rawIndex.saveToDisk('main');
    unlinkSync(join(contentDir, 'stale.md'));
    const index = new DerivedDocumentIndex({
      projectDir,
      contentDir,
      contentFilter,
      getGlobalSkillRoots: () => [],
      signalChannel: () => {},
    });
    cleanups.push(async () => {
      await index.close();
      rmSync(projectDir, { recursive: true, force: true });
    });

    const startup = index.beginStartup('main');

    await expect(startup.offlineDeletionsReady).resolves.toEqual(['stale']);
    await expect(startup.backlinksReady).resolves.toEqual({
      backlinkIndexDegraded: false,
    });
    await index.settleStartupAfterWatcherSeed();
  });

  test('degraded startup releases query readiness and reports index degradation', async () => {
    const warn = vi.spyOn(getLogger('derived-document-index'), 'warn');
    const rig = createRig();
    vi.spyOn(BacklinkIndex.prototype, 'loadFromDisk').mockRejectedValueOnce(
      new Error('broken backlink cache'),
    );
    vi.spyOn(TagIndex.prototype, 'loadFromDisk').mockRejectedValueOnce(
      new Error('broken tag cache'),
    );
    const startup = rig.index.beginStartup('main');
    await expect(startup.offlineDeletionsReady).resolves.toEqual([]);
    await expect(startup.backlinksReady).resolves.toEqual({
      backlinkIndexDegraded: true,
    });
    vi.spyOn(TagIndex.prototype, 'reconcileWithDisk').mockRejectedValueOnce(
      new Error('broken tag scan'),
    );
    const query = rig.index.getIndexedDocNames();

    await expect(rig.index.settleStartupAfterWatcherSeed()).resolves.toEqual({
      tagIndexDegraded: true,
    });
    await expect(query).resolves.toEqual([]);
    expect(warn).toHaveBeenCalledWith(
      expect.objectContaining({ err: expect.any(Error) }),
      '[derived-document-index] tag-index warm boot failed; continuing with stale or empty index',
    );
  });

  test('a startup graph pass with no file inventory keeps extension-less file hrefs as document edges', async () => {
    const rig = createRig(() => null);
    writeDoc(rig, 'src.md', 'See [notice](assets/NOTICE).\n');
    writeDoc(rig, 'assets/NOTICE', 'plain text\n');

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    await rig.index.settleStartupAfterWatcherSeed();

    expect((await rig.index.getBacklinks('assets/NOTICE')).map((entry) => entry.source)).toEqual([
      'src',
    ]);
  });

  test('startup settlement re-derives the graph once the watcher inventory arrives', async () => {
    let inventory: WatcherLocalTargetInventory | null = null;
    const rig = createRig(() => inventory);
    writeDoc(rig, 'src.md', 'See [notice](assets/NOTICE).\n');
    writeDoc(rig, 'assets/NOTICE', 'plain text\n');

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    inventory = { documentTargets: ['src'], fileTargets: ['assets/NOTICE'] };
    await rig.index.settleStartupAfterWatcherSeed();

    expect(await rig.index.getBacklinks('assets/NOTICE')).toEqual([]);
  });

  test('the graph file oracle recognises a file under an equivalent spelling', async () => {
    const stored = 'assets/NOTICE\u0301';
    const linked = 'assets/NOTIC\u00c9';
    let inventory: WatcherLocalTargetInventory | null = null;
    const rig = createRig(() => inventory);
    writeDoc(rig, 'src.md', `See [notice](${linked}).\n`);
    writeDoc(rig, stored, 'plain text\n');

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    inventory = { documentTargets: ['src'], fileTargets: [stored] };
    await rig.index.settleStartupAfterWatcherSeed();

    expect(await rig.index.getBacklinks(linked)).toEqual([]);
    expect(await rig.index.getDeadLinks(['src'])).toEqual([]);
  });

  test('startup settlement re-derives a warm graph cache against the watcher inventory', async () => {
    let inventory: WatcherLocalTargetInventory | null = null;
    const rig = createRig(() => inventory);
    writeDoc(rig, 'src.md', 'See [notice](assets/NOTICE).\n');
    writeDoc(rig, 'assets/NOTICE', 'plain text\n');

    const cached = new BacklinkIndex({
      projectDir: rig.projectDir,
      contentDir: rig.contentDir,
      contentFilter: rig.contentFilter,
    });
    await cached.rebuildFromDisk('main');
    await cached.saveToDisk('main');
    expect(cached.getBacklinks('assets/NOTICE', 'main')).toHaveLength(1);

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    inventory = { documentTargets: ['src'], fileTargets: ['assets/NOTICE'] };
    await rig.index.settleStartupAfterWatcherSeed();

    expect(await rig.index.getBacklinks('assets/NOTICE')).toEqual([]);
  });

  test('close flushes a pending paired save and rejects future commands', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordDiskUpsert('source', '# pending\n');
    const closing = rig.index.close();
    await expect(rig.index.recordDirectDelete('source')).rejects.toThrow(
      'Derived document index is closed',
    );
    await closing;
    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).toHaveBeenCalledTimes(1);
  });

  test('close flushes a pending backlink-only durable-store save', async () => {
    vi.useFakeTimers();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();

    await rig.index.recordDurableStore('source', 'See [[target]].\n');
    await rig.index.close();
    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).not.toHaveBeenCalled();
  });

  test('repeated close calls wait for the same dependency drain', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const tagClose = Promise.withResolvers<void>();
    const closeTagIndex = vi
      .spyOn(TagIndex.prototype, 'close')
      .mockReturnValueOnce(tagClose.promise);

    const firstClose = rig.index.close();
    const secondClose = rig.index.close();
    let secondCloseSettled = false;
    void secondClose.then(() => {
      secondCloseSettled = true;
    });
    await Promise.resolve();

    expect(closeTagIndex).toHaveBeenCalledTimes(1);
    expect(secondCloseSettled).toBe(false);

    tagClose.resolve();
    await Promise.all([firstClose, secondClose]);
    expect(secondCloseSettled).toBe(true);
  });

  test('close rejects an already-admitted queued disk mutation before it can arm a timer', async () => {
    vi.useFakeTimers();
    const deferredSave = Promise.withResolvers<void>();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const tagSave = vi.spyOn(TagIndex.prototype, 'saveToDisk');
    const indexLog = getLogger('derived-document-index');
    const warn = vi.spyOn(indexLog, 'warn');
    const debug = vi.spyOn(indexLog, 'debug');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();
    tagSave.mockClear();
    backlinkSave.mockImplementationOnce(async () => deferredSave.promise);

    const running = rig.index.recordDirectDocument('running', '# running\n');
    await vi.waitFor(() => expect(backlinkSave).toHaveBeenCalledTimes(1));
    const queued = rig.index.recordDiskUpsert('queued', '# queued\n');
    await Promise.resolve();
    const closing = rig.index.close();
    deferredSave.resolve();

    await expect(running).resolves.toBeUndefined();
    await expect(queued).rejects.toThrow('Derived document index is closed');
    await closing;
    const tagSaveCallsAfterClose = tagSave.mock.calls.length;
    await vi.advanceTimersByTimeAsync(2000);

    expect(backlinkSave).toHaveBeenCalledTimes(1);
    expect(tagSave).toHaveBeenCalledTimes(tagSaveCallsAfterClose);
    expect(debug).toHaveBeenCalledWith(
      expect.objectContaining({ err: expect.any(Error) }),
      'Derived document index operation rejected after close',
    );
    expect(warn).not.toHaveBeenCalledWith(
      expect.anything(),
      'Derived document index operation failed; queue remains available',
    );
  });

  test('close drains a debounced save already enqueued behind in-flight work', async () => {
    vi.useFakeTimers();
    const deferredSave = Promise.withResolvers<void>();
    const backlinkSave = vi.spyOn(BacklinkIndex.prototype, 'saveToDisk');
    const rig = createRig();
    await settleStartup(rig);
    backlinkSave.mockClear();

    await rig.index.recordDiskUpsert('disk-event', '# disk\n');
    backlinkSave.mockImplementationOnce(async () => deferredSave.promise);
    const running = rig.index.recordDirectDocument('running', '# running\n');
    await vi.waitFor(() => expect(backlinkSave).toHaveBeenCalledTimes(1));
    await vi.advanceTimersByTimeAsync(2000);

    const closing = rig.index.close();
    deferredSave.resolve();
    await expect(running).resolves.toBeUndefined();
    await closing;

    expect(backlinkSave).toHaveBeenCalledTimes(2);
  });
});

describe('DerivedDocumentIndex local-target projection', () => {
  test('a source edit assesses local targets and signals local-targets alongside relations', async () => {
    const rig = createRig();
    await settleStartup(rig);

    await rig.index.recordDirectDocument('src', 'See [x](target) and [pdf](assets/f.pdf).\n');

    const assessments = await rig.index.getLocalTargetAssessments('src');
    expect(assessments.map((a) => [a.targetKind, a.resolvedTarget, a.status])).toEqual([
      ['document', 'target', 'missing'],
      ['file', 'assets/f.pdf', 'missing'],
    ]);
    expect(rig.signals).toEqual(['backlinks', 'graph', 'local-targets', 'tags']);
  });

  test('the batch source query returns every source, or a scoped subset, through the ready gate', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('a', 'Download [pdf](assets/a.pdf).\n');
    await rig.index.recordDirectDocument('b', 'Download [pdf](assets/b.pdf).\n');

    const all = await rig.index.getLocalTargetAssessmentsForSources();
    expect(all.map((entry) => entry.source).sort()).toEqual(['a', 'b']);
    expect(all.flatMap((entry) => entry.assessments).every((a) => a.status === 'missing')).toBe(
      true,
    );

    const scoped = await rig.index.getLocalTargetAssessmentsForSources(['a']);
    expect(scoped.map((entry) => entry.source)).toEqual(['a']);
  });

  test('wiki-only and occurrence-free edits never signal local-targets or move its generation', async () => {
    const rig = createRig();
    await settleStartup(rig);
    const generation = await rig.index.getLocalTargetGeneration();

    await rig.index.recordDirectDocument('wiki', 'See [[target]]. #tagged\n');

    expect(rig.signals).toEqual(['backlinks', 'graph', 'tags']);
    expect(await rig.index.getLocalTargetGeneration()).toBe(generation);
    expect(await rig.index.getLocalTargetAssessments('wiki')).toEqual([]);
  });

  test('creating the target document heals the reference and re-signals', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('src', 'See [x](target).\n');
    rig.signals.length = 0;

    await rig.index.recordDirectDocument('target', '# Target\n');

    expect((await rig.index.getLocalTargetAssessments('src'))[0]).toMatchObject({
      status: 'exact',
    });
    expect(rig.signals).toContain('local-targets');
    expect(await rig.index.getLocalTargetDocumentDependents('target')).toEqual(['src']);
  });

  test('ordinary-file target events heal and break references and signal only when a dependent moves', async () => {
    const rig = createRig();
    await settleStartup(rig);
    await rig.index.recordDirectDocument('src', 'Download [pdf](assets/report.pdf).\n');
    rig.signals.length = 0;

    await rig.index.recordFileTargetUpsert('assets/report.pdf');
    expect((await rig.index.getLocalTargetAssessments('src'))[0]).toMatchObject({
      status: 'exact',
    });
    expect(rig.signals).toEqual(['local-targets']);

    rig.signals.length = 0;
    await rig.index.recordFileTargetDelete('assets/report.pdf');
    expect((await rig.index.getLocalTargetAssessments('src'))[0]).toMatchObject({
      status: 'missing',
      reason: 'no-such-file',
    });
    expect(rig.signals).toEqual(['local-targets']);

    rig.signals.length = 0;
    await rig.index.recordFileTargetUpsert('assets/unreferenced.pdf');
    expect(rig.signals).toEqual([]);
  });

  test('the dependency-only sweep repairs file inventory in both missed-watcher directions', async () => {
    vi.useFakeTimers();
    const inventory: WatcherLocalTargetInventory = {
      documentTargets: ['source'],
      fileTargets: ['assets/report.pdf'],
    };
    const recovered: Array<{ relativePath: string; exists: boolean }> = [];
    const rig = createRig(
      () => inventory,
      (relativePath, exists) => recovered.push({ relativePath, exists }),
    );
    writeDoc(rig, 'source.md', 'Download [pdf](assets/report.pdf).\n');
    writeDoc(rig, 'assets/report.pdf', '%PDF-1.4\n');
    await settleStartup(rig);
    expect((await rig.index.getLocalTargetAssessments('source'))[0]).toMatchObject({
      status: 'exact',
    });

    unlinkSync(join(rig.contentDir, 'assets/report.pdf'));
    await vi.advanceTimersByTimeAsync(5000);

    expect((await rig.index.getLocalTargetAssessments('source'))[0]).toMatchObject({
      status: 'missing',
      reason: 'no-such-file',
    });
    expect(rig.signals).toEqual(['local-targets', 'files']);
    expect(recovered).toEqual([{ relativePath: 'assets/report.pdf', exists: false }]);

    rig.signals.length = 0;
    writeDoc(rig, 'assets/report.pdf', '%PDF-1.4 restored\n');
    await vi.advanceTimersByTimeAsync(5000);

    expect((await rig.index.getLocalTargetAssessments('source'))[0]).toMatchObject({
      status: 'exact',
    });
    expect(rig.signals).toEqual(['local-targets', 'files']);
    expect(recovered).toEqual([
      { relativePath: 'assets/report.pdf', exists: false },
      { relativePath: 'assets/report.pdf', exists: true },
    ]);
  });

  test('a canonical document rename invalidates old aliases and admits new aliases', async () => {
    let inventory: WatcherLocalTargetInventory = {
      documentTargets: ['source', 'canonical-old', 'old-alias'],
      fileTargets: [],
    };
    const rig = createRig(() => inventory);
    writeDoc(rig, 'source.md', 'See [old](old-alias) and [new](new-alias).\n');
    writeDoc(rig, 'canonical-old.md', '# Old\n');
    await settleStartup(rig);
    expect((await rig.index.getLocalTargetAssessments('source')).map((a) => a.status)).toEqual([
      'exact',
      'missing',
    ]);

    inventory = {
      documentTargets: ['source', 'canonical-new', 'new-alias'],
      fileTargets: [],
    };
    await rig.index.recordDirectRename('canonical-old', 'canonical-new', '# New\n');

    expect((await rig.index.getLocalTargetAssessments('source')).map((a) => a.status)).toEqual([
      'missing',
      'exact',
    ]);
  });

  test('an ordinary-file delete invalidates direct and directory-alias identities together', async () => {
    let inventory: WatcherLocalTargetInventory = {
      documentTargets: ['source'],
      fileTargets: ['canonical/data.csv', 'direct.csv', 'folder-alias/data.csv'],
    };
    const rig = createRig(() => inventory);
    writeDoc(
      rig,
      'source.md',
      '[canonical](canonical/data.csv) [direct](direct.csv) [folder](folder-alias/data.csv)\n',
    );
    await settleStartup(rig);
    expect(
      (await rig.index.getLocalTargetAssessments('source')).every((a) => a.status === 'exact'),
    ).toBe(true);

    inventory = { documentTargets: ['source'], fileTargets: [] };
    await rig.index.recordFileTargetDelete('canonical/data.csv');

    expect((await rig.index.getLocalTargetAssessments('source')).map((a) => a.status)).toEqual([
      'missing',
      'missing',
      'missing',
    ]);
  });

  test('a direct batch coalesces high-fanout source assessments into one local-targets signal', async () => {
    const rig = createRig();
    await settleStartup(rig);

    await rig.index.recordDirectMutations(
      Array.from({ length: 12 }, (_, i) => ({
        kind: 'upsert' as const,
        documentName: `dep-${i}`,
        markdown: 'Download [pdf](assets/shared.pdf).\n',
      })),
    );

    expect(rig.signals.filter((channel) => channel === 'local-targets')).toHaveLength(1);
    expect(await rig.index.getLocalTargetFileDependents('assets/shared.pdf')).toHaveLength(12);
    expect(await rig.index.recordFileTargetUpsert('assets/shared.pdf')).toBeUndefined();
    for (let i = 0; i < 12; i++) {
      expect((await rig.index.getLocalTargetAssessments(`dep-${i}`))[0]).toMatchObject({
        status: 'exact',
      });
    }
  });

  test('local-target queries wait for post-watcher settlement rather than return a falsely clean result', async () => {
    const rig = createRig();
    writeDoc(rig, 'src.md', 'See [x](target).\n');
    const startup = rig.index.beginStartup('main');

    const pending = rig.index.getLocalTargetAssessments('src');
    let settled = false;
    void pending.then(() => {
      settled = true;
    });

    await startup.backlinksReady;
    await Promise.resolve();
    expect(settled).toBe(false);

    await rig.index.settleStartupAfterWatcherSeed();
    const assessments = await pending;
    expect(settled).toBe(true);
    expect(assessments[0]).toMatchObject({ resolvedTarget: 'target', status: 'missing' });
  });

  test('local-target queries fail closed when the startup rebuild fails', async () => {
    const rig = createRig();
    writeDoc(rig, 'src.md', 'See [x](target).\n');
    vi.spyOn(LocalTargetIndex.prototype, 'rebuildFromDisk').mockRejectedValueOnce(
      new Error('forced local-target rebuild failure'),
    );

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    await rig.index.settleStartupAfterWatcherSeed();

    await expect(rig.index.getIndexedDocNames()).resolves.toContain('src');
    await expect(rig.index.getLocalTargetAssessments('src')).rejects.toThrow(
      'Local-target index is not ready',
    );
    await expect(rig.index.getLocalTargetAssessmentsForSources()).rejects.toThrow(
      'Local-target index is not ready',
    );
  });

  test('a transient startup rebuild failure recovers on the scheduled retry', async () => {
    vi.useFakeTimers();
    const rig = createRig();
    writeDoc(rig, 'src.md', 'See [x](target).\n');
    vi.spyOn(LocalTargetIndex.prototype, 'rebuildFromDisk').mockRejectedValueOnce(
      new Error('transient rebuild failure'),
    );

    const startup = rig.index.beginStartup('main');
    await startup.backlinksReady;
    await rig.index.settleStartupAfterWatcherSeed();
    await expect(rig.index.getLocalTargetAssessments('src')).rejects.toThrow(
      'Local-target index is not ready',
    );

    await vi.advanceTimersByTimeAsync(1000);
    await expect(rig.index.getLocalTargetAssessments('src')).resolves.toEqual([
      expect.objectContaining({ resolvedTarget: 'target', status: 'missing' }),
    ]);
    expect(rig.signals).toContain('local-targets');
  });

  test('a branch switch reassesses against the new branch inventory', async () => {
    const rig = createRig();
    writeDoc(rig, 'src.md', 'See [x](target).\n');
    writeDoc(rig, 'target.md', '# Target\n');
    await settleStartup(rig);
    expect((await rig.index.getLocalTargetAssessments('src'))[0]).toMatchObject({
      status: 'exact',
    });

    unlinkSync(join(rig.contentDir, 'target.md'));
    const transition = await rig.index.beginBranchSwitch('feature');
    await rig.index.settleBranchFromDisk(transition);

    expect((await rig.index.getLocalTargetAssessments('src'))[0]).toMatchObject({
      status: 'missing',
      reason: 'no-such-doc',
    });
  });

  test('startup and branch-switch reuse persisted source links without reconcile logs', async () => {
    const rig = createRig();
    writeDoc(rig, 'source.md', 'See [[target]].\n');
    writeDoc(rig, 'target.md', '# Target\n');
    await settleStartup(rig);
    await rig.index.close();
    const info = vi.spyOn(getLogger('derived-document-index'), 'info');
    const restarted = new DerivedDocumentIndex({
      projectDir: rig.projectDir,
      contentDir: rig.contentDir,
      contentFilter: rig.contentFilter,
      getGlobalSkillRoots: () => [],
      signalChannel: () => {},
    });
    cleanups.unshift(() => restarted.close());
    await restarted.beginStartup('main').backlinksReady;
    await restarted.settleStartupAfterWatcherSeed();
    expect(info).not.toHaveBeenCalled();

    await restarted.settleBranchFromDisk(await restarted.beginBranchSwitch('feature'));
    info.mockClear();
    await restarted.settleBranchFromDisk(await restarted.beginBranchSwitch('main'));
    expect(info).not.toHaveBeenCalled();
  });

  test('startup and branch-switch reconcile changed sources from valid snapshots', async () => {
    const rig = createRig();
    writeDoc(rig, 'source.md', 'See [[first]].\n');
    await settleStartup(rig);
    await rig.index.close();

    const sourcePath = join(rig.contentDir, 'source.md');
    let nextMtimeMs = statSync(sourcePath).mtimeMs + 2000;
    const changeSource = (markdown: string) => {
      writeFileSync(sourcePath, markdown);
      const bumped = new Date(nextMtimeMs);
      nextMtimeMs += 2000;
      utimesSync(sourcePath, bumped, bumped);
    };
    const info = vi.spyOn(getLogger('derived-document-index'), 'info');
    const rebuild = vi.spyOn(BacklinkIndex.prototype, 'rebuildFromDisk');
    changeSource('See [[second]].\n');

    const restarted = new DerivedDocumentIndex({
      projectDir: rig.projectDir,
      contentDir: rig.contentDir,
      contentFilter: rig.contentFilter,
      getGlobalSkillRoots: () => [],
      signalChannel: () => {},
    });
    cleanups.unshift(() => restarted.close());
    await restarted.beginStartup('main').backlinksReady;
    await restarted.settleStartupAfterWatcherSeed();
    expect(info).toHaveBeenCalledWith(
      expect.objectContaining({ added: 0, updated: 1, deleted: 0 }),
      '[backlinks] startup reconcile',
    );
    expect(await restarted.getBacklinks('second')).toHaveLength(1);
    expect(await restarted.getBacklinks('first')).toHaveLength(0);
    expect(rebuild).not.toHaveBeenCalled();

    await restarted.settleBranchFromDisk(await restarted.beginBranchSwitch('feature'));
    expect(rebuild).toHaveBeenCalledTimes(1);
    changeSource('See [[third]].\n');
    info.mockClear();
    await restarted.settleBranchFromDisk(await restarted.beginBranchSwitch('main'));
    expect(info).toHaveBeenCalledWith(
      expect.objectContaining({ added: 0, updated: 1, deleted: 0 }),
      '[backlinks] branch-switch reconcile for main',
    );
    expect(await restarted.getBacklinks('third')).toHaveLength(1);
    expect(await restarted.getBacklinks('second')).toHaveLength(0);
    expect(rebuild).toHaveBeenCalledTimes(1);
  });
});