@aglyn/tenant-feature-instance 1.0.0-beta.143

package/src/lib/hooks/firebase/firestore-cache.d.ts

@@ -0,0 +1,125 @@
+import { type FirebaseApp } from 'firebase/app';
+import { type FirestoreLocalCache } from 'firebase/firestore';
+import { type AuthPersistenceClass } from './auth-persistence';
+import { type SharedClientStatePrunePlan } from './firestore-shared-client-state';
+/**
+ * The durable cache's size bound: the SDK's own default, 40 MB, written down.
+ * See "The durable cache's size" on {@link localCacheFor}.
+ */
+export declare const DURABLE_CACHE_SIZE_BYTES: number;
+/**
+ * The Firestore `localCache` an origin of this persistence class may use
+ * (AGL-1456).
+ *
+ * ## Why this keys off the *auth* persistence class
+ *
+ * The name is historical — the class predates this file (AGL-1379) — but the
+ * question it answers was never auth-specific. `AuthPersistenceClass` is
+ * documented as *"how much of a session an origin is allowed to keep"*, and
+ * AGL-1099a's D6 justified `ephemeral` on the grounds that **"the customer can
+ * re-point the DNS and read this origin."**
+ *
+ * That reasoning does not stop at the credential. It is equally true of every
+ * document body Firestore caches in IndexedDB on that origin — measured, not
+ * argued: the PoC (`docs/design/agl-1099a-poc-findings.md` §5) dumped every
+ * object store on the origin and found full document contents under
+ * `firestore/<app>/<project>/main → remoteDocumentsV14`, alongside
+ * `firestore_clients_*` / `firestore_online_state_*` /
+ * `firestore_sequence_number_*` in `localStorage`. D6 hardened the key and
+ * left the safe behind it open; this closes it.
+ *
+ * **One declaration, two consequences — deliberately.** A separate
+ * `firestoreCache` prop would let a caller declare a custom console domain
+ * `ephemeral` for auth and still hand it a persistent cache, which is exactly
+ * the split that produced this bug. There is one fact about the origin, so
+ * there is one place to state it.
+ *
+ * ## The two classes
+ *
+ * - `durable` → `persistentLocalCache` with the multi-tab manager. Unchanged
+ *   from what every host has always run, and it must stay that way:
+ *   `*.aglyn.com` / `*.aglyn.app` are ours forever, and this cache is part of
+ *   why console read volume is what it is (AGL-1440).
+ * - `ephemeral` → `memoryLocalCache`, so **nothing** reaches disk on an origin
+ *   whose DNS the customer can re-point at their own server.
+ *
+ * ## The durable cache's size
+ *
+ * `cacheSizeBytes` is spelled out at the SDK default so the bound is stated
+ * here and cannot quietly become `CACHE_SIZE_UNLIMITED` if that default moves.
+ * Stating it changes nothing at runtime, and what it governs is narrower than
+ * the name suggests — measured against `@firebase/firestore` 4.17.1:
+ *
+ * - LRU collection is on without it: an unset `cacheSizeBytes` resolves to
+ *   `LruParams.DEFAULT`, the same 40 MB threshold.
+ * - It runs only in the tab holding the primary lease, 1 minute after that tab
+ *   becomes primary and every 5 minutes after.
+ * - The threshold is compared with the byte size of **cached documents**
+ *   (`remoteDocumentsV14`) and nothing else. `targets` and `targetDocuments`
+ *   rows are collected alongside documents once documents cross it, never
+ *   before.
+ * - It never touches `localStorage`, where the multi-tab manager strands a
+ *   record per tab and per query target; {@link pruneSharedClientStateFor}
+ *   handles those.
+ *
+ * It is deliberately not lowered. A smaller cache evicts exactly the documents
+ * that make this cache worth having — a cold load resuming from disk, and
+ * listeners painting through a stale session — and a collected target is given
+ * a NEW id the next time its query is listened to, which adds a `localStorage`
+ * record rather than removing one.
+ *
+ * ## Why the memory cache gets the LRU collector, not the default
+ *
+ * `memoryLocalCache()` defaults to `memoryEagerGarbageCollector`, which drops
+ * a document the moment no listener references it — so navigating away from a
+ * console page and back re-reads its whole working set from the server. The
+ * LRU collector keeps documents in the JS heap up to its 40 MB default instead,
+ * which recovers most of the intra-session read saving `persistentLocalCache`
+ * was giving us.
+ *
+ * It costs nothing against the property being protected: the LRU collector is
+ * still **memory only**. Nothing is written to IndexedDB, nothing survives a
+ * tab close, and a page load on a re-pointed origin starts empty — the same
+ * bound `inMemoryPersistence` gives the refresh token.
+ *
+ * The read cost that remains is real and is the stated trade: a **cold** page
+ * load on a custom console domain re-reads its working set where a durable
+ * origin would have resumed from disk, and multiple tabs no longer share one
+ * backend connection through `persistentMultipleTabManager`. That is the right
+ * trade for an Enterprise-only feature, but it is a trade.
+ *
+ * ## `Failed to obtain primary lease for action '…'` is not a bug to fix
+ *
+ * Exactly one open tab holds the IndexedDB primary lease and applies remote
+ * events; the rest read the results it writes. When the lease changes hands —
+ * a tab opening, closing, or coming back to the foreground — a transaction
+ * already in flight on the losing tab finds itself no longer primary, and the
+ * SDK `logError`s that message immediately before throwing a
+ * `failed-precondition` that its OWN multi-tab sync engine catches
+ * (`ignoreIfPrimaryLeaseLoss`) and downgrades to a debug line. The tab then
+ * continues as a secondary. Nothing is dropped and no listener stops.
+ *
+ * It is therefore noise from a handled handoff, and it scales with how many
+ * tabs are churning rather than with anything the console does. The message
+ * names a lease, so the obvious reading is that the multi-tab manager is
+ * missing and should be added — it is already here, which is why the message
+ * appears at all: `persistentSingleTabManager` refuses the second tab's
+ * persistence outright instead of sharing it. Confirmed at runtime by the
+ * `owner` record in `firestore/<app>/<project>/main`, which carries
+ * `allowTabSynchronization: true`.
+ */
+export declare function localCacheFor(originClass: AuthPersistenceClass): FirestoreLocalCache;
+/**
+ * Prunes the multi-tab records the durable cache strands in `localStorage`
+ * (AGL-2845), for an app whose Firestore this page has just initialized.
+ *
+ * Keyed off the same origin class as {@link localCacheFor}, because the
+ * durable class is the only one running `persistentMultipleTabManager`, the
+ * only writer of those records. An ephemeral origin's memory cache writes
+ * none, so it resolves without looking.
+ *
+ * Fire-and-forget: it never rejects and nothing waits on it. What it deletes,
+ * and why a live tab's records never are, is in
+ * `firestore-shared-client-state.ts`.
+ */
+export declare function pruneSharedClientStateFor(originClass: AuthPersistenceClass, app: FirebaseApp): Promise<SharedClientStatePrunePlan | undefined>;

