@aglyn/aglyn 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/plugin-manager/plugin-site-export.d.ts

@@ -54,6 +54,49 @@ export interface PluginHostCollectionSiteExport {
     limit: number;
     /** The keys a restore writes back. Anything else a bundle carries is dropped. */
     fields: readonly string[];
+    /** What a site package calls each document (AGL-3533). */
+    package: PluginSitePackageItemDeclaration;
+    /**
+     * What a restore is met against when the collection has no `resource`: a
+     * plan counter, a flat platform cap by core's name for it, or `uncapped`
+     * with the reason a count adds nothing (the browser already creates the
+     * collection without one).
+     */
+    count?: {
+        quotaKey: string;
+    } | {
+        platformCap: string;
+    } | {
+        uncapped: string;
+    };
+}
+/**
+ * How a site package lists a plugin's items (AGL-3533): the kind, the plural
+ * label the import screen groups them under, the field an item with a new id
+ * is matched by (a slug first, then a name), the fields that hold ids of
+ * other site items, the binding token (`var`, `fn`) that names one of these
+ * items inside a design, and the node props that place one. Compiled, and checked by the generator: one
+ * owner per kind, none of the platform's own.
+ */
+export interface PluginSitePackageItemDeclaration {
+    kind: string;
+    label: string;
+    nameField?: string;
+    slugField?: string;
+    references?: ReadonlyArray<{
+        field: string;
+        kind: string;
+    }>;
+    bindingToken?: 'var' | 'fn';
+    /**
+     * Node props that place one of these items in a design: a `form` node's
+     * `formId`, any node's `repeatDataset`. `componentId` narrows it to one
+     * element; absent, any node's prop counts.
+     */
+    placements?: ReadonlyArray<{
+        componentId?: string;
+        prop: string;
+    }>;
 }
 /** What a restore of a declared collection is counted against. */
 export type PluginSiteExportCount = 
@@ -67,15 +110,28 @@ export type PluginSiteExportCount =
  */
  | {
     max: number | null;
+}
+/** Nothing to count, for the reason the declaration gives. */
+ | {
+    uncapped: string;
 };
 /** A declared collection with the plugin that made it and its count. */
-export interface ResolvedPluginSiteExportCollection extends PluginHostCollectionSiteExport {
+export interface ResolvedPluginSiteExportCollection extends Omit<PluginHostCollectionSiteExport, 'count'> {
     pluginId: string;
     /** The subcollection under `hosts/{hostId}`, and its key in the bundle. */
     collection: string;
     /** Plural, for a restore's refusal: "this backup holds 40 {label}". */
     label: string;
     count: PluginSiteExportCount;
+    /**
+     * The field that may send traffic off the platform, and the field its
+     * approver lands in: a restore stamps the importing admin there, since a
+     * file's approver is provenance it cannot supply.
+     */
+    externalDestination?: {
+        field: string;
+        approvedByField: string;
+    };
 }
 /** Every collection a plugin declares for the site backup, in config order. */
 export declare function listPluginSiteExportCollections(): ResolvedPluginSiteExportCollection[];

package/src/lib/plugin-manager/plugin-site-export.js

@@ -1,3 +1,4 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -15,24 +16,36 @@
  * limitations under the License.
  */ import { PLUGIN_HOST_COLLECTIONS_DECLARED } from "./first-party-plugins.generated.js";
 import { hostResourcePlatformCap } from "./plugin-host-resources.js";
+function siteExportCount(resource, count) {
+    var _ref, _ref1;
+    const source = (_ref = resource != null ? resource : count) != null ? _ref : {};
+    if ('uncapped' in source && source.uncapped) return {
+        uncapped: source.uncapped
+    };
+    if ('quotaKey' in source && source.quotaKey) return {
+        quotaKey: source.quotaKey
+    };
+    return {
+        max: hostResourcePlatformCap((_ref1 = 'platformCap' in source ? source.platformCap : '') != null ? _ref1 : '')
+    };
+}
 /** Every collection a plugin declares for the site backup, in config order. */ export function listPluginSiteExportCollections() {
     const out = [];
     for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED){
-        var _resource_platformCap;
+        var _ref;
         const { siteExport, resource } = row;
-        if (!siteExport || !resource) continue;
-        out.push({
+        if (!siteExport || !resource && !siteExport.count) continue;
+        out.push(_extends({
             pluginId: row.pluginId,
             collection: row.name,
             limit: siteExport.limit,
             fields: siteExport.fields,
-            label: resource.label,
-            count: resource.quotaKey ? {
-                quotaKey: resource.quotaKey
-            } : {
-                max: hostResourcePlatformCap((_resource_platformCap = resource.platformCap) != null ? _resource_platformCap : '')
-            }
-        });
+            package: siteExport.package,
+            label: (_ref = resource == null ? void 0 : resource.label) != null ? _ref : siteExport.package.label.toLowerCase(),
+            count: siteExportCount(resource, siteExport.count)
+        }, (resource == null ? void 0 : resource.externalDestination) ? {
+            externalDestination: resource.externalDestination
+        } : {}));
     }
     return out;
 }

