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

package/src/lib/server/live-page-usage.js

@@ -0,0 +1,300 @@
+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.
+ */ /**
+ * Which live pages a change reaches, for a site's screens, layouts and
+ * components.
+ *
+ * The corpus read and the two closures over it, held here rather than in the
+ * console because the console is no longer the only side that needs them. A
+ * dataset record is written from the tenant as well — a form submission, an
+ * automation step — and those writes make the same pages stale as a console
+ * edit does. Two implementations of "which screens render this" is the shape
+ * that put AGL-1223 in the tree: one reader handled a node tree's second
+ * storage form and the other did not, so half the corpus answered "used
+ * nowhere" and a publish dropped no cache.
+ *
+ * Nothing here is dataset-specific, and nothing is console-specific. The
+ * console's `scan-artifact-usage` re-exports these and keeps the parts that
+ * are about the console's own "what would I break" copy.
+ */ import { nodesReferenceComponent, decodeStoredNodes } from "@aglyn/aglyn/server";
+/** `displayName`, falling back to a legacy `name`, then the raw id. */ export function usageCandidateLabel(candidate) {
+    var _ref, _candidate_displayName;
+    return String((_ref = (_candidate_displayName = candidate.displayName) != null ? _candidate_displayName : candidate.name) != null ? _ref : candidate.id);
+}
+/** A soft-deleted document renders nothing, so it depends on nothing. */ export const isLiveUsageCandidate = (candidate)=>!candidate.deletedAt;
+/**
+ * Everything that references a reusable component (AGL-703).
+ *
+ * Three places, because the renderer expands instances in three places:
+ * published screen versions, published layout versions, and OTHER component
+ * definitions — `composeReusableComponentNodes` grafts nested instances, so
+ * a component used only inside another component is genuinely used. Omitting
+ * that third scan would report "used nowhere" for it and invite a confident
+ * deletion, which is worse than showing nothing at all.
+ */ export function scanComponentUsage(componentId, sources) {
+    if (!componentId) return [];
+    const dependents = [];
+    const collect = (candidates, type)=>{
+        for (const candidate of candidates){
+            if (!isLiveUsageCandidate(candidate)) continue;
+            // A component never counts as using itself, however it nests.
+            if (type === 'component' && candidate.id === componentId) continue;
+            if (!nodesReferenceComponent(candidate.nodes, componentId)) continue;
+            dependents.push(_extends({
+                type,
+                id: candidate.id,
+                name: usageCandidateLabel(candidate),
+                // Instances reference by id, so a rename can never break them.
+                via: [
+                    'id'
+                ]
+            }, candidate.versionId ? {
+                versionId: candidate.versionId
+            } : {}));
+        }
+    };
+    collect(sources.screens, 'screen');
+    collect(sources.layouts, 'layout');
+    collect(sources.components, 'component');
+    return dependents;
+}
+/**
+ * Everything rendering inside a layout (AGL-703).
+ *
+ * Two kinds of dependent, both expressed by the same `layoutId` pointer:
+ *
+ * - **screens**, which name the layout they render inside;
+ * - **other layouts**, since a layout can itself sit inside one. A nested
+ *   layout is a real dependent — deleting its parent unwraps every screen
+ *   underneath it — so leaving layouts out would report a parent layout as
+ *   used only by the screens that name it directly, and none of the ones
+ *   that reach it through a child.
+ *
+ * A layout never counts as its own dependent; `canNestLayout` refuses that,
+ * and this refuses to report it even if stored data holds one.
+ */ export function scanLayoutUsage(layoutId, screens, layouts = []) {
+    if (!layoutId) return [];
+    const dependentsOf = (candidates, type)=>candidates.filter((candidate)=>isLiveUsageCandidate(candidate) && candidate.layoutId === layoutId && candidate.id !== layoutId).map((candidate)=>_extends({
+                type,
+                id: candidate.id,
+                name: usageCandidateLabel(candidate),
+                via: [
+                    'id'
+                ]
+            }, candidate.versionId ? {
+                versionId: candidate.versionId
+            } : {}));
+    return [
+        ...dependentsOf(screens, 'screen'),
+        ...dependentsOf(layouts, 'layout')
+    ];
+}
+/**
+ * Every live screen rendered inside `layoutId`, at ANY nesting depth
+ * (AGL-1150).
+ *
+ * `scanLayoutUsage` answers one level. Layouts nest — a screen points at a
+ * layout, which can point at a parent layout, and `compose-screen-nodes` walks
+ * that whole chain when composing a page. So publishing a layout changes every
+ * screen below it, not just the ones bound to it directly, and a cache drop
+ * that only handles the direct level leaves the rest showing stale chrome for
+ * the full revalidate window.
+ *
+ * Pure, and separate from the Firestore read, so the nesting behaviour is
+ * testable without a database.
+ *
+ * Cycle-safe. `canNestLayout` refuses to create a cycle, but a document written
+ * straight to Firestore is not bound by that, and a cycle here would hang a
+ * publish request rather than surface anything.
+ */ export function screenIdsUsingLayoutDeep(layoutId, screens, layouts = []) {
+    if (!layoutId) return [];
+    const screenIds = new Set();
+    const seenLayouts = new Set([
+        layoutId
+    ]);
+    let frontier = [
+        layoutId
+    ];
+    while(frontier.length){
+        const next = [];
+        for (const id of frontier){
+            for (const dependent of scanLayoutUsage(id, screens, layouts)){
+                if (dependent.type === 'screen') {
+                    screenIds.add(dependent.id);
+                } else if (!seenLayouts.has(dependent.id)) {
+                    seenLayouts.add(dependent.id);
+                    next.push(dependent.id);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return [
+        ...screenIds
+    ];
+}
+/**
+ * Every live screen whose rendered output contains `componentId`, however
+ * indirectly (AGL-1161).
+ *
+ * `scanComponentUsage` answers one level and returns three kinds of dependent.
+ * Only one of them is a screen, and the other two both reach screens by routes
+ * a single-level scan cannot see:
+ *
+ * - a **component** dependent nests the target inside itself, and that outer
+ *   component may itself only be used inside a third — so component→component
+ *   edges have to be followed to a fixed point;
+ * - a **layout** dependent puts the component in page chrome, which every
+ *   screen under that layout renders. Layouts nest, so that is
+ *   `screenIdsUsingLayoutDeep`, not a direct `layoutId` match.
+ *
+ * Miss either and a publish reports success while some pages keep serving the
+ * old component for the full revalidate window — the failure this whole arc
+ * exists to remove, and the one that is hardest to notice because the pages
+ * that ARE dropped update instantly.
+ *
+ * Pure, and separate from the Firestore read, so the closure is testable
+ * without a database — the same split `screenIdsUsingLayoutDeep` uses.
+ *
+ * Cycle-safe. `composeReusableComponentNodes` would not survive a cycle, but a
+ * document written straight to Firestore is not bound by what the editor
+ * allows, and a cycle here would hang a publish rather than surface anything.
+ */ export function screenIdsUsingComponentDeep(componentId, sources) {
+    if (!componentId) return [];
+    const screenIds = new Set();
+    const seenComponents = new Set([
+        componentId
+    ]);
+    // Layouts are resolved through their own deep walk, so remember which ones
+    // have already been expanded: two components in the same layout would
+    // otherwise re-walk the whole layout tree once each.
+    const seenLayouts = new Set();
+    let frontier = [
+        componentId
+    ];
+    while(frontier.length){
+        const next = [];
+        for (const id of frontier){
+            for (const dependent of scanComponentUsage(id, sources)){
+                if (dependent.type === 'screen') {
+                    screenIds.add(dependent.id);
+                } else if (dependent.type === 'layout') {
+                    if (seenLayouts.has(dependent.id)) continue;
+                    seenLayouts.add(dependent.id);
+                    // The layout itself renders no URL; the screens beneath it do.
+                    for (const screenId of screenIdsUsingLayoutDeep(dependent.id, sources.screens, sources.layouts)){
+                        screenIds.add(screenId);
+                    }
+                } else if (!seenComponents.has(dependent.id)) {
+                    seenComponents.add(dependent.id);
+                    next.push(dependent.id);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return [
+        ...screenIds
+    ];
+}
+/**
+ * One collection's documents, with published nodes attached when the scan
+ * needs to search them.
+ *
+ * `limit` is a real bound, not a guess: it is fetched with one extra document
+ * so exceeding it is DETECTED rather than assumed away. A caller that ignores
+ * `truncated` is choosing to be wrong quietly.
+ */ export async function readUsageCandidates(hostRef, collectionName, options) {
+    const { withNodes, limit } = options;
+    // One over the limit: if the extra document comes back, there was more than
+    // we are about to look at. Cheaper than a count() and exact.
+    const docs = await hostRef.collection(collectionName).limit(limit + 1).get();
+    const truncated = docs.size > limit;
+    const inScope = truncated ? docs.docs.slice(0, limit) : docs.docs;
+    const candidates = await Promise.all(inScope.map(async (docSnapshot)=>{
+        const versionId = docSnapshot.get('versionId');
+        // Components keep their tree on the document; screens and layouts keep
+        // it on the published version.
+        //
+        // BOTH reads are decoded (AGL-1223). A component document is msgpack
+        // for anything promoted since components were compressed and a plain
+        // map for everything older, and `decodeStoredNodes` returns a map
+        // unchanged — so the branch below cannot be simplified back into a raw
+        // read on either side.
+        //
+        // What rides on this: every consumer walks the value with
+        // `Object.values`, which over a `Buffer` yields byte NUMBERS and
+        // matches nothing. The answer that produces is "used nowhere" — for
+        // `/api/hosts/where-used` an invitation to delete something a live page
+        // renders, and for `/api/screens/revalidate` a publish that drops no
+        // cache and leaves the old page served.
+        const nodes = collectionName === 'components' ? decodeStoredNodes(docSnapshot.get('nodes')) : withNodes && versionId ? await docSnapshot.ref.collection('versions').doc(String(versionId)).get().then((version)=>decodeStoredNodes(version.get('nodes'))).catch(()=>null) : null;
+        return _extends({
+            id: docSnapshot.id,
+            displayName: docSnapshot.get('displayName'),
+            name: docSnapshot.get('name'),
+            deletedAt: docSnapshot.get('deletedAt'),
+            nodes
+        }, versionId ? {
+            versionId: String(versionId)
+        } : {}, docSnapshot.get('layoutId') ? {
+            layoutId: String(docSnapshot.get('layoutId'))
+        } : {}, docSnapshot.get('parentId') ? {
+            parentId: String(docSnapshot.get('parentId'))
+        } : {}, collectionName === 'components' && Array.isArray(docSnapshot.get('props')) ? {
+            props: docSnapshot.get('props')
+        } : {});
+    }));
+    return {
+        candidates,
+        truncated
+    };
+}
+/**
+ * Every screen, layout and component of a site, with their node trees — the
+ * corpus every tree-searching closure above walks.
+ *
+ * Each collection ONCE, in memory: a query per level would multiply round
+ * trips by the nesting depth of the graph. Shared so two scans cannot read
+ * different corpora under different bounds, and a change to one cannot quietly
+ * narrow the other.
+ */ export async function readUsageSources(hostRef, limit) {
+    const [screens, layouts, components] = await Promise.all([
+        readUsageCandidates(hostRef, 'screens', {
+            withNodes: true,
+            limit
+        }),
+        readUsageCandidates(hostRef, 'layouts', {
+            withNodes: true,
+            limit
+        }),
+        readUsageCandidates(hostRef, 'components', {
+            withNodes: true,
+            limit
+        })
+    ]);
+    return {
+        candidates: {
+            screens: screens.candidates,
+            layouts: layouts.candidates,
+            components: components.candidates
+        },
+        truncated: screens.truncated || layouts.truncated || components.truncated
+    };
+}
+
+//# sourceMappingURL=live-page-usage.js.map

package/src/lib/server/live-page-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/live-page-usage.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 * Which live pages a change reaches, for a site's screens, layouts and\n * components.\n *\n * The corpus read and the two closures over it, held here rather than in the\n * console because the console is no longer the only side that needs them. A\n * dataset record is written from the tenant as well — a form submission, an\n * automation step — and those writes make the same pages stale as a console\n * edit does. Two implementations of \"which screens render this\" is the shape\n * that put AGL-1223 in the tree: one reader handled a node tree's second\n * storage form and the other did not, so half the corpus answered \"used\n * nowhere\" and a publish dropped no cache.\n *\n * Nothing here is dataset-specific, and nothing is console-specific. The\n * console's `scan-artifact-usage` re-exports these and keeps the parts that\n * are about the console's own \"what would I break\" copy.\n */\n\nimport {\n  nodesReferenceComponent,\n  decodeStoredNodes,\n  type ReusableComponentProp,\n} from '@aglyn/aglyn/server'\n\n/** A screen/layout/component reduced to what a usage scan needs. */\nexport interface UsageCandidate {\n  id: string\n  displayName?: string\n  /** Legacy field some older documents used instead of `displayName`. */\n  name?: string\n  deletedAt?: unknown\n  /**\n   * Node tree to search. For screens and layouts this is the PUBLISHED\n   * version's nodes (what visitors see); for components it is the definition\n   * tree off the component document, which is what the runtime reads.\n   */\n  nodes?: Record<string, any> | null\n  /** Published version, carried through so the caller can deep-link. */\n  versionId?: string\n  /** Screens only: the layout they render inside. */\n  layoutId?: string\n  /** Screens only: the screen they nest under, which is part of their path. */\n  parentId?: string\n  /**\n   * Components only: the properties the definition declares (AGL-1247). A\n   * Link property's default renders as a link wherever an instance leaves the\n   * property unset, and it is stored here, not in `nodes` (AGL-2846).\n   */\n  props?: ReadonlyArray<ReusableComponentProp | null | undefined> | null\n}\n\n/** One document that depends on the artifact a scan was asked about. */\nexport interface UsageDependent {\n  type: 'screen' | 'layout' | 'component' | 'collection'\n  id: string\n  name: string\n  via: Array<'id' | 'name'>\n  versionId?: string\n  /**\n   * HOW the dependent references the artifact — screens and collection\n   * listings (AGL-703, AGL-2806).\n   *\n   * A component or a layout has exactly one kind of dependent and the noun\n   * says everything: an instance, or a binding. A screen has three, and they\n   * break in three different ways — a link goes dead, a child moves, a\n   * collection loses the page it renders through. Copy that could not tell\n   * them apart would have to describe the worst case every time. A collection\n   * listing's dependents are all links, and say so.\n   */\n  relation?: 'link' | 'child' | 'template'\n}\n\n/** The three corpora every closure below walks. */\nexport interface UsageSources {\n  screens: UsageCandidate[]\n  layouts: UsageCandidate[]\n  components: UsageCandidate[]\n}\n\n/** `displayName`, falling back to a legacy `name`, then the raw id. */\nexport function usageCandidateLabel(candidate: UsageCandidate): string {\n  return String(candidate.displayName ?? candidate.name ?? candidate.id)\n}\n\n/** A soft-deleted document renders nothing, so it depends on nothing. */\nexport const isLiveUsageCandidate = (candidate: UsageCandidate): boolean =>\n  !candidate.deletedAt\n\n/**\n * Everything that references a reusable component (AGL-703).\n *\n * Three places, because the renderer expands instances in three places:\n * published screen versions, published layout versions, and OTHER component\n * definitions — `composeReusableComponentNodes` grafts nested instances, so\n * a component used only inside another component is genuinely used. Omitting\n * that third scan would report \"used nowhere\" for it and invite a confident\n * deletion, which is worse than showing nothing at all.\n */\nexport function scanComponentUsage(\n  componentId: string,\n  sources: UsageSources,\n): UsageDependent[] {\n  if (!componentId) return []\n  const dependents: UsageDependent[] = []\n  const collect = (\n    candidates: UsageCandidate[],\n    type: UsageDependent['type'],\n  ) => {\n    for (const candidate of candidates) {\n      if (!isLiveUsageCandidate(candidate)) continue\n      // A component never counts as using itself, however it nests.\n      if (type === 'component' && candidate.id === componentId) continue\n      if (!nodesReferenceComponent(candidate.nodes, componentId)) continue\n      dependents.push({\n        type,\n        id: candidate.id,\n        name: usageCandidateLabel(candidate),\n        // Instances reference by id, so a rename can never break them.\n        via: ['id'],\n        ...(candidate.versionId ? { versionId: candidate.versionId } : {}),\n      })\n    }\n  }\n  collect(sources.screens, 'screen')\n  collect(sources.layouts, 'layout')\n  collect(sources.components, 'component')\n  return dependents\n}\n\n/**\n * Everything rendering inside a layout (AGL-703).\n *\n * Two kinds of dependent, both expressed by the same `layoutId` pointer:\n *\n * - **screens**, which name the layout they render inside;\n * - **other layouts**, since a layout can itself sit inside one. A nested\n *   layout is a real dependent — deleting its parent unwraps every screen\n *   underneath it — so leaving layouts out would report a parent layout as\n *   used only by the screens that name it directly, and none of the ones\n *   that reach it through a child.\n *\n * A layout never counts as its own dependent; `canNestLayout` refuses that,\n * and this refuses to report it even if stored data holds one.\n */\nexport function scanLayoutUsage(\n  layoutId: string,\n  screens: UsageCandidate[],\n  layouts: UsageCandidate[] = [],\n): UsageDependent[] {\n  if (!layoutId) return []\n  const dependentsOf = (\n    candidates: UsageCandidate[],\n    type: 'screen' | 'layout',\n  ) =>\n    candidates\n      .filter(\n        (candidate) =>\n          isLiveUsageCandidate(candidate) &&\n          candidate.layoutId === layoutId &&\n          candidate.id !== layoutId,\n      )\n      .map((candidate) => ({\n        type,\n        id: candidate.id,\n        name: usageCandidateLabel(candidate),\n        via: ['id' as const],\n        ...(candidate.versionId ? { versionId: candidate.versionId } : {}),\n      }))\n  return [\n    ...dependentsOf(screens, 'screen'),\n    ...dependentsOf(layouts, 'layout'),\n  ]\n}\n\n/**\n * Every live screen rendered inside `layoutId`, at ANY nesting depth\n * (AGL-1150).\n *\n * `scanLayoutUsage` answers one level. Layouts nest — a screen points at a\n * layout, which can point at a parent layout, and `compose-screen-nodes` walks\n * that whole chain when composing a page. So publishing a layout changes every\n * screen below it, not just the ones bound to it directly, and a cache drop\n * that only handles the direct level leaves the rest showing stale chrome for\n * the full revalidate window.\n *\n * Pure, and separate from the Firestore read, so the nesting behaviour is\n * testable without a database.\n *\n * Cycle-safe. `canNestLayout` refuses to create a cycle, but a document written\n * straight to Firestore is not bound by that, and a cycle here would hang a\n * publish request rather than surface anything.\n */\nexport function screenIdsUsingLayoutDeep(\n  layoutId: string,\n  screens: UsageCandidate[],\n  layouts: UsageCandidate[] = [],\n): string[] {\n  if (!layoutId) return []\n  const screenIds = new Set<string>()\n  const seenLayouts = new Set<string>([layoutId])\n  let frontier = [layoutId]\n\n  while (frontier.length) {\n    const next: string[] = []\n    for (const id of frontier) {\n      for (const dependent of scanLayoutUsage(id, screens, layouts)) {\n        if (dependent.type === 'screen') {\n          screenIds.add(dependent.id)\n        } else if (!seenLayouts.has(dependent.id)) {\n          seenLayouts.add(dependent.id)\n          next.push(dependent.id)\n        }\n      }\n    }\n    frontier = next\n  }\n\n  return [...screenIds]\n}\n\n/**\n * Every live screen whose rendered output contains `componentId`, however\n * indirectly (AGL-1161).\n *\n * `scanComponentUsage` answers one level and returns three kinds of dependent.\n * Only one of them is a screen, and the other two both reach screens by routes\n * a single-level scan cannot see:\n *\n * - a **component** dependent nests the target inside itself, and that outer\n *   component may itself only be used inside a third — so component→component\n *   edges have to be followed to a fixed point;\n * - a **layout** dependent puts the component in page chrome, which every\n *   screen under that layout renders. Layouts nest, so that is\n *   `screenIdsUsingLayoutDeep`, not a direct `layoutId` match.\n *\n * Miss either and a publish reports success while some pages keep serving the\n * old component for the full revalidate window — the failure this whole arc\n * exists to remove, and the one that is hardest to notice because the pages\n * that ARE dropped update instantly.\n *\n * Pure, and separate from the Firestore read, so the closure is testable\n * without a database — the same split `screenIdsUsingLayoutDeep` uses.\n *\n * Cycle-safe. `composeReusableComponentNodes` would not survive a cycle, but a\n * document written straight to Firestore is not bound by what the editor\n * allows, and a cycle here would hang a publish rather than surface anything.\n */\nexport function screenIdsUsingComponentDeep(\n  componentId: string,\n  sources: UsageSources,\n): string[] {\n  if (!componentId) return []\n  const screenIds = new Set<string>()\n  const seenComponents = new Set<string>([componentId])\n  // Layouts are resolved through their own deep walk, so remember which ones\n  // have already been expanded: two components in the same layout would\n  // otherwise re-walk the whole layout tree once each.\n  const seenLayouts = new Set<string>()\n  let frontier = [componentId]\n\n  while (frontier.length) {\n    const next: string[] = []\n    for (const id of frontier) {\n      for (const dependent of scanComponentUsage(id, sources)) {\n        if (dependent.type === 'screen') {\n          screenIds.add(dependent.id)\n        } else if (dependent.type === 'layout') {\n          if (seenLayouts.has(dependent.id)) continue\n          seenLayouts.add(dependent.id)\n          // The layout itself renders no URL; the screens beneath it do.\n          for (const screenId of screenIdsUsingLayoutDeep(\n            dependent.id,\n            sources.screens,\n            sources.layouts,\n          )) {\n            screenIds.add(screenId)\n          }\n        } else if (!seenComponents.has(dependent.id)) {\n          seenComponents.add(dependent.id)\n          next.push(dependent.id)\n        }\n      }\n    }\n    frontier = next\n  }\n\n  return [...screenIds]\n}\n\nexport interface UsageCandidateRead {\n  candidates: UsageCandidate[]\n  /**\n   * The collection held more documents than `limit` allowed, so the scan below\n   * it is INCOMPLETE.\n   *\n   * Returned rather than logged, because the two callers owe the user\n   * different things: an advisory \"what would I break\" can show a partial\n   * answer and say so, while a cache drop that silently scans a prefix reports\n   * a successful publish and leaves real pages stale.\n   */\n  truncated: boolean\n}\n\n/**\n * One collection's documents, with published nodes attached when the scan\n * needs to search them.\n *\n * `limit` is a real bound, not a guess: it is fetched with one extra document\n * so exceeding it is DETECTED rather than assumed away. A caller that ignores\n * `truncated` is choosing to be wrong quietly.\n */\nexport async function readUsageCandidates(\n  hostRef: FirebaseFirestore.DocumentReference,\n  collectionName: 'screens' | 'layouts' | 'components',\n  options: { withNodes: boolean; limit: number },\n): Promise<UsageCandidateRead> {\n  const { withNodes, limit } = options\n  // One over the limit: if the extra document comes back, there was more than\n  // we are about to look at. Cheaper than a count() and exact.\n  const docs = await hostRef.collection(collectionName).limit(limit + 1).get()\n  const truncated = docs.size > limit\n  const inScope = truncated ? docs.docs.slice(0, limit) : docs.docs\n\n  const candidates = await Promise.all(\n    inScope.map(async (docSnapshot) => {\n      const versionId = docSnapshot.get('versionId')\n      // Components keep their tree on the document; screens and layouts keep\n      // it on the published version.\n      //\n      // BOTH reads are decoded (AGL-1223). A component document is msgpack\n      // for anything promoted since components were compressed and a plain\n      // map for everything older, and `decodeStoredNodes` returns a map\n      // unchanged — so the branch below cannot be simplified back into a raw\n      // read on either side.\n      //\n      // What rides on this: every consumer walks the value with\n      // `Object.values`, which over a `Buffer` yields byte NUMBERS and\n      // matches nothing. The answer that produces is \"used nowhere\" — for\n      // `/api/hosts/where-used` an invitation to delete something a live page\n      // renders, and for `/api/screens/revalidate` a publish that drops no\n      // cache and leaves the old page served.\n      const nodes =\n        collectionName === 'components'\n          ? decodeStoredNodes(docSnapshot.get('nodes'))\n          : withNodes && versionId\n            ? await docSnapshot.ref\n                .collection('versions')\n                .doc(String(versionId))\n                .get()\n                .then((version) => decodeStoredNodes(version.get('nodes')))\n                .catch(() => null)\n            : null\n      return {\n        id: docSnapshot.id,\n        displayName: docSnapshot.get('displayName'),\n        name: docSnapshot.get('name'),\n        deletedAt: docSnapshot.get('deletedAt'),\n        nodes,\n        ...(versionId ? { versionId: String(versionId) } : {}),\n        ...(docSnapshot.get('layoutId')\n          ? { layoutId: String(docSnapshot.get('layoutId')) }\n          : {}),\n        // Screens only, and only the screen scan reads it: a child screen is\n        // a dependent of its parent, because its PATH is built from it\n        // (AGL-703).\n        ...(docSnapshot.get('parentId')\n          ? { parentId: String(docSnapshot.get('parentId')) }\n          : {}),\n        // Components only: the declared properties, whose Link defaults render\n        // as links wherever an instance leaves one unset (AGL-2846). The same\n        // document the tree came from, so it costs no read.\n        ...(collectionName === 'components' &&\n        Array.isArray(docSnapshot.get('props'))\n          ? { props: docSnapshot.get('props') }\n          : {}),\n      } satisfies UsageCandidate\n    }),\n  )\n\n  return { candidates, truncated }\n}\n\n/**\n * Every screen, layout and component of a site, with their node trees — the\n * corpus every tree-searching closure above walks.\n *\n * Each collection ONCE, in memory: a query per level would multiply round\n * trips by the nesting depth of the graph. Shared so two scans cannot read\n * different corpora under different bounds, and a change to one cannot quietly\n * narrow the other.\n */\nexport async function readUsageSources(\n  hostRef: FirebaseFirestore.DocumentReference,\n  limit: number,\n): Promise<{ candidates: UsageSources; truncated: boolean }> {\n  const [screens, layouts, components] = await Promise.all([\n    readUsageCandidates(hostRef, 'screens', { withNodes: true, limit }),\n    readUsageCandidates(hostRef, 'layouts', { withNodes: true, limit }),\n    readUsageCandidates(hostRef, 'components', { withNodes: true, limit }),\n  ])\n  return {\n    candidates: {\n      screens: screens.candidates,\n      layouts: layouts.candidates,\n      components: components.candidates,\n    },\n    truncated: screens.truncated || layouts.truncated || components.truncated,\n  }\n}\n"],"names":["nodesReferenceComponent","decodeStoredNodes","usageCandidateLabel","candidate","String","displayName","name","id","isLiveUsageCandidate","deletedAt","scanComponentUsage","componentId","sources","dependents","collect","candidates","type","nodes","push","via","versionId","screens","layouts","components","scanLayoutUsage","layoutId","dependentsOf","filter","map","screenIdsUsingLayoutDeep","screenIds","Set","seenLayouts","frontier","length","next","dependent","add","has","screenIdsUsingComponentDeep","seenComponents","screenId","readUsageCandidates","hostRef","collectionName","options","withNodes","limit","docs","collection","get","truncated","size","inScope","slice","Promise","all","docSnapshot","ref","doc","then","version","catch","parentId","Array","isArray","props","readUsageSources"],"mappings":"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"}

package/src/lib/server/lockdown.d.ts

@@ -0,0 +1,313 @@
+/**
+ * @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.
+ */
+/**
+ * Server half of the lockdown system (AGL-1501): the verdict every
+ * enforcement chokepoint asks for. The pure shape/precedence logic lives in
+ * `@aglyn/aglyn` `app-utils/lockdown.ts`; this module adds the Admin-SDK
+ * reads and the two properties only the server can hold:
+ *
+ * **The un-panic invariant.** A verified `staff` claim bypasses EVERY scope,
+ * unconditionally, before any read happens. A platform-wide lockdown must
+ * never lock out the staff who can lift it — a panic button that panics its
+ * own operator is worse than none. Nothing may be added to
+ * `getLockdownVerdict` above the staff check.
+ *
+ * **Fail-open on infrastructure error.** If the `lockdowns/platform` read
+ * throws (Firestore outage, emulator without the collection), the verdict is
+ * "not locked": an infrastructure blip must not weld the whole platform
+ * shut. The same posture as the sanctions gate on an absent geo signal
+ * (AGL-1492) and the release-flag reader on a missing template.
+ *
+ * **…except for takedowns (AGL-1621).** One class of lock inverts that cost
+ * function: a legal or abuse takedown must keep holding when Firestore is
+ * unreachable, because "we served it, our database was down" answers no
+ * court order. The class is an EXPLICIT stored field (`enforcement`), never
+ * inferred from scope or reason, and absent means `standard` — so every
+ * lock that exists today, and every lock an operator does not classify,
+ * keeps failing open exactly as before. See the takedown ledger below for
+ * how a classification survives the read that loses it.
+ */
+import { type LockdownFeatureKey, type LockdownIntent, type LockdownNotice, type LockdownState, normalizeHostLockdown, normalizeOrgLockdown } from '@aglyn/aglyn/server';
+/**
+ * Bounded like the user and domain caches, and for the same reason: two of
+ * the four keyed readers take their key from caller-controlled input.
+ * Eviction is least-recently-USED.
+ */
+export declare const TAKEDOWN_LEDGER_MAX = 5000;
+/**
+ * Forget every remembered takedown. NOT part of the panic path and not
+ * called by the admin route — this exists for process-boundary and test
+ * setup, where a ledger surviving between cases would make one test's lock
+ * another test's fail-closed verdict.
+ */
+export declare function resetTakedownLedger(): void;
+/**
+ * Record what a SUCCESSFUL site read saw, per scope. Same contract as the
+ * four `lockdowns/*` readers: a takedown is remembered, and anything else —
+ * no lock, an ordinary lock, a takedown DOWNGRADED to one — retires the
+ * entry, which is how a lift takes effect.
+ */
+export declare function rememberSiteTakedown(hostId: string, states: {
+    org: LockdownState | null;
+    host: LockdownState | null;
+}): void;
+/**
+ * What a FAILED site read may still serve: the remembered, still-active
+ * takedowns at org and host scope, or nulls — which is the shipped fail-open
+ * answer and therefore the default for every lock that is not an observed
+ * takedown.
+ */
+export declare function heldSiteTakedown(hostId: string, nowMs: number): {
+    org: LockdownState | null;
+    host: LockdownState | null;
+};
+/**
+ * Drop the in-process platform cache. Called by /api/admin/lockdown after a
+ * platform write so the process that took the action serves fresh verdicts
+ * immediately; other processes converge within PLATFORM_TTL_MS.
+ */
+export declare function invalidatePlatformLockdownCache(): void;
+/** `lockdowns/platform`, normalized; null = not locked (incl. on error). */
+export declare function getPlatformLockdown(): Promise<LockdownState | null>;
+/** Drop the in-process feature cache (all keys) after an admin write. */
+export declare function invalidateFeatureLockdownCache(): void;
+/** `lockdowns/feature--{key}`, normalized; null = not locked (incl. error). */
+export declare function getFeatureLockdown(feature: LockdownFeatureKey): Promise<LockdownState | null>;
+/**
+ * `lockdowns/feature--{key}--org--{orgId}` (AGL-2927): the same capability
+ * paused for ONE workspace. Same cache, same TTL, same fail-open posture as
+ * the platform-wide document; null = not paused for that org.
+ */
+export declare function getOrgFeatureLockdown(feature: LockdownFeatureKey, orgId: string): Promise<LockdownState | null>;
+/**
+ * The feature verdict and refusal in one call (AGL-1510) — the one-line
+ * wiring a feature chokepoint carries:
+ *
+ *   const locked = await featureLockdownRefusal({ feature: 'checkout', staff })
+ *   if (locked) return locked
+ *
+ * Composition, not ranking: a PLATFORM lock implies every feature, so it is
+ * checked first (TTL-cached — routes that already ran the scope verdict pay
+ * no extra read), and the platform-scope staff bypass there is UNCHANGED
+ * and unconditional. The feature doc is checked second, and its staff
+ * bypass is per-feature (`lockdownFeatureStaffBypass`): granted where a
+ * staff action aids incident response (uploads, installs, ai-assist),
+ * withheld where it would BE the incident (checkout — a staff checkout
+ * session is still a real charge). A feature lock implies nothing about the
+ * org/host/user scopes — those stay with `lockdownRefusal` at the routes
+ * that carry it.
+ *
+ * A door that names the org it serves passes `orgId` (AGL-2927), and the
+ * workspace-scoped carrier for the same feature is checked third, under the
+ * same per-feature staff bypass: the staff AI pause is a spend stop on one
+ * customer, and a staff call made to verify the pause is ours to spend. A
+ * door that names no org — the plugin dispatcher, which gates by path
+ * before the body is read — sees the platform-wide document only, which is
+ * what it saw before.
+ */
+export declare function featureLockdownRefusal(options: {
+    feature: LockdownFeatureKey;
+    /** Verified `staff` custom claim — from a VERIFIED token only. */
+    staff?: boolean;
+    /** The workspace the request is metered against, where the door knows it. */
+    orgId?: string | null;
+    nowMs?: number;
+}): Promise<Response | null>;
+/**
+ * User-doc cache (AGL-1522): the last per-call read on the verdict path.
+ * AGL-1506 wired the verdict into ~36 routes plus the session mint/exchange,
+ * and every call carrying a `uid` paid one Firestore get on
+ * `lockdowns/user--{uid}` — an active console editor generated one read per
+ * wired mutation, against the AGL-1302 read budget. Same TTL, same pending
+ * dedupe, same fail-open posture as the platform and feature caches above —
+ * ONE cache pattern in this module, not three implementations.
+ *
+ * The staleness tradeoff, stated: a user locked mid-window keeps passing
+ * this check for up to PLATFORM_TTL_MS (15s) plus the caller's polling
+ * cadence — on every process EXCEPT the one that took the action, which
+ * refuses immediately because /api/admin/lockdown invalidates this uid's
+ * entry after the write (the platform/feature invalidation hook, mirrored).
+ * That bound is acceptable here for the same reason `media/sign` omits the
+ * user scope entirely: the hard kill never rode this read. A user lock also
+ * disables the Auth account and revokes refresh tokens, so the ID token
+ * stops refreshing and the session cookie dies at its next
+ * `verifySessionCookie(…, true)` — the cache can only delay the DISTINCT
+ * 423 body, not access itself, and 15s matches the platform scope's stated
+ * worst case and the drill's measured flip times.
+ *
+ * Bounded so a scan of uids cannot balloon a warm process: past
+ * USER_LOCKDOWN_CACHE_MAX entries the least-recently-USED is evicted (a
+ * cache hit refreshes recency, so active sessions survive a scan).
+ */
+export declare const USER_LOCKDOWN_CACHE_MAX = 5000;
+/**
+ * Drop one uid's cached verdict (after a user lock/unlock write), or the
+ * whole cache when called bare. The acting process serves a fresh verdict
+ * immediately; other processes converge within PLATFORM_TTL_MS.
+ */
+export declare function invalidateUserLockdownCache(uid?: string): void;
+/** `lockdowns/user--{uid}`, normalized; null = not locked (incl. on error). */
+export declare function getUserLockdown(uid: string): Promise<LockdownState | null>;
+/**
+ * DOMAIN-lock cache (AGL-1513), same shape and same TTL as the user cache.
+ *
+ * Bounded for the same reason and one more: the key is a HOSTNAME taken from
+ * the request, so an unbounded map here would be attacker-keyed by anyone who
+ * can point a DNS record at us — which, for the hijack incident this scope
+ * exists for, is the adversary by definition.
+ */
+export declare const DOMAIN_LOCKDOWN_CACHE_MAX = 5000;
+/**
+ * Drop one hostname's cached verdict (after a domain lock/unlock write), or
+ * the whole cache when called bare.
+ */
+export declare function invalidateDomainLockdownCache(hostname?: string): void;
+/**
+ * `lockdowns/domain--{hostname}`, normalized; null = not locked (incl. on
+ * error), matching every other reader here — an unreachable Firestore is an
+ * outage, not a lockdown.
+ */
+export declare function getDomainLockdown(hostname: string): Promise<LockdownState | null>;
+export interface LockdownVerdictOptions {
+    /**
+     * The verified `staff` custom claim of the caller — from a VERIFIED token
+     * only, never from a header or body. True bypasses every scope: this is
+     * the un-panic invariant.
+     */
+    staff?: boolean;
+    /** Verified caller uid; enables the user scope. */
+    uid?: string | null;
+    /**
+     * Already-loaded org doc (or its suspension fields), when the caller has
+     * one in hand — org scope costs no extra read. Absent = scope not
+     * evaluated.
+     */
+    org?: Parameters<typeof normalizeOrgLockdown>[0];
+    /** Already-loaded host doc; same contract as `org`. */
+    host?: Parameters<typeof normalizeHostLockdown>[0];
+    /**
+     * READ-ONLY discrimination (AGL-1511). A `read-only` lock refuses writes
+     * and passes reads; a `full` lock refuses both, so this changes nothing
+     * for every lock written before the mode existed.
+     *
+     * The request the chokepoint is answering — its METHOD decides. Passing
+     * the route's own `request` is the wiring, because a single console
+     * handler is usually exported as both GET and POST and the verdict runs
+     * before the method branch: derive the intent, never restate it.
+     */
+    request?: {
+        method?: string;
+    } | null;
+    /**
+     * Explicit intent, overriding `request`. For the routes whose method lies
+     * about what they do — a POST that is really a query (`where-used`,
+     * `plugin-impact`), or a GET that mutates.
+     *
+     * Neither given = `write`, the fail-safe: a chokepoint that never declared
+     * its intent refuses during a migration rather than letting an
+     * unconsidered write race the repair.
+     */
+    intent?: LockdownIntent;
+    nowMs?: number;
+}
+/**
+ * The one verdict: the lockdown that REFUSES this caller's request, or null.
+ * Precedence platform > org > host > user, strictness before width (from
+ * `resolveLockdown`).
+ *
+ * "Refuses this request" rather than "covers this caller" since AGL-1511: a
+ * read-only lock is active but does not refuse a read, and returning it
+ * anyway would make every wired chokepoint 423 a GET — a read-only mode that
+ * behaves exactly like a full one. The active state is still what
+ * `resolveLockdown` chose, so the staff probe and the notice copy see the
+ * real lock; only the ANSWER is intent-aware.
+ */
+export declare function getLockdownVerdict(options: LockdownVerdictOptions): Promise<LockdownState | null>;
+/**
+ * The refusal an API route returns for a locked caller: **423 Locked** with
+ * a machine-readable body, so an API consumer sees "suspended: billing" and
+ * not a mystery 403. Carries only the sanitized, user-facing subset — never
+ * the actor uid or staff rationale.
+ */
+/**
+ * Verdict and refusal in one call — the two-line wiring every org-scoped
+ * API route carries (AGL-1506):
+ *
+ *   const locked = await lockdownRefusal({ staff, uid, org, host })
+ *   if (locked) return locked
+ *
+ * Null means "not locked, proceed". One mechanism: this delegates to
+ * `getLockdownVerdict` (so the un-panic invariant and fail-open posture are
+ * inherited, never re-implemented) and to `lockdownJsonResponse` for the
+ * distinct 423 body. Routes with a richer flow (the session mint clears
+ * cookies on refusal) keep calling the two halves directly.
+ */
+export declare function lockdownRefusal(options: LockdownVerdictOptions & {
+    /** Visitor-facing copy override; see `lockdownJsonResponse`. */
+    notice?: LockdownNotice;
+}): Promise<Response | null>;
+export declare function lockdownJsonResponse(state: LockdownState, options?: {
+    /**
+     * Substitute copy for a surface whose reader is not the account holder
+     * — the tenant runtime's visitor-facing pause (AGL-1511). ONE wire
+     * shape and ONE writer either way: only the words change, so
+     * `parseLockdownRefusal` reads a paused checkout exactly as it reads a
+     * locked console.
+     */
+    notice?: LockdownNotice;
+}): Response;
+/**
+ * IS THE CREATION-LEVEL VALVE ACTUALLY ARMED? (AGL-1531)
+ *
+ * The signups feature lock refuses the session mint, the acceptance recorder
+ * and the signup-page doors from code that ships with every deploy. It also
+ * refuses account CREATION — but only through a Firebase Auth
+ * `beforeUserCreated` blocking function in `cloud/functions`, which merging
+ * does not deploy and deploying does not necessarily register. Identity
+ * Platform holds that registration, not this repo.
+ *
+ * So the staff page had a way to be confidently wrong: the switch reads
+ * LOCKED either way, and an operator during a bot wave would have no way to
+ * tell "creation is refused" from "creation is still wide open and only
+ * sessions are being turned away". This is the read that closes that gap —
+ * the panic surface states which of the two it is instead of implying the
+ * stronger one.
+ *
+ * `unknown` is a first-class answer and is NEVER rendered as armed. The
+ * probe needs a credential with the identitytoolkit scope and an outbound
+ * call; a deployment where either is missing must report that it does not
+ * know, because "we could not check" and "it is on" are the two answers an
+ * incident cannot afford to have confused.
+ */
+/**
+ * A STRING discriminant, not a `boolean | null`. `strictNullChecks` is off
+ * repo-wide, so `null` is assignable to every member and a `armed: null` arm
+ * cannot narrow — the compiler collapses the union and the "unknown" case
+ * silently stops being distinguishable from the other two. Which is the one
+ * distinction this type exists to hold.
+ */
+export type SignupsCreationTriggerStatus = {
+    status: 'armed';
+    functionUri: string | null;
+    updateTime: string | null;
+} | {
+    status: 'absent';
+} | {
+    status: 'unknown';
+    reason: string;
+};
+export declare function readSignupsCreationTriggerStatus(): Promise<SignupsCreationTriggerStatus>;