@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-entitlement-keys.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @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.
+ */
+/**
+ * The TYPE half of a plugin's billing and access keys (AGL-3124).
+ *
+ * AGL-2940 built `registerPluginEntitlements`, and the registration migrated:
+ * a plugin declares its seat add-ons, its feature flags, its lockdown levers
+ * and its permissions, and the catalogs that used to be edited per key read
+ * the declarations. What did not migrate is the TYPE. `OrgEntitlements` and
+ * `OrgFeatureFlags` still spell out keys named after seven plugin domains, so
+ * a plugin can register a key the platform's own types have never heard of,
+ * and a key it cannot register is one the platform still has to be edited
+ * for.
+ *
+ * This module closes that half. The two interfaces below are EMPTY and are
+ * meant to be augmented: a plugin declares the type of each key it owns with
+ * `declare module`, and the core shapes compose from them rather than listing
+ * them. The registry beside them is the runtime twin — what a staff page, a
+ * migration or a support answer reads to say which plugin a key came from, and
+ * what refuses two plugins claiming one key before either can resolve it.
+ *
+ * ```ts
+ * // libs/plugins/cellar — the plugin's own module
+ * declare module '@aglyn/aglyn/plugin-manager/plugin-entitlement-keys' {
+ *   interface PluginEntitlementQuotas {
+ *     bottlesPerHost?: number
+ *   }
+ *   interface PluginEntitlementFeatures {
+ *     cellarTastings?: boolean
+ *   }
+ * }
+ * ```
+ *
+ * From then on `entitlements.bottlesPerHost` type-checks everywhere
+ * `OrgEntitlements` is read, and nothing in the core names a bottle.
+ *
+ * ## Why the interfaces are declared here and not beside the shapes
+ *
+ * The augmentation target has to be a module a plugin may import, and a plugin
+ * imports the plugin-manager seams by design. The billing types are on the
+ * package's public surface and are read through the foundation barrel, which a
+ * published page must never reach; the composition is a type-only edge in that
+ * direction, which TypeScript erases, so the shapes gain the plugin half
+ * without the graph gaining an edge.
+ *
+ * ## The NUMBERS stay where they are checked
+ *
+ * A key's price is not here and must not come here. A seat add-on's price is a
+ * row in `PLAN_PRICING`, read by the Stripe wiring and reconciled by
+ * `check-pricing-drift`; a declaration names the key and what the key MEANS,
+ * and nothing here restates a price. That is the same line
+ * `plugin-entitlements` draws, for the same reason: two places that both hold
+ * a number are two places that can disagree about what a customer is charged.
+ *
+ * ## One key, one owner
+ *
+ * A key is stored under an organization's entitlements and resolved into what
+ * that organization may do. Two plugins declaring one key would be two meanings for
+ * one stored value, so a key another plugin declared is refused naming both,
+ * and the whole registration is refused with it — half a plugin's keys landing
+ * would be worse than none.
+ */
+/**
+ * Quota and limit keys plugins add to `OrgEntitlements`. Augment with
+ * `declare module`, declaring each key OPTIONAL — an entitlement is resolved
+ * and may be absent, exactly like every key the core declares.
+ */
+export interface PluginEntitlementQuotas {
+}
+/** Feature flags plugins add to `OrgFeatureFlags`, on the same terms. */
+export interface PluginEntitlementFeatures {
+}
+/**
+ * The two halves above as MAPPED types, for composing into a type alias
+ * rather than into an interface.
+ *
+ * Not a style choice. TypeScript hands an implicit string index signature to a
+ * mapped type and withholds it from an interface, and several readers pass a
+ * resolved entitlements or features object where a `Record<string, boolean>`
+ * or `Record<string, unknown>` is wanted — a quota line reading every number,
+ * a digest reading every gate. Intersecting `Required<CoreOrgFeatureFlags>`
+ * with the raw interface loses that index signature and those readers stop
+ * compiling, for a plugin half that is empty. Mapping it keeps them.
+ *
+ * An interface is still what a plugin AUGMENTS: `declare module` merges into
+ * an interface and not into a type alias, so the pair is the augmentation
+ * target and its composable form, and the mapping follows whatever is
+ * declared.
+ */
+export type PluginOrgQuotas = {
+    [Key in keyof PluginEntitlementQuotas]: PluginEntitlementQuotas[Key];
+};
+/** See {@link PluginOrgQuotas}. */
+export type PluginOrgFeatures = {
+    [Key in keyof PluginEntitlementFeatures]: PluginEntitlementFeatures[Key];
+};
+/**
+ * What a declared key is, which is what decides where it is read.
+ *
+ * There is deliberately no third kind for a plugin's SETTINGS block on the
+ * organization document. `org-write-deny-coverage.spec.ts` enumerates that
+ * document's fields by reading `org-billing.types.ts`'s source and checks each
+ * one against the Firestore write-deny rules, so a field declared from a
+ * plugin's own file would be a hole in a rules-coverage guard. A plugin's
+ * settings already have a home that is not a hole:
+ * `registerPluginConfigSchema` stores them at `pluginSettings/{pluginId}`,
+ * which is its own document under its own rule.
+ */
+export type PluginEntitlementKeyKind = 
+/** A number in `OrgEntitlements`: a limit, a band, an allowance. */
+'quota'
+/** A boolean in `OrgFeatureFlags`. */
+ | 'feature';
+export interface PluginEntitlementKeyDeclaration {
+    /** The stored key, exactly as the org document spells it. */
+    key: string;
+    kind: PluginEntitlementKeyKind;
+    /** What a staff page and a support answer call it. */
+    label: string;
+    /**
+     * What the key means — for a quota, what it counts and what it does not.
+     * The confusions this platform has already had (a catalog cap read as a
+     * traffic cap, a daily pace read as a monthly band) all came from a key
+     * whose name said something narrower or wider than it meant.
+     */
+    description?: string;
+}
+export interface PluginEntitlementKeyRegistration {
+    pluginId: string;
+    keys: readonly PluginEntitlementKeyDeclaration[];
+}
+/** A declaration with the plugin that made it. */
+export type ResolvedPluginEntitlementKey = PluginEntitlementKeyDeclaration & {
+    pluginId: string;
+};
+/**
+ * Declares the entitlement keys a plugin owns. The owner is the loader's
+ * marker when a register fn is running, else `registration.pluginId`; with
+ * neither the registration throws. Idempotent per plugin — re-registering
+ * replaces that plugin's declarations. A key another plugin declared refuses
+ * the whole registration, naming both.
+ */
+export declare function registerPluginEntitlementKeys(registration: PluginEntitlementKeyRegistration): void;
+/** Every declared key, with its owner, in registration order. */
+export declare function listPluginEntitlementKeys(): ResolvedPluginEntitlementKey[];
+/** One declared key, with its owner, or `null` when no plugin declares it. */
+export declare function pluginEntitlementKey(key: string): ResolvedPluginEntitlementKey | null;
+/** The plugin that declared a key, for attribution, or `undefined`. */
+export declare function pluginIdForEntitlementKey(key: string): string | undefined;
+/** The declared keys of one kind, with their owners, in registration order. */
+export declare function listPluginEntitlementKeysOfKind(kind: PluginEntitlementKeyKind): ResolvedPluginEntitlementKey[];
+/** Drops a plugin's declarations — what a bundle unloading calls. */
+export declare function unregisterPluginEntitlementKeys(pluginId: string): void;
+/** Test seam: forget every declaration. */
+export declare function resetPluginEntitlementKeysForTests(): void;