package/src/lib/plugin-manager/plugin-site-export.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-export.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { PLUGIN_HOST_COLLECTIONS_DECLARED } from './first-party-plugins.generated'\nimport { hostResourcePlatformCap } from './plugin-host-resources'\n\n/**\n * A plugin's host collection in the platform's whole-site backup (AGL-3080).\n *\n * `/api/hosts/export` writes one JSON bundle of everything designable on a\n * site and `/api/hosts/import` restores it (AGL-163). The platform's own\n * documents — screens, layouts, components, authors, content collections,\n * media — are the routes' to carry. A plugin whose site documents belong in\n * a backup declares so beside the collection, in the `hostCollections` block\n * of `plugins.config.json` (a host collection's `siteExport`), and both\n * routes walk the declarations: the export reads up to `limit` live documents\n * into the bundle under the collection's own name, and the restore writes each\n * one back through `fields` and counts the result against the collection's\n * declared `resource`.\n *\n * ## `fields` is the round trip, not the create\n *\n * A restore writes with `merge: false`, so the list is every key a live\n * document carries — which can be narrower than what a create admits, and is\n * often wider — and a key left off is ERASED from every restored document\n * (AGL-1382). Nothing the restore stamps (`createdAt`, `updatedAt`,\n * `deletedAt`) or scopes (`visibleTo`) is on it; the generator refuses them.\n *\n * ## Compiled, and counted\n *\n * A backup that silently lacks a collection is worse than a failed one: the\n * file looks whole until the day it is restored. So the declarations are\n * compiled, present the moment this module is imported, and a runtime\n * `registerPluginHostCollections` carrying a `siteExport` throws. A restore\n * creates documents with the Admin SDK, past the rules, so the generator also\n * refuses a `siteExport` on a collection with no `resource`: the resource's\n * plan counter or flat platform cap is what the restore is met against.\n *\n * Reached by its own subpath, never the barrel: its readers are the two\n * console routes.\n */\nexport interface PluginHostCollectionSiteExport {\n  /** The most live documents one bundle carries; a restore writes no more. */\n  limit: number\n  /** The keys a restore writes back. Anything else a bundle carries is dropped. */\n  fields: readonly string[]\n}\n\n/** What a restore of a declared collection is counted against. */\nexport type PluginSiteExportCount =\n  /** A plan counter, an `OrgEntitlements` key core resolves. */\n  | { quotaKey: string }\n  /**\n   * A flat platform cap, resolved from the name the resource declares, or\n   * `null` for a name core does not hold — which a restore refuses.\n   */\n  | { max: number | null }\n\n/** A declared collection with the plugin that made it and its count. */\nexport interface ResolvedPluginSiteExportCollection extends PluginHostCollectionSiteExport {\n  pluginId: string\n  /** The subcollection under `hosts/{hostId}`, and its key in the bundle. */\n  collection: string\n  /** Plural, for a restore's refusal: \"this backup holds 40 {label}\". */\n  label: string\n  count: PluginSiteExportCount\n}\n\n/** Every collection a plugin declares for the site backup, in config order. */\nexport function listPluginSiteExportCollections(): ResolvedPluginSiteExportCollection[] {\n  const out: ResolvedPluginSiteExportCollection[] = []\n  for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED) {\n    const { siteExport, resource } = row\n    if (!siteExport || !resource) continue\n    out.push({\n      pluginId: row.pluginId,\n      collection: row.name,\n      limit: siteExport.limit,\n      fields: siteExport.fields,\n      label: resource.label,\n      count: resource.quotaKey\n        ? { quotaKey: resource.quotaKey }\n        : { max: hostResourcePlatformCap(resource.platformCap ?? '') },\n    })\n  }\n  return out\n}\n"],"names":["PLUGIN_HOST_COLLECTIONS_DECLARED","hostResourcePlatformCap","listPluginSiteExportCollections","out","row","resource","siteExport","push","pluginId","collection","name","limit","fields","label","count","quotaKey","max","platformCap"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gCAAgC,QAAQ,qCAAiC;AAClF,SAASC,uBAAuB,QAAQ,6BAAyB;AAgEjE,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,MAA4C,EAAE;IACpD,KAAK,MAAMC,OAAOJ,iCAAkC;YAWbK;QAVrC,MAAM,EAAEC,UAAU,EAAED,QAAQ,EAAE,GAAGD;QACjC,IAAI,CAACE,cAAc,CAACD,UAAU;QAC9BF,IAAII,IAAI,CAAC;YACPC,UAAUJ,IAAII,QAAQ;YACtBC,YAAYL,IAAIM,IAAI;YACpBC,OAAOL,WAAWK,KAAK;YACvBC,QAAQN,WAAWM,MAAM;YACzBC,OAAOR,SAASQ,KAAK;YACrBC,OAAOT,SAASU,QAAQ,GACpB;gBAAEA,UAAUV,SAASU,QAAQ;YAAC,IAC9B;gBAAEC,KAAKf,yBAAwBI,wBAAAA,SAASY,WAAW,YAApBZ,wBAAwB;YAAI;QACjE;IACF;IACA,OAAOF;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-export.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { PLUGIN_HOST_COLLECTIONS_DECLARED } from './first-party-plugins.generated'\nimport { hostResourcePlatformCap } from './plugin-host-resources'\n\n/**\n * A plugin's host collection in the platform's whole-site backup (AGL-3080).\n *\n * `/api/hosts/export` writes one JSON bundle of everything designable on a\n * site and `/api/hosts/import` restores it (AGL-163). The platform's own\n * documents — screens, layouts, components, authors, content collections,\n * media — are the routes' to carry. A plugin whose site documents belong in\n * a backup declares so beside the collection, in the `hostCollections` block\n * of `plugins.config.json` (a host collection's `siteExport`), and both\n * routes walk the declarations: the export reads up to `limit` live documents\n * into the bundle under the collection's own name, and the restore writes each\n * one back through `fields` and counts the result against the collection's\n * declared `resource`.\n *\n * ## `fields` is the round trip, not the create\n *\n * A restore writes with `merge: false`, so the list is every key a live\n * document carries — which can be narrower than what a create admits, and is\n * often wider — and a key left off is ERASED from every restored document\n * (AGL-1382). Nothing the restore stamps (`createdAt`, `updatedAt`,\n * `deletedAt`) or scopes (`visibleTo`) is on it; the generator refuses them.\n *\n * ## Compiled, and counted\n *\n * A backup that silently lacks a collection is worse than a failed one: the\n * file looks whole until the day it is restored. So the declarations are\n * compiled, present the moment this module is imported, and a runtime\n * `registerPluginHostCollections` carrying a `siteExport` throws. A restore\n * creates documents with the Admin SDK, past the rules, so the generator also\n * refuses a `siteExport` on a collection with no `resource`: the resource's\n * plan counter or flat platform cap is what the restore is met against.\n *\n * Reached by its own subpath, never the barrel: its readers are the two\n * console routes.\n */\nexport interface PluginHostCollectionSiteExport {\n  /** The most live documents one bundle carries; a restore writes no more. */\n  limit: number\n  /** The keys a restore writes back. Anything else a bundle carries is dropped. */\n  fields: readonly string[]\n  /** What a site package calls each document (AGL-3533). */\n  package: PluginSitePackageItemDeclaration\n  /**\n   * What a restore is met against when the collection has no `resource`: a\n   * plan counter, a flat platform cap by core's name for it, or `uncapped`\n   * with the reason a count adds nothing (the browser already creates the\n   * collection without one).\n   */\n  count?: { quotaKey: string } | { platformCap: string } | { uncapped: string }\n}\n\n/**\n * How a site package lists a plugin's items (AGL-3533): the kind, the plural\n * label the import screen groups them under, the field an item with a new id\n * is matched by (a slug first, then a name), the fields that hold ids of\n * other site items, the binding token (`var`, `fn`) that names one of these\n * items inside a design, and the node props that place one. Compiled, and checked by the generator: one\n * owner per kind, none of the platform's own.\n */\nexport interface PluginSitePackageItemDeclaration {\n  kind: string\n  label: string\n  nameField?: string\n  slugField?: string\n  references?: ReadonlyArray<{ field: string; kind: string }>\n  bindingToken?: 'var' | 'fn'\n  /**\n   * Node props that place one of these items in a design: a `form` node's\n   * `formId`, any node's `repeatDataset`. `componentId` narrows it to one\n   * element; absent, any node's prop counts.\n   */\n  placements?: ReadonlyArray<{ componentId?: string; prop: string }>\n}\n\n/** What a restore of a declared collection is counted against. */\nexport type PluginSiteExportCount =\n  /** A plan counter, an `OrgEntitlements` key core resolves. */\n  | { quotaKey: string }\n  /**\n   * A flat platform cap, resolved from the name the resource declares, or\n   * `null` for a name core does not hold — which a restore refuses.\n   */\n  | { max: number | null }\n  /** Nothing to count, for the reason the declaration gives. */\n  | { uncapped: string }\n\n/** A declared collection with the plugin that made it and its count. */\nexport interface ResolvedPluginSiteExportCollection extends Omit<PluginHostCollectionSiteExport, 'count'> {\n  pluginId: string\n  /** The subcollection under `hosts/{hostId}`, and its key in the bundle. */\n  collection: string\n  /** Plural, for a restore's refusal: \"this backup holds 40 {label}\". */\n  label: string\n  count: PluginSiteExportCount\n  /**\n   * The field that may send traffic off the platform, and the field its\n   * approver lands in: a restore stamps the importing admin there, since a\n   * file's approver is provenance it cannot supply.\n   */\n  externalDestination?: { field: string; approvedByField: string }\n}\n\nfunction siteExportCount(\n  resource: { quotaKey?: string; platformCap?: string } | undefined,\n  count: PluginHostCollectionSiteExport['count'],\n): PluginSiteExportCount {\n  const source = resource ?? count ?? {}\n  if ('uncapped' in source && source.uncapped) return { uncapped: source.uncapped }\n  if ('quotaKey' in source && source.quotaKey) return { quotaKey: source.quotaKey }\n  return { max: hostResourcePlatformCap(('platformCap' in source ? source.platformCap : '') ?? '') }\n}\n\n/** Every collection a plugin declares for the site backup, in config order. */\nexport function listPluginSiteExportCollections(): ResolvedPluginSiteExportCollection[] {\n  const out: ResolvedPluginSiteExportCollection[] = []\n  for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED) {\n    const { siteExport, resource } = row\n    if (!siteExport || (!resource && !siteExport.count)) continue\n    out.push({\n      pluginId: row.pluginId,\n      collection: row.name,\n      limit: siteExport.limit,\n      fields: siteExport.fields,\n      package: siteExport.package,\n      label: resource?.label ?? siteExport.package.label.toLowerCase(),\n      count: siteExportCount(resource, siteExport.count),\n      ...(resource?.externalDestination ? { externalDestination: resource.externalDestination } : {}),\n    })\n  }\n  return out\n}\n"],"names":["PLUGIN_HOST_COLLECTIONS_DECLARED","hostResourcePlatformCap","siteExportCount","resource","count","source","uncapped","quotaKey","max","platformCap","listPluginSiteExportCollections","out","row","siteExport","push","pluginId","collection","name","limit","fields","package","label","toLowerCase","externalDestination"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gCAAgC,QAAQ,qCAAiC;AAClF,SAASC,uBAAuB,QAAQ,6BAAyB;AAwGjE,SAASC,gBACPC,QAAiE,EACjEC,KAA8C;QAE/BD,MAGwB;IAHvC,MAAME,UAASF,OAAAA,mBAAAA,WAAYC,iBAAZD,OAAqB,CAAC;IACrC,IAAI,cAAcE,UAAUA,OAAOC,QAAQ,EAAE,OAAO;QAAEA,UAAUD,OAAOC,QAAQ;IAAC;IAChF,IAAI,cAAcD,UAAUA,OAAOE,QAAQ,EAAE,OAAO;QAAEA,UAAUF,OAAOE,QAAQ;IAAC;IAChF,OAAO;QAAEC,KAAKP,yBAAyB,QAAA,iBAAiBI,SAASA,OAAOI,WAAW,GAAG,cAA/C,QAAsD;IAAI;AACnG;AAEA,6EAA6E,GAC7E,OAAO,SAASC;IACd,MAAMC,MAA4C,EAAE;IACpD,KAAK,MAAMC,OAAOZ,iCAAkC;;QAClD,MAAM,EAAEa,UAAU,EAAEV,QAAQ,EAAE,GAAGS;QACjC,IAAI,CAACC,cAAe,CAACV,YAAY,CAACU,WAAWT,KAAK,EAAG;QACrDO,IAAIG,IAAI,CAAC;YACPC,UAAUH,IAAIG,QAAQ;YACtBC,YAAYJ,IAAIK,IAAI;YACpBC,OAAOL,WAAWK,KAAK;YACvBC,QAAQN,WAAWM,MAAM;YACzBC,SAASP,WAAWO,OAAO;YAC3BC,KAAK,UAAElB,4BAAAA,SAAUkB,KAAK,mBAAIR,WAAWO,OAAO,CAACC,KAAK,CAACC,WAAW;YAC9DlB,OAAOF,gBAAgBC,UAAUU,WAAWT,KAAK;WAC7CD,CAAAA,4BAAAA,SAAUoB,mBAAmB,IAAG;YAAEA,qBAAqBpB,SAASoB,mBAAmB;QAAC,IAAI,CAAC;IAEjG;IACA,OAAOZ;AACT"}

package/src/lib/plugin-manager/plugin-sitemap-readers.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @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.
+ */
+/**
+ * Child sitemaps a plugin's READER lists, for pages no query over one site
+ * collection can describe (AGL-3475).
+ *
+ * `plugin-sitemap-sections` covers a plugin whose pages are the documents of
+ * one collection under the site, addressed by one fixed path: a product per
+ * row of `products`, at `/products/{slug}`. A record page is neither. Its rows
+ * live in the ORGANIZATION's datasets, its address is a base the site chose,
+ * and a site can have several record templates — each its own set of pages at
+ * its own base. So the plugin answers in code, the way it answers a repeat's
+ * rows (`repeat-rows.ts`): it names a section family here, and its reader says
+ * which children the family has on a site and what each one lists.
+ *
+ * ## The family and its children
+ *
+ * A declaration names a section, `records`. Its reader answers with KEYS, and
+ * each key is one child sitemap, `/sitemaps/records-{key}/{page}.xml` — one per
+ * record template, say. That is how a content collection's sitemap has always
+ * been addressed (`content-{slug}`), and for the same reason: the index counts
+ * each child once and the child pages through its own URLs, so one template
+ * with ten thousand records never shifts the page numbers of another.
+ *
+ * ## Declared, then registered — and an absent reader is NOT "no pages"
+ *
+ * A search engine reads a section missing from the index as pages that no
+ * longer exist, so a reader a process forgot to register must not answer
+ * "nothing". The plugin declares the family in `plugins.config.json`
+ * (`sitemapReaders`), the generator compiles it, and the reader registers from
+ * the plugin's `serverDeclarations`, which every process runs at boot. A
+ * declared family with no reader runs the app's declarations step once more
+ * and then THROWS ({@link PluginSitemapReaderUnavailableError}); the sitemap
+ * route reads a throw as a degraded answer and keeps the cached one rather
+ * than shipping a smaller index.
+ *
+ * Reached by its own subpath, never the barrel: only the tenant's sitemap and
+ * `llms.txt` ask.
+ */
+/** The compiled declaration of one section family. */
+export interface PluginSitemapReaderDeclaration {
+    /** The family's name: its children are `{section}-{key}`. */
+    section: string;
+}
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginSitemapReaderDeclaration = PluginSitemapReaderDeclaration & {
+    pluginId: string;
+};
+/** One child a reader lists on a site. */
+export interface PluginSitemapChild {
+    /** The child's key: lowercase letters and digits joined by hyphens. */
+    key: string;
+    /**
+     * How many URLs the child lists — at most, since a row with no address is
+     * left out of the page that would have held it. Sizes the index.
+     */
+    urls: number;
+}
+/** One URL a child lists. */
+export interface PluginSitemapUrl {
+    /** The page's site path: `/services/roofing`. */
+    path: string;
+    /** When the page last changed: anything `sitemapLastmod` reads. */
+    lastmod?: unknown;
+}
+/** A group of pages worth naming in `/llms.txt`. */
+export interface PluginSitemapListing {
+    /** What the pages are: "Services". */
+    name: string;
+    /** The path the pages share, without slashes at either end: `services`. */
+    base: string;
+    /** How many pages the group holds. */
+    count: number;
+}
+/** What a reader answers, for one site at a time. */
+export interface PluginSitemapReader {
+    /** The children this site has, in the order the index lists them. */
+    children(request: {
+        hostId: string;
+    }): Promise<PluginSitemapChild[]>;
+    /** One page of one child's URLs. */
+    urls(request: {
+        hostId: string;
+        key: string;
+        page: number;
+        perPage: number;
+    }): Promise<PluginSitemapUrl[]>;
+    /** The groups `/llms.txt` names. Optional: a family need not have any. */
+    listings?(request: {
+        hostId: string;
+    }): Promise<PluginSitemapListing[]>;
+}
+/** Every declared family, in config order — the order the index lists them. */
+export declare function listPluginSitemapReaders(): readonly ResolvedPluginSitemapReaderDeclaration[];
+/** A child's section name: `records-services`. */
+export declare function pluginSitemapChildSection(section: string, key: string): string;
+/** Whether a reader's key can name a child section. */
+export declare function isPluginSitemapChildKey(key: unknown): key is string;
+/**
+ * The declared family and child key a section name addresses, or `null`. The
+ * longest family wins, so `records-x` never reads as a child of a family
+ * named `rec`.
+ */
+export declare function parsePluginSitemapChildSection(section: string, declared?: readonly ResolvedPluginSitemapReaderDeclaration[]): {
+    declaration: ResolvedPluginSitemapReaderDeclaration;
+    key: string;
+} | null;
+/**
+ * Registers the reader for a declared family. The owner is the plugin whose
+ * register fn is running, or the `pluginId` passed for a boot declaration;
+ * with neither, or with a plugin other than the one the declaration names,
+ * the registration throws. The same plugin registering again replaces its
+ * reader. Returns the unregister.
+ */
+export declare function registerPluginSitemapReader(section: string, reader: PluginSitemapReader, options?: {
+    pluginId?: string;
+}): () => void;
+/** Only for specs: forgets every registered reader. */
+export declare function resetPluginSitemapReadersForTests(): void;
+/**
+ * A declared family's reader was not registered, even after the app's
+ * declarations step ran again. Thrown, never answered as "no pages".
+ */
+export declare class PluginSitemapReaderUnavailableError extends Error {
+    readonly declaration: ResolvedPluginSitemapReaderDeclaration;
+    constructor(declaration: ResolvedPluginSitemapReaderDeclaration);
+}
+/**
+ * The reader a declared family answers through — after one repair when it is
+ * missing, and a throw when it is still missing.
+ */
+export declare function pluginSitemapReader(declaration: ResolvedPluginSitemapReaderDeclaration): Promise<PluginSitemapReader>;

package/src/lib/plugin-manager/plugin-sitemap-readers.js

@@ -0,0 +1,110 @@
+var _globalScope_READERS_KEY;
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { PLUGIN_SITEMAP_READERS_DECLARED } from "./first-party-plugins.generated.js";
+import { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
+/** Every declared family, in config order — the order the index lists them. */ export function listPluginSitemapReaders() {
+    return PLUGIN_SITEMAP_READERS_DECLARED;
+}
+/** A child's section name: `records-services`. */ export function pluginSitemapChildSection(section, key) {
+    return `${section}-${key}`;
+}
+/**
+ * A child key a section name can carry: lowercase letters and digits, joined
+ * by runs of hyphens — a run of two is how a reader spells a path separator
+ * (`services--residential`).
+ */ const CHILD_KEY = /^[a-z0-9]+(?:-+[a-z0-9]+)*$/;
+/** Whether a reader's key can name a child section. */ export function isPluginSitemapChildKey(key) {
+    return typeof key === 'string' && key.length <= 120 && CHILD_KEY.test(key);
+}
+/**
+ * The declared family and child key a section name addresses, or `null`. The
+ * longest family wins, so `records-x` never reads as a child of a family
+ * named `rec`.
+ */ export function parsePluginSitemapChildSection(section, declared = PLUGIN_SITEMAP_READERS_DECLARED) {
+    const matches = declared.filter((one)=>section.startsWith(`${one.section}-`)).sort((a, b)=>b.section.length - a.section.length);
+    const declaration = matches[0];
+    if (!declaration) return null;
+    const key = section.slice(declaration.section.length + 1);
+    return isPluginSitemapChildKey(key) ? {
+        declaration,
+        key
+    } : null;
+}
+/**
+ * One table per process, on `globalThis` (AGL-3412): readers register from
+ * `instrumentation.ts`, which Next compiles apart from the routes that read.
+ */ const READERS_KEY = Symbol.for('@aglyn/aglyn:plugin-sitemap-readers');
+const globalScope = globalThis;
+const readers = (_globalScope_READERS_KEY = globalScope[READERS_KEY]) != null ? _globalScope_READERS_KEY : globalScope[READERS_KEY] = new Map();
+/**
+ * Registers the reader for a declared family. The owner is the plugin whose
+ * register fn is running, or the `pluginId` passed for a boot declaration;
+ * with neither, or with a plugin other than the one the declaration names,
+ * the registration throws. The same plugin registering again replaces its
+ * reader. Returns the unregister.
+ */ export function registerPluginSitemapReader(section, reader, options) {
+    var _ref, _getRegisteringPluginId;
+    const name = section.trim();
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!name) throw new Error('a sitemap reader needs a section');
+    if (!pluginId) {
+        throw new Error(`sitemap reader "${name}" registered with no owner: pass { pluginId } ` + 'when registering outside a plugin register fn');
+    }
+    const declared = PLUGIN_SITEMAP_READERS_DECLARED.find((one)=>one.section === name);
+    if (declared && declared.pluginId !== pluginId) {
+        throw new Error(`sitemap section "${name}" is declared by "${declared.pluginId}"; ` + `refused a reader from "${pluginId}"`);
+    }
+    const entry = {
+        pluginId,
+        reader
+    };
+    readers.set(name, entry);
+    return ()=>{
+        if (readers.get(name) === entry) readers.delete(name);
+    };
+}
+/** Only for specs: forgets every registered reader. */ export function resetPluginSitemapReadersForTests() {
+    readers.clear();
+}
+/**
+ * A declared family's reader was not registered, even after the app's
+ * declarations step ran again. Thrown, never answered as "no pages".
+ */ export class PluginSitemapReaderUnavailableError extends Error {
+    constructor(declaration){
+        super(`sitemap section "${declaration.section}" is declared by ` + `"${declaration.pluginId}" but no reader is registered in this process ` + '— its server declarations did not run.'), this.declaration = declaration;
+        this.name = 'PluginSitemapReaderUnavailableError';
+    }
+}
+/**
+ * The reader a declared family answers through — after one repair when it is
+ * missing, and a throw when it is still missing.
+ */ export async function pluginSitemapReader(declaration) {
+    let registered = readers.get(declaration.section);
+    if (!registered) {
+        try {
+            await runPluginDeclarationsRepair();
+        } catch (error) {
+            console.error('[sitemap-readers] the declarations repair failed', error);
+        }
+        registered = readers.get(declaration.section);
+    }
+    if (!registered) throw new PluginSitemapReaderUnavailableError(declaration);
+    return registered.reader;
+}
+
+//# sourceMappingURL=plugin-sitemap-readers.js.map

package/src/lib/plugin-manager/plugin-sitemap-readers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-sitemap-readers.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { PLUGIN_SITEMAP_READERS_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * Child sitemaps a plugin's READER lists, for pages no query over one site\n * collection can describe (AGL-3475).\n *\n * `plugin-sitemap-sections` covers a plugin whose pages are the documents of\n * one collection under the site, addressed by one fixed path: a product per\n * row of `products`, at `/products/{slug}`. A record page is neither. Its rows\n * live in the ORGANIZATION's datasets, its address is a base the site chose,\n * and a site can have several record templates — each its own set of pages at\n * its own base. So the plugin answers in code, the way it answers a repeat's\n * rows (`repeat-rows.ts`): it names a section family here, and its reader says\n * which children the family has on a site and what each one lists.\n *\n * ## The family and its children\n *\n * A declaration names a section, `records`. Its reader answers with KEYS, and\n * each key is one child sitemap, `/sitemaps/records-{key}/{page}.xml` — one per\n * record template, say. That is how a content collection's sitemap has always\n * been addressed (`content-{slug}`), and for the same reason: the index counts\n * each child once and the child pages through its own URLs, so one template\n * with ten thousand records never shifts the page numbers of another.\n *\n * ## Declared, then registered — and an absent reader is NOT \"no pages\"\n *\n * A search engine reads a section missing from the index as pages that no\n * longer exist, so a reader a process forgot to register must not answer\n * \"nothing\". The plugin declares the family in `plugins.config.json`\n * (`sitemapReaders`), the generator compiles it, and the reader registers from\n * the plugin's `serverDeclarations`, which every process runs at boot. A\n * declared family with no reader runs the app's declarations step once more\n * and then THROWS ({@link PluginSitemapReaderUnavailableError}); the sitemap\n * route reads a throw as a degraded answer and keeps the cached one rather\n * than shipping a smaller index.\n *\n * Reached by its own subpath, never the barrel: only the tenant's sitemap and\n * `llms.txt` ask.\n */\n\n/** The compiled declaration of one section family. */\nexport interface PluginSitemapReaderDeclaration {\n  /** The family's name: its children are `{section}-{key}`. */\n  section: string\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginSitemapReaderDeclaration = PluginSitemapReaderDeclaration & {\n  pluginId: string\n}\n\n/** One child a reader lists on a site. */\nexport interface PluginSitemapChild {\n  /** The child's key: lowercase letters and digits joined by hyphens. */\n  key: string\n  /**\n   * How many URLs the child lists — at most, since a row with no address is\n   * left out of the page that would have held it. Sizes the index.\n   */\n  urls: number\n}\n\n/** One URL a child lists. */\nexport interface PluginSitemapUrl {\n  /** The page's site path: `/services/roofing`. */\n  path: string\n  /** When the page last changed: anything `sitemapLastmod` reads. */\n  lastmod?: unknown\n}\n\n/** A group of pages worth naming in `/llms.txt`. */\nexport interface PluginSitemapListing {\n  /** What the pages are: \"Services\". */\n  name: string\n  /** The path the pages share, without slashes at either end: `services`. */\n  base: string\n  /** How many pages the group holds. */\n  count: number\n}\n\n/** What a reader answers, for one site at a time. */\nexport interface PluginSitemapReader {\n  /** The children this site has, in the order the index lists them. */\n  children(request: { hostId: string }): Promise<PluginSitemapChild[]>\n  /** One page of one child's URLs. */\n  urls(request: {\n    hostId: string\n    key: string\n    page: number\n    perPage: number\n  }): Promise<PluginSitemapUrl[]>\n  /** The groups `/llms.txt` names. Optional: a family need not have any. */\n  listings?(request: { hostId: string }): Promise<PluginSitemapListing[]>\n}\n\n/** Every declared family, in config order — the order the index lists them. */\nexport function listPluginSitemapReaders(): readonly ResolvedPluginSitemapReaderDeclaration[] {\n  return PLUGIN_SITEMAP_READERS_DECLARED\n}\n\n/** A child's section name: `records-services`. */\nexport function pluginSitemapChildSection(section: string, key: string): string {\n  return `${section}-${key}`\n}\n\n/**\n * A child key a section name can carry: lowercase letters and digits, joined\n * by runs of hyphens — a run of two is how a reader spells a path separator\n * (`services--residential`).\n */\nconst CHILD_KEY = /^[a-z0-9]+(?:-+[a-z0-9]+)*$/\n\n/** Whether a reader's key can name a child section. */\nexport function isPluginSitemapChildKey(key: unknown): key is string {\n  return typeof key === 'string' && key.length <= 120 && CHILD_KEY.test(key)\n}\n\n/**\n * The declared family and child key a section name addresses, or `null`. The\n * longest family wins, so `records-x` never reads as a child of a family\n * named `rec`.\n */\nexport function parsePluginSitemapChildSection(\n  section: string,\n  declared: readonly ResolvedPluginSitemapReaderDeclaration[] = PLUGIN_SITEMAP_READERS_DECLARED,\n): { declaration: ResolvedPluginSitemapReaderDeclaration; key: string } | null {\n  const matches = declared\n    .filter((one) => section.startsWith(`${one.section}-`))\n    .sort((a, b) => b.section.length - a.section.length)\n  const declaration = matches[0]\n  if (!declaration) return null\n  const key = section.slice(declaration.section.length + 1)\n  return isPluginSitemapChildKey(key) ? { declaration, key } : null\n}\n\ninterface RegisteredReader {\n  pluginId: string\n  reader: PluginSitemapReader\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): readers register from\n * `instrumentation.ts`, which Next compiles apart from the routes that read.\n */\nconst READERS_KEY = Symbol.for('@aglyn/aglyn:plugin-sitemap-readers')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [READERS_KEY]?: Map<string, RegisteredReader>\n}\n\nconst readers: Map<string, RegisteredReader> =\n  globalScope[READERS_KEY] ?? (globalScope[READERS_KEY] = new Map())\n\n/**\n * Registers the reader for a declared family. The owner is the plugin whose\n * register fn is running, or the `pluginId` passed for a boot declaration;\n * with neither, or with a plugin other than the one the declaration names,\n * the registration throws. The same plugin registering again replaces its\n * reader. Returns the unregister.\n */\nexport function registerPluginSitemapReader(\n  section: string,\n  reader: PluginSitemapReader,\n  options?: { pluginId?: string },\n): () => void {\n  const name = section.trim()\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!name) throw new Error('a sitemap reader needs a section')\n  if (!pluginId) {\n    throw new Error(\n      `sitemap reader \"${name}\" registered with no owner: pass { pluginId } ` +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const declared = PLUGIN_SITEMAP_READERS_DECLARED.find((one) => one.section === name)\n  if (declared && declared.pluginId !== pluginId) {\n    throw new Error(\n      `sitemap section \"${name}\" is declared by \"${declared.pluginId}\"; ` +\n        `refused a reader from \"${pluginId}\"`,\n    )\n  }\n  const entry: RegisteredReader = { pluginId, reader }\n  readers.set(name, entry)\n  return () => {\n    if (readers.get(name) === entry) readers.delete(name)\n  }\n}\n\n/** Only for specs: forgets every registered reader. */\nexport function resetPluginSitemapReadersForTests(): void {\n  readers.clear()\n}\n\n/**\n * A declared family's reader was not registered, even after the app's\n * declarations step ran again. Thrown, never answered as \"no pages\".\n */\nexport class PluginSitemapReaderUnavailableError extends Error {\n  constructor(readonly declaration: ResolvedPluginSitemapReaderDeclaration) {\n    super(\n      `sitemap section \"${declaration.section}\" is declared by ` +\n        `\"${declaration.pluginId}\" but no reader is registered in this process ` +\n        '— its server declarations did not run.',\n    )\n    this.name = 'PluginSitemapReaderUnavailableError'\n  }\n}\n\n/**\n * The reader a declared family answers through — after one repair when it is\n * missing, and a throw when it is still missing.\n */\nexport async function pluginSitemapReader(\n  declaration: ResolvedPluginSitemapReaderDeclaration,\n): Promise<PluginSitemapReader> {\n  let registered = readers.get(declaration.section)\n  if (!registered) {\n    try {\n      await runPluginDeclarationsRepair()\n    } catch (error) {\n      console.error('[sitemap-readers] the declarations repair failed', error)\n    }\n    registered = readers.get(declaration.section)\n  }\n  if (!registered) throw new PluginSitemapReaderUnavailableError(declaration)\n  return registered.reader\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_SITEMAP_READERS_DECLARED","runPluginDeclarationsRepair","listPluginSitemapReaders","pluginSitemapChildSection","section","key","CHILD_KEY","isPluginSitemapChildKey","length","test","parsePluginSitemapChildSection","declared","matches","filter","one","startsWith","sort","a","b","declaration","slice","READERS_KEY","Symbol","for","globalThis","readers","Map","registerPluginSitemapReader","reader","options","name","trim","pluginId","Error","find","entry","set","get","delete","resetPluginSitemapReadersForTests","clear","PluginSitemapReaderUnavailableError","pluginSitemapReader","registered","error","console"],"mappings":"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"}