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/fix/cache disposed (#6885)
Sean Aye6fe24fc727dc
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.tsindex 70373f1d4d..3deeb17495 100644--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts@@ -24,7 +24,8 @@ import {type Source,subscribe,} from 'wonka';-import type { CacheHost } from '../host/types';+import { CacheNavigationError } from '../host/navigation-error';+import type { CacheGenerationChange, CacheHost } from '../host/types';import {ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,type ClaimedMutation,@@ -202,11 +203,15 @@ type FakeHost = CacheHost & {args: Parameters<CacheHost['enqueueOptimisticMutation']>[0]) => void;pushAffected: (opKeys: number[]) => void;+ pushGeneration: (change: CacheGenerationChange) => void;};function makeFakeHost(): FakeHost {let readResult: ReadResult = { kind: 'miss' };const subscribers = new Set<(opKeys: number[]) => void>();+ const generationSubscribers = new Set<+ (change: CacheGenerationChange) => void+ >();const queue: Array<{transactionId: string;args: Parameters<CacheHost['enqueueOptimisticMutation']>[0];@@ -266,6 +271,9 @@ function makeFakeHost(): FakeHost {pushAffected: (opKeys) => {for (const cb of subscribers) cb(opKeys);},+ pushGeneration: (change) => {+ for (const cb of generationSubscribers) cb(change);+ },async currentRevision() {return INITIAL_CACHE_REVISION;},@@ -416,8 +424,9 @@ function makeFakeHost(): FakeHost {onCacheChanged() {return () => undefined;},- onCacheGenerationChanged() {- return () => undefined;+ onCacheGenerationChanged(cb) {+ generationSubscribers.add(cb);+ return () => generationSubscribers.delete(cb);},onMutationSettled() {return () => undefined;@@ -836,6 +845,53 @@ describe('normalizedCacheExchange', () => {expect(cacheContainsDocument).toBe(false);});+ it('cancels queued subscription effects on teardown even when the same key resubscribes', async () => {+ const firstWrite = deferred<WriteResult>();+ const write = vi+ .spyOn(host, 'writeQuery')+ .mockImplementationOnce(() => firstWrite.promise);+ const remove = vi.spyOn(host, 'deleteRecords');+ const { ops, network } = controlledQueryHarness(host);+ const operation = makeSubscriptionOp(24);+ ops.next(operation);+ network.next(+ queryResult(operation, {+ soupUpdates: [+ {+ __typename: 'SoupUpdated',+ item: { __typename: 'GraphqlSoupDocument', id: 'one' },+ },+ {+ __typename: 'GraphqlCacheDeletion',+ graphqlTypeName: 'GraphqlSoupDocument',+ entityId: 'one',+ },+ ],+ })+ );+ network.next(+ queryResult(operation, {+ soupUpdates: [{ id: 'queued-before-navigation' }],+ })+ );+ await vi.waitFor(() => expect(write).toHaveBeenCalledOnce());++ ops.next(makeOperation('teardown', operation, operation.context));+ ops.next(operation);+ const fresh = { soupUpdates: [{ id: 'after-restore' }] };+ network.next(queryResult(operation, fresh));+ firstWrite.resolve({+ revision: INITIAL_CACHE_REVISION,+ revisionAdvanced: true,+ changed: [],+ affectedOps: [],+ reset: false,+ });+ await vi.waitFor(() => expect(write).toHaveBeenCalledTimes(2));+ expect(write.mock.calls[1]?.[0].data).toBe(fresh);+ expect(remove).not.toHaveBeenCalled();+ });+it('reports cache failures without dropping subscription results or later patches', async () => {const error = new Error('subscription cache write failed');vi.spyOn(host, 'writeQuery').mockRejectedValueOnce(error);@@ -2450,6 +2506,192 @@ describe('normalizedCacheExchange', () => {expect(host.commits[0]?.transactionId).toBe('restored-1');});+ describe('mutation drain after cache restoration', () => {+ beforeEach(() => vi.useFakeTimers());+ afterEach(() => {+ vi.clearAllTimers();+ vi.useRealTimers();+ vi.restoreAllMocks();+ });++ it.each([+ { wake: 'online', whileDeferring: false },+ { wake: 'online', whileDeferring: true },+ { wake: 'restore', whileDeferring: false },+ { wake: 'restore', whileDeferring: true },+ ])(+ 'preserves short retry deadlines after $wake (while deferring: $whileDeferring)',+ async ({ wake, whileDeferring }) => {+ // Isolate the online listener from other exchanges in this suite.+ const events = new EventTarget();+ vi.spyOn(globalThis, 'addEventListener').mockImplementation(+ events.addEventListener.bind(events)+ );+ const deferring = deferred<void>();+ const defer = host.deferOptimisticWrite.bind(host);+ const deferSpy = vi.spyOn(host, 'deferOptimisticWrite');+ if (whileDeferring) {+ deferSpy.mockImplementationOnce(async (...args) => {+ const result = await defer(...args);+ await deferring.promise;+ return result;+ });+ }+ const error = new CombinedError({+ networkError: new Error('offline'),+ });+ let attempts = 0;+ const { ops, forwarded } = harness(+ host,+ () =>+ ++attempts <= 5+ ? { error, data: undefined }+ : { data: optimistic },+ { shouldRetryMutation: () => true }+ );+ ops.next(makeMutationOp(1, optimistic));+ await vi.advanceTimersByTimeAsync(0);++ for (const delay of [1_000, 2_000, 4_000, 8_000, 16_000]) {+ const retryAt = deferSpy.mock.calls.at(-1)![2];+ expect(retryAt - Date.now()).toBe(delay);+ const sendsBeforeWake = forwarded.length;+ await vi.advanceTimersByTimeAsync(100);+ if (wake === 'online') events.dispatchEvent(new Event('online'));+ else host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(1);+ deferring.resolve();+ await vi.advanceTimersByTimeAsync(1);+ expect(forwarded).toHaveLength(sendsBeforeWake);++ await vi.advanceTimersByTimeAsync(retryAt - Date.now() - 1);+ expect(forwarded).toHaveLength(sendsBeforeWake);+ await vi.advanceTimersByTimeAsync(1);+ expect(forwarded).toHaveLength(sendsBeforeWake + 1);+ }+ expect(host.begins).toHaveLength(1);+ expect(host.defers).toHaveLength(5);+ expect(host.commits).toHaveLength(1);+ expect(host.rollbacks).toHaveLength(0);+ }+ );++ it('retires an expired retry hint if another runner owns the head', async () => {+ const error = new CombinedError({ networkError: new Error('offline') });+ const { ops, forwarded } = harness(+ host,+ () => ({ error, data: undefined }),+ { shouldRetryMutation: () => true }+ );+ ops.next(makeMutationOp(1, optimistic));+ await vi.advanceTimersByTimeAsync(0);+ const claim = vi+ .spyOn(host, 'claimNextMutation')+ .mockResolvedValue(undefined);+ await vi.advanceTimersByTimeAsync(100);+ host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(0);+ expect(claim).toHaveBeenCalledOnce();+ await vi.advanceTimersByTimeAsync(1_000);+ expect(claim).toHaveBeenCalledTimes(2);+ expect(forwarded).toHaveLength(1);+ });++ it.each([false, true])(+ 'resumes an interrupted claim without waiting for the poll (restore while pending: %s)',+ async (restoreWhilePending) => {+ const pendingClaim = deferred<ClaimedMutation | undefined>();+ const claim = vi.spyOn(host, 'claimNextMutation');+ claim.mockImplementationOnce(() => pendingClaim.promise);+ host.seedQueued({+ uuid: crypto.randomUUID(),+ query: stringifyDocument(MUTATION),+ data: optimistic,+ });+ const { forwarded } = harness(host);+ await vi.advanceTimersByTimeAsync(0);+ expect(claim).toHaveBeenCalledOnce();++ if (restoreWhilePending) {+ host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(1);+ expect(claim).toHaveBeenCalledOnce();+ }+ pendingClaim.reject(new CacheNavigationError());+ await vi.advanceTimersByTimeAsync(1);+ if (!restoreWhilePending) {+ expect(forwarded).toHaveLength(0);+ host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(1);+ }++ expect(host.claims).toEqual(['restored-1']);+ expect(host.commits).toHaveLength(1);+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);+ }+ );++ it.each([+ { restoreWhilePending: false, committed: false },+ { restoreWhilePending: false, committed: true },+ { restoreWhilePending: true, committed: false },+ { restoreWhilePending: true, committed: true },+ ])(+ 'rechecks an uncertain commit without bypassing leases ($restoreWhilePending, $committed)',+ async ({ restoreWhilePending, committed }) => {+ const pendingCommit = deferred<CommitOptimisticWriteResult>();+ const commit = host.commitOptimisticWrite.bind(host);+ vi.spyOn(host, 'commitOptimisticWrite').mockImplementationOnce(+ async (...args) => {+ // The worker may have committed even though its reply was lost.+ if (committed) await commit(...args);+ return await pendingCommit.promise;+ }+ );+ const claim = vi.spyOn(host, 'claimNextMutation');+ const { ops, forwarded, results } = harness(host);+ await vi.advanceTimersByTimeAsync(0);+ ops.next(makeMutationOp(1, optimistic));+ await vi.advanceTimersByTimeAsync(1);+ host.seedQueued({+ uuid: crypto.randomUUID(),+ query: stringifyDocument(MUTATION),+ data: optimistic,+ });+ const claimsBeforeRestore = claim.mock.calls.length;++ if (restoreWhilePending) {+ host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(1);+ expect(claim).toHaveBeenCalledTimes(claimsBeforeRestore);+ }+ pendingCommit.reject(new CacheNavigationError());+ await vi.advanceTimersByTimeAsync(1);+ if (!restoreWhilePending) {+ host.pushGeneration({ storage: 'reset' });+ await vi.advanceTimersByTimeAsync(1);+ }++ expect(claim.mock.calls.length).toBeGreaterThan(claimsBeforeRestore);+ expect(+ optimisticMutationDispositionOf(+ results.find((result) => result.operation.key === 1)!+ )+ ).toEqual({ kind: 'queued', transactionId: 'txn-1' });+ // A runnable successor is sent immediately, but an unsettled head's+ // existing lease must never be stolen or its network call duplicated.+ expect(forwarded).toHaveLength(committed ? 2 : 1);+ expect(host.commits).toHaveLength(committed ? 2 : 0);+ const claimsAfterRestore = claim.mock.calls.length;+ await vi.advanceTimersByTimeAsync(30_000);+ // Forget the stale five-minute local backoff even if no head could+ // be claimed on restore; the durable queue still controls eligibility.+ expect(claim.mock.calls.length).toBeGreaterThan(claimsAfterRestore);+ expect(forwarded).toHaveLength(committed ? 2 : 1);+ }+ );+ });+it('rolls back when a persisted replay resolves with an urql error', async () => {host.seedQueued({uuid: '00000000-0000-4000-8000-000000000002',diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.tsindex b2fac447bb..96707a1722 100644--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts@@ -767,17 +767,31 @@ export function normalizedCacheExchange(}>();const subscriptionEffectChains = new Map<number, Promise<void>>();+ // Teardown invalidates queued effects, including when the same operation+ // is immediately resubscribed after a back/forward-cache restore.+ const subscriptionGenerations = new Map<number, object>();let attemptInFlight = false;let drainRunning = false;+ let drainRequested = false;let deferredUntil: number | undefined;let drainTimer: ReturnType<typeof setTimeout> | undefined;function scheduleDrain(delayMs = 0): void {if (drainTimer !== undefined) clearTimeout(drainTimer);- drainTimer = setTimeout(() => {- drainTimer = undefined;- void drainQueue();- }, delayMs);+ drainTimer = setTimeout(+ () => {+ drainTimer = undefined;+ void drainQueue();+ },+ drainRequested ? 0 : delayMs+ );+ }++ function wakeDrain(): void {+ // Keep the wakeup until the runner can claim again. An interrupted+ // claim/settlement may still be unwinding and scheduling its backoff.+ drainRequested = true;+ scheduleDrain();}function resolveLiveOperationsAsQueued(): void {@@ -880,8 +894,15 @@ export function normalizedCacheExchange(}if (drainRunning) return;drainRunning = true;+ drainRequested = false;try {const now = Date.now();+ // A wakeup probes immediately, but must retain a future retry+ // deadline if the durable head is not eligible yet. Consume expired+ // hints so a head leased by another runner cannot cause a busy loop.+ if (deferredUntil !== undefined && deferredUntil <= now) {+ deferredUntil = undefined;+ }const claimed = await host.claimNextMutation(queueOwner,now,@@ -889,10 +910,15 @@ export function normalizedCacheExchange();if (!claimed) {resolveLiveOperationsAsQueued();+ // Short retries keep their deadline; uncertain five-minute lease+ // backoffs must not prevent regular polling after a wakeup.scheduleDrain(deferredUntil === undefined? EMPTY_QUEUE_POLL_MS- : Math.max(0, deferredUntil - Date.now())+ : Math.min(+ EMPTY_QUEUE_POLL_MS,+ Math.max(0, deferredUntil - Date.now())+ ));return;}@@ -905,6 +931,7 @@ export function normalizedCacheExchange(scheduleDrain(EMPTY_QUEUE_POLL_MS);} finally {drainRunning = false;+ if (drainRequested) scheduleDrain();}}@@ -1145,9 +1172,11 @@ export function normalizedCacheExchange(/** Applies operation cache effects serially and isolates every failure. */async function applyOperationCacheEffects(op: Operation,- effects: CacheEffect[]+ effects: CacheEffect[],+ isCurrent: () => boolean = () => true): Promise<void> {for (const effect of effects) {+ if (!isCurrent()) return;try {if (effect.kind === 'write') {await host.writeQuery({@@ -1268,8 +1297,15 @@ export function normalizedCacheExchange(// result after its effects settle.const previousEffects =subscriptionEffectChains.get(op.key) ?? Promise.resolve();+ const generation = subscriptionGenerations.get(op.key);const effects = previousEffects.then(() =>- applyOperationCacheEffects(op, operationCacheEffects(result.data))+ applyOperationCacheEffects(+ op,+ operationCacheEffects(result.data),+ () =>+ generation !== undefined &&+ subscriptionGenerations.get(op.key) === generation+ ));subscriptionEffectChains.set(op.key, effects);try {@@ -1492,7 +1528,11 @@ export function normalizedCacheExchange(shared,filter((op) => op.kind !== 'query' && op.kind !== 'mutation'),tap((op) => {+ if (op.kind === 'subscription') {+ subscriptionGenerations.set(op.key, {});+ }if (op.kind === 'teardown') {+ subscriptionGenerations.delete(op.key);activeOps.delete(op.key);queryStates.delete(op.key);affectedRereads.forget(op.key);@@ -1509,8 +1549,12 @@ export function normalizedCacheExchange(if (!host.disabled) {scheduleDrain();+ // Includes BFCache restoration, even with no active query keys. The+ // host gates claims on initialization; durable leases still decide+ // which head is runnable after reconnecting.+ host.onCacheGenerationChanged(wakeDrain);if (typeof addEventListener === 'function') {- addEventListener('online', () => scheduleDrain());+ addEventListener('online', wakeDrain);}}void unsubscribePush;diff --git a/apps/web/src/lib/graphql-cache/host/navigation-error.ts b/apps/web/src/lib/graphql-cache/host/navigation-error.tsnew file mode 100644index 0000000000..da34f6026e--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/navigation-error.ts@@ -0,0 +1,7 @@+/** Expected cancellation when a page releases its cache transport for navigation. */+export class CacheNavigationError extends Error {+ constructor() {+ super('cache worker host was disposed for page navigation');+ this.name = 'CacheNavigationError';+ }+}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 13cb428559..e9265de39e 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@@ -26,6 +26,7 @@ import {CacheBootstrapExhaustedError,COORDINATOR_CONNECT_TIMEOUT_MS,} from '../worker/startup';+import { CacheNavigationError } from './navigation-error';import { createWorkerCacheHost } from './worker-host';const CLIENT_ID = '00000000-0000-4000-8000-000000000007';@@ -1557,6 +1558,235 @@ describe('createWorkerCacheHost', () => {await draining;});+ it('classifies admitted and late navigation writes consistently', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.currentRevision();+ const adapter = requireAdapter();+ adapter.ignoredKinds.add('write');+ const args = {+ query: 'subscription Updates { update }',+ data: { update: 1 },+ };+ const admitted = host.writeQuery(args);+ const rejected =+ expect(admitted).rejects.toBeInstanceOf(CacheNavigationError);+ await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('write'));+ dispatchEvent(new PageTransitionEvent('pagehide'));+ await rejected;+ await expect(host.writeQuery(args)).rejects.toBeInstanceOf(+ CacheNavigationError+ );+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await expect(host.currentRevision()).rejects.toBeInstanceOf(+ CacheNavigationError+ );+ expect(adapterFactory).toHaveBeenCalledOnce();+ });++ it('reconnects the same host repeatedly and retains subscriptions and active query dependencies', async () => {+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ const affected = vi.fn();+ const generations = vi.fn();+ const changed = vi.fn();+ const hydrated = vi.fn();+ const settled = vi.fn();+ host.onOpsAffected(affected);+ host.onCacheGenerationChanged(generations);+ host.onCacheChanged(changed);+ host.onCacheChanged(hydrated, { includeHydration: true });+ host.onMutationSettled(settled);++ for (let cycle = 0; cycle < 2; cycle += 1) {+ await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });+ await host.readQuery({ opKey: 9, query: 'query Nine { nine }' });+ const old = requireAdapter();+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ expect(old.dispose).toHaveBeenCalledWith({+ graceful: false,+ preserveDatabase: true,+ });+ await host.teardown(9);+ await expect(host.currentRevision()).rejects.toBeInstanceOf(+ CacheNavigationError+ );+ old.terminalError(new Error('late retired transport error'));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await host.currentRevision();+ const replacement = requireAdapter();+ expect(replacement).not.toBe(old);+ expect(affected).toHaveBeenLastCalledWith([7]);+ expect(generations).toHaveBeenLastCalledWith({ storage: 'reset' });+ expect(host.clientId).toBe(CLIENT_ID);+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');+ expect(replacement.options.scope).toBe('scope-1');+ old.replace(100);+ old.terminalError(new Error('late callback after restore'));+ old.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });+ expect(changed).toHaveBeenCalledTimes(cycle);+ replacement.push({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ });+ replacement.push({+ kind: 'cache-hydrated',+ revision: INITIAL_CACHE_REVISION,+ });+ replacement.push({+ kind: 'mutation-settled',+ settlement: { transactionId: '3', status: 'committed' },+ });+ expect(changed).toHaveBeenCalledTimes(cycle + 1);+ expect(hydrated).toHaveBeenCalledTimes((cycle + 1) * 2);+ expect(settled).toHaveBeenCalledTimes(cycle + 1);+ }+ expect(adapterFactory).toHaveBeenCalledTimes(3);+ expect(onInitializationError).not.toHaveBeenCalled();+ host.dispose();+ });++ it.each(['registration', 'init'] as const)(+ 'restores when pagehide interrupts %s without resurrecting the old attempt',+ async (phase) => {+ configureAdapter = (fake) => {+ if (phase === 'registration')+ fake.start.mockImplementationOnce(() => new Promise(() => {}));+ else fake.ignoredKinds.add('init');+ };+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ const affected = vi.fn();+ host.onOpsAffected(affected);+ const read = host.readQuery({ opKey: 7, query: 'query Seven { seven }' });+ const rejected =+ expect(read).rejects.toBeInstanceOf(CacheNavigationError);+ const old = requireAdapter();+ if (phase === 'init')+ await vi.waitFor(() => expect(old.requests).toHaveLength(1));+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ configureAdapter = () => undefined;+ // No intervening microtask: exercise the old startup's catch/finally racing restore.+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await rejected;+ await expect(host.currentRevision()).resolves.toBe(+ INITIAL_CACHE_REVISION+ );+ expect(requireAdapter()).not.toBe(old);+ expect(affected).toHaveBeenCalledWith([7]);+ expect(onInitializationError).not.toHaveBeenCalled();+ expect(adapterFactory).toHaveBeenCalledTimes(2);+ host.dispose();+ }+ );++ it.each([false, true])(+ 'does not resurrect an explicitly disposed host (restore started: %s)',+ async (restoreStarted) => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.currentRevision();+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ if (restoreStarted)+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ host.dispose();+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await expect(host.currentRevision()).rejects.toThrow(+ 'cache worker host was disposed'+ );+ await new Promise((resolve) => setTimeout(resolve, 0));+ expect(adapterFactory).toHaveBeenCalledOnce();+ }+ );++ it('reports a failed restore through normal initialization fallback', async () => {+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ onInitializationError,+ });+ await host.currentRevision();+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ configureAdapter = (fake) => fake.errors.set('init', 'restore failed');+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await expect(host.currentRevision()).rejects.toThrow('restore failed');+ expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ message: 'restore failed' })+ );+ host.dispose();+ });++ it('revalidates reads attempted while suspended instead of counting them as replacement registrations', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ const affected = vi.fn();+ host.onOpsAffected(affected);+ await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ for (const opKey of [7, 9]) {+ await expect(+ host.readQuery({ opKey, query: 'query Value { value }' })+ ).rejects.toBeInstanceOf(CacheNavigationError);+ }+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await host.currentRevision();+ expect(affected).toHaveBeenCalledWith([7, 9]);+ host.dispose();+ });++ it('fences a pre-navigation write waiting to be admitted across immediate restoration', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.currentRevision();+ const stale = host.writeQuery({+ query: 'query Value { value }',+ data: { value: 'stale' },+ });+ const rejected = expect(stale).rejects.toBeInstanceOf(CacheNavigationError);+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await rejected;+ await host.currentRevision();+ expect(requireAdapter().requests.some(({ kind }) => kind === 'write')).toBe(+ false+ );+ host.dispose();+ });++ it('never replays an uncertain enqueue after restoration', async () => {+ const host = createWorkerCacheHost({ scope: 'scope-1' });+ await host.currentRevision();+ const old = requireAdapter();+ old.ignoredKinds.add('enqueue-optimistic-mutation');+ const mutation = host.enqueueOptimisticMutation(+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ const rejected = expect(mutation).rejects.toMatchObject({+ errorCode: 'admitted-enqueue-uncertain',+ });+ await vi.waitFor(() =>+ expect(old.requests.at(-1)?.kind).toBe('enqueue-optimistic-mutation')+ );+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ await rejected;+ await host.currentRevision();+ expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([+ 'init',+ 'current-revision',+ ]);+ host.dispose();+ });+it('treats pagehide enqueue as uncertain without quarantining persistent storage', async () => {configureAdapter = (fake) => {fake.ignoredKinds.add('enqueue-optimistic-mutation');diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex b17ca76297..2c52f40999 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -57,6 +57,7 @@ import {COORDINATOR_CONNECT_TIMEOUT_MS,STARTUP_RESPONSE_GRACE_MS,} from '../worker/startup';+import { CacheNavigationError } from './navigation-error';import { createNoopCacheHost } from './noop-host';import type {CacheChangeOptions,@@ -85,6 +86,7 @@ type HostState =| 'initializing'| 'awaiting-replacement'| 'ready'+ | 'suspended'| 'disposing'| 'failed'| 'disposed';@@ -175,13 +177,13 @@ const isOwnerEpochLoss = (error: unknown): error is CacheResponseError =>error.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {- const pageTelemetry = options.telemetry+ let pageTelemetry = options.telemetry? undefined: createPageCacheTelemetry({rolloutCohort: options.rolloutCohort ?? 'unknown',sink: options.telemetrySink,});- const telemetry = isolateCacheTelemetry(+ let telemetry = isolateCacheTelemetry(options.telemetry ?? pageTelemetry?.recorder);const now = (): number => globalThis.performance?.now() ?? Date.now();@@ -217,10 +219,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {let initializationTimeoutMs =options.initializationTimeoutMs ?? COORDINATOR_CONNECT_TIMEOUT_MS;let registrationInProgress = false;- let cancelRegistration: (() => void) | undefined;+ let cancelRegistration: ((error: Error) => void) | undefined;let nextRequestId = 1;let state: HostState = 'idle';let initialization: Promise<void> | undefined;+ let initializationAttempt = 0;+ let navigationGeneration = 0;+ let suspension: Promise<void> | undefined;let initializationError: Error | undefined;let replacementError: CacheResponseError | undefined;let recoveryInProgress = false;@@ -353,9 +358,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {ownerEpoch: number,openOutcome: EngineOpenOutcome): void {- if (state === 'failed' || state === 'disposing' || state === 'disposed') {+ if (+ state === 'failed' ||+ state === 'suspended' ||+ state === 'disposing' ||+ state === 'disposed'+ )return;- }if (ownerEpoch <= latestReplacementEpoch) return;latestReplacementEpoch = ownerEpoch;// Initial readiness completes the already-running first handshake.@@ -376,9 +385,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {}function observeOwnerEpochLoss(error: CacheResponseError): void {- if (state === 'failed' || state === 'disposing' || state === 'disposed') {+ if (+ state === 'failed' ||+ state === 'suspended' ||+ state === 'disposing' ||+ state === 'disposed'+ )return;- }beginRecoveryGeneration();// A rejected old-epoch read may have registered dependencies before its// response was lost. It belongs to the lost generation, not replacement.@@ -393,13 +406,15 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return;}removeEventListener('pagehide', onPagehide);+ removeEventListener('pageshow', onPageshow);pagehideRegistered = false;}function registerPagehide(): void {if (pagehideRegistered || typeof addEventListener !== 'function') return;pagehideRegistered = true;- addEventListener('pagehide', onPagehide, { once: true });+ addEventListener('pagehide', onPagehide);+ addEventListener('pageshow', onPageshow);}function getAdapter(): CacheCoordinatorPageAdapter {@@ -411,7 +426,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const created = createCacheCoordinatorPageAdapter({scope: options.scope,hotCapacity: options.hotCapacity,- onEngineReplaced,+ onEngineReplaced: (epoch, outcome) => {+ if (adapter === created) onEngineReplaced(epoch, outcome);+ },onStartupProgress: (progress) => {if (adapter !== created) return;initializationTimeoutMs =@@ -425,18 +442,20 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {onTerminalError: (error) => {// start() also rejects; let the bounded registration loop retry before// reporting a terminal failure or quarantining any cache scope.- if (adapter === created && !registrationInProgress)+ if (adapter === created && !registrationInProgress && !suspension)failTransport(error);},telemetry,});- created.onmessage = onMessage;+ created.onmessage = (event) => {+ if (adapter === created && state !== 'suspended') onMessage(event);+ };adapter = created;registerPagehide();return created;}- async function registerAdapter(): Promise<void> {+ async function registerAdapter(initializationId: number): Promise<void> {registrationInProgress = true;try {for (@@ -450,10 +469,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {await Promise.race([current.start(),new Promise<never>((_resolve, reject) => {- cancelRegistration = () =>- reject(- new Error('cache worker host was disposed during startup')- );+ cancelRegistration = reject;timer = setTimeout(() => reject(new Error('cache worker timeout: registration')),options.initializationTimeoutMs ??@@ -461,6 +477,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {);}),]);+ if (initializationId !== initializationAttempt)+ throw new CacheNavigationError();if (state !== 'initializing')throw new Error('cache worker host was disposed during startup');registeredAdapter = current;@@ -470,6 +488,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {await current.dispose({ graceful: false });if (adapter === current) adapter = undefined;if (+ initializationId !== initializationAttempt ||state !== 'initializing' ||attempt + 1 === COORDINATOR_CONNECT_ATTEMPTS)@@ -567,6 +586,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {function failInitialization(error: Error): void {if (state === 'failed' ||+ state === 'suspended' ||state === 'disposing' ||state === 'disposed' ||state === 'ready'@@ -597,7 +617,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {}function failTransport(error: Error): void {- if (terminalFailureHandled) return;+ if (terminalFailureHandled || state === 'suspended') return;const storageWasUntouched = error instanceof CacheBootstrapExhaustedError;stopStorageHealthSampling();const admittedWorkIsUncertain = [...pending.values()].some(@@ -669,7 +689,11 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {}function disposeHost(graceful: boolean, preserveDatabase = false): void {- cancelRegistration?.();+ cancelRegistration?.(+ preserveDatabase+ ? new CacheNavigationError()+ : new Error('cache worker host was disposed during startup')+ );stopStorageHealthSampling();if (state === 'disposed') return;if (state === 'disposing') {@@ -683,10 +707,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {if (preserveDatabase) {disposalMode = 'navigation';clearSubscribers();- rejectPending(- new Error('cache worker host was disposed for page navigation'),- true- );+ rejectPending(new CacheNavigationError(), true);startAdapterDisposal(false, true);return;}@@ -715,10 +736,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {clearSubscribers();if (preserveDatabase) {disposalMode = 'navigation';- rejectPending(- new Error('cache worker host was disposed for page navigation'),- true- );+ rejectPending(new CacheNavigationError(), true);startAdapterDisposal(false, true);return;}@@ -730,8 +748,65 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {startAdapterDisposal(false);}- function onPagehide(): void {- disposeHost(false, true);+ async function finishSuspension(+ startup: Promise<void> | undefined,+ retirement: Promise<void>+ ): Promise<void> {+ // A canceled registration must unwind before a replacement can publish its+ // adapter. Never let the old startup's finally block clear the new one.+ try {+ await startup;+ } catch {+ // Navigation already settled startup callers.+ }+ await retirement;+ }++ function onPagehide(event: PageTransitionEvent): void {+ if (+ !event.persisted ||+ state === 'failed' ||+ state === 'disposing' ||+ state === 'disposed'+ ) {+ disposeHost(false, true);+ return;+ }+ if (state === 'suspended') return;+ state = 'suspended';+ navigationGeneration += 1;+ initializationAttempt += 1;+ beginRecoveryGeneration();+ // All active operations need fresh dependencies after reconnect, including+ // reads that never reached the old engine before the page was frozen.+ for (const key of activeOpKeys) lostRegisteredOpKeys.add(key);+ replacementReadOpKeys.clear();+ cancelRegistration?.(new CacheNavigationError());+ rejectPending(new CacheNavigationError(), true);+ if (adapter) adapter.onmessage = null;+ suspension = finishSuspension(initialization, disposeAdapter(false, true));+ finishTelemetry();+ }++ async function resumeAfterNavigation(): Promise<void> {+ try {+ // Keep the host and all its subscribers alive; only the page transport is+ // replaced. Initialization waits for the suspended startup to unwind.+ await startInitialization();+ } catch {+ // Non-navigation failures already invoke the normal product fallback.+ }+ }++ function onPageshow(event: PageTransitionEvent): void {+ if (!event.persisted || state !== 'suspended') return;+ void resumeAfterNavigation();+ }++ function navigationError(): CacheNavigationError | undefined {+ if (state === 'suspended' || disposalMode === 'navigation') {+ return new CacheNavigationError();+ }}function armRequestTimeout(@@ -759,6 +834,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {initializationError ?? new Error('cache worker initialization failed'));}+ const canceled = navigationError();+ if (canceled) return Promise.reject(canceled);if (state === 'disposing' || state === 'disposed') {return Promise.reject(new Error('cache worker host was disposed'));}@@ -862,18 +939,53 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {scope: options.scope,hotCapacity: options.hotCapacity,});- const ready =- adapter && registeredAdapter === adapter- ? sendInit()- : (async () => {- await registerAdapter();- return await sendInit();- })();+ const attempt = ++initializationAttempt;+ const suspended = suspension;+ const ready = (async () => {+ if (suspended) {+ await suspended;+ if (attempt !== initializationAttempt) throw new CacheNavigationError();+ if (state !== 'initializing')+ throw new Error('cache worker host was disposed');+ suspension = undefined;+ adapter = undefined;+ registeredAdapter = undefined;+ adapterDisposePromise = undefined;+ adapterDisposeWasGraceful = false;+ adapterDisposalStarted = false;+ latestReplacementEpoch = 0;+ initializationTimeoutMs =+ options.initializationTimeoutMs ?? COORDINATOR_CONNECT_TIMEOUT_MS;+ telemetryFinished = false;+ telemetryRelayStarted = false;+ pageTelemetry = options.telemetry+ ? undefined+ : createPageCacheTelemetry({+ rolloutCohort: options.rolloutCohort ?? 'unknown',+ sink: options.telemetrySink,+ });+ telemetry = isolateCacheTelemetry(+ options.telemetry ?? pageTelemetry?.recorder+ );+ }+ if (!adapter || registeredAdapter !== adapter)+ await registerAdapter(attempt);+ if (attempt !== initializationAttempt) throw new CacheNavigationError();+ return await sendInit();+ })();const handshake = ready.then(() => {- if (state !== 'initializing') return;+ if (attempt !== initializationAttempt || state !== 'initializing')+ return;state = 'ready';initialization = undefined;+ if (suspended) {+ // A surviving coordinator need not send engine-replaced to a late+ // joiner. Resets while frozen are unknowable, so conservatively+ // invalidate local checkpoints as well as revision/dependency state.+ for (const cb of generationChangeSubscribers)+ cb({ storage: 'reset' });+ }telemetry?.record({name: 'graphql_cache.host_ready',operationCategory: 'initialization',@@ -895,6 +1007,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},(error: unknown) => {const initializationFailure = asError(error);+ if (attempt !== initializationAttempt) throw initializationFailure;initialization = undefined;if (isOwnerEpochLoss(initializationFailure)) {observeOwnerEpochLoss(initializationFailure);@@ -921,29 +1034,45 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {initializationError ?? new Error('cache worker initialization failed'));}+ const canceled = navigationError();+ if (canceled) return Promise.reject(canceled);if (state === 'disposing' || state === 'disposed') {return Promise.reject(new Error('cache worker host was disposed'));}return startInitialization();}+ async function initializedRequest(+ msg: DistributiveOmit<CacheRequest, 'id'>,+ opKey?: number+ ): Promise<unknown> {+ const generation = navigationGeneration;+ await ensureInitialized();+ // Do not admit an old-page operation to a newly restored transport.+ if (generation !== navigationGeneration) throw new CacheNavigationError();+ return await request(msg, opKey);+ }++ function trackActiveOperation(opKey: number): void {+ activeOpKeys.add(opKey);+ if (state === 'suspended') lostRegisteredOpKeys.add(opKey);+ else if (recoveryInProgress) replacementReadOpKeys.add(opKey);+ }+const opId = (opKey: number) => `${clientId}:${opKey}`;return {clientId,async currentRevision(): Promise<CacheRevision> {- await ensureInitialized();- return (await request({ kind: 'current-revision' })) as CacheRevision;+ return (await initializedRequest({+ kind: 'current-revision',+ })) as CacheRevision;},async readQuery(args: CacheReadArgs): Promise<ReadResult> {- if (args.opKey !== undefined) {- activeOpKeys.add(args.opKey);- if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);- }- await ensureInitialized();- return (await request(+ if (args.opKey !== undefined) trackActiveOperation(args.opKey);+ return (await initializedRequest({kind: 'read',opId: args.opKey === undefined ? undefined : opId(args.opKey),@@ -961,8 +1090,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {args: ReadRecordsByKeysArgs): Promise<ReadRecordsByKeysResult> {const keys = validateRecordSelectionKeys(args.keys);- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'read-records-by-keys',document: args.document,fragmentName: args.fragmentName,@@ -972,8 +1100,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async search(args: SearchCacheArgs): Promise<SearchCachePage> {const requestArgs = validateCacheSearchArgs(args);- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'search',request: requestArgs,})) as SearchCachePage;@@ -982,8 +1109,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async entityFilter(args: EntityFilterCacheArgs): Promise<EntityFilterCacheResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'entity-filter',request: args,})) as EntityFilterCacheResult;@@ -991,11 +1117,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {if (args.registerDependencies && args.opKey !== undefined) {- activeOpKeys.add(args.opKey);- if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);+ trackActiveOperation(args.opKey);}- await ensureInitialized();- return (await request(+ return (await initializedRequest({kind: 'write',originOpId: args.opKey === undefined ? undefined : opId(args.opKey),@@ -1019,8 +1143,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async hydrateQuery(args: Omit<CacheWriteArgs, 'opKey'>): Promise<HydrationResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'hydrate',query: args.query,operationName: args.operationName,@@ -1034,8 +1157,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {args: EnqueueOptimisticMutationArgs,claim: InitialMutationClaimArgs): Promise<EnqueueOptimisticMutationResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'enqueue-optimistic-mutation',originOpId: args.opKey === undefined ? undefined : opId(args.opKey),uuid: args.uuid,@@ -1055,8 +1177,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async inspectQueryVariants(args: InspectQueryVariantsArgs): Promise<CachedQueryVariantWire[]> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'inspect-query-variants',query: args.query,operationName: args.operationName,@@ -1067,8 +1188,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async inspectQuery(args: InspectQueryArgs): Promise<CachedQueryInstanceWire[]> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'inspect-query',query: args.query,operationName: args.operationName,@@ -1082,8 +1202,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {nowMs: number,leaseExpiresAtMs: number): Promise<ClaimedMutation | undefined> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'claim-next-mutation',owner,nowMs,@@ -1097,8 +1216,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {nextAttemptAtMs: number,error: string) {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'defer-optimistic-write',transactionId,leaseOwner: claim.owner,@@ -1113,8 +1231,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {claim: MutationClaim,args: CacheWriteArgs): Promise<CommitOptimisticWriteResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'commit-optimistic-write',transactionId,leaseOwner: claim.owner,@@ -1131,8 +1248,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {claim: MutationClaim,error: string): Promise<RollbackOptimisticWriteResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'rollback-optimistic-write',transactionId,leaseOwner: claim.owner,@@ -1142,16 +1258,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},async invalidate(keys: string[]): Promise<AffectedOperationsResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'invalidate',keys,})) as AffectedOperationsResult;},async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {- await ensureInitialized();- return (await request({+ return (await initializedRequest({kind: 'delete-records',keys,})) as AffectedOperationsResult;@@ -1179,8 +1293,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {},async clear(): Promise<CacheRevision> {- await ensureInitialized();- const revision = (await request({ kind: 'clear' })) as CacheRevision;+ const revision = (await initializedRequest({+ kind: 'clear',+ })) as CacheRevision;telemetry?.record({name: 'graphql_cache.logical_reset',operationCategory: 'lifecycle',diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.tsindex 2c21603da7..de6dee4dba 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts@@ -1,3 +1,6 @@+import { type Client, createClient, gql, stringifyDocument } from '@urql/core';+import { filter, map, pipe } from 'wonka';+import { normalizedCacheExchange } from '../../exchange/normalized-cache-exchange';import type { CacheHost } from '../../host/types';import { createWorkerCacheHost } from '../../host/worker-host';import { clearRegisteredCaches, registerCacheHost } from '../../lifecycle';@@ -33,6 +36,17 @@ let owner: CacheHost | undefined;let standby: CacheHost | undefined;let unregisterOwner: (() => void) | undefined;let hostConstructionCount = 0;+const restoredGenerations: string[] = [];+const affectedOperations: number[][] = [];+let cacheChanges = 0;+let pageRestores = 0;+let watchingNavigation = false;+let mutationRunner: Client | undefined;+let mutationReplays = 0;+const settledMutations: string[] = [];+addEventListener('pageshow', (event: PageTransitionEvent) => {+ if (event.persisted) pageRestores += 1;+});const query = (operationName: string@@ -122,6 +136,108 @@ const api = {async startSingle(): Promise<void> {await startOwner();},+ async watchNavigation(): Promise<void> {+ const host = requireOwner();+ if (!watchingNavigation) {+ watchingNavigation = true;+ host.onCacheGenerationChanged(({ storage }) =>+ restoredGenerations.push(storage)+ );+ host.onOpsAffected((keys) => affectedOperations.push(keys));+ host.onCacheChanged(() => (cacheChanges += 1));+ }+ await host.readQuery({+ opKey: 4242,+ query: query('CacheLifecycleQuery'),+ operationName: 'CacheLifecycleQuery',+ variables: variables(1),+ });+ },+ async queueMutationForRestore(): Promise<string> {+ const host = requireOwner();+ const mutation = gql`+ mutation CacheLifecycleMutation($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) { id displayName }+ }+ `;+ const response = {+ setEntityProperty: { id: 'restored-property', displayName: 'Restored' },+ };+ if (!mutationRunner) {+ const firstClaim = Promise.withResolvers<void>();+ host.onMutationSettled(({ transactionId }) =>+ settledMutations.push(transactionId)+ );+ mutationRunner = createClient({+ url: 'http://cache-lifecycle.test/graphql',+ exchanges: [+ normalizedCacheExchange({+ ...host,+ async claimNextMutation(...args) {+ const claimed = await host.claimNextMutation(...args);+ firstClaim.resolve();+ return claimed;+ },+ }),+ () => (operations) =>+ pipe(+ operations,+ filter((operation) => operation.kind === 'mutation'),+ map((operation) => {+ mutationReplays += 1;+ return {+ operation,+ data: response,+ stale: false,+ hasNext: false,+ };+ })+ ),+ ],+ });+ // Let the initial empty-queue poll finish before inserting runnable work.+ await firstClaim.promise;+ }+ const nowMs = Date.now();+ const owner = 'browser-test-seed';+ const queued = await host.enqueueOptimisticMutation(+ {+ uuid: crypto.randomUUID(),+ query: stringifyDocument(mutation),+ variables: {+ input: {+ entityType: 'DOCUMENT',+ entityId: 'restored-document',+ propertyDefinitionId: 'restored-definition',+ value: { string: 'restored' },+ },+ },+ data: response,+ },+ { owner, nowMs, leaseExpiresAtMs: nowMs + 300_000 }+ );+ if (queued.initialClaim.kind !== 'claimed') {+ throw new Error('expected to claim the browser-test mutation');+ }+ await host.deferOptimisticWrite(+ queued.transactionId,+ { owner, generation: queued.initialClaim.mutation.leaseGeneration },+ nowMs,+ 'runnable on restore'+ );+ return queued.transactionId;+ },+ navigationState() {+ return {+ clientId: requireOwner().clientId,+ restoredGenerations: [...restoredGenerations],+ affectedOperations: [...affectedOperations],+ cacheChanges,+ pageRestores,+ mutationReplays,+ settledMutations: [...settledMutations],+ };+ },async startLogoutHost(): Promise<void> {await startOwner(true);},diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.tsindex a8c8addf11..c148c594f8 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts@@ -36,6 +36,163 @@ const cacheResources = (urls: string[]) => ({],});+test('Cache reconnects in place across persisted page lifecycle events', async ({+ page,+}, testInfo) => {+ const scope = `cache-restore-${crypto.randomUUID()}`;+ await page.goto(+ `${harnessPath(testInfo.project.name)}?treatment=true&scope=${scope}`+ );+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');+ await page.evaluate(async () => {+ await window.cacheLifecycleHarness.startSingle();+ await window.cacheLifecycleHarness.write('before-navigation');+ await window.cacheLifecycleHarness.watchNavigation();+ const editor = document.createElement('textarea');+ editor.id = 'unsaved-editor';+ editor.value = 'unsaved local text';+ document.body.append(editor);+ });+ const original = await page.evaluate(() =>+ window.cacheLifecycleHarness.navigationState()+ );+ for (let cycle = 0; cycle < 2; cycle += 1) {+ const transactionId = await page.evaluate(() =>+ window.cacheLifecycleHarness.queueMutationForRestore()+ );+ const result = await page.evaluate(async () => {+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ let cancellation: string | undefined;+ try {+ await window.cacheLifecycleHarness.write('must-not-write');+ } catch (error) {+ cancellation = (error as Error).name;+ }+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ return { cancellation, read: await window.cacheLifecycleHarness.read() };+ });+ expect(result.cancellation).toBe('CacheNavigationError');+ expect(isHit(result.read)).toBe(true);+ expect(JSON.stringify(result.read)).not.toContain('must-not-write');+ await page.evaluate(+ (cycle) => window.cacheLifecycleHarness.write(`after-restore-${cycle}`),+ cycle+ );+ await expect+ .poll(() =>+ page.evaluate(+ () => window.cacheLifecycleHarness.navigationState().cacheChanges+ )+ )+ .toBeGreaterThan(original.cacheChanges + cycle);+ await expect+ .poll(() =>+ page.evaluate(+ () => window.cacheLifecycleHarness.navigationState().settledMutations+ )+ )+ .toContain(transactionId);+ const restored = await page.evaluate(() =>+ window.cacheLifecycleHarness.navigationState()+ );+ expect(restored.mutationReplays).toBe(cycle + 1);+ expect(restored.clientId).toBe(original.clientId);+ expect(restored.affectedOperations).toContainEqual([4242]);+ expect(restored.restoredGenerations).toContain('reset');+ expect(await page.locator('#unsaved-editor').inputValue()).toBe(+ 'unsaved local text'+ );+ // Re-register like the urql affected-query handler before the next cycle.+ await page.evaluate(() => window.cacheLifecycleHarness.watchNavigation());+ }+ expect(+ await page.evaluate(() =>+ window.cacheLifecycleHarness.hostConstructionCount()+ )+ ).toBe(1);+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());+});++test('Cache preserves editor state and reconnects after a real back-forward-cache restore', async ({+ browser,+ baseURL,+}, testInfo) => {+ test.skip(+ browser.browserType().name() !== 'chromium',+ 'Chromium-specific BFCache launch configuration'+ );+ // Playwright disables BFCache by default. A separate browser enables an+ // actual restore without changing assumptions of the other lifecycle tests.+ const restoringBrowser = await browser.browserType().launch({+ ...testInfo.project.use.launchOptions,+ ignoreDefaultArgs: ['--disable-back-forward-cache'],+ });+ try {+ const page = await restoringBrowser.newPage();+ const path = new URL(harnessPath(testInfo.project.name), baseURL).href;+ const scope = `cache-real-restore-${crypto.randomUUID()}`;+ await page.goto(`${path}?treatment=true&scope=${scope}`);+ await page.evaluate(async () => {+ await window.cacheLifecycleHarness.startSingle();+ await window.cacheLifecycleHarness.write('before-real-navigation');+ await window.cacheLifecycleHarness.watchNavigation();+ const editor = document.createElement('textarea');+ editor.id = 'unsaved-editor';+ editor.value = 'unsaved text across Back';+ document.body.append(editor);+ });+ const before = await page.evaluate(() =>+ window.cacheLifecycleHarness.navigationState()+ );+ const transactionId = await page.evaluate(() =>+ window.cacheLifecycleHarness.queueMutationForRestore()+ );+ await page.goto(`${path}?treatment=false`);+ await page.goBack({ waitUntil: 'commit' });+ expect(await page.locator('#unsaved-editor').inputValue()).toBe(+ 'unsaved text across Back'+ );+ const read = await page.evaluate(() => window.cacheLifecycleHarness.read());+ expect(isHit(read)).toBe(true);+ expect(JSON.stringify(read)).toContain('before-real-navigation');+ const restored = await page.evaluate(() =>+ window.cacheLifecycleHarness.navigationState()+ );+ expect(restored.pageRestores).toBe(1);+ await expect+ .poll(() =>+ page.evaluate(+ () => window.cacheLifecycleHarness.navigationState().settledMutations+ )+ )+ .toContain(transactionId);+ expect(+ await page.evaluate(+ () => window.cacheLifecycleHarness.navigationState().mutationReplays+ )+ ).toBe(1);+ expect(restored.clientId).toBe(before.clientId);+ expect(restored.affectedOperations).toContainEqual([4242]);+ await page.evaluate(() =>+ window.cacheLifecycleHarness.write('after-real-restore')+ );+ expect(+ JSON.stringify(+ await page.evaluate(() => window.cacheLifecycleHarness.read())+ )+ ).toContain('after-real-restore');+ await expect+ .poll(() =>+ page.evaluate(+ () => window.cacheLifecycleHarness.navigationState().cacheChanges+ )+ )+ .toBeGreaterThan(before.cacheChanges);+ } finally {+ await restoringBrowser.close();+ }+});+test('Cache exact host stays navigation-lazy, preserves offline handoff, resets identity, and wipes abrupt loss', async ({context,page,diff --git a/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts b/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.tsindex c6c3b5cde5..e2bbac2217 100644--- a/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts+++ b/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts@@ -90,6 +90,7 @@ describe('GraphQL preview hover reactivity', () => {const host = {clientId: 'preview-test',onOpsAffected: () => () => {},+ onCacheGenerationChanged: () => () => {},claimNextMutation: async () => undefined,readQuery: async () =>cachedData@@ -110,6 +111,7 @@ describe('GraphQL preview hover reactivity', () => {CacheHost,| 'clientId'| 'onOpsAffected'+ | 'onCacheGenerationChanged'| 'claimNextMutation'| 'readQuery'| 'writeQuery'diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.tsindex 977896c113..f11838d467 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts@@ -125,6 +125,57 @@ describe('GraphQL Soup subscription lifecycle', () => {for (const unsubscribe of unsubscribes)expect(unsubscribe).toHaveBeenCalledOnce();});+ it('pauses subscriptions for navigation and reconnects in place exactly once per restore', () => {+ const unsubscribes: Array<ReturnType<typeof vi.fn>> = [];+ const client = {+ query: vi.fn(),+ subscription: vi.fn(() => ({+ subscribe: vi.fn(() => {+ const unsubscribe = vi.fn();+ unsubscribes.push(unsubscribe);+ return { unsubscribe };+ }),+ })),+ };+ const lifecycle = createGraphqlSoupSubscriptionsLifecycle({+ suspendOnPagehide: true,+ });+ lifecycle.replace(client as never, { disabled: false } as never);+ expect(client.subscription).toHaveBeenCalledTimes(3);+ for (let cycle = 0; cycle < 2; cycle += 1) {+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ for (const unsubscribe of unsubscribes)+ expect(unsubscribe).toHaveBeenCalledOnce();+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: false }));+ expect(client.subscription).toHaveBeenCalledTimes((cycle + 1) * 3);+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ expect(client.subscription).toHaveBeenCalledTimes((cycle + 2) * 3);+ }+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ lifecycle.dispose();+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ expect(client.subscription).toHaveBeenCalledTimes(9);+ for (const unsubscribe of unsubscribes)+ expect(unsubscribe).toHaveBeenCalledOnce();+ });++ it('does not attach browser lifecycle behavior to the native client', () => {+ const unsubscribe = vi.fn();+ const client = {+ subscription: vi.fn(() => ({ subscribe: () => ({ unsubscribe }) })),+ };+ const lifecycle = createGraphqlSoupSubscriptionsLifecycle({+ suspendOnPagehide: false,+ });+ lifecycle.replace(client as never);+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));+ expect(client.subscription).toHaveBeenCalledTimes(2);+ expect(unsubscribe).not.toHaveBeenCalled();+ lifecycle.dispose();+ });+it('signals a terminal subscription failure once across both subscriptions', () => {toastFailure.mockClear();const receive: Array<(result: { error?: unknown }) => void> = [];diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.tsindex deb3fc88dd..bf67d2232f 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts@@ -123,7 +123,9 @@ const LIVE_UPDATE_SUBSCRIPTIONS: readonly {] as const;/** Owns the realtime subscriptions served by the Soup GraphQL websocket. */-export function createGraphqlSoupSubscriptionsLifecycle(): {+export function createGraphqlSoupSubscriptionsLifecycle(+ options: { suspendOnPagehide?: boolean } = {}+): {replace(client?: Pick<Client, 'subscription' | 'query'>,host?: CacheHost@@ -131,6 +133,9 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {connected(): void;dispose(): void;} {+ let currentClient: Pick<Client, 'subscription' | 'query'> | undefined;+ let currentHost: CacheHost | undefined;+ let suspended = false;let unsubscribes: Array<() => void> = [];let activity: ReturnType<typeof createActivityUpdatesHandler> | undefined;let channels: ReturnType<typeof createChannelListUpdatesHandler> | undefined;@@ -144,10 +149,28 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {channels = undefined;};- return {- replace(client, host) {+ const onPagehide = () => {+ suspended = true;+ // The graphql-ws client is lazy: removing all subscriptions closes the+ // socket without permanently disposing it, so it can reconnect on restore.+ unsubscribeAll();+ };+ const onPageshow = (event: PageTransitionEvent) => {+ if (!event.persisted || !suspended) return;+ suspended = false;+ lifecycle.replace(currentClient, currentHost);+ };+ if (options.suspendOnPagehide) {+ addEventListener('pagehide', onPagehide);+ addEventListener('pageshow', onPageshow);+ }++ const lifecycle = {+ replace(client?: Pick<Client, 'subscription' | 'query'>, host?: CacheHost) {+ currentClient = client;+ currentHost = host;unsubscribeAll();- if (!client) return;+ if (!client || suspended) return;activity = createActivityUpdatesHandler(client);channels = createChannelListUpdatesHandler(client);const activityHandler = activity;@@ -195,6 +218,15 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {activity?.reconnect();channels?.reconnect();},- dispose: unsubscribeAll,+ dispose() {+ if (options.suspendOnPagehide) {+ removeEventListener('pagehide', onPagehide);+ removeEventListener('pageshow', onPageshow);+ }+ currentClient = undefined;+ currentHost = undefined;+ unsubscribeAll();+ },};+ return lifecycle;}diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.tsindex 58b249f2c6..447a044b9a 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts@@ -645,7 +645,7 @@ describe('GraphQL Soup browser cache session gate', () => {expect(mocks.host.dispose).not.toHaveBeenCalled();});- it.each(['query', 'mutation'] as const)(+ it.each(['query', 'mutation', 'subscription'] as const)('reports handled cache-disposed failures for %s without exporting operation payloads',async (kind) => {const soup = await import('./graphql-soup');@@ -661,10 +661,10 @@ describe('GraphQL Soup browser cache session gate', () => {const report =mocks.normalizedCacheExchange.mock.calls[0]?.[1]?.onCacheError;- report?.(- new Error('cache worker host was disposed for page navigation'),- operation+ const { CacheNavigationError } = await import(+ '@graphql-cache/host/navigation-error');+ report?.(new CacheNavigationError(), operation);expect(mocks.telemetryError).not.toHaveBeenCalled();report?.(error, operation);diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.tsindex dfac98500c..57b69b8b55 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts@@ -12,6 +12,7 @@ import {HYDRATE_ONLY_CONTEXT_KEY,normalizedCacheExchange,} from '@graphql-cache/exchange/normalized-cache-exchange';+import { CacheNavigationError } from '@graphql-cache/host/navigation-error';import type { CacheHost } from '@graphql-cache/host/types';import {createTauriCacheHost,@@ -321,7 +322,9 @@ function disposeUncachedRealtimeClient(): void {function getUncachedRealtimeClient(): Client {if (uncachedRealtimeClient) return uncachedRealtimeClient;- const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();+ const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle({+ suspendOnPagehide: !isTauri(),+ });const websocketClient = createGraphqlSoupWebSocketClient(subscriptionsLifecycle.connected);@@ -414,11 +417,7 @@ export function getGraphqlSoupClient(): Client {try {// Navigation deliberately rejects outstanding reads. Do not turn that// expected shutdown into an error; unexpected disposal still reports.- if (- error instanceof Error &&- error.message === 'cache worker host was disposed for page navigation'- )- return;+ if (error instanceof CacheNavigationError) return;// Caught cache failures never reach window.unhandledrejection. Report// them through the Datadog-bound exporter without query/variable data.Telemetry.error(error, {@@ -434,7 +433,9 @@ export function getGraphqlSoupClient(): Client {let host: CacheHost | undefined;let websocketClient: GraphqlWsClient | undefined;let unregisterHost: () => void = () => undefined;- const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();+ const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle({+ suspendOnPagehide: !native,+ });const cleanup = () => {unregisterHost();// Unsubscribing emits urql teardown operations; keep the cache hostdiff --git a/docs/AGENT_GUIDE/navigation.md b/docs/AGENT_GUIDE/navigation.mdindex feef34c4ba..2eb85c8f8d 100644--- a/docs/AGENT_GUIDE/navigation.md+++ b/docs/AGENT_GUIDE/navigation.md@@ -1,5 +1,16 @@# Navigation and App Structure+## Returning from another page++A browser back/forward-cache restore reconnects the GraphQL cache worker and+live subscriptions in place; it must not reload the app or discard in-memory+editor state. For lifecycle verification, navigate to another document and Back,+confirm `pageshow.persisted` is true (otherwise this was a fresh load), then check+that cached reads, live updates, and the existing editor still work. Runnable+queued mutations should resume promptly, without waiting for the old poll or+local retry timer; durable leases and server-retry deadlines still apply.+Switching tabs or navigating an in-app route is not a back/forward-cache restore.+## Direct URLs (all under the frontend origin)| Route | Surface |