Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

160 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import { setTimeout as wait } from 'node:timers/promises';
import { Compartment } from '@codemirror/state';
import { PROTOCOL_VERSION } from '@inkeep/open-knowledge-core';
import { parseHocuspocusAuthToken } from '@inkeep/open-knowledge-server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import * as Y from 'yjs';
import { buildAuthToken } from '../lib/auth-token';
import { __resetCardinalityWarnings, getCollector } from '../lib/perf/collector';
import type { ClientPersistenceProvider } from './client-persistence';
import { ProviderPool } from './provider-pool';
import {
  __resetSyncPromiseCache,
  __syncPromiseCacheSize,
  BridgeSetupError,
  PreSyncDisconnectError,
  syncPromise,
} from './sync-promise';

function uniqueDocName(prefix = 'pp-us003'): string {
  return `${prefix}-${randomUUID()}`;
}

async function waitFor(predicate: () => boolean, timeoutMs = 1_000): Promise<boolean> {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    if (predicate()) return true;
    await wait(10);
  }
  return predicate();
}

async function awaitAttachedPersistence(entry: {
  persistence: ClientPersistenceProvider | null;
}): Promise<ClientPersistenceProvider> {
  await waitFor(() => entry.persistence !== null, 2_000);
  const persistence = entry.persistence;
  if (persistence === null) throw new Error('expected persistence to attach');
  return persistence;
}

const DUMMY_WS = 'ws://localhost:1/collab';

const TEST_SERVER_INSTANCE_ID = 'test-server-instance';

let pool: ProviderPool;

afterEach(() => {
  pool?.dispose();
});

describe('ProviderPool basics', () => {
  test('starts empty with no active document', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    expect(pool.entries.size).toBe(0);
    expect(pool.getActive()).toBeNull();
    expect(pool.getActiveDocName()).toBeNull();
  });

  test('open() creates an entry and returns it', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    expect(entry).not.toBeNull();
    expect(entry?.docName).toBe('doc1');
    expect(entry?.provider).toBeDefined();
    expect(pool.has('doc1')).toBe(true);
    expect(pool.entries.size).toBe(1);
  });

  test('open() reuses existing entry for same docName', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry1 = pool.open('doc1');
    const entry2 = pool.open('doc1');
    expect(entry1?.provider).toBe(entry2?.provider);
    expect(pool.entries.size).toBe(1);
  });

  test('setActive() sets the active document', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.setActive('doc1');
    expect(pool.getActiveDocName()).toBe('doc1');
    expect(pool.getActive()?.docName).toBe('doc1');
  });

  test('setActive() throws for unopened document', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    expect(() => pool.setActive('nonexistent')).toThrow('is not open');
  });

  test('close() removes entry and clears active if it was active', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.setActive('doc1');
    pool.close('doc1');
    expect(pool.has('doc1')).toBe(false);
    expect(pool.getActiveDocName()).toBeNull();
  });

  test('close() is no-op for unknown document', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.close('nonexistent');
    expect(pool.entries.size).toBe(0);
  });

  test('open() mints a fresh poolEventId on cold construct + emits hit:false', () => {
    getCollector()?.reset();
    __resetCardinalityWarnings();
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open(uniqueDocName());
    expect(entry).not.toBeNull();
    expect(typeof entry?.poolEventId).toBe('string');
    expect(entry?.poolEventId.length).toBeGreaterThan(0);
    const c = getCollector();
    const counter = c?.counters['ok/pool/open'];
    expect(counter?.byProp.hit?.false).toBe(1);
    expect(counter?.byProp.hit?.true).toBeUndefined();
    const openMark = c?.marks
      .toArray()
      .find((m) => m.name === 'ok/pool/open' && m.properties?.docName === entry?.docName);
    expect(openMark?.properties?.hit).toBe(false);
    expect(openMark?.properties?.poolEventId).toBe(entry?.poolEventId);
  });

  test('open() warm-back emits hit:true with previous lastAccessedAt and stable poolEventId', async () => {
    getCollector()?.reset();
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName();
    const fresh = pool.open(docName);
    expect(fresh).not.toBeNull();
    const previousAccessedAt = fresh?.lastAccessedAt ?? 0;
    const stableId = fresh?.poolEventId ?? '';
    await wait(2);
    const second = pool.open(docName);
    expect(second).toBe(fresh);
    expect(second?.poolEventId).toBe(stableId);
    expect((second?.lastAccessedAt ?? 0) >= previousAccessedAt).toBe(true);
    const c = getCollector();
    const counter = c?.counters['ok/pool/open'];
    expect(counter?.byProp.hit?.false).toBe(1);
    expect(counter?.byProp.hit?.true).toBe(1);
    const hitMark = c?.marks
      .toArray()
      .find(
        (m) =>
          m.name === 'ok/pool/open' &&
          m.properties?.docName === docName &&
          m.properties?.hit === true,
      );
    expect(hitMark?.properties?.lastAccessedAt).toBe(previousAccessedAt);
    expect(hitMark?.properties?.poolEventId).toBe(stableId);
  });

  test('open() returns null and emits no marks for system docs', () => {
    getCollector()?.reset();
    pool = new ProviderPool(3, DUMMY_WS);
    const result = pool.open('__system__');
    expect(result).toBeNull();
    const c = getCollector();
    const openMarks = c?.marks.toArray().filter((m) => m.name === 'ok/pool/open') ?? [];
    expect(openMarks.length).toBe(0);
    expect(c?.counters['ok/pool/open']).toBeUndefined();
  });

  test('peek() returns the entry without affecting LRU or emitting marks', () => {
    getCollector()?.reset();
    pool = new ProviderPool(3, DUMMY_WS);
    const a = uniqueDocName();
    const b = uniqueDocName();
    pool.open(a);
    pool.open(b);
    const c = getCollector();
    const beforeMarks = c?.marks.length ?? 0;
    const peeked = pool.peek(a);
    expect(peeked).not.toBeNull();
    expect(peeked?.docName).toBe(a);
    expect(c?.marks.length).toBe(beforeMarks);
    pool.open(uniqueDocName());
    pool.open(uniqueDocName());
    expect(pool.has(a)).toBe(false);
    expect(pool.has(b)).toBe(true);
  });

  test('prewarm() inherits open()-path poolEventId mint', () => {
    getCollector()?.reset();
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName();
    const entry = pool.prewarm(docName);
    expect(entry).not.toBeNull();
    expect(typeof entry?.poolEventId).toBe('string');
    expect(entry?.poolEventId.length).toBeGreaterThan(0);
    const c = getCollector();
    const counter = c?.counters['ok/pool/open'];
    expect(counter?.byProp.hit?.false).toBe(1);
  });

  test('has() returns false for unknown documents', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    expect(pool.has('nope')).toBe(false);
  });
});

describe('ProviderPool LRU eviction', () => {
  test('evicts LRU entry when at capacity', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.open('doc3');
    pool.open('doc4');
    expect(pool.has('doc1')).toBe(false);
    expect(pool.has('doc2')).toBe(true);
    expect(pool.has('doc3')).toBe(true);
    expect(pool.has('doc4')).toBe(true);
    expect(pool.entries.size).toBe(3);
  });

  test('never evicts the active document', () => {
    pool = new ProviderPool(2, DUMMY_WS);
    pool.open('doc1');
    pool.setActive('doc1');
    pool.open('doc2');
    pool.open('doc3');
    expect(pool.has('doc1')).toBe(true);
    expect(pool.has('doc2')).toBe(false);
    expect(pool.has('doc3')).toBe(true);
  });

  test('never evicts a visible non-focused document', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('focused');
    pool.open('visible');
    pool.open('hidden');
    pool.setActive('focused');
    pool.setVisibleDocNames(new Set(['focused', 'visible']));

    pool.open('new-doc');

    expect(pool.has('focused')).toBe(true);
    expect(pool.has('visible')).toBe(true);
    expect(pool.has('hidden')).toBe(false);
    expect(pool.has('new-doc')).toBe(true);
  });

  test('grows beyond the normal capacity for visible documents and trims after pane removal', () => {
    pool = new ProviderPool(2, DUMMY_WS);
    pool.setVisibleDocNames(new Set(['a', 'b', 'c', 'd']));
    pool.open('a');
    pool.open('b');
    pool.open('c');
    pool.open('d');
    pool.setActive('a');

    expect(pool.entries.size).toBe(4);

    pool.setVisibleDocNames(new Set(['a']));

    expect(pool.entries.size).toBe(2);
    expect(pool.has('a')).toBe(true);
  });

  test('ignores system documents in the visible protection set', () => {
    pool = new ProviderPool(2, DUMMY_WS);
    pool.open('a');
    pool.open('b');
    pool.setActive('a');
    pool.setVisibleDocNames(new Set(['a', '__system__']));

    pool.open('c');

    expect(pool.has('a')).toBe(true);
    expect(pool.has('b')).toBe(false);
    expect(pool.has('c')).toBe(true);
  });

  test('LRU order updates when document is re-opened', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.open('doc3');
    pool.open('doc1');
    pool.open('doc4');
    expect(pool.has('doc1')).toBe(true);
    expect(pool.has('doc2')).toBe(false);
    expect(pool.has('doc3')).toBe(true);
    expect(pool.has('doc4')).toBe(true);
  });

  test('LRU order updates when document is set active', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.open('doc3');
    pool.setActive('doc1');
    pool.open('doc4');
    expect(pool.has('doc1')).toBe(true);
    expect(pool.has('doc2')).toBe(false);
  });

  test('eviction with capacity 1 and active doc', () => {
    pool = new ProviderPool(1, DUMMY_WS);
    pool.open('doc1');
    pool.setActive('doc1');
    pool.open('doc2');
    expect(pool.has('doc1')).toBe(true);
    expect(pool.has('doc2')).toBe(true);
  });
});

describe('ProviderPool onChange', () => {
  test('fires onChange callback on open', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let callCount = 0;
    pool.setOnChange(() => callCount++);
    pool.open('doc1');
    expect(callCount).toBeGreaterThan(0);
  });

  test('fires onChange on setActive', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    let callCount = 0;
    pool.setOnChange(() => callCount++);
    pool.setActive('doc1');
    expect(callCount).toBe(1);
  });

  test('fires onChange on close', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    let callCount = 0;
    pool.setOnChange(() => callCount++);
    pool.close('doc1');
    expect(callCount).toBeGreaterThan(0);
  });
});

describe('ProviderPool unsynced-work signal', () => {
  test('hasAnyUnsyncedWork reflects an active provider unsyncedChanges count', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (entry === null) throw new Error('expected entry');
    expect(pool.hasAnyUnsyncedWork()).toBe(false);
    entry.provider.unsyncedChanges = 1;
    expect(pool.hasAnyUnsyncedWork()).toBe(true);
    entry.provider.unsyncedChanges = 0;
    expect(pool.hasAnyUnsyncedWork()).toBe(false);
  });

  test('addUnsyncedWorkListener fires on the provider unsyncedChanges event; unsubscribe stops it', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (entry === null) throw new Error('expected entry');
    let calls = 0;
    const stop = pool.addUnsyncedWorkListener(() => {
      calls++;
    });
    entry.provider.emit('unsyncedChanges', { number: 1 });
    expect(calls).toBe(1);
    stop();
    entry.provider.emit('unsyncedChanges', { number: 2 });
    expect(calls).toBe(1);
  });
});

describe('ProviderPool onEvict subscription', () => {
  test('fires evict listener on close', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    const evicted: string[] = [];
    pool.onEvict((name) => evicted.push(name));
    pool.close('doc1');
    expect(evicted).toEqual(['doc1']);
  });

  test('fires evict listener on LRU eviction', () => {
    pool = new ProviderPool(2, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.setActive('doc2');
    const evicted: string[] = [];
    pool.onEvict((name) => evicted.push(name));
    pool.open('doc3');
    expect(evicted).toEqual(['doc1']);
  });

  test('fires evict listener on dispose for every entry', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.open('doc3');
    const evicted: string[] = [];
    pool.onEvict((name) => evicted.push(name));
    pool.dispose();
    expect(new Set(evicted)).toEqual(new Set(['doc1', 'doc2', 'doc3']));
  });

  test('multiple subscribers all fire', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    let count1 = 0;
    let count2 = 0;
    pool.onEvict(() => count1++);
    pool.onEvict(() => count2++);
    pool.close('doc1');
    expect(count1).toBe(1);
    expect(count2).toBe(1);
  });

  test('unsubscribe stops the listener', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    let count = 0;
    const unsubscribe = pool.onEvict(() => count++);
    pool.close('doc1');
    expect(count).toBe(1);
    unsubscribe();
    pool.close('doc2');
    expect(count).toBe(1);
  });

  test('a throwing listener does not prevent others from firing', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    let secondFired = false;
    pool.onEvict(() => {
      throw new Error('synthetic listener failure');
    });
    pool.onEvict(() => {
      secondFired = true;
    });
    const originalWarn = console.warn;
    console.warn = vi.fn(() => {});
    try {
      pool.close('doc1');
    } finally {
      console.warn = originalWarn;
    }
    expect(secondFired).toBe(true);
  });
});

describe('ProviderPool disconnect recycling', () => {
  test('does not recycle a provider that disconnects before first sync', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const originalProvider = entry.provider;
    originalProvider.emit('disconnect', {
      event: { code: 1006, reason: 'startup offline', wasClean: false },
    });

    expect(pool.getActive()?.provider).toBe(originalProvider);
  });

  test('recycles a contentless active provider after disconnect when no unsynced changes remain', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 50 });
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const originalProvider = entry.provider;
    originalProvider.emit('synced', { state: true });
    originalProvider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });

    expect(entry.pendingRecycleTimer).not.toBeNull();

    await wait(100);

    const recycled = pool.getActive();
    expect(recycled).not.toBeNull();
    expect(recycled?.provider).not.toBe(originalProvider);
    expect(recycled?.docName).toBe('doc1');
  });

  test('preserves synced local content across disconnect debounce after tab switch', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 50 });
    const foo = pool.open('foo');
    const bar = pool.open('bar');
    if (!foo || !bar) throw new Error('expected entries');
    pool.setActive('foo');

    const originalProvider = foo.provider;
    const source = originalProvider.document.getText('source');
    source.insert(0, '# Foo\n\nLarge synced body\n');
    originalProvider.emit('synced', { state: true });
    originalProvider.unsyncedChanges = 0;

    originalProvider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });
    pool.setActive('bar');

    expect(foo.pendingRecycleTimer).toBeNull();

    await wait(100);

    expect(pool.has('foo')).toBe(true);
    expect(pool.entries.get('foo')?.provider).toBe(originalProvider);
    expect(source.toString()).toContain('Large synced body');
    expect(pool.getActiveDocName()).toBe('bar');

    const reopened = pool.open('foo');
    expect(reopened?.provider).toBe(originalProvider);
    pool.setActive('foo');
    expect(pool.getActive()?.provider).toBe(originalProvider);
    expect(source.toString()).toContain('Large synced body');
  });

  test('keeps the provider when disconnect occurs with unsynced local changes', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const originalProvider = entry.provider;
    originalProvider.emit('synced', { state: true });
    originalProvider.unsyncedChanges = 1;
    originalProvider.emit('disconnect', {
      event: { code: 1006, reason: 'offline', wasClean: false },
    });

    expect(pool.getActive()?.provider).toBe(originalProvider);
  });

  test('open() recycles a pooled entry whose socket already dropped', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const staleProvider = entry.provider;
    staleProvider.emit('synced', { state: true });
    staleProvider.emit('status', { status: 'disconnected' });
    expect(entry.syncState).toBe('disconnected');

    const reopened = pool.open('doc1');
    expect(reopened).not.toBeNull();
    expect(reopened?.provider).not.toBe(staleProvider);
    expect(reopened?.syncState).toBe('connecting');
    expect(pool.getActiveDocName()).toBe('doc1');
  });

  test('open() re-opens a disconnected background doc from scratch', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.setActive('doc1');
    const background = pool.open('doc2');
    if (!background) throw new Error('expected entry');

    const staleProvider = background.provider;
    staleProvider.emit('synced', { state: true });
    staleProvider.emit('status', { status: 'disconnected' });

    const reopened = pool.open('doc2');
    expect(reopened?.provider).not.toBe(staleProvider);
    expect(pool.entries.size).toBe(2);
  });

  test('open() keeps a disconnected entry that still holds unsynced edits', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const originalProvider = entry.provider;
    originalProvider.emit('synced', { state: true });
    originalProvider.unsyncedChanges = 1;
    originalProvider.emit('status', { status: 'disconnected' });

    expect(pool.open('doc1')?.provider).toBe(originalProvider);
  });
});

describe('ProviderPool dispose', () => {
  test('dispose clears all entries and state', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc1');
    pool.open('doc2');
    pool.setActive('doc1');
    pool.dispose();
    expect(pool.entries.size).toBe(0);
    expect(pool.getActive()).toBeNull();
    expect(pool.getActiveDocName()).toBeNull();
  });
});

