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

package/src/lib/plugin-manager/plugin-host-resources.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @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 as a KIND the platform's generic create route
+ * writes (AGL-3080).
+ *
+ * `/api/hosts/resources` is the only door a client creates quota-governed
+ * site documents through: the rules deny client `create` on each of these
+ * collections, and the route is the allow-list of what a client may write
+ * (AGL-1377), the count it is met against (AGL-473, AGL-2231) and the
+ * provenance it stamps (AGL-118). `duplicateResource` is its twin for a copy.
+ * Both used to hold every plugin's row — which collection a workflow lives
+ * in, which entitlement a product needs, which fields a redirect may carry —
+ * so the platform was the keeper of its plugins' document models, and a
+ * plugin could not add a kind without editing core.
+ *
+ * So the plugin that owns a collection declares the kind it is created as,
+ * beside the collection itself in the `hostCollections` block of
+ * `plugins.config.json` (a host collection's `resource`),
+ * and both readers ask this module.
+ *
+ * ## Compiled, and refused when absent
+ *
+ * The route is a SECURITY path: its field list is what stands between a
+ * client and a document the UI later presents as trustworthy. A runtime
+ * registry that one process had not filled would either refuse a legitimate
+ * create or — worse, if a reader ever fell back to an open list — store
+ * whatever it was sent. So these rows are compiled by
+ * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this
+ * module is imported, and a kind nobody declares is REFUSED as an unknown
+ * resource. There is no registrar: `registerPluginHostCollections` refuses a
+ * declaration that carries a `resource`.
+ *
+ * The generator checks what a reader would otherwise have to trust: one owner
+ * per kind and none of core's own; a count on every kind (a plan `quotaKey` or
+ * a `platformCap`); no server-stamped field, stamp or approver field on the
+ * client's list; `externalDestination` only with the publishing role; and a
+ * copy's fields a subset of the create's.
+ *
+ * ## What core keeps
+ *
+ * The NUMBERS. A declaration names its plan counter and feature flag as keys
+ * (`quotaKey`, `entitlement`) and core's plan table resolves them, exactly as
+ * it does for its own kinds. A flat platform cap is named the same way —
+ * `platformCap` is the name of a constant core holds, resolved by
+ * {@link hostResourcePlatformCap} — so no plugin carries a number that is the
+ * platform's abuse ceiling. Core also keeps everything a create does for
+ * EVERY kind: the role gate, the lockdown verdict, the transaction that counts
+ * and writes, the node codec, the timestamps and `createdBy`.
+ *
+ * Reached by its own subpath, never the barrel: its readers are server routes.
+ */
+/** A constant value a create writes: never the client's, never another stamp's. */
+export type PluginHostResourceStampValue = string | number | boolean | null;
+/** How a whole copy of the kind is made, when the kind can be duplicated. */
+export interface PluginHostResourceDuplicate {
+    /** The field the name lives in; the copy's is made unique among the live siblings. */
+    nameField: string;
+    /** The source fields carried onto the copy — a subset of the create's. */
+    fields: readonly string[];
+    /** What the copy carries beyond the source's fields: a cleared trigger. */
+    stamps?: Readonly<Record<string, PluginHostResourceStampValue>>;
+}
+export interface PluginHostResourceDeclaration {
+    /** The `resource` a caller names, in camelCase: `product`, `workflow`. */
+    kind: string;
+    /** Plural, for quota copy: "this site can run 5 {label}". */
+    label: string;
+    /** Singular, for the site activity line: "Created {activityNoun}". */
+    activityNoun: string;
+    /** The activity target type a row filters and deep-links by; `content` when absent. */
+    activityType?: string;
+    /** The plan counter, an `OrgEntitlements` key core resolves. */
+    quotaKey?: string;
+    /** The plan feature the kind needs at all, an `OrgFeatureFlags` key. */
+    entitlement?: string;
+    /** A flat platform cap by the name of core's constant; see {@link hostResourcePlatformCap}. */
+    platformCap?: string;
+    /** Deleting stamps `deletedAt`, so the cap counts live documents only. */
+    softDeletes?: boolean;
+    /** Creating it needs the publishing role rather than the write role. */
+    requiresPublishRole?: boolean;
+    /** The keys a client may set. Anything else it sends is dropped. */
+    fields: readonly string[];
+    /** Constant values every create writes, e.g. `deletedAt: null` for a kind born live. */
+    stamps?: Readonly<Record<string, PluginHostResourceStampValue>>;
+    /**
+     * A destination field that may point off the platform. When the value is
+     * not a site path, the creating publisher's VERIFIED uid is stamped into
+     * `approvedByField` — the evidence a serve path trusts that somebody chose
+     * to send traffic away. Only with `requiresPublishRole`.
+     */
+    externalDestination?: {
+        field: string;
+        approvedByField: string;
+    };
+    /**
+     * The field holding the site path the document answers at the moment it
+     * exists. A create announces it to the site cache, because what used to
+     * answer there is already cached as the page.
+     */
+    livePathField?: string;
+    duplicate?: PluginHostResourceDuplicate;
+}
+/** A declaration with the plugin that made it and the collection it writes. */
+export type ResolvedPluginHostResource = PluginHostResourceDeclaration & {
+    pluginId: string;
+    /** The subcollection under `hosts/{hostId}` the kind is created in. */
+    collection: string;
+};
+/** Every declared kind, in config order. */
+export declare function listPluginHostResources(): ResolvedPluginHostResource[];
+/** One declared kind, or `null` — which every reader treats as unknown. */
+export declare function pluginHostResource(kind: unknown): ResolvedPluginHostResource | null;
+/**
+ * The number a `platformCap` names, or `null` for a name core does not hold —
+ * which the create route answers by refusing, never by leaving it uncapped.
+ */
+export declare function hostResourcePlatformCap(name: string): number | null;

package/src/lib/plugin-manager/plugin-host-resources.js

@@ -0,0 +1,52 @@
+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.
+ */ import { ACTIONS_MAX_PER_HOST, WEBHOOK_MAX_PER_HOST } from "../app-utils/actions.js";
+import { PLUGIN_HOST_COLLECTIONS_DECLARED } from "./first-party-plugins.generated.js";
+/** Every declared kind, in config order. */ export function listPluginHostResources() {
+    const out = [];
+    for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED){
+        if (row.resource) {
+            out.push(_extends({}, row.resource, {
+                pluginId: row.pluginId,
+                collection: row.name
+            }));
+        }
+    }
+    return out;
+}
+/** One declared kind, or `null` — which every reader treats as unknown. */ export function pluginHostResource(kind) {
+    var _listPluginHostResources_find;
+    if (typeof kind !== 'string' || !kind) return null;
+    return (_listPluginHostResources_find = listPluginHostResources().find((one)=>one.kind === kind)) != null ? _listPluginHostResources_find : null;
+}
+/**
+ * The flat platform caps a declaration may name (AGL-1360, AGL-2266): a
+ * ceiling on documents mintable from a browser that no plan varies, so it has
+ * no `OrgEntitlements` key. Keyed by the constant's own name, so a search for
+ * the constant finds the declaration that uses it.
+ */ const HOST_RESOURCE_PLATFORM_CAPS = {
+    ACTIONS_MAX_PER_HOST,
+    WEBHOOK_MAX_PER_HOST
+};
+/**
+ * The number a `platformCap` names, or `null` for a name core does not hold —
+ * which the create route answers by refusing, never by leaving it uncapped.
+ */ export function hostResourcePlatformCap(name) {
+    return Object.prototype.hasOwnProperty.call(HOST_RESOURCE_PLATFORM_CAPS, name) ? HOST_RESOURCE_PLATFORM_CAPS[name] : null;
+}
+
+//# sourceMappingURL=plugin-host-resources.js.map

