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

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

@@ -0,0 +1,316 @@
+/**
+ * @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 const STALE_SHARED_CLIENT_STATE_MS = 24 * 60 * 60 * 1000;
+/** The IndexedDB store holding one heartbeat row per running tab, keyed by client id. */ const CLIENT_METADATA_STORE = 'clientMetadata';
+/**
+ * `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 function firestorePersistencePrefix(appName, projectId) {
+    return `firestore/${appName}/${projectId}/`;
+}
+/** The SDK's `RemoteClientState` parse: whatever it would reject is `undefined`. */ function parseClientRecord(value) {
+    if (value === null) return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    } catch (unused) {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const { activeTargetIds, updateTimeMs } = parsed;
+    if (!Array.isArray(activeTargetIds) || !activeTargetIds.every(Number.isSafeInteger)) {
+        return undefined;
+    }
+    return {
+        activeTargetIds,
+        updateTimeMs: typeof updateTimeMs === 'number' && Number.isFinite(updateTimeMs) ? updateTimeMs : undefined
+    };
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 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 function planSharedClientStatePrune(storage, prefix, heartbeatClientIds, now) {
+    const escaped = escapeRegExp(prefix);
+    // The SDK's own key shapes: a client id never contains `_`, a target id is digits.
+    const clientKey = new RegExp(`^firestore_clients_${escaped}_([^_]*)$`);
+    const targetKey = new RegExp(`^firestore_targets_${escaped}_(\\d+)$`);
+    const zombieKey = new RegExp(`^firestore_zombie_${escaped}_([^_]*)$`);
+    const isStale = (at)=>at !== undefined && now - at >= STALE_SHARED_CLIENT_STATE_MS;
+    const plan = {
+        remove: [],
+        targets: {
+            kept: 0,
+            removed: 0
+        },
+        clients: {
+            kept: 0,
+            removed: 0
+        },
+        zombies: {
+            kept: 0,
+            removed: 0
+        },
+        heartbeat: heartbeatClientIds !== undefined
+    };
+    const targets = [];
+    const pinned = new Set();
+    for(let index = 0; index < storage.length; index++){
+        const key = storage.key(index);
+        if (key === null) continue;
+        const target = targetKey.exec(key);
+        if (target) {
+            targets.push({
+                key,
+                targetId: Number(target[1])
+            });
+            continue;
+        }
+        const client = clientKey.exec(key);
+        if (client) {
+            const record = parseClientRecord(storage.getItem(key));
+            const dead = record !== undefined && heartbeatClientIds !== undefined && !heartbeatClientIds.has(client[1]) && isStale(record.updateTimeMs);
+            if (dead) {
+                plan.remove.push(key);
+                plan.clients.removed++;
+            } else {
+                plan.clients.kept++;
+                record == null ? void 0 : record.activeTargetIds.forEach((targetId)=>pinned.add(targetId));
+            }
+            continue;
+        }
+        if (zombieKey.test(key)) {
+            const value = storage.getItem(key);
+            if (value !== null && /^\d+$/.test(value) && isStale(Number(value))) {
+                plan.remove.push(key);
+                plan.zombies.removed++;
+            } else {
+                plan.zombies.kept++;
+            }
+        }
+    }
+    // Judged last, once every surviving client record has pinned its targets.
+    for (const { key, targetId } of targets){
+        if (pinned.has(targetId)) {
+            plan.targets.kept++;
+        } else {
+            plan.remove.push(key);
+            plan.targets.removed++;
+        }
+    }
+    return plan;
+}
+/**
+ * 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 async function readHeartbeatClientIds(factory, databaseName, timeoutMs = 5000) {
+    if (!factory || typeof factory.databases !== 'function') return undefined;
+    try {
+        const databases = await factory.databases();
+        if (!databases.some((database)=>database.name === databaseName)) return undefined;
+    } catch (unused) {
+        return undefined;
+    }
+    return new Promise((resolve)=>{
+        let settled = false;
+        const settle = (value, database)=>{
+            database == null ? void 0 : database.close();
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(()=>settle(undefined), timeoutMs);
+        let request;
+        try {
+            request = factory.open(databaseName);
+        } catch (unused) {
+            settle(undefined);
+            return;
+        }
+        // The database was deleted between `databases()` and `open()`: abort the
+        // creation rather than leave the SDK an empty version-1 database.
+        request.onupgradeneeded = ()=>{
+            var _request_transaction;
+            return (_request_transaction = request.transaction) == null ? void 0 : _request_transaction.abort();
+        };
+        request.onerror = ()=>settle(undefined);
+        request.onsuccess = ()=>{
+            const database = request.result;
+            database.onversionchange = ()=>database.close();
+            if (settled || !database.objectStoreNames.contains(CLIENT_METADATA_STORE)) {
+                settle(undefined, database);
+                return;
+            }
+            try {
+                const keys = database.transaction(CLIENT_METADATA_STORE, 'readonly').objectStore(CLIENT_METADATA_STORE).getAllKeys();
+                keys.onsuccess = ()=>settle(new Set(keys.result.filter((key)=>typeof key === 'string')), database);
+                keys.onerror = ()=>settle(undefined, database);
+            } catch (unused) {
+                settle(undefined, database);
+            }
+        };
+    });
+}
+/**
+ * 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 async function pruneSharedClientState({ storage, prefix, heartbeatClientIds, now = Date.now }) {
+    let heartbeat;
+    try {
+        heartbeat = await heartbeatClientIds();
+    } catch (unused) {
+        heartbeat = undefined;
+    }
+    try {
+        const plan = planSharedClientStatePrune(storage, prefix, heartbeat, now());
+        for (const key of plan.remove)storage.removeItem(key);
+        return plan;
+    } catch (unused) {
+        return 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 async function pruneBrowserSharedClientState(appName, projectId) {
+    if (!appName || !projectId || typeof window === 'undefined') return undefined;
+    let storage;
+    let factory;
+    try {
+        storage = window.localStorage;
+        factory = window.indexedDB;
+    } catch (unused) {
+        return undefined;
+    }
+    if (!storage) return undefined;
+    const prefix = firestorePersistencePrefix(appName, projectId);
+    return pruneSharedClientState({
+        storage,
+        prefix,
+        heartbeatClientIds: ()=>readHeartbeatClientIds(factory, `${prefix}main`)
+    });
+}
+
+//# sourceMappingURL=firestore-shared-client-state.js.map

package/src/lib/hooks/firebase/firestore-shared-client-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-shared-client-state.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\n/**\n * The multi-tab records the Firestore SDK strands in `localStorage`, and the\n * prune that bounds them (AGL-2845).\n *\n * ## What leaks\n *\n * `persistentMultipleTabManager` shares one IndexedDB cache between tabs and\n * coordinates them through `localStorage` (`WebStorageSharedClientState`).\n * Three of its record families grow without bound, all keyed under the\n * persistence prefix `firestore/<appName>/<projectId>/`:\n *\n * | record | holds |\n * | -- | -- |\n * | `firestore_clients_<prefix>_<clientId>` | the target ids one tab listens to, and when that set last changed |\n * | `firestore_targets_<prefix>_<targetId>` | a target's `current` / `not-current` / `rejected` state, written by the primary tab |\n * | `firestore_zombie_<prefix>_<clientId>` | when a tab closed, so no other tab waits on its lease |\n *\n * Measured against `@firebase/firestore` 4.17.1, and unchanged on the SDK's\n * main branch, a target record is removed in exactly one place:\n * `clearQueryState`, which runs only when the PRIMARY tab unlistens a target no\n * other tab holds. Every other way a target ends leaves its record behind:\n *\n * - a secondary tab unlistens — the primary releases the target and never\n *   clears its state;\n * - the backend rejects the listen — `rejected` is written and nothing removes\n *   it, so a missing composite index or a `permission-denied` stays on disk;\n * - any tab closes or reloads — `pagehide` removes that tab's own client record\n *   and none of its targets.\n *\n * A client record is stranded the same way when a tab ends without `pagehide`\n * (a crash, a discarded tab, a browser quit), and a zombie marker survives\n * whenever its tab's shutdown does not finish and no primary later finds that\n * tab's heartbeat row. Nothing sweeps any of the three. A target id is reused\n * for an identical query, so the pile grows with the number of distinct queries\n * a browser has ever listened to: one production console profile held 2,531\n * target records going back five weeks, against 3 live tabs.\n *\n * ## Why it cannot be left alone\n *\n * `localStorage` holds about 5 MB per origin. Once it is full, the next\n * `setItem` inside the SDK throws `QuotaExceededError` on the SDK's async\n * queue. That marks the queue failed, and every later Firestore operation in\n * the tab dies on `INTERNAL ASSERTION FAILED: Unexpected state (ID: b815)` — the\n * whole Firestore client, not only tab sync. Upstream treats a full\n * `localStorage` as expected under multi-tab (firebase-js-sdk#8305) and closed\n * the leak report without a fix (#9209), so no SDK upgrade removes this.\n *\n * ## What is safe to delete\n *\n * The constraint is absolute: a record a live tab depends on is never removed.\n *\n * - **A target record no surviving client record lists is dead data.** The SDK\n *   reads one only when some tab lists that target as active\n *   (`addLocalQueryTarget` asks `isActiveQueryTarget` first), and it ignores a\n *   storage event reporting one deleted. A record any readable client lists is\n *   kept, whether or not that client is live: without it, the next tab to join\n *   the target would start it `not-current`.\n * - **A client record is deleted only after the SDK itself has given up on that\n *   tab.** Its heartbeat row must be gone from IndexedDB's `clientMetadata`\n *   store — a running tab rewrites that row every 4 seconds, and the primary\n *   deletes rows 30 minutes stale — AND the record must not have changed for\n *   {@link STALE_SHARED_CLIENT_STATE_MS}. Deleting a live tab's client record\n *   would make every other tab drop its targets, and the primary would stop\n *   watching them. The heartbeat is what separates a live tab left idle (fresh\n *   row, old record) from a dead one; the age covers a tab frozen rather than\n *   closed, and a tab that started between the heartbeat read and the scan.\n * - **When the heartbeat cannot be read** — no `indexedDB.databases()`, no\n *   database yet, a schema without that store — no client record is deleted,\n *   and every readable client record keeps pinning its targets.\n * - **A client record that does not parse** pins nothing and is never deleted,\n *   matching the SDK, which ignores it the same way.\n * - **A zombie marker older than {@link STALE_SHARED_CLIENT_STATE_MS}** is\n *   deleted. The SDK consults one only while the closed tab's heartbeat could\n *   still count as fresh, and a day later it cannot.\n *\n * Mutation, online-state, sequence-number and bundle records are never touched,\n * and neither is anything under another app's or another database's prefix.\n *\n * ## When it runs\n *\n * Once per page load, after the provider has initialized the durable cache\n * (`pruneSharedClientStateFor` in `firestore-cache.ts`). Each load clears what\n * earlier sessions stranded, which is what bounds the growth; a one-off cleanup\n * would not, because the SDK strands more on every close.\n */\n\n/**\n * How long a client record or zombie marker must sit unchanged before it can\n * be treated as dead. A day, against the SDK's own 30-minute inactivity\n * horizon, because deleting a live tab's record is the one outcome this must\n * never produce.\n */\nexport const STALE_SHARED_CLIENT_STATE_MS = 24 * 60 * 60 * 1000\n\n/** The IndexedDB store holding one heartbeat row per running tab, keyed by client id. */\nconst CLIENT_METADATA_STORE = 'clientMetadata'\n\n/**\n * `firestore/<appName>/<projectId>/` — the SDK's `indexedDbStoragePrefix` for\n * the default database, the only one the console opens. Every record family\n * above hangs off it, and so does the IndexedDB database, `<prefix>main`.\n */\nexport function firestorePersistencePrefix(appName: string, projectId: string): string {\n  return `firestore/${appName}/${projectId}/`\n}\n\nexport interface SharedClientStateTally {\n  kept: number\n  removed: number\n}\n\nexport interface SharedClientStatePrunePlan {\n  /** Every record to delete. */\n  remove: string[]\n  targets: SharedClientStateTally\n  clients: SharedClientStateTally\n  zombies: SharedClientStateTally\n  /** Whether the heartbeat was readable — without it no client record is eligible. */\n  heartbeat: boolean\n}\n\ninterface ClientRecord {\n  activeTargetIds: readonly number[]\n  updateTimeMs: number | undefined\n}\n\n/** The SDK's `RemoteClientState` parse: whatever it would reject is `undefined`. */\nfunction parseClientRecord(value: string | null): ClientRecord | undefined {\n  if (value === null) return undefined\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(value)\n  } catch {\n    return undefined\n  }\n  if (typeof parsed !== 'object' || parsed === null) return undefined\n  const { activeTargetIds, updateTimeMs } = parsed as Record<string, unknown>\n  if (!Array.isArray(activeTargetIds) || !activeTargetIds.every(Number.isSafeInteger)) {\n    return undefined\n  }\n  return {\n    activeTargetIds,\n    updateTimeMs:\n      typeof updateTimeMs === 'number' && Number.isFinite(updateTimeMs)\n        ? updateTimeMs\n        : undefined,\n  }\n}\n\nfunction escapeRegExp(text: string): string {\n  return text.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')\n}\n\n/**\n * Decides what to delete. Reads `storage` and changes nothing.\n *\n * `heartbeatClientIds` is the set of client ids that still have a row in the\n * SDK's `clientMetadata` store, or `undefined` when it could not be read — in\n * which case no client record is eligible.\n */\nexport function planSharedClientStatePrune(\n  storage: Pick<Storage, 'length' | 'key' | 'getItem'>,\n  prefix: string,\n  heartbeatClientIds: ReadonlySet<string> | undefined,\n  now: number,\n): SharedClientStatePrunePlan {\n  const escaped = escapeRegExp(prefix)\n  // The SDK's own key shapes: a client id never contains `_`, a target id is digits.\n  const clientKey = new RegExp(`^firestore_clients_${escaped}_([^_]*)$`)\n  const targetKey = new RegExp(`^firestore_targets_${escaped}_(\\\\d+)$`)\n  const zombieKey = new RegExp(`^firestore_zombie_${escaped}_([^_]*)$`)\n  const isStale = (at: number | undefined) =>\n    at !== undefined && now - at >= STALE_SHARED_CLIENT_STATE_MS\n\n  const plan: SharedClientStatePrunePlan = {\n    remove: [],\n    targets: { kept: 0, removed: 0 },\n    clients: { kept: 0, removed: 0 },\n    zombies: { kept: 0, removed: 0 },\n    heartbeat: heartbeatClientIds !== undefined,\n  }\n  const targets: Array<{ key: string; targetId: number }> = []\n  const pinned = new Set<number>()\n\n  for (let index = 0; index < storage.length; index++) {\n    const key = storage.key(index)\n    if (key === null) continue\n\n    const target = targetKey.exec(key)\n    if (target) {\n      targets.push({ key, targetId: Number(target[1]) })\n      continue\n    }\n\n    const client = clientKey.exec(key)\n    if (client) {\n      const record = parseClientRecord(storage.getItem(key))\n      const dead =\n        record !== undefined &&\n        heartbeatClientIds !== undefined &&\n        !heartbeatClientIds.has(client[1]) &&\n        isStale(record.updateTimeMs)\n      if (dead) {\n        plan.remove.push(key)\n        plan.clients.removed++\n      } else {\n        plan.clients.kept++\n        record?.activeTargetIds.forEach((targetId) => pinned.add(targetId))\n      }\n      continue\n    }\n\n    if (zombieKey.test(key)) {\n      const value = storage.getItem(key)\n      if (value !== null && /^\\d+$/.test(value) && isStale(Number(value))) {\n        plan.remove.push(key)\n        plan.zombies.removed++\n      } else {\n        plan.zombies.kept++\n      }\n    }\n  }\n\n  // Judged last, once every surviving client record has pinned its targets.\n  for (const { key, targetId } of targets) {\n    if (pinned.has(targetId)) {\n      plan.targets.kept++\n    } else {\n      plan.remove.push(key)\n      plan.targets.removed++\n    }\n  }\n  return plan\n}\n\n/**\n * The client ids that still have a heartbeat row in the SDK's `clientMetadata`\n * store, or `undefined` when that cannot be established.\n *\n * Opens only a database that already exists, at whatever version it already\n * has: `open(name)` on a missing database would CREATE it at version 1, and the\n * SDK would then try to migrate a schema that was never written. The connection\n * serves one read-only request and is closed — at once, too, on\n * `versionchange`, so it can never hold up the SDK's own upgrade.\n */\nexport async function readHeartbeatClientIds(\n  factory: IDBFactory | undefined,\n  databaseName: string,\n  timeoutMs = 5_000,\n): Promise<ReadonlySet<string> | undefined> {\n  if (!factory || typeof factory.databases !== 'function') return undefined\n  try {\n    const databases = await factory.databases()\n    if (!databases.some((database) => database.name === databaseName)) return undefined\n  } catch {\n    return undefined\n  }\n\n  return new Promise((resolve) => {\n    let settled = false\n    const settle = (value: ReadonlySet<string> | undefined, database?: IDBDatabase) => {\n      database?.close()\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      resolve(value)\n    }\n    const timer = setTimeout(() => settle(undefined), timeoutMs)\n\n    let request: IDBOpenDBRequest\n    try {\n      request = factory.open(databaseName)\n    } catch {\n      settle(undefined)\n      return\n    }\n    // The database was deleted between `databases()` and `open()`: abort the\n    // creation rather than leave the SDK an empty version-1 database.\n    request.onupgradeneeded = () => request.transaction?.abort()\n    request.onerror = () => settle(undefined)\n    request.onsuccess = () => {\n      const database = request.result\n      database.onversionchange = () => database.close()\n      if (settled || !database.objectStoreNames.contains(CLIENT_METADATA_STORE)) {\n        settle(undefined, database)\n        return\n      }\n      try {\n        const keys = database\n          .transaction(CLIENT_METADATA_STORE, 'readonly')\n          .objectStore(CLIENT_METADATA_STORE)\n          .getAllKeys()\n        keys.onsuccess = () =>\n          settle(\n            new Set(keys.result.filter((key): key is string => typeof key === 'string')),\n            database,\n          )\n        keys.onerror = () => settle(undefined, database)\n      } catch {\n        settle(undefined, database)\n      }\n    }\n  })\n}\n\nexport interface PruneSharedClientStateOptions {\n  storage: Storage\n  prefix: string\n  heartbeatClientIds: () => Promise<ReadonlySet<string> | undefined>\n  now?: () => number\n}\n\n/**\n * Reads the heartbeat, then plans and deletes in one synchronous pass, so\n * nothing else in this tab can write a record between the scan and the\n * deletes. The heartbeat is read BEFORE the scan: a tab that starts in between\n * shows up with a brand-new record and no heartbeat row, which the age rule\n * keeps.\n *\n * Never rejects. Resolves `undefined` when storage could not be read.\n */\nexport async function pruneSharedClientState({\n  storage,\n  prefix,\n  heartbeatClientIds,\n  now = Date.now,\n}: PruneSharedClientStateOptions): Promise<SharedClientStatePrunePlan | undefined> {\n  let heartbeat: ReadonlySet<string> | undefined\n  try {\n    heartbeat = await heartbeatClientIds()\n  } catch {\n    heartbeat = undefined\n  }\n  try {\n    const plan = planSharedClientStatePrune(storage, prefix, heartbeat, now())\n    for (const key of plan.remove) storage.removeItem(key)\n    return plan\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * {@link pruneSharedClientState} against this page's own `localStorage` and\n * IndexedDB. Resolves `undefined` off-browser, without an app name or project\n * id, or where site data is blocked (reading `window.localStorage` throws\n * there).\n */\nexport async function pruneBrowserSharedClientState(\n  appName: string | undefined,\n  projectId: string | undefined,\n): Promise<SharedClientStatePrunePlan | undefined> {\n  if (!appName || !projectId || typeof window === 'undefined') return undefined\n  let storage: Storage | undefined\n  let factory: IDBFactory | undefined\n  try {\n    storage = window.localStorage\n    factory = window.indexedDB\n  } catch {\n    return undefined\n  }\n  if (!storage) return undefined\n  const prefix = firestorePersistencePrefix(appName, projectId)\n  return pruneSharedClientState({\n    storage,\n    prefix,\n    heartbeatClientIds: () => readHeartbeatClientIds(factory, `${prefix}main`),\n  })\n}\n"],"names":["STALE_SHARED_CLIENT_STATE_MS","CLIENT_METADATA_STORE","firestorePersistencePrefix","appName","projectId","parseClientRecord","value","undefined","parsed","JSON","parse","activeTargetIds","updateTimeMs","Array","isArray","every","Number","isSafeInteger","isFinite","escapeRegExp","text","replace","planSharedClientStatePrune","storage","prefix","heartbeatClientIds","now","escaped","clientKey","RegExp","targetKey","zombieKey","isStale","at","plan","remove","targets","kept","removed","clients","zombies","heartbeat","pinned","Set","index","length","key","target","exec","push","targetId","client","record","getItem","dead","has","forEach","add","test","readHeartbeatClientIds","factory","databaseName","timeoutMs","databases","some","database","name","Promise","resolve","settled","settle","close","clearTimeout","timer","setTimeout","request","open","onupgradeneeded","transaction","abort","onerror","onsuccess","result","onversionchange","objectStoreNames","contains","keys","objectStore","getAllKeys","filter","pruneSharedClientState","Date","removeItem","pruneBrowserSharedClientState","window","localStorage","indexedDB"],"mappings":"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"}

package/src/lib/hooks/firestore-denial-reporter.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @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.
+ */
+/**
+ * Let a LISTENER tell the app its reads are being refused (AGL-1066).
+ *
+ * `session-health` was built around one-shot reads, because that is where
+ * AGL-1062 was first noticed. The console is listener-first, so the detector
+ * was watching the read style the console barely uses: only four one-shot
+ * call sites pass a collection label, one of them fires once per mount and
+ * so can never recur inside the 60s window, and none of the pages carrying a
+ * stale-write guard issues a labelled read at all. The verdict was
+ * unreachable on the surfaces that needed it.
+ *
+ * Listeners are on every page, and they already know which collection they
+ * are reading, so labelling is free rather than something a caller must
+ * remember. This is the seam that lets them report without the library
+ * importing the app: the console registers `reportDeniedRead` at startup and
+ * the hooks call it through here. An unregistered reporter is a no-op, which
+ * is what the tenant runtime wants — it has no client Firestore at all.
+ *
+ * ## Why this cannot fire offline
+ *
+ * Only `permission-denied` is ever reported. A client that has simply lost
+ * the network gets no error callback at all — the listen sits there and the
+ * cache keeps answering — and any one-shot it does make fails `unavailable`.
+ * That is what keeps the whole mechanism from mistaking a tunnel for a dead
+ * session, and it is why callers must NOT relax the code check.
+ *
+ * The channel runs both ways: see {@link reportFirestoreSessionHeal} at the
+ * bottom of this file for the return leg, which is how a refused listener
+ * learns the session came back. It lives here rather than in a module of its
+ * own because a heal is defined entirely in terms of the denial it reverses —
+ * split them and someone broadcasts one without the other's rules.
+ */
+export interface FirestoreSessionReporters {
+    /** A listen was refused past the budget; names the collection. */
+    onDenied: (collection?: string) => void;
+    /**
+     * A listen was answered BY THE SERVER.
+     *
+     * Reported as well as the denials, and it is what keeps this safe to turn
+     * on. A scoped collaborator (AGL-1041) has collections they may not read
+     * by design, and with listeners reporting they could otherwise accumulate
+     * two denied collections and be told their session is dead. But their
+     * other listens keep succeeding against the server, and one server answer
+     * clears the evidence outright — a genuinely dead session has no such
+     * answer to offer, so it is the discriminator the denial count alone
+     * cannot be.
+     *
+     * A CACHED snapshot must never be passed here; it proves nothing.
+     */
+    onServerRead: () => void;
+}
+/**
+ * Register the app's reporters. Called once, by the app that owns
+ * `session-health`. Pass `null` to unregister (tests).
+ */
+export declare function setFirestoreSessionReporters(next: FirestoreSessionReporters | null): void;
+/** Report a refused listen. No-op when nothing is registered. */
+export declare function reportFirestoreDenial(collection?: string): void;
+/** Report a listen the SERVER answered. No-op when nothing is registered. */
+export declare function reportFirestoreServerRead(): void;
+/**
+ * Record a server-answered snapshot WITHOUT reporting to `session-health`.
+ * `reportFirestoreServerRead` calls this; `helpers/use-doc` calls only this.
+ */
+export declare function noteFirestoreServerRead(): void;
+/** Test seam — the evidence is module scope by design. */
+export declare function resetFirestoreServerReadEvidence(): void;
+/**
+ * Cadence for a refusal streak that has outlived the retry budget (AGL-1066).
+ *
+ * A `permission-denied` has two very different causes and the client cannot
+ * tell them apart from the error alone:
+ *
+ *  - a SESSION fault — stale token, App Check hiccup, an AGL-1143 SSO
+ *    session that refuses everything. Every listener in the tab is refused,
+ *    and the heal is an AGL-664 in-place re-auth or a token that attaches
+ *    late. A young fault usually heals within seconds, so it starts at 2s.
+ *
+ *  - a RULES denial — the ref itself is one this user may never read (a
+ *    sentinel id, a scoped collaborator's off-limits collection). Only a
+ *    rules change (a membership granted mid-session) can end it, so it
+ *    starts at 60s (AGL-1440).
+ *
+ * The discriminator is the one this module already trusts for the
+ * session-health verdict: A GENUINELY DEAD SESSION HAS NO SERVER ANSWER TO
+ * OFFER. If any listener has been answered by the server since this
+ * listener's streak began, the session can read and this refusal is about
+ * the ref.
+ *
+ * Either way the delay then grows with the streak's age — a tenth of it, up
+ * to five minutes (AGL-2945). A refusal that has lasted ten minutes is
+ * unlikely to end in the next two seconds, and refused listens are not free:
+ * they bill reads (AGL-2944), so a fixed cadence made every console left open
+ * on a dead session a standing cost of 1,800 refusals an hour per listener.
+ * Per listener a session fault now costs ~70 in its first hour and 12 an hour
+ * after; a rules denial ~35, then 12. The listen is never abandoned.
+ *
+ * What the fast fixed cadence used to protect is kept as WAKES rather than as
+ * a timer — see {@link scheduleRefusedReopen}. The AGL-664 heal broadcast, the
+ * tab becoming visible and the window regaining focus all reopen at once, so
+ * the slow road only governs a page nobody is touching. The AGL-1358 write
+ * guards wait on a save someone clicks, which puts someone at the page.
+ */
+export declare const SESSION_REFUSED_RETRY_DELAY_MS = 2000;
+export declare const RULES_REFUSED_RETRY_DELAY_MS = 60000;
+/** The longest a refused listen ever waits for its next reopen. */
+export declare const REFUSED_RETRY_CEILING_MS: number;
+/**
+ * The delay before a spent refusal streak reopens its listen.
+ *
+ * `streakStartedAt` is when the streak's FIRST refusal landed. Evaluated per
+ * retry, not once: evidence that arrives mid-streak (another listener's
+ * first server answer) raises the floor from the next reopen on, and the age
+ * term keeps growing for as long as the streak lasts.
+ */
+export declare function refusedRetryDelayMs(streakStartedAt: number): number;
+/**
+ * Schedule the reopen of a spent refusal streak, and return its cancel.
+ *
+ * In a visible tab the reopen waits {@link refusedRetryDelayMs}. A HIDDEN tab
+ * sets no timer at all: nobody is there to heal for, and an unattended tab on
+ * a dead session was the Aug 20 – Sep 4 storm — 400K–1.7M rules denials a day
+ * in ~8-hour blocks, ~$2 of reads the `read_ops_count` metric never showed
+ * (AGL-2944). A tab that goes hidden while a reopen is pending drops its
+ * timer and waits the same way.
+ *
+ * A person arriving reopens at once, whatever the cadence: the tab becoming
+ * visible or the window regaining focus. (The heal broadcast is the third
+ * instant road; the hooks subscribe to it themselves.) Arrivals are held to
+ * one reopen no sooner than {@link SESSION_REFUSED_RETRY_DELAY_MS} after the
+ * refusal that scheduled this, so focus churn can never run the loop faster
+ * than the fixed cadence it replaced.
+ */
+export declare function scheduleRefusedReopen(reopen: () => void, streakStartedAt: number): () => void;
+/**
+ * Listen for "the session may have recovered". Returns the unsubscribe.
+ *
+ * The callback runs synchronously inside {@link reportFirestoreSessionHeal},
+ * so it must be cheap and must tolerate being called when there is nothing
+ * to do.
+ */
+export declare function subscribeFirestoreSessionHeal(listener: () => void): () => void;
+/**
+ * Tell every listener the session may have recovered.
+ *
+ * Iterates a COPY: a subscriber reopening its listen can unsubscribe (an
+ * unmount racing the broadcast) and mutating the set mid-iteration would skip
+ * the next one.
+ */
+export declare function reportFirestoreSessionHeal(): void;
+/**
+ * Consecutive refusals before a listener says anything.
+ *
+ * Matched to `firestore-one-shot-retry`'s budget so both read styles apply
+ * the same bar: surviving this many means it is not the AGL-216/217
+ * post-sign-in race, which resolves in well under two seconds.
+ *
+ * The streak this counts is NOT the hook's retry `attempt`. That one is
+ * reset by any snapshot, including one served from cache, so under
+ * `persistentLocalCache` it never reaches any threshold at all — see
+ * `use-firestore-collection-cached-retry.spec.ts`. This one is reset only by
+ * a snapshot the SERVER answered, which is the only evidence that actually
+ * bears on whether the session can read.
+ */
+export declare const DENIAL_STREAK_TO_REPORT = 5;
+/**
+ * The collection a listen was against, when it can be known from public API.
+ *
+ * `DocumentReference` exposes `parent`, and a `CollectionReference` exposes
+ * `path`. A filtered `Query` exposes neither, and reaching into `_query` to
+ * get one would be reading SDK internals — so those report `undefined` and
+ * land in the shared `unknown` bucket. That can only ever fail to reach the
+ * two-collection threshold, never trip it falsely, which is the right way
+ * for this to degrade.
+ */
+export declare function denialLabelForQuery(target: unknown): string | undefined;