@oxy.so/services 9.0.0 → 9.1.0

package/src/ui/hooks/accountQueryPersistence.ts

@@ -8,29 +8,43 @@
  *
  * - Storage is keyed by the account (`oxy_account_queries:<accountId>`), so a
  *   restore can only ever hydrate the account that is signed in.
- * - The buster is the build (`getOxyBuildId`), so no cache written by an older
- *   bundle, in an older shape, is ever served.
- * - On a subject change the declared roots, memory-only ones included, and the
- *   account's paused mutations are dropped
- *   from memory synchronously, before anyone is woken, and the new account's
- *   blob is restored. `isReady()` is false until that restore settles, and
+ * - Queries written by another build are dropped on restore; queued (paused)
+ *   mutations are kept (`persistedQueryCache.ts`).
+ * - On a subject change the account's queries, memory-only ones included, and
+ *   its paused mutations are dropped from memory synchronously, before anyone
+ *   is woken. The leaving account's latest state is written first, a sign-out
+ *   then deletes it, and only then is the next account's blob read.
+ * - `isReady()` is false until the signed-in account's blob is restored, and
  *   `RequireOxyAuth` waits on it, so another account's rows never render.
- * - On sign-out the signed-out account's blob is deleted.
+ *
+ * Every storage operation runs through one queue, in order, and a restore
+ * checks that its account is still the active one in the same tick it hydrates.
  */
 
 import { hashKey, type Mutation, type Query, type QueryClient, type QueryKey } from '@tanstack/react-query';
-import { persistQueryClient } from '@tanstack/react-query-persist-client';
-import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
 import type { StorageInterface } from '../utils/storageHelpers';
