Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

74.2 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import type {
  CacheRequest,
  CacheResponseErrorCode,
  WorkerMessage,
  WriteResult,
} from '../protocol';
import { INITIAL_CACHE_REVISION } from '../protocol';
import type {
  CacheCoordinatorPageAdapter,
  CacheCoordinatorPageAdapterOptions,
  PageAdapterDisposeOptions,
} from '../worker/coordinator-page-adapter';

const adapterFactory = vi.hoisted(() => vi.fn());

vi.mock('../worker/coordinator-page-adapter', () => ({
  createCacheCoordinatorPageAdapter: adapterFactory,
}));

import {
  CACHE_COORDINATOR_PROTOCOL_VERSION,
  type EngineOpenOutcome,
} from '../worker/coordinator-protocol';
import {
  CacheBootstrapExhaustedError,
  COORDINATOR_CONNECT_TIMEOUT_MS,
} from '../worker/startup';
import { CacheNavigationError } from './navigation-error';
import { createWorkerCacheHost } from './worker-host';

const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
const STORAGE_GENERATION = '00000000-0000-7000-8000-000000000001';
const EMPTY_WRITE: WriteResult = {
  revision: INITIAL_CACHE_REVISION,
  revisionAdvanced: false,
  changed: [],
  affectedOps: [],
  reset: false,
};

function responseFor(request: CacheRequest): unknown {
  switch (request.kind) {
    case 'current-revision':
      return INITIAL_CACHE_REVISION;
    case 'current-storage-generation':
      return STORAGE_GENERATION;
    case 'read':
      return { kind: 'miss' };
    case 'read-records-by-keys':
      return { revision: INITIAL_CACHE_REVISION, records: [] };
    case 'search':
      return { documents: [], nextCursor: null };
    case 'hydrate':
      return {
        kind: 'data',
        data: { cursor: 'next' },
        revision: INITIAL_CACHE_REVISION,
      };
    case 'write':
    case 'commit-optimistic-write':
    case 'rollback-optimistic-write':
      return EMPTY_WRITE;
    case 'enqueue-optimistic-mutation':
      return {
        ...EMPTY_WRITE,
        transactionId: '1',
        initialClaim: { kind: 'not-runnable' },
      };
    case 'inspect-mutations':
    case 'inspect-query':
    case 'inspect-query-variants':
      return [];
    case 'claim-next-mutation':
      return undefined;
    case 'invalidate':
    case 'delete-records':
      return { revision: INITIAL_CACHE_REVISION, affectedOps: request.keys };
    case 'init':
    case 'defer-optimistic-write':
    case 'teardown':
      return null;
    case 'clear':
      return INITIAL_CACHE_REVISION;
  }
}

class FakePageAdapter {
  onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;
  readonly requests: CacheRequest[] = [];
  readonly start = vi.fn(async (): Promise<void> => {});
  readonly ignoredKinds = new Set<CacheRequest['kind']>();
  readonly errors = new Map<CacheRequest['kind'], string>();
  readonly dispose = vi.fn(
    async (_options: PageAdapterDisposeOptions = {}): Promise<void> => {}
  );

  constructor(readonly options: CacheCoordinatorPageAdapterOptions) {}

  postMessage(request: CacheRequest): void {
    this.requests.push(request);
    if (this.ignoredKinds.has(request.kind)) return;
    const error = this.errors.get(request.kind);
    queueMicrotask(() => {
      if (error === undefined) this.respond(request.id, responseFor(request));
      else this.reject(request.id, error);
    });
  }

  respond(id: number, result: unknown): void {
    this.emit({ id, ok: true, result });
  }

  reject(id: number, error: string, errorCode?: CacheResponseErrorCode): void {
    this.emit({
      id,
      ok: false,
      error,
      ...(errorCode === undefined ? {} : { errorCode }),
    });
  }

  push(message: WorkerMessage | unknown): void {
    this.emit(message as WorkerMessage);
  }

  replace(
    ownerEpoch: number,
    openOutcome: EngineOpenOutcome = 'opened-existing'
  ): void {
    this.options.onEngineReplaced?.(ownerEpoch, openOutcome);
  }

  protocolError(error: Error): void {
    this.options.onProtocolError?.(error);
  }

  terminalError(error: Error): void {
    this.options.onTerminalError?.(error);
  }

  unavailable(reason: string): void {
    this.options.onCacheUnavailable?.(reason);
  }

  superseded(reason: string): void {
    this.options.onCacheSuperseded?.(reason);
  }

  private emit(message: WorkerMessage): void {
    this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);
  }
}

let lastAdapter: FakePageAdapter | undefined;
let configureAdapter: (adapter: FakePageAdapter) => void;
let sharedWorkerConstructor: ReturnType<typeof vi.fn>;
let dedicatedWorkerConstructor: ReturnType<typeof vi.fn>;
let indexedDbDelete: ReturnType<typeof vi.fn>;

function stubSupportedBrowser(): void {
  sharedWorkerConstructor = vi.fn();
  dedicatedWorkerConstructor = vi.fn();
  vi.stubGlobal('SharedWorker', sharedWorkerConstructor);
  vi.stubGlobal('Worker', dedicatedWorkerConstructor);
  vi.stubGlobal('MessageChannel', vi.fn());
  indexedDbDelete = vi.fn(() => ({
    onblocked: null,
    onerror: null,
    onsuccess: null,
  }));
  vi.stubGlobal('indexedDB', { deleteDatabase: indexedDbDelete });
  vi.stubGlobal('navigator', {
    locks: {
      request: vi.fn(
        async (
          name: string,
          _options: LockOptions,
          callback: (lock: Lock | null) => unknown
        ) => await callback({ name, mode: 'exclusive' } as Lock)
      ),
    },
    storage: { getDirectory: vi.fn() },
  });
}

function requireAdapter(): FakePageAdapter {
  if (!lastAdapter) throw new Error('page adapter was not constructed');
  return lastAdapter;
}

