@aglyn/plugins-data 1.0.0-beta.220 → 1.0.0-beta.222

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

@@ -0,0 +1,436 @@
+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 — `repeatKeys`, 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.
+ *
+ * And the dataset's own record pages (AGL-3475): every page a record template
+ * on the site draws from it, by each record's address.
+ *
+ * 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.
+ *
+ * ## Which pages is the data plugin's; how a page is dropped is the runtime's
+ *
+ * Datasets are this plugin's, so the walk from a dataset to the pages that
+ * repeat over it is too. The drop itself is the platform's
+ * (`@aglyn/tenant-data-admin/server/live-page-drops`): the deployment that
+ * owns the caches registers its dropper there, and a caller holding its own —
+ * the console's — passes it here.
+ */ import { ORG_SCOPE_TOKEN, hostIdsFromScope, repeatKeys, screenRoutePathToUrl } from "@aglyn/aglyn/server";
+import { registeredLivePageDropper } from "@aglyn/tenant-data-admin/server/live-page-drops";
+import { readUsageSources, screenIdsUsingComponentDeep, screenIdsUsingLayoutDeep, isLiveUsageCandidate } from "@aglyn/tenant-data-admin/server/live-page-usage";
+/**
+ * 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 `repeatKeys` — 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 repeatKeys(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 (the data plugin's
+ * repeat rows resolve 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, datasetId) {
+    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, recordPages] = await Promise.all([
+        readUsageSources(hostRef, DATASET_SCAN_LIMIT),
+        // The dataset's own record pages (AGL-3475), which no routing-map entry
+        // names: a template draws them all from one screen.
+        // Loaded on first use, like every other read here: this module is on
+        // every record write's path, and the record pages read reaches the whole
+        // admin barrel.
+        import("../record-pages/record-page-live-paths.server.js").then((module)=>module.recordPagePathsForDataset(hostId, datasetId)).catch((error)=>{
+            console.error('[dataset-live-pages] record pages scan failed', hostId, error);
+            return {
+                paths: [],
+                truncated: false
+            };
+        })
+    ]);
+    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)),
+        ...recordPages.paths
+    ].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 || recordPages.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, snapshot.id);
+            } 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'
+        };
+    }
+}
+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 : registeredLivePageDropper();
+    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/plugins/data/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 — `repeatKeys`, 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 * And the dataset's own record pages (AGL-3475): every page a record template\n * on the site draws from it, by each record's address.\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 * ## Which pages is the data plugin's; how a page is dropped is the runtime's\n *\n * Datasets are this plugin's, so the walk from a dataset to the pages that\n * repeat over it is too. The drop itself is the platform's\n * (`@aglyn/tenant-data-admin/server/live-page-drops`): the deployment that\n * owns the caches registers its dropper there, and a caller holding its own —\n * the console's — passes it here.\n */\n\nimport {\n  ORG_SCOPE_TOKEN,\n  hostIdsFromScope,\n  repeatKeys,\n  screenRoutePathToUrl,\n} from '@aglyn/aglyn/server'\nimport type { Firestore } from 'firebase-admin/firestore'\nimport {\n  type LivePageDropper,\n  type LivePageTarget,\n  registeredLivePageDropper,\n} from '@aglyn/tenant-data-admin/server/live-page-drops'\nimport {\n  readUsageSources,\n  screenIdsUsingComponentDeep,\n  screenIdsUsingLayoutDeep,\n  isLiveUsageCandidate,\n  type UsageCandidate,\n  type UsageSources,\n} from '@aglyn/tenant-data-admin/server/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\nexport interface DatasetLivePageScope {\n  targets: LivePageTarget[]\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 `repeatKeys` — 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 repeatKeys(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 (the data plugin's\n * repeat rows resolve 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  datasetId: string,\n): Promise<LivePageTarget | 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, recordPages] = await Promise.all([\n    readUsageSources(hostRef, DATASET_SCAN_LIMIT),\n    // The dataset's own record pages (AGL-3475), which no routing-map entry\n    // names: a template draws them all from one screen.\n    // Loaded on first use, like every other read here: this module is on\n    // every record write's path, and the record pages read reaches the whole\n    // admin barrel.\n    import('../record-pages/record-page-live-paths.server')\n      .then((module) => module.recordPagePathsForDataset(hostId, datasetId))\n      .catch((error: unknown) => {\n        console.error('[dataset-live-pages] record pages scan failed', hostId, error)\n        return { paths: [] as string[], truncated: false }\n      }),\n  ])\n  const screens = (hostSnapshot.get('screens') ?? {}) as Record<string, string>\n  const paths = [\n    ...screenIdsRepeatingDataset(keys, sources.candidates)\n      .map((screenId) => screens[screenId])\n      .filter((path): path is string => Boolean(path))\n      .map((path) => screenRoutePathToUrl(path)),\n    ...recordPages.paths,\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 || recordPages.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, snapshot.id)\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 LivePageTarget => 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\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 ?? registeredLivePageDropper()\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","repeatKeys","screenRoutePathToUrl","registeredLivePageDropper","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","datasetId","hostSnapshot","hostRef","exists","subdomain","recordPages","Promise","then","module","recordPagePathsForDataset","catch","error","console","paths","truncated","candidates","filter","path","Boolean","index","indexOf","cname","datasetLivePageScope","options","targets","reason","resolved","target","EMPTY_RESULT","sitesRefreshed","pathsRefreshed","sitesRefused","scanTruncated","announceDatasetRecordChange","drop","warn","JSON","stringify","tag","throttleKey","Date","scope","landed","result","log","describeDatasetAnnounceShortfall","lead"],"mappings":"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"}

package/src/lib/server/dataset-steps.server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 { ServerStepAnswer, ServerStepRequest } from '@aglyn/aglyn/plugin-manager/plugin-server-steps';
+import type { DATASET_STEP_TYPES } from '../constants/bundle-common';
+/**
+ * THE TWO AUTOMATION STEPS THAT WRITE A DATASET RECORD (AGL-257, AGL-556,
+ * AGL-2773), run for the automation engine through the platform's server-step
+ * seam (`plugin-server-steps`, AGL-3080).
+ *
+ * `datasetAppend` adds a record; `updateDataset` merges into the record whose
+ * `email` field equals the event's email and appends when none does. Both read
+ * the event's fields that match a field of the dataset, held to its model.
+ *
+ * The engine runs the step's guard and keeps the run's history; this answers
+ * what the step did. A refusal is ANSWERED as `error`, never thrown, and its
+ * words are the line the run history carries — the same words the engine
+ * wrote when these steps were its own.
+ */
+export type DatasetStepType = (typeof DATASET_STEP_TYPES)[number];
+/**
+ * A dataset step as it is stored: the dataset by id (AGL-261, rename-safe),
+ * with its name kept as a display hint — and the name alone on a step from
+ * before ids, which the lookup resolves either way.
+ */
+export interface DatasetStep {
+    type: DatasetStepType;
+    datasetId?: string;
+    datasetName?: string;
+}
+/** Runs one dataset step for the automation engine. */
+export declare function runDatasetStep(request: ServerStepRequest): Promise<ServerStepAnswer>;