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

package/src/lib/hooks/firestore-denial-reporter.js

@@ -0,0 +1,293 @@
+/**
+ * @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.
+ */ let reporters = null;
+/**
+ * Register the app's reporters. Called once, by the app that owns
+ * `session-health`. Pass `null` to unregister (tests).
+ */ export function setFirestoreSessionReporters(next) {
+    reporters = next;
+}
+/** Report a refused listen. No-op when nothing is registered. */ export function reportFirestoreDenial(collection) {
+    reporters == null ? void 0 : reporters.onDenied(collection);
+}
+/** Report a listen the SERVER answered. No-op when nothing is registered. */ export function reportFirestoreServerRead() {
+    noteFirestoreServerRead();
+    reporters == null ? void 0 : reporters.onServerRead();
+}
+/**
+ * When ANY listener in this tab last got a server-answered snapshot.
+ *
+ * Library-internal evidence, kept regardless of whether app reporters are
+ * registered — `helpers/use-doc` deliberately does not feed `session-health`
+ * (its callers are the besigner document family, where a false verdict hurts
+ * most) but its server answers are still proof the session can read, and
+ * {@link refusedRetryDelayMs} needs that proof from every hook.
+ */ let lastServerReadAt = 0;
+/**
+ * Record a server-answered snapshot WITHOUT reporting to `session-health`.
+ * `reportFirestoreServerRead` calls this; `helpers/use-doc` calls only this.
+ */ export function noteFirestoreServerRead() {
+    lastServerReadAt = Date.now();
+}
+/** Test seam — the evidence is module scope by design. */ export function resetFirestoreServerReadEvidence() {
+    lastServerReadAt = 0;
+}
+/**
+ * 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 const SESSION_REFUSED_RETRY_DELAY_MS = 2000;
+export const RULES_REFUSED_RETRY_DELAY_MS = 60000;
+/** The longest a refused listen ever waits for its next reopen. */ export const REFUSED_RETRY_CEILING_MS = 5 * 60000;
+/** The delay is the streak's age divided by this, between floor and ceiling. */ const REFUSED_RETRY_AGE_DIVISOR = 10;
+/**
+ * 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 function refusedRetryDelayMs(streakStartedAt) {
+    const floor = lastServerReadAt > streakStartedAt ? RULES_REFUSED_RETRY_DELAY_MS : SESSION_REFUSED_RETRY_DELAY_MS;
+    // A backwards clock reads as a young streak, never as a negative age.
+    const age = Math.max(0, Date.now() - streakStartedAt);
+    return Math.min(REFUSED_RETRY_CEILING_MS, Math.max(floor, age / REFUSED_RETRY_AGE_DIVISOR));
+}
+/** No `document` (SSR, a worker) counts as visible: nothing to wait for. */ function tabIsHidden() {
+    return typeof document !== 'undefined' && document.visibilityState === 'hidden';
+}
+/**
+ * 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 function scheduleRefusedReopen(reopen, streakStartedAt) {
+    const scheduledAt = Date.now();
+    let timer = null;
+    let dueAt = Number.POSITIVE_INFINITY;
+    let settled = false;
+    const disarm = ()=>{
+        if (timer !== null) clearTimeout(timer);
+        timer = null;
+        dueAt = Number.POSITIVE_INFINITY;
+    };
+    const fire = ()=>{
+        if (settled) return;
+        cancel();
+        reopen();
+    };
+    /** Reopen no later than `atMs`; an earlier due time already set wins. */ const arm = (atMs)=>{
+        if (settled || atMs >= dueAt) return;
+        if (atMs <= Date.now()) {
+            fire();
+            return;
+        }
+        if (timer !== null) clearTimeout(timer);
+        dueAt = atMs;
+        timer = setTimeout(fire, atMs - Date.now());
+    };
+    const onArrival = ()=>{
+        if (tabIsHidden()) return;
+        arm(scheduledAt + SESSION_REFUSED_RETRY_DELAY_MS);
+    };
+    // `visibilitychange` fires on the way INTO hidden as well as out of it.
+    const onVisibilityChange = ()=>{
+        if (tabIsHidden()) disarm();
+        else onArrival();
+    };
+    const cancel = ()=>{
+        settled = true;
+        disarm();
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        }
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('focus', onArrival);
+        }
+    };
+    if (typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('focus', onArrival);
+    }
+    if (!tabIsHidden()) arm(scheduledAt + refusedRetryDelayMs(streakStartedAt));
+    return cancel;
+}
+/**
+ * The same seam in the other direction: the app telling refused listeners
+ * that the session came back (AGL-1066).
+ *
+ * ## Why this has to exist
+ *
+ * A refused listen recovers today only because the retry loop never stops —
+ * every reopen is another chance for the token to have attached. That is also
+ * the single reason the AGL-664 in-place re-auth works at all: nothing else
+ * re-subscribes. The hooks' effects depend on the query's identity
+ * (`[ref.firestore, ref.path]` and each caller's `deps`), and a `stale`-reason
+ * re-auth signs the same uid back in, so no dependency changes and no effect
+ * re-runs. `AuthenticatedLayout` deliberately holds the tree MOUNTED while a
+ * re-auth prompt is pending (AGL-664), which is what makes "resume exactly
+ * where you were" true — and it is exactly why a remount cannot be relied on
+ * to reopen anything.
+ *
+ * So any change that lets a refusal streak go terminal — the AGL-1066 item-3
+ * flip — needs this channel first, or a user who re-authenticates
+ * successfully sits in front of an errored console until they reload.
+ *
+ * ## What may broadcast, and what must not
+ *
+ * A heal is a RECOVERY FROM DENIAL, not any token event. Firebase refreshes
+ * the ID token roughly hourly; broadcasting on that would reopen every
+ * listener in the console on a timer for no reason. The console broadcasts
+ * from one place — a session fault that has been resolved — see
+ * `apps/console/utils/session-heal.ts`.
+ *
+ * Subscribers gate themselves as well: a listener the server is NOT refusing
+ * ignores the broadcast entirely, so even a spurious heal costs nothing.
+ * Nothing here clears `serverDenied` or `deniedStreak` — only a snapshot the
+ * server answered is evidence, and that invariant does not bend for a
+ * hopeful signal from the auth layer.
+ */ const healListeners = new Set();
+/**
+ * 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 function subscribeFirestoreSessionHeal(listener) {
+    healListeners.add(listener);
+    return ()=>void healListeners.delete(listener);
+}
+/**
+ * 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 function reportFirestoreSessionHeal() {
+    for (const listener of [
+        ...healListeners
+    ])listener();
+}
+/**
+ * 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 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 function denialLabelForQuery(target) {
+    var _candidate_parent;
+    const candidate = target;
+    if (!candidate) return undefined;
+    // A document listen: name the collection that holds it, not the document,
+    // so two docs in one collection stay ONE piece of evidence.
+    if ((_candidate_parent = candidate.parent) == null ? void 0 : _candidate_parent.path) return candidate.parent.path;
+    if (candidate.type === 'collection' && candidate.path) return candidate.path;
+    return undefined;
+}
+
+//# sourceMappingURL=firestore-denial-reporter.js.map

package/src/lib/hooks/firestore-denial-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/firestore-denial-reporter.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 * Let a LISTENER tell the app its reads are being refused (AGL-1066).\n *\n * `session-health` was built around one-shot reads, because that is where\n * AGL-1062 was first noticed. The console is listener-first, so the detector\n * was watching the read style the console barely uses: only four one-shot\n * call sites pass a collection label, one of them fires once per mount and\n * so can never recur inside the 60s window, and none of the pages carrying a\n * stale-write guard issues a labelled read at all. The verdict was\n * unreachable on the surfaces that needed it.\n *\n * Listeners are on every page, and they already know which collection they\n * are reading, so labelling is free rather than something a caller must\n * remember. This is the seam that lets them report without the library\n * importing the app: the console registers `reportDeniedRead` at startup and\n * the hooks call it through here. An unregistered reporter is a no-op, which\n * is what the tenant runtime wants — it has no client Firestore at all.\n *\n * ## Why this cannot fire offline\n *\n * Only `permission-denied` is ever reported. A client that has simply lost\n * the network gets no error callback at all — the listen sits there and the\n * cache keeps answering — and any one-shot it does make fails `unavailable`.\n * That is what keeps the whole mechanism from mistaking a tunnel for a dead\n * session, and it is why callers must NOT relax the code check.\n *\n * The channel runs both ways: see {@link reportFirestoreSessionHeal} at the\n * bottom of this file for the return leg, which is how a refused listener\n * learns the session came back. It lives here rather than in a module of its\n * own because a heal is defined entirely in terms of the denial it reverses —\n * split them and someone broadcasts one without the other's rules.\n */\n\nexport interface FirestoreSessionReporters {\n  /** A listen was refused past the budget; names the collection. */\n  onDenied: (collection?: string) => void\n  /**\n   * A listen was answered BY THE SERVER.\n   *\n   * Reported as well as the denials, and it is what keeps this safe to turn\n   * on. A scoped collaborator (AGL-1041) has collections they may not read\n   * by design, and with listeners reporting they could otherwise accumulate\n   * two denied collections and be told their session is dead. But their\n   * other listens keep succeeding against the server, and one server answer\n   * clears the evidence outright — a genuinely dead session has no such\n   * answer to offer, so it is the discriminator the denial count alone\n   * cannot be.\n   *\n   * A CACHED snapshot must never be passed here; it proves nothing.\n   */\n  onServerRead: () => void\n}\n\nlet reporters: FirestoreSessionReporters | null = null\n\n/**\n * Register the app's reporters. Called once, by the app that owns\n * `session-health`. Pass `null` to unregister (tests).\n */\nexport function setFirestoreSessionReporters(\n  next: FirestoreSessionReporters | null,\n): void {\n  reporters = next\n}\n\n/** Report a refused listen. No-op when nothing is registered. */\nexport function reportFirestoreDenial(collection?: string): void {\n  reporters?.onDenied(collection)\n}\n\n/** Report a listen the SERVER answered. No-op when nothing is registered. */\nexport function reportFirestoreServerRead(): void {\n  noteFirestoreServerRead()\n  reporters?.onServerRead()\n}\n\n/**\n * When ANY listener in this tab last got a server-answered snapshot.\n *\n * Library-internal evidence, kept regardless of whether app reporters are\n * registered — `helpers/use-doc` deliberately does not feed `session-health`\n * (its callers are the besigner document family, where a false verdict hurts\n * most) but its server answers are still proof the session can read, and\n * {@link refusedRetryDelayMs} needs that proof from every hook.\n */\nlet lastServerReadAt = 0\n\n/**\n * Record a server-answered snapshot WITHOUT reporting to `session-health`.\n * `reportFirestoreServerRead` calls this; `helpers/use-doc` calls only this.\n */\nexport function noteFirestoreServerRead(): void {\n  lastServerReadAt = Date.now()\n}\n\n/** Test seam — the evidence is module scope by design. */\nexport function resetFirestoreServerReadEvidence(): void {\n  lastServerReadAt = 0\n}\n\n/**\n * Cadence for a refusal streak that has outlived the retry budget (AGL-1066).\n *\n * A `permission-denied` has two very different causes and the client cannot\n * tell them apart from the error alone:\n *\n *  - a SESSION fault — stale token, App Check hiccup, an AGL-1143 SSO\n *    session that refuses everything. Every listener in the tab is refused,\n *    and the heal is an AGL-664 in-place re-auth or a token that attaches\n *    late. A young fault usually heals within seconds, so it starts at 2s.\n *\n *  - a RULES denial — the ref itself is one this user may never read (a\n *    sentinel id, a scoped collaborator's off-limits collection). Only a\n *    rules change (a membership granted mid-session) can end it, so it\n *    starts at 60s (AGL-1440).\n *\n * The discriminator is the one this module already trusts for the\n * session-health verdict: A GENUINELY DEAD SESSION HAS NO SERVER ANSWER TO\n * OFFER. If any listener has been answered by the server since this\n * listener's streak began, the session can read and this refusal is about\n * the ref.\n *\n * Either way the delay then grows with the streak's age — a tenth of it, up\n * to five minutes (AGL-2945). A refusal that has lasted ten minutes is\n * unlikely to end in the next two seconds, and refused listens are not free:\n * they bill reads (AGL-2944), so a fixed cadence made every console left open\n * on a dead session a standing cost of 1,800 refusals an hour per listener.\n * Per listener a session fault now costs ~70 in its first hour and 12 an hour\n * after; a rules denial ~35, then 12. The listen is never abandoned.\n *\n * What the fast fixed cadence used to protect is kept as WAKES rather than as\n * a timer — see {@link scheduleRefusedReopen}. The AGL-664 heal broadcast, the\n * tab becoming visible and the window regaining focus all reopen at once, so\n * the slow road only governs a page nobody is touching. The AGL-1358 write\n * guards wait on a save someone clicks, which puts someone at the page.\n */\nexport const SESSION_REFUSED_RETRY_DELAY_MS = 2_000\nexport const RULES_REFUSED_RETRY_DELAY_MS = 60_000\n/** The longest a refused listen ever waits for its next reopen. */\nexport const REFUSED_RETRY_CEILING_MS = 5 * 60_000\n/** The delay is the streak's age divided by this, between floor and ceiling. */\nconst REFUSED_RETRY_AGE_DIVISOR = 10\n\n/**\n * The delay before a spent refusal streak reopens its listen.\n *\n * `streakStartedAt` is when the streak's FIRST refusal landed. Evaluated per\n * retry, not once: evidence that arrives mid-streak (another listener's\n * first server answer) raises the floor from the next reopen on, and the age\n * term keeps growing for as long as the streak lasts.\n */\nexport function refusedRetryDelayMs(streakStartedAt: number): number {\n  const floor =\n    lastServerReadAt > streakStartedAt\n      ? RULES_REFUSED_RETRY_DELAY_MS\n      : SESSION_REFUSED_RETRY_DELAY_MS\n  // A backwards clock reads as a young streak, never as a negative age.\n  const age = Math.max(0, Date.now() - streakStartedAt)\n  return Math.min(\n    REFUSED_RETRY_CEILING_MS,\n    Math.max(floor, age / REFUSED_RETRY_AGE_DIVISOR),\n  )\n}\n\n/** No `document` (SSR, a worker) counts as visible: nothing to wait for. */\nfunction tabIsHidden(): boolean {\n  return (\n    typeof document !== 'undefined' && document.visibilityState === 'hidden'\n  )\n}\n\n/**\n * Schedule the reopen of a spent refusal streak, and return its cancel.\n *\n * In a visible tab the reopen waits {@link refusedRetryDelayMs}. A HIDDEN tab\n * sets no timer at all: nobody is there to heal for, and an unattended tab on\n * a dead session was the Aug 20 – Sep 4 storm — 400K–1.7M rules denials a day\n * in ~8-hour blocks, ~$2 of reads the `read_ops_count` metric never showed\n * (AGL-2944). A tab that goes hidden while a reopen is pending drops its\n * timer and waits the same way.\n *\n * A person arriving reopens at once, whatever the cadence: the tab becoming\n * visible or the window regaining focus. (The heal broadcast is the third\n * instant road; the hooks subscribe to it themselves.) Arrivals are held to\n * one reopen no sooner than {@link SESSION_REFUSED_RETRY_DELAY_MS} after the\n * refusal that scheduled this, so focus churn can never run the loop faster\n * than the fixed cadence it replaced.\n */\nexport function scheduleRefusedReopen(\n  reopen: () => void,\n  streakStartedAt: number,\n): () => void {\n  const scheduledAt = Date.now()\n  let timer: ReturnType<typeof setTimeout> | null = null\n  let dueAt = Number.POSITIVE_INFINITY\n  let settled = false\n\n  const disarm = () => {\n    if (timer !== null) clearTimeout(timer)\n    timer = null\n    dueAt = Number.POSITIVE_INFINITY\n  }\n\n  const fire = () => {\n    if (settled) return\n    cancel()\n    reopen()\n  }\n\n  /** Reopen no later than `atMs`; an earlier due time already set wins. */\n  const arm = (atMs: number) => {\n    if (settled || atMs >= dueAt) return\n    if (atMs <= Date.now()) {\n      fire()\n      return\n    }\n    if (timer !== null) clearTimeout(timer)\n    dueAt = atMs\n    timer = setTimeout(fire, atMs - Date.now())\n  }\n\n  const onArrival = () => {\n    if (tabIsHidden()) return\n    arm(scheduledAt + SESSION_REFUSED_RETRY_DELAY_MS)\n  }\n\n  // `visibilitychange` fires on the way INTO hidden as well as out of it.\n  const onVisibilityChange = () => {\n    if (tabIsHidden()) disarm()\n    else onArrival()\n  }\n\n  const cancel = () => {\n    settled = true\n    disarm()\n    if (typeof document !== 'undefined') {\n      document.removeEventListener('visibilitychange', onVisibilityChange)\n    }\n    if (typeof window !== 'undefined') {\n      window.removeEventListener('focus', onArrival)\n    }\n  }\n\n  if (typeof document !== 'undefined') {\n    document.addEventListener('visibilitychange', onVisibilityChange)\n  }\n  if (typeof window !== 'undefined') {\n    window.addEventListener('focus', onArrival)\n  }\n  if (!tabIsHidden()) arm(scheduledAt + refusedRetryDelayMs(streakStartedAt))\n\n  return cancel\n}\n\n/**\n * The same seam in the other direction: the app telling refused listeners\n * that the session came back (AGL-1066).\n *\n * ## Why this has to exist\n *\n * A refused listen recovers today only because the retry loop never stops —\n * every reopen is another chance for the token to have attached. That is also\n * the single reason the AGL-664 in-place re-auth works at all: nothing else\n * re-subscribes. The hooks' effects depend on the query's identity\n * (`[ref.firestore, ref.path]` and each caller's `deps`), and a `stale`-reason\n * re-auth signs the same uid back in, so no dependency changes and no effect\n * re-runs. `AuthenticatedLayout` deliberately holds the tree MOUNTED while a\n * re-auth prompt is pending (AGL-664), which is what makes \"resume exactly\n * where you were\" true — and it is exactly why a remount cannot be relied on\n * to reopen anything.\n *\n * So any change that lets a refusal streak go terminal — the AGL-1066 item-3\n * flip — needs this channel first, or a user who re-authenticates\n * successfully sits in front of an errored console until they reload.\n *\n * ## What may broadcast, and what must not\n *\n * A heal is a RECOVERY FROM DENIAL, not any token event. Firebase refreshes\n * the ID token roughly hourly; broadcasting on that would reopen every\n * listener in the console on a timer for no reason. The console broadcasts\n * from one place — a session fault that has been resolved — see\n * `apps/console/utils/session-heal.ts`.\n *\n * Subscribers gate themselves as well: a listener the server is NOT refusing\n * ignores the broadcast entirely, so even a spurious heal costs nothing.\n * Nothing here clears `serverDenied` or `deniedStreak` — only a snapshot the\n * server answered is evidence, and that invariant does not bend for a\n * hopeful signal from the auth layer.\n */\nconst healListeners = new Set<() => void>()\n\n/**\n * Listen for \"the session may have recovered\". Returns the unsubscribe.\n *\n * The callback runs synchronously inside {@link reportFirestoreSessionHeal},\n * so it must be cheap and must tolerate being called when there is nothing\n * to do.\n */\nexport function subscribeFirestoreSessionHeal(\n  listener: () => void,\n): () => void {\n  healListeners.add(listener)\n  return () => void healListeners.delete(listener)\n}\n\n/**\n * Tell every listener the session may have recovered.\n *\n * Iterates a COPY: a subscriber reopening its listen can unsubscribe (an\n * unmount racing the broadcast) and mutating the set mid-iteration would skip\n * the next one.\n */\nexport function reportFirestoreSessionHeal(): void {\n  for (const listener of [...healListeners]) listener()\n}\n\n/**\n * Consecutive refusals before a listener says anything.\n *\n * Matched to `firestore-one-shot-retry`'s budget so both read styles apply\n * the same bar: surviving this many means it is not the AGL-216/217\n * post-sign-in race, which resolves in well under two seconds.\n *\n * The streak this counts is NOT the hook's retry `attempt`. That one is\n * reset by any snapshot, including one served from cache, so under\n * `persistentLocalCache` it never reaches any threshold at all — see\n * `use-firestore-collection-cached-retry.spec.ts`. This one is reset only by\n * a snapshot the SERVER answered, which is the only evidence that actually\n * bears on whether the session can read.\n */\nexport const DENIAL_STREAK_TO_REPORT = 5\n\n/**\n * The collection a listen was against, when it can be known from public API.\n *\n * `DocumentReference` exposes `parent`, and a `CollectionReference` exposes\n * `path`. A filtered `Query` exposes neither, and reaching into `_query` to\n * get one would be reading SDK internals — so those report `undefined` and\n * land in the shared `unknown` bucket. That can only ever fail to reach the\n * two-collection threshold, never trip it falsely, which is the right way\n * for this to degrade.\n */\nexport function denialLabelForQuery(target: unknown): string | undefined {\n  const candidate = target as\n    | { type?: string; path?: string; parent?: { path?: string } }\n    | null\n    | undefined\n  if (!candidate) return undefined\n  // A document listen: name the collection that holds it, not the document,\n  // so two docs in one collection stay ONE piece of evidence.\n  if (candidate.parent?.path) return candidate.parent.path\n  if (candidate.type === 'collection' && candidate.path) return candidate.path\n  return undefined\n}\n"],"names":["reporters","setFirestoreSessionReporters","next","reportFirestoreDenial","collection","onDenied","reportFirestoreServerRead","noteFirestoreServerRead","onServerRead","lastServerReadAt","Date","now","resetFirestoreServerReadEvidence","SESSION_REFUSED_RETRY_DELAY_MS","RULES_REFUSED_RETRY_DELAY_MS","REFUSED_RETRY_CEILING_MS","REFUSED_RETRY_AGE_DIVISOR","refusedRetryDelayMs","streakStartedAt","floor","age","Math","max","min","tabIsHidden","document","visibilityState","scheduleRefusedReopen","reopen","scheduledAt","timer","dueAt","Number","POSITIVE_INFINITY","settled","disarm","clearTimeout","fire","cancel","arm","atMs","setTimeout","onArrival","onVisibilityChange","removeEventListener","window","addEventListener","healListeners","Set","subscribeFirestoreSessionHeal","listener","add","delete","reportFirestoreSessionHeal","DENIAL_STREAK_TO_REPORT","denialLabelForQuery","target","candidate","undefined","parent","path","type"],"mappings":"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"}

package/src/lib/hooks/helpers/besigner-nodes-converter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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 DocumentReference } from 'firebase/firestore';
+/**
+ * Compression at rest for a besigner document that has no converter of its
+ * own — the two EMAIL editors (AGL-1151).
+ *
+ * ## Why a converter rather than decoding at the read site
+ *
+ * Both email besigners read their version with a bare `useFirestoreDoc` and
+ * write it with `saveNodesGuarded` on a bare `doc(...)`, and `nodes` has to
+ * be in ONE shape across four comparisons for either to work:
+ *
+ *  - `useBesignerDocument` diffs the arriving snapshot against its baseline to
+ *    decide whether somebody else has written, and against the tree it just
+ *    sent to recognise the echo of its own save;
+ *  - `saveNodesGuarded` re-reads inside its transaction and compares the
+ *    stored `nodes` against the baseline the editor presents.
+ *
+ * Decoding at the read site alone would leave the stored form on one side of
+ * those comparisons and a decoded map on the other, so every save would look
+ * like a conflict and be refused. A converter puts the decode BEFORE all four,
+ * which is why the screen, layout, component and form editors — which have
+ * carried converters since AGL-1151 — never had the problem.
+ *
+ * ## What it does not do
+ *
+ * It does not stamp `updatedAt`. The version converters do, because their
+ * callers do not; both email editors pass their own stamp, and the seeding
+ * writes pass the one they also put on the template document, so a stamp
+ * applied here would silently replace a value the caller is coordinating.
+ */
+export declare const besignerNodesConverter: {
+    toFirestore(data: Record<string, any>): {
+        [x: string]: any;
+    };
+    fromFirestore(snapshot: any, options: any): any;
+};
+/**
+ * The same document, read and written through {@link besignerNodesConverter}.
+ *
+ * A named wrapper rather than `.withConverter(...)` at each call site: an
+ * editor has to apply it to BOTH the ref it reads and the ref it saves
+ * through, and the failure when only one of them gets it is a save refused as
+ * a phantom conflict rather than anything that looks like a missing converter.
+ */
+export declare function withBesignerNodes<T>(ref: DocumentReference<any>): DocumentReference<T>;
+export default besignerNodesConverter;

package/src/lib/hooks/helpers/besigner-nodes-converter.js

@@ -0,0 +1,91 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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 { decodeStoredNodes, encodeStoredNodes } from "@aglyn/aglyn";
+import { Bytes } from "firebase/firestore";
+/**
+ * Compression at rest for a besigner document that has no converter of its
+ * own — the two EMAIL editors (AGL-1151).
+ *
+ * ## Why a converter rather than decoding at the read site
+ *
+ * Both email besigners read their version with a bare `useFirestoreDoc` and
+ * write it with `saveNodesGuarded` on a bare `doc(...)`, and `nodes` has to
+ * be in ONE shape across four comparisons for either to work:
+ *
+ *  - `useBesignerDocument` diffs the arriving snapshot against its baseline to
+ *    decide whether somebody else has written, and against the tree it just
+ *    sent to recognise the echo of its own save;
+ *  - `saveNodesGuarded` re-reads inside its transaction and compares the
+ *    stored `nodes` against the baseline the editor presents.
+ *
+ * Decoding at the read site alone would leave the stored form on one side of
+ * those comparisons and a decoded map on the other, so every save would look
+ * like a conflict and be refused. A converter puts the decode BEFORE all four,
+ * which is why the screen, layout, component and form editors — which have
+ * carried converters since AGL-1151 — never had the problem.
+ *
+ * ## What it does not do
+ *
+ * It does not stamp `updatedAt`. The version converters do, because their
+ * callers do not; both email editors pass their own stamp, and the seeding
+ * writes pass the one they also put on the template document, so a stamp
+ * applied here would silently replace a value the caller is coordinating.
+ */ export const besignerNodesConverter = {
+    toFirestore (data) {
+        const { $id } = data, rest = _object_without_properties_loose(data, [
+            "$id"
+        ]);
+        // Only emit `nodes` when the write actually carries them (AGL-1250).
+        // Encoding `rest.nodes` unconditionally would make a partial
+        // `setDoc(…, {merge: true})` — one that set some other field — ship an
+        // empty map, and merge faithfully merges that emptiness over the real
+        // tree, destroying the document.
+        if ((rest == null ? void 0 : rest.nodes) === undefined) return rest;
+        const nodes = encodeStoredNodes(rest.nodes);
+        // `encodeStoredNodes` passes an already-encoded value through, so a write
+        // that round-trips what it read cannot double-encode. `Bytes` is what the
+        // client SDK accepts for a bytes field.
+        return _extends({}, rest, nodes ? {
+            nodes: Bytes.fromUint8Array(nodes)
+        } : {});
+    },
+    fromFirestore (snapshot, options) {
+        if (!snapshot.exists()) return undefined;
+        const data = snapshot.data(options);
+        if ((data == null ? void 0 : data.nodes) === undefined) return data;
+        // BOTH forms, permanently. Every email version written before this
+        // converter is a plain map and nothing migrates them; `decodeStoredNodes`
+        // returns a plain map unchanged, so one call serves both.
+        return _extends({}, data, {
+            nodes: decodeStoredNodes(data.nodes)
+        });
+    }
+};
+/**
+ * The same document, read and written through {@link besignerNodesConverter}.
+ *
+ * A named wrapper rather than `.withConverter(...)` at each call site: an
+ * editor has to apply it to BOTH the ref it reads and the ref it saves
+ * through, and the failure when only one of them gets it is a save refused as
+ * a phantom conflict rather than anything that looks like a missing converter.
+ */ export function withBesignerNodes(ref) {
+    return ref.withConverter(besignerNodesConverter);
+}
+export default besignerNodesConverter;
+
+//# sourceMappingURL=besigner-nodes-converter.js.map

package/src/lib/hooks/helpers/besigner-nodes-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/besigner-nodes-converter.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 { decodeStoredNodes, encodeStoredNodes } from '@aglyn/aglyn'\nimport { Bytes, type DocumentReference } from 'firebase/firestore'\n\n/**\n * Compression at rest for a besigner document that has no converter of its\n * own — the two EMAIL editors (AGL-1151).\n *\n * ## Why a converter rather than decoding at the read site\n *\n * Both email besigners read their version with a bare `useFirestoreDoc` and\n * write it with `saveNodesGuarded` on a bare `doc(...)`, and `nodes` has to\n * be in ONE shape across four comparisons for either to work:\n *\n *  - `useBesignerDocument` diffs the arriving snapshot against its baseline to\n *    decide whether somebody else has written, and against the tree it just\n *    sent to recognise the echo of its own save;\n *  - `saveNodesGuarded` re-reads inside its transaction and compares the\n *    stored `nodes` against the baseline the editor presents.\n *\n * Decoding at the read site alone would leave the stored form on one side of\n * those comparisons and a decoded map on the other, so every save would look\n * like a conflict and be refused. A converter puts the decode BEFORE all four,\n * which is why the screen, layout, component and form editors — which have\n * carried converters since AGL-1151 — never had the problem.\n *\n * ## What it does not do\n *\n * It does not stamp `updatedAt`. The version converters do, because their\n * callers do not; both email editors pass their own stamp, and the seeding\n * writes pass the one they also put on the template document, so a stamp\n * applied here would silently replace a value the caller is coordinating.\n */\nexport const besignerNodesConverter = {\n  toFirestore(data: Record<string, any>) {\n    const { $id, ...rest } = data\n    // Only emit `nodes` when the write actually carries them (AGL-1250).\n    // Encoding `rest.nodes` unconditionally would make a partial\n    // `setDoc(…, {merge: true})` — one that set some other field — ship an\n    // empty map, and merge faithfully merges that emptiness over the real\n    // tree, destroying the document.\n    if (rest?.nodes === undefined) return rest\n    const nodes = encodeStoredNodes(rest.nodes)\n    // `encodeStoredNodes` passes an already-encoded value through, so a write\n    // that round-trips what it read cannot double-encode. `Bytes` is what the\n    // client SDK accepts for a bytes field.\n    return { ...rest, ...(nodes ? { nodes: Bytes.fromUint8Array(nodes) } : {}) }\n  },\n  fromFirestore(snapshot: any, options: any) {\n    if (!snapshot.exists()) return undefined\n    const data = snapshot.data(options)\n    if (data?.nodes === undefined) return data\n    // BOTH forms, permanently. Every email version written before this\n    // converter is a plain map and nothing migrates them; `decodeStoredNodes`\n    // returns a plain map unchanged, so one call serves both.\n    return { ...data, nodes: decodeStoredNodes(data.nodes) }\n  },\n}\n\n/**\n * The same document, read and written through {@link besignerNodesConverter}.\n *\n * A named wrapper rather than `.withConverter(...)` at each call site: an\n * editor has to apply it to BOTH the ref it reads and the ref it saves\n * through, and the failure when only one of them gets it is a save refused as\n * a phantom conflict rather than anything that looks like a missing converter.\n */\nexport function withBesignerNodes<T>(\n  ref: DocumentReference<any>,\n): DocumentReference<T> {\n  return ref.withConverter(\n    besignerNodesConverter as never,\n  ) as DocumentReference<T>\n}\n\nexport default besignerNodesConverter\n"],"names":["decodeStoredNodes","encodeStoredNodes","Bytes","besignerNodesConverter","toFirestore","data","$id","rest","nodes","undefined","fromUint8Array","fromFirestore","snapshot","options","exists","withBesignerNodes","ref","withConverter"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,EAAEC,iBAAiB,QAAQ,eAAc;AACnE,SAASC,KAAK,QAAgC,qBAAoB;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,yBAAyB;IACpCC,aAAYC,IAAyB;QACnC,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;QACzB,qEAAqE;QACrE,6DAA6D;QAC7D,uEAAuE;QACvE,sEAAsE;QACtE,iCAAiC;QACjC,IAAIE,CAAAA,wBAAAA,KAAMC,KAAK,MAAKC,WAAW,OAAOF;QACtC,MAAMC,QAAQP,kBAAkBM,KAAKC,KAAK;QAC1C,0EAA0E;QAC1E,0EAA0E;QAC1E,wCAAwC;QACxC,OAAO,aAAKD,MAAUC,QAAQ;YAAEA,OAAON,MAAMQ,cAAc,CAACF;QAAO,IAAI,CAAC;IAC1E;IACAG,eAAcC,QAAa,EAAEC,OAAY;QACvC,IAAI,CAACD,SAASE,MAAM,IAAI,OAAOL;QAC/B,MAAMJ,OAAOO,SAASP,IAAI,CAACQ;QAC3B,IAAIR,CAAAA,wBAAAA,KAAMG,KAAK,MAAKC,WAAW,OAAOJ;QACtC,mEAAmE;QACnE,0EAA0E;QAC1E,0DAA0D;QAC1D,OAAO,aAAKA;YAAMG,OAAOR,kBAAkBK,KAAKG,KAAK;;IACvD;AACF,EAAC;AAED;;;;;;;CAOC,GACD,OAAO,SAASO,kBACdC,GAA2B;IAE3B,OAAOA,IAAIC,aAAa,CACtBd;AAEJ;AAEA,eAAeA,uBAAsB"}

package/src/lib/hooks/helpers/guarded-nodes-save.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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 DocumentReference } from 'firebase/firestore';
+/**
+ * What the editor believes the stored document looked like when it last
+ * agreed with it. Both fields optional: an absent baseline means "never
+ * established", which must not refuse the save (see `hasConcurrentWrite`).
+ */
+export interface NodesSaveBaseline {
+    /** `versionStamp(...)` of the document's `updatedAt` at load/last save. */
+    baseStamp?: string | null;
+    /** The stored nodes as of that agreement, in STORED shape. */
+    baseNodes?: unknown;
+}
+/**
+ * Persists a besigner node map only if the stored document still matches the
+ * baseline the editor loaded (AGL-1301).
+ *
+ * The AGL-674 guard is listener-based, so a save clicked in the window
+ * between another writer's commit and the local snapshot's delivery still
+ * overwrote it — the guard had simply not heard yet. Running the same check
+ * inside a Firestore transaction closes that window: the `get` is served by
+ * the backend (never the local cache), the check runs against what is
+ * actually stored, and the write only commits if nothing moved. Contention
+ * during the transaction re-runs it against fresh data, so the late writer
+ * aborts rather than winning by timing.
+ *
+ * TWO preconditions, deliberately:
+ *
+ * - The `updatedAt` stamp, same equality-only comparison as the listener
+ *   guard.
+ * - The stored `nodes` content itself. `updatedAt` is an app-level FIELD
+ *   that a writer can forget — admin backfills have updated `nodes` without
+ *   touching it, and such a write was invisible to the stamp and got
+ *   clobbered. The web client SDK exposes no server-side `updateTime` on a
+ *   snapshot (`snapshot.metadata` carries only `hasPendingWrites` /
+ *   `fromCache`; document update times are Admin-SDK-only), so comparing
+ *   the content is the strongest check actually available to this client —
+ *   and it is exact: this save only ever writes `nodes` (+ stamp), so
+ *   "did `nodes` change under me" is precisely the conflict that loses work.
+ *
+ * Aborts by throwing `ConcurrentEditError`, which `useBesignerDocument`
+ * surfaces through the existing refusal UX. A converter on `ref` applies as
+ * usual, so compressed-at-rest documents stay compressed and keep stamping
+ * `updatedAt` on write.
+ *
+ * Trade-off, accepted: a transaction requires the backend, so this save no
+ * longer queues offline. A conflict guard that consults a local cache would
+ * be theatre — the AGL-674 refusal already implies "the server has spoken".
+ *
+ * ## Why this did NOT change when the client relaxed (AGL-2486)
+ *
+ * The client no longer refuses merely because the stored version moved: with
+ * the co-edit mirror running it usually already holds what the other writer
+ * stored, so its own write is a superset (`incorporatesStoredNodes`). What
+ * it does with that evidence is advance its BASELINE onto the write it has
+ * incorporated — and this precondition is what makes that safe. It is
+ * unchanged and strictly stricter: the baseline the client presents must
+ * still match what is actually stored when the transaction reads it, so
+ * anything that lands between the client's decision and this commit moves
+ * `nodes` away from it and aborts. The docs' promise that "even a save
+ * racing the conflict by milliseconds is refused" therefore holds exactly as
+ * before; the client simply stopped refusing saves this would have accepted.
+ */
+export declare function saveNodesGuarded<T>(ref: DocumentReference<T>, data: Partial<T>, baseline?: NodesSaveBaseline): Promise<void>;
+export default saveNodesGuarded;