describe('ProviderPool setupObservers init-throw recovery (S4)', () => {
  test('init-time throw rejects held syncPromise with BridgeSetupError + leaves entry pool-resident', async () => {
    pool = new ProviderPool(3, DUMMY_WS);

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    const consumerPromise = syncPromise('doc1', entry.provider);

    const doc = entry.provider.document;
    doc.getXmlFragment = () => {
      throw new Error('synthetic getXmlFragment failure');
    };

    const errorSpy = vi.fn(() => {});
    const origError = console.error;
    console.error = errorSpy;

    entry.provider.emit('synced', { state: true });

    console.error = origError;

    try {
      await consumerPromise;
      throw new Error('expected promise to reject');
    } catch (err) {
      expect(err).toBeInstanceOf(BridgeSetupError);
      expect((err as BridgeSetupError).docName).toBe('doc1');
      expect((err as BridgeSetupError).cause).toBeInstanceOf(Error);
      expect(((err as BridgeSetupError).cause as Error).message).toContain(
        'synthetic getXmlFragment failure',
      );
    }

    expect(pool.has('doc1')).toBe(true);
    expect(pool.entries.get('doc1')?.bridgeSetupFailed).toBe(true);
    expect(pool.getActiveDocName()).toBe('doc1');
    expect(pool.getActive()?.provider).toBe(entry.provider);

    expect(errorSpy).toHaveBeenCalledTimes(1);
    const loggedPrefix = errorSpy.mock.calls[0]?.[0] as string;
    const loggedError = errorSpy.mock.calls[0]?.[1] as Error;
    expect(loggedPrefix).toContain('[ProviderPool] setupObservers init failed for doc1:');
    expect(loggedError).toBeInstanceOf(Error);
    expect(loggedError.message).toContain('synthetic getXmlFragment failure');
  });

  test('pool.recycle on a bridge-setup-failed entry replaces it with a fresh provider', () => {
    pool = new ProviderPool(3, DUMMY_WS);

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    entry.provider.document.getXmlFragment = () => {
      throw new Error('synthetic init failure');
    };
    const errorSpy = vi.fn(() => {});
    const origError = console.error;
    console.error = errorSpy;
    entry.provider.emit('synced', { state: true });
    console.error = origError;

    expect(pool.entries.get('doc1')?.bridgeSetupFailed).toBe(true);
    const brokenProvider = entry.provider;

    pool.recycle('doc1');

    expect(pool.has('doc1')).toBe(true);
    expect(pool.getActiveDocName()).toBe('doc1');
    const newEntry = pool.entries.get('doc1');
    expect(newEntry).toBeDefined();
    expect(newEntry?.provider).not.toBe(brokenProvider);
    expect(newEntry?.bridgeSetupFailed).toBe(false);
  });

  test('contentless background doc disconnect triggers debounced destroy without re-open', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 50 });
    let onChangeCalls = 0;
    pool.setOnChange(() => onChangeCalls++);

    const entry1 = pool.open('doc1');
    if (!entry1) throw new Error('expected entry1');
    pool.setActive('doc1');
    const entry2 = pool.open('doc2');
    if (!entry2) throw new Error('expected entry2');
    onChangeCalls = 0;

    entry2.provider.emit('synced', { state: true });
    entry2.provider.unsyncedChanges = 0;

    entry2.provider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });

    expect(entry2.pendingRecycleTimer).not.toBeNull();
    expect(pool.has('doc2')).toBe(true);

    await wait(100);

    expect(pool.has('doc2')).toBe(false);

    expect(pool.has('doc1')).toBe(true);
    expect(pool.getActiveDocName()).toBe('doc1');
    expect(pool.getActive()?.provider).toBe(entry1.provider);

    expect(pool.entries.size).toBe(1);

    expect(onChangeCalls).toBeGreaterThanOrEqual(1);
  });

  test('recycle debounce is cancelled when provider reconnects (onSynced)', () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 200 });
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    entry.observerCleanup = () => {};

    entry.hasSynced = true;
    entry.syncState = 'synced';
    entry.provider.unsyncedChanges = 0;

    entry.provider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });
    expect(entry.pendingRecycleTimer).not.toBeNull();
    const _originalTimer = entry.pendingRecycleTimer;

    entry.provider.emit('synced', { state: true });
    expect(entry.pendingRecycleTimer).toBeNull();

    expect(pool.has('doc1')).toBe(true);
    expect(pool.getActive()?.provider).toBe(entry.provider);
    expect(entry.syncState).toBe('synced');
  });
});

describe('ProviderPool prewarm (V2 SPEC FR12 / Option G)', () => {
  test('prewarm admits a cold doc and returns its entry', () => {
    const pool = new ProviderPool(10, 'ws://localhost:9999');
    const entry = pool.prewarm('prewarm-doc');
    expect(entry).not.toBeNull();
    expect(pool.has('prewarm-doc')).toBe(true);
    pool.dispose();
  });

  test('prewarm places new entry at LRU-oldest — it is the first evicted', () => {
    const pool = new ProviderPool(3, 'ws://localhost:9999');
    pool.open('user-a');
    pool.open('user-b');
    pool.setActive('user-b');

    pool.prewarm('prewarm-c');
    expect(pool.has('prewarm-c')).toBe(true);

    pool.open('user-d');
    expect(pool.has('prewarm-c')).toBe(false);
    expect(pool.has('user-a')).toBe(true);
    expect(pool.has('user-b')).toBe(true);
    expect(pool.has('user-d')).toBe(true);
    pool.dispose();
  });

  test('prewarm is idempotent — re-prewarming an existing doc returns same entry', () => {
    const pool = new ProviderPool(10, 'ws://localhost:9999');
    const first = pool.prewarm('idempotent-doc');
    const second = pool.prewarm('idempotent-doc');
    expect(second).toBe(first);
    pool.dispose();
  });

  test('prewarm rejects system docs (__system__)', () => {
    const pool = new ProviderPool(10, 'ws://localhost:9999');
    const entry = pool.prewarm('__system__');
    expect(entry).toBeNull();
    expect(pool.has('__system__')).toBe(false);
    pool.dispose();
  });
});

describe('ProviderPool admission filter (__system__, DX7)', () => {
  test('open("__system__") returns null and does not add the pseudo-doc to the pool', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('__system__');
    expect(entry).toBeNull();
    expect(pool.has('__system__')).toBe(false);
    expect(pool.entries.size).toBe(0);
  });

  test('open("__system__") does not fire onChange notification', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let calls = 0;
    pool.setOnChange(() => calls++);
    pool.open('__system__');
    expect(calls).toBe(0);
  });

  test('non-system doc names are admitted normally', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('my-__system__-notes');
    expect(entry).not.toBeNull();
    expect(pool.has('my-__system__-notes')).toBe(true);
  });
});

describe('ProviderPool HocuspocusProvider configuration (D8)', () => {
  test('new providers receive forceSyncInterval: 5000', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(entry.provider.configuration.forceSyncInterval).toBe(5000);
  });
});

describe('buildAuthToken (MECHANISM-ONLY — CRDT restart recovery + client version)', () => {
  test('always returns a token carrying client version metadata, even anonymous', () => {
    const token = buildAuthToken(null, null);
    const parsed = parseHocuspocusAuthToken(token);
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.clientProtocolVersion).toBe(PROTOCOL_VERSION);
    expect(typeof parsed.clientRuntimeVersion).toBe('string');
    expect(parsed.clientKind).toBe('browser');
    expect(parsed.principalId).toBeUndefined();
    expect(parsed.expectedServerInstanceId).toBeUndefined();
  });

  test('includes expectedServerInstanceId when the cache is set', () => {
    const tabId = { principalId: 'p-1', tabSessionId: 's-1' };
    const parsed = parseHocuspocusAuthToken(buildAuthToken(tabId, 'server-instance-abc'));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.principalId).toBe('p-1');
    expect(parsed.tabSessionId).toBe('s-1');
    expect(parsed.expectedServerInstanceId).toBe('server-instance-abc');
    expect(parsed.clientKind).toBe('browser');
  });

  test('omits expectedServerInstanceId when the cache is null', () => {
    const tabId = { principalId: 'p-1', tabSessionId: 's-1' };
    const parsed = parseHocuspocusAuthToken(buildAuthToken(tabId, null));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBeUndefined();
    expect(parsed.principalId).toBe('p-1');
    expect(parsed.tabSessionId).toBe('s-1');
  });

  test('empty-string instance ID is treated as absent (not claimed)', () => {
    const tabId = { principalId: 'p-1', tabSessionId: 's-1' };
    const parsed = parseHocuspocusAuthToken(buildAuthToken(tabId, ''));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBeUndefined();
  });

  test('instance-ID-only claim (no tab identity) still serializes cleanly', () => {
    const parsed = parseHocuspocusAuthToken(buildAuthToken(null, 'server-instance-abc'));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBe('server-instance-abc');
    expect(parsed.principalId).toBeUndefined();
    expect(parsed.tabSessionId).toBeUndefined();
  });

  test('includes expectedBranch when supplied', () => {
    const parsed = parseHocuspocusAuthToken(buildAuthToken(null, null, 'feature'));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedBranch).toBe('feature');
  });

  test('omits expectedBranch when null or empty', () => {
    const tabId = { principalId: 'p-1', tabSessionId: 's-1' };
    expect(
      parseHocuspocusAuthToken(buildAuthToken(tabId, 'sid-x', null))?.expectedBranch,
    ).toBeUndefined();
    expect(
      parseHocuspocusAuthToken(buildAuthToken(tabId, 'sid-x', ''))?.expectedBranch,
    ).toBeUndefined();
  });

  test('includes expectedDocLineageEpoch when supplied', () => {
    const parsed = parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, 'epoch-1'));
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedDocLineageEpoch).toBe('epoch-1');
  });

  test('omits expectedDocLineageEpoch when null or empty', () => {
    expect(
      parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, null))?.expectedDocLineageEpoch,
    ).toBeUndefined();
    expect(
      parseHocuspocusAuthToken(buildAuthToken(null, 'sid-x', null, ''))?.expectedDocLineageEpoch,
    ).toBeUndefined();
  });
});

describe('ProviderPool server-instance-ID claim (US-001)', () => {
  test('token serialized on open() reflects setExpectedServerInstanceId', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setTabIdentity({ principalId: 'p-1', tabSessionId: 's-1' });
    pool.setExpectedServerInstanceId('server-instance-xyz');

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const resolved = entry.provider.configuration.token as unknown;
    expect(typeof resolved).toBe('string');
    const parsed = parseHocuspocusAuthToken(resolved as string);
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBe('server-instance-xyz');
    expect(parsed.principalId).toBe('p-1');
    expect(parsed.tabSessionId).toBe('s-1');
  });

  test('token omits expectedServerInstanceId when the cache is null', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setTabIdentity({ principalId: 'p-1', tabSessionId: 's-1' });

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const resolved = entry.provider.configuration.token as unknown;
    expect(typeof resolved).toBe('string');
    const parsed = parseHocuspocusAuthToken(resolved as string);
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBeUndefined();
  });

  test('setExpectedServerInstanceId(null) clears a previously-set cache', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setTabIdentity({ principalId: 'p-1', tabSessionId: 's-1' });
    pool.setExpectedServerInstanceId('server-instance-xyz');
    pool.setExpectedServerInstanceId(null);

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const resolved = entry.provider.configuration.token as unknown;
    const parsed = parseHocuspocusAuthToken(resolved as string);
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedServerInstanceId).toBeUndefined();
  });

  test('token serialized on open() reflects setObservedBranch', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setTabIdentity({ principalId: 'p-1', tabSessionId: 's-1' });
    pool.setObservedBranch('feature');

    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
    if (!parsed) throw new Error('expected valid token');
    expect(parsed.expectedBranch).toBe('feature');
  });

  test('branch-mismatch authenticationFailed invokes onBranchMismatch', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let called = 0;
    pool.setOnBranchMismatch(() => {
      called++;
    });
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    (entry.provider as unknown as { emit: (e: string, p: unknown) => void }).emit(
      'authenticationFailed',
      { reason: 'branch-mismatch' },
    );
    await Promise.resolve();
    expect(called).toBe(1);
  });

  test('branch-mismatch with no handler set is a clean no-op', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(() => {
      (entry.provider as unknown as { emit: (e: string, p: unknown) => void }).emit(
        'authenticationFailed',
        { reason: 'branch-mismatch' },
      );
    }).not.toThrow();
  });

  test('concurrent branch-mismatch rejections collapse to a single in-flight callback', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let pending: (() => void) | null = null;
    let called = 0;
    pool.setOnBranchMismatch(
      () =>
        new Promise<void>((resolve) => {
          called++;
          pending = () => resolve();
        }),
    );
    const e1 = pool.open('doc1');
    const e2 = pool.open('doc2');
    if (!e1 || !e2) throw new Error('expected entries');

    const emit = (entry: typeof e1) => {
      (entry.provider as unknown as { emit: (e: string, p: unknown) => void }).emit(
        'authenticationFailed',
        { reason: 'branch-mismatch' },
      );
    };
    emit(e1);
    emit(e2);
    await Promise.resolve();

    expect(called).toBe(1);

    if (pending !== null) (pending as () => void)();
    await wait(0);
    emit(e1);
    await Promise.resolve();
    expect(called).toBe(2);
  });

  test('cross-turn branch-mismatch holds the gate while the callback promise is pending', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let resolveWork: (() => void) | null = null;
    let called = 0;
    pool.setOnBranchMismatch(
      () =>
        new Promise<void>((resolve) => {
          called++;
          resolveWork = () => resolve();
        }),
    );
    const e1 = pool.open('doc1');
    const e2 = pool.open('doc2');
    if (!e1 || !e2) throw new Error('expected entries');
    const emit = (entry: typeof e1) => {
      (entry.provider as unknown as { emit: (e: string, p: unknown) => void }).emit(
        'authenticationFailed',
        { reason: 'branch-mismatch' },
      );
    };
    emit(e1);
    await Promise.resolve();
    await Promise.resolve();
    emit(e2);
    await Promise.resolve();
    expect(called).toBe(1);
    if (resolveWork !== null) (resolveWork as () => void)();
    await wait(0);
  });

  describe('observed-branch localStorage persistence', () => {
    function makeStubStorage(): {
      stub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
      store: Map<string, string>;
    } {
      const store = new Map<string, string>();
      const stub = {
        getItem: (k: string) => store.get(k) ?? null,
        setItem: (k: string, v: string) => {
          store.set(k, v);
        },
        removeItem: (k: string) => {
          store.delete(k);
        },
      };
      return { stub, store };
    }

    test('setObservedBranch writes the value to storage', () => {
      const { stub, store } = makeStubStorage();
      pool = new ProviderPool(3, DUMMY_WS, { storage: stub });
      pool.setObservedBranch('feature');
      expect(store.get('ok-last-observed-branch')).toBe('feature');
    });

    test('cold pool with pre-seeded storage value claims that branch on first open()', () => {
      const { stub, store } = makeStubStorage();
      store.set('ok-last-observed-branch', 'main');
      pool = new ProviderPool(3, DUMMY_WS, { storage: stub });
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedBranch).toBe('main');
    });

    test('setObservedBranch with empty string clears the storage key', () => {
      const { stub, store } = makeStubStorage();
      store.set('ok-last-observed-branch', 'feature');
      pool = new ProviderPool(3, DUMMY_WS, { storage: stub });
      pool.setObservedBranch('');
      expect(store.has('ok-last-observed-branch')).toBe(false);
    });

    test('storage.setItem throw is non-fatal — in-memory cache still updates', () => {
      const throwingStub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> = {
        getItem: () => null,
        setItem: () => {
          throw new Error('synthetic quota error');
        },
        removeItem: () => {},
      };
      pool = new ProviderPool(3, DUMMY_WS, { storage: throwingStub });
      pool.setObservedBranch('feature');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedBranch).toBe('feature');
    });

    test('null storage (default in Node tests) — pool runs without persistence', () => {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setObservedBranch('feature');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedBranch).toBe('feature');
    });
  });

  describe('server-instance-id auth-claim derivation', () => {
    test('open() carries the live server id as the auth-token claim', () => {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('server-current');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedServerInstanceId).toBe('server-current');
    });

    test('mismatch clears the cached id; next open() carries no claim', async () => {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');
      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await pool.awaitMismatchSettled();

      const next = pool.open('doc2');
      if (!next) throw new Error('expected next entry');
      const parsed = parseHocuspocusAuthToken(next.provider.configuration.token as string);
      expect(parsed?.expectedServerInstanceId).toBeUndefined();
    });

    test('null storage — pool runs without persistence', () => {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-instance-abc');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedServerInstanceId).toBe('server-instance-abc');
    });
  });

  test('setExpectedServerInstanceId affects future opens, not existing providers', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setTabIdentity({ principalId: 'p-1', tabSessionId: 's-1' });

    const entry1 = pool.open('doc1');
    if (!entry1) throw new Error('expected entry1');

    pool.setExpectedServerInstanceId('server-instance-xyz');

    const entry2 = pool.open('doc2');
    if (!entry2) throw new Error('expected entry2');

    const tok1 = parseHocuspocusAuthToken(entry1.provider.configuration.token as string);
    const tok2 = parseHocuspocusAuthToken(entry2.provider.configuration.token as string);
    if (!tok1 || !tok2) throw new Error('expected valid tokens');
    expect(tok1.expectedServerInstanceId).toBeUndefined();
    expect(tok2.expectedServerInstanceId).toBe('server-instance-xyz');
  });
});

