Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

28.3 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, describe, expect, test, vi } from 'vitest';
import type * as Y from 'yjs';
import { applyAgentMarkdownWrite } from '../../../server/src/agent-sessions';
import { DerivedDocumentIndex } from '../../../server/src/derived-document-index';
import * as diskContentIntake from '../../../server/src/disk-content-intake';
import { _resetDocExtensionsForTests } from '../../../server/src/doc-extensions';
import * as fsTraced from '../../../server/src/fs-traced';
import { getMetrics } from '../../../server/src/metrics';
import { contentHash } from '../../../server/src/version-hash';
import { createManualClock } from '../../../server/src/watcher-clock.test-helper';
import { createWatcherDouble } from '../../../server/src/watcher-double.test-helper';
import {
  createTestClient,
  createTestServer,
  pollUntil,
  type TestClient,
  type TestServer,
} from './test-harness';

const SEED = '# Doc\n\nfirst paragraph\n\nsecond paragraph\n';

let server: TestServer | undefined;
let client: TestClient | undefined;
const ownedDirs: string[] = [];

afterEach(async () => {
  vi.restoreAllMocks();
  delete process.env.OK_TEST_COMPARE_READ_FAULT;
  delete process.env.OK_TEST_STORE_RESTAT_RACE;
  delete process.env.OK_TEST_STORE_FAULT;
  await client?.cleanup();
  client = undefined;
  await server?.cleanup();
  server = undefined;
  for (const dir of ownedDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});

function compareCount(outcome: string): number {
  return (getMetrics().storeDiskCompare as Record<string, number | undefined>)[outcome] ?? 0;
}

async function startWithDoc(
  options: Parameters<typeof createTestServer>[0] = {},
): Promise<{ server: TestServer; docName: string; file: string }> {
  const started = await createTestServer({
    watcherBackend: createWatcherDouble().backend,
    debounce: 50,
    maxDebounce: 200,
    ...options,
  });
  server = started;
  const docName = `receipt-${randomUUID()}`;
  const file = join(started.contentDir, `${docName}.md`);
  writeFileSync(file, SEED);
  return { server: started, docName, file };
}

async function openClient(
  port: number,
  docName: string,
  options?: Parameters<typeof createTestClient>[2],
): Promise<TestClient> {
  client = await createTestClient(port, docName, options);
  const opened = client;
  await pollUntil(() => opened.ytext.toString() === SEED, 5_000, 25, 'the seeded document');
  return opened;
}

function typeAfter(doc: Y.Doc, text: Y.Text, anchor: string, insertion: string): void {
  const at = text.toString().indexOf(anchor);
  if (at < 0) throw new Error(`anchor not found: ${anchor}`);
  doc.transact(() => text.insert(at + anchor.length, insertion));
}

function serverText(target: TestServer, docName: string): string | undefined {
  return target.instance.hocuspocus.documents.get(docName)?.getText('source').toString();
}

async function expectDiskAndLiveToSettleOn(
  target: TestServer,
  docName: string,
  file: string,
  expected: string,
): Promise<void> {
  await pollUntil(
    () => readFileSync(file, 'utf-8') === expected,
    8_000,
    25,
    'the merged bytes on disk',
  );
  await pollUntil(() => serverText(target, docName) === expected, 5_000, 25, 'the live text');
  expect(target.instance.durabilityState.getReceipt(docName)?.hash).toBe(contentHash(expected));
}

describe('compare before every Markdown write', () => {
  test('a person save over an outside edit in another block merges both, byte for byte', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const changedBefore = compareCount('changed');

    writeFileSync(file, '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n');
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph typed here\n',
    );
    expect(compareCount('changed')).toBeGreaterThan(changedBefore);
  });

  test('an outside change the bridge normalizer would tolerate is kept, not written over', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);

    writeFileSync(file, '# Doc\n\nfirst paragraph   \n\nsecond paragraph\n');
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph   \n\nsecond paragraph typed here\n',
    );
  });

  test('an agent store over an outside change its pre-write merge skipped merges it first', async () => {
    const { server: s, docName, file } = await startWithDoc();
    await openClient(s.port, docName);

    writeFileSync(file, '# Doc\n\nfirst paragraph   \n\nsecond paragraph\n');
    const response = await fetch(`http://127.0.0.1:${s.port}/api/agent-write-md`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ docName, markdown: '\nagent line\n', position: 'append' }),
    });
    expect(response.status).toBe(200);

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph   \n\nsecond paragraph\n\nagent line\n',
    );
  });

  test('the staleness watchdog forces a store that merges an outside edit instead of standing down', async () => {
    const {
      server: s,
      docName,
      file,
    } = await startWithDoc({
      stalenessGraceMs: 250,
      stalenessSweepIntervalMs: 100,
    });
    await openClient(s.port, docName);
    const forcedBefore = getMetrics().persistenceStalenessForcedStores;

    process.env.OK_TEST_STORE_FAULT = docName;
    const failed = await fetch(`http://127.0.0.1:${s.port}/api/agent-write-md`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ docName, markdown: '\nagent line\n', position: 'append' }),
    });
    expect(failed.status).toBe(507);
    delete process.env.OK_TEST_STORE_FAULT;
    writeFileSync(file, '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n\nagent line\n',
    );
    expect(getMetrics().persistenceStalenessForcedStores).toBeGreaterThan(forcedBefore);
  });

  test('a whole-document agent replace saved by the ordinary store merges an outside edit', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const session = await s.instance.sessionManager.getSession(docName, 'acp-replace', {
      displayName: 'ACP agent',
      colorSeed: 'acp-replace',
      clientName: 'acp',
    });
    await pollUntil(
      () => serverText(s, docName) === SEED,
      5_000,
      25,
      'the session to load the document',
    );

    writeFileSync(file, '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n');
    session.dc.document.transact(() => {
      applyAgentMarkdownWrite(
        session.dc.document,
        '# Doc\n\nfirst paragraph\n\nsecond paragraph rewritten by the agent\n',
        'replace',
      );
    }, session.origin);

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph rewritten by the agent\n',
    );
  });

  test('the shutdown flush merges an outside edit into the pending save', async () => {
    const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-receipt-shutdown-')));
    ownedDirs.push(contentDir);
    const {
      server: s,
      docName,
      file,
    } = await startWithDoc({
      contentDir,
      keepContentDir: true,
      debounce: 60_000,
      maxDebounce: 120_000,
    });
    await s.instance.hocuspocus.openDirectConnection(docName);
    const live = s.instance.hocuspocus.documents.get(docName);
    if (!live) throw new Error('document not loaded');
    await pollUntil(() => live.getText('source').toString() === SEED, 5_000, 25, 'the load');

    typeAfter(live, live.getText('source'), 'second paragraph', ' typed here');
    writeFileSync(file, '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n');
    expect(readFileSync(file, 'utf-8')).not.toContain('typed here');

    await s.cleanup();
    server = undefined;

    expect(readFileSync(file, 'utf-8')).toBe(
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph typed here\n',
    );
  });

  test('a change made while the server was stopped is found at load from the persisted receipt', async () => {
    const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-receipt-restart-')));
    ownedDirs.push(contentDir);
    const first = await startWithDoc({ contentDir, keepContentDir: true });
    const c = await openClient(first.server.port, first.docName, { resetOnCleanup: false });
    typeAfter(c.doc, c.ytext, 'second paragraph', ' saved before quitting');
    const saved = '# Doc\n\nfirst paragraph\n\nsecond paragraph saved before quitting\n';
    await pollUntil(() => readFileSync(first.file, 'utf-8') === saved, 8_000, 25, 'the save');
    await c.cleanup();
    client = undefined;
    await first.server.cleanup();
    server = undefined;

    const receiptLog = readFileSync(join(contentDir, '.ok', 'local', 'receipts.jsonl'), 'utf-8');
    expect(receiptLog).toContain(contentHash(saved));

    const editedWhileStopped =
      '# Doc\n\nfirst paragraph edited while stopped\n\nsecond paragraph saved before quitting\n';
    writeFileSync(first.file, editedWhileStopped);
    const changedAtLoadBefore = getMetrics().receiptAtLoad.changed ?? 0;
    const mergesBefore = compareCount('changed');

    server = await createTestServer({
      contentDir,
      keepContentDir: true,
      watcherBackend: createWatcherDouble().backend,
      debounce: 50,
      maxDebounce: 200,
    });
    client = await createTestClient(server.port, first.docName);
    const reopened = client;
    await pollUntil(
      () => reopened.ytext.toString() === editedWhileStopped,
      5_000,
      25,
      'the disk version at load',
    );
    expect(getMetrics().receiptAtLoad.changed ?? 0).toBe(changedAtLoadBefore + 1);
    expect(server.instance.durabilityState.getReconciledBase(first.docName)).toBe(
      editedWhileStopped,
    );

    typeAfter(reopened.doc, reopened.ytext, 'saved before quitting', ' and after');
    const final =
      '# Doc\n\nfirst paragraph edited while stopped\n\nsecond paragraph saved before quitting and after\n';
    await expectDiskAndLiveToSettleOn(server, first.docName, first.file, final);
    expect(compareCount('changed')).toBe(mergesBefore);
  });

  test('an .mdx receipt survives a cold restart, counts a change made while stopped and recognises a late echo', async () => {
    const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-receipt-mdx-restart-')));
    ownedDirs.push(contentDir);
    const docName = `receipt-mdx-${randomUUID()}`;
    const file = join(contentDir, `${docName}.mdx`);
    writeFileSync(file, SEED);
    server = await createTestServer({
      contentDir,
      keepContentDir: true,
      watcherBackend: createWatcherDouble().backend,
      debounce: 50,
      maxDebounce: 200,
    });
    const first = await openClient(server.port, docName, { resetOnCleanup: false });
    typeAfter(first.doc, first.ytext, 'second paragraph', ' saved before quitting');
    const saved = '# Doc\n\nfirst paragraph\n\nsecond paragraph saved before quitting\n';
    await pollUntil(() => readFileSync(file, 'utf-8') === saved, 8_000, 25, 'the save');
    await first.cleanup();
    client = undefined;
    await server.cleanup();
    server = undefined;

    const edited =
      '# Doc\n\nfirst paragraph edited while stopped\n\nsecond paragraph saved before quitting\n';
    writeFileSync(file, edited);
    _resetDocExtensionsForTests();
    const changedBefore = getMetrics().receiptAtLoad.changed ?? 0;
    const clock = createManualClock(Date.now());
    const double = createWatcherDouble();
    server = await createTestServer({
      contentDir,
      keepContentDir: true,
      watcherBackend: double.backend,
      watcherClock: clock,
      debounce: 50,
      maxDebounce: 200,
    });
    const restarted = server;
    await new Promise((resolve) => setImmediate(resolve));
    client = await createTestClient(restarted.port, docName);
    const reopened = client;
    await pollUntil(() => reopened.ytext.toString() === edited, 5_000, 25, 'the load');
    expect(getMetrics().receiptAtLoad.changed ?? 0).toBe(changedBefore + 1);

    typeAfter(reopened.doc, reopened.ytext, 'quitting', ' and after');
    const final =
      '# Doc\n\nfirst paragraph edited while stopped\n\nsecond paragraph saved before quitting and after\n';
    await pollUntil(
      () => readFileSync(file, 'utf-8') === final,
      8_000,
      25,
      'the save after restart',
    );
    clock.advance(25_000);
    const echoesBefore = getMetrics().receiptIntakeSkip.echo ?? 0;
    double.subscriptionFor(restarted.contentDir).deliver([{ type: 'update', path: file }]);
    await pollUntil(
      () => {
        clock.advance(50);
        return (getMetrics().receiptIntakeSkip.echo ?? 0) > echoesBefore;
      },
      5_000,
      25,
      'the late echo to reach the intake',
    );
    expect(readFileSync(join(contentDir, '.ok', 'local', 'receipts.jsonl'), 'utf-8')).toContain(
      contentHash(final),
    );
  });

  test('a store whose merge of the outside edit fails to apply holds the save and never writes over the outside bytes', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const outside = '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n';
    const realApply = diskContentIntake.applyDiskContentToDoc;
    vi.spyOn(diskContentIntake, 'applyDiskContentToDoc').mockImplementation((...args) => {
      if (args[1].includes('changed outside')) throw new Error('injected apply failure');
      return realApply(...args);
    });
    const heldBefore = compareCount('pending-intake-failed');

    writeFileSync(file, outside);
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await pollUntil(
      () => compareCount('pending-intake-failed') > heldBefore,
      8_000,
      25,
      'the held save',
    );
    expect(readFileSync(file, 'utf-8')).toBe(outside);
    expect(serverText(s, docName)).toContain('typed here');
    expect(serverText(s, docName)).not.toContain('changed outside');
    expect(s.instance.durabilityState.getReceipt(docName)?.hash).not.toBe(contentHash(outside));
    expect(s.instance.durabilityState.isStoreRefused(docName)).toBe(true);

    vi.restoreAllMocks();
    typeAfter(c.doc, c.ytext, 'typed here', ' and again');
    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph typed here and again\n',
    );
  });

  test('a save with no agreed version whose ingest of the outside file fails is held and leaves no receipt for the outside bytes', async () => {
    const started = await createTestServer({
      watcherBackend: createWatcherDouble().backend,
      debounce: 300_000,
      maxDebounce: 600_000,
    });
    server = started;
    const docName = `receipt-no-base-${randomUUID()}`;
    const file = join(started.contentDir, `${docName}.md`);
    client = await createTestClient(started.port, docName);
    const c = client;
    c.doc.transact(() => c.ytext.insert(0, '# Typed\n\nbefore the file existed\n'));
    await pollUntil(
      () => serverText(started, docName)?.includes('before the file existed') === true,
      5_000,
      25,
      'the typing to reach the server',
    );
    const outside = '# Doc\n\ncreated outside\n';
    writeFileSync(file, outside);
    const realApply = diskContentIntake.applyDiskContentToDoc;
    vi.spyOn(diskContentIntake, 'applyDiskContentToDoc').mockImplementation((...args) => {
      if (args[1].includes('created outside')) throw new Error('injected apply failure');
      return realApply(...args);
    });
    const heldBefore = compareCount('pending-intake-failed-no-base');

    await runPendingStore(started, docName).catch(() => undefined);

    expect(compareCount('pending-intake-failed-no-base')).toBe(heldBefore + 1);
    expect(readFileSync(file, 'utf-8')).toBe(outside);
    expect(started.instance.durabilityState.getReceipt(docName)).toBeUndefined();
    expect(started.instance.durabilityState.getReconciledBase(docName)).toBeUndefined();
    expect(serverText(started, docName)).toContain('before the file existed');

    vi.restoreAllMocks();
    c.doc.transact(() => c.ytext.insert(c.ytext.length, '\nmore typing\n'));
    await pollUntil(
      () => serverText(started, docName)?.includes('more typing') === true,
      5_000,
      25,
      'the second edit to reach the server',
    );
    await runPendingStore(started, docName).catch(() => undefined);
    await pollUntil(() => serverText(started, docName) === outside, 5_000, 25, 'the ingest');
    expect(readFileSync(file, 'utf-8')).toBe(outside);
    expect(started.instance.durabilityState.getReceipt(docName)?.hash).toBe(contentHash(outside));
  });

  test('an outside file the intake raises a conflict for holds the save once as a conflict, not as a file that kept changing', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const conflictsBefore = getMetrics().conflictCount;
    const heldBefore = compareCount('pending-conflict');
    const exhaustedBefore = compareCount('pending-exhausted');
    const marked =
      '# Doc\n\n<<<<<<< HEAD\nfirst paragraph\n=======\nfirst paragraph elsewhere\n>>>>>>> other\n\nsecond paragraph\n';

    writeFileSync(file, marked);
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await pollUntil(
      () => compareCount('pending-conflict') > heldBefore,
      8_000,
      25,
      'the held save',
    );
    expect(compareCount('pending-exhausted')).toBe(exhaustedBefore);
    expect(getMetrics().conflictCount).toBe(conflictsBefore + 1);
    expect(s.instance.conflicts.findByDocName(docName)).toBeDefined();
    expect(readFileSync(file, 'utf-8')).toBe(marked);
    expect(serverText(s, docName)).toContain('typed here');
  });

  test('an index failure after the outside edit was taken in does not hold the save', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const heldBefore = compareCount('pending-intake-failed');
    const outside = '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph\n';
    const realUpsert = DerivedDocumentIndex.prototype.recordDiskUpsert;
    vi.spyOn(DerivedDocumentIndex.prototype, 'recordDiskUpsert').mockImplementation(function (
      this: DerivedDocumentIndex,
      documentName,
      markdown,
    ) {
      if (documentName === docName && markdown === outside) {
        return Promise.reject(new Error('injected index failure'));
      }
      return realUpsert.call(this, documentName, markdown);
    });

    writeFileSync(file, outside);
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph changed outside\n\nsecond paragraph typed here\n',
    );
    expect(compareCount('pending-intake-failed')).toBe(heldBefore);
  });

  test('a file that keeps changing across every run holds the save with the file untouched and the edit kept', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const exhaustedBefore = compareCount('pending-exhausted');
    let outsideWrites = 0;
    const realWrite = fsTraced.tracedWriteFile;
    vi.spyOn(fsTraced, 'tracedWriteFile').mockImplementation(async (...args) => {
      await realWrite(...args);
      if (!String(args[0]).startsWith(`${file}.tmp.`)) return;
      outsideWrites++;
      writeFileSync(file, `# Doc\n\noutside write ${outsideWrites}\n\nsecond paragraph\n`);
    });

    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await pollUntil(
      () => compareCount('pending-exhausted') > exhaustedBefore,
      8_000,
      25,
      'the exhausted save',
    );
    expect(readFileSync(file, 'utf-8')).toBe(
      `# Doc\n\noutside write ${outsideWrites}\n\nsecond paragraph\n`,
    );
    expect(serverText(s, docName)).toContain('typed here');
    expect(s.instance.durabilityState.isStoreRefused(docName)).toBe(true);
  });

  test('an echo of our own save delivered after the tracker window is recognised by the receipt', async () => {
    const clock = createManualClock(Date.now());
    const double = createWatcherDouble();
    const {
      server: s,
      docName,
      file,
    } = await startWithDoc({
      watcherBackend: double.backend,
      watcherClock: clock,
    });
    const c = await openClient(s.port, docName);
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');
    const saved = '# Doc\n\nfirst paragraph\n\nsecond paragraph typed here\n';
    await pollUntil(() => readFileSync(file, 'utf-8') === saved, 8_000, 25, 'the save');

    clock.advance(25_000);
    const echoesBefore = getMetrics().receiptIntakeSkip.echo ?? 0;
    const reconcilesBefore = getMetrics().reconcileCount;
    double.subscriptionFor(s.contentDir).deliver([{ type: 'update', path: file }]);
    await pollUntil(
      () => {
        clock.advance(50);
        return (getMetrics().receiptIntakeSkip.echo ?? 0) > echoesBefore;
      },
      5_000,
      25,
      'the late echo to reach the intake',
    );

    expect(getMetrics().reconcileCount).toBe(reconcilesBefore);
    expect(serverText(s, docName)).toBe(saved);
    expect(readFileSync(file, 'utf-8')).toBe(saved);
  });

  test('a compare read that is briefly busy is retried and the save lands', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const retriesBefore = getMetrics().storeDiskCompareReadRetries;

    process.env.OK_TEST_COMPARE_READ_FAULT = `${docName}:EBUSY:2`;
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph\n\nsecond paragraph typed here\n',
    );
    expect(getMetrics().storeDiskCompareReadRetries).toBe(retriesBefore + 2);
  });

  test('a compare read that stays busy leaves the save pending and the file untouched', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const pendingBefore = compareCount('pending-unreadable');

    process.env.OK_TEST_COMPARE_READ_FAULT = `${docName}:EBUSY:1000`;
    typeAfter(c.doc, c.ytext, 'second paragraph', ' typed here');

    await pollUntil(
      () => compareCount('pending-unreadable') > pendingBefore,
      8_000,
      25,
      'the pending save',
    );
    expect(readFileSync(file, 'utf-8')).toBe(SEED);
    expect(serverText(s, docName)).toContain('typed here');
    expect(s.instance.durabilityState.isStoreRefused(docName)).toBe(true);
  });

  test('a write that lands between the compare and the rename is refused and merged on the next run', async () => {
    const { server: s, docName, file } = await startWithDoc();
    const c = await openClient(s.port, docName);
    const refusedBefore = getMetrics().storeRestatRefused;

    process.env.OK_TEST_STORE_RESTAT_RACE = docName;
    typeAfter(c.doc, c.ytext, 'first paragraph', ' typed here');

    await expectDiskAndLiveToSettleOn(
      s,
      docName,
      file,
      '# Doc\n\nfirst paragraph typed here\n\nsecond paragraph\n\nrestat-race-injected\n',
    );
    expect(getMetrics().storeRestatRefused).toBe(refusedBefore + 1);
  });
});

