@aglyn/tenant-feature-instance 1.0.0-beta.209 → 1.0.0-beta.212

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/tenant-feature-instance",
-  "version": "1.0.0-beta.209",
+  "version": "1.0.0-beta.212",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,12 +25,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.209",
-    "@aglyn/shared-data-enums": "1.0.0-beta.209",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.209",
-    "@aglyn/shared-util-email": "1.0.0-beta.209",
-    "@aglyn/shared-util-http": "1.0.0-beta.209",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.209",
+    "@aglyn/aglyn": "1.0.0-beta.212",
+    "@aglyn/shared-data-enums": "1.0.0-beta.212",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.212",
+    "@aglyn/shared-util-email": "1.0.0-beta.212",
+    "@aglyn/shared-util-http": "1.0.0-beta.212",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.212",
     "@swc/helpers": "0.5.23",
     "lodash-es": "^4.18.1"
   },

package/src/lib/hooks/helpers/site-wide-change.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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, type Firestore, type WriteBatch } from 'firebase/firestore';
+/**
+ * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES
+ * (AGL-3386).
+ *
+ * A site's settings, and the plugin data its pages render — the theme, the
+ * announcement bar, a product, a site variable — are client Firestore writes
+ * with no publish step. The live site is ISR-cached for an hour, so each of
+ * those writes has to tell the tenant to drop the site's cached pages, or the
+ * change waits out the hour while the console says it is saved.
+ *
+ * Telling it from the tab is the fast path, and a tab is not durable: close
+ * it, sleep the laptop or lose the network between the write and the fetch,
+ * and the write has landed while the drop has landed nowhere. So the drop is
+ * also WRITTEN DOWN, as a publish outbox entry in the same batch as the
+ * write — either both land or neither does — and the console's scheduled
+ * drain fires any entry the tab did not get to release. This is the same
+ * mechanism a screen publish uses (AGL-2575); the entry carries
+ * `entireHost: true`, because a site-wide setting has no address of its own.
+ *
+ * Shared here rather than kept in the console because plugins write these
+ * documents too, and a plugin cannot import the console.
+ */
+/**
+ * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same
+ * collection, and `host-document-writes-sweep.spec.ts` holds the two names
+ * and the entry's keys to the console's constants and to the rule.
+ */
+export declare const SITE_WIDE_OUTBOX_COLLECTION = "publishOutbox";
+/**
+ * What a site-wide entry names. The rule insists every entry names at least
+ * one address; the drain reads `entireHost` and drops every routed page of
+ * the site instead, which is what a site-wide change needs.
+ */
+export declare const SITE_WIDE_OUTBOX_PATHS: readonly string[];
+/**
+ * What an entry can be staged into: a batch, or a transaction — anything
+ * whose `set` lands in the same commit as the write beside it.
+ */
+export interface SiteWideEntryWriter {
+    set(ref: DocumentReference, data: Record<string, unknown>): unknown;
+}
+/** Stages one site-wide outbox entry into the caller's batch. */
+export declare function stageSiteWideOutboxEntry(batch: SiteWideEntryWriter, firestore: Firestore, hostId: string): DocumentReference;
+/** Adds a site-wide outbox entry to a batch that is about to commit. */
+export type StageSiteWideEntry = (batch: SiteWideEntryWriter, firestore: Firestore) => void;
+/**
+ * Commits a write with its site-wide outbox entry beside it, and answers the
+ * entry — or `null` when the write had to land without one.
+ *
+ * `commit` performs the write. It is handed the stager on the first attempt
+ * and must put the entry in the SAME batch as the write; it is called again
+ * without one if that batch is refused.
+ *
+ * The retry is what keeps the entry from ever costing a save. The entry is
+ * the durable copy of a cache drop, and the write is the user's work: a rule
+ * that refuses the entry — the window between a code release and the rules
+ * deploy that admits it, or a role the outbox rule does not cover — must
+ * leave the save exactly as it was without it, with the tab's own drop still
+ * behind it. A write the rules refuse on its own merits is refused again,
+ * and that second refusal is the one the caller sees.
+ */
+export declare function commitWithSiteWideEntry(hostId: string, commit: (stage: StageSiteWideEntry | undefined) => Promise<void>): Promise<DocumentReference | null>;
+/**
+ * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from
+ * the console route and nothing else. Any other answer leaves it for the
+ * drain, because the entry is the only record that the site may still be
+ * stale; the cost of keeping one needlessly is a duplicate drop, which is a
+ * no-op.
+ */
+export declare function releaseSiteWideOutboxEntry(entry: DocumentReference | null, reason: string | null | undefined): Promise<void>;
+/**
+ * Asks the console to drop every cached page of the site, and answers its
+ * reason — `'ok'` only when the drop landed.
+ *
+ * The plugin-side door to the console's own `/api/screens/revalidate`, which
+ * a plugin cannot import. Never throws: a cache hint that fails must not make
+ * a successful save look failed, and the outbox entry and the hour-long
+ * window are both underneath it.
+ */
+export declare function announceSiteWideChange(options: {
+    /** The signed-in user; its ID token authenticates the console route. */
+    user: {
+        getIdToken?: () => Promise<string>;
+    } | null | undefined;
+    hostId: string;
+}): Promise<string | null>;
+/**
+ * After the write has landed: ask for the drop, and release the entry when it
+ * lands. Fire and forget — it never rejects.
+ */
+export declare function settleSiteWideChange(options: {
+    user: {
+        getIdToken?: () => Promise<string>;
+    } | null | undefined;
+    hostId: string;
+    entry: DocumentReference | null;
+}): void;
+/**
+ * THE ONE CALL A PLUGIN'S CONSOLE CARD MAKES TO SAVE SOMETHING A PUBLISHED
+ * PAGE RENDERS.
+ *
+ * `write` stages the card's writes into the batch it is handed —
+ * `batch.update(ref, …)`, `batch.set(ref, …, { merge: true })`,
+ * `batch.delete(ref)` — and the batch commits with the site-wide outbox entry
+ * beside them. Resolves when the write has landed, rejects exactly when it
+ * did not; the drop runs behind it and never rejects.
+ */
+export declare function writeSiteWideChange(options: {
+    firestore: Firestore;
+    user: {
+        getIdToken?: () => Promise<string>;
+    } | null | undefined;
+    hostId: string;
+    write: (batch: WriteBatch) => void;
+}): Promise<void>;

package/src/lib/hooks/helpers/site-wide-change.js