describe('cross-project storage-key isolation', () => {
  function makeStubStorage(): {
    stub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
    store: Map<string, string>;
  } {
    const store = new Map<string, string>();
    const stub = {
      getItem: (k: string) => store.get(k) ?? null,
      setItem: (k: string, v: string) => {
        store.set(k, v);
      },
      removeItem: (k: string) => {
        store.delete(k);
      },
    };
    return { stub, store };
  }

  test("a sibling project's persisted branch does not become this pool's claim", () => {
    const { stub } = makeStubStorage();
    const poolA = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      storageNamespace: '/Users/dev/code/project-a',
    });
    try {
      poolA.setObservedBranch('main');

      const poolB = new ProviderPool(3, DUMMY_WS, {
        storage: stub,
        storageNamespace: '/Users/dev/code/project-b',
      });
      try {
        const entry = poolB.open('doc1');
        if (!entry) throw new Error('expected entry');
        const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
        if (!parsed) throw new Error('expected valid token');
        expect(parsed.expectedBranch).toBeUndefined();
      } finally {
        poolB.dispose();
      }
    } finally {
      poolA.dispose();
    }
  });

  test('an empty namespace is scoped, not treated as a web host', () => {
    const { stub, store } = makeStubStorage();
    const projectless = new ProviderPool(3, DUMMY_WS, { storage: stub, storageNamespace: '' });
    try {
      projectless.setObservedBranch('main');
      expect(store.has('ok-last-observed-branch')).toBe(false);
      expect(store.get('ok-last-observed-branch:811c9dc5')).toBe('main');
    } finally {
      projectless.dispose();
    }
  });

  test('a project still reads back its OWN branch across a cold boot', () => {
    const { stub } = makeStubStorage();
    const namespace = '/Users/dev/code/project-a';
    const first = new ProviderPool(3, DUMMY_WS, { storage: stub, storageNamespace: namespace });
    try {
      first.setObservedBranch('feature/example');
    } finally {
      first.dispose();
    }

    const second = new ProviderPool(3, DUMMY_WS, { storage: stub, storageNamespace: namespace });
    try {
      const entry = second.open('doc1');
      if (!entry) throw new Error('expected entry');
      const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
      if (!parsed) throw new Error('expected valid token');
      expect(parsed.expectedBranch).toBe('feature/example');
    } finally {
      second.dispose();
    }
  });
});

describe('ProviderPool doc-lineage epoch records', () => {
  const ENVELOPE_KEY = 'ok-doc-lineage-epochs';

  function makeStubStorage(): {
    stub: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
    store: Map<string, string>;
  } {
    const store = new Map<string, string>();
    const stub = {
      getItem: (k: string) => store.get(k) ?? null,
      setItem: (k: string, v: string) => {
        store.set(k, v);
      },
      removeItem: (k: string) => {
        store.delete(k);
      },
    };
    return { stub, store };
  }

  function makePersistenceStub(): ClientPersistenceProvider {
    return {
      whenSynced: Promise.resolve(undefined as never),
      synced: true,
      destroy: async () => {},
      clearData: async () => {},
      flushFullState: async () => {},
    } as unknown as ClientPersistenceProvider;
  }

  function makeEnvelope(
    serverInstanceId: string,
    epochs: Record<string, string>,
    branch = '_unknown_',
  ): string {
    return JSON.stringify({ branch, serverInstanceId, epochs });
  }

  function tokenOf(entry: { provider: { configuration: { token: unknown } } }) {
    const parsed = parseHocuspocusAuthToken(entry.provider.configuration.token as string);
    if (!parsed) throw new Error('expected valid token');
    return parsed;
  }

  test('open() claims the epoch recorded in a valid storage envelope', () => {
    const { stub, store } = makeStubStorage();
    store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }));
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(tokenOf(entry).expectedDocLineageEpoch).toBe('epoch-1');
  });

  test('claim is omitted while the server instance id is unknown', () => {
    const { stub, store } = makeStubStorage();
    store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }));
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
  });

  test('envelope from a different server instance is ignored', () => {
    const { stub, store } = makeStubStorage();
    store.set(ENVELOPE_KEY, makeEnvelope('dead-instance', { doc1: 'epoch-1' }));
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
  });

  test('envelope from a different branch scope is ignored', () => {
    const { stub, store } = makeStubStorage();
    store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { doc1: 'epoch-1' }, 'feature'));
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    expect(tokenOf(entry).expectedDocLineageEpoch).toBeUndefined();
  });

  test('synced lifecycle epoch is recorded and round-trips into a fresh pool', () => {
    const { stub, store } = makeStubStorage();
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-lineage-record');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');

    entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
    entry.provider.emit('synced', { state: true });

    const raw = store.get(ENVELOPE_KEY);
    if (raw === undefined) throw new Error('expected envelope written to storage');
    const envelope = JSON.parse(raw) as {
      branch: string;
      serverInstanceId: string;
      epochs: Record<string, string>;
    };
    expect(envelope.serverInstanceId).toBe(TEST_SERVER_INSTANCE_ID);
    expect(envelope.epochs[docName]).toBe('epoch-live');

    const pool2 = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    try {
      pool2.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const entry2 = pool2.open(docName);
      if (!entry2) throw new Error('expected entry2');
      expect(tokenOf(entry2).expectedDocLineageEpoch).toBe('epoch-live');
    } finally {
      pool2.dispose();
    }
  });

  test('doc-lineage-mismatch rejection drops the record and reopens claim-less', async () => {
    const { stub, store } = makeStubStorage();
    const docName = uniqueDocName('pp-lineage-reject');
    store.set(ENVELOPE_KEY, makeEnvelope(TEST_SERVER_INSTANCE_ID, { [docName]: 'epoch-dead' }));
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    pool.setActive(docName);
    expect(tokenOf(entry).expectedDocLineageEpoch).toBe('epoch-dead');

    const warnSpy = vi.fn(() => {});
    const origWarn = console.warn;
    console.warn = warnSpy;
    entry.provider.emit('authenticationFailed', { reason: 'doc-lineage-mismatch' });
    console.warn = origWarn;

    const reopened = pool.peek(docName);
    if (!reopened) throw new Error('expected reopened entry');
    expect(reopened).not.toBe(entry);
    expect(pool.getActiveDocName()).toBe(docName);
    expect(tokenOf(reopened).expectedDocLineageEpoch).toBeUndefined();

    const raw = store.get(ENVELOPE_KEY);
    if (raw === undefined) throw new Error('expected envelope still present');
    const envelope = JSON.parse(raw) as { epochs: Record<string, string> };
    expect(envelope.epochs[docName]).toBeUndefined();

    const emitted = warnSpy.mock.calls
      .map((call) => call[0] as string)
      .filter((line) => typeof line === 'string' && line.includes('ok-doc-lineage-mismatch'));
    expect(emitted.length).toBe(1);
    const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
    expect(event.via).toBe('auth-rejection');
    expect(event.staleEpoch).toBe('epoch-dead');

    await wait(10);
  });

  test('deferred-attach guard replaces a stale-lineage entry instead of hydrating it', async () => {
    const { stub } = makeStubStorage();
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    const docName = uniqueDocName('pp-lineage-deferred');

    const first = pool.open(docName);
    if (!first) throw new Error('expected first entry');
    first.provider.document.getMap('lifecycle').set('epoch', 'epoch-dead');
    first.provider.emit('synced', { state: true });
    pool.close(docName);

    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.persistence).toBeNull();
    entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
    entry.provider.emit('synced', { state: true });

    const warnSpy = vi.fn(() => {});
    const origWarn = console.warn;
    console.warn = warnSpy;
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    console.warn = origWarn;

    const reopened = pool.peek(docName);
    if (!reopened) throw new Error('expected reopened entry');
    expect(reopened).not.toBe(entry);
    expect(tokenOf(reopened).expectedDocLineageEpoch).toBe('epoch-live');
    expect(reopened.lineageEpochRecordAtOpen).toBe('epoch-live');

    const emitted = warnSpy.mock.calls
      .map((call) => call[0] as string)
      .filter((line) => typeof line === 'string' && line.includes('ok-doc-lineage-mismatch'));
    expect(emitted.length).toBe(1);
    const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
    expect(event.via).toBe('deferred-attach');
    expect(event.staleEpoch).toBe('epoch-dead');
    expect(event.liveEpoch).toBe('epoch-live');

    await wait(10);
  });

  test('rename-redirect and doc-deleted rejections prune the lineage record', () => {
    const { stub, store } = makeStubStorage();
    const renamedDoc = uniqueDocName('pp-lineage-renamed');
    const deletedDoc = uniqueDocName('pp-lineage-deleted');
    store.set(
      ENVELOPE_KEY,
      makeEnvelope(TEST_SERVER_INSTANCE_ID, {
        [renamedDoc]: 'epoch-a',
        [deletedDoc]: 'epoch-b',
      }),
    );
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const renamedEntry = pool.open(renamedDoc);
    const deletedEntry = pool.open(deletedDoc);
    if (!renamedEntry || !deletedEntry) throw new Error('expected entries');

    renamedEntry.provider.emit('authenticationFailed', {
      reason: `rename-redirect:${renamedDoc}-new`,
    });
    deletedEntry.provider.emit('authenticationFailed', { reason: 'doc-deleted' });

    const raw = store.get(ENVELOPE_KEY);
    if (raw === undefined) throw new Error('expected envelope still present');
    const envelope = JSON.parse(raw) as { epochs: Record<string, string> };
    expect(envelope.epochs[renamedDoc]).toBeUndefined();
    expect(envelope.epochs[deletedDoc]).toBeUndefined();
  });

  test("a sibling project cannot read back this project's lineage envelope", () => {
    const { stub, store } = makeStubStorage();
    const docName = uniqueDocName('pp-lineage-cross-project');

    const projectA = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      storageNamespace: '/Users/dev/code/project-a',
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    try {
      projectA.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const entryA = projectA.open(docName);
      if (!entryA) throw new Error('expected entry');
      entryA.provider.document.getMap('lifecycle').set('epoch', 'epoch-project-a');
      entryA.provider.emit('synced', { state: true });
      expect(store.get(ENVELOPE_KEY)).toBeUndefined();
    } finally {
      projectA.dispose();
    }

    const projectB = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      storageNamespace: '/Users/dev/code/project-b',
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    try {
      projectB.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const entryB = projectB.open(docName);
      if (!entryB) throw new Error('expected entry');
      expect(tokenOf(entryB).expectedDocLineageEpoch).toBeUndefined();
    } finally {
      projectB.dispose();
    }

    const projectAAgain = new ProviderPool(3, DUMMY_WS, {
      storage: stub,
      storageNamespace: '/Users/dev/code/project-a',
      persistenceFactory: vi.fn(makePersistenceStub),
    });
    try {
      projectAAgain.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const entryA2 = projectAAgain.open(docName);
      if (!entryA2) throw new Error('expected entry');
      expect(tokenOf(entryA2).expectedDocLineageEpoch).toBe('epoch-project-a');
    } finally {
      projectAAgain.dispose();
    }
  });
});