interface HistoryVersion {
  side: string;
  content: string;
}

async function historyVersions(
  target: TestServer,
  docName: string,
  kind: string,
  count: number,
): Promise<HistoryVersion[]> {
  let rows: Array<{ sha: string; checkpoint?: { kind?: string; metadata?: { side?: string } } }> =
    [];
  await pollUntil(
    async () => {
      const res = await fetch(
        `http://127.0.0.1:${target.port}/api/history?docName=${encodeURIComponent(docName)}&limit=100`,
      );
      const body = (await res.json()) as { entries?: typeof rows };
      rows = (body.entries ?? []).filter((entry) => entry.checkpoint?.kind === kind);
      return rows.length >= count;
    },
    10_000,
    50,
    `${count} ${kind} history entries`,
  );
  const versions: HistoryVersion[] = [];
  for (const row of rows) {
    const res = await fetch(
      `http://127.0.0.1:${target.port}/api/history/${row.sha}?docName=${encodeURIComponent(docName)}`,
    );
    const body = (await res.json()) as { content: string };
    versions.push({ side: row.checkpoint?.metadata?.side ?? '', content: body.content });
  }
  return versions.sort((a, b) => a.side.localeCompare(b.side));
}

async function startWithUnsavedEdit(
  saved: string,
  edit: { find: string; replace: string },
): Promise<{ server: TestServer; docName: string; file: string }> {
  const started = await createTestServer({
    gitEnabled: true,
    watcherBackend: createWatcherDouble().backend,
    debounce: 300_000,
    maxDebounce: 600_000,
  });
  server = started;
  const docName = `receipt-collide-${randomUUID()}`;
  const file = join(started.contentDir, `${docName}.md`);
  writeFileSync(file, saved);
  client = await createTestClient(started.port, docName);
  const opened = client;
  await pollUntil(() => opened.ytext.toString() === saved, 5_000, 25, 'the seeded document');
  opened.doc.transact(() => {
    const at = opened.ytext.toString().indexOf(edit.find);
    opened.ytext.delete(at, edit.find.length);
    opened.ytext.insert(at, edit.replace);
  });
  await pollUntil(
    () => serverText(started, docName)?.includes(edit.replace) === true,
    5_000,
    25,
    'the unsaved edit to reach the server',
  );
  return { server: started, docName, file };
}

