@aglyn/tenant-feature-instance 1.0.0-beta.218 → 1.0.0-beta.220

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

@@ -1 +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"}
+{"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 { memoryCacheFallbackActive } from './firestore-multitab-wedge'\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 * The cache class THIS TAB's Firestore runs, which is the origin's own class\n * unless the tab has fallen back to the memory cache (AGL-3428).\n *\n * A durable origin's tab that found the shared IndexedDB locked by another\n * tab records a fallback in its `sessionStorage` and reloads; this is where\n * that reload picks it up. The answer is `ephemeral` then because the\n * ephemeral cache is exactly what the tab needs — memory only, shared with no\n * other tab — and nothing else keys off this answer: the AUTH persistence of\n * the tab keeps the origin's class, so the session survives the reload.\n * Every other tab keeps the durable cache. See `firestore-multitab-wedge.ts`.\n */\nexport function firestoreCacheClassFor(\n  originClass: AuthPersistenceClass,\n  fallbackActive: () => boolean = () => memoryCacheFallbackActive(),\n): AuthPersistenceClass {\n  if (originClass === 'durable' && fallbackActive()) return 'ephemeral'\n  return originClass\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","memoryCacheFallbackActive","pruneBrowserSharedClientState","DURABLE_CACHE_SIZE_BYTES","localCacheFor","originClass","garbageCollector","tabManager","cacheSizeBytes","firestoreCacheClassFor","fallbackActive","pruneSharedClientStateFor","app","Promise","resolve","undefined","name","options","projectId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAGA,SAEEA,gBAAgB,EAChBC,yBAAyB,EACzBC,oBAAoB,EACpBC,4BAA4B,QACvB,qBAAoB;AAG3B,SAASC,yBAAyB,QAAQ,gCAA4B;AACtE,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,OAAOR,iBAAiB;YAAES,kBAAkBR;QAA4B;IAC1E;IACA,OAAOC,qBAAqB;QAC1BQ,YAAYP;QACZQ,gBAAgBL;IAClB;AACF;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASM,uBACdJ,WAAiC,EACjCK,iBAAgC,IAAMT,2BAA2B;IAEjE,IAAII,gBAAgB,aAAaK,kBAAkB,OAAO;IAC1D,OAAOL;AACT;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASM,0BACdN,WAAiC,EACjCO,GAAgB;QAG+BA;IAD/C,IAAIP,gBAAgB,aAAa,OAAOQ,QAAQC,OAAO,CAACC;IACxD,OAAOb,8BAA8BU,IAAII,IAAI,GAAEJ,eAAAA,IAAIK,OAAO,qBAAXL,aAAaM,SAAS;AACvE"}

package/src/lib/hooks/firebase/firestore-multitab-wedge.d.ts

