Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

68.0 KB
Raw Blame
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  statSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, expect, test, vi } from 'vitest';
import * as Y from 'yjs';
import { DiskReceiptLog } from './disk-receipts.ts';
import {
  _resetDocExtensionsForTests,
  docNameToRelativePath,
  isRegisteredMarkdownDocName,
  registerDocExtension,
} from './doc-extensions.ts';
import {
  DISPLACED_VERSION_LIMIT,
  DISPLACED_VERSION_TTL_MS,
  DocumentDurabilityState,
  DocumentDurabilityStateError,
  editWasCarried,
  type StorePublishOutcome,
  WRITE_WAIT_BUDGET_MS,
  writtenThroughOf,
} from './document-durability-state.ts';
import * as tracedFs from './fs-traced.ts';
import { getLogger } from './logger.ts';
import { getMetrics, resetMetrics } from './metrics.ts';
import { contentHash } from './version-hash.ts';

describe('the merge a store recorded for agent writes', () => {
  const at = (clock: number) => ({ clientId: 7, clock });

  test('reaches every write the store carried, not only the first flush that reads it', () => {
    const state = new DocumentDurabilityState();
    state.recordStoreIntake('doc', 'both-kept', at(10));

    expect(state.readStoreIntake('doc', at(4))).toBe('both-kept');
    expect(state.readStoreIntake('doc', at(9))).toBe('both-kept');
  });

  test('never reaches a write that an earlier store did not carry', () => {
    const state = new DocumentDurabilityState();
    state.recordStoreIntake('doc', 'both-kept', at(5));
    state.recordStoreIntake('doc', 'merged', at(12));

    expect(state.readStoreIntake('doc', at(8))).toBe('merged');
    expect(state.readStoreIntake('doc', at(13))).toBeUndefined();
    expect(state.readStoreIntake('doc', { clientId: 8, clock: 1 })).toBeUndefined();
  });

  test('is cleared with the rest of the document state', () => {
    const state = new DocumentDurabilityState();
    state.recordStoreIntake('doc', 'kept-live', at(10));
    state.deleteReconciledBase('doc');

    expect(state.readStoreIntake('doc', at(4))).toBeUndefined();
  });
});

describe('DocumentDurabilityState', () => {
  test('starts with an empty main scope and no transient coordination state', () => {
    const state = new DocumentDurabilityState();

    expect(state.getActiveBranch()).toBe('main');
    expect(state.getReconciledBase('doc')).toBeUndefined();
    expect(state.peekInFlightFlush('doc')).toBeUndefined();
    expect(state.isBatchInProgress()).toBe(false);
    expect(state.consumeAgentWriteStore('doc')).toBe(false);
    expect(state.takeStoreFailure('doc')).toBeNull();
  });

  test('records receipts for a document without giving it a reconciled base', () => {
    const state = new DocumentDurabilityState('main', { receipts: new DiskReceiptLog() });
    state.recordReceiptAgreed('flow.mmd', 'graph TD\n');
    expect(state.getReceipt('flow.mmd')).toMatchObject({ via: 'agreed' });
    state.recordReceiptOwnWrite('flow.mmd', 'graph LR\n');
    expect(state.getReceipt('flow.mmd')).toMatchObject({ via: 'own-write' });
    expect(state.isRecentOwnWrite('flow.mmd', contentHash('graph LR\n'))).toBe(true);
    expect(state.getReconciledBase('flow.mmd')).toBeUndefined();
  });

  test('a batch held by two owners lasts until both release it, and only the last release ends it', () => {
    const state = new DocumentDurabilityState();
    state.holdBatch('head-watcher');
    state.holdBatch('sync-engine');
    state.holdBatch('sync-engine');

    expect(state.releaseBatch('conflict-resolve')).toBe(false);
    expect(state.isBatchInProgress()).toBe(true);
    expect(state.releaseBatch('sync-engine')).toBe(false);
    expect(state.isBatchInProgress()).toBe(true);
    expect(state.releaseBatch('head-watcher')).toBe(true);
    expect(state.isBatchInProgress()).toBe(false);
    expect(state.releaseBatch('head-watcher')).toBe(false);
  });

  test('keeps one reconciled base across branch switches, the bytes last agreed with disk', () => {
    const state = new DocumentDurabilityState();
    state.setReconciledBase('doc', 'main bytes');
    state.switchReconciledBaseScope('feature');
    expect(state.getReconciledBase('doc')).toBe('main bytes');

    state.setReconciledBase('doc', 'feature bytes');
    state.switchReconciledBaseScope('main');
    expect(state.getReconciledBase('doc')).toBe('feature bytes');
  });

  test('a base deleted on one branch stays deleted after a switch', () => {
    const state = new DocumentDurabilityState();
    state.setReconciledBase('doc', 'main bytes');
    state.switchReconciledBaseScope('feature');
    state.deleteReconciledBase('doc');

    state.switchReconciledBaseScope('main');
    expect(state.getReconciledBase('doc')).toBeUndefined();
  });

  test('a document with a stale external write on the target branch keeps that branch base', () => {
    const state = new DocumentDurabilityState();
    state.switchReconciledBaseScope('feature');
    state.setReconciledBase('doc', 'feature acknowledged');
    state.recordStaleExternalWrite('doc', 'stale bytes');
    state.switchReconciledBaseScope('main');
    state.setReconciledBase('doc', 'main bytes');

    state.switchReconciledBaseScope('feature');
    expect(state.getReconciledBase('doc')).toBe('feature acknowledged');
  });

  test('isolates every owned coordination channel between instances', async () => {
    const first = new DocumentDurabilityState();
    const second = new DocumentDurabilityState();
    first.setReconciledBase('doc', 'first');
    first.setBatchInProgress(true);
    first.beginInFlightFlush('doc', 'first flush');
    first.markAgentWriteStore('doc');
    first.recordStoreFailure('doc', { code: 'ENOSPC', message: 'full' });
    first.openDeferredStore('doc');

    expect(second.getReconciledBase('doc')).toBeUndefined();
    expect(second.isBatchInProgress()).toBe(false);
    expect(second.peekInFlightFlush('doc')).toBeUndefined();
    expect(second.consumeAgentWriteStore('doc')).toBe(false);
    expect(second.takeStoreFailure('doc')).toBeNull();
    await expect(second.awaitDeferredStoreOutcome('doc')).resolves.toBeUndefined();
  });

  test('holds writes until every admission hold is released', async () => {
    const state = new DocumentDurabilityState();
    await expect(state.whenWriteAdmitted()).resolves.toBe(true);

    state.setBatchInProgress(true);
    await expect(state.whenWriteAdmitted()).resolves.toBe(true);

    const releaseBranchSwitch = state.holdWriteAdmission();
    const releaseOverlapping = state.holdWriteAdmission();
    let settled = false;
    const waiting = state.whenWriteAdmitted().then((result) => {
      settled = true;
      return result;
    });
    await new Promise((resolve) => setTimeout(resolve, 0));
    expect(settled).toBe(false);

    releaseOverlapping();
    releaseOverlapping();
    state.setBatchInProgress(false);
    await new Promise((resolve) => setTimeout(resolve, 0));
    expect(settled).toBe(false);

    releaseBranchSwitch();
    await expect(waiting).resolves.toBe(true);
    expect(state.isWriteAdmissionHeld()).toBe(false);
  });

  test('stops waiting for admission once the bound elapses', async () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.holdWriteAdmission();
      let result: boolean | undefined;
      const waiting = state.whenWriteAdmitted().then((admitted) => {
        result = admitted;
      });

      await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);
      expect(result).toBeUndefined();
      await vi.advanceTimersByTimeAsync(1);
      await waiting;

      expect(result).toBe(false);
      expect(state.isWriteAdmissionHeld()).toBe(true);
    } finally {
      vi.useRealTimers();
    }
  });

  test('bounds every wait inside one write budget by that budget together', async () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.holdWriteAdmission();
      state.openDeferredStore('doc');
      let finishedAt: number | undefined;
      const started = Date.now();
      const waits = state.runWithinWriteWaitBudget(async () => {
        const admitted = await state.whenWriteAdmitted();
        const outcome = await state.awaitDeferredStoreOutcome('doc');
        const admittedAgain = await state.whenWriteAdmitted();
        finishedAt = Date.now();
        return { admitted, outcome, admittedAgain };
      });

      await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);
      expect(finishedAt).toBeUndefined();
      await vi.advanceTimersByTimeAsync(1);

      await expect(waits).resolves.toEqual({
        admitted: false,
        outcome: { kind: 'unsettled' },
        admittedAgain: false,
      });
      expect(finishedAt).toBe(started + WRITE_WAIT_BUDGET_MS);
    } finally {
      vi.useRealTimers();
    }
  });

  test('does not wait for a deferred store while no admission hold is active', async () => {
    const state = new DocumentDurabilityState();
    state.setBatchInProgress(true);
    state.openDeferredStore('doc');
    await expect(state.awaitDeferredStoreOutcome('doc')).resolves.toBeUndefined();
  });

  test('reports the outcome of the latest deferred store for a document', async () => {
    const state = new DocumentDurabilityState();
    state.holdWriteAdmission();
    await expect(state.awaitDeferredStoreOutcome('doc')).resolves.toBeUndefined();

    const earlier = state.openDeferredStore('doc');
    const earlierOutcome = state.awaitDeferredStoreOutcome('doc');
    const later = state.openDeferredStore('doc');
    const laterOutcome = state.awaitDeferredStoreOutcome('doc');

    earlier.settle({ kind: 'completed' });
    await expect(earlierOutcome).resolves.toEqual({ kind: 'completed' });
    const stillPending = state.awaitDeferredStoreOutcome('doc');

    later.settle({ kind: 'discarded' });
    await expect(laterOutcome).resolves.toEqual({ kind: 'discarded' });
    await expect(stillPending).resolves.toEqual({ kind: 'discarded' });
    await expect(state.awaitDeferredStoreOutcome('doc')).resolves.toBeUndefined();
  });

  test('reports a deferred store that has not settled within the bound as unsettled', async () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.holdWriteAdmission();
      state.openDeferredStore('doc');
      let result: unknown;
      const waiting = state.awaitDeferredStoreOutcome('doc').then((outcome) => {
        result = outcome;
      });

      await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);
      expect(result).toBeUndefined();
      await vi.advanceTimersByTimeAsync(1);
      await waiting;

      expect(result).toEqual({ kind: 'unsettled' });
    } finally {
      vi.useRealTimers();
    }
  });

  test('reports a discard that lands within the bound', async () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.holdWriteAdmission();
      const deferral = state.openDeferredStore('doc');
      const waiting = state.awaitDeferredStoreOutcome('doc');

      await vi.advanceTimersByTimeAsync(WRITE_WAIT_BUDGET_MS - 1);
      deferral.settle({ kind: 'discarded' });

      await expect(waiting).resolves.toEqual({ kind: 'discarded' });
      expect(vi.getTimerCount()).toBe(0);
    } finally {
      vi.useRealTimers();
    }
  });

  test('does not let an older flush clear a newer in-flight snapshot', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'older');
    state.beginInFlightFlush('doc', 'newer');
    state.finishInFlightFlush('doc', 'older');
    expect(state.peekInFlightFlush('doc')).toBe('newer');
    state.finishInFlightFlush('doc', 'newer');
    expect(state.peekInFlightFlush('doc')).toBeUndefined();
  });

  test('consumes agent markers and failures once', () => {
    const state = new DocumentDurabilityState();
    state.markAgentWriteStore('doc');
    state.recordStoreFailure('doc', { message: 'write failed' });

    expect(state.consumeAgentWriteStore('doc')).toBe(true);
    expect(state.consumeAgentWriteStore('doc')).toBe(false);
    expect(state.takeStoreFailure('doc')).toEqual({ message: 'write failed' });
    expect(state.takeStoreFailure('doc')).toBeNull();
  });

  test('clears a store failure without consuming another document failure', () => {
    const state = new DocumentDurabilityState();
    state.recordStoreFailure('cleared', { code: 'ENOSPC', message: 'full' });
    state.recordStoreFailure('retained', { message: 'readonly' });

    state.clearStoreFailure('cleared');
    expect(state.takeStoreFailure('cleared')).toBeNull();
    expect(state.takeStoreFailure('retained')).toEqual({ message: 'readonly' });
  });
});