package/src/lib/plugin-manager/plugin-entitlement-keys.js

@@ -0,0 +1,84 @@
+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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const registrations = new Map();
+function ownerOf(key) {
+    for (const entry of registrations.values()){
+        if (entry.keys.some((one)=>one.key === key)) return entry.pluginId;
+    }
+    return undefined;
+}
+/**
+ * Declares the entitlement keys a plugin owns. The owner is the loader's
+ * marker when a register fn is running, else `registration.pluginId`; with
+ * neither the registration throws. Idempotent per plugin — re-registering
+ * replaces that plugin's declarations. A key another plugin declared refuses
+ * the whole registration, naming both.
+ */ export function registerPluginEntitlementKeys(registration) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : registration.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error('plugin entitlement keys registered with no owner: pass ' + '{ pluginId } when registering outside a plugin register fn');
+    }
+    const keys = registration.keys.map((declaration)=>{
+        var _ref;
+        var _declaration_key, _declaration_label;
+        const key = (_ref = (_declaration_key = declaration.key) == null ? void 0 : _declaration_key.trim()) != null ? _ref : '';
+        if (!key) throw new Error('a plugin entitlement key needs a key');
+        if (!((_declaration_label = declaration.label) == null ? void 0 : _declaration_label.trim())) {
+            throw new Error(`plugin entitlement key "${key}" needs a label`);
+        }
+        const owner = ownerOf(key);
+        if (owner && owner !== pluginId) {
+            throw new Error(`entitlement key "${key}" is already declared by "${owner}"; ` + `refused "${pluginId}"`);
+        }
+        return _extends({}, declaration, {
+            key
+        });
+    });
+    registrations.set(pluginId, {
+        pluginId,
+        keys
+    });
+}
+/** Every declared key, with its owner, in registration order. */ export function listPluginEntitlementKeys() {
+    return [
+        ...registrations.values()
+    ].flatMap((entry)=>entry.keys.map((one)=>_extends({}, one, {
+                pluginId: entry.pluginId
+            })));
+}
+/** One declared key, with its owner, or `null` when no plugin declares it. */ export function pluginEntitlementKey(key) {
+    var _listPluginEntitlementKeys_find;
+    const wanted = key.trim();
+    return (_listPluginEntitlementKeys_find = listPluginEntitlementKeys().find((one)=>one.key === wanted)) != null ? _listPluginEntitlementKeys_find : null;
+}
+/** The plugin that declared a key, for attribution, or `undefined`. */ export function pluginIdForEntitlementKey(key) {
+    var _pluginEntitlementKey;
+    return (_pluginEntitlementKey = pluginEntitlementKey(key)) == null ? void 0 : _pluginEntitlementKey.pluginId;
+}
+/** The declared keys of one kind, with their owners, in registration order. */ export function listPluginEntitlementKeysOfKind(kind) {
+    return listPluginEntitlementKeys().filter((one)=>one.kind === kind);
+}
+/** Drops a plugin's declarations — what a bundle unloading calls. */ export function unregisterPluginEntitlementKeys(pluginId) {
+    registrations.delete(pluginId.trim());
+}
+/** Test seam: forget every declaration. */ export function resetPluginEntitlementKeysForTests() {
+    registrations.clear();
+}
+
+//# sourceMappingURL=plugin-entitlement-keys.js.map