@@ -0,0 +1,200 @@
+/**
+ * @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.
+ */
+import { type Firestore } from 'firebase/firestore';
+/**
+ * A MULTI-TAB CACHE THAT ANOTHER TAB HAS LOCKED, AND THE WAY OUT (AGL-3428).
+ *
+ * ## The wedge the network cycle cannot clear
+ *
+ * `firestore-stall-recovery.ts` recovers a lapsed primary lease by cycling the
+ * network, which runs the lease election at once (AGL-3373). That needs the
+ * election's IndexedDB transaction to run. Measured against
+ * `@firebase/firestore` 4.17.2: `IndexedDbPersistence.runTransaction` opens
+ * EVERY transaction over EVERY object store (`getObjectStores(schemaVersion)`),
+ * so one tab that stops partway through a readwrite transaction — frozen or
+ * discarded by the browser while it runs — holds every store for every tab on
+ * the origin. Behind it, in every other tab:
+ *
+ * - the lease election waits, so the lease row is never renewed by anyone;
+ * - cache reads wait, so pages sit on their spinners;
+ * - the mutation-queue write waits, so a save never reaches the network;
+ * - a freshly opened tab's persistence `start()` waits, so a new tab hangs too;
+ * - `disableNetwork`, `enableNetwork` and `terminate` are queued on the same
+ *   AsyncQueue behind the stuck operation, so none of them ever runs.
+ *
+ * On 2026-09-30 production (beta.218) did exactly this three times in two
+ * hours: every console tab stopped, and the `owner` row named a background
+ * tab that had stopped renewing it.
+ *
+ * ## How it is told apart from a slow read
+ *
+ * Only after the network cycle, and only from a visible tab on a browser that
+ * reports a network. Such a tab wins a lapsed lease within one 4-second
+ * election tick, and the cycle has just forced one. So, after a short settle,
+ * the tab reads the `owner` row itself:
+ *
+ * - **the read cannot complete in time** — the store is locked by another
+ *   tab's open transaction; or
+ * - **the lease is older than {@link STALE_PRIMARY_LEASE_MS}** — no tab,
+ *   including this one, is completing an election.
+ *
+ * Either is the wedge. A fresh lease — this tab's or another's — is a healthy
+ * cache and a merely slow server, and nothing more happens.
+ *
+ * ## The way out
+ *
+ * The tab records a {@link MemoryCacheFallback} in `sessionStorage` and
+ * reloads. `firestoreCacheClassFor` reads it at startup and gives this tab the
+ * memory cache, which shares nothing with other tabs, so the locked database
+ * cannot reach it. `sessionStorage` is per tab: other tabs keep the durable
+ * cache, and the fallback leaves when this tab closes or after
+ * {@link MEMORY_CACHE_FALLBACK_TTL_MS}.
+ *
+ * A reload, not an in-place swap, because nothing in place can work: the
+ * wedged instance's `terminate()` is queued behind the stuck operation, a
+ * second instance for the same app throws until the first is gone, and
+ * hundreds of readers hold the instance from context and from closures.
+ * Nothing that could be saved is lost — the wedge had already stopped every
+ * write in the tab from leaving it.
+ */
+/** `sessionStorage` key of this tab's memory-cache fallback. */
+export declare const MEMORY_CACHE_FALLBACK_KEY = "aglyn:firestore-memory-cache-fallback";
+/**
+ * How long a tab keeps the memory cache after falling back. The SDK's own
+ * inactivity horizon (`MAX_CLIENT_AGE_MS`), after which a tab that is still
+ * stuck no longer counts as a client; past it, a reload tries the durable
+ * cache again, and falls back again if it has to.
+ */
+export declare const MEMORY_CACHE_FALLBACK_TTL_MS: number;
+/**
+ * A lease older than this, read from a visible online tab right after a
+ * forced election, means no election is completing. The SDK treats a lease as
+ * lapsed at 5 s (`MAX_PRIMARY_ELIGIBLE_AGE_MS`) and runs the election every
+ * 4 s; this is three times the first, so an election that is merely late is
+ * never mistaken for one that cannot run.
+ */
+export declare const STALE_PRIMARY_LEASE_MS = 15000;
+/**
+ * How long the lease read may take before the store is judged locked. The
+ * SDK's own transactions take milliseconds.
+ */
+export declare const LEASE_PROBE_TIMEOUT_MS = 4000;
+/**
+ * How long after the network cycle the lease is read, so the election the
+ * cycle queued has run.
+ */
+export declare const LEASE_SETTLE_MS = 3000;
+/** What reading the lease found. */
+export type PrimaryLeaseProbe = 
+/** The read did not complete in time: another tab's transaction holds the store. */
+{
+    state: 'locked';
+}
+/** The lease row: who holds it and how long ago it was renewed. */
+ | {
+    state: 'leased';
+    ownerId: string;
+    ageMs: number;
+}
+/** There is no lease row. */
+ | {
+    state: 'vacant';
+}
+/** The lease could not be read: no IndexedDB, no database, no store, an error. */
+ | {
+    state: 'unknown';
+};
+/** Why a tab concluded the multi-tab cache is wedged. */
+export type WedgeEvidence = {
+    reason: 'lease-locked';
+} | {
+    reason: 'lease-stale';
+    ownerId: string;
+    ageMs: number;
+};
+/** The fallback this tab recorded, and why. */
+export type MemoryCacheFallback = WedgeEvidence & {
+    at: number;
+};
+/**
+ * Reads the SDK's `owner` row from `databaseName`.
+ *
+ * Opens only a database that already exists, at whatever version it has (the
+ * same rule as `readHeartbeatClientIds`): `open(name)` on a missing database
+ * would create it at version 1 under the SDK. The connection serves one
+ * read-only request and is closed — also on `versionchange`, so it never
+ * holds up the SDK's own upgrade, and also when the read lands after the
+ * timeout.
+ */
+export declare function probePrimaryLease(factory: IDBFactory | undefined, databaseName: string, { timeoutMs, now, }?: {
+    timeoutMs?: number;
+    now?: () => number;
+}): Promise<PrimaryLeaseProbe>;
+/**
+ * Whether a lease read taken right after a forced election, from a visible
+ * online tab, shows the wedge. Anything that could be a healthy cache —
+ * a fresh lease, no lease row, an unreadable one — is not evidence.
+ */
+export declare function wedgeEvidenceFrom(probe: PrimaryLeaseProbe, staleMs?: number): WedgeEvidence | undefined;
+/**
+ * This tab's fallback, or `undefined` when there is none, it has expired, or
+ * it does not parse.
+ */
+export declare function readMemoryCacheFallback(storage: Pick<Storage, 'getItem'> | undefined, now: number, ttlMs?: number): MemoryCacheFallback | undefined;
+/** Whether this browser tab is running on its memory-cache fallback. */
+export declare function memoryCacheFallbackActive(now?: number): boolean;
+export interface WedgeEscalationDeps {
+    /** Reads the lease. */
+    probe: () => Promise<PrimaryLeaseProbe>;
+    /** Moves this tab off the shared cache. */
+    fallBack: (evidence: WedgeEvidence) => void;
+    /** Whether this tab is already on the fallback — it then never escalates. */
+    isFallbackActive?: () => boolean;
+    isOnline?: () => boolean;
+    isVisible?: () => boolean;
+    /** Waits `ms`; the settle before the lease read. */
+    wait?: (ms: number) => Promise<void>;
+    settleMs?: number;
+}
+/**
+ * The step `createStallRecovery` runs after its network cycle for a
+ * multi-tab client. Resolves `true` when it has moved the tab to the fallback.
+ * Never rejects.
+ */
+export declare function createWedgeEscalation(deps: WedgeEscalationDeps): () => Promise<boolean>;
+/**
+ * Records the fallback for this tab and reloads it onto the memory cache.
+ * When the record cannot be written it does not reload: without it, the
+ * reloaded tab would open the same locked database and hang again.
+ */
+export declare function fallBackToMemoryCache(evidence: WedgeEvidence, { storage, reload, now, }?: {
+    storage?: Pick<Storage, 'setItem'>;
+    reload?: () => void;
+    now?: () => number;
+}): void;
+/**
+ * Registers `firestore` as running the durable multi-tab cache under
+ * `databaseName` (`<persistence prefix>main`). Only a registered client ever
+ * escalates past the network cycle.
+ */
+export declare function markMultiTabFirestore(firestore: Firestore, databaseName: string): void;
+/**
+ * The browser escalation for `firestore`, or `undefined` when it does not run
+ * the durable multi-tab cache (the emulator configuration, an ephemeral
+ * origin, a tab already on the fallback).
+ */
+export declare function browserWedgeEscalationFor(firestore: Firestore): (() => Promise<boolean>) | undefined;