package/src/lib/hooks/firebase/firestore-cache.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { memoryLocalCache, memoryLruGarbageCollector, persistentLocalCache, persistentMultipleTabManager } from "firebase/firestore";
+import { pruneBrowserSharedClientState } from "./firestore-shared-client-state.js";
+/**
+ * The durable cache's size bound: the SDK's own default, 40 MB, written down.
+ * See "The durable cache's size" on {@link localCacheFor}.
+ */ export const DURABLE_CACHE_SIZE_BYTES = 40 * 1024 * 1024;
+/**
+ * The Firestore `localCache` an origin of this persistence class may use
+ * (AGL-1456).
+ *
+ * ## Why this keys off the *auth* persistence class
+ *
+ * The name is historical — the class predates this file (AGL-1379) — but the
+ * question it answers was never auth-specific. `AuthPersistenceClass` is
+ * documented as *"how much of a session an origin is allowed to keep"*, and
+ * AGL-1099a's D6 justified `ephemeral` on the grounds that **"the customer can
+ * re-point the DNS and read this origin."**
+ *
+ * That reasoning does not stop at the credential. It is equally true of every
+ * document body Firestore caches in IndexedDB on that origin — measured, not
+ * argued: the PoC (`docs/design/agl-1099a-poc-findings.md` §5) dumped every
+ * object store on the origin and found full document contents under
+ * `firestore/<app>/<project>/main → remoteDocumentsV14`, alongside
+ * `firestore_clients_*` / `firestore_online_state_*` /
+ * `firestore_sequence_number_*` in `localStorage`. D6 hardened the key and
+ * left the safe behind it open; this closes it.
+ *
+ * **One declaration, two consequences — deliberately.** A separate
+ * `firestoreCache` prop would let a caller declare a custom console domain
+ * `ephemeral` for auth and still hand it a persistent cache, which is exactly
+ * the split that produced this bug. There is one fact about the origin, so
+ * there is one place to state it.
+ *
+ * ## The two classes
+ *
+ * - `durable` → `persistentLocalCache` with the multi-tab manager. Unchanged
+ *   from what every host has always run, and it must stay that way:
+ *   `*.aglyn.com` / `*.aglyn.app` are ours forever, and this cache is part of
+ *   why console read volume is what it is (AGL-1440).
+ * - `ephemeral` → `memoryLocalCache`, so **nothing** reaches disk on an origin
+ *   whose DNS the customer can re-point at their own server.
+ *
+ * ## The durable cache's size
+ *
+ * `cacheSizeBytes` is spelled out at the SDK default so the bound is stated
+ * here and cannot quietly become `CACHE_SIZE_UNLIMITED` if that default moves.
+ * Stating it changes nothing at runtime, and what it governs is narrower than
+ * the name suggests — measured against `@firebase/firestore` 4.17.1:
+ *
+ * - LRU collection is on without it: an unset `cacheSizeBytes` resolves to
+ *   `LruParams.DEFAULT`, the same 40 MB threshold.
+ * - It runs only in the tab holding the primary lease, 1 minute after that tab
+ *   becomes primary and every 5 minutes after.
+ * - The threshold is compared with the byte size of **cached documents**
+ *   (`remoteDocumentsV14`) and nothing else. `targets` and `targetDocuments`
+ *   rows are collected alongside documents once documents cross it, never
+ *   before.
+ * - It never touches `localStorage`, where the multi-tab manager strands a
+ *   record per tab and per query target; {@link pruneSharedClientStateFor}
+ *   handles those.
+ *
+ * It is deliberately not lowered. A smaller cache evicts exactly the documents
+ * that make this cache worth having — a cold load resuming from disk, and
+ * listeners painting through a stale session — and a collected target is given
+ * a NEW id the next time its query is listened to, which adds a `localStorage`
+ * record rather than removing one.
+ *
+ * ## Why the memory cache gets the LRU collector, not the default
+ *
+ * `memoryLocalCache()` defaults to `memoryEagerGarbageCollector`, which drops
+ * a document the moment no listener references it — so navigating away from a
+ * console page and back re-reads its whole working set from the server. The
+ * LRU collector keeps documents in the JS heap up to its 40 MB default instead,
+ * which recovers most of the intra-session read saving `persistentLocalCache`
+ * was giving us.
+ *
+ * It costs nothing against the property being protected: the LRU collector is
+ * still **memory only**. Nothing is written to IndexedDB, nothing survives a
+ * tab close, and a page load on a re-pointed origin starts empty — the same
+ * bound `inMemoryPersistence` gives the refresh token.
+ *
+ * The read cost that remains is real and is the stated trade: a **cold** page
+ * load on a custom console domain re-reads its working set where a durable
+ * origin would have resumed from disk, and multiple tabs no longer share one
+ * backend connection through `persistentMultipleTabManager`. That is the right
+ * trade for an Enterprise-only feature, but it is a trade.
+ *
+ * ## `Failed to obtain primary lease for action '…'` is not a bug to fix
+ *
+ * Exactly one open tab holds the IndexedDB primary lease and applies remote
+ * events; the rest read the results it writes. When the lease changes hands —
+ * a tab opening, closing, or coming back to the foreground — a transaction
+ * already in flight on the losing tab finds itself no longer primary, and the
+ * SDK `logError`s that message immediately before throwing a
+ * `failed-precondition` that its OWN multi-tab sync engine catches
+ * (`ignoreIfPrimaryLeaseLoss`) and downgrades to a debug line. The tab then
+ * continues as a secondary. Nothing is dropped and no listener stops.
+ *
+ * It is therefore noise from a handled handoff, and it scales with how many
+ * tabs are churning rather than with anything the console does. The message
+ * names a lease, so the obvious reading is that the multi-tab manager is
+ * missing and should be added — it is already here, which is why the message
+ * appears at all: `persistentSingleTabManager` refuses the second tab's
+ * persistence outright instead of sharing it. Confirmed at runtime by the
+ * `owner` record in `firestore/<app>/<project>/main`, which carries
+ * `allowTabSynchronization: true`.
+ */ export function localCacheFor(originClass) {
+    if (originClass === 'ephemeral') {
+        return memoryLocalCache({
+            garbageCollector: memoryLruGarbageCollector()
+        });
+    }
+    return persistentLocalCache({
+        tabManager: persistentMultipleTabManager(),
+        cacheSizeBytes: DURABLE_CACHE_SIZE_BYTES
+    });
+}
+/**
+ * Prunes the multi-tab records the durable cache strands in `localStorage`
+ * (AGL-2845), for an app whose Firestore this page has just initialized.
+ *
+ * Keyed off the same origin class as {@link localCacheFor}, because the
+ * durable class is the only one running `persistentMultipleTabManager`, the
+ * only writer of those records. An ephemeral origin's memory cache writes
+ * none, so it resolves without looking.
+ *
+ * Fire-and-forget: it never rejects and nothing waits on it. What it deletes,
+ * and why a live tab's records never are, is in
+ * `firestore-shared-client-state.ts`.
+ */ export function pruneSharedClientStateFor(originClass, app) {
+    var _app_options;
+    if (originClass === 'ephemeral') return Promise.resolve(undefined);
+    return pruneBrowserSharedClientState(app.name, (_app_options = app.options) == null ? void 0 : _app_options.projectId);
+}
+
+//# sourceMappingURL=firestore-cache.js.map

