@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/dataset-live-pages.js

@@ -0,0 +1,421 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 dataset record write refreshes the live pages that show it (AGL-3113).
+ *
+ * ## What was missing
+ *
+ * Every other change a visitor can see announces itself the moment it lands: a
+ * publish, a layout, a component, a content entry, a redirect rule, the
+ * maintenance toggle. A dataset RECORD did not. It was written — by a form, by
+ * an automation, over `/v1`, from the console — and the pages repeating over
+ * it went on serving the rows they were built from until the hour-long window
+ * lapsed. `PUBLISHED_SITE_DATA_TTL_SECONDS` was the propagation mechanism,
+ * which is the same mistake AGL-1302 and AGL-1150 each had to undo elsewhere:
+ * a backstop doing a job nothing else was doing.
+ *
+ * ## Scope, not the site
+ *
+ * A record changed one dataset, so this drops the pages that repeat over that
+ * dataset and nothing else. The set is derived from the SAME binding the
+ * published page expands — `repeatDatasetKeys`, the generic
+ * `props.repeatDataset` any node can now carry (AGL-3111) — rather than from a
+ * list of components that may repeat. A component allowlist was already wrong
+ * the day repeat stopped being the Stack's: a heading bound to a dataset
+ * renders rows exactly as a Stack does, and would have been missed.
+ *
+ * Three corpora, because the composer reads repeat keys after the layout chain
+ * and the reusable-component graft: a repeat in a layout's chrome or inside a
+ * component reaches every screen that renders it.
+ *
+ * ## Which sites
+ *
+ * Datasets are ORG-scoped and shared with sites through `visibleTo` — every
+ * site in the org, or up to `MAX_SCOPE_HOSTS` named ones. Each site caches its
+ * own copy of the rows under its own `tenant-data:{hostId}` tag and its own
+ * page keys, so one record write is a fan-out. A missing `visibleTo` is
+ * visible to NOBODY and announces nothing; defaulting it to org-wide here
+ * would re-make AGL-1466 in the cache layer.
+ *
+ * ## Best effort, always
+ *
+ * The record is already written by the time any of this runs. A refused or
+ * failed drop is reported to the caller and logged, never thrown: a record
+ * must not be lost because a cache refused, and the TTL is still underneath as
+ * the backstop it was always meant to be.
+ */ import { ORG_SCOPE_TOKEN, hostIdsFromScope, repeatDatasetKeys, screenRoutePathToUrl } from "@aglyn/aglyn/server";
+import { readUsageSources, screenIdsUsingComponentDeep, screenIdsUsingLayoutDeep, isLiveUsageCandidate } from "./live-page-usage.js";
+/**
+ * How many documents per collection the per-site scan reads.
+ *
+ * The console's publish scan uses the same number for the same reason
+ * (AGL-1161): this decides which caches get dropped, so a prefix scan would
+ * report a refreshed site and leave real pages serving the old rows. Bounded
+ * all the same, and when the bound bites it is SAID rather than absorbed.
+ */ export const DATASET_SCAN_LIMIT = 2000;
+/**
+ * How many sites one record write fans out to.
+ *
+ * `MAX_SCOPE_HOSTS` is the ceiling on a NAMED selection, so only an org-wide
+ * dataset can reach this — an org with more sites than this pays a scan per
+ * site on every write otherwise, which is a cost the person writing one row
+ * did not ask for. Sites past the cap keep the TTL they had before this
+ * existed, and the shortfall is returned and logged rather than swallowed.
+ */ export const MAX_DATASET_FANOUT_HOSTS = 30;
+/**
+ * How long one site-and-dataset pair waits before announcing again.
+ *
+ * A 1,000-row import is one announce because the importer announces after its
+ * loop, not per row. This covers the other burst — many small writes arriving
+ * separately, a form under load or an automation fanning out — where each one
+ * would otherwise pay a full scan per site and hand the tenant the same path
+ * list again.
+ *
+ * Leading edge, so the FIRST write of a burst refreshes immediately; what is
+ * skipped is a repeat inside the window, and the next write after it announces
+ * again. The cost of the skip is bounded by the window: a row written during
+ * one is visible no later than the next announce.
+ */ export const DATASET_ANNOUNCE_WINDOW_MS = 2000;
+/** Last announce per `orgId/datasetId/hostId`, for the window above. */ const lastAnnouncedAt = new Map();
+/**
+ * Bounded so a long-lived server cannot grow this map without limit. Far above
+ * the number of datasets any one instance writes in a window; when it bites,
+ * the oldest entries simply lose their throttle and announce again.
+ */ const MAX_THROTTLE_ENTRIES = 5000;
+function throttleAllows(key, now) {
+    const previous = lastAnnouncedAt.get(key);
+    if (previous !== undefined && now - previous < DATASET_ANNOUNCE_WINDOW_MS) {
+        return false;
+    }
+    if (lastAnnouncedAt.size >= MAX_THROTTLE_ENTRIES) lastAnnouncedAt.clear();
+    lastAnnouncedAt.set(key, now);
+    return true;
+}
+/** Test seam: the window is process-wide state, so a spec has to reset it. */ export function resetDatasetAnnounceThrottle() {
+    lastAnnouncedAt.clear();
+}
+/**
+ * Whether a node tree repeats over any of `keys`.
+ *
+ * Asks `repeatDatasetKeys` — literally the function the tenant composer calls
+ * to decide which datasets to load for a page — so this cannot come to
+ * disagree with what actually renders. A predicate even slightly narrower than
+ * the expansion's is a page that renders rows and never refreshes them.
+ */ function nodesRepeatDataset(nodes, keys) {
+    return repeatDatasetKeys(nodes).some((key)=>keys.has(key));
+}
+/**
+ * Every live screen whose rendered output repeats over the dataset, however
+ * indirectly.
+ *
+ * The same three-bucket closure a placed form's pages are found by, for the
+ * same reason: a binding is found by SEARCHING node trees rather than by
+ * matching a pointer, so it can sit on the screen, in the chrome of the layout
+ * the screen renders inside, or inside a reusable component a third component
+ * nests. After the first level the fan-out is identical, so it is delegated
+ * rather than restated.
+ *
+ * Pure, and separate from the Firestore read, so the closure is testable
+ * without a database.
+ */ export function screenIdsRepeatingDataset(keys, sources) {
+    if (!keys.size) return [];
+    const screenIds = new Set();
+    for (const candidate of sources.screens){
+        if (!isLiveUsageCandidate(candidate)) continue;
+        if (nodesRepeatDataset(candidate.nodes, keys)) screenIds.add(candidate.id);
+    }
+    for (const candidate of sources.layouts){
+        if (!isLiveUsageCandidate(candidate)) continue;
+        if (!nodesRepeatDataset(candidate.nodes, keys)) continue;
+        // The layout itself renders no URL; the screens beneath it do.
+        for (const screenId of screenIdsUsingLayoutDeep(candidate.id, sources.screens, sources.layouts)){
+            screenIds.add(screenId);
+        }
+    }
+    for (const candidate of sources.components){
+        if (!isLiveUsageCandidate(candidate)) continue;
+        if (!nodesRepeatDataset(candidate.nodes, keys)) continue;
+        // And a component renders wherever it is placed, however deeply nested.
+        for (const screenId of screenIdsUsingComponentDeep(candidate.id, sources)){
+            screenIds.add(screenId);
+        }
+    }
+    return [
+        ...screenIds
+    ];
+}
+/**
+ * The keys a page can be bound to this dataset by: its id, and the display
+ * name editors type into the Repeat attribute.
+ *
+ * Both, because the expansion looks a key up either way (`getDatasets`
+ * resolves an id first and then a display name). Matching only the id would
+ * miss every binding written by name, which is the older and still-supported
+ * half of them.
+ */ function datasetKeysOf(snapshot) {
+    var _snapshot_get;
+    const keys = new Set([
+        snapshot.id
+    ]);
+    const displayName = String((_snapshot_get = snapshot.get('displayName')) != null ? _snapshot_get : '').trim();
+    if (displayName) keys.add(displayName);
+    return keys;
+}
+/**
+ * The sites a dataset is shared with, as host ids.
+ *
+ * Fails CLOSED on a missing or empty `visibleTo`, matching `visibleToHost` and
+ * both enforcement layers underneath it: a document nobody scoped is shared
+ * with nobody, and reading it as org-wide here would announce one org's
+ * dataset change to sites that cannot see the dataset at all.
+ */ async function hostIdsSharingDataset(firestore, orgId, visibleTo) {
+    if (!Array.isArray(visibleTo) || !visibleTo.length) {
+        return {
+            hostIds: [],
+            hostsDropped: 0
+        };
+    }
+    if (!visibleTo.includes(ORG_SCOPE_TOKEN)) {
+        const named = hostIdsFromScope(visibleTo);
+        return {
+            hostIds: named,
+            hostsDropped: 0
+        };
+    }
+    // One over the cap, so a shortfall is detected rather than assumed away.
+    const hosts = await firestore.collection('hosts').where('orgId', '==', orgId).limit(MAX_DATASET_FANOUT_HOSTS + 1).get();
+    const all = hosts.docs.map((doc)=>doc.id);
+    return {
+        hostIds: all.slice(0, MAX_DATASET_FANOUT_HOSTS),
+        hostsDropped: Math.max(0, all.length - MAX_DATASET_FANOUT_HOSTS)
+    };
+}
+/** One site's paths, or `null` when the site has nothing to refresh. */ async function targetForHost(firestore, hostId, keys) {
+    var _hostSnapshot_get, _hostSnapshot_get1, _hostSnapshot_get2;
+    const hostRef = firestore.collection('hosts').doc(hostId);
+    const hostSnapshot = await hostRef.get();
+    if (!hostSnapshot.exists) return null;
+    const subdomain = String((_hostSnapshot_get = hostSnapshot.get('subdomain')) != null ? _hostSnapshot_get : '');
+    // Without a subdomain there is no tenant deployment holding cached pages for
+    // this site — the ordinary state of one not yet given a name, not a failure.
+    if (!subdomain) return null;
+    const sources = await readUsageSources(hostRef, DATASET_SCAN_LIMIT);
+    const screens = (_hostSnapshot_get1 = hostSnapshot.get('screens')) != null ? _hostSnapshot_get1 : {};
+    const paths = screenIdsRepeatingDataset(keys, sources.candidates).map((screenId)=>screens[screenId]).filter((path)=>Boolean(path)).map((path)=>screenRoutePathToUrl(path)).filter((path, index, all)=>all.indexOf(path) === index);
+    if (!paths.length) return null;
+    const cname = String((_hostSnapshot_get2 = hostSnapshot.get('cname')) != null ? _hostSnapshot_get2 : '');
+    return _extends({
+        hostId,
+        subdomain
+    }, cname ? {
+        cname
+    } : {}, {
+        paths,
+        truncated: sources.truncated
+    });
+}
+/**
+ * Every live page a change to this dataset's records makes stale, per site.
+ *
+ * Reads only; announcing is the caller's, because the two runtimes announce
+ * differently — the console posts to the tenant over the shared secret, and
+ * the tenant drops its own caches in process. Splitting it here is what lets
+ * both use one answer to the question of WHICH pages.
+ *
+ * Never throws. A scope that could not be computed is a scope of nothing, and
+ * the TTL underneath is unaffected.
+ */ export async function datasetLivePageScope(options) {
+    const { firestore, orgId, datasetId } = options;
+    if (!orgId || !datasetId) {
+        return {
+            targets: [],
+            hostsDropped: 0,
+            reason: 'no-dataset'
+        };
+    }
+    try {
+        const snapshot = await firestore.collection('orgs').doc(orgId).collection('datasets').doc(datasetId).get();
+        if (!snapshot.exists) {
+            return {
+                targets: [],
+                hostsDropped: 0,
+                reason: 'no-dataset'
+            };
+        }
+        const { hostIds, hostsDropped } = await hostIdsSharingDataset(firestore, orgId, snapshot.get('visibleTo'));
+        if (!hostIds.length) {
+            return {
+                targets: [],
+                hostsDropped,
+                reason: 'no-sites'
+            };
+        }
+        const keys = datasetKeysOf(snapshot);
+        const resolved = await Promise.all(hostIds.map(async (hostId)=>{
+            try {
+                return await targetForHost(firestore, hostId, keys);
+            } catch (error) {
+                // One unreadable site must not cost the others their refresh.
+                console.error('[dataset-live-pages] site scan failed', hostId, error);
+                return null;
+            }
+        }));
+        const targets = resolved.filter((target)=>target !== null);
+        return {
+            targets,
+            hostsDropped,
+            reason: targets.length ? 'ok' : 'not-rendered'
+        };
+    } catch (error) {
+        console.error('[dataset-live-pages] scope failed', datasetId, error);
+        return {
+            targets: [],
+            hostsDropped: 0,
+            reason: 'error'
+        };
+    }
+}
+let registeredDropper;
+/**
+ * Registers the dropper for this process, replacing any previous one. Returns
+ * the unregister, which removes it only if it is still the one registered.
+ *
+ * Called from a function the platform calls BY NAME at boot, never from a
+ * module's top level: a bundler deletes a module imported only for its side
+ * effect when its package says it has none (AGL-3025).
+ */ export function registerLivePageDropper(drop) {
+    registeredDropper = drop;
+    return ()=>{
+        if (registeredDropper === drop) registeredDropper = undefined;
+    };
+}
+const EMPTY_RESULT = {
+    sitesRefreshed: 0,
+    pathsRefreshed: 0,
+    sitesRefused: 0,
+    hostsDropped: 0,
+    scanTruncated: false
+};
+/**
+ * Refresh every live page that shows this dataset's records.
+ *
+ * The one call a write path makes. BEST EFFORT, ALWAYS: it never throws and
+ * never rejects, so a caller can `await` it inside the try that already guards
+ * the write without any chance of turning a stored record into a failed one.
+ *
+ * `drop` overrides the registered dropper for callers that hold their own —
+ * the console, whose announce is an authenticated request rather than a local
+ * cache call.
+ */ export async function announceDatasetRecordChange(options) {
+    var _options_drop;
+    const { firestore, orgId, datasetId } = options;
+    const drop = (_options_drop = options.drop) != null ? _options_drop : registeredDropper;
+    if (!drop) {
+        // Said out loud: a process that writes records and registered no dropper
+        // is one where this feature is silently absent, which reads exactly like
+        // a working one until somebody watches a page fail to change.
+        console.warn(JSON.stringify({
+            tag: 'AGL-3113:no-live-page-dropper',
+            orgId,
+            datasetId
+        }));
+        return _extends({}, EMPTY_RESULT, {
+            reason: 'no-dropper'
+        });
+    }
+    const throttleKey = `${orgId}/${datasetId}`;
+    if (!throttleAllows(throttleKey, Date.now())) {
+        return _extends({}, EMPTY_RESULT, {
+            reason: 'throttled'
+        });
+    }
+    const scope = await datasetLivePageScope({
+        firestore,
+        orgId,
+        datasetId
+    });
+    if (!scope.targets.length) {
+        return _extends({}, EMPTY_RESULT, {
+            hostsDropped: scope.hostsDropped,
+            reason: scope.reason
+        });
+    }
+    let sitesRefreshed = 0;
+    let sitesRefused = 0;
+    let pathsRefreshed = 0;
+    for (const target of scope.targets){
+        let landed = false;
+        try {
+            landed = await drop(target);
+        } catch (error) {
+            // A dropper that throws is a dropper that failed; it is not a write
+            // that failed.
+            console.error('[dataset-live-pages] drop failed', target.hostId, error);
+        }
+        if (landed) {
+            sitesRefreshed += 1;
+            pathsRefreshed += target.paths.length;
+        } else {
+            sitesRefused += 1;
+        }
+    }
+    const scanTruncated = scope.targets.some((target)=>target.truncated);
+    const result = {
+        sitesRefreshed,
+        pathsRefreshed,
+        sitesRefused,
+        hostsDropped: scope.hostsDropped,
+        scanTruncated,
+        reason: scope.reason
+    };
+    // ONE line per announce, on success as well as failure, for the reason
+    // `postTenantRevalidate` gives: a record that only logs its failures cannot
+    // tell "every write refreshed" apart from "the call never happened", and
+    // that ambiguity is how an eleven-day propagation outage went unnoticed.
+    console.log(JSON.stringify(_extends({
+        tag: 'AGL-3113:dataset-announce',
+        orgId,
+        datasetId
+    }, result)));
+    return result;
+}
+/**
+ * One sentence for a refresh that did not cover every page, or `null` when it
+ * did.
+ *
+ * Beside the call rather than at each surface, so the console cannot word this
+ * differently in two places — the same reason `describeRevalidateShortfall`
+ * lives beside `revalidateLivePages`. `lead` names the act that succeeded,
+ * because only that word differs between surfaces: a record is SAVED, and
+ * telling someone who fixed a typo that they published it is a worse error
+ * than the staleness the sentence is about.
+ */ export function describeDatasetAnnounceShortfall(result, lead = 'Saved.') {
+    if (!result) return null;
+    // `not-rendered`, `no-sites` and `throttled` are deliberately silent: a
+    // dataset no page shows has no stale page, and a throttled drop means one
+    // already went out a moment ago. Saying anything would be alarming and wrong.
+    if (result.reason === 'error' || result.sitesRefused) {
+        return `${lead} The live pages could not be refreshed just now, so they ` + 'may show the previous records for up to an hour.';
+    }
+    if (result.hostsDropped || result.scanTruncated) {
+        return `${lead} Some pages that use this dataset are too many to refresh at ` + 'once — they update on their own within an hour.';
+    }
+    return null;
+}
+export default announceDatasetRecordChange;
+
+//# sourceMappingURL=dataset-live-pages.js.map