@@ -0,0 +1,174 @@
+/**
+ * @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 { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
+import { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+import { deleteDoc, doc, serverTimestamp, writeBatch } from "firebase/firestore";
+/**
+ * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES
+ * (AGL-3386).
+ *
+ * A site's settings, and the plugin data its pages render — the theme, the
+ * announcement bar, a product, a site variable — are client Firestore writes
+ * with no publish step. The live site is ISR-cached for an hour, so each of
+ * those writes has to tell the tenant to drop the site's cached pages, or the
+ * change waits out the hour while the console says it is saved.
+ *
+ * Telling it from the tab is the fast path, and a tab is not durable: close
+ * it, sleep the laptop or lose the network between the write and the fetch,
+ * and the write has landed while the drop has landed nowhere. So the drop is
+ * also WRITTEN DOWN, as a publish outbox entry in the same batch as the
+ * write — either both land or neither does — and the console's scheduled
+ * drain fires any entry the tab did not get to release. This is the same
+ * mechanism a screen publish uses (AGL-2575); the entry carries
+ * `entireHost: true`, because a site-wide setting has no address of its own.
+ *
+ * Shared here rather than kept in the console because plugins write these
+ * documents too, and a plugin cannot import the console.
+ */ /**
+ * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same
+ * collection, and `host-document-writes-sweep.spec.ts` holds the two names
+ * and the entry's keys to the console's constants and to the rule.
+ */ export const SITE_WIDE_OUTBOX_COLLECTION = 'publishOutbox';
+/**
+ * What a site-wide entry names. The rule insists every entry names at least
+ * one address; the drain reads `entireHost` and drops every routed page of
+ * the site instead, which is what a site-wide change needs.
+ */ export const SITE_WIDE_OUTBOX_PATHS = [
+    '/'
+];
+/** Stages one site-wide outbox entry into the caller's batch. */ export function stageSiteWideOutboxEntry(batch, firestore, hostId) {
+    // Named by the id every console resource carries, never an SDK auto-id.
+    const ref = doc(firestore, SITE_WIDE_OUTBOX_COLLECTION, createResourceUid());
+    batch.set(ref, {
+        hostId,
+        paths: [
+            ...SITE_WIDE_OUTBOX_PATHS
+        ],
+        // A server timestamp: the rules pin it to `request.time`, and the drain
+        // ages entries by it.
+        createdAt: serverTimestamp(),
+        attempts: 0,
+        entireHost: true
+    });
+    return ref;
+}
+const isPermissionDenied = (error)=>(error == null ? void 0 : error.code) === 'permission-denied';
+/**
+ * Commits a write with its site-wide outbox entry beside it, and answers the
+ * entry — or `null` when the write had to land without one.
+ *
+ * `commit` performs the write. It is handed the stager on the first attempt
+ * and must put the entry in the SAME batch as the write; it is called again
+ * without one if that batch is refused.
+ *
+ * The retry is what keeps the entry from ever costing a save. The entry is
+ * the durable copy of a cache drop, and the write is the user's work: a rule
+ * that refuses the entry — the window between a code release and the rules
+ * deploy that admits it, or a role the outbox rule does not cover — must
+ * leave the save exactly as it was without it, with the tab's own drop still
+ * behind it. A write the rules refuse on its own merits is refused again,
+ * and that second refusal is the one the caller sees.
+ */ export async function commitWithSiteWideEntry(hostId, commit) {
+    // A holder rather than a `let`: the stager assigns it inside a callback,
+    // which control-flow narrowing cannot see.
+    const staged = {
+        entry: null
+    };
+    try {
+        await commit((batch, firestore)=>{
+            staged.entry = stageSiteWideOutboxEntry(batch, firestore, hostId);
+        });
+        return staged.entry;
+    } catch (error) {
+        if (!staged.entry || !isPermissionDenied(error)) throw error;
+        await commit(undefined);
+        return null;
+    }
+}
+/**
+ * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from
+ * the console route and nothing else. Any other answer leaves it for the
+ * drain, because the entry is the only record that the site may still be
+ * stale; the cost of keeping one needlessly is a duplicate drop, which is a
+ * no-op.
+ */ export async function releaseSiteWideOutboxEntry(entry, reason) {
+    if (!entry || reason !== 'ok') return;
+    await deleteDoc(entry).catch(()=>undefined);
+}
+/**
+ * Asks the console to drop every cached page of the site, and answers its
+ * reason — `'ok'` only when the drop landed.
+ *
+ * The plugin-side door to the console's own `/api/screens/revalidate`, which
+ * a plugin cannot import. Never throws: a cache hint that fails must not make
+ * a successful save look failed, and the outbox entry and the hour-long
+ * window are both underneath it.
+ */ export async function announceSiteWideChange(options) {
+    const { user, hostId } = options;
+    if (!hostId) return null;
+    try {
+        const response = await authorizedFetch(user, '/api/screens/revalidate', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                hostId,
+                entireHost: true
+            })
+        });
+        if (!response.ok) return `console-${response.status}`;
+        const body = await response.json().catch(()=>null);
+        return typeof (body == null ? void 0 : body.reason) === 'string' ? body.reason : 'ok';
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * After the write has landed: ask for the drop, and release the entry when it
+ * lands. Fire and forget — it never rejects.
+ */ export function settleSiteWideChange(options) {
+    const { user, hostId, entry } = options;
+    void announceSiteWideChange({
+        user,
+        hostId
+    }).then((reason)=>releaseSiteWideOutboxEntry(entry, reason)).catch(()=>undefined);
+}
+/**
+ * THE ONE CALL A PLUGIN'S CONSOLE CARD MAKES TO SAVE SOMETHING A PUBLISHED
+ * PAGE RENDERS.
+ *
+ * `write` stages the card's writes into the batch it is handed —
+ * `batch.update(ref, …)`, `batch.set(ref, …, { merge: true })`,
+ * `batch.delete(ref)` — and the batch commits with the site-wide outbox entry
+ * beside them. Resolves when the write has landed, rejects exactly when it
+ * did not; the drop runs behind it and never rejects.
+ */ export async function writeSiteWideChange(options) {
+    const { firestore, user, hostId, write } = options;
+    const entry = await commitWithSiteWideEntry(hostId, async (stage)=>{
+        const batch = writeBatch(firestore);
+        write(batch);
+        stage == null ? void 0 : stage(batch, firestore);
+        await batch.commit();
+    });
+    settleSiteWideChange({
+        user,
+        hostId,
+        entry
+    });
+}
+
+//# sourceMappingURL=site-wide-change.js.map

package/src/lib/hooks/helpers/site-wide-change.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/site-wide-change.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 { createResourceUid } from '@aglyn/aglyn/app-utils/create-resource-uid'\nimport { authorizedFetch } from '@aglyn/shared-util-http/authorized-token'\nimport {\n  deleteDoc,\n  doc,\n  serverTimestamp,\n  writeBatch,\n  type DocumentReference,\n  type Firestore,\n  type WriteBatch,\n} from 'firebase/firestore'\n\n/**\n * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES\n * (AGL-3386).\n *\n * A site's settings, and the plugin data its pages render — the theme, the\n * announcement bar, a product, a site variable — are client Firestore writes\n * with no publish step. The live site is ISR-cached for an hour, so each of\n * those writes has to tell the tenant to drop the site's cached pages, or the\n * change waits out the hour while the console says it is saved.\n *\n * Telling it from the tab is the fast path, and a tab is not durable: close\n * it, sleep the laptop or lose the network between the write and the fetch,\n * and the write has landed while the drop has landed nowhere. So the drop is\n * also WRITTEN DOWN, as a publish outbox entry in the same batch as the\n * write — either both land or neither does — and the console's scheduled\n * drain fires any entry the tab did not get to release. This is the same\n * mechanism a screen publish uses (AGL-2575); the entry carries\n * `entireHost: true`, because a site-wide setting has no address of its own.\n *\n * Shared here rather than kept in the console because plugins write these\n * documents too, and a plugin cannot import the console.\n */\n\n/**\n * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same\n * collection, and `host-document-writes-sweep.spec.ts` holds the two names\n * and the entry's keys to the console's constants and to the rule.\n */\nexport const SITE_WIDE_OUTBOX_COLLECTION = 'publishOutbox'\n\n/**\n * What a site-wide entry names. The rule insists every entry names at least\n * one address; the drain reads `entireHost` and drops every routed page of\n * the site instead, which is what a site-wide change needs.\n */\nexport const SITE_WIDE_OUTBOX_PATHS: readonly string[] = ['/']\n\n/**\n * What an entry can be staged into: a batch, or a transaction — anything\n * whose `set` lands in the same commit as the write beside it.\n */\nexport interface SiteWideEntryWriter {\n  set(ref: DocumentReference, data: Record<string, unknown>): unknown\n}\n\n/** Stages one site-wide outbox entry into the caller's batch. */\nexport function stageSiteWideOutboxEntry(\n  batch: SiteWideEntryWriter,\n  firestore: Firestore,\n  hostId: string,\n): DocumentReference {\n  // Named by the id every console resource carries, never an SDK auto-id.\n  const ref = doc(firestore, SITE_WIDE_OUTBOX_COLLECTION, createResourceUid())\n  batch.set(ref, {\n    hostId,\n    paths: [...SITE_WIDE_OUTBOX_PATHS],\n    // A server timestamp: the rules pin it to `request.time`, and the drain\n    // ages entries by it.\n    createdAt: serverTimestamp(),\n    attempts: 0,\n    entireHost: true,\n  })\n  return ref\n}\n\n/** Adds a site-wide outbox entry to a batch that is about to commit. */\nexport type StageSiteWideEntry = (\n  batch: SiteWideEntryWriter,\n  firestore: Firestore,\n) => void\n\nconst isPermissionDenied = (error: unknown): boolean =>\n  (error as { code?: unknown } | null)?.code === 'permission-denied'\n\n/**\n * Commits a write with its site-wide outbox entry beside it, and answers the\n * entry — or `null` when the write had to land without one.\n *\n * `commit` performs the write. It is handed the stager on the first attempt\n * and must put the entry in the SAME batch as the write; it is called again\n * without one if that batch is refused.\n *\n * The retry is what keeps the entry from ever costing a save. The entry is\n * the durable copy of a cache drop, and the write is the user's work: a rule\n * that refuses the entry — the window between a code release and the rules\n * deploy that admits it, or a role the outbox rule does not cover — must\n * leave the save exactly as it was without it, with the tab's own drop still\n * behind it. A write the rules refuse on its own merits is refused again,\n * and that second refusal is the one the caller sees.\n */\nexport async function commitWithSiteWideEntry(\n  hostId: string,\n  commit: (stage: StageSiteWideEntry | undefined) => Promise<void>,\n): Promise<DocumentReference | null> {\n  // A holder rather than a `let`: the stager assigns it inside a callback,\n  // which control-flow narrowing cannot see.\n  const staged: { entry: DocumentReference | null } = { entry: null }\n  try {\n    await commit((batch, firestore) => {\n      staged.entry = stageSiteWideOutboxEntry(batch, firestore, hostId)\n    })\n    return staged.entry\n  } catch (error) {\n    if (!staged.entry || !isPermissionDenied(error)) throw error\n    await commit(undefined)\n    return null\n  }\n}\n\n/**\n * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from\n * the console route and nothing else. Any other answer leaves it for the\n * drain, because the entry is the only record that the site may still be\n * stale; the cost of keeping one needlessly is a duplicate drop, which is a\n * no-op.\n */\nexport async function releaseSiteWideOutboxEntry(\n  entry: DocumentReference | null,\n  reason: string | null | undefined,\n): Promise<void> {\n  if (!entry || reason !== 'ok') return\n  await deleteDoc(entry).catch(() => undefined)\n}\n\n/**\n * Asks the console to drop every cached page of the site, and answers its\n * reason — `'ok'` only when the drop landed.\n *\n * The plugin-side door to the console's own `/api/screens/revalidate`, which\n * a plugin cannot import. Never throws: a cache hint that fails must not make\n * a successful save look failed, and the outbox entry and the hour-long\n * window are both underneath it.\n */\nexport async function announceSiteWideChange(options: {\n  /** The signed-in user; its ID token authenticates the console route. */\n  user: { getIdToken?: () => Promise<string> } | null | undefined\n  hostId: string\n}): Promise<string | null> {\n  const { user, hostId } = options\n  if (!hostId) return null\n  try {\n    const response = await authorizedFetch(user, '/api/screens/revalidate', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ hostId, entireHost: true }),\n    })\n    if (!response.ok) return `console-${response.status}`\n    const body = (await response.json().catch(() => null)) as {\n      reason?: unknown\n    } | null\n    return typeof body?.reason === 'string' ? body.reason : 'ok'\n  } catch {\n    return null\n  }\n}\n\n/**\n * After the write has landed: ask for the drop, and release the entry when it\n * lands. Fire and forget — it never rejects.\n */\nexport function settleSiteWideChange(options: {\n  user: { getIdToken?: () => Promise<string> } | null | undefined\n  hostId: string\n  entry: DocumentReference | null\n}): void {\n  const { user, hostId, entry } = options\n  void announceSiteWideChange({ user, hostId })\n    .then((reason) => releaseSiteWideOutboxEntry(entry, reason))\n    .catch(() => undefined)\n}\n\n/**\n * THE ONE CALL A PLUGIN'S CONSOLE CARD MAKES TO SAVE SOMETHING A PUBLISHED\n * PAGE RENDERS.\n *\n * `write` stages the card's writes into the batch it is handed —\n * `batch.update(ref, …)`, `batch.set(ref, …, { merge: true })`,\n * `batch.delete(ref)` — and the batch commits with the site-wide outbox entry\n * beside them. Resolves when the write has landed, rejects exactly when it\n * did not; the drop runs behind it and never rejects.\n */\nexport async function writeSiteWideChange(options: {\n  firestore: Firestore\n  user: { getIdToken?: () => Promise<string> } | null | undefined\n  hostId: string\n  write: (batch: WriteBatch) => void\n}): Promise<void> {\n  const { firestore, user, hostId, write } = options\n  const entry = await commitWithSiteWideEntry(hostId, async (stage) => {\n    const batch = writeBatch(firestore)\n    write(batch)\n    stage?.(batch, firestore)\n    await batch.commit()\n  })\n  settleSiteWideChange({ user, hostId, entry })\n}\n"],"names":["createResourceUid","authorizedFetch","deleteDoc","doc","serverTimestamp","writeBatch","SITE_WIDE_OUTBOX_COLLECTION","SITE_WIDE_OUTBOX_PATHS","stageSiteWideOutboxEntry","batch","firestore","hostId","ref","set","paths","createdAt","attempts","entireHost","isPermissionDenied","error","code","commitWithSiteWideEntry","commit","staged","entry","undefined","releaseSiteWideOutboxEntry","reason","catch","announceSiteWideChange","options","user","response","method","headers","body","JSON","stringify","ok","status","json","settleSiteWideChange","then","writeSiteWideChange","write","stage"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,eAAe,QAAQ,2CAA0C;AAC1E,SACEC,SAAS,EACTC,GAAG,EACHC,eAAe,EACfC,UAAU,QAIL,qBAAoB;AAE3B;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED;;;;CAIC,GACD,OAAO,MAAMC,8BAA8B,gBAAe;AAE1D;;;;CAIC,GACD,OAAO,MAAMC,yBAA4C;IAAC;CAAI,CAAA;AAU9D,+DAA+D,GAC/D,OAAO,SAASC,yBACdC,KAA0B,EAC1BC,SAAoB,EACpBC,MAAc;IAEd,wEAAwE;IACxE,MAAMC,MAAMT,IAAIO,WAAWJ,6BAA6BN;IACxDS,MAAMI,GAAG,CAACD,KAAK;QACbD;QACAG,OAAO;eAAIP;SAAuB;QAClC,wEAAwE;QACxE,sBAAsB;QACtBQ,WAAWX;QACXY,UAAU;QACVC,YAAY;IACd;IACA,OAAOL;AACT;AAQA,MAAMM,qBAAqB,CAACC,QAC1B,CAACA,yBAAD,AAACA,MAAqCC,IAAI,MAAK;AAEjD;;;;;;;;;;;;;;;CAeC,GACD,OAAO,eAAeC,wBACpBV,MAAc,EACdW,MAAgE;IAEhE,yEAAyE;IACzE,2CAA2C;IAC3C,MAAMC,SAA8C;QAAEC,OAAO;IAAK;IAClE,IAAI;QACF,MAAMF,OAAO,CAACb,OAAOC;YACnBa,OAAOC,KAAK,GAAGhB,yBAAyBC,OAAOC,WAAWC;QAC5D;QACA,OAAOY,OAAOC,KAAK;IACrB,EAAE,OAAOL,OAAO;QACd,IAAI,CAACI,OAAOC,KAAK,IAAI,CAACN,mBAAmBC,QAAQ,MAAMA;QACvD,MAAMG,OAAOG;QACb,OAAO;IACT;AACF;AAEA;;;;;;CAMC,GACD,OAAO,eAAeC,2BACpBF,KAA+B,EAC/BG,MAAiC;IAEjC,IAAI,CAACH,SAASG,WAAW,MAAM;IAC/B,MAAMzB,UAAUsB,OAAOI,KAAK,CAAC,IAAMH;AACrC;AAEA;;;;;;;;CAQC,GACD,OAAO,eAAeI,uBAAuBC,OAI5C;IACC,MAAM,EAAEC,IAAI,EAAEpB,MAAM,EAAE,GAAGmB;IACzB,IAAI,CAACnB,QAAQ,OAAO;IACpB,IAAI;QACF,MAAMqB,WAAW,MAAM/B,gBAAgB8B,MAAM,2BAA2B;YACtEE,QAAQ;YACRC,SAAS;gBAAE,gBAAgB;YAAmB;YAC9CC,MAAMC,KAAKC,SAAS,CAAC;gBAAE1B;gBAAQM,YAAY;YAAK;QAClD;QACA,IAAI,CAACe,SAASM,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAEN,SAASO,MAAM,EAAE;QACrD,MAAMJ,OAAQ,MAAMH,SAASQ,IAAI,GAAGZ,KAAK,CAAC,IAAM;QAGhD,OAAO,QAAOO,wBAAAA,KAAMR,MAAM,MAAK,WAAWQ,KAAKR,MAAM,GAAG;IAC1D,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;CAGC,GACD,OAAO,SAASc,qBAAqBX,OAIpC;IACC,MAAM,EAAEC,IAAI,EAAEpB,MAAM,EAAEa,KAAK,EAAE,GAAGM;IAChC,KAAKD,uBAAuB;QAAEE;QAAMpB;IAAO,GACxC+B,IAAI,CAAC,CAACf,SAAWD,2BAA2BF,OAAOG,SACnDC,KAAK,CAAC,IAAMH;AACjB;AAEA;;;;;;;;;CASC,GACD,OAAO,eAAekB,oBAAoBb,OAKzC;IACC,MAAM,EAAEpB,SAAS,EAAEqB,IAAI,EAAEpB,MAAM,EAAEiC,KAAK,EAAE,GAAGd;IAC3C,MAAMN,QAAQ,MAAMH,wBAAwBV,QAAQ,OAAOkC;QACzD,MAAMpC,QAAQJ,WAAWK;QACzBkC,MAAMnC;QACNoC,yBAAAA,MAAQpC,OAAOC;QACf,MAAMD,MAAMa,MAAM;IACpB;IACAmB,qBAAqB;QAAEV;QAAMpB;QAAQa;IAAM;AAC7C"}

package/src/lib/hooks/helpers/use-modify-doc-callback.d.ts

@@ -14,11 +14,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type DocumentReference, type SetOptions, type UpdateData } from 'firebase/firestore';
+import { type DocumentReference, type Firestore, type SetOptions, type UpdateData, type WriteBatch } from 'firebase/firestore';
 export type UpdateDocCallback<T> = (data: UpdateData<T>) => Promise<void>;
 export type SetDocCallback<T> = (data: Partial<T>, options?: SetOptions) => Promise<void>;
 export type ModifyDocOptions = SetOptions & {
     shouldSet?: boolean;
+    /**
+     * Other writes that must land in the SAME commit as this one, or not at
+     * all. Given, the write goes through a batch — the same stamp, strip and
+     * converter as without it — with whatever this stages beside it. The
+     * console uses it to write a site-wide cache drop down durably next to a
+     * settings save (AGL-3386).
+     */
+    alongside?: (batch: WriteBatch, firestore: Firestore) => void;
 };
 export type ModifyDocCallback<T> = (data: UpdateData<T> | Partial<T>, options?: ModifyDocOptions) => Promise<void>;
 export declare function useUpdateDocCallback<T>(ref: DocumentReference<T>): UpdateDocCallback<T>;

package/src/lib/hooks/helpers/use-modify-doc-callback.js

@@ -1,4 +1,5 @@
 import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
 /**
  * @license
  * Copyright 2022 Aglyn LLC
@@ -15,7 +16,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { HOST_UNPERSISTED_FIELDS, ORG_UNPERSISTED_FIELDS } from "@aglyn/aglyn";
-import { serverTimestamp, setDoc, updateDoc } from "firebase/firestore";
+import { serverTimestamp, setDoc, updateDoc, writeBatch } from "firebase/firestore";
 import { useCallback } from "react";
 /**
  * Every UI write stamps `updatedAt` (AGL-455) — the "last updated" columns
@@ -98,9 +99,27 @@ export function useModifyDocCallback(ref) {
         // a payload. Anything that must hold for both branches belongs above
         // it, which is where `dropUnpersistedFields` now runs.
         const shouldSet = (options == null ? void 0 : options.shouldSet) || options && 'merge' in options || options && 'mergeFields' in options;
+        if (options == null ? void 0 : options.alongside) {
+            // `shouldSet` is this hook's own flag, never a Firestore option.
+            const { alongside, shouldSet: _flag } = options, setOptions = _object_without_properties_loose(options, [
+                "alongside",
+                "shouldSet"
+            ]);
+            void _flag;
+            const batch = writeBatch(ref.firestore);
+            const payload = stampUpdatedAt(dropUnpersistedFields(data));
+            // `batch.set` applies the ref's converter exactly as `setDoc` does,
+            // and `batch.update` skips it exactly as `updateDoc` does — so the
+            // batched write stores what the unbatched one would have.
+            if (shouldSet) batch.set(ref, payload, setOptions);
+            else batch.update(ref, payload);
+            alongside(batch, ref.firestore);
+            return batch.commit();
+        }
         if (shouldSet) return setDocCb(data, options);
         return updateDocCb(data);
     }, [
+        ref,
         updateDocCb,
         setDocCb
     ]);

package/src/lib/hooks/helpers/use-modify-doc-callback.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/use-modify-doc-callback.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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 { HOST_UNPERSISTED_FIELDS, ORG_UNPERSISTED_FIELDS } from '@aglyn/aglyn'\nimport {\n  type DocumentReference,\n  serverTimestamp,\n  setDoc,\n  type SetOptions,\n  type UpdateData,\n  updateDoc,\n} from 'firebase/firestore'\nimport { useCallback } from 'react'\n\n/**\n * Every UI write stamps `updatedAt` (AGL-455) — the \"last updated\" columns\n * read it, and callers historically forgot it. Spread order lets a caller's\n * explicit `updatedAt` win (backfills, imports).\n */\nfunction stampUpdatedAt<D extends object>(data: D): D {\n  return { updatedAt: serverTimestamp(), ...data }\n}\n\n/**\n * Keys that are never document fields, taken from where that is written down\n * (AGL-1429). `HOST_UNPERSISTED_FIELDS` and `ORG_UNPERSISTED_FIELDS` each\n * declare the synthetic `$id` the readers attach; the INTERSECTION is used\n * deliberately, so this generic boundary only ever strips a key that every\n * declaration agrees is unpersisted. A key added to one map alone is not\n * silently stripped from the other collection's writes — the spec's drift\n * assertion fires instead, and someone decides.\n */\n/*\n * Resolved on first use, not at module scope. Computing it eagerly made this\n * module — and therefore every consumer of the write callbacks — fail to LOAD\n * in any suite that mocks the `@aglyn/aglyn` barrel without re-exporting both\n * maps, which two console specs do. A write-boundary guard that cannot be\n * imported is worse than the leak it prevents.\n */\nlet unpersistedFields: readonly string[] | undefined\n\nfunction getUnpersistedFields(): readonly string[] {\n  if (unpersistedFields) return unpersistedFields\n  const host = HOST_UNPERSISTED_FIELDS ?? {}\n  const org = ORG_UNPERSISTED_FIELDS ?? {}\n  unpersistedFields = Object.freeze(\n    Object.keys(host).filter((key) => key in org),\n  )\n  return unpersistedFields\n}\n\n/**\n * Drop the reader-injected keys before the payload leaves for Firestore.\n *\n * This has to happen here rather than in the refs' converters, which is where\n * it used to live alone (`503f197ca` added the `$id` strip to `useHostRef`'s\n * `toFirestore`). `updateDoc` never applies a converter — `setDoc` calls\n * `applyFirestoreDataConverter` and `updateDoc` does not — so a converter\n * strip is a guarantee about ONE of the two SDK calls, and which one a write\n * gets is decided by whether its caller happened to pass `merge`. That is how\n * `hosts/-MtN17_cpfPPLwWjE6z4` came to hold a persisted `$id` (AGL-1423).\n *\n * Only exact top-level keys are removed. Dotted `updateDoc` paths address\n * nested maps, and besigner node maps legitimately store a `$id` per node —\n * matching those would be the same over-broad scan AGL-1423 warned about.\n */\nfunction dropUnpersistedFields<D extends object>(data: D): D {\n  const keys = getUnpersistedFields()\n  if (!keys.some((key) => key in data)) return data\n  const rest = { ...data } as Record<string, unknown>\n  for (const key of keys) delete rest[key]\n  return rest as D\n}\n\n\nexport type UpdateDocCallback<T> = (data: UpdateData<T>) => Promise<void>\nexport type SetDocCallback<T> = (\n  data: Partial<T>,\n  options?: SetOptions,\n) => Promise<void>\nexport type ModifyDocOptions = SetOptions & { shouldSet?: boolean }\nexport type ModifyDocCallback<T> = (\n  data: UpdateData<T> | Partial<T>,\n  options?: ModifyDocOptions,\n) => Promise<void>\n\n// `updateDoc`'s overload resolution keys off `DocumentReference`'s\n// `DbModelType` param, which defaults to the generic `DocumentData` when a\n// caller only supplies `AppModelType` (as every hook here does) — that\n// makes TS widen `UpdateData<T>` for unconstrained `T` and reject the\n// match. Pin the call to the single-overload signature actually used.\nconst typedUpdateDoc = updateDoc as <T>(\n  ref: DocumentReference<T>,\n  data: UpdateData<T>,\n) => Promise<void>\n\nexport function useUpdateDocCallback<T>(\n  ref: DocumentReference<T>,\n): UpdateDocCallback<T> {\n  return useCallback(\n    (data: UpdateData<T>) =>\n      typedUpdateDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as UpdateData<T>,\n      ),\n    [ref],\n  )\n}\n\nexport function useSetDocCallback<T>(\n  ref: DocumentReference<T>,\n): SetDocCallback<T> {\n  return useCallback(\n    (data: Partial<T>, options?: SetOptions) =>\n      setDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as Partial<T>,\n        options ?? {},\n      ),\n    [ref],\n  )\n}\n\nexport function useModifyDocCallback<T>(\n  ref: DocumentReference<T>,\n): ModifyDocCallback<T> {\n  const updateDocCb = useUpdateDocCallback(ref)\n  const setDocCb = useSetDocCallback(ref)\n  return useCallback(\n    (data: UpdateData<T> | Partial<T>, options?: ModifyDocOptions) => {\n      // SetOptions semantics (merge/mergeFields) require setDoc: updateDoc\n      // ignores them and, critically, bypasses the ref's withConverter\n      // serialization (e.g. screen-version node compression) — and with it\n      // EVERY strip the converter performs, including `$id` (AGL-1429).\n      //\n      // Nothing downstream of this line may therefore be relied on to clean\n      // a payload. Anything that must hold for both branches belongs above\n      // it, which is where `dropUnpersistedFields` now runs.\n      const shouldSet =\n        options?.shouldSet ||\n        (options && 'merge' in options) ||\n        (options && 'mergeFields' in options)\n      if (shouldSet) return setDocCb(data as Partial<T>, options)\n      return updateDocCb(data as UpdateData<T>)\n    },\n    [updateDocCb, setDocCb],\n  )\n}\n\n\nexport type UseModifyDocCallback<T> = typeof useModifyDocCallback<T>\n\nexport default useModifyDocCallback\n"],"names":["HOST_UNPERSISTED_FIELDS","ORG_UNPERSISTED_FIELDS","serverTimestamp","setDoc","updateDoc","useCallback","stampUpdatedAt","data","updatedAt","unpersistedFields","getUnpersistedFields","host","org","Object","freeze","keys","filter","key","dropUnpersistedFields","some","rest","typedUpdateDoc","useUpdateDocCallback","ref","useSetDocCallback","options","useModifyDocCallback","updateDocCb","setDocCb","shouldSet"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,EAAEC,sBAAsB,QAAQ,eAAc;AAC9E,SAEEC,eAAe,EACfC,MAAM,EAGNC,SAAS,QACJ,qBAAoB;AAC3B,SAASC,WAAW,QAAQ,QAAO;AAEnC;;;;CAIC,GACD,SAASC,eAAiCC,IAAO;IAC/C,OAAO;QAAEC,WAAWN;OAAsBK;AAC5C;AAEA;;;;;;;;CAQC,GACD;;;;;;CAMC,GACD,IAAIE;AAEJ,SAASC;IACP,IAAID,mBAAmB,OAAOA;IAC9B,MAAME,OAAOX,kCAAAA,0BAA2B,CAAC;IACzC,MAAMY,MAAMX,iCAAAA,yBAA0B,CAAC;IACvCQ,oBAAoBI,OAAOC,MAAM,CAC/BD,OAAOE,IAAI,CAACJ,MAAMK,MAAM,CAAC,CAACC,MAAQA,OAAOL;IAE3C,OAAOH;AACT;AAEA;;;;;;;;;;;;;;CAcC,GACD,SAASS,sBAAwCX,IAAO;IACtD,MAAMQ,OAAOL;IACb,IAAI,CAACK,KAAKI,IAAI,CAAC,CAACF,MAAQA,OAAOV,OAAO,OAAOA;IAC7C,MAAMa,OAAO,aAAKb;IAClB,KAAK,MAAMU,OAAOF,KAAM,OAAOK,IAAI,CAACH,IAAI;IACxC,OAAOG;AACT;AAcA,mEAAmE;AACnE,2EAA2E;AAC3E,uEAAuE;AACvE,sEAAsE;AACtE,sEAAsE;AACtE,MAAMC,iBAAiBjB;AAKvB,OAAO,SAASkB,qBACdC,GAAyB;IAEzB,OAAOlB,YACL,CAACE,OACCc,eACEE,KACAjB,eAAeY,sBAAsBX,SAEzC;QAACgB;KAAI;AAET;AAEA,OAAO,SAASC,kBACdD,GAAyB;IAEzB,OAAOlB,YACL,CAACE,MAAkBkB,UACjBtB,OACEoB,KACAjB,eAAeY,sBAAsBX,QACrCkB,kBAAAA,UAAW,CAAC,IAEhB;QAACF;KAAI;AAET;AAEA,OAAO,SAASG,qBACdH,GAAyB;IAEzB,MAAMI,cAAcL,qBAAqBC;IACzC,MAAMK,WAAWJ,kBAAkBD;IACnC,OAAOlB,YACL,CAACE,MAAkCkB;QACjC,qEAAqE;QACrE,iEAAiE;QACjE,qEAAqE;QACrE,kEAAkE;QAClE,EAAE;QACF,sEAAsE;QACtE,qEAAqE;QACrE,uDAAuD;QACvD,MAAMI,YACJJ,CAAAA,2BAAAA,QAASI,SAAS,KACjBJ,WAAW,WAAWA,WACtBA,WAAW,iBAAiBA;QAC/B,IAAII,WAAW,OAAOD,SAASrB,MAAoBkB;QACnD,OAAOE,YAAYpB;IACrB,GACA;QAACoB;QAAaC;KAAS;AAE3B;AAKA,eAAeF,qBAAoB"}
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/use-modify-doc-callback.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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 { HOST_UNPERSISTED_FIELDS, ORG_UNPERSISTED_FIELDS } from '@aglyn/aglyn'\nimport {\n  type DocumentData,\n  type DocumentReference,\n  type Firestore,\n  serverTimestamp,\n  setDoc,\n  type SetOptions,\n  type UpdateData,\n  updateDoc,\n  type WriteBatch,\n  writeBatch,\n} from 'firebase/firestore'\nimport { useCallback } from 'react'\n\n/**\n * Every UI write stamps `updatedAt` (AGL-455) — the \"last updated\" columns\n * read it, and callers historically forgot it. Spread order lets a caller's\n * explicit `updatedAt` win (backfills, imports).\n */\nfunction stampUpdatedAt<D extends object>(data: D): D {\n  return { updatedAt: serverTimestamp(), ...data }\n}\n\n/**\n * Keys that are never document fields, taken from where that is written down\n * (AGL-1429). `HOST_UNPERSISTED_FIELDS` and `ORG_UNPERSISTED_FIELDS` each\n * declare the synthetic `$id` the readers attach; the INTERSECTION is used\n * deliberately, so this generic boundary only ever strips a key that every\n * declaration agrees is unpersisted. A key added to one map alone is not\n * silently stripped from the other collection's writes — the spec's drift\n * assertion fires instead, and someone decides.\n */\n/*\n * Resolved on first use, not at module scope. Computing it eagerly made this\n * module — and therefore every consumer of the write callbacks — fail to LOAD\n * in any suite that mocks the `@aglyn/aglyn` barrel without re-exporting both\n * maps, which two console specs do. A write-boundary guard that cannot be\n * imported is worse than the leak it prevents.\n */\nlet unpersistedFields: readonly string[] | undefined\n\nfunction getUnpersistedFields(): readonly string[] {\n  if (unpersistedFields) return unpersistedFields\n  const host = HOST_UNPERSISTED_FIELDS ?? {}\n  const org = ORG_UNPERSISTED_FIELDS ?? {}\n  unpersistedFields = Object.freeze(\n    Object.keys(host).filter((key) => key in org),\n  )\n  return unpersistedFields\n}\n\n/**\n * Drop the reader-injected keys before the payload leaves for Firestore.\n *\n * This has to happen here rather than in the refs' converters, which is where\n * it used to live alone (`503f197ca` added the `$id` strip to `useHostRef`'s\n * `toFirestore`). `updateDoc` never applies a converter — `setDoc` calls\n * `applyFirestoreDataConverter` and `updateDoc` does not — so a converter\n * strip is a guarantee about ONE of the two SDK calls, and which one a write\n * gets is decided by whether its caller happened to pass `merge`. That is how\n * `hosts/-MtN17_cpfPPLwWjE6z4` came to hold a persisted `$id` (AGL-1423).\n *\n * Only exact top-level keys are removed. Dotted `updateDoc` paths address\n * nested maps, and besigner node maps legitimately store a `$id` per node —\n * matching those would be the same over-broad scan AGL-1423 warned about.\n */\nfunction dropUnpersistedFields<D extends object>(data: D): D {\n  const keys = getUnpersistedFields()\n  if (!keys.some((key) => key in data)) return data\n  const rest = { ...data } as Record<string, unknown>\n  for (const key of keys) delete rest[key]\n  return rest as D\n}\n\n\nexport type UpdateDocCallback<T> = (data: UpdateData<T>) => Promise<void>\nexport type SetDocCallback<T> = (\n  data: Partial<T>,\n  options?: SetOptions,\n) => Promise<void>\nexport type ModifyDocOptions = SetOptions & {\n  shouldSet?: boolean\n  /**\n   * Other writes that must land in the SAME commit as this one, or not at\n   * all. Given, the write goes through a batch — the same stamp, strip and\n   * converter as without it — with whatever this stages beside it. The\n   * console uses it to write a site-wide cache drop down durably next to a\n   * settings save (AGL-3386).\n   */\n  alongside?: (batch: WriteBatch, firestore: Firestore) => void\n}\nexport type ModifyDocCallback<T> = (\n  data: UpdateData<T> | Partial<T>,\n  options?: ModifyDocOptions,\n) => Promise<void>\n\n// `updateDoc`'s overload resolution keys off `DocumentReference`'s\n// `DbModelType` param, which defaults to the generic `DocumentData` when a\n// caller only supplies `AppModelType` (as every hook here does) — that\n// makes TS widen `UpdateData<T>` for unconstrained `T` and reject the\n// match. Pin the call to the single-overload signature actually used.\nconst typedUpdateDoc = updateDoc as <T>(\n  ref: DocumentReference<T>,\n  data: UpdateData<T>,\n) => Promise<void>\n\nexport function useUpdateDocCallback<T>(\n  ref: DocumentReference<T>,\n): UpdateDocCallback<T> {\n  return useCallback(\n    (data: UpdateData<T>) =>\n      typedUpdateDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as UpdateData<T>,\n      ),\n    [ref],\n  )\n}\n\nexport function useSetDocCallback<T>(\n  ref: DocumentReference<T>,\n): SetDocCallback<T> {\n  return useCallback(\n    (data: Partial<T>, options?: SetOptions) =>\n      setDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as Partial<T>,\n        options ?? {},\n      ),\n    [ref],\n  )\n}\n\nexport function useModifyDocCallback<T>(\n  ref: DocumentReference<T>,\n): ModifyDocCallback<T> {\n  const updateDocCb = useUpdateDocCallback(ref)\n  const setDocCb = useSetDocCallback(ref)\n  return useCallback(\n    (data: UpdateData<T> | Partial<T>, options?: ModifyDocOptions) => {\n      // SetOptions semantics (merge/mergeFields) require setDoc: updateDoc\n      // ignores them and, critically, bypasses the ref's withConverter\n      // serialization (e.g. screen-version node compression) — and with it\n      // EVERY strip the converter performs, including `$id` (AGL-1429).\n      //\n      // Nothing downstream of this line may therefore be relied on to clean\n      // a payload. Anything that must hold for both branches belongs above\n      // it, which is where `dropUnpersistedFields` now runs.\n      const shouldSet =\n        options?.shouldSet ||\n        (options && 'merge' in options) ||\n        (options && 'mergeFields' in options)\n      if (options?.alongside) {\n        // `shouldSet` is this hook's own flag, never a Firestore option.\n        const { alongside, shouldSet: _flag, ...setOptions } = options\n        void _flag\n        const batch = writeBatch(ref.firestore)\n        const payload = stampUpdatedAt(dropUnpersistedFields(data as object))\n        // `batch.set` applies the ref's converter exactly as `setDoc` does,\n        // and `batch.update` skips it exactly as `updateDoc` does — so the\n        // batched write stores what the unbatched one would have.\n        if (shouldSet) batch.set(ref, payload as Partial<T>, setOptions)\n        // Pinned to the untyped overload for the reason `typedUpdateDoc` is.\n        else batch.update(ref as DocumentReference, payload as UpdateData<DocumentData>)\n        alongside(batch, ref.firestore)\n        return batch.commit()\n      }\n      if (shouldSet) return setDocCb(data as Partial<T>, options)\n      return updateDocCb(data as UpdateData<T>)\n    },\n    [ref, updateDocCb, setDocCb],\n  )\n}\n\n\nexport type UseModifyDocCallback<T> = typeof useModifyDocCallback<T>\n\nexport default useModifyDocCallback\n"],"names":["HOST_UNPERSISTED_FIELDS","ORG_UNPERSISTED_FIELDS","serverTimestamp","setDoc","updateDoc","writeBatch","useCallback","stampUpdatedAt","data","updatedAt","unpersistedFields","getUnpersistedFields","host","org","Object","freeze","keys","filter","key","dropUnpersistedFields","some","rest","typedUpdateDoc","useUpdateDocCallback","ref","useSetDocCallback","options","useModifyDocCallback","updateDocCb","setDocCb","shouldSet","alongside","_flag","setOptions","batch","firestore","payload","set","update","commit"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,EAAEC,sBAAsB,QAAQ,eAAc;AAC9E,SAIEC,eAAe,EACfC,MAAM,EAGNC,SAAS,EAETC,UAAU,QACL,qBAAoB;AAC3B,SAASC,WAAW,QAAQ,QAAO;AAEnC;;;;CAIC,GACD,SAASC,eAAiCC,IAAO;IAC/C,OAAO;QAAEC,WAAWP;OAAsBM;AAC5C;AAEA;;;;;;;;CAQC,GACD;;;;;;CAMC,GACD,IAAIE;AAEJ,SAASC;IACP,IAAID,mBAAmB,OAAOA;IAC9B,MAAME,OAAOZ,kCAAAA,0BAA2B,CAAC;IACzC,MAAMa,MAAMZ,iCAAAA,yBAA0B,CAAC;IACvCS,oBAAoBI,OAAOC,MAAM,CAC/BD,OAAOE,IAAI,CAACJ,MAAMK,MAAM,CAAC,CAACC,MAAQA,OAAOL;IAE3C,OAAOH;AACT;AAEA;;;;;;;;;;;;;;CAcC,GACD,SAASS,sBAAwCX,IAAO;IACtD,MAAMQ,OAAOL;IACb,IAAI,CAACK,KAAKI,IAAI,CAAC,CAACF,MAAQA,OAAOV,OAAO,OAAOA;IAC7C,MAAMa,OAAO,aAAKb;IAClB,KAAK,MAAMU,OAAOF,KAAM,OAAOK,IAAI,CAACH,IAAI;IACxC,OAAOG;AACT;AAwBA,mEAAmE;AACnE,2EAA2E;AAC3E,uEAAuE;AACvE,sEAAsE;AACtE,sEAAsE;AACtE,MAAMC,iBAAiBlB;AAKvB,OAAO,SAASmB,qBACdC,GAAyB;IAEzB,OAAOlB,YACL,CAACE,OACCc,eACEE,KACAjB,eAAeY,sBAAsBX,SAEzC;QAACgB;KAAI;AAET;AAEA,OAAO,SAASC,kBACdD,GAAyB;IAEzB,OAAOlB,YACL,CAACE,MAAkBkB,UACjBvB,OACEqB,KACAjB,eAAeY,sBAAsBX,QACrCkB,kBAAAA,UAAW,CAAC,IAEhB;QAACF;KAAI;AAET;AAEA,OAAO,SAASG,qBACdH,GAAyB;IAEzB,MAAMI,cAAcL,qBAAqBC;IACzC,MAAMK,WAAWJ,kBAAkBD;IACnC,OAAOlB,YACL,CAACE,MAAkCkB;QACjC,qEAAqE;QACrE,iEAAiE;QACjE,qEAAqE;QACrE,kEAAkE;QAClE,EAAE;QACF,sEAAsE;QACtE,qEAAqE;QACrE,uDAAuD;QACvD,MAAMI,YACJJ,CAAAA,2BAAAA,QAASI,SAAS,KACjBJ,WAAW,WAAWA,WACtBA,WAAW,iBAAiBA;QAC/B,IAAIA,2BAAAA,QAASK,SAAS,EAAE;YACtB,iEAAiE;YACjE,MAAM,EAAEA,SAAS,EAAED,WAAWE,KAAK,EAAiB,GAAGN,SAAfO,8CAAeP;;;;YACvD,KAAKM;YACL,MAAME,QAAQ7B,WAAWmB,IAAIW,SAAS;YACtC,MAAMC,UAAU7B,eAAeY,sBAAsBX;YACrD,oEAAoE;YACpE,mEAAmE;YACnE,0DAA0D;YAC1D,IAAIsB,WAAWI,MAAMG,GAAG,CAACb,KAAKY,SAAuBH;iBAEhDC,MAAMI,MAAM,CAACd,KAA0BY;YAC5CL,UAAUG,OAAOV,IAAIW,SAAS;YAC9B,OAAOD,MAAMK,MAAM;QACrB;QACA,IAAIT,WAAW,OAAOD,SAASrB,MAAoBkB;QACnD,OAAOE,YAAYpB;IACrB,GACA;QAACgB;QAAKI;QAAaC;KAAS;AAEhC;AAKA,eAAeF,qBAAoB"}

package/src/lib/testing/site-wide-change-double.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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.
+ */
+/**
+ * A stand-in for `hooks/helpers/site-wide-change` in a card's spec (AGL-3386).
+ *
+ * A card that saves something a published page renders writes through
+ * `writeSiteWideChange`, which batches the write with a publish outbox entry
+ * and asks the console to drop the site's cache. A card's spec is about the
+ * write the card makes, and it already doubles `firebase/firestore`'s
+ * `setDoc`/`updateDoc`/`deleteDoc` to see it. This routes each staged batch
+ * operation to the SAME double call the card made before it batched — so a
+ * spec keeps asserting what reached storage, and says nothing about a cache
+ * drop it is not testing. The helper's own contract is pinned in
+ * `site-wide-change.spec.ts`.
+ *
+ * Use it as the factory of the module mock:
+ *
+ *     jest.mock('@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change', () =>
+ *       jest
+ *         .requireActual('@aglyn/tenant-feature-instance/testing/site-wide-change-double')
+ *         .siteWideChangeThroughSdk(() => jest.requireMock('firebase/firestore')),
+ *     )
+ *
+ * The SDK is handed in rather than required here: Jest injects `jest` into
+ * each spec module rather than onto `globalThis`, so this file cannot reach
+ * the spec's mock itself.
+ */
+type SdkCall = (...args: unknown[]) => Promise<unknown>;
+interface SdkWrites {
+    setDoc: SdkCall;
+    updateDoc: SdkCall;
+    deleteDoc: SdkCall;
+}
+/** The module's exports, with every write sent to the doubled SDK calls. */
+export declare function siteWideChangeThroughSdk(sdk: () => SdkWrites): {
+    __esModule: boolean;
+    SITE_WIDE_OUTBOX_COLLECTION: string;
+    SITE_WIDE_OUTBOX_PATHS: string[];
+    writeSiteWideChange: (options: {
+        write: (batch: ReturnType<(pending: Promise<unknown>[]) => {
+            set: (...args: unknown[]) => void;
+            update: (...args: unknown[]) => void;
+            delete: (...args: unknown[]) => void;
+        }>) => void;
+    }) => Promise<void>;
+    commitWithSiteWideEntry: (_hostId: string, commit: (stage: undefined) => Promise<void>) => Promise<any>;
+    settleSiteWideChange: () => any;
+    announceSiteWideChange: () => Promise<any>;
+    releaseSiteWideOutboxEntry: () => Promise<any>;
+    stageSiteWideOutboxEntry: () => any;
+};
+export {};

package/src/lib/testing/site-wide-change-double.js

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */ /**
+ * A stand-in for `hooks/helpers/site-wide-change` in a card's spec (AGL-3386).
+ *
+ * A card that saves something a published page renders writes through
+ * `writeSiteWideChange`, which batches the write with a publish outbox entry
+ * and asks the console to drop the site's cache. A card's spec is about the
+ * write the card makes, and it already doubles `firebase/firestore`'s
+ * `setDoc`/`updateDoc`/`deleteDoc` to see it. This routes each staged batch
+ * operation to the SAME double call the card made before it batched — so a
+ * spec keeps asserting what reached storage, and says nothing about a cache
+ * drop it is not testing. The helper's own contract is pinned in
+ * `site-wide-change.spec.ts`.
+ *
+ * Use it as the factory of the module mock:
+ *
+ *     jest.mock('@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change', () =>
+ *       jest
+ *         .requireActual('@aglyn/tenant-feature-instance/testing/site-wide-change-double')
+ *         .siteWideChangeThroughSdk(() => jest.requireMock('firebase/firestore')),
+ *     )
+ *
+ * The SDK is handed in rather than required here: Jest injects `jest` into
+ * each spec module rather than onto `globalThis`, so this file cannot reach
+ * the spec's mock itself.
+ */ /** The module's exports, with every write sent to the doubled SDK calls. */ export function siteWideChangeThroughSdk(sdk) {
+    const batchOverSdk = (pending)=>({
+            set: (...args)=>{
+                pending.push(sdk().setDoc(...args));
+            },
+            update: (...args)=>{
+                pending.push(sdk().updateDoc(...args));
+            },
+            delete: (...args)=>{
+                pending.push(sdk().deleteDoc(...args));
+            }
+        });
+    return {
+        __esModule: true,
+        SITE_WIDE_OUTBOX_COLLECTION: 'publishOutbox',
+        SITE_WIDE_OUTBOX_PATHS: [
+            '/'
+        ],
+        writeSiteWideChange: async (options)=>{
+            const pending = [];
+            options.write(batchOverSdk(pending));
+            await Promise.all(pending);
+        },
+        commitWithSiteWideEntry: async (_hostId, commit)=>{
+            await commit(undefined);
+            return null;
+        },
+        settleSiteWideChange: ()=>undefined,
+        announceSiteWideChange: async ()=>null,
+        releaseSiteWideOutboxEntry: async ()=>undefined,
+        stageSiteWideOutboxEntry: ()=>null
+    };
+}
+
+//# sourceMappingURL=site-wide-change-double.js.map

package/src/lib/testing/site-wide-change-double.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/testing/site-wide-change-double.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 * A stand-in for `hooks/helpers/site-wide-change` in a card's spec (AGL-3386).\n *\n * A card that saves something a published page renders writes through\n * `writeSiteWideChange`, which batches the write with a publish outbox entry\n * and asks the console to drop the site's cache. A card's spec is about the\n * write the card makes, and it already doubles `firebase/firestore`'s\n * `setDoc`/`updateDoc`/`deleteDoc` to see it. This routes each staged batch\n * operation to the SAME double call the card made before it batched — so a\n * spec keeps asserting what reached storage, and says nothing about a cache\n * drop it is not testing. The helper's own contract is pinned in\n * `site-wide-change.spec.ts`.\n *\n * Use it as the factory of the module mock:\n *\n *     jest.mock('@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change', () =>\n *       jest\n *         .requireActual('@aglyn/tenant-feature-instance/testing/site-wide-change-double')\n *         .siteWideChangeThroughSdk(() => jest.requireMock('firebase/firestore')),\n *     )\n *\n * The SDK is handed in rather than required here: Jest injects `jest` into\n * each spec module rather than onto `globalThis`, so this file cannot reach\n * the spec's mock itself.\n */\n\ntype SdkCall = (...args: unknown[]) => Promise<unknown>\n\ninterface SdkWrites {\n  setDoc: SdkCall\n  updateDoc: SdkCall\n  deleteDoc: SdkCall\n}\n\n/** The module's exports, with every write sent to the doubled SDK calls. */\nexport function siteWideChangeThroughSdk(sdk: () => SdkWrites) {\n  const batchOverSdk = (pending: Promise<unknown>[]) => ({\n    set: (...args: unknown[]) => {\n      pending.push(sdk().setDoc(...args))\n    },\n    update: (...args: unknown[]) => {\n      pending.push(sdk().updateDoc(...args))\n    },\n    delete: (...args: unknown[]) => {\n      pending.push(sdk().deleteDoc(...args))\n    },\n  })\n  return {\n    __esModule: true,\n    SITE_WIDE_OUTBOX_COLLECTION: 'publishOutbox',\n    SITE_WIDE_OUTBOX_PATHS: ['/'],\n    writeSiteWideChange: async (options: {\n      write: (batch: ReturnType<typeof batchOverSdk>) => void\n    }) => {\n      const pending: Promise<unknown>[] = []\n      options.write(batchOverSdk(pending))\n      await Promise.all(pending)\n    },\n    commitWithSiteWideEntry: async (\n      _hostId: string,\n      commit: (stage: undefined) => Promise<void>,\n    ) => {\n      await commit(undefined)\n      return null\n    },\n    settleSiteWideChange: () => undefined,\n    announceSiteWideChange: async () => null,\n    releaseSiteWideOutboxEntry: async () => undefined,\n    stageSiteWideOutboxEntry: () => null,\n  }\n}\n"],"names":["siteWideChangeThroughSdk","sdk","batchOverSdk","pending","set","args","push","setDoc","update","updateDoc","delete","deleteDoc","__esModule","SITE_WIDE_OUTBOX_COLLECTION","SITE_WIDE_OUTBOX_PATHS","writeSiteWideChange","options","write","Promise","all","commitWithSiteWideEntry","_hostId","commit","undefined","settleSiteWideChange","announceSiteWideChange","releaseSiteWideOutboxEntry","stageSiteWideOutboxEntry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GAUD,0EAA0E,GAC1E,OAAO,SAASA,yBAAyBC,GAAoB;IAC3D,MAAMC,eAAe,CAACC,UAAiC,CAAA;YACrDC,KAAK,CAAC,GAAGC;gBACPF,QAAQG,IAAI,CAACL,MAAMM,MAAM,IAAIF;YAC/B;YACAG,QAAQ,CAAC,GAAGH;gBACVF,QAAQG,IAAI,CAACL,MAAMQ,SAAS,IAAIJ;YAClC;YACAK,QAAQ,CAAC,GAAGL;gBACVF,QAAQG,IAAI,CAACL,MAAMU,SAAS,IAAIN;YAClC;QACF,CAAA;IACA,OAAO;QACLO,YAAY;QACZC,6BAA6B;QAC7BC,wBAAwB;YAAC;SAAI;QAC7BC,qBAAqB,OAAOC;YAG1B,MAAMb,UAA8B,EAAE;YACtCa,QAAQC,KAAK,CAACf,aAAaC;YAC3B,MAAMe,QAAQC,GAAG,CAAChB;QACpB;QACAiB,yBAAyB,OACvBC,SACAC;YAEA,MAAMA,OAAOC;YACb,OAAO;QACT;QACAC,sBAAsB,IAAMD;QAC5BE,wBAAwB,UAAY;QACpCC,4BAA4B,UAAYH;QACxCI,0BAA0B,IAAM;IAClC;AACF"}