@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

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

@@ -0,0 +1,145 @@
+/**
+ * @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 plugin's SECTION of the whole-site backup (AGL-3080): what it carries in
+ * the bundle and restores from it, when a host collection's `siteExport`
+ * cannot say so.
+ *
+ * A plain host collection is copied by the export and restore routes
+ * themselves (`plugin-site-export.ts`). Some plugin data is not that shape:
+ * it lives under the ORGANIZATION and is narrowed to the site being backed up,
+ * it carries a subcollection, a restore has to validate it against its own
+ * model and derive what the model implies, and its count is sold as an add-on
+ * rather than read off the plan. Only the plugin knows any of that. So the
+ * plugin declares the section and answers for it: the export asks it for the
+ * site's share, and the restore asks it — before the first write — whether
+ * the bundle would cross what the organization has paid for, then hands it the
+ * bundle's items and the restore's writer.
+ *
+ * ## Declared, then registered — and an absent section is refused
+ *
+ * The plugin declares the section in `plugins.config.json`
+ * (`siteBundleSections`: the bundle key and the most items it carries), which
+ * the generator compiles, and registers the answer from its
+ * `serverDeclarations` entry. A backup that silently lacks a section is worse
+ * than a failed one — the file looks whole until the day it is restored — so
+ * a section declared and not registered is not read as "nothing to carry":
+ * {@link resolveSiteBundleSections} runs the app's declarations step again,
+ * and throws if the section is still missing, which fails the export or the
+ * restore out loud.
+ *
+ * ## What the restore owns
+ *
+ * The section writes through {@link SiteBundleImportRequest.write}, never
+ * with a writer of its own: the restore's chunked batches, its document count
+ * and its all-or-nothing refusal are the restore's, and a write that went
+ * around them would land after a refusal or be missing from the total. The
+ * restore's own stamps (`createdAt`, `updatedAt`) come from
+ * {@link SiteBundleImportRequest.stamps}, so a restored document is dated the
+ * way every other one is.
+ *
+ * Reached by its own subpath, never the barrel: its readers are the two
+ * console routes and the plugins that answer them.
+ */
+/** A section as declared: its key in the bundle and the most items it carries. */
+export interface PluginSiteBundleSectionDeclaration {
+    /** The bundle's top-level key for this section's items, e.g. `datasets`. */
+    key: string;
+    /** The most items one bundle carries; a restore reads no more. */
+    limit: number;
+}
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginSiteBundleSectionDeclaration = PluginSiteBundleSectionDeclaration & {
+    pluginId: string;
+};
+/** One item of a section, as the bundle carries it: a document with its `$id`. */
+export type SiteBundleItem = Record<string, any>;
+/** Whose backup this is. */
+export interface SiteBundleRequest {
+    hostId: string;
+    /**
+     * The site's organization, or `null` for a site with none — which holds no
+     * organization data, a known-empty answer rather than a failure.
+     */
+    orgId: string | null;
+    /** The section's declared limit: the most items one bundle carries. */
+    limit: number;
+}
+/** The restore's question: this bundle's items, for this site. */
+export interface SiteBundleRestoreRequest extends SiteBundleRequest {
+    /** The organization's document, for the plan and add-ons a count is met against. */
+    org: unknown;
+    /** The bundle's items under the section's key, already capped at its declared limit. */
+    items: readonly SiteBundleItem[];
+}
+/** What the restore hands a section to write with. */
+export interface SiteBundleImportRequest extends SiteBundleRestoreRequest {
+    /**
+     * Writes one document, whole (`merge: false`), by its full path
+     * (`orgs/{orgId}/…`), on the restore's batches and counted in its total.
+     */
+    write(documentPath: string, data: Record<string, unknown>): Promise<void>;
+    /** The restore's own stamps for a document it writes: its creation and update times. */
+    stamps(): Record<string, unknown>;
+    /**
+     * Loads every plugin's console server surface, for a section that checks
+     * what it restores against something other plugins register there (a
+     * custom field type). Costs a load, so a section asks only when it needs to.
+     */
+    loadPluginSurfaces(): Promise<void>;
+}
+/** A row the restore reports without refusing: a document restored as it was, and why it is worth a look. */
+export type SiteBundleReportRow = Record<string, unknown>;
+/** A plugin's answers for one section. */
+export interface PluginSiteBundleSection {
+    /** The site's share, read whole or not at all: throw rather than return a short list. */
+    export(request: SiteBundleRequest): Promise<SiteBundleItem[]>;
+    /**
+     * Before the restore writes anything: the sentence it answers 403 with when
+     * restoring these items would cross what the organization may hold, or
+     * `null`. A bundle refused here writes nothing at all.
+     */
+    refusal?(request: SiteBundleRestoreRequest): Promise<string | null>;
+    /** Writes the items back through `request.write`; answers the rows worth reporting. */
+    import(request: SiteBundleImportRequest): Promise<readonly SiteBundleReportRow[]>;
+}
+/** Every declared section, in config order — the order the bundle carries them. */
+export declare function listDeclaredSiteBundleSections(): readonly ResolvedPluginSiteBundleSectionDeclaration[];
+/**
+ * Registers a plugin's answers for a section it declared. The owner is the
+ * plugin whose register fn is running, or the `pluginId` passed from a boot
+ * declaration. Refused: no owner, a key nobody declared (only a declared
+ * section is ever read, so an undeclared one would be carried by nothing),
+ * and a key another plugin declared. The same plugin registering again
+ * replaces its answers.
+ */
+export declare function registerPluginSiteBundleSection(key: string, section: PluginSiteBundleSection, options?: {
+    pluginId?: string;
+}): void;
+/** A declared section with the answers its plugin registered. */
+export type ResolvedSiteBundleSection = ResolvedPluginSiteBundleSectionDeclaration & {
+    section: PluginSiteBundleSection;
+};
+/**
+ * Every declared section with its answers, in config order. A declared
+ * section with nothing registered runs the app's declarations step once and
+ * asks again; still missing, this THROWS naming it — an export that carried
+ * the rest would be a backup missing a section with nothing to say so.
+ */
+export declare function resolveSiteBundleSections(): Promise<ResolvedSiteBundleSection[]>;
+/** Only for specs: forgets every registered section. */
+export declare function resetSiteBundleSectionsForTests(): void;

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