describe('createWorkerCacheHost', () => {
  beforeEach(() => {
    localStorage.clear();
    stubSupportedBrowser();
    vi.spyOn(crypto, 'randomUUID').mockReturnValue(CLIENT_ID);
    lastAdapter = undefined;
    configureAdapter = () => undefined;
    adapterFactory.mockReset();
    adapterFactory.mockImplementation(
      (options: CacheCoordinatorPageAdapterOptions) => {
        const fake = new FakePageAdapter(options);
        configureAdapter(fake);
        lastAdapter = fake;
        return fake as unknown as CacheCoordinatorPageAdapter;
      }
    );
  });

  afterEach(() => {
    vi.useRealTimers();
    vi.unstubAllGlobals();
    vi.restoreAllMocks();
  });

  it('uses a storage-free no-op host when a required capability is unavailable', async () => {
    vi.stubGlobal('SharedWorker', undefined);
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});

    const host = createWorkerCacheHost({ scope: 'scope-1' });

    expect(warn).toHaveBeenCalledWith(
      '[graphql-cache] disabled: SharedWorker is not supported by this browser'
    );
    expect(adapterFactory).not.toHaveBeenCalled();
    expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
    expect(indexedDbDelete).not.toHaveBeenCalled();
    expect(host.disabled).toBe(true);
    await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({
      kind: 'miss',
    });
    await expect(
      host.writeQuery({ query: '{ x }', data: { x: 1 } })
    ).resolves.toEqual(EMPTY_WRITE);
  });

  it("refuses a scope whose database would read as another scope's WAL file", () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});

    const host = createWorkerCacheHost({ scope: 'scope-1-wal' });

    expect(warn).toHaveBeenCalledWith(
      '[graphql-cache] disabled: cache scope must not end with -wal'
    );
    expect(adapterFactory).not.toHaveBeenCalled();
    expect(host.disabled).toBe(true);
  });

  it('routes hydration through the payload-projecting RPC', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });

    await expect(
      host.hydrateQuery({
        query: 'query Backfill { items @cacheOnly { id } cursor }',
        data: { items: [{ id: '1' }], cursor: 'next' },
        identity: 'user-1',
      })
    ).resolves.toEqual({
      kind: 'data',
      data: { cursor: 'next' },
      revision: INITIAL_CACHE_REVISION,
    });

    expect(requireAdapter().requests).toContainEqual(
      expect.objectContaining({
        kind: 'hydrate',
        query: 'query Backfill { items @cacheOnly { id } cursor }',
        data: { items: [{ id: '1' }], cursor: 'next' },
        identity: 'user-1',
      })
    );
  });

  it('reads the durable generation through initialization without requiring a reset notification', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await expect(host.currentStorageGeneration()).resolves.toBe(
      STORAGE_GENERATION
    );
    expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
      'init',
      'current-storage-generation',
    ]);
    host.dispose();
  });

  it('notifies generation subscribers only when a live cache change resets storage', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.currentStorageGeneration();
    const changed = vi.fn();
    const unsubscribe = host.onCacheGenerationChanged(changed);
    requireAdapter().push({
      kind: 'cache-changed',
      revision: INITIAL_CACHE_REVISION,
    });
    expect(changed).not.toHaveBeenCalled();
    requireAdapter().push({
      kind: 'cache-changed',
      revision: INITIAL_CACHE_REVISION,
      reset: true,
    });
    expect(changed).toHaveBeenCalledExactlyOnceWith({ storage: 'reset' });
    unsubscribe();
    requireAdapter().push({
      kind: 'cache-changed',
      revision: INITIAL_CACHE_REVISION,
      reset: true,
    });
    expect(changed).toHaveBeenCalledOnce();
    host.dispose();
  });

  it('uses the no-op host when OPFS is unavailable', () => {
    vi.stubGlobal('navigator', {
      locks: { request: vi.fn() },
      storage: {},
    });
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});

    const host = createWorkerCacheHost({ scope: 'scope-1' });

    expect(host.disabled).toBe(true);
    expect(warn).toHaveBeenCalledWith(
      '[graphql-cache] disabled: OPFS is not supported by this browser'
    );
    expect(adapterFactory).not.toHaveBeenCalled();
  });

  it('does not false-gate worker-only sync access handle capability', async () => {
    vi.stubGlobal('FileSystemFileHandle', undefined);
    vi.stubGlobal('FileSystemSyncAccessHandle', undefined);
    configureAdapter = (fake) => {
      fake.errors.set('init', 'sync access handles unavailable in engine');
    };
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });

    expect(host.disabled).not.toBe(true);
    await expect(host.clear()).rejects.toThrow(
      'sync access handles unavailable in engine'
    );
    expect(adapterFactory).toHaveBeenCalledOnce();
    expect(onInitializationError).toHaveBeenCalledOnce();
  });

  it('treats teardown as local cleanup after initialization failure and disposal', async () => {
    configureAdapter = (fake) => {
      fake.errors.set('init', 'injected initialization failure');
    };
    const host = createWorkerCacheHost({ scope: 'scope-1' });

    await expect(host.clear()).rejects.toThrow(
      'injected initialization failure'
    );
    host.dispose();
    await expect(host.teardown(7)).resolves.toBeUndefined();

    expect(
      requireAdapter().requests.filter((request) => request.kind === 'teardown')
    ).toEqual([]);
  });

  it('samples origin storage pressure periodically and clears the timer on dispose', async () => {
    vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
    const estimate = vi.fn(async () => ({ usage: 25, quota: 100 }));
    vi.stubGlobal('navigator', {
      ...(navigator as unknown as Record<string, unknown>),
      storage: {
        getDirectory: vi.fn(),
        estimate,
        persisted: vi.fn(async () => true),
      },
    });
    const observations: Array<Record<string, unknown>> = [];
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      storageHealthIntervalMs: 1_000,
      telemetry: {
        record: (observation) => observations.push(observation),
        flush: vi.fn(),
      },
    });

    await host.readQuery({ query: 'query Ready { value }' });
    await Promise.resolve();
    expect(estimate).toHaveBeenCalledOnce();
    await vi.advanceTimersByTimeAsync(2_000);
    expect(estimate).toHaveBeenCalledTimes(3);

    host.dispose();
    await vi.advanceTimersByTimeAsync(2_000);
    expect(estimate).toHaveBeenCalledTimes(3);
    expect(
      observations.filter(
        (observation) =>
          observation.name === 'graphql_cache.origin_storage_pressure'
      )
    ).toHaveLength(3);
  });

  it('constructs the coordinator adapter and starts cutover cleanup lazily on first RPC', async () => {
    const host = createWorkerCacheHost({ scope: 'lazy-scope' });
    host.onOpsAffected(() => undefined);

    expect(adapterFactory).not.toHaveBeenCalled();
    expect(sharedWorkerConstructor).not.toHaveBeenCalled();
    expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
    expect(indexedDbDelete).not.toHaveBeenCalled();

    const read = host.readQuery({ query: '{ x }' });
    expect(adapterFactory).toHaveBeenCalledOnce();
    await vi.waitFor(() => expect(indexedDbDelete).toHaveBeenCalledOnce());
    expect(indexedDbDelete).toHaveBeenCalledWith('graphql-cache:lazy-scope');
    expect(adapterFactory).toHaveBeenCalledWith(
      expect.objectContaining({ scope: 'lazy-scope' })
    );
    await expect(read).resolves.toEqual({ kind: 'miss' });
    await host.clear();
    expect(requireAdapter().requests.map((request) => request.kind)).toEqual([
      'init',
      'read',
      'clear',
    ]);
    expect(indexedDbDelete).toHaveBeenCalledOnce();
    host.dispose();
  });

  it('preserves the complete CacheHost RPC surface, request ids, and call order', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1', hotCapacity: 42 });
    const claim = { owner: 'runner', generation: 'generation-1' };

    const results = await Promise.all([
      host.readQuery({
        opKey: 7,
        query: 'query Read { user { id } }',
        priority: 'user-visible',
        entityResolvers: [
          {
            parentType: 'GraphqlUser',
            fieldName: 'emailThread',
            targetType: 'GraphqlSoupEmailThread',
            argumentPath: ['input', 'threadId'],
          },
        ],
      }),
      host.readRecordsByKeys({
        document: 'fragment Item on GraphqlSoupDocument { id }',
        fragmentName: 'Item',
        keys: ['GraphqlSoupDocument:item-1'],
      }),
      host.search({
        profile: 'quick-access-v1',
        buckets: ['document'],
        query: 'plan',
        limit: 20,
        nowMs: 123,
      }),
      host.writeQuery({
        opKey: 8,
        registerDependencies: true,
        query: 'query Read { user { id } }',
        data: { user: { id: 'user-1' } },
        identity: 'user-1',
        entityResolvers: [
          {
            parentType: 'GraphqlUser',
            fieldName: 'emailThread',
            targetType: 'GraphqlSoupEmailThread',
            argumentPath: ['input', 'threadId'],
          },
        ],
      }),
      host.enqueueOptimisticMutation(
        {
          uuid: '00000000-0000-4000-8000-000000000005',
          opKey: 9,
          query: 'mutation Rename { rename { id } }',
          data: { rename: { id: 'doc-1' } },
        },
        { owner: 'runner', nowMs: 100, leaseExpiresAtMs: 1_100 }
      ),
      host.inspectQueryVariants({
        query: 'query Views { views }',
        path: [{ field: 'views' }],
      }),
      host.inspectQuery({
        query: 'query Views { views }',
        path: [{ field: 'views' }],
        variableFilters: [{ input: { limit: 20 } }],
      }),
      host.claimNextMutation('runner', 200, 1_200),
      host.deferOptimisticWrite('1', claim, 2_000, 'offline'),
      host.commitOptimisticWrite('1', claim, {
        query: 'mutation Rename { rename { id } }',
        data: { rename: { id: 'doc-1' } },
      }),
      host.rollbackOptimisticWrite('2', claim, 'denied', 'DRAFT_ALREADY_SENT'),
      host.invalidate(['User:1']),
      host.deleteRecords(['Document:1']),
      host.teardown(7),
      host.clear(),
    ]);

    const requests = requireAdapter().requests;
    expect(
      requests.find((request) => request.kind === 'rollback-optimistic-write')
    ).toMatchObject({ errorCode: 'DRAFT_ALREADY_SENT', error: 'denied' });
    expect(requests.map(({ id, kind }) => [id, kind])).toEqual([
      [1, 'init'],
      [2, 'read'],
      [3, 'read-records-by-keys'],
      [4, 'search'],
      [5, 'write'],
      [6, 'enqueue-optimistic-mutation'],
      [7, 'inspect-query-variants'],
      [8, 'inspect-query'],
      [9, 'claim-next-mutation'],
      [10, 'defer-optimistic-write'],
      [11, 'commit-optimistic-write'],
      [12, 'rollback-optimistic-write'],
      [13, 'invalidate'],
      [14, 'delete-records'],
      [15, 'teardown'],
      [16, 'clear'],
    ]);
    expect(requests[0]).toEqual({
      id: 1,
      kind: 'init',
      scope: 'scope-1',
      hotCapacity: 42,
    });
    expect(requests[1]).toEqual(
      expect.objectContaining({
        opId: `${CLIENT_ID}:7`,
        priority: 'user-visible',
        entityResolvers: [
          expect.objectContaining({
            parentType: 'GraphqlUser',
            fieldName: 'emailThread',
          }),
        ],
      })
    );
    expect(requests[3]).toEqual({
      id: 4,
      kind: 'search',
      request: {
        profile: 'quick-access-v1',
        buckets: ['document'],
        query: 'plan',
        limit: 20,
        nowMs: 123,
      },
    });
    expect(requests[5]).toEqual(
      expect.objectContaining({
        uuid: '00000000-0000-4000-8000-000000000005',
      })
    );
    expect(requests[4]).toEqual(
      expect.objectContaining({
        originOpId: `${CLIENT_ID}:8`,
        registration: {
          opId: `${CLIENT_ID}:8`,
          entityResolvers: [
            expect.objectContaining({
              parentType: 'GraphqlUser',
              fieldName: 'emailThread',
            }),
          ],
        },
      })
    );
    expect(requests[5]).toEqual(
      expect.objectContaining({
        originOpId: `${CLIENT_ID}:9`,
        owner: 'runner',
        createdAtMs: 100,
        nowMs: 100,
        leaseExpiresAtMs: 1_100,
      })
    );
    expect(requests[14]).toEqual({
      id: 15,
      kind: 'teardown',
      opId: `${CLIENT_ID}:7`,
    });
    expect(results[0]).toEqual({ kind: 'miss' });
    expect(results[2]).toEqual({ documents: [], nextCursor: null });
    expect(results[4]).toEqual(expect.objectContaining({ transactionId: '1' }));
    host.dispose();
  });

  it('follows coordinator phase deadlines instead of applying the read timeout to startup', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('init');
      fake.ignoredKinds.add('read');
    };
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 10,
      onInitializationError,
    });
    const read = host.readQuery({ query: '{ user }' });
    const rejected = expect(read).rejects.toThrow('cache worker timeout: read');
    await vi.advanceTimersByTimeAsync(0);
    const adapter = requireAdapter();
    const progress = (
      ownerEpoch: number,
      phase: 'loading-assets' | 'opening-database',
      timeoutMs: number
    ) =>
      adapter.options.onStartupProgress?.({
        coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
        kind: 'engine-startup',
        ownerEpoch,
        databaseAction: 'open-existing',
        phase,
        timeoutMs,
      });
    progress(1, 'loading-assets', 60_000);
    await vi.advanceTimersByTimeAsync(30_000);
    expect(onInitializationError).not.toHaveBeenCalled();
    progress(1, 'opening-database', 20_000);
    await vi.advanceTimersByTimeAsync(20_001);
    // The coordinator retries before the page's grace expires.
    progress(2, 'loading-assets', 60_000);
    await vi.advanceTimersByTimeAsync(30_000);
    expect(onInitializationError).not.toHaveBeenCalled();
    adapter.respond(1, null);
    await vi.advanceTimersByTimeAsync(11);
    await rejected;
    expect(onInitializationError).not.toHaveBeenCalled();
    host.dispose();
  });

  it('retries a transient coordinator registration failure without disabling or quarantining the cache', async () => {
    let attempt = 0;
    let first: FakePageAdapter | undefined;
    configureAdapter = (fake) => {
      if (attempt++ !== 0) return;
      first = fake;
      fake.start.mockImplementation(async () => {
        const error = new Error('SharedWorker load failed');
        fake.terminalError(error);
        throw error;
      });
    };
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    await expect(host.readQuery({ query: '{ user }' })).resolves.toEqual({
      kind: 'miss',
    });
    expect(adapterFactory).toHaveBeenCalledTimes(2);
    expect(first?.dispose).toHaveBeenCalledWith({ graceful: false });
    expect(first?.requests).toEqual([]);
    expect(onInitializationError).not.toHaveBeenCalled();
    host.dispose();
  });

  it('bounds hung coordinator registration retries and reports terminal failure only once', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) =>
      fake.start.mockImplementation(() => new Promise(() => {}));
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const rejected = expect(host.currentRevision()).rejects.toThrow(
      'cache worker timeout: registration'
    );
    await vi.advanceTimersByTimeAsync(
      COORDINATOR_CONNECT_TIMEOUT_MS * 3 + 100 + 200 + 1
    );
    await rejected;
    expect(adapterFactory).toHaveBeenCalledTimes(3);
    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(requireAdapter().requests).toEqual([]);
    expect(vi.getTimerCount()).toBe(0);
  });

  it('cancels coordinator registration on disposal without retrying or reporting failure', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) =>
      fake.start.mockImplementation(() => new Promise(() => {}));
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const rejected = expect(host.currentRevision()).rejects.toThrow(
      'disposed during startup'
    );
    host.dispose();
    await rejected;
    expect(adapterFactory).toHaveBeenCalledOnce();
    expect(onInitializationError).not.toHaveBeenCalled();
    expect(vi.getTimerCount()).toBe(0);
  });

  it.each([
    ['open-existing', true],
    ['open-existing', false],
    ['wipe-before-open', false],
  ] as const)(
    'requires coordinator proof to preserve a failed startup scope (%s, proof: %s)',
    async (databaseAction, provenUntouched) => {
      configureAdapter = (fake) => fake.ignoredKinds.add('init');
      localStorage.setItem('graphql-cache:scope', 'scope-1');
      const onInitializationError = vi.fn();
      const host = createWorkerCacheHost({
        scope: 'scope-1',
        onInitializationError,
      });
      const rejected = expect(host.currentRevision()).rejects.toThrow(
        'bootstrap attempts exhausted'
      );
      const adapter = requireAdapter();
      await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
      adapter.options.onStartupProgress?.({
        coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
        kind: 'engine-startup',
        ownerEpoch: 1,
        phase: 'loading-assets',
        databaseAction,
        timeoutMs: 60_000,
      });
      adapter.terminalError(
        provenUntouched
          ? new CacheBootstrapExhaustedError('bootstrap attempts exhausted')
          : new Error('bootstrap attempts exhausted')
      );
      await rejected;
      await vi.waitFor(() =>
        expect(onInitializationError).toHaveBeenCalledOnce()
      );
      expect(localStorage.getItem('graphql-cache:scope')).toBe(
        provenUntouched ? 'scope-1' : 'quarantine:scope-1'
      );
    }
  );

  it.each([false, true])(
    'pauses initialization during a blocked handoff without failing writes (replacement: %s)',
    async (replacement) => {
      vi.useFakeTimers();
      configureAdapter = (fake) => fake.ignoredKinds.add('init');
      localStorage.setItem('graphql-cache:scope', 'scope-1');
      const onInitializationError = vi.fn();
      const host = createWorkerCacheHost({
        scope: 'scope-1',
        initializationTimeoutMs: 10,
        onInitializationError,
      });
      const read = host.readQuery({ opKey: 7, query: 'query Read { user }' });
      const rejected = expect(read).rejects.toThrow('owner handoff timeout');
      const mutation = host.enqueueOptimisticMutation(
        {
          uuid: '00000000-0000-4000-8000-000000000100',
          query: 'mutation Update { update }',
          data: { update: true },
        },
        { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
      );
      await vi.advanceTimersByTimeAsync(0);
      const adapter = requireAdapter();
      adapter.options.onCacheReadAvailabilityChanged?.('blocked');
      await rejected;
      await vi.advanceTimersByTimeAsync(60_001);
      expect(adapter.requests.map(({ kind }) => kind)).toEqual(['init']);
      expect(onInitializationError).not.toHaveBeenCalled();
      expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
      if (replacement) adapter.replace(2);
      else adapter.options.onCacheReadAvailabilityChanged?.('ready');
      adapter.respond(1, null);
      await mutation;
      expect(adapter.requests.map(({ kind }) => kind)).toEqual([
        'init',
        'enqueue-optimistic-mutation',
      ]);
      await expect(
        host.readQuery({ query: 'query Recovered { user }' })
      ).resolves.toEqual({ kind: 'miss' });
      host.dispose();
    }
  );

  it('queues parked reads, writes, and teardown in call order without background timeouts', async () => {
    vi.useFakeTimers();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 10,
    });
    await host.currentRevision();
    const adapter = requireAdapter();
    adapter.ignoredKinds.add('read');
    adapter.ignoredKinds.add('write');
    adapter.ignoredKinds.add('teardown');
    adapter.options.onCacheReadAvailabilityChanged?.('waiting');
    const read = host.readQuery({ opKey: 7, query: 'query Parked { user }' });
    const write = host.writeQuery({
      query: 'query Parked { user }',
      data: { user: true },
    });
    const teardown = host.teardown(7);
    await vi.advanceTimersByTimeAsync(300_001);
    const queued = adapter.requests.filter((request) =>
      ['read', 'write', 'teardown'].includes(request.kind)
    );
    expect(queued.map((request) => request.kind)).toEqual([
      'read',
      'write',
      'teardown',
    ]);
    adapter.options.onCacheReadAvailabilityChanged?.('ready');
    for (const request of queued)
      adapter.respond(request.id, responseFor(request));
    await Promise.all([read, write, teardown]);
    host.dispose();
  });

  it('keeps an initially parked host initializing without failing reads or writes', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => fake.ignoredKinds.add('init');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      initializationTimeoutMs: 10,
      onInitializationError,
    });
    const read = host.readQuery({ query: 'query Initial { user }' });
    const write = host.writeQuery({
      query: 'query Initial { user }',
      data: { user: true },
    });
    await vi.advanceTimersByTimeAsync(0);
    const adapter = requireAdapter();
    adapter.options.onCacheReadAvailabilityChanged?.('waiting');
    await vi.advanceTimersByTimeAsync(300_001);
    expect(adapter.requests.map((request) => request.kind)).toEqual(['init']);
    expect(onInitializationError).not.toHaveBeenCalled();
    adapter.options.onCacheReadAvailabilityChanged?.('ready');
    adapter.respond(1, null);
    await Promise.all([read, write]);
    expect(adapter.requests.map((request) => request.kind)).toEqual([
      'init',
      'read',
      'write',
    ]);
    host.dispose();
  });

  it('bounds hung registration/init before admitting reads or mutations', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => fake.ignoredKinds.add('init');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 100,
      initializationTimeoutMs: 10,
      onInitializationError,
    });

    const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const readRejected = expect(read).rejects.toThrow(
      'cache worker timeout: init'
    );
    const mutationRejected = expect(mutation).rejects.toThrow(
      'cache worker timeout: init'
    );

    await vi.advanceTimersByTimeAsync(11);
    await Promise.all([readRejected, mutationRejected]);

    const adapter = requireAdapter();
    expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
      [1, 'init'],
    ]);
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(vi.getTimerCount()).toBe(0);
  });

  it.each(['current-revision', 'inspect-mutations'] as const)(
    'times out a hung %s request',
    async (kind) => {
      vi.useFakeTimers();
      configureAdapter = (fake) => fake.ignoredKinds.add(kind);
      const host = createWorkerCacheHost({
        scope: 'scope-1',
        requestTimeoutMs: 10,
      });

      const revision =
        kind === 'inspect-mutations'
          ? host.inspectMutations!()
          : host.currentRevision();
      const revisionRejected = expect(revision).rejects.toThrow(
        `cache worker timeout: ${kind}`
      );

      await vi.advanceTimersByTimeAsync(11);
      await revisionRejected;
      expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
        'init',
        kind,
      ]);
      host.dispose();
      expect(vi.getTimerCount()).toBe(0);
    }
  );

  it('recovers typed initial epoch loss with fresh init handshakes only', async () => {
    configureAdapter = (fake) => fake.ignoredKinds.add('init');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const affected: number[][] = [];
    host.onOpsAffected((keys) => affected.push(keys));

    const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const readRejected = expect(read).rejects.toMatchObject({
      message: 'owner epoch 1 was lost',
      errorCode: 'owner-epoch-lost',
    });
    const mutationRejected = expect(mutation).rejects.toMatchObject({
      message: 'owner epoch 1 was lost',
      errorCode: 'owner-epoch-lost',
    });
    const adapter = requireAdapter();
    await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
    adapter.reject(1, 'owner epoch 1 was lost', 'owner-epoch-lost');
    await Promise.all([readRejected, mutationRejected]);

    adapter.replace(2);
    expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
      [1, 'init'],
      [2, 'init'],
    ]);
    expect(affected).toEqual([]);
    adapter.reject(2, 'owner epoch 2 was lost', 'owner-epoch-lost');
    await Promise.resolve();

    adapter.replace(3);
    expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
      [1, 'init'],
      [2, 'init'],
      [3, 'init'],
    ]);
    expect(affected).toEqual([]);
    adapter.respond(3, null);
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(({ kind }) => kind === 'init')
      ).toHaveLength(3)
    );
    expect(affected).toEqual([]);

    expect(
      adapter.requests.filter(
        (request) =>
          request.kind === 'read' ||
          request.kind === 'enqueue-optimistic-mutation'
      )
    ).toEqual([]);
    expect(onInitializationError).not.toHaveBeenCalled();
    host.dispose();
  });

  it('suppresses replacement notification while an original init is queued', async () => {
    configureAdapter = (fake) => fake.ignoredKinds.add('init');
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected: number[][] = [];
    host.onOpsAffected((keys) => affected.push(keys));

    const read = host.readQuery({ opKey: 5, query: 'query Read { user }' });
    const adapter = requireAdapter();
    await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
    adapter.replace(2);
    adapter.respond(1, null);
    await expect(read).resolves.toEqual({ kind: 'miss' });

    expect(affected).toEqual([]);
    expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
      [1, 'init'],
      [2, 'read'],
    ]);
    host.dispose();
  });

  it('times out read-only RPC without timing out or replaying mutations', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('read');
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 10,
    });

    const read = host.readQuery({ query: 'query Read { user { id } }' });
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000006',
        query: 'mutation Rename { rename { id } }',
        data: { rename: { id: 'doc-1' } },
      },
      { owner: 'runner', nowMs: 123, leaseExpiresAtMs: 1_123 }
    );
    const readResult = expect(read).rejects.toThrow(
      'cache worker timeout: read'
    );
    let mutationSettled = false;
    void mutation.then(
      () => {
        mutationSettled = true;
      },
      () => {
        mutationSettled = true;
      }
    );

    await vi.advanceTimersByTimeAsync(11);
    await readResult;
    expect(mutationSettled).toBe(false);
    const adapter = requireAdapter();
    expect(
      adapter.requests.filter(
        (request) => request.kind === 'enqueue-optimistic-mutation'
      )
    ).toHaveLength(1);

    const mutationRequest = adapter.requests.find(
      (request) => request.kind === 'enqueue-optimistic-mutation'
    );
    adapter.respond(mutationRequest?.id as number, {
      ...EMPTY_WRITE,
      transactionId: '1',
      initialClaim: { kind: 'not-runnable' },
    });
    await expect(mutation).resolves.toEqual(
      expect.objectContaining({ transactionId: '1' })
    );
    expect(
      adapter.requests.filter(
        (request) => request.kind === 'enqueue-optimistic-mutation'
      )
    ).toHaveLength(1);
    host.dispose();
  });

  it('rejects old-epoch requests and never replays reads or durable mutations', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('read');
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected: number[][] = [];
    host.onOpsAffected((keys) => affected.push(keys));
    await host.clear();

    const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');
    const mutationRejected = expect(mutation).rejects.toThrow(
      'owner epoch 1 was lost'
    );
    const adapter = requireAdapter();
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          (request) =>
            request.kind === 'read' ||
            request.kind === 'enqueue-optimistic-mutation'
        )
      ).toHaveLength(2)
    );
    const oldEpochRequests = adapter.requests.filter(
      (request) =>
        request.kind === 'read' ||
        request.kind === 'enqueue-optimistic-mutation'
    );
    for (const request of oldEpochRequests) {
      adapter.reject(request.id, 'owner epoch 1 was lost', 'owner-epoch-lost');
    }
    await Promise.all([readRejected, mutationRejected]);

    adapter.replace(2);
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(({ kind }) => kind === 'init')
      ).toHaveLength(2)
    );
    expect(affected).toEqual([]);

    expect(
      adapter.requests.filter((request) => request.kind === 'init')
    ).toHaveLength(2);
    expect(
      adapter.requests.filter(
        (request) =>
          request.kind === 'read' ||
          request.kind === 'enqueue-optimistic-mutation'
      )
    ).toEqual(oldEpochRequests);
    host.dispose();
  });

  it('notifies a successfully registered key whose old-epoch reread was rejected', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected: number[][] = [];
    host.onOpsAffected((keys) => affected.push(keys));
    await host.clear();
    await Promise.all([
      host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
      host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),
    ]);
    const adapter = requireAdapter();
    adapter.ignoredKinds.add('read');

    const reread = host.readQuery({
      opKey: 7,
      query: 'query SlowSeven { seven }',
    });
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          (request) =>
            request.kind === 'read' && request.query.includes('SlowSeven')
        )
      ).toHaveLength(1)
    );
    const request = adapter.requests.find(
      (candidate) =>
        candidate.kind === 'read' && candidate.query.includes('SlowSeven')
    );
    adapter.reject(
      request?.id as number,
      'owner epoch 1 was lost',
      'owner-epoch-lost'
    );
    await expect(reread).rejects.toMatchObject({
      errorCode: 'owner-epoch-lost',
    });

    adapter.replace(2);
    await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));
    expect(
      adapter.requests.filter(
        (candidate) =>
          candidate.kind === 'read' && candidate.query.includes('SlowSeven')
      )
    ).toHaveLength(1);
    host.dispose();
  });

  it('notifies only registered active operations and deduplicates replacement epochs', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected: number[][] = [];
    const unsubscribe = host.onOpsAffected((keys) => affected.push(keys));
    await host.clear();

    await Promise.all([
      host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
      host.writeQuery({
        opKey: 9,
        registerDependencies: true,
        query: 'query Nine { nine }',
        data: { nine: 9 },
      }),
      host.readQuery({ query: 'query Untracked { untracked }' }),
    ]);
    const adapter = requireAdapter();
    adapter.replace(2);
    await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));

    await host.teardown(7);
    await host.readQuery({ opKey: 9, query: 'query NineAgain { nine }' });
    adapter.replace(2);
    adapter.replace(1);
    adapter.replace(3);
    adapter.replace(3);
    await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9]]));

    await Promise.all([
      host.readQuery({ opKey: 9, query: 'query NineThird { nine }' }),
      host.readQuery({ opKey: 7, query: 'query SevenAgain { seven }' }),
    ]);
    adapter.replace(4);
    await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9], [9, 7]]));
    unsubscribe();

    expect(affected).toEqual([[7, 9], [9], [9, 7]]);
    host.dispose();
  });

  it.each([
    ['opened-existing', 'preserved'],
    ['opened-new', 'reset'],
    ['reset-incompatible', 'reset'],
    ['reset-corrupt', 'reset'],
    ['reset-storage-uncertain', 'reset'],
  ] as const)(
    'invalidates engine dependencies but reports %s storage as %s',
    async (openOutcome, storage) => {
      const host = createWorkerCacheHost({ scope: 'scope-1' });
      const generations = vi.fn();
      const affected = vi.fn();
      const unsubscribe = host.onCacheGenerationChanged(generations);
      host.onOpsAffected(affected);
      await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
      const adapter = requireAdapter();
      adapter.replace(2, openOutcome);
      await vi.waitFor(() => expect(affected).toHaveBeenCalledWith([7]));
      expect(generations).toHaveBeenCalledExactlyOnceWith({ storage });
      expect(adapter.requests.filter((r) => r.kind === 'init')).toHaveLength(2);
      adapter.replace(2, 'reset-corrupt');
      adapter.replace(1, 'reset-corrupt');
      expect(generations).toHaveBeenCalledOnce();
      unsubscribe();
      adapter.replace(3, openOutcome);
      expect(generations).toHaveBeenCalledOnce();
      host.dispose();
    }
  );

  it.each(
    [[], ['note'], ['channel', 'dm']].map((searchChangedBuckets) => ({
      searchChangedBuckets,
    }))
  )(
    'forwards hydration search metadata $searchChangedBuckets',
    async ({ searchChangedBuckets }) => {
      const host = createWorkerCacheHost({ scope: 'scope-1' });
      const listener = vi.fn();
      host.onCacheChanged(listener, { includeHydration: true });
      await host.currentRevision();
      requireAdapter().push({
        kind: 'cache-hydrated',
        revision: INITIAL_CACHE_REVISION,
        searchChangedBuckets,
      });
      expect(listener).toHaveBeenCalledWith(INITIAL_CACHE_REVISION, {
        searchChangedBuckets,
      });
      host.dispose();
    }
  );

  it.each(
    [[], ['note']].map((searchChangedBuckets) => ({ searchChangedBuckets }))
  )(
    'forwards query-write metadata and ignores it on reset: $searchChangedBuckets',
    async ({ searchChangedBuckets }) => {
      const host = createWorkerCacheHost({ scope: 'scope-1' });
      const listener = vi.fn();
      host.onCacheChanged(listener);
      await host.currentRevision();
      requireAdapter().push({
        kind: 'cache-changed',
        revision: INITIAL_CACHE_REVISION,
        searchChangedBuckets,
      });
      expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION, {
        searchChangedBuckets,
      });
      requireAdapter().push({
        kind: 'cache-changed',
        revision: INITIAL_CACHE_REVISION,
        searchChangedBuckets,
        reset: true,
      });
      expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION);
      host.dispose();
    }
  );

  it('delivers hydration only to opted-in subscribers and cleans them up', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const foreground = vi.fn();
    const quickAccess = vi.fn();
    const operations = vi.fn();
    host.onCacheChanged(foreground);
    host.onOpsAffected(operations);
    const unsubscribe = host.onCacheChanged(quickAccess, {
      includeHydration: true,
    });
    await host.currentRevision();
    const adapter = requireAdapter();
    adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
    expect(quickAccess).toHaveBeenCalledOnce();
    expect(foreground).not.toHaveBeenCalled();
    expect(operations).not.toHaveBeenCalled();
    adapter.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });
    expect(quickAccess).toHaveBeenCalledTimes(2);
    expect(foreground).toHaveBeenCalledOnce();
    unsubscribe();
    adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
    expect(quickAccess).toHaveBeenCalledTimes(2);
    host.onCacheChanged(quickAccess, { includeHydration: true });
    host.dispose();
    adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
    expect(quickAccess).toHaveBeenCalledTimes(2);
  });

  it('strictly filters pushes to the exact client operation prefix', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected: number[][] = [];
    const cacheChanges = vi.fn();
    const settlements: unknown[] = [];
    host.onOpsAffected((keys) => affected.push(keys));
    host.onCacheChanged(cacheChanges);
    host.onMutationSettled((settlement) => settlements.push(settlement));
    await host.clear();

    const adapter = requireAdapter();
    adapter.push({
      kind: 'ops-affected',
      opIds: [
        `${CLIENT_ID}:7`,
        `${CLIENT_ID}:7`,
        `foreign:${CLIENT_ID}:8`,
        `${CLIENT_ID}0:9`,
        `${CLIENT_ID}:1e3`,
        `${CLIENT_ID}:0x10`,
        `${CLIENT_ID}:NaN`,
        `${CLIENT_ID}:9007199254740992`,
        `${CLIENT_ID}:007`,
        `${CLIENT_ID}:-0`,
        `${CLIENT_ID}:not-a-number`,
        `${CLIENT_ID}:`,
        `${CLIENT_ID}:12`,
      ],
      keys: ['User:1'],
    });
    adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });
    adapter.push({
      kind: 'cache-changed',
      revision: INITIAL_CACHE_REVISION,
    });
    adapter.push({
      kind: 'mutation-settled',
      settlement: { transactionId: '3', status: 'committed' },
    });

    expect(affected).toEqual([[7, 12]]);
    expect(cacheChanges).toHaveBeenCalledOnce();
    expect(settlements).toEqual([{ transactionId: '3', status: 'committed' }]);
    host.dispose();
  });

  it('reports initialization failure once, settles callers, and closes transport', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => {
      fake.errors.set('init', 'OPFS initialization failed');
    };
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 10,
      onInitializationError,
    });

    const read = host.readQuery({ query: 'query Read { user }' });
    const write = host.writeQuery({
      query: 'query Read { user }',
      data: { user: null },
    });
    const readRejected = expect(read).rejects.toThrow(
      'OPFS initialization failed'
    );
    const writeRejected = expect(write).rejects.toThrow(
      'OPFS initialization failed'
    );
    await vi.runAllTimersAsync();
    await Promise.all([readRejected, writeRejected]);

    const adapter = requireAdapter();
    adapter.protocolError(new Error('late coordinator error'));
    adapter.reject(1, 'late initialization response');

    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(onInitializationError).toHaveBeenCalledWith(
      expect.objectContaining({ message: 'OPFS initialization failed' })
    );
    expect(adapter.dispose).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
    expect(vi.getTimerCount()).toBe(0);
    host.dispose();
    expect(adapter.dispose).toHaveBeenCalledOnce();
  });

  it('terminal transport failure quarantines scope and rejects admitted mutations once', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const affected = vi.fn();
    host.onOpsAffected(affected);
    await host.clear();
    const adapter = requireAdapter();
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const transportError = new Error('coordinator MessagePort messageerror');
    const mutationRejected = expect(mutation).rejects.toMatchObject({
      message: expect.stringContaining('coordinator MessagePort messageerror'),
      errorCode: 'admitted-enqueue-uncertain',
      cause: transportError,
    });
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          (request) => request.kind === 'enqueue-optimistic-mutation'
        )
      ).toHaveLength(1)
    );

    adapter.terminalError(transportError);
    await mutationRejected;
    adapter.terminalError(new Error('duplicate terminal callback'));
    adapter.replace(2);

    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'quarantine:scope-1'
    );
    expect(affected).not.toHaveBeenCalled();
    expect(
      adapter.requests.filter(
        (request) => request.kind === 'enqueue-optimistic-mutation'
      )
    ).toHaveLength(1);
    await expect(host.clear()).rejects.toThrow(
      'coordinator MessagePort messageerror'
    );
  });

  it('stops using the cache without quarantine when another context holds the database', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('init');
    };
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const read = host.readQuery({ query: 'query Q { q }' });
    const unavailable = expect(read).rejects.toMatchObject({
      errorCode: 'owner-lock-unavailable',
    });
    await vi.waitFor(() =>
      expect(requireAdapter().requests.map(({ kind }) => kind)).toContain(
        'init'
      )
    );
    const adapter = requireAdapter();

    adapter.unavailable('cache database owner lock is held by another context');

    await unavailable;
    expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
      expect.objectContaining({ errorCode: 'owner-lock-unavailable' })
    );
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
    // Storage was never touched, so the scope stays reusable next load.
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
    await expect(
      host.readQuery({ query: 'query Q { q }' })
    ).rejects.toMatchObject({ errorCode: 'owner-lock-unavailable' });
    adapter.unavailable('duplicate notice');
    expect(onInitializationError).toHaveBeenCalledOnce();
  });

  it('retires a ready host once a request is refused because the database is unavailable', async () => {
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    await host.clear();
    const adapter = requireAdapter();
    adapter.ignoredKinds.add('read');
    const read = host.readQuery({ query: 'query Q { q }' });
    await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('read'));

    adapter.reject(
      adapter.requests.at(-1)?.id ?? -1,
      'cache database owner lock is held by another context',
      'owner-lock-unavailable'
    );

    await expect(read).rejects.toMatchObject({
      errorCode: 'owner-lock-unavailable',
    });
    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
  });

  it('retires quietly and asks the app to reload when a newer build takes over', async () => {
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const onSuperseded = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
      onSuperseded,
    });
    await host.clear();
    const adapter = requireAdapter();

    adapter.superseded('a newer version of the app took over the local cache');
    adapter.superseded('duplicate notice');

    expect(onSuperseded).toHaveBeenCalledOnce();
    expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
      expect.objectContaining({ errorCode: 'owner-lock-unavailable' })
    );
    // Leaving like a navigating page stops the engine without counting as a
    // lost owner, so the newer build opens the same database.
    expect(adapter.dispose).toHaveBeenCalledWith({
      graceful: false,
      preserveDatabase: true,
    });
    // The newer build opens the same database, so the scope is kept.
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
    await expect(
      host.readQuery({ query: 'query Q { q }' })
    ).rejects.toMatchObject({ errorCode: 'owner-lock-unavailable' });
  });

  it('reports an enqueue in flight at the handover as uncertain, never unsent', async () => {
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.clear();
    const adapter = requireAdapter();
    adapter.ignoredKinds.add('enqueue-optimistic-mutation');
    adapter.ignoredKinds.add('read');
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000101',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const read = host.readQuery({ query: 'query Q { q }' });
    // The newer build replays the queued row, so the page must not send the
    // mutation itself; the read never touched durable state.
    const mutationRejected = expect(mutation).rejects.toMatchObject({
      errorCode: 'admitted-enqueue-uncertain',
    });
    const readRejected = expect(read).rejects.toMatchObject({
      errorCode: 'owner-lock-unavailable',
    });
    await vi.waitFor(() =>
      expect(adapter.requests.map(({ kind }) => kind)).toEqual(
        expect.arrayContaining(['enqueue-optimistic-mutation', 'read'])
      )
    );

    adapter.superseded('a newer version of the app took over the local cache');

    await mutationRejected;
    await readRejected;
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
  });

  it('quarantines transport scope before invoking the product failure callback', async () => {
    let runLock!: () => Promise<void>;
    vi.stubGlobal('navigator', {
      locks: {
        request: vi.fn(
          <T>(
            _name: string,
            _options: LockOptions,
            callback: (lock: Lock | null) => T | PromiseLike<T>
          ) =>
            new Promise<T>((resolve, reject) => {
              runLock = async () => {
                try {
                  resolve(
                    await callback({
                      name: 'graphql-cache:scope-storage',
                      mode: 'exclusive',
                    } as Lock)
                  );
                } catch (error) {
                  reject(error);
                }
              };
            })
        ),
      },
      storage: { getDirectory: vi.fn() },
    });
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const callbackScopes: Array<string | null> = [];
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError: () => {
        callbackScopes.push(localStorage.getItem('graphql-cache:scope'));
      },
    });
    await host.clear();

    requireAdapter().terminalError(new Error('transport failed'));
    expect(callbackScopes).toEqual([]);
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
    await runLock();
    await vi.waitFor(() =>
      expect(callbackScopes).toEqual(['quarantine:scope-1'])
    );
  });

  it('converges same-scope failures and ignores stale or disposed host quarantine', async () => {
    const adapters: FakePageAdapter[] = [];
    adapterFactory.mockImplementation(
      (adapterOptions: CacheCoordinatorPageAdapterOptions) => {
        const fake = new FakePageAdapter(adapterOptions);
        adapters.push(fake);
        return fake as unknown as CacheCoordinatorPageAdapter;
      }
    );
    localStorage.setItem('graphql-cache:scope', 'shared-old');
    const firstError = vi.fn();
    const secondError = vi.fn();
    const first = createWorkerCacheHost({
      scope: 'shared-old',
      onInitializationError: firstError,
    });
    const second = createWorkerCacheHost({
      scope: 'shared-old',
      onInitializationError: secondError,
    });
    await Promise.all([first.clear(), second.clear()]);

    adapters[0]?.terminalError(new Error('first tab transport failed'));
    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'quarantine:shared-old'
    );
    adapters[1]?.terminalError(new Error('second tab transport failed'));
    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'quarantine:shared-old'
    );
    await vi.waitFor(() => {
      expect(firstError).toHaveBeenCalledOnce();
      expect(secondError).toHaveBeenCalledOnce();
    });

    const staleError = vi.fn();
    const stale = createWorkerCacheHost({
      scope: 'shared-old',
      onInitializationError: staleError,
    });
    await stale.clear();
    localStorage.setItem('graphql-cache:scope', 'new-healthy-scope');
    adapters[2]?.terminalError(new Error('late stale transport failed'));
    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'new-healthy-scope'
    );

    const disposedError = vi.fn();
    const disposed = createWorkerCacheHost({
      scope: 'shared-old',
      onInitializationError: disposedError,
    });
    await disposed.clear();
    disposed.dispose();
    adapters[3]?.terminalError(new Error('late disposed callback'));
    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'new-healthy-scope'
    );
    expect(disposedError).not.toHaveBeenCalled();
  });

  it('reports a lazy adapter-construction failure without leaking a transport', async () => {
    adapterFactory.mockImplementationOnce(() => {
      throw new Error('SharedWorker construction failed');
    });
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });

    expect(adapterFactory).not.toHaveBeenCalled();
    await expect(host.clear()).rejects.toThrow(
      'SharedWorker construction failed'
    );

    expect(adapterFactory).toHaveBeenCalledOnce();
    expect(onInitializationError).toHaveBeenCalledOnce();
    expect(lastAdapter).toBeUndefined();
    host.dispose();
  });

  it('disposes explicitly with graceful idempotence and drains pending mutation responses', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.clear();
    const adapter = requireAdapter();
    let finishDrain: (() => void) | undefined;
    const draining = new Promise<void>((resolve) => {
      finishDrain = resolve;
    });
    adapter.dispose.mockImplementationOnce(async () => await draining);
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          (request) => request.kind === 'enqueue-optimistic-mutation'
        )
      ).toHaveLength(1)
    );
    const mutationRequest = adapter.requests.find(
      (request) => request.kind === 'enqueue-optimistic-mutation'
    );

    host.dispose();
    host.dispose();
    expect(adapter.dispose).not.toHaveBeenCalled();
    adapter.respond(mutationRequest?.id as number, {
      ...EMPTY_WRITE,
      transactionId: '4',
      initialClaim: { kind: 'not-runnable' },
    });

    await expect(mutation).resolves.toEqual(
      expect.objectContaining({ transactionId: '4' })
    );
    finishDrain?.();
    await draining;
    expect(adapter.dispose).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
    await expect(host.clear()).rejects.toThrow(
      'cache worker host was disposed'
    );
  });

  it('keeps pagehide armed until graceful adapter retirement resolves', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.clear();
    const adapter = requireAdapter();
    let finishRetirement!: () => void;
    const retirement = new Promise<void>((resolve) => {
      finishRetirement = resolve;
    });
    adapter.dispose.mockImplementationOnce(async () => await retirement);

    host.dispose();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
    dispatchEvent(new Event('pagehide'));

    expect(adapter.dispose).toHaveBeenNthCalledWith(2, {
      graceful: false,
      preserveDatabase: true,
    });
    finishRetirement();
    await retirement;
    await expect(host.clear()).rejects.toThrow(
      'cache worker host was disposed'
    );
  });

  it('quarantines and reports transport failure during adapter retirement', async () => {
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    await host.clear();
    const adapter = requireAdapter();
    let finishRetirement!: () => void;
    const retirement = new Promise<void>((resolve) => {
      finishRetirement = resolve;
    });
    adapter.dispose.mockImplementationOnce(async () => await retirement);

    host.dispose();
    adapter.terminalError(new Error('SharedWorker failed during retirement'));

    expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });
    await vi.waitFor(() => {
      expect(localStorage.getItem('graphql-cache:scope')).toBe(
        'quarantine:scope-1'
      );
      expect(onInitializationError).toHaveBeenCalledOnce();
    });
    finishRetirement();
    await retirement;
  });

  it('waits for existing read timeout before gracefully disconnecting a requester', async () => {
    vi.useFakeTimers();
    configureAdapter = (fake) => fake.ignoredKinds.add('read');
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      requestTimeoutMs: 10,
    });
    await host.clear();
    const adapter = requireAdapter();
    const read = host.readQuery({ query: 'query Slow { slow }' });
    const readOutcome = read.then(
      () => undefined,
      (error: unknown) => error
    );
    await Promise.resolve();
    expect(adapter.requests.filter(({ kind }) => kind === 'read')).toHaveLength(
      1
    );

    host.dispose();
    expect(adapter.dispose).not.toHaveBeenCalled();
    await vi.advanceTimersByTimeAsync(11);
    await expect(readOutcome).resolves.toMatchObject({
      message: 'cache worker timeout: read',
    });

    expect(adapter.dispose).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
  });

  it('preserves transport uncertainty when graceful disposal is already draining admitted work', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    await host.clear();
    const adapter = requireAdapter();
    let finishDrain!: () => void;
    const draining = new Promise<void>((resolve) => {
      finishDrain = resolve;
    });
    adapter.dispose.mockImplementationOnce(async () => await draining);
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          ({ kind }) => kind === 'enqueue-optimistic-mutation'
        )
      ).toHaveLength(1)
    );

    host.dispose();
    adapter.terminalError(new Error('transport failed during drain'));
    await expect(mutation).rejects.toMatchObject({
      errorCode: 'admitted-enqueue-uncertain',
    });

    expect(localStorage.getItem('graphql-cache:scope')).toBe(
      'quarantine:scope-1'
    );
    expect(onInitializationError).toHaveBeenCalledOnce();
    finishDrain();
    await draining;
  });

  it('classifies admitted and late navigation writes consistently', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.currentRevision();
    const adapter = requireAdapter();
    adapter.ignoredKinds.add('write');
    const args = {
      query: 'subscription Updates { update }',
      data: { update: 1 },
    };
    const admitted = host.writeQuery(args);
    const rejected =
      expect(admitted).rejects.toBeInstanceOf(CacheNavigationError);
    await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('write'));
    dispatchEvent(new PageTransitionEvent('pagehide'));
    await rejected;
    await expect(host.writeQuery(args)).rejects.toBeInstanceOf(
      CacheNavigationError
    );
    dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
    await expect(host.currentRevision()).rejects.toBeInstanceOf(
      CacheNavigationError
    );
    expect(adapterFactory).toHaveBeenCalledOnce();
  });

  it('reconnects the same host repeatedly and retains subscriptions and active query dependencies', async () => {
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    const affected = vi.fn();
    const generations = vi.fn();
    const changed = vi.fn();
    const hydrated = vi.fn();
    const settled = vi.fn();
    host.onOpsAffected(affected);
    host.onCacheGenerationChanged(generations);
    host.onCacheChanged(changed);
    host.onCacheChanged(hydrated, { includeHydration: true });
    host.onMutationSettled(settled);

    for (let cycle = 0; cycle < 2; cycle += 1) {
      await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
      await host.readQuery({ opKey: 9, query: 'query Nine { nine }' });
      const old = requireAdapter();
      dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
      expect(old.dispose).toHaveBeenCalledWith({
        graceful: false,
        preserveDatabase: true,
      });
      await host.teardown(9);
      await expect(host.currentRevision()).rejects.toBeInstanceOf(
        CacheNavigationError
      );
      old.terminalError(new Error('late retired transport error'));
      dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
      dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
      await host.currentRevision();
      const replacement = requireAdapter();
      expect(replacement).not.toBe(old);
      expect(affected).toHaveBeenLastCalledWith([7]);
      expect(generations).toHaveBeenLastCalledWith({ storage: 'reset' });
      expect(host.clientId).toBe(CLIENT_ID);
      expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
      expect(replacement.options.scope).toBe('scope-1');
      old.replace(100);
      old.terminalError(new Error('late callback after restore'));
      old.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });
      expect(changed).toHaveBeenCalledTimes(cycle);
      replacement.push({
        kind: 'cache-changed',
        revision: INITIAL_CACHE_REVISION,
      });
      replacement.push({
        kind: 'cache-hydrated',
        revision: INITIAL_CACHE_REVISION,
      });
      replacement.push({
        kind: 'mutation-settled',
        settlement: { transactionId: '3', status: 'committed' },
      });
      expect(changed).toHaveBeenCalledTimes(cycle + 1);
      expect(hydrated).toHaveBeenCalledTimes((cycle + 1) * 2);
      expect(settled).toHaveBeenCalledTimes(cycle + 1);
    }
    expect(adapterFactory).toHaveBeenCalledTimes(3);
    expect(onInitializationError).not.toHaveBeenCalled();
    host.dispose();
  });

  it.each(['registration', 'init'] as const)(
    'restores when pagehide interrupts %s without resurrecting the old attempt',
    async (phase) => {
      configureAdapter = (fake) => {
        if (phase === 'registration')
          fake.start.mockImplementationOnce(() => new Promise(() => {}));
        else fake.ignoredKinds.add('init');
      };
      const onInitializationError = vi.fn();
      const host = createWorkerCacheHost({
        scope: 'scope-1',
        onInitializationError,
      });
      const affected = vi.fn();
      host.onOpsAffected(affected);
      const read = host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
      const rejected =
        expect(read).rejects.toBeInstanceOf(CacheNavigationError);
      const old = requireAdapter();
      if (phase === 'init')
        await vi.waitFor(() => expect(old.requests).toHaveLength(1));
      dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
      configureAdapter = () => undefined;
      // No intervening microtask: exercise the old startup's catch/finally racing restore.
      dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
      await rejected;
      await expect(host.currentRevision()).resolves.toBe(
        INITIAL_CACHE_REVISION
      );
      expect(requireAdapter()).not.toBe(old);
      expect(affected).toHaveBeenCalledWith([7]);
      expect(onInitializationError).not.toHaveBeenCalled();
      expect(adapterFactory).toHaveBeenCalledTimes(2);
      host.dispose();
    }
  );

  it.each([false, true])(
    'does not resurrect an explicitly disposed host (restore started: %s)',
    async (restoreStarted) => {
      const host = createWorkerCacheHost({ scope: 'scope-1' });
      await host.currentRevision();
      dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
      if (restoreStarted)
        dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
      host.dispose();
      dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
      await expect(host.currentRevision()).rejects.toThrow(
        'cache worker host was disposed'
      );
      await new Promise((resolve) => setTimeout(resolve, 0));
      expect(adapterFactory).toHaveBeenCalledOnce();
    }
  );

  it('reports a failed restore through normal initialization fallback', async () => {
    const onInitializationError = vi.fn();
    const host = createWorkerCacheHost({
      scope: 'scope-1',
      onInitializationError,
    });
    await host.currentRevision();
    dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
    configureAdapter = (fake) => fake.errors.set('init', 'restore failed');
    dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
    await expect(host.currentRevision()).rejects.toThrow('restore failed');
    expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
      expect.objectContaining({ message: 'restore failed' })
    );
    host.dispose();
  });

  it('revalidates reads attempted while suspended instead of counting them as replacement registrations', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    const affected = vi.fn();
    host.onOpsAffected(affected);
    await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
    dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
    for (const opKey of [7, 9]) {
      await expect(
        host.readQuery({ opKey, query: 'query Value { value }' })
      ).rejects.toBeInstanceOf(CacheNavigationError);
    }
    dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
    await host.currentRevision();
    expect(affected).toHaveBeenCalledWith([7, 9]);
    host.dispose();
  });

  it('fences a pre-navigation write waiting to be admitted across immediate restoration', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.currentRevision();
    const stale = host.writeQuery({
      query: 'query Value { value }',
      data: { value: 'stale' },
    });
    const rejected = expect(stale).rejects.toBeInstanceOf(CacheNavigationError);
    dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
    dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
    await rejected;
    await host.currentRevision();
    expect(requireAdapter().requests.some(({ kind }) => kind === 'write')).toBe(
      false
    );
    host.dispose();
  });

  it('never replays an uncertain enqueue after restoration', async () => {
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.currentRevision();
    const old = requireAdapter();
    old.ignoredKinds.add('enqueue-optimistic-mutation');
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const rejected = expect(mutation).rejects.toMatchObject({
      errorCode: 'admitted-enqueue-uncertain',
      cause: expect.any(CacheNavigationError),
    });
    await vi.waitFor(() =>
      expect(old.requests.at(-1)?.kind).toBe('enqueue-optimistic-mutation')
    );
    dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
    dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
    await rejected;
    await host.currentRevision();
    expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
      'init',
      'current-revision',
    ]);
    host.dispose();
  });

  it('treats pagehide enqueue as uncertain without quarantining persistent storage', async () => {
    configureAdapter = (fake) => {
      fake.ignoredKinds.add('enqueue-optimistic-mutation');
    };
    localStorage.setItem('graphql-cache:scope', 'scope-1');
    const host = createWorkerCacheHost({ scope: 'scope-1' });
    await host.clear();
    const adapter = requireAdapter();
    const mutation = host.enqueueOptimisticMutation(
      {
        uuid: '00000000-0000-4000-8000-000000000100',
        query: 'mutation Update { update }',
        data: { update: true },
      },
      { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
    );
    const rejected = expect(mutation).rejects.toMatchObject({
      message: expect.stringContaining('disposed for page navigation'),
      errorCode: 'admitted-enqueue-uncertain',
      cause: expect.any(CacheNavigationError),
    });
    await vi.waitFor(() =>
      expect(
        adapter.requests.filter(
          ({ kind }) => kind === 'enqueue-optimistic-mutation'
        )
      ).toHaveLength(1)
    );

    host.dispose();
    expect(adapter.dispose).not.toHaveBeenCalled();
    dispatchEvent(new Event('pagehide'));
    await rejected;

    expect(adapter.dispose).toHaveBeenCalledOnce();
    expect(adapter.dispose).toHaveBeenCalledWith({
      graceful: false,
      preserveDatabase: true,
    });
    expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
  });
});