package/src/lib/hooks/firebase/firestore-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-cache.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { type FirebaseApp } from 'firebase/app'\nimport {\n  type FirestoreLocalCache,\n  memoryLocalCache,\n  memoryLruGarbageCollector,\n  persistentLocalCache,\n  persistentMultipleTabManager,\n} from 'firebase/firestore'\n\nimport { type AuthPersistenceClass } from './auth-persistence'\nimport {\n  pruneBrowserSharedClientState,\n  type SharedClientStatePrunePlan,\n} from './firestore-shared-client-state'\n\n/**\n * The durable cache's size bound: the SDK's own default, 40 MB, written down.\n * See \"The durable cache's size\" on {@link localCacheFor}.\n */\nexport const DURABLE_CACHE_SIZE_BYTES = 40 * 1024 * 1024\n\n/**\n * The Firestore `localCache` an origin of this persistence class may use\n * (AGL-1456).\n *\n * ## Why this keys off the *auth* persistence class\n *\n * The name is historical — the class predates this file (AGL-1379) — but the\n * question it answers was never auth-specific. `AuthPersistenceClass` is\n * documented as *\"how much of a session an origin is allowed to keep\"*, and\n * AGL-1099a's D6 justified `ephemeral` on the grounds that **\"the customer can\n * re-point the DNS and read this origin.\"**\n *\n * That reasoning does not stop at the credential. It is equally true of every\n * document body Firestore caches in IndexedDB on that origin — measured, not\n * argued: the PoC (`docs/design/agl-1099a-poc-findings.md` §5) dumped every\n * object store on the origin and found full document contents under\n * `firestore/<app>/<project>/main → remoteDocumentsV14`, alongside\n * `firestore_clients_*` / `firestore_online_state_*` /\n * `firestore_sequence_number_*` in `localStorage`. D6 hardened the key and\n * left the safe behind it open; this closes it.\n *\n * **One declaration, two consequences — deliberately.** A separate\n * `firestoreCache` prop would let a caller declare a custom console domain\n * `ephemeral` for auth and still hand it a persistent cache, which is exactly\n * the split that produced this bug. There is one fact about the origin, so\n * there is one place to state it.\n *\n * ## The two classes\n *\n * - `durable` → `persistentLocalCache` with the multi-tab manager. Unchanged\n *   from what every host has always run, and it must stay that way:\n *   `*.aglyn.com` / `*.aglyn.app` are ours forever, and this cache is part of\n *   why console read volume is what it is (AGL-1440).\n * - `ephemeral` → `memoryLocalCache`, so **nothing** reaches disk on an origin\n *   whose DNS the customer can re-point at their own server.\n *\n * ## The durable cache's size\n *\n * `cacheSizeBytes` is spelled out at the SDK default so the bound is stated\n * here and cannot quietly become `CACHE_SIZE_UNLIMITED` if that default moves.\n * Stating it changes nothing at runtime, and what it governs is narrower than\n * the name suggests — measured against `@firebase/firestore` 4.17.1:\n *\n * - LRU collection is on without it: an unset `cacheSizeBytes` resolves to\n *   `LruParams.DEFAULT`, the same 40 MB threshold.\n * - It runs only in the tab holding the primary lease, 1 minute after that tab\n *   becomes primary and every 5 minutes after.\n * - The threshold is compared with the byte size of **cached documents**\n *   (`remoteDocumentsV14`) and nothing else. `targets` and `targetDocuments`\n *   rows are collected alongside documents once documents cross it, never\n *   before.\n * - It never touches `localStorage`, where the multi-tab manager strands a\n *   record per tab and per query target; {@link pruneSharedClientStateFor}\n *   handles those.\n *\n * It is deliberately not lowered. A smaller cache evicts exactly the documents\n * that make this cache worth having — a cold load resuming from disk, and\n * listeners painting through a stale session — and a collected target is given\n * a NEW id the next time its query is listened to, which adds a `localStorage`\n * record rather than removing one.\n *\n * ## Why the memory cache gets the LRU collector, not the default\n *\n * `memoryLocalCache()` defaults to `memoryEagerGarbageCollector`, which drops\n * a document the moment no listener references it — so navigating away from a\n * console page and back re-reads its whole working set from the server. The\n * LRU collector keeps documents in the JS heap up to its 40 MB default instead,\n * which recovers most of the intra-session read saving `persistentLocalCache`\n * was giving us.\n *\n * It costs nothing against the property being protected: the LRU collector is\n * still **memory only**. Nothing is written to IndexedDB, nothing survives a\n * tab close, and a page load on a re-pointed origin starts empty — the same\n * bound `inMemoryPersistence` gives the refresh token.\n *\n * The read cost that remains is real and is the stated trade: a **cold** page\n * load on a custom console domain re-reads its working set where a durable\n * origin would have resumed from disk, and multiple tabs no longer share one\n * backend connection through `persistentMultipleTabManager`. That is the right\n * trade for an Enterprise-only feature, but it is a trade.\n *\n * ## `Failed to obtain primary lease for action '…'` is not a bug to fix\n *\n * Exactly one open tab holds the IndexedDB primary lease and applies remote\n * events; the rest read the results it writes. When the lease changes hands —\n * a tab opening, closing, or coming back to the foreground — a transaction\n * already in flight on the losing tab finds itself no longer primary, and the\n * SDK `logError`s that message immediately before throwing a\n * `failed-precondition` that its OWN multi-tab sync engine catches\n * (`ignoreIfPrimaryLeaseLoss`) and downgrades to a debug line. The tab then\n * continues as a secondary. Nothing is dropped and no listener stops.\n *\n * It is therefore noise from a handled handoff, and it scales with how many\n * tabs are churning rather than with anything the console does. The message\n * names a lease, so the obvious reading is that the multi-tab manager is\n * missing and should be added — it is already here, which is why the message\n * appears at all: `persistentSingleTabManager` refuses the second tab's\n * persistence outright instead of sharing it. Confirmed at runtime by the\n * `owner` record in `firestore/<app>/<project>/main`, which carries\n * `allowTabSynchronization: true`.\n */\nexport function localCacheFor(\n  originClass: AuthPersistenceClass,\n): FirestoreLocalCache {\n  if (originClass === 'ephemeral') {\n    return memoryLocalCache({ garbageCollector: memoryLruGarbageCollector() })\n  }\n  return persistentLocalCache({\n    tabManager: persistentMultipleTabManager(),\n    cacheSizeBytes: DURABLE_CACHE_SIZE_BYTES,\n  })\n}\n\n/**\n * Prunes the multi-tab records the durable cache strands in `localStorage`\n * (AGL-2845), for an app whose Firestore this page has just initialized.\n *\n * Keyed off the same origin class as {@link localCacheFor}, because the\n * durable class is the only one running `persistentMultipleTabManager`, the\n * only writer of those records. An ephemeral origin's memory cache writes\n * none, so it resolves without looking.\n *\n * Fire-and-forget: it never rejects and nothing waits on it. What it deletes,\n * and why a live tab's records never are, is in\n * `firestore-shared-client-state.ts`.\n */\nexport function pruneSharedClientStateFor(\n  originClass: AuthPersistenceClass,\n  app: FirebaseApp,\n): Promise<SharedClientStatePrunePlan | undefined> {\n  if (originClass === 'ephemeral') return Promise.resolve(undefined)\n  return pruneBrowserSharedClientState(app.name, app.options?.projectId)\n}\n"],"names":["memoryLocalCache","memoryLruGarbageCollector","persistentLocalCache","persistentMultipleTabManager","pruneBrowserSharedClientState","DURABLE_CACHE_SIZE_BYTES","localCacheFor","originClass","garbageCollector","tabManager","cacheSizeBytes","pruneSharedClientStateFor","app","Promise","resolve","undefined","name","options","projectId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAGA,SAEEA,gBAAgB,EAChBC,yBAAyB,EACzBC,oBAAoB,EACpBC,4BAA4B,QACvB,qBAAoB;AAG3B,SACEC,6BAA6B,QAExB,qCAAiC;AAExC;;;CAGC,GACD,OAAO,MAAMC,2BAA2B,KAAK,OAAO,KAAI;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoGC,GACD,OAAO,SAASC,cACdC,WAAiC;IAEjC,IAAIA,gBAAgB,aAAa;QAC/B,OAAOP,iBAAiB;YAAEQ,kBAAkBP;QAA4B;IAC1E;IACA,OAAOC,qBAAqB;QAC1BO,YAAYN;QACZO,gBAAgBL;IAClB;AACF;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASM,0BACdJ,WAAiC,EACjCK,GAAgB;QAG+BA;IAD/C,IAAIL,gBAAgB,aAAa,OAAOM,QAAQC,OAAO,CAACC;IACxD,OAAOX,8BAA8BQ,IAAII,IAAI,GAAEJ,eAAAA,IAAIK,OAAO,qBAAXL,aAAaM,SAAS;AACvE"}