-import { getOxyBuildId } from '../utils/buildId';
+import {
+  PERSISTED_QUERY_PREFIXES,
+  SDK_MEMORY_ONLY_ROOTS,
+  hydrateSnapshot,
+  rootOf,
+  snapshot,
+  subscribeSnapshots,
+  type PersistFilters,
+} from './persistedQueryCache';
 
 /** An app's declaration of which data is private to the signed-in account. */
 export interface AccountQueriesConfig {
   /**
    * Query-key roots (`queryKey[0]`) whose data belongs to the signed-in account
-   * and survives a restart.
+   * and survives a restart. `'all'`: every query the app runs, for an app whose
+   * every read may depend on who is signed in, so no root can be forgotten.
+   *
+   * The roots `accounts`, `sessions` and `devices` are reserved for the SDK's
+   * device-level data: an app must not use them. `users` and `privacy` are the
+   * SDK's too, and with `'all'` they are dropped on a switch like the app's.
    */
-  roots: readonly string[];
+  roots: readonly string[] | 'all';
   /**
    * Roots that belong to the account too, but must not be written to disk
    * (signed URLs, AI output, search results): dropped on a switch, never persisted.
@@ -43,6 +57,46 @@ export interface AccountQueriesConfig {
   mutationKeys?: readonly QueryKey[];
 }
 
+/** Which queries and mutations an `AccountQueriesConfig` makes the account's. */
+export interface AccountQueryOwnership {
+  /** Dropped from memory on a subject change. */
+  ownsQuery: (query: Query) => boolean;
+  /** Written to the account's blob. */
+  persistsQuery: (query: Query) => boolean;
+  ownsMutation: (mutation: Mutation) => boolean;
+}
+
+/** SDK roots that hold device-level data, the same whoever is signed in. */
+const DEVICE_ROOTS = new Set(['accounts', 'sessions', 'devices']);
+
+export function accountQueryOwnership(config: AccountQueriesConfig): AccountQueryOwnership {
+  const memoryOnly = new Set([...(config.memoryOnlyRoots ?? []), ...SDK_MEMORY_ONLY_ROOTS]);
+  const sdkRoots = new Set(PERSISTED_QUERY_PREFIXES);
+  const declared = config.roots === 'all' ? null : new Set(config.roots);
+  const mutationHashes = new Set((config.mutationKeys ?? []).map((key) => hashKey(key)));
+
+  const ownsQuery = (query: Query): boolean => {
+    const root = rootOf(query);
+    if (root !== null && memoryOnly.has(root)) return true;
+    if (declared === null) return root === null || !DEVICE_ROOTS.has(root);
+    return root !== null && declared.has(root);
+  };
+  return {
+    ownsQuery,
+    persistsQuery: (query) => {
+      if (!ownsQuery(query)) return false;
+      const root = rootOf(query);
+      if (root === null) return true;
+      // The SDK's own roots stay with the SDK persister.
+      return !memoryOnly.has(root) && (declared !== null || !sdkRoots.has(root));
+    },
+    ownsMutation: (mutation) => {
+      const key = mutation.options.mutationKey;
+      return key !== undefined && mutationHashes.has(hashKey(key));
+    },
+  };
+}
+
 export const ACCOUNT_QUERY_CACHE_KEY = 'oxy_account_queries';
 const ACCOUNT_QUERY_CACHE_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
 const ACCOUNT_QUERY_PERSIST_THROTTLE_MS = 1_000;
@@ -52,12 +106,13 @@ export interface AccountQueryPersistence {
   setStorage(storage: StorageInterface): void;
   /** The signed-in account changed. `null` is a sign-out. Synchronous in-memory reset. */
   activate(accountId: string | null): void;
+  /** The owning provider mounted: restore and persist the active account. */
+  attach(): void;
+  /** The owning provider unmounted: stop touching the client and storage. */
+  detach(): void;
   /** True once the active account's cache is restored (always true signed out). */
   isReady(): boolean;
   subscribe(listener: () => void): () => void;
-  /** Whether a mutation is account-scoped (so the SDK's own persister skips it). */
-  ownsMutation(mutation: Mutation): boolean;
-  dispose(): void;
 }
 
 function storageKeyFor(accountId: string): string {
@@ -68,36 +123,37 @@ export function createAccountQueryPersistence(
   queryClient: QueryClient,
   config: AccountQueriesConfig,
 ): AccountQueryPersistence {
-  const persistedRoots = new Set(config.roots);
-  const accountRoots = new Set([...config.roots, ...(config.memoryOnlyRoots ?? [])]);
-  const mutationHashes = new Set((config.mutationKeys ?? []).map((key) => hashKey(key)));
+  const { ownsQuery, persistsQuery, ownsMutation } = accountQueryOwnership(config);
+  const filters: PersistFilters = {
+    shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
+    shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
+  };
   const listeners = new Set<() => void>();
 
-  let storage: StorageInterface | null = null;
+  let resolveStorage: (storage: StorageInterface) => void = () => undefined;
+  const storageReady = new Promise<StorageInterface>((resolve) => {
+    resolveStorage = resolve;
+  });
+  let hasStorage = false;
+  // Every read, write and delete runs here, in order, once storage exists.
+  let io: Promise<unknown> = storageReady;
+  const enqueue = (operation: (storage: StorageInterface) => Promise<unknown> | unknown) => {
+    io = io
+      .then(() => storageReady)
+      .then(operation)
+      .catch(() => undefined);
+  };
+
+  let attached = false;
   let accountId: string | null = null;
   let restoredFor: string | null = null;
   let generation = 0;
-  let unsubscribePersist: (() => void) | null = null;
-  // The in-flight restore. A new account waits for it, so a late restore can
-  // never hydrate the previous account's rows after the switch.
-  let restoring: Promise<void> = Promise.resolve();
+  let writer: ReturnType<typeof subscribeSnapshots> | null = null;
 
   const notify = () => {
     for (const listener of listeners) listener();
   };
 
-  const rootOf = (query: Query): string | null => {
-    const head = query.queryKey[0];
-    return typeof head === 'string' ? head : null;
-  };
-  const ownsQuery = (query: Query): boolean => accountRoots.has(rootOf(query) ?? '');
-  const persistsQuery = (query: Query): boolean => persistedRoots.has(rootOf(query) ?? '');
-
-  const ownsMutation = (mutation: Mutation): boolean => {
-    const key = mutation.options.mutationKey;
-    return key !== undefined && mutationHashes.has(hashKey(key));
-  };
-
   const dropScopedData = () => {
     queryClient.removeQueries({ predicate: ownsQuery });
     const mutations = queryClient.getMutationCache();
@@ -106,77 +162,76 @@ export function createAccountQueryPersistence(
     }
   };
 
-  const persisterFor = (id: string, target: StorageInterface) =>
-    createAsyncStoragePersister({
-      storage: {
-        getItem: (key) => target.getItem(key),
-        setItem: (key, value) => target.setItem(key, value),
-        removeItem: (key) => target.removeItem(key),
-      },
-      key: storageKeyFor(id),
-      throttleTime: ACCOUNT_QUERY_PERSIST_THROTTLE_MS,
-    });
+  const stopWriting = () => {
+    writer?.unsubscribe();
+    writer = null;
+  };
 
-  const start = () => {
+  const restore = () => {
     const id = accountId;
-    const target = storage;
-    if (!id || !target || unsubscribePersist) return;
+    if (!attached || id === null) return;
     const current = generation;
-    const [unsubscribe, restored] = persistQueryClient({
-      queryClient,
-      persister: persisterFor(id, target),
-      maxAge: ACCOUNT_QUERY_CACHE_MAX_AGE,
-      buster: getOxyBuildId(),
-      dehydrateOptions: {
-        shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
-        shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
-      },
-    });
-    unsubscribePersist = unsubscribe;
-    restoring = restored.catch(() => undefined).then(() => {
+    const key = storageKeyFor(id);
+    enqueue(async (storage) => {
+      const raw = await storage.getItem(key);
+      // Same tick as the hydrate: a switch in between cannot be missed.
       if (current !== generation) return;
+      if (!hydrateSnapshot(queryClient, raw, ACCOUNT_QUERY_CACHE_MAX_AGE) && raw) {
+        await storage.removeItem(key);
+        if (current !== generation) return;
+      }
       restoredFor = id;
+      writer = subscribeSnapshots(queryClient, filters, ACCOUNT_QUERY_PERSIST_THROTTLE_MS, (serialized) => {
+        if (current !== generation) return;
+        enqueue((target) => target.setItem(key, serialized));
+      });
       notify();
     });
   };
 
-  const stop = () => {
-    unsubscribePersist?.();
-    unsubscribePersist = null;
-  };
-
   return {
     setStorage(next) {
-      if (storage) return;
-      storage = next;
-      const current = generation;
-      void restoring.then(() => {
-        if (current === generation) start();
-      });
+      if (hasStorage) return;
+      hasStorage = true;
+      resolveStorage(next);
     },
 
     activate(next) {
       if (next === accountId) return;
       const previous = accountId;
+      // Keep the leaving account's latest state, but only once its own blob was
+      // restored: before that, the cache holds none of it to write.
+      if (previous !== null && restoredFor === previous) {
+        const serialized = snapshot(queryClient, filters);
+        const key = storageKeyFor(previous);
+        enqueue((storage) => storage.setItem(key, serialized));
+      }
       generation += 1;
-      const current = generation;
-      stop();
+      stopWriting();
       dropScopedData();
       accountId = next;
       restoredFor = null;
+      if (next === null && previous !== null) {
+        const key = storageKeyFor(previous);
+        enqueue((storage) => storage.removeItem(key));
+      }
       notify();
+      restore();
+    },
 
-      if (next === null && previous !== null && storage) {
-        void persisterFor(previous, storage).removeClient();
-      }
+    attach() {
+      if (attached) return;
+      attached = true;
+      restore();
+    },
 
-      void restoring.then(() => {
-        if (current !== generation) return;
-        // A restore that was already in flight may have hydrated the previous
-        // account's rows; drop them again before this account's restore.
-        dropScopedData();
-        start();
-      });
+    detach() {
+      if (!attached) return;
+      attached = false;
+      writer?.flush();
+      generation += 1;
+      stopWriting();
+      restoredFor = null;
     },
 
     isReady() {
@@ -189,13 +244,5 @@ export function createAccountQueryPersistence(
         listeners.delete(listener);
       };
     },
-
-    ownsMutation,
-
-    dispose() {
-      generation += 1;
-      stop();
-      listeners.clear();
-    },
   };
 }

package/src/ui/hooks/persistedQueryCache.ts

@@ -0,0 +1,126 @@
+/**
+ * The storage format and restore rules shared by the SDK's two query caches:
+ * the account-agnostic one (`attachQueryPersistence`) and the per-account one
+ * (`createAccountQueryPersistence`).
+ *
+ * A blob is `{ buster, timestamp, clientState }`, TanStack's persisted-client
+ * shape. Restoring it treats its two halves differently:
+ *
+ * - Queries are served before any refetch, so a query written by another
+ *   build, in whatever shape that build used, is dropped (`getOxyBuildId`).
+ * - Paused mutations are the user's queued actions (a star, a send made
+ *   offline). A deploy must not lose them, so they are restored whatever build
+ *   wrote them; the current build's `setMutationDefaults` replays them.
+ */
+
+import {
+  dehydrate,
+  hydrate,
+  type DehydratedState,
+  type Mutation,
+  type Query,
+  type QueryClient,
+} from '@tanstack/react-query';
+import { getOxyBuildId } from '../utils/buildId';
+
+/** The SDK's own account-agnostic query roots, persisted by `attachQueryPersistence`. */
+export const PERSISTED_QUERY_PREFIXES: ReadonlyArray<string> = [
+  'accounts',
+  'users',
+  'sessions',
+  'devices',
+  'privacy',
+];
+
+/**
+ * SDK queries whose data (or key) carries a signed, expiring URL. Never
+ * written to disk: a restored one would serve an expired URL.
+ */
+export const SDK_MEMORY_ONLY_ROOTS: ReadonlyArray<string> = [
+  'assetDownloadUrls',
+  'avatarCropSource',
+  'avatarCropMeasure',
+  'justifiedPhotoDimensions',
+];
+
+export interface PersistFilters {
+  shouldDehydrateQuery: (query: Query) => boolean;
+  shouldDehydrateMutation: (mutation: Mutation) => boolean;
+}
+
+interface PersistedBlob {
+  buster: string;
+  timestamp: number;
+  clientState: DehydratedState;
+}
+
+export function rootOf(query: Query): string | null {
+  const head = query.queryKey[0];
+  return typeof head === 'string' ? head : null;
+}
+
+/** Serialize what the filters select, stamped with this build. */
+export function snapshot(queryClient: QueryClient, filters: PersistFilters): string {
+  const blob: PersistedBlob = {
+    buster: getOxyBuildId(),
+    timestamp: Date.now(),
+    clientState: dehydrate(queryClient, filters),
+  };
+  return JSON.stringify(blob);
+}
+
+/**
+ * Hydrate a stored blob into the client, synchronously, so a caller can check
+ * it is still wanted immediately before. Returns false when there was nothing
+ * usable (absent, unreadable or expired), in which case the caller removes it.
+ */
+export function hydrateSnapshot(queryClient: QueryClient, raw: string | null, maxAge: number): boolean {
+  if (!raw) return false;
+  let blob: PersistedBlob;
+  try {
+    blob = JSON.parse(raw) as PersistedBlob;
+  } catch {
+    return false;
+  }
+  if (!blob?.clientState || typeof blob.timestamp !== 'number' || Date.now() - blob.timestamp > maxAge) {
+    return false;
+  }
+  const sameBuild = blob.buster === getOxyBuildId();
+  hydrate(queryClient, {
+    queries: sameBuild ? blob.clientState.queries : [],
+    mutations: blob.clientState.mutations ?? [],
+  });
+  return true;
+}
+
+/**
+ * Write the filtered cache on every change, at most once per `throttleMs`.
+ * `write` receives the serialized snapshot; `flush()` writes now.
+ */
+export function subscribeSnapshots(
+  queryClient: QueryClient,
+  filters: PersistFilters,
+  throttleMs: number,
+  write: (serialized: string) => void,
+): { flush: () => void; unsubscribe: () => void } {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const flush = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    write(snapshot(queryClient, filters));
+  };
+  const schedule = () => {
+    if (!timer) timer = setTimeout(flush, throttleMs);
+  };
+  const offQueries = queryClient.getQueryCache().subscribe(schedule);
+  const offMutations = queryClient.getMutationCache().subscribe(schedule);
+  return {
+    flush,
+    unsubscribe: () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      offQueries();
+      offMutations();
+    },
+  };
+}

package/src/ui/hooks/queryClient.ts

@@ -5,34 +5,28 @@
  * - TanStack Query with `networkMode: 'offlineFirst'` for queries and mutations
  *   so cached data is served immediately and mutations are queued (paused) while
  *   the browser/device reports offline.
- * - `persistQueryClient(...)` from `@tanstack/react-query-persist-client` so that
- *   query results AND paused mutations survive a cold restart (kill-and-relaunch).
+ * - `attachQueryPersistence(...)` so that query results AND paused mutations
+ *   survive a cold restart (kill-and-relaunch); see `persistedQueryCache.ts`.
  * - `onlineManager` resume hook so paused mutations replay the moment the
  *   network is reported back, even if the host app swapped in a custom
  *   onlineManager implementation.
  *
- * Storage layer:
- * - React Native -> AsyncStorage via `createAsyncStoragePersister`.
- * - Web -> localStorage via `createSyncStoragePersister` (wrapped in the
- *   async persister API for a single call site).
- * - Both adapters are content-shape compatible with our `StorageInterface`.
+ * Storage layer: the platform `StorageInterface` (AsyncStorage on native,
+ * localStorage on web).
  *
  * Whitelist policy:
  * - Persist every account/user/session/privacy query and every queued mutation.
  * - DO NOT persist large list queries (e.g. activity feeds) — they go stale
  *   fast and would balloon storage. Add new keys to `PERSISTED_QUERY_PREFIXES`
- *   when introducing reads that should survive restart.
+ *   (`persistedQueryCache.ts`) when introducing reads that should survive restart.
  */
 
-import { QueryClient, hashKey, onlineManager, type Query, type Mutation, type QueryKey } from '@tanstack/react-query';
-import {
-  persistQueryClient,
-  type PersistedClient,
-} from '@tanstack/react-query-persist-client';
-import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
+import { QueryClient, onlineManager, type Mutation, type Query } from '@tanstack/react-query';
+import type { PersistedClient } from '@tanstack/react-query-persist-client';
 import { isDev } from '@oxy.so/core';
 import type { StorageInterface } from '../utils/storageHelpers';
-import { getOxyBuildId } from '../utils/buildId';
+import { accountQueryOwnership, type AccountQueriesConfig } from './accountQueryPersistence';
+import { PERSISTED_QUERY_PREFIXES, hydrateSnapshot, subscribeSnapshots } from './persistedQueryCache';
 
 const QUERY_CACHE_KEY = 'oxy_query_cache_v3';
 const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -55,59 +49,18 @@ export function shouldRetryQuery(failureCount: number, error: unknown): boolean
 }
 
 /**
- * Query-key prefixes that should survive cold restart. Anything not listed
- * is dropped during dehydration so the persisted blob stays small.
- *
- * Mutations are persisted independently (always) so the offline write queue
- * works regardless of the read whitelist.
- */
-const PERSISTED_QUERY_PREFIXES: ReadonlyArray<string> = [
-  'accounts',
-  'users',
-  'sessions',
-  'devices',
-  'privacy',
-];
-
-/**
- * Adapt our `StorageInterface` (which always returns `null` for missing keys)
- * to TanStack's `AsyncStorage` shape. The two are structurally identical
- * apart from naming; this also gives us a single place to add error
- * suppression if a host platform's storage throws.
- */
-function adaptStorage(storage: StorageInterface): {
-  getItem: (key: string) => Promise<string | null>;
-  setItem: (key: string, value: string) => Promise<void>;
-  removeItem: (key: string) => Promise<void>;
-} {
-  return {
-    getItem: (key) => storage.getItem(key),
-    setItem: (key, value) => storage.setItem(key, value),
-    removeItem: (key) => storage.removeItem(key),
-  };
-}
-
-/**
- * Decide whether a given query should be written to persistent storage.
- *
- * Two gates:
- * 1. The query must be in our prefix whitelist.
- * 2. The query must have completed successfully at least once — there's no
- *    point persisting a `pending`/`error` state, and persisting `error` would
- *    leak failure objects across restarts.
+ * Whether a query belongs in the account-agnostic cache: successful (a
+ * `pending`/`error` state is not worth keeping, and an error would leak
+ * failure objects across restarts) and under one of the SDK's own prefixes.
  */
-function shouldDehydrateQuery(query: Query): boolean {
+function isSharedQuery(query: Query): boolean {
   if (query.state.status !== 'success') {
     return false;
   }
   const head = query.queryKey[0];
-  if (typeof head !== 'string') {
-    return false;
-  }
-  return PERSISTED_QUERY_PREFIXES.includes(head);
+  return typeof head === 'string' && PERSISTED_QUERY_PREFIXES.includes(head);
 }
 
-
 /**
  * Create a QueryClient with offline-first defaults.
  *
@@ -174,10 +127,13 @@ export interface AttachPersistenceResult {
 }
 
 /**
- * Wire `persistQueryClient` to the supplied storage adapter.
+ * Restore, then keep writing, the account-agnostic cache.
  *
- * Returns once the in-flight restore promise is available so callers can
- * `await result.restored` before rendering UI that depends on cached data.
+ * Queries written by another build are dropped; queued mutations are kept
+ * (`persistedQueryCache.ts`). Whatever the app declared account-scoped
+ * (`accountQueries`) is left to `createAccountQueryPersistence`, even under
+ * one of the SDK's prefixes, so private rows never land in the shared blob and
+ * a paused mutation cannot replay twice or under another account.
  *
  * Safe to no-op if `storage` is null/undefined (e.g. server-side render
  * with no host storage).
@@ -185,12 +141,7 @@ export interface AttachPersistenceResult {
 export const attachQueryPersistence = (
   queryClient: QueryClient,
   storage: StorageInterface | null | undefined,
-  /**
-   * Mutation keys the app declared account-scoped (`accountQueries`). Those are
-   * persisted per account by `createAccountQueryPersistence`, never here, so a
-   * paused mutation cannot replay twice or under another account.
-   */
-  accountMutationKeys: readonly QueryKey[] = [],
+  accountQueries?: AccountQueriesConfig,
 ): AttachPersistenceResult => {
   if (!storage) {
     return {
@@ -199,38 +150,44 @@ export const attachQueryPersistence = (
     };
   }
 
-  const persister = createAsyncStoragePersister({
-    storage: adaptStorage(storage),
-    key: QUERY_CACHE_KEY,
-    throttleTime: QUERY_PERSIST_THROTTLE_MS,
-  });
-
-  // Persist every other mutation regardless of status: paused mutations are
-  // exactly the ones that must survive restart to replay when online.
-  const accountScoped = new Set(accountMutationKeys.map((key) => hashKey(key)));
-  const shouldDehydrateMutation = (mutation: Mutation): boolean => {
-    const key = mutation.options.mutationKey;
-    return key === undefined || !accountScoped.has(hashKey(key));
+  const account = accountQueries ? accountQueryOwnership(accountQueries) : null;
+  const filters = {
+    shouldDehydrateQuery: (query: Query) =>
+      isSharedQuery(query) && !(account?.ownsQuery(query) ?? false),
+    // Every other mutation, whatever its status: paused ones are exactly the
+    // ones that must survive a restart to replay when online.
+    shouldDehydrateMutation: (mutation: Mutation) =>
+      !(account?.ownsMutation(mutation) ?? false),
   };
 
-  const [unsubscribe, restored] = persistQueryClient({
-    queryClient,
-    persister,
-    maxAge: QUERY_CACHE_MAX_AGE,
-    buster: getOxyBuildId(),
-    dehydrateOptions: {
-      shouldDehydrateQuery,
-      shouldDehydrateMutation,
-    },
-  });
-
-  restored.catch((error) => {
-    if (isDev()) {
-      console.warn('[QueryClient] Failed to restore persisted cache', error);
+  let stopped = false;
+  let writer: ReturnType<typeof subscribeSnapshots> | null = null;
+  const restored = (async () => {
+    const raw = await storage.getItem(QUERY_CACHE_KEY);
+    if (stopped) return;
+    if (!hydrateSnapshot(queryClient, raw, QUERY_CACHE_MAX_AGE) && raw) {
+      await storage.removeItem(QUERY_CACHE_KEY);
     }
-  });
+  })()
+    .catch((error) => {
+      if (isDev()) {
+        console.warn('[QueryClient] Failed to restore persisted cache', error);
+      }
+    })
+    .then(() => {
+      if (stopped) return;
+      writer = subscribeSnapshots(queryClient, filters, QUERY_PERSIST_THROTTLE_MS, (serialized) => {
+        void Promise.resolve(storage.setItem(QUERY_CACHE_KEY, serialized)).catch(() => undefined);
+      });
+    });
 
-  return { unsubscribe, restored };
+  return {
+    restored,
+    unsubscribe: () => {
+      stopped = true;
+      writer?.unsubscribe();
+    },
+  };
 };
 
 /**