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.

172 KB
Raw Blame
import type {
  Client,
  GraphQLRequest,
  Operation,
  OperationContext,
  OperationResult,
} from '@urql/core';
import { CombinedError } from '@urql/core';
import { type DocumentNode, print } from 'graphql';
import { createComputed, createRoot, createSignal } from 'solid-js';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { makeSubject } from 'wonka';
import {
  type LiveQueryUpdate,
  parseCacheRevision,
} from '../../../graphql-cache/protocol';

const getGraphqlSoupClientMock = vi.hoisted(() => vi.fn());
const getGraphqlSoupCacheHostMock = vi.hoisted(() => vi.fn());
const entityFilterMock = vi.hoisted(() => vi.fn());
const readRecordsByKeysMock = vi.hoisted(() => vi.fn());
const REVISION_0 = '0';
const REVISION_1 = '1';
const REVISION_2 = '2';
const mapGraphqlSoupItemMock = vi.hoisted(() => vi.fn((item) => item));
const mapSoupPageToEntityListMock = vi.hoisted(() =>
  vi.fn(
    (page, _options?: { showSupportedForeignEntities?: boolean }) => page.items
  )
);
const makeGraphqlSoupInputMock = vi.hoisted(() => vi.fn());

vi.mock('../../../graphql-cache/exchange/record-selection', () => ({
  selectRecords: vi.fn((document) => ({ document })),
  readRecordsByKeys: readRecordsByKeysMock,
}));

vi.mock('../../../graphql-cache/exchange/normalized-cache-exchange', () => ({
  normalizedCacheResultMetadata: (result: OperationResult) =>
    result.extensions?.__macroNormalizedCache,
}));

vi.mock('@service-storage/graphql-soup', () => ({
  emailThreadSortTs: (record: {
    latestInboundMessageTs?: string;
    updatedAt: string;
  }) => record.latestInboundMessageTs ?? record.updatedAt,
  getGraphqlSoupClient: getGraphqlSoupClientMock,
  getGraphqlSoupCacheHost: getGraphqlSoupCacheHostMock,
  hasGraphqlCacheHost: () => getGraphqlSoupCacheHostMock() !== undefined,
  graphqlSoupProjectionSupported: () => true,
  mapGraphqlSoupItem: mapGraphqlSoupItemMock,
}));

vi.mock('./ast', () => ({
  makeGraphqlSoupInput: makeGraphqlSoupInputMock,
}));

vi.mock('../transform-utils', () => ({
  mapApiSoupItemToEntity: vi.fn((item) => item),
  mapSoupPageToEntityList: mapSoupPageToEntityListMock,
}));

vi.mock('@queries/client', async () => {
  const { QueryClient } = await import('@tanstack/solid-query');
  return { queryClient: new QueryClient() };
});

import { queryClient } from '@queries/client';
import {
  delegateChannelNotificationRefresh,
  disposeChannelNotificationRefresh,
} from '../../channel/notification-refresh';
import { registerChannelNotificationRefresh } from '../../channel/register-notification-refresh';
import { getActiveGraphqlSoupRevalidations } from './active-queries';
import { createSoupLiveQuery } from './create-soup-live-query';
import { createGraphqlSoupAstItemsQuery } from './items';
import {
  createGraphqlSoupDeletion,
  GRAPHQL_SOUP_DELETE_MUTATION_KEY,
} from './optimistic-deletions';

type FakeExecution = {
  document: DocumentNode;
  context: Partial<OperationContext>;
  variables: Record<string, unknown>;
  fail(error: CombinedError): void;
  next(
    data: unknown,
    metadata?: {
      source: 'live-network' | 'normalized-cache-hit' | 'affected-cache-reread';
      revision?: string;
      persistence?: Promise<string | undefined>;
    },
    error?: CombinedError
  ): void;
};

type SoupPageFixture = {
  items: unknown[];
  next_cursor: string | null;
};

function graphqlSoupPage(page: SoupPageFixture) {
  return {
    user: {
      soup: {
        items: page.items.map((item) => ({
          __typename: 'GraphqlSoupDocument',
          createdAt: '2026-01-01T00:00:00Z',
          updatedAt: '2026-01-01T00:00:00Z',
          ...(item as object),
        })),
        nextCursor: page.next_cursor,
      },
    },
  };
}

function makeFakeClient(): {
  client: Client;
  executions: FakeExecution[];
} {
  const executions: FakeExecution[] = [];
  const execute = (
    _request: GraphQLRequest<unknown, Record<string, unknown>>,
    context: Partial<OperationContext>
  ) => {
    const subject =
      makeSubject<OperationResult<unknown, Record<string, unknown>>>();
    const operation = {
      kind: 'query',
      context,
    } as Operation<unknown, Record<string, unknown>>;
    executions.push({
      document: _request.query,
      context,
      variables: _request.variables,
      fail: (error) =>
        subject.next({ operation, error, stale: false, hasNext: false }),
      next: (
        data,
        metadata = { source: 'live-network', revision: REVISION_1 },
        error
      ) =>
        subject.next({
          operation,
          data,
          error,
          extensions: { __macroNormalizedCache: metadata },
          stale: false,
          hasNext: false,
        } as OperationResult<unknown, Record<string, unknown>>),
    });
    return subject.source;
  };

  return {
    executions,
    client: {
      executeQuery: execute,
    } as unknown as Client,
  };
}

function deferred<T>() {
  let resolve!: (value: T) => void;
  let reject!: (error: Error) => void;
  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });
  return { promise, resolve, reject };
}

/** Cached Mail thread records for `readRecordsByKeys`, named by their keys. */
function mailThreadRecords(requested: string[]) {
  return requested.map((key) => ({
    recordKey: key,
    record: {
      __typename: 'GraphqlSoupEmailThread',
      id: key.split(':')[1],
      name: key,
      mailAllPreview: {
        id: `${key}-preview`,
        subject: key,
        snippet: 'canonical',
        isDraft: false,
        senderEmail: null,
        senderName: null,
        senderPhotoUrl: null,
      },
      mailDraftPreview: null,
      mailSentPreview: null,
    },
  }));
}