@@ -0,0 +1,78 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+var _globalScope_SECTIONS_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_SITE_BUNDLE_SECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+import { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
+/**
+ * One table per process, on `globalThis` (AGL-3412): a plugin registers from
+ * its declarations at boot, which Next compiles apart from the routes that
+ * read, and a module-scoped map would be filled in one copy and read empty in
+ * the other.
+ */ const SECTIONS_KEY = Symbol.for('@aglyn/aglyn:site-bundle-sections');
+const globalScope = globalThis;
+const sections = (_globalScope_SECTIONS_KEY = globalScope[SECTIONS_KEY]) != null ? _globalScope_SECTIONS_KEY : globalScope[SECTIONS_KEY] = new Map();
+/** Every declared section, in config order — the order the bundle carries them. */ export function listDeclaredSiteBundleSections() {
+    return PLUGIN_SITE_BUNDLE_SECTIONS_DECLARED;
+}
+/**
+ * Registers a plugin's answers for a section it declared. The owner is the
+ * plugin whose register fn is running, or the `pluginId` passed from a boot
+ * declaration. Refused: no owner, a key nobody declared (only a declared
+ * section is ever read, so an undeclared one would be carried by nothing),
+ * and a key another plugin declared. The same plugin registering again
+ * replaces its answers.
+ */ export function registerPluginSiteBundleSection(key, section, options) {
+    var _ref, _getRegisteringPluginId;
+    const name = key.trim();
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`site bundle section "${name}" registered with no owner: pass { pluginId } ` + 'when registering outside a plugin register fn');
+    }
+    const declared = listDeclaredSiteBundleSections().find((one)=>one.key === name);
+    if (!declared) {
+        throw new Error(`site bundle section "${name}" is not declared in plugins.config.json ` + '(siteBundleSections), so no export would ever carry it');
+    }
+    if (declared.pluginId !== pluginId) {
+        throw new Error(`site bundle section "${name}" is declared by "${declared.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    sections.set(name, {
+        pluginId,
+        section
+    });
+}
+/**
+ * Every declared section with its answers, in config order. A declared
+ * section with nothing registered runs the app's declarations step once and
+ * asks again; still missing, this THROWS naming it — an export that carried
+ * the rest would be a backup missing a section with nothing to say so.
+ */ export async function resolveSiteBundleSections() {
+    const missing = ()=>listDeclaredSiteBundleSections().filter((declared)=>!sections.has(declared.key));
+    if (missing().length) await runPluginDeclarationsRepair();
+    const absent = missing();
+    if (absent.length) {
+        throw new Error(`[plugins] site bundle section(s) ${absent.map((one)=>`"${one.key}" (${one.pluginId})`).join(', ')} ` + 'declared and not registered in this process');
+    }
+    return listDeclaredSiteBundleSections().map((declared)=>_extends({}, declared, {
+            section: sections.get(declared.key).section
+        }));
+}
+/** Only for specs: forgets every registered section. */ export function resetSiteBundleSectionsForTests() {
+    sections.clear();
+}
+
+//# sourceMappingURL=plugin-site-bundle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-bundle.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_SITE_BUNDLE_SECTIONS_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * A plugin's SECTION of the whole-site backup (AGL-3080): what it carries in\n * the bundle and restores from it, when a host collection's `siteExport`\n * cannot say so.\n *\n * A plain host collection is copied by the export and restore routes\n * themselves (`plugin-site-export.ts`). Some plugin data is not that shape:\n * it lives under the ORGANIZATION and is narrowed to the site being backed up,\n * it carries a subcollection, a restore has to validate it against its own\n * model and derive what the model implies, and its count is sold as an add-on\n * rather than read off the plan. Only the plugin knows any of that. So the\n * plugin declares the section and answers for it: the export asks it for the\n * site's share, and the restore asks it — before the first write — whether\n * the bundle would cross what the organization has paid for, then hands it the\n * bundle's items and the restore's writer.\n *\n * ## Declared, then registered — and an absent section is refused\n *\n * The plugin declares the section in `plugins.config.json`\n * (`siteBundleSections`: the bundle key and the most items it carries), which\n * the generator compiles, and registers the answer from its\n * `serverDeclarations` entry. A backup that silently lacks a section is worse\n * than a failed one — the file looks whole until the day it is restored — so\n * a section declared and not registered is not read as \"nothing to carry\":\n * {@link resolveSiteBundleSections} runs the app's declarations step again,\n * and throws if the section is still missing, which fails the export or the\n * restore out loud.\n *\n * ## What the restore owns\n *\n * The section writes through {@link SiteBundleImportRequest.write}, never\n * with a writer of its own: the restore's chunked batches, its document count\n * and its all-or-nothing refusal are the restore's, and a write that went\n * around them would land after a refusal or be missing from the total. The\n * restore's own stamps (`createdAt`, `updatedAt`) come from\n * {@link SiteBundleImportRequest.stamps}, so a restored document is dated the\n * way every other one is.\n *\n * Reached by its own subpath, never the barrel: its readers are the two\n * console routes and the plugins that answer them.\n */\n\n/** A section as declared: its key in the bundle and the most items it carries. */\nexport interface PluginSiteBundleSectionDeclaration {\n  /** The bundle's top-level key for this section's items, e.g. `datasets`. */\n  key: string\n  /** The most items one bundle carries; a restore reads no more. */\n  limit: number\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginSiteBundleSectionDeclaration =\n  PluginSiteBundleSectionDeclaration & { pluginId: string }\n\n/** One item of a section, as the bundle carries it: a document with its `$id`. */\nexport type SiteBundleItem = Record<string, any>\n\n/** Whose backup this is. */\nexport interface SiteBundleRequest {\n  hostId: string\n  /**\n   * The site's organization, or `null` for a site with none — which holds no\n   * organization data, a known-empty answer rather than a failure.\n   */\n  orgId: string | null\n  /** The section's declared limit: the most items one bundle carries. */\n  limit: number\n}\n\n/** The restore's question: this bundle's items, for this site. */\nexport interface SiteBundleRestoreRequest extends SiteBundleRequest {\n  /** The organization's document, for the plan and add-ons a count is met against. */\n  org: unknown\n  /** The bundle's items under the section's key, already capped at its declared limit. */\n  items: readonly SiteBundleItem[]\n}\n\n/** What the restore hands a section to write with. */\nexport interface SiteBundleImportRequest extends SiteBundleRestoreRequest {\n  /**\n   * Writes one document, whole (`merge: false`), by its full path\n   * (`orgs/{orgId}/…`), on the restore's batches and counted in its total.\n   */\n  write(documentPath: string, data: Record<string, unknown>): Promise<void>\n  /** The restore's own stamps for a document it writes: its creation and update times. */\n  stamps(): Record<string, unknown>\n  /**\n   * Loads every plugin's console server surface, for a section that checks\n   * what it restores against something other plugins register there (a\n   * custom field type). Costs a load, so a section asks only when it needs to.\n   */\n  loadPluginSurfaces(): Promise<void>\n}\n\n/** A row the restore reports without refusing: a document restored as it was, and why it is worth a look. */\nexport type SiteBundleReportRow = Record<string, unknown>\n\n/** A plugin's answers for one section. */\nexport interface PluginSiteBundleSection {\n  /** The site's share, read whole or not at all: throw rather than return a short list. */\n  export(request: SiteBundleRequest): Promise<SiteBundleItem[]>\n  /**\n   * Before the restore writes anything: the sentence it answers 403 with when\n   * restoring these items would cross what the organization may hold, or\n   * `null`. A bundle refused here writes nothing at all.\n   */\n  refusal?(request: SiteBundleRestoreRequest): Promise<string | null>\n  /** Writes the items back through `request.write`; answers the rows worth reporting. */\n  import(request: SiteBundleImportRequest): Promise<readonly SiteBundleReportRow[]>\n}\n\ninterface Registered {\n  pluginId: string\n  section: PluginSiteBundleSection\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): a plugin registers from\n * its declarations at boot, which Next compiles apart from the routes that\n * read, and a module-scoped map would be filled in one copy and read empty in\n * the other.\n */\nconst SECTIONS_KEY = Symbol.for('@aglyn/aglyn:site-bundle-sections')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [SECTIONS_KEY]?: Map<string, Registered>\n}\n\nconst sections: Map<string, Registered> =\n  globalScope[SECTIONS_KEY] ?? (globalScope[SECTIONS_KEY] = new Map())\n\n/** Every declared section, in config order — the order the bundle carries them. */\nexport function listDeclaredSiteBundleSections(): readonly ResolvedPluginSiteBundleSectionDeclaration[] {\n  return PLUGIN_SITE_BUNDLE_SECTIONS_DECLARED\n}\n\n/**\n * Registers a plugin's answers for a section it declared. The owner is the\n * plugin whose register fn is running, or the `pluginId` passed from a boot\n * declaration. Refused: no owner, a key nobody declared (only a declared\n * section is ever read, so an undeclared one would be carried by nothing),\n * and a key another plugin declared. The same plugin registering again\n * replaces its answers.\n */\nexport function registerPluginSiteBundleSection(\n  key: string,\n  section: PluginSiteBundleSection,\n  options?: { pluginId?: string },\n): void {\n  const name = key.trim()\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `site bundle section \"${name}\" registered with no owner: pass { pluginId } ` +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const declared = listDeclaredSiteBundleSections().find((one) => one.key === name)\n  if (!declared) {\n    throw new Error(\n      `site bundle section \"${name}\" is not declared in plugins.config.json ` +\n        '(siteBundleSections), so no export would ever carry it',\n    )\n  }\n  if (declared.pluginId !== pluginId) {\n    throw new Error(\n      `site bundle section \"${name}\" is declared by \"${declared.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  sections.set(name, { pluginId, section })\n}\n\n/** A declared section with the answers its plugin registered. */\nexport type ResolvedSiteBundleSection = ResolvedPluginSiteBundleSectionDeclaration & {\n  section: PluginSiteBundleSection\n}\n\n/**\n * Every declared section with its answers, in config order. A declared\n * section with nothing registered runs the app's declarations step once and\n * asks again; still missing, this THROWS naming it — an export that carried\n * the rest would be a backup missing a section with nothing to say so.\n */\nexport async function resolveSiteBundleSections(): Promise<ResolvedSiteBundleSection[]> {\n  const missing = () =>\n    listDeclaredSiteBundleSections().filter((declared) => !sections.has(declared.key))\n  if (missing().length) await runPluginDeclarationsRepair()\n  const absent = missing()\n  if (absent.length) {\n    throw new Error(\n      `[plugins] site bundle section(s) ${absent.map((one) => `\"${one.key}\" (${one.pluginId})`).join(', ')} ` +\n        'declared and not registered in this process',\n    )\n  }\n  return listDeclaredSiteBundleSections().map((declared) => ({\n    ...declared,\n    section: (sections.get(declared.key) as Registered).section,\n  }))\n}\n\n/** Only for specs: forgets every registered section. */\nexport function resetSiteBundleSectionsForTests(): void {\n  sections.clear()\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_SITE_BUNDLE_SECTIONS_DECLARED","runPluginDeclarationsRepair","SECTIONS_KEY","Symbol","for","globalThis","sections","Map","listDeclaredSiteBundleSections","registerPluginSiteBundleSection","key","section","options","name","trim","pluginId","Error","declared","find","one","set","resolveSiteBundleSections","missing","filter","has","length","absent","map","join","get","resetSiteBundleSectionsForTests","clear"],"mappings":";IAsJEA;AAtJF;;;;;;;;;;;;;;;CAeC,GAED,SAASC,sBAAsB,QAAQ,qCAAiC;AACxE,SAASC,oCAAoC,QAAQ,qCAAiC;AACtF,SAASC,2BAA2B,QAAQ,kCAA8B;AAsH1E;;;;;CAKC,GACD,MAAMC,eAAeC,OAAOC,GAAG,CAAC;AAEhC,MAAMN,cAAcO;AAIpB,MAAMC,YACJR,4BAAAA,WAAW,CAACI,aAAa,YAAzBJ,4BAA8BA,WAAW,CAACI,aAAa,GAAG,IAAIK;AAEhE,iFAAiF,GACjF,OAAO,SAASC;IACd,OAAOR;AACT;AAEA;;;;;;;CAOC,GACD,OAAO,SAASS,gCACdC,GAAW,EACXC,OAAgC,EAChCC,OAA+B;QAGbb,MAAAA;IADlB,MAAMc,OAAOH,IAAII,IAAI;IACrB,MAAMC,WAAW,EAAChB,QAAAA,0BAAAA,oCAAAA,0BAA4Ba,2BAAAA,QAASG,QAAQ,YAA7ChB,OAAiD,IAAIe,IAAI;IAC3E,IAAI,CAACC,UAAU;QACb,MAAM,IAAIC,MACR,CAAC,qBAAqB,EAAEH,KAAK,8CAA8C,CAAC,GAC1E;IAEN;IACA,MAAMI,WAAWT,iCAAiCU,IAAI,CAAC,CAACC,MAAQA,IAAIT,GAAG,KAAKG;IAC5E,IAAI,CAACI,UAAU;QACb,MAAM,IAAID,MACR,CAAC,qBAAqB,EAAEH,KAAK,yCAAyC,CAAC,GACrE;IAEN;IACA,IAAII,SAASF,QAAQ,KAAKA,UAAU;QAClC,MAAM,IAAIC,MACR,CAAC,qBAAqB,EAAEH,KAAK,kBAAkB,EAAEI,SAASF,QAAQ,CAAC,GAAG,CAAC,GACrE,CAAC,SAAS,EAAEA,SAAS,CAAC,CAAC;IAE7B;IACAT,SAASc,GAAG,CAACP,MAAM;QAAEE;QAAUJ;IAAQ;AACzC;AAOA;;;;;CAKC,GACD,OAAO,eAAeU;IACpB,MAAMC,UAAU,IACdd,iCAAiCe,MAAM,CAAC,CAACN,WAAa,CAACX,SAASkB,GAAG,CAACP,SAASP,GAAG;IAClF,IAAIY,UAAUG,MAAM,EAAE,MAAMxB;IAC5B,MAAMyB,SAASJ;IACf,IAAII,OAAOD,MAAM,EAAE;QACjB,MAAM,IAAIT,MACR,CAAC,iCAAiC,EAAEU,OAAOC,GAAG,CAAC,CAACR,MAAQ,CAAC,CAAC,EAAEA,IAAIT,GAAG,CAAC,GAAG,EAAES,IAAIJ,QAAQ,CAAC,CAAC,CAAC,EAAEa,IAAI,CAAC,MAAM,CAAC,CAAC,GACrG;IAEN;IACA,OAAOpB,iCAAiCmB,GAAG,CAAC,CAACV,WAAc,aACtDA;YACHN,SAAS,AAACL,SAASuB,GAAG,CAACZ,SAASP,GAAG,EAAiBC,OAAO;;AAE/D;AAEA,sDAAsD,GACtD,OAAO,SAASmB;IACdxB,SAASyB,KAAK;AAChB"}

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