package/src/lib/hooks/firebase/firestore-shared-client-state.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The multi-tab records the Firestore SDK strands in `localStorage`, and the
+ * prune that bounds them (AGL-2845).
+ *
+ * ## What leaks
+ *
+ * `persistentMultipleTabManager` shares one IndexedDB cache between tabs and
+ * coordinates them through `localStorage` (`WebStorageSharedClientState`).
+ * Three of its record families grow without bound, all keyed under the
+ * persistence prefix `firestore/<appName>/<projectId>/`:
+ *
+ * | record | holds |
+ * | -- | -- |
+ * | `firestore_clients_<prefix>_<clientId>` | the target ids one tab listens to, and when that set last changed |
+ * | `firestore_targets_<prefix>_<targetId>` | a target's `current` / `not-current` / `rejected` state, written by the primary tab |
+ * | `firestore_zombie_<prefix>_<clientId>` | when a tab closed, so no other tab waits on its lease |
+ *
+ * Measured against `@firebase/firestore` 4.17.1, and unchanged on the SDK's
+ * main branch, a target record is removed in exactly one place:
+ * `clearQueryState`, which runs only when the PRIMARY tab unlistens a target no
+ * other tab holds. Every other way a target ends leaves its record behind:
+ *
+ * - a secondary tab unlistens — the primary releases the target and never
+ *   clears its state;
+ * - the backend rejects the listen — `rejected` is written and nothing removes
+ *   it, so a missing composite index or a `permission-denied` stays on disk;
+ * - any tab closes or reloads — `pagehide` removes that tab's own client record
+ *   and none of its targets.
+ *
+ * A client record is stranded the same way when a tab ends without `pagehide`
+ * (a crash, a discarded tab, a browser quit), and a zombie marker survives
+ * whenever its tab's shutdown does not finish and no primary later finds that
+ * tab's heartbeat row. Nothing sweeps any of the three. A target id is reused
+ * for an identical query, so the pile grows with the number of distinct queries
+ * a browser has ever listened to: one production console profile held 2,531
+ * target records going back five weeks, against 3 live tabs.
+ *
+ * ## Why it cannot be left alone
+ *
+ * `localStorage` holds about 5 MB per origin. Once it is full, the next
+ * `setItem` inside the SDK throws `QuotaExceededError` on the SDK's async
+ * queue. That marks the queue failed, and every later Firestore operation in
+ * the tab dies on `INTERNAL ASSERTION FAILED: Unexpected state (ID: b815)` — the
+ * whole Firestore client, not only tab sync. Upstream treats a full
+ * `localStorage` as expected under multi-tab (firebase-js-sdk#8305) and closed
+ * the leak report without a fix (#9209), so no SDK upgrade removes this.
+ *
+ * ## What is safe to delete
+ *
+ * The constraint is absolute: a record a live tab depends on is never removed.
+ *
+ * - **A target record no surviving client record lists is dead data.** The SDK
+ *   reads one only when some tab lists that target as active
+ *   (`addLocalQueryTarget` asks `isActiveQueryTarget` first), and it ignores a
+ *   storage event reporting one deleted. A record any readable client lists is
+ *   kept, whether or not that client is live: without it, the next tab to join
+ *   the target would start it `not-current`.
+ * - **A client record is deleted only after the SDK itself has given up on that
+ *   tab.** Its heartbeat row must be gone from IndexedDB's `clientMetadata`
+ *   store — a running tab rewrites that row every 4 seconds, and the primary
+ *   deletes rows 30 minutes stale — AND the record must not have changed for
+ *   {@link STALE_SHARED_CLIENT_STATE_MS}. Deleting a live tab's client record
+ *   would make every other tab drop its targets, and the primary would stop
+ *   watching them. The heartbeat is what separates a live tab left idle (fresh
+ *   row, old record) from a dead one; the age covers a tab frozen rather than
+ *   closed, and a tab that started between the heartbeat read and the scan.
+ * - **When the heartbeat cannot be read** — no `indexedDB.databases()`, no
+ *   database yet, a schema without that store — no client record is deleted,
+ *   and every readable client record keeps pinning its targets.
+ * - **A client record that does not parse** pins nothing and is never deleted,
+ *   matching the SDK, which ignores it the same way.
+ * - **A zombie marker older than {@link STALE_SHARED_CLIENT_STATE_MS}** is
+ *   deleted. The SDK consults one only while the closed tab's heartbeat could
+ *   still count as fresh, and a day later it cannot.
+ *
+ * Mutation, online-state, sequence-number and bundle records are never touched,
+ * and neither is anything under another app's or another database's prefix.
+ *
+ * ## When it runs
+ *
+ * Once per page load, after the provider has initialized the durable cache
+ * (`pruneSharedClientStateFor` in `firestore-cache.ts`). Each load clears what
+ * earlier sessions stranded, which is what bounds the growth; a one-off cleanup
+ * would not, because the SDK strands more on every close.
+ */
+/**
+ * How long a client record or zombie marker must sit unchanged before it can
+ * be treated as dead. A day, against the SDK's own 30-minute inactivity
+ * horizon, because deleting a live tab's record is the one outcome this must
+ * never produce.
+ */
+export declare const STALE_SHARED_CLIENT_STATE_MS: number;
+/**
+ * `firestore/<appName>/<projectId>/` — the SDK's `indexedDbStoragePrefix` for
+ * the default database, the only one the console opens. Every record family
+ * above hangs off it, and so does the IndexedDB database, `<prefix>main`.
+ */
+export declare function firestorePersistencePrefix(appName: string, projectId: string): string;
+export interface SharedClientStateTally {
+    kept: number;
+    removed: number;
+}
+export interface SharedClientStatePrunePlan {
+    /** Every record to delete. */
+    remove: string[];
+    targets: SharedClientStateTally;
+    clients: SharedClientStateTally;
+    zombies: SharedClientStateTally;
+    /** Whether the heartbeat was readable — without it no client record is eligible. */
+    heartbeat: boolean;
+}
+/**
+ * Decides what to delete. Reads `storage` and changes nothing.
+ *
+ * `heartbeatClientIds` is the set of client ids that still have a row in the
+ * SDK's `clientMetadata` store, or `undefined` when it could not be read — in
+ * which case no client record is eligible.
+ */
+export declare function planSharedClientStatePrune(storage: Pick<Storage, 'length' | 'key' | 'getItem'>, prefix: string, heartbeatClientIds: ReadonlySet<string> | undefined, now: number): SharedClientStatePrunePlan;
+/**
+ * The client ids that still have a heartbeat row in the SDK's `clientMetadata`
+ * store, or `undefined` when that cannot be established.
+ *
+ * Opens only a database that already exists, at whatever version it already
+ * has: `open(name)` on a missing database would CREATE it at version 1, and the
+ * SDK would then try to migrate a schema that was never written. The connection
+ * serves one read-only request and is closed — at once, too, on
+ * `versionchange`, so it can never hold up the SDK's own upgrade.
+ */
+export declare function readHeartbeatClientIds(factory: IDBFactory | undefined, databaseName: string, timeoutMs?: number): Promise<ReadonlySet<string> | undefined>;
+export interface PruneSharedClientStateOptions {
+    storage: Storage;
+    prefix: string;
+    heartbeatClientIds: () => Promise<ReadonlySet<string> | undefined>;
+    now?: () => number;
+}
+/**
+ * Reads the heartbeat, then plans and deletes in one synchronous pass, so
+ * nothing else in this tab can write a record between the scan and the
+ * deletes. The heartbeat is read BEFORE the scan: a tab that starts in between
+ * shows up with a brand-new record and no heartbeat row, which the age rule
+ * keeps.
+ *
+ * Never rejects. Resolves `undefined` when storage could not be read.
+ */
+export declare function pruneSharedClientState({ storage, prefix, heartbeatClientIds, now, }: PruneSharedClientStateOptions): Promise<SharedClientStatePrunePlan | undefined>;
+/**
+ * {@link pruneSharedClientState} against this page's own `localStorage` and
+ * IndexedDB. Resolves `undefined` off-browser, without an app name or project
+ * id, or where site data is blocked (reading `window.localStorage` throws
+ * there).
+ */
+export declare function pruneBrowserSharedClientState(appName: string | undefined, projectId: string | undefined): Promise<SharedClientStatePrunePlan | undefined>;