Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
Seanaye/perf/improve engine handoff (#6833)
Sean Ayef9fdd83a38a7
diff --git a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.tsindex 8f4c4b601d..cd60535421 100644--- a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts+++ b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.test.ts@@ -7,9 +7,23 @@ import type {} from '@graphql-cache/index';import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';import type { HistoryItem } from '@queries/history/types';-import { createRoot, createSignal } from 'solid-js';+import { render } from '@solidjs/testing-library';+import {+ QueryClient,+ QueryClientProvider,+ type UseQueryResult,+ useQuery,+} from '@tanstack/solid-query';+import {+ createComponent,+ createRenderEffect,+ createRoot,+ createSignal,+} from 'solid-js';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { useQuickAccess } from './context';import { MAX_BROWSE_PAGES_PER_LOAD } from './projected-list';+import { QuickAccessProvider } from './QuickAccessProvider';import { createQuickAccessValue } from './QuickAccessSource';import {BUCKET_COMBINATIONS,@@ -28,6 +42,12 @@ const mocks = vi.hoisted(() => ({companies: [] as CrmCompanyEntity[],crmEnabled: (): boolean => true,cacheEnabled: true,+ queries: {} as Partial<+ Record<+ 'history' | 'channels' | 'recently-viewed',+ () => UseQueryResult<unknown[]>+ >+ >,}));vi.mock('@core/constant/featureFlags', () => ({enableCrm: {},@@ -48,22 +68,25 @@ vi.mock('@core/user', () => ({useIsConnectedSecondaryInbox: () => () => false,}));vi.mock('@queries/channel/channels', () => ({- useCachedGraphqlChannelsQuery: () => ({- data: [],- isLoading: false,- refetch: mocks.channelRefetch,- }),+ useCachedGraphqlChannelsQuery: () =>+ mocks.queries.channels?.() ?? {+ data: [],+ isSuccess: true,+ isLoading: false,+ refetch: mocks.channelRefetch,+ },}));vi.mock('@queries/channel/graphql', () => ({materializeCachedGraphqlChannels: async () => [],}));-vi.mock('@queries/gate', () => ({ queryReadyGate: () => true }));vi.mock('@queries/history/history', () => ({- useHistoryQuery: () => ({- data: mocks.history,- isLoading: false,- refetch: vi.fn(),- }),+ useHistoryQuery: () =>+ mocks.queries.history?.() ?? {+ data: mocks.history,+ isSuccess: true,+ isLoading: false,+ refetch: vi.fn(),+ },}));vi.mock('@queries/history/graphql', () => ({materializeCachedGraphqlHistoryItems: async (@@ -96,7 +119,8 @@ vi.mock('@queries/soup/quick-access-snippets', () => ({useQuickAccessSnippetsQuery: () => ({ query: {}, snippets: () => [] }),}));vi.mock('@queries/soup/recently-viewed', () => ({- useRecentlyViewedSoupQuery: () => ({ data: [] }),+ useRecentlyViewedSoupQuery: () =>+ mocks.queries['recently-viewed']?.() ?? { data: [], isSuccess: true },}));vi.mock('@queries/storage/instructions-md', () => ({useInstructionsMdIdQuery: () => ({ data: undefined }),@@ -148,6 +172,7 @@ beforeEach(() => {mocks.companies = [];mocks.crmEnabled = () => true;mocks.cacheEnabled = true;+ mocks.queries = {};mocks.readRecordsByKeys.mockReset().mockResolvedValue({revision: INITIAL_CACHE_REVISION,records: [@@ -192,7 +217,214 @@ const restCompany: CrmCompanyEntity = {domains: [{ id: 'domain-1', companyId: 'company-1', domain: 'acme.example' }],};+const retainedHistory: HistoryItem[] = [+ {+ id: 'older-note',+ type: 'document',+ fileType: 'md',+ name: 'Older note',+ ownerId: 'owner',+ updatedAt: '2026-08-01T00:00:00.000Z',+ },+ {+ id: 'newer-note',+ type: 'document',+ fileType: 'md',+ name: 'Newer note',+ ownerId: 'owner',+ updatedAt: '2026-08-02T00:00:00.000Z',+ },+];+const retainedQueryData = {+ history: retainedHistory,+ channels: [+ {+ id: 'retained-channel',+ name: 'Retained channel',+ ownerId: 'owner',+ channelType: 'public',+ participantIds: [],+ createdAt: '2026-08-01T00:00:00.000Z',+ updatedAt: '2026-08-02T00:00:00.000Z',+ },+ ],+ 'recently-viewed': [+ { id: 'older-note', viewedAt: '2026-08-03T00:00:00.000Z' },+ ],+};++const retainedListText = {+ history: `newer-note@${Date.parse('2026-08-02T00:00:00.000Z')},older-note@${Date.parse('2026-08-01T00:00:00.000Z')}`,+ channels: `retained-channel@${Date.parse('2026-08-02T00:00:00.000Z')}`,+ 'recently-viewed': `older-note@${Date.parse('2026-08-03T00:00:00.000Z')},newer-note@${Date.parse('2026-08-02T00:00:00.000Z')}`,+};++function renderRetainedList(client: QueryClient) {+ const Shell = () => {+ const list = useQuickAccess().useList();+ const node = document.createElement('main');+ node.dataset.testid = 'retained-shell';+ createRenderEffect(() => {+ node.textContent = list+ .items()+ .map((item) => `${item.id}@${item.sortTimestamp}`)+ .join(',');+ });+ return node;+ };+ return render(() =>+ createComponent(QueryClientProvider, {+ client,+ get children() {+ return createComponent(QuickAccessProvider, {+ get children() {+ return createComponent(Shell, {});+ },+ });+ },+ })+ );+}+describe('Quick Access source integration', () => {+ it.each(+ (['history', 'channels', 'recently-viewed'] as const).flatMap((source) =>+ (['resolve', 'reject'] as const).map((settlement) => ({+ source,+ settlement,+ }))+ )+ )(+ 'keeps the same app shell mounted while $source is pending and after $settlement',+ async ({ source, settlement }) => {+ let resolve!: (items: never[]) => void;+ let reject!: (error: Error) => void;+ const pending = new Promise<never[]>((finish, fail) => {+ resolve = finish;+ reject = fail;+ });+ let query: UseQueryResult<never[]> | undefined;+ mocks.queries[source] = () =>+ (query = useQuery(() => ({+ queryKey: ['shell-regression', source],+ queryFn: () => pending,+ retry: false,+ throwOnError: false,+ })));+ const client = new QueryClient();+ const Shell = () => {+ const list = useQuickAccess().useList();+ const node = document.createElement('main');+ node.dataset.testid = 'app-shell';+ createRenderEffect(() => {+ node.textContent = `Items: ${list.totalCount()}`;+ });+ return node;+ };+ const rendered = render(() =>+ createComponent(QueryClientProvider, {+ client,+ get children() {+ return createComponent(QuickAccessProvider, {+ get children() {+ return createComponent(Shell, {});+ },+ });+ },+ })+ );+ try {+ await vi.waitFor(() => expect(query?.isPending).toBe(true));+ const shell = rendered.getByTestId('app-shell');+ expect(shell.textContent).toBe('Items: 0');+ if (settlement === 'resolve') resolve([]);+ else reject(new Error('cache lookup failed'));+ await vi.waitFor(() =>+ expect(+ settlement === 'resolve' ? query?.isSuccess : query?.isError+ ).toBe(true)+ );+ expect(rendered.getByTestId('app-shell')).toBe(shell);+ } finally {+ rendered.unmount();+ client.clear();+ }+ }+ );++ it.each(['history', 'channels', 'recently-viewed'] as const)(+ 'preserves %s items and ordering throughout a failed background refresh',+ async (source) => {+ if (source === 'recently-viewed') mocks.history = retainedHistory;+ const data = retainedQueryData[source];+ let rejectRefresh!: (error: Error) => void;+ const pendingRefresh = new Promise<unknown[]>((_resolve, reject) => {+ rejectRefresh = reject;+ });+ const fetch = vi+ .fn<() => Promise<unknown[]>>()+ .mockResolvedValueOnce(data)+ .mockReturnValueOnce(pendingRefresh);+ let query: UseQueryResult<unknown[]> | undefined;+ mocks.queries[source] = () =>+ (query = useQuery(() => ({+ queryKey: ['retained-refresh', source],+ queryFn: fetch,+ retry: false,+ throwOnError: false,+ })));+ const client = new QueryClient();+ const rendered = renderRetainedList(client);+ try {+ await vi.waitFor(() => expect(query?.isSuccess).toBe(true));+ const shell = rendered.getByTestId('retained-shell');+ const expected = retainedListText[source];+ expect(shell.textContent).toBe(expected);+ const refresh = query!.refetch();+ await vi.waitFor(() => expect(query?.isRefetching).toBe(true));+ expect(shell.textContent).toBe(expected);+ rejectRefresh(new Error('cache refresh failed'));+ await refresh;+ await vi.waitFor(() => expect(query?.isRefetchError).toBe(true));+ expect(query?.isSuccess).toBe(false);+ expect(query?.data).toEqual(data);+ expect(rendered.getByTestId('retained-shell')).toBe(shell);+ expect(shell.textContent).toBe(expected);+ } finally {+ rendered.unmount();+ client.clear();+ }+ }+ );++ it.each(['history', 'channels', 'recently-viewed'] as const)(+ 'shows %s placeholder data without suspending while a replacement is pending',+ async (source) => {+ if (source === 'recently-viewed') mocks.history = retainedHistory;+ let query: UseQueryResult<unknown[]> | undefined;+ mocks.queries[source] = () =>+ (query = useQuery<unknown[]>(() => ({+ queryKey: ['placeholder', source],+ queryFn: () => new Promise(() => {}),+ placeholderData: retainedQueryData[source],+ retry: false,+ })));+ const client = new QueryClient();+ const rendered = renderRetainedList(client);+ try {+ await vi.waitFor(() => expect(query?.isPlaceholderData).toBe(true));+ expect(query?.isFetching).toBe(true);+ expect(query?.isSuccess).toBe(true);+ expect(rendered.getByTestId('retained-shell').textContent).toBe(+ retainedListText[source]+ );+ } finally {+ rendered.unmount();+ client.clear();+ }+ }+ );+it.each(['Acme', 'acme.example'])('finds a cached CRM company absent from the REST feed by %s',async (query) => {diff --git a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsxindex fae57f44b6..af50348a4e 100644--- a/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx+++ b/apps/web/src/lib/core/context/quickAccess/QuickAccessSource.tsx@@ -380,7 +380,9 @@ export function createQuickAccessValue(): QuickAccessContextValue {const soupViewedAtMap = createLazyMemo(() => {const map = new Map<string, string>();- const data = recentlyViewedQuery.data;+ const data = queryReadyGate(recentlyViewedQuery)+ ? recentlyViewedQuery.data+ : undefined;if (!data) return map;for (const item of data) {if (item.viewedAt) map.set(item.id, item.viewedAt);@@ -394,7 +396,7 @@ export function createQuickAccessValue(): QuickAccessContextValue {const allEntries: IndexEntry[] = [];// Process history items- const historyData = historyQuery.data ?? [];+ const historyData = queryReadyGate(historyQuery) ? historyQuery.data : [];const hidden = hiddenIds();for (const item of historyData) {if (item.deletedAt) continue;@@ -454,7 +456,9 @@ export function createQuickAccessValue(): QuickAccessContextValue {// The GraphQL cache is authoritative while enabled. Otherwise preserve the// existing channel-list source unchanged.const channelData = cacheHost- ? (cachedChannelsQuery.data ?? [])+ ? queryReadyGate(cachedChannelsQuery)+ ? cachedChannelsQuery.data+ : []: channels().map(apiChannelToQuickAccessChannel);for (const sourceChannel of channelData) {const viewedAt = cacheHostdiff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 884f7ba45c..aedcf09101 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -89,6 +89,11 @@ export type CacheChangeOptions = {includeHydration?: boolean;};+/** Engine replacement is independent of whether durable cache data survived. */+export type CacheGenerationChange = {+ storage: 'preserved' | 'reset';+};+export interface CacheHost {/** Stable id of this context; used to namespace operation ids. */readonly clientId: string;@@ -172,8 +177,11 @@ export interface CacheHost {options?: CacheChangeOptions): () => void;- /** Invalidates revision watermarks before a replacement engine is used. */- onCacheGenerationChanged(cb: () => void): () => void;+ /** Invalidates in-memory revisions/dependencies on every engine replacement.+ * Durable checkpoints survive replacements that preserve stored records. */+ onCacheGenerationChanged(+ cb: (change: CacheGenerationChange) => void+ ): () => void;/** Subscribes to final commit, rollback, or supersession events. */onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void;diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.tsindex d8b40ba637..13cb428559 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -18,7 +18,10 @@ vi.mock('../worker/coordinator-page-adapter', () => ({createCacheCoordinatorPageAdapter: adapterFactory,}));-import { CACHE_COORDINATOR_PROTOCOL_VERSION } from '../worker/coordinator-protocol';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ type EngineOpenOutcome,+} from '../worker/coordinator-protocol';import {CacheBootstrapExhaustedError,COORDINATOR_CONNECT_TIMEOUT_MS,@@ -116,8 +119,11 @@ class FakePageAdapter {this.emit(message as WorkerMessage);}- replace(ownerEpoch: number): void {- this.options.onEngineReplaced?.(ownerEpoch);+ replace(+ ownerEpoch: number,+ openOutcome: EngineOpenOutcome = 'opened-existing'+ ): void {+ this.options.onEngineReplaced?.(ownerEpoch, openOutcome);}protocolError(error: Error): void {@@ -1038,6 +1044,36 @@ describe('createWorkerCacheHost', () => {host.dispose();});+ it.each([+ ['opened-existing', 'preserved'],+ ['opened-new', 'reset'],+ ['reset-incompatible', 'reset'],+ ['reset-corrupt', 'reset'],+ ['reset-storage-uncertain', 'reset'],+ ] as const)(+ 'invalidates engine dependencies but reports %s storage as %s',+ async (openOutcome, storage) => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const generations = vi.fn();+ const affected = vi.fn();+ const unsubscribe = host.onCacheGenerationChanged(generations);+ host.onOpsAffected(affected);+ await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });+ const adapter = requireAdapter();+ adapter.replace(2, openOutcome);+ await vi.waitFor(() => expect(affected).toHaveBeenCalledWith([7]));+ expect(generations).toHaveBeenCalledExactlyOnceWith({ storage });+ expect(adapter.requests.filter((r) => r.kind === 'init')).toHaveLength(2);+ adapter.replace(2, 'reset-corrupt');+ adapter.replace(1, 'reset-corrupt');+ expect(generations).toHaveBeenCalledOnce();+ unsubscribe();+ adapter.replace(3, openOutcome);+ expect(generations).toHaveBeenCalledOnce();+ host.dispose();+ }+ );+it('delivers hydration only to opted-in subscribers and cleans them up', async () => {const host = createWorkerCacheHost({ scope: 'scope-1' });const foreground = vi.fn();diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 7bcff4cdc1..b17ca76297 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -50,6 +50,7 @@ import {type CacheCoordinatorPageAdapter,createCacheCoordinatorPageAdapter,} from '../worker/coordinator-page-adapter';+import type { EngineOpenOutcome } from '../worker/coordinator-protocol';import {CacheBootstrapExhaustedError,COORDINATOR_CONNECT_ATTEMPTS,@@ -59,6 +60,7 @@ import {import { createNoopCacheHost } from './noop-host';import type {CacheChangeOptions,+ CacheGenerationChange,CacheHost,CacheReadArgs,CacheWriteArgs,@@ -204,7 +206,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const affectedSubscribers = new Set<(opKeys: number[]) => void>();const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();const hydrationSubscribers = new Set<(revision: CacheRevision) => void>();- const generationChangeSubscribers = new Set<() => void>();+ const generationChangeSubscribers = new Set<+ (change: CacheGenerationChange) => void+ >();const settlementSubscribers = new Set<(settlement: MutationSettlement) => void>();@@ -345,7 +349,10 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {for (const cb of affectedSubscribers) cb(opKeys);}- function onEngineReplaced(ownerEpoch: number): void {+ function onEngineReplaced(+ ownerEpoch: number,+ openOutcome: EngineOpenOutcome+ ): void {if (state === 'failed' || state === 'disposing' || state === 'disposed') {return;}@@ -353,7 +360,10 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {latestReplacementEpoch = ownerEpoch;// Initial readiness completes the already-running first handshake.if (state === 'initializing' && !recoveryInProgress) return;- for (const cb of generationChangeSubscribers) cb();+ const change: CacheGenerationChange = {+ storage: openOutcome === 'opened-existing' ? 'preserved' : 'reset',+ };+ for (const cb of generationChangeSubscribers) cb(change);if (state === 'ready') {beginRecoveryGeneration();// No old response put this host into recovery. Requests still pending at@@ -1198,7 +1208,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {};},- onCacheGenerationChanged(cb: () => void): () => void {+ onCacheGenerationChanged(+ cb: (change: CacheGenerationChange) => void+ ): () => void {generationChangeSubscribers.add(cb);return () => generationChangeSubscribers.delete(cb);},diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.tsindex 06f7101e87..34b8654463 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/browser-wire.ts@@ -1,3 +1,5 @@+import type { EngineOpenOutcome } from '../coordinator-protocol';+export type BrowserHarnessCommand =| { kind: 'write'; commandId: string; value: string }| { kind: 'read'; commandId: string }@@ -26,7 +28,11 @@ export type BrowserHarnessEnvelope =| { kind: 'registered' }| { kind: 'worker-created'; ownerEpoch: number }| { kind: 'worker-terminated'; ownerEpoch: number; reason: string }- | { kind: 'engine-replaced'; ownerEpoch: number }+ | {+ kind: 'engine-replaced';+ ownerEpoch: number;+ openOutcome: EngineOpenOutcome;+ }| { kind: 'cache-push'; pushKind: string }| {kind: 'command-result';diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.tsindex 9eafdf52a6..4285e09996 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/coordinator.browser.e2e.ts@@ -65,6 +65,11 @@ test('three pages fence graceful, abrupt, stale, and worker-only ownership', asypushReachedAllTabs: true,ownerLockContentionEpochs: [1, 2, 3, 4],engineReplacedEpochs: [2, 3, 4],+ replacementStorageOutcomes: [+ [2, 'opened-existing'],+ [3, 'reset-storage-uncertain'],+ [4, 'reset-storage-uncertain'],+ ],protocolErrors: [],});expect(browserErrors).toEqual([]);@@ -116,6 +121,7 @@ test('production CacheHost performs fresh init and active reread after owner los],oldEpochRejectedBeforeReplacement: true,oldRequestReplayCount: 1,+ replacementStorage: ['reset'],replacementActiveKeys: [[7, 9]],replacementReadCompleted: true,gracefulDrained: true,diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.tsindex eedb3d5aa0..7c025e0a44 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts@@ -16,7 +16,7 @@ import {declare const self: DedicatedWorkerGlobalScope;-const withVersion = <T extends { coordinatorVersion: 3 }>(+const withVersion = <T extends { coordinatorVersion: 4 }>(value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never): T =>({diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.tsindex 691d1f4ed3..be3aebb1bb 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/harness.ts@@ -61,6 +61,7 @@ const run = async (): Promise<Record<string, unknown>> => {reason: string;}> = [];const replacements = new Set<number>();+ const replacementStorageOutcomes = new Map<number, string>();const pushes = new Map<string, number>();const telemetry: EngineTelemetry[] = [];const pendingCommands = new Map<@@ -106,6 +107,10 @@ const run = async (): Promise<Record<string, unknown>> => {break;case 'engine-replaced':replacements.add(tabEvent.ownerEpoch);+ replacementStorageOutcomes.set(+ tabEvent.ownerEpoch,+ tabEvent.openOutcome+ );break;case 'cache-push':pushes.set(envelope.tabId, (pushes.get(envelope.tabId) ?? 0) + 1);@@ -367,6 +372,7 @@ const run = async (): Promise<Record<string, unknown>> => {pushReachedAllTabs: tabIds.every((tabId) => (pushes.get(tabId) ?? 0) > 0),ownerLockContentionEpochs: [1, 2, 3, 4],engineReplacedEpochs: [...replacements].toSorted(),+ replacementStorageOutcomes: [...replacementStorageOutcomes.entries()],protocolErrors,};diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.tsindex 658e44597e..d39ac4a144 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/host-harness.ts@@ -113,6 +113,11 @@ try {report.noEagerConstructor =sharedWorkerConstructions === 0 && engineWorkers.length === 0;+ const replacementStorage: string[] = [];+ host.onCacheGenerationChanged(({ storage }) =>+ replacementStorage.push(storage)+ );+ report.replacementStorage = replacementStorage;const order: string[] = [];const replacementActiveKeys: number[][] = [];let replacementRead: Promise<unknown> | undefined;diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.tsindex 3cc93fbde2..9e45691e8d 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/tab.ts@@ -77,8 +77,8 @@ const adapter = createCacheCoordinatorPageAdapter({currentWorker = undefined;report({ kind: 'worker-terminated', ownerEpoch, reason });},- onEngineReplaced: (ownerEpoch) => {- report({ kind: 'engine-replaced', ownerEpoch });+ onEngineReplaced: (ownerEpoch, openOutcome) => {+ report({ kind: 'engine-replaced', ownerEpoch, openOutcome });},onProtocolError: (error) => {report({ kind: 'protocol-error', error: error.message });diff --git a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.tsindex 18dc8cf195..435f2cb80d 100644--- a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts@@ -44,7 +44,7 @@ class FakeEndpoint extends EventTarget {}const message = {- coordinatorVersion: 3,+ coordinatorVersion: 4,kind: 'disconnect-tab',tabId: 'tab-a',reason: 'test',@@ -90,7 +90,7 @@ describe('cache coordinator runtime', () => {expect(() =>ports[0]?.postMessage({- coordinatorVersion: 3,+ coordinatorVersion: 4,kind: 'protocol-error',error: 'test',} satisfies CoordinatorToTabEnvelope)diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.tsindex bd97ce04aa..c990a4ae1e 100644--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts@@ -84,7 +84,7 @@ export interface CacheEngineRuntimeOptions {memoryTelemetryIntervalMs?: number;}-const withVersion = <T extends { coordinatorVersion: 3 }>(+const withVersion = <T extends { coordinatorVersion: 4 }>(value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never): T =>({diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.tsindex 2f85b40f9a..4546351c80 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts@@ -128,9 +128,48 @@ describe('CoordinatorCore', () => {expect(ready(core, 'tab-b', 2, 'opened-existing')).toContainEqual({kind: 'broadcast-engine-replaced',ownerEpoch: 2,+ openOutcome: 'opened-existing',});});+ it.each([+ 'opened-existing',+ 'opened-new',+ 'reset-incompatible',+ 'reset-corrupt',+ 'reset-storage-uncertain',+ ] as const)(+ 'reports actual %s storage outcome, not the requested open action',+ (openOutcome) => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ ready(core, 'tab-a', 1, 'opened-existing');+ core.beginGracefulDeparture('tab-a', 1);+ const handoff = core.engineDrained('tab-a', 1);+ expect(action(handoff, 'elect-owner').databaseAction).toBe(+ 'open-existing'+ );+ core.beginEngineOpen('tab-b', 2);+ const actions = core.engineReady({+ tabId: 'tab-b',+ ownerEpoch: 2,+ ownerLockName: OWNER_LOCK,+ expectedOwnerLockName: OWNER_LOCK,+ ownerLockHeld: true,+ databaseActionProof: openOutcome.startsWith('reset-')+ ? 'wiped-before-open'+ : 'opened-existing',+ openOutcome,+ });+ expect(action(actions, 'broadcast-engine-replaced')).toEqual({+ kind: 'broadcast-engine-replaced',+ ownerEpoch: 2,+ openOutcome,+ });+ }+ );+it('rejects unregistered and retiring-tab requests', () => {const core = new CoordinatorCore('scope');expect(core.request('missing', clear(1))).toEqual([@@ -269,6 +308,7 @@ describe('CoordinatorCore', () => {expect(ready(core, 'tab-b', 2, 'wiped-before-open')).toContainEqual({kind: 'broadcast-engine-replaced',ownerEpoch: 2,+ openOutcome: 'reset-storage-uncertain',});expect(diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.tsindex 314392a360..bb11c8ec2e 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts@@ -86,7 +86,11 @@ export type CoordinatorAction =| { kind: 'drop-tab'; tabId: string }| { kind: 'retire-tab'; tabId: string; ownerEpoch: OwnerEpoch }| { kind: 'schedule-reset-activation' }- | { kind: 'broadcast-engine-replaced'; ownerEpoch: OwnerEpoch }+ | {+ kind: 'broadcast-engine-replaced';+ ownerEpoch: OwnerEpoch;+ openOutcome: EngineOpenOutcome;+ }| {kind: 'drop-stale-engine-message';ownerEpoch: OwnerEpoch;@@ -239,6 +243,7 @@ export class CoordinatorCore {actions.push({kind: 'broadcast-engine-replaced',ownerEpoch: state.ownerEpoch,+ openOutcome: ready.openOutcome,});}while (this.queuedRequests.length > 0) {diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.tsindex b943954d13..82614459b2 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts@@ -811,7 +811,7 @@ describe('CacheCoordinatorPageAdapter', () => {const firstWorker = new FakeWorker();const workers = [firstWorker, new FakeWorker()];const dedicatedFactory = vi.fn(() => workers.shift() as FakeWorker);- const replacements: number[] = [];+ const replacements = vi.fn();const terminalErrors: string[] = [];const adapter = createCacheCoordinatorPageAdapter({scope: 'scope',@@ -821,7 +821,7 @@ describe('CacheCoordinatorPageAdapter', () => {port: coordinatorPort as unknown as MessagePort,}),createDedicatedWorker: dedicatedFactory,- onEngineReplaced: (epoch) => replacements.push(epoch),+ onEngineReplaced: replacements,onTerminalError: (error) => terminalErrors.push(error.message),});const started = adapter.start();@@ -833,11 +833,13 @@ describe('CacheCoordinatorPageAdapter', () => {...version,kind: 'engine-replaced',ownerEpoch: 1,+ openOutcome: 'opened-existing',});coordinatorPort.receive({...version,kind: 'engine-replaced',ownerEpoch: 1,+ openOutcome: 'reset-corrupt',});coordinatorPort.receive({...version,@@ -848,7 +850,7 @@ describe('CacheCoordinatorPageAdapter', () => {});coordinatorPort.receive(election(1));- expect(replacements).toEqual([1]);+ expect(replacements).toHaveBeenCalledExactlyOnceWith(1, 'opened-existing');expect(dedicatedFactory).toHaveBeenCalledOnce();expect(firstWorker.messages).toHaveLength(1);expect(firstWorker.messages[0]?.message).toMatchObject({diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.tsindex b2cef2215b..767c8a412d 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts@@ -8,6 +8,7 @@ import {import {CACHE_COORDINATOR_PROTOCOL_VERSION,type CoordinatorToTabEnvelope,+ type EngineOpenOutcome,isCacheRequest,type PageToEngineEnvelope,type TabToCoordinatorEnvelope,@@ -42,7 +43,10 @@ export interface CacheCoordinatorPageAdapterOptions {ownerEpoch: number) => DedicatedWorkerLike;lockManager?: Pick<LockManager, 'request'>;- onEngineReplaced?: (ownerEpoch: number) => void;+ onEngineReplaced?: (+ ownerEpoch: number,+ openOutcome: EngineOpenOutcome+ ) => void;onStartupProgress?: (progress: Extract<CoordinatorToTabEnvelope, { kind: 'engine-startup' }>) => void;@@ -71,7 +75,7 @@ interface CoordinatorConnection {const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;-const withVersion = <T extends { coordinatorVersion: 3 }>(+const withVersion = <T extends { coordinatorVersion: 4 }>(value: T extends unknown ? Omit<T, 'coordinatorVersion'> : never): T =>({@@ -573,7 +577,10 @@ export class CacheCoordinatorPageAdapter {this.highestOwnerEpochSeen,message.ownerEpoch);- this.options.onEngineReplaced?.(message.ownerEpoch);+ this.options.onEngineReplaced?.(+ message.ownerEpoch,+ message.openOutcome+ );break;case 'protocol-error': {const error = new Error(message.error);diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.tsindex a427dbaf91..0f7832e00a 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts@@ -333,13 +333,64 @@ describe('coordinator runtime protocol', () => {tabId: 'tab',ownerEpoch: 1,},- { ...version, kind: 'engine-replaced', ownerEpoch: 2 },+ {+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 2,+ openOutcome: 'opened-existing',+ },{ ...version, kind: 'protocol-error', error: 'bad envelope' },{ ...version, kind: 'terminal-error', error: 'recovery exhausted' },])('accepts coordinator-to-tab envelope $kind', (message) => {expect(validateCoordinatorToTabEnvelope(message).ok).toBe(true);});+ it.each([+ 'opened-existing',+ 'opened-new',+ 'reset-incompatible',+ 'reset-corrupt',+ 'reset-storage-uncertain',+ ])(+ 'retains the validated storage outcome %s on replacement',+ (openOutcome) => {+ const message = {+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 2,+ openOutcome,+ };+ expect(validateCoordinatorToTabEnvelope(message)).toEqual({+ ok: true,+ value: message,+ });+ }+ );++ it.each([undefined, null, 'open-existing', 'unknown'])(+ 'rejects ambiguous replacement storage outcome %s',+ (openOutcome) => {+ expect(+ validateCoordinatorToTabEnvelope({+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 2,+ openOutcome,+ }).ok+ ).toBe(false);+ }+ );++ it('rejects the old protocol rather than guessing whether storage survived', () => {+ expect(+ validateCoordinatorToTabEnvelope({+ coordinatorVersion: 3,+ kind: 'engine-replaced',+ ownerEpoch: 2,+ }).ok+ ).toBe(false);+ });+it('validates activation and both direct-port directions', () => {expect(validatePageToEngineEnvelope({diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.tsindex 9041b3332d..c23b307326 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts@@ -20,7 +20,7 @@ import {export { isCachePush, isCacheResponse, isWorkerMessage };/** Version of the topology envelope and routed cache RPC surface. */-export const CACHE_COORDINATOR_PROTOCOL_VERSION = 3 as const;+export const CACHE_COORDINATOR_PROTOCOL_VERSION = 4 as const;export type EngineStartupPhase = 'loading-assets' | 'opening-database';export type OwnerEpoch = number;@@ -40,7 +40,7 @@ export type ActivationFailureCode =export type TabToCoordinatorEnvelope =| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'register-tab';scope: string;tabId: string;@@ -48,40 +48,40 @@ export type TabToCoordinatorEnvelope =hotCapacity?: number;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'cache-request';tabId: string;request: CacheRequest;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'attach-engine-port';tabId: string;ownerEpoch: OwnerEpoch;enginePort: MessagePort;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'graceful-departure';tabId: string;ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'navigation-departure';tabId: string;ownerEpoch: OwnerEpoch;reason: string;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-lost';tabId: string;ownerEpoch: OwnerEpoch;reason: string;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'disconnect-tab';tabId: string;reason: string;@@ -89,12 +89,12 @@ export type TabToCoordinatorEnvelope =export type CoordinatorToTabEnvelope =| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'registered';tabId: string;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'become-owner';scope: string;tabId: string;@@ -104,25 +104,25 @@ export type CoordinatorToTabEnvelope =hotCapacity?: number;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'cache-message';message: WorkerMessage;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'terminate-engine';tabId: string;ownerEpoch: OwnerEpoch;reason: string;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'retire-complete';tabId: string;ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-startup';ownerEpoch: OwnerEpoch;phase: EngineStartupPhase;@@ -130,24 +130,26 @@ export type CoordinatorToTabEnvelope =timeoutMs: number;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-replaced';ownerEpoch: OwnerEpoch;+ /** Whether this engine reopened durable data or created/reset it. */+ openOutcome: EngineOpenOutcome;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'protocol-error';error: string;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'terminal-error';error: string;storageUntouched?: true;};export type PageToEngineEnvelope = {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'activate-engine';scope: string;tabId: string;@@ -159,24 +161,24 @@ export type PageToEngineEnvelope = {export type CoordinatorToEngineEnvelope =| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'open-engine';ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-request';ownerEpoch: OwnerEpoch;routeId: RouteId;request: CacheRequest;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'drain-engine';ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'heartbeat';ownerEpoch: OwnerEpoch;heartbeatId: number;@@ -184,13 +186,13 @@ export type CoordinatorToEngineEnvelope =export type EngineToCoordinatorEnvelope =| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-assets-ready';tabId: string;ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-ready';tabId: string;ownerEpoch: OwnerEpoch;@@ -200,26 +202,26 @@ export type EngineToCoordinatorEnvelope =openOutcome: EngineOpenOutcome;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-response';ownerEpoch: OwnerEpoch;routeId: RouteId;response: CacheResponse;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-push';ownerEpoch: OwnerEpoch;push: CachePush;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-drained';tabId: string;ownerEpoch: OwnerEpoch;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'engine-fatal';tabId: string;ownerEpoch: OwnerEpoch;@@ -227,7 +229,7 @@ export type EngineToCoordinatorEnvelope =fatalCode: EngineFatalCode;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'activation-failed';tabId: string;ownerEpoch: OwnerEpoch;@@ -235,7 +237,7 @@ export type EngineToCoordinatorEnvelope =failureCode: ActivationFailureCode;}| {- coordinatorVersion: 3;+ coordinatorVersion: 4;kind: 'heartbeat-ack';ownerEpoch: OwnerEpoch;heartbeatId: number;@@ -860,8 +862,14 @@ export function validateCoordinatorToTabEnvelope(break;case 'engine-replaced':if (- hasOnlyKeys(value, ['coordinatorVersion', 'kind', 'ownerEpoch']) &&- isPositiveInteger(value.ownerEpoch)+ hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'openOutcome',+ ]) &&+ isPositiveInteger(value.ownerEpoch) &&+ isEngineOpenOutcome(value.openOutcome)) {return pass(value as CoordinatorToTabEnvelope);}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.tsindex 6d4b306047..bb5f59a839 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts@@ -122,7 +122,7 @@ type WithoutVersion<T> = T extends unknown? Omit<T, 'coordinatorVersion'>: never;-const envelope = <T extends { coordinatorVersion: 3 }>(+const envelope = <T extends { coordinatorVersion: 4 }>(value: WithoutVersion<T>): T =>({@@ -855,6 +855,7 @@ export class CoordinatorRouter {envelope<CoordinatorToTabEnvelope>({kind: 'engine-replaced',ownerEpoch: action.ownerEpoch,+ openOutcome: action.openOutcome,}));break;diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsxindex 5e1cdf010c..d079239260 100644--- a/apps/web/src/lib/queries/soup/backfill.test.tsx+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx@@ -1,3 +1,4 @@+import type { CacheGenerationChange } from '@graphql-cache/host/types';import { render } from '@solidjs/testing-library';import * as Effect from 'effect/Effect';import * as Fiber from 'effect/Fiber';@@ -28,12 +29,16 @@ const telemetryMocks = vi.hoisted(() => ({anonymousSpan: vi.fn(),}));-const cacheGenerationCallbacks = new Set<() => void>();+const cacheGenerationCallbacks = new Set<+ (change: CacheGenerationChange) => void+>();const mockCacheHost = {- onCacheGenerationChanged: vi.fn((callback: () => void) => {- cacheGenerationCallbacks.add(callback);- return () => cacheGenerationCallbacks.delete(callback);- }),+ onCacheGenerationChanged: vi.fn(+ (callback: (change: CacheGenerationChange) => void) => {+ cacheGenerationCallbacks.add(callback);+ return () => cacheGenerationCallbacks.delete(callback);+ }+ ),};vi.mock('@app/lib/analytics/posthog', () => ({@@ -429,60 +434,167 @@ describe('runSoupBackfills', () => {});});- it('restarts from the beginning when the cache generation is replaced', async () => {- localStorage.setItem(- 'graphql-soup-backfill:v15:user-1:core-entities',- JSON.stringify({- userId: 'user-1',- nextCursor: 'stale-cursor',- pagesFetched: 12,- completed: false,- scanStartedAt: '2026-09-01T00:00:00.000Z',- updatedSince: null,- completedAt: null,- })- );- const fetchInputs: unknown[] = [];- const fetchSignals: AbortSignal[] = [];- graphqlMocks.hydrateGraphqlSoup.mockImplementation(- (- _document,- variables: { input: unknown },- options: { signal: AbortSignal }- ) =>- new Promise((_resolve, reject) => {- fetchInputs.push(variables.input);- fetchSignals.push(options.signal);- options.signal.addEventListener(- 'abort',- () => reject(options.signal.reason),- { once: true }- );+ it.each(['preserved', 'reset'] as const)(+ 'restarts the runner with %s storage semantics and ignores obsolete completions',+ async (storage) => {+ localStorage.setItem(+ 'graphql-soup-backfill:v15:user-1:core-entities',+ JSON.stringify({+ userId: 'user-1',+ nextCursor: 'stale-cursor',+ pagesFetched: 12,+ completed: false,+ scanStartedAt: '2026-09-01T00:00:00.000Z',+ updatedSince: null,+ completedAt: null,})- );-- const rendered = render(() => <BackfillRunner userId="user-1" />);- await vi.waitFor(() =>- expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledOnce()- );- expect(fetchInputs[0]).toMatchObject({- continuation: { cursor: 'stale-cursor' },- });-- for (const callback of cacheGenerationCallbacks) callback();-- await vi.waitFor(() =>- expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)- );- expect(fetchSignals[0]?.aborted).toBe(true);- expect(fetchInputs[1]).toMatchObject({ initial: { limit: 100 } });- expect(loadSoupBackfillCheckpoint('user-1', 'core-entities')).toMatchObject(- {- nextCursor: null,- pagesFetched: 0,+ );+ const fetchInputs: unknown[] = [];+ const fetchSignals: AbortSignal[] = [];+ const finishPages: Array<(page: { nextCursor: string | null }) => void> =+ [];+ graphqlMocks.hydrateGraphqlSoup.mockImplementation(+ (+ _document,+ variables: { input: unknown },+ options: { signal: AbortSignal }+ ) =>+ new Promise((resolve) => {+ fetchInputs.push(variables.input);+ fetchSignals.push(options.signal);+ // Model an already-admitted cache write that cannot be cancelled.+ finishPages.push(resolve);+ })+ );++ const rendered = render(() => <BackfillRunner userId="user-1" />);+ await vi.waitFor(() =>+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledOnce()+ );+ expect(fetchInputs[0]).toMatchObject({+ continuation: { cursor: 'stale-cursor' },+ });++ for (const callback of cacheGenerationCallbacks) callback({ storage });++ await vi.waitFor(() =>+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)+ );+ expect(fetchSignals[0]?.aborted).toBe(true);+ expect(fetchInputs[1]).toMatchObject(+ storage === 'preserved'+ ? { continuation: { cursor: 'stale-cursor' } }+ : { initial: { limit: 100 } }+ );+ const expected =+ storage === 'preserved'+ ? { nextCursor: 'stale-cursor', pagesFetched: 12 }+ : { nextCursor: null, pagesFetched: 0 };+ expect(+ loadSoupBackfillCheckpoint('user-1', 'core-entities')+ ).toMatchObject(expected);+ finishPages[0]({ nextCursor: 'obsolete-cursor' });+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(+ loadSoupBackfillCheckpoint('user-1', 'core-entities')+ ).toMatchObject(expected);+ rendered.unmount();+ }+ );++ it.each(['preserved', 'reset'] as const)(+ 'keeps completed watermarks and other lanes only for %s storage',+ async (storage) => {+ const watermark = '2026-09-01T00:00:00.000Z';+ for (const checkpointId of ['core-entities', 'email-thread-pages']) {+ localStorage.setItem(+ `graphql-soup-backfill:v15:user-1:${checkpointId}`,+ JSON.stringify({+ userId: 'user-1',+ nextCursor: null,+ pagesFetched: 12,+ completed: true,+ scanStartedAt: null,+ updatedSince: watermark,+ completedAt: watermark,+ })+ );}- );- rendered.unmount();+ graphqlMocks.hydrateGraphqlSoup.mockImplementation(+ () => new Promise(() => {})+ );+ const rendered = render(() => <BackfillRunner userId="user-1" />);+ try {+ await vi.waitFor(() =>+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledOnce()+ );+ const firstInput = graphqlMocks.hydrateGraphqlSoup.mock.calls[0][1];+ expect(JSON.stringify(firstInput)).toContain(watermark);+ for (const callback of cacheGenerationCallbacks) callback({ storage });+ await vi.waitFor(() =>+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)+ );+ const nextInput = graphqlMocks.hydrateGraphqlSoup.mock.calls[1][1];+ if (storage === 'preserved') {+ expect(nextInput).toEqual(firstInput);+ expect(+ loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')+ ).toMatchObject({+ completed: true,+ pagesFetched: 12,+ updatedSince: watermark,+ });+ } else {+ expect(JSON.stringify(nextInput)).not.toContain(watermark);+ expect(+ loadSoupBackfillCheckpoint('user-1', 'email-thread-pages')+ ).toMatchObject({+ completed: false,+ pagesFetched: 0,+ updatedSince: null,+ });+ }+ } finally {+ rendered.unmount();+ }+ }+ );++ it('transfers leadership between runners without refetching committed pages', async () => {+ const [firstLeader, setFirstLeader] = createSignal(true);+ const [secondLeader, setSecondLeader] = createSignal(false);+ leaderMocks.createTabLeaderSignal+ .mockReturnValueOnce(firstLeader)+ .mockReturnValueOnce(secondLeader);+ graphqlMocks.hydrateGraphqlSoup+ .mockResolvedValueOnce({ nextCursor: 'committed-page-cursor' })+ .mockImplementation(() => new Promise(() => {}));+ const first = render(() => <BackfillRunner userId="user-1" />);+ const second = render(() => <BackfillRunner userId="user-1" />);+ try {+ await vi.waitFor(() =>+ expect(+ loadSoupBackfillCheckpoint('user-1', 'core-entities')+ ).toMatchObject({+ nextCursor: 'committed-page-cursor',+ pagesFetched: 1,+ })+ );+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledOnce();+ setFirstLeader(false);+ setSecondLeader(true);+ await vi.waitFor(() =>+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)+ );+ expect(graphqlMocks.hydrateGraphqlSoup.mock.calls[1][1]).toMatchObject({+ input: { continuation: { cursor: 'committed-page-cursor' } },+ });+ expect(cacheGenerationCallbacks.size).toBe(1);+ } finally {+ first.unmount();+ second.unmount();+ }+ expect(cacheGenerationCallbacks.size).toBe(0);});it('cancels the current backfill and starts a new one when the user changes', async () => {diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.tsindex 56013b0969..941711fb4f 100644--- a/apps/web/src/lib/queries/soup/backfill.ts+++ b/apps/web/src/lib/queries/soup/backfill.ts@@ -583,8 +583,8 @@ const waitForGraphqlSoupCacheHost = Effect.suspend(() => {/*** Runs the checkpointed backfill Effect while this tab owns leadership.* Interrupting the fiber cancels cache readiness waits, active fetches, and- * inter-page sleeps. A replacement cache generation resets the external- * cursors before restarting so they can never point past wiped cache data.+ * inter-page sleeps. Engine handoffs resume durable checkpoints; only loss of+ * stored cache data resets cursors so they cannot point past wiped records.*/export function useSoupBackfills(userId: string): void {const graphqlSoupFlag = useFeatureFlag(enableGraphqlSoup);@@ -615,8 +615,8 @@ export function useSoupBackfills(userId: string): void {const host = cacheHost();if (!host) return;- const unsubscribe = host.onCacheGenerationChanged(() => {- resetDefaultSoupBackfillCheckpoints(userId);+ const unsubscribe = host.onCacheGenerationChanged(({ storage }) => {+ if (storage === 'reset') resetDefaultSoupBackfillCheckpoints(userId);setCacheGeneration((generation) => generation + 1);});onCleanup(unsubscribe);diff --git a/docs/AGENT_GUIDE/navigation.md b/docs/AGENT_GUIDE/navigation.mdindex 80c3434f57..50d0269b8e 100644--- a/docs/AGENT_GUIDE/navigation.md+++ b/docs/AGENT_GUIDE/navigation.md@@ -335,6 +335,15 @@ another pagination attempt. A missing item may still be uncached, but should applocal search excludes unsupported email hits before limiting entity results;email mentions keep their separate search-service path.+Pending or failed Quick Access history, recently-viewed, and cached-channel lookups+must not hide the app shell. Verify a cold lookup with Cmd/Ctrl+K: navigation stays+mounted and usable while the optional source loads or fails. A failed background+refresh retains available history/channel items and recently-viewed ordering.+Placeholder results also remain usable while replacement data loads. A normal cache-worker+handoff between tabs preserves backfill cursors and watermarks; only a replacement+that creates or resets stored cache data discards them. Per-lane full-refresh and+Shared Mail restart rules still apply.+## Keyboard model (from the in-app guide; verified partially)- `Ctrl/Cmd+K` — jump to anything by name.