@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/plugin-manager/plugin-revenue-sources.js

@@ -0,0 +1,194 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT A PLUGIN EARNED THE OPERATOR, ON THE STAFF REVENUE REPORT (AGL-3080).
+ *
+ * The operator's revenue report states what the deployment actually kept in a
+ * period. Its own subscription invoices are platform billing and the report
+ * folds them itself. A plugin that sells through the platform's account — a
+ * storefront's application fee, a marketplace's commission — earns the
+ * operator a take the report cannot compute without knowing that plugin's
+ * storage and its fee rules, and it has no business restating either.
+ *
+ * So the division is: the REPORT is the platform's — the period, the two
+ * bases, the gap, the sweep ceiling, the read budget for names and the page.
+ * What a plugin's sales earned, net of what is not the operator's, and who
+ * produced it, are the plugin's. A source answers one period with a
+ * {@link RevenueSourceAnswer}: its earned line, its gross-to-net lines, its
+ * qualifications, its attribution tables and its own settled figures.
+ *
+ * ## ⛔ AN UNREAD SOURCE IS NEVER A ZERO
+ *
+ * A source that answered nothing reads, on a total, exactly like one that
+ * earned nothing, and a revenue total quoted short is a figure somebody
+ * repeats. So, as the tax return's sources do:
+ *
+ * - every plugin that earns through the platform declares
+ *   `"revenueSource": true` in `plugins.config.json`, compiled into
+ *   {@link PLUGIN_REVENUE_SOURCES}; a declared plugin with no registration, a
+ *   source that threw and a malformed answer each come back
+ *   `outcome: 'refused'`, and the page says whose earnings are missing;
+ * - a source whose own read could not run answers with `failure` and figures
+ *   it does NOT claim, and one whose sweep stopped at the ceiling answers
+ *   `truncated` — the page names both rather than quoting the total.
+ *
+ * {@link readRevenueSources} never throws and never drops a declared source.
+ * The reader is the staff revenue route, which awaits `ensureAll` on the
+ * `consoleApi` surface before it asks.
+ */ import { PLUGIN_REVENUE_SOURCES } from "./first-party-plugins.generated.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export { PLUGIN_REVENUE_SOURCES };
+/** Every source answers; one per plugin. */ export const REVENUE_SOURCES = definePluginServiceContract('core.revenue-sources', {
+    multiple: true
+});
+/** Installs a plugin's source; registering again replaces it. */ export function registerRevenueSource(source, options) {
+    if (typeof (source == null ? void 0 : source.read) !== 'function') {
+        throw new Error('a revenue source needs a read function');
+    }
+    registerPluginService(REVENUE_SOURCES, source, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The plugins with a registered source, in the order they answer. */ export function listRevenueSources() {
+    return resolvePluginServices(REVENUE_SOURCES).map((entry)=>entry.pluginId);
+}
+/**
+ * Group, sort and cap — every attribution table's shared half.
+ *
+ * A row whose key is missing is NOT dropped. It is grouped under an explicit
+ * unattributed key, because a sale nobody can attribute still happened and
+ * dropping it would make the rows sum below the total — the one property that
+ * makes any of these tables worth reading. The cap carries its remainder as
+ * FIGURES, so the table stays a complete accounting even when it is not a
+ * complete list.
+ */ export function groupRevenueAttribution(entries, limit, unattributedLabel) {
+    const byKey = new Map();
+    for (const entry of entries != null ? entries : []){
+        var _byKey_get, _entry_detail;
+        const key = entry.key || unattributedLabel;
+        const row = (_byKey_get = byKey.get(key)) != null ? _byKey_get : {
+            key,
+            name: key === unattributedLabel ? unattributedLabel : key,
+            detail: (_entry_detail = entry.detail) != null ? _entry_detail : '',
+            gainCents: 0,
+            lossCents: 0,
+            count: 0
+        };
+        row.gainCents += entry.gain;
+        row.lossCents += entry.loss;
+        row.count += 1;
+        if (!row.detail && entry.detail) row.detail = entry.detail;
+        byKey.set(key, row);
+    }
+    const rows = [
+        ...byKey.values()
+    ].sort((a, b)=>b.gainCents - a.gainCents || b.lossCents - a.lossCents || a.key.localeCompare(b.key));
+    const kept = rows.slice(0, Math.max(0, limit));
+    const dropped = rows.slice(Math.max(0, limit));
+    return {
+        rows: kept,
+        omittedRows: dropped.length,
+        omittedGainCents: dropped.reduce((sum, row)=>sum + row.gainCents, 0),
+        omittedLossCents: dropped.reduce((sum, row)=>sum + row.lossCents, 0)
+    };
+}
+const isText = (value)=>typeof value === 'string' && value.trim().length > 0;
+/** What is wrong with an answer, or null when it can be printed. */ function malformed(answer) {
+    var _answer_earned, _answer_earned1;
+    if (!answer || typeof answer !== 'object') return 'no report';
+    if (!isText(answer.id) || !isText(answer.name)) return 'a report with no id or name';
+    const cents = (_answer_earned = answer.earned) == null ? void 0 : _answer_earned.cents;
+    if (typeof cents !== 'number' || !Number.isFinite(cents)) return 'no earned figure';
+    if (!isText((_answer_earned1 = answer.earned) == null ? void 0 : _answer_earned1.label)) return 'an earned figure with no label';
+    if (typeof answer.truncated !== 'boolean') return 'no truncation flag';
+    for (const key of [
+        'grossToNet',
+        'notes',
+        'attribution'
+    ]){
+        if (!Array.isArray(answer[key])) return `no ${key}`;
+    }
+    const badLine = answer.grossToNet.find((line)=>typeof (line == null ? void 0 : line.cents) !== 'number' || !Number.isFinite(line.cents));
+    if (badLine) return 'a gross-to-net line with no figure';
+    return null;
+}
+/**
+ * Every source's answer for one period — declared sources first, in the
+ * compiled order, then any other registered source.
+ *
+ * NEVER THROWS and never drops a declared source. `declared` is the compiled
+ * {@link PLUGIN_REVENUE_SOURCES} unless a spec passes its own.
+ */ export async function readRevenueSources(request, declared = PLUGIN_REVENUE_SOURCES) {
+    const registered = resolvePluginServices(REVENUE_SOURCES);
+    const order = [
+        ...declared,
+        ...registered.map((entry)=>entry.pluginId).filter((pluginId)=>!declared.includes(pluginId))
+    ].filter((pluginId, index, all)=>all.indexOf(pluginId) === index);
+    const answers = await Promise.all(order.map(async (pluginId)=>{
+        var _registered_find;
+        const source = (_registered_find = registered.find((entry)=>entry.pluginId === pluginId)) == null ? void 0 : _registered_find.impl;
+        if (!source) {
+            console.error(`[revenue] "${pluginId}" declares a revenue source and none is ` + 'registered in this process; its earnings cannot be read.');
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin earns through the platform and registered ` + 'nothing to read its earnings with.'
+            };
+        }
+        try {
+            const answer = await source.read(request);
+            const problem = malformed(answer);
+            if (problem) {
+                return {
+                    outcome: 'refused',
+                    pluginId,
+                    id: pluginId,
+                    reason: `The “${pluginId}” plugin answered ${problem}.`
+                };
+            }
+            return _extends({}, answer, {
+                outcome: 'answered',
+                pluginId
+            });
+        } catch (error) {
+            console.error(`[revenue] "${pluginId}" failed to read its earnings`, error);
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin could not read its earnings for this period.`
+            };
+        }
+    }));
+    const seen = new Set();
+    return answers.map((section)=>{
+        if (section.outcome !== 'answered') return section;
+        if (!seen.has(section.id)) {
+            seen.add(section.id);
+            return section;
+        }
+        return {
+            outcome: 'refused',
+            pluginId: section.pluginId,
+            id: section.pluginId,
+            reason: `The “${section.pluginId}” plugin answered as “${section.id}”, which ` + 'another source already is.'
+        };
+    });
+}
+
+//# sourceMappingURL=plugin-revenue-sources.js.map

package/src/lib/plugin-manager/plugin-revenue-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-revenue-sources.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 * WHAT A PLUGIN EARNED THE OPERATOR, ON THE STAFF REVENUE REPORT (AGL-3080).\n *\n * The operator's revenue report states what the deployment actually kept in a\n * period. Its own subscription invoices are platform billing and the report\n * folds them itself. A plugin that sells through the platform's account — a\n * storefront's application fee, a marketplace's commission — earns the\n * operator a take the report cannot compute without knowing that plugin's\n * storage and its fee rules, and it has no business restating either.\n *\n * So the division is: the REPORT is the platform's — the period, the two\n * bases, the gap, the sweep ceiling, the read budget for names and the page.\n * What a plugin's sales earned, net of what is not the operator's, and who\n * produced it, are the plugin's. A source answers one period with a\n * {@link RevenueSourceAnswer}: its earned line, its gross-to-net lines, its\n * qualifications, its attribution tables and its own settled figures.\n *\n * ## ⛔ AN UNREAD SOURCE IS NEVER A ZERO\n *\n * A source that answered nothing reads, on a total, exactly like one that\n * earned nothing, and a revenue total quoted short is a figure somebody\n * repeats. So, as the tax return's sources do:\n *\n * - every plugin that earns through the platform declares\n *   `\"revenueSource\": true` in `plugins.config.json`, compiled into\n *   {@link PLUGIN_REVENUE_SOURCES}; a declared plugin with no registration, a\n *   source that threw and a malformed answer each come back\n *   `outcome: 'refused'`, and the page says whose earnings are missing;\n * - a source whose own read could not run answers with `failure` and figures\n *   it does NOT claim, and one whose sweep stopped at the ceiling answers\n *   `truncated` — the page names both rather than quoting the total.\n *\n * {@link readRevenueSources} never throws and never drops a declared source.\n * The reader is the staff revenue route, which awaits `ensureAll` on the\n * `consoleApi` surface before it asks.\n */\n\nimport { PLUGIN_REVENUE_SOURCES } from './first-party-plugins.generated'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\nexport { PLUGIN_REVENUE_SOURCES }\n\n/**\n * Pages a query to exhaustion under the operator's ceiling. The ceiling is the\n * platform's policy about its own request, so a source is handed the sweep\n * rather than choosing one; `truncated` means the ceiling stopped it.\n */\nexport type RevenueSweep = <Doc>(\n  query: unknown,\n  orderField: unknown,\n) => Promise<{ docs: Doc[]; truncated: boolean }>\n\n/** One attributed row: who produced a gain, and the loss beside it. */\nexport interface RevenueAttributionRow {\n  key: string\n  /** Display name, filled in by a bounded lookup; the id until then. */\n  name: string\n  /** Secondary identity — plugin id, publisher, subdomain. */\n  detail: string\n  /** Revenue earned, net of its own reversals. */\n  gainCents: number\n  /** Money handed back. Already deducted from `gainCents`. */\n  lossCents: number\n  count: number\n}\n\n/** A capped attribution: shown rows plus the remainder, as figures. */\nexport interface RevenueAttribution {\n  rows: RevenueAttributionRow[]\n  omittedRows: number\n  omittedGainCents: number\n  omittedLossCents: number\n}\n\n/** What the report asks every source, once per period. */\nexport interface RevenueSourceRequest {\n  /** `2026-08` or `2026-Q3`, echoed for the record. */\n  period: string\n  /** Half-open UTC bounds of the period. */\n  start: Date\n  end: Date\n  /** Rows per attribution table the page shows; the rest is carried as figures. */\n  attributionLimit: number\n  sweep: RevenueSweep\n  /**\n   * Display names for organizations — which the report has already read, so\n   * naming a publisher costs nothing.\n   */\n  orgNames(orgIds: readonly string[]): Promise<ReadonlyMap<string, string>>\n  /**\n   * Names the rows a source will SHOW from a collection's documents, in place:\n   * `name` from `nameField`, `detail` from `detailField`, and `(deleted)` for a\n   * document that is gone. Called AFTER capping, so the read is bounded by what\n   * is displayed rather than by how many sales the period holds.\n   */\n  nameRows(\n    rows: RevenueAttributionRow[],\n    from: { collection: string; nameField: string; detailField: string },\n  ): Promise<void>\n}\n\n/** A line of the report's gross-versus-net reconciliation. */\nexport interface RevenueSourceLine {\n  label: string\n  cents: number\n  /** Subtracted on the way from gross to what the operator kept. */\n  deduction: boolean\n  /** Whose money it is — the sentence that says why it is or is not revenue. */\n  note: string\n}\n\n/** A table of who produced a source's earnings. */\nexport interface RevenueAttributionTable extends RevenueAttribution {\n  id: string\n  heading: string\n  /** The column naming what a row is: `Listing`, `Storefront`. */\n  unit: string\n  /** The column counting what was summed: `Sales`, `Orders`. */\n  countLabel: string\n  empty: string\n  /** Draw the rows as ranked bars above the table, saying this when there are none. */\n  chartEmpty?: string\n}\n\n/** What a source answers for one period. */\nexport interface RevenueSourceAnswer {\n  /** Stable key, unique on the report. */\n  id: string\n  /** How the report names it when its read stopped short: `marketplace`. */\n  name: string\n  /** Its line of \"where the money came from\", net of everything not the operator's. */\n  earned: { label: string; cents: number; note: string }\n  grossToNet: RevenueSourceLine[]\n  /** Qualifications worth stating beside the figures. Only those that apply. */\n  notes: Array<{ label: string; tone: 'warning' | 'neutral' }>\n  /** Each sums to `earned`. */\n  attribution: RevenueAttributionTable[]\n  /** A sentence under the source's attribution tables. */\n  attributionNote?: string\n  /** The sweep stopped at the ceiling: every figure is a LOWER BOUND. */\n  truncated: boolean\n  /**\n   * The source's read could not run at all, so its figures are not counted —\n   * never a cap, which is a different state with a different remedy.\n   */\n  failure: { title: string; detail: string } | null\n  /** The source's own settled figures, carried whole for the audit. */\n  summary: unknown\n}\n\n/** One source on the report: its answer, or why there is none. */\nexport type RevenueSection =\n  | ({ outcome: 'answered'; pluginId: string } & RevenueSourceAnswer)\n  | {\n      outcome: 'refused'\n      pluginId: string\n      /** The plugin id: a refused source never said what it calls itself. */\n      id: string\n      reason: string\n    }\n\nexport interface RevenueSource {\n  /** This plugin's earnings for one period. May throw: the report refuses it. */\n  read(request: RevenueSourceRequest): Promise<RevenueSourceAnswer>\n}\n\n/** Every source answers; one per plugin. */\nexport const REVENUE_SOURCES = definePluginServiceContract<RevenueSource>(\n  'core.revenue-sources',\n  { multiple: true },\n)\n\n/** Installs a plugin's source; registering again replaces it. */\nexport function registerRevenueSource(\n  source: RevenueSource,\n  options?: { pluginId?: string },\n): void {\n  if (typeof source?.read !== 'function') {\n    throw new Error('a revenue source needs a read function')\n  }\n  registerPluginService(REVENUE_SOURCES, source, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The plugins with a registered source, in the order they answer. */\nexport function listRevenueSources(): string[] {\n  return resolvePluginServices(REVENUE_SOURCES).map((entry) => entry.pluginId)\n}\n\n/**\n * Group, sort and cap — every attribution table's shared half.\n *\n * A row whose key is missing is NOT dropped. It is grouped under an explicit\n * unattributed key, because a sale nobody can attribute still happened and\n * dropping it would make the rows sum below the total — the one property that\n * makes any of these tables worth reading. The cap carries its remainder as\n * FIGURES, so the table stays a complete accounting even when it is not a\n * complete list.\n */\nexport function groupRevenueAttribution(\n  entries: ReadonlyArray<{ key: string; detail: string; gain: number; loss: number }>,\n  limit: number,\n  unattributedLabel: string,\n): RevenueAttribution {\n  const byKey = new Map<string, RevenueAttributionRow>()\n  for (const entry of entries ?? []) {\n    const key = entry.key || unattributedLabel\n    const row = byKey.get(key) ?? {\n      key,\n      name: key === unattributedLabel ? unattributedLabel : key,\n      detail: entry.detail ?? '',\n      gainCents: 0,\n      lossCents: 0,\n      count: 0,\n    }\n    row.gainCents += entry.gain\n    row.lossCents += entry.loss\n    row.count += 1\n    if (!row.detail && entry.detail) row.detail = entry.detail\n    byKey.set(key, row)\n  }\n  const rows = [...byKey.values()].sort(\n    (a, b) =>\n      b.gainCents - a.gainCents ||\n      b.lossCents - a.lossCents ||\n      a.key.localeCompare(b.key),\n  )\n  const kept = rows.slice(0, Math.max(0, limit))\n  const dropped = rows.slice(Math.max(0, limit))\n  return {\n    rows: kept,\n    omittedRows: dropped.length,\n    omittedGainCents: dropped.reduce((sum, row) => sum + row.gainCents, 0),\n    omittedLossCents: dropped.reduce((sum, row) => sum + row.lossCents, 0),\n  }\n}\n\nconst isText = (value: unknown): value is string =>\n  typeof value === 'string' && value.trim().length > 0\n\n/** What is wrong with an answer, or null when it can be printed. */\nfunction malformed(answer: RevenueSourceAnswer): string | null {\n  if (!answer || typeof answer !== 'object') return 'no report'\n  if (!isText(answer.id) || !isText(answer.name)) return 'a report with no id or name'\n  const cents = answer.earned?.cents\n  if (typeof cents !== 'number' || !Number.isFinite(cents)) return 'no earned figure'\n  if (!isText(answer.earned?.label)) return 'an earned figure with no label'\n  if (typeof answer.truncated !== 'boolean') return 'no truncation flag'\n  for (const key of ['grossToNet', 'notes', 'attribution'] as const) {\n    if (!Array.isArray(answer[key])) return `no ${key}`\n  }\n  const badLine = answer.grossToNet.find(\n    (line) => typeof line?.cents !== 'number' || !Number.isFinite(line.cents),\n  )\n  if (badLine) return 'a gross-to-net line with no figure'\n  return null\n}\n\n/**\n * Every source's answer for one period — declared sources first, in the\n * compiled order, then any other registered source.\n *\n * NEVER THROWS and never drops a declared source. `declared` is the compiled\n * {@link PLUGIN_REVENUE_SOURCES} unless a spec passes its own.\n */\nexport async function readRevenueSources(\n  request: RevenueSourceRequest,\n  declared: readonly string[] = PLUGIN_REVENUE_SOURCES,\n): Promise<RevenueSection[]> {\n  const registered = resolvePluginServices(REVENUE_SOURCES)\n  const order = [\n    ...declared,\n    ...registered\n      .map((entry) => entry.pluginId)\n      .filter((pluginId) => !declared.includes(pluginId)),\n  ].filter((pluginId, index, all) => all.indexOf(pluginId) === index)\n\n  const answers = await Promise.all(\n    order.map(async (pluginId): Promise<RevenueSection> => {\n      const source = registered.find((entry) => entry.pluginId === pluginId)?.impl\n      if (!source) {\n        console.error(\n          `[revenue] \"${pluginId}\" declares a revenue source and none is ` +\n            'registered in this process; its earnings cannot be read.',\n        )\n        return {\n          outcome: 'refused',\n          pluginId,\n          id: pluginId,\n          reason:\n            `The “${pluginId}” plugin earns through the platform and registered ` +\n            'nothing to read its earnings with.',\n        }\n      }\n      try {\n        const answer = await source.read(request)\n        const problem = malformed(answer)\n        if (problem) {\n          return {\n            outcome: 'refused',\n            pluginId,\n            id: pluginId,\n            reason: `The “${pluginId}” plugin answered ${problem}.`,\n          }\n        }\n        return { ...answer, outcome: 'answered', pluginId }\n      } catch (error) {\n        console.error(`[revenue] \"${pluginId}\" failed to read its earnings`, error)\n        return {\n          outcome: 'refused',\n          pluginId,\n          id: pluginId,\n          reason: `The “${pluginId}” plugin could not read its earnings for this period.`,\n        }\n      }\n    }),\n  )\n\n  const seen = new Set<string>()\n  return answers.map((section) => {\n    if (section.outcome !== 'answered') return section\n    if (!seen.has(section.id)) {\n      seen.add(section.id)\n      return section\n    }\n    return {\n      outcome: 'refused',\n      pluginId: section.pluginId,\n      id: section.pluginId,\n      reason:\n        `The “${section.pluginId}” plugin answered as “${section.id}”, which ` +\n        'another source already is.',\n    }\n  })\n}\n"],"names":["PLUGIN_REVENUE_SOURCES","definePluginServiceContract","registerPluginService","resolvePluginServices","REVENUE_SOURCES","multiple","registerRevenueSource","source","options","read","Error","pluginId","listRevenueSources","map","entry","groupRevenueAttribution","entries","limit","unattributedLabel","byKey","Map","key","row","get","name","detail","gainCents","lossCents","count","gain","loss","set","rows","values","sort","a","b","localeCompare","kept","slice","Math","max","dropped","omittedRows","length","omittedGainCents","reduce","sum","omittedLossCents","isText","value","trim","malformed","answer","id","cents","earned","Number","isFinite","label","truncated","Array","isArray","badLine","grossToNet","find","line","readRevenueSources","request","declared","registered","order","filter","includes","index","all","indexOf","answers","Promise","impl","console","error","outcome","reason","problem","seen","Set","section","has","add"],"mappings":"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"}

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[];