package/src/lib/plugin-manager/plugin-entitlement-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlement-keys.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'\n\n/**\n * The TYPE half of a plugin's billing and access keys (AGL-3124).\n *\n * AGL-2940 built `registerPluginEntitlements`, and the registration migrated:\n * a plugin declares its seat add-ons, its feature flags, its lockdown levers\n * and its permissions, and the catalogs that used to be edited per key read\n * the declarations. What did not migrate is the TYPE. `OrgEntitlements` and\n * `OrgFeatureFlags` still spell out keys named after seven plugin domains, so\n * a plugin can register a key the platform's own types have never heard of,\n * and a key it cannot register is one the platform still has to be edited\n * for.\n *\n * This module closes that half. The two interfaces below are EMPTY and are\n * meant to be augmented: a plugin declares the type of each key it owns with\n * `declare module`, and the core shapes compose from them rather than listing\n * them. The registry beside them is the runtime twin — what a staff page, a\n * migration or a support answer reads to say which plugin a key came from, and\n * what refuses two plugins claiming one key before either can resolve it.\n *\n * ```ts\n * // libs/plugins/cellar — the plugin's own module\n * declare module '@aglyn/aglyn/plugin-manager/plugin-entitlement-keys' {\n *   interface PluginEntitlementQuotas {\n *     bottlesPerHost?: number\n *   }\n *   interface PluginEntitlementFeatures {\n *     cellarTastings?: boolean\n *   }\n * }\n * ```\n *\n * From then on `entitlements.bottlesPerHost` type-checks everywhere\n * `OrgEntitlements` is read, and nothing in the core names a bottle.\n *\n * ## Why the interfaces are declared here and not beside the shapes\n *\n * The augmentation target has to be a module a plugin may import, and a plugin\n * imports the plugin-manager seams by design. The billing types are on the\n * package's public surface and are read through the foundation barrel, which a\n * published page must never reach; the composition is a type-only edge in that\n * direction, which TypeScript erases, so the shapes gain the plugin half\n * without the graph gaining an edge.\n *\n * ## The NUMBERS stay where they are checked\n *\n * A key's price is not here and must not come here. A seat add-on's price is a\n * row in `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the key and what the key MEANS,\n * and nothing here restates a price. That is the same line\n * `plugin-entitlements` draws, for the same reason: two places that both hold\n * a number are two places that can disagree about what a customer is charged.\n *\n * ## One key, one owner\n *\n * A key is stored under an organization's entitlements and resolved into what\n * that organization may do. Two plugins declaring one key would be two meanings for\n * one stored value, so a key another plugin declared is refused naming both,\n * and the whole registration is refused with it — half a plugin's keys landing\n * would be worse than none.\n */\n\n/**\n * Quota and limit keys plugins add to `OrgEntitlements`. Augment with\n * `declare module`, declaring each key OPTIONAL — an entitlement is resolved\n * and may be absent, exactly like every key the core declares.\n */\nexport interface PluginEntitlementQuotas {}\n\n/** Feature flags plugins add to `OrgFeatureFlags`, on the same terms. */\nexport interface PluginEntitlementFeatures {}\n\n/**\n * The two halves above as MAPPED types, for composing into a type alias\n * rather than into an interface.\n *\n * Not a style choice. TypeScript hands an implicit string index signature to a\n * mapped type and withholds it from an interface, and several readers pass a\n * resolved entitlements or features object where a `Record<string, boolean>`\n * or `Record<string, unknown>` is wanted — a quota line reading every number,\n * a digest reading every gate. Intersecting `Required<CoreOrgFeatureFlags>`\n * with the raw interface loses that index signature and those readers stop\n * compiling, for a plugin half that is empty. Mapping it keeps them.\n *\n * An interface is still what a plugin AUGMENTS: `declare module` merges into\n * an interface and not into a type alias, so the pair is the augmentation\n * target and its composable form, and the mapping follows whatever is\n * declared.\n */\nexport type PluginOrgQuotas = {\n  [Key in keyof PluginEntitlementQuotas]: PluginEntitlementQuotas[Key]\n}\n/** See {@link PluginOrgQuotas}. */\nexport type PluginOrgFeatures = {\n  [Key in keyof PluginEntitlementFeatures]: PluginEntitlementFeatures[Key]\n}\n\n/**\n * What a declared key is, which is what decides where it is read.\n *\n * There is deliberately no third kind for a plugin's SETTINGS block on the\n * organization document. `org-write-deny-coverage.spec.ts` enumerates that\n * document's fields by reading `org-billing.types.ts`'s source and checks each\n * one against the Firestore write-deny rules, so a field declared from a\n * plugin's own file would be a hole in a rules-coverage guard. A plugin's\n * settings already have a home that is not a hole:\n * `registerPluginConfigSchema` stores them at `pluginSettings/{pluginId}`,\n * which is its own document under its own rule.\n */\nexport type PluginEntitlementKeyKind =\n  /** A number in `OrgEntitlements`: a limit, a band, an allowance. */\n  | 'quota'\n  /** A boolean in `OrgFeatureFlags`. */\n  | 'feature'\n\nexport interface PluginEntitlementKeyDeclaration {\n  /** The stored key, exactly as the org document spells it. */\n  key: string\n  kind: PluginEntitlementKeyKind\n  /** What a staff page and a support answer call it. */\n  label: string\n  /**\n   * What the key means — for a quota, what it counts and what it does not.\n   * The confusions this platform has already had (a catalog cap read as a\n   * traffic cap, a daily pace read as a monthly band) all came from a key\n   * whose name said something narrower or wider than it meant.\n   */\n  description?: string\n}\n\nexport interface PluginEntitlementKeyRegistration {\n  pluginId: string\n  keys: readonly PluginEntitlementKeyDeclaration[]\n}\n\n/** A declaration with the plugin that made it. */\nexport type ResolvedPluginEntitlementKey = PluginEntitlementKeyDeclaration & {\n  pluginId: string\n}\n\nconst registrations = new Map<string, PluginEntitlementKeyRegistration>()\n\nfunction ownerOf(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.keys.some((one) => one.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\n/**\n * Declares the entitlement keys a plugin owns. The owner is the loader's\n * marker when a register fn is running, else `registration.pluginId`; with\n * neither the registration throws. Idempotent per plugin — re-registering\n * replaces that plugin's declarations. A key another plugin declared refuses\n * the whole registration, naming both.\n */\nexport function registerPluginEntitlementKeys(\n  registration: PluginEntitlementKeyRegistration,\n): void {\n  const pluginId = (\n    getRegisteringPluginId() ??\n    registration.pluginId ??\n    ''\n  ).trim()\n  if (!pluginId) {\n    throw new Error(\n      'plugin entitlement keys registered with no owner: pass ' +\n        '{ pluginId } when registering outside a plugin register fn',\n    )\n  }\n  const keys = registration.keys.map((declaration) => {\n    const key = declaration.key?.trim() ?? ''\n    if (!key) throw new Error('a plugin entitlement key needs a key')\n    if (!declaration.label?.trim()) {\n      throw new Error(`plugin entitlement key \"${key}\" needs a label`)\n    }\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `entitlement key \"${key}\" is already declared by \"${owner}\"; ` +\n          `refused \"${pluginId}\"`,\n      )\n    }\n    return { ...declaration, key }\n  })\n  registrations.set(pluginId, { pluginId, keys })\n}\n\n/** Every declared key, with its owner, in registration order. */\nexport function listPluginEntitlementKeys(): ResolvedPluginEntitlementKey[] {\n  return [...registrations.values()].flatMap((entry) =>\n    entry.keys.map((one) => ({ ...one, pluginId: entry.pluginId })),\n  )\n}\n\n/** One declared key, with its owner, or `null` when no plugin declares it. */\nexport function pluginEntitlementKey(\n  key: string,\n): ResolvedPluginEntitlementKey | null {\n  const wanted = key.trim()\n  return (\n    listPluginEntitlementKeys().find((one) => one.key === wanted) ?? null\n  )\n}\n\n/** The plugin that declared a key, for attribution, or `undefined`. */\nexport function pluginIdForEntitlementKey(key: string): string | undefined {\n  return pluginEntitlementKey(key)?.pluginId\n}\n\n/** The declared keys of one kind, with their owners, in registration order. */\nexport function listPluginEntitlementKeysOfKind(\n  kind: PluginEntitlementKeyKind,\n): ResolvedPluginEntitlementKey[] {\n  return listPluginEntitlementKeys().filter((one) => one.kind === kind)\n}\n\n/** Drops a plugin's declarations — what a bundle unloading calls. */\nexport function unregisterPluginEntitlementKeys(pluginId: string): void {\n  registrations.delete(pluginId.trim())\n}\n\n/** Test seam: forget every declaration. */\nexport function resetPluginEntitlementKeysForTests(): void {\n  registrations.clear()\n}\n"],"names":["getRegisteringPluginId","registrations","Map","ownerOf","key","entry","values","keys","some","one","pluginId","undefined","registerPluginEntitlementKeys","registration","trim","Error","map","declaration","label","owner","set","listPluginEntitlementKeys","flatMap","pluginEntitlementKey","wanted","find","pluginIdForEntitlementKey","listPluginEntitlementKeysOfKind","kind","filter","unregisterPluginEntitlementKeys","delete","resetPluginEntitlementKeysForTests","clear"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AA6IxE,MAAMC,gBAAgB,IAAIC;AAE1B,SAASC,QAAQC,GAAW;IAC1B,KAAK,MAAMC,SAASJ,cAAcK,MAAM,GAAI;QAC1C,IAAID,MAAME,IAAI,CAACC,IAAI,CAAC,CAACC,MAAQA,IAAIL,GAAG,KAAKA,MAAM,OAAOC,MAAMK,QAAQ;IACtE;IACA,OAAOC;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,8BACdC,YAA8C;QAG5Cb,MAAAA;IADF,MAAMU,WAAW,EACfV,QAAAA,0BAAAA,oCAAAA,0BACAa,aAAaH,QAAQ,YADrBV,OAEA,IACAc,IAAI;IACN,IAAI,CAACJ,UAAU;QACb,MAAM,IAAIK,MACR,4DACE;IAEN;IACA,MAAMR,OAAOM,aAAaN,IAAI,CAACS,GAAG,CAAC,CAACC;;YACtBA,kBAEPA;QAFL,MAAMb,eAAMa,mBAAAA,YAAYb,GAAG,qBAAfa,iBAAiBH,IAAI,qBAAM;QACvC,IAAI,CAACV,KAAK,MAAM,IAAIW,MAAM;QAC1B,IAAI,GAACE,qBAAAA,YAAYC,KAAK,qBAAjBD,mBAAmBH,IAAI,KAAI;YAC9B,MAAM,IAAIC,MAAM,CAAC,wBAAwB,EAAEX,IAAI,eAAe,CAAC;QACjE;QACA,MAAMe,QAAQhB,QAAQC;QACtB,IAAIe,SAASA,UAAUT,UAAU;YAC/B,MAAM,IAAIK,MACR,CAAC,iBAAiB,EAAEX,IAAI,0BAA0B,EAAEe,MAAM,GAAG,CAAC,GAC5D,CAAC,SAAS,EAAET,SAAS,CAAC,CAAC;QAE7B;QACA,OAAO,aAAKO;YAAab;;IAC3B;IACAH,cAAcmB,GAAG,CAACV,UAAU;QAAEA;QAAUH;IAAK;AAC/C;AAEA,+DAA+D,GAC/D,OAAO,SAASc;IACd,OAAO;WAAIpB,cAAcK,MAAM;KAAG,CAACgB,OAAO,CAAC,CAACjB,QAC1CA,MAAME,IAAI,CAACS,GAAG,CAAC,CAACP,MAAS,aAAKA;gBAAKC,UAAUL,MAAMK,QAAQ;;AAE/D;AAEA,4EAA4E,GAC5E,OAAO,SAASa,qBACdnB,GAAW;QAITiB;IAFF,MAAMG,SAASpB,IAAIU,IAAI;IACvB,QACEO,kCAAAA,4BAA4BI,IAAI,CAAC,CAAChB,MAAQA,IAAIL,GAAG,KAAKoB,mBAAtDH,kCAAiE;AAErE;AAEA,qEAAqE,GACrE,OAAO,SAASK,0BAA0BtB,GAAW;QAC5CmB;IAAP,QAAOA,wBAAAA,qBAAqBnB,yBAArBmB,sBAA2Bb,QAAQ;AAC5C;AAEA,6EAA6E,GAC7E,OAAO,SAASiB,gCACdC,IAA8B;IAE9B,OAAOP,4BAA4BQ,MAAM,CAAC,CAACpB,MAAQA,IAAImB,IAAI,KAAKA;AAClE;AAEA,mEAAmE,GACnE,OAAO,SAASE,gCAAgCpB,QAAgB;IAC9DT,cAAc8B,MAAM,CAACrB,SAASI,IAAI;AACpC;AAEA,yCAAyC,GACzC,OAAO,SAASkB;IACd/B,cAAcgC,KAAK;AACrB"}

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