package/src/lib/server/dataset-live-pages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dataset-live-pages.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 dataset record write refreshes the live pages that show it (AGL-3113).\n *\n * ## What was missing\n *\n * Every other change a visitor can see announces itself the moment it lands: a\n * publish, a layout, a component, a content entry, a redirect rule, the\n * maintenance toggle. A dataset RECORD did not. It was written — by a form, by\n * an automation, over `/v1`, from the console — and the pages repeating over\n * it went on serving the rows they were built from until the hour-long window\n * lapsed. `PUBLISHED_SITE_DATA_TTL_SECONDS` was the propagation mechanism,\n * which is the same mistake AGL-1302 and AGL-1150 each had to undo elsewhere:\n * a backstop doing a job nothing else was doing.\n *\n * ## Scope, not the site\n *\n * A record changed one dataset, so this drops the pages that repeat over that\n * dataset and nothing else. The set is derived from the SAME binding the\n * published page expands — `repeatDatasetKeys`, the generic\n * `props.repeatDataset` any node can now carry (AGL-3111) — rather than from a\n * list of components that may repeat. A component allowlist was already wrong\n * the day repeat stopped being the Stack's: a heading bound to a dataset\n * renders rows exactly as a Stack does, and would have been missed.\n *\n * Three corpora, because the composer reads repeat keys after the layout chain\n * and the reusable-component graft: a repeat in a layout's chrome or inside a\n * component reaches every screen that renders it.\n *\n * ## Which sites\n *\n * Datasets are ORG-scoped and shared with sites through `visibleTo` — every\n * site in the org, or up to `MAX_SCOPE_HOSTS` named ones. Each site caches its\n * own copy of the rows under its own `tenant-data:{hostId}` tag and its own\n * page keys, so one record write is a fan-out. A missing `visibleTo` is\n * visible to NOBODY and announces nothing; defaulting it to org-wide here\n * would re-make AGL-1466 in the cache layer.\n *\n * ## Best effort, always\n *\n * The record is already written by the time any of this runs. A refused or\n * failed drop is reported to the caller and logged, never thrown: a record\n * must not be lost because a cache refused, and the TTL is still underneath as\n * the backstop it was always meant to be.\n */\n\nimport {\n  ORG_SCOPE_TOKEN,\n  hostIdsFromScope,\n  repeatDatasetKeys,\n  screenRoutePathToUrl,\n} from '@aglyn/aglyn/server'\nimport type { Firestore } from 'firebase-admin/firestore'\nimport {\n  readUsageSources,\n  screenIdsUsingComponentDeep,\n  screenIdsUsingLayoutDeep,\n  isLiveUsageCandidate,\n  type UsageCandidate,\n  type UsageSources,\n} from './live-page-usage'\n\n/**\n * How many documents per collection the per-site scan reads.\n *\n * The console's publish scan uses the same number for the same reason\n * (AGL-1161): this decides which caches get dropped, so a prefix scan would\n * report a refreshed site and leave real pages serving the old rows. Bounded\n * all the same, and when the bound bites it is SAID rather than absorbed.\n */\nexport const DATASET_SCAN_LIMIT = 2000\n\n/**\n * How many sites one record write fans out to.\n *\n * `MAX_SCOPE_HOSTS` is the ceiling on a NAMED selection, so only an org-wide\n * dataset can reach this — an org with more sites than this pays a scan per\n * site on every write otherwise, which is a cost the person writing one row\n * did not ask for. Sites past the cap keep the TTL they had before this\n * existed, and the shortfall is returned and logged rather than swallowed.\n */\nexport const MAX_DATASET_FANOUT_HOSTS = 30\n\n/**\n * How long one site-and-dataset pair waits before announcing again.\n *\n * A 1,000-row import is one announce because the importer announces after its\n * loop, not per row. This covers the other burst — many small writes arriving\n * separately, a form under load or an automation fanning out — where each one\n * would otherwise pay a full scan per site and hand the tenant the same path\n * list again.\n *\n * Leading edge, so the FIRST write of a burst refreshes immediately; what is\n * skipped is a repeat inside the window, and the next write after it announces\n * again. The cost of the skip is bounded by the window: a row written during\n * one is visible no later than the next announce.\n */\nexport const DATASET_ANNOUNCE_WINDOW_MS = 2000\n\n/** Last announce per `orgId/datasetId/hostId`, for the window above. */\nconst lastAnnouncedAt = new Map<string, number>()\n\n/**\n * Bounded so a long-lived server cannot grow this map without limit. Far above\n * the number of datasets any one instance writes in a window; when it bites,\n * the oldest entries simply lose their throttle and announce again.\n */\nconst MAX_THROTTLE_ENTRIES = 5000\n\nfunction throttleAllows(key: string, now: number): boolean {\n  const previous = lastAnnouncedAt.get(key)\n  if (previous !== undefined && now - previous < DATASET_ANNOUNCE_WINDOW_MS) {\n    return false\n  }\n  if (lastAnnouncedAt.size >= MAX_THROTTLE_ENTRIES) lastAnnouncedAt.clear()\n  lastAnnouncedAt.set(key, now)\n  return true\n}\n\n/** Test seam: the window is process-wide state, so a spec has to reset it. */\nexport function resetDatasetAnnounceThrottle(): void {\n  lastAnnouncedAt.clear()\n}\n\n/** One site's share of a dataset change. */\nexport interface DatasetLivePageTarget {\n  hostId: string\n  /** The tenant keys its cache on this, never on `hostId`. */\n  subdomain: string\n  /** The attached custom domain, whose pages live under a second cache key. */\n  cname?: string\n  /** Site-absolute addresses (`/`, `/team`) that repeat over the dataset. */\n  paths: string[]\n  /** The site held more documents than the scan read, so `paths` is partial. */\n  truncated: boolean\n}\n\nexport interface DatasetLivePageScope {\n  targets: DatasetLivePageTarget[]\n  /**\n   * Sites the fan-out cap left out. Zero in the ordinary case, and reported\n   * rather than logged because a caller that says \"refreshed\" while some sites\n   * were skipped is the failure this whole arc exists to remove.\n   */\n  hostsDropped: number\n  /**\n   * Why there is nothing to announce, or `'ok'`.\n   *\n   * `'not-rendered'` is a success: a dataset no page repeats over has no live\n   * page to refresh. It is kept apart from `'error'` for the same reason the\n   * revalidate route keeps `not-routed` apart from a refusal — one means there\n   * was nothing to do, the other means something was left stale.\n   */\n  reason: 'ok' | 'no-dataset' | 'no-sites' | 'not-rendered' | 'error'\n}\n\n/**\n * Whether a node tree repeats over any of `keys`.\n *\n * Asks `repeatDatasetKeys` — literally the function the tenant composer calls\n * to decide which datasets to load for a page — so this cannot come to\n * disagree with what actually renders. A predicate even slightly narrower than\n * the expansion's is a page that renders rows and never refreshes them.\n */\nfunction nodesRepeatDataset(\n  nodes: UsageCandidate['nodes'],\n  keys: ReadonlySet<string>,\n): boolean {\n  return repeatDatasetKeys(nodes).some((key) => keys.has(key))\n}\n\n/**\n * Every live screen whose rendered output repeats over the dataset, however\n * indirectly.\n *\n * The same three-bucket closure a placed form's pages are found by, for the\n * same reason: a binding is found by SEARCHING node trees rather than by\n * matching a pointer, so it can sit on the screen, in the chrome of the layout\n * the screen renders inside, or inside a reusable component a third component\n * nests. After the first level the fan-out is identical, so it is delegated\n * rather than restated.\n *\n * Pure, and separate from the Firestore read, so the closure is testable\n * without a database.\n */\nexport function screenIdsRepeatingDataset(\n  keys: ReadonlySet<string>,\n  sources: UsageSources,\n): string[] {\n  if (!keys.size) return []\n  const screenIds = new Set<string>()\n\n  for (const candidate of sources.screens) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (nodesRepeatDataset(candidate.nodes, keys)) screenIds.add(candidate.id)\n  }\n  for (const candidate of sources.layouts) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (!nodesRepeatDataset(candidate.nodes, keys)) continue\n    // The layout itself renders no URL; the screens beneath it do.\n    for (const screenId of screenIdsUsingLayoutDeep(\n      candidate.id,\n      sources.screens,\n      sources.layouts,\n    )) {\n      screenIds.add(screenId)\n    }\n  }\n  for (const candidate of sources.components) {\n    if (!isLiveUsageCandidate(candidate)) continue\n    if (!nodesRepeatDataset(candidate.nodes, keys)) continue\n    // And a component renders wherever it is placed, however deeply nested.\n    for (const screenId of screenIdsUsingComponentDeep(candidate.id, sources)) {\n      screenIds.add(screenId)\n    }\n  }\n\n  return [...screenIds]\n}\n\n/**\n * The keys a page can be bound to this dataset by: its id, and the display\n * name editors type into the Repeat attribute.\n *\n * Both, because the expansion looks a key up either way (`getDatasets`\n * resolves an id first and then a display name). Matching only the id would\n * miss every binding written by name, which is the older and still-supported\n * half of them.\n */\nfunction datasetKeysOf(\n  snapshot: FirebaseFirestore.DocumentSnapshot,\n): Set<string> {\n  const keys = new Set<string>([snapshot.id])\n  const displayName = String(snapshot.get('displayName') ?? '').trim()\n  if (displayName) keys.add(displayName)\n  return keys\n}\n\n/**\n * The sites a dataset is shared with, as host ids.\n *\n * Fails CLOSED on a missing or empty `visibleTo`, matching `visibleToHost` and\n * both enforcement layers underneath it: a document nobody scoped is shared\n * with nobody, and reading it as org-wide here would announce one org's\n * dataset change to sites that cannot see the dataset at all.\n */\nasync function hostIdsSharingDataset(\n  firestore: Firestore,\n  orgId: string,\n  visibleTo: readonly string[] | undefined,\n): Promise<{ hostIds: string[]; hostsDropped: number }> {\n  if (!Array.isArray(visibleTo) || !visibleTo.length) {\n    return { hostIds: [], hostsDropped: 0 }\n  }\n  if (!visibleTo.includes(ORG_SCOPE_TOKEN)) {\n    const named = hostIdsFromScope(visibleTo)\n    return { hostIds: named, hostsDropped: 0 }\n  }\n  // One over the cap, so a shortfall is detected rather than assumed away.\n  const hosts = await firestore\n    .collection('hosts')\n    .where('orgId', '==', orgId)\n    .limit(MAX_DATASET_FANOUT_HOSTS + 1)\n    .get()\n  const all = hosts.docs.map((doc) => doc.id)\n  return {\n    hostIds: all.slice(0, MAX_DATASET_FANOUT_HOSTS),\n    hostsDropped: Math.max(0, all.length - MAX_DATASET_FANOUT_HOSTS),\n  }\n}\n\n/** One site's paths, or `null` when the site has nothing to refresh. */\nasync function targetForHost(\n  firestore: Firestore,\n  hostId: string,\n  keys: ReadonlySet<string>,\n): Promise<DatasetLivePageTarget | null> {\n  const hostRef = firestore.collection('hosts').doc(hostId)\n  const hostSnapshot = await hostRef.get()\n  if (!hostSnapshot.exists) return null\n  const subdomain = String(hostSnapshot.get('subdomain') ?? '')\n  // Without a subdomain there is no tenant deployment holding cached pages for\n  // this site — the ordinary state of one not yet given a name, not a failure.\n  if (!subdomain) return null\n\n  const sources = await readUsageSources(hostRef, DATASET_SCAN_LIMIT)\n  const screens = (hostSnapshot.get('screens') ?? {}) as Record<string, string>\n  const paths = screenIdsRepeatingDataset(keys, sources.candidates)\n    .map((screenId) => screens[screenId])\n    .filter((path): path is string => Boolean(path))\n    .map((path) => screenRoutePathToUrl(path))\n    .filter((path, index, all) => all.indexOf(path) === index)\n  if (!paths.length) return null\n\n  const cname = String(hostSnapshot.get('cname') ?? '')\n  return {\n    hostId,\n    subdomain,\n    ...(cname ? { cname } : {}),\n    paths,\n    truncated: sources.truncated,\n  }\n}\n\n/**\n * Every live page a change to this dataset's records makes stale, per site.\n *\n * Reads only; announcing is the caller's, because the two runtimes announce\n * differently — the console posts to the tenant over the shared secret, and\n * the tenant drops its own caches in process. Splitting it here is what lets\n * both use one answer to the question of WHICH pages.\n *\n * Never throws. A scope that could not be computed is a scope of nothing, and\n * the TTL underneath is unaffected.\n */\nexport async function datasetLivePageScope(options: {\n  firestore: Firestore\n  orgId: string\n  datasetId: string\n}): Promise<DatasetLivePageScope> {\n  const { firestore, orgId, datasetId } = options\n  if (!orgId || !datasetId) {\n    return { targets: [], hostsDropped: 0, reason: 'no-dataset' }\n  }\n  try {\n    const snapshot = await firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('datasets')\n      .doc(datasetId)\n      .get()\n    if (!snapshot.exists) {\n      return { targets: [], hostsDropped: 0, reason: 'no-dataset' }\n    }\n    const { hostIds, hostsDropped } = await hostIdsSharingDataset(\n      firestore,\n      orgId,\n      snapshot.get('visibleTo') as readonly string[] | undefined,\n    )\n    if (!hostIds.length) {\n      return { targets: [], hostsDropped, reason: 'no-sites' }\n    }\n    const keys = datasetKeysOf(snapshot)\n    const resolved = await Promise.all(\n      hostIds.map(async (hostId) => {\n        try {\n          return await targetForHost(firestore, hostId, keys)\n        } catch (error) {\n          // One unreadable site must not cost the others their refresh.\n          console.error('[dataset-live-pages] site scan failed', hostId, error)\n          return null\n        }\n      }),\n    )\n    const targets = resolved.filter(\n      (target): target is DatasetLivePageTarget => target !== null,\n    )\n    return {\n      targets,\n      hostsDropped,\n      reason: targets.length ? 'ok' : 'not-rendered',\n    }\n  } catch (error) {\n    console.error('[dataset-live-pages] scope failed', datasetId, error)\n    return { targets: [], hostsDropped: 0, reason: 'error' }\n  }\n}\n\n/**\n * How one runtime drops a site's cached pages.\n *\n * The generic seam, registered by the deployment that owns the caches. The\n * tenant registers an in-process drop at boot; the console announces over the\n * shared secret and passes its own dropper at the call site. Core names\n * neither, exactly as it names no repeat source.\n *\n * Returns whether the drop landed. It must never throw: everything above it\n * has already been written.\n */\nexport type LivePageDropper = (\n  target: DatasetLivePageTarget,\n) => Promise<boolean>\n\nlet registeredDropper: LivePageDropper | undefined\n\n/**\n * Registers the dropper for this process, replacing any previous one. Returns\n * the unregister, which removes it only if it is still the one registered.\n *\n * Called from a function the platform calls BY NAME at boot, never from a\n * module's top level: a bundler deletes a module imported only for its side\n * effect when its package says it has none (AGL-3025).\n */\nexport function registerLivePageDropper(drop: LivePageDropper): () => void {\n  registeredDropper = drop\n  return () => {\n    if (registeredDropper === drop) registeredDropper = undefined\n  }\n}\n\nexport interface DatasetAnnounceResult {\n  /** Sites whose cached pages were dropped. */\n  sitesRefreshed: number\n  /** Pages named across those sites. */\n  pathsRefreshed: number\n  /** Sites the drop was attempted on and refused. */\n  sitesRefused: number\n  /** Sites past the fan-out cap, and sites whose scan was truncated. */\n  hostsDropped: number\n  scanTruncated: boolean\n  /** `'throttled'` when a drop for this pair already went out just now. */\n  reason: DatasetLivePageScope['reason'] | 'throttled' | 'no-dropper'\n}\n\nconst EMPTY_RESULT: Omit<DatasetAnnounceResult, 'reason'> = {\n  sitesRefreshed: 0,\n  pathsRefreshed: 0,\n  sitesRefused: 0,\n  hostsDropped: 0,\n  scanTruncated: false,\n}\n\n/**\n * Refresh every live page that shows this dataset's records.\n *\n * The one call a write path makes. BEST EFFORT, ALWAYS: it never throws and\n * never rejects, so a caller can `await` it inside the try that already guards\n * the write without any chance of turning a stored record into a failed one.\n *\n * `drop` overrides the registered dropper for callers that hold their own —\n * the console, whose announce is an authenticated request rather than a local\n * cache call.\n */\nexport async function announceDatasetRecordChange(options: {\n  firestore: Firestore\n  orgId: string\n  datasetId: string\n  drop?: LivePageDropper\n}): Promise<DatasetAnnounceResult> {\n  const { firestore, orgId, datasetId } = options\n  const drop = options.drop ?? registeredDropper\n  if (!drop) {\n    // Said out loud: a process that writes records and registered no dropper\n    // is one where this feature is silently absent, which reads exactly like\n    // a working one until somebody watches a page fail to change.\n    console.warn(\n      JSON.stringify({\n        tag: 'AGL-3113:no-live-page-dropper',\n        orgId,\n        datasetId,\n      }),\n    )\n    return { ...EMPTY_RESULT, reason: 'no-dropper' }\n  }\n  const throttleKey = `${orgId}/${datasetId}`\n  if (!throttleAllows(throttleKey, Date.now())) {\n    return { ...EMPTY_RESULT, reason: 'throttled' }\n  }\n  const scope = await datasetLivePageScope({ firestore, orgId, datasetId })\n  if (!scope.targets.length) {\n    return {\n      ...EMPTY_RESULT,\n      hostsDropped: scope.hostsDropped,\n      reason: scope.reason,\n    }\n  }\n\n  let sitesRefreshed = 0\n  let sitesRefused = 0\n  let pathsRefreshed = 0\n  for (const target of scope.targets) {\n    let landed = false\n    try {\n      landed = await drop(target)\n    } catch (error) {\n      // A dropper that throws is a dropper that failed; it is not a write\n      // that failed.\n      console.error('[dataset-live-pages] drop failed', target.hostId, error)\n    }\n    if (landed) {\n      sitesRefreshed += 1\n      pathsRefreshed += target.paths.length\n    } else {\n      sitesRefused += 1\n    }\n  }\n\n  const scanTruncated = scope.targets.some((target) => target.truncated)\n  const result: DatasetAnnounceResult = {\n    sitesRefreshed,\n    pathsRefreshed,\n    sitesRefused,\n    hostsDropped: scope.hostsDropped,\n    scanTruncated,\n    reason: scope.reason,\n  }\n  // ONE line per announce, on success as well as failure, for the reason\n  // `postTenantRevalidate` gives: a record that only logs its failures cannot\n  // tell \"every write refreshed\" apart from \"the call never happened\", and\n  // that ambiguity is how an eleven-day propagation outage went unnoticed.\n  console.log(\n    JSON.stringify({\n      tag: 'AGL-3113:dataset-announce',\n      orgId,\n      datasetId,\n      ...result,\n    }),\n  )\n  return result\n}\n\n/**\n * One sentence for a refresh that did not cover every page, or `null` when it\n * did.\n *\n * Beside the call rather than at each surface, so the console cannot word this\n * differently in two places — the same reason `describeRevalidateShortfall`\n * lives beside `revalidateLivePages`. `lead` names the act that succeeded,\n * because only that word differs between surfaces: a record is SAVED, and\n * telling someone who fixed a typo that they published it is a worse error\n * than the staleness the sentence is about.\n */\nexport function describeDatasetAnnounceShortfall(\n  result: DatasetAnnounceResult | null,\n  lead = 'Saved.',\n): string | null {\n  if (!result) return null\n  // `not-rendered`, `no-sites` and `throttled` are deliberately silent: a\n  // dataset no page shows has no stale page, and a throttled drop means one\n  // already went out a moment ago. Saying anything would be alarming and wrong.\n  if (result.reason === 'error' || result.sitesRefused) {\n    return (\n      `${lead} The live pages could not be refreshed just now, so they ` +\n      'may show the previous records for up to an hour.'\n    )\n  }\n  if (result.hostsDropped || result.scanTruncated) {\n    return (\n      `${lead} Some pages that use this dataset are too many to refresh at ` +\n      'once — they update on their own within an hour.'\n    )\n  }\n  return null\n}\n\nexport default announceDatasetRecordChange\n"],"names":["ORG_SCOPE_TOKEN","hostIdsFromScope","repeatDatasetKeys","screenRoutePathToUrl","readUsageSources","screenIdsUsingComponentDeep","screenIdsUsingLayoutDeep","isLiveUsageCandidate","DATASET_SCAN_LIMIT","MAX_DATASET_FANOUT_HOSTS","DATASET_ANNOUNCE_WINDOW_MS","lastAnnouncedAt","Map","MAX_THROTTLE_ENTRIES","throttleAllows","key","now","previous","get","undefined","size","clear","set","resetDatasetAnnounceThrottle","nodesRepeatDataset","nodes","keys","some","has","screenIdsRepeatingDataset","sources","screenIds","Set","candidate","screens","add","id","layouts","screenId","components","datasetKeysOf","snapshot","displayName","String","trim","hostIdsSharingDataset","firestore","orgId","visibleTo","Array","isArray","length","hostIds","hostsDropped","includes","named","hosts","collection","where","limit","all","docs","map","doc","slice","Math","max","targetForHost","hostId","hostSnapshot","hostRef","exists","subdomain","paths","candidates","filter","path","Boolean","index","indexOf","cname","truncated","datasetLivePageScope","options","datasetId","targets","reason","resolved","Promise","error","console","target","registeredDropper","registerLivePageDropper","drop","EMPTY_RESULT","sitesRefreshed","pathsRefreshed","sitesRefused","scanTruncated","announceDatasetRecordChange","warn","JSON","stringify","tag","throttleKey","Date","scope","landed","result","log","describeDatasetAnnounceShortfall","lead"],"mappings":"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"}