describe('ProviderPool stored-state validation spine', () => {
  function makePersistenceStub(): ClientPersistenceProvider {
    return {
      whenSynced: Promise.resolve(undefined as never),
      synced: true,
      destroy: async () => {},
      clearData: async () => {},
      flushFullState: async () => {},
    } as unknown as ClientPersistenceProvider;
  }

  function captureWarns(): {
    lines: () => string[];
    restore: () => void;
    spy: ReturnType<typeof vi.spyOn>;
  } {
    const spy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    return {
      lines: () =>
        spy.mock.calls
          .map((call) => call[0])
          .filter((first): first is string => typeof first === 'string'),
      restore: () => spy.mockRestore(),
      spy,
    };
  }

  test('refuses stored rows whose in-band epoch differs from the live lineage', async () => {
    const warns = captureWarns();
    try {
      const peek = vi.fn(async () => 'epoch-dead');
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory: vi.fn(makePersistenceStub),
        peekStoredLineageEpoch: peek,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-refuse');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      pool.setActive(docName);
      expect(entry.persistence).toBeNull();

      entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
      entry.provider.emit('synced', { state: true });

      const replaced = await waitFor(
        () => pool.peek(docName) !== null && pool.peek(docName) !== entry,
        2_000,
      );
      expect(replaced).toBe(true);
      expect(pool.getActiveDocName()).toBe(docName);

      const emitted = warns.lines().filter((line) => line.includes('ok-doc-lineage-mismatch'));
      expect(emitted.length).toBe(1);
      const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
      expect(event.via).toBe('stored-state-validation');
      expect(event.staleEpoch).toBe('epoch-dead');
      expect(event.liveEpoch).toBe('epoch-live');
      expect(event.docName).toBe(docName);

      await wait(10);
    } finally {
      warns.restore();
    }
  });

  test('refuses stored epoch-bearing rows when the live doc carries no epoch post-sync', async () => {
    const warns = captureWarns();
    try {
      const peek = vi.fn(async () => 'epoch-dead');
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory: vi.fn(makePersistenceStub),
        peekStoredLineageEpoch: peek,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-live-absent');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');

      entry.provider.emit('synced', { state: true });

      const replaced = await waitFor(
        () => pool.peek(docName) !== null && pool.peek(docName) !== entry,
        2_000,
      );
      expect(replaced).toBe(true);

      const emitted = warns.lines().filter((line) => line.includes('ok-doc-lineage-mismatch'));
      expect(emitted.length).toBe(1);
      const event = JSON.parse(emitted[0] ?? '{}') as Record<string, string>;
      expect(event.via).toBe('stored-state-validation');
      expect(event.staleEpoch).toBe('epoch-dead');
      expect(event.liveEpoch).toBe('<absent>');

      await wait(10);
    } finally {
      warns.restore();
    }
  });

  test('attaches when the stored epoch matches the live lineage, then backfills the cache', async () => {
    const flushSpy = vi.fn(async () => {});
    const persistenceFactory = vi.fn(
      () =>
        ({
          whenSynced: Promise.resolve(undefined as never),
          synced: true,
          destroy: async () => {},
          clearData: async () => {},
          flushFullState: flushSpy,
        }) as unknown as ClientPersistenceProvider,
    );
    const peek = vi.fn(async () => 'epoch-live');
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: null,
      persistenceFactory,
      peekStoredLineageEpoch: peek,
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-spine-match');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
    entry.provider.emit('synced', { state: true });

    await awaitAttachedPersistence(entry);
    expect(persistenceFactory).toHaveBeenCalledTimes(1);
    const flushed = await waitFor(() => flushSpy.mock.calls.length === 1, 2_000);
    expect(flushed).toBe(true);
  });

  test('attaches immediately when the stored rows carry nothing to validate (null peek)', async () => {
    const persistenceFactory = vi.fn(makePersistenceStub);
    const peek = vi.fn(async () => null);
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: null,
      persistenceFactory,
      peekStoredLineageEpoch: peek,
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-spine-null');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');

    await awaitAttachedPersistence(entry);
    expect(entry.hasSynced).toBe(false);
    expect(persistenceFactory).toHaveBeenCalledTimes(1);
  });

  test('record-present entry that has not synced waits for sync before validating', async () => {
    const persistenceFactory = vi.fn(makePersistenceStub);
    const peek = vi.fn(async () => 'epoch-x');
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: null,
      persistenceFactory,
      peekStoredLineageEpoch: peek,
    });
    const docName = uniqueDocName('pp-spine-wait');

    const first = pool.open(docName);
    if (!first) throw new Error('expected first entry');
    first.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');
    first.provider.emit('synced', { state: true });
    pool.close(docName);

    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.lineageEpochRecordAtOpen).toBe('epoch-x');
    expect(entry.hasSynced).toBe(false);

    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);

    await wait(50);
    expect(entry.persistence).toBeNull();

    entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');
    entry.provider.emit('synced', { state: true });
    await awaitAttachedPersistence(entry);
    expect(persistenceFactory).toHaveBeenCalledTimes(1);
  });

  test('a record-present open that attaches eagerly still backfills the cache after its first sync', async () => {
    const flushSpy = vi.fn(async () => {});
    const persistenceFactory = vi.fn(
      () =>
        ({
          whenSynced: Promise.resolve(undefined as never),
          synced: true,
          destroy: async () => {},
          clearData: async () => {},
          flushFullState: flushSpy,
        }) as unknown as ClientPersistenceProvider,
    );
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: null,
      persistenceFactory,
      peekStoredLineageEpoch: async () => null,
    });
    const docName = uniqueDocName('pp-eager-backfill');

    const first = pool.open(docName);
    if (!first) throw new Error('expected first entry');
    first.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');
    first.provider.emit('synced', { state: true });
    pool.close(docName);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);

    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.lineageEpochRecordAtOpen).toBe('epoch-x');
    expect(entry.persistence).not.toBeNull();
    expect(persistenceFactory).toHaveBeenCalledTimes(1);

    await wait(20);
    expect(flushSpy).not.toHaveBeenCalled();
    entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-x');
    entry.provider.emit('synced', { state: true });
    const flushed = await waitFor(() => flushSpy.mock.calls.length === 1, 2_000);
    expect(flushed).toBe(true);
  });

  test('a re-dispatch onto an entry with an in-flight spine run is a no-op (attach ownership)', async () => {
    let resolvePeek: (value: string | null) => void = () => {};
    const peek = vi.fn(() => {
      const { promise, resolve } = Promise.withResolvers<string | null>();
      resolvePeek = resolve;
      return promise;
    });
    const persistenceFactory = vi.fn(makePersistenceStub);
    pool = new ProviderPool(3, DUMMY_WS, {
      storage: null,
      persistenceFactory,
      peekStoredLineageEpoch: peek,
    });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-spine-own');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(peek).toHaveBeenCalledTimes(1);

    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    expect(peek).toHaveBeenCalledTimes(1);

    resolvePeek(null);
    await awaitAttachedPersistence(entry);
    expect(persistenceFactory).toHaveBeenCalledTimes(1);
  });

  test('a rejecting peek leaves the entry cacheless and emits the attach-failed arm', async () => {
    const warns = captureWarns();
    try {
      const persistenceFactory = vi.fn(makePersistenceStub);
      const peek = vi.fn(async (): Promise<string | null> => {
        throw new Error('idb exploded');
      });
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory,
        peekStoredLineageEpoch: peek,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-peek-reject');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');

      const emitted = await waitFor(
        () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),
        2_000,
      );
      expect(emitted).toBe(true);
      const lines = warns
        .lines()
        .filter((line) => line.includes('ok-client-persistence-attach-failed'));
      expect(lines.length).toBe(1);
      const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;
      expect(event.docName).toBe(docName);
      expect(event.phase).toBe('peek');
      expect(event.errorMessage).toBe('idb exploded');
      expect(entry.persistence).toBeNull();
      expect(persistenceFactory).not.toHaveBeenCalled();
    } finally {
      warns.restore();
    }
  });

  test('a wedged peek decays into the attach-failed arm after the timeout', async () => {
    const warns = captureWarns();
    try {
      const persistenceFactory = vi.fn(makePersistenceStub);
      const peek = vi.fn(() => new Promise<string | null>(() => {}));
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory,
        peekStoredLineageEpoch: peek,
        clearDataTimeoutMs: 20,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-peek-wedge');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');

      const emitted = await waitFor(
        () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),
        2_000,
      );
      expect(emitted).toBe(true);
      const lines = warns
        .lines()
        .filter((line) => line.includes('ok-client-persistence-attach-failed'));
      const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;
      expect(event.docName).toBe(docName);
      expect(event.phase).toBe('peek');
      expect(event.errorName).toBe('StoredEpochPeekTimeoutError');
      expect(entry.persistence).toBeNull();
      expect(persistenceFactory).not.toHaveBeenCalled();
    } finally {
      warns.restore();
    }
  });

  test('a throwing factory on the matched-epoch arm emits attach-failed and leaves the entry cacheless', async () => {
    const warns = captureWarns();
    try {
      const peek = vi.fn(async () => 'epoch-live');
      const persistenceFactory = vi.fn((): ClientPersistenceProvider => {
        throw new Error('factory exploded');
      });
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory,
        peekStoredLineageEpoch: peek,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-factory-throw');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      entry.provider.document.getMap('lifecycle').set('epoch', 'epoch-live');
      entry.provider.emit('synced', { state: true });

      const emitted = await waitFor(
        () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),
        2_000,
      );
      expect(emitted).toBe(true);
      const lines = warns
        .lines()
        .filter((line) => line.includes('ok-client-persistence-attach-failed'));
      const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;
      expect(event.docName).toBe(docName);
      expect(event.phase).toBe('attach');
      expect(event.errorMessage).toBe('factory exploded');
      expect(entry.persistence).toBeNull();
    } finally {
      warns.restore();
    }
  });

  test('a failing backfill emits the structured attach-failed event with phase backfill', async () => {
    const warns = captureWarns();
    try {
      const persistenceFactory = vi.fn(
        () =>
          ({
            whenSynced: Promise.resolve(undefined as never),
            synced: true,
            destroy: async () => {},
            clearData: async () => {},
            flushFullState: async () => {
              throw new Error('backfill exploded');
            },
          }) as unknown as ClientPersistenceProvider,
      );
      const peek = vi.fn(async () => null);
      pool = new ProviderPool(3, DUMMY_WS, {
        storage: null,
        persistenceFactory,
        peekStoredLineageEpoch: peek,
      });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-spine-backfill-fail');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      await awaitAttachedPersistence(entry);
      entry.provider.emit('synced', { state: true });

      const emitted = await waitFor(
        () => warns.lines().some((line) => line.includes('ok-client-persistence-attach-failed')),
        2_000,
      );
      expect(emitted).toBe(true);
      const lines = warns
        .lines()
        .filter((line) => line.includes('ok-client-persistence-attach-failed'));
      const event = JSON.parse(lines[0] ?? '{}') as Record<string, string>;
      expect(event.docName).toBe(docName);
      expect(event.phase).toBe('backfill');
      expect(event.errorMessage).toBe('backfill exploded');
      expect(entry.persistence).not.toBeNull();
    } finally {
      warns.restore();
    }
  });
});

describe("ProviderPool authenticationFailed handling (US-002 / 'server-instance-mismatch')", () => {
  test("reason 'server-instance-mismatch' recycles every pool entry", async () => {
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
    pool.setExpectedServerInstanceId('server-old');

    const e1 = pool.open('doc1');
    const e2 = pool.open('doc2');
    const e3 = pool.open('doc3');
    if (!e1 || !e2 || !e3) throw new Error('expected entries');
    pool.setActive('doc1');
    const originalProvider = e1.provider;

    e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    await pool.awaitMismatchSettled();

    expect(pool.has('doc1')).toBe(true);
    expect(pool.has('doc2')).toBe(false);
    expect(pool.has('doc3')).toBe(false);
    const postE1 = pool.entries.get('doc1');
    expect(postE1?.provider).not.toBe(originalProvider);
    expect(pool.getActiveDocName()).toBe('doc1');
  });

  test("reason 'server-instance-mismatch' clears the stale current instance claim", async () => {
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
    pool.setExpectedServerInstanceId('server-old');
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });

    const claimCleared = await waitFor(() => {
      const replaced = pool.entries.get('doc1');
      if (!replaced || replaced === entry) return false;
      const resolved = replaced.provider.configuration.token;
      if (typeof resolved !== 'string') return true;
      const parsed = parseHocuspocusAuthToken(resolved);
      return parsed?.expectedServerInstanceId === undefined;
    });
    expect(claimCleared).toBe(true);
    const replaced = pool.entries.get('doc1');
    if (!replaced) throw new Error('expected replaced entry');
    const resolved = replaced.provider.configuration.token;
    if (typeof resolved === 'string') {
      const parsed = parseHocuspocusAuthToken(resolved);
      expect(parsed?.expectedServerInstanceId).toBeUndefined();
    }
  });

  test('other reasons do not trigger recycle', () => {
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
    pool.setExpectedServerInstanceId('server-old');
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');
    const originalProvider = entry.provider;

    entry.provider.emit('authenticationFailed', { reason: 'permission-denied' });

    expect(pool.getActive()?.provider).toBe(originalProvider);
    const resolved = originalProvider.configuration.token as unknown;
    expect(resolved).toBeDefined();
  });

  test('second mismatch event is a no-op after cache is cleared (idempotence)', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      pool.setObservedBranch('telemetry-branch-idem');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      const firstRecycled = await waitFor(() => {
        const postFirstEntry = pool.entries.get('doc1');
        return postFirstEntry !== undefined && postFirstEntry.provider !== entry.provider;
      });
      expect(firstRecycled).toBe(true);
      const postFirstEntry = pool.entries.get('doc1');
      if (!postFirstEntry) throw new Error('expected post-first entry');
      const postFirstProvider = postFirstEntry.provider;

      const epochSignals = warnSpy.mock.calls.filter(([first]) => {
        if (typeof first !== 'string') return false;
        try {
          return JSON.parse(first).event === 'ok-client-cache-epoch-mismatch';
        } catch {
          return false;
        }
      });
      expect(epochSignals.length).toBe(1);

      postFirstProvider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(0);
      const epochAfterSecond = warnSpy.mock.calls.filter(([first]) => {
        if (typeof first !== 'string') return false;
        try {
          return JSON.parse(first).event === 'ok-client-cache-epoch-mismatch';
        } catch {
          return false;
        }
      });
      expect(epochAfterSecond.length).toBe(1);

      const postSecond = pool.entries.get('doc1');
      expect(postSecond?.provider).toBe(postFirstProvider);
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('server-instance-mismatch exposes recovery state and clears it after fresh sync', async () => {
    __resetSyncPromiseCache();
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
    pool.setExpectedServerInstanceId('server-old');
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const persistence = await awaitAttachedPersistence(entry);
    pool.setActive('doc1');

    let resolveClear: () => void = () => {};
    persistence.clearData = vi.fn(() => {
      const { promise, resolve } = Promise.withResolvers<void>();
      resolveClear = resolve;
      return promise;
    });

    syncPromise('doc1', entry.provider).catch(() => {});
    expect(__syncPromiseCacheSize()).toBe(1);

    entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });

    expect(__syncPromiseCacheSize()).toBe(0);
    expect(pool.getServerRestartRecoveryState()).toMatchObject({
      kind: 'recovering',
      phase: 'clearing-local-cache',
      docNames: ['doc1'],
    });

    resolveClear();
    await wait(50);

    expect(pool.getServerRestartRecoveryState()).toMatchObject({
      kind: 'recovering',
      phase: 'reconnecting',
      docNames: ['doc1'],
    });

    const replacement = pool.getActive();
    if (!replacement) throw new Error('expected replacement');
    replacement.observerCleanup = () => {};
    replacement.provider.emit('synced', { state: true });

    expect(pool.getServerRestartRecoveryState()).toEqual({ kind: 'idle' });
    __resetSyncPromiseCache();
  });

  test('active doc clearData failure exposes targeted recovery failure state', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('server-old');
      pool.setObservedBranch('clear-fail-branch');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const persistence = await awaitAttachedPersistence(entry);
      pool.setActive('doc1');
      const originalProvider = entry.provider;
      persistence.clearData = vi.fn(() => Promise.reject(new Error('idb blocked')));

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(50);

      expect(pool.getActive()?.provider).toBe(originalProvider);
      expect(pool.getServerRestartRecoveryState()).toMatchObject({
        kind: 'failed',
        reason: 'clear-data-failed',
        docNames: ['doc1'],
        failedDocNames: ['doc1'],
      });

      const clearFailed = warnSpy.mock.calls
        .map((c) => c[0])
        .filter((first): first is string => typeof first === 'string')
        .filter((first) => {
          try {
            return JSON.parse(first).event === 'ok-client-cache-clear-failed';
          } catch {
            return false;
          }
        });
      expect(clearFailed.length).toBe(1);
      const payload = JSON.parse(clearFailed[0] ?? '{}') as {
        event: string;
        docName: string;
        branch: string;
        serverInstanceId?: string;
        failureKind: string;
        errorName?: string;
        errorMessage?: string;
      };
      expect(payload.docName).toBe('doc1');
      expect(payload.branch).toBe('clear-fail-branch');
      expect(payload.serverInstanceId).toBe('server-old');
      expect(payload.failureKind).toBe('rejected');
      expect(payload.errorName).toBe('Error');
      expect(payload.errorMessage).toBe('idb blocked');
      expect(Object.keys(payload).every((k) => !['message', 'stack', 'reason'].includes(k))).toBe(
        true,
      );
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('active doc clearData timeout exposes targeted timeout state', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { clearDataTimeoutMs: 5 });
      pool.setExpectedServerInstanceId('server-old');
      pool.setObservedBranch('timeout-branch');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      const persistence = await awaitAttachedPersistence(entry);
      pool.setActive('doc1');
      persistence.clearData = vi.fn(() => new Promise<void>(() => {}));

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(30);

      expect(pool.getServerRestartRecoveryState()).toMatchObject({
        kind: 'failed',
        reason: 'clear-data-timeout',
        docNames: ['doc1'],
        failedDocNames: ['doc1'],
      });

      const clearFailed = warnSpy.mock.calls
        .map((c) => c[0])
        .filter((first): first is string => typeof first === 'string')
        .filter((first) => {
          try {
            return JSON.parse(first).event === 'ok-client-cache-clear-failed';
          } catch {
            return false;
          }
        });
      expect(clearFailed.length).toBe(1);
      const payload = JSON.parse(clearFailed[0] ?? '{}') as { failureKind: string };
      expect(payload.failureKind).toBe('timeout');
    } finally {
      warnSpy.mockRestore();
    }
  });
});