@@ -27,6 +27,18 @@ export interface PluginSiteCacheRequest {
      * `'marketplace listing revoked'`, not `'revoke'`.
      */
     reason: string;
+    /**
+     * Narrows a site's drop to the pages that changed: its site-absolute
+     * addresses (`/`, `/contact`), keyed by site id. A site named here loses
+     * only those pages, and one named with an empty list loses none; a site
+     * not named here loses every page it serves.
+     *
+     * For a change the plugin can place exactly — a document it publishes that
+     * renders on the pages that place it — rather than one that reaches every
+     * page, like a revoked bundle. The plugin knows which pages; the app knows
+     * how to drop one, on every address the site answers at.
+     */
+    paths?: Readonly<Record<string, readonly string[]>>;
 }
 export interface PluginSiteCacheResult {
     /** Sites whose cached pages were dropped. */

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-cache.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 * HOW A PLUGIN DROPS A SITE'S CACHED PAGES (AGL-3080).\n *\n * The shell hands this one down rather than up. Every other contract in this\n * directory is a plugin telling the shell something; this is the shell\n * telling plugins it can do something — purge the rendered HTML of a site —\n * because purging it takes the tenant's cache tags and revalidation paths,\n * which live in the app and are not a plugin's to know.\n *\n * ## The case, and why it is a kill switch rather than a nicety\n *\n * A marketplace plugin can be REVOKED. Revoking writes a stop on the\n * version, and the tenant refuses revoked bytes at render time — but a page\n * already rendered and cached does not re-render to find that out. So the\n * revoke has a second half: drop the cached pages of every site running it.\n * Without it a revoked plugin keeps executing in visitors' browsers for as\n * long as the cache holds, which is the whole failure the stop exists to\n * prevent.\n *\n * ## ⛔ AN ABSENT IMPLEMENTATION IS AN ANSWER, AND IT IS `complete: false`\n *\n * The registry is filled by the APP at boot. A process that has not filled\n * it resolves \"no cache to drop\" — indistinguishable, from the inside, from\n * a workspace whose sites were all already fresh. That is the AGL-3025 shape\n * and on this path it means a revoked plugin quietly kept serving.\n *\n * So there is no silent branch. {@link dropPluginSiteCache} always answers a\n * {@link PluginSiteCacheResult}, and `complete` is false whenever the drop\n * did not certainly happen — nothing registered, or the implementation\n * threw. A caller acts on that: the revoke itself must still stand (a plugin\n * left un-revoked because a cache purge failed is strictly worse), but the\n * reader has to be told the purge did not run, and the log has to carry it.\n *\n * ## The split, in one line\n *\n * The plugin knows WHICH sites — that is its own install pins, its own\n * collection. The shell knows HOW to drop one, and owns the fan-out policy:\n * the cap, the concurrency, and saying out loud when a cap truncated the\n * list. Neither half is guessable from the other side.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** What the caller wants dropped, and why. */\nexport interface PluginSiteCacheRequest {\n  /**\n   * The sites whose rendered pages must go. Duplicates are the caller's to\n   * avoid or not — the implementation is free to collapse them.\n   */\n  hostIds: readonly string[]\n  /**\n   * Why, in a few words, for the fan-out's own logging: a truncated purge\n   * is only debuggable if the record says what it was purging for.\n   * `'marketplace listing revoked'`, not `'revoke'`.\n   */\n  reason: string\n}\n\nexport interface PluginSiteCacheResult {\n  /** Sites whose cached pages were dropped. */\n  dropped: number\n  /**\n   * Sites deliberately left holding cached pages because the fan-out hit\n   * its cap. Not an error — a decision the shell made and logged — but a\n   * number a caller may want to surface, because those sites are still\n   * serving what was just stopped.\n   */\n  skipped: number\n  /**\n   * Whether the drop certainly happened. FALSE when no implementation is\n   * registered or one threw, and a caller must not read `dropped: 0` as\n   * \"there was nothing to drop\" without checking this first.\n   */\n  complete: boolean\n}\n\nexport interface PluginSiteCache {\n  drop(request: PluginSiteCacheRequest): Promise<PluginSiteCacheResult>\n}\n\n/**\n * One implementation: the app's. Two would be two cache layers disagreeing\n * about whether a page is gone, and the second to register would be the one\n * nobody knew about.\n */\nexport const PLUGIN_SITE_CACHE = definePluginServiceContract<PluginSiteCache>(\n  'core.site-cache',\n  { multiple: false },\n)\n\n/**\n * Installs the app's implementation. Called once, at server boot, by the app\n * that owns the tenant's cache.\n *\n * `pluginId` is required from outside a plugin's register fn, as it is for\n * every service: the app passes its own marker, and the contract refuses an\n * anonymous registration rather than accepting one nothing can be traced to.\n */\nexport function registerPluginSiteCache(\n  cache: PluginSiteCache,\n  options?: { pluginId?: string },\n): void {\n  if (typeof cache?.drop !== 'function') {\n    throw new Error('a site cache needs a drop function')\n  }\n  registerPluginService(PLUGIN_SITE_CACHE, cache, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Whether an implementation is installed — for a caller that wants to say so. */\nexport function hasPluginSiteCache(): boolean {\n  return Boolean(resolvePluginService(PLUGIN_SITE_CACHE))\n}\n\n/**\n * Drops the cached pages of the named sites.\n *\n * NEVER THROWS and never silently succeeds: a failure comes back as\n * `complete: false` with the reason logged, because the callers are stop\n * paths that must complete their own work either way. Read `complete`\n * before reading `dropped`.\n */\nexport async function dropPluginSiteCache(\n  request: PluginSiteCacheRequest,\n): Promise<PluginSiteCacheResult> {\n  const hostIds = [...new Set(request.hostIds.filter(Boolean))]\n  if (!hostIds.length) {\n    // Nothing asked for is the one case where \"nothing dropped\" is complete\n    // on its own terms, whether or not anything is registered.\n    return { dropped: 0, skipped: 0, complete: true }\n  }\n  const cache = resolvePluginService(PLUGIN_SITE_CACHE)\n  if (!cache) {\n    console.error(\n      `[site-cache] no implementation is installed, so ${hostIds.length} ` +\n        `site(s) keep their cached pages after: ${request.reason}. The app ` +\n        'registers this at boot; a process that has not is serving stopped ' +\n        'content.',\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n  try {\n    return await cache.drop({ ...request, hostIds })\n  } catch (error) {\n    console.error(\n      `[site-cache] the drop failed after: ${request.reason}`,\n      error,\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_SITE_CACHE","multiple","registerPluginSiteCache","cache","options","drop","Error","pluginId","hasPluginSiteCache","Boolean","dropPluginSiteCache","request","hostIds","Set","filter","length","dropped","skipped","complete","console","error","reason"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAwC1B;;;;CAIC,GACD,OAAO,MAAMC,oBAAoBH,4BAC/B,mBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;;;CAOC,GACD,OAAO,SAASC,wBACdC,KAAsB,EACtBC,OAA+B;IAE/B,IAAI,QAAOD,yBAAAA,MAAOE,IAAI,MAAK,YAAY;QACrC,MAAM,IAAIC,MAAM;IAClB;IACAR,sBAAsBE,mBAAmBG,OAAO,aAC1CC,CAAAA,2BAAAA,QAASG,QAAQ,IAAG;QAAEA,UAAUH,QAAQG,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,gFAAgF,GAChF,OAAO,SAASC;IACd,OAAOC,QAAQV,qBAAqBC;AACtC;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeU,oBACpBC,OAA+B;IAE/B,MAAMC,UAAU;WAAI,IAAIC,IAAIF,QAAQC,OAAO,CAACE,MAAM,CAACL;KAAU;IAC7D,IAAI,CAACG,QAAQG,MAAM,EAAE;QACnB,wEAAwE;QACxE,2DAA2D;QAC3D,OAAO;YAAEC,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAK;IAClD;IACA,MAAMf,QAAQJ,qBAAqBC;IACnC,IAAI,CAACG,OAAO;QACVgB,QAAQC,KAAK,CACX,CAAC,gDAAgD,EAAER,QAAQG,MAAM,CAAC,CAAC,CAAC,GAClE,CAAC,uCAAuC,EAAEJ,QAAQU,MAAM,CAAC,UAAU,CAAC,GACpE,uEACA;QAEJ,OAAO;YAAEL,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;IACA,IAAI;QACF,OAAO,MAAMf,MAAME,IAAI,CAAC,aAAKM;YAASC;;IACxC,EAAE,OAAOQ,OAAO;QACdD,QAAQC,KAAK,CACX,CAAC,oCAAoC,EAAET,QAAQU,MAAM,EAAE,EACvDD;QAEF,OAAO;YAAEJ,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;AACF"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-cache.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 * HOW A PLUGIN DROPS A SITE'S CACHED PAGES (AGL-3080).\n *\n * The shell hands this one down rather than up. Every other contract in this\n * directory is a plugin telling the shell something; this is the shell\n * telling plugins it can do something — purge the rendered HTML of a site —\n * because purging it takes the tenant's cache tags and revalidation paths,\n * which live in the app and are not a plugin's to know.\n *\n * ## The case, and why it is a kill switch rather than a nicety\n *\n * A marketplace plugin can be REVOKED. Revoking writes a stop on the\n * version, and the tenant refuses revoked bytes at render time — but a page\n * already rendered and cached does not re-render to find that out. So the\n * revoke has a second half: drop the cached pages of every site running it.\n * Without it a revoked plugin keeps executing in visitors' browsers for as\n * long as the cache holds, which is the whole failure the stop exists to\n * prevent.\n *\n * ## ⛔ AN ABSENT IMPLEMENTATION IS AN ANSWER, AND IT IS `complete: false`\n *\n * The registry is filled by the APP at boot. A process that has not filled\n * it resolves \"no cache to drop\" — indistinguishable, from the inside, from\n * a workspace whose sites were all already fresh. That is the AGL-3025 shape\n * and on this path it means a revoked plugin quietly kept serving.\n *\n * So there is no silent branch. {@link dropPluginSiteCache} always answers a\n * {@link PluginSiteCacheResult}, and `complete` is false whenever the drop\n * did not certainly happen — nothing registered, or the implementation\n * threw. A caller acts on that: the revoke itself must still stand (a plugin\n * left un-revoked because a cache purge failed is strictly worse), but the\n * reader has to be told the purge did not run, and the log has to carry it.\n *\n * ## The split, in one line\n *\n * The plugin knows WHICH sites — that is its own install pins, its own\n * collection. The shell knows HOW to drop one, and owns the fan-out policy:\n * the cap, the concurrency, and saying out loud when a cap truncated the\n * list. Neither half is guessable from the other side.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** What the caller wants dropped, and why. */\nexport interface PluginSiteCacheRequest {\n  /**\n   * The sites whose rendered pages must go. Duplicates are the caller's to\n   * avoid or not — the implementation is free to collapse them.\n   */\n  hostIds: readonly string[]\n  /**\n   * Why, in a few words, for the fan-out's own logging: a truncated purge\n   * is only debuggable if the record says what it was purging for.\n   * `'marketplace listing revoked'`, not `'revoke'`.\n   */\n  reason: string\n  /**\n   * Narrows a site's drop to the pages that changed: its site-absolute\n   * addresses (`/`, `/contact`), keyed by site id. A site named here loses\n   * only those pages, and one named with an empty list loses none; a site\n   * not named here loses every page it serves.\n   *\n   * For a change the plugin can place exactly — a document it publishes that\n   * renders on the pages that place it — rather than one that reaches every\n   * page, like a revoked bundle. The plugin knows which pages; the app knows\n   * how to drop one, on every address the site answers at.\n   */\n  paths?: Readonly<Record<string, readonly string[]>>\n}\n\nexport interface PluginSiteCacheResult {\n  /** Sites whose cached pages were dropped. */\n  dropped: number\n  /**\n   * Sites deliberately left holding cached pages because the fan-out hit\n   * its cap. Not an error — a decision the shell made and logged — but a\n   * number a caller may want to surface, because those sites are still\n   * serving what was just stopped.\n   */\n  skipped: number\n  /**\n   * Whether the drop certainly happened. FALSE when no implementation is\n   * registered or one threw, and a caller must not read `dropped: 0` as\n   * \"there was nothing to drop\" without checking this first.\n   */\n  complete: boolean\n}\n\nexport interface PluginSiteCache {\n  drop(request: PluginSiteCacheRequest): Promise<PluginSiteCacheResult>\n}\n\n/**\n * One implementation: the app's. Two would be two cache layers disagreeing\n * about whether a page is gone, and the second to register would be the one\n * nobody knew about.\n */\nexport const PLUGIN_SITE_CACHE = definePluginServiceContract<PluginSiteCache>(\n  'core.site-cache',\n  { multiple: false },\n)\n\n/**\n * Installs the app's implementation. Called once, at server boot, by the app\n * that owns the tenant's cache.\n *\n * `pluginId` is required from outside a plugin's register fn, as it is for\n * every service: the app passes its own marker, and the contract refuses an\n * anonymous registration rather than accepting one nothing can be traced to.\n */\nexport function registerPluginSiteCache(\n  cache: PluginSiteCache,\n  options?: { pluginId?: string },\n): void {\n  if (typeof cache?.drop !== 'function') {\n    throw new Error('a site cache needs a drop function')\n  }\n  registerPluginService(PLUGIN_SITE_CACHE, cache, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** Whether an implementation is installed — for a caller that wants to say so. */\nexport function hasPluginSiteCache(): boolean {\n  return Boolean(resolvePluginService(PLUGIN_SITE_CACHE))\n}\n\n/**\n * Drops the cached pages of the named sites.\n *\n * NEVER THROWS and never silently succeeds: a failure comes back as\n * `complete: false` with the reason logged, because the callers are stop\n * paths that must complete their own work either way. Read `complete`\n * before reading `dropped`.\n */\nexport async function dropPluginSiteCache(\n  request: PluginSiteCacheRequest,\n): Promise<PluginSiteCacheResult> {\n  const hostIds = [...new Set(request.hostIds.filter(Boolean))]\n  if (!hostIds.length) {\n    // Nothing asked for is the one case where \"nothing dropped\" is complete\n    // on its own terms, whether or not anything is registered.\n    return { dropped: 0, skipped: 0, complete: true }\n  }\n  const cache = resolvePluginService(PLUGIN_SITE_CACHE)\n  if (!cache) {\n    console.error(\n      `[site-cache] no implementation is installed, so ${hostIds.length} ` +\n        `site(s) keep their cached pages after: ${request.reason}. The app ` +\n        'registers this at boot; a process that has not is serving stopped ' +\n        'content.',\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n  try {\n    return await cache.drop({ ...request, hostIds })\n  } catch (error) {\n    console.error(\n      `[site-cache] the drop failed after: ${request.reason}`,\n      error,\n    )\n    return { dropped: 0, skipped: 0, complete: false }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_SITE_CACHE","multiple","registerPluginSiteCache","cache","options","drop","Error","pluginId","hasPluginSiteCache","Boolean","dropPluginSiteCache","request","hostIds","Set","filter","length","dropped","skipped","complete","console","error","reason"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAoD1B;;;;CAIC,GACD,OAAO,MAAMC,oBAAoBH,4BAC/B,mBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;;;CAOC,GACD,OAAO,SAASC,wBACdC,KAAsB,EACtBC,OAA+B;IAE/B,IAAI,QAAOD,yBAAAA,MAAOE,IAAI,MAAK,YAAY;QACrC,MAAM,IAAIC,MAAM;IAClB;IACAR,sBAAsBE,mBAAmBG,OAAO,aAC1CC,CAAAA,2BAAAA,QAASG,QAAQ,IAAG;QAAEA,UAAUH,QAAQG,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,gFAAgF,GAChF,OAAO,SAASC;IACd,OAAOC,QAAQV,qBAAqBC;AACtC;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeU,oBACpBC,OAA+B;IAE/B,MAAMC,UAAU;WAAI,IAAIC,IAAIF,QAAQC,OAAO,CAACE,MAAM,CAACL;KAAU;IAC7D,IAAI,CAACG,QAAQG,MAAM,EAAE;QACnB,wEAAwE;QACxE,2DAA2D;QAC3D,OAAO;YAAEC,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAK;IAClD;IACA,MAAMf,QAAQJ,qBAAqBC;IACnC,IAAI,CAACG,OAAO;QACVgB,QAAQC,KAAK,CACX,CAAC,gDAAgD,EAAER,QAAQG,MAAM,CAAC,CAAC,CAAC,GAClE,CAAC,uCAAuC,EAAEJ,QAAQU,MAAM,CAAC,UAAU,CAAC,GACpE,uEACA;QAEJ,OAAO;YAAEL,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;IACA,IAAI;QACF,OAAO,MAAMf,MAAME,IAAI,CAAC,aAAKM;YAASC;;IACxC,EAAE,OAAOQ,OAAO;QACdD,QAAQC,KAAK,CACX,CAAC,oCAAoC,EAAET,QAAQU,MAAM,EAAE,EACvDD;QAEF,OAAO;YAAEJ,SAAS;YAAGC,SAAS;YAAGC,UAAU;QAAM;IACnD;AACF"}

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

@@ -0,0 +1,81 @@
+/**
+ * @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 plugin's host collection in the platform's whole-site backup (AGL-3080).
+ *
+ * `/api/hosts/export` writes one JSON bundle of everything designable on a
+ * site and `/api/hosts/import` restores it (AGL-163). The platform's own
+ * documents — screens, layouts, components, authors, content collections,
+ * media — are the routes' to carry. A plugin whose site documents belong in
+ * a backup declares so beside the collection, in the `hostCollections` block
+ * of `plugins.config.json` (a host collection's `siteExport`), and both
+ * routes walk the declarations: the export reads up to `limit` live documents
+ * into the bundle under the collection's own name, and the restore writes each
+ * one back through `fields` and counts the result against the collection's
+ * declared `resource`.
+ *
+ * ## `fields` is the round trip, not the create
+ *
+ * A restore writes with `merge: false`, so the list is every key a live
+ * document carries — which can be narrower than what a create admits, and is
+ * often wider — and a key left off is ERASED from every restored document
+ * (AGL-1382). Nothing the restore stamps (`createdAt`, `updatedAt`,
+ * `deletedAt`) or scopes (`visibleTo`) is on it; the generator refuses them.
+ *
+ * ## Compiled, and counted
+ *
+ * A backup that silently lacks a collection is worse than a failed one: the
+ * file looks whole until the day it is restored. So the declarations are
+ * compiled, present the moment this module is imported, and a runtime
+ * `registerPluginHostCollections` carrying a `siteExport` throws. A restore
+ * creates documents with the Admin SDK, past the rules, so the generator also
+ * refuses a `siteExport` on a collection with no `resource`: the resource's
+ * plan counter or flat platform cap is what the restore is met against.
+ *
+ * Reached by its own subpath, never the barrel: its readers are the two
+ * console routes.
+ */
+export interface PluginHostCollectionSiteExport {
+    /** The most live documents one bundle carries; a restore writes no more. */
+    limit: number;
+    /** The keys a restore writes back. Anything else a bundle carries is dropped. */
+    fields: readonly string[];
+}
+/** What a restore of a declared collection is counted against. */
+export type PluginSiteExportCount = 
+/** A plan counter, an `OrgEntitlements` key core resolves. */
+{
+    quotaKey: string;
+}
+/**
+ * A flat platform cap, resolved from the name the resource declares, or
+ * `null` for a name core does not hold — which a restore refuses.
+ */
+ | {
+    max: number | null;
+};
+/** A declared collection with the plugin that made it and its count. */
+export interface ResolvedPluginSiteExportCollection extends PluginHostCollectionSiteExport {
+    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;
+}
+/** 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

@@ -0,0 +1,40 @@
+/**
+ * @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 { PLUGIN_HOST_COLLECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+import { hostResourcePlatformCap } from "./plugin-host-resources.js";
+/** 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;
+        const { siteExport, resource } = row;
+        if (!siteExport || !resource) continue;
+        out.push({
+            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 : '')
+            }
+        });
+    }
+    return out;
+}
+
+//# sourceMappingURL=plugin-site-export.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,88 @@
+/**
+ * @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 child sitemap a plugin's documents fill, declared by that plugin
+ * (AGL-3080).
+ *
+ * The tenant's `/sitemap.xml` is an index over one child per section (AGL-2520):
+ * the site's pages, its content collections and its authors are the platform's
+ * and are built by the route itself. A plugin that serves pages of its own — a
+ * product at `/products/{slug}` — had its section written into that route by
+ * hand: the collection, the filter, the store setting that switches it on, the
+ * address and the date field were all core's knowledge of one plugin's model.
+ *
+ * So the plugin declares the section, and the route builds every declared one
+ * the same way: counted for the index, paged by document id for the child.
+ *
+ * ## Compiled, because the reader is a published page's
+ *
+ * The sitemap is what a search engine is told the site holds. A section
+ * registered at runtime would be missing from any process that had not loaded
+ * the plugin, and a crawler reads a missing section as pages that no longer
+ * exist — the products drop out of the index silently, on a live site. So
+ * sections are compiled from `plugins.config.json` by
+ * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this
+ * module is imported, and there is no registrar.
+ *
+ * ## What a declaration can say
+ *
+ * Only what a sitemap needs and a query can express: one equality filter, the
+ * setting that must be set for the pages to render at all, the address with
+ * `{slug}` in it, a field that drops a row (a soft delete), and the date
+ * fields to try in order. A row without a slug addresses nothing and is left
+ * out. Anything richer belongs to the plugin's own page, not to its sitemap.
+ *
+ * Reached by its own subpath, never the barrel.
+ */
+export interface PluginSitemapSectionDeclaration {
+    /** The section's path segment: `/sitemaps/{section}/{page}.xml`. */
+    section: string;
+    /** The subcollection under `hosts/{hostId}` whose documents are the pages. */
+    collection: string;
+    /** The one equality a document must meet to be a page. */
+    where?: {
+        field: string;
+        equals: string | number | boolean;
+    };
+    /**
+     * A `collection/doc` under the host and a field on it that must be set for
+     * the section to exist: the template the pages render through. Unset, the
+     * section is left out rather than listing addresses that 404.
+     */
+    enabledBy?: {
+        doc: string;
+        field: string;
+    };
+    /** The page's site path, with `{slug}` standing for the document's slug. */
+    path: string;
+    /** The field holding the slug; `slug` when absent. */
+    slugField?: string;
+    /** A field whose truthy value leaves the row out, for a soft delete the filter cannot see. */
+    skipWhen?: string;
+    /** The fields a row's `lastmod` is read from, first present wins. */
+    lastmod?: readonly string[];
+}
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginSitemapSection = PluginSitemapSectionDeclaration & {
+    pluginId: string;
+};
+/** Every declared section, in config order — the order the index lists them. */
+export declare function listPluginSitemapSections(): readonly ResolvedPluginSitemapSection[];
+/** One declared section by its name, or `null`. */
+export declare function pluginSitemapSection(section: string): ResolvedPluginSitemapSection | null;
+/** The site path of one row, or `null` for a row with no slug. */
+export declare function pluginSitemapSectionPath(declaration: PluginSitemapSectionDeclaration, slug: unknown): string | null;

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

@@ -0,0 +1,29 @@
+/**
+ * @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 { PLUGIN_SITEMAP_SECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+/** Every declared section, in config order — the order the index lists them. */ export function listPluginSitemapSections() {
+    return PLUGIN_SITEMAP_SECTIONS_DECLARED;
+}
+/** One declared section by its name, or `null`. */ export function pluginSitemapSection(section) {
+    var _PLUGIN_SITEMAP_SECTIONS_DECLARED_find;
+    return (_PLUGIN_SITEMAP_SECTIONS_DECLARED_find = PLUGIN_SITEMAP_SECTIONS_DECLARED.find((one)=>one.section === section)) != null ? _PLUGIN_SITEMAP_SECTIONS_DECLARED_find : null;
+}
+/** The site path of one row, or `null` for a row with no slug. */ export function pluginSitemapSectionPath(declaration, slug) {
+    if (typeof slug !== 'string' || !slug) return null;
+    return declaration.path.replace('{slug}', slug);
+}
+
+//# sourceMappingURL=plugin-sitemap-sections.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-sitemap-sections.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_SITEMAP_SECTIONS_DECLARED } from './first-party-plugins.generated'\n\n/**\n * A child sitemap a plugin's documents fill, declared by that plugin\n * (AGL-3080).\n *\n * The tenant's `/sitemap.xml` is an index over one child per section (AGL-2520):\n * the site's pages, its content collections and its authors are the platform's\n * and are built by the route itself. A plugin that serves pages of its own — a\n * product at `/products/{slug}` — had its section written into that route by\n * hand: the collection, the filter, the store setting that switches it on, the\n * address and the date field were all core's knowledge of one plugin's model.\n *\n * So the plugin declares the section, and the route builds every declared one\n * the same way: counted for the index, paged by document id for the child.\n *\n * ## Compiled, because the reader is a published page's\n *\n * The sitemap is what a search engine is told the site holds. A section\n * registered at runtime would be missing from any process that had not loaded\n * the plugin, and a crawler reads a missing section as pages that no longer\n * exist — the products drop out of the index silently, on a live site. So\n * sections are compiled from `plugins.config.json` by\n * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this\n * module is imported, and there is no registrar.\n *\n * ## What a declaration can say\n *\n * Only what a sitemap needs and a query can express: one equality filter, the\n * setting that must be set for the pages to render at all, the address with\n * `{slug}` in it, a field that drops a row (a soft delete), and the date\n * fields to try in order. A row without a slug addresses nothing and is left\n * out. Anything richer belongs to the plugin's own page, not to its sitemap.\n *\n * Reached by its own subpath, never the barrel.\n */\nexport interface PluginSitemapSectionDeclaration {\n  /** The section's path segment: `/sitemaps/{section}/{page}.xml`. */\n  section: string\n  /** The subcollection under `hosts/{hostId}` whose documents are the pages. */\n  collection: string\n  /** The one equality a document must meet to be a page. */\n  where?: { field: string; equals: string | number | boolean }\n  /**\n   * A `collection/doc` under the host and a field on it that must be set for\n   * the section to exist: the template the pages render through. Unset, the\n   * section is left out rather than listing addresses that 404.\n   */\n  enabledBy?: { doc: string; field: string }\n  /** The page's site path, with `{slug}` standing for the document's slug. */\n  path: string\n  /** The field holding the slug; `slug` when absent. */\n  slugField?: string\n  /** A field whose truthy value leaves the row out, for a soft delete the filter cannot see. */\n  skipWhen?: string\n  /** The fields a row's `lastmod` is read from, first present wins. */\n  lastmod?: readonly string[]\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginSitemapSection = PluginSitemapSectionDeclaration & {\n  pluginId: string\n}\n\n/** Every declared section, in config order — the order the index lists them. */\nexport function listPluginSitemapSections(): readonly ResolvedPluginSitemapSection[] {\n  return PLUGIN_SITEMAP_SECTIONS_DECLARED\n}\n\n/** One declared section by its name, or `null`. */\nexport function pluginSitemapSection(\n  section: string,\n): ResolvedPluginSitemapSection | null {\n  return PLUGIN_SITEMAP_SECTIONS_DECLARED.find((one) => one.section === section) ?? null\n}\n\n/** The site path of one row, or `null` for a row with no slug. */\nexport function pluginSitemapSectionPath(\n  declaration: PluginSitemapSectionDeclaration,\n  slug: unknown,\n): string | null {\n  if (typeof slug !== 'string' || !slug) return null\n  return declaration.path.replace('{slug}', slug)\n}\n"],"names":["PLUGIN_SITEMAP_SECTIONS_DECLARED","listPluginSitemapSections","pluginSitemapSection","section","find","one","pluginSitemapSectionPath","declaration","slug","path","replace"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gCAAgC,QAAQ,qCAAiC;AAgElF,8EAA8E,GAC9E,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,iDAAiD,GACjD,OAAO,SAASE,qBACdC,OAAe;QAERH;IAAP,QAAOA,yCAAAA,iCAAiCI,IAAI,CAAC,CAACC,MAAQA,IAAIF,OAAO,KAAKA,oBAA/DH,yCAA2E;AACpF;AAEA,gEAAgE,GAChE,OAAO,SAASM,yBACdC,WAA4C,EAC5CC,IAAa;IAEb,IAAI,OAAOA,SAAS,YAAY,CAACA,MAAM,OAAO;IAC9C,OAAOD,YAAYE,IAAI,CAACC,OAAO,CAAC,UAAUF;AAC5C"}

package/src/lib/plugin-manager/plugin-subscription-topics.generated.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GENERATED FILE — do not edit. Regenerate with:
+ *   node tools/scripts/generate-plugin-manifests.mjs
+ *
+ * The subscription topics plugins declare (AGL-3080): each plugin's
+ * `subscriptionTopics` block in plugins.config.json, in preference-page
+ * order. Core's `app-utils/subscription-topics.ts` reads them as the
+ * built-in floor of every org's topic catalog; core names no stream.
+ */
+import type { DeclaredSubscriptionTopic } from '../app-utils/subscription-topics';
+export declare const PLUGIN_SUBSCRIPTION_TOPICS_DECLARED: readonly DeclaredSubscriptionTopic[];

package/src/lib/plugin-manager/plugin-subscription-topics.generated.js

@@ -0,0 +1,41 @@
+/**
+ * GENERATED FILE — do not edit. Regenerate with:
+ *   node tools/scripts/generate-plugin-manifests.mjs
+ *
+ * The subscription topics plugins declare (AGL-3080): each plugin's
+ * `subscriptionTopics` block in plugins.config.json, in preference-page
+ * order. Core's `app-utils/subscription-topics.ts` reads them as the
+ * built-in floor of every org's topic catalog; core names no stream.
+ */ export const PLUGIN_SUBSCRIPTION_TOPICS_DECLARED = [
+    {
+        "pluginId": "marketing",
+        "id": "marketing",
+        "name": "Promotions and offers",
+        "description": "Sales, discounts and seasonal campaigns.",
+        "order": 10,
+        "default": true
+    },
+    {
+        "pluginId": "commerce",
+        "id": "newsletter",
+        "name": "Newsletter",
+        "description": "Regular news and stories from us.",
+        "order": 20
+    },
+    {
+        "pluginId": "commerce",
+        "id": "product-updates",
+        "name": "Product updates",
+        "description": "New products, restocks and changes to what we offer.",
+        "order": 30
+    },
+    {
+        "pluginId": "outreach",
+        "id": "sales",
+        "name": "Sales outreach",
+        "description": "Messages from a person here about working together.",
+        "order": 40
+    }
+];
+
+//# sourceMappingURL=plugin-subscription-topics.generated.js.map