@@ -0,0 +1,181 @@
+/**
+ * @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.
+ */
+/**
+ * Plugin-declared billing and access keys (AGL-2940).
+ *
+ * A plugin that sells something, gates something, or can be switched off in
+ * an incident declares the KEYS here — a seat add-on, a feature flag, a
+ * lockdown lever, a permission — and the core catalogs that used to be
+ * edited for each one read the declarations instead:
+ *
+ * - `plan-entitlements` folds every registered seat add-on into
+ *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)
+ *   and answers a registered feature's plan defaults;
+ * - `lockdown` lists a registered lever on the staff page, carries its label,
+ *   its staff-bypass rule and its visitor notice, and maps the API paths it
+ *   names onto it for the plugin dispatcher;
+ * - `plugin-permissions` receives the permissions with the owner filled in;
+ * - `org-permissions` folds every declared catalog key into the org
+ *   permission catalog — the role editor, custom roles, per-member overrides
+ *   and the rules stamp — and `host-permissions` decides the keys that
+ *   declare host-role defaults for a site collaborator, per site.
+ *
+ * The NUMBERS stay where they are checked. A seat add-on's price is a row in
+ * `PLAN_PRICING`, read by the Stripe wiring and reconciled by
+ * `check-pricing-drift`; a declaration names the quota it widens and by how
+ * much per plan, and nothing here restates a price.
+ *
+ * Registration order is deterministic: the catalog order of
+ * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules
+ * load in parallel, so the order they REGISTER in is whatever the network
+ * gave, and a list that followed it would put the staff lockdown checklist
+ * in a different order per session.
+ */
+import type { HostAccessRole, OrgPlan, OrgRole } from '../foundation';
+import { type PluginPermission } from './plugin-permissions';
+export interface PluginSeatAddonDeclaration {
+    /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */
+    key: string;
+    label: string;
+    /**
+     * How many purchased units count. `1` for an org-wide add-on that is
+     * bought once, where a doubled webhook item or a hand edit above one is
+     * still one purchase; absent to count the stored quantity.
+     */
+    maxUnits?: number;
+    /**
+     * The quota each unit widens, per plan: the resolved entitlement named by
+     * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold
+     * on declares 0.
+     */
+    quota?: {
+        key: string;
+        perUnitByPlan: Readonly<Record<OrgPlan, number>>;
+    };
+    /** Feature flags a purchased unit switches on. */
+    features?: readonly string[];
+}
+export interface PluginFeatureDeclaration {
+    /** The `OrgFeatureFlags` key. */
+    key: string;
+    label: string;
+    /**
+     * The plan defaults, when the key is not one the plan tables already
+     * carry. Absent means the plan tables decide, which is the case for every
+     * key that predates this registry.
+     */
+    defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>;
+}
+export interface PluginLockdownFeatureDeclaration {
+    /** The lever's wire identity (`ai-generate`). */
+    key: string;
+    /** The staff checklist's label. */
+    label: string;
+    /**
+     * Whether a verified staff claim passes the lock. Granted where a staff
+     * action aids incident response — one real call proves a provider is back
+     * — and withheld where the staff action would BE the incident.
+     */
+    staffBypass: boolean;
+    /**
+     * What a visitor reads while the lever is pulled: what is paused AND what
+     * still works. The expected-back window is appended by the notice builder.
+     */
+    notice: {
+        title: string;
+        body: string;
+    };
+    /**
+     * Plugin API paths the lever gates at the dispatcher: exact paths, and
+     * prefixes matched on a segment boundary (`ai/generate` also gates
+     * `ai/generate/section`, never `ai/generated-report`).
+     */
+    apiPaths?: {
+        exact?: readonly string[];
+        prefixes?: readonly string[];
+    };
+}
+/**
+ * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular
+ * map custom roles and per-member overrides are stored in, that
+ * `resolveOrgPermissions` layers and the rules stamp carries, and that the
+ * role editor lists. A declared key is stored, layered and resolved exactly
+ * like a core key; the declaration supplies what a core key's catalog entry
+ * and role table supply.
+ */
+export interface PluginOrgPermissionDeclaration {
+    /** The dotted key a custom role and a per-member override store (`reviews.reply`). */
+    key: string;
+    /** The role editor's line for the key, and the word a refusal names. */
+    label: string;
+    /** What the key opens, under the label in the role editor. */
+    description: string;
+    /** Each org role's verdict when no custom role or per-member override sets the key. */
+    roleDefaults: Readonly<Record<OrgRole, boolean>>;
+    /**
+     * Each HOST role's verdict, for a key a site collaborator holds per site.
+     *
+     * A collaborator's membership carries no org standing to refine — it
+     * exists only to carry access to named sites — so a key with this field is
+     * decided for them on the site a request names: the host role they hold
+     * there, refined by the per-site toggle on their member document. A key
+     * without it is never held by a collaborator.
+     */
+    hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>;
+}
+export interface PluginEntitlementRegistration {
+    pluginId: string;
+    seatAddons?: readonly PluginSeatAddonDeclaration[];
+    features?: readonly PluginFeatureDeclaration[];
+    lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[];
+    /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */
+    permissions?: readonly Omit<PluginPermission, 'pluginId'>[];
+    /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */
+    orgPermissions?: readonly PluginOrgPermissionDeclaration[];
+}
+/** Calls `listener` after every registration and reset; answers the unsubscribe. */
+export declare function subscribePluginEntitlements(listener: () => void): () => void;
+/**
+ * Idempotent per plugin — re-registration replaces that plugin's
+ * declarations. A seat add-on, lockdown or catalog permission key another
+ * plugin already owns refuses the whole registration: one key, one owner,
+ * or the two declarations disagree about what the key means.
+ */
+export declare function registerPluginEntitlements(registration: PluginEntitlementRegistration): void;
+/** Every declared catalog permission, in catalog order, with the plugin that declared it. */
+export declare function listPluginOrgPermissions(): Array<PluginOrgPermissionDeclaration & {
+    pluginId: string;
+}>;
+/** Every declared seat add-on, in catalog order. */
+export declare function listPluginSeatAddons(): PluginSeatAddonDeclaration[];
+/** One declared seat add-on by its `seatAddons` key. */
+export declare function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined;
+/** Every declared feature, in catalog order. */
+export declare function listPluginFeatures(): PluginFeatureDeclaration[];
+/** Every declared lockdown lever, in catalog order. */
+export declare function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[];
+/** One declared lockdown lever by key. */
+export declare function pluginLockdownFeature(key: string): PluginLockdownFeatureDeclaration | undefined;
+/** The plugin that declared a lockdown lever, for attribution. */
+export declare function pluginIdForLockdownFeature(key: string): string | undefined;
+/** Every registration, in catalog order. */
+export declare function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[];
+/**
+ * Test seam: forget every registration. The per-tier permissions stay
+ * registered; the catalog permissions go with their registrations.
+ */
+export declare function resetPluginEntitlementsForTests(): void;

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