describe('ProviderPool epoch-transition observation', () => {
  function countRecycles(infoSpy: ReturnType<typeof vi.spyOn>): number {
    return infoSpy.mock.calls.filter(([first]) => {
      if (typeof first !== 'string') return false;
      try {
        return (JSON.parse(first) as { event?: string }).event === 'ok-pool-mismatch-recycle-begin';
      } catch {
        return false;
      }
    }).length;
  }

  test('observing a rotated epoch over HTTP recycles the pool', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');
      const originalProvider = entry.provider;

      pool.setExpectedServerInstanceId('server-new');
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(1);
      expect(pool.entries.get('doc1')?.provider).not.toBe(originalProvider);
      expect(await pool.whenServerInstanceKnown()).toBe('server-new');
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('a stale claim rejected after the refresh landed the new epoch still recycles exactly once', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');
      const originalProvider = entry.provider;

      pool.setExpectedServerInstanceId('server-new');
      originalProvider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(1);
      expect(pool.entries.get('doc1')?.provider).not.toBe(originalProvider);
      expect(await pool.whenServerInstanceKnown()).toBe('server-new');
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('a stale claim rejected before the refresh lands still recycles exactly once', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      pool.setExpectedServerInstanceId('server-new');
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(1);
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('re-observing the same epoch is a no-op', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');
      const originalProvider = entry.provider;

      pool.setExpectedServerInstanceId('server-old');
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(0);
      expect(pool.entries.get('doc1')?.provider).toBe(originalProvider);
      expect(await pool.whenServerInstanceKnown()).toBe('server-old');
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('the first epoch observed after boot is adopted without a recycle', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');
      const originalProvider = entry.provider;

      pool.setExpectedServerInstanceId('server-first');
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(0);
      expect(pool.entries.get('doc1')?.provider).toBe(originalProvider);
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('an epoch re-observed after a recycle is adopted without a second recycle', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-old');
      const entry = pool.open('doc1');
      if (!entry) throw new Error('expected entry');
      pool.setActive('doc1');

      pool.setExpectedServerInstanceId('server-new');
      await pool.awaitMismatchSettled();
      pool.setExpectedServerInstanceId('server-new');
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy)).toBe(1);
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('two providers holding distinct stale claims collapse into one recycle', async () => {
    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS, { storage: null });
      pool.setExpectedServerInstanceId('server-a');
      const e1 = pool.open('doc1');
      if (!e1) throw new Error('expected entry');
      pool.setActive('doc1');
      pool.setExpectedServerInstanceId(null);
      pool.setExpectedServerInstanceId('server-b');
      const e2 = pool.open('doc2');
      if (!e2) throw new Error('expected entry');

      const recyclesBefore = countRecycles(infoSpy);
      e2.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      expect(pool.isMismatchRecycleInFlight()).toBe(true);
      e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await pool.awaitMismatchSettled();

      expect(countRecycles(infoSpy) - recyclesBefore).toBe(1);
      const collapsed = infoSpy.mock.calls.filter(([first]) => {
        if (typeof first !== 'string') return false;
        try {
          const parsed = JSON.parse(first) as { event?: string; reason?: string };
          return (
            parsed.event === 'ok-pool-mismatch-transition-deduped' &&
            parsed.reason === 'recycle-in-flight'
          );
        } catch {
          return false;
        }
      });
      expect(collapsed.length).toBe(1);
      const collapsedFields = JSON.parse(String(collapsed[0]?.[0])) as {
        staleClaim?: string;
        inflightForClaim?: string;
      };
      expect(collapsedFields.staleClaim).toBe('server-a');
      expect(collapsedFields.inflightForClaim).toBe('server-b');
    } finally {
      infoSpy.mockRestore();
    }
  });

  test('a disposed pool no longer reports a recycle in flight', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
    pool.setExpectedServerInstanceId('server-old');
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');

    entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    expect(pool.isMismatchRecycleInFlight()).toBe(true);
    pool.dispose();

    expect(pool.isMismatchRecycleInFlight()).toBe(false);
    pool = new ProviderPool(3, DUMMY_WS, { storage: null });
  });
});

describe('ProviderPool syncPromise lifecycle integration (F15)', () => {
  beforeEach(() => {
    __resetSyncPromiseCache();
  });

  afterEach(() => {
    __resetSyncPromiseCache();
  });

  test('close(docName) invalidates the cached syncPromise', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const p = syncPromise('doc1', entry.provider);
    p.catch(() => {});
    expect(__syncPromiseCacheSize()).toBe(1);

    pool.close('doc1');

    expect(__syncPromiseCacheSize()).toBe(0);
  });

  test('LRU eviction invalidates the cached syncPromise of the evicted doc', () => {
    pool = new ProviderPool(2, DUMMY_WS);
    const e1 = pool.open('doc1');
    if (!e1) throw new Error('expected e1');
    pool.setActive('doc1');
    const e2 = pool.open('doc2');
    if (!e2) throw new Error('expected e2');

    syncPromise('doc1', e1.provider).catch(() => {});
    syncPromise('doc2', e2.provider).catch(() => {});
    expect(__syncPromiseCacheSize()).toBe(2);

    const e3 = pool.open('doc3');
    if (!e3) throw new Error('expected e3');

    expect(pool.has('doc2')).toBe(false);
    expect(__syncPromiseCacheSize()).toBe(1);
  });

  test('contentless recycle after disconnect invalidates the cached syncPromise', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 50 });
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc1');
    entry.observerCleanup = () => {};

    entry.hasSynced = true;
    entry.syncState = 'synced';
    entry.provider.unsyncedChanges = 0;

    syncPromise('doc1', entry.provider).catch(() => {});
    expect(__syncPromiseCacheSize()).toBe(1);

    entry.provider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });

    await wait(100);

    expect(__syncPromiseCacheSize()).toBe(0);
  });

  test('dispose() invalidates all cached syncPromises', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const e1 = pool.open('doc1');
    const e2 = pool.open('doc2');
    if (!e1 || !e2) throw new Error('expected entries');
    syncPromise('doc1', e1.provider).catch(() => {});
    syncPromise('doc2', e2.provider).catch(() => {});
    expect(__syncPromiseCacheSize()).toBe(2);

    pool.dispose();

    expect(__syncPromiseCacheSize()).toBe(0);
  });

  test('natural (network-triggered) close event rejects the syncPromise with PreSyncDisconnectError', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const p = syncPromise('doc1', entry.provider);

    entry.provider.emit('close', {
      event: { code: 1006, reason: 'network drop', wasClean: false },
    });

    await expect(p).rejects.toBeInstanceOf(PreSyncDisconnectError);
    expect(__syncPromiseCacheSize()).toBe(1);
  });

  test('server-driven-close reauth is bounded — sequential closes do not sendToken without limit', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const sendTokenSpy = vi
      .spyOn(entry.provider, 'sendToken')
      .mockImplementation(() => Promise.resolve());

    const CLOSES = 15;
    for (let i = 0; i < CLOSES; i++) {
      entry.provider.emit('close', {
        event: { code: 4205, reason: 'Reset Connection', wasClean: true },
      });
      await Promise.resolve();
      await Promise.resolve();
    }

    expect(sendTokenSpy.mock.calls.length).toBe(5);
  });

  test('a transport-drop close (empty reason) never triggers a reauth', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const sendTokenSpy = vi
      .spyOn(entry.provider, 'sendToken')
      .mockImplementation(() => Promise.resolve());

    for (let i = 0; i < 15; i++) {
      entry.provider.emit('close', { event: { code: 1006, reason: '', wasClean: false } });
      entry.provider.emit('close', { event: { code: 1006, wasClean: false } });
      await Promise.resolve();
      await Promise.resolve();
    }

    expect(sendTokenSpy).not.toHaveBeenCalled();
  });

  test('the client-minted forced close never triggers a reauth', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (entry?.kind !== 'active') throw new Error('expected an active entry');
    const sendTokenSpy = vi
      .spyOn(entry.provider, 'sendToken')
      .mockImplementation(() => Promise.resolve());

    for (let i = 0; i < 15; i++) {
      entry.provider.emit('close', { event: { code: 4408, reason: 'forced', wasClean: false } });
      await Promise.resolve();
      await Promise.resolve();
    }

    expect(sendTokenSpy).not.toHaveBeenCalled();
    expect(entry.serverDrivenCloseReauthAttempts).toBe(0);
  });

  test('a 4408 the client did not mint still reauths', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const sendTokenSpy = vi
      .spyOn(entry.provider, 'sendToken')
      .mockImplementation(() => Promise.resolve());

    entry.provider.emit('close', {
      event: { code: 4408, reason: 'Connection Timeout', wasClean: true },
    });
    await Promise.resolve();
    await Promise.resolve();

    expect(sendTokenSpy).toHaveBeenCalledTimes(1);
  });

  test('a forced close while a mount gate is pending rejects it', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const gate = syncPromise('doc1', entry.provider);

    entry.provider.emit('close', { event: { code: 4408, reason: 'forced', wasClean: false } });

    await expect(gate).rejects.toBeInstanceOf(PreSyncDisconnectError);
  });

  test('a successful sync resets the server-driven-close reauth ceiling', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    const sendTokenSpy = vi
      .spyOn(entry.provider, 'sendToken')
      .mockImplementation(() => Promise.resolve());

    const fireClose = async () => {
      entry.provider.emit('close', {
        event: { code: 4205, reason: 'Reset Connection', wasClean: true },
      });
      await Promise.resolve();
      await Promise.resolve();
    };

    for (let i = 0; i < 10; i++) await fireClose();
    const afterCeiling = sendTokenSpy.mock.calls.length;
    expect(afterCeiling).toBeLessThanOrEqual(6);

    entry.provider.emit('synced', { state: true });
    await Promise.resolve();

    for (let i = 0; i < 10; i++) await fireClose();

    expect(sendTokenSpy.mock.calls.length).toBeGreaterThan(afterCeiling);
  });

  test('the ceiling breadcrumb is emitted exactly once no matter how many closes follow', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc1');
    if (!entry) throw new Error('expected entry');
    vi.spyOn(entry.provider, 'sendToken').mockImplementation(() => Promise.resolve());
    const warns: string[] = [];
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation((msg: unknown) => {
      warns.push(String(msg));
    });

    try {
      for (let i = 0; i < 20; i++) {
        entry.provider.emit('close', {
          event: { code: 4205, reason: 'Reset Connection', wasClean: true },
        });
        await Promise.resolve();
        await Promise.resolve();
      }
    } finally {
      warnSpy.mockRestore();
    }

    const ceilingWarns = warns.filter((w) =>
      w.includes('ok-provider-server-driven-close-reauth-ceiling'),
    );
    expect(ceilingWarns).toHaveLength(1);
  });
});

interface FakeContainer {
  parentElement: FakeContainer | null;
  scrollTop: number;
  children: FakeContainer[];
  appendChild(child: FakeContainer): FakeContainer;
  removeChild(child: FakeContainer): FakeContainer;
  setAttribute(key: string, value: string): void;
  style: Record<string, string>;
}

function makeFakeNode(): FakeContainer {
  const node: FakeContainer = {
    parentElement: null,
    scrollTop: 0,
    children: [],
    style: {},
    setAttribute() {},
    appendChild(child) {
      if (child.parentElement) child.parentElement.removeChild(child);
      node.children.push(child);
      child.parentElement = node;
      return child;
    },
    removeChild(child) {
      const idx = node.children.indexOf(child);
      if (idx !== -1) node.children.splice(idx, 1);
      child.parentElement = null;
      return child;
    },
  };
  return node;
}

interface OkPerfCountersShape {
  providerObserverFires: Record<string, number>;
}

function readFireCount(docName: string): number {
  const counters = (globalThis as { __okPerfCounters?: OkPerfCountersShape }).__okPerfCounters;
  return counters?.providerObserverFires[docName] ?? 0;
}

function hasFireCountEntry(docName: string): boolean {
  const counters = (globalThis as { __okPerfCounters?: OkPerfCountersShape }).__okPerfCounters;
  return counters !== undefined && docName in counters.providerObserverFires;
}

function resetFireCounts(): void {
  const counters = (globalThis as { __okPerfCounters?: OkPerfCountersShape }).__okPerfCounters;
  if (counters) counters.providerObserverFires = {};
}

describe('US-003 (cap-calibration-probes): observer-fire counter for M5', () => {
  beforeEach(() => {
    resetFireCounts();
  });
  afterEach(() => {
    pool?.dispose();
    resetFireCounts();
  });

  test('increments on REMOTE transactions (Y.applyUpdate from a peer doc)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-remote');
    if (!entry) throw new Error('expected entry');

    const peerDoc = new Y.Doc();
    peerDoc.getText('source').insert(0, 'hello-from-peer');
    const update = Y.encodeStateAsUpdate(peerDoc);
    Y.applyUpdate(entry.provider.document, update);

    expect(readFireCount('doc-remote')).toBeGreaterThanOrEqual(1);
  });

  test('does NOT increment on LOCAL transactions (transact)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-local');
    if (!entry) throw new Error('expected entry');

    entry.provider.document.transact(() => {
      entry.provider.document.getText('source').insert(0, 'local-write');
    });

    expect(readFireCount('doc-local')).toBe(0);
  });

  test('counter is per-docName (multiple docs tracked independently)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const a = pool.open('doc-a');
    const b = pool.open('doc-b');
    if (!a || !b) throw new Error('expected entries');

    const peerA = new Y.Doc();
    peerA.getText('source').insert(0, 'a');
    Y.applyUpdate(a.provider.document, Y.encodeStateAsUpdate(peerA));

    const peerB = new Y.Doc();
    peerB.getText('source').insert(0, 'b');
    Y.applyUpdate(b.provider.document, Y.encodeStateAsUpdate(peerB));
    peerB.getText('source').insert(1, '2');
    Y.applyUpdate(b.provider.document, Y.encodeStateAsUpdate(peerB));

    expect(readFireCount('doc-a')).toBe(1);
    expect(readFireCount('doc-b')).toBeGreaterThanOrEqual(2);
  });

  test('counter is removed on close (pool teardown path for evict)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-evict');
    if (!entry) throw new Error('expected entry');
    const peer = new Y.Doc();
    peer.getText('source').insert(0, 'x');
    Y.applyUpdate(entry.provider.document, Y.encodeStateAsUpdate(peer));
    expect(hasFireCountEntry('doc-evict')).toBe(true);

    pool.close('doc-evict');

    expect(hasFireCountEntry('doc-evict')).toBe(false);
  });

  test('counter is removed on recycle (Try-Again retry path)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-recycle');
    if (!entry) throw new Error('expected entry');
    pool.setActive('doc-recycle');
    const peer = new Y.Doc();
    peer.getText('source').insert(0, 'y');
    Y.applyUpdate(entry.provider.document, Y.encodeStateAsUpdate(peer));
    expect(hasFireCountEntry('doc-recycle')).toBe(true);

    pool.recycle('doc-recycle');

    expect(readFireCount('doc-recycle')).toBe(0);
  });

  test('counter is removed on dispose (pool teardown path for all entries)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const a = pool.open('doc-disp-a');
    const b = pool.open('doc-disp-b');
    if (!a || !b) throw new Error('expected entries');
    const peer = new Y.Doc();
    peer.getText('source').insert(0, 'z');
    Y.applyUpdate(a.provider.document, Y.encodeStateAsUpdate(peer));
    Y.applyUpdate(b.provider.document, Y.encodeStateAsUpdate(peer));
    expect(hasFireCountEntry('doc-disp-a')).toBe(true);
    expect(hasFireCountEntry('doc-disp-b')).toBe(true);

    pool.dispose();

    expect(hasFireCountEntry('doc-disp-a')).toBe(false);
    expect(hasFireCountEntry('doc-disp-b')).toBe(false);
  });

  test('existing setupObservers / bridge is NOT modified (regression guard)', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-nomod');
    if (!entry) throw new Error('expected entry');
    expect(entry.bridgeSetupFailed).toBe(false);

    const peer = new Y.Doc();
    peer.getText('source').insert(0, 'remote');
    Y.applyUpdate(entry.provider.document, Y.encodeStateAsUpdate(peer));

    expect(entry.bridgeSetupFailed).toBe(false);
    expect(readFireCount('doc-nomod')).toBeGreaterThanOrEqual(1);
  });

  test('globalThis.__okPerfCounters surface is reachable and well-shaped', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.open('doc-shape');
    const peer = new Y.Doc();
    peer.getText('source').insert(0, 'probe');
    const entry = pool.entries.get('doc-shape');
    if (!entry) throw new Error('expected entry');
    Y.applyUpdate(entry.provider.document, Y.encodeStateAsUpdate(peer));

    const counters = (globalThis as { __okPerfCounters?: OkPerfCountersShape }).__okPerfCounters;
    expect(counters).toBeDefined();
    expect(typeof counters?.providerObserverFires).toBe('object');
    expect(counters?.providerObserverFires['doc-shape']).toBeGreaterThanOrEqual(1);
  });
});

describe('ProviderPool → V2 editor cache eviction coupling (Critical #2)', () => {
  test('close() evicts both TipTap + CM cache entries before destroying the provider', async () => {
    const cacheModule = await import('./editor-cache');
    cacheModule.__resetCacheForTests();
    const fakeTipDom = makeFakeNode();
    const fakeCmDom = makeFakeNode();
    const fakeEditor = {
      editorView: { dom: fakeTipDom, scrollDOM: fakeTipDom },
      commands: { focus: vi.fn(() => {}) },
      destroy: vi.fn(() => {}),
    } as unknown as import('@tiptap/core').Editor;
    const fakeView = {
      dom: fakeCmDom,
      scrollDOM: fakeCmDom,
      focus: vi.fn(() => {}),
      destroy: vi.fn(() => {}),
    } as unknown as import('@codemirror/view').EditorView;
    const makeProv = () =>
      ({
        destroy: vi.fn(() => {}),
        document: { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc,
        awareness: null,
      }) as unknown as import('@hocuspocus/provider').HocuspocusProvider;
    const fakeYDoc = { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc;
    const fakeYText = { toString: () => '' } as unknown as import('yjs').Text;

    cacheModule.mountTiptapEditor({
      docName: 'doc-eviction-regression',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        editor: fakeEditor,
        ydoc: fakeYDoc,
        ytext: fakeYText,
        provider: makeProv(),
      }),
    });
    cacheModule.mountCmEditor({
      docName: 'doc-eviction-regression',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        view: fakeView,
        ydoc: fakeYDoc,
        ytext: fakeYText,
        provider: makeProv(),
        themeCompartment: new Compartment(),
        wordWrapCompartment: new Compartment(),
        placeholderCompartment: new Compartment(),
      }),
    });
    expect(cacheModule.peekTiptap('doc-eviction-regression')).toBeDefined();
    expect(cacheModule.__peekCm('doc-eviction-regression')).toBeDefined();

    pool = new ProviderPool(3, DUMMY_WS);
    cacheModule.subscribePoolEviction(pool);
    pool.open('doc-eviction-regression');
    pool.close('doc-eviction-regression');

    expect(cacheModule.peekTiptap('doc-eviction-regression')).toBeUndefined();
    expect(cacheModule.__peekCm('doc-eviction-regression')).toBeUndefined();
  });

  test('recycle() also evicts both caches (used by Try-Again retry path)', async () => {
    const cacheModule = await import('./editor-cache');
    cacheModule.__resetCacheForTests();
    const fakeTipDom = makeFakeNode();
    const fakeCmDom = makeFakeNode();
    const fakeEditor = {
      editorView: { dom: fakeTipDom, scrollDOM: fakeTipDom },
      commands: { focus: vi.fn(() => {}) },
      destroy: vi.fn(() => {}),
    } as unknown as import('@tiptap/core').Editor;
    const fakeView = {
      dom: fakeCmDom,
      scrollDOM: fakeCmDom,
      focus: vi.fn(() => {}),
      destroy: vi.fn(() => {}),
    } as unknown as import('@codemirror/view').EditorView;
    const makeProv = () =>
      ({
        destroy: vi.fn(() => {}),
        document: { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc,
        awareness: null,
      }) as unknown as import('@hocuspocus/provider').HocuspocusProvider;
    const fakeYDoc = { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc;
    const fakeYText = { toString: () => '' } as unknown as import('yjs').Text;
    cacheModule.mountTiptapEditor({
      docName: 'doc-recycle-regression',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        editor: fakeEditor,
        ydoc: fakeYDoc,
        ytext: fakeYText,
        provider: makeProv(),
      }),
    });
    cacheModule.mountCmEditor({
      docName: 'doc-recycle-regression',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        view: fakeView,
        ydoc: fakeYDoc,
        ytext: fakeYText,
        provider: makeProv(),
        themeCompartment: new Compartment(),
        wordWrapCompartment: new Compartment(),
        placeholderCompartment: new Compartment(),
      }),
    });

    pool = new ProviderPool(3, DUMMY_WS);
    cacheModule.subscribePoolEviction(pool);
    pool.open('doc-recycle-regression');
    pool.recycle('doc-recycle-regression');

    expect(cacheModule.peekTiptap('doc-recycle-regression')).toBeUndefined();
    expect(cacheModule.__peekCm('doc-recycle-regression')).toBeUndefined();
  });

  test('dispose() evicts all cached editors across all pool entries', async () => {
    const cacheModule = await import('./editor-cache');
    cacheModule.__resetCacheForTests();
    const makeProv = () =>
      ({
        destroy: vi.fn(() => {}),
        document: { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc,
        awareness: null,
      }) as unknown as import('@hocuspocus/provider').HocuspocusProvider;
    const makeFakeEditor = () => {
      const dom = makeFakeNode();
      return {
        editorView: { dom, scrollDOM: dom },
        commands: { focus: vi.fn(() => {}) },
        destroy: vi.fn(() => {}),
      } as unknown as import('@tiptap/core').Editor;
    };
    const fakeYText = { toString: () => '' } as unknown as import('yjs').Text;

    cacheModule.mountTiptapEditor({
      docName: 'dispose-a',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        editor: makeFakeEditor(),
        ydoc: { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc,
        ytext: fakeYText,
        provider: makeProv(),
      }),
    });
    cacheModule.mountTiptapEditor({
      docName: 'dispose-b',
      container: makeFakeNode() as unknown as HTMLElement,
      factory: () => ({
        editor: makeFakeEditor(),
        ydoc: { destroy: vi.fn(() => {}) } as unknown as import('yjs').Doc,
        ytext: fakeYText,
        provider: makeProv(),
      }),
    });

    pool = new ProviderPool(3, DUMMY_WS);
    cacheModule.subscribePoolEviction(pool);
    pool.open('dispose-a');
    pool.open('dispose-b');
    pool.dispose();

    expect(cacheModule.peekTiptap('dispose-a')).toBeUndefined();
    expect(cacheModule.peekTiptap('dispose-b')).toBeUndefined();
  });
});