async function runPendingStore(target: TestServer, docName: string): Promise<void> {
  const id = `onStoreDocument-${docName}`;
  if (target.instance.hocuspocus.debouncer.isDebounced(id)) {
    await target.instance.hocuspocus.debouncer.executeNow(id);
  }
}

describe('compare before every Markdown write: an outside edit to the block being saved', () => {
  test('a person save keeps both versions of the block, live and on disk, and both originals in history', async () => {
    const saved = '# Doc\n\nShared paragraph.\n\nTail.\n';
    const {
      server: s,
      docName,
      file,
    } = await startWithUnsavedEdit(saved, {
      find: 'Shared paragraph.',
      replace: 'Shared paragraph, edited here.',
    });
    const bothKeptBefore = getMetrics().reconcileBothKept;
    const outside = '# Doc\n\nShared paragraph, edited outside.\n\nTail.\n';

    writeFileSync(file, outside);
    await runPendingStore(s, docName);

    const bothKept =
      '# Doc\n\nShared paragraph, edited here.\n\nShared paragraph, edited outside.\n\nTail.\n';
    await expectDiskAndLiveToSettleOn(s, docName, file, bothKept);
    expect(getMetrics().reconcileBothKept).toBe(bothKeptBefore + 1);
    expect(s.instance.conflicts.list()).toEqual([]);
    expect(await historyVersions(s, docName, 'external-change-both-kept', 2)).toEqual([
      { side: 'ours', content: '# Doc\n\nShared paragraph, edited here.\n\nTail.\n' },
      { side: 'theirs', content: outside },
    ]);
  });

  test('a person save whose merge fails the fidelity check keeps the version here and moves the outside version to history', async () => {
    const saved = '# Doc\n\nA\n\nB\n\nC\n';
    const {
      server: s,
      docName,
      file,
    } = await startWithUnsavedEdit(saved, {
      find: 'B\n\nC',
      replace: 'X\n\nB edited\n\nC',
    });
    const keptLiveBefore = getMetrics().reconcileKeptLive;
    const outside = '# Doc\n\nA\n\nX\n\nB\n\nC\n';

    writeFileSync(file, outside);
    await runPendingStore(s, docName);

    const here = '# Doc\n\nA\n\nX\n\nB edited\n\nC\n';
    await expectDiskAndLiveToSettleOn(s, docName, file, here);
    expect(getMetrics().reconcileKeptLive).toBe(keptLiveBefore + 1);
    expect(s.instance.conflicts.list()).toEqual([]);
    expect(await historyVersions(s, docName, 'external-change-kept-live', 1)).toEqual([
      { side: 'theirs', content: outside },
    ]);
  });
});