describe('createGraphqlSoupAstItemsQuery', () => {
  beforeEach(() => {
    queryClient.clear();
    vi.clearAllMocks();
    mapSoupPageToEntityListMock.mockImplementation((page) => page.items);
    getGraphqlSoupCacheHostMock.mockReturnValue(undefined);
    makeGraphqlSoupInputMock.mockReturnValue({
      initial: { limit: 50, sortMethod: 'UPDATED_AT' },
    });
  });

  it('retains CRM dependency scope on opaque continuation pages', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const { query, dispose } = createRoot((dispose) => ({
      query: createSoupLiveQuery(() => ({
        sortMethod: 'UPDATED_AT',
        filters: {
          crmCompanyFilter: {
            literal: { id: '00000000-0000-0000-0000-000000000000' },
          },
          crmContactFilter: { literal: { hidden: false } },
        },
      })),
      dispose,
    }));
    try {
      await vi.waitFor(() => expect(fake.executions).toHaveLength(1));
      expect(fake.executions[0].context.externalCacheWriteTypes).toEqual([
        'GraphqlSoupCrmContact',
      ]);
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'page-2' })
      );
      const more = query.fetchNextPage();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      expect(fake.executions[1].variables).toMatchObject({
        input: { continuation: { cursor: 'page-2' } },
      });
      expect(fake.executions[1].context.externalCacheWriteTypes).toEqual([
        'GraphqlSoupCrmContact',
      ]);
      fake.executions[1].next(
        graphqlSoupPage({ items: [], next_cursor: null })
      );
      await more;
    } finally {
      dispose();
    }
  });

  it.each([
    { entityType: 'CHANNEL', typename: 'GraphqlSoupChannel' },
    { entityType: 'DOCUMENT', typename: 'GraphqlSoupDocument' },
  ] as const)(
    'resolves an all-cached $entityType lookup without a network request',
    async ({ entityType, typename }) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      const key = `${typename}:cached`;
      const changes = new Set<(revision: string) => void>();
      const evaluation = deferred<LiveQueryUpdate>();
      entityFilterMock.mockImplementation((args) =>
        args.liveQuery?.release
          ? Promise.resolve({ kind: 'unsupported' })
          : evaluation.promise
      );
      getGraphqlSoupCacheHostMock.mockReturnValue({
        liveQueries: true,
        currentRevision: async () => REVISION_0,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: (revision: string) => void) => {
          changes.add(callback);
          return () => changes.delete(callback);
        },
        onCacheGenerationChanged: () => () => {},
      });
      const ready = deferred<void>();
      const { query, dispose } = createRoot((dispose) => {
        const query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({
            enabled: true,
            ...(entityType === 'CHANNEL'
              ? { projection: 'channel-list' as const }
              : {}),
            cacheFirstEntities: [{ entityType, entityId: 'cached' }],
          })
        );
        createComputed(() => {
          if (query.cacheStatus?.() === 'ready') ready.resolve();
        });
        return { query, dispose };
      });
      try {
        expect(query.cacheStatus?.()).toBe('loading');
        expect(entityFilterMock).toHaveBeenCalledWith(
          expect.objectContaining({
            baseline: [],
            liveQuery: expect.any(Object),
          })
        );
        expect(fake.executions).toHaveLength(0);
        evaluation.resolve({
          kind: 'live-query',
          revision: parseCacheRevision(REVISION_0),
          reset: true,
          keys: [key],
          upserts: [
            {
              recordKey: key,
              record: {
                __typename: typename,
                id: 'cached',
                createdAt: '2026-01-01T00:00:00Z',
                updatedAt: '2026-01-01T00:00:00Z',
              },
            },
          ],
          patches: [],
          removed: [],
          retainedKeys: [],
          optimistic: false,
        });
        await ready.promise;
        expect(query.data()?.entities.map(({ id }) => id)).toEqual(['cached']);
        expect(query.cacheStatus?.()).toBe('ready');
        expect(query.isFetching()).toBe(false);
        expect(query.isEnabled()).toBe(true);
        expect(fake.executions).toHaveLength(0);
        expect(getActiveGraphqlSoupRevalidations(fake.client)).toHaveLength(1);
        const refresh = query.refresh();
        await vi.waitFor(() => expect(fake.executions).toHaveLength(1));
        fake.executions[0].next(
          graphqlSoupPage({
            items: [{ __typename: typename, id: 'cached' }],
            next_cursor: null,
          })
        );
        await refresh;
        expect(fake.executions).toHaveLength(1);
        entityFilterMock.mockResolvedValue({
          kind: 'live-query',
          revision: parseCacheRevision(REVISION_2),
          reset: true,
          keys: [],
          upserts: [],
          patches: [],
          removed: [],
          retainedKeys: [],
          optimistic: false,
        });
        for (const changed of changes) changed(REVISION_2);
        await vi.waitFor(() => expect(query.data()?.entities).toEqual([]));
      } finally {
        dispose();
      }
    }
  );

  it('keeps cached entities and a stable missing-ID request through pagination and retry', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const cached = {
      __typename: 'GraphqlSoupChannel' as const,
      id: 'cached',
      createdAt: '2026-01-01T00:00:00Z',
      updatedAt: '2026-01-01T00:00:00Z',
    };
    const callbacks = new Set<(revision: string) => void>();
    getGraphqlSoupCacheHostMock.mockReturnValue({
      liveQueries: true,
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: (revision: string) => void) => {
        callbacks.add(callback);
        return () => callbacks.delete(callback);
      },
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockImplementation(async (args) => ({
      kind: 'live-query',
      revision: parseCacheRevision(REVISION_1),
      reset: true,
      keys: [
        'GraphqlSoupChannel:cached',
        ...args.baseline.map(({ key }: { key: string }) => key),
      ],
      upserts: [{ recordKey: 'GraphqlSoupChannel:cached', record: cached }],
      patches: [],
      removed: [],
      retainedKeys: args.baseline.map(({ key }: { key: string }) => key),
      optimistic: false,
    }));
    const { query, dispose } = createRoot((dispose) => ({
      query: createSoupLiveQuery(
        () => ({ sortMethod: 'CREATED_AT', limit: 4 }),
        () => ({
          cacheFirstEntities: [
            { entityType: 'CHANNEL', entityId: 'cached' },
            { entityType: 'DOCUMENT', entityId: 'cached' },
            { entityType: 'CHANNEL', entityId: 'first' },
            { entityType: 'CHANNEL', entityId: 'second' },
          ],
        })
      ),
      dispose,
    }));
    try {
      await vi.waitFor(() => expect(fake.executions).toHaveLength(1));
      const request = fake.executions[0].variables;
      expect(JSON.stringify(request)).not.toContain('"channelId":"cached"');
      expect(JSON.stringify(request)).toContain('"channelId":"first"');
      expect(JSON.stringify(request)).toContain('"channelId":"second"');
      expect(JSON.stringify(request)).toContain('"id":"cached"');
      const persistence = deferred<string | undefined>();
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ ...cached, id: 'first' }],
          next_cursor: 'page-2',
        }),
        { source: 'live-network', persistence: persistence.promise }
      );
      expect(query.data()?.map((row) => row.id)).toEqual(['cached', 'first']);
      const more = query.fetchNextPage();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      for (const callback of callbacks) callback(REVISION_1);
      await vi.waitFor(() => expect(query.cacheStatus()).toBe('ready'));
      expect(fake.executions).toHaveLength(2);
      fake.executions[1].fail(
        new CombinedError({ networkError: new Error('page unavailable') })
      );
      await more;
      expect(query.data()?.map((row) => row.id)).toEqual(['cached', 'first']);
      expect(query.fetchError()).toBeDefined();

      const retry = query.refresh();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(3));
      expect(fake.executions[2].variables).toEqual(request);
      fake.executions[2].next(
        graphqlSoupPage({
          items: [{ ...cached, id: 'first' }],
          next_cursor: 'page-2',
        })
      );
      await vi.waitFor(() => expect(fake.executions).toHaveLength(4));
      fake.executions[3].next(
        graphqlSoupPage({
          items: [
            { ...cached, id: 'second' },
            { ...cached, __typename: 'GraphqlSoupDocument', id: 'cached' },
          ],
          next_cursor: null,
        })
      );
      await retry;
      persistence.resolve(undefined);
      expect(
        query
          .data()
          ?.map((row) => `${row.__typename}:${row.id}`)
          .sort()
      ).toEqual([
        'GraphqlSoupChannel:cached',
        'GraphqlSoupChannel:first',
        'GraphqlSoupChannel:second',
        'GraphqlSoupDocument:cached',
      ]);
      expect(query.hasNextPage()).toBe(false);
      expect(fake.executions).toHaveLength(4);
      const deletion = createGraphqlSoupDeletion([
        'GraphqlSoupDocument:cached',
      ]);
      const pending = deferred<void>();
      const mutation = queryClient.getMutationCache().build(queryClient, {
        mutationKey: GRAPHQL_SOUP_DELETE_MUTATION_KEY,
        onMutate: () => ({ graphqlDeletion: deletion }),
        mutationFn: () => pending.promise,
        onSettled: () => deletion.release(),
      });
      const completion = mutation.execute(undefined);
      try {
        await vi.waitFor(() =>
          expect(
            query
              .data()
              ?.map((row) => `${row.__typename}:${row.id}`)
              .sort()
          ).toEqual([
            'GraphqlSoupChannel:cached',
            'GraphqlSoupChannel:first',
            'GraphqlSoupChannel:second',
          ])
        );
      } finally {
        pending.resolve();
        await completion;
      }
      expect(query.data()).toHaveLength(4);
    } finally {
      dispose();
    }
  });

  it('restarts missing-ID hydration after a cache generation changes', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const cached = {
      __typename: 'GraphqlSoupChannel' as const,
      id: 'cached',
      createdAt: '2026-01-01T00:00:00Z',
      updatedAt: '2026-01-01T00:00:00Z',
    };
    let hasCachedRow = true;
    const generations = new Set<() => void>();
    entityFilterMock.mockImplementation(async () => ({
      kind: 'live-query',
      revision: parseCacheRevision(REVISION_0),
      reset: true,
      keys: hasCachedRow ? ['GraphqlSoupChannel:cached'] : [],
      upserts: hasCachedRow
        ? [{ recordKey: 'GraphqlSoupChannel:cached', record: cached }]
        : [],
      patches: [],
      removed: [],
      retainedKeys: [],
      optimistic: false,
    }));
    getGraphqlSoupCacheHostMock.mockReturnValue({
      liveQueries: true,
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: (callback: () => void) => {
        generations.add(callback);
        return () => generations.delete(callback);
      },
    });
    const { query, dispose } = createRoot((dispose) => ({
      query: createSoupLiveQuery(
        () => ({ sortMethod: 'CREATED_AT', limit: 2 }),
        () => ({
          projection: 'channel-list',
          cacheFirstEntities: [
            { entityType: 'CHANNEL', entityId: 'cached' },
            { entityType: 'CHANNEL', entityId: 'missing' },
          ],
        })
      ),
      dispose,
    }));
    try {
      await vi.waitFor(() => expect(fake.executions).toHaveLength(1));
      hasCachedRow = false;
      for (const changed of generations) changed();
      await vi.waitFor(() => expect(query.cacheStatus()).toBe('ready'));
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      expect(JSON.stringify(fake.executions[1].variables)).toContain(
        '"channelId":"cached"'
      );
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ ...cached, id: 'stale' }],
          next_cursor: null,
        })
      );
      expect(query.data()?.some((row) => row.id === 'stale')).not.toBe(true);
      fake.executions[1].next(
        graphqlSoupPage({
          items: [cached, { ...cached, id: 'missing' }],
          next_cursor: null,
        })
      );
      expect(query.data()?.map((row) => row.id)).toEqual(['cached', 'missing']);
    } finally {
      dispose();
    }
  });

  it('fetches uncached channels without repeating a successful omission', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const { query, dispose } = createRoot((dispose) => ({
      query: createSoupLiveQuery(
        () => ({ sortMethod: 'CREATED_AT', limit: 1 }),
        () => ({
          projection: 'channel-list',
          cacheFirstEntities: [{ entityType: 'CHANNEL', entityId: 'missing' }],
        })
      ),
      dispose,
    }));
    try {
      await vi.waitFor(() => expect(fake.executions).toHaveLength(1));
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: null })
      );
      expect(query.data()).toEqual([]);
      expect(query.isFetching()).toBe(false);
      expect(fake.executions).toHaveLength(1);
    } finally {
      dispose();
    }
  });

  it.each([
    { name: 'current host', supported: true, includesInvite: true },
    { name: 'older host omits row', supported: false, includesInvite: false },
    {
      name: 'older host omits preview',
      supported: false,
      includesInvite: true,
    },
  ])(
    'keeps server mail during incomplete cache refreshes ($name)',
    async ({ supported, includesInvite }) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: { emailView: 'INBOX', sortMethod: 'UPDATED_AT', limit: 20 },
      });
      let revision = REVISION_1;
      let archived = false;
      let hydrated = false;
      let changed: (revision: string) => void = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof changed) => {
          changed = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      const normalKey = 'GraphqlSoupEmailThread:normal';
      const inviteKey = 'GraphqlSoupEmailThread:invite';
      entityFilterMock.mockImplementation(async () => ({
        kind: 'mail-page',
        revision,
        keys:
          includesInvite && !archived ? [inviteKey, normalKey] : [normalKey],
        ...(supported ? { retainedKeys: archived ? [] : [inviteKey] } : {}),
        sortTimestamps: ['2026-01-02T00:00:00Z', '2026-01-01T00:00:00Z'],
        nextCursor: null,
        optimistic: false,
      }));
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: mailThreadRecords([normalKey, inviteKey]).map((row) => ({
          ...row,
          record: {
            ...row.record,
            emailName: 'Preview from another tab',
            ...(!hydrated && row.recordKey === inviteKey
              ? { mailAllPreview: null }
              : {}),
          },
        })),
      }));
      const { query, dispose } = createRoot((dispose) => ({
        dispose,
        query: createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        ),
      }));
      try {
        fake.executions[0].next(
          graphqlSoupPage({
            items: ['invite', 'normal'].map((id) => ({
              __typename: 'GraphqlSoupEmailThread',
              id,
              emailName:
                id === 'invite' ? 'Calendar invitation' : 'Ordinary email',
              latestInboundMessageTs: '2026-01-02T00:00:00Z',
            })),
            next_cursor: null,
          })
        );
        await vi.waitFor(() => expect(query.data()?.entities).toHaveLength(2));
        revision = REVISION_2;
        changed(revision);
        await vi.waitFor(() =>
          expect(entityFilterMock).toHaveBeenCalledWith(
            expect.objectContaining({
              baseline: expect.arrayContaining([
                { key: inviteKey, sortTimestamp: '2026-01-02T00:00:00Z' },
              ]),
            })
          )
        );
        if (includesInvite)
          await vi.waitFor(() => expect(query.data()?.cachedMail).toBe(true));
        else
          await vi.waitFor(() =>
            expect(query.cacheMaintained?.()).not.toBe(true)
          );
        expect(query.data()?.entities.map((row) => row.id)).toEqual([
          'invite',
          'normal',
        ]);
        expect(query.data()?.entities[0]).toMatchObject({
          emailName: 'Calendar invitation',
        });
        expect(query.cacheMaintained?.()).toBe(false);
        expect(
          getActiveGraphqlSoupRevalidations(undefined, {
            unmaintainedOnly: true,
          })
        ).not.toHaveLength(0);
        if (supported) {
          archived = true;
          revision = '3';
          changed(revision);
          await vi.waitFor(() =>
            expect(query.data()?.entities.map((row) => row.id)).toEqual([
              'normal',
            ])
          );
        } else if (includesInvite) {
          hydrated = true;
          revision = '3';
          changed(revision);
          await vi.waitFor(() =>
            expect(query.data()?.entities[0]).toMatchObject({
              emailName: inviteKey,
            })
          );
        }
        if (!supported) {
          expect(query.cacheMaintained?.()).toBe(false);
          archived = true;
          revision = '4';
          changed(revision);
          const refresh = query.refresh();
          fake.executions.at(-1)!.next(
            graphqlSoupPage({
              items: [{ __typename: 'GraphqlSoupEmailThread', id: 'normal' }],
              next_cursor: null,
            }),
            { source: 'live-network', revision }
          );
          await refresh;
          expect(query.data()?.entities.map((row) => row.id)).toEqual([
            'normal',
          ]);
        }
      } finally {
        dispose();
      }
    }
  );

  it('keeps retained previews while read state changes before and after settlement', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = '1';
    let changed: (revision: string) => void = () => {};
    let isRead = false;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof changed) => {
        changed = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = 'GraphqlSoupEmailThread:invite';
    entityFilterMock.mockImplementation(async () => ({
      kind: 'mail-page',
      revision,
      keys: [key],
      retainedKeys: [key],
      sortTimestamps: ['2026-01-01T00:00:00Z'],
      nextCursor: null,
      optimistic: revision === '2',
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: [
        {
          recordKey: key,
          record: {
            __typename: 'GraphqlSoupEmailThread',
            id: 'invite',
            isRead,
            inboxVisible: true,
            isSignal: false,
            emailName: 'Another view',
            mailAllPreview: null,
          },
        },
      ],
    }));
    const { source, dispose } = createRoot((dispose) => ({
      dispose,
      source: createSoupLiveQuery(() => ({
        emailView: 'INBOX',
        sortMethod: 'UPDATED_AT',
        limit: 20,
      })),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [
            {
              __typename: 'GraphqlSoupEmailThread',
              id: 'invite',
              isRead: false,
              inboxVisible: true,
              emailName: 'Invitation',
            },
          ],
          next_cursor: null,
        })
      );
      revision = '2';
      isRead = true;
      changed(revision);
      await vi.waitFor(() =>
        expect(source.data()?.[0]).toMatchObject({
          isRead: true,
          emailName: 'Invitation',
        })
      );
      expect(source.cacheMaintained()).toBe(false);
      revision = '3';
      changed(revision);
      await vi.waitFor(() => expect(source.localRevision()).toBe('3'));
      expect(source.data()?.[0]).toMatchObject({
        isRead: true,
        emailName: 'Invitation',
      });
      isRead = false;
      revision = '4';
      changed(revision);
      await vi.waitFor(() =>
        expect(source.data()?.[0]).toMatchObject({
          isRead: false,
          emailName: 'Invitation',
        })
      );
    } finally {
      dispose();
    }
  });

  it('merges retained rows across a Mail cursor before publishing the next page', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = '1';
    let changed: (revision: string) => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof changed) => {
        changed = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = (id: string) => `GraphqlSoupEmailThread:${id}`;
    entityFilterMock.mockImplementation(async ({ mail }) => ({
      kind: 'mail-page',
      revision,
      keys: (mail.through === 'end'
        ? ['first', 'second', 'retained']
        : mail.cursor
          ? ['second']
          : ['first', 'retained']
      ).map(key),
      retainedKeys: mail.cursor ? [] : [key('retained')],
      sortTimestamps:
        mail.through === 'end'
          ? [
              '2026-01-03T00:00:00Z',
              '2026-01-02T00:00:00Z',
              '2026-01-01T00:00:00Z',
            ]
          : mail.cursor
            ? ['2026-01-02T00:00:00Z']
            : ['2026-01-03T00:00:00Z', '2026-01-01T00:00:00Z'],
      endCursor: mail.cursor || mail.through === 'end' ? 'end' : 'first',
      nextCursor: mail.cursor || mail.through === 'end' ? null : 'next',
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, keys) => ({
        revision,
        records: mailThreadRecords(keys),
      })
    );
    const { source, dispose } = createRoot((dispose) => ({
      dispose,
      source: createSoupLiveQuery(() => ({
        emailView: 'INBOX',
        sortMethod: 'UPDATED_AT',
        limit: 1,
      })),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [
            {
              __typename: 'GraphqlSoupEmailThread',
              id: 'retained',
              emailName: 'Invitation',
            },
          ],
          next_cursor: null,
        })
      );
      revision = '2';
      changed(revision);
      await vi.waitFor(() => expect(source.cachedMail()).toBe(true));
      expect(source.data()?.map((row) => row.id)).toEqual([
        'first',
        'retained',
      ]);
      await source.fetchNextPage();
      expect(source.data()?.map((row) => row.id)).toEqual([
        'first',
        'second',
        'retained',
      ]);
    } finally {
      dispose();
    }
  });

  it('discards a local Mail projection when the server baseline exceeds its bound', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = '1';
    let changed: (revision: string) => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof changed) => {
        changed = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = 'GraphqlSoupEmailThread:one';
    entityFilterMock.mockImplementation(async () => ({
      kind: 'mail-page',
      revision,
      keys: [key],
      retainedKeys: [],
      sortTimestamps: ['2026-01-01T00:00:00Z'],
      nextCursor: null,
      endCursor: 'previous-depth',
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: mailThreadRecords([key]),
    }));
    const { source, dispose } = createRoot((dispose) => ({
      dispose,
      source: createSoupLiveQuery(() => ({
        emailView: 'INBOX',
        sortMethod: 'UPDATED_AT',
        limit: 20,
      })),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'one' }],
          next_cursor: null,
        })
      );
      revision = '2';
      changed(revision);
      await vi.waitFor(() => expect(source.cachedMail()).toBe(true));
      const refresh = source.refresh();
      const items = Array.from({ length: 5001 }, (_, i) => ({
        __typename: 'GraphqlSoupEmailThread',
        id: i === 0 ? 'one' : String(i),
        emailName: 'Fresh server row',
      }));
      fake.executions
        .at(-1)!
        .next(graphqlSoupPage({ items, next_cursor: null }), {
          source: 'live-network',
          revision: '3',
        });
      await refresh;
      revision = '4';
      changed(revision);
      await vi.waitFor(() => expect(source.cachedMail()).toBe(false));
      expect(source.cacheMaintained()).toBe(false);
      expect(source.data()?.[0]).toMatchObject({
        emailName: 'Fresh server row',
      });
      entityFilterMock.mockClear();
      source.resetToInitialPage();
      fake.executions.at(-1)!.next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'one' }],
          next_cursor: null,
        }),
        { source: 'normalized-cache-hit', revision }
      );
      await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalled());
      expect(entityFilterMock.mock.calls[0][0].mail.through).toBeUndefined();
    } finally {
      dispose();
    }
  });

  it('reconciles late server rows even when the local list is already longer', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = '1';
    let changed: (revision: string) => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof changed) => {
        changed = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = (id: string) => `GraphqlSoupEmailThread:${id}`;
    entityFilterMock.mockImplementation(async ({ baseline }) => {
      const ids = baseline?.some(
        (entry: { key: string }) => entry.key === key('late')
      )
        ? ['late', 'one', 'two']
        : ['one', 'two'];
      return {
        kind: 'mail-page',
        revision,
        keys: ids.map(key),
        retainedKeys: [],
        sortTimestamps: ids.map(() => '2026-01-01T00:00:00Z'),
        nextCursor: null,
        optimistic: false,
      };
    });
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, keys) => ({
        revision,
        records: mailThreadRecords(keys),
      })
    );
    const { source, dispose } = createRoot((dispose) => ({
      dispose,
      source: createSoupLiveQuery(() => ({
        emailView: 'INBOX',
        sortMethod: 'UPDATED_AT',
        limit: 20,
      })),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'one' }],
          next_cursor: null,
        })
      );
      revision = '2';
      changed(revision);
      await vi.waitFor(() => expect(source.cachedMail()).toBe(true));
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'late' }],
          next_cursor: null,
        }),
        { source: 'normalized-cache-hit', revision }
      );
      await vi.waitFor(() =>
        expect(source.data()?.map((row) => row.id)).toEqual([
          'late',
          'one',
          'two',
        ])
      );
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: null }),
        { source: 'normalized-cache-hit', revision }
      );
      await vi.waitFor(() =>
        expect(source.data()?.map((row) => row.id)).toEqual(['one', 'two'])
      );
      expect(source.cacheMaintained()).toBe(true);
    } finally {
      dispose();
    }
  });

  it('keeps recovery refreshes enabled when server evidence arrives during pagination', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = '1';
    let changed: (revision: string) => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof changed) => {
        changed = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = (id: string) => `GraphqlSoupEmailThread:${id}`;
    const merged = {
      kind: 'mail-page' as const,
      revision: '2',
      keys: ['first', 'second', 'retained'].map(key),
      retainedKeys: [key('retained')],
      sortTimestamps: [
        '2026-01-03T00:00:00Z',
        '2026-01-02T00:00:00Z',
        '2026-01-01T00:00:00Z',
      ],
      nextCursor: null,
      endCursor: 'end',
      optimistic: false,
    };
    const evaluation = deferred<typeof merged>();
    let paging = false;
    entityFilterMock.mockImplementation(async ({ mail, baseline }) => {
      if (mail.cursor) {
        paging = true;
        fake.executions[0].next(
          graphqlSoupPage({
            items: ['first', 'retained'].map((id) => ({
              __typename: 'GraphqlSoupEmailThread',
              id,
            })),
            next_cursor: null,
          }),
          { source: 'normalized-cache-hit', revision }
        );
        return {
          ...merged,
          keys: [key('second')],
          retainedKeys: [],
          sortTimestamps: [merged.sortTimestamps[1]],
        };
      }
      if (mail.through === 'end') return merged;
      if (
        paging &&
        baseline.some((entry: { key: string }) => entry.key === key('retained'))
      ) {
        return evaluation.promise;
      }
      return {
        ...merged,
        revision,
        keys: [key('first')],
        retainedKeys: [],
        sortTimestamps: [merged.sortTimestamps[0]],
        endCursor: 'first',
        nextCursor: 'next',
      };
    });
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, keys: string[]) => ({
        revision,
        records: mailThreadRecords(
          keys.filter((key) => !key.endsWith(':retained'))
        ),
      })
    );
    const { source, dispose } = createRoot((dispose) => ({
      dispose,
      source: createSoupLiveQuery(() => ({
        emailView: 'INBOX',
        sortMethod: 'UPDATED_AT',
        limit: 1,
      })),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'first' }],
          next_cursor: null,
        })
      );
      revision = '2';
      changed(revision);
      await vi.waitFor(() => expect(source.cacheMaintained()).toBe(true));
      await source.fetchNextPage();
      expect(source.data()?.map((row) => row.id)).toEqual([
        'first',
        'second',
        'retained',
      ]);
      expect(source.cacheMaintained()).toBe(false);
      expect(
        getActiveGraphqlSoupRevalidations(undefined, { unmaintainedOnly: true })
      ).not.toHaveLength(0);
    } finally {
      evaluation.resolve(merged);
      dispose();
    }
  });

  it("hands the query's email view to the item mapper", async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    makeGraphqlSoupInputMock.mockReturnValue({
      initial: { limit: 50, sortMethod: 'UPDATED_AT', emailView: 'INBOX' },
    });
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ __typename: 'GraphqlSoupEmailThread', id: 'invite' }],
          next_cursor: null,
        })
      );
      expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
        'invite',
      ]);
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledWith(
        expect.objectContaining({ id: 'invite' }),
        { emailView: 'INBOX' }
      );
    } finally {
      dispose();
    }
  });

  it('owns fetching, continuation arguments, refresh and reset from a Soup declaration', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const filters = {
      projectFilter: { literal: { projectIdSelf: 'project' } },
    };
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createSoupLiveQuery(() => ({
        filters,
        sortMethod: 'UPDATED_AT',
        sortDirection: 'ASC',
        emailView: 'ALL',
        limit: 2,
      })),
    }));
    try {
      expect(fake.executions[0].variables).toEqual({
        input: {
          initial: {
            filters,
            sortMethod: 'UPDATED_AT',
            sortDirection: 'ASC',
            emailView: 'ALL',
            limit: 2,
            expand: true,
          },
        },
      });
      fake.executions[0].next(
        graphqlSoupPage({ items: [{ id: 'one' }], next_cursor: 'next' })
      );
      expect(query.data()?.map((row) => row.id)).toEqual(['one']);
      const more = query.fetchNextPage();
      expect(fake.executions[1].variables).toEqual({
        input: {
          continuation: {
            cursor: 'next',
            sortDirection: 'ASC',
            emailView: 'ALL',
            expand: true,
          },
        },
      });
      fake.executions[1].next(
        graphqlSoupPage({ items: [{ id: 'two' }], next_cursor: null })
      );
      await more;
      expect(query.data()?.map((row) => row.id)).toEqual(['one', 'two']);
      query.resetToInitialPage();
      expect(query.data()?.map((row) => row.id)).toEqual(['one']);
      const refresh = query.refresh();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(3));
      fake.executions[2].next(
        graphqlSoupPage({ items: [{ id: 'fresh' }], next_cursor: null })
      );
      await refresh;
      expect(query.data()?.map((row) => row.id)).toEqual(['fresh']);
      expect(mapGraphqlSoupItemMock).not.toHaveBeenCalled();
    } finally {
      dispose();
    }
  });

  it.each(['write', 'hydration'])(
    'constructs a live baseline from fetched pages and applies %s deltas through the public source',
    async (kind) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_1;
      const listeners = new Map<(value: string) => void, boolean>();
      const record = {
        __typename: 'GraphqlSoupDocument',
        id: 'one',
        documentName: 'Before',
        createdAt: '2026-01-01T00:00:00Z',
        updatedAt: '2026-01-01T00:00:00Z',
      };
      const key = 'GraphqlSoupDocument:one';
      getGraphqlSoupCacheHostMock.mockReturnValue({
        liveQueries: true,
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (
          callback: (value: string) => void,
          options?: { includeHydration?: boolean }
        ) => {
          listeners.set(callback, options?.includeHydration === true);
          return () => listeners.delete(callback);
        },
        onCacheGenerationChanged: () => () => {},
      });
      entityFilterMock.mockImplementation(async (args) =>
        args.liveQuery?.release
          ? { kind: 'unsupported' }
          : {
              kind: 'live-query',
              revision,
              reset: !args.liveQuery.since,
              ...(!args.liveQuery.since ? { keys: [key] } : {}),
              upserts: !args.liveQuery.since
                ? [{ recordKey: key, record }]
                : [],
              patches: args.liveQuery.since
                ? [
                    {
                      recordKey: key,
                      fields: [{ path: ['documentName'], value: 'After' }],
                      identity: { mutationUuid: null, pending: false },
                    },
                  ]
                : [],
              removed: [],
              retainedKeys: [],
              optimistic: false,
            }
      );
      const { query, dispose } = createRoot((dispose) => ({
        dispose,
        query: createSoupLiveQuery(() => ({
          filters: {},
          sortMethod: 'UPDATED_AT',
          limit: 50,
        })),
      }));
      try {
        fake.executions[0].next(
          graphqlSoupPage({ items: [record], next_cursor: null }),
          { source: 'live-network', revision }
        );
        await vi.waitFor(() =>
          expect(query.data()?.[0]).toMatchObject({ documentName: 'Before' })
        );
        await vi.waitFor(() =>
          expect(entityFilterMock).toHaveBeenCalledWith(
            expect.objectContaining({
              baseline: [{ key, sortTimestamp: record.updatedAt }],
              liveQuery: expect.anything(),
            })
          )
        );
        const row = query.data()?.[0];
        const rows = query.data();
        revision = REVISION_2;
        listeners.forEach((includeHydration, callback) => {
          if (kind === 'write' || includeHydration) callback(revision);
        });
        await vi.waitFor(() =>
          expect(query.data()?.[0]).toMatchObject({ documentName: 'After' })
        );
        expect(query.data()?.[0]).toBe(row);
        expect(query.data()).toBe(rows);
        expect(readRecordsByKeysMock).not.toHaveBeenCalled();
        expect(fake.executions).toHaveLength(1);
      } finally {
        dispose();
      }
    }
  );

  it.each([
    { localReconciliation: undefined, maintained: true },
    { localReconciliation: 'without-email' as const, maintained: false },
  ])(
    'reports a live list cache-maintained only once its query is ready ($localReconciliation)',
    async ({ localReconciliation, maintained }) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      const record = {
        __typename: 'GraphqlSoupDocument',
        id: 'one',
        documentName: 'Doc',
        createdAt: '2026-01-01T00:00:00Z',
        updatedAt: '2026-01-01T00:00:00Z',
      };
      const key = 'GraphqlSoupDocument:one';
      getGraphqlSoupCacheHostMock.mockReturnValue({
        liveQueries: true,
        currentRevision: async () => REVISION_1,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: () => () => {},
      });
      const firstEvaluation = deferred<unknown>();
      entityFilterMock.mockImplementation(async (args) =>
        args.liveQuery?.release
          ? { kind: 'unsupported' }
          : firstEvaluation.promise
      );
      const { query, dispose } = createRoot((dispose) => ({
        dispose,
        query: createSoupLiveQuery(
          () => ({ filters: {}, sortMethod: 'UPDATED_AT', limit: 50 }),
          () => ({ localReconciliation })
        ),
      }));
      try {
        fake.executions[0].next(
          graphqlSoupPage({ items: [record], next_cursor: null }),
          { source: 'live-network', revision: REVISION_1 }
        );
        await vi.waitFor(() =>
          expect(entityFilterMock).toHaveBeenCalledWith(
            expect.objectContaining({ liveQuery: expect.anything() })
          )
        );
        // Still loading, the list shows the server page: writes read it again.
        expect(query.cacheMaintained?.()).toBe(false);
        firstEvaluation.resolve({
          kind: 'live-query',
          revision: REVISION_1,
          reset: true,
          keys: [key],
          upserts: [{ recordKey: key, record }],
          patches: [],
          removed: [],
          retainedKeys: [],
          optimistic: false,
        });
        // A folder list keeps its email rows from the server.
        await vi.waitFor(() =>
          expect(query.cacheMaintained?.()).toBe(maintained)
        );
      } finally {
        dispose();
      }
    }
  );

  it('keeps fetched timestamp coverage when a live version of the same row has a different timestamp', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_1;
    let notify = (_revision: string) => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof notify) => {
        notify = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockImplementation(async () => ({
      kind: 'reconciled',
      revision,
      keys: ['GraphqlSoupDocument:one'],
      retainedKeys: [],
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: [
        {
          recordKey: 'GraphqlSoupDocument:one',
          record: {
            __typename: 'GraphqlSoupDocument',
            id: 'one',
            name: 'Live version',
            updatedAt: '2026-09-10T00:00:00Z',
          },
        },
      ],
    }));
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [
            { id: 'one', name: 'Fetched', updatedAt: '2026-09-01T00:00:00Z' },
          ],
          next_cursor: 'next',
        })
      );
      revision = REVISION_2;
      notify(revision);
      await vi.waitFor(() =>
        expect(query.data()?.entities[0]?.name).toBe('Live version')
      );
      expect(query.data()?.oldestFetchedTimestamp).toBe(
        Date.parse('2026-09-01T00:00:00Z')
      );
      expect(query.hasNextPage()).toBe(true);
    } finally {
      dispose();
    }
  });

  it('uses maintained record deltas without rereading the list or its fragments', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_1;
    const listeners = new Set<(revision: string) => void>();
    const record = {
      __typename: 'GraphqlSoupDocument',
      id: 'task',
      type: 'document',
      name: 'Before',
      createdAt: '2026-01-01T00:00:00Z',
      updatedAt: '2026-01-01T00:00:00Z',
    };
    const key = 'GraphqlSoupDocument:task';
    getGraphqlSoupCacheHostMock.mockReturnValue({
      liveQueries: true,
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: (revision: string) => void) => {
        listeners.add(callback);
        return () => listeners.delete(callback);
      },
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockImplementation(async (args) =>
      args.liveQuery?.release
        ? { kind: 'unsupported' }
        : {
            kind: 'live-query',
            revision,
            reset: !args.liveQuery?.since,
            ...(!args.liveQuery?.since ? { keys: [key] } : {}),
            upserts: !args.liveQuery?.since ? [{ recordKey: key, record }] : [],
            patches: args.liveQuery?.since
              ? [
                  {
                    recordKey: key,
                    fields: [{ path: ['name'], value: 'After' }],
                    identity: { mutationUuid: null, pending: false },
                  },
                ]
              : [],
            removed: [],
            retainedKeys: [],
            optimistic: false,
          }
    );
    const state = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ ...record, name: 'Server' }],
          next_cursor: null,
        }),
        { source: 'normalized-cache-hit', revision: REVISION_1 }
      );
      await vi.waitFor(() =>
        expect(state.query.data()?.entities[0]?.name).toBe('Before')
      );
      await vi.waitFor(() =>
        expect(
          entityFilterMock.mock.calls.some(([args]) => args.liveQuery)
        ).toBe(true)
      );
      const entity = state.query.data()?.entities[0];
      revision = REVISION_2;
      listeners.forEach((listener) => listener(revision));
      await vi.waitFor(() =>
        expect(state.query.data()?.entities[0]?.name).toBe('After')
      );
      expect(state.query.data()?.entities[0]).toBe(entity);
      expect(readRecordsByKeysMock).not.toHaveBeenCalled();
      expect(fake.executions).toHaveLength(1);
    } finally {
      state.dispose();
    }
  });

  describe('cached response errors before local reconciliation', () => {
    function fixture() {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      const local = deferred<unknown>();
      let resetGeneration = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => REVISION_0,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: (callback: () => void) => {
          resetGeneration = callback;
          return () => {};
        },
      });
      entityFilterMock.mockReturnValue(local.promise);
      const [limit, setLimit] = createSignal(50);
      makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
        cursor ? { continuation: { cursor } } : { initial: { limit: limit() } }
      );
      const root = createRoot((dispose) => ({
        dispose,
        query: createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({
            enabled: true,
            projection: 'channel-list',
            keepPreviousData: true,
          })
        ),
      }));
      const error = new CombinedError({
        networkError: new TypeError('Failed to fetch'),
      });
      return {
        ...root,
        fake,
        error,
        setLimit,
        resetGeneration: () => resetGeneration(),
        cached(empty = false, failure?: CombinedError) {
          fake.executions.at(-1)!.next(
            graphqlSoupPage({
              items: empty ? [] : [{ id: 'cached-channel' }],
              next_cursor: 'next',
            }),
            { source: 'normalized-cache-hit', revision: REVISION_0 },
            failure
          );
        },
        dispose() {
          root.dispose();
          local.resolve({ kind: 'unsupported' });
        },
      };
    }

    it.each([false, true])(
      'keeps cached results quiet while reconciliation is pending (empty=%s)',
      (empty) => {
        const f = fixture();
        try {
          f.cached(empty);
          f.fake.executions[0].fail(f.error);
          expect(f.query.data()?.entities).toHaveLength(empty ? 0 : 1);
          expect(f.query.error()).toBeUndefined();
          expect(f.query.fetchError?.()).toBe(f.error);
        } finally {
          f.dispose();
        }
      }
    );

    it('clears an early failure when a delayed cache hit carries the same error', () => {
      const f = fixture();
      try {
        f.fake.executions[0].fail(f.error);
        expect(f.query.error()).toBe(f.error);
        expect(f.query.data()).toBeUndefined();
        f.cached(false, f.error);
        expect(f.query.data()?.entities).toHaveLength(1);
        expect(f.query.error()).toBeUndefined();
      } finally {
        f.dispose();
      }
    });

    it('does not use retained data from other filters or a reset cache generation', () => {
      const f = fixture();
      try {
        f.cached();
        f.setLimit(20);
        f.fake.executions.at(-1)!.fail(f.error);
        expect(f.query.error()).toBe(f.error);
        f.cached(false, f.error);
        expect(f.query.error()).toBeUndefined();
        f.resetGeneration();
        expect(f.query.error()).toBe(f.error);
      } finally {
        f.dispose();
      }
    });

    it('keeps a failed load-more request visible despite cached earlier pages', async () => {
      const f = fixture();
      try {
        f.cached();
        const more = f.query.fetchNextPage();
        f.fake.executions.at(-1)!.fail(f.error);
        await more;
        expect(f.query.data()?.entities).toHaveLength(1);
        expect(f.query.error()).toBe(f.error);
      } finally {
        f.dispose();
      }
    });

    it.each([
      new CombinedError({ graphQLErrors: ['Forbidden'] }),
      new CombinedError({
        networkError: new TypeError('Failed to fetch'),
        graphQLErrors: ['Resolver failed'],
      }),
      ...[401, 403, 503].map(
        (status) =>
          new CombinedError({
            networkError: new Error('HTTP failure'),
            response: { status },
          })
      ),
    ])('does not suppress server errors with cached data: %s', (error) => {
      const f = fixture();
      try {
        f.cached(false, error);
        expect(f.query.error()).toBe(error);
      } finally {
        f.dispose();
      }
    });
  });

  describe('mixed folder contents', () => {
    const excludedId = '00000000-0000-0000-0000-000000000000';
    const item = (id: string, __typename = 'GraphqlSoupDocument') => ({
      id,
      __typename,
      projectId: 'folder-a',
      createdAt: '2026-01-01T00:00:00Z',
      updatedAt: '2026-01-02T00:00:00Z',
    });

    function fixture(localItems = [item('cached-document')]) {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_0;
      let notify: (revision: string) => void = () => {};
      const [folder, setFolder] = createSignal('folder-a');
      const filters = () => ({
        documentFilter: { literal: { projectId: folder() } },
        chatFilter: { literal: { projectId: folder() } },
        projectFilter: { literal: { projectId: folder() } },
        emailFilter: { tree: { literal: { projectId: folder() } } },
      });
      makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
        cursor
          ? { continuation: { cursor } }
          : {
              initial: {
                filters: filters(),
                emailView: 'ALL',
                sortMethod: 'UPDATED_AT',
                limit: 100,
              },
            }
      );
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof notify) => {
          notify = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      entityFilterMock.mockImplementation(async () => ({
        kind: 'reconciled',
        revision,
        keys: localItems.map((record) => `${record.__typename}:${record.id}`),
        retainedKeys: [],
        optimistic: false,
      }));
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: localItems.map((record) => ({
          recordKey: `${record.__typename}:${record.id}`,
          record,
        })),
      }));
      const { query, dispose } = createRoot((dispose) => ({
        dispose,
        query: createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true, localReconciliation: 'without-email' })
        ),
      }));
      return {
        fake,
        query,
        dispose,
        filters,
        setFolder,
        ids: () => query.data()?.entities.map((entity) => entity.id),
        push: () => {
          revision = String(Number(revision) + 1);
          notify(revision);
        },
      };
    }

    it('hydrates a never-visited folder without waiting for its mixed GraphQL response', async () => {
      const f = fixture([
        item('document'),
        item('chat', 'GraphqlSoupChat'),
        item('subfolder', 'GraphqlSoupProject'),
      ]);
      try {
        await vi.waitFor(() =>
          expect(f.ids()).toEqual(['document', 'chat', 'subfolder'])
        );
        expect(f.query.isLoading()).toBe(false);
        expect(f.query.isFetching()).toBe(true);
        expect(f.query.hasNextPage()).toBe(false);
        expect(f.fake.executions).toHaveLength(1);
        expect(f.fake.executions[0].variables).toMatchObject({
          input: { initial: { filters: f.filters(), emailView: 'ALL' } },
        });
        expect(entityFilterMock).toHaveBeenCalledWith({
          filters: {
            ...f.filters(),
            emailFilter: { tree: { literal: { threadId: excludedId } } },
          },
          sortMethod: 'UPDATED_AT',
          sortDirection: 'DESC',
          limit: 100,
          baseline: [],
        });
      } finally {
        f.dispose();
      }
    });

    it('retains server email and cursors across local reconciliation and later pages', async () => {
      const f = fixture();
      const email = item('email', 'GraphqlSoupEmailThread');
      const olderEmail = item('older-email', 'GraphqlSoupEmailThread');
      try {
        await vi.waitFor(() => expect(f.ids()).toEqual(['cached-document']));
        f.fake.executions[0].next(
          graphqlSoupPage({
            items: [item('server-document'), email],
            next_cursor: 'page-2',
          }),
          { source: 'normalized-cache-hit' }
        );
        f.push();
        await vi.waitFor(() =>
          expect(f.ids()).toEqual(['cached-document', 'email'])
        );
        expect(entityFilterMock.mock.lastCall?.[0].baseline).toEqual([
          {
            key: 'GraphqlSoupDocument:server-document',
            sortTimestamp: '2026-01-02T00:00:00Z',
          },
        ]);
        expect(f.query.hasNextPage()).toBe(true);
        const next = f.query.fetchNextPage();
        expect(f.fake.executions[1].variables).toEqual({
          input: {
            continuation: { cursor: 'page-2', emailView: 'ALL', expand: true },
          },
        });
        f.fake.executions[1].next(
          graphqlSoupPage({ items: [olderEmail], next_cursor: null }),
          { source: 'normalized-cache-hit' }
        );
        await next;
        await vi.waitFor(() =>
          expect(f.ids()).toEqual(['cached-document', 'email', 'older-email'])
        );
        expect(f.query.hasNextPage()).toBe(false);
        const refresh = f.query.refresh();
        f.fake.executions[2].next(
          graphqlSoupPage({ items: [email], next_cursor: null })
        );
        await refresh;
        expect(f.ids()).toEqual(['email']);
      } finally {
        f.dispose();
      }
    });

    it.each(['email-only', 'network-error'] as const)(
      'does not mistake an empty partial projection for an empty folder: %s',
      async (outcome) => {
        const f = fixture([]);
        try {
          await vi.waitFor(() =>
            expect(readRecordsByKeysMock).toHaveBeenCalled()
          );
          expect(f.query.data()).toBeUndefined();
          expect(f.query.isLoading()).toBe(true);
          if (outcome === 'network-error') {
            const error = new CombinedError({
              networkError: new Error('offline'),
            });
            f.fake.executions[0].fail(error);
            expect(f.query.error()).toBe(error);
            expect(f.query.data()).toBeUndefined();
          } else {
            f.fake.executions[0].next(
              graphqlSoupPage({
                items: [item('email', 'GraphqlSoupEmailThread')],
                next_cursor: null,
              })
            );
            expect(f.ids()).toEqual(['email']);
          }
        } finally {
          f.dispose();
        }
      }
    );

    it.each([false, true])(
      'requires visible local rows before suppressing loading/errors unless server data exists: %s',
      async (hasServerData) => {
        const f = fixture();
        const deletion = createGraphqlSoupDeletion([
          'GraphqlSoupDocument:cached-document',
        ]);
        const pending = deferred<void>();
        const mutation = queryClient.getMutationCache().build(queryClient, {
          mutationKey: GRAPHQL_SOUP_DELETE_MUTATION_KEY,
          onMutate: () => ({ graphqlDeletion: deletion }),
          mutationFn: () => pending.promise,
          onSettled: () => deletion.release(),
        });
        let completion: Promise<void> | undefined;
        try {
          await vi.waitFor(() => expect(f.ids()).toEqual(['cached-document']));
          if (hasServerData) {
            f.fake.executions[0].next(
              graphqlSoupPage({
                items: [item('cached-document')],
                next_cursor: null,
              }),
              { source: 'normalized-cache-hit' }
            );
          }
          completion = mutation.execute(undefined);
          await vi.waitFor(() =>
            expect(mutation.state.context?.graphqlDeletion).toBe(deletion)
          );
          await vi.waitFor(() =>
            expect(f.ids()).toEqual(hasServerData ? [] : undefined)
          );
          expect(f.query.isLoading()).toBe(!hasServerData);

          const error = new CombinedError({
            networkError: new Error('offline'),
          });
          f.fake.executions[0].fail(error);
          expect(f.query.error()).toBe(hasServerData ? undefined : error);
          expect(f.ids()).toEqual(hasServerData ? [] : undefined);

          // Releasing the deletion makes the cached projection usable again.
          deletion.release();
          await vi.waitFor(() => expect(f.ids()).toEqual(['cached-document']));
          expect(f.query.error()).toBeUndefined();
          expect(f.query.isLoading()).toBe(false);
        } finally {
          pending.resolve();
          await completion;
          deletion.release();
          f.dispose();
        }
      }
    );

    it('keeps a partial projection usable when only some cached rows are pending deletion', async () => {
      const f = fixture([item('deleted'), item('visible')]);
      const deletion = createGraphqlSoupDeletion([
        'GraphqlSoupDocument:deleted',
      ]);
      const pending = deferred<void>();
      const mutation = queryClient.getMutationCache().build(queryClient, {
        mutationKey: GRAPHQL_SOUP_DELETE_MUTATION_KEY,
        onMutate: () => ({ graphqlDeletion: deletion }),
        mutationFn: () => pending.promise,
        onSettled: () => deletion.release(),
      });
      let completion: Promise<void> | undefined;
      try {
        await vi.waitFor(() => expect(f.ids()).toEqual(['deleted', 'visible']));
        completion = mutation.execute(undefined);
        await vi.waitFor(() => expect(f.ids()).toEqual(['visible']));
        expect(f.query.isLoading()).toBe(false);
        f.fake.executions[0].fail(
          new CombinedError({ networkError: new Error('offline') })
        );
        expect(f.query.error()).toBeUndefined();
        expect(f.ids()).toEqual(['visible']);
      } finally {
        pending.resolve();
        await completion;
        deletion.release();
        f.dispose();
      }
    });

    it('does not leak local members across folders while a new projection is pending', async () => {
      const f = fixture();
      const pending = deferred<unknown>();
      try {
        await vi.waitFor(() => expect(f.ids()).toEqual(['cached-document']));
        entityFilterMock.mockImplementation(() => pending.promise);
        f.setFolder('folder-b');
        expect(f.query.data()).toBeUndefined();
        expect(f.query.isLoading()).toBe(true);
        await vi.waitFor(() =>
          expect(entityFilterMock.mock.lastCall?.[0].filters).toMatchObject({
            documentFilter: { literal: { projectId: 'folder-b' } },
          })
        );
        f.fake.executions[0].next(
          graphqlSoupPage({ items: [item('late-folder-a')], next_cursor: null })
        );
        expect(f.query.data()).toBeUndefined();
      } finally {
        f.dispose();
        pending.resolve({ kind: 'unsupported' });
      }
    });
  });

  it('uses the channel list projection for initial pages, pagination, refresh and reconciliation', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
      cursor
        ? { continuation: { cursor } }
        : { initial: { limit: 50, sortMethod: 'UPDATED_AT' } }
    );
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockResolvedValue({
      kind: 'reconciled',
      revision: REVISION_0,
      keys: [],
      retainedKeys: [],
      optimistic: false,
    });
    readRecordsByKeysMock.mockResolvedValue({
      revision: REVISION_0,
      records: [],
    });
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true, projection: 'channel-list' })
      ),
    }));
    try {
      expect(print(fake.executions[0].document)).toContain(
        'query ChannelListSoup'
      );
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'next' }),
        {
          source: 'normalized-cache-hit',
          revision: REVISION_0,
        }
      );
      await vi.waitFor(() => expect(readRecordsByKeysMock).toHaveBeenCalled());
      const selection = readRecordsByKeysMock.mock.calls[0][1];
      expect(print(selection.document)).toContain(
        'fragment ChannelListItemFields'
      );
      expect(print(selection.document)).not.toContain(
        'channelMessageSendMessageContent'
      );
      const more = query.fetchNextPage();
      fake.executions[1].next(
        graphqlSoupPage({ items: [], next_cursor: null })
      );
      await more;
      expect(fake.executions[1].variables).toEqual({
        input: { continuation: { cursor: 'next', expand: true } },
      });
      for (const entry of getActiveGraphqlSoupRevalidations()) {
        expect(print(entry.document)).toContain('query ChannelListSoup');
      }
      const refresh = query.refresh();
      fake.executions[2].next(
        graphqlSoupPage({ items: [], next_cursor: null })
      );
      await refresh;
      for (const execution of fake.executions) {
        expect(print(execution.document)).toContain('query ChannelListSoup');
        expect(print(execution.document)).not.toContain(
          'channelMessageSendMessageContent'
        );
      }
    } finally {
      dispose();
    }
  });

  it('keeps loaded channel pages registered for retry after a transient refresh failure', async () => {
    vi.useFakeTimers();
    const visibility = vi
      .spyOn(document, 'hidden', 'get')
      .mockReturnValue(false);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
      cursor ? { continuation: { cursor } } : { initial: { limit: 50 } }
    );
    const { query, dispose } = createRoot((dispose) => {
      const query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true, projection: 'channel-list' })
      );
      registerChannelNotificationRefresh(() => ({
        client: fake.client,
        queries: query.revalidationQueries?.() ?? [],
        reader: {
          enabled: query.isEnabled(),
          fetching: query.isFetching(),
          filtered: true,
          notificationIds: [],
        },
      }));
      return { query, dispose };
    });
    const error = new CombinedError({ networkError: new Error('offline') });
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const pageData = graphqlSoupPage({ items: [], next_cursor: null });
    const refresh = vi
      .fn()
      .mockReturnValueOnce({
        toPromise: async () => {
          fake.executions[1].fail(error);
          return { error };
        },
      })
      .mockReturnValue({
        toPromise: async () => {
          fake.executions[1].next(pageData);
          return { data: pageData };
        },
      });
    fake.client.query = refresh as unknown as Client['query'];
    try {
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'next' })
      );
      const more = query.fetchNextPage();
      fake.executions[1].next(pageData);
      await more;
      const page = getActiveGraphqlSoupRevalidations().find(
        (entry) => entry.variables?.input?.continuation?.cursor === 'next'
      )!;
      expect(delegateChannelNotificationRefresh(fake.client, page)).toBe(true);
      await vi.advanceTimersByTimeAsync(100);
      expect(refresh).toHaveBeenCalledOnce();
      // The refresh still retries, but its failure does not warn over a cached page.
      expect(query.error()).toBeUndefined();
      await vi.advanceTimersByTimeAsync(1000);
      expect(refresh).toHaveBeenCalledTimes(2);
      expect(refresh).toHaveBeenLastCalledWith(page.document, page.variables, {
        requestPolicy: 'network-only',
      });
      expect(query.error()).toBeUndefined();
      query.resetToInitialPage();
      expect(delegateChannelNotificationRefresh(fake.client, page)).toBe(false);
    } finally {
      dispose();
      disposeChannelNotificationRefresh(fake.client);
      warn.mockRestore();
      visibility.mockRestore();
      vi.useRealTimers();
    }
  });

  it('registers enabled flat pages for durable replay and drops reset or unmounted pages', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
      cursor ? { continuation: { cursor } } : { initial: { limit: 50 } }
    );
    const [enabled, setEnabled] = createSignal(true);
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    const dispose = createRoot((dispose) => {
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: enabled() })
      );
      return dispose;
    });
    try {
      expect(
        getActiveGraphqlSoupRevalidations().map((query) => query.variables)
      ).toEqual([fake.executions[0].variables]);
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'next' })
      );
      const next = query.fetchNextPage();
      fake.executions[1].next(
        graphqlSoupPage({ items: [], next_cursor: null })
      );
      await next;
      expect(
        getActiveGraphqlSoupRevalidations().map((query) => query.variables)
      ).toEqual(fake.executions.map((execution) => execution.variables));
      query.resetToInitialPage();
      expect(getActiveGraphqlSoupRevalidations()).toHaveLength(1);
      setEnabled(false);
      expect(getActiveGraphqlSoupRevalidations()).toEqual([]);
    } finally {
      dispose();
    }
    expect(getActiveGraphqlSoupRevalidations()).toEqual([]);
  });

  it.each([
    { sort: 'touched_by_me', field: 'touchedAt' },
    { sort: 'notified_at', field: 'notifiedAt' },
    { sort: 'updated_at', field: 'updatedAt' },
  ] as const)(
    'preserves fetched coverage through display filtering ($sort)',
    async ({ sort, field }) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      mapSoupPageToEntityListMock.mockImplementation((page) =>
        page.items.filter((item: { id: string }) => item.id === 'visible')
      );
      const { query, dispose } = createRoot((dispose) => ({
        dispose,
        query: createGraphqlSoupAstItemsQuery(
          () => ({ params: { sort_method: sort }, body: {} }),
          () => ({ enabled: true })
        ),
      }));
      try {
        fake.executions[0].next(
          graphqlSoupPage({
            items: [
              { id: 'visible', [field]: '2026-09-10T00:00:00Z' },
              { id: 'hidden', [field]: '2026-09-08T00:00:00Z' },
            ],
            next_cursor: 'next-page',
          })
        );
        expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
          'visible',
        ]);
        expect(query.data()?.oldestFetchedTimestamp).toBe(
          Date.parse('2026-09-08T00:00:00Z')
        );

        const nextPage = query.fetchNextPage();
        await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
        fake.executions[1].next(
          graphqlSoupPage({
            items: [{ id: 'older-hidden', [field]: '2026-09-01T00:00:00Z' }],
            next_cursor: null,
          })
        );
        await nextPage;
        expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
          'visible',
        ]);
        expect(query.data()?.oldestFetchedTimestamp).toBe(
          Date.parse('2026-09-01T00:00:00Z')
        );
      } finally {
        dispose();
      }
    }
  );

  it('hides pending deletes across loaded pages and restores fresh data on failure', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({ items: [{ id: 'a' }], next_cursor: 'next' })
      );
      const next = query.fetchNextPage();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      fake.executions[1].next(
        graphqlSoupPage({
          items: [{ id: 'b' }, { id: 'keep' }],
          next_cursor: null,
        })
      );
      await next;
      let reject!: (error: Error) => void;
      const mutation = queryClient.getMutationCache().build(queryClient, {
        mutationKey: GRAPHQL_SOUP_DELETE_MUTATION_KEY,
        onMutate: () => ({
          graphqlDeletion: createGraphqlSoupDeletion([
            'GraphqlSoupDocument:a',
            'GraphqlSoupDocument:b',
          ]),
        }),
        onSettled: (_data, _error, _vars, context) =>
          context?.graphqlDeletion.release(),
        mutationFn: () =>
          new Promise<void>((_resolve, fail) => {
            reject = fail;
          }),
      });
      const failed = expect(mutation.execute(undefined)).rejects.toThrow(
        'rejected'
      );
      const ids = () => query.data()?.entities.map((entity) => entity.id);
      await vi.waitFor(() => expect(ids()).toEqual(['keep']));
      // A late query response must neither resurrect pending deletes nor be
      // overwritten by a whole-page snapshot rollback.
      fake.executions[1].next(
        graphqlSoupPage({
          items: [{ id: 'b', name: 'updated' }, { id: 'new' }],
          next_cursor: null,
        })
      );
      expect(ids()).toEqual(['new']);
      reject(new Error('rejected'));
      await failed;
      await vi.waitFor(() => expect(ids()).toEqual(['a', 'b', 'new']));
    } finally {
      dispose();
    }
  });

  it('keeps other pages when one page result omits its soup payload', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({ items: [{ id: 'a' }], next_cursor: 'next' })
      );
      const next = query.fetchNextPage();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      fake.executions[1].next(
        graphqlSoupPage({ items: [{ id: 'b' }], next_cursor: 'more' })
      );
      await next;
      const ids = () => query.data()?.entities.map((entity) => entity.id);
      expect(ids()).toEqual(['a', 'b']);

      fake.executions[0].next({ user: { id: 'viewer' } });
      expect(query.error()).toBeUndefined();
      expect(ids()).toEqual(['b']);
      expect(query.hasNextPage()).toBe(true);

      fake.executions[1].next({ user: { id: 'viewer' } });
      expect(query.error()).toBeUndefined();
      expect(ids()).toEqual([]);
      expect(query.hasNextPage()).toBe(false);

      fake.executions[0].next(
        graphqlSoupPage({ items: [{ id: 'a' }], next_cursor: 'next' })
      );
      fake.executions[1].next(
        graphqlSoupPage({ items: [{ id: 'b' }], next_cursor: 'more' })
      );
      expect(query.error()).toBeUndefined();
      expect(ids()).toEqual(['a', 'b']);
      expect(query.hasNextPage()).toBe(true);
    } finally {
      dispose();
    }
  });

  it('retains the page projection when only query activity changes', () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const [enabled, setEnabled] = createSignal(true);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: enabled() })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({ items: [{ id: 'retained' }], next_cursor: null })
      );
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(1);
      const entities = query.data()?.entities;

      setEnabled(false);
      expect(query.isEnabled()).toBe(false);
      setEnabled(true);
      expect(query.isEnabled()).toBe(true);
      query.resetToInitialPage();

      expect(query.data()?.entities).toBe(entities);
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(1);
      expect(mapSoupPageToEntityListMock).toHaveBeenCalledTimes(1);
    } finally {
      dispose();
    }
  });

  it('keeps raw wire payloads outside deep store reconciliation', () => {
    mapSoupPageToEntityListMock.mockImplementation((page) =>
      page.items.map((item: { id: string }) => ({ id: item.id }))
    );
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    const metadata = { content: { message: 'large immutable payload' } };
    const descriptors = vi.spyOn(Object, 'getOwnPropertyDescriptors');
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ id: 'document', metadata }],
          next_cursor: null,
        })
      );

      expect(query.data()?.entities[0]?.id).toBe('document');
      expect(descriptors).not.toHaveBeenCalledWith(metadata);
      expect(descriptors).not.toHaveBeenCalledWith(metadata.content);
    } finally {
      descriptors.mockRestore();
      dispose();
    }
  });

  it('updates mapped entities reactively without mutating raw wire records', () => {
    mapSoupPageToEntityListMock.mockImplementation((page) =>
      page.items.map((item: object) => ({ ...item }))
    );
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const names: Array<string | undefined> = [];
    const { query, dispose } = createRoot((dispose) => {
      const query = createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'updated_at' }, body: {} }),
        () => ({ enabled: true })
      );
      createComputed(() => names.push(query.data()?.entities[0]?.name));
      return { query, dispose };
    });
    try {
      const firstPage = graphqlSoupPage({
        items: [{ id: 'document', name: 'before' }],
        next_cursor: null,
      });
      fake.executions[0].next(firstPage);
      const previousEntity = query.data()?.entities[0];
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ id: 'document', name: 'after' }],
          next_cursor: null,
        })
      );

      expect(query.data()?.entities[0]?.name).toBe('after');
      expect(names).toContain('before');
      expect(names.at(-1)).toBe('after');
      expect(query.data()?.entities[0]).toBe(previousEntity);
      expect(firstPage.user.soup.items[0]).toMatchObject({ name: 'before' });
      expect(fake.executions).toHaveLength(1);
    } finally {
      dispose();
    }
  });

  it('reprojects retained pages when projection inputs change', () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    const [sort, setSort] = createSignal<'notified_at' | 'updated_at'>(
      'updated_at'
    );
    const [showForeign, setShowForeign] = createSignal(false);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: sort() }, body: {} }),
        () => ({ enabled: true, showSupportedForeignEntities: showForeign() })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ id: 'retained', notifiedAt: '2025-01-01T00:00:00Z' }],
          next_cursor: null,
        })
      );
      expect(query.data()?.oldestFetchedTimestamp).toBe(
        Date.parse('2026-01-01T00:00:00Z')
      );
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(1);

      setSort('notified_at');
      expect(query.data()?.oldestFetchedTimestamp).toBe(
        Date.parse('2025-01-01T00:00:00Z')
      );
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(2);

      setShowForeign(true);
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(3);
      expect(mapSoupPageToEntityListMock).toHaveBeenLastCalledWith(
        expect.anything(),
        expect.objectContaining({ showSupportedForeignEntities: true })
      );
    } finally {
      dispose();
    }
  });

  it.each([
    ['invalid', undefined],
    [undefined, Date.parse('2026-09-08T00:00:00Z')],
  ])(
    'preserves timestamp coverage with a %s timestamp',
    (notifiedAt, expected) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      createRoot((dispose) => {
        const query = createGraphqlSoupAstItemsQuery(
          () => ({ params: { sort_method: 'notified_at' }, body: {} }),
          () => ({ enabled: true })
        );
        fake.executions[0].next(
          graphqlSoupPage({
            items: [
              { id: 'known', notifiedAt: '2026-09-08T00:00:00Z' },
              { id: 'unknown', notifiedAt },
            ],
            next_cursor: 'next-page',
          })
        );
        expect(query.data()?.oldestFetchedTimestamp).toBe(expected);
        dispose();
      });
    }
  );

  it('retains fetched coverage when display filtering hides every row', () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    mapSoupPageToEntityListMock.mockReturnValue([]);
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'notified_at' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ id: 'hidden', notifiedAt: '2026-09-08T00:00:00Z' }],
          next_cursor: 'next-page',
        })
      );
      expect(query.data()?.entities).toEqual([]);
      expect(query.data()?.oldestFetchedTimestamp).toBe(
        Date.parse('2026-09-08T00:00:00Z')
      );
      expect(query.hasNextPage()).toBe(true);
    } finally {
      dispose();
    }
  });

  it('keeps fetched timestamp coverage separate from older local cache candidates', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockResolvedValue({
      kind: 'reconciled',
      revision: REVISION_0,
      keys: ['GraphqlSoupDocument:cached'],
      retainedKeys: [],
      optimistic: false,
    });
    readRecordsByKeysMock.mockResolvedValue({
      revision: REVISION_0,
      records: [
        {
          recordKey: 'GraphqlSoupDocument:cached',
          record: {
            __typename: 'GraphqlSoupDocument',
            id: 'cached',
            type: 'document',
            name: 'Cached',
            touchedAt: '2025-01-01T00:00:00Z',
          },
        },
      ],
    });
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: { sort_method: 'touched_by_me' }, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      await vi.waitFor(() =>
        expect(query.data()?.entities[0]?.id).toBe('cached')
      );
      expect(query.data()?.oldestFetchedTimestamp).toBeUndefined();
      fake.executions[0].next(
        graphqlSoupPage({
          items: [
            {
              id: 'fetched',
              type: 'document',
              name: 'Fetched',
              touchedAt: '2026-09-08T00:00:00Z',
            },
          ],
          next_cursor: 'next-page',
        }),
        { source: 'normalized-cache-hit', revision: REVISION_0 }
      );
      await vi.waitFor(() => {
        expect(
          query.data()?.entities.some((entity) => entity.id === 'cached')
        ).toBe(true);
        expect(query.data()?.oldestFetchedTimestamp).toBe(
          Date.parse('2026-09-08T00:00:00Z')
        );
      });
    } finally {
      dispose();
    }
  });

  it('accepts a coherent Mail page at a newer revision without repeating the filter scan', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      // Background hydration can advance the engine without a foreground push.
      currentRevision: vi
        .fn()
        .mockResolvedValueOnce(REVISION_0)
        .mockResolvedValue(REVISION_2),
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    makeGraphqlSoupInputMock.mockReturnValue({
      initial: { emailView: 'ALL', sortMethod: 'UPDATED_AT', limit: 20 },
    });
    entityFilterMock.mockResolvedValue({
      kind: 'mail-page',
      retainedKeys: [],
      revision: REVISION_2,
      keys: [],
      sortTimestamps: [],
      nextCursor: null,
      optimistic: false,
    });
    readRecordsByKeysMock.mockResolvedValue({
      revision: REVISION_2,
      records: [],
    });
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    try {
      await vi.waitFor(() => expect(query.data()?.cachedMail).toBe(true));
      expect(entityFilterMock).toHaveBeenCalledTimes(1);
      expect(readRecordsByKeysMock).toHaveBeenCalledTimes(1);
    } finally {
      dispose();
    }
  });

  it('keeps a newer non-Mail reconciliation authoritative after reconnect', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_1;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockImplementation(async () => ({
      kind: 'reconciled',
      revision,
      keys: ['GraphqlSoupDocument:item-0'],
      retainedKeys: [],
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: [
        {
          recordKey: 'GraphqlSoupDocument:item-0',
          record: {
            id: 'item-0',
            type: 'document',
            name: 'Hydrated local item',
          },
        },
      ],
    }));
    const { query, dispose } = createRoot((dispose) => ({
      dispose,
      query: createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true })
      ),
    }));
    const names = () => query.data()?.entities.map((item) => item.name);
    const page = (name: string) =>
      graphqlSoupPage({
        items: [{ id: 'item-0', type: 'document', name }],
        next_cursor: null,
      });
    try {
      fake.executions[0].next(page('Old network item'), {
        source: 'live-network',
        revision: REVISION_1,
      });
      await vi.waitFor(() => expect(names()).toEqual(['Old network item']));

      // Hydration advances storage without notifying foreground readers.
      revision = REVISION_2;
      online.mockReturnValue(false);
      window.dispatchEvent(new Event('offline'));
      await vi.waitFor(() => expect(names()).toEqual(['Hydrated local item']));
      expect(entityFilterMock.mock.calls.at(-1)?.[0]).toHaveProperty(
        'baseline'
      );
      expect(entityFilterMock.mock.calls.at(-1)?.[0]).not.toHaveProperty(
        'mail'
      );

      online.mockReturnValue(true);
      window.dispatchEvent(new Event('online'));
      // Neither the synchronous publication nor a completed follow-up may
      // restore revision 1 merely because connectivity returned.
      expect(names()).toEqual(['Hydrated local item']);
      await vi.waitFor(() => expect(names()).toEqual(['Hydrated local item']));
      expect(fake.executions).toHaveLength(1);

      // A genuinely newer network snapshot must still take authority.
      revision = '3';
      fake.executions[0].next(page('Fresh network item'), {
        source: 'live-network',
        revision,
      });
      await vi.waitFor(() => expect(names()).toEqual(['Fresh network item']));
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it('paginates never-visited Mail filters offline without a server cursor or stale preview timestamps', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(false);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    const keys = [
      'GraphqlSoupEmailThread:one',
      'GraphqlSoupEmailThread:two',
      'GraphqlSoupEmailThread:three',
    ];
    const ts = '2025-01-01T00:00:00.000001Z';
    entityFilterMock.mockImplementation(async (args) => {
      const index = args.filters.emailFilter ? 2 : args.mail.cursor ? 1 : 0;
      return {
        kind: 'mail-page',
        retainedKeys: [],
        revision: REVISION_0,
        keys: [keys[index]],
        sortTimestamps: [ts],
        nextCursor: index === 0 ? 'local-next' : null,
        optimistic: false,
      };
    });
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, requested) => ({
        revision: REVISION_0,
        records: requested.map((key: string) => ({
          recordKey: key,
          record: {
            __typename: 'GraphqlSoupEmailThread',
            id: key.split(':')[1],
            name: key,
            mailAllPreview: {
              id: `${key}-preview`,
              subject: key,
              snippet: 'canonical',
              isDraft: false,
              senderEmail: null,
              senderName: null,
              senderPhotoUrl: null,
            },
            mailDraftPreview: null,
            mailSentPreview: null,
          },
        })),
      })
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    let change!: () => void;
    createRoot((d) => {
      dispose = d;
      const [input, setInput] = createSignal({
        initial: {
          emailView: 'ALL',
          sortMethod: 'UPDATED_AT',
          limit: 1,
          filters: {},
        },
      });
      change = () =>
        setInput({
          initial: {
            emailView: 'INBOX',
            sortMethod: 'UPDATED_AT',
            limit: 1,
            filters: { emailFilter: { tree: { literal: { read: true } } } },
          },
        });
      makeGraphqlSoupInputMock.mockImplementation(() => input());
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    try {
      await vi.waitFor(() => expect(query.data()?.entities).toHaveLength(1));
      expect(query.data()?.cachedMail).toBe(true);
      expect(query.isLoading()).toBe(false);
      expect(query.hasNextPage()).toBe(true);
      await query.fetchNextPage();
      expect(entityFilterMock.mock.calls.at(-1)?.[0].mail).toEqual({
        view: 'ALL',
        cursor: 'local-next',
      });
      expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
        'one',
        'two',
      ]);
      expect(query.hasNextPage()).toBe(false);
      expect(fake.executions).toHaveLength(1);
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'server-cursor' }),
        { source: 'normalized-cache-hit', revision: REVISION_0 }
      );
      expect(query.data()?.entities).toHaveLength(2);
      change();
      await vi.waitFor(() =>
        expect(query.data()?.entities[0]?.id).toBe('three')
      );
      expect(query.data()?.entities).toHaveLength(1);
      expect(entityFilterMock.mock.calls.at(-1)?.[0].mail).toEqual({
        view: 'INBOX',
      });
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it('keeps the server page fetched behind a local Mail list out of its loading and error state', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    entityFilterMock.mockImplementation(async (args) => ({
      kind: 'mail-page',
      retainedKeys: [],
      revision: REVISION_0,
      keys: [`GraphqlSoupEmailThread:${args.mail.cursor ? 'two' : 'one'}`],
      sortTimestamps: ['2025-01-01T00:00:00.000001Z'],
      nextCursor: args.mail.cursor ? null : 'local-next',
      // Only the first page shows a pending write.
      optimistic: !args.mail.cursor,
    }));
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, requested) => ({
        revision: REVISION_0,
        records: requested.map((key: string) => ({
          recordKey: key,
          record: {
            __typename: 'GraphqlSoupEmailThread',
            id: key.split(':')[1],
            name: key,
            mailAllPreview: {
              id: `${key}-preview`,
              subject: key,
              snippet: 'canonical',
              isDraft: false,
              senderEmail: null,
              senderName: null,
              senderPhotoUrl: null,
            },
            mailDraftPreview: null,
            mailSentPreview: null,
          },
        })),
      })
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((d) => {
      dispose = d;
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: { emailView: 'ALL', sortMethod: 'UPDATED_AT', limit: 1 },
      });
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    try {
      await vi.waitFor(() => expect(query.data()?.cachedMail).toBe(true));
      fake.executions[0].next(
        graphqlSoupPage({ items: [], next_cursor: 'server-cursor' }),
        { source: 'normalized-cache-hit', revision: REVISION_0 }
      );
      await query.fetchNextPage();
      expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
        'one',
        'two',
      ]);
      // The server page behind the list is requested but not waited on.
      expect(fake.executions).toHaveLength(2);
      expect(query.isFetchingNextPage()).toBe(false);
      fake.executions[1].fail(
        new CombinedError({ networkError: new Error('offline') })
      );
      expect(query.error()).toBeUndefined();
      expect(query.data()?.entities).toHaveLength(2);
      // The write still pending on the first page keeps the local list up.
      expect(query.data()?.cachedMail).toBe(true);
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it('keeps fetching server pages behind a local Mail list until they are as deep', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    const all = ['one', 'two', 'three', 'four'].map(
      (id) => `GraphqlSoupEmailThread:${id}`
    );
    entityFilterMock.mockImplementation(
      async (args: {
        limit: number;
        mail: { cursor?: string; through?: string };
      }) => {
        const start = args.mail.cursor ? all.indexOf(args.mail.cursor) + 1 : 0;
        const end = args.mail.through
          ? Math.max(all.indexOf(args.mail.through) + 1, args.limit)
          : start + args.limit;
        const keys = all.slice(start, end);
        return {
          kind: 'mail-page',
          retainedKeys: [],
          revision: REVISION_0,
          keys,
          sortTimestamps: keys.map(() => '2025-01-01T00:00:00.000001Z'),
          nextCursor: start + keys.length < all.length ? keys.at(-1) : null,
          endCursor: keys.at(-1) ?? null,
          optimistic: false,
        };
      }
    );
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, requested: string[]) => ({
        revision: REVISION_0,
        records: mailThreadRecords(requested),
      })
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((d) => {
      dispose = d;
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: { emailView: 'ALL', sortMethod: 'UPDATED_AT', limit: 1 },
      });
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    const serverPage = (id: string, next: string | null) =>
      graphqlSoupPage({
        items: [{ __typename: 'GraphqlSoupEmailThread', id }],
        next_cursor: next,
      });
    const ids = () => query.data()?.entities.map((entity) => entity.id);
    const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
    try {
      await vi.waitFor(() => expect(query.data()?.cachedMail).toBe(true));
      fake.executions[0].next(serverPage('one', 's1'), {
        source: 'normalized-cache-hit',
        revision: REVISION_0,
      });
      // Two local pages while the first server page behind them is in flight.
      await query.fetchNextPage();
      await query.fetchNextPage();
      expect(ids()).toEqual(['one', 'two', 'three']);
      expect(fake.executions).toHaveLength(2);
      fake.executions[1].next(serverPage('two', 's2'), {
        source: 'normalized-cache-hit',
        revision: REVISION_0,
      });
      // The server pages catch up with the third local row, then stop.
      await vi.waitFor(() => expect(fake.executions).toHaveLength(3));
      expect(fake.executions[2].variables).toMatchObject({
        input: { continuation: { cursor: 's2' } },
      });
      fake.executions[2].next(serverPage('three', 's3'), {
        source: 'normalized-cache-hit',
        revision: REVISION_0,
      });
      await tick();
      expect(fake.executions).toHaveLength(3);

      // A reset while a server page is in flight ends the catch-up: nothing
      // fetches the pages it dropped again.
      await query.fetchNextPage();
      expect(fake.executions).toHaveLength(4);
      query.resetToInitialPage();
      await vi.waitFor(() => expect(ids()).toEqual(['one']));
      fake.executions[3].next(serverPage('four', null), {
        source: 'normalized-cache-hit',
        revision: REVISION_0,
      });
      await tick();
      expect(fake.executions).toHaveLength(4);
      expect(ids()).toEqual(['one']);
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it('stays cache-maintained across a stale retry and stops on an engine handoff', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(false);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_0;
    let notifyGeneration: () => void = () => undefined;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => undefined,
      onCacheGenerationChanged: (callback: () => void) => {
        notifyGeneration = callback;
        return () => undefined;
      },
    });
    entityFilterMock.mockImplementation(async () => ({
      kind: 'mail-page',
      retainedKeys: [],
      revision,
      keys: ['GraphqlSoupEmailThread:a'],
      sortTimestamps: ['2025-01-01T00:00:00.000001Z'],
      nextCursor: null,
      optimistic: false,
    }));
    // The first read races a write: its records come from a newer revision.
    let reads = 0;
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, requested: string[]) => {
        reads += 1;
        if (reads === 1) revision = REVISION_1;
        return {
          revision,
          records: requested.map((key) => ({
            recordKey: key,
            record: {
              __typename: 'GraphqlSoupEmailThread',
              id: key.split(':')[1],
              name: key,
              mailAllPreview: {
                id: `${key}-preview`,
                subject: key,
                snippet: 'canonical',
                isDraft: false,
                senderEmail: null,
                senderName: null,
                senderPhotoUrl: null,
              },
              mailDraftPreview: null,
              mailSentPreview: null,
            },
          })),
        };
      }
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((d) => {
      dispose = d;
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: { emailView: 'INBOX', sortMethod: 'UPDATED_AT', limit: 2 },
      });
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    try {
      await vi.waitFor(() =>
        expect(query.data()?.entities.map(({ id }) => id)).toEqual(['a'])
      );
      expect(reads).toBeGreaterThan(1);
      // The retry succeeded, so cache writes keep this page current.
      expect(query.cacheMaintained?.()).toBe(true);

      // A new engine generation has not evaluated the page yet.
      entityFilterMock.mockImplementation(() => new Promise(() => {}));
      notifyGeneration();
      expect(query.cacheMaintained?.()).toBe(false);
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it('keeps a paged Mail list ending at the same row when mail arrives above it', async () => {
    const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(false);
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_0;
    let notifyCacheChanged: (revision: string) => void = () => undefined;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: (revision: string) => void) => {
        notifyCacheChanged = callback;
        return () => undefined;
      },
      onCacheGenerationChanged: () => () => {},
    });
    const key = (id: string) => `GraphqlSoupEmailThread:${id}`;
    let all = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'].map(key);
    let generation = 'first';
    // Like the engine's, a position names a row of one engine generation and
    // outlives writes.
    const row = (position: string) => {
      const [positionGeneration, rowKey] = position.split('|');
      return positionGeneration === generation ? rowKey : undefined;
    };
    entityFilterMock.mockImplementation(
      async (args: {
        limit: number;
        mail: { cursor?: string; through?: string };
      }) => {
        const position = args.mail.cursor ?? args.mail.through;
        const rowKey = position === undefined ? undefined : row(position);
        if (position !== undefined && rowKey === undefined)
          return { kind: 'stale-cursor', revision };
        const index = rowKey === undefined ? -1 : all.indexOf(rowKey);
        const start = args.mail.cursor ? index + 1 : 0;
        const end = args.mail.through
          ? Math.max(index + 1, args.limit)
          : start + args.limit;
        const keys = all.slice(start, end);
        const last = keys.length ? `${generation}|${keys.at(-1)}` : null;
        return {
          kind: 'mail-page',
          retainedKeys: [],
          revision,
          keys,
          sortTimestamps: keys.map(() => '2025-01-01T00:00:00.000001Z'),
          nextCursor: start + keys.length < all.length ? last : null,
          endCursor: last,
          optimistic: false,
        };
      }
    );
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, requested: string[]) => ({
        revision,
        records: mailThreadRecords(requested),
      })
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((d) => {
      dispose = d;
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: {
          emailView: 'INBOX',
          sortMethod: 'UPDATED_AT',
          limit: 2,
          filters: {},
        },
      });
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    const ids = () => query.data()?.entities.map((entity) => entity.id);
    try {
      await vi.waitFor(() => expect(ids()).toEqual(['a', 'b']));
      // The first evaluation's edge does not keep it from counting as current.
      expect(query.cacheMaintained?.()).toBe(true);
      await query.fetchNextPage();
      expect(ids()).toEqual(['a', 'b', 'c', 'd']);

      // New mail lands above the list: it re-reads through its last row,
      // which a row count would have pushed off the bottom.
      all = [key('z'), ...all];
      revision = REVISION_1;
      notifyCacheChanged(REVISION_1);
      await vi.waitFor(() => expect(ids()).toEqual(['z', 'a', 'b', 'c', 'd']));
      expect(entityFilterMock.mock.calls.at(-1)?.[0]).toMatchObject({
        limit: 2,
        mail: { view: 'INBOX', through: `first|${key('d')}` },
      });

      // The next page continues after the same row, with no re-read.
      const requestsBeforePage = entityFilterMock.mock.calls.length;
      await query.fetchNextPage();
      expect(ids()).toEqual(['z', 'a', 'b', 'c', 'd', 'e', 'f']);
      expect(entityFilterMock.mock.calls.length - requestsBeforePage).toBe(1);

      // A write racing the next page: the list is read again through the
      // page's last row at the new revision.
      revision = REVISION_2;
      await query.fetchNextPage();
      await vi.waitFor(() =>
        expect(ids()).toEqual(['z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'])
      );
      expect(entityFilterMock.mock.calls.at(-1)?.[0]).toMatchObject({
        mail: { through: `first|${key('h')}` },
      });

      // Resetting to the first page forgets the edge.
      query.resetToInitialPage();
      await vi.waitFor(() => expect(ids()).toEqual(['z', 'a']));
      expect(entityFilterMock.mock.calls.at(-1)?.[0].mail).toEqual({
        view: 'INBOX',
      });

      // A Load More still reading its records when the list resets does not
      // bring the old depth back.
      const pageRecords = deferred<{
        revision: string;
        records: ReturnType<typeof mailThreadRecords>;
      }>();
      let pageKeys: string[] = [];
      readRecordsByKeysMock.mockImplementationOnce(
        (_host, _selection, requested: string[]) => {
          pageKeys = requested;
          return pageRecords.promise;
        }
      );
      const loading = query.fetchNextPage();
      await vi.waitFor(() => expect(pageKeys).not.toHaveLength(0));
      query.resetToInitialPage();
      await vi.waitFor(() => expect(ids()).toEqual(['z', 'a']));
      pageRecords.resolve({ revision, records: mailThreadRecords(pageKeys) });
      await loading;
      await new Promise((resolve) => setTimeout(resolve, 0));
      expect(ids()).toEqual(['z', 'a']);
      expect(entityFilterMock.mock.calls.at(-1)?.[0].mail).toEqual({
        view: 'INBOX',
      });

      // A replaced engine no longer knows the position: read from the top.
      generation = 'second';
      revision = '3';
      const requestsBeforeReplacement = entityFilterMock.mock.calls.length;
      notifyCacheChanged('3');
      await vi.waitFor(() =>
        expect(
          entityFilterMock.mock.calls
            .slice(requestsBeforeReplacement)
            .map(([args]) => [args.limit, args.mail])
        ).toEqual([
          [2, { view: 'INBOX', through: `first|${key('a')}` }],
          [2, { view: 'INBOX' }],
        ])
      );
      await vi.waitFor(() => expect(query.localRevision?.()).toBe('3'));
      expect(ids()).toEqual(['z', 'a']);

      // Load More from a replaced engine restarts at the first page.
      generation = 'third';
      const requestsBeforeRestart = entityFilterMock.mock.calls.length;
      await query.fetchNextPage();
      await vi.waitFor(() => expect(ids()).toEqual(['z', 'a']));
      expect(
        entityFilterMock.mock.calls
          .slice(requestsBeforeRestart)
          .map(([args]) => args.mail)
      ).toEqual([
        { view: 'INBOX', cursor: `second|${key('a')}` },
        { view: 'INBOX', through: `second|${key('a')}` },
        { view: 'INBOX' },
      ]);
    } finally {
      dispose();
      online.mockRestore();
    }
  });

  it.each([
    { mail: true, kind: 'mail-page' },
    { mail: true, kind: 'incomplete' },
    { mail: true, kind: 'unsupported' },
    { mail: false, kind: 'reconciled' },
    { mail: false, kind: 'incomplete' },
    { mail: false, kind: 'unsupported' },
  ] as const)(
    'handles a failed network refresh with $kind local proof (mail=$mail)',
    async ({ mail, kind }) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => REVISION_0,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: () => () => {},
      });
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: {
          ...(mail ? { emailView: 'ALL' } : {}),
          sortMethod: 'UPDATED_AT',
          limit: 10,
        },
      });
      entityFilterMock.mockResolvedValue({
        kind,
        retainedKeys: [],
        revision: REVISION_0,
        keys: [],
        sortTimestamps: [],
        nextCursor: null,
        optimistic: false,
      });
      readRecordsByKeysMock.mockResolvedValue({
        revision: REVISION_0,
        records: [],
      });
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
      });
      try {
        await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalled());
        const offlineError = new CombinedError({
          networkError: new Error('API disconnected'),
        });
        fake.executions[0].fail(offlineError);
        if (kind === 'mail-page' || kind === 'reconciled') {
          await vi.waitFor(() => expect(query.data()?.entities).toEqual([]));
          expect(query.data()?.cachedMail).toBe(mail);
          // A local Mail page that evaluates keeps itself current: writes
          // that update the cache need not read it again.
          if (mail) expect(query.cacheMaintained?.()).toBe(true);
          if (!mail)
            expect(entityFilterMock.mock.calls.at(-1)?.[0].baseline).toEqual(
              []
            );
          expect(query.error()).toBeUndefined();
          // Server-reported errors are not hidden just because local data exists.
          const serverError = new CombinedError({
            graphQLErrors: ['Forbidden'],
          });
          fake.executions[0].fail(serverError);
          expect(query.error()).toBe(serverError);
          const unauthorized = new CombinedError({
            networkError: new Error('HTTP 403'),
            response: { status: 403 },
          });
          fake.executions[0].fail(unauthorized);
          expect(query.error()).toBe(unauthorized);
          const unavailable = new CombinedError({
            networkError: new Error('HTTP 503'),
            response: { status: 503 },
          });
          fake.executions[0].fail(unavailable);
          expect(query.error()).toBe(unavailable);
        } else {
          expect(query.data()?.cachedMail).not.toBe(true);
          expect(query.error()).toBe(offlineError);
          // An incomplete or unsupported page still needs the server.
          if (mail) expect(query.cacheMaintained?.()).toBe(false);
        }
      } finally {
        dispose();
      }
    }
  );

  it.each([
    { localNext: null, networkNext: 'server-next' },
    { localNext: 'local-next', networkNext: null },
  ])(
    'uses network pagination after reconnect ($localNext / $networkNext)',
    async ({ localNext, networkNext }) => {
      const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => REVISION_0,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: () => () => {},
      });
      makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
        cursor
          ? { continuation: { cursor } }
          : {
              initial: { emailView: 'ALL', sortMethod: 'UPDATED_AT', limit: 1 },
            }
      );
      entityFilterMock.mockResolvedValue({
        kind: 'mail-page',
        retainedKeys: [],
        revision: REVISION_0,
        keys: [],
        sortTimestamps: [],
        nextCursor: localNext,
        optimistic: false,
      });
      readRecordsByKeysMock.mockResolvedValue({
        revision: REVISION_0,
        records: [],
      });
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
      });
      try {
        fake.executions[0].next(
          graphqlSoupPage({ items: [], next_cursor: networkNext }),
          { source: 'live-network', revision: REVISION_0 }
        );
        await vi.waitFor(() => expect(query.data()).toBeDefined());
        expect(query.data()?.cachedMail).not.toBe(true);
        online.mockReturnValue(false);
        window.dispatchEvent(new Event('offline'));
        await vi.waitFor(() => expect(query.data()?.cachedMail).toBe(true));
        expect(query.hasNextPage()).toBe(localNext !== null);
        // Reconnect at the same revision without a fresh network response. The
        // existing server baseline becomes authoritative again.
        online.mockReturnValue(true);
        window.dispatchEvent(new Event('online'));
        await vi.waitFor(() => expect(query.data()?.cachedMail).not.toBe(true));
        expect(query.hasNextPage()).toBe(networkNext !== null);
        if (networkNext) {
          const pending = query.fetchNextPage();
          await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
          expect(fake.executions[1].variables).toEqual({
            input: {
              continuation: {
                cursor: networkNext,
                emailView: 'ALL',
                expand: true,
              },
            },
          });
          fake.executions[1].next(
            graphqlSoupPage({ items: [], next_cursor: null }),
            { source: 'live-network', revision: REVISION_0 }
          );
          await pending;
          expect(query.hasNextPage()).toBe(false);
        }
      } finally {
        dispose();
        online.mockRestore();
      }
    }
  );

  it.each([
    { emailView: 'INBOX', networkFirst: false, delayed: true },
    { emailView: 'DRAFTS', networkFirst: false, delayed: true },
    { emailView: 'INBOX', networkFirst: false },
    { emailView: 'DRAFTS', networkFirst: false },
    { emailView: 'INBOX', networkFirst: true },
    { emailView: 'DRAFTS', networkFirst: true },
  ])(
    'keeps a restored queued draft visible in $emailView (network first: $networkFirst, delayed: $delayed)',
    async ({ emailView, networkFirst, delayed }) => {
      vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_0;
      let changed: (revision: string) => void = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof changed) => {
          changed = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      makeGraphqlSoupInputMock.mockReturnValue({
        initial: { emailView, sortMethod: 'UPDATED_AT', limit: 20 },
      });
      const preview = {
        id: 'draft-message',
        subject: 'Offline draft',
        snippet: 'Keep me',
        isDraft: true,
        senderEmail: null,
        senderName: null,
        senderPhotoUrl: null,
      };
      entityFilterMock.mockImplementation(async () => ({
        kind: 'mail-page',
        retainedKeys: [],
        revision,
        keys: ['GraphqlSoupEmailThread:local-draft'],
        sortTimestamps: ['2026-09-28T12:00:00Z'],
        nextCursor: null,
        optimistic: revision !== REVISION_2,
      }));
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: [
          {
            recordKey: 'GraphqlSoupEmailThread:local-draft',
            record: {
              __typename: 'GraphqlSoupEmailThread',
              id: 'local-draft',
              mailAllPreview: preview,
              mailDraftPreview: preview,
              mailSentPreview: null,
            },
          },
        ],
      }));
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
      });
      try {
        if (networkFirst) {
          fake.executions[0].next(
            graphqlSoupPage({ items: [], next_cursor: null }),
            { source: 'live-network', revision }
          );
        }
        await vi.waitFor(() =>
          expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
            'local-draft',
          ])
        );
        const write = deferred<string | undefined>();
        revision = REVISION_1;
        fake.executions[0].next(
          graphqlSoupPage({ items: [], next_cursor: null }),
          delayed
            ? { source: 'live-network', persistence: write.promise }
            : { source: 'live-network', revision }
        );
        // Keep the pending draft even before evaluation of the new revision.
        expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
          'local-draft',
        ]);
        write.resolve(revision);
        await vi.waitFor(() => expect(query.localRevision?.()).toBe(revision));
        await vi.waitFor(() =>
          expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
            'local-draft',
          ])
        );
        expect(query.data()?.cachedMail).toBe(true);

        entityFilterMock.mockRejectedValueOnce(
          new Error('temporary cache read failure')
        );
        revision = REVISION_2;
        changed(revision);
        await vi.waitFor(() => expect(query.cacheMaintained?.()).toBe(false));
        expect(query.data()?.entities.map((row) => row.id)).toEqual([
          'local-draft',
        ]);

        // Once the write settles, the fresh server page takes over even if
        // an old local row remains. Pending preservation must not retain ghosts.
        revision = REVISION_2;
        fake.executions[0].next(
          graphqlSoupPage({
            items: [{ id: 'server-draft' }],
            next_cursor: null,
          }),
          { source: 'live-network', revision }
        );
        await vi.waitFor(() =>
          expect(query.data()?.entities.map((entity) => entity.id)).toEqual([
            'server-draft',
          ])
        );
        expect(query.data()?.cachedMail).not.toBe(true);
      } finally {
        dispose();
      }
    }
  );

  it('does not run the local filter for the implicit VIEWED_AT sort', () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => undefined,
      onCacheGenerationChanged: () => () => undefined,
    });
    makeGraphqlSoupInputMock.mockReturnValue({ initial: { limit: 50 } });

    createRoot((dispose) => {
      createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );

      expect(fake.executions).toHaveLength(1);
      expect(entityFilterMock).not.toHaveBeenCalled();
      dispose();
    });
  });

  it.each([
    { result: 'emails', optimistic: false },
    { result: 'empty', optimistic: false },
    { result: 'network error', optimistic: false },
    { result: 'emails', optimistic: true },
  ] as const)(
    'keeps a cold empty Mail result loading until $result (optimistic: $optimistic)',
    async ({ result, optimistic }) => {
      const online = vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(true);
      const fake = makeFakeClient();
      let revision = REVISION_0;
      let keys: string[] = [];
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: () => () => {},
      });
      entityFilterMock.mockImplementation(async () => ({
        kind: 'mail-page',
        revision,
        keys,
        retainedKeys: [],
        sortTimestamps: keys.map(() => '2026-01-01T00:00:00Z'),
        nextCursor: null,
        endCursor: null,
        optimistic,
      }));
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: mailThreadRecords(keys),
      }));
      const { source, dispose } = createRoot((dispose) => ({
        dispose,
        source: createSoupLiveQuery(() => ({
          emailView: 'INBOX',
          sortMethod: 'UPDATED_AT',
          filters: {
            emailFilter: { tree: { literal: { importance: false } } },
          },
          limit: 20,
        })),
      }));
      try {
        await vi.waitFor(() => expect(source.cachedMail()).toBe(true));
        expect(source.data()).toEqual([]);
        expect(source.isFetching()).toBe(true);
        expect(source.isLoading()).toBe(true);
        if (result === 'network error') {
          fake.executions[0].fail(
            new CombinedError({ networkError: new Error('API disconnected') })
          );
          expect(source.isLoading()).toBe(false);
          expect(source.data()).toEqual([]);
          expect(source.error()).toBeUndefined();
          return;
        }
        revision = REVISION_1;
        keys = result === 'emails' ? ['GraphqlSoupEmailThread:noise'] : [];
        fake.executions[0].next(
          graphqlSoupPage({
            items:
              result === 'emails'
                ? [{ __typename: 'GraphqlSoupEmailThread', id: 'noise' }]
                : [],
            next_cursor: null,
          })
        );
        expect(source.isLoading()).toBe(false);
        await vi.waitFor(() =>
          expect(source.data()?.map((record) => record.id)).toEqual(
            result === 'emails' ? ['noise'] : []
          )
        );
        if (result === 'empty') {
          const refresh = source.refresh();
          expect(source.isFetching()).toBe(true);
          expect(source.isLoading()).toBe(false);
          fake.executions
            .at(-1)!
            .next(graphqlSoupPage({ items: [], next_cursor: null }));
          await refresh;
          expect(source.isLoading()).toBe(false);
        }
      } finally {
        dispose();
        online.mockRestore();
      }
    }
  );

  it.each(['offline', 'cache-only', 'local-only'] as const)(
    'does not wait for HTTP when an empty Mail result is %s',
    async (mode) => {
      const online = vi
        .spyOn(navigator, 'onLine', 'get')
        .mockReturnValue(mode !== 'offline');
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => REVISION_0,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: () => () => {},
      });
      entityFilterMock.mockResolvedValue({
        kind: 'mail-page',
        revision: REVISION_0,
        keys: [],
        retainedKeys: [],
        sortTimestamps: [],
        nextCursor: null,
        endCursor: null,
        optimistic: false,
      });
      readRecordsByKeysMock.mockResolvedValue({
        revision: REVISION_0,
        records: [],
      });
      const { source, dispose } = createRoot((dispose) => ({
        dispose,
        source: createSoupLiveQuery(
          () => ({ emailView: 'INBOX', sortMethod: 'UPDATED_AT', limit: 20 }),
          () => ({
            networkPaused: mode === 'cache-only',
            localOnly: mode === 'local-only',
          })
        ),
      }));
      try {
        await vi.waitFor(() => expect(source.cachedMail()).toBe(true));
        expect(source.data()).toEqual([]);
        expect(source.isLoading()).toBe(false);
        if (mode === 'local-only') expect(fake.executions).toHaveLength(0);
      } finally {
        dispose();
        online.mockRestore();
      }
    }
  );

  it('shows current-query local data without a tab placeholder while the network continues', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_0,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => undefined,
      onCacheGenerationChanged: () => () => undefined,
    });
    entityFilterMock.mockResolvedValue({
      kind: 'reconciled',
      retainedKeys: [],
      revision: REVISION_0,
      keys: ['GraphqlSoupDocument:task-1'],
      optimistic: false,
    });
    readRecordsByKeysMock.mockResolvedValue({
      revision: REVISION_0,
      records: [
        {
          recordKey: 'GraphqlSoupDocument:task-1',
          record: { id: 'task-1', type: 'document', name: 'Local task' },
        },
      ],
    });

    await new Promise<void>((resolve, reject) => {
      createRoot((dispose) => {
        const query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }) as never,
          () => ({ enabled: true })
        );

        expect(fake.executions).toHaveLength(1);
        vi.waitFor(() => {
          expect(query.isPlaceholderData()).toBe(false);
          expect(query.isLoading()).toBe(false);
          expect(query.data()?.entities[0]?.name).toBe('Local task');
        })
          .then(() => {
            fake.executions[0]?.next(
              graphqlSoupPage({
                items: [
                  { id: 'task-1', type: 'document', name: 'Network task' },
                ],
                next_cursor: null,
              })
            );
            expect(query.isPlaceholderData()).toBe(false);
            expect(query.data()?.entities[0]?.name).toBe('Network task');
            dispose();
            resolve();
          })
          .catch(reject);
      });
    });
    expect(entityFilterMock).toHaveBeenCalled();
  });

  it('reevaluates exact local membership after optimistic settlement', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let currentRevision = REVISION_0;
    let notifyCacheChanged: (revision: string) => void = () => undefined;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => currentRevision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: (revision: string) => void) => {
        notifyCacheChanged = callback;
        return () => undefined;
      },
      onCacheGenerationChanged: () => () => undefined,
    });
    entityFilterMock
      .mockResolvedValueOnce({
        kind: 'reconciled',
        retainedKeys: [],
        revision: REVISION_0,
        keys: ['GraphqlSoupDocument:task-1'],
        optimistic: true,
      })
      .mockResolvedValueOnce({
        kind: 'reconciled',
        retainedKeys: [],
        revision: REVISION_2,
        keys: ['GraphqlSoupDocument:task-1'],
        optimistic: false,
      });
    readRecordsByKeysMock
      .mockResolvedValueOnce({
        revision: REVISION_0,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:task-1',
            record: { id: 'task-1', type: 'document', name: 'Optimistic task' },
          },
        ],
      })
      .mockResolvedValueOnce({
        revision: REVISION_2,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:task-1',
            record: { id: 'task-1', type: 'document', name: 'Network task' },
          },
        ],
      });

    await new Promise<void>((resolve, reject) => {
      createRoot((dispose) => {
        const query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }) as never,
          () => ({ enabled: true })
        );

        vi.waitFor(() => {
          expect(query.data()?.entities[0]?.name).toBe('Optimistic task');
          expect(query.isPlaceholderData()).toBe(false);
        })
          .then(async () => {
            fake.executions[0]?.next(
              graphqlSoupPage({
                items: [
                  { id: 'task-1', type: 'document', name: 'Network task' },
                ],
                next_cursor: null,
              })
            );
            expect(query.data()?.entities[0]?.name).toBe('Network task');

            currentRevision = REVISION_2;
            notifyCacheChanged(REVISION_2);
            await vi.waitFor(() => {
              expect(entityFilterMock).toHaveBeenCalledTimes(2);
              expect(query.data()?.entities[0]?.name).toBe('Network task');
              expect(query.isPlaceholderData()).toBe(false);
            });
            dispose();
            resolve();
          })
          .catch(reject);
      });
    });
  });

  describe('network publication before persistence', () => {
    function fixture() {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_0;
      let notify: (revision: string) => void = () => {};
      let notifyGeneration: () => void = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof notify) => {
          notify = callback;
          return () => {};
        },
        onCacheGenerationChanged: (callback: typeof notifyGeneration) => {
          notifyGeneration = callback;
          return () => {};
        },
      });
      entityFilterMock.mockImplementation(async () => ({
        kind: 'reconciled',
        revision,
        keys: ['GraphqlSoupDocument:item-0'],
        retainedKeys: [],
        optimistic: true,
      }));
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:item-0',
            record: {
              id: 'item-0',
              type: 'document',
              name: `Local ${revision}`,
            },
          },
        ],
      }));
      makeGraphqlSoupInputMock.mockImplementation(({ params, cursor }) =>
        cursor
          ? { continuation: { cursor } }
          : {
              initial: {
                limit: 50,
                sortMethod: 'UPDATED_AT',
                sortDirection: params.sort_direction === 'asc' ? 'ASC' : 'DESC',
              },
            }
      );
      const root = createRoot((dispose) => {
        const [sort, setSort] = createSignal<'asc' | 'desc'>('desc');
        const query = createGraphqlSoupAstItemsQuery(
          () => ({ params: { sort_direction: sort() }, body: {} }),
          () => ({ enabled: true })
        );
        return { dispose, query, setSort };
      });
      return {
        ...root,
        fake,
        names: () => root.query.data()?.entities.map((entity) => entity.name),
        push: (next: string) => {
          revision = next;
          notify(next);
        },
        replace: () => {
          revision = REVISION_0;
          notifyGeneration();
        },
        page: (
          name: string,
          next_cursor: string | null = null,
          id = 'item-0'
        ) =>
          graphqlSoupPage({
            items: [{ id, type: 'document', name }],
            next_cursor,
          }),
      };
    }

    it('shows network rows immediately and resumes local reconciliation after acknowledgement', async () => {
      const f = fixture();
      const write = deferred<string | undefined>();
      try {
        f.fake.executions[0].next(f.page('Network'), {
          source: 'live-network',
          persistence: write.promise,
        });
        expect(f.names()).toEqual(['Network']);
        expect(f.query.isLoading()).toBe(false);
        await Promise.resolve();
        expect(entityFilterMock).not.toHaveBeenCalled();
        write.resolve(REVISION_1);
        await Promise.resolve();
        expect(f.names()).toEqual(['Network']);
        expect(entityFilterMock).not.toHaveBeenCalled();
        f.push(REVISION_2);
        await vi.waitFor(() => expect(f.names()).toEqual(['Local 2']));
      } finally {
        f.dispose();
      }
    });

    it('does not rewind an optimistic revision that arrives before acknowledgement', async () => {
      const f = fixture();
      const write = deferred<string | undefined>();
      try {
        f.fake.executions[0].next(f.page('Network'), {
          source: 'live-network',
          persistence: write.promise,
        });
        f.push(REVISION_2);
        expect(f.names()).toEqual(['Network']);
        write.resolve(REVISION_1);
        await vi.waitFor(() => expect(f.names()).toEqual(['Local 2']));
      } finally {
        f.dispose();
      }
    });

    it('does not reassert network authority over a newer affected cache result', async () => {
      const f = fixture();
      const write = deferred<string | undefined>();
      try {
        f.fake.executions[0].next(f.page('Network'), {
          source: 'live-network',
          persistence: write.promise,
        });
        f.push(REVISION_2);
        f.fake.executions[0].next(f.page('Optimistic'), {
          source: 'affected-cache-reread',
        });
        await vi.waitFor(() => expect(f.names()).toEqual(['Local 2']));
        write.resolve(REVISION_1);
        await Promise.resolve();
        expect(f.names()).toEqual(['Local 2']);
        f.push('3');
        await vi.waitFor(() => expect(f.names()).toEqual(['Local 3']));
      } finally {
        f.dispose();
      }
    });

    it.each(['failed', 'rejected'] as const)(
      'keeps successful network rows when persistence is %s',
      async (outcome) => {
        const f = fixture();
        const write = deferred<string | undefined>();
        try {
          f.fake.executions[0].next(f.page('Network'), {
            source: 'live-network',
            persistence: write.promise,
          });
          if (outcome === 'failed') write.resolve(undefined);
          else write.reject(new Error('cache unavailable'));
          await Promise.resolve();
          f.push(REVISION_1);
          await Promise.resolve();
          expect(f.names()).toEqual(['Network']);
          expect(f.query.isLoading()).toBe(false);
          expect(entityFilterMock).not.toHaveBeenCalled();
          f.fake.executions[0].next(f.page('Recovered cache'), {
            source: 'normalized-cache-hit',
          });
          await vi.waitFor(() => expect(f.names()).toEqual(['Local 1']));
        } finally {
          f.dispose();
        }
      }
    );

    it('ignores an older acknowledgement while a newer network page is pending', async () => {
      const f = fixture();
      const first = deferred<string | undefined>();
      const second = deferred<string | undefined>();
      try {
        f.fake.executions[0].next(f.page('First'), {
          source: 'live-network',
          persistence: first.promise,
        });
        f.fake.executions[0].next(f.page('Second'), {
          source: 'live-network',
          persistence: second.promise,
        });
        first.resolve(REVISION_1);
        f.push(REVISION_1);
        await Promise.resolve();
        expect(f.names()).toEqual(['Second']);
        expect(entityFilterMock).not.toHaveBeenCalled();
        second.resolve(REVISION_2);
        f.push(REVISION_2);
        await Promise.resolve();
        expect(f.names()).toEqual(['Second']);
      } finally {
        f.dispose();
      }
    });

    it('tracks continuation-page persistence independently of the first page', async () => {
      const f = fixture();
      const first = deferred<string | undefined>();
      const second = deferred<string | undefined>();
      try {
        f.fake.executions[0].next(f.page('First', 'next'), {
          source: 'live-network',
          persistence: first.promise,
        });
        const next = f.query.fetchNextPage();
        await vi.waitFor(() => expect(f.fake.executions).toHaveLength(2));
        f.fake.executions[1].next(f.page('Second', null, 'item-1'), {
          source: 'live-network',
          persistence: second.promise,
        });
        await next;
        expect(f.names()).toEqual(['First', 'Second']);
        first.resolve(REVISION_1);
        f.push(REVISION_1);
        await Promise.resolve();
        expect(entityFilterMock).not.toHaveBeenCalled();
        expect(f.names()).toEqual(['First', 'Second']);
        second.resolve(REVISION_2);
        f.push(REVISION_2);
        await Promise.resolve();
        expect(f.names()).toEqual(['First', 'Second']);
        expect(entityFilterMock).not.toHaveBeenCalled();
      } finally {
        f.dispose();
      }
    });

    it.each(['input', 'generation', 'dispose'] as const)(
      'fences acknowledgements after a change of %s',
      async (change) => {
        const f = fixture();
        const write = deferred<string | undefined>();
        try {
          f.fake.executions[0].next(f.page('Old input'), {
            source: 'live-network',
            persistence: write.promise,
          });
          if (change === 'dispose') f.dispose();
          else {
            if (change === 'input') f.setSort('asc');
            else f.replace();
            f.fake.executions.at(-1)!.next(f.page('Current cache'), {
              source: 'normalized-cache-hit',
            });
            await vi.waitFor(() => expect(f.names()).toEqual(['Local 0']));
          }
          const calls = entityFilterMock.mock.calls.length;
          write.resolve(REVISION_1);
          await Promise.resolve();
          await Promise.resolve();
          expect(entityFilterMock).toHaveBeenCalledTimes(calls);
          if (change !== 'dispose') expect(f.names()).toEqual(['Local 0']);
        } finally {
          f.dispose();
        }
      }
    );
  });

  it('promotes realtime local revisions without a network rerun and fences stale generations', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let currentRevision = REVISION_1;
    let notifyCacheChanged: (revision: string) => void = () => undefined;
    let notifyGenerationChanged: () => void = () => undefined;
    let resolveRevision4!: (value: unknown) => void;
    let revision4Started = false;
    const revision4Filter = new Promise((resolve) => {
      resolveRevision4 = resolve;
    });
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => currentRevision,
      onCacheChanged: (callback: (revision: string) => void) => {
        notifyCacheChanged = callback;
        return () => undefined;
      },
      onCacheGenerationChanged: (callback: () => void) => {
        notifyGenerationChanged = callback;
        return () => undefined;
      },
      entityFilter: entityFilterMock,
    });
    entityFilterMock.mockImplementation(async () => {
      if (currentRevision === '4') {
        revision4Started = true;
        return await revision4Filter;
      }
      const names =
        currentRevision === REVISION_2
          ? ['Network item', 'Realtime item']
          : currentRevision === '6'
            ? ['Latest local item']
            : ['Replacement durable item'];
      return {
        kind: 'reconciled',
        retainedKeys: [],
        revision: currentRevision,
        keys: names.map((_, index) => `GraphqlSoupDocument:item-${index}`),
        optimistic: false,
      };
    });
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, keys: string[]) => {
        const names =
          currentRevision === REVISION_2
            ? ['Network item', 'Realtime item']
            : currentRevision === '6'
              ? ['Latest local item']
              : ['Replacement durable item'];
        return {
          revision: currentRevision,
          records: keys.map((recordKey, index) => ({
            recordKey,
            record: {
              id: `item-${index}`,
              type: 'document',
              name: names[index],
            },
          })),
        };
      }
    );

    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((rootDispose) => {
      dispose = rootDispose;
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });

    fake.executions[0]?.next(
      graphqlSoupPage({
        items: [{ id: 'item-0', type: 'document', name: 'Network item' }],
        next_cursor: null,
      }),
      { source: 'live-network', revision: REVISION_1 }
    );
    expect(query.data()?.entities.map((item) => item.name)).toEqual([
      'Network item',
    ]);

    currentRevision = REVISION_2;
    notifyCacheChanged(REVISION_2);
    await vi.waitFor(() => {
      expect(query.data()?.entities.map((item) => item.name)).toEqual([
        'Network item',
        'Realtime item',
      ]);
    });
    expect(fake.executions).toHaveLength(1);

    fake.executions[0]?.next(
      graphqlSoupPage({
        items: [{ id: 'item-0', type: 'document', name: 'New network item' }],
        next_cursor: null,
      }),
      { source: 'live-network', revision: '3' }
    );
    expect(query.data()?.entities.map((item) => item.name)).toEqual([
      'New network item',
    ]);

    currentRevision = '4';
    notifyCacheChanged('4');
    await vi.waitFor(() => expect(revision4Started).toBe(true));
    const callsBeforePendingChanges = entityFilterMock.mock.calls.length;
    currentRevision = '5';
    notifyCacheChanged('5');
    currentRevision = '6';
    notifyCacheChanged('6');
    await Promise.resolve();
    expect(entityFilterMock).toHaveBeenCalledTimes(callsBeforePendingChanges);
    expect(query.data()?.entities.map((item) => item.name)).toEqual([
      'New network item',
    ]);
    resolveRevision4({
      kind: 'reconciled',
      retainedKeys: [],
      revision: '4',
      keys: ['GraphqlSoupDocument:stale'],
      optimistic: false,
    });
    await vi.waitFor(() => {
      expect(entityFilterMock).toHaveBeenCalledTimes(
        callsBeforePendingChanges + 1
      );
      expect(query.data()?.entities.map((item) => item.name)).toEqual([
        'Latest local item',
      ]);
    });

    currentRevision = REVISION_0;
    notifyGenerationChanged();
    await vi.waitFor(() => {
      expect(query.data()?.entities.map((item) => item.name)).toEqual([
        'Replacement durable item',
      ]);
    });
    expect(fake.executions).toHaveLength(1);
    dispose();
  });

  it('skips local evaluation on cache changes while hidden and catches up once', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let currentRevision = REVISION_1;
    let notifyCacheChanged!: (revision: string) => void;
    let notifyGenerationChanged!: () => void;
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => currentRevision,
      onCacheChanged: (callback: (revision: string) => void) => {
        notifyCacheChanged = callback;
        return () => undefined;
      },
      onCacheGenerationChanged: (callback: () => void) => {
        notifyGenerationChanged = callback;
        return () => undefined;
      },
      entityFilter: entityFilterMock,
    });
    entityFilterMock.mockImplementation(async () => ({
      kind: 'reconciled',
      retainedKeys: [],
      revision: currentRevision,
      keys: [],
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision: currentRevision,
      records: [],
    }));
    const visibility = vi.spyOn(document, 'visibilityState', 'get');
    let dispose!: () => void;
    createRoot((rootDispose) => {
      dispose = rootDispose;
      createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );
    });
    try {
      fake.executions[0]?.next(
        graphqlSoupPage({
          items: [{ id: 'item-0', type: 'document', name: 'Network item' }],
          next_cursor: null,
        }),
        { source: 'live-network', revision: REVISION_1 }
      );
      await Promise.resolve();
      entityFilterMock.mockClear();

      visibility.mockReturnValue('hidden');
      currentRevision = REVISION_2;
      notifyCacheChanged(REVISION_2);
      currentRevision = '3';
      notifyCacheChanged('3');
      notifyGenerationChanged();
      currentRevision = '4';
      notifyCacheChanged('4');
      await Promise.resolve();
      await Promise.resolve();
      expect(entityFilterMock).not.toHaveBeenCalled();

      visibility.mockReturnValue('visible');
      document.dispatchEvent(new Event('visibilitychange'));
      await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalledTimes(1));
    } finally {
      dispose();
      visibility.mockRestore();
    }
  });

  it('merges baseline survivors with candidates without resetting server pagination', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_1;
    let notify: (revision: string) => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: (callback: typeof notify) => {
        notify = callback;
        return () => {};
      },
      onCacheGenerationChanged: () => () => {},
    });
    makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
      cursor
        ? { continuation: { cursor } }
        : { initial: { sortMethod: 'UPDATED_AT', limit: 2 } }
    );
    entityFilterMock.mockImplementation(async ({ baseline }) => ({
      kind: 'reconciled',
      revision,
      optimistic: false,
      // 'removed' is a confirmed non-match, 'kept' is unknown. The latter
      // need not materialize from current normalized storage to survive.
      keys: [
        'GraphqlSoupDocument:new',
        ...baseline
          .filter((entry: { key: string }) => !entry.key.endsWith(':removed'))
          .map((entry: { key: string }) => entry.key),
      ],
      retainedKeys: ['GraphqlSoupDocument:kept'],
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: [
        {
          recordKey: 'GraphqlSoupDocument:new',
          record: { id: 'new', name: 'New candidate' },
        },
      ],
    }));
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((stop) => {
      dispose = stop;
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true })
      );
    });
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [
            { id: 'kept', name: 'Baseline survivor' },
            { id: 'removed', name: 'No longer matches' },
          ],
          next_cursor: 'server-cursor-2',
        })
      );
      revision = REVISION_2;
      notify(revision);
      await vi.waitFor(() =>
        expect(query.data()?.entities.map((item) => item.name)).toEqual([
          'New candidate',
          'Baseline survivor',
        ])
      );
      expect(fake.executions).toHaveLength(1);
      expect(query.hasNextPage()).toBe(true);
      const nextPage = query.fetchNextPage();
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      expect(fake.executions[1].variables).toEqual({
        input: { continuation: { cursor: 'server-cursor-2', expand: true } },
      });
      revision = '3';
      notify(revision);
      fake.executions[1].next(
        graphqlSoupPage({
          items: [{ id: 'page-2', name: 'Second page' }],
          next_cursor: null,
        }),
        { source: 'live-network', revision }
      );
      await nextPage;
      await vi.waitFor(() =>
        expect(query.data()?.entities.map((item) => item.name)).toEqual([
          'New candidate',
          'Baseline survivor',
          'Second page',
        ])
      );
      expect(query.hasNextPage()).toBe(false);
      expect(fake.executions).toHaveLength(2);
      // Once a projection covers page two, resetting the chain must not keep
      // those unloaded rows alive through that projection if reevaluation fails.
      entityFilterMock.mockRejectedValue(new Error('reconciliation failed'));
      const callsBeforeReset = entityFilterMock.mock.calls.length;
      query.resetToInitialPage();
      expect(
        query.data()?.entities.some((item) => item.name === 'Second page')
      ).toBe(false);
      await vi.waitFor(() =>
        expect(entityFilterMock.mock.calls.length).toBeGreaterThan(
          callsBeforeReset
        )
      );
      expect(
        query.data()?.entities.some((item) => item.name === 'Second page')
      ).toBe(false);
      expect(query.hasNextPage()).toBe(true);
    } finally {
      dispose();
    }
  });

  it.each(['error', 'unsupported', 'incomplete'] as const)(
    'shows later server pages while reconciliation is pending and after %s',
    async (outcome) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_1;
      let notify: (revision: string) => void = () => {};
      let release!: () => void;
      const pending = new Promise<void>((resolve) => {
        release = resolve;
      });
      let retries = 0;
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof notify) => {
          notify = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
        cursor
          ? { continuation: { cursor } }
          : { initial: { sortMethod: 'UPDATED_AT', limit: 2 } }
      );
      entityFilterMock.mockImplementation(async () => {
        if (revision !== REVISION_2) {
          retries += 1;
          await pending;
          if (outcome === 'error') throw new Error('reconciliation failed');
          return { kind: outcome, revision };
        }
        return {
          kind: 'reconciled',
          revision,
          keys: ['GraphqlSoupDocument:new', 'GraphqlSoupDocument:kept'],
          retainedKeys: [],
          optimistic: false,
        };
      });
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:new',
            record: {
              __typename: 'GraphqlSoupDocument',
              id: 'new',
              name: 'New candidate',
            },
          },
        ],
      }));
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
      });
      const names = () => query.data()?.entities.map((item) => item.name);
      try {
        fake.executions[0].next(
          graphqlSoupPage({
            items: [
              { id: 'kept', name: 'Baseline survivor' },
              { id: 'removed', name: 'Confirmed non-match' },
            ],
            next_cursor: 'server-cursor-2',
          })
        );
        revision = REVISION_2;
        notify(revision);
        await vi.waitFor(() =>
          expect(names()).toEqual(['New candidate', 'Baseline survivor'])
        );
        const secondPage = query.fetchNextPage();
        await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
        revision = '3';
        notify(revision);
        fake.executions[1].next(
          graphqlSoupPage({
            // The candidate is also returned by pagination: render it only once.
            items: [
              { id: 'new', name: 'New candidate' },
              { id: 'second', name: 'Second page' },
            ],
            next_cursor: 'server-cursor-3',
          }),
          { source: 'live-network', revision }
        );
        await secondPage;
        await vi.waitFor(() => expect(retries).toBeGreaterThan(0));
        expect(names()).toEqual([
          'New candidate',
          'Baseline survivor',
          'Second page',
        ]);
        expect(query.isLoading()).toBe(false);
        expect(query.isPlaceholderData()).toBe(false);
        release();
        await vi.waitFor(() =>
          expect(entityFilterMock).toHaveBeenLastCalledWith(
            expect.objectContaining({
              baseline: expect.arrayContaining([
                expect.objectContaining({ key: 'GraphqlSoupDocument:second' }),
              ]),
            })
          )
        );
        expect(names()).toEqual([
          'New candidate',
          'Baseline survivor',
          'Second page',
        ]);
        // A second load-more must not rely on local evaluation recovering.
        const thirdPage = query.fetchNextPage();
        await vi.waitFor(() => expect(fake.executions).toHaveLength(3));
        expect(fake.executions[2].variables).toEqual({
          input: { continuation: { cursor: 'server-cursor-3', expand: true } },
        });
        revision = '4';
        notify(revision);
        fake.executions[2].next(
          graphqlSoupPage({
            items: [{ id: 'third', name: 'Third page' }],
            next_cursor: null,
          }),
          { source: 'live-network', revision }
        );
        await thirdPage;
        expect(names()).toEqual([
          'New candidate',
          'Baseline survivor',
          'Second page',
          'Third page',
        ]);
        expect(query.hasNextPage()).toBe(false);
      } finally {
        release();
        dispose();
      }
    }
  );

  it('never supplies another filter or cache generation as baseline evidence', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    let revision = REVISION_1;
    let notifyGeneration: () => void = () => {};
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => revision,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: (callback: () => void) => {
        notifyGeneration = callback;
        return () => {};
      },
    });
    const [scope, setScope] = createSignal('one');
    makeGraphqlSoupInputMock.mockImplementation(({ body }) => ({
      initial: { sortMethod: 'UPDATED_AT', filters: body, limit: 100 },
    }));
    entityFilterMock.mockImplementation(async () => ({
      kind: 'reconciled',
      revision,
      keys: [],
      retainedKeys: [],
      optimistic: false,
    }));
    readRecordsByKeysMock.mockImplementation(async () => ({
      revision,
      records: [],
    }));
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((stop) => {
      dispose = stop;
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: { scope: scope() } }) as never,
        () => ({ enabled: true })
      );
    });
    try {
      fake.executions[0].next(
        graphqlSoupPage({
          items: [{ id: 'old', name: 'Old filter' }],
          next_cursor: null,
        })
      );
      setScope('two');
      await vi.waitFor(() => expect(fake.executions).toHaveLength(2));
      await vi.waitFor(() =>
        expect(entityFilterMock).toHaveBeenCalledWith(
          expect.objectContaining({ filters: { scope: 'two' }, baseline: [] })
        )
      );
      expect(query.data()?.entities.some((item) => item.id === 'old')).not.toBe(
        true
      );
      fake.executions[1].next(
        graphqlSoupPage({
          items: [{ id: 'new', name: 'New filter' }],
          next_cursor: null,
        })
      );
      revision = REVISION_0;
      notifyGeneration();
      await vi.waitFor(() =>
        expect(entityFilterMock).toHaveBeenLastCalledWith(
          expect.objectContaining({ baseline: [] })
        )
      );
      await vi.waitFor(() => expect(query.data()?.entities).toEqual([]));
    } finally {
      dispose();
    }
  });

  it.each(['unsupported', 'incomplete'])(
    'retains the network baseline when reconciliation is %s',
    async (kind) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_1;
      let notify: (revision: string) => void = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof notify) => {
          notify = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      entityFilterMock.mockImplementation(async () => ({ kind, revision }));
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
      });
      try {
        fake.executions[0].next(
          graphqlSoupPage({
            items: [{ id: 'server', name: 'Server row' }],
            next_cursor: null,
          })
        );
        revision = REVISION_2;
        notify(revision);
        await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalled());
        expect(query.data()?.entities.map((item) => item.name)).toEqual([
          'Server row',
        ]);
      } finally {
        dispose();
      }
    }
  );

  it('batches large overlays and rejects mixed-revision materialization', async () => {
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);
    getGraphqlSoupCacheHostMock.mockReturnValue({
      currentRevision: async () => REVISION_2,
      entityFilter: entityFilterMock,
      onCacheChanged: () => () => {},
      onCacheGenerationChanged: () => () => {},
    });
    const keys = Array.from(
      { length: 501 },
      (_, i) => `GraphqlSoupDocument:${i}`
    );
    entityFilterMock.mockResolvedValue({
      kind: 'reconciled',
      revision: REVISION_2,
      keys,
      retainedKeys: [],
      optimistic: false,
    });
    let reads = 0;
    readRecordsByKeysMock.mockImplementation(
      async (_host, _selection, chunk: string[]) => ({
        revision: reads++ === 0 ? REVISION_1 : REVISION_2,
        records: chunk.map((recordKey) => ({
          recordKey,
          record: { id: recordKey, name: recordKey },
        })),
      })
    );
    let dispose!: () => void;
    let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
    createRoot((stop) => {
      dispose = stop;
      query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }),
        () => ({ enabled: true })
      );
    });
    try {
      await vi.waitFor(() => expect(query.data()?.entities).toHaveLength(501));
      expect(entityFilterMock).toHaveBeenCalledTimes(2);
      expect(
        readRecordsByKeysMock.mock.calls.map((call) => call[2].length)
      ).toEqual([500, 1, 500, 1]);
    } finally {
      dispose();
    }
  });

  it.each(['pending', 'empty', 'older rows'] as const)(
    'keeps the last local display while recomputing against a %s server page',
    async (serverPage) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_1;
      let notify: (revision: string) => void = () => {};
      let release!: (result: unknown) => void;
      const pending = new Promise((resolve) => {
        release = resolve;
      });
      let recomputing = false;
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: (callback: typeof notify) => {
          notify = callback;
          return () => {};
        },
        onCacheGenerationChanged: () => () => {},
      });
      const result = () => ({
        kind: 'reconciled',
        revision,
        keys: ['GraphqlSoupDocument:local'],
        retainedKeys: [],
        optimistic: false,
      });
      entityFilterMock.mockImplementation(async () => {
        if (revision === '3') {
          recomputing = true;
          return pending;
        }
        return result();
      });
      readRecordsByKeysMock.mockImplementation(async () => ({
        revision,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:local',
            record: {
              id: 'local',
              name: revision === '3' ? 'Updated local row' : 'Local row',
            },
          },
        ],
      }));
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      const displays: Array<{
        names: string[] | undefined;
        loading: boolean;
        placeholder: boolean;
      }> = [];
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: {} }),
          () => ({ enabled: true })
        );
        createComputed(() =>
          displays.push({
            names: query.data()?.entities.map((item) => item.name),
            loading: query.isLoading(),
            placeholder: query.isPlaceholderData(),
          })
        );
      });
      try {
        if (serverPage !== 'pending') {
          fake.executions[0].next(
            graphqlSoupPage({
              items:
                serverPage === 'empty'
                  ? []
                  : [{ id: 'server', name: 'Old server row' }],
              next_cursor: null,
            })
          );
        }
        revision = REVISION_2;
        notify(revision);
        await vi.waitFor(() =>
          expect(query.data()?.entities[0]?.name).toBe('Local row')
        );
        const previousDisplay = query.data();
        displays.length = 0;
        revision = '3';
        notify(revision);
        await vi.waitFor(() => expect(recomputing).toBe(true));
        expect(query.data()).toBe(previousDisplay);
        expect(query.isLoading()).toBe(false);
        expect(query.isPlaceholderData()).toBe(false);
        // The outstanding initial network request still has normal fetching
        // semantics; recomputation does not turn retained rows into loading.
        expect(query.isFetching()).toBe(serverPage === 'pending');
        release(result());
        await vi.waitFor(() =>
          expect(query.data()?.entities[0]?.name).toBe('Updated local row')
        );
        expect(
          displays.every(
            (display) =>
              !display.loading &&
              !display.placeholder &&
              (display.names?.[0] === 'Local row' ||
                display.names?.[0] === 'Updated local row')
          )
        ).toBe(true);
        // A failed local retry also keeps the display, not an older baseline.
        entityFilterMock.mockRejectedValue(
          new Error('temporary cache failure')
        );
        const calls = entityFilterMock.mock.calls.length;
        revision = '4';
        notify(revision);
        await vi.waitFor(() =>
          expect(entityFilterMock.mock.calls.length).toBeGreaterThan(calls)
        );
        expect(query.data()?.entities[0]?.name).toBe('Updated local row');
        expect(query.isLoading()).toBe(false);
        fake.executions[0].next(
          graphqlSoupPage({
            items: [{ id: 'fresh', name: 'Fresh server row' }],
            next_cursor: null,
          }),
          { source: 'live-network', revision: '4' }
        );
        expect(query.data()?.entities[0]?.name).toBe('Fresh server row');
      } finally {
        dispose();
      }
    }
  );

  it.each(['query', 'generation'] as const)(
    'never retains the local display across a %s change',
    async (change) => {
      const fake = makeFakeClient();
      getGraphqlSoupClientMock.mockReturnValue(fake.client);
      let revision = REVISION_1;
      let notifyGeneration: () => void = () => {};
      getGraphqlSoupCacheHostMock.mockReturnValue({
        currentRevision: async () => revision,
        entityFilter: entityFilterMock,
        onCacheChanged: () => () => {},
        onCacheGenerationChanged: (callback: () => void) => {
          notifyGeneration = callback;
          return () => {};
        },
      });
      const [scope, setScope] = createSignal('one');
      makeGraphqlSoupInputMock.mockImplementation(({ body }) => ({
        initial: { sortMethod: 'UPDATED_AT', filters: body, limit: 100 },
      }));
      entityFilterMock.mockResolvedValue({
        kind: 'reconciled',
        revision,
        keys: ['GraphqlSoupDocument:old'],
        retainedKeys: [],
        optimistic: false,
      });
      readRecordsByKeysMock.mockResolvedValue({
        revision,
        records: [
          {
            recordKey: 'GraphqlSoupDocument:old',
            record: { id: 'old', name: 'Previous local result' },
          },
        ],
      });
      let dispose!: () => void;
      let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
      createRoot((stop) => {
        dispose = stop;
        query = createGraphqlSoupAstItemsQuery(
          () => ({ params: {}, body: { scope: scope() } }) as never,
          () => ({ enabled: true })
        );
      });
      try {
        await vi.waitFor(() =>
          expect(query.data()?.entities[0]?.name).toBe('Previous local result')
        );
        entityFilterMock.mockImplementation(() => new Promise(() => {}));
        if (change === 'query') setScope('two');
        else {
          revision = REVISION_0;
          notifyGeneration();
        }
        expect(
          query.data()?.entities.some((item) => item.id === 'old')
        ).not.toBe(true);
        expect(query.isLoading()).toBe(true);
        expect(query.isPlaceholderData()).toBe(false);
      } finally {
        dispose();
      }
    }
  );

  it('retains identical page projections across cache re-executions', () => {
    const firstPage = {
      items: [{ id: 'task-1', type: 'document', name: 'Task' }],
      next_cursor: null,
    };
    const fake = makeFakeClient();
    getGraphqlSoupClientMock.mockReturnValue(fake.client);

    createRoot((dispose) => {
      const query = createGraphqlSoupAstItemsQuery(
        () => ({ params: {}, body: {} }) as never,
        () => ({ enabled: true })
      );

      expect(fake.executions).toHaveLength(1);
      fake.executions[0]?.next(graphqlSoupPage(firstPage));
      expect(mapGraphqlSoupItemMock).toHaveBeenCalledTimes(1);

      const initial = query.data();
      const initialEntity = initial?.entities[0];
      expect(initialEntity).toMatchObject(firstPage.items[0]);

      fake.executions[0]?.next(graphqlSoupPage(structuredClone(firstPage)));
      expect(query.data()).toBe(initial);
      expect(query.data()?.entities[0]).toBe(initialEntity);

      fake.executions[0]?.next(
        graphqlSoupPage({
          ...firstPage,
          items: [{ ...firstPage.items[0], name: 'Updated task' }],
        })
      );
      expect(query.data()?.entities[0]).toBe(initialEntity);
      expect(query.data()?.entities[0]?.name).toBe('Updated task');

      dispose();
    });
  });
});