package/src/lib/hooks/firebase/firestore-multitab-wedge.js

@@ -0,0 +1,325 @@
+/**
+ * @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.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * A MULTI-TAB CACHE THAT ANOTHER TAB HAS LOCKED, AND THE WAY OUT (AGL-3428).
+ *
+ * ## The wedge the network cycle cannot clear
+ *
+ * `firestore-stall-recovery.ts` recovers a lapsed primary lease by cycling the
+ * network, which runs the lease election at once (AGL-3373). That needs the
+ * election's IndexedDB transaction to run. Measured against
+ * `@firebase/firestore` 4.17.2: `IndexedDbPersistence.runTransaction` opens
+ * EVERY transaction over EVERY object store (`getObjectStores(schemaVersion)`),
+ * so one tab that stops partway through a readwrite transaction — frozen or
+ * discarded by the browser while it runs — holds every store for every tab on
+ * the origin. Behind it, in every other tab:
+ *
+ * - the lease election waits, so the lease row is never renewed by anyone;
+ * - cache reads wait, so pages sit on their spinners;
+ * - the mutation-queue write waits, so a save never reaches the network;
+ * - a freshly opened tab's persistence `start()` waits, so a new tab hangs too;
+ * - `disableNetwork`, `enableNetwork` and `terminate` are queued on the same
+ *   AsyncQueue behind the stuck operation, so none of them ever runs.
+ *
+ * On 2026-09-30 production (beta.218) did exactly this three times in two
+ * hours: every console tab stopped, and the `owner` row named a background
+ * tab that had stopped renewing it.
+ *
+ * ## How it is told apart from a slow read
+ *
+ * Only after the network cycle, and only from a visible tab on a browser that
+ * reports a network. Such a tab wins a lapsed lease within one 4-second
+ * election tick, and the cycle has just forced one. So, after a short settle,
+ * the tab reads the `owner` row itself:
+ *
+ * - **the read cannot complete in time** — the store is locked by another
+ *   tab's open transaction; or
+ * - **the lease is older than {@link STALE_PRIMARY_LEASE_MS}** — no tab,
+ *   including this one, is completing an election.
+ *
+ * Either is the wedge. A fresh lease — this tab's or another's — is a healthy
+ * cache and a merely slow server, and nothing more happens.
+ *
+ * ## The way out
+ *
+ * The tab records a {@link MemoryCacheFallback} in `sessionStorage` and
+ * reloads. `firestoreCacheClassFor` reads it at startup and gives this tab the
+ * memory cache, which shares nothing with other tabs, so the locked database
+ * cannot reach it. `sessionStorage` is per tab: other tabs keep the durable
+ * cache, and the fallback leaves when this tab closes or after
+ * {@link MEMORY_CACHE_FALLBACK_TTL_MS}.
+ *
+ * A reload, not an in-place swap, because nothing in place can work: the
+ * wedged instance's `terminate()` is queued behind the stuck operation, a
+ * second instance for the same app throws until the first is gone, and
+ * hundreds of readers hold the instance from context and from closures.
+ * Nothing that could be saved is lost — the wedge had already stopped every
+ * write in the tab from leaving it.
+ */ /** `sessionStorage` key of this tab's memory-cache fallback. */ export const MEMORY_CACHE_FALLBACK_KEY = 'aglyn:firestore-memory-cache-fallback';
+/**
+ * How long a tab keeps the memory cache after falling back. The SDK's own
+ * inactivity horizon (`MAX_CLIENT_AGE_MS`), after which a tab that is still
+ * stuck no longer counts as a client; past it, a reload tries the durable
+ * cache again, and falls back again if it has to.
+ */ export const MEMORY_CACHE_FALLBACK_TTL_MS = 30 * 60 * 1000;
+/**
+ * A lease older than this, read from a visible online tab right after a
+ * forced election, means no election is completing. The SDK treats a lease as
+ * lapsed at 5 s (`MAX_PRIMARY_ELIGIBLE_AGE_MS`) and runs the election every
+ * 4 s; this is three times the first, so an election that is merely late is
+ * never mistaken for one that cannot run.
+ */ export const STALE_PRIMARY_LEASE_MS = 15000;
+/**
+ * How long the lease read may take before the store is judged locked. The
+ * SDK's own transactions take milliseconds.
+ */ export const LEASE_PROBE_TIMEOUT_MS = 4000;
+/**
+ * How long after the network cycle the lease is read, so the election the
+ * cycle queued has run.
+ */ export const LEASE_SETTLE_MS = 3000;
+/** The SDK's lease store and its single row's key (`DbPrimaryClientStore`, `DbPrimaryClientKey`). */ const OWNER_STORE = 'owner';
+const OWNER_KEY = 'owner';
+/**
+ * Reads the SDK's `owner` row from `databaseName`.
+ *
+ * Opens only a database that already exists, at whatever version it has (the
+ * same rule as `readHeartbeatClientIds`): `open(name)` on a missing database
+ * would create it at version 1 under the SDK. The connection serves one
+ * read-only request and is closed — also on `versionchange`, so it never
+ * holds up the SDK's own upgrade, and also when the read lands after the
+ * timeout.
+ */ export async function probePrimaryLease(factory, databaseName, { timeoutMs = LEASE_PROBE_TIMEOUT_MS, now = Date.now } = {}) {
+    if (!factory || typeof factory.databases !== 'function') return {
+        state: 'unknown'
+    };
+    try {
+        const databases = await factory.databases();
+        if (!databases.some((database)=>database.name === databaseName)) {
+            return {
+                state: 'unknown'
+            };
+        }
+    } catch (unused) {
+        return {
+            state: 'unknown'
+        };
+    }
+    return new Promise((resolve)=>{
+        let settled = false;
+        let database;
+        const settle = (probe)=>{
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(probe);
+        };
+        const close = ()=>{
+            try {
+                database == null ? void 0 : database.close();
+            } catch (unused) {
+            // Already closed.
+            }
+        };
+        // Only a lock can hold a read-only request this long; the connection is
+        // closed when the request finally lands.
+        const timer = setTimeout(()=>settle({
+                state: 'locked'
+            }), timeoutMs);
+        let request;
+        try {
+            request = factory.open(databaseName);
+        } catch (unused) {
+            settle({
+                state: 'unknown'
+            });
+            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({
+                state: 'unknown'
+            });
+        request.onsuccess = ()=>{
+            database = request.result;
+            database.onversionchange = close;
+            if (settled || !database.objectStoreNames.contains(OWNER_STORE)) {
+                close();
+                settle({
+                    state: 'unknown'
+                });
+                return;
+            }
+            try {
+                const read = database.transaction(OWNER_STORE, 'readonly').objectStore(OWNER_STORE).get(OWNER_KEY);
+                read.onsuccess = ()=>{
+                    close();
+                    const row = read.result;
+                    if (!row || typeof row.ownerId !== 'string' || typeof row.leaseTimestampMs !== 'number') {
+                        settle({
+                            state: 'vacant'
+                        });
+                        return;
+                    }
+                    settle({
+                        state: 'leased',
+                        ownerId: row.ownerId,
+                        ageMs: now() - row.leaseTimestampMs
+                    });
+                };
+                read.onerror = ()=>{
+                    close();
+                    settle({
+                        state: 'unknown'
+                    });
+                };
+            } catch (unused) {
+                close();
+                settle({
+                    state: 'unknown'
+                });
+            }
+        };
+    });
+}
+/**
+ * Whether a lease read taken right after a forced election, from a visible
+ * online tab, shows the wedge. Anything that could be a healthy cache —
+ * a fresh lease, no lease row, an unreadable one — is not evidence.
+ */ export function wedgeEvidenceFrom(probe, staleMs = STALE_PRIMARY_LEASE_MS) {
+    if (probe.state === 'locked') return {
+        reason: 'lease-locked'
+    };
+    if (probe.state === 'leased' && probe.ageMs >= staleMs) {
+        return {
+            reason: 'lease-stale',
+            ownerId: probe.ownerId,
+            ageMs: probe.ageMs
+        };
+    }
+    return undefined;
+}
+/**
+ * This tab's fallback, or `undefined` when there is none, it has expired, or
+ * it does not parse.
+ */ export function readMemoryCacheFallback(storage, now, ttlMs = MEMORY_CACHE_FALLBACK_TTL_MS) {
+    let raw;
+    try {
+        var _ref;
+        raw = (_ref = storage == null ? void 0 : storage.getItem(MEMORY_CACHE_FALLBACK_KEY)) != null ? _ref : null;
+    } catch (unused) {
+        return undefined;
+    }
+    if (raw === null) return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (unused) {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const record = parsed;
+    if (typeof record.at !== 'number' || !Number.isFinite(record.at)) return undefined;
+    if (now - record.at >= ttlMs || record.at > now) return undefined;
+    return record;
+}
+const browserSessionStorage = ()=>{
+    try {
+        return typeof window === 'undefined' ? undefined : window.sessionStorage;
+    } catch (unused) {
+        // Site data blocked: reading `window.sessionStorage` throws.
+        return undefined;
+    }
+};
+/** Whether this browser tab is running on its memory-cache fallback. */ export function memoryCacheFallbackActive(now = Date.now()) {
+    return readMemoryCacheFallback(browserSessionStorage(), now) !== undefined;
+}
+const browserOnline = ()=>typeof navigator === 'undefined' || navigator.onLine !== false;
+const documentVisible = ()=>typeof document === 'undefined' || document.visibilityState !== 'hidden';
+/**
+ * The step `createStallRecovery` runs after its network cycle for a
+ * multi-tab client. Resolves `true` when it has moved the tab to the fallback.
+ * Never rejects.
+ */ export function createWedgeEscalation(deps) {
+    const { probe, fallBack, isFallbackActive = ()=>memoryCacheFallbackActive(), isOnline = browserOnline, isVisible = documentVisible, wait = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms)), settleMs = LEASE_SETTLE_MS } = deps;
+    return async ()=>{
+        try {
+            if (isFallbackActive()) return false;
+            await wait(settleMs);
+            // Both guards again: the reader may have gone, or the network with it.
+            if (!isOnline() || !isVisible()) return false;
+            const evidence = wedgeEvidenceFrom(await probe());
+            if (!evidence) return false;
+            fallBack(evidence);
+            return true;
+        } catch (unused) {
+            return false;
+        }
+    };
+}
+/**
+ * Records the fallback for this tab and reloads it onto the memory cache.
+ * When the record cannot be written it does not reload: without it, the
+ * reloaded tab would open the same locked database and hang again.
+ */ export function fallBackToMemoryCache(evidence, { storage = browserSessionStorage(), reload = ()=>window.location.reload(), now = Date.now } = {}) {
+    if (!storage) return;
+    const record = _extends({}, evidence, {
+        at: now()
+    });
+    try {
+        storage.setItem(MEMORY_CACHE_FALLBACK_KEY, JSON.stringify(record));
+    } catch (unused) {
+        return;
+    }
+    console.warn('[firestore] The multi-tab cache is locked by another tab; reloading this tab on the memory cache (AGL-3428).', record);
+    reload();
+}
+/** The IndexedDB database of each client running the durable multi-tab cache. */ const multiTabDatabases = new WeakMap();
+/**
+ * Registers `firestore` as running the durable multi-tab cache under
+ * `databaseName` (`<persistence prefix>main`). Only a registered client ever
+ * escalates past the network cycle.
+ */ export function markMultiTabFirestore(firestore, databaseName) {
+    if (firestore && typeof firestore === 'object') {
+        multiTabDatabases.set(firestore, databaseName);
+    }
+}
+/**
+ * The browser escalation for `firestore`, or `undefined` when it does not run
+ * the durable multi-tab cache (the emulator configuration, an ephemeral
+ * origin, a tab already on the fallback).
+ */ export function browserWedgeEscalationFor(firestore) {
+    const databaseName = multiTabDatabases.get(firestore);
+    if (databaseName === undefined) return undefined;
+    return createWedgeEscalation({
+        probe: ()=>{
+            let factory;
+            try {
+                factory = typeof window === 'undefined' ? undefined : window.indexedDB;
+            } catch (unused) {
+                factory = undefined;
+            }
+            return probePrimaryLease(factory, databaseName);
+        },
+        fallBack: (evidence)=>fallBackToMemoryCache(evidence)
+    });
+}
+
+//# sourceMappingURL=firestore-multitab-wedge.js.map