@@ -0,0 +1,188 @@
+/**
+ * @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.
+ */ /**
+ * Plugin-declared billing and access keys (AGL-2940).
+ *
+ * A plugin that sells something, gates something, or can be switched off in
+ * an incident declares the KEYS here — a seat add-on, a feature flag, a
+ * lockdown lever, a permission — and the core catalogs that used to be
+ * edited for each one read the declarations instead:
+ *
+ * - `plan-entitlements` folds every registered seat add-on into
+ *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)
+ *   and answers a registered feature's plan defaults;
+ * - `lockdown` lists a registered lever on the staff page, carries its label,
+ *   its staff-bypass rule and its visitor notice, and maps the API paths it
+ *   names onto it for the plugin dispatcher;
+ * - `plugin-permissions` receives the permissions with the owner filled in;
+ * - `org-permissions` folds every declared catalog key into the org
+ *   permission catalog — the role editor, custom roles, per-member overrides
+ *   and the rules stamp — and `host-permissions` decides the keys that
+ *   declare host-role defaults for a site collaborator, per site.
+ *
+ * The NUMBERS stay where they are checked. A seat add-on's price is a row in
+ * `PLAN_PRICING`, read by the Stripe wiring and reconciled by
+ * `check-pricing-drift`; a declaration names the quota it widens and by how
+ * much per plan, and nothing here restates a price.
+ *
+ * Registration order is deterministic: the catalog order of
+ * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules
+ * load in parallel, so the order they REGISTER in is whatever the network
+ * gave, and a list that followed it would put the staff lockdown checklist
+ * in a different order per session.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { FIRST_PARTY_PLUGINS } from "./enabled-plugins.js";
+import { registerPluginPermissions } from "./plugin-permissions.js";
+const registrations = new Map();
+/**
+ * Readers of the registrations that keep a derived view in step with them —
+ * the org permission catalog rebuilds itself on every registration and
+ * reset, because a plugin's declarations can register after a module that
+ * imported the catalog was evaluated.
+ */ const listeners = new Set();
+/** Calls `listener` after every registration and reset; answers the unsubscribe. */ export function subscribePluginEntitlements(listener) {
+    listeners.add(listener);
+    return ()=>{
+        listeners.delete(listener);
+    };
+}
+function notifyListeners() {
+    for (const listener of [
+        ...listeners
+    ])listener();
+}
+const CATALOG_ORDER = new Map(FIRST_PARTY_PLUGINS.map((plugin, index)=>[
+        plugin.id,
+        index
+    ]));
+function catalogRank(pluginId) {
+    var _CATALOG_ORDER_get;
+    return (_CATALOG_ORDER_get = CATALOG_ORDER.get(pluginId)) != null ? _CATALOG_ORDER_get : Number.MAX_SAFE_INTEGER;
+}
+function orderedRegistrations() {
+    return [
+        ...registrations.values()
+    ].sort((a, b)=>catalogRank(a.pluginId) - catalogRank(b.pluginId) || a.pluginId.localeCompare(b.pluginId));
+}
+function refuseStolenKeys(pluginId, kind, keys, ownerOf) {
+    for (const key of keys){
+        const owner = ownerOf(key);
+        if (owner && owner !== pluginId) {
+            throw new Error(`${kind} "${key}" is already declared by "${owner}"; refused "${pluginId}"`);
+        }
+    }
+}
+/**
+ * Idempotent per plugin — re-registration replaces that plugin's
+ * declarations. A seat add-on, lockdown or catalog permission key another
+ * plugin already owns refuses the whole registration: one key, one owner,
+ * or the two declarations disagree about what the key means.
+ */ export function registerPluginEntitlements(registration) {
+    var _registration_seatAddons, _registration_lockdownFeatures, _registration_orgPermissions;
+    var _registration_permissions;
+    const pluginId = registration.pluginId.trim();
+    if (!pluginId) throw new Error('plugin entitlements need a pluginId');
+    refuseStolenKeys(pluginId, 'seat add-on', ((_registration_seatAddons = registration.seatAddons) != null ? _registration_seatAddons : []).map((entry)=>entry.key), (key)=>pluginSeatAddonOwner(key));
+    refuseStolenKeys(pluginId, 'lockdown feature', ((_registration_lockdownFeatures = registration.lockdownFeatures) != null ? _registration_lockdownFeatures : []).map((entry)=>entry.key), (key)=>pluginLockdownFeatureOwner(key));
+    refuseStolenKeys(pluginId, 'org permission', ((_registration_orgPermissions = registration.orgPermissions) != null ? _registration_orgPermissions : []).map((entry)=>entry.key), (key)=>pluginOrgPermissionOwner(key));
+    registrations.set(pluginId, _extends({}, registration, {
+        pluginId
+    }));
+    if ((_registration_permissions = registration.permissions) == null ? void 0 : _registration_permissions.length) {
+        registerPluginPermissions(registration.permissions.map((permission)=>_extends({}, permission, {
+                pluginId
+            })));
+    }
+    notifyListeners();
+}
+function pluginSeatAddonOwner(key) {
+    for (const entry of registrations.values()){
+        var _entry_seatAddons;
+        if ((_entry_seatAddons = entry.seatAddons) == null ? void 0 : _entry_seatAddons.some((addon)=>addon.key === key)) return entry.pluginId;
+    }
+    return undefined;
+}
+function pluginLockdownFeatureOwner(key) {
+    for (const entry of registrations.values()){
+        var _entry_lockdownFeatures;
+        if ((_entry_lockdownFeatures = entry.lockdownFeatures) == null ? void 0 : _entry_lockdownFeatures.some((feature)=>feature.key === key)) {
+            return entry.pluginId;
+        }
+    }
+    return undefined;
+}
+function pluginOrgPermissionOwner(key) {
+    for (const entry of registrations.values()){
+        var _entry_orgPermissions;
+        if ((_entry_orgPermissions = entry.orgPermissions) == null ? void 0 : _entry_orgPermissions.some((permission)=>permission.key === key)) {
+            return entry.pluginId;
+        }
+    }
+    return undefined;
+}
+/** Every declared catalog permission, in catalog order, with the plugin that declared it. */ export function listPluginOrgPermissions() {
+    return orderedRegistrations().flatMap((entry)=>{
+        var _entry_orgPermissions;
+        return ((_entry_orgPermissions = entry.orgPermissions) != null ? _entry_orgPermissions : []).map((permission)=>_extends({}, permission, {
+                pluginId: entry.pluginId
+            }));
+    });
+}
+/** Every declared seat add-on, in catalog order. */ export function listPluginSeatAddons() {
+    return orderedRegistrations().flatMap((entry)=>{
+        var _entry_seatAddons;
+        return [
+            ...(_entry_seatAddons = entry.seatAddons) != null ? _entry_seatAddons : []
+        ];
+    });
+}
+/** One declared seat add-on by its `seatAddons` key. */ export function pluginSeatAddon(key) {
+    return listPluginSeatAddons().find((entry)=>entry.key === key);
+}
+/** Every declared feature, in catalog order. */ export function listPluginFeatures() {
+    return orderedRegistrations().flatMap((entry)=>{
+        var _entry_features;
+        return [
+            ...(_entry_features = entry.features) != null ? _entry_features : []
+        ];
+    });
+}
+/** Every declared lockdown lever, in catalog order. */ export function listPluginLockdownFeatures() {
+    return orderedRegistrations().flatMap((entry)=>{
+        var _entry_lockdownFeatures;
+        return [
+            ...(_entry_lockdownFeatures = entry.lockdownFeatures) != null ? _entry_lockdownFeatures : []
+        ];
+    });
+}
+/** One declared lockdown lever by key. */ export function pluginLockdownFeature(key) {
+    return listPluginLockdownFeatures().find((entry)=>entry.key === key);
+}
+/** The plugin that declared a lockdown lever, for attribution. */ export function pluginIdForLockdownFeature(key) {
+    return pluginLockdownFeatureOwner(key);
+}
+/** Every registration, in catalog order. */ export function listPluginEntitlementRegistrations() {
+    return orderedRegistrations();
+}
+/**
+ * Test seam: forget every registration. The per-tier permissions stay
+ * registered; the catalog permissions go with their registrations.
+ */ export function resetPluginEntitlementsForTests() {
+    registrations.clear();
+    notifyListeners();
+}
+
+//# sourceMappingURL=plugin-entitlements.js.map