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 parking (#8825)
Sean Ayec01b3b0a65b3
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.mdindex 5e02068239..fa5269bca7 100644--- a/apps/web/AGENTS.md+++ b/apps/web/AGENTS.md@@ -164,6 +164,15 @@ ownership. Cancel, logout, and the ten-minute timeout retire pending callbacks.- Treat a repeated worker-ready frame as a coordinator restart: retire the oldengine and re-register in place, preserving durable storage and never replayinguncertain enqueues. See `docs/graphql-normalized-cache-plan.md`.+- Reject already-routed optimistic enqueues with missing replies as uncertain on+ every owner departure; never forward them through network fallback, because+ their durable queue entries may survive the old engine.+- Drain browser cache engines when their last visible consumer hides, then park+ without retiring clients; queue background work until a visible owner reopens+ storage, retaining accepted mutation settlements even if their caller leaves.+ Publish recovery reset outcomes before parking while retaining the read pause.+ Bound foreground resume reads to one second without killing an owner, stealing+ its lock, replaying writes, or treating intentional parking as a failure.- Mobile dock customization shares the navigation island’s measured capacity; persist ordering per user with `mobile-dock-order.ts`, preserve gated destinations, and keep Search and More fixed. Reorder handles drag without a hold delay; the rest of each row scrolls.- Share sidebar and mobile dock unread presence through `components/app/use-navigation-unread.ts`; keep badges reactive to read/done changes, guard all query data with `queryReadyGate` so pending preferences or paused queries cannot suspend the shell, and avoid fetching extra pages for counts.- Name Home thread rows from their latest scoped notification, including document mentions and reactions; use the thread author only when no notification exists. Document rows whose newest outstanding notification is a comment, and calendar event rows whose newest is a join request, say who did it (`row-notification.ts`).diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.mdindex d9d66fc452..774140ae5b 100644--- a/apps/web/docs/graphql-normalized-cache-plan.md+++ b/apps/web/docs/graphql-normalized-cache-plan.md@@ -209,7 +209,63 @@ SharedWorker still runs. The coordinator probes the physical owner Web Lockwithout waiting or stealing it; a held lock (or a failed probe) retries theheartbeat without changing epochs or touching storage. A released lock confirmssilent worker termination and triggers the usual fenced recovery. Read deadlines-still bound callers waiting on an unresponsive engine.+still bound callers waiting on an unresponsive engine outside a visibility handoff.++Protocol v10 reports tab visibility and epoch-fenced read states: `ready`,+`waiting`, and `blocked`. A visible owner stays put even if another visible window+gets focus. When its page hides, stop routing new work into that engine and ask it+to drain immediately, without waiting for another visible consumer. An engine+already loading/opening first finishes startup before draining. The runtime waits+for admitted work and closes OPFS before acknowledging. Only then may another+eligible visible page acquire the owner lock and open the existing database.+Clients and their subscribers stay connected; an explicit page disposal can join+the same drain and retire that page normally.++If no eligible tab is visible, the coordinator enters `parked` with no engine.+Background cache work queues until a visible page resumes ownership; it never+starts a replacement in a hidden tab. A first-ever hidden registration also parks+without touching storage. If an in-progress startup becomes all-hidden, pause its+phase watchdog rather than misclassifying browser suspension as failure; resume+the phase budget when a visible consumer returns. Parking retains the required+open/reset action: it does not erase a reset requirement established by a real+failure. Storage identity and version are unchanged. A ready recovery epoch+publishes its storage outcome before immediately draining or parking, so hosts+invalidate reset data/leases even if the next owner only opens existing storage.+Reset completion accounting likewise follows accepted readiness, not whether+that epoch remains active; its read pause stays in force during the drain.++While parked or transitioning, `waiting` pauses read/init deadlines without+creating a second page-side request queue. Reads, writes, and teardown retain+coordinator admission order. A visible consumer starts a one-second read budget+covering drain/startup/resume; changes of candidate do not extend it. If everyone+hides again, cancel that budget. On expiry, `blocked` allows ordinary query network+fallback (`cache-only` still never forwards) without repeatedly paying ten seconds.+Only read callers are canceled, not admitted engine work or writes. Readiness+restores deadlines and refreshes dependency registrations with preserved-storage+semantics, including when startup finishes on its original owner.++Already-sent HTTP mutations may finish while parked. Their local commit, rollback,+or defer requests wait for storage and retain their position ahead of later+claims. Accepted settlement requests survive their caller disconnecting; their+orphaned replies are dropped, not their known outcomes. This queue is still+coordinator memory, not durable storage: loss before acceptance or loss of all+contexts/coordinator still needs the existing uncertain-outcome and server-side+idempotency protections. Parking never reports an unpersisted enqueue as durable.++The read budget never kills an owner, steals a lock, wipes storage, or replays a+write. If a drain itself stalls, writes wait until it can finish or existing+failure/navigation recovery applies. Owner telemetry adds `park-started`, `parked`,+`unpark-started`, and `unpark-completed` alongside the `visibility-handoff-*` events.+The backend-free `parking.browser.e2e.ts` exercises physical release, retained+clients/storage, and a response settled after parking.++Every departure rejects already-routed optimistic enqueues whose replies were+lost as `admitted-enqueue-uncertain`, including requests from surviving tabs.+An engine epoch fence does not undo a committed queue entry, and a planned+recovery wipe has not erased it yet. The exchange must neither retry those+enqueues nor forward them directly to the API. Requests queued at the coordinator+but not yet routed remain eligible for one dispatch to the replacement engine;+late old-epoch responses cannot settle the rejected requests.Safari can recreate the SharedWorker global while retaining a page's MessagePort,including when another tab closes. A second Effect ready frame is a transportdiff --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 56ae1eb475..b18a34665e 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@@ -31,8 +31,8 @@* through the standard write path so dependent cached queries update.** Cache failures normally degrade to the network. An admitted optimistic- * enqueue with an unfenced transport outcome emits an error instead, because- * forwarding could duplicate a side effect already durable in the old scope.+ * enqueue with an unknown durable outcome emits an error instead, because+ * forwarding could duplicate a side effect already in the persistent queue.*/import { fireAndForget } from '@core/util/fireAndForget';@@ -1096,8 +1096,8 @@ export function normalizedCacheExchange(if (isAdmittedEnqueueUncertainError(error)) {enqueueTelemetry.failed('uncertain');options.onCacheError?.(error, op);- // The old-scope queue may already contain the side effect. It is- // unsafe to forward or retry without a coordinator fence.+ // Fencing the old engine does not remove a committed queue entry.+ // Never forward or retry an enqueue whose reply was lost.return uncertainEnqueueResult(op, error);}// Another context holds the database, so the enqueue never reacheddiff --git a/apps/web/src/lib/graphql-cache/host/read-availability.test.ts b/apps/web/src/lib/graphql-cache/host/read-availability.test.tsnew file mode 100644index 0000000000..0f193aad47--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/read-availability.test.ts@@ -0,0 +1,33 @@+import { expect, it } from 'vitest';+import { CacheReadAvailability } from './read-availability';++it('interrupts a read waiting for initialization without interrupting a write or replaying either', async () => {+ const availability = new CacheReadAvailability();+ const initialized = Promise.withResolvers<void>();+ const read = availability.waitUntilReady(() => initialized.promise, true);+ const rejected = expect(read).rejects.toThrow('handoff');+ const write = availability.waitUntilReady(() => initialized.promise, false);+ availability.block(new Error('handoff'));+ await rejected;+ await expect(+ availability.waitUntilReady(() => initialized.promise, true)+ ).rejects.toThrow('handoff');+ availability.resume();+ initialized.resolve();+ await write;+ await availability.waitUntilReady(() => initialized.promise, true);+});++it('preserves read/write startup continuation order', async () => {+ const availability = new CacheReadAvailability();+ const initialized = Promise.withResolvers<void>();+ const order: boolean[] = [];+ const wait = async (readOnly: boolean) => {+ await availability.waitUntilReady(() => initialized.promise, readOnly);+ order.push(readOnly);+ };+ const pending = [wait(true), wait(false), wait(true), wait(false)];+ initialized.resolve();+ await Promise.all(pending);+ expect(order).toEqual([true, false, true, false]);+});diff --git a/apps/web/src/lib/graphql-cache/host/read-availability.ts b/apps/web/src/lib/graphql-cache/host/read-availability.tsnew file mode 100644index 0000000000..37f072b67b--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/read-availability.ts@@ -0,0 +1,69 @@+import type { CacheRequest } from '../protocol';++/** Only RPCs that cannot durably change storage may time out or bypass a handoff. */+export function isReadOnlyCacheRequest(kind: CacheRequest['kind']): boolean {+ return (+ kind === 'current-revision' ||+ kind === 'current-storage-generation' ||+ kind === 'read' ||+ kind === 'read-records-by-keys' ||+ kind === 'search' ||+ kind === 'entity-filter' ||+ kind === 'calendar-range' ||+ kind === 'inspect-mutations' ||+ kind === 'inspect-query' ||+ kind === 'inspect-query-variants'+ );+}++/** Interrupts read-only startup waits without canceling initialization or writes. */+export class CacheReadAvailability {+ private unavailable: Error | undefined;+ private paused = false;+ private readonly waiting = new Set<(error: Error) => void>();++ get error(): Error | undefined {+ return this.unavailable;+ }++ get timeoutsPaused(): boolean {+ return this.paused;+ }++ wait(): void {+ this.paused = true;+ this.unavailable = undefined;+ }++ block(error: Error): void {+ this.paused = true;+ this.unavailable = error;+ for (const reject of this.waiting) reject(error);+ this.waiting.clear();+ }++ resume(): void {+ this.paused = false;+ this.unavailable = undefined;+ }++ async waitUntilReady(+ initialize: () => Promise<void>,+ readOnly: boolean+ ): Promise<void> {+ if (readOnly && this.unavailable) throw this.unavailable;+ let rejectRead: ((error: Error) => void) | undefined;+ const blocked = new Promise<never>((_resolve, reject) => {+ rejectRead = reject;+ if (readOnly) this.waiting.add(reject);+ });+ try {+ // Both read and write startup waits take the same microtask path so+ // making reads interruptible cannot reorder admission ahead of writes.+ await Promise.race([initialize(), blocked]);+ if (readOnly && this.unavailable) throw this.unavailable;+ } finally {+ if (rejectRead) this.waiting.delete(rejectRead);+ }+ }+}diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration-helpers.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration-helpers.tsnew file mode 100644index 0000000000..8be800fb58--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration-helpers.ts@@ -0,0 +1,102 @@+import {+ type Client,+ makeOperation,+ type Operation,+ type OperationResult,+} from '@urql/core';+import { vi } from 'vitest';+import { makeSubject, pipe, type Source, subscribe } from 'wonka';+import { normalizedCacheExchange } from '../exchange/normalized-cache-exchange';+import type { OptimisticLinkPatchWire } from '../protocol';+import type { CacheHost } from './types';++export function exchangeHarness(+ host: CacheHost,+ operation: Operation,+ onResult?: (result: OperationResult) => void,+ onForward?: () => void+) {+ const operations = makeSubject<Operation>();+ const network = makeSubject<OperationResult>();+ const forwarded: Operation[] = [];+ const results: OperationResult[] = [];+ const client = { reexecuteOperation: vi.fn() } as unknown as Client;+ const forward = (source: Source<Operation>): Source<OperationResult> => {+ pipe(+ source,+ subscribe((forwardedOperation) => {+ forwarded.push(forwardedOperation);+ onForward?.();+ })+ );+ return network.source;+ };+ pipe(+ normalizedCacheExchange(host)({+ forward,+ client,+ dispatchDebug: () => undefined,+ })(operations.source),+ subscribe((result) => {+ results.push(result);+ onResult?.(result);+ })+ );+ operations.next(operation);+ return { forwarded, results };+}++export function optimisticMutation(+ key: number,+ query: Operation['query'],+ linkPatches?: OptimisticLinkPatchWire[]+): Operation {+ return makeOperation('mutation', { key, query, variables: {} }, {+ requestPolicy: 'cache-first',+ url: 'http://integration.test',+ suspense: false,+ normalizedCacheOptimistic: {+ uuid: '00000000-0000-4000-8000-000000000001',+ optimisticResponse: { held: true },+ linkPatches,+ },+ } as never);+}++export class LinkedMessagePort extends EventTarget {+ peer: LinkedMessagePort | undefined;+ onmessage: ((event: MessageEvent<unknown>) => void) | null = null;+ onmessageerror: (() => void) | null = null;+ closed = false;++ postMessage(+ message: unknown,+ transfer: Transferable[] | StructuredSerializeOptions = []+ ): void {+ const peer = this.peer;+ if (this.closed || !peer || peer.closed) return;+ const ports = (+ Array.isArray(transfer) ? transfer : (transfer.transfer ?? [])+ ) as MessagePort[];+ queueMicrotask(() => {+ if (peer.closed) return;+ peer.onmessage?.({ data: message, ports } as unknown as MessageEvent);+ peer.dispatchEvent(new MessageEvent('message', { data: message, ports }));+ });+ }++ start(): void {}+ close(): void {+ this.closed = true;+ }+}++export class LinkedMessageChannel {+ readonly port1 = new LinkedMessagePort();+ readonly port2 = new LinkedMessagePort();++ constructor() {+ this.port1.peer = this.port2;+ this.port2.peer = this.port1;+ }+}diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.tsindex 51b4dc14e0..fa5908e51f 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts@@ -1,20 +1,18 @@-import {- type Client,- gql,- makeOperation,- type Operation,- type OperationResult,-} from '@urql/core';+import { gql, type OperationResult } from '@urql/core';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';-import { makeSubject, pipe, type Source, subscribe } from 'wonka';-import { normalizedCacheExchange } from '../exchange/normalized-cache-exchange';import type { CacheRequest, CacheResponse } from '../protocol';import { installCacheCoordinatorWorker } from '../worker/cache-coordinator-runtime';import { installCacheEngineWorker } from '../worker/cache-engine-runtime';+import { createCacheCoordinatorPageAdapter } from '../worker/coordinator-page-adapter';import { CoordinatorRouter } from '../worker/coordinator-router';import { EFFECT_WORKER_CLOSE_FRAME } from '../worker/effect-worker-transport';-import type { CacheHost } from './types';import { createWorkerCacheHost } from './worker-host';+import {+ exchangeHarness,+ LinkedMessageChannel,+ LinkedMessagePort,+ optimisticMutation,+} from './worker-host.integration-helpers';const PAGEHIDE_MUTATION = gql`mutation HoldPagehide {@@ -37,92 +35,6 @@ const RETIREMENT_FAILURE_MUTATION = gql`}`;-function exchangeHarness(- host: CacheHost,- operation: Operation,- onResult?: (result: OperationResult) => void-) {- const operations = makeSubject<Operation>();- const network = makeSubject<OperationResult>();- const forwarded: Operation[] = [];- const results: OperationResult[] = [];- const client = { reexecuteOperation: vi.fn() } as unknown as Client;- const forward = (source: Source<Operation>): Source<OperationResult> => {- pipe(- source,- subscribe((forwardedOperation) => forwarded.push(forwardedOperation))- );- return network.source;- };- pipe(- normalizedCacheExchange(host)({- forward,- client,- dispatchDebug: () => undefined,- })(operations.source),- subscribe((result) => {- results.push(result);- onResult?.(result);- })- );- operations.next(operation);- return { forwarded, results };-}--function optimisticMutation(key: number, query: Operation['query']): Operation {- return makeOperation('mutation', { key, query, variables: {} }, {- requestPolicy: 'cache-first',- url: 'http://integration.test',- suspense: false,- normalizedCacheOptimistic: {- uuid: '00000000-0000-4000-8000-000000000001',- optimisticResponse: { held: true },- },- } as never);-}--class LinkedMessagePort extends EventTarget {- peer: LinkedMessagePort | undefined;- onmessage: ((event: MessageEvent<unknown>) => void) | null = null;- onmessageerror: (() => void) | null = null;- closed = false;-- postMessage(- message: unknown,- transfer: Transferable[] | StructuredSerializeOptions = []- ): void {- const peer = this.peer;- if (this.closed || !peer || peer.closed) return;- const ports = (- Array.isArray(transfer) ? transfer : (transfer.transfer ?? [])- ) as MessagePort[];- queueMicrotask(() => {- if (peer.closed) return;- peer.onmessage?.({- data: message,- ports,- } as unknown as MessageEvent);- peer.dispatchEvent(new MessageEvent('message', { data: message, ports }));- });- }-- start(): void {}-- close(): void {- this.closed = true;- }-}--class LinkedMessageChannel {- readonly port1 = new LinkedMessagePort();- readonly port2 = new LinkedMessagePort();-- constructor() {- this.port1.peer = this.port2;- this.port2.peer = this.port1;- }-}-type RuntimeLog = {epoch: number;kind: CacheRequest['kind'] | 'drain';@@ -131,6 +43,8 @@ type RuntimeLog = {};const requestObservers = new Set<(entry: RuntimeLog) => void>();+// Fake durable storage shared by successive engine instances.+const committedEnqueues: string[] = [];type Deferred = { promise: Promise<void>; resolve: () => void };const deferred = (): Deferred => {@@ -179,6 +93,7 @@ class IntegrationCore {return;}if (request.kind === 'enqueue-optimistic-mutation') {+ committedEnqueues.push(request.uuid);const gate = this.enqueueGates.get(request.operationName ?? '');if (gate) await gate;}@@ -315,6 +230,7 @@ describe('worker CacheHost coordinator integration', () => {hostInitGates.clear();enqueueGates.clear();requestObservers.clear();+ committedEnqueues.length = 0;router = new CoordinatorRouter({verifyTabLockHeld: async () => true,watchTabLock: () => () => undefined,@@ -805,6 +721,179 @@ describe('worker CacheHost coordinator integration', () => {);});+ it.each([false, true])(+ 'never forwards a committed standby enqueue after owner navigation (link patches: %s)',+ async (withLinkPatches) => {+ // Only the owner navigates; the standby's page/host remains alive.+ const owner = createCacheCoordinatorPageAdapter({+ scope: 'integration-scope',+ });+ await owner.start();+ const admitted = Promise.withResolvers<void>();+ requestObservers.add((entry) => {+ if (entry.kind === 'enqueue-optimistic-mutation') admitted.resolve();+ });+ const gate = deferred();+ enqueueGates.set('HoldStandby', gate.promise);+ const standby = createWorkerCacheHost({ scope: 'integration-scope' });+ const recovered = Promise.withResolvers<unknown>();+ standby.onCacheGenerationChanged(recovered.resolve);+ const completed = Promise.withResolvers<OperationResult | 'forwarded'>();+ const { forwarded, results } = exchangeHarness(+ standby,+ optimisticMutation(+ 105,+ STANDBY_MUTATION,+ withLinkPatches+ ? [+ {+ query: 'query Items { items { id } }',+ variablesJson: '{}',+ path: [{ field: 'items' }],+ operation: { kind: 'remove', entityKey: 'Item:1' },+ },+ ]+ : []+ ),+ completed.resolve,+ () => completed.resolve('forwarded')+ );+ try {+ await admitted.promise;+ expect(committedEnqueues).toEqual([+ '00000000-0000-4000-8000-000000000001',+ ]);+ await owner.dispose({ graceful: false, preserveDatabase: true });+ expect(await completed.promise).toMatchObject({+ error: { networkError: { errorCode: 'admitted-enqueue-uncertain' } },+ });+ expect(await recovered.promise).toEqual({ storage: 'preserved' });+ await expect(+ standby.readQuery({ query: 'query After { after }' })+ ).resolves.toEqual({ kind: 'miss' });+ gate.resolve();+ expect(dedicatedWorkers.map(({ epoch }) => epoch)).toEqual([1, 2]);+ expect(dedicatedWorkers[0]?.terminated).toBe(true);+ expect(forwarded).toHaveLength(0);+ expect(results).toHaveLength(1);+ expect(committedEnqueues).toEqual([+ '00000000-0000-4000-8000-000000000001',+ ]);+ expect(+ logs.filter(({ kind }) => kind === 'enqueue-optimistic-mutation')+ ).toHaveLength(1);+ } finally {+ gate.resolve();+ standby.dispose();+ await owner.dispose({ graceful: false, preserveDatabase: true });+ }+ }+ );++ it('bounds reads for existing and joining clients without terminating a blocked owner or replaying writes', async () => {+ class Visibility extends EventTarget {+ visibilityState: DocumentVisibilityState = 'visible';+ }+ const visibility = new Visibility();+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');+ const blocked = Promise.withResolvers<void>();+ router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => undefined,+ handoffReadTimeoutMs: 0,+ telemetry: {+ record: (event) => {+ if (event.ownerEvent === 'visibility-handoff-blocked')+ blocked.resolve();+ },+ flush() {},+ },+ });+ const owner = createCacheCoordinatorPageAdapter({+ scope: 'integration-scope',+ visibility,+ });+ await owner.start();+ const standby = createWorkerCacheHost({ scope: 'integration-scope' });+ await standby.readQuery({ opKey: 7, query: 'query Warm { warm }' });+ const recovered = Promise.withResolvers<unknown>();+ const affected = Promise.withResolvers<number[]>();+ standby.onCacheGenerationChanged(recovered.resolve);+ standby.onOpsAffected(affected.resolve);+ const admitted = Promise.withResolvers<void>();+ requestObservers.add((entry) => {+ if (entry.kind === 'enqueue-optimistic-mutation') admitted.resolve();+ });+ const gate = deferred();+ enqueueGates.set('HoldStandby', gate.promise);+ const completed = Promise.withResolvers<OperationResult>();+ const { forwarded } = exchangeHarness(+ standby,+ optimisticMutation(106, STANDBY_MUTATION),+ completed.resolve+ );+ await admitted.promise;+ visibility.visibilityState = 'hidden';+ visibility.dispatchEvent(new Event('visibilitychange'));+ await blocked.promise;+ await expect(+ standby.readQuery({ opKey: 9, query: 'query Blocked { blocked }' })+ ).rejects.toThrow('owner handoff timeout');+ const write = standby.writeQuery({+ query: 'query Write { write }',+ data: { write: true },+ });+ const onInitializationError = vi.fn();+ const late = createWorkerCacheHost({+ scope: 'integration-scope',+ onInitializationError,+ });+ const lateAffected = Promise.withResolvers<number[]>();+ late.onOpsAffected(lateAffected.resolve);+ try {+ await expect(+ late.readQuery({ opKey: 11, query: 'query Late { late }' })+ ).rejects.toThrow('owner handoff timeout');+ expect(onInitializationError).not.toHaveBeenCalled();+ expect(dedicatedWorkers).toHaveLength(1);+ expect(dedicatedWorkers[0]?.terminated).toBe(false);+ expect(router.snapshot()?.state.kind).toBe('draining');+ expect(logs.filter(({ kind }) => kind === 'write')).toEqual([]);+ expect(forwarded).toHaveLength(0);+ gate.resolve();+ expect((await completed.promise).error).toBeUndefined();+ expect(await recovered.promise).toEqual({ storage: 'preserved' });+ expect(await affected.promise).toEqual([7, 9]);+ await write;+ expect(await lateAffected.promise).toEqual([11]);+ await expect(+ late.readQuery({ query: 'query Recovered { recovered }' })+ ).resolves.toEqual({ kind: 'miss' });+ const ownerRead = Promise.withResolvers<unknown>();+ owner.onmessage = ({ data }) => {+ if ('id' in data && data.id === 55) ownerRead.resolve(data);+ };+ owner.postMessage({ id: 55, kind: 'current-revision' });+ expect(await ownerRead.promise).toMatchObject({ ok: true });+ expect(sharedWorkers[0]?.port.closed).toBe(false);+ expect(dedicatedWorkers.map(({ epoch }) => epoch)).toEqual([1, 2]);+ expect(dedicatedWorkers[0]?.terminated).toBe(true);+ expect(logs.filter(({ kind }) => kind === 'write')).toMatchObject([+ { epoch: 2 },+ ]);+ expect(+ logs.filter(({ kind }) => kind === 'enqueue-optimistic-mutation')+ ).toHaveLength(1);+ expect(onInitializationError).not.toHaveBeenCalled();+ expect(forwarded).toHaveLength(0);+ } finally {+ gate.resolve();+ standby.dispose();+ late.dispose();+ await owner.dispose({ graceful: false, preserveDatabase: true });+ }+ });+it('keeps a standby connected until its admitted enqueue response settles', async () => {const owner = createWorkerCacheHost({ scope: 'integration-scope' });await owner.readQuery({ query: 'query OwnerWarm { ownerWarm }' });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 f780fbbc9c..d320b1c71f 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@@ -746,6 +746,116 @@ describe('createWorkerCacheHost', () => {});+ it.each([false, true])(+ 'pauses initialization during a blocked handoff without failing writes (replacement: %s)',+ async (replacement) => {+ vi.useFakeTimers();+ configureAdapter = (fake) => fake.ignoredKinds.add('init');+ localStorage.setItem('graphql-cache:scope', 'scope-1');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ initializationTimeoutMs: 10,+ onInitializationError,+ });+ const read = host.readQuery({ opKey: 7, query: 'query Read { user }' });+ const rejected = expect(read).rejects.toThrow('owner handoff timeout');+ const mutation = host.enqueueOptimisticMutation(+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }+ );+ await vi.advanceTimersByTimeAsync(0);+ const adapter = requireAdapter();+ adapter.options.onCacheReadAvailabilityChanged?.('blocked');+ await rejected;+ await vi.advanceTimersByTimeAsync(60_001);+ expect(adapter.requests.map(({ kind }) => kind)).toEqual(['init']);+ expect(onInitializationError).not.toHaveBeenCalled();+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');+ if (replacement) adapter.replace(2);+ else adapter.options.onCacheReadAvailabilityChanged?.('ready');+ adapter.respond(1, null);+ await mutation;+ expect(adapter.requests.map(({ kind }) => kind)).toEqual([+ 'init',+ 'enqueue-optimistic-mutation',+ ]);+ await expect(+ host.readQuery({ query: 'query Recovered { user }' })+ ).resolves.toEqual({ kind: 'miss' });+ host.dispose();+ }+ );++ it('queues parked reads, writes, and teardown in call order without background timeouts', async () => {+ vi.useFakeTimers();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ requestTimeoutMs: 10,+ });+ await host.currentRevision();+ const adapter = requireAdapter();+ adapter.ignoredKinds.add('read');+ adapter.ignoredKinds.add('write');+ adapter.ignoredKinds.add('teardown');+ adapter.options.onCacheReadAvailabilityChanged?.('waiting');+ const read = host.readQuery({ opKey: 7, query: 'query Parked { user }' });+ const write = host.writeQuery({+ query: 'query Parked { user }',+ data: { user: true },+ });+ const teardown = host.teardown(7);+ await vi.advanceTimersByTimeAsync(300_001);+ const queued = adapter.requests.filter((request) =>+ ['read', 'write', 'teardown'].includes(request.kind)+ );+ expect(queued.map((request) => request.kind)).toEqual([+ 'read',+ 'write',+ 'teardown',+ ]);+ adapter.options.onCacheReadAvailabilityChanged?.('ready');+ for (const request of queued)+ adapter.respond(request.id, responseFor(request));+ await Promise.all([read, write, teardown]);+ host.dispose();+ });++ it('keeps an initially parked host initializing without failing reads or writes', async () => {+ vi.useFakeTimers();+ configureAdapter = (fake) => fake.ignoredKinds.add('init');+ const onInitializationError = vi.fn();+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ initializationTimeoutMs: 10,+ onInitializationError,+ });+ const read = host.readQuery({ query: 'query Initial { user }' });+ const write = host.writeQuery({+ query: 'query Initial { user }',+ data: { user: true },+ });+ await vi.advanceTimersByTimeAsync(0);+ const adapter = requireAdapter();+ adapter.options.onCacheReadAvailabilityChanged?.('waiting');+ await vi.advanceTimersByTimeAsync(300_001);+ expect(adapter.requests.map((request) => request.kind)).toEqual(['init']);+ expect(onInitializationError).not.toHaveBeenCalled();+ adapter.options.onCacheReadAvailabilityChanged?.('ready');+ adapter.respond(1, null);+ await Promise.all([read, write]);+ expect(adapter.requests.map((request) => request.kind)).toEqual([+ 'init',+ 'read',+ 'write',+ ]);+ host.dispose();+ });+it('bounds hung registration/init before admitting reads or mutations', async () => {vi.useFakeTimers();configureAdapter = (fake) => fake.ignoredKinds.add('init');diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 301eb8fc4c..f8832f0793 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -7,6 +7,7 @@ import type { MutationInspection } from '../protocol';*/import { fireAndForget } from '@core/util/fireAndForget';+import { match } from 'ts-pattern';import { deleteLegacyNormalizedCacheIdb } from '../legacy-idb-cleanup';import {ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,@@ -71,6 +72,10 @@ import {} from '../worker/startup';import { CacheNavigationError } from './navigation-error';import { createNoopCacheHost } from './noop-host';+import {+ CacheReadAvailability,+ isReadOnlyCacheRequest,+} from './read-availability';import type {AffectedOperationsListener,CacheChangeListener,@@ -228,6 +233,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const clientId = crypto.randomUUID();const pending = new Map<number, Pending>();+ const readAvailability = new CacheReadAvailability();const activeOpKeys = new Set<number>();const registeredOpKeys = new Set<number>();const lostRegisteredOpKeys = new Set<number>();@@ -418,6 +424,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return;if (ownerEpoch <= latestReplacementEpoch) return;latestReplacementEpoch = ownerEpoch;+ resumeCacheReads();// Initial readiness completes the already-running first handshake.if (state === 'initializing' && !recoveryInProgress) return;const change: CacheGenerationChange = {@@ -435,6 +442,61 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {void startInitialization().catch(() => undefined);}+ function resumeCacheReads(): void {+ if (state === 'failed' || state === 'suspended' || state === 'disposed')+ return;+ readAvailability.resume();+ for (const [id, entry] of pending) {+ if (entry.kind === 'init')+ armRequestTimeout(id, entry, initializationTimeoutMs);+ else if (isReadOnlyCacheRequest(entry.kind))+ armRequestTimeout(id, entry, requestTimeoutMs);+ }+ }++ function waitForCacheReads(): void {+ if (state === 'failed' || state === 'suspended' || state === 'disposed')+ return;+ readAvailability.wait();+ // Keep read/write/teardown admission ordered at the coordinator. Pausing+ // their deadlines must not create a separate page-side read queue.+ for (const entry of pending.values()) {+ if (+ (entry.kind === 'init' || isReadOnlyCacheRequest(entry.kind)) &&+ entry.timer !== undefined+ ) {+ clearTimeout(entry.timer);+ entry.timer = undefined;+ }+ }+ }++ function onOwnerHandoffBlocked(): void {+ if (state === 'failed' || state === 'suspended' || state === 'disposed')+ return;+ const error = new Error(+ 'cache reads unavailable after owner handoff timeout'+ );+ beginRecoveryGeneration();+ for (const key of activeOpKeys) lostRegisteredOpKeys.add(key);+ replacementReadOpKeys.clear();+ readAvailability.block(error);+ // Cancel only the callers, not initialization or admitted worker fibers.+ // Writes remain queued until the engine has safely drained and reopened.+ for (const [id, entry] of pending) {+ if (entry.kind === 'init' && entry.timer !== undefined) {+ clearTimeout(entry.timer);+ entry.timer = undefined;+ }+ if (!isReadOnlyCacheRequest(entry.kind)) continue;+ pending.delete(id);+ if (entry.timer !== undefined) clearTimeout(entry.timer);+ recordRequestOutcome(entry, 'error', error);+ entry.reject(error);+ }+ finishGracefulDisposeIfDrained();+ }+function observeOwnerEpochLoss(error: CacheResponseError): void {if (state === 'failed' ||@@ -480,13 +542,21 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {onEngineReplaced: (epoch, outcome) => {if (adapter === created) onEngineReplaced(epoch, outcome);},+ onCacheReadAvailabilityChanged: (availability) => {+ if (adapter !== created) return;+ match(availability)+ .with('ready', resumeCacheReads)+ .with('waiting', waitForCacheReads)+ .with('blocked', onOwnerHandoffBlocked)+ .exhaustive();+ },onStartupProgress: (progress) => {if (adapter !== created) return;initializationTimeoutMs =options.initializationTimeoutMs ??progress.timeoutMs + STARTUP_RESPONSE_GRACE_MS;for (const [id, entry] of pending) {- if (entry.kind === 'init')+ if (entry.kind === 'init' && !readAvailability.timeoutsPaused)armRequestTimeout(id, entry, initializationTimeoutMs);}},@@ -682,6 +752,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {{ uncertain = false, preserveDatabase = false } = {}): void {state = 'failed';+ readAvailability.resume();initialization = undefined;initializationError = error;rejectPending(error, uncertain);@@ -897,6 +968,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {function suspendTransport(error: Error): void {state = 'suspended';+ readAvailability.resume();transportGeneration += 1;transportInterruption = error;initializationAttempt += 1;@@ -1008,6 +1080,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return Promise.reject(new Error('cache worker host was disposed'));}+ if (isReadOnlyCacheRequest(msg.kind) && readAvailability.error) {+ return Promise.reject(readAvailability.error);+ }const id = nextRequestId++;return new Promise((resolve, reject) => {const entry: Pending = {@@ -1018,19 +1093,11 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {admitted: false,startedAt: now(),};- const timeoutMs =- msg.kind === 'init'+ const timeoutMs = readAvailability.timeoutsPaused+ ? undefined+ : msg.kind === 'init'? initializationTimeoutMs- : msg.kind === 'current-revision' ||- msg.kind === 'current-storage-generation' ||- msg.kind === 'read' ||- msg.kind === 'read-records-by-keys' ||- msg.kind === 'search' ||- msg.kind === 'entity-filter' ||- msg.kind === 'calendar-range' ||- msg.kind === 'inspect-mutations' ||- msg.kind === 'inspect-query' ||- msg.kind === 'inspect-query-variants'+ : isReadOnlyCacheRequest(msg.kind)? requestTimeoutMs: undefined;if (timeoutMs !== undefined) {@@ -1219,7 +1286,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {opKey?: number): Promise<unknown> {const generation = transportGeneration;- await ensureInitialized();+ if (state === 'ready') {+ await ensureInitialized();+ } else {+ await readAvailability.waitUntilReady(+ ensureInitialized,+ isReadOnlyCacheRequest(msg.kind)+ );+ }// Never admit an interrupted operation to a different transport generation.if (generation !== transportGeneration)throw transportInterruption ?? new CacheNavigationError();@@ -1228,7 +1302,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {function trackActiveOperation(opKey: number): void {activeOpKeys.add(opKey);- if (state === 'suspended') lostRegisteredOpKeys.add(opKey);+ if (state === 'suspended' || readAvailability.error)+ lostRegisteredOpKeys.add(opKey);else if (recoveryInProgress) replacementReadOpKeys.add(opKey);}@@ -1509,10 +1584,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {if (state !== 'ready' && state !== 'initializing') return;if (state === 'initializing') {try {- await ensureInitialized();+ await readAvailability.waitUntilReady(ensureInitialized, false);} catch {return;}+ } else {+ // Match ordinary RPC admission so a same-turn teardown cannot pass a+ // read waiting for the parked coordinator and leave its deps alive.+ await ensureInitialized();}// Disposal or owner loss can win while an initialization await yields.if (state !== 'ready') return;diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 4686ae96f8..92eb908808 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -911,7 +911,7 @@ export const OWNER_EPOCH_LOST_ERROR_CODE: CacheResponseErrorCode =export const OWNER_LOCK_UNAVAILABLE_ERROR_CODE: CacheResponseErrorCode ='owner-lock-unavailable';-/** An enqueue send was admitted before its unfenced transport became uncertain. */+/** An admitted enqueue lost its reply and may already be durably queued. */export const ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE: CacheResponseErrorCode ='admitted-enqueue-uncertain';@@ -987,7 +987,7 @@ export const isOwnerLockUnavailableError = ('errorCode' in value &&value.errorCode === OWNER_LOCK_UNAVAILABLE_ERROR_CODE;-/** Identifies the host-only uncertainty result for an admitted enqueue send. */+/** Identifies an admitted enqueue whose durable outcome is unknown. */export const isAdmittedEnqueueUncertainError = (value: unknown): value is Error & { errorCode: 'admitted-enqueue-uncertain' } =>diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.tsindex 77900c0b74..fd5132bc58 100644--- a/apps/web/src/lib/graphql-cache/telemetry.ts+++ b/apps/web/src/lib/graphql-cache/telemetry.ts@@ -129,6 +129,13 @@ export const CACHE_OWNER_EVENTS = ['activated','graceful-drain-started','graceful-drain-completed',+ 'visibility-handoff-started',+ 'visibility-handoff-blocked',+ 'visibility-handoff-completed',+ 'park-started',+ 'parked',+ 'unpark-started',+ 'unpark-completed','navigation-departure','coordinator-restarted','abrupt-loss',diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/parking-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/parking-harness.tsnew file mode 100644index 0000000000..2b5264e877--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/parking-harness.ts@@ -0,0 +1,169 @@+import {+ createClient,+ fetchExchange,+ gql,+ stringifyDocument,+} from '@urql/core';+import { normalizedCacheExchange } from '../../exchange/normalized-cache-exchange';+import type { CacheHost } from '../../host/types';+import { createWorkerCacheHost } from '../../host/worker-host';++const params = new URLSearchParams(location.search);+const scope = params.get('scope');+if (!scope?.startsWith('cache-parking-'))+ throw new Error('synthetic scope required');+const nativeWorker = globalThis.Worker;+const parked = Promise.withResolvers<void>();+const epochs: number[] = [];+globalThis.Worker = new Proxy(nativeWorker, {+ construct(_target, args: ConstructorParameters<typeof Worker>) {+ const worker = new nativeWorker(...args);+ if (args[1]?.name?.startsWith('graphql-cache-engine:')) {+ epochs.push(Number(args[1].name.split(':').at(-1)));+ const terminate = worker.terminate.bind(worker);+ worker.terminate = () => {+ terminate();+ parked.resolve();+ };+ }+ return worker;+ },+});+const query = 'query ParkingWitness { user { id } }';+const data = { user: { id: 'macro|parking-fixture' } };+const mutation = gql`mutation ParkingMutation($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) { id displayName }+}`;+const variables = (uuid: string) => ({+ input: {+ entityType: 'DOCUMENT',+ entityId: 'synthetic-document',+ propertyDefinitionId: uuid,+ value: { string: 'synthetic' },+ },+});+let host: CacheHost | undefined;+let apiRequests = 0;+let generationBefore: string | undefined;+let seedUuid: string | undefined;+const response = Promise.withResolvers<Response>();+const sent = Promise.withResolvers<void>();+const settling = Promise.withResolvers<void>();+let result: Promise<unknown> | undefined;+function requireHost(): CacheHost {+ if (!host) throw new Error('cache not started');+ return host;+}+const api = {+ async start(seed = false) {+ host ??= createWorkerCacheHost({ scope });+ if (seed) {+ await host.writeQuery({ query, data });+ seedUuid = crypto.randomUUID();+ const now = Date.now();+ await host.enqueueOptimisticMutation(+ {+ uuid: seedUuid,+ query: stringifyDocument(mutation),+ variables: variables(seedUuid),+ data: { setEntityProperty: { id: seedUuid, displayName: 'Queued' } },+ },+ {+ owner: 'parking-seed',+ nowMs: now,+ leaseExpiresAtMs: now + 86_400_000,+ }+ );+ }+ generationBefore ??= await host.currentStorageGeneration();+ return generationBefore;+ },+ async snapshot() {+ const current = requireHost();+ return {+ clientId: current.clientId,+ generation: await current.currentStorageGeneration(),+ queue: await current.inspectMutations?.(),+ read: await current.readQuery({ query }),+ generationBefore,+ seedUuid,+ epochs: [...epochs],+ apiRequests,+ visibility: document.visibilityState,+ };+ },+ parked: () => parked.promise,+ async locks() {+ return (await navigator.locks.query()).held?.filter((lock) =>+ lock.name?.includes(scope)+ );+ },+ async beginMutation() {+ const current = requireHost();+ await current.writeQuery({ query, data });+ generationBefore = await current.currentStorageGeneration();+ const uuid = crypto.randomUUID();+ const client = createClient({+ url: 'https://parking.invalid/graphql',+ fetch: async () => {+ apiRequests += 1;+ sent.resolve();+ return await response.promise;+ },+ exchanges: [+ normalizedCacheExchange({+ ...current,+ async commitOptimisticWrite(...args) {+ const committed = current.commitOptimisticWrite(...args);+ settling.resolve();+ return await committed;+ },+ }),+ fetchExchange,+ ],+ });+ result = client+ .mutation(mutation, variables(uuid), {+ normalizedCacheOptimistic: {+ uuid,+ optimisticResponse: {+ setEntityProperty: { id: uuid, displayName: 'Optimistic' },+ },+ },+ })+ .toPromise();+ await sent.promise;+ return uuid;+ },+ async reply(uuid: string) {+ response.resolve(+ new Response(+ JSON.stringify({+ data: {+ setEntityProperty: { id: uuid, displayName: 'Confirmed' },+ },+ }),+ { headers: { 'content-type': 'application/json' } }+ )+ );+ await settling.promise;+ },+ result: () => result,+ async competingClaim() {+ return await requireHost().claimNextMutation(+ 'parking-competitor',+ Date.now() + 600_000,+ Date.now() + 900_000+ );+ },+ dispose() {+ host?.dispose();+ },+};+declare global {+ interface Window {+ cacheParkingHarness: typeof api;+ }+}+window.cacheParkingHarness = api;+document.querySelector('#result')?.setAttribute('data-status', 'ready');diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/parking.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/parking.browser.e2e.tsnew file mode 100644index 0000000000..eff3ceb153--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/parking.browser.e2e.ts@@ -0,0 +1,94 @@+import { expect, test } from '@playwright/test';++const path = (project: string) =>+ project.includes('production') ? '/app/parking.html' : '/parking.html';++test('all-hidden storage parks and another page reopens it without waking the old owner', async ({+ context,+ page,+}, info) => {+ const url = `${path(info.project.name)}?scope=cache-parking-${crypto.randomUUID()}`;+ await page.goto(url);+ await page.evaluate(() => window.cacheParkingHarness.start(true));+ const before = await page.evaluate(() =>+ window.cacheParkingHarness.snapshot()+ );+ const other = await context.newPage();+ await other.goto(url);+ await other.bringToFront();+ // Headless browsers keep every page visible. Exercise the visibility event+ // deterministically here; real Safari lifecycle qualification is separate.+ await page.evaluate(() => {+ Object.defineProperty(document, 'visibilityState', {+ configurable: true,+ get: () => 'hidden',+ });+ document.dispatchEvent(new Event('visibilitychange'));+ });+ expect(await page.evaluate(() => document.visibilityState)).toBe('hidden');+ await page.evaluate(() => window.cacheParkingHarness.parked());+ const locks = await other.evaluate(() => window.cacheParkingHarness.locks());+ expect(+ locks?.filter((lock) => lock.name?.startsWith('macro:turso-opfs:'))+ ).toEqual([]);+ await other.evaluate(() => window.cacheParkingHarness.start());+ const after = await other.evaluate(() =>+ window.cacheParkingHarness.snapshot()+ );+ expect(after.generation).toBe(before.generation);+ expect(after.queue?.map((item) => item.uuid)).toEqual([before.seedUuid]);+ expect(after.read).toMatchObject({ kind: 'hit' });+ const old = await page.evaluate(() => window.cacheParkingHarness.snapshot());+ expect(old.clientId).toBe(before.clientId);+ expect(old.generation).toBe(before.generation);+ expect(old.visibility).toBe('hidden');+});++test('settles a response received while parked before a competing expired-lease claim', async ({+ context,+ page,+}, info) => {+ const url = `${path(info.project.name)}?scope=cache-parking-${crypto.randomUUID()}`;+ await page.goto(url);+ await page.evaluate(() => window.cacheParkingHarness.start());+ const uuid = await page.evaluate(() =>+ window.cacheParkingHarness.beginMutation()+ );+ const before = await page.evaluate(() =>+ window.cacheParkingHarness.snapshot()+ );+ const other = await context.newPage();+ await other.goto(url);+ await other.bringToFront();+ await page.evaluate(() => {+ Object.defineProperty(document, 'visibilityState', {+ configurable: true,+ get: () => 'hidden',+ });+ document.dispatchEvent(new Event('visibilitychange'));+ });+ await page.evaluate(() => window.cacheParkingHarness.parked());+ await page.evaluate((uuid) => window.cacheParkingHarness.reply(uuid), uuid);+ expect(await page.evaluate(() => document.visibilityState)).toBe('hidden');+ const locks = await other.evaluate(() => window.cacheParkingHarness.locks());+ expect(+ locks?.filter((lock) => lock.name?.startsWith('macro:turso-opfs:'))+ ).toEqual([]);+ await other.evaluate(() => window.cacheParkingHarness.start());+ expect(+ await other.evaluate(() => window.cacheParkingHarness.competingClaim())+ ).toBeFalsy();+ const after = await other.evaluate(() =>+ window.cacheParkingHarness.snapshot()+ );+ expect(after.generation).toBe(before.generation);+ expect(after.queue).toEqual([]);+ const result = await page.evaluate(() => window.cacheParkingHarness.result());+ expect(result).toMatchObject({+ data: { setEntityProperty: { id: uuid, displayName: 'Confirmed' } },+ });+ expect(+ (await page.evaluate(() => window.cacheParkingHarness.snapshot()))+ .apiRequests+ ).toBe(1);+});diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/parking.html b/apps/web/src/lib/graphql-cache/worker/browser-test/parking.htmlnew file mode 100644index 0000000000..c1ef16db86--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/parking.html@@ -0,0 +1,5 @@+<!doctype html>+<html lang="en">+<head><meta charset="utf-8"><title>Cache parking fixture</title></head>+<body><h1>Cache parking fixture</h1><p>Synthetic local data; no backend.</p><pre id="result"></pre><script type="module" src="./parking-harness.ts"></script></body>+</html>diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.tsindex e4be160f2b..2cdfa7afd0 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.config.ts@@ -10,6 +10,7 @@ export default defineConfig({'independent-send-recovery.browser.e2e.ts','calendar-points.browser.e2e.ts','coordinator.browser.e2e.ts',+ 'parking.browser.e2e.ts','cache-wasm-packaging.browser.e2e.ts','notification-projection.browser.e2e.ts','mail-projection.browser.e2e.ts',diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.tsindex ba06b23ea3..82aaf9b88b 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/playwright.production.config.ts@@ -9,6 +9,7 @@ export default defineConfig({testMatch: ['calendar-points.browser.e2e.ts','coordinator.browser.e2e.ts',+ 'parking.browser.e2e.ts','cache-startup.browser.e2e.ts','cache-artifact-compatibility.browser.e2e.ts','cache-wasm-packaging.browser.e2e.ts',diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.tsindex 856fe00226..9cccf35e0f 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/vite.config.ts@@ -50,6 +50,7 @@ export default defineConfig(({ command }) => ({'performance.html','exact-production-host.html','cache-lifecycle.html',+ 'parking.html','graphql-soup-rollout.html','cache-recovery.html','notification-projection.html',diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.tsindex e84f3f9046..42b18b7bd1 100644--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts@@ -152,6 +152,7 @@ const registerTab = async (scope: 'scope',tabId,livenessLockName: `graphql-cache-tab:scope:${tabId}`,+ visible: true,buildTime: 0,});};diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.tsindex 04e93e9463..e2392e3f72 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@@ -1,5 +1,6 @@+import { match } from 'ts-pattern';import { describe, expect, it } from 'vitest';-import { INITIAL_CACHE_REVISION } from '../protocol';+import { type CacheRequest, INITIAL_CACHE_REVISION } from '../protocol';import { type CoordinatorAction, CoordinatorCore } from './coordinator-core';import type { DatabaseActionProof } from './coordinator-protocol';@@ -610,6 +611,130 @@ describe('CoordinatorCore', () => {});});+ it.each(['navigation', 'graceful', 'abrupt'] as const)(+ 'keeps routed enqueues uncertain and unrouted enqueues queued after %s departure',+ (departureKind) => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ ready(core, 'tab-a', 1, 'opened-existing');+ const enqueue = {+ id: 9,+ kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000001',+ query: 'mutation Enqueue { enqueue }',+ data: { enqueue: true },+ createdAtMs: 1,+ owner: 'tab-b',+ nowMs: 1,+ leaseExpiresAtMs: 300_001,+ } satisfies CacheRequest;+ const routed = action(core.request('tab-b', enqueue), 'route-request');+ core.beginGracefulDeparture('tab-a', 1);+ const queued = {+ ...enqueue,+ id: 10,+ uuid: '00000000-0000-4000-8000-000000000002',+ };+ expect(core.request('tab-b', queued)).toEqual([]);++ const departure = match(departureKind)+ .with('navigation', () =>+ core.departForNavigation('tab-a', 1, 'pagehide')+ )+ .with('graceful', () => core.engineDrained('tab-a', 1))+ .with('abrupt', () => [+ ...core.ownerLost('tab-a', 1, 'worker stopped'),+ ...core.resumeAfterLoss(),+ ])+ .exhaustive();+ expect(departure.filter(({ kind }) => kind === 'reject-request')).toEqual(+ [+ {+ kind: 'reject-request',+ tabId: 'tab-b',+ requestId: 9,+ error: expect.any(String),+ errorCode: 'admitted-enqueue-uncertain',+ },+ ]+ );+ expect(action(departure, 'elect-owner')).toMatchObject({+ tabId: 'tab-b',+ ownerEpoch: 2,+ databaseAction:+ departureKind === 'abrupt' ? 'wipe-before-open' : 'open-existing',+ });+ const replacement = ready(+ core,+ 'tab-b',+ 2,+ departureKind === 'abrupt' ? 'wiped-before-open' : 'opened-existing'+ );+ expect(+ replacement.filter(({ kind }) => kind === 'route-request')+ ).toEqual([+ expect.objectContaining({+ ownerEpoch: 2,+ request: { ...queued, id: expect.any(Number) },+ }),+ ]);+ expect(+ core.engineResponse(1, routed.routeId, {+ id: routed.routeId,+ ok: true,+ result: null,+ })+ ).toEqual([+ expect.objectContaining({ kind: 'drop-stale-engine-message' }),+ ]);+ }+ );++ it.each([false, true])(+ 'announces a reset before draining a hidden recovery owner (visible survivor: %s)',+ (visibleSurvivor) => {+ const core = new CoordinatorCore('scope');+ core.registerTab('tab-a');+ core.registerTab('tab-b');+ ready(core, 'tab-a', 1, 'opened-existing');+ core.ownerLost('tab-a', 1, 'engine failed');+ core.resumeAfterLoss();+ core.setTabVisibility('tab-a', visibleSurvivor);+ core.setTabVisibility('tab-b', false);+ expect(+ core.request('tab-a', { id: 9, kind: 'current-revision' })+ ).toEqual([]);++ expect(ready(core, 'tab-b', 2, 'wiped-before-open')).toEqual([+ {+ kind: 'broadcast-engine-replaced',+ ownerEpoch: 2,+ openOutcome: 'reset-storage-uncertain',+ },+ { kind: 'drain-owner', tabId: 'tab-b', ownerEpoch: 2, handoff: true },+ ]);+ expect(core.state.kind).toBe('draining');+ expect(core.snapshot().inFlightRequestCount).toBe(0);+ expect(core.snapshot().queuedRequestCount).toBe(1);+ core.engineDrained('tab-b', 2);+ if (!visibleSurvivor) {+ expect(core.state.kind).toBe('parked');+ core.setTabVisibility('tab-a', true);+ }+ const reopened = ready(core, 'tab-a', 3, 'opened-existing');+ expect(action(reopened, 'broadcast-engine-replaced')).toMatchObject({+ ownerEpoch: 3,+ openOutcome: 'opened-existing',+ });+ expect(action(reopened, 'route-request')).toMatchObject({+ ownerEpoch: 3,+ requesterTabId: 'tab-a',+ request: { kind: 'current-revision' },+ });+ }+ );+it('does not downgrade an interrupted recovery activation to open-existing', () => {const core = new CoordinatorCore('scope');core.registerTab('tab-a');diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.tsindex cf2b12bf77..37c2903263 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts@@ -1,4 +1,5 @@import {+ ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,type CachePush,type CacheRequest,type CacheResponse,@@ -17,6 +18,7 @@ import type {export type CoordinatorState =| { kind: 'waiting-for-tab'; nextDatabaseAction: DatabaseAction }+ | { kind: 'parked'; nextDatabaseAction: DatabaseAction }| {kind: 'activating';tabId: string;@@ -82,7 +84,14 @@ export type CoordinatorAction =error: string;errorCode?: CacheResponseErrorCode;}- | { kind: 'drain-owner'; tabId: string; ownerEpoch: OwnerEpoch }+ | {+ kind: 'drain-owner';+ tabId: string;+ ownerEpoch: OwnerEpoch;+ handoff?: true;+ }+ | { kind: 'release-owner'; tabId: string; ownerEpoch: OwnerEpoch }+ | { kind: 'handoff-pending'; ownerEpoch: OwnerEpoch }| { kind: 'close-engine-route'; tabId: string; ownerEpoch: OwnerEpoch }| { kind: 'drop-tab'; tabId: string }| { kind: 'retire-tab'; tabId: string; ownerEpoch: OwnerEpoch }@@ -130,6 +139,15 @@ const STORAGE_BUSY_REASON =const SUPERSEDED_REASON ='a newer version of the app took over the local cache';+/** Known outcomes must survive a caller leaving while storage is parked. */+function isMutationSettlement(request: CacheRequest): boolean {+ return (+ request.kind === 'commit-optimistic-write' ||+ request.kind === 'rollback-optimistic-write' ||+ request.kind === 'defer-optimistic-write'+ );+}+/** Pure election, epoch, routing, drain, and abrupt-loss state machine. */export class CoordinatorCore {private stateValue: CoordinatorState = {@@ -138,6 +156,7 @@ export class CoordinatorCore {};private readonly tabs: string[] = [];private readonly retiringTabs = new Set<string>();+ private readonly visibleTabs = new Set<string>();/** Tabs told the database is unavailable, with the reason they were given;* their pages stay uncached. */private readonly unavailableTabs = new Map<string, string>();@@ -172,14 +191,20 @@ export class CoordinatorCore {};}+ /** Visibility of eligible consumers, not merely the page owning an engine. */+ get hasVisibleTab(): boolean {+ return this.chooseCandidate() !== undefined;+ }+/** Whether a newer app build took the database over. */get superseded(): boolean {return this.supersededReason !== undefined;}- registerTab(tabId: string): CoordinatorAction[] {+ registerTab(tabId: string, visible = true): CoordinatorAction[] {if (this.tabs.includes(tabId)) return [];this.tabs.push(tabId);+ if (visible) this.visibleTabs.add(tabId);if (this.supersededReason !== undefined) {// A page of this build loaded after the handover, as after a rollback// or from stale HTML. Reloading could land on this build again, so it@@ -212,10 +237,27 @@ export class CoordinatorCore {},];}- if (this.stateValue.kind !== 'waiting-for-tab') return [];+ if (+ this.stateValue.kind !== 'waiting-for-tab' &&+ this.stateValue.kind !== 'parked'+ )+ return this.handoffIfNeeded();return this.activateNext(this.stateValue.nextDatabaseAction);}+ setTabVisibility(tabId: string, visible: boolean): CoordinatorAction[] {+ if (!this.tabs.includes(tabId)) return [];+ if (visible) this.visibleTabs.add(tabId);+ else this.visibleTabs.delete(tabId);+ if (+ this.stateValue.kind === 'parked' ||+ this.stateValue.kind === 'waiting-for-tab'+ ) {+ return this.activateNext(this.stateValue.nextDatabaseAction);+ }+ return this.handoffIfNeeded();+ }+request(tabId: string, request: CacheRequest): CoordinatorAction[] {if (!this.tabs.includes(tabId)) {return [@@ -365,9 +407,17 @@ export class CoordinatorCore {openOutcome: ready.openOutcome,});}+ // A hidden engine may have reset storage before it immediately drains.+ // Notify hosts of that outcome, but leave queued work for its successor.+ const handoff = this.handoffIfNeeded();+ if (handoff.length > 0) return [...actions, ...handoff];while (this.queuedRequests.length > 0) {const queued = this.queuedRequests.shift();- if (queued && this.tabs.includes(queued.tabId)) {+ if (+ queued &&+ (this.tabs.includes(queued.tabId) ||+ isMutationSettlement(queued.request))+ ) {actions.push(this.route(queued, this.stateValue));}}@@ -389,6 +439,7 @@ export class CoordinatorCore {}this.inFlight.delete(routeId);+ if (!this.tabs.includes(request.tabId)) return [];return [{kind: 'deliver-response',@@ -411,7 +462,7 @@ export class CoordinatorCore {): CoordinatorAction[] {const state = this.stateValue;if (- state.kind !== 'active' ||+ (state.kind !== 'active' && state.kind !== 'draining') ||state.tabId !== tabId ||state.ownerEpoch !== ownerEpoch) {@@ -420,6 +471,8 @@ export class CoordinatorCore {);}this.retiringTabs.add(tabId);+ // An explicit disposal may join an already-running visibility handoff.+ if (state.kind === 'draining') return [];this.stateValue = { kind: 'draining', tabId, ownerEpoch };return [{ kind: 'drain-owner', tabId, ownerEpoch }];}@@ -440,12 +493,15 @@ export class CoordinatorCore {ownerEpoch,'engine drained before delivering its response');- this.removeTabRecord(tabId);- this.retiringTabs.delete(tabId);- actions.push(- { kind: 'close-engine-route', tabId, ownerEpoch },- { kind: 'retire-tab', tabId, ownerEpoch }- );+ actions.push({ kind: 'close-engine-route', tabId, ownerEpoch });+ if (this.retiringTabs.delete(tabId)) {+ this.removeTabRecord(tabId);+ actions.push({ kind: 'retire-tab', tabId, ownerEpoch });+ } else {+ // The engine closed storage, not the page. Its host and subscriptions+ // remain connected and the usual replacement broadcast refreshes them.+ actions.push({ kind: 'release-owner', tabId, ownerEpoch });+ }this.stateValue = {kind: 'waiting-for-tab',nextDatabaseAction: 'open-existing',@@ -475,7 +531,10 @@ export class CoordinatorCore {const { kind } = this.stateValue;if (this.supersededReason !== undefined ||- (kind !== 'active' && kind !== 'waiting-for-tab' && kind !== 'failed')+ (kind !== 'active' &&+ kind !== 'waiting-for-tab' &&+ kind !== 'parked' &&+ kind !== 'failed')) {return [];}@@ -586,7 +645,7 @@ export class CoordinatorCore {const candidate = this.chooseCandidate(state.previousTabId);if (!candidate) {this.stateValue = {- kind: 'waiting-for-tab',+ kind: this.eligibleTabs().length > 0 ? 'parked' : 'waiting-for-tab',nextDatabaseAction: state.databaseAction,};return [];@@ -666,8 +725,15 @@ export class CoordinatorCore {for (const [routeId, request] of this.inFlight) {if (request.ownerEpoch !== ownerEpoch) continue;this.inFlight.delete(routeId);+ // Fencing an engine does not undo a durable enqueue. Even a planned+ // reset has not erased it yet, so a missing reply must never cause+ // the caller to retry or forward the mutation directly to the API.+ const requestErrorCode =+ request.request.kind === 'enqueue-optimistic-mutation'+ ? ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE+ : errorCode;actions.push(- this.reject(request.tabId, request.request.id, error, errorCode)+ this.reject(request.tabId, request.request.id, error, requestErrorCode));}return actions;@@ -677,7 +743,7 @@ export class CoordinatorCore {const candidate = this.chooseCandidate();if (!candidate) {this.stateValue = {- kind: 'waiting-for-tab',+ kind: this.eligibleTabs().length > 0 ? 'parked' : 'waiting-for-tab',nextDatabaseAction: databaseAction,};return [];@@ -700,12 +766,40 @@ export class CoordinatorCore {];}- private chooseCandidate(avoid?: string): string | undefined {- const eligible = this.tabs.filter(+ private handoffIfNeeded(): CoordinatorAction[] {+ const state = this.stateValue;+ if (+ (state.kind !== 'active' && state.kind !== 'activating') ||+ this.visibleTabs.has(state.tabId)+ )+ return [];+ // Start draining on the last visible page's exit, not after a hidden+ // worker has had time to suspend. Startup still finishes before draining.+ if (state.kind === 'activating')+ return [{ kind: 'handoff-pending', ownerEpoch: state.ownerEpoch }];+ this.stateValue = { ...state, kind: 'draining' };+ return [+ {+ kind: 'drain-owner',+ tabId: state.tabId,+ ownerEpoch: state.ownerEpoch,+ handoff: true,+ },+ ];+ }++ private eligibleTabs(): string[] {+ return this.tabs.filter((tabId) =>!this.retiringTabs.has(tabId) && !this.unavailableTabs.has(tabId));- return eligible.find((tabId) => tabId !== avoid) ?? eligible[0];+ }++ private chooseCandidate(avoid?: string): string | undefined {+ const visible = this.eligibleTabs().filter((tabId) =>+ this.visibleTabs.has(tabId)+ );+ return visible.find((tabId) => tabId !== avoid) ?? visible[0];}private route(@@ -735,8 +829,10 @@ export class CoordinatorCore {const index = this.tabs.indexOf(tabId);if (index >= 0) this.tabs.splice(index, 1);this.unavailableTabs.delete(tabId);+ this.visibleTabs.delete(tabId);for (let index = this.queuedRequests.length - 1; index >= 0; index -= 1) {- if (this.queuedRequests[index]?.tabId === tabId) {+ const queued = this.queuedRequests[index];+ if (queued?.tabId === tabId && !isMutationSettlement(queued.request)) {this.queuedRequests.splice(index, 1);}}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.test.tsnew file mode 100644index 0000000000..f4e0d9d01c--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.test.ts@@ -0,0 +1,93 @@+import { afterEach, beforeEach, expect, it, vi } from 'vitest';+import { CoordinatorHandoff } from './coordinator-handoff';++beforeEach(() => vi.useFakeTimers());+afterEach(() => vi.useRealTimers());++it('bounds foreground reads without extending the budget on candidate changes', async () => {+ const record = vi.fn();+ const onChange = vi.fn();+ const handoff = new CoordinatorHandoff({+ timeoutMs: 1000,+ setTimeout,+ clearTimeout,+ now: Date.now,+ telemetry: { record, flush() {} },+ onChange,+ });+ handoff.start(1);+ await vi.advanceTimersByTimeAsync(900);+ handoff.start(2);+ await vi.advanceTimersByTimeAsync(100);+ expect(handoff.readState).toEqual({ ownerEpoch: 2, state: 'blocked' });+ expect(onChange).toHaveBeenLastCalledWith({+ ownerEpoch: 2,+ state: 'blocked',+ });+ handoff.ready(2);+ expect(handoff.readState).toEqual({ ownerEpoch: 2, state: 'ready' });+ expect(record).toHaveBeenCalledWith(+ expect.objectContaining({+ ownerEvent: 'visibility-handoff-completed',+ durationMs: 1000,+ })+ );+});++it('parks without a background read deadline and starts a fresh foreground resume budget', async () => {+ const record = vi.fn();+ const onChange = vi.fn();+ const handoff = new CoordinatorHandoff({+ timeoutMs: 1000,+ setTimeout,+ clearTimeout,+ now: Date.now,+ telemetry: { record, flush() {} },+ onChange,+ });+ handoff.start(1, false);+ await vi.advanceTimersByTimeAsync(60_000);+ expect(handoff.readState).toEqual({ ownerEpoch: 1, state: 'waiting' });+ expect(vi.getTimerCount()).toBe(0);+ handoff.park(1);+ handoff.park(1);+ expect(+ record.mock.calls.filter(([event]) => event.ownerEvent === 'parked')+ ).toHaveLength(1);+ await vi.advanceTimersByTimeAsync(300_000);+ handoff.start(2, true);+ await vi.advanceTimersByTimeAsync(999);+ expect(handoff.readState?.state).toBe('waiting');+ await vi.advanceTimersByTimeAsync(1);+ expect(handoff.readState?.state).toBe('blocked');+ handoff.ready(2);+ expect(record).toHaveBeenCalledWith(+ expect.objectContaining({+ ownerEvent: 'unpark-completed',+ durationMs: 1000,+ })+ );+});++it('cancels foreground deadlines when everyone hides, but failure alone never resumes reads', async () => {+ const handoff = new CoordinatorHandoff({+ timeoutMs: 1000,+ setTimeout,+ clearTimeout,+ now: Date.now,+ telemetry: { record() {}, flush() {} },+ onChange() {},+ });+ handoff.start(1);+ await vi.advanceTimersByTimeAsync(900);+ handoff.start(1, false);+ await vi.advanceTimersByTimeAsync(60_000);+ expect(handoff.readState?.state).toBe('waiting');+ handoff.start(1, true);+ await vi.advanceTimersByTimeAsync(1000);+ expect(handoff.readState?.state).toBe('blocked');+ handoff.cancel();+ expect(handoff.readState?.state).toBe('blocked');+ handoff.ready(2);+ expect(handoff.readState?.state).toBe('ready');+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.tsnew file mode 100644index 0000000000..623ae314ff--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-handoff.ts@@ -0,0 +1,150 @@+import type { CacheTelemetryRecorderLike } from '../telemetry';+import type { CacheReadState } from './coordinator-protocol';++export const OWNER_HANDOFF_READ_TIMEOUT_MS = 1_000;++export type CacheReadAvailability = Readonly<{+ ownerEpoch: number;+ state: CacheReadState;+}>;++/** Bounds foreground read availability, never engine lifetime or lock ownership. */+export class CoordinatorHandoff {+ private active:+ | {+ ownerEpoch: number;+ startedAt: number;+ resumed: boolean;+ }+ | undefined;+ private timer: ReturnType<typeof setTimeout> | undefined;+ private budget: object | undefined;+ private current: CacheReadAvailability | undefined;+ private parked = false;++ constructor(+ private readonly options: {+ timeoutMs: number;+ setTimeout: typeof globalThis.setTimeout;+ clearTimeout: typeof globalThis.clearTimeout;+ now: () => number;+ telemetry: CacheTelemetryRecorderLike;+ onChange: (availability: CacheReadAvailability) => void;+ }+ ) {}++ get readState(): CacheReadAvailability | undefined {+ return this.current;+ }++ get transitioning(): boolean {+ return (+ this.active !== undefined ||+ (this.current !== undefined && this.current.state !== 'ready')+ );+ }++ start(ownerEpoch: number, visible = true): void {+ if (!this.active) {+ this.active = {+ ownerEpoch,+ startedAt: this.options.now(),+ resumed: this.parked,+ };+ this.options.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'graceful',+ ownerEvent: this.parked+ ? 'unpark-started'+ : visible+ ? 'visibility-handoff-started'+ : 'park-started',+ });+ }+ this.parked = false;+ const active = this.active;+ active.ownerEpoch = ownerEpoch;+ if (!visible) {+ this.clearBudget();+ this.update(ownerEpoch, 'waiting');+ return;+ }+ // Changes of candidate must not reset an exhausted foreground budget.+ if (this.current?.state === 'blocked') {+ this.update(ownerEpoch, 'blocked');+ return;+ }+ this.update(ownerEpoch, 'waiting');+ if (this.timer !== undefined) return;+ const budget = {};+ this.budget = budget;+ const startedAt = this.options.now();+ this.timer = this.options.setTimeout(() => {+ if (this.active !== active || this.budget !== budget) return;+ this.timer = undefined;+ this.budget = undefined;+ this.options.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'error',+ errorCode: 'timeout',+ ownerEvent: 'visibility-handoff-blocked',+ durationMs: this.options.now() - startedAt,+ });+ this.update(active.ownerEpoch, 'blocked');+ }, this.options.timeoutMs);+ }++ park(ownerEpoch: number): void {+ if (this.parked && this.current?.ownerEpoch === ownerEpoch) return;+ const startedAt = this.active?.startedAt;+ this.cancel();+ this.parked = true;+ this.update(ownerEpoch, 'waiting');+ this.options.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'graceful',+ ownerEvent: 'parked',+ durationMs:+ startedAt === undefined ? undefined : this.options.now() - startedAt,+ });+ }++ ready(ownerEpoch: number): void {+ if (this.active) {+ this.options.telemetry.record({+ name: 'graphql_cache.owner',+ operationCategory: 'lifecycle',+ outcome: 'success',+ ownerEvent: this.active.resumed+ ? 'unpark-completed'+ : 'visibility-handoff-completed',+ durationMs: this.options.now() - this.active.startedAt,+ });+ }+ this.cancel();+ this.parked = false;+ if (this.current) this.update(ownerEpoch, 'ready');+ }++ cancel(): void {+ this.clearBudget();+ this.active = undefined;+ // Failure is not readiness. Keep waiting/bypass until an owner is usable.+ }++ private clearBudget(): void {+ if (this.timer !== undefined) this.options.clearTimeout(this.timer);+ this.timer = undefined;+ this.budget = undefined;+ }++ private update(ownerEpoch: number, state: CacheReadState): void {+ if (this.current?.ownerEpoch === ownerEpoch && this.current.state === state)+ return;+ this.current = { ownerEpoch, state };+ this.options.onChange(this.current);+ }+}diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.tsindex 423c8dc07e..4604ab6d17 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@@ -175,6 +175,83 @@ describe('CacheCoordinatorPageAdapter', () => {expect(attach?.transfer).toHaveLength(1);});+ it('reports visibility changes during registration and fences stale handoff notices', async () => {+ class Visibility extends EventTarget {+ visibilityState: DocumentVisibilityState = 'visible';+ }+ const visibility = new Visibility();+ const detached = vi.spyOn(visibility, 'removeEventListener');+ const port = new FakeCoordinatorPort();+ const sent = Promise.withResolvers<void>();+ const post = port.postMessage.bind(port);+ vi.spyOn(port, 'postMessage').mockImplementation((message, transfer) => {+ post(message, transfer);+ sent.resolve();+ });+ const onCacheReadAvailabilityChanged = vi.fn();+ const adapter = createCacheCoordinatorPageAdapter({+ scope: 'scope',+ tabId: 'tab-a',+ visibility,+ onCacheReadAvailabilityChanged,+ lockManager: heldLockManager(),+ createSharedWorker: () => ({ port: port as unknown as MessagePort }),+ createDedicatedWorker: () => new FakeWorker(),+ });+ const started = adapter.start();+ await sent.promise;+ expect(port.messages[0]?.message).toMatchObject({+ kind: 'register-tab',+ visible: true,+ });+ visibility.visibilityState = 'hidden';+ port.receive({ ...version, kind: 'registered', tabId: 'tab-a' });+ await started;+ expect(port.messages.at(-1)?.message).toMatchObject({+ kind: 'tab-visibility',+ visible: false,+ });+ visibility.visibilityState = 'visible';+ visibility.dispatchEvent(new Event('visibilitychange'));+ expect(port.messages.at(-1)?.message).toMatchObject({+ kind: 'tab-visibility',+ visible: true,+ });+ port.receive({+ ...version,+ kind: 'cache-read-availability',+ ownerEpoch: 1,+ state: 'blocked',+ });+ port.receive({+ ...version,+ kind: 'engine-replaced',+ ownerEpoch: 2,+ openOutcome: 'opened-existing',+ });+ port.receive({+ ...version,+ kind: 'cache-read-availability',+ ownerEpoch: 1,+ state: 'blocked',+ });+ expect(onCacheReadAvailabilityChanged).toHaveBeenCalledExactlyOnceWith(+ 'blocked'+ );+ port.receive({+ ...version,+ kind: 'cache-read-availability',+ ownerEpoch: 2,+ state: 'ready',+ });+ expect(onCacheReadAvailabilityChanged).toHaveBeenLastCalledWith('ready');+ await adapter.dispose({ graceful: false });+ expect(detached).toHaveBeenCalledWith(+ 'visibilitychange',+ expect.any(Function)+ );+ });+it('forwards startup phases once, ignores stale epochs, and rejects a backwards phase', async () => {const port = new FakeCoordinatorPort();const progress = vi.fn();diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.tsindex 236cf9af64..fb05212c33 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@@ -9,6 +9,7 @@ import {} from '../telemetry';import {CACHE_COORDINATOR_PROTOCOL_VERSION,+ type CacheReadState,type CleanupToPageEnvelope,type CoordinatorToTabEnvelope,ENGINE_STARTUP_PHASES,@@ -48,6 +49,9 @@ export interface CacheCoordinatorPageAdapterOptions {scope: string;hotCapacity?: number;tabId?: string;+ visibility?: Pick<Document, 'visibilityState'> &+ Pick<EventTarget, 'addEventListener' | 'removeEventListener'>;+ onCacheReadAvailabilityChanged?: (state: CacheReadState) => void;createSharedWorker?: (scope: string) => SharedWorkerLike;createDedicatedWorker?: (scope: string,@@ -148,6 +152,21 @@ export class CacheCoordinatorPageAdapter {) => DedicatedWorkerLike;private readonly lockManager: Pick<LockManager, 'request'> | undefined;private readonly gracefulTimeoutMs: number;+ private readonly visibility: CacheCoordinatorPageAdapterOptions['visibility'];+ private lastVisibility: boolean | undefined;+ private readonly onVisibilityChange = (): void => {+ if (!this.registered || this.closed) return;+ const visible = this.visibility?.visibilityState !== 'hidden';+ if (visible === this.lastVisibility) return;+ this.lastVisibility = visible;+ this.postCoordinator(+ withVersion<TabToCoordinatorEnvelope>({+ kind: 'tab-visibility',+ tabId: this.tabId,+ visible,+ })+ );+ };private coordinatorConnection: CoordinatorConnection | undefined;private engineWorker: DedicatedWorkerLike | undefined;private ownerEpoch: number | undefined;@@ -166,6 +185,7 @@ export class CacheCoordinatorPageAdapter {private readonly terminatedOwnerEpochs = new Set<number>();private highestOwnerEpochSeen = 0;private latestEngineReplacedEpoch = 0;+ private latestReadStateEpoch = 0;private startupProgress:| Extract<CoordinatorToTabEnvelope, { kind: 'engine-startup' }>| undefined;@@ -185,6 +205,9 @@ export class CacheCoordinatorPageAdapter {throw new Error('hot capacity must be a positive integer');}this.tabId = options.tabId ?? crypto.randomUUID();+ this.visibility =+ options.visibility ??+ (typeof document === 'undefined' ? undefined : document);this.createSharedWorker =options.createSharedWorker ??((scope) =>@@ -496,12 +519,14 @@ export class CacheCoordinatorPageAdapter {}this.coordinatorConnection = { worker, transport };void transport.ready.catch(() => undefined);+ this.lastVisibility = this.visibility?.visibilityState !== 'hidden';this.postCoordinator(withVersion<TabToCoordinatorEnvelope>({kind: 'register-tab',scope: this.options.scope,tabId: this.tabId,livenessLockName,+ visible: this.lastVisibility,hotCapacity: this.options.hotCapacity,buildTime: this.options.buildTime ?? APP_BUILD_TIME,})@@ -515,6 +540,18 @@ export class CacheCoordinatorPageAdapter {return;}const message = parsed.value;+ if (message.kind === 'cache-read-availability') {+ if (!this.registered) {+ this.failTerminal(new Error('owner handoff preceded registration'));+ } else if (+ message.ownerEpoch >=+ Math.max(this.latestEngineReplacedEpoch, this.latestReadStateEpoch)+ ) {+ this.latestReadStateEpoch = message.ownerEpoch;+ this.options.onCacheReadAvailabilityChanged?.(message.state);+ }+ return;+ }switch (message.kind) {case 'registered':if (message.tabId !== this.tabId || this.registered) {@@ -528,6 +565,11 @@ export class CacheCoordinatorPageAdapter {this.resolveRegistration = undefined;this.rejectRegistration = undefined;this.registerPagehide();+ this.visibility?.addEventListener(+ 'visibilitychange',+ this.onVisibilityChange+ );+ this.onVisibilityChange();for (const request of this.queuedRequests.splice(0)) {this.postMessage(request);}@@ -615,7 +657,11 @@ export class CacheCoordinatorPageAdapter {break;}case 'engine-replaced':- if (message.ownerEpoch <= this.latestEngineReplacedEpoch) return;+ if (+ message.ownerEpoch <= this.latestEngineReplacedEpoch ||+ message.ownerEpoch < this.latestReadStateEpoch+ )+ return;this.latestEngineReplacedEpoch = message.ownerEpoch;this.highestOwnerEpochSeen = Math.max(this.highestOwnerEpochSeen,@@ -983,6 +1029,10 @@ export class CacheCoordinatorPageAdapter {}private closeCoordinatorPort(): void {+ this.visibility?.removeEventListener(+ 'visibilitychange',+ this.onVisibilityChange+ );const connection = this.coordinatorConnection;this.coordinatorConnection = undefined;if (!connection) return;diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-parking.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-parking.test.tsnew file mode 100644index 0000000000..7bf3e56d47--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-parking.test.ts@@ -0,0 +1,187 @@+import { expect, it } from 'vitest';+import { CoordinatorCore } from './coordinator-core';++function ready(core: CoordinatorCore, tabId: string, ownerEpoch: number) {+ core.beginOwnerLockWait(tabId, ownerEpoch);+ core.beginEngineOpen(tabId, ownerEpoch);+ return core.engineReady({+ tabId,+ ownerEpoch,+ ownerLockName: 'lock',+ expectedOwnerLockName: 'lock',+ ownerLockHeld: true,+ databaseActionProof: 'opened-existing',+ openOutcome: 'opened-existing',+ });+}++it('parks a hidden first registration without opening storage and wakes only on visibility', () => {+ const core = new CoordinatorCore('scope');+ expect(core.registerTab('a', false)).toEqual([]);+ expect(core.state).toEqual({+ kind: 'parked',+ nextDatabaseAction: 'open-existing',+ });+ expect(core.snapshot().ownerEpoch).toBe(0);+ expect(core.request('a', { id: 1, kind: 'init', scope: 'scope' })).toEqual(+ []+ );+ expect(core.registerTab('b', false)).toEqual([]);+ expect(core.setTabVisibility('a', false)).toEqual([]);+ expect(core.setTabVisibility('b', true)).toEqual([+ {+ kind: 'elect-owner',+ tabId: 'b',+ ownerEpoch: 1,+ databaseAction: 'open-existing',+ },+ ]);+ expect(ready(core, 'b', 1)).toMatchObject([+ { kind: 'route-request', requesterTabId: 'a', request: { kind: 'init' } },+ ]);+});++it('closes on last-visible exit, keeps clients, and routes an old settlement before a new claim', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a');+ ready(core, 'a', 1);+ core.registerTab('b', false);+ core.setTabVisibility('a', false);+ expect(core.state.kind).toBe('draining');+ expect(core.engineDrained('a', 1)).toEqual([+ { kind: 'close-engine-route', tabId: 'a', ownerEpoch: 1 },+ { kind: 'release-owner', tabId: 'a', ownerEpoch: 1 },+ ]);+ expect(core.state).toEqual({+ kind: 'parked',+ nextDatabaseAction: 'open-existing',+ });+ expect(core.snapshot().tabIds).toEqual(['a', 'b']);+ expect(+ core.request('a', {+ id: 3,+ kind: 'commit-optimistic-write',+ transactionId: '1',+ leaseOwner: 'a',+ leaseGeneration: '1',+ query: 'mutation Saved { saved }',+ data: { saved: true },+ })+ ).toEqual([]);+ expect(core.request('b', { id: 4, kind: 'current-revision' })).toEqual([]);+ expect(core.setTabVisibility('b', true)).toEqual([+ {+ kind: 'elect-owner',+ tabId: 'b',+ ownerEpoch: 2,+ databaseAction: 'open-existing',+ },+ ]);+ expect(+ core.request('b', {+ id: 5,+ kind: 'claim-next-mutation',+ owner: 'b',+ nowMs: 600_000,+ leaseExpiresAtMs: 900_000,+ })+ ).toEqual([]);+ const actions = ready(core, 'b', 2);+ expect(+ actions+ .filter((action) => action.kind === 'route-request')+ .map((action) => action.request.kind)+ ).toEqual([+ 'commit-optimistic-write',+ 'current-revision',+ 'claim-next-mutation',+ ]);+ expect(core.snapshot().queuedRequestCount).toBe(0);+});++it('retains an accepted settlement after its caller leaves, without retaining abandoned reads', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a');+ ready(core, 'a', 1);+ core.registerTab('b', false);+ core.setTabVisibility('a', false);+ core.engineDrained('a', 1);+ core.request('a', {+ id: 7,+ kind: 'commit-optimistic-write',+ transactionId: '1',+ leaseOwner: 'a',+ leaseGeneration: '1',+ query: 'mutation Saved { saved }',+ data: { saved: true },+ });+ core.request('a', { id: 8, kind: 'current-revision' });+ core.tabLost('a');+ expect(core.snapshot().queuedRequestCount).toBe(1);+ core.setTabVisibility('b', true);+ const routes = ready(core, 'b', 2).filter(+ (action) => action.kind === 'route-request'+ );+ expect(routes).toHaveLength(1);+ const route = routes[0];+ if (!route) throw new Error('missing retained settlement');+ expect(route.request.kind).toBe('commit-optimistic-write');+ expect(+ core.engineResponse(2, route.routeId, {+ id: route.routeId,+ ok: true,+ result: null,+ })+ ).toEqual([]);+ expect(core.snapshot().inFlightRequestCount).toBe(0);+});++it('does not cancel a storage open on hide and parks only after its drain acknowledgement', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a');+ core.beginOwnerLockWait('a', 1);+ core.beginEngineOpen('a', 1);+ expect(core.setTabVisibility('a', false)).toEqual([+ { kind: 'handoff-pending', ownerEpoch: 1 },+ ]);+ expect(core.state).toMatchObject({+ kind: 'activating',+ phase: 'opening-database',+ });+ const actions = core.engineReady({+ tabId: 'a',+ ownerEpoch: 1,+ ownerLockName: 'lock',+ expectedOwnerLockName: 'lock',+ ownerLockHeld: true,+ databaseActionProof: 'opened-existing',+ openOutcome: 'opened-existing',+ });+ expect(actions).toEqual([+ { kind: 'drain-owner', tabId: 'a', ownerEpoch: 1, handoff: true },+ ]);+ expect(core.snapshot().ownerEpoch).toBe(1);+ core.engineDrained('a', 1);+ expect(core.state.kind).toBe('parked');+});++it('retains a real abrupt-loss reset requirement through all-hidden recovery', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a');+ ready(core, 'a', 1);+ core.setTabVisibility('a', false);+ core.ownerLost('a', 1, 'runtime failure');+ expect(core.resumeAfterLoss()).toEqual([]);+ expect(core.state).toEqual({+ kind: 'parked',+ nextDatabaseAction: 'wipe-before-open',+ });+ expect(core.setTabVisibility('a', true)).toEqual([+ {+ kind: 'elect-owner',+ tabId: 'a',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ },+ ]);+});diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.tsindex 14919d469d..8a62dc3875 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@@ -525,6 +525,7 @@ describe('coordinator runtime protocol', () => {scope: 'scope',tabId: 'tab',livenessLockName: 'graphql-cache-tab:scope:tab',+ visible: true,buildTime: 1_790_000_000_000,},{@@ -777,6 +778,7 @@ describe('coordinator runtime protocol', () => {scope: 'scope',tabId: 'tab',livenessLockName: 'lock',+ visible: true,buildTime: 0,}).ok).toBe(false);@@ -788,6 +790,7 @@ describe('coordinator runtime protocol', () => {scope: 'scope',tabId: 'tab',livenessLockName: 'lock',+ visible: true,}).ok).toBe(false);expect(diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.tsindex 45f8aa5509..e3851e4830 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts@@ -23,7 +23,7 @@ import {export { isCachePush, isCacheResponse, isWorkerMessage };/** Version of the topology envelope and routed cache RPC surface. */-export const CACHE_COORDINATOR_PROTOCOL_VERSION = 8 as const;+export const CACHE_COORDINATOR_PROTOCOL_VERSION = 10 as const;/*** Startup phases in order. The engine may touch storage only in* `opening-database`, which begins once it holds the database owner lock. It@@ -41,6 +41,9 @@ export const ENGINE_STARTUP_PHASES: readonly EngineStartupPhase[] = ['opening-database',];+/** Waiting queues reads without a deadline; blocked permits read-only fallback. */+export type CacheReadState = 'ready' | 'waiting' | 'blocked';+export type OwnerEpoch = number;export type RouteId = number;export type DatabaseAction = 'open-existing' | 'wipe-before-open';@@ -61,12 +64,19 @@ export type ActivationFailureCode =| 'storage-busy';export type TabToCoordinatorEnvelope =+ | {+ coordinatorVersion: typeof CACHE_COORDINATOR_PROTOCOL_VERSION;+ kind: 'tab-visibility';+ tabId: string;+ visible: boolean;+ }| {coordinatorVersion: typeof CACHE_COORDINATOR_PROTOCOL_VERSION;kind: 'register-tab';scope: string;tabId: string;livenessLockName: string;+ visible: boolean;hotCapacity?: number;/** When the page's app build was made, in ms since the epoch; 0 if* unstamped. A newer build takes the database over from an older one. */@@ -113,6 +123,13 @@ export type TabToCoordinatorEnvelope =};export type CoordinatorToTabEnvelope =+ | {+ coordinatorVersion: typeof CACHE_COORDINATOR_PROTOCOL_VERSION;+ kind: 'cache-read-availability';+ /** Zero is valid only for an initially parked scope with no engine yet. */+ ownerEpoch: OwnerEpoch;+ state: CacheReadState;+ }| {coordinatorVersion: typeof CACHE_COORDINATOR_PROTOCOL_VERSION;kind: 'registered';@@ -832,10 +849,26 @@ export function validateTabToCoordinatorEnvelope(if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {return fail('invalid coordinator envelope header');}- const base =- value.coordinatorVersion === CACHE_COORDINATOR_PROTOCOL_VERSION &&- isNonEmptyString(value.tabId);- if (!base) return fail('invalid coordinator tab identity');+ if (+ value.coordinatorVersion !== CACHE_COORDINATOR_PROTOCOL_VERSION ||+ !isNonEmptyString(value.tabId)+ )+ return fail('invalid coordinator tab identity');+ if (value.kind === 'tab-visibility') {+ return hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'tabId',+ 'visible',+ ]) && typeof value.visible === 'boolean'+ ? pass({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ kind: 'tab-visibility',+ tabId: value.tabId,+ visible: value.visible,+ })+ : fail('invalid tab-visibility coordinator envelope');+ }switch (value.kind) {case 'register-tab':@@ -846,11 +879,13 @@ export function validateTabToCoordinatorEnvelope('scope','tabId','livenessLockName',+ 'visible','hotCapacity','buildTime',]) &&isNonEmptyString(value.scope) &&isNonEmptyString(value.livenessLockName) &&+ typeof value.visible === 'boolean' &&isOptionalPositiveInteger(value.hotCapacity) &&isSafeNonNegativeInteger(value.buildTime)) {@@ -947,6 +982,26 @@ export function validateCoordinatorToTabEnvelope(if (!isRecord(value) || !hasVersion(value) || !isString(value.kind)) {return fail('invalid coordinator envelope header');}+ if (value.kind === 'cache-read-availability') {+ return hasOnlyKeys(value, [+ 'coordinatorVersion',+ 'kind',+ 'ownerEpoch',+ 'state',+ ]) &&+ isSafeNonNegativeInteger(value.ownerEpoch) &&+ (value.state === 'waiting' ||+ value.state === 'blocked' ||+ value.state === 'ready') &&+ (value.ownerEpoch > 0 || value.state === 'waiting')+ ? pass({+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ kind: 'cache-read-availability',+ ownerEpoch: value.ownerEpoch,+ state: value.state,+ })+ : fail('invalid cache-read-availability coordinator envelope');+ }switch (value.kind) {case 'registered':if (diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.tsindex b21f8d9f10..092a17144e 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts@@ -3,6 +3,7 @@ import { INITIAL_CACHE_REVISION } from '../protocol';import {CACHE_COORDINATOR_PROTOCOL_VERSION,databaseOwnerLockName,+ type EngineOpenOutcome,} from './coordinator-protocol';import {type CoordinatorMessagePort,@@ -72,6 +73,7 @@ const register = async (scope: 'scope',tabId,livenessLockName: `graphql-cache-tab:scope:${tabId}`,+ visible: true,buildTime,});};@@ -97,7 +99,10 @@ const ready = (enginePort: FakePort,tabId: string,ownerEpoch: number,- proof: 'opened-existing' | 'wiped-before-open'+ proof: 'opened-existing' | 'wiped-before-open',+ openOutcome: EngineOpenOutcome = proof === 'wiped-before-open'+ ? 'reset-storage-uncertain'+ : 'opened-existing'): void => {const sent = (kind: string) =>enginePort.received.some(@@ -127,10 +132,7 @@ const ready = (ownerLockName: databaseOwnerLockName('scope'),ownerLockHeld: true,databaseActionProof: proof,- openOutcome:- proof === 'wiped-before-open'- ? 'reset-storage-uncertain'- : 'opened-existing',+ openOutcome,});};@@ -232,6 +234,140 @@ describe('CoordinatorRouter', () => {]);});+ it.each([+ { planned: true, blocked: false },+ { planned: false, blocked: false },+ { planned: true, blocked: true },+ ])(+ 'records a reset completed by an immediately draining owner (planned: $planned, blocked: $blocked)',+ async ({ planned, blocked }) => {+ vi.useFakeTimers();+ const observations: Array<Record<string, unknown>> = [];+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => undefined,+ telemetry: { record: (event) => observations.push(event), flush() {} },+ handoffReadTimeoutMs: 0,+ });+ const tabA = new FakePort();+ const tabB = new FakePort();+ const engineA = new FakePort();+ await register(router, tabA, 'tab-a');+ await register(router, tabB, 'tab-b');+ await attach(router, tabA, 'tab-a', 1, engineA);+ ready(engineA, 'tab-a', 1, 'opened-existing');+ await router.handleTabMessage(tabA, {+ ...version,+ kind: planned ? 'engine-lost' : 'navigation-departure',+ tabId: 'tab-a',+ ownerEpoch: 1,+ reason: 'old owner left',+ });+ const engineB = new FakePort();+ await attach(router, tabB, 'tab-b', 2, engineB);+ if (planned && !blocked)+ await router.handleTabMessage(tabA, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'tab-a',+ visible: false,+ });+ await router.handleTabMessage(tabB, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'tab-b',+ visible: false,+ });+ await router.handleTabMessage(tabB, {+ ...version,+ kind: 'cache-request',+ tabId: 'tab-b',+ request: { id: 99, kind: 'current-revision' },+ });+ await vi.advanceTimersByTimeAsync(0);+ const outcome = planned ? 'reset-storage-uncertain' : 'reset-corrupt';+ ready(engineB, 'tab-b', 2, 'wiped-before-open', outcome);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'draining',+ ownerEpoch: 2,+ });+ expect(messagesOfKind(engineB, 'engine-request')).toEqual([]);+ expect(messagesOfKind(tabB, 'engine-replaced')).toMatchObject([+ { ownerEpoch: 2, openOutcome: outcome },+ ]);+ // Hosts learn the reset, but must not resume reads against the draining owner.+ const resetIndex = tabB.events.lastIndexOf('post:engine-replaced');+ expect(tabB.events[resetIndex + 1]).toBe('post:cache-read-availability');+ expect(+ messagesOfKind(tabB, 'cache-read-availability').at(-1)+ ).toMatchObject({+ ownerEpoch: 2,+ state: blocked ? 'blocked' : 'waiting',+ });+ const reason = planned ? 'abrupt-owner-loss' : 'integrity-failure';+ for (const name of [+ 'graphql_cache.storage_reset_required',+ 'graphql_cache.logical_reset',+ 'graphql_cache.reset_wipe',+ ]) {+ expect(+ observations.filter((event) => event.name === name)+ ).toMatchObject([{ resetReason: reason }]);+ }+ const wipes = observations.filter(+ (event) => event.name === 'graphql_cache.reset_wipe'+ );+ expect(wipes).toMatchObject([+ { outcome: 'success', openOutcome: outcome },+ ]);+ if (planned) {+ expect(wipes[0]).toHaveProperty('resetAttempt', 'wipe-before-open');+ // A later drain failure must not retroactively fail the completed reset.+ engineB.receive({+ ...version,+ kind: 'engine-fatal',+ tabId: 'tab-b',+ ownerEpoch: 2,+ reason: 'drain failed after ready',+ fatalCode: 'runtime-failure',+ });+ expect(+ observations.filter(+ (event) => event.name === 'graphql_cache.reset_wipe'+ )+ ).toEqual(wipes);+ } else {+ expect(wipes[0]).not.toHaveProperty('resetAttempt');+ engineB.receive({+ ...version,+ kind: 'engine-drained',+ tabId: 'tab-b',+ ownerEpoch: 2,+ });+ expect(router.snapshot()?.state.kind).toBe('parked');+ await router.handleTabMessage(tabB, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'tab-b',+ visible: true,+ });+ const engineC = new FakePort();+ await attach(router, tabB, 'tab-b', 3, engineC);+ ready(engineC, 'tab-b', 3, 'opened-existing');+ expect(messagesOfKind(tabB, 'engine-replaced')).toMatchObject([+ { ownerEpoch: 2, openOutcome: 'reset-corrupt' },+ { ownerEpoch: 3, openOutcome: 'opened-existing' },+ ]);+ expect(messagesOfKind(engineC, 'engine-request')).toHaveLength(1);+ expect(+ observations.filter(+ (event) => event.name === 'graphql_cache.reset_wipe'+ )+ ).toEqual(wipes);+ }+ }+ );+it('backs off repeated recovery attempts and terminal-fails at the retry limit', async () => {vi.useFakeTimers();const router = new CoordinatorRouter({@@ -374,6 +510,7 @@ describe('CoordinatorRouter', () => {scope: 'scope',tabId: 'stale-tab',livenessLockName: 'graphql-cache-tab:scope:stale-tab',+ visible: true,buildTime: 0,});@@ -1580,6 +1717,103 @@ describe('CoordinatorRouter', () => {});});+ it('pauses a hidden storage-open watchdog without treating suspension as a failure', async () => {+ vi.useFakeTimers();+ const router = new CoordinatorRouter({+ assetLoadTimeoutMs: 10,+ activationTimeoutMs: 10,+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => undefined,+ });+ const owner = new FakePort();+ const engine = new FakePort();+ await register(router, owner, 'owner');+ await attach(router, owner, 'owner', 1, engine);+ engine.receive({+ ...version,+ kind: 'engine-assets-ready',+ tabId: 'owner',+ ownerEpoch: 1,+ });+ engine.receive({+ ...version,+ kind: 'owner-lock-acquired',+ tabId: 'owner',+ ownerEpoch: 1,+ });+ await router.handleTabMessage(owner, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'owner',+ visible: false,+ });+ await vi.advanceTimersByTimeAsync(60_000);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ phase: 'opening-database',+ });+ expect(messagesOfKind(owner, 'terminate-engine')).toEqual([]);+ await router.handleTabMessage(owner, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'owner',+ visible: true,+ });+ await vi.advanceTimersByTimeAsync(11);+ expect(messagesOfKind(owner, 'terminate-engine')).toHaveLength(1);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'activating',+ ownerEpoch: 2,+ databaseAction: 'wipe-before-open',+ });+ });++ it('resumes bounded startup reads when the original owner becomes visible before readiness', async () => {+ vi.useFakeTimers();+ const router = new CoordinatorRouter({+ verifyTabLockHeld: async () => true,+ watchTabLock: () => () => undefined,+ });+ const owner = new FakePort();+ const client = new FakePort();+ const engine = new FakePort();+ await register(router, owner, 'owner');+ await attach(router, owner, 'owner', 1, engine);+ await register(router, client, 'client');+ await router.handleTabMessage(owner, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'owner',+ visible: false,+ });+ await vi.advanceTimersByTimeAsync(1000);+ expect(messagesOfKind(client, 'cache-read-availability')).toMatchObject([+ { ownerEpoch: 1, state: 'waiting' },+ { ownerEpoch: 1, state: 'blocked' },+ ]);+ expect(messagesOfKind(owner, 'terminate-engine')).toEqual([]);+ expect(messagesOfKind(client, 'become-owner')).toEqual([]);+ expect(router.snapshot()?.state.kind).toBe('activating');+ await router.handleTabMessage(owner, {+ ...version,+ kind: 'tab-visibility',+ tabId: 'owner',+ visible: true,+ });+ ready(engine, 'owner', 1, 'opened-existing');+ expect(messagesOfKind(client, 'cache-read-availability')).toMatchObject([+ { ownerEpoch: 1, state: 'waiting' },+ { ownerEpoch: 1, state: 'blocked' },+ { ownerEpoch: 1, state: 'ready' },+ ]);+ expect(messagesOfKind(client, 'engine-replaced')).toEqual([]);+ expect(router.snapshot()?.state).toMatchObject({+ kind: 'active',+ tabId: 'owner',+ ownerEpoch: 1,+ });+ });+it('preserves the owner and in-flight work through repeated missed heartbeats', async () => {vi.useFakeTimers();const verifyLockHeld = vi.fn(async () => true);@@ -1943,6 +2177,7 @@ describe('CoordinatorRouter', () => {scope: 'scope',tabId: 'tab-a',livenessLockName: 'graphql-cache-tab:scope:tab-a',+ visible: true,buildTime: 0,});await vi.waitFor(() =>diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.tsindex fb4369eed8..69bd02bd63 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts@@ -18,6 +18,10 @@ import {type CoordinatorSnapshot,startupPhaseMayTouchStorage,} from './coordinator-core';+import {+ CoordinatorHandoff,+ OWNER_HANDOFF_READ_TIMEOUT_MS,+} from './coordinator-handoff';import {type ActivationFailureCode,CACHE_COORDINATOR_PROTOCOL_VERSION,@@ -73,6 +77,7 @@ export interface CoordinatorRouterOptions {activationTimeoutMs?: number;heartbeatIntervalMs?: number;heartbeatTimeoutMs?: number;+ handoffReadTimeoutMs?: number;verifyTabLockHeld?: (lockName: string) => Promise<boolean>;verifyOwnerLockHeld?: (lockName: string) => Promise<boolean>;/** Names of every Web Lock currently held in this storage partition. */@@ -257,6 +262,7 @@ export class CoordinatorRouter {private readonly clearTimeoutFn: typeof globalThis.clearTimeout;private readonly queueMicrotaskFn: typeof globalThis.queueMicrotask;private readonly telemetry: CacheTelemetryRecorderLike;+ private readonly handoff: CoordinatorHandoff;private readonly routeStarted = new Map<number,{@@ -310,6 +316,20 @@ export class CoordinatorRouter {? workerCacheTelemetry(): NOOP_CACHE_TELEMETRY));+ this.handoff = new CoordinatorHandoff({+ timeoutMs: options.handoffReadTimeoutMs ?? OWNER_HANDOFF_READ_TIMEOUT_MS,+ setTimeout: this.setTimeoutFn,+ clearTimeout: this.clearTimeoutFn,+ now: this.now,+ telemetry: this.telemetry,+ onChange: (availability) =>+ this.broadcast(+ envelope<CoordinatorToTabEnvelope>({+ kind: 'cache-read-availability',+ ...availability,+ })+ ),+ });}get core(): CoordinatorCore | undefined {@@ -387,6 +407,9 @@ export class CoordinatorRouter {}match(message)+ .with({ kind: 'tab-visibility' }, ({ visible }) => {+ this.applyActions(core.setTabVisibility(tabId, visible));+ }).with({ kind: 'cache-request' }, ({ request }) => {this.applyActions(core.request(tabId, request));})@@ -530,8 +553,19 @@ export class CoordinatorRouter {) {this.resetRecoveryRetries();}- const actions = this.coreValue.registerTab(message.tabId);+ const actions = this.coreValue.registerTab(message.tabId, message.visible);+ const previousReadState = this.handoff.readState;this.applyActions(actions);+ const readState = this.handoff.readState;+ // A changed state was already broadcast to this registered connection.+ if (readState !== undefined && readState === previousReadState)+ this.postToTab(+ message.tabId,+ envelope<CoordinatorToTabEnvelope>({+ kind: 'cache-read-availability',+ ...readState,+ })+ );// Late joiners must use the same startup budget as the elected owner.if (!actions.some((action) => action.kind === 'elect-owner')) {const progress = this.startupProgress();@@ -678,27 +712,9 @@ export class CoordinatorRouter {const violated = actions.some((action) => action.kind === 'protocol-violation');- this.applyActions(actions);- if (violated) {- if (this.isCurrentOwner(route.tabId, route.ownerEpoch)) {- this.failOwner(- route.tabId,- route.ownerEpoch,- 'engine readiness proof was rejected'- );- } else {- this.postTerminateEngine(- route.tabId,- route.ownerEpoch,- 'engine readiness proof was rejected'- );- }- break;- }- if (- core.state.kind === 'active' &&- core.state.ownerEpoch === message.ownerEpoch- ) {+ if (!violated) {+ // Accepted readiness proves the storage outcome even if visibility+ // immediately drains this epoch or publishing its actions fails.const recoveryResetReason = this.pendingRecoveryResetEpochs.get(message.ownerEpoch);@@ -721,6 +737,28 @@ export class CoordinatorRouter {false);}+ }+ this.applyActions(actions);+ if (violated) {+ if (this.isCurrentOwner(route.tabId, route.ownerEpoch)) {+ this.failOwner(+ route.tabId,+ route.ownerEpoch,+ 'engine readiness proof was rejected'+ );+ } else {+ this.postTerminateEngine(+ route.tabId,+ route.ownerEpoch,+ 'engine readiness proof was rejected'+ );+ }+ break;+ }+ if (+ core.state.kind === 'active' &&+ core.state.ownerEpoch === message.ownerEpoch+ ) {const startedAt = this.activationStarted.get(message.ownerEpoch);this.activationStarted.delete(message.ownerEpoch);this.telemetry.record({@@ -904,7 +942,14 @@ export class CoordinatorRouter {: { errorCode: action.errorCode }),});break;+ case 'handoff-pending':+ this.handoff.start(action.ownerEpoch, core.hasVisibleTab);+ break;case 'drain-owner': {+ if (action.handoff)+ this.handoff.start(action.ownerEpoch, core.hasVisibleTab);+ this.clearActivationTimer();+ this.activationStarted.delete(action.ownerEpoch);this.telemetry.record({name: 'graphql_cache.owner',operationCategory: 'lifecycle',@@ -950,6 +995,13 @@ export class CoordinatorRouter {case 'drop-tab':this.removeTabConnection(action.tabId);break;+ case 'release-owner':+ this.postTerminateEngine(+ action.tabId,+ action.ownerEpoch,+ 'visibility handoff drained'+ );+ break;case 'retire-tab':this.postToTab(action.tabId,@@ -989,7 +1041,7 @@ export class CoordinatorRouter {}));break;- case 'broadcast-engine-replaced':+ case 'broadcast-engine-replaced': {this.telemetry.record({name: 'graphql_cache.owner',operationCategory: 'lifecycle',@@ -1003,7 +1055,19 @@ export class CoordinatorRouter {openOutcome: action.openOutcome,}));+ // Replacement invalidates host generations and resumes their reads.+ // Reassert the existing pause when this epoch is already draining.+ const readState = this.handoff.readState;+ if (core.state.kind === 'draining' && readState) {+ this.broadcast(+ envelope<CoordinatorToTabEnvelope>({+ kind: 'cache-read-availability',+ ...readState,+ })+ );+ }break;+ }case 'drop-stale-engine-message':this.telemetry.record({name: 'graphql_cache.stale_drop',@@ -1033,6 +1097,7 @@ export class CoordinatorRouter {);break;case 'terminal-failure':+ this.handoff.cancel();this.broadcast(envelope<CoordinatorToTabEnvelope>({kind: 'terminal-error',@@ -1043,6 +1108,41 @@ export class CoordinatorRouter {break;}}+ this.syncReadAvailability();+ }++ private syncReadAvailability(): void {+ const core = this.coreValue;+ if (!core) return;+ match(core.state)+ .with({ kind: 'parked' }, () =>+ this.handoff.park(core.snapshot().ownerEpoch)+ )+ .with({ kind: 'activating' }, ({ tabId, ownerEpoch }) => {+ if (!core.hasVisibleTab) this.clearActivationTimer();+ else if (this.activationTimer === undefined)+ this.armStartupWatchdog(tabId, ownerEpoch);+ if (this.handoff.transitioning)+ this.handoff.start(ownerEpoch, core.hasVisibleTab);+ })+ .with({ kind: 'draining' }, ({ ownerEpoch }) => {+ if (this.handoff.transitioning)+ this.handoff.start(ownerEpoch, core.hasVisibleTab);+ })+ .with({ kind: 'active' }, ({ ownerEpoch }) =>+ this.handoff.ready(ownerEpoch)+ )+ .with(+ { kind: 'waiting-for-tab' },+ { kind: 'resetting-after-loss' },+ { kind: 'failed' },+ () => this.handoff.cancel()+ )+ .exhaustive(() =>+ this.applyActions(+ core.terminalFailure('unrecognized coordinator ownership state')+ )+ );}private startupProgress():@@ -1070,6 +1170,9 @@ export class CoordinatorRouter {const progress = this.startupProgress();if (!progress) return;this.broadcast(progress);+ // A hidden startup may be suspended by the browser while we wait to park+ // it. Resume the phase budget when there is a visible consumer again.+ if (!this.coreValue?.hasVisibleTab) return;const { phase, timeoutMs } = progress;this.activationTimer = this.setTimeoutFn(() => {this.failOwner(@@ -1148,6 +1251,7 @@ export class CoordinatorRouter {? core.storageBusy(tabId, ownerEpoch): core.ownerLockUnavailable(tabId, ownerEpoch);if (actions.length === 0) return;+ this.handoff.cancel();this.activationStarted.delete(ownerEpoch);// Storage was not changed, or a busy wipe removed only part of it, so a// pending recovery wipe carries over to the next attempt exactly as after@@ -1251,6 +1355,7 @@ export class CoordinatorRouter {if (!core) return;const actions = core.ownerLost(tabId, ownerEpoch, reason);if (actions.length === 0) return;+ this.handoff.cancel();this.activationStarted.delete(ownerEpoch);const next = core.state;if (@@ -1307,6 +1412,7 @@ export class CoordinatorRouter {const state = core.state;const isCurrentOwner =state.kind !== 'waiting-for-tab' &&+ state.kind !== 'parked' &&state.kind !== 'resetting-after-loss' &&state.kind !== 'failed' &&state.tabId === tabId &&@@ -1353,10 +1459,12 @@ export class CoordinatorRouter {const state = core.state;if (state.kind !== 'waiting-for-tab' &&+ state.kind !== 'parked' &&state.kind !== 'resetting-after-loss' &&state.kind !== 'failed' &&state.tabId === tabId) {+ this.handoff.cancel();this.activationStarted.delete(state.ownerEpoch);if (state.kind !== 'activating' ||@@ -1471,6 +1579,7 @@ export class CoordinatorRouter {return Boolean(state &&state.kind !== 'waiting-for-tab' &&+ state.kind !== 'parked' &&state.kind !== 'resetting-after-loss' &&state.kind !== 'failed' &&state.tabId === tabId &&diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-visibility.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-visibility.test.tsnew file mode 100644index 0000000000..7da06856f7--- /dev/null+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-visibility.test.ts@@ -0,0 +1,171 @@+import { describe, expect, it } from 'vitest';+import { CoordinatorCore } from './coordinator-core';+import {+ CACHE_COORDINATOR_PROTOCOL_VERSION,+ validateCoordinatorToTabEnvelope,+ validateTabToCoordinatorEnvelope,+} from './coordinator-protocol';++function ready(core: CoordinatorCore, tabId: string, ownerEpoch: number) {+ core.beginOwnerLockWait(tabId, ownerEpoch);+ core.beginEngineOpen(tabId, ownerEpoch);+ return core.engineReady({+ tabId,+ ownerEpoch,+ ownerLockName: 'lock',+ expectedOwnerLockName: 'lock',+ ownerLockHeld: true,+ databaseActionProof: 'opened-existing',+ openOutcome: 'opened-existing',+ });+}++describe('visibility ownership', () => {+ it('validates visibility and handoff epoch messages without accepting extra fields', () => {+ const visibility = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ kind: 'tab-visibility',+ tabId: 'a',+ visible: false,+ };+ expect(validateTabToCoordinatorEnvelope(visibility).ok).toBe(true);+ expect(+ validateTabToCoordinatorEnvelope({ ...visibility, visible: 'hidden' }).ok+ ).toBe(false);+ expect(+ validateTabToCoordinatorEnvelope({ ...visibility, ownerEpoch: 1 }).ok+ ).toBe(false);+ const blocked = {+ coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,+ kind: 'cache-read-availability',+ ownerEpoch: 1,+ state: 'blocked',+ };+ expect(validateCoordinatorToTabEnvelope(blocked).ok).toBe(true);+ expect(+ validateCoordinatorToTabEnvelope({ ...blocked, ownerEpoch: 0 }).ok+ ).toBe(false);+ expect(+ validateCoordinatorToTabEnvelope({+ ...blocked,+ ownerEpoch: 0,+ state: 'waiting',+ }).ok+ ).toBe(true);+ expect(+ validateCoordinatorToTabEnvelope({ ...blocked, state: 'invalid' }).ok+ ).toBe(false);+ expect(+ validateCoordinatorToTabEnvelope({ ...blocked, visible: false }).ok+ ).toBe(false);+ });+ it('keeps a visible owner but starts parking on the last visible tab exit', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a', true);+ ready(core, 'a', 1);+ expect(core.registerTab('b', true)).toEqual([]);+ expect(core.setTabVisibility('b', false)).toEqual([]);+ expect(core.setTabVisibility('a', false)).toEqual([+ { kind: 'drain-owner', tabId: 'a', ownerEpoch: 1, handoff: true },+ ]);+ expect(core.state).toEqual({ kind: 'draining', tabId: 'a', ownerEpoch: 1 });+ expect(core.setTabVisibility('a', true)).toEqual([]);+ });++ it('drains a hidden owner, keeps its client, and routes waiting work once to a visible survivor', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a', true);+ ready(core, 'a', 1);+ core.registerTab('b', true);+ expect(core.setTabVisibility('a', false)).toEqual([+ { kind: 'drain-owner', tabId: 'a', ownerEpoch: 1, handoff: true },+ ]);+ expect(core.registerTab('c', true)).toEqual([]);+ expect(core.setTabVisibility('a', false)).toEqual([]);+ expect(core.request('a', { id: 8, kind: 'current-revision' })).toEqual([]);+ expect(core.request('b', { id: 9, kind: 'clear' })).toEqual([]);+ expect(core.snapshot().ownerEpoch).toBe(1);+ expect(core.snapshot().queuedRequestCount).toBe(2);++ const drained = core.engineDrained('a', 1);+ expect(drained).toEqual([+ { kind: 'close-engine-route', tabId: 'a', ownerEpoch: 1 },+ { kind: 'release-owner', tabId: 'a', ownerEpoch: 1 },+ {+ kind: 'elect-owner',+ tabId: 'b',+ ownerEpoch: 2,+ databaseAction: 'open-existing',+ },+ ]);+ expect(core.snapshot().tabIds).toEqual(['a', 'b', 'c']);+ const replacement = ready(core, 'b', 2);+ expect(+ replacement.filter((action) => action.kind === 'route-request')+ ).toMatchObject([+ {+ requesterTabId: 'a',+ ownerEpoch: 2,+ request: { kind: 'current-revision' },+ },+ { requesterTabId: 'b', ownerEpoch: 2, request: { kind: 'clear' } },+ ]);+ expect(core.snapshot().queuedRequestCount).toBe(0);+ expect(core.engineDrained('a', 1)).toMatchObject([+ { kind: 'protocol-violation' },+ ]);+ expect(core.setTabVisibility('a', true)).toEqual([]);+ expect(core.state).toEqual({ kind: 'active', tabId: 'b', ownerEpoch: 2 });+ });++ it('chooses from the latest surviving visibility instead of pinning a departed candidate', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a', true);+ ready(core, 'a', 1);+ core.registerTab('b', true);+ core.setTabVisibility('a', false);+ core.registerTab('c', true);+ core.tabLost('b');+ core.setTabVisibility('b', true);+ expect(core.engineDrained('a', 1)).toContainEqual({+ kind: 'elect-owner',+ tabId: 'c',+ ownerEpoch: 2,+ databaseAction: 'open-existing',+ });+ });++ it('defers a startup visibility change until storage is ready to drain', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a', true);+ core.registerTab('b', true);+ expect(core.setTabVisibility('a', false)).toEqual([+ { kind: 'handoff-pending', ownerEpoch: 1 },+ ]);+ expect(core.state.kind).toBe('activating');+ core.request('b', { id: 1, kind: 'clear' });+ expect(ready(core, 'a', 1)).toEqual([+ { kind: 'drain-owner', tabId: 'a', ownerEpoch: 1, handoff: true },+ ]);+ expect(core.snapshot().inFlightRequestCount).toBe(0);+ core.engineDrained('a', 1);+ expect(+ ready(core, 'b', 2).filter((action) => action.kind === 'route-request')+ ).toHaveLength(1);+ });++ it('lets explicit disposal join a handoff without draining twice', () => {+ const core = new CoordinatorCore('scope');+ core.registerTab('a', true);+ ready(core, 'a', 1);+ core.registerTab('b', true);+ core.setTabVisibility('a', false);+ expect(core.beginGracefulDeparture('a', 1)).toEqual([]);+ expect(core.engineDrained('a', 1)).toContainEqual({+ kind: 'retire-tab',+ tabId: 'a',+ ownerEpoch: 1,+ });+ expect(core.snapshot().tabIds).toEqual(['b']);+ });+});diff --git a/docs/agent-guide/navigation.md b/docs/agent-guide/navigation.mdindex 3deaacc434..0d4449b516 100644--- a/docs/agent-guide/navigation.md+++ b/docs/agent-guide/navigation.md@@ -47,6 +47,23 @@ queued mutations should resume promptly, without waiting for the old poll orlocal 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.+Browser cache ownership prefers a visible tab. When the owner hides, its engine+cooperatively drains and closes storage; if every app tab is hidden, storage parks+without retiring their clients or reloading pages. Background cache work waits.+Returning to any tab opens the same database in a visible owner. A visible owner+is not moved just because another visible window gets focus. Reads can wait for+normal warmup; if foreground handoff/resume exceeds one second, ordinary queries+use network fallback while cache-only reads never forward. Writes and received+mutation confirmations wait for storage instead of being sent twice.++Verify the all-hidden case without activating the former owner: no held physical+owner lock after parking, preserved generation/queue, and successful reads/writes+from a returning tab. Also verify a pending HTTP response settling after parking+and multiple surviving clients. A drain that Safari has already suspended still+waits for that worker to resume; no deadline kills it or steals its lock. Lifecycle+telemetry uses `park-started`, `parked`, `unpark-started`, `unpark-completed`, and+`visibility-handoff-*` owner events.+Safari can also restart the SharedWorker when its creating tab closes, leavinganother tab's port alive but its coordinator registrations gone. The survivingpage must re-register without a reload or cache wipe. Open two tabs, close the@@ -56,6 +73,12 @@ optimistic enqueues must not be sent twice. A `graphql_cache.owner` event with`ownerEvent: coordinator-restarted` distinguishes this from engine replacementor a BFCache restore.+The same write-safety rule applies when an owner navigates away without restarting+the coordinator: a surviving tab's enqueue may be committed even if its reply was+lost. It must report an uncertain outcome, not retry or fall through to a second+API write. Verify this lost-reply case only with an isolated synthetic fixture,+not by injecting mutation failures into a dev or production account.+## Android system navigation and sharingIn the Android app, Back first hides the keyboard, then dismisses the active