describe('ProviderPool client-persistence attachment (US-003)', () => {
  function stubPersistence(): ClientPersistenceProvider {
    return {
      whenSynced: Promise.resolve(undefined as never),
      synced: true,
      destroy: vi.fn(async () => {}),
      clearData: vi.fn(async () => {}),
      flushFullState: async () => {},
    } as ClientPersistenceProvider;
  }

  test('open() attaches a ClientPersistenceProvider to the pool entry', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName();
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const persistence = await awaitAttachedPersistence(entry);
    expect(typeof persistence.destroy).toBe('function');
    expect(typeof persistence.clearData).toBe('function');
  });

  test('open() before serverInstanceId is known leaves persistence null', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName();
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.persistence).toBeNull();
  });

  test('deferred persistence attach continues after one entry throws', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      const badDoc = uniqueDocName('pp-deferred-throw');
      const goodDoc = uniqueDocName('pp-deferred-ok');
      const goodPersistence = stubPersistence();
      const persistenceFactory = vi.fn(({ docName }: { docName: string }) => {
        if (docName === badDoc) {
          throw new Error('idb unavailable');
        }
        return goodPersistence;
      });

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory });
      const badEntry = pool.open(badDoc);
      const goodEntry = pool.open(goodDoc);
      if (!badEntry || !goodEntry) throw new Error('expected entries');
      expect(badEntry.persistence).toBeNull();
      expect(goodEntry.persistence).toBeNull();

      expect(() => pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID)).not.toThrow();

      await awaitAttachedPersistence(goodEntry);
      expect(goodEntry.persistence).toBe(goodPersistence);
      await waitFor(() => persistenceFactory.mock.calls.length === 2, 2_000);
      expect(persistenceFactory).toHaveBeenCalledTimes(2);
      expect(badEntry.persistence).toBeNull();
      const events = warnSpy.mock.calls.map((call) => String(call[0] ?? ''));
      expect(
        events.some((event) => event.includes('"event":"ok-client-persistence-attach-failed"')),
      ).toBe(true);
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('re-opening the same docName reuses the existing persistence instance', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName();
    const entry1 = pool.open(docName);
    if (!entry1) throw new Error('expected entry1');
    const persistence1 = await awaitAttachedPersistence(entry1);
    const entry2 = pool.open(docName);
    expect(entry2?.persistence).toBe(persistence1);
  });

  test('prewarm() also attaches a persistence instance', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-prewarm');
    const entry = pool.prewarm(docName);
    if (!entry) throw new Error('expected prewarmed entry');
    await awaitAttachedPersistence(entry);
    expect(entry.persistence).not.toBeNull();
  });

  test('close() destroys the persistence before the provider', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-close');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const attached = await awaitAttachedPersistence(entry);

    const order: string[] = [];
    const persistenceSpy = vi.fn(async () => {
      order.push('persistence');
    });
    attached.destroy = persistenceSpy;

    const origProviderDestroy = entry.provider.destroy.bind(entry.provider);
    entry.provider.destroy = (() => {
      order.push('provider');
      origProviderDestroy();
    }) as typeof entry.provider.destroy;

    pool.close(docName);

    expect(persistenceSpy).toHaveBeenCalledTimes(1);
    expect(order[0]).toBe('persistence');
    expect(order[1]).toBe('provider');
  });

  test('recycleDisconnectedEntry destroys the persistence before the provider', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { recycleDebounceMs: 50 });
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-recycle');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const attached = await awaitAttachedPersistence(entry);
    pool.setActive(docName);
    entry.observerCleanup = () => {};

    const order: string[] = [];
    const persistenceSpy = vi.fn(async () => {
      order.push('persistence');
    });
    attached.destroy = persistenceSpy;

    const origProviderDestroy = entry.provider.destroy.bind(entry.provider);
    entry.provider.destroy = (() => {
      order.push('provider');
      origProviderDestroy();
    }) as typeof entry.provider.destroy;

    entry.hasSynced = true;
    entry.syncState = 'synced';
    entry.provider.unsyncedChanges = 0;
    entry.provider.emit('disconnect', {
      event: { code: 1006, reason: 'server restart', wasClean: false },
    });
    await wait(100);

    expect(persistenceSpy).toHaveBeenCalledTimes(1);
    expect(order[0]).toBe('persistence');
    expect(order[1]).toBe('provider');
  });

  test('evictLru destroys the persistence on the evicted entry', async () => {
    pool = new ProviderPool(2, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const doc1 = uniqueDocName('pp-evict');
    const doc2 = uniqueDocName('pp-evict');
    const doc3 = uniqueDocName('pp-evict');
    pool.open(doc1);
    pool.setActive(doc1);
    const entry2 = pool.open(doc2);
    if (!entry2) throw new Error('expected entry on doc2');
    const attached2 = await awaitAttachedPersistence(entry2);

    const destroySpy = vi.fn(async () => {});
    attached2.destroy = destroySpy;

    pool.open(doc3);

    expect(pool.has(doc2)).toBe(false);
    expect(destroySpy).toHaveBeenCalledTimes(1);
  });

  test('dispose() destroys every pool entry’s persistence', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const doc1 = uniqueDocName('pp-dispose');
    const doc2 = uniqueDocName('pp-dispose');
    const e1 = pool.open(doc1);
    const e2 = pool.open(doc2);
    if (!e1 || !e2) throw new Error('expected entries');
    const p1 = await awaitAttachedPersistence(e1);
    const p2 = await awaitAttachedPersistence(e2);

    const spy1 = vi.fn(async () => {});
    const spy2 = vi.fn(async () => {});
    p1.destroy = spy1;
    p2.destroy = spy2;

    pool.dispose();

    expect(spy1).toHaveBeenCalledTimes(1);
    expect(spy2).toHaveBeenCalledTimes(1);
  });

  test('closeAndClearPersistence calls clearData on a pooled entry, then closes it', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    const docName = uniqueDocName('pp-rename-clear');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const attached = await awaitAttachedPersistence(entry);

    const clearSpy = vi.fn(async () => {});
    attached.clearData = clearSpy;

    await pool.closeAndClearPersistence(docName);

    expect(clearSpy).toHaveBeenCalledTimes(1);
    expect(pool.has(docName)).toBe(false);
  });

  test('closeAndClearPersistence deletes the IDB directly when the doc is not in the pool', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setObservedBranch('main');
    pool.setExpectedServerInstanceId('server-rename-orphan');
    const docName = uniqueDocName('pp-rename-orphan');
    const dbName = `ok-ydoc:main:server-rename-orphan:${docName}`;

    await new Promise<void>((resolve, reject) => {
      const req = indexedDB.open(dbName);
      req.onsuccess = () => {
        req.result.close();
        resolve();
      };
      req.onerror = () => reject(req.error);
    });

    let dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbName)).toBeDefined();

    expect(pool.has(docName)).toBe(false);
    await pool.closeAndClearPersistence(docName);

    dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbName)).toBeUndefined();
  });

  test('closeAndClearPersistence is a no-op when serverInstanceId is unknown and doc not in pool', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setObservedBranch('main');
    const docName = uniqueDocName('pp-rename-noepoch');

    const dbName = `ok-ydoc:main:server-prior:${docName}`;
    await new Promise<void>((resolve, reject) => {
      const req = indexedDB.open(dbName);
      req.onsuccess = () => {
        req.result.close();
        resolve();
      };
      req.onerror = () => reject(req.error);
    });

    await pool.closeAndClearPersistence(docName);

    const dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbName)).toBeDefined();

    await new Promise<void>((resolve) => {
      const req = indexedDB.deleteDatabase(dbName);
      req.onsuccess = () => resolve();
      req.onerror = () => resolve();
    });
  });

  test('rename round-trip (A→B→A) clears IDB so reopen at A starts fresh', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setObservedBranch('main');
    pool.setExpectedServerInstanceId('server-roundtrip');
    const nameA = uniqueDocName('pp-roundtrip-A');
    const nameB = uniqueDocName('pp-roundtrip-B');
    const dbA = `ok-ydoc:main:server-roundtrip:${nameA}`;
    const dbB = `ok-ydoc:main:server-roundtrip:${nameB}`;

    const entryA1 = pool.open(nameA);
    if (!entryA1) throw new Error('expected entry');
    await (await awaitAttachedPersistence(entryA1)).whenSynced;
    let dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbA)).toBeDefined();

    await pool.closeAndClearPersistence(nameA);
    await pool.closeAndClearPersistence(nameB);
    dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbA)).toBeUndefined();
    expect(dbs.find((d) => d.name === dbB)).toBeUndefined();

    const entryB = pool.open(nameB);
    if (!entryB) throw new Error('expected entry');
    await (await awaitAttachedPersistence(entryB)).whenSynced;
    dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbB)).toBeDefined();

    await pool.closeAndClearPersistence(nameB);
    await pool.closeAndClearPersistence(nameA);
    dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbA)).toBeUndefined();
    expect(dbs.find((d) => d.name === dbB)).toBeUndefined();

    const entryA2 = pool.open(nameA);
    if (!entryA2) throw new Error('expected entry');
    await (await awaitAttachedPersistence(entryA2)).whenSynced;
    dbs = await indexedDB.databases();
    expect(dbs.find((d) => d.name === dbA)).toBeDefined();
  });

  test('server-instance-mismatch calls clearData on every entry before destroying', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-old');
    const doc1 = uniqueDocName('pp-mismatch');
    const doc2 = uniqueDocName('pp-mismatch');
    const e1 = pool.open(doc1);
    const e2 = pool.open(doc2);
    if (!e1 || !e2) throw new Error('expected entries');
    const p1 = await awaitAttachedPersistence(e1);
    const p2 = await awaitAttachedPersistence(e2);
    pool.setActive(doc1);
    e1.observerCleanup = () => {};

    const clearSpy1 = vi.fn(async () => {});
    const clearSpy2 = vi.fn(async () => {});
    p1.clearData = clearSpy1;
    p2.clearData = clearSpy2;

    e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    await wait(50);

    expect(clearSpy1).toHaveBeenCalledTimes(1);
    expect(clearSpy2).toHaveBeenCalledTimes(1);
    expect(pool.has(doc2)).toBe(false);
    expect(pool.has(doc1)).toBe(true);
  });

  test('server-instance-mismatch with partial clearData failure recycles cleared entries only', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-old');
    const doc1 = uniqueDocName('pp-partial-ok');
    const doc2 = uniqueDocName('pp-partial-fail');
    const doc3 = uniqueDocName('pp-partial-ok2');
    const e1 = pool.open(doc1);
    const e2 = pool.open(doc2);
    const e3 = pool.open(doc3);
    if (!e1 || !e2 || !e3) {
      throw new Error('expected entries');
    }
    const p1 = await awaitAttachedPersistence(e1);
    const p2 = await awaitAttachedPersistence(e2);
    const p3 = await awaitAttachedPersistence(e3);
    pool.setActive(doc1);
    e1.observerCleanup = () => {};
    e2.observerCleanup = () => {};
    e3.observerCleanup = () => {};

    const preProvider1 = e1.provider;
    const preProvider2 = e2.provider;
    const preProvider3 = e3.provider;

    const clearOk1 = vi.fn(async () => {});
    const clearFail = vi.fn(() => Promise.reject(new Error('idb-clear-blocked')));
    const clearOk2 = vi.fn(async () => {});
    p1.clearData = clearOk1;
    p2.clearData = clearFail;
    p3.clearData = clearOk2;

    e1.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    await wait(50);

    expect(clearOk1).toHaveBeenCalledTimes(1);
    expect(clearFail).toHaveBeenCalledTimes(1);
    expect(clearOk2).toHaveBeenCalledTimes(1);

    const post1 = pool.entries.get(doc1);
    if (post1?.kind !== 'active') throw new Error('expected active doc1 post-recycle');
    expect(post1.provider).not.toBe(preProvider1);

    expect(pool.has(doc3)).toBe(false);

    const post2 = pool.entries.get(doc2);
    if (post2?.kind !== 'active') throw new Error('expected active doc2 still in pool');
    expect(post2.provider).toBe(preProvider2);
    void preProvider3;
  });

  test('partial clearData with timeout preserves timeout reason after active reconnect syncs', async () => {
    pool = new ProviderPool(3, DUMMY_WS, { clearDataTimeoutMs: 15 });
    pool.setExpectedServerInstanceId('server-old');
    const docActive = uniqueDocName('pp-partial-timeout-active');
    const docHung = uniqueDocName('pp-partial-timeout-hung');
    const ea = pool.open(docActive);
    const eb = pool.open(docHung);
    if (!ea || !eb) {
      throw new Error('expected entries');
    }
    const pa = await awaitAttachedPersistence(ea);
    const pb = await awaitAttachedPersistence(eb);
    pool.setActive(docActive);
    ea.observerCleanup = () => {};
    eb.observerCleanup = () => {};

    pa.clearData = vi.fn(async () => {});
    pb.clearData = vi.fn(() => new Promise<void>(() => {}));

    ea.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    await wait(60);

    const postActive = pool.entries.get(docActive);
    if (postActive?.kind !== 'active') throw new Error('expected active doc post-recycle');
    expect(pool.getServerRestartRecoveryState()).toMatchObject({
      kind: 'recovering',
      phase: 'reconnecting',
      docNames: [docActive],
      failedDocNames: [docHung],
      clearFailureReason: 'clear-data-timeout',
    });

    postActive.provider.emit('synced', { state: true });

    expect(pool.getServerRestartRecoveryState()).toMatchObject({
      kind: 'failed',
      reason: 'clear-data-timeout',
      docNames: [docHung],
      failedDocNames: [docHung],
    });
  });

  describe('pendingClears dedup + deferred-attach', () => {
    interface ControllableStub {
      stub: ClientPersistenceProvider;
      clearSpy: ReturnType<typeof vi.fn>;
    }

    function makeControllableStub(clearImpl: () => Promise<void>): ControllableStub {
      const clearSpy = vi.fn(clearImpl);
      const stub = {
        whenSynced: Promise.resolve(undefined as never),
        synced: true,
        destroy: vi.fn(async () => {}),
        clearData: clearSpy,
        flushFullState: async () => {},
      } as unknown as ClientPersistenceProvider;
      return { stub, clearSpy };
    }

    test('closeAndClearPersistence dedups concurrent calls via in-flight reuse', async () => {
      let resolveClear: () => void = () => {};
      const { stub, clearSpy } = makeControllableStub(() => {
        const { promise, resolve } = Promise.withResolvers<void>();
        resolveClear = resolve;
        return promise;
      });
      const persistenceFactory = vi.fn(() => stub);
      const deleteDbSpy = vi.spyOn(indexedDB, 'deleteDatabase');

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });
      pool.setObservedBranch('main');
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-pending-clears-dedup');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      await awaitAttachedPersistence(entry);

      const deleteDbCallsBefore = deleteDbSpy.mock.calls.length;
      const call1 = pool.closeAndClearPersistence(docName);
      const call2 = pool.closeAndClearPersistence(docName);

      expect(clearSpy).toHaveBeenCalledTimes(1);
      expect(deleteDbSpy.mock.calls.length).toBe(deleteDbCallsBefore);

      resolveClear();
      await Promise.all([call1, call2]);
      expect(clearSpy).toHaveBeenCalledTimes(1);
      expect(deleteDbSpy.mock.calls.length).toBe(deleteDbCallsBefore);
    });

    test('deferred persistence attach: pool.open during in-flight clear leaves persistence null synchronously, attaches once clear resolves', async () => {
      let resolveClear: () => void = () => {};
      const cleared = makeControllableStub(() => {
        const { promise, resolve } = Promise.withResolvers<void>();
        resolveClear = resolve;
        return promise;
      });
      const fresh = makeControllableStub(async () => {});
      let callCount = 0;
      const persistenceFactory = vi.fn(() => {
        callCount += 1;
        return callCount === 1 ? cleared.stub : fresh.stub;
      });

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-pending-clears-defer-success');

      const entry1 = pool.open(docName);
      if (!entry1) throw new Error('expected entry1');
      await awaitAttachedPersistence(entry1);

      const clearPromise = pool.closeAndClearPersistence(docName);

      const entry2 = pool.open(docName);
      if (!entry2) throw new Error('expected entry2');
      expect(entry2.persistence).toBeNull();

      resolveClear();
      await clearPromise;
      await waitFor(() => entry2.persistence !== null, 2_000);
      expect(entry2.persistence).toBe(fresh.stub);
    });

    test('deferred persistence attach skipped on pending-clear-failed (structured warn fires, persistence stays null)', async () => {
      let rejectClear: (err: Error) => void = () => {};
      const cleared = makeControllableStub(() => {
        const { promise, reject } = Promise.withResolvers<void>();
        rejectClear = reject;
        return promise;
      });
      const persistenceFactory = vi.fn(() => cleared.stub);

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-pending-clears-defer-fail');

      const entry1 = pool.open(docName);
      if (!entry1) throw new Error('expected entry1');
      await awaitAttachedPersistence(entry1);
      const clearPromise = pool.closeAndClearPersistence(docName);

      const entry2 = pool.open(docName);
      if (!entry2) throw new Error('expected entry2');
      expect(entry2.persistence).toBeNull();

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
      try {
        rejectClear(new Error('idb-clear-blocked'));
        await clearPromise;
        await wait(0);

        const skippedWarn = warnSpy.mock.calls
          .map((call) => String(call[0] ?? ''))
          .find((s) => s.includes('"event":"ok-pool-deferred-persistence-attach-skipped"'));
        expect(skippedWarn).toBeDefined();
        expect(skippedWarn).toContain('"reason":"pending-clear-failed"');
        expect(entry2.persistence).toBeNull();
      } finally {
        warnSpy.mockRestore();
      }
    });

    test('dispose() clears pendingClears tracking so the deferred-attach .then never reattaches', async () => {
      let resolveClear: () => void = () => {};
      const cleared = makeControllableStub(() => {
        const { promise, resolve } = Promise.withResolvers<void>();
        resolveClear = resolve;
        return promise;
      });
      const fresh = makeControllableStub(async () => {});
      let callCount = 0;
      const persistenceFactory = vi.fn(() => {
        callCount += 1;
        return callCount === 1 ? cleared.stub : fresh.stub;
      });

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-pending-clears-dispose');
      const entry1 = pool.open(docName);
      if (!entry1) throw new Error('expected entry1');
      await awaitAttachedPersistence(entry1);

      const clearPromise = pool.closeAndClearPersistence(docName);
      const entry2 = pool.open(docName);
      if (!entry2) throw new Error('expected entry2');
      expect(entry2.persistence).toBeNull();

      pool.dispose();
      resolveClear();
      await clearPromise;
      await wait(0);

      expect(persistenceFactory).toHaveBeenCalledTimes(1);
      expect(entry2.persistence).toBeNull();
    });

    test('Promise.all batch over closeAndClearPersistence resolves even when one inner clearData rejects', async () => {
      const ok1 = makeControllableStub(async () => {});
      const fail = makeControllableStub(() => Promise.reject(new Error('idb-failed')));
      const ok2 = makeControllableStub(async () => {});
      const stubs = [ok1.stub, fail.stub, ok2.stub];
      let idx = 0;
      const persistenceFactory = vi.fn(() => {
        const s = stubs[idx];
        idx += 1;
        return s;
      });

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory });
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docs = [
        uniqueDocName('pp-swallow-ok1'),
        uniqueDocName('pp-swallow-fail'),
        uniqueDocName('pp-swallow-ok2'),
      ];
      for (const d of docs) {
        const entry = pool.open(d);
        if (!entry) throw new Error('expected entry');
        await awaitAttachedPersistence(entry);
      }

      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
      try {
        await Promise.all(docs.map((d) => pool.closeAndClearPersistence(d)));
        expect(ok1.clearSpy).toHaveBeenCalledTimes(1);
        expect(fail.clearSpy).toHaveBeenCalledTimes(1);
        expect(ok2.clearSpy).toHaveBeenCalledTimes(1);
      } finally {
        warnSpy.mockRestore();
      }
    });

    test('non-concurrent reopen after a failed clear retries the IDB clear before attaching fresh persistence', async () => {
      const failedStub = makeControllableStub(() => Promise.reject(new Error('idb-blocked')));
      const freshStub = makeControllableStub(async () => {});
      let factoryCallCount = 0;
      const persistenceFactory = vi.fn(() => {
        factoryCallCount += 1;
        return factoryCallCount === 1 ? failedStub.stub : freshStub.stub;
      });

      pool = new ProviderPool(3, DUMMY_WS, { persistenceFactory, clearDataTimeoutMs: 30_000 });
      pool.setObservedBranch('main');
      pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
      const docName = uniqueDocName('pp-clearfail-retry');

      const entry1 = pool.open(docName);
      if (!entry1) throw new Error('expected entry1');
      await awaitAttachedPersistence(entry1);

      const deleteDbSpy = vi.spyOn(indexedDB, 'deleteDatabase');
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
      try {
        const baselineDeleteCalls = deleteDbSpy.mock.calls.length;

        await pool.closeAndClearPersistence(docName);
        await wait(0);

        const entry2 = pool.open(docName);
        if (!entry2) throw new Error('expected entry2');

        expect(entry2.persistence).toBeNull();

        const retryDbName = `ok-ydoc:main:${TEST_SERVER_INSTANCE_ID}:${docName}`;
        expect(deleteDbSpy.mock.calls.length).toBeGreaterThan(baselineDeleteCalls);
        expect(deleteDbSpy.mock.calls.some((call) => call[0] === retryDbName)).toBe(true);

        const attached = await waitFor(() => entry2.persistence !== null, 2_000);
        expect(attached).toBe(true);
        expect(entry2.persistence).toBe(freshStub.stub);
      } finally {
        warnSpy.mockRestore();
        deleteDbSpy.mockRestore();
      }
    });
  });
});