describe('in-flight flush queue semantics', () => {
  test('finishing one of two identical snapshots leaves the other pending', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'same');
    state.beginInFlightFlush('doc', 'same');
    state.finishInFlightFlush('doc', 'same');
    expect(state.inFlightFlushCount('doc')).toBe(1);
    expect(state.hasInFlightFlush('doc', 'same')).toBe(true);
    state.finishInFlightFlush('doc', 'same');
    expect(state.peekInFlightFlush('doc')).toBeUndefined();
    expect(state.inFlightFlushCount('doc')).toBe(0);
  });

  test('finishing a snapshot that was never begun leaves the queue untouched', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'real');
    state.finishInFlightFlush('doc', 'never-begun');
    expect(state.inFlightFlushCount('doc')).toBe(1);
    expect(state.hasInFlightFlush('doc', 'real')).toBe(true);
  });

  test('a middle entry can finish out of order without disturbing its neighbours', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'a');
    state.beginInFlightFlush('doc', 'b');
    state.beginInFlightFlush('doc', 'c');
    state.finishInFlightFlush('doc', 'b');
    expect(state.hasInFlightFlush('doc', 'a')).toBe(true);
    expect(state.hasInFlightFlush('doc', 'b')).toBe(false);
    expect(state.hasInFlightFlush('doc', 'c')).toBe(true);
    expect(state.peekInFlightFlush('doc')).toBe('c');
  });

  test('content absent from a populated queue does not match', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'a');
    state.beginInFlightFlush('doc', 'b');
    expect(state.hasInFlightFlush('doc', 'absent')).toBe(false);
    expect(state.hasInFlightFlush('other-doc', 'a')).toBe(false);
  });

  test('a leaked entry expires on read, with no later flush needed to sweep it', () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.beginInFlightFlush('doc', 'leaked');
      expect(state.peekInFlightFlush('doc')).toBe('leaked');

      vi.advanceTimersByTime(61_000);

      expect(state.peekInFlightFlush('doc')).toBeUndefined();
      expect(state.inFlightFlushCount('doc')).toBe(0);
      expect(state.hasInFlightFlush('doc', 'leaked')).toBe(false);
    } finally {
      vi.useRealTimers();
    }
  });

  test('deleting a doc clears its in-flight flush records alongside its reconciled base', () => {
    const state = new DocumentDurabilityState();
    state.setReconciledBase('doc', 'base');
    state.beginInFlightFlush('doc', 'pending');
    state.beginInFlightFlush('other', 'pending');

    state.deleteReconciledBase('doc');

    expect(state.getReconciledBase('doc')).toBeUndefined();
    expect(state.inFlightFlushCount('doc')).toBe(0);
    expect(state.inFlightFlushCount('other')).toBe(1);
  });

  test('switching branch scope leaves in-flight flush records alone, since a write in flight is not branch-scoped', () => {
    const state = new DocumentDurabilityState();
    state.beginInFlightFlush('doc', 'pending');

    state.switchReconciledBaseScope('feature');

    expect(state.inFlightFlushCount('doc')).toBe(1);
    expect(state.hasInFlightFlush('doc', 'pending')).toBe(true);
  });

  test('the expiry counter reports how many records were dropped, not how many prunes ran', () => {
    vi.useFakeTimers();
    try {
      resetMetrics();
      const state = new DocumentDurabilityState();
      state.beginInFlightFlush('doc', 'first');
      state.beginInFlightFlush('doc', 'second');

      vi.advanceTimersByTime(61_000);
      expect(state.inFlightFlushCount('doc')).toBe(0);

      expect(getMetrics().inFlightFlushExpired).toBe(2);
    } finally {
      vi.useRealTimers();
    }
  });

  test('a stale entry is also discarded when the next flush for the same document begins', () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.beginInFlightFlush('doc', 'leaked');
      vi.advanceTimersByTime(61_000);
      state.beginInFlightFlush('doc', 'fresh');

      expect(state.hasInFlightFlush('doc', 'leaked')).toBe(false);
      expect(state.inFlightFlushCount('doc')).toBe(1);
      state.finishInFlightFlush('doc', 'fresh');
      expect(state.peekInFlightFlush('doc')).toBeUndefined();
    } finally {
      vi.useRealTimers();
    }
  });

  test('a flush still in flight is not aged out while it keeps company with newer flushes', () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.beginInFlightFlush('doc', 'slow');
      vi.advanceTimersByTime(5_000);
      state.beginInFlightFlush('doc', 'quick');
      expect(state.hasInFlightFlush('doc', 'slow')).toBe(true);
      expect(state.inFlightFlushCount('doc')).toBe(2);
    } finally {
      vi.useRealTimers();
    }
  });
});