package/src/lib/plugin-manager/plugin-host-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-host-resources.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 { ACTIONS_MAX_PER_HOST, WEBHOOK_MAX_PER_HOST } from '../app-utils/actions'\nimport { PLUGIN_HOST_COLLECTIONS_DECLARED } from './first-party-plugins.generated'\n\n/**\n * A plugin's host collection as a KIND the platform's generic create route\n * writes (AGL-3080).\n *\n * `/api/hosts/resources` is the only door a client creates quota-governed\n * site documents through: the rules deny client `create` on each of these\n * collections, and the route is the allow-list of what a client may write\n * (AGL-1377), the count it is met against (AGL-473, AGL-2231) and the\n * provenance it stamps (AGL-118). `duplicateResource` is its twin for a copy.\n * Both used to hold every plugin's row — which collection a workflow lives\n * in, which entitlement a product needs, which fields a redirect may carry —\n * so the platform was the keeper of its plugins' document models, and a\n * plugin could not add a kind without editing core.\n *\n * So the plugin that owns a collection declares the kind it is created as,\n * beside the collection itself in the `hostCollections` block of\n * `plugins.config.json` (a host collection's `resource`),\n * and both readers ask this module.\n *\n * ## Compiled, and refused when absent\n *\n * The route is a SECURITY path: its field list is what stands between a\n * client and a document the UI later presents as trustworthy. A runtime\n * registry that one process had not filled would either refuse a legitimate\n * create or — worse, if a reader ever fell back to an open list — store\n * whatever it was sent. So these rows are compiled by\n * `tools/scripts/generate-plugin-manifests.mjs`, present the moment this\n * module is imported, and a kind nobody declares is REFUSED as an unknown\n * resource. There is no registrar: `registerPluginHostCollections` refuses a\n * declaration that carries a `resource`.\n *\n * The generator checks what a reader would otherwise have to trust: one owner\n * per kind and none of core's own; a count on every kind (a plan `quotaKey` or\n * a `platformCap`); no server-stamped field, stamp or approver field on the\n * client's list; `externalDestination` only with the publishing role; and a\n * copy's fields a subset of the create's.\n *\n * ## What core keeps\n *\n * The NUMBERS. A declaration names its plan counter and feature flag as keys\n * (`quotaKey`, `entitlement`) and core's plan table resolves them, exactly as\n * it does for its own kinds. A flat platform cap is named the same way —\n * `platformCap` is the name of a constant core holds, resolved by\n * {@link hostResourcePlatformCap} — so no plugin carries a number that is the\n * platform's abuse ceiling. Core also keeps everything a create does for\n * EVERY kind: the role gate, the lockdown verdict, the transaction that counts\n * and writes, the node codec, the timestamps and `createdBy`.\n *\n * Reached by its own subpath, never the barrel: its readers are server routes.\n */\n\n/** A constant value a create writes: never the client's, never another stamp's. */\nexport type PluginHostResourceStampValue = string | number | boolean | null\n\n/** How a whole copy of the kind is made, when the kind can be duplicated. */\nexport interface PluginHostResourceDuplicate {\n  /** The field the name lives in; the copy's is made unique among the live siblings. */\n  nameField: string\n  /** The source fields carried onto the copy — a subset of the create's. */\n  fields: readonly string[]\n  /** What the copy carries beyond the source's fields: a cleared trigger. */\n  stamps?: Readonly<Record<string, PluginHostResourceStampValue>>\n}\n\nexport interface PluginHostResourceDeclaration {\n  /** The `resource` a caller names, in camelCase: `product`, `workflow`. */\n  kind: string\n  /** Plural, for quota copy: \"this site can run 5 {label}\". */\n  label: string\n  /** Singular, for the site activity line: \"Created {activityNoun}\". */\n  activityNoun: string\n  /** The activity target type a row filters and deep-links by; `content` when absent. */\n  activityType?: string\n  /** The plan counter, an `OrgEntitlements` key core resolves. */\n  quotaKey?: string\n  /** The plan feature the kind needs at all, an `OrgFeatureFlags` key. */\n  entitlement?: string\n  /** A flat platform cap by the name of core's constant; see {@link hostResourcePlatformCap}. */\n  platformCap?: string\n  /** Deleting stamps `deletedAt`, so the cap counts live documents only. */\n  softDeletes?: boolean\n  /** Creating it needs the publishing role rather than the write role. */\n  requiresPublishRole?: boolean\n  /** The keys a client may set. Anything else it sends is dropped. */\n  fields: readonly string[]\n  /** Constant values every create writes, e.g. `deletedAt: null` for a kind born live. */\n  stamps?: Readonly<Record<string, PluginHostResourceStampValue>>\n  /**\n   * A destination field that may point off the platform. When the value is\n   * not a site path, the creating publisher's VERIFIED uid is stamped into\n   * `approvedByField` — the evidence a serve path trusts that somebody chose\n   * to send traffic away. Only with `requiresPublishRole`.\n   */\n  externalDestination?: { field: string; approvedByField: string }\n  /**\n   * The field holding the site path the document answers at the moment it\n   * exists. A create announces it to the site cache, because what used to\n   * answer there is already cached as the page.\n   */\n  livePathField?: string\n  duplicate?: PluginHostResourceDuplicate\n}\n\n/** A declaration with the plugin that made it and the collection it writes. */\nexport type ResolvedPluginHostResource = PluginHostResourceDeclaration & {\n  pluginId: string\n  /** The subcollection under `hosts/{hostId}` the kind is created in. */\n  collection: string\n}\n\n/** Every declared kind, in config order. */\nexport function listPluginHostResources(): ResolvedPluginHostResource[] {\n  const out: ResolvedPluginHostResource[] = []\n  for (const row of PLUGIN_HOST_COLLECTIONS_DECLARED) {\n    if (row.resource) {\n      out.push({ ...row.resource, pluginId: row.pluginId, collection: row.name })\n    }\n  }\n  return out\n}\n\n/** One declared kind, or `null` — which every reader treats as unknown. */\nexport function pluginHostResource(kind: unknown): ResolvedPluginHostResource | null {\n  if (typeof kind !== 'string' || !kind) return null\n  return listPluginHostResources().find((one) => one.kind === kind) ?? null\n}\n\n/**\n * The flat platform caps a declaration may name (AGL-1360, AGL-2266): a\n * ceiling on documents mintable from a browser that no plan varies, so it has\n * no `OrgEntitlements` key. Keyed by the constant's own name, so a search for\n * the constant finds the declaration that uses it.\n */\nconst HOST_RESOURCE_PLATFORM_CAPS: Readonly<Record<string, number>> = {\n  ACTIONS_MAX_PER_HOST,\n  WEBHOOK_MAX_PER_HOST,\n}\n\n/**\n * The number a `platformCap` names, or `null` for a name core does not hold —\n * which the create route answers by refusing, never by leaving it uncapped.\n */\nexport function hostResourcePlatformCap(name: string): number | null {\n  return Object.prototype.hasOwnProperty.call(HOST_RESOURCE_PLATFORM_CAPS, name)\n    ? HOST_RESOURCE_PLATFORM_CAPS[name]\n    : null\n}\n"],"names":["ACTIONS_MAX_PER_HOST","WEBHOOK_MAX_PER_HOST","PLUGIN_HOST_COLLECTIONS_DECLARED","listPluginHostResources","out","row","resource","push","pluginId","collection","name","pluginHostResource","kind","find","one","HOST_RESOURCE_PLATFORM_CAPS","hostResourcePlatformCap","Object","prototype","hasOwnProperty","call"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,EAAEC,oBAAoB,QAAQ,0BAAsB;AACjF,SAASC,gCAAgC,QAAQ,qCAAiC;AAgHlF,0CAA0C,GAC1C,OAAO,SAASC;IACd,MAAMC,MAAoC,EAAE;IAC5C,KAAK,MAAMC,OAAOH,iCAAkC;QAClD,IAAIG,IAAIC,QAAQ,EAAE;YAChBF,IAAIG,IAAI,CAAC,aAAKF,IAAIC,QAAQ;gBAAEE,UAAUH,IAAIG,QAAQ;gBAAEC,YAAYJ,IAAIK,IAAI;;QAC1E;IACF;IACA,OAAON;AACT;AAEA,yEAAyE,GACzE,OAAO,SAASO,mBAAmBC,IAAa;QAEvCT;IADP,IAAI,OAAOS,SAAS,YAAY,CAACA,MAAM,OAAO;IAC9C,QAAOT,gCAAAA,0BAA0BU,IAAI,CAAC,CAACC,MAAQA,IAAIF,IAAI,KAAKA,iBAArDT,gCAA8D;AACvE;AAEA;;;;;CAKC,GACD,MAAMY,8BAAgE;IACpEf;IACAC;AACF;AAEA;;;CAGC,GACD,OAAO,SAASe,wBAAwBN,IAAY;IAClD,OAAOO,OAAOC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACL,6BAA6BL,QACrEK,2BAA2B,CAACL,KAAK,GACjC;AACN"}