describe('ProviderPool buffer-and-replay (US-004)', () => {
  test('captures the last server-synced state vector on every synced event', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open(uniqueDocName('pp-sv'));
    if (!entry) throw new Error('expected entry');
    entry.observerCleanup = () => {};
    expect(entry.lastServerSyncedSV).toBeNull();

    entry.provider.emit('synced', { state: true });
    expect(entry.lastServerSyncedSV).toBeInstanceOf(Uint8Array);
  });

  test('TAB_REPLAY_ORIGIN is a stable frozen object', async () => {
    const mod = await import('./provider-pool');
    expect(mod.TAB_REPLAY_ORIGIN.kind).toBe('tab-replay');
    expect(Object.isFrozen(mod.TAB_REPLAY_ORIGIN)).toBe(true);
  });
});

describe('ProviderPool observeDiskAck (disk-ack watermark)', () => {
  test('advances lastDiskAckedSV on the active entry', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName('pp-dack');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.lastDiskAckedSV).toBeNull();

    const sv = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
    pool.observeDiskAck(docName, sv);
    expect(entry.lastDiskAckedSV).toBe(sv);
  });

  test('advances on subsequent observe with a strictly-newer SV', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName('pp-dack');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');

    const doc = new Y.Doc();
    doc.getText('t').insert(0, 'A');
    const svAfterA = Y.encodeStateVector(doc);
    doc.getText('t').insert(1, 'B');
    const svAfterAB = Y.encodeStateVector(doc);
    doc.destroy();

    pool.observeDiskAck(docName, svAfterA);
    pool.observeDiskAck(docName, svAfterAB);
    expect(entry.lastDiskAckedSV).toEqual(svAfterAB);
  });

  test('does NOT regress on out-of-order observe with a strictly-older SV', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName('pp-dack');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');

    const doc = new Y.Doc();
    doc.getText('t').insert(0, 'A');
    const svAfterA = Y.encodeStateVector(doc);
    doc.getText('t').insert(1, 'B');
    const svAfterAB = Y.encodeStateVector(doc);
    doc.destroy();

    pool.observeDiskAck(docName, svAfterAB);
    pool.observeDiskAck(docName, svAfterA);
    expect(entry.lastDiskAckedSV).toEqual(svAfterAB);
  });

  test('no-op when entry does not exist for docName', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    expect(() => {
      pool.observeDiskAck('nonexistent-doc', new Uint8Array([1, 2, 3]));
    }).not.toThrow();
  });

  test('no-op when entry has been removed from the pool', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const docName = uniqueDocName('pp-dack');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const initialSV = new Uint8Array([0xab]);
    pool.observeDiskAck(docName, initialSV);

    pool.close(docName);
    pool.observeDiskAck(docName, new Uint8Array([0xcd]));
    const fresh = pool.open(docName);
    if (!fresh) throw new Error('expected fresh entry');
    expect(fresh.lastDiskAckedSV).toBeNull();
  });
});

describe('ProviderPool observeDiskAckBatch (missed-frame recovery)', () => {
  test('updates lastDiskAckedSV for every doc named in the batch', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docA = uniqueDocName('pp-batch');
    const docB = uniqueDocName('pp-batch');
    const entryA = pool.open(docA);
    const entryB = pool.open(docB);
    if (!entryA || !entryB) throw new Error('expected entries');

    const yDocA = new Y.Doc();
    yDocA.getText('t').insert(0, 'A');
    const svA = Y.encodeStateVector(yDocA);
    yDocA.destroy();
    const yDocB = new Y.Doc();
    yDocB.getText('t').insert(0, 'BB');
    const svB = Y.encodeStateVector(yDocB);
    yDocB.destroy();

    pool.observeDiskAckBatch({ [docA]: svA, [docB]: svB });

    expect(entryA.lastDiskAckedSV).toEqual(svA);
    expect(entryB.lastDiskAckedSV).toEqual(svB);
  });

  test('silently ignores docs in the batch that the pool does not have open', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docA = uniqueDocName('pp-batch');
    const entryA = pool.open(docA);
    if (!entryA) throw new Error('expected entry');

    const yDoc = new Y.Doc();
    yDoc.getText('t').insert(0, 'X');
    const sv = Y.encodeStateVector(yDoc);
    yDoc.destroy();

    expect(() => {
      pool.observeDiskAckBatch({
        [docA]: sv,
        'nonexistent-doc': sv,
      });
    }).not.toThrow();
    expect(entryA.lastDiskAckedSV).toEqual(sv);
  });

  test('empty batch is a no-op', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docA = uniqueDocName('pp-batch');
    const entryA = pool.open(docA);
    if (!entryA) throw new Error('expected entry');

    const yDoc = new Y.Doc();
    yDoc.getText('t').insert(0, 'A');
    const sv = Y.encodeStateVector(yDoc);
    yDoc.destroy();
    pool.observeDiskAck(docA, sv);

    pool.observeDiskAckBatch({});
    expect(entryA.lastDiskAckedSV).toEqual(sv);
  });

  test('advances a stale lastDiskAckedSV when the batch carries a strictly-newer SV', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docA = uniqueDocName('pp-batch');
    const entryA = pool.open(docA);
    if (!entryA) throw new Error('expected entry');

    const yDoc = new Y.Doc();
    yDoc.getText('t').insert(0, 'A');
    const stale = Y.encodeStateVector(yDoc);
    yDoc.getText('t').insert(1, 'B');
    const fresh = Y.encodeStateVector(yDoc);
    yDoc.destroy();

    pool.observeDiskAck(docA, stale);
    pool.observeDiskAckBatch({ [docA]: fresh });
    expect(entryA.lastDiskAckedSV).toEqual(fresh);
  });

  test('does NOT regress a current lastDiskAckedSV when the batch carries an older SV', async () => {
    const Y = await import('yjs');
    pool = new ProviderPool(3, DUMMY_WS);
    const docA = uniqueDocName('pp-batch');
    const entryA = pool.open(docA);
    if (!entryA) throw new Error('expected entry');

    const yDoc = new Y.Doc();
    yDoc.getText('t').insert(0, 'A');
    const olderSV = Y.encodeStateVector(yDoc);
    yDoc.getText('t').insert(1, 'B');
    const newerSV = Y.encodeStateVector(yDoc);
    yDoc.destroy();

    pool.observeDiskAck(docA, newerSV);
    pool.observeDiskAckBatch({ [docA]: olderSV });
    expect(entryA.lastDiskAckedSV).toEqual(newerSV);
  });
});

describe('ProviderPool handleServerInstanceMismatch baseline-selection', () => {
  test('handleServerInstanceMismatch uses lastDiskAckedSV when present', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('server-old');
      const docName = uniqueDocName('pp-baseline');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      pool.setActive(docName);
      entry.observerCleanup = () => {};

      const Y = await import('yjs');
      const cp = await import('./client-persistence');
      entry.provider.document.getText('source').insert(0, 'AAA');
      const svAfterAAA = cp.captureStateVector(entry.provider.document);
      entry.provider.document.getText('source').insert(3, 'BBB');
      const svAfterAAABBB = cp.captureStateVector(entry.provider.document);
      entry.provider.document.getText('source').insert(6, 'CCC');

      entry.lastDiskAckedSV = svAfterAAA;
      entry.lastServerSyncedSV = svAfterAAABBB;

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(100);

      const noBaselineSkipped = warnSpy.mock.calls.filter(([first]) => {
        if (typeof first !== 'string') return false;
        try {
          return JSON.parse(first).event === 'ok-buffer-replay-skipped-no-baseline';
        } catch {
          return false;
        }
      }).length;

      const buffered = pool.__test_getBufferedUpdate(docName);
      if (!buffered) throw new Error('expected buffered update for active doc');

      expect(noBaselineSkipped).toBe(0);

      const expected = Y.encodeStateAsUpdate(entry.provider.document, svAfterAAA);
      expect(buffered).toEqual(expected);

      const wrong = Y.encodeStateAsUpdate(entry.provider.document, svAfterAAABBB);
      expect(buffered.byteLength).toBeGreaterThan(wrong.byteLength);
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('handleServerInstanceMismatch falls back to lastServerSyncedSV when lastDiskAckedSV is null', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-old');
    const docName = uniqueDocName('pp-baseline');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    pool.setActive(docName);
    entry.observerCleanup = () => {};

    const Y = await import('yjs');
    const cp = await import('./client-persistence');
    entry.provider.document.getText('source').insert(0, 'AAA');
    const svAfterAAA = cp.captureStateVector(entry.provider.document);
    entry.provider.document.getText('source').insert(3, 'BBB');

    entry.lastServerSyncedSV = svAfterAAA;
    expect(entry.lastDiskAckedSV).toBeNull();

    entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
    await wait(100);

    const buffered = pool.__test_getBufferedUpdate(docName);
    if (!buffered) throw new Error('expected buffered update');

    const expected = Y.encodeStateAsUpdate(entry.provider.document, svAfterAAA);
    expect(buffered).toEqual(expected);
  });

  test('handleServerInstanceMismatch skips buffer replay when both watermark SVs are null', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('server-old');
      pool.setObservedBranch('no-baseline-branch');
      const docName = uniqueDocName('pp-baseline');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      pool.setActive(docName);

      entry.provider.document.getText('source').insert(0, 'unacked content');
      expect(entry.lastServerSyncedSV).toBeNull();
      expect(entry.lastDiskAckedSV).toBeNull();

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(100);

      expect(pool.__test_getBufferedUpdate(docName)).toBeUndefined();

      const noBaselineCalls = warnSpy.mock.calls.filter(([first]) => {
        if (typeof first !== 'string') return false;
        try {
          return JSON.parse(first).event === 'ok-buffer-replay-skipped-no-baseline';
        } catch {
          return false;
        }
      });
      expect(noBaselineCalls.length).toBe(1);
      const firstArg = noBaselineCalls[0]?.[0];
      expect(typeof firstArg).toBe('string');
      const payload = JSON.parse(firstArg) as {
        event: string;
        docName: string;
        branch: string;
        serverInstanceId: string;
        reason: string;
      };
      expect(payload.event).toBe('ok-buffer-replay-skipped-no-baseline');
      expect(payload.docName).toBe(docName);
      expect(payload.branch).toBe('no-baseline-branch');
      expect(payload.serverInstanceId).toBe('server-old');
      expect(payload.reason).toBe('no-disk-ack-or-server-sync-vector');
      expect(new Set(Object.keys(payload))).toEqual(
        new Set(['event', 'docName', 'branch', 'serverInstanceId', 'reason']),
      );
    } finally {
      warnSpy.mockRestore();
    }
  });
});