describe('displaced-version history', () => {
  test('recognizes a version this server displaced and ignores one it never wrote', () => {
    const state = new DocumentDurabilityState();
    state.recordDisplacedVersion('doc', 'v1 bytes');

    expect(state.isDisplacedVersion('doc', 'v1 bytes')).toBe(true);
    expect(state.isDisplacedVersion('doc', 'never written')).toBe(false);
    expect(state.isDisplacedVersion('other-doc', 'v1 bytes')).toBe(false);
  });

  test('retains only the newest DISPLACED_VERSION_LIMIT versions per document', () => {
    const state = new DocumentDurabilityState();
    for (let i = 0; i <= DISPLACED_VERSION_LIMIT; i++) {
      state.recordDisplacedVersion('doc', `v${i}`);
    }

    expect(state.isDisplacedVersion('doc', 'v0')).toBe(false);
    expect(state.isDisplacedVersion('doc', 'v1')).toBe(true);
    expect(state.isDisplacedVersion('doc', `v${DISPLACED_VERSION_LIMIT}`)).toBe(true);
  });

  test('a re-displaced version refreshes in place instead of consuming another slot', () => {
    const state = new DocumentDurabilityState();
    for (let i = 0; i < DISPLACED_VERSION_LIMIT; i++) {
      state.recordDisplacedVersion('doc', 'repeat');
    }
    state.recordDisplacedVersion('doc', 'distinct');

    expect(state.isDisplacedVersion('doc', 'repeat')).toBe(true);
    expect(state.isDisplacedVersion('doc', 'distinct')).toBe(true);
  });

  test('a displaced version expires on read once its TTL has passed', () => {
    vi.useFakeTimers();
    try {
      const state = new DocumentDurabilityState();
      state.recordDisplacedVersion('doc', 'v1 bytes');
      expect(state.isDisplacedVersion('doc', 'v1 bytes')).toBe(true);

      vi.advanceTimersByTime(DISPLACED_VERSION_TTL_MS + 1_000);

      expect(state.isDisplacedVersion('doc', 'v1 bytes')).toBe(false);
    } finally {
      vi.useRealTimers();
    }
  });

  test('displaced versions are scoped to the branch that displaced them', () => {
    const state = new DocumentDurabilityState();
    state.recordDisplacedVersion('doc', 'main v1');
    state.switchReconciledBaseScope('feature');

    expect(state.isDisplacedVersion('doc', 'main v1')).toBe(false);
    state.recordDisplacedVersion('doc', 'feature v1');
    state.switchReconciledBaseScope('main');
    expect(state.isDisplacedVersion('doc', 'feature v1')).toBe(false);
    expect(state.isDisplacedVersion('doc', 'main v1')).toBe(true);
  });

  test('deleting a doc clears its displaced versions, leaving other documents intact', () => {
    const state = new DocumentDurabilityState();
    state.recordDisplacedVersion('doc', 'v1 bytes');
    state.recordDisplacedVersion('other', 'v1 bytes');

    state.deleteReconciledBase('doc');

    expect(state.isDisplacedVersion('doc', 'v1 bytes')).toBe(false);
    expect(state.isDisplacedVersion('other', 'v1 bytes')).toBe(true);
  });

  test('tracks stale external conflicts per branch and clears them with document state', () => {
    const state = new DocumentDurabilityState();
    const conflict = state.recordStaleExternalWrite('doc', 'stale bytes');

    expect(state.staleExternalWriteMatches('doc', 'stale bytes')).toBe(true);
    expect(state.listStaleExternalWrites()).toEqual([conflict]);
    state.switchReconciledBaseScope('feature');
    expect(state.listStaleExternalWrites()).toEqual([]);
    state.switchReconciledBaseScope('main');
    state.deleteReconciledBase('doc');
    expect(state.listStaleExternalWrites()).toEqual([]);
  });

  test('restores displaced history, acknowledged content, and unresolved conflicts after restart', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-state-'));
    const persistencePath = join(dir, 'stale-external-writes.json');
    try {
      const first = new DocumentDurabilityState('main', { persistencePath });
      first.setReconciledBase('doc', 'old bytes');
      first.recordDisplacedVersion('doc', 'old bytes');
      first.setReconciledBase('doc', 'acknowledged bytes');
      first.recordStaleExternalWrite('doc', 'old bytes');

      const restored = new DocumentDurabilityState('main', { persistencePath });

      expect(restored.getReconciledBase('doc')).toBe('acknowledged bytes');
      expect(restored.isDisplacedVersion('doc', 'old bytes')).toBe(true);
      expect(restored.staleExternalWriteMatches('doc', 'old bytes')).toBe(true);

      restored.deleteReconciledBase('doc');
      const afterDelete = new DocumentDurabilityState('main', { persistencePath });
      expect(afterDelete.getReconciledBase('doc')).toBeUndefined();
      expect(afterDelete.isDisplacedVersion('doc', 'old bytes')).toBe(false);
      expect(afterDelete.staleExternalWriteMatches('doc', 'old bytes')).toBe(false);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('keeps unresolved persisted conflicts after their displaced-history window expires', () => {
    vi.useFakeTimers();
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-conflict-'));
    const persistencePath = join(dir, 'stale-external-writes.json');
    try {
      const first = new DocumentDurabilityState('main', { persistencePath });
      first.setReconciledBase('doc', 'acknowledged bytes');
      first.recordDisplacedVersion('doc', 'old bytes');
      first.recordStaleExternalWrite('doc', 'old bytes');
      vi.advanceTimersByTime(DISPLACED_VERSION_TTL_MS + 1_000);

      const restored = new DocumentDurabilityState('main', { persistencePath });

      expect(restored.getReconciledBase('doc')).toBe('acknowledged bytes');
      expect(restored.isDisplacedVersion('doc', 'old bytes')).toBe(false);
      expect(restored.staleExternalWriteMatches('doc', 'old bytes')).toBe(true);
    } finally {
      vi.useRealTimers();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('sweeps expired inactive history without expiring unresolved conflicts', () => {
    vi.useFakeTimers();
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-expiry-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('expired-doc', 'acknowledged');
      state.recordDisplacedVersion('expired-doc', 'old');
      state.setReconciledBase('conflicted-doc', 'preserved');
      state.recordDisplacedVersion('conflicted-doc', 'rejected');
      state.recordStaleExternalWrite('conflicted-doc', 'rejected');
      state.switchReconciledBaseScope('feature');
      vi.advanceTimersByTime(DISPLACED_VERSION_TTL_MS + 1);
      state.setReconciledBase('fresh-doc', 'new acknowledged');
      state.recordDisplacedVersion('fresh-doc', 'new old');
      const serialized = readFileSync(persistencePath, 'utf-8');
      expect(serialized).not.toContain('expired-doc');
      expect(serialized).toContain('conflicted-doc');
      const restored = new DocumentDurabilityState('main', { persistencePath });
      expect(restored.getReconciledBase('conflicted-doc')).toBe('preserved');
      expect(restored.staleExternalWriteMatches('conflicted-doc', 'rejected')).toBe(true);
    } finally {
      vi.useRealTimers();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('a branch switch purges expired restored plaintext but retains unresolved recovery data', () => {
    vi.useFakeTimers();
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-restored-expiry-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('expired', 'expired plaintext');
      state.recordDisplacedVersion('expired', 'old');
      state.setReconciledBase('pending', 'protected plaintext');
      state.recordStaleExternalWrite('pending', 'rejected');
      vi.advanceTimersByTime(DISPLACED_VERSION_TTL_MS + 1);
      const beforeRestore = readFileSync(persistencePath, 'utf-8');
      const restored = new DocumentDurabilityState('main', { persistencePath });
      expect(restored.getReconciledBase('expired')).toBeUndefined();
      expect(readFileSync(persistencePath, 'utf-8')).toBe(beforeRestore);
      restored.switchReconciledBaseScope('feature');
      expect(readFileSync(persistencePath, 'utf-8')).not.toContain('expired plaintext');
      expect(readFileSync(persistencePath, 'utf-8')).toContain('protected plaintext');
      expect(readFileSync(persistencePath, 'utf-8')).toContain('rejected');
    } finally {
      vi.useRealTimers();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('failed durable clearing retains the conflict until a successful retry', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-clear-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('doc', 'acknowledged');
      state.recordStaleExternalWrite('doc', 'rejected');
      renameSync(persistencePath, `${persistencePath}.backup`);
      mkdirSync(persistencePath);
      expect(() => state.clearStaleExternalWrite('doc')).toThrow();
      expect(state.getStaleExternalWrite('doc')?.diskContent).toBe('rejected');
      expect(readdirSync(dir).filter((name) => name.includes('.tmp.'))).toEqual([]);
      rmSync(persistencePath, { recursive: true });
      renameSync(`${persistencePath}.backup`, persistencePath);
      const restored = new DocumentDurabilityState('main', { persistencePath });
      expect(restored.getStaleExternalWrite('doc')?.diskContent).toBe('rejected');
      state.clearStaleExternalWrite('doc');
      expect(state.getStaleExternalWrite('doc')).toBeUndefined();
      expect(
        new DocumentDurabilityState('main', { persistencePath }).getStaleExternalWrite('doc'),
      ).toBeUndefined();
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test.each([
    ['{invalid', 'corrupt'],
    [JSON.stringify({ version: 2, branches: {} }), 'incompatible'],
    [JSON.stringify({ version: 1, branches: { main: [{ docName: 'bad' }] } }), 'corrupt'],
  ])('preserves invalid recovery state and fails with actionable %s diagnostics', (raw, kind) => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-invalid-'));
    const persistencePath = join(dir, 'state.json');
    try {
      writeFileSync(persistencePath, raw);
      expect(() => new DocumentDurabilityState('main', { persistencePath })).toThrow(
        DocumentDurabilityStateError,
      );
      try {
        new DocumentDurabilityState('main', { persistencePath });
      } catch (error) {
        expect(error).toMatchObject({ kind, path: persistencePath });
        expect(error instanceof Error ? error.message : '').toContain('Do not delete');
      }
      expect(readFileSync(persistencePath, 'utf-8')).toBe(raw);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('reports an unreadable snapshot without replacing it', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-unreadable-'));
    const persistencePath = join(dir, 'state.json');
    try {
      mkdirSync(persistencePath);
      expect(() => new DocumentDurabilityState('main', { persistencePath })).toThrow(
        expect.objectContaining({ kind: 'unreadable', path: persistencePath }),
      );
      expect(statSync(persistencePath).isDirectory()).toBe(true);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test.each([
    ['EACCES', 'permissions'],
    ['EPERM', 'permissions'],
    ['EISDIR', 'regular file'],
    ['EIO', 'filesystem'],
  ])('unreadable %s diagnostics name the filesystem problem', (code, guidance) => {
    const cause = Object.assign(new Error('read failed'), { code });
    const error = new DocumentDurabilityStateError('/project/state.json', 'unreadable', cause);
    expect(error.message).toContain(code);
    expect(error.message).toContain(guidance);
    expect(error.message).not.toContain('Restore this snapshot from a known-good backup');
    expect(error.cause).toBe(cause);
  });

  test('incompatible diagnostics do not claim an unrecorded writer version is known', () => {
    const error = new DocumentDurabilityStateError('/project/state.json', 'incompatible');
    expect(error.message).not.toContain('version that wrote');
    expect(error.message).toContain('schema');
  });

  test('a tracked target is re-derived from docName rather than trusted from the snapshot', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-target-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('protected', 'acknowledged');
      state.recordStaleExternalWrite('protected', 'old');
      const tampered = readFileSync(persistencePath, 'utf-8').replace(
        '"file":"protected.md"',
        '"file":"unrelated.md"',
      );
      writeFileSync(persistencePath, tampered);
      const restored = new DocumentDurabilityState('main', { persistencePath });
      expect(restored.getStaleExternalWrite('protected')?.file).toBe('protected.md');
      expect(restored.listStaleExternalWrites().map((entry) => entry.file)).toEqual([
        'protected.md',
      ]);
      expect(readFileSync(persistencePath, 'utf-8')).toBe(tampered);
      const invalidPath = new Error('document path escapes content directory');
      expect(
        () =>
          new DocumentDurabilityState('main', {
            persistencePath,
            fileForDocName: () => {
              throw invalidPath;
            },
          }),
      ).toThrow(expect.objectContaining({ kind: 'corrupt', cause: invalidPath }));
      expect(readFileSync(persistencePath, 'utf-8')).toBe(tampered);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('re-recording the same disk hash with a new retained edit does not count a new conflict', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-recount-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('doc', 'acknowledged');
      const beforeCount = getMetrics().staleExternalWriteRefused;
      state.recordStaleExternalWrite('doc', 'old');
      expect(getMetrics().staleExternalWriteRefused).toBe(beforeCount + 1);
      const first = state.getStaleExternalWrite('doc');
      state.recordStaleExternalWrite('doc', 'old', 'a pending edit');
      expect(getMetrics().staleExternalWriteRefused).toBe(beforeCount + 1);
      expect(state.getStaleExternalWrite('doc')?.retainedContent).toBe('a pending edit');
      expect(state.getStaleExternalWrite('doc')?.detectedAt).toBe(first?.detectedAt);
      state.recordStaleExternalWrite('doc', 'newer disk bytes');
      expect(getMetrics().staleExternalWriteRefused).toBe(beforeCount + 2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('an .mdx document restored before the watcher scan resolves to its .mdx file', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-mdx-'));
    const persistencePath = join(dir, 'state.json');
    const options = {
      persistencePath,
      fileForDocName: docNameToRelativePath,
      hasResolvedExtension: isRegisteredMarkdownDocName,
    };
    try {
      _resetDocExtensionsForTests();
      registerDocExtension('notes/guide', '.mdx');
      const state = new DocumentDurabilityState('main', options);
      state.setReconciledBase('notes/guide', 'acknowledged');
      state.recordStaleExternalWrite('notes/guide', 'old');
      expect(state.getStaleExternalWrite('notes/guide')?.file).toBe('notes/guide.mdx');

      _resetDocExtensionsForTests();
      const booting = new DocumentDurabilityState('main', options);
      expect(booting.getStaleExternalWrite('notes/guide')?.file).toBe('notes/guide.mdx');
      expect(booting.listStaleExternalWrites().map((entry) => entry.file)).toEqual([
        'notes/guide.mdx',
      ]);
    } finally {
      _resetDocExtensionsForTests();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('a scan that observes .md displaces an .mdx snapshot instead of being outranked by it', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-mdx-renamed-'));
    const persistencePath = join(dir, 'state.json');
    const options = {
      persistencePath,
      fileForDocName: docNameToRelativePath,
      hasResolvedExtension: isRegisteredMarkdownDocName,
    };
    try {
      _resetDocExtensionsForTests();
      registerDocExtension('notes/guide', '.mdx');
      const state = new DocumentDurabilityState('main', options);
      state.setReconciledBase('notes/guide', 'acknowledged');
      state.recordStaleExternalWrite('notes/guide', 'old');
      expect(state.getStaleExternalWrite('notes/guide')?.file).toBe('notes/guide.mdx');

      _resetDocExtensionsForTests();
      const booting = new DocumentDurabilityState('main', options);
      expect(registerDocExtension('notes/guide', '.md')).toEqual({
        effective: '.md',
        changed: true,
        shadowed: null,
      });
      expect(booting.getStaleExternalWrite('notes/guide')?.file).toBe('notes/guide.md');
    } finally {
      _resetDocExtensionsForTests();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('a restored file naming an extension the registry rejects still opens the project', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-mmd-'));
    const persistencePath = join(dir, 'state.json');
    const options = {
      persistencePath,
      fileForDocName: docNameToRelativePath,
      hasResolvedExtension: isRegisteredMarkdownDocName,
    };
    try {
      _resetDocExtensionsForTests();
      const state = new DocumentDurabilityState('main', options);
      state.setReconciledBase('flow.mmd', 'acknowledged');
      state.recordStaleExternalWrite('flow.mmd', 'old');
      expect(state.getStaleExternalWrite('flow.mmd')?.file).toBe('flow.mmd');

      _resetDocExtensionsForTests();
      const booting = new DocumentDurabilityState('main', options);
      expect(booting.getStaleExternalWrite('flow.mmd')?.file).toBe('flow.mmd');
    } finally {
      _resetDocExtensionsForTests();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('a conflict file is re-derived from the resolver on every read, never replayed', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-moved-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', {
        persistencePath,
        fileForDocName: (docName) => `sub/${docName}.md`,
      });
      state.setReconciledBase('guide', 'acknowledged');
      state.recordStaleExternalWrite('guide', 'old');
      expect(state.getStaleExternalWrite('guide')?.file).toBe('sub/guide.md');

      const moved = new DocumentDurabilityState('main', {
        persistencePath,
        fileForDocName: (docName) => `moved/${docName}.md`,
      });
      expect(moved.getStaleExternalWrite('guide')?.file).toBe('moved/guide.md');
      expect(moved.listStaleExternalWrites().map((entry) => entry.file)).toEqual([
        'moved/guide.md',
      ]);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('an unrelated mutation on a document whose conflict file moved does not re-notify', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-renotify-'));
    const persistencePath = join(dir, 'state.json');
    const changed = vi.fn();
    let prefix = 'sub';
    try {
      const state = new DocumentDurabilityState('main', {
        persistencePath,
        fileForDocName: (docName) => `${prefix}/${docName}.md`,
        onStaleExternalWriteChange: changed,
      });
      state.setReconciledBase('guide', 'acknowledged');
      state.recordStaleExternalWrite('guide', 'old');
      expect(changed).toHaveBeenCalledTimes(1);

      prefix = 'moved';
      expect(state.getStaleExternalWrite('guide')?.file).toBe('moved/guide.md');
      state.setReconciledBase('guide', 'a later acknowledgement');
      expect(changed).toHaveBeenCalledTimes(1);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('ordinary clears and branch switches create no snapshot, and restore does not rewrite one', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-noop-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('ordinary', 'content');
      state.clearStaleExternalWrite('ordinary');
      state.clearDisplacedVersions('ordinary');
      state.deleteReconciledBase('ordinary');
      state.switchReconciledBaseScope('feature');
      expect(existsSync(persistencePath)).toBe(false);
      state.setReconciledBase('protected', 'content');
      state.recordDisplacedVersion('protected', 'old');
      utimesSync(persistencePath, 1, 1);
      const before = statSync(persistencePath);
      new DocumentDurabilityState('feature', { persistencePath });
      expect(statSync(persistencePath).mtimeMs).toBe(before.mtimeMs);
      if (process.platform !== 'win32') expect(before.mode & 0o777).toBe(0o600);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('all persisted mutators retain their previous state when the atomic replacement fails', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-atomic-'));
    const persistencePath = join(dir, 'state.json');
    const changed = vi.fn();
    try {
      const state = new DocumentDurabilityState('main', {
        persistencePath,
        onStaleExternalWriteChange: changed,
      });
      state.setReconciledBase('doc', 'acknowledged');
      state.recordDisplacedVersion('doc', 'old');
      const beforeCount = getMetrics().staleExternalWriteRefused;
      state.recordStaleExternalWrite('doc', 'old');
      state.recordStaleExternalWrite('doc', 'old');
      expect(getMetrics().staleExternalWriteRefused).toBe(beforeCount + 1);
      expect(changed).toHaveBeenCalledTimes(1);
      renameSync(persistencePath, `${persistencePath}.backup`);
      mkdirSync(persistencePath);
      for (const mutate of [
        () => state.setReconciledBase('doc', 'changed'),
        () => state.recordDisplacedVersion('doc', 'another'),
        () => state.clearDisplacedVersions('doc'),
        () => state.recordStaleExternalWrite('doc', 'another'),
        () => state.clearStaleExternalWrite('doc'),
        () => state.deleteReconciledBase('doc'),
      ]) {
        expect(mutate).toThrow();
        expect(state.getReconciledBase('doc')).toBe('acknowledged');
        expect(state.getStaleExternalWrite('doc')?.diskContent).toBe('old');
        expect(state.isDisplacedVersion('doc', 'old')).toBe(true);
        expect(state.isDisplacedVersion('doc', 'another')).toBe(false);
        expect(changed).toHaveBeenCalledTimes(1);
        expect(getMetrics().staleExternalWriteRefused).toBe(beforeCount + 1);
        expect(readdirSync(dir).filter((name) => name.includes('.tmp.'))).toEqual([]);
      }
      rmSync(persistencePath, { recursive: true });
      renameSync(`${persistencePath}.backup`, persistencePath);
      const restored = new DocumentDurabilityState('main', {
        persistencePath,
        onStaleExternalWriteChange: changed,
      });
      expect(changed).toHaveBeenCalledTimes(1);
      restored.clearStaleExternalWrite('doc');
      expect(changed).toHaveBeenCalledTimes(2);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('keeps the original replacement failure when temporary-file cleanup also fails', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-cleanup-'));
    const persistencePath = join(dir, 'state.json');
    let originalError: unknown;
    const state = new DocumentDurabilityState('main', { persistencePath });
    state.setReconciledBase('doc', 'acknowledged');
    mkdirSync(persistencePath);
    const renameSpy = vi.spyOn(tracedFs, 'tracedRenameSync').mockImplementation((from, to) => {
      try {
        renameSync(from, to);
      } catch (cause) {
        originalError = cause;
        rmSync(from);
        mkdirSync(from);
        throw cause;
      }
    });
    const warnSpy = vi.spyOn(getLogger('document-durability-state'), 'warn');
    try {
      let actualError: unknown;
      try {
        state.recordDisplacedVersion('doc', 'old');
      } catch (cause) {
        actualError = cause;
      }
      expect(originalError).toBeInstanceOf(Error);
      expect(actualError).toBe(originalError);
      expect(state.isDisplacedVersion('doc', 'old')).toBe(false);
      const payload = (warnSpy.mock.calls[0]?.[0] ?? {}) as { writeError?: unknown };
      expect(payload.writeError).toBe((originalError as Error).message);
      expect(JSON.stringify(payload.writeError)).not.toBe('{}');
    } finally {
      warnSpy.mockRestore();
      renameSpy.mockRestore();
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('a different rejected version preserves the retained candidate across restart', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-retained-'));
    const persistencePath = join(dir, 'state.json');
    try {
      const state = new DocumentDurabilityState('main', { persistencePath });
      state.setReconciledBase('doc', 'acknowledged');
      state.recordDisplacedVersion('doc', 'old A');
      state.recordDisplacedVersion('doc', 'old Z');
      state.recordStaleExternalWrite('doc', 'old A', 'retained C');
      state.recordStaleExternalWrite('doc', 'old Z');
      const restored = new DocumentDurabilityState('main', { persistencePath });
      expect(restored.getStaleExternalWrite('doc')).toMatchObject({
        diskContent: 'old Z',
        retainedContent: 'retained C',
      });
      restored.recordStaleExternalWrite('doc', 'old A', '');
      expect(restored.getStaleExternalWrite('doc')?.retainedContent).toBe('');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('store publish generation primitives', () => {
  test('beginStoreAttempt issues monotonically increasing tokens per document', () => {
    const state = new DocumentDurabilityState();
    expect(state.beginStoreAttempt('doc')).toEqual({ docName: 'doc', generation: 1 });
    expect(state.beginStoreAttempt('doc')).toEqual({ docName: 'doc', generation: 2 });
    expect(state.beginStoreAttempt('doc')).toEqual({ docName: 'doc', generation: 3 });
    expect(state.beginStoreAttempt('other')).toEqual({ docName: 'other', generation: 1 });
  });

  test('tryPublishStore refuses a stale token without publishing and without moving the published watermark', () => {
    const state = new DocumentDurabilityState();
    const first = state.beginStoreAttempt('doc');
    const second = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    expect(
      state.tryPublishStore(second, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(publishCalls).toBe(1);
    expect(
      state.tryPublishStore(first, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(1);
    expect(
      state.tryPublishStore(first, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(1);
  });

  test('tryPublishStore refuses an already-published token and advances the watermark only on publish', () => {
    const state = new DocumentDurabilityState();
    const first = state.beginStoreAttempt('doc');
    const second = state.beginStoreAttempt('doc');
    const third = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    expect(
      state.tryPublishStore(second, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(second, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(first, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(third, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(second, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(third, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(2);
  });

  test('tryPublishStore invokes the publish callback synchronously before returning', () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    let committed = false;
    const accepted = state.tryPublishStore(token, () => {
      committed = true;
    });
    expect(accepted).toBe('published');
    expect(committed).toBe(true);
  });

  test('tryPublishStore rejects a publish callback that returns a thenable instead of publishing synchronously', () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    let renamed = false;
    expect(() =>
      state.tryPublishStore(token, async () => {
        await Promise.resolve();
        renamed = true;
      }),
    ).toThrow(TypeError);
    expect(renamed).toBe(false);
    expect(
      state.tryPublishStore(token, () => {
        renamed = true;
      }),
    ).toBe('published');
    expect(renamed).toBe(true);
  });

  test('a rejecting async publish callback throws without leaking an unhandled rejection', async () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      expect(() =>
        state.tryPublishStore(token, async () => {
          await Promise.reject(new Error('in-flight rename failed'));
        }),
      ).toThrow(TypeError);
      await new Promise((resolve) => setImmediate(resolve));
      const events = warnSpy.mock.calls
        .map((call) => call.map(String).join(' '))
        .filter((line) => line.includes('"event":"persistence-store-publish-async-rejected"'));
      expect(events).toHaveLength(1);
      const payload = JSON.parse(events[0]) as Record<string, unknown>;
      expect(payload['doc.name']).toBe('doc');
      expect(payload.generation).toBe(1);
      expect(payload.error).toBe('in-flight rename failed');
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('a non-Error rejection reason still lands the async-rejected event without crashing the handler', async () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      expect(() =>
        state.tryPublishStore(token, async () => {
          await Promise.reject({ toString: 1 });
        }),
      ).toThrow(TypeError);
      await new Promise((resolve) => setImmediate(resolve));
      const events = warnSpy.mock.calls
        .map((call) => call.map(String).join(' '))
        .filter((line) => line.includes('"event":"persistence-store-publish-async-rejected"'));
      expect(events).toHaveLength(1);
      const payload = JSON.parse(events[0]) as Record<string, unknown>;
      expect(payload['doc.name']).toBe('doc');
      expect(payload.generation).toBe(1);
      expect(typeof payload.error).toBe('string');
      expect(payload.error).not.toBe('');
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('an Error cause carrying a non-string message still lands the event with a string reason', async () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    try {
      const hostile = new Error('placeholder');
      const circular: Record<string, unknown> = {};
      circular.self = circular;
      hostile.message = circular;
      expect(() =>
        state.tryPublishStore(token, async () => {
          await Promise.reject(hostile);
        }),
      ).toThrow(TypeError);
      await new Promise((resolve) => setImmediate(resolve));
      const events = warnSpy.mock.calls
        .map((call) => call.map(String).join(' '))
        .filter((line) => line.includes('"event":"persistence-store-publish-async-rejected"'));
      expect(events).toHaveLength(1);
      const payload = JSON.parse(events[0]) as Record<string, unknown>;
      expect(payload['doc.name']).toBe('doc');
      expect(payload.generation).toBe(1);
      expect(typeof payload.error).toBe('string');
    } finally {
      warnSpy.mockRestore();
    }
  });

  test('a sync-throwing then on a refused thenable still surfaces the TypeError contract', () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const syncThrowing = () => {};
    Reflect.set(syncThrowing, 'then', () => {
      throw new Error('then threw synchronously');
    });
    expect(() => state.tryPublishStore(token, () => syncThrowing)).toThrow(TypeError);
    expect(state.tryPublishStore(token, () => {})).toBe('published');
  });

  test('a self-resolving thenable return is refused without assimilating it into the promise machinery', () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const selfResolving = () => {};
    Reflect.set(selfResolving, 'then', (onFulfilled: (value: unknown) => void) => {
      onFulfilled(selfResolving);
    });
    expect(() => state.tryPublishStore(token, () => selfResolving)).toThrow(TypeError);
    expect(state.tryPublishStore(token, () => {})).toBe('published');
  });

  test('tryPublishStore rejects a thenable that is a function carrying a then method', () => {
    const state = new DocumentDurabilityState();
    const token = state.beginStoreAttempt('doc');
    const callableThenable = () => {};
    Reflect.set(callableThenable, 'then', () => {});
    expect(() => state.tryPublishStore(token, () => callableThenable)).toThrow(TypeError);
    expect(state.tryPublishStore(token, () => {})).toBe('published');
  });

  test('a nested publish attempt inside the gate is refused before its callback runs and the outer attempt completes', () => {
    const state = new DocumentDurabilityState();
    const stale = state.beginStoreAttempt('doc');
    const outer = state.beginStoreAttempt('doc');
    const afterOuter = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    let nestedOutcome: StorePublishOutcome | undefined;
    expect(
      state.tryPublishStore(outer, () => {
        publishCalls += 1;
        nestedOutcome = state.tryPublishStore(stale, () => {
          publishCalls += 1;
        });
      }),
    ).toBe('published');
    expect(nestedOutcome).toBe('reentrant');
    expect(publishCalls).toBe(1);
    expect(
      state.tryPublishStore(outer, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(afterOuter, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(publishCalls).toBe(2);
  });

  test('a reentrant attempt with a higher generation is still refused while the outer publish is in flight', () => {
    const state = new DocumentDurabilityState();
    const outer = state.beginStoreAttempt('doc');
    const nested = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    let nestedOutcome: StorePublishOutcome | undefined;
    expect(
      state.tryPublishStore(outer, () => {
        publishCalls += 1;
        nestedOutcome = state.tryPublishStore(nested, () => {
          publishCalls += 1;
        });
      }),
    ).toBe('published');
    expect(nestedOutcome).toBe('reentrant');
    expect(publishCalls).toBe(1);
    expect(
      state.tryPublishStore(outer, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(nested, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(publishCalls).toBe(2);
  });

  test('an in-flight publish for one document does not refuse a nested publish for another document', () => {
    const state = new DocumentDurabilityState();
    const docToken = state.beginStoreAttempt('doc');
    const otherToken = state.beginStoreAttempt('other');
    let docPublishCalls = 0;
    let otherPublishCalls = 0;
    let nestedOtherOutcome: StorePublishOutcome | undefined;
    let docReentryOutcome: StorePublishOutcome | undefined;
    expect(
      state.tryPublishStore(docToken, () => {
        docPublishCalls += 1;
        nestedOtherOutcome = state.tryPublishStore(otherToken, () => {
          otherPublishCalls += 1;
        });
        docReentryOutcome = state.tryPublishStore(docToken, () => {
          docPublishCalls += 1;
        });
      }),
    ).toBe('published');
    expect(nestedOtherOutcome).toBe('published');
    expect(otherPublishCalls).toBe(1);
    expect(docReentryOutcome).toBe('reentrant');
    expect(docPublishCalls).toBe(1);
    const otherFollowUp = state.beginStoreAttempt('other');
    expect(
      state.tryPublishStore(otherFollowUp, () => {
        otherPublishCalls += 1;
      }),
    ).toBe('published');
    expect(otherPublishCalls).toBe(2);
  });

  test('a reentrant attempt that is also stale is still refused as reentrant while the outer publish is in flight', () => {
    const state = new DocumentDurabilityState();
    const first = state.beginStoreAttempt('doc');
    expect(state.tryPublishStore(first, () => {})).toBe('published');
    const outer = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    let nestedOutcome: StorePublishOutcome | undefined;
    expect(
      state.tryPublishStore(outer, () => {
        publishCalls += 1;
        nestedOutcome = state.tryPublishStore(first, () => {
          publishCalls += 1;
        });
      }),
    ).toBe('published');
    expect(nestedOutcome).toBe('reentrant');
    expect(publishCalls).toBe(1);
  });

  test('a throwing publish callback propagates without advancing the published watermark', () => {
    const state = new DocumentDurabilityState();
    const first = state.beginStoreAttempt('doc');
    expect(state.tryPublishStore(first, () => {})).toBe('published');
    const second = state.beginStoreAttempt('doc');
    expect(() =>
      state.tryPublishStore(second, () => {
        throw new Error('rename failed');
      }),
    ).toThrow('rename failed');
    expect(state.tryPublishStore(second, () => {})).toBe('published');
    const third = state.beginStoreAttempt('doc');
    expect(state.tryPublishStore(third, () => {})).toBe('published');
  });

  test('a pre-delete store token stays outranked across the delete boundary', () => {
    const state = new DocumentDurabilityState();
    const stale = state.beginStoreAttempt('doc');
    const current = state.beginStoreAttempt('doc');
    const otherFirst = state.beginStoreAttempt('other');
    const otherSecond = state.beginStoreAttempt('other');
    let publishCalls = 0;
    expect(
      state.tryPublishStore(current, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(
      state.tryPublishStore(otherSecond, () => {
        publishCalls += 1;
      }),
    ).toBe('published');

    state.deleteReconciledBase('doc');

    expect(state.beginStoreAttempt('doc')).toEqual({ docName: 'doc', generation: 3 });
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    const postDelete = state.beginStoreAttempt('doc');
    expect(postDelete).toEqual({ docName: 'doc', generation: 4 });
    expect(
      state.tryPublishStore(postDelete, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(3);
    expect(state.beginStoreAttempt('other')).toEqual({ docName: 'other', generation: 3 });
    expect(
      state.tryPublishStore(otherFirst, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(3);
  });

  test('a pre-delete store token stays outranked across a persisted delete', () => {
    const state = new DocumentDurabilityState();
    state.recordDisplacedVersion('doc', 'displaced bytes');
    const stale = state.beginStoreAttempt('doc');
    const current = state.beginStoreAttempt('doc');
    let publishCalls = 0;
    expect(
      state.tryPublishStore(current, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');

    state.deleteReconciledBase('doc');

    expect(state.beginStoreAttempt('doc')).toEqual({ docName: 'doc', generation: 3 });
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    const postDelete = state.beginStoreAttempt('doc');
    expect(
      state.tryPublishStore(postDelete, () => {
        publishCalls += 1;
      }),
    ).toBe('published');
    expect(
      state.tryPublishStore(stale, () => {
        publishCalls += 1;
      }),
    ).toBe('stale');
    expect(publishCalls).toBe(2);
  });

  test('a refused-store mark does not survive an unpersisted teardown', () => {
    const state = new DocumentDurabilityState();
    state.markStoreRefused('doc');
    state.recordStoreFailure('doc', { code: 'ENOSPC', message: 'no space left on device' });
    expect(state.isStoreRefused('doc')).toBe(true);

    state.deleteReconciledBase('doc');

    expect(state.isStoreRefused('doc')).toBe(false);
    expect(state.getRefusedStoreDocNames()).toEqual([]);
    expect(state.takeStoreFailure('doc')).toBeNull();
  });

  test('a refused-store mark does not survive a persisted teardown', () => {
    const state = new DocumentDurabilityState();
    state.recordDisplacedVersion('doc', 'displaced bytes');
    state.markStoreRefused('doc');
    state.recordStoreFailure('doc', { code: 'ENOSPC', message: 'no space left on device' });
    expect(state.isStoreRefused('doc')).toBe(true);

    state.deleteReconciledBase('doc');

    expect(state.isStoreRefused('doc')).toBe(false);
    expect(state.getRefusedStoreDocNames()).toEqual([]);
    expect(state.takeStoreFailure('doc')).toBeNull();
  });

  test('tearing one document down leaves a sibling document refused', () => {
    const state = new DocumentDurabilityState();
    state.markStoreRefused('doc');
    state.markStoreRefused('sibling');

    state.deleteReconciledBase('doc');

    expect(state.isStoreRefused('sibling')).toBe(true);
    expect(state.getRefusedStoreDocNames()).toEqual(['sibling']);
  });
});

describe('DocumentDurabilityStateError names the running channel CLI', () => {
  test('Stable keeps its exact message', () => {
    vi.stubEnv('OK_CHANNEL', 'stable');
    try {
      expect(new DocumentDurabilityStateError('/p/state.json', 'corrupt').message).toBe(
        'Cannot safely open this project: its stale-write recovery snapshot is corrupt (/p/state.json). The snapshot has been preserved because it may contain the only copy of protected edits. Restore this snapshot from a known-good backup, or contact support to recover its protected edits. Run ok bug-report from the project directory to collect diagnostics without starting the server. Do not delete it to bypass recovery.',
      );
    } finally {
      vi.unstubAllEnvs();
    }
  });

  test('Beta names ok-beta bug-report', () => {
    vi.stubEnv('OK_CHANNEL', 'beta');
    try {
      expect(new DocumentDurabilityStateError('/p/state.json', 'corrupt').message).toContain(
        'Run ok-beta bug-report from the project directory',
      );
    } finally {
      vi.unstubAllEnvs();
    }
  });
});

describe('the durable receipt follows the acknowledged base', () => {
  test('setting the base records it as agreed, a store records it as an own write, and a delete forgets it', () => {
    const state = new DocumentDurabilityState();
    state.setReconciledBase('doc', 'loaded\n');
    expect(state.getReceipt('doc')).toMatchObject({
      hash: contentHash('loaded\n'),
      via: 'agreed',
    });

    const observation = { size: 7n, mtimeNs: 5n, dev: 1n, ino: 9n };
    state.recordSuccessfulStore('doc', 'stored\n', undefined, observation);
    expect(state.getReceipt('doc')).toMatchObject({
      hash: contentHash('stored\n'),
      via: 'own-write',
      ino: '9',
    });
    expect(state.isRecentOwnWrite('doc', contentHash('loaded\n'))).toBe(false);
    expect(state.isRecentOwnWrite('doc', contentHash('stored\n'))).toBe(true);

    state.deleteReconciledBase('doc');
    expect(state.getReceipt('doc')).toBeUndefined();
  });

  test('a store that displaces an agent-acknowledged version still records the written bytes', () => {
    const state = new DocumentDurabilityState();
    state.setReconciledBase('doc', 'before\n');
    state.recordSuccessfulStore('doc', 'after\n', 'before\n');
    expect(state.getReceipt('doc')?.hash).toBe(contentHash('after\n'));
    expect(state.getReconciledBase('doc')).toBe('after\n');
  });

  test('the check at load reports a missing, unchanged or changed receipt and counts it', () => {
    resetMetrics();
    const dir = mkdtempSync(join(tmpdir(), 'ok-durability-receipts-'));
    try {
      const path = join(dir, 'receipts.jsonl');
      const before = new DocumentDurabilityState('main', {
        receipts: new DiskReceiptLog({ path }),
      });
      expect(before.checkReceiptAtLoad('doc', 'first\n')).toBe('missing');
      before.setReconciledBase('doc', 'first\n');

      const restarted = new DocumentDurabilityState('main', {
        receipts: new DiskReceiptLog({ path }),
      });
      expect(restarted.getReconciledBase('doc')).toBeUndefined();
      expect(restarted.checkReceiptAtLoad('doc', 'first\n')).toBe('unchanged');
      expect(restarted.checkReceiptAtLoad('doc', 'edited while closed\n')).toBe('changed');
      expect(getMetrics().receiptAtLoad).toEqual({ missing: 1, unchanged: 1, changed: 1 });
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('an outside change to a document that is not loaded refreshes the receipt it already has', () => {
    const receipts = new DiskReceiptLog();
    receipts.recordAgreed('closed', 'v1\n');
    const state = new DocumentDurabilityState('main', { receipts });

    state.refreshReceiptWithoutBase('closed', 'v2\n');
    expect(state.getReceipt('closed')?.hash).toBe(contentHash('v2\n'));

    state.refreshReceiptWithoutBase('never-loaded', 'bytes\n');
    expect(state.getReceipt('never-loaded')).toBeUndefined();

    state.setReconciledBase('loaded', 'v1\n');
    state.refreshReceiptWithoutBase('loaded', 'v2\n');
    expect(state.getReceipt('loaded')?.hash).toBe(contentHash('v1\n'));
  });
});

describe('which edits a rename outside the app carried to the new name', () => {
  function frozenDocWithCarriedAndLaterEdit() {
    const document = new Y.Doc();
    const source = document.getText('source');
    source.insert(0, 'Before the move.\n');
    const carriedEdit = writtenThroughOf(document);
    const carried = writtenThroughOf(document);
    source.insert(source.length, 'After the move.\n');
    const laterEdit = writtenThroughOf(document);
    return { carriedEdit, carried, laterEdit };
  }

  test('an edit the carry included is carried, and an edit made after it is not', () => {
    const { carriedEdit, carried, laterEdit } = frozenDocWithCarriedAndLaterEdit();
    expect(editWasCarried(carriedEdit, carried)).toBe(true);
    expect(editWasCarried(laterEdit, carried)).toBe(false);
    expect(editWasCarried(carriedEdit, null)).toBe(false);
    expect(editWasCarried(undefined, carried)).toBe(false);
    expect(editWasCarried({ ...carriedEdit, clientId: carriedEdit.clientId + 1 }, carried)).toBe(
      false,
    );
  });

  test('a write refused while the carry runs waits for it, and a failed carry answers not carried', async () => {
    const state = new DocumentDurabilityState();
    const { carried } = frozenDocWithCarriedAndLaterEdit();
    const carry = state.beginRenameCarry('notes');
    let answered = false;
    const answer = state.awaitRenameCarry('notes', carry).then((value) => {
      answered = true;
      return value;
    });
    await Promise.resolve();
    expect(answered).toBe(false);
    state.settleRenameCarry('notes', null);
    expect(await answer).toEqual({ kind: 'settled', carried: null });

    const archive = state.beginRenameCarry('archive');
    const carriedAnswer = state.awaitRenameCarry('archive', archive);
    state.settleRenameCarry('archive', carried);
    expect(await carriedAnswer).toEqual({ kind: 'settled', carried });
    expect(await state.awaitRenameCarry('archive', state.renameCarryOf('archive'))).toEqual({
      kind: 'settled',
      carried,
    });
  });

  test('a route that begins a carry and never reaches it answers not carried', async () => {
    const state = new DocumentDurabilityState();
    const carry = state.beginRenameCarry('notes');
    expect(state.beginRenameCarry('notes')).toBe(carry);
    state.abandonRenameCarry('notes');
    expect(await carry).toEqual({ kind: 'settled', carried: null });
  });

  test('a revive while the carry runs still answers the waiting write, and the late settle leaves no record', async () => {
    const state = new DocumentDurabilityState();
    const { carried } = frozenDocWithCarriedAndLaterEdit();
    const carry = state.beginRenameCarry('notes');
    state.endRenameCarry('notes');
    state.settleRenameCarry('notes', carried);
    expect(await carry).toEqual({ kind: 'settled', carried });
    expect(state.renameCarryOf('notes')).toBeUndefined();

    state.beginRenameCarry('archive');
    state.settleRenameCarry('archive', carried);
    state.endRenameCarry('archive');
    expect(state.renameCarryOf('archive')).toBeUndefined();
    state.settleRenameCarry('archive', carried);
    expect(state.renameCarryOf('archive')).toBeUndefined();
  });

  test('ending every record at shutdown answers a waiting write as stopped and leaves none', async () => {
    const state = new DocumentDurabilityState();
    const { carried } = frozenDocWithCarriedAndLaterEdit();
    const pending = state.beginRenameCarry('notes');
    state.beginRenameCarry('archive');
    state.settleRenameCarry('archive', carried);
    state.endAllRenameCarries();
    expect(await pending).toEqual({ kind: 'stopped' });
    expect(state.renameCarryOf('notes')).toBeUndefined();
    expect(state.renameCarryOf('archive')).toBeUndefined();
  });

  test("a carry that outlasts the write's remaining wait answers unsettled, never not carried", async () => {
    const state = new DocumentDurabilityState();
    const carry = state.beginRenameCarry('notes');
    const warn = vi
      .spyOn(getLogger('document-durability-state'), 'warn')
      .mockImplementation(() => {});
    try {
      const started = Date.now();
      const answer = await state.runWithinWriteWaitBudget(
        () => state.awaitRenameCarry('notes', carry),
        20,
      );
      expect(answer).toEqual({ kind: 'unsettled' });
      expect(Date.now() - started).toBeLessThan(WRITE_WAIT_BUDGET_MS);
      expect(warn).toHaveBeenCalledOnce();
    } finally {
      warn.mockRestore();
    }
  });
});