package/src/lib/hooks/firebase/firestore-multitab-wedge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firebase/firestore-multitab-wedge.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\nimport { type Firestore } from 'firebase/firestore'\n\n/**\n * A MULTI-TAB CACHE THAT ANOTHER TAB HAS LOCKED, AND THE WAY OUT (AGL-3428).\n *\n * ## The wedge the network cycle cannot clear\n *\n * `firestore-stall-recovery.ts` recovers a lapsed primary lease by cycling the\n * network, which runs the lease election at once (AGL-3373). That needs the\n * election's IndexedDB transaction to run. Measured against\n * `@firebase/firestore` 4.17.2: `IndexedDbPersistence.runTransaction` opens\n * EVERY transaction over EVERY object store (`getObjectStores(schemaVersion)`),\n * so one tab that stops partway through a readwrite transaction — frozen or\n * discarded by the browser while it runs — holds every store for every tab on\n * the origin. Behind it, in every other tab:\n *\n * - the lease election waits, so the lease row is never renewed by anyone;\n * - cache reads wait, so pages sit on their spinners;\n * - the mutation-queue write waits, so a save never reaches the network;\n * - a freshly opened tab's persistence `start()` waits, so a new tab hangs too;\n * - `disableNetwork`, `enableNetwork` and `terminate` are queued on the same\n *   AsyncQueue behind the stuck operation, so none of them ever runs.\n *\n * On 2026-09-30 production (beta.218) did exactly this three times in two\n * hours: every console tab stopped, and the `owner` row named a background\n * tab that had stopped renewing it.\n *\n * ## How it is told apart from a slow read\n *\n * Only after the network cycle, and only from a visible tab on a browser that\n * reports a network. Such a tab wins a lapsed lease within one 4-second\n * election tick, and the cycle has just forced one. So, after a short settle,\n * the tab reads the `owner` row itself:\n *\n * - **the read cannot complete in time** — the store is locked by another\n *   tab's open transaction; or\n * - **the lease is older than {@link STALE_PRIMARY_LEASE_MS}** — no tab,\n *   including this one, is completing an election.\n *\n * Either is the wedge. A fresh lease — this tab's or another's — is a healthy\n * cache and a merely slow server, and nothing more happens.\n *\n * ## The way out\n *\n * The tab records a {@link MemoryCacheFallback} in `sessionStorage` and\n * reloads. `firestoreCacheClassFor` reads it at startup and gives this tab the\n * memory cache, which shares nothing with other tabs, so the locked database\n * cannot reach it. `sessionStorage` is per tab: other tabs keep the durable\n * cache, and the fallback leaves when this tab closes or after\n * {@link MEMORY_CACHE_FALLBACK_TTL_MS}.\n *\n * A reload, not an in-place swap, because nothing in place can work: the\n * wedged instance's `terminate()` is queued behind the stuck operation, a\n * second instance for the same app throws until the first is gone, and\n * hundreds of readers hold the instance from context and from closures.\n * Nothing that could be saved is lost — the wedge had already stopped every\n * write in the tab from leaving it.\n */\n\n/** `sessionStorage` key of this tab's memory-cache fallback. */\nexport const MEMORY_CACHE_FALLBACK_KEY = 'aglyn:firestore-memory-cache-fallback'\n\n/**\n * How long a tab keeps the memory cache after falling back. The SDK's own\n * inactivity horizon (`MAX_CLIENT_AGE_MS`), after which a tab that is still\n * stuck no longer counts as a client; past it, a reload tries the durable\n * cache again, and falls back again if it has to.\n */\nexport const MEMORY_CACHE_FALLBACK_TTL_MS = 30 * 60 * 1000\n\n/**\n * A lease older than this, read from a visible online tab right after a\n * forced election, means no election is completing. The SDK treats a lease as\n * lapsed at 5 s (`MAX_PRIMARY_ELIGIBLE_AGE_MS`) and runs the election every\n * 4 s; this is three times the first, so an election that is merely late is\n * never mistaken for one that cannot run.\n */\nexport const STALE_PRIMARY_LEASE_MS = 15_000\n\n/**\n * How long the lease read may take before the store is judged locked. The\n * SDK's own transactions take milliseconds.\n */\nexport const LEASE_PROBE_TIMEOUT_MS = 4_000\n\n/**\n * How long after the network cycle the lease is read, so the election the\n * cycle queued has run.\n */\nexport const LEASE_SETTLE_MS = 3_000\n\n/** The SDK's lease store and its single row's key (`DbPrimaryClientStore`, `DbPrimaryClientKey`). */\nconst OWNER_STORE = 'owner'\nconst OWNER_KEY = 'owner'\n\n/** What reading the lease found. */\nexport type PrimaryLeaseProbe =\n  /** The read did not complete in time: another tab's transaction holds the store. */\n  | { state: 'locked' }\n  /** The lease row: who holds it and how long ago it was renewed. */\n  | { state: 'leased'; ownerId: string; ageMs: number }\n  /** There is no lease row. */\n  | { state: 'vacant' }\n  /** The lease could not be read: no IndexedDB, no database, no store, an error. */\n  | { state: 'unknown' }\n\n/** Why a tab concluded the multi-tab cache is wedged. */\nexport type WedgeEvidence =\n  | { reason: 'lease-locked' }\n  | { reason: 'lease-stale'; ownerId: string; ageMs: number }\n\n/** The fallback this tab recorded, and why. */\nexport type MemoryCacheFallback = WedgeEvidence & { at: number }\n\n/**\n * Reads the SDK's `owner` row from `databaseName`.\n *\n * Opens only a database that already exists, at whatever version it has (the\n * same rule as `readHeartbeatClientIds`): `open(name)` on a missing database\n * would create it at version 1 under the SDK. The connection serves one\n * read-only request and is closed — also on `versionchange`, so it never\n * holds up the SDK's own upgrade, and also when the read lands after the\n * timeout.\n */\nexport async function probePrimaryLease(\n  factory: IDBFactory | undefined,\n  databaseName: string,\n  {\n    timeoutMs = LEASE_PROBE_TIMEOUT_MS,\n    now = Date.now,\n  }: { timeoutMs?: number; now?: () => number } = {},\n): Promise<PrimaryLeaseProbe> {\n  if (!factory || typeof factory.databases !== 'function') return { state: 'unknown' }\n  try {\n    const databases = await factory.databases()\n    if (!databases.some((database) => database.name === databaseName)) {\n      return { state: 'unknown' }\n    }\n  } catch {\n    return { state: 'unknown' }\n  }\n\n  return new Promise((resolve) => {\n    let settled = false\n    let database: IDBDatabase | undefined\n    const settle = (probe: PrimaryLeaseProbe) => {\n      if (settled) return\n      settled = true\n      clearTimeout(timer)\n      resolve(probe)\n    }\n    const close = () => {\n      try {\n        database?.close()\n      } catch {\n        // Already closed.\n      }\n    }\n    // Only a lock can hold a read-only request this long; the connection is\n    // closed when the request finally lands.\n    const timer = setTimeout(() => settle({ state: 'locked' }), timeoutMs)\n\n    let request: IDBOpenDBRequest\n    try {\n      request = factory.open(databaseName)\n    } catch {\n      settle({ state: 'unknown' })\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({ state: 'unknown' })\n    request.onsuccess = () => {\n      database = request.result\n      database.onversionchange = close\n      if (settled || !database.objectStoreNames.contains(OWNER_STORE)) {\n        close()\n        settle({ state: 'unknown' })\n        return\n      }\n      try {\n        const read = database\n          .transaction(OWNER_STORE, 'readonly')\n          .objectStore(OWNER_STORE)\n          .get(OWNER_KEY)\n        read.onsuccess = () => {\n          close()\n          const row = read.result as\n            | { ownerId?: unknown; leaseTimestampMs?: unknown }\n            | undefined\n          if (\n            !row ||\n            typeof row.ownerId !== 'string' ||\n            typeof row.leaseTimestampMs !== 'number'\n          ) {\n            settle({ state: 'vacant' })\n            return\n          }\n          settle({\n            state: 'leased',\n            ownerId: row.ownerId,\n            ageMs: now() - row.leaseTimestampMs,\n          })\n        }\n        read.onerror = () => {\n          close()\n          settle({ state: 'unknown' })\n        }\n      } catch {\n        close()\n        settle({ state: 'unknown' })\n      }\n    }\n  })\n}\n\n/**\n * Whether a lease read taken right after a forced election, from a visible\n * online tab, shows the wedge. Anything that could be a healthy cache —\n * a fresh lease, no lease row, an unreadable one — is not evidence.\n */\nexport function wedgeEvidenceFrom(\n  probe: PrimaryLeaseProbe,\n  staleMs = STALE_PRIMARY_LEASE_MS,\n): WedgeEvidence | undefined {\n  if (probe.state === 'locked') return { reason: 'lease-locked' }\n  if (probe.state === 'leased' && probe.ageMs >= staleMs) {\n    return { reason: 'lease-stale', ownerId: probe.ownerId, ageMs: probe.ageMs }\n  }\n  return undefined\n}\n\n/**\n * This tab's fallback, or `undefined` when there is none, it has expired, or\n * it does not parse.\n */\nexport function readMemoryCacheFallback(\n  storage: Pick<Storage, 'getItem'> | undefined,\n  now: number,\n  ttlMs = MEMORY_CACHE_FALLBACK_TTL_MS,\n): MemoryCacheFallback | undefined {\n  let raw: string | null\n  try {\n    raw = storage?.getItem(MEMORY_CACHE_FALLBACK_KEY) ?? null\n  } catch {\n    return undefined\n  }\n  if (raw === null) return undefined\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch {\n    return undefined\n  }\n  if (typeof parsed !== 'object' || parsed === null) return undefined\n  const record = parsed as Partial<MemoryCacheFallback>\n  if (typeof record.at !== 'number' || !Number.isFinite(record.at)) return undefined\n  if (now - record.at >= ttlMs || record.at > now) return undefined\n  return record as MemoryCacheFallback\n}\n\nconst browserSessionStorage = (): Storage | undefined => {\n  try {\n    return typeof window === 'undefined' ? undefined : window.sessionStorage\n  } catch {\n    // Site data blocked: reading `window.sessionStorage` throws.\n    return undefined\n  }\n}\n\n/** Whether this browser tab is running on its memory-cache fallback. */\nexport function memoryCacheFallbackActive(now = Date.now()): boolean {\n  return readMemoryCacheFallback(browserSessionStorage(), now) !== undefined\n}\n\nexport interface WedgeEscalationDeps {\n  /** Reads the lease. */\n  probe: () => Promise<PrimaryLeaseProbe>\n  /** Moves this tab off the shared cache. */\n  fallBack: (evidence: WedgeEvidence) => void\n  /** Whether this tab is already on the fallback — it then never escalates. */\n  isFallbackActive?: () => boolean\n  isOnline?: () => boolean\n  isVisible?: () => boolean\n  /** Waits `ms`; the settle before the lease read. */\n  wait?: (ms: number) => Promise<void>\n  settleMs?: number\n}\n\nconst browserOnline = () =>\n  typeof navigator === 'undefined' || navigator.onLine !== false\n\nconst documentVisible = () =>\n  typeof document === 'undefined' || document.visibilityState !== 'hidden'\n\n/**\n * The step `createStallRecovery` runs after its network cycle for a\n * multi-tab client. Resolves `true` when it has moved the tab to the fallback.\n * Never rejects.\n */\nexport function createWedgeEscalation(\n  deps: WedgeEscalationDeps,\n): () => Promise<boolean> {\n  const {\n    probe,\n    fallBack,\n    isFallbackActive = () => memoryCacheFallbackActive(),\n    isOnline = browserOnline,\n    isVisible = documentVisible,\n    wait = (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),\n    settleMs = LEASE_SETTLE_MS,\n  } = deps\n  return async () => {\n    try {\n      if (isFallbackActive()) return false\n      await wait(settleMs)\n      // Both guards again: the reader may have gone, or the network with it.\n      if (!isOnline() || !isVisible()) return false\n      const evidence = wedgeEvidenceFrom(await probe())\n      if (!evidence) return false\n      fallBack(evidence)\n      return true\n    } catch {\n      return false\n    }\n  }\n}\n\n/**\n * Records the fallback for this tab and reloads it onto the memory cache.\n * When the record cannot be written it does not reload: without it, the\n * reloaded tab would open the same locked database and hang again.\n */\nexport function fallBackToMemoryCache(\n  evidence: WedgeEvidence,\n  {\n    storage = browserSessionStorage(),\n    reload = () => window.location.reload(),\n    now = Date.now,\n  }: {\n    storage?: Pick<Storage, 'setItem'>\n    reload?: () => void\n    now?: () => number\n  } = {},\n): void {\n  if (!storage) return\n  const record: MemoryCacheFallback = { ...evidence, at: now() }\n  try {\n    storage.setItem(MEMORY_CACHE_FALLBACK_KEY, JSON.stringify(record))\n  } catch {\n    return\n  }\n  console.warn(\n    '[firestore] The multi-tab cache is locked by another tab; reloading this tab on the memory cache (AGL-3428).',\n    record,\n  )\n  reload()\n}\n\n/** The IndexedDB database of each client running the durable multi-tab cache. */\nconst multiTabDatabases = new WeakMap<Firestore, string>()\n\n/**\n * Registers `firestore` as running the durable multi-tab cache under\n * `databaseName` (`<persistence prefix>main`). Only a registered client ever\n * escalates past the network cycle.\n */\nexport function markMultiTabFirestore(firestore: Firestore, databaseName: string): void {\n  if (firestore && typeof firestore === 'object') {\n    multiTabDatabases.set(firestore, databaseName)\n  }\n}\n\n/**\n * The browser escalation for `firestore`, or `undefined` when it does not run\n * the durable multi-tab cache (the emulator configuration, an ephemeral\n * origin, a tab already on the fallback).\n */\nexport function browserWedgeEscalationFor(\n  firestore: Firestore,\n): (() => Promise<boolean>) | undefined {\n  const databaseName = multiTabDatabases.get(firestore)\n  if (databaseName === undefined) return undefined\n  return createWedgeEscalation({\n    probe: () => {\n      let factory: IDBFactory | undefined\n      try {\n        factory = typeof window === 'undefined' ? undefined : window.indexedDB\n      } catch {\n        factory = undefined\n      }\n      return probePrimaryLease(factory, databaseName)\n    },\n    fallBack: (evidence) => fallBackToMemoryCache(evidence),\n  })\n}\n"],"names":["MEMORY_CACHE_FALLBACK_KEY","MEMORY_CACHE_FALLBACK_TTL_MS","STALE_PRIMARY_LEASE_MS","LEASE_PROBE_TIMEOUT_MS","LEASE_SETTLE_MS","OWNER_STORE","OWNER_KEY","probePrimaryLease","factory","databaseName","timeoutMs","now","Date","databases","state","some","database","name","Promise","resolve","settled","settle","probe","clearTimeout","timer","close","setTimeout","request","open","onupgradeneeded","transaction","abort","onerror","onsuccess","result","onversionchange","objectStoreNames","contains","read","objectStore","get","row","ownerId","leaseTimestampMs","ageMs","wedgeEvidenceFrom","staleMs","reason","undefined","readMemoryCacheFallback","storage","ttlMs","raw","getItem","parsed","JSON","parse","record","at","Number","isFinite","browserSessionStorage","window","sessionStorage","memoryCacheFallbackActive","browserOnline","navigator","onLine","documentVisible","document","visibilityState","createWedgeEscalation","deps","fallBack","isFallbackActive","isOnline","isVisible","wait","ms","settleMs","evidence","fallBackToMemoryCache","reload","location","setItem","stringify","console","warn","multiTabDatabases","WeakMap","markMultiTabFirestore","firestore","set","browserWedgeEscalationFor","indexedDB"],"mappings":"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"}