describe('ProviderPool structured mismatch telemetry', () => {
  test('replay applies corrupt buffer emits ok-buffer-replay-failed with bounded fields', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('epoch-replay-telemetry');
      pool.setObservedBranch('replay-telemetry-branch');
      const docName = uniqueDocName('replay-flush');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      await awaitAttachedPersistence(entry);
      pool.setActive(docName);
      entry.observerCleanup = () => {};

      const cp = await import('./client-persistence');
      entry.provider.document.getText('source').insert(0, 'R');
      const svDisk = cp.captureStateVector(entry.provider.document);
      entry.lastDiskAckedSV = svDisk;

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(150);

      const neo = pool.entries.get(docName);
      if (neo?.kind !== 'active') throw new Error('expected recycled active entry');

      neo.observerCleanup = () => {};
      pool.__test_seedBufferedUpdate(docName, new Uint8Array([255, 0, 254]));
      neo.provider.emit('synced', { state: true });

      await wait(20);

      const replayFailedCalls = warnSpy.mock.calls
        .map((c) => c[0])
        .filter((first): first is string => typeof first === 'string')
        .filter((first) => {
          try {
            return JSON.parse(first).event === 'ok-buffer-replay-failed';
          } catch {
            return false;
          }
        });
      expect(replayFailedCalls.length).toBe(1);
      const payload = JSON.parse(replayFailedCalls[0] ?? '{}') as {
        event: string;
        docName: string;
        branch: string;
        serverInstanceId?: string;
        replayByteLength: number;
        errorName: string;
        errorMessage: string;
      };
      expect(payload.event).toBe('ok-buffer-replay-failed');
      expect(payload.docName).toBe(docName);
      expect(payload.branch).toBe('replay-telemetry-branch');
      expect(payload.serverInstanceId).toBe('epoch-replay-telemetry');
      expect(payload.replayByteLength).toBe(3);
      expect(typeof payload.errorName).toBe('string');
      expect(typeof payload.errorMessage).toBe('string');
      expect(new Set(Object.keys(payload))).toEqual(
        new Set([
          'event',
          'docName',
          'branch',
          'serverInstanceId',
          'replayByteLength',
          'errorName',
          'errorMessage',
        ]),
      );
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('epoch mismatch envelope uses active doc plus branch and stale instance claim', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
    try {
      pool = new ProviderPool(3, DUMMY_WS);
      pool.setExpectedServerInstanceId('stale-epoch-telemetry');
      pool.setObservedBranch('epoch-msg-branch');
      const docName = uniqueDocName('epoch-msg');
      const entry = pool.open(docName);
      if (!entry) throw new Error('expected entry');
      pool.setActive(docName);

      entry.provider.emit('authenticationFailed', { reason: 'server-instance-mismatch' });
      await wait(30);

      const epochCalls = warnSpy.mock.calls
        .map((c) => c[0])
        .filter((first): first is string => typeof first === 'string')
        .filter((first) => {
          try {
            return JSON.parse(first).event === 'ok-client-cache-epoch-mismatch';
          } catch {
            return false;
          }
        });
      expect(epochCalls.length).toBe(1);
      const payload = JSON.parse(epochCalls[0] ?? '{}') as {
        event: string;
        docName: string;
        branch: string;
        serverInstanceId: string;
      };
      expect(payload.docName).toBe(docName);
      expect(payload.branch).toBe('epoch-msg-branch');
      expect(payload.serverInstanceId).toBe('stale-epoch-telemetry');
      expect(new Set(Object.keys(payload))).toEqual(
        new Set(['event', 'docName', 'branch', 'serverInstanceId']),
      );
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('recovery state machine never reports blocked-suspicious-write labels', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const snapshot = JSON.stringify(pool.getServerRestartRecoveryState());
    expect(snapshot).not.toContain('blocked-suspicious-write');
    expect(snapshot).not.toContain('blocked_suspicious_write');
  });
});

describe('ProviderPool provider-open gating', () => {
  test('whenServerInstanceKnown resolves immediately when id is already cached', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId(TEST_SERVER_INSTANCE_ID);
    expect(await pool.whenServerInstanceKnown()).toBe(TEST_SERVER_INSTANCE_ID);
  });

  test('whenServerInstanceKnown returns the same pending promise for concurrent callers', () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const p1 = pool.whenServerInstanceKnown();
    const p2 = pool.whenServerInstanceKnown();
    expect(p1).toBe(p2);
  });

  test('whenServerInstanceKnown resolves once setExpectedServerInstanceId lands a non-null id', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const pending = pool.whenServerInstanceKnown();
    pool.setExpectedServerInstanceId('server-cold-boot');
    expect(await pending).toBe('server-cold-boot');
  });

  test('setExpectedServerInstanceId(null) does not reject pending whenServerInstanceKnown', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const pending = pool.whenServerInstanceKnown();
    pool.setExpectedServerInstanceId(null);
    pool.setExpectedServerInstanceId('server-after-null');
    expect(await pending).toBe('server-after-null');
  });

  test('a previously-resolved whenServerInstanceKnown promise is not re-resolved on a later id change', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-first');
    const resolved = await pool.whenServerInstanceKnown();
    expect(resolved).toBe('server-first');
    pool.setExpectedServerInstanceId('server-second');
    expect(await pool.whenServerInstanceKnown()).toBe('server-second');
    expect(resolved).toBe('server-first');
  });

  test('open() before serverInstanceId is known does not construct a stale-shape IDB database', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setObservedBranch('main');
    const docName = uniqueDocName('pp-cold-boot');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    expect(entry.persistence).toBeNull();
    expect(entry.kind).toBe('active');

    if (typeof indexedDB !== 'undefined') {
      const dbs = await indexedDB.databases();
      const staleShapeName = `ok-ydoc:main:${docName}`;
      const newShapeUnknownEpoch = `ok-ydoc:main::${docName}`;
      expect(dbs.find((d) => d.name === staleShapeName)).toBeUndefined();
      expect(dbs.find((d) => d.name === newShapeUnknownEpoch)).toBeUndefined();
    }
  });

  test('setExpectedServerInstanceId retroactively attaches persistence with the new-shape DB name', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setObservedBranch('main');
    const docA = uniqueDocName('pp-retro');
    const docB = uniqueDocName('pp-retro');
    const entryA = pool.open(docA);
    const entryB = pool.open(docB);
    if (!entryA || !entryB) throw new Error('expected entries');
    expect(entryA.persistence).toBeNull();
    expect(entryB.persistence).toBeNull();

    pool.setExpectedServerInstanceId('server-retro-attach');

    if (entryA.kind !== 'active' || entryB.kind !== 'active') {
      throw new Error('expected entries to remain active');
    }
    await awaitAttachedPersistence(entryA);
    await awaitAttachedPersistence(entryB);
    expect(entryA.persistence).not.toBeNull();
    expect(entryB.persistence).not.toBeNull();
    expect(typeof entryA.persistence?.destroy).toBe('function');
    expect(typeof entryA.persistence?.clearData).toBe('function');

    if (typeof indexedDB !== 'undefined') {
      await entryA.persistence?.whenSynced;
      await entryB.persistence?.whenSynced;
      const dbs = await indexedDB.databases();
      const names = new Set(dbs.map((d) => d.name).filter((n): n is string => n !== undefined));
      expect(names.has(`ok-ydoc:main:server-retro-attach:${docA}`)).toBe(true);
      expect(names.has(`ok-ydoc:main:server-retro-attach:${docB}`)).toBe(true);
      expect(names.has(`ok-ydoc:main:${docA}`)).toBe(false);
      expect(names.has(`ok-ydoc:main::${docA}`)).toBe(false);
    }
  });

  test('re-observing the live epoch leaves already-attached persistence alone', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-warm');
    const docName = uniqueDocName('pp-warm');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const persistenceBefore = await awaitAttachedPersistence(entry);

    pool.setExpectedServerInstanceId('server-warm');
    await wait(20);
    if (entry.kind !== 'active') throw new Error('expected entry to remain active');
    expect(entry.persistence).toBe(persistenceBefore);
  });

  test('observing a rotated epoch recycles the entry onto fresh persistence', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-warm');
    const docName = uniqueDocName('pp-rotate');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const persistenceBefore = await awaitAttachedPersistence(entry);

    pool.setExpectedServerInstanceId('server-warm-update');
    await pool.awaitMismatchSettled();

    const replaced = pool.entries.get(docName);
    expect(replaced?.provider).not.toBe(entry.provider);
    if (replaced !== undefined && replaced.kind === 'active' && replaced.persistence !== null) {
      expect(replaced.persistence).not.toBe(persistenceBefore);
    }
  });

  test('setExpectedServerInstanceId(null) does not detach already-attached persistence', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    pool.setExpectedServerInstanceId('server-warm');
    const docName = uniqueDocName('pp-no-detach');
    const entry = pool.open(docName);
    if (!entry) throw new Error('expected entry');
    const persistenceBefore = await awaitAttachedPersistence(entry);

    pool.setExpectedServerInstanceId(null);
    await wait(20);
    if (entry.kind !== 'active') throw new Error('expected entry to remain active');
    expect(entry.persistence).toBe(persistenceBefore);
  });

  test('dispose() drops the pending whenServerInstanceKnown handle', async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const pending = pool.whenServerInstanceKnown();
    pool.dispose();

    let settled = false;
    void pending.then(() => {
      settled = true;
    });
    await wait(10);
    expect(settled).toBe(false);

    pool = new ProviderPool(3, DUMMY_WS);
  });
});

describe('ProviderPool authenticationFailed: rename-redirect / doc-deleted', () => {
  const emit = (entry: { provider: unknown }, reason: string) => {
    (entry.provider as { emit: (e: string, p: unknown) => void }).emit('authenticationFailed', {
      reason,
    });
  };

  test("'rename-redirect:foo' parses payload and invokes onRenameRedirect", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const calls: { fromDocName: string; toDocName: string; hadOpenProvider: boolean }[] = [];
    pool.setOnRenameRedirect((args) => calls.push(args));
    const entry = pool.open('doc-from');
    if (!entry) throw new Error('expected entry');
    emit(entry, 'rename-redirect:doc-to');
    expect(calls).toEqual([
      { fromDocName: 'doc-from', toDocName: 'doc-to', hadOpenProvider: true },
    ]);
  });

  test("'rename-redirect' with payload containing colon round-trips on first colon only", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const calls: { toDocName: string }[] = [];
    pool.setOnRenameRedirect((args) => calls.push({ toDocName: args.toDocName }));
    const entry = pool.open('a');
    if (!entry) throw new Error('expected entry');
    emit(entry, 'rename-redirect:has:colon/in/path');
    expect(calls[0]?.toDocName).toBe('has:colon/in/path');
  });

  test("'rename-redirect' with empty payload warns and skips cleanup", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let cleanupCalled = 0;
    pool.setOnRenameRedirect(() => {
      cleanupCalled++;
    });
    const warns: string[] = [];
    const orig = console.warn;
    console.warn = (msg: unknown) => warns.push(String(msg));
    try {
      const entry = pool.open('doc-x');
      if (!entry) throw new Error('expected entry');
      emit(entry, 'rename-redirect');
      emit(entry, 'rename-redirect:');
    } finally {
      console.warn = orig;
    }
    expect(cleanupCalled).toBe(0);
    const matched = warns.filter((w) => w.includes('rename-redirect-missing-payload'));
    expect(matched.length).toBe(2);
  });

  test("'doc-deleted' invokes onDocDeleted with hadOpenProvider true when entry is active", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const calls: { docName: string; hadOpenProvider: boolean }[] = [];
    pool.setOnDocDeleted((args) => calls.push(args));
    const entry = pool.open('doc-z');
    if (!entry) throw new Error('expected entry');
    emit(entry, 'doc-deleted');
    expect(calls).toEqual([{ docName: 'doc-z', hadOpenProvider: true }]);
  });

  test("server-driven 'close' triggers a fresh sendToken so onAuthenticate can re-run", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-close');
    if (!entry) throw new Error('expected entry');
    const provider = entry.provider as {
      sendToken: () => Promise<void>;
      emit: (e: string, p: unknown) => void;
    };
    const sendTokenSpy = vi.spyOn(provider, 'sendToken').mockResolvedValue();
    sendTokenSpy.mockClear();
    provider.emit('close', { event: { code: 1000, reason: 'Server closed the connection' } });
    expect(sendTokenSpy).toHaveBeenCalledTimes(1);
  });

  test("server-driven 'close' followed by sendToken rejection emits a structured warn", async () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-warn');
    if (!entry) throw new Error('expected entry');
    const provider = entry.provider as {
      sendToken: () => Promise<void>;
      emit: (e: string, p: unknown) => void;
    };
    const sendTokenSpy = vi
      .spyOn(provider, 'sendToken')
      .mockRejectedValue(new Error('synthetic transport-closed failure'));
    sendTokenSpy.mockClear();
    const warns: string[] = [];
    const originalWarn = console.warn;
    console.warn = (...args: unknown[]): void => {
      warns.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '));
    };
    try {
      provider.emit('close', { event: { code: 1000, reason: 'rename-driven' } });
      await waitFor(
        () => warns.some((w) => w.includes('ok-provider-server-driven-close-reauth-failed')),
        500,
      );
      const matched = warns.filter((w) =>
        w.includes('ok-provider-server-driven-close-reauth-failed'),
      );
      expect(matched.length).toBeGreaterThanOrEqual(1);
      expect(matched[0]).toContain('"docName":"doc-warn"');
      expect(matched[0]).toContain('synthetic transport-closed failure');
    } finally {
      console.warn = originalWarn;
    }
  });

  test("burst of server-driven 'close' frames during in-flight sendToken does not stack parallel auths", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-burst');
    if (!entry) throw new Error('expected entry');
    const provider = entry.provider as {
      sendToken: () => Promise<void>;
      emit: (e: string, p: unknown) => void;
    };
    const neverResolve = new Promise<void>(() => {});
    const sendTokenSpy = vi.spyOn(provider, 'sendToken').mockReturnValue(neverResolve);
    sendTokenSpy.mockClear();
    provider.emit('close', { event: { code: 1000, reason: 'first' } });
    provider.emit('close', { event: { code: 1000, reason: 'second' } });
    provider.emit('close', { event: { code: 1000, reason: 'third' } });
    expect(sendTokenSpy).toHaveBeenCalledTimes(1);
  });

  test("'rename-redirect' / 'doc-deleted' with no handler set are clean no-ops", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    const entry = pool.open('doc-a');
    if (!entry) throw new Error('expected entry');
    expect(() => emit(entry, 'rename-redirect:doc-b')).not.toThrow();
    expect(() => emit(entry, 'doc-deleted')).not.toThrow();
  });

  test("existing 'server-instance-mismatch' arm is unchanged by the new arms", () => {
    pool = new ProviderPool(3, DUMMY_WS);
    let renameRedirectCalls = 0;
    let docDeletedCalls = 0;
    pool.setOnRenameRedirect(() => {
      renameRedirectCalls++;
    });
    pool.setOnDocDeleted(() => {
      docDeletedCalls++;
    });
    pool.setExpectedServerInstanceId('old-instance-id');
    const entry = pool.open('doc-svr');
    if (!entry) throw new Error('expected entry');
    emit(entry, 'server-instance-mismatch');
    expect(renameRedirectCalls).toBe(0);
    expect(docDeletedCalls).toBe(0);
  });
});