package/src/lib/plugin-manager/plugin-org-erasure.d.ts

@@ -14,6 +14,20 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS } from './first-party-plugins.generated';
+export { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS };
+/**
+ * A plugin's top-level collection whose documents name an organization in a
+ * field, declared by that plugin. See the module note.
+ */
+export interface PluginOrgKeyedCollection {
+    /** The plugin that declared it. */
+    pluginId: string;
+    /** The top-level collection. */
+    name: string;
+    /** The field naming the organization a document belongs to. */
+    orgField: string;
+}
 /** What an eraser is asked to erase. */
 export interface PluginOrgErasureRequest {
     /** The workspace being erased. */
@@ -43,10 +57,22 @@ export declare function registerPluginOrgEraser(eraser: PluginOrgEraser, options
 /**
  * Runs every eraser, in registration order, and answers each plugin's
  * report by plugin id: the eraser's own report, or `null` for one that
- * threw. Never throws.
+ * threw.
+ *
+ * Throws in exactly two cases, both about a REQUIRED eraser (`required`,
+ * the compiled {@link PLUGIN_REQUIRED_ORG_ERASERS} unless a spec passes its
+ * own): before running anything, when one is not registered; and after
+ * running every eraser, when one threw.
  */
-export declare function runPluginOrgErasers(request: PluginOrgErasureRequest): Promise<Record<string, PluginOrgErasureReport | null>>;
+export declare function runPluginOrgErasers(request: PluginOrgErasureRequest, required?: readonly string[]): Promise<Record<string, PluginOrgErasureReport | null>>;
 /** The plugins with a workspace eraser, in the order they run. */
 export declare function listPluginOrgErasers(): string[];
 /** Test seam: forget every eraser. */
 export declare function resetPluginOrgErasersForTests(): void;
+/**
+ * Test seam: a no-op eraser for every REQUIRED plugin that has none, so a
+ * spec about the erasure's own sweeps can run it without loading a plugin
+ * (core and the data layer may not import one). A spec about a required
+ * plugin's share registers the real one through the app's manifest instead.
+ */
+export declare function standInRequiredOrgErasersForTests(): void;

package/src/lib/plugin-manager/plugin-org-erasure.js

@@ -46,7 +46,33 @@
  * `consoleServerDeclarations` for an eraser that opens a credential only the
  * console holds — so the eraser is in place in a server process that never
  * loaded the plugin's API surface.
+ *
+ * ## A REQUIRED eraser (AGL-3080)
+ *
+ * Isolation is right for a share whose failure leaves the workspace's data
+ * gone and only a provider-side courtesy undone. It is wrong for a share the
+ * erasure PROMISES: a public record naming the erased organization, a payout
+ * identifier on a world-readable document. A plugin holding such a record
+ * declares `"requiredOrgEraser": true` in `plugins.config.json`, compiled into
+ * {@link PLUGIN_REQUIRED_ORG_ERASERS} so no registration can opt out of it, and:
+ *
+ * - an erasure REFUSES to start while a required eraser is not registered —
+ *   a boot that failed to declare it must not produce a "complete" erasure
+ *   with the record still standing;
+ * - a required eraser that throws still lets every other eraser run, and then
+ *   fails the erasure's `plugins` step, which the cron retries.
+ *
+ * ## Plugin collections keyed by the organization (AGL-3080)
+ *
+ * A plugin's TOP-LEVEL collection whose documents carry the organization's id
+ * in a field is invisible to the erasure's path deletes. The plugin declares
+ * it (`orgKeyedCollections`, compiled into {@link PLUGIN_ORG_KEYED_COLLECTIONS})
+ * and the erasure sweeps it by that field in every process, with or without
+ * the plugin loaded — a deletion that must not depend on which bundles an
+ * erasing process happened to load, so it is data rather than an eraser.
  */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS } from "./first-party-plugins.generated.js";
+export { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS };
 const registrations = [];
 /**
  * Registers a plugin's workspace eraser. Owner = the loader's marker inside a
@@ -72,9 +98,20 @@ const registrations = [];
 /**
  * Runs every eraser, in registration order, and answers each plugin's
  * report by plugin id: the eraser's own report, or `null` for one that
- * threw. Never throws.
- */ export async function runPluginOrgErasers(request) {
+ * threw.
+ *
+ * Throws in exactly two cases, both about a REQUIRED eraser (`required`,
+ * the compiled {@link PLUGIN_REQUIRED_ORG_ERASERS} unless a spec passes its
+ * own): before running anything, when one is not registered; and after
+ * running every eraser, when one threw.
+ */ export async function runPluginOrgErasers(request, required = PLUGIN_REQUIRED_ORG_ERASERS) {
+    const registered = new Set(registrations.map((entry)=>entry.pluginId));
+    const missing = required.filter((pluginId)=>!registered.has(pluginId));
+    if (missing.length) {
+        throw new Error(`[plugins] erasing org ${request.orgId} refused: ${missing.join(', ')} ` + 'declared a required org eraser and none is registered in this process');
+    }
     const reports = {};
+    const failedRequired = [];
     for (const { pluginId, eraser } of [
         ...registrations
     ]){
@@ -86,8 +123,12 @@ const registrations = [];
         } catch (error) {
             reports[pluginId] = null;
             console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error);
+            if (required.includes(pluginId)) failedRequired.push(pluginId);
         }
     }
+    if (failedRequired.length) {
+        throw new Error(`[plugins] erasing org ${request.orgId} incomplete: the required eraser of ` + `${failedRequired.join(', ')} failed`);
+    }
     return reports;
 }
 /** The plugins with a workspace eraser, in the order they run. */ export function listPluginOrgErasers() {
@@ -96,5 +137,23 @@ const registrations = [];
 /** Test seam: forget every eraser. */ export function resetPluginOrgErasersForTests() {
     registrations.length = 0;
 }
+/**
+ * Test seam: a no-op eraser for every REQUIRED plugin that has none, so a
+ * spec about the erasure's own sweeps can run it without loading a plugin
+ * (core and the data layer may not import one). A spec about a required
+ * plugin's share registers the real one through the app's manifest instead.
+ */ export function standInRequiredOrgErasersForTests() {
+    const registered = new Set(registrations.map((entry)=>entry.pluginId));
+    for (const pluginId of PLUGIN_REQUIRED_ORG_ERASERS){
+        if (!registered.has(pluginId)) {
+            registrations.push({
+                pluginId,
+                eraser: async ()=>({
+                        standIn: true
+                    })
+            });
+        }
+    }
+}
 
 //# sourceMappingURL=plugin-org-erasure.js.map

package/src/lib/plugin-manager/plugin-org-erasure.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-org-erasure.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A plugin's share of a workspace erasure (AGL-2978).\n *\n * The workspace erasure destroys what the platform holds for an\n * organization: its document tree, its sites, and the top-level records\n * keyed to it by a field. A plugin that holds something those deletes cannot\n * finish on their own registers an eraser here — a grant at a provider that\n * only the plugin can revoke, or a record outside every path and field the\n * erasure sweeps — and the erasure runs every eraser with the organization's\n * id.\n *\n * Erasers run BEFORE the erasure deletes anything of its own. The\n * organization, its roster and every record the erasure is about to sweep\n * still exist when an eraser runs, so an eraser that has to act through a\n * record — open a stored grant to revoke it — finds the record there. What\n * the erasure deletes on its own stays its to delete: an eraser adds to the\n * erasure, and the erasure does not wait on one to finish its own sweeps.\n *\n * Erasers run in registration order and are ISOLATED: a throw is logged\n * against its plugin, recorded as `null`, and does not stop the next one or\n * the erasure. An erasure runs against a legal clock, and one plugin's\n * outage must not keep every other plugin's data, or the workspace, past it.\n * The `null` is how the erasure's audit record says that plugin's share may\n * not be done, which a report of zero would hide.\n *\n * A DRY RUN is handed to every eraser, which must then touch no provider and\n * write nothing: it counts what it would do. A plan that reached a vendor\n * would be an erasure that happened without anybody deciding it should.\n *\n * Registered from a plugin's declarations — `serverDeclarations`, or\n * `consoleServerDeclarations` for an eraser that opens a credential only the\n * console holds — so the eraser is in place in a server process that never\n * loaded the plugin's API surface.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** What an eraser is asked to erase. */\nexport interface PluginOrgErasureRequest {\n  /** The workspace being erased. */\n  orgId: string\n  /**\n   * A plan, not an erasure: count, touch no provider, write nothing. The\n   * erasure's own sweeps honor the same flag.\n   */\n  dryRun: boolean\n}\n\n/**\n * What an eraser reports for the erasure's audit record: counts and flags,\n * never the erased content, because the record outlives the data by design.\n * A `null` field is a figure the eraser could not measure, which is not zero.\n */\nexport type PluginOrgErasureReport = Readonly<Record<string, number | boolean | null>>\n\nexport type PluginOrgEraser = (\n  request: PluginOrgErasureRequest,\n) => Promise<PluginOrgErasureReport>\n\ninterface Registration {\n  pluginId: string\n  eraser: PluginOrgEraser\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's workspace eraser. Owner = the loader's marker inside a\n * register fn, else `options.pluginId`; an eraser with neither throws. One\n * eraser per plugin: registering again replaces the plugin's earlier eraser\n * in place, so a module evaluated twice does not erase twice.\n */\nexport function registerPluginOrgEraser(\n  eraser: PluginOrgEraser,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin org eraser was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const index = registrations.findIndex((entry) => entry.pluginId === pluginId)\n  if (index >= 0) registrations[index] = { pluginId, eraser }\n  else registrations.push({ pluginId, eraser })\n}\n\n/**\n * Runs every eraser, in registration order, and answers each plugin's\n * report by plugin id: the eraser's own report, or `null` for one that\n * threw. Never throws.\n */\nexport async function runPluginOrgErasers(\n  request: PluginOrgErasureRequest,\n): Promise<Record<string, PluginOrgErasureReport | null>> {\n  const reports: Record<string, PluginOrgErasureReport | null> = {}\n  for (const { pluginId, eraser } of [...registrations]) {\n    try {\n      reports[pluginId] = await eraser({ orgId: request.orgId, dryRun: request.dryRun })\n    } catch (error) {\n      reports[pluginId] = null\n      console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error)\n    }\n  }\n  return reports\n}\n\n/** The plugins with a workspace eraser, in the order they run. */\nexport function listPluginOrgErasers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every eraser. */\nexport function resetPluginOrgErasersForTests(): void {\n  registrations.length = 0\n}\n"],"names":["getRegisteringPluginId","registrations","registerPluginOrgEraser","eraser","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginOrgErasers","request","reports","orgId","dryRun","error","console","listPluginOrgErasers","map","resetPluginOrgErasersForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AA6BxE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,wBACdC,MAAuB,EACvBC,OAA+B;QAEbJ,MAAAA;IAAlB,MAAMK,WAAW,EAACL,QAAAA,0BAAAA,oCAAAA,0BAA4BI,2BAAAA,QAASC,QAAQ,YAA7CL,OAAiD,IAAIM,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,yEACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAO;SACrDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAO;AAC7C;AAEA;;;;CAIC,GACD,OAAO,eAAeS,oBACpBC,OAAgC;IAEhC,MAAMC,UAAyD,CAAC;IAChE,KAAK,MAAM,EAAET,QAAQ,EAAEF,MAAM,EAAE,IAAI;WAAIF;KAAc,CAAE;QACrD,IAAI;YACFa,OAAO,CAACT,SAAS,GAAG,MAAMF,OAAO;gBAAEY,OAAOF,QAAQE,KAAK;gBAAEC,QAAQH,QAAQG,MAAM;YAAC;QAClF,EAAE,OAAOC,OAAO;YACdH,OAAO,CAACT,SAAS,GAAG;YACpBa,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEZ,SAAS,qBAAqB,EAAEQ,QAAQE,KAAK,EAAE,EAAEE;QAC9E;IACF;IACA,OAAOH;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASK;IACd,OAAOlB,cAAcmB,GAAG,CAAC,CAACV,QAAUA,MAAML,QAAQ;AACpD;AAEA,oCAAoC,GACpC,OAAO,SAASgB;IACdpB,cAAcqB,MAAM,GAAG;AACzB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-org-erasure.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A plugin's share of a workspace erasure (AGL-2978).\n *\n * The workspace erasure destroys what the platform holds for an\n * organization: its document tree, its sites, and the top-level records\n * keyed to it by a field. A plugin that holds something those deletes cannot\n * finish on their own registers an eraser here — a grant at a provider that\n * only the plugin can revoke, or a record outside every path and field the\n * erasure sweeps — and the erasure runs every eraser with the organization's\n * id.\n *\n * Erasers run BEFORE the erasure deletes anything of its own. The\n * organization, its roster and every record the erasure is about to sweep\n * still exist when an eraser runs, so an eraser that has to act through a\n * record — open a stored grant to revoke it — finds the record there. What\n * the erasure deletes on its own stays its to delete: an eraser adds to the\n * erasure, and the erasure does not wait on one to finish its own sweeps.\n *\n * Erasers run in registration order and are ISOLATED: a throw is logged\n * against its plugin, recorded as `null`, and does not stop the next one or\n * the erasure. An erasure runs against a legal clock, and one plugin's\n * outage must not keep every other plugin's data, or the workspace, past it.\n * The `null` is how the erasure's audit record says that plugin's share may\n * not be done, which a report of zero would hide.\n *\n * A DRY RUN is handed to every eraser, which must then touch no provider and\n * write nothing: it counts what it would do. A plan that reached a vendor\n * would be an erasure that happened without anybody deciding it should.\n *\n * Registered from a plugin's declarations — `serverDeclarations`, or\n * `consoleServerDeclarations` for an eraser that opens a credential only the\n * console holds — so the eraser is in place in a server process that never\n * loaded the plugin's API surface.\n *\n * ## A REQUIRED eraser (AGL-3080)\n *\n * Isolation is right for a share whose failure leaves the workspace's data\n * gone and only a provider-side courtesy undone. It is wrong for a share the\n * erasure PROMISES: a public record naming the erased organization, a payout\n * identifier on a world-readable document. A plugin holding such a record\n * declares `\"requiredOrgEraser\": true` in `plugins.config.json`, compiled into\n * {@link PLUGIN_REQUIRED_ORG_ERASERS} so no registration can opt out of it, and:\n *\n * - an erasure REFUSES to start while a required eraser is not registered —\n *   a boot that failed to declare it must not produce a \"complete\" erasure\n *   with the record still standing;\n * - a required eraser that throws still lets every other eraser run, and then\n *   fails the erasure's `plugins` step, which the cron retries.\n *\n * ## Plugin collections keyed by the organization (AGL-3080)\n *\n * A plugin's TOP-LEVEL collection whose documents carry the organization's id\n * in a field is invisible to the erasure's path deletes. The plugin declares\n * it (`orgKeyedCollections`, compiled into {@link PLUGIN_ORG_KEYED_COLLECTIONS})\n * and the erasure sweeps it by that field in every process, with or without\n * the plugin loaded — a deletion that must not depend on which bundles an\n * erasing process happened to load, so it is data rather than an eraser.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  PLUGIN_ORG_KEYED_COLLECTIONS,\n  PLUGIN_REQUIRED_ORG_ERASERS,\n} from './first-party-plugins.generated'\n\nexport { PLUGIN_ORG_KEYED_COLLECTIONS, PLUGIN_REQUIRED_ORG_ERASERS }\n\n/**\n * A plugin's top-level collection whose documents name an organization in a\n * field, declared by that plugin. See the module note.\n */\nexport interface PluginOrgKeyedCollection {\n  /** The plugin that declared it. */\n  pluginId: string\n  /** The top-level collection. */\n  name: string\n  /** The field naming the organization a document belongs to. */\n  orgField: string\n}\n\n/** What an eraser is asked to erase. */\nexport interface PluginOrgErasureRequest {\n  /** The workspace being erased. */\n  orgId: string\n  /**\n   * A plan, not an erasure: count, touch no provider, write nothing. The\n   * erasure's own sweeps honor the same flag.\n   */\n  dryRun: boolean\n}\n\n/**\n * What an eraser reports for the erasure's audit record: counts and flags,\n * never the erased content, because the record outlives the data by design.\n * A `null` field is a figure the eraser could not measure, which is not zero.\n */\nexport type PluginOrgErasureReport = Readonly<Record<string, number | boolean | null>>\n\nexport type PluginOrgEraser = (\n  request: PluginOrgErasureRequest,\n) => Promise<PluginOrgErasureReport>\n\ninterface Registration {\n  pluginId: string\n  eraser: PluginOrgEraser\n}\n\nconst registrations: Registration[] = []\n\n/**\n * Registers a plugin's workspace eraser. Owner = the loader's marker inside a\n * register fn, else `options.pluginId`; an eraser with neither throws. One\n * eraser per plugin: registering again replaces the plugin's earlier eraser\n * in place, so a module evaluated twice does not erase twice.\n */\nexport function registerPluginOrgEraser(\n  eraser: PluginOrgEraser,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'a plugin org eraser was registered with no owner: pass { pluginId } ' +\n        'when registering outside a plugin register fn',\n    )\n  }\n  const index = registrations.findIndex((entry) => entry.pluginId === pluginId)\n  if (index >= 0) registrations[index] = { pluginId, eraser }\n  else registrations.push({ pluginId, eraser })\n}\n\n/**\n * Runs every eraser, in registration order, and answers each plugin's\n * report by plugin id: the eraser's own report, or `null` for one that\n * threw.\n *\n * Throws in exactly two cases, both about a REQUIRED eraser (`required`,\n * the compiled {@link PLUGIN_REQUIRED_ORG_ERASERS} unless a spec passes its\n * own): before running anything, when one is not registered; and after\n * running every eraser, when one threw.\n */\nexport async function runPluginOrgErasers(\n  request: PluginOrgErasureRequest,\n  required: readonly string[] = PLUGIN_REQUIRED_ORG_ERASERS,\n): Promise<Record<string, PluginOrgErasureReport | null>> {\n  const registered = new Set(registrations.map((entry) => entry.pluginId))\n  const missing = required.filter((pluginId) => !registered.has(pluginId))\n  if (missing.length) {\n    throw new Error(\n      `[plugins] erasing org ${request.orgId} refused: ${missing.join(', ')} ` +\n        'declared a required org eraser and none is registered in this process',\n    )\n  }\n  const reports: Record<string, PluginOrgErasureReport | null> = {}\n  const failedRequired: string[] = []\n  for (const { pluginId, eraser } of [...registrations]) {\n    try {\n      reports[pluginId] = await eraser({ orgId: request.orgId, dryRun: request.dryRun })\n    } catch (error) {\n      reports[pluginId] = null\n      console.error(`[plugins] ${pluginId} failed to erase org ${request.orgId}`, error)\n      if (required.includes(pluginId)) failedRequired.push(pluginId)\n    }\n  }\n  if (failedRequired.length) {\n    throw new Error(\n      `[plugins] erasing org ${request.orgId} incomplete: the required eraser of ` +\n        `${failedRequired.join(', ')} failed`,\n    )\n  }\n  return reports\n}\n\n/** The plugins with a workspace eraser, in the order they run. */\nexport function listPluginOrgErasers(): string[] {\n  return registrations.map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every eraser. */\nexport function resetPluginOrgErasersForTests(): void {\n  registrations.length = 0\n}\n\n/**\n * Test seam: a no-op eraser for every REQUIRED plugin that has none, so a\n * spec about the erasure's own sweeps can run it without loading a plugin\n * (core and the data layer may not import one). A spec about a required\n * plugin's share registers the real one through the app's manifest instead.\n */\nexport function standInRequiredOrgErasersForTests(): void {\n  const registered = new Set(registrations.map((entry) => entry.pluginId))\n  for (const pluginId of PLUGIN_REQUIRED_ORG_ERASERS) {\n    if (!registered.has(pluginId)) {\n      registrations.push({ pluginId, eraser: async () => ({ standIn: true }) })\n    }\n  }\n}\n"],"names":["getRegisteringPluginId","PLUGIN_ORG_KEYED_COLLECTIONS","PLUGIN_REQUIRED_ORG_ERASERS","registrations","registerPluginOrgEraser","eraser","options","pluginId","trim","Error","index","findIndex","entry","push","runPluginOrgErasers","request","required","registered","Set","map","missing","filter","has","length","orgId","join","reports","failedRequired","dryRun","error","console","includes","listPluginOrgErasers","resetPluginOrgErasersForTests","standInRequiredOrgErasersForTests","standIn"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,4BAA4B,EAC5BC,2BAA2B,QACtB,qCAAiC;AAExC,SAASD,4BAA4B,EAAEC,2BAA2B,GAAE;AA0CpE,MAAMC,gBAAgC,EAAE;AAExC;;;;;CAKC,GACD,OAAO,SAASC,wBACdC,MAAuB,EACvBC,OAA+B;QAEbN,MAAAA;IAAlB,MAAMO,WAAW,EAACP,QAAAA,0BAAAA,oCAAAA,0BAA4BM,2BAAAA,QAASC,QAAQ,YAA7CP,OAAiD,IAAIQ,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,yEACE;IAEN;IACA,MAAMC,QAAQP,cAAcQ,SAAS,CAAC,CAACC,QAAUA,MAAML,QAAQ,KAAKA;IACpE,IAAIG,SAAS,GAAGP,aAAa,CAACO,MAAM,GAAG;QAAEH;QAAUF;IAAO;SACrDF,cAAcU,IAAI,CAAC;QAAEN;QAAUF;IAAO;AAC7C;AAEA;;;;;;;;;CASC,GACD,OAAO,eAAeS,oBACpBC,OAAgC,EAChCC,WAA8Bd,2BAA2B;IAEzD,MAAMe,aAAa,IAAIC,IAAIf,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;IACtE,MAAMa,UAAUJ,SAASK,MAAM,CAAC,CAACd,WAAa,CAACU,WAAWK,GAAG,CAACf;IAC9D,IAAIa,QAAQG,MAAM,EAAE;QAClB,MAAM,IAAId,MACR,CAAC,sBAAsB,EAAEM,QAAQS,KAAK,CAAC,UAAU,EAAEJ,QAAQK,IAAI,CAAC,MAAM,CAAC,CAAC,GACtE;IAEN;IACA,MAAMC,UAAyD,CAAC;IAChE,MAAMC,iBAA2B,EAAE;IACnC,KAAK,MAAM,EAAEpB,QAAQ,EAAEF,MAAM,EAAE,IAAI;WAAIF;KAAc,CAAE;QACrD,IAAI;YACFuB,OAAO,CAACnB,SAAS,GAAG,MAAMF,OAAO;gBAAEmB,OAAOT,QAAQS,KAAK;gBAAEI,QAAQb,QAAQa,MAAM;YAAC;QAClF,EAAE,OAAOC,OAAO;YACdH,OAAO,CAACnB,SAAS,GAAG;YACpBuB,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEtB,SAAS,qBAAqB,EAAEQ,QAAQS,KAAK,EAAE,EAAEK;YAC5E,IAAIb,SAASe,QAAQ,CAACxB,WAAWoB,eAAed,IAAI,CAACN;QACvD;IACF;IACA,IAAIoB,eAAeJ,MAAM,EAAE;QACzB,MAAM,IAAId,MACR,CAAC,sBAAsB,EAAEM,QAAQS,KAAK,CAAC,oCAAoC,CAAC,GAC1E,GAAGG,eAAeF,IAAI,CAAC,MAAM,OAAO,CAAC;IAE3C;IACA,OAAOC;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASM;IACd,OAAO7B,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;AACpD;AAEA,oCAAoC,GACpC,OAAO,SAAS0B;IACd9B,cAAcoB,MAAM,GAAG;AACzB;AAEA;;;;;CAKC,GACD,OAAO,SAASW;IACd,MAAMjB,aAAa,IAAIC,IAAIf,cAAcgB,GAAG,CAAC,CAACP,QAAUA,MAAML,QAAQ;IACtE,KAAK,MAAMA,YAAYL,4BAA6B;QAClD,IAAI,CAACe,WAAWK,GAAG,CAACf,WAAW;YAC7BJ,cAAcU,IAAI,CAAC;gBAAEN;gBAAUF,QAAQ,UAAa,CAAA;wBAAE8B,SAAS;oBAAK,CAAA;YAAG;QACzE;IACF;AACF"}

package/src/lib/plugin-manager/plugin-plan-entitlements.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @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 EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).
+ *
+ * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by
+ * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key
+ * without core naming it. That leaves the VALUE: what Free, Starter and every
+ * other plan include of it. A key that only a plugin's type declares still
+ * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the
+ * figure is core naming the key.
+ *
+ * So the owning plugin declares the figure per plan, beside the reasoning
+ * that sized it, and core composes it into the plan table. A plan row in
+ * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same
+ * number — `/pricing`, the plan comparison, the pricing-table generator and
+ * every quota gate read the composed table and cannot tell the difference.
+ *
+ * ## Compiled, never registered
+ *
+ * The readers include the published pricing tables, which a generator builds
+ * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan
+ * comparison, which renders before any plugin surface does. A registry one of
+ * them had not filled would publish a plan without the band — a missing row on
+ * the price list, or a quota gate reading nothing — with nothing red. So a
+ * first-party plugin names a function under `register.planEntitlements` in
+ * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads
+ * `${package}/plan-entitlements`, calls it, validates the answer and compiles
+ * it into `first-party-plugins.generated.ts` as data. There is no runtime
+ * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing
+ * can safely call is worse than none.
+ *
+ * ## What a missing figure means
+ *
+ * A declaration names every plan: the generated rows are typed
+ * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody
+ * declares is absent from the table, and each reader answers absence in the
+ * closed direction — a quota reads as nothing included, a feature as off.
+ * `planQuotaOf` below is that reading, and it never answers "unlimited" or
+ * "free" for a key that has no figure.
+ *
+ * ## One key, one owner, and never one of core's
+ *
+ * The generator refuses a key two plugins declare. A key the platform's own
+ * rows already carry is refused by `plan-entitlements.spec.ts` rather than
+ * here, because the generator cannot read core's rows without loading the
+ * module that imports this one; the composition keeps core's figure either
+ * way, so a collision can shadow nothing a customer is charged.
+ */
+import type { OrgPlan } from '../foundation';
+/** A numeric entitlement a plugin owns: a band, a daily pace, a take rate. */
+export interface PluginPlanQuotaDeclaration {
+    /** The stored key, exactly as `OrgEntitlements` and an override spell it. */
+    key: string;
+    /** What a staff page calls it. */
+    label: string;
+    /**
+     * What each plan includes. `Infinity` is `UNLIMITED`; every other value is
+     * a finite, non-negative number.
+     */
+    byPlan: Readonly<Record<OrgPlan, number>>;
+    /**
+     * A PRICE rather than a cap — a percentage of a sale — so an uncapped plan
+     * comp must never lift it (`PRICE_ENTITLEMENT_KEYS`).
+     */
+    price?: boolean;
+}
+/** A boolean gate a plugin owns. */
+export interface PluginPlanFeatureDeclaration {
+    /** The stored key, exactly as `OrgFeatureFlags` and an override spell it. */
+    key: string;
+    label: string;
+    byPlan: Readonly<Record<OrgPlan, boolean>>;
+}
+/** What a plugin's `planEntitlements` function answers. */
+export interface PluginPlanEntitlementsDeclaration {
+    quotas?: readonly PluginPlanQuotaDeclaration[];
+    features?: readonly PluginPlanFeatureDeclaration[];
+}
+/** A quota declaration with the plugin that made it. */
+export type ResolvedPluginPlanQuota = PluginPlanQuotaDeclaration & {
+    pluginId: string;
+};
+/** A feature declaration with the plugin that made it. */
+export type ResolvedPluginPlanFeature = PluginPlanFeatureDeclaration & {
+    pluginId: string;
+};
+/** Every declared quota, in catalog order. */
+export declare function pluginPlanQuotas(): readonly ResolvedPluginPlanQuota[];
+/** Every declared feature, in catalog order. */
+export declare function pluginPlanFeatures(): readonly ResolvedPluginPlanFeature[];
+/** The plugin that declared a quota or feature key, or `null`. */
+export declare function pluginPlanEntitlementOwner(key: string): string | null;
+/** The declared quotas' figures for one plan, keyed by the stored key. */
+export declare function pluginPlanQuotaRow(plan: OrgPlan): Record<string, number>;
+/** The declared features' answers for one plan, keyed by the stored key. */
+export declare function pluginPlanFeatureRow(plan: OrgPlan): Record<string, boolean>;
+/**
+ * A resolved quota read by its key — the reading core uses for a key a plugin
+ * owns, since core compiles without the plugin's type augmentation.
+ *
+ * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is
+ * not a number, reads as `0`: every gate that compares usage against it
+ * refuses, and every meter drawn from it shows full. That is the same
+ * direction `plugin-org-capacity` answers an unknown capacity in. Reading
+ * absence as `UNLIMITED` would be a plan giving away what nobody declared it
+ * sells.
+ */
+export declare function planQuotaOf(entitlements: object, key: string): number;

package/src/lib/plugin-manager/plugin-plan-entitlements.js

@@ -0,0 +1,101 @@
+/**
+ * @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 EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).
+ *
+ * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by
+ * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key
+ * without core naming it. That leaves the VALUE: what Free, Starter and every
+ * other plan include of it. A key that only a plugin's type declares still
+ * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the
+ * figure is core naming the key.
+ *
+ * So the owning plugin declares the figure per plan, beside the reasoning
+ * that sized it, and core composes it into the plan table. A plan row in
+ * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same
+ * number — `/pricing`, the plan comparison, the pricing-table generator and
+ * every quota gate read the composed table and cannot tell the difference.
+ *
+ * ## Compiled, never registered
+ *
+ * The readers include the published pricing tables, which a generator builds
+ * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan
+ * comparison, which renders before any plugin surface does. A registry one of
+ * them had not filled would publish a plan without the band — a missing row on
+ * the price list, or a quota gate reading nothing — with nothing red. So a
+ * first-party plugin names a function under `register.planEntitlements` in
+ * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads
+ * `${package}/plan-entitlements`, calls it, validates the answer and compiles
+ * it into `first-party-plugins.generated.ts` as data. There is no runtime
+ * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing
+ * can safely call is worse than none.
+ *
+ * ## What a missing figure means
+ *
+ * A declaration names every plan: the generated rows are typed
+ * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody
+ * declares is absent from the table, and each reader answers absence in the
+ * closed direction — a quota reads as nothing included, a feature as off.
+ * `planQuotaOf` below is that reading, and it never answers "unlimited" or
+ * "free" for a key that has no figure.
+ *
+ * ## One key, one owner, and never one of core's
+ *
+ * The generator refuses a key two plugins declare. A key the platform's own
+ * rows already carry is refused by `plan-entitlements.spec.ts` rather than
+ * here, because the generator cannot read core's rows without loading the
+ * module that imports this one; the composition keeps core's figure either
+ * way, so a collision can shadow nothing a customer is charged.
+ */ import { PLUGIN_PLAN_FEATURES_DECLARED, PLUGIN_PLAN_QUOTAS_DECLARED } from "./first-party-plugins.generated.js";
+/** Every declared quota, in catalog order. */ export function pluginPlanQuotas() {
+    return PLUGIN_PLAN_QUOTAS_DECLARED;
+}
+/** Every declared feature, in catalog order. */ export function pluginPlanFeatures() {
+    return PLUGIN_PLAN_FEATURES_DECLARED;
+}
+/** The plugin that declared a quota or feature key, or `null`. */ export function pluginPlanEntitlementOwner(key) {
+    var _ref, _ref1;
+    var _PLUGIN_PLAN_QUOTAS_DECLARED_find, _PLUGIN_PLAN_FEATURES_DECLARED_find;
+    return (_ref = (_ref1 = (_PLUGIN_PLAN_QUOTAS_DECLARED_find = PLUGIN_PLAN_QUOTAS_DECLARED.find((one)=>one.key === key)) == null ? void 0 : _PLUGIN_PLAN_QUOTAS_DECLARED_find.pluginId) != null ? _ref1 : (_PLUGIN_PLAN_FEATURES_DECLARED_find = PLUGIN_PLAN_FEATURES_DECLARED.find((one)=>one.key === key)) == null ? void 0 : _PLUGIN_PLAN_FEATURES_DECLARED_find.pluginId) != null ? _ref : null;
+}
+/** The declared quotas' figures for one plan, keyed by the stored key. */ export function pluginPlanQuotaRow(plan) {
+    return Object.fromEntries(PLUGIN_PLAN_QUOTAS_DECLARED.map((one)=>[
+            one.key,
+            one.byPlan[plan]
+        ]));
+}
+/** The declared features' answers for one plan, keyed by the stored key. */ export function pluginPlanFeatureRow(plan) {
+    return Object.fromEntries(PLUGIN_PLAN_FEATURES_DECLARED.map((one)=>[
+            one.key,
+            one.byPlan[plan]
+        ]));
+}
+/**
+ * A resolved quota read by its key — the reading core uses for a key a plugin
+ * owns, since core compiles without the plugin's type augmentation.
+ *
+ * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is
+ * not a number, reads as `0`: every gate that compares usage against it
+ * refuses, and every meter drawn from it shows full. That is the same
+ * direction `plugin-org-capacity` answers an unknown capacity in. Reading
+ * absence as `UNLIMITED` would be a plan giving away what nobody declared it
+ * sells.
+ */ export function planQuotaOf(entitlements, key) {
+    const value = entitlements[key];
+    return typeof value === 'number' && !Number.isNaN(value) ? value : 0;
+}
+
+//# sourceMappingURL=plugin-plan-entitlements.js.map

package/src/lib/plugin-manager/plugin-plan-entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-plan-entitlements.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 EACH PLAN INCLUDES OF A PLUGIN'S OWN KEYS (AGL-3080).\n *\n * `plugin-entitlement-keys` gives a plugin the TYPE of a key it owns, by\n * augmentation, so `OrgEntitlements` and `OrgFeatureFlags` carry the key\n * without core naming it. That leaves the VALUE: what Free, Starter and every\n * other plan include of it. A key that only a plugin's type declares still\n * needs a figure in every row of `PLAN_ENTITLEMENTS`, and core writing the\n * figure is core naming the key.\n *\n * So the owning plugin declares the figure per plan, beside the reasoning\n * that sized it, and core composes it into the plan table. A plan row in\n * `PLAN_ENTITLEMENTS` still answers every key the platform sells, at the same\n * number — `/pricing`, the plan comparison, the pricing-table generator and\n * every quota gate read the composed table and cannot tell the difference.\n *\n * ## Compiled, never registered\n *\n * The readers include the published pricing tables, which a generator builds\n * from `PLAN_ENTITLEMENTS` with no plugin loaded, and the customer's plan\n * comparison, which renders before any plugin surface does. A registry one of\n * them had not filled would publish a plan without the band — a missing row on\n * the price list, or a quota gate reading nothing — with nothing red. So a\n * first-party plugin names a function under `register.planEntitlements` in\n * `plugins.config.json`; `tools/scripts/generate-plugin-manifests.mjs` loads\n * `${package}/plan-entitlements`, calls it, validates the answer and compiles\n * it into `first-party-plugins.generated.ts` as data. There is no runtime\n * registrar, for the reason `plugin-org-capacity` gives: a registrar nothing\n * can safely call is worse than none.\n *\n * ## What a missing figure means\n *\n * A declaration names every plan: the generated rows are typed\n * `Record<OrgPlan, …>`, so a plan left out does not compile. A key nobody\n * declares is absent from the table, and each reader answers absence in the\n * closed direction — a quota reads as nothing included, a feature as off.\n * `planQuotaOf` below is that reading, and it never answers \"unlimited\" or\n * \"free\" for a key that has no figure.\n *\n * ## One key, one owner, and never one of core's\n *\n * The generator refuses a key two plugins declare. A key the platform's own\n * rows already carry is refused by `plan-entitlements.spec.ts` rather than\n * here, because the generator cannot read core's rows without loading the\n * module that imports this one; the composition keeps core's figure either\n * way, so a collision can shadow nothing a customer is charged.\n */\n\nimport type { OrgPlan } from '../foundation'\nimport {\n  PLUGIN_PLAN_FEATURES_DECLARED,\n  PLUGIN_PLAN_QUOTAS_DECLARED,\n} from './first-party-plugins.generated'\n\n/** A numeric entitlement a plugin owns: a band, a daily pace, a take rate. */\nexport interface PluginPlanQuotaDeclaration {\n  /** The stored key, exactly as `OrgEntitlements` and an override spell it. */\n  key: string\n  /** What a staff page calls it. */\n  label: string\n  /**\n   * What each plan includes. `Infinity` is `UNLIMITED`; every other value is\n   * a finite, non-negative number.\n   */\n  byPlan: Readonly<Record<OrgPlan, number>>\n  /**\n   * A PRICE rather than a cap — a percentage of a sale — so an uncapped plan\n   * comp must never lift it (`PRICE_ENTITLEMENT_KEYS`).\n   */\n  price?: boolean\n}\n\n/** A boolean gate a plugin owns. */\nexport interface PluginPlanFeatureDeclaration {\n  /** The stored key, exactly as `OrgFeatureFlags` and an override spell it. */\n  key: string\n  label: string\n  byPlan: Readonly<Record<OrgPlan, boolean>>\n}\n\n/** What a plugin's `planEntitlements` function answers. */\nexport interface PluginPlanEntitlementsDeclaration {\n  quotas?: readonly PluginPlanQuotaDeclaration[]\n  features?: readonly PluginPlanFeatureDeclaration[]\n}\n\n/** A quota declaration with the plugin that made it. */\nexport type ResolvedPluginPlanQuota = PluginPlanQuotaDeclaration & {\n  pluginId: string\n}\n\n/** A feature declaration with the plugin that made it. */\nexport type ResolvedPluginPlanFeature = PluginPlanFeatureDeclaration & {\n  pluginId: string\n}\n\n/** Every declared quota, in catalog order. */\nexport function pluginPlanQuotas(): readonly ResolvedPluginPlanQuota[] {\n  return PLUGIN_PLAN_QUOTAS_DECLARED\n}\n\n/** Every declared feature, in catalog order. */\nexport function pluginPlanFeatures(): readonly ResolvedPluginPlanFeature[] {\n  return PLUGIN_PLAN_FEATURES_DECLARED\n}\n\n/** The plugin that declared a quota or feature key, or `null`. */\nexport function pluginPlanEntitlementOwner(key: string): string | null {\n  return (\n    PLUGIN_PLAN_QUOTAS_DECLARED.find((one) => one.key === key)?.pluginId ??\n    PLUGIN_PLAN_FEATURES_DECLARED.find((one) => one.key === key)?.pluginId ??\n    null\n  )\n}\n\n/** The declared quotas' figures for one plan, keyed by the stored key. */\nexport function pluginPlanQuotaRow(plan: OrgPlan): Record<string, number> {\n  return Object.fromEntries(\n    PLUGIN_PLAN_QUOTAS_DECLARED.map((one) => [one.key, one.byPlan[plan]]),\n  )\n}\n\n/** The declared features' answers for one plan, keyed by the stored key. */\nexport function pluginPlanFeatureRow(plan: OrgPlan): Record<string, boolean> {\n  return Object.fromEntries(\n    PLUGIN_PLAN_FEATURES_DECLARED.map((one) => [one.key, one.byPlan[plan]]),\n  )\n}\n\n/**\n * A resolved quota read by its key — the reading core uses for a key a plugin\n * owns, since core compiles without the plugin's type augmentation.\n *\n * ⚑ ABSENT IS NOTHING INCLUDED. A key no plugin declares, or a value that is\n * not a number, reads as `0`: every gate that compares usage against it\n * refuses, and every meter drawn from it shows full. That is the same\n * direction `plugin-org-capacity` answers an unknown capacity in. Reading\n * absence as `UNLIMITED` would be a plan giving away what nobody declared it\n * sells.\n */\nexport function planQuotaOf(entitlements: object, key: string): number {\n  const value = (entitlements as Record<string, unknown>)[key]\n  return typeof value === 'number' && !Number.isNaN(value) ? value : 0\n}\n"],"names":["PLUGIN_PLAN_FEATURES_DECLARED","PLUGIN_PLAN_QUOTAS_DECLARED","pluginPlanQuotas","pluginPlanFeatures","pluginPlanEntitlementOwner","key","find","one","pluginId","pluginPlanQuotaRow","plan","Object","fromEntries","map","byPlan","pluginPlanFeatureRow","planQuotaOf","entitlements","value","Number","isNaN"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GAGD,SACEA,6BAA6B,EAC7BC,2BAA2B,QACtB,qCAAiC;AA4CxC,4CAA4C,GAC5C,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,8CAA8C,GAC9C,OAAO,SAASE;IACd,OAAOH;AACT;AAEA,gEAAgE,GAChE,OAAO,SAASI,2BAA2BC,GAAW;QAElDJ;QAAAA,mCACAD;IAFF,QACEC,iBAAAA,oCAAAA,4BAA4BK,IAAI,CAAC,CAACC,MAAQA,IAAIF,GAAG,KAAKA,yBAAtDJ,kCAA4DO,QAAQ,qBACpER,sCAAAA,8BAA8BM,IAAI,CAAC,CAACC,MAAQA,IAAIF,GAAG,KAAKA,yBAAxDL,oCAA8DQ,QAAQ,YADtEP,OAEA;AAEJ;AAEA,wEAAwE,GACxE,OAAO,SAASQ,mBAAmBC,IAAa;IAC9C,OAAOC,OAAOC,WAAW,CACvBX,4BAA4BY,GAAG,CAAC,CAACN,MAAQ;YAACA,IAAIF,GAAG;YAAEE,IAAIO,MAAM,CAACJ,KAAK;SAAC;AAExE;AAEA,0EAA0E,GAC1E,OAAO,SAASK,qBAAqBL,IAAa;IAChD,OAAOC,OAAOC,WAAW,CACvBZ,8BAA8Ba,GAAG,CAAC,CAACN,MAAQ;YAACA,IAAIF,GAAG;YAAEE,IAAIO,MAAM,CAACJ,KAAK;SAAC;AAE1E;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASM,YAAYC,YAAoB,EAAEZ,GAAW;IAC3D,MAAMa,QAAQ,AAACD,YAAwC,CAACZ,IAAI;IAC5D,OAAO,OAAOa,UAAU,YAAY,CAACC,OAAOC,KAAK,CAACF,SAASA,QAAQ;AACrE"}