Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Seanaye/fix/cache parking (#8825)

Sean Ayec01b3b0a65b3
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 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 old
engine and re-register in place, preserving durable storage and never replaying
uncertain 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.md
index 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 Lock
without waiting or stealing it; a held lock (or a failed probe) retries the
heartbeat without changing epochs or touching storage. A released lock confirms
silent 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 transport
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
index 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 reached
diff --git a/apps/web/src/lib/graphql-cache/host/read-availability.test.ts b/apps/web/src/lib/graphql-cache/host/read-availability.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.html
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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 or
local retry timer; durable leases and server-retry deadlines still apply.
Switching tabs or navigating an in-app route is not a back/forward-cache restore.
+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, leaving
another tab's port alive but its coordinator registrations gone. The surviving
page 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 replacement
or 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 sharing
In the Android app, Back first hides the keyboard, then dismisses the active