package/src/lib/server/dns-probe.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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.
+ */
+/** Resolvers asked before the runtime's own. */
+export declare const PUBLIC_DNS_RESOLVERS: string[];
+/** Whether a resolver error code is an answer rather than a failure to get one. */
+export declare function isConclusiveDnsCode(code: string | undefined): boolean;
+export interface DnsLookupResult<T> {
+    /**
+     * True when the lookup got an answer, including the answer "there is
+     * nothing here". False only when nobody answered.
+     */
+    answered: boolean;
+    /** Empty on a conclusive miss and on an unreachable lookup alike. */
+    records: T[];
+}
+/**
+ * TXT records at `host`, each joined from its chunks and trimmed.
+ *
+ * A TXT answer arrives as an array of string CHUNKS per record, because DNS
+ * splits strings longer than 255 bytes. Comparing without joining means a long
+ * value — every DKIM public key, for instance — can never match.
+ */
+export declare function lookupTxt(host: string): Promise<DnsLookupResult<string>>;
+/**
+ * CAA records at `host`, as `<flags> <tag> "<value>"` strings.
+ *
+ * NOT walked up the tree. The caller asks about one exact name, because the
+ * question this exists for is "does THIS name publish a policy of its own",
+ * and a walk would answer a different one — a parent's policy is inherited by
+ * resolution, not by publication, and reporting the parent's records as the
+ * child's would say a name restricts issuance when it publishes nothing.
+ */
+export declare function lookupCaa(host: string): Promise<DnsLookupResult<string>>;
+export interface MxRecord {
+    exchange: string;
+    priority: number;
+}
+/** MX records at `host`, exchanges lowercased and stripped of a trailing dot. */
+export declare function lookupMx(host: string): Promise<DnsLookupResult<MxRecord>>;