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.

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.ts
index 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.tsx
index 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 = cacheHost
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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', asy
pushReachedAllTabs: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.md
index 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 app
local 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.