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

package/src/lib/hooks/helpers/guarded-nodes-save.js

@@ -0,0 +1,89 @@
+/**
+ * @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 { ConcurrentEditError, hasConcurrentWrite, versionStamp } from "@aglyn/aglyn";
+import { runTransaction } from "firebase/firestore";
+import isEqual from "lodash-es/isEqual.js";
+/**
+ * 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 async function saveNodesGuarded(ref, data, baseline) {
+    await runTransaction(ref.firestore, async (transaction)=>{
+        const snapshot = await transaction.get(ref);
+        const stored = snapshot.data();
+        if (stored) {
+            var _ref;
+            const storedStamp = versionStamp(stored.updatedAt);
+            if (hasConcurrentWrite((_ref = baseline == null ? void 0 : baseline.baseStamp) != null ? _ref : null, storedStamp)) {
+                throw new ConcurrentEditError();
+            }
+            if ((baseline == null ? void 0 : baseline.baseNodes) != null && stored.nodes != null && !isEqual(stored.nodes, baseline.baseNodes)) {
+                throw new ConcurrentEditError();
+            }
+        }
+        transaction.set(ref, data, {
+            merge: true
+        });
+    });
+}
+export default saveNodesGuarded;
+
+//# sourceMappingURL=guarded-nodes-save.js.map

package/src/lib/hooks/helpers/guarded-nodes-save.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/guarded-nodes-save.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 {\n  ConcurrentEditError,\n  hasConcurrentWrite,\n  versionStamp,\n} from '@aglyn/aglyn'\nimport { runTransaction, type DocumentReference } from 'firebase/firestore'\nimport isEqual from 'lodash-es/isEqual.js'\n\n/**\n * What the editor believes the stored document looked like when it last\n * agreed with it. Both fields optional: an absent baseline means \"never\n * established\", which must not refuse the save (see `hasConcurrentWrite`).\n */\nexport interface NodesSaveBaseline {\n  /** `versionStamp(...)` of the document's `updatedAt` at load/last save. */\n  baseStamp?: string | null\n  /** The stored nodes as of that agreement, in STORED shape. */\n  baseNodes?: unknown\n}\n\n/**\n * Persists a besigner node map only if the stored document still matches the\n * baseline the editor loaded (AGL-1301).\n *\n * The AGL-674 guard is listener-based, so a save clicked in the window\n * between another writer's commit and the local snapshot's delivery still\n * overwrote it — the guard had simply not heard yet. Running the same check\n * inside a Firestore transaction closes that window: the `get` is served by\n * the backend (never the local cache), the check runs against what is\n * actually stored, and the write only commits if nothing moved. Contention\n * during the transaction re-runs it against fresh data, so the late writer\n * aborts rather than winning by timing.\n *\n * TWO preconditions, deliberately:\n *\n * - The `updatedAt` stamp, same equality-only comparison as the listener\n *   guard.\n * - The stored `nodes` content itself. `updatedAt` is an app-level FIELD\n *   that a writer can forget — admin backfills have updated `nodes` without\n *   touching it, and such a write was invisible to the stamp and got\n *   clobbered. The web client SDK exposes no server-side `updateTime` on a\n *   snapshot (`snapshot.metadata` carries only `hasPendingWrites` /\n *   `fromCache`; document update times are Admin-SDK-only), so comparing\n *   the content is the strongest check actually available to this client —\n *   and it is exact: this save only ever writes `nodes` (+ stamp), so\n *   \"did `nodes` change under me\" is precisely the conflict that loses work.\n *\n * Aborts by throwing `ConcurrentEditError`, which `useBesignerDocument`\n * surfaces through the existing refusal UX. A converter on `ref` applies as\n * usual, so compressed-at-rest documents stay compressed and keep stamping\n * `updatedAt` on write.\n *\n * Trade-off, accepted: a transaction requires the backend, so this save no\n * longer queues offline. A conflict guard that consults a local cache would\n * be theatre — the AGL-674 refusal already implies \"the server has spoken\".\n *\n * ## Why this did NOT change when the client relaxed (AGL-2486)\n *\n * The client no longer refuses merely because the stored version moved: with\n * the co-edit mirror running it usually already holds what the other writer\n * stored, so its own write is a superset (`incorporatesStoredNodes`). What\n * it does with that evidence is advance its BASELINE onto the write it has\n * incorporated — and this precondition is what makes that safe. It is\n * unchanged and strictly stricter: the baseline the client presents must\n * still match what is actually stored when the transaction reads it, so\n * anything that lands between the client's decision and this commit moves\n * `nodes` away from it and aborts. The docs' promise that \"even a save\n * racing the conflict by milliseconds is refused\" therefore holds exactly as\n * before; the client simply stopped refusing saves this would have accepted.\n */\nexport async function saveNodesGuarded<T>(\n  ref: DocumentReference<T>,\n  data: Partial<T>,\n  baseline?: NodesSaveBaseline,\n): Promise<void> {\n  await runTransaction(ref.firestore, async (transaction) => {\n    const snapshot = await transaction.get(ref)\n    const stored = snapshot.data() as\n      | { updatedAt?: unknown; nodes?: unknown }\n      | undefined\n    if (stored) {\n      const storedStamp = versionStamp(stored.updatedAt)\n      if (hasConcurrentWrite(baseline?.baseStamp ?? null, storedStamp)) {\n        throw new ConcurrentEditError()\n      }\n      if (\n        baseline?.baseNodes != null &&\n        stored.nodes != null &&\n        !isEqual(stored.nodes, baseline.baseNodes)\n      ) {\n        throw new ConcurrentEditError()\n      }\n    }\n    transaction.set(ref, data, { merge: true })\n  })\n}\n\nexport default saveNodesGuarded\n"],"names":["ConcurrentEditError","hasConcurrentWrite","versionStamp","runTransaction","isEqual","saveNodesGuarded","ref","data","baseline","firestore","transaction","snapshot","get","stored","storedStamp","updatedAt","baseStamp","baseNodes","nodes","set","merge"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,mBAAmB,EACnBC,kBAAkB,EAClBC,YAAY,QACP,eAAc;AACrB,SAASC,cAAc,QAAgC,qBAAoB;AAC3E,OAAOC,aAAa,uBAAsB;AAc1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDC,GACD,OAAO,eAAeC,iBACpBC,GAAyB,EACzBC,IAAgB,EAChBC,QAA4B;IAE5B,MAAML,eAAeG,IAAIG,SAAS,EAAE,OAAOC;QACzC,MAAMC,WAAW,MAAMD,YAAYE,GAAG,CAACN;QACvC,MAAMO,SAASF,SAASJ,IAAI;QAG5B,IAAIM,QAAQ;;YACV,MAAMC,cAAcZ,aAAaW,OAAOE,SAAS;YACjD,IAAId,2BAAmBO,4BAAAA,SAAUQ,SAAS,mBAAI,MAAMF,cAAc;gBAChE,MAAM,IAAId;YACZ;YACA,IACEQ,CAAAA,4BAAAA,SAAUS,SAAS,KAAI,QACvBJ,OAAOK,KAAK,IAAI,QAChB,CAACd,QAAQS,OAAOK,KAAK,EAAEV,SAASS,SAAS,GACzC;gBACA,MAAM,IAAIjB;YACZ;QACF;QACAU,YAAYS,GAAG,CAACb,KAAKC,MAAM;YAAEa,OAAO;QAAK;IAC3C;AACF;AAEA,eAAef,iBAAgB"}

package/src/lib/hooks/helpers/guarded-seed-write.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @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.
+ */
+/**
+ * Refuse a whole-object write whose form was seeded from a read we cannot
+ * trust (AGL-1356, AGL-1358, AGL-1066).
+ *
+ * ## The shape this exists for
+ *
+ * A form seeded from a Firestore LISTENER, saved with a payload that carries
+ * every field rather than the one that changed. `merge: true` protects
+ * nothing there — the untouched fields are all present in the payload — so
+ * saving one edit rewrites the rest to whatever the seed held. If the seed
+ * came from IndexedDB during a stale session, "whatever the seed held" can
+ * be arbitrarily old, and the user's real values are destroyed by a save
+ * they asked for and had every reason to expect to be safe.
+ *
+ * ## Why it WRAPS the write instead of preceding it
+ *
+ * The guards this replaces sat in front of their writes as early returns,
+ * which is a shape you can have and still write — add a branch, reorder a
+ * line, and the guard is decoration. Here the write is only reachable
+ * THROUGH the verdict, so a call site cannot keep the guard and lose the
+ * protection. It also makes the refusal testable as a refusal: assert the
+ * inner function never ran.
+ *
+ * ## The three signals, in the order they are worth trusting
+ *
+ * 1. `fromCache` — the server never confirmed what is on screen (AGL-1066).
+ *    This is the one that catches the dangerous case, because a cache-served
+ *    read looks completely healthy: populated form, plausible values. It is
+ *    per-listener ground truth from the SDK, so it needs no threshold and no
+ *    window, and it clears itself the instant a server snapshot lands. It
+ *    leads because it is also the more ACCURATE explanation whenever it is
+ *    true — see the ordering note on `checkSeedFreshness`.
+ * 2. `unreadable` — the read FAILED and there is nothing cached behind it
+ *    (AGL-1143). Saving would write blanks over a populated document.
+ * 3. `staleSession` — the console's own heuristic. Kept because it means
+ *    something the other two do not (the SESSION is dead, not merely
+ *    unconfirmed), but it must never be the ONLY guard: it needs two
+ *    distinct labelled collections denied inside 60s, which is unreachable
+ *    on a listener-only page. That was exactly how AGL-1356 stayed open.
+ *
+ * ## Why this lives in the library rather than the console (AGL-1358)
+ *
+ * Most of the ~forty sites wearing this shape are plugin cards in
+ * `libs/plugins/**`, which cannot import from `apps/console`. The guard
+ * itself is pure, and `fromCache` — the signal that actually fires —
+ * originates here, on the listener hooks. What it cannot own is
+ * `session-health`, which is console state.
+ *
+ * So the third signal is INJECTED, through the same seam
+ * `firestore-denial-reporter` already uses for the reverse direction: the
+ * console registers a check at startup and the guard pulls it. That keeps a
+ * single guard for every call site with no new dependency edge and nothing
+ * inverted — the library still knows nothing about the app. An unregistered
+ * check simply reports "not stale", which is what the tenant runtime and the
+ * unit tests want; the other two signals are unaffected, and they are the
+ * ones the doc above says must carry the guard anyway.
+ */
+export type StaleSeedReason = 'unreadable' | 'unconfirmed' | 'stale-session';
+/**
+ * Register the app's stale-session verdict. Called once, by the app that owns
+ * `session-health`. Pass `null` to unregister (tests).
+ *
+ * Registered at module scope alongside `setFirestoreSessionReporters` rather
+ * than in an effect, for the same reason: a save can be clicked before any
+ * effect has run, and a guard that consults a check which does not exist yet
+ * silently loses its third signal.
+ */
+export declare function setStaleSessionCheck(check: (() => boolean) | null): void;
+export interface GuardedSeedWriteOptions {
+    /**
+     * What is being saved, in the user's words — "profile", "settings".
+     * Used to build the refusal message, so it reads naturally in a sentence
+     * like "Your profile could not be loaded".
+     */
+    subject: string;
+    /** The seeding read FAILED (`status === 'error'`). */
+    unreadable?: boolean;
+    /** The seeding snapshot came from cache (`metadata.fromCache`). */
+    fromCache?: boolean;
+    /**
+     * Also consult `session-health`. On by default; the only reason to turn it
+     * off is a surface that deliberately writes during a known-degraded
+     * session.
+     */
+    checkSession?: boolean;
+}
+export interface GuardedSeedWriteResult {
+    /** True when the write RAN. */
+    ok: boolean;
+    /** Why it did not run. */
+    reason?: StaleSeedReason;
+    /**
+     * What to tell the user. Always populated when `ok` is false — a refused
+     * save that says nothing is its own bug: the user retypes the form and
+     * tries again, and the second attempt is refused just as silently.
+     */
+    message?: string;
+}
+/** The verdict on its own, for a caller that needs it before the click. */
+export declare function checkSeedFreshness(options: GuardedSeedWriteOptions): GuardedSeedWriteResult;
+/**
+ * Run `write` only if the seed can be trusted.
+ *
+ * Never throws on refusal — the caller reports `message` and leaves the
+ * user's typed values on screen, because the whole point is that we are not
+ * confident enough to touch the stored document, not that the input was bad.
+ */
+export declare function writeGuardedBySeed(options: GuardedSeedWriteOptions, write: () => Promise<void>): Promise<GuardedSeedWriteResult>;
+export default writeGuardedBySeed;

package/src/lib/hooks/helpers/guarded-seed-write.js

@@ -0,0 +1,193 @@
+/**
+ * @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.
+ */ /**
+ * Refuse a whole-object write whose form was seeded from a read we cannot
+ * trust (AGL-1356, AGL-1358, AGL-1066).
+ *
+ * ## The shape this exists for
+ *
+ * A form seeded from a Firestore LISTENER, saved with a payload that carries
+ * every field rather than the one that changed. `merge: true` protects
+ * nothing there — the untouched fields are all present in the payload — so
+ * saving one edit rewrites the rest to whatever the seed held. If the seed
+ * came from IndexedDB during a stale session, "whatever the seed held" can
+ * be arbitrarily old, and the user's real values are destroyed by a save
+ * they asked for and had every reason to expect to be safe.
+ *
+ * ## Why it WRAPS the write instead of preceding it
+ *
+ * The guards this replaces sat in front of their writes as early returns,
+ * which is a shape you can have and still write — add a branch, reorder a
+ * line, and the guard is decoration. Here the write is only reachable
+ * THROUGH the verdict, so a call site cannot keep the guard and lose the
+ * protection. It also makes the refusal testable as a refusal: assert the
+ * inner function never ran.
+ *
+ * ## The three signals, in the order they are worth trusting
+ *
+ * 1. `fromCache` — the server never confirmed what is on screen (AGL-1066).
+ *    This is the one that catches the dangerous case, because a cache-served
+ *    read looks completely healthy: populated form, plausible values. It is
+ *    per-listener ground truth from the SDK, so it needs no threshold and no
+ *    window, and it clears itself the instant a server snapshot lands. It
+ *    leads because it is also the more ACCURATE explanation whenever it is
+ *    true — see the ordering note on `checkSeedFreshness`.
+ * 2. `unreadable` — the read FAILED and there is nothing cached behind it
+ *    (AGL-1143). Saving would write blanks over a populated document.
+ * 3. `staleSession` — the console's own heuristic. Kept because it means
+ *    something the other two do not (the SESSION is dead, not merely
+ *    unconfirmed), but it must never be the ONLY guard: it needs two
+ *    distinct labelled collections denied inside 60s, which is unreachable
+ *    on a listener-only page. That was exactly how AGL-1356 stayed open.
+ *
+ * ## Why this lives in the library rather than the console (AGL-1358)
+ *
+ * Most of the ~forty sites wearing this shape are plugin cards in
+ * `libs/plugins/**`, which cannot import from `apps/console`. The guard
+ * itself is pure, and `fromCache` — the signal that actually fires —
+ * originates here, on the listener hooks. What it cannot own is
+ * `session-health`, which is console state.
+ *
+ * So the third signal is INJECTED, through the same seam
+ * `firestore-denial-reporter` already uses for the reverse direction: the
+ * console registers a check at startup and the guard pulls it. That keeps a
+ * single guard for every call site with no new dependency edge and nothing
+ * inverted — the library still knows nothing about the app. An unregistered
+ * check simply reports "not stale", which is what the tenant runtime and the
+ * unit tests want; the other two signals are unaffected, and they are the
+ * ones the doc above says must carry the guard anyway.
+ */ /**
+ * The console's `session-health` verdict, injected because it is app state.
+ * Null until the app registers one — see {@link setStaleSessionCheck}.
+ */ let staleSessionCheck = null;
+/**
+ * Register the app's stale-session verdict. Called once, by the app that owns
+ * `session-health`. Pass `null` to unregister (tests).
+ *
+ * Registered at module scope alongside `setFirestoreSessionReporters` rather
+ * than in an effect, for the same reason: a save can be clicked before any
+ * effect has run, and a guard that consults a check which does not exist yet
+ * silently loses its third signal.
+ */ export function setStaleSessionCheck(check) {
+    staleSessionCheck = check;
+}
+/** The registered verdict, or `false` when nothing is registered. */ function isSessionStale() {
+    return staleSessionCheck ? staleSessionCheck() : false;
+}
+/**
+ * Why we refused, in words that say what to DO about it.
+ *
+ * ## The subject is INTERPOLATED, so nothing here may agree with it (AGL-1446)
+ *
+ * Call sites pass "profile", "SEO settings", "theme overrides", "categories".
+ * The copy used to read "Your SEO settings **has** not been confirmed", "so
+ * **it** cannot be saved", "so **this** SEO settings may be out of date" —
+ * fine for the singular subjects it was written against and wrong for half the
+ * ~126 call sites. Every sentence below is number-neutral instead, and
+ * `guarded-seed-write.spec.ts` pins all three verbatim against a plural
+ * subject so it stays that way.
+ *
+ * ## Why `unconfirmed` names a SECOND remedy (AGL-1446)
+ *
+ * "Reload" was the only instruction, and it is the one that fails in the case
+ * where an author is most stuck. A long-lived console tab can go permanently
+ * cache-only: no Firestore `Listen` channel is ever established, every
+ * listener is served from IndexedDB, `fromCache` never clears, and this guard
+ * correctly refuses every save — forever. Observed on 2026-08-12 (AGL-1066):
+ * refused three times ACROSS A FULL RELOAD with the session entirely healthy
+ * (`securetoken` 200, `runAggregationQuery` 200). A brand-new tab fixed it on
+ * the first try.
+ *
+ * ## Why this is copy rather than a branch
+ *
+ * Three different states reach this message with byte-identical evidence:
+ *
+ * 1. the server has not confirmed the read YET (reload, or just wait);
+ * 2. the client is OFFLINE (reconnect — the case `persistentLocalCache` was
+ *    added for in the first place);
+ * 3. the tab is permanently cache-only (only a new tab helps).
+ *
+ * In all three, `fromCache` is true, `unreadable` is false, and
+ * `session-health` reports nothing: a listen that is never issued and a listen
+ * that has not been answered yet both produce no error callback, so no
+ * `permission-denied` is ever counted and `staleSession` cannot fire. The one
+ * signal that separates (3) from (1) — whether {@link
+ * reportFirestoreServerRead} has EVER fired in this tab — is dispatched
+ * straight into `session-health.reportSuccessfulRead`, which returns early
+ * when there is no denial evidence and retains nothing; `getSessionHealth()`
+ * exposes only the denial verdict. So the bit is produced and discarded, and
+ * latching it would still not be enough: a freshly-opened tab and an offline
+ * tab have not had a listen answered either, so a detector would need a time
+ * threshold AND an online check (which lives in the app, behind another seam)
+ * before it could say "stuck" without mislabelling both. That is a new tuned
+ * heuristic in the path of every save, to choose between two remedies that
+ * cost the reader one sentence to be told both of.
+ *
+ * So the message names all three: connection, reload, and the new tab — with
+ * the reason the new tab is not just "reload harder", because an instruction
+ * that reads as a superstition is one people skip.
+ */ function refusalMessage(subject, reason) {
+    switch(reason){
+        case 'unreadable':
+            return `Your ${subject} could not be loaded, so there is nothing safe to ` + 'save — saving now would overwrite the stored copy with blanks. ' + 'Reload and try again.';
+        case 'unconfirmed':
+            return `We could not confirm your ${subject} with the server, so what is ` + 'on screen may be out of date — saving now could overwrite newer ' + 'values. Check your connection and reload; if it is refused again, ' + 'open this page in a new browser tab — reloading cannot restore a ' + 'connection this tab never opened.';
+        case 'stale-session':
+            return `Your session went stale, so your ${subject} may be out of date — ` + 'saving now could overwrite newer values. Sign in again and reload.';
+    }
+}
+/** The verdict on its own, for a caller that needs it before the click. */ export function checkSeedFreshness(options) {
+    const { subject, unreadable, fromCache, checkSession = true } = options;
+    /**
+   * `fromCache` OUTRANKS `unreadable` (AGL-1066).
+   *
+   * It did not, and the ordering was harmless only while a refused listen
+   * could never reach `status: 'error'`. Now that it can, the common case is
+   * BOTH flags true at once — the cache is serving the document and the
+   * server has stopped answering for it — and taking `unreadable` there
+   * tells the user their settings "could not be loaded" and that saving
+   * "would overwrite it with blanks", while a populated, plausible form sits
+   * in front of them. The refusal is right; that explanation is not, and a
+   * refusal whose reason is visibly false is one the user works around.
+   *
+   * What is left to `unreadable` is the read that failed with nothing to
+   * show for it, which is the AGL-1143 case it was written for and where the
+   * blanks are real. The heuristic still comes last.
+   */ const reason = fromCache ? 'unconfirmed' : unreadable ? 'unreadable' : checkSession && isSessionStale() ? 'stale-session' : undefined;
+    if (!reason) return {
+        ok: true
+    };
+    return {
+        ok: false,
+        reason,
+        message: refusalMessage(subject, reason)
+    };
+}
+/**
+ * Run `write` only if the seed can be trusted.
+ *
+ * Never throws on refusal — the caller reports `message` and leaves the
+ * user's typed values on screen, because the whole point is that we are not
+ * confident enough to touch the stored document, not that the input was bad.
+ */ export async function writeGuardedBySeed(options, write) {
+    const verdict = checkSeedFreshness(options);
+    if (!verdict.ok) return verdict;
+    await write();
+    return verdict;
+}
+export default writeGuardedBySeed;
+
+//# sourceMappingURL=guarded-seed-write.js.map

package/src/lib/hooks/helpers/guarded-seed-write.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/guarded-seed-write.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 * Refuse a whole-object write whose form was seeded from a read we cannot\n * trust (AGL-1356, AGL-1358, AGL-1066).\n *\n * ## The shape this exists for\n *\n * A form seeded from a Firestore LISTENER, saved with a payload that carries\n * every field rather than the one that changed. `merge: true` protects\n * nothing there — the untouched fields are all present in the payload — so\n * saving one edit rewrites the rest to whatever the seed held. If the seed\n * came from IndexedDB during a stale session, \"whatever the seed held\" can\n * be arbitrarily old, and the user's real values are destroyed by a save\n * they asked for and had every reason to expect to be safe.\n *\n * ## Why it WRAPS the write instead of preceding it\n *\n * The guards this replaces sat in front of their writes as early returns,\n * which is a shape you can have and still write — add a branch, reorder a\n * line, and the guard is decoration. Here the write is only reachable\n * THROUGH the verdict, so a call site cannot keep the guard and lose the\n * protection. It also makes the refusal testable as a refusal: assert the\n * inner function never ran.\n *\n * ## The three signals, in the order they are worth trusting\n *\n * 1. `fromCache` — the server never confirmed what is on screen (AGL-1066).\n *    This is the one that catches the dangerous case, because a cache-served\n *    read looks completely healthy: populated form, plausible values. It is\n *    per-listener ground truth from the SDK, so it needs no threshold and no\n *    window, and it clears itself the instant a server snapshot lands. It\n *    leads because it is also the more ACCURATE explanation whenever it is\n *    true — see the ordering note on `checkSeedFreshness`.\n * 2. `unreadable` — the read FAILED and there is nothing cached behind it\n *    (AGL-1143). Saving would write blanks over a populated document.\n * 3. `staleSession` — the console's own heuristic. Kept because it means\n *    something the other two do not (the SESSION is dead, not merely\n *    unconfirmed), but it must never be the ONLY guard: it needs two\n *    distinct labelled collections denied inside 60s, which is unreachable\n *    on a listener-only page. That was exactly how AGL-1356 stayed open.\n *\n * ## Why this lives in the library rather than the console (AGL-1358)\n *\n * Most of the ~forty sites wearing this shape are plugin cards in\n * `libs/plugins/**`, which cannot import from `apps/console`. The guard\n * itself is pure, and `fromCache` — the signal that actually fires —\n * originates here, on the listener hooks. What it cannot own is\n * `session-health`, which is console state.\n *\n * So the third signal is INJECTED, through the same seam\n * `firestore-denial-reporter` already uses for the reverse direction: the\n * console registers a check at startup and the guard pulls it. That keeps a\n * single guard for every call site with no new dependency edge and nothing\n * inverted — the library still knows nothing about the app. An unregistered\n * check simply reports \"not stale\", which is what the tenant runtime and the\n * unit tests want; the other two signals are unaffected, and they are the\n * ones the doc above says must carry the guard anyway.\n */\n\nexport type StaleSeedReason = 'unreadable' | 'unconfirmed' | 'stale-session'\n\n/**\n * The console's `session-health` verdict, injected because it is app state.\n * Null until the app registers one — see {@link setStaleSessionCheck}.\n */\nlet staleSessionCheck: (() => boolean) | null = null\n\n/**\n * Register the app's stale-session verdict. Called once, by the app that owns\n * `session-health`. Pass `null` to unregister (tests).\n *\n * Registered at module scope alongside `setFirestoreSessionReporters` rather\n * than in an effect, for the same reason: a save can be clicked before any\n * effect has run, and a guard that consults a check which does not exist yet\n * silently loses its third signal.\n */\nexport function setStaleSessionCheck(check: (() => boolean) | null): void {\n  staleSessionCheck = check\n}\n\n/** The registered verdict, or `false` when nothing is registered. */\nfunction isSessionStale(): boolean {\n  return staleSessionCheck ? staleSessionCheck() : false\n}\n\nexport interface GuardedSeedWriteOptions {\n  /**\n   * What is being saved, in the user's words — \"profile\", \"settings\".\n   * Used to build the refusal message, so it reads naturally in a sentence\n   * like \"Your profile could not be loaded\".\n   */\n  subject: string\n  /** The seeding read FAILED (`status === 'error'`). */\n  unreadable?: boolean\n  /** The seeding snapshot came from cache (`metadata.fromCache`). */\n  fromCache?: boolean\n  /**\n   * Also consult `session-health`. On by default; the only reason to turn it\n   * off is a surface that deliberately writes during a known-degraded\n   * session.\n   */\n  checkSession?: boolean\n}\n\nexport interface GuardedSeedWriteResult {\n  /** True when the write RAN. */\n  ok: boolean\n  /** Why it did not run. */\n  reason?: StaleSeedReason\n  /**\n   * What to tell the user. Always populated when `ok` is false — a refused\n   * save that says nothing is its own bug: the user retypes the form and\n   * tries again, and the second attempt is refused just as silently.\n   */\n  message?: string\n}\n\n/**\n * Why we refused, in words that say what to DO about it.\n *\n * ## The subject is INTERPOLATED, so nothing here may agree with it (AGL-1446)\n *\n * Call sites pass \"profile\", \"SEO settings\", \"theme overrides\", \"categories\".\n * The copy used to read \"Your SEO settings **has** not been confirmed\", \"so\n * **it** cannot be saved\", \"so **this** SEO settings may be out of date\" —\n * fine for the singular subjects it was written against and wrong for half the\n * ~126 call sites. Every sentence below is number-neutral instead, and\n * `guarded-seed-write.spec.ts` pins all three verbatim against a plural\n * subject so it stays that way.\n *\n * ## Why `unconfirmed` names a SECOND remedy (AGL-1446)\n *\n * \"Reload\" was the only instruction, and it is the one that fails in the case\n * where an author is most stuck. A long-lived console tab can go permanently\n * cache-only: no Firestore `Listen` channel is ever established, every\n * listener is served from IndexedDB, `fromCache` never clears, and this guard\n * correctly refuses every save — forever. Observed on 2026-08-12 (AGL-1066):\n * refused three times ACROSS A FULL RELOAD with the session entirely healthy\n * (`securetoken` 200, `runAggregationQuery` 200). A brand-new tab fixed it on\n * the first try.\n *\n * ## Why this is copy rather than a branch\n *\n * Three different states reach this message with byte-identical evidence:\n *\n * 1. the server has not confirmed the read YET (reload, or just wait);\n * 2. the client is OFFLINE (reconnect — the case `persistentLocalCache` was\n *    added for in the first place);\n * 3. the tab is permanently cache-only (only a new tab helps).\n *\n * In all three, `fromCache` is true, `unreadable` is false, and\n * `session-health` reports nothing: a listen that is never issued and a listen\n * that has not been answered yet both produce no error callback, so no\n * `permission-denied` is ever counted and `staleSession` cannot fire. The one\n * signal that separates (3) from (1) — whether {@link\n * reportFirestoreServerRead} has EVER fired in this tab — is dispatched\n * straight into `session-health.reportSuccessfulRead`, which returns early\n * when there is no denial evidence and retains nothing; `getSessionHealth()`\n * exposes only the denial verdict. So the bit is produced and discarded, and\n * latching it would still not be enough: a freshly-opened tab and an offline\n * tab have not had a listen answered either, so a detector would need a time\n * threshold AND an online check (which lives in the app, behind another seam)\n * before it could say \"stuck\" without mislabelling both. That is a new tuned\n * heuristic in the path of every save, to choose between two remedies that\n * cost the reader one sentence to be told both of.\n *\n * So the message names all three: connection, reload, and the new tab — with\n * the reason the new tab is not just \"reload harder\", because an instruction\n * that reads as a superstition is one people skip.\n */\nfunction refusalMessage(subject: string, reason: StaleSeedReason): string {\n  switch (reason) {\n    case 'unreadable':\n      return (\n        `Your ${subject} could not be loaded, so there is nothing safe to ` +\n        'save — saving now would overwrite the stored copy with blanks. ' +\n        'Reload and try again.'\n      )\n    case 'unconfirmed':\n      return (\n        `We could not confirm your ${subject} with the server, so what is ` +\n        'on screen may be out of date — saving now could overwrite newer ' +\n        'values. Check your connection and reload; if it is refused again, ' +\n        'open this page in a new browser tab — reloading cannot restore a ' +\n        'connection this tab never opened.'\n      )\n    case 'stale-session':\n      return (\n        `Your session went stale, so your ${subject} may be out of date — ` +\n        'saving now could overwrite newer values. Sign in again and reload.'\n      )\n  }\n}\n\n/** The verdict on its own, for a caller that needs it before the click. */\nexport function checkSeedFreshness(\n  options: GuardedSeedWriteOptions,\n): GuardedSeedWriteResult {\n  const { subject, unreadable, fromCache, checkSession = true } = options\n  /**\n   * `fromCache` OUTRANKS `unreadable` (AGL-1066).\n   *\n   * It did not, and the ordering was harmless only while a refused listen\n   * could never reach `status: 'error'`. Now that it can, the common case is\n   * BOTH flags true at once — the cache is serving the document and the\n   * server has stopped answering for it — and taking `unreadable` there\n   * tells the user their settings \"could not be loaded\" and that saving\n   * \"would overwrite it with blanks\", while a populated, plausible form sits\n   * in front of them. The refusal is right; that explanation is not, and a\n   * refusal whose reason is visibly false is one the user works around.\n   *\n   * What is left to `unreadable` is the read that failed with nothing to\n   * show for it, which is the AGL-1143 case it was written for and where the\n   * blanks are real. The heuristic still comes last.\n   */\n  const reason: StaleSeedReason | undefined = fromCache\n    ? 'unconfirmed'\n    : unreadable\n      ? 'unreadable'\n      : checkSession && isSessionStale()\n        ? 'stale-session'\n        : undefined\n  if (!reason) return { ok: true }\n  return { ok: false, reason, message: refusalMessage(subject, reason) }\n}\n\n/**\n * Run `write` only if the seed can be trusted.\n *\n * Never throws on refusal — the caller reports `message` and leaves the\n * user's typed values on screen, because the whole point is that we are not\n * confident enough to touch the stored document, not that the input was bad.\n */\nexport async function writeGuardedBySeed(\n  options: GuardedSeedWriteOptions,\n  write: () => Promise<void>,\n): Promise<GuardedSeedWriteResult> {\n  const verdict = checkSeedFreshness(options)\n  if (!verdict.ok) return verdict\n  await write()\n  return verdict\n}\n\nexport default writeGuardedBySeed\n"],"names":["staleSessionCheck","setStaleSessionCheck","check","isSessionStale","refusalMessage","subject","reason","checkSeedFreshness","options","unreadable","fromCache","checkSession","undefined","ok","message","writeGuardedBySeed","write","verdict"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDC,GAID;;;CAGC,GACD,IAAIA,oBAA4C;AAEhD;;;;;;;;CAQC,GACD,OAAO,SAASC,qBAAqBC,KAA6B;IAChEF,oBAAoBE;AACtB;AAEA,mEAAmE,GACnE,SAASC;IACP,OAAOH,oBAAoBA,sBAAsB;AACnD;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDC,GACD,SAASI,eAAeC,OAAe,EAAEC,MAAuB;IAC9D,OAAQA;QACN,KAAK;YACH,OACE,CAAC,KAAK,EAAED,QAAQ,kDAAkD,CAAC,GACnE,oEACA;QAEJ,KAAK;YACH,OACE,CAAC,0BAA0B,EAAEA,QAAQ,6BAA6B,CAAC,GACnE,qEACA,uEACA,sEACA;QAEJ,KAAK;YACH,OACE,CAAC,iCAAiC,EAAEA,QAAQ,sBAAsB,CAAC,GACnE;IAEN;AACF;AAEA,yEAAyE,GACzE,OAAO,SAASE,mBACdC,OAAgC;IAEhC,MAAM,EAAEH,OAAO,EAAEI,UAAU,EAAEC,SAAS,EAAEC,eAAe,IAAI,EAAE,GAAGH;IAChE;;;;;;;;;;;;;;;GAeC,GACD,MAAMF,SAAsCI,YACxC,gBACAD,aACE,eACAE,gBAAgBR,mBACd,kBACAS;IACR,IAAI,CAACN,QAAQ,OAAO;QAAEO,IAAI;IAAK;IAC/B,OAAO;QAAEA,IAAI;QAAOP;QAAQQ,SAASV,eAAeC,SAASC;IAAQ;AACvE;AAEA;;;;;;CAMC,GACD,OAAO,eAAeS,mBACpBP,OAAgC,EAChCQ,KAA0B;IAE1B,MAAMC,UAAUV,mBAAmBC;IACnC,IAAI,CAACS,QAAQJ,EAAE,EAAE,OAAOI;IACxB,MAAMD;IACN,OAAOC;AACT;AAEA,eAAeF,mBAAkB"}

package/src/lib/hooks/helpers/listen-options.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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 SnapshotListenOptions } from 'firebase/firestore';
+/**
+ * The listen options every hook that reports `fromCache` MUST pass (AGL-2486).
+ *
+ * ## What breaks without it
+ *
+ * `fromCache` is the signal `writeGuardedBySeed` refuses on, and without this
+ * option it can LATCH TRUE FOR THE LIFE OF THE LISTENER — so every guarded
+ * save on the page is refused forever, across reloads, while the connection is
+ * perfectly healthy. That is the "We could not confirm your SEO settings with
+ * the server" banner in AGL-2486, and it is not a connection fault at all.
+ *
+ * The cause is in the SDK's own event-raising rule
+ * (`@firebase/firestore` 4.17.0, `QueryListener.shouldRaiseEvent`):
+ *
+ * ```js
+ * if (snap.docChanges.length > 0) return true;
+ * const pendingChanged = this.snap && this.snap.hasPendingWrites !== snap.hasPendingWrites;
+ * return !(!snap.syncStateChanged && !pendingChanged)
+ *   && true === this.options.includeMetadataChanges;
+ * ```
+ *
+ * The cache→server confirmation is a `syncStateChanged` tick and nothing else:
+ * when the server confirms a document the cache already held, the data is
+ * IDENTICAL, so `docChanges` is empty. The rule above then raises the event
+ * **only if `includeMetadataChanges === true`**. At the default of `false` the
+ * confirmation is silently dropped, `setFromCache(false)` never runs, and the
+ * hook keeps reporting the value it was initialised with — `true`.
+ *
+ * So the bug fires precisely when the local cache is WARM and AGREES with the
+ * server, which under `persistentLocalCache` is the ordinary state of any
+ * console page the author has opened before. It clears only by luck: if the
+ * server's copy happens to differ, `docChanges` is non-empty and the event is
+ * raised. That is why this survived — it is intermittent by data, not by
+ * network.
+ *
+ * ## Measured, not argued (2026-08-24)
+ *
+ * A real browser, the real SDK, `persistentLocalCache`, one document seeded so
+ * cache and server agree, reloading between runs:
+ *
+ * - default options → 1 event, `fromCache: true`, never clears (6s), and
+ *   IDENTICAL on reload — while `…/Firestore/Listen/channel` returned 200.
+ * - `{ includeMetadataChanges: true }` → 2 events; the second at 121ms with
+ *   `fromCache: false` and the same data. Latch cleared.
+ *
+ * Note the first bullet: the Listen channel is OPEN and ANSWERING. The old
+ * theory that the refusal means "a tab that never opened a listener" is wrong,
+ * and so is the "only a fresh tab fixes it" folklore — a fresh tab only helps
+ * when it happens to read a document the cache does not already agree with.
+ *
+ * ## Why this is the fix and not a workaround
+ *
+ * It does not weaken the gate: `fromCache` still comes from the SDK, still
+ * starts `true`, and still refuses while the server has genuinely not
+ * confirmed. It restores the SDK event the guard was always written to
+ * consume. Defaulting the flag to `false`, or adding a "save anyway" escape,
+ * would trade the banner for the silent whole-object overwrite the guard
+ * exists to prevent.
+ *
+ * ## Cost
+ *
+ * One extra callback per listener when the server confirms (measured at ~100ms
+ * after subscribe, i.e. at page load, long before a user has typed), plus the
+ * pending-write acknowledgement tick — which was ALSO being suppressed, so
+ * `hasPendingWrites` was equally unreliable before this. Consumers must
+ * therefore tolerate a snapshot whose data is unchanged; none may treat a new
+ * emission as "the document changed".
+ *
+ * `useOrgScope` has passed this since AGL-886 for the same reason, and
+ * `useConfirmedDoc` pays for a whole extra `getDocFromServer` to work around
+ * not passing it.
+ */
+export declare const CONFIRMABLE_LISTEN_OPTIONS: SnapshotListenOptions;
+export default CONFIRMABLE_LISTEN_OPTIONS;

package/src/lib/hooks/helpers/listen-options.js

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The listen options every hook that reports `fromCache` MUST pass (AGL-2486).
+ *
+ * ## What breaks without it
+ *
+ * `fromCache` is the signal `writeGuardedBySeed` refuses on, and without this
+ * option it can LATCH TRUE FOR THE LIFE OF THE LISTENER — so every guarded
+ * save on the page is refused forever, across reloads, while the connection is
+ * perfectly healthy. That is the "We could not confirm your SEO settings with
+ * the server" banner in AGL-2486, and it is not a connection fault at all.
+ *
+ * The cause is in the SDK's own event-raising rule
+ * (`@firebase/firestore` 4.17.0, `QueryListener.shouldRaiseEvent`):
+ *
+ * ```js
+ * if (snap.docChanges.length > 0) return true;
+ * const pendingChanged = this.snap && this.snap.hasPendingWrites !== snap.hasPendingWrites;
+ * return !(!snap.syncStateChanged && !pendingChanged)
+ *   && true === this.options.includeMetadataChanges;
+ * ```
+ *
+ * The cache→server confirmation is a `syncStateChanged` tick and nothing else:
+ * when the server confirms a document the cache already held, the data is
+ * IDENTICAL, so `docChanges` is empty. The rule above then raises the event
+ * **only if `includeMetadataChanges === true`**. At the default of `false` the
+ * confirmation is silently dropped, `setFromCache(false)` never runs, and the
+ * hook keeps reporting the value it was initialised with — `true`.
+ *
+ * So the bug fires precisely when the local cache is WARM and AGREES with the
+ * server, which under `persistentLocalCache` is the ordinary state of any
+ * console page the author has opened before. It clears only by luck: if the
+ * server's copy happens to differ, `docChanges` is non-empty and the event is
+ * raised. That is why this survived — it is intermittent by data, not by
+ * network.
+ *
+ * ## Measured, not argued (2026-08-24)
+ *
+ * A real browser, the real SDK, `persistentLocalCache`, one document seeded so
+ * cache and server agree, reloading between runs:
+ *
+ * - default options → 1 event, `fromCache: true`, never clears (6s), and
+ *   IDENTICAL on reload — while `…/Firestore/Listen/channel` returned 200.
+ * - `{ includeMetadataChanges: true }` → 2 events; the second at 121ms with
+ *   `fromCache: false` and the same data. Latch cleared.
+ *
+ * Note the first bullet: the Listen channel is OPEN and ANSWERING. The old
+ * theory that the refusal means "a tab that never opened a listener" is wrong,
+ * and so is the "only a fresh tab fixes it" folklore — a fresh tab only helps
+ * when it happens to read a document the cache does not already agree with.
+ *
+ * ## Why this is the fix and not a workaround
+ *
+ * It does not weaken the gate: `fromCache` still comes from the SDK, still
+ * starts `true`, and still refuses while the server has genuinely not
+ * confirmed. It restores the SDK event the guard was always written to
+ * consume. Defaulting the flag to `false`, or adding a "save anyway" escape,
+ * would trade the banner for the silent whole-object overwrite the guard
+ * exists to prevent.
+ *
+ * ## Cost
+ *
+ * One extra callback per listener when the server confirms (measured at ~100ms
+ * after subscribe, i.e. at page load, long before a user has typed), plus the
+ * pending-write acknowledgement tick — which was ALSO being suppressed, so
+ * `hasPendingWrites` was equally unreliable before this. Consumers must
+ * therefore tolerate a snapshot whose data is unchanged; none may treat a new
+ * emission as "the document changed".
+ *
+ * `useOrgScope` has passed this since AGL-886 for the same reason, and
+ * `useConfirmedDoc` pays for a whole extra `getDocFromServer` to work around
+ * not passing it.
+ */ export const CONFIRMABLE_LISTEN_OPTIONS = {
+    includeMetadataChanges: true
+};
+export default CONFIRMABLE_LISTEN_OPTIONS;
+
+//# sourceMappingURL=listen-options.js.map

package/src/lib/hooks/helpers/listen-options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/listen-options.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 SnapshotListenOptions } from 'firebase/firestore'\n\n/**\n * The listen options every hook that reports `fromCache` MUST pass (AGL-2486).\n *\n * ## What breaks without it\n *\n * `fromCache` is the signal `writeGuardedBySeed` refuses on, and without this\n * option it can LATCH TRUE FOR THE LIFE OF THE LISTENER — so every guarded\n * save on the page is refused forever, across reloads, while the connection is\n * perfectly healthy. That is the \"We could not confirm your SEO settings with\n * the server\" banner in AGL-2486, and it is not a connection fault at all.\n *\n * The cause is in the SDK's own event-raising rule\n * (`@firebase/firestore` 4.17.0, `QueryListener.shouldRaiseEvent`):\n *\n * ```js\n * if (snap.docChanges.length > 0) return true;\n * const pendingChanged = this.snap && this.snap.hasPendingWrites !== snap.hasPendingWrites;\n * return !(!snap.syncStateChanged && !pendingChanged)\n *   && true === this.options.includeMetadataChanges;\n * ```\n *\n * The cache→server confirmation is a `syncStateChanged` tick and nothing else:\n * when the server confirms a document the cache already held, the data is\n * IDENTICAL, so `docChanges` is empty. The rule above then raises the event\n * **only if `includeMetadataChanges === true`**. At the default of `false` the\n * confirmation is silently dropped, `setFromCache(false)` never runs, and the\n * hook keeps reporting the value it was initialised with — `true`.\n *\n * So the bug fires precisely when the local cache is WARM and AGREES with the\n * server, which under `persistentLocalCache` is the ordinary state of any\n * console page the author has opened before. It clears only by luck: if the\n * server's copy happens to differ, `docChanges` is non-empty and the event is\n * raised. That is why this survived — it is intermittent by data, not by\n * network.\n *\n * ## Measured, not argued (2026-08-24)\n *\n * A real browser, the real SDK, `persistentLocalCache`, one document seeded so\n * cache and server agree, reloading between runs:\n *\n * - default options → 1 event, `fromCache: true`, never clears (6s), and\n *   IDENTICAL on reload — while `…/Firestore/Listen/channel` returned 200.\n * - `{ includeMetadataChanges: true }` → 2 events; the second at 121ms with\n *   `fromCache: false` and the same data. Latch cleared.\n *\n * Note the first bullet: the Listen channel is OPEN and ANSWERING. The old\n * theory that the refusal means \"a tab that never opened a listener\" is wrong,\n * and so is the \"only a fresh tab fixes it\" folklore — a fresh tab only helps\n * when it happens to read a document the cache does not already agree with.\n *\n * ## Why this is the fix and not a workaround\n *\n * It does not weaken the gate: `fromCache` still comes from the SDK, still\n * starts `true`, and still refuses while the server has genuinely not\n * confirmed. It restores the SDK event the guard was always written to\n * consume. Defaulting the flag to `false`, or adding a \"save anyway\" escape,\n * would trade the banner for the silent whole-object overwrite the guard\n * exists to prevent.\n *\n * ## Cost\n *\n * One extra callback per listener when the server confirms (measured at ~100ms\n * after subscribe, i.e. at page load, long before a user has typed), plus the\n * pending-write acknowledgement tick — which was ALSO being suppressed, so\n * `hasPendingWrites` was equally unreliable before this. Consumers must\n * therefore tolerate a snapshot whose data is unchanged; none may treat a new\n * emission as \"the document changed\".\n *\n * `useOrgScope` has passed this since AGL-886 for the same reason, and\n * `useConfirmedDoc` pays for a whole extra `getDocFromServer` to work around\n * not passing it.\n */\nexport const CONFIRMABLE_LISTEN_OPTIONS: SnapshotListenOptions = {\n  includeMetadataChanges: true,\n}\n\nexport default CONFIRMABLE_LISTEN_OPTIONS\n"],"names":["CONFIRMABLE_LISTEN_OPTIONS","includeMetadataChanges"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuEC,GACD,OAAO,MAAMA,6BAAoD;IAC/DC,wBAAwB;AAC1B,EAAC;AAED,eAAeD,2BAA0B"}