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

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

@@ -0,0 +1,54 @@
+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";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_SITE_BEACONS = definePluginServiceContract('core.site-beacons', {
+    multiple: true
+});
+/**
+ * Registers a beacon. The owner is the loader's marker inside a register fn,
+ * else `options.pluginId`; with neither the registration throws. A field
+ * another plugin claims throws naming both.
+ */ export function registerPluginSiteBeacon(beacon, options) {
+    var _beacon_field, _ref, _getRegisteringPluginId;
+    const field = String((_beacon_field = beacon.field) != null ? _beacon_field : '').trim();
+    if (!field) throw new Error('a site beacon needs the body field that marks it');
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) throw new Error(`the site beacon "${field}" was registered with no owner`);
+    const incumbent = resolvePluginServices(PLUGIN_SITE_BEACONS).find((entry)=>entry.key === field);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`site beacon field "${field}" is already counted by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_SITE_BEACONS, _extends({}, beacon, {
+        field
+    }), {
+        pluginId,
+        key: field
+    });
+}
+/** The owner of a beacon body, or `null` when no registered field marks it. */ export function pluginSiteBeaconFor(body) {
+    for (const entry of resolvePluginServices(PLUGIN_SITE_BEACONS)){
+        const value = body[entry.impl.field];
+        if (typeof value === 'string' && value) return {
+            pluginId: entry.pluginId,
+            beacon: entry.impl
+        };
+    }
+    return null;
+}
+
+//# sourceMappingURL=plugin-site-beacons.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-beacons.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A plugin's own beacons, posted to the platform's site collector.\n *\n * A published page has one place to report what visitors did — the\n * collector behind `sendAnalyticsBeacon` — and that endpoint owns what every\n * beacon owes before anything is counted: the host must exist, a platform,\n * org or site lockdown refuses it silently, and the per-address rate limit\n * applies. What a plugin's site runtime reports beyond a pageview (an\n * announcement bar seen, a popup dismissed) is the plugin's to count, in its\n * own documents.\n *\n * So the plugin registers a beacon by the body FIELD that marks it as its\n * own, and the collector hands a beacon carrying that field to the plugin\n * after its own gates, then answers 204 without counting a pageview. The\n * field is the beacon's whole claim: one owner per field, refused naming\n * both, and the incumbent keeps serving.\n *\n * Registered from the plugin's `serverDeclarations`, so every server process\n * has it from boot; keep the registration light and import the counting\n * code on the first beacon.\n */\n\n/** What the collector hands the owner, after the host and lockdown gates. */\nexport interface PluginSiteBeaconRequest {\n  hostId: string\n  /** The collector's day bucket, `YYYY-MM-DD` in UTC. */\n  day: string\n  /**\n   * When the site's analytics document for {@link day} expires: the\n   * platform's retention. An owner that writes into that document stamps it,\n   * so a document created by its beacons alone is still swept.\n   */\n  dayExpiresAt: Date\n  /** The beacon as the browser sent it. Untrusted: validate every field read. */\n  body: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginSiteBeacon {\n  /** The body field whose non-empty string marks a beacon as this plugin's. */\n  field: string\n  /** Counts one beacon. A throw is logged by the collector, never surfaced. */\n  count(request: PluginSiteBeaconRequest): Promise<void>\n}\n\nexport const PLUGIN_SITE_BEACONS = definePluginServiceContract<PluginSiteBeacon>(\n  'core.site-beacons',\n  { multiple: true },\n)\n\n/**\n * Registers a beacon. The owner is the loader's marker inside a register fn,\n * else `options.pluginId`; with neither the registration throws. A field\n * another plugin claims throws naming both.\n */\nexport function registerPluginSiteBeacon(\n  beacon: PluginSiteBeacon,\n  options?: { pluginId?: string },\n): void {\n  const field = String(beacon.field ?? '').trim()\n  if (!field) throw new Error('a site beacon needs the body field that marks it')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) throw new Error(`the site beacon \"${field}\" was registered with no owner`)\n  const incumbent = resolvePluginServices(PLUGIN_SITE_BEACONS).find((entry) => entry.key === field)\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `site beacon field \"${field}\" is already counted by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_SITE_BEACONS, { ...beacon, field }, { pluginId, key: field })\n}\n\n/** The owner of a beacon body, or `null` when no registered field marks it. */\nexport function pluginSiteBeaconFor(\n  body: Readonly<Record<string, unknown>>,\n): { pluginId: string; beacon: PluginSiteBeacon } | null {\n  for (const entry of resolvePluginServices(PLUGIN_SITE_BEACONS)) {\n    const value = body[entry.impl.field]\n    if (typeof value === 'string' && value) return { pluginId: entry.pluginId, beacon: entry.impl }\n  }\n  return null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_SITE_BEACONS","multiple","registerPluginSiteBeacon","beacon","options","field","String","trim","Error","pluginId","incumbent","find","entry","key","pluginSiteBeaconFor","body","value","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA8C1B,OAAO,MAAMC,sBAAsBH,4BACjC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,yBACdC,MAAwB,EACxBC,OAA+B;QAEVD,eAEHP,MAAAA;IAFlB,MAAMS,QAAQC,QAAOH,gBAAAA,OAAOE,KAAK,YAAZF,gBAAgB,IAAII,IAAI;IAC7C,IAAI,CAACF,OAAO,MAAM,IAAIG,MAAM;IAC5B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BQ,2BAAAA,QAASK,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,IAAI,CAACE,UAAU,MAAM,IAAID,MAAM,CAAC,iBAAiB,EAAEH,MAAM,8BAA8B,CAAC;IACxF,MAAMK,YAAYX,sBAAsBC,qBAAqBW,IAAI,CAAC,CAACC,QAAUA,MAAMC,GAAG,KAAKR;IAC3F,IAAIK,aAAaA,UAAUD,QAAQ,KAAKA,UAAU;QAChD,MAAM,IAAID,MACR,CAAC,mBAAmB,EAAEH,MAAM,yBAAyB,EAAEK,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAEvG;IACAX,sBAAsBE,qBAAqB,aAAKG;QAAQE;QAAS;QAAEI;QAAUI,KAAKR;IAAM;AAC1F;AAEA,6EAA6E,GAC7E,OAAO,SAASS,oBACdC,IAAuC;IAEvC,KAAK,MAAMH,SAASb,sBAAsBC,qBAAsB;QAC9D,MAAMgB,QAAQD,IAAI,CAACH,MAAMK,IAAI,CAACZ,KAAK,CAAC;QACpC,IAAI,OAAOW,UAAU,YAAYA,OAAO,OAAO;YAAEP,UAAUG,MAAMH,QAAQ;YAAEN,QAAQS,MAAMK,IAAI;QAAC;IAChG;IACA,OAAO;AACT"}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-subscription-topics.generated.ts"],"sourcesContent":["/**\n * GENERATED FILE — do not edit. Regenerate with:\n *   node tools/scripts/generate-plugin-manifests.mjs\n *\n * The subscription topics plugins declare (AGL-3080): each plugin's\n * `subscriptionTopics` block in plugins.config.json, in preference-page\n * order. Core's `app-utils/subscription-topics.ts` reads them as the\n * built-in floor of every org's topic catalog; core names no stream.\n */\n\nimport type { DeclaredSubscriptionTopic } from '../app-utils/subscription-topics'\n\nexport const PLUGIN_SUBSCRIPTION_TOPICS_DECLARED: readonly DeclaredSubscriptionTopic[] = [\n  {\n    \"pluginId\": \"marketing\",\n    \"id\": \"marketing\",\n    \"name\": \"Promotions and offers\",\n    \"description\": \"Sales, discounts and seasonal campaigns.\",\n    \"order\": 10,\n    \"default\": true\n  },\n  {\n    \"pluginId\": \"commerce\",\n    \"id\": \"newsletter\",\n    \"name\": \"Newsletter\",\n    \"description\": \"Regular news and stories from us.\",\n    \"order\": 20\n  },\n  {\n    \"pluginId\": \"commerce\",\n    \"id\": \"product-updates\",\n    \"name\": \"Product updates\",\n    \"description\": \"New products, restocks and changes to what we offer.\",\n    \"order\": 30\n  },\n  {\n    \"pluginId\": \"outreach\",\n    \"id\": \"sales\",\n    \"name\": \"Sales outreach\",\n    \"description\": \"Messages from a person here about working together.\",\n    \"order\": 40\n  }\n]\n"],"names":["PLUGIN_SUBSCRIPTION_TOPICS_DECLARED"],"mappings":"AAAA;;;;;;;;CAQC,GAID,OAAO,MAAMA,sCAA4E;IACvF;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;QACT,WAAW;IACb;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;IACA;QACE,YAAY;QACZ,MAAM;QACN,QAAQ;QACR,eAAe;QACf,SAAS;IACX;CACD,CAAA"}

package/src/lib/plugin-manager/plugin-usage-axes.d.ts

@@ -14,6 +14,60 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * WHAT A PLUGIN'S USAGE COSTS, AND HOW MUCH OF ITS BAND IT SPENT (AGL-3080).
+ *
+ * The platform keeps one cost model (`orgMonthlyCogsUsd`) and one
+ * utilization table (`margin-utilization.ts`), and both read the monthly
+ * usage rollup. Several of the rollup's meters are a plugin's: the AI
+ * plugin's provider spend, the CRM's records, the forms plugin's
+ * submissions, the workflows plugin's runs. Core used to name each of them —
+ * its rollup field, the unit rate that prices it, the band it is measured
+ * against — so a plugin that metered something new could not reach the
+ * discount guardrail without a core edit, and core could not be taken
+ * without the plugins it named.
+ *
+ * So a plugin declares its meters, and core composes them:
+ *
+ *  - a COST AXIS names the rollup fields a meter is recorded under and the
+ *    `ORG_COGS_UNIT_RATES_USD` key that prices one unit, or no key when the
+ *    field is already dollars. `orgMonthlyCogsUsd` prices it beside core's
+ *    own axes, and `orgCogsInputFrom` forwards its fields.
+ *  - a BAND names the rollup fields that measure it and the entitlement that
+ *    says what the plan includes. The utilization table reads it beside
+ *    core's own bands. A METERED band is also billed past what the plan
+ *    includes, at cost × `METERED_MARKUP`, beside storage and bandwidth: the
+ *    invoice sweep, the Billing card's estimate, the monthly summary and the
+ *    staff usage rows read it from here.
+ *  - a SPEND LINE names the month document holding what the plugin's usage
+ *    came to at the rates it bills, the deployment variable naming the month
+ *    it is first charged for, and the unit a customer sees it in. The usage
+ *    budget shows it beside the metered figure and counts it once charged.
+ *  - a METER names what the plugin measures in the monthly usage sweep
+ *    (`plugin-usage-meters.ts`), so the sweep can refuse to bill a month the
+ *    registered meter is missing from.
+ *
+ * ## What core keeps
+ *
+ * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the
+ * billed table it is reconciled against (`METERED_UNIT_RATES_USD`, which a
+ * metered band names its rate in), and every included figure stays in
+ * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no
+ * price. The one number a declaration may carry is a band's unit cost, where
+ * the band is sold in a unit OF cost (a credit is a fixed quantity of
+ * dollars), and that number is the plugin's own definition of its unit.
+ *
+ * ## Compiled, never registered
+ *
+ * The cost model's readers include the staff org page, which prices a rollup
+ * in the browser, and the discount guardrail, whose every wrong answer is in
+ * the approving direction: a cost axis a registry had not filled would price
+ * at nothing and approve a discount the margin cannot carry. So these are
+ * compiled from each plugin's `usage-axes` declaration by the manifest
+ * generator, like the plan figures, and a rate key core does not have is an
+ * error rather than a zero.
+ */
+import type { ReleaseFlagKey } from '../app-utils/release-flags';
 /** A meter a plugin contributes to the platform's cost model. */
 export interface PluginCostAxisDeclaration {
     /** The breakdown key every staff reader shows it under. */
@@ -32,6 +86,12 @@ export interface PluginCostAxisDeclaration {
      * by `orgCogsInputFrom` and never priced.
      */
     recordedFields?: readonly string[];
+    /**
+     * Rollup fields the plugin's usage sweep writes beside the meter for its
+     * staff surfaces to read — served on the staff usage rows, `null` where a
+     * rollup never wrote one, and never forwarded to the cost model.
+     */
+    staffFields?: readonly string[];
     /**
      * The `ORG_COGS_UNIT_RATES_USD` key pricing one unit. Absent when the
      * fields are already dollars, which then enter the model at ×1.
@@ -67,6 +127,101 @@ export interface PluginUsageBandDeclaration {
      * made never reads as less of the band.
      */
     unitCostUsd?: number;
+    /**
+     * The per-site monthly counter the band is measured by:
+     * `hosts/{hostId}/counters/{hostCounter}`, field `{month}`, summed over the
+     * workspace's sites.
+     */
+    hostCounter?: string;
+    /**
+     * The workspace is WARNED as it approaches and reaches this band, by the
+     * usage-alerts sweep, from its `hostCounter` against what the plan includes
+     * of `entitlement`, once per threshold per month. `label` names the band in
+     * the title ("monthly workflow runs") and `noun` in the opening sentence
+     * ("workflow runs"); `outcome` is what happens at the band — `stops`,
+     * `bills` or `continues` — and `reached` and `approach` are the sentences
+     * that say so, at the band and approaching it.
+     */
+    alert?: {
+        label: string;
+        noun: string;
+        outcome: 'stops' | 'bills' | 'continues';
+        reached: string;
+        approach: string;
+    };
+    /**
+     * The band is one of the INFRASTRUCTURE meters (AGL-1280): what the
+     * workspace uses past it is billed at our cost × `METERED_MARKUP`, beside
+     * storage and bandwidth, on the same invoice line and the same estimate.
+     * A metered band names one rollup field and the `hostCounter` it is
+     * measured by.
+     */
+    metered?: PluginMeteredBand;
+}
+/** How a metered band is priced, quoted and withheld. */
+export interface PluginMeteredBand {
+    /**
+     * The `METERED_UNIT_RATES_USD` key holding our cost per unit — never a
+     * number: the rate table is the platform's, beside the markup it is
+     * published with.
+     */
+    rate: string;
+    /** The count a published price is quoted per: `1000` reads "per 1,000". */
+    quotedPer: number;
+    /** The band in running prose, plural and lowercase: "form submissions". */
+    noun: string;
+    /**
+     * A release flag the overage waits behind: while it is off for the
+     * workspace, the units are counted and the charge is recorded as withheld
+     * rather than billed — nobody is charged for what they cannot reach
+     * (AGL-1604). The rollup records the verdict as `{field}Billed` and what
+     * was forgone, at cost, as `{field}OverageWithheldUsd`.
+     */
+    withheldUntil?: ReleaseFlagKey;
+}
+/**
+ * A line of a workspace's monthly SPEND a plugin contributes to its usage
+ * budget (`usage-budget.ts`): what the plugin's usage came to this month, in
+ * the dollars it is billed at, shown on the customer's budget card and
+ * counted toward the budget from the month the plugin starts charging for it.
+ */
+export interface PluginSpendLineDeclaration {
+    /** The line's key. */
+    id: string;
+    /** What the budget card and the budget alert call it. */
+    label: string;
+    /**
+     * Where the month's figure is read: `orgs/{orgId}/{collection}/{month}`,
+     * field `field`, in dollars.
+     */
+    live: {
+        collection: string;
+        field: string;
+    };
+    /**
+     * The deployment variable naming the first month (`YYYY-MM`) the line is
+     * charged for. Until it names this month or an earlier one — and on any
+     * value that is not a month — the line is shown and never counted.
+     */
+    billedFromEnv: string;
+    /**
+     * The unit the customer is shown the line in, when the stored dollars are
+     * not theirs to see: `ceil(dollars / costUsd)` of `label`, and the dollar
+     * figure never crosses to the browser.
+     */
+    unit?: {
+        costUsd: number;
+        label: string;
+    };
+}
+/**
+ * A meter the plugin measures in the platform's monthly usage sweep and
+ * registers at runtime (`plugin-usage-meters.ts`). Declared as well as
+ * registered so the sweep can refuse to bill a workspace's month without it.
+ */
+export interface PluginUsageMeterDeclaration {
+    /** As `registerPluginUsageMeter` names it. */
+    id: string;
 }
 export type ResolvedPluginCostAxis = PluginCostAxisDeclaration & {
     pluginId: string;
@@ -74,13 +229,55 @@ export type ResolvedPluginCostAxis = PluginCostAxisDeclaration & {
 export type ResolvedPluginUsageBand = PluginUsageBandDeclaration & {
     pluginId: string;
 };
+export type ResolvedPluginSpendLine = PluginSpendLineDeclaration & {
+    pluginId: string;
+};
+export type ResolvedPluginUsageMeter = PluginUsageMeterDeclaration & {
+    pluginId: string;
+};
 /** What a plugin's `usageAxes` function answers. */
 export interface PluginUsageAxesDeclaration {
     costAxes?: readonly PluginCostAxisDeclaration[];
     bands?: readonly PluginUsageBandDeclaration[];
+    spendLines?: readonly PluginSpendLineDeclaration[];
+    meters?: readonly PluginUsageMeterDeclaration[];
 }
 export declare function pluginCostAxes(): readonly ResolvedPluginCostAxis[];
 export declare function pluginUsageBands(): readonly ResolvedPluginUsageBand[];
+/** A declared band that is metered, with its one field and its counter. */
+export type ResolvedPluginMeteredBand = ResolvedPluginUsageBand & {
+    metered: PluginMeteredBand;
+    hostCounter: string;
+};
+/**
+ * Every band billed at cost past what the plan includes, in band order — the
+ * infrastructure meters a plugin adds beside storage and bandwidth.
+ */
+export declare function meteredPluginBands(): readonly ResolvedPluginMeteredBand[];
+/** A declared band measured by a per-site counter and never billed past it. */
+export type ResolvedPluginCountedBand = ResolvedPluginUsageBand & {
+    hostCounter: string;
+};
+/**
+ * Every band measured by a per-site counter and not metered, in band order:
+ * the usage sweep sums each across the workspace's sites and records it under
+ * the band's first field, and the staff usage rows show the count. A metered
+ * band's counter is read with the infrastructure meters instead.
+ */
+export declare function countedPluginBands(): readonly ResolvedPluginCountedBand[];
+/** The rollup field a metered band records its count under. */
+export declare function meteredBandField(band: ResolvedPluginMeteredBand): string;
+/**
+ * Where the rollup records a withheld band's verdict (`metered.withheldUntil`):
+ * whether the month billed the band's overage, and what was forgone, at cost,
+ * when it did not. Without the second a withheld month reads as a month that
+ * stayed inside the band.
+ */
+export declare function meteredBandVerdictFields(band: ResolvedPluginMeteredBand): {
+    billed: string;
+    withheldUsd: string;
+};
+export declare function pluginSpendLines(): readonly ResolvedPluginSpendLine[];
 /**
  * What a rollup recorded for a declared meter: `fields` summed, or
  * `fallbackFields` summed when the rollup carries none of `fields` at all.
@@ -105,3 +302,18 @@ export declare function liveMeterReading(document: {
 }): number | undefined;
 /** Every rollup field the declared cost axes read or record, in order. */
 export declare function pluginCostAxisFields(): string[];
+/**
+ * A month's rollup as a staff reader is served it, one entry per field the
+ * declared cost axes read, record or serve to staff (`get` reads one rollup
+ * field).
+ *
+ * A field an axis prices reads zero where the rollup lacks it, as the cost
+ * model reads it — except where the axis falls back to an older basis when
+ * the rollup carries none of its fields: there absence is the answer that
+ * selects the fallback, so it is served as `null`, and a reader pricing the
+ * served row reads the month the way the sweep did. A field an axis only
+ * records or serves reads `null` when the rollup never wrote it: "not
+ * recorded" and "recorded zero" are different answers, and a projection
+ * that collapses them invents history (AGL-2321).
+ */
+export declare function pluginCostAxisProjection(get: (field: string) => unknown): Record<string, number | null>;

package/src/lib/plugin-manager/plugin-usage-axes.js

@@ -34,12 +34,23 @@
  *    own axes, and `orgCogsInputFrom` forwards its fields.
  *  - a BAND names the rollup fields that measure it and the entitlement that
  *    says what the plan includes. The utilization table reads it beside
- *    core's own bands.
+ *    core's own bands. A METERED band is also billed past what the plan
+ *    includes, at cost × `METERED_MARKUP`, beside storage and bandwidth: the
+ *    invoice sweep, the Billing card's estimate, the monthly summary and the
+ *    staff usage rows read it from here.
+ *  - a SPEND LINE names the month document holding what the plugin's usage
+ *    came to at the rates it bills, the deployment variable naming the month
+ *    it is first charged for, and the unit a customer sees it in. The usage
+ *    budget shows it beside the metered figure and counts it once charged.
+ *  - a METER names what the plugin measures in the monthly usage sweep
+ *    (`plugin-usage-meters.ts`), so the sweep can refuse to bill a month the
+ *    registered meter is missing from.
  *
  * ## What core keeps
  *
  * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the
- * billed table it is reconciled against, and every included figure stays in
+ * billed table it is reconciled against (`METERED_UNIT_RATES_USD`, which a
+ * metered band names its rate in), and every included figure stays in
  * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no
  * price. The one number a declaration may carry is a band's unit cost, where
  * the band is sold in a unit OF cost (a credit is a fixed quantity of
@@ -54,13 +65,45 @@
  * compiled from each plugin's `usage-axes` declaration by the manifest
  * generator, like the plan figures, and a rate key core does not have is an
  * error rather than a zero.
- */ import { PLUGIN_USAGE_BANDS_DECLARED, PLUGIN_COST_AXES_DECLARED } from "./first-party-plugins.generated.js";
+ */ import { PLUGIN_COST_AXES_DECLARED, PLUGIN_SPEND_LINES_DECLARED, PLUGIN_USAGE_BANDS_DECLARED } from "./first-party-plugins.generated.js";
 export function pluginCostAxes() {
     return PLUGIN_COST_AXES_DECLARED;
 }
 export function pluginUsageBands() {
     return PLUGIN_USAGE_BANDS_DECLARED;
 }
+/**
+ * Every band billed at cost past what the plan includes, in band order — the
+ * infrastructure meters a plugin adds beside storage and bandwidth.
+ */ export function meteredPluginBands() {
+    return PLUGIN_USAGE_BANDS_DECLARED.filter((band)=>Boolean(band.metered && band.hostCounter));
+}
+/**
+ * Every band measured by a per-site counter and not metered, in band order:
+ * the usage sweep sums each across the workspace's sites and records it under
+ * the band's first field, and the staff usage rows show the count. A metered
+ * band's counter is read with the infrastructure meters instead.
+ */ export function countedPluginBands() {
+    return PLUGIN_USAGE_BANDS_DECLARED.filter((band)=>Boolean(band.hostCounter && !band.metered));
+}
+/** The rollup field a metered band records its count under. */ export function meteredBandField(band) {
+    return band.fields[0];
+}
+/**
+ * Where the rollup records a withheld band's verdict (`metered.withheldUntil`):
+ * whether the month billed the band's overage, and what was forgone, at cost,
+ * when it did not. Without the second a withheld month reads as a month that
+ * stayed inside the band.
+ */ export function meteredBandVerdictFields(band) {
+    const field = meteredBandField(band);
+    return {
+        billed: `${field}Billed`,
+        withheldUsd: `${field}OverageWithheldUsd`
+    };
+}
+export function pluginSpendLines() {
+    return PLUGIN_SPEND_LINES_DECLARED;
+}
 /** A positive finite number, or 0 — the reading every meter is priced from. */ function meterValue(value) {
     const parsed = Number(value != null ? value : 0);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
@@ -103,5 +146,41 @@ export function pluginUsageBands() {
     }
     return fields;
 }
+/**
+ * A month's rollup as a staff reader is served it, one entry per field the
+ * declared cost axes read, record or serve to staff (`get` reads one rollup
+ * field).
+ *
+ * A field an axis prices reads zero where the rollup lacks it, as the cost
+ * model reads it — except where the axis falls back to an older basis when
+ * the rollup carries none of its fields: there absence is the answer that
+ * selects the fallback, so it is served as `null`, and a reader pricing the
+ * served row reads the month the way the sweep did. A field an axis only
+ * records or serves reads `null` when the rollup never wrote it: "not
+ * recorded" and "recorded zero" are different answers, and a projection
+ * that collapses them invents history (AGL-2321).
+ */ export function pluginCostAxisProjection(get) {
+    const out = {};
+    for (const axis of PLUGIN_COST_AXES_DECLARED){
+        var _axis_recordedFields, _axis_staffFields, _axis_fallbackFields, _axis_recordedFields1, _axis_staffFields1;
+        var _axis_fallbackFields1;
+        const absentIsNull = [
+            ...((_axis_fallbackFields1 = axis.fallbackFields) == null ? void 0 : _axis_fallbackFields1.length) ? axis.fields : [],
+            ...(_axis_recordedFields = axis.recordedFields) != null ? _axis_recordedFields : [],
+            ...(_axis_staffFields = axis.staffFields) != null ? _axis_staffFields : []
+        ];
+        for (const field of [
+            ...axis.fields,
+            ...(_axis_fallbackFields = axis.fallbackFields) != null ? _axis_fallbackFields : [],
+            ...(_axis_recordedFields1 = axis.recordedFields) != null ? _axis_recordedFields1 : [],
+            ...(_axis_staffFields1 = axis.staffFields) != null ? _axis_staffFields1 : []
+        ]){
+            if (field in out) continue;
+            const value = get(field);
+            out[field] = value != null ? Number(value) : absentIsNull.includes(field) ? null : 0;
+        }
+    }
+    return out;
+}
 
 //# sourceMappingURL=plugin-usage-axes.js.map

package/src/lib/plugin-manager/plugin-usage-axes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-usage-axes.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHAT A PLUGIN'S USAGE COSTS, AND HOW MUCH OF ITS BAND IT SPENT (AGL-3080).\n *\n * The platform keeps one cost model (`orgMonthlyCogsUsd`) and one\n * utilization table (`margin-utilization.ts`), and both read the monthly\n * usage rollup. Several of the rollup's meters are a plugin's: the AI\n * plugin's provider spend, the CRM's records, the forms plugin's\n * submissions, the workflows plugin's runs. Core used to name each of them —\n * its rollup field, the unit rate that prices it, the band it is measured\n * against — so a plugin that metered something new could not reach the\n * discount guardrail without a core edit, and core could not be taken\n * without the plugins it named.\n *\n * So a plugin declares its meters, and core composes them:\n *\n *  - a COST AXIS names the rollup fields a meter is recorded under and the\n *    `ORG_COGS_UNIT_RATES_USD` key that prices one unit, or no key when the\n *    field is already dollars. `orgMonthlyCogsUsd` prices it beside core's\n *    own axes, and `orgCogsInputFrom` forwards its fields.\n *  - a BAND names the rollup fields that measure it and the entitlement that\n *    says what the plan includes. The utilization table reads it beside\n *    core's own bands.\n *\n * ## What core keeps\n *\n * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the\n * billed table it is reconciled against, and every included figure stays in\n * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no\n * price. The one number a declaration may carry is a band's unit cost, where\n * the band is sold in a unit OF cost (a credit is a fixed quantity of\n * dollars), and that number is the plugin's own definition of its unit.\n *\n * ## Compiled, never registered\n *\n * The cost model's readers include the staff org page, which prices a rollup\n * in the browser, and the discount guardrail, whose every wrong answer is in\n * the approving direction: a cost axis a registry had not filled would price\n * at nothing and approve a discount the margin cannot carry. So these are\n * compiled from each plugin's `usage-axes` declaration by the manifest\n * generator, like the plan figures, and a rate key core does not have is an\n * error rather than a zero.\n */\n\nimport {\n  PLUGIN_USAGE_BANDS_DECLARED,\n  PLUGIN_COST_AXES_DECLARED,\n} from './first-party-plugins.generated'\n\n/** A meter a plugin contributes to the platform's cost model. */\nexport interface PluginCostAxisDeclaration {\n  /** The breakdown key every staff reader shows it under. */\n  id: string\n  /** Where it sorts among the cost model's axes; core's own are multiples of 10. */\n  order: number\n  /** Rollup fields summed for the axis. */\n  fields: readonly string[]\n  /**\n   * Read only when every one of `fields` is absent from a rollup — the\n   * narrower field an older rollup recorded the same meter under.\n   */\n  fallbackFields?: readonly string[]\n  /**\n   * Rollup fields recorded beside the meter so its sum is legible, forwarded\n   * by `orgCogsInputFrom` and never priced.\n   */\n  recordedFields?: readonly string[]\n  /**\n   * The `ORG_COGS_UNIT_RATES_USD` key pricing one unit. Absent when the\n   * fields are already dollars, which then enter the model at ×1.\n   */\n  rate?: string\n  /**\n   * The month's LIVE reading, when the rollup's figure is a snapshot a meter\n   * keeps adding to: `orgs/{orgId}/{collection}/{month}`, the first of\n   * `fields` that is a positive number. It replaces the axis's first rollup\n   * field wherever a reader fetches it.\n   */\n  live?: { collection: string; fields: readonly string[] }\n}\n\n/** A band a plugin contributes to the utilization table. */\nexport interface PluginUsageBandDeclaration {\n  /** The band's key, and the column the staff table shows it under. */\n  id: string\n  label: string\n  order: number\n  /** Rollup fields summed for what the org used. */\n  fields: readonly string[]\n  fallbackFields?: readonly string[]\n  /** The resolved entitlement holding what the plan includes. */\n  entitlement: string\n  /** The entitlement is per SITE and the org-wide band is it × `hostLimit`. */\n  perHost?: boolean\n  /**\n   * The band is sold in a unit of cost and the rollup records dollars: what\n   * was used is `ceil(dollars / unitCostUsd)`, rounded UP so spend already\n   * made never reads as less of the band.\n   */\n  unitCostUsd?: number\n}\n\nexport type ResolvedPluginCostAxis = PluginCostAxisDeclaration & { pluginId: string }\nexport type ResolvedPluginUsageBand = PluginUsageBandDeclaration & { pluginId: string }\n\n/** What a plugin's `usageAxes` function answers. */\nexport interface PluginUsageAxesDeclaration {\n  costAxes?: readonly PluginCostAxisDeclaration[]\n  bands?: readonly PluginUsageBandDeclaration[]\n}\n\nexport function pluginCostAxes(): readonly ResolvedPluginCostAxis[] {\n  return PLUGIN_COST_AXES_DECLARED\n}\n\nexport function pluginUsageBands(): readonly ResolvedPluginUsageBand[] {\n  return PLUGIN_USAGE_BANDS_DECLARED\n}\n\n/** A positive finite number, or 0 — the reading every meter is priced from. */\nfunction meterValue(value: unknown): number {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\n/**\n * What a rollup recorded for a declared meter: `fields` summed, or\n * `fallbackFields` summed when the rollup carries none of `fields` at all.\n *\n * \"Carries none\" is `null` or absent, never zero. A rollup that measured\n * zero has answered, and must not fall back to a figure recorded under an\n * older, narrower basis.\n */\nexport function declaredMeterReading(\n  source: Readonly<Record<string, unknown>> | null | undefined,\n  declared: {\n    fields: readonly string[]\n    fallbackFields?: readonly string[]\n  },\n): number {\n  const present = declared.fields.some((field) => source?.[field] != null)\n  const fields =\n    !present && declared.fallbackFields?.length\n      ? declared.fallbackFields\n      : declared.fields\n  return fields.reduce((sum, field) => sum + meterValue(source?.[field]), 0)\n}\n\n/**\n * The live reading a cost axis names: the first of its `live.fields` that is\n * a positive number on the month's document, or `undefined` when none is.\n * `undefined` is \"keep the rollup's snapshot\", never zero.\n */\nexport function liveMeterReading(\n  document: { get(field: string): unknown } | null | undefined,\n  live: { fields: readonly string[] },\n): number | undefined {\n  for (const field of live.fields) {\n    const value = meterValue(document?.get(field))\n    if (value > 0) return value\n  }\n  return undefined\n}\n\n/** Every rollup field the declared cost axes read or record, in order. */\nexport function pluginCostAxisFields(): string[] {\n  const fields: string[] = []\n  for (const axis of PLUGIN_COST_AXES_DECLARED) {\n    for (const field of [\n      ...axis.fields,\n      ...(axis.fallbackFields ?? []),\n      ...(axis.recordedFields ?? []),\n    ]) {\n      if (!fields.includes(field)) fields.push(field)\n    }\n  }\n  return fields\n}\n"],"names":["PLUGIN_USAGE_BANDS_DECLARED","PLUGIN_COST_AXES_DECLARED","pluginCostAxes","pluginUsageBands","meterValue","value","parsed","Number","isFinite","declaredMeterReading","source","declared","present","fields","some","field","fallbackFields","length","reduce","sum","liveMeterReading","document","live","get","undefined","pluginCostAxisFields","axis","recordedFields","includes","push"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GAED,SACEA,2BAA2B,EAC3BC,yBAAyB,QACpB,qCAAiC;AAgExC,OAAO,SAASC;IACd,OAAOD;AACT;AAEA,OAAO,SAASE;IACd,OAAOH;AACT;AAEA,6EAA6E,GAC7E,SAASI,WAAWC,KAAc;IAChC,MAAMC,SAASC,OAAOF,gBAAAA,QAAS;IAC/B,OAAOE,OAAOC,QAAQ,CAACF,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA;;;;;;;CAOC,GACD,OAAO,SAASG,qBACdC,MAA4D,EAC5DC,QAGC;QAIaA;IAFd,MAAMC,UAAUD,SAASE,MAAM,CAACC,IAAI,CAAC,CAACC,QAAUL,CAAAA,0BAAAA,MAAQ,CAACK,MAAM,KAAI;IACnE,MAAMF,SACJ,CAACD,aAAWD,2BAAAA,SAASK,cAAc,qBAAvBL,yBAAyBM,MAAM,IACvCN,SAASK,cAAc,GACvBL,SAASE,MAAM;IACrB,OAAOA,OAAOK,MAAM,CAAC,CAACC,KAAKJ,QAAUI,MAAMf,WAAWM,0BAAAA,MAAQ,CAACK,MAAM,GAAG;AAC1E;AAEA;;;;CAIC,GACD,OAAO,SAASK,iBACdC,QAA4D,EAC5DC,IAAmC;IAEnC,KAAK,MAAMP,SAASO,KAAKT,MAAM,CAAE;QAC/B,MAAMR,QAAQD,WAAWiB,4BAAAA,SAAUE,GAAG,CAACR;QACvC,IAAIV,QAAQ,GAAG,OAAOA;IACxB;IACA,OAAOmB;AACT;AAEA,wEAAwE,GACxE,OAAO,SAASC;IACd,MAAMZ,SAAmB,EAAE;IAC3B,KAAK,MAAMa,QAAQzB,0BAA2B;YAGtCyB,sBACAA;QAHN,KAAK,MAAMX,SAAS;eACfW,KAAKb,MAAM;gBACVa,uBAAAA,KAAKV,cAAc,YAAnBU,uBAAuB,EAAE;gBACzBA,uBAAAA,KAAKC,cAAc,YAAnBD,uBAAuB,EAAE;SAC9B,CAAE;YACD,IAAI,CAACb,OAAOe,QAAQ,CAACb,QAAQF,OAAOgB,IAAI,CAACd;QAC3C;IACF;IACA,OAAOF;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-usage-axes.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHAT A PLUGIN'S USAGE COSTS, AND HOW MUCH OF ITS BAND IT SPENT (AGL-3080).\n *\n * The platform keeps one cost model (`orgMonthlyCogsUsd`) and one\n * utilization table (`margin-utilization.ts`), and both read the monthly\n * usage rollup. Several of the rollup's meters are a plugin's: the AI\n * plugin's provider spend, the CRM's records, the forms plugin's\n * submissions, the workflows plugin's runs. Core used to name each of them —\n * its rollup field, the unit rate that prices it, the band it is measured\n * against — so a plugin that metered something new could not reach the\n * discount guardrail without a core edit, and core could not be taken\n * without the plugins it named.\n *\n * So a plugin declares its meters, and core composes them:\n *\n *  - a COST AXIS names the rollup fields a meter is recorded under and the\n *    `ORG_COGS_UNIT_RATES_USD` key that prices one unit, or no key when the\n *    field is already dollars. `orgMonthlyCogsUsd` prices it beside core's\n *    own axes, and `orgCogsInputFrom` forwards its fields.\n *  - a BAND names the rollup fields that measure it and the entitlement that\n *    says what the plan includes. The utilization table reads it beside\n *    core's own bands. A METERED band is also billed past what the plan\n *    includes, at cost × `METERED_MARKUP`, beside storage and bandwidth: the\n *    invoice sweep, the Billing card's estimate, the monthly summary and the\n *    staff usage rows read it from here.\n *  - a SPEND LINE names the month document holding what the plugin's usage\n *    came to at the rates it bills, the deployment variable naming the month\n *    it is first charged for, and the unit a customer sees it in. The usage\n *    budget shows it beside the metered figure and counts it once charged.\n *  - a METER names what the plugin measures in the monthly usage sweep\n *    (`plugin-usage-meters.ts`), so the sweep can refuse to bill a month the\n *    registered meter is missing from.\n *\n * ## What core keeps\n *\n * The MONEY. Every unit rate stays in `ORG_COGS_UNIT_RATES_USD`, beside the\n * billed table it is reconciled against (`METERED_UNIT_RATES_USD`, which a\n * metered band names its rate in), and every included figure stays in\n * `PLAN_ENTITLEMENTS`. A declaration names fields and keys; it carries no\n * price. The one number a declaration may carry is a band's unit cost, where\n * the band is sold in a unit OF cost (a credit is a fixed quantity of\n * dollars), and that number is the plugin's own definition of its unit.\n *\n * ## Compiled, never registered\n *\n * The cost model's readers include the staff org page, which prices a rollup\n * in the browser, and the discount guardrail, whose every wrong answer is in\n * the approving direction: a cost axis a registry had not filled would price\n * at nothing and approve a discount the margin cannot carry. So these are\n * compiled from each plugin's `usage-axes` declaration by the manifest\n * generator, like the plan figures, and a rate key core does not have is an\n * error rather than a zero.\n */\n\nimport type { ReleaseFlagKey } from '../app-utils/release-flags'\nimport {\n  PLUGIN_COST_AXES_DECLARED,\n  PLUGIN_SPEND_LINES_DECLARED,\n  PLUGIN_USAGE_BANDS_DECLARED,\n} from './first-party-plugins.generated'\n\n/** A meter a plugin contributes to the platform's cost model. */\nexport interface PluginCostAxisDeclaration {\n  /** The breakdown key every staff reader shows it under. */\n  id: string\n  /** Where it sorts among the cost model's axes; core's own are multiples of 10. */\n  order: number\n  /** Rollup fields summed for the axis. */\n  fields: readonly string[]\n  /**\n   * Read only when every one of `fields` is absent from a rollup — the\n   * narrower field an older rollup recorded the same meter under.\n   */\n  fallbackFields?: readonly string[]\n  /**\n   * Rollup fields recorded beside the meter so its sum is legible, forwarded\n   * by `orgCogsInputFrom` and never priced.\n   */\n  recordedFields?: readonly string[]\n  /**\n   * Rollup fields the plugin's usage sweep writes beside the meter for its\n   * staff surfaces to read — served on the staff usage rows, `null` where a\n   * rollup never wrote one, and never forwarded to the cost model.\n   */\n  staffFields?: readonly string[]\n  /**\n   * The `ORG_COGS_UNIT_RATES_USD` key pricing one unit. Absent when the\n   * fields are already dollars, which then enter the model at ×1.\n   */\n  rate?: string\n  /**\n   * The month's LIVE reading, when the rollup's figure is a snapshot a meter\n   * keeps adding to: `orgs/{orgId}/{collection}/{month}`, the first of\n   * `fields` that is a positive number. It replaces the axis's first rollup\n   * field wherever a reader fetches it.\n   */\n  live?: { collection: string; fields: readonly string[] }\n}\n\n/** A band a plugin contributes to the utilization table. */\nexport interface PluginUsageBandDeclaration {\n  /** The band's key, and the column the staff table shows it under. */\n  id: string\n  label: string\n  order: number\n  /** Rollup fields summed for what the org used. */\n  fields: readonly string[]\n  fallbackFields?: readonly string[]\n  /** The resolved entitlement holding what the plan includes. */\n  entitlement: string\n  /** The entitlement is per SITE and the org-wide band is it × `hostLimit`. */\n  perHost?: boolean\n  /**\n   * The band is sold in a unit of cost and the rollup records dollars: what\n   * was used is `ceil(dollars / unitCostUsd)`, rounded UP so spend already\n   * made never reads as less of the band.\n   */\n  unitCostUsd?: number\n  /**\n   * The per-site monthly counter the band is measured by:\n   * `hosts/{hostId}/counters/{hostCounter}`, field `{month}`, summed over the\n   * workspace's sites.\n   */\n  hostCounter?: string\n  /**\n   * The workspace is WARNED as it approaches and reaches this band, by the\n   * usage-alerts sweep, from its `hostCounter` against what the plan includes\n   * of `entitlement`, once per threshold per month. `label` names the band in\n   * the title (\"monthly workflow runs\") and `noun` in the opening sentence\n   * (\"workflow runs\"); `outcome` is what happens at the band — `stops`,\n   * `bills` or `continues` — and `reached` and `approach` are the sentences\n   * that say so, at the band and approaching it.\n   */\n  alert?: {\n    label: string\n    noun: string\n    outcome: 'stops' | 'bills' | 'continues'\n    reached: string\n    approach: string\n  }\n  /**\n   * The band is one of the INFRASTRUCTURE meters (AGL-1280): what the\n   * workspace uses past it is billed at our cost × `METERED_MARKUP`, beside\n   * storage and bandwidth, on the same invoice line and the same estimate.\n   * A metered band names one rollup field and the `hostCounter` it is\n   * measured by.\n   */\n  metered?: PluginMeteredBand\n}\n\n/** How a metered band is priced, quoted and withheld. */\nexport interface PluginMeteredBand {\n  /**\n   * The `METERED_UNIT_RATES_USD` key holding our cost per unit — never a\n   * number: the rate table is the platform's, beside the markup it is\n   * published with.\n   */\n  rate: string\n  /** The count a published price is quoted per: `1000` reads \"per 1,000\". */\n  quotedPer: number\n  /** The band in running prose, plural and lowercase: \"form submissions\". */\n  noun: string\n  /**\n   * A release flag the overage waits behind: while it is off for the\n   * workspace, the units are counted and the charge is recorded as withheld\n   * rather than billed — nobody is charged for what they cannot reach\n   * (AGL-1604). The rollup records the verdict as `{field}Billed` and what\n   * was forgone, at cost, as `{field}OverageWithheldUsd`.\n   */\n  withheldUntil?: ReleaseFlagKey\n}\n\n/**\n * A line of a workspace's monthly SPEND a plugin contributes to its usage\n * budget (`usage-budget.ts`): what the plugin's usage came to this month, in\n * the dollars it is billed at, shown on the customer's budget card and\n * counted toward the budget from the month the plugin starts charging for it.\n */\nexport interface PluginSpendLineDeclaration {\n  /** The line's key. */\n  id: string\n  /** What the budget card and the budget alert call it. */\n  label: string\n  /**\n   * Where the month's figure is read: `orgs/{orgId}/{collection}/{month}`,\n   * field `field`, in dollars.\n   */\n  live: { collection: string; field: string }\n  /**\n   * The deployment variable naming the first month (`YYYY-MM`) the line is\n   * charged for. Until it names this month or an earlier one — and on any\n   * value that is not a month — the line is shown and never counted.\n   */\n  billedFromEnv: string\n  /**\n   * The unit the customer is shown the line in, when the stored dollars are\n   * not theirs to see: `ceil(dollars / costUsd)` of `label`, and the dollar\n   * figure never crosses to the browser.\n   */\n  unit?: { costUsd: number; label: string }\n}\n\n/**\n * A meter the plugin measures in the platform's monthly usage sweep and\n * registers at runtime (`plugin-usage-meters.ts`). Declared as well as\n * registered so the sweep can refuse to bill a workspace's month without it.\n */\nexport interface PluginUsageMeterDeclaration {\n  /** As `registerPluginUsageMeter` names it. */\n  id: string\n}\n\nexport type ResolvedPluginCostAxis = PluginCostAxisDeclaration & { pluginId: string }\nexport type ResolvedPluginUsageBand = PluginUsageBandDeclaration & { pluginId: string }\nexport type ResolvedPluginSpendLine = PluginSpendLineDeclaration & { pluginId: string }\nexport type ResolvedPluginUsageMeter = PluginUsageMeterDeclaration & { pluginId: string }\n\n/** What a plugin's `usageAxes` function answers. */\nexport interface PluginUsageAxesDeclaration {\n  costAxes?: readonly PluginCostAxisDeclaration[]\n  bands?: readonly PluginUsageBandDeclaration[]\n  spendLines?: readonly PluginSpendLineDeclaration[]\n  meters?: readonly PluginUsageMeterDeclaration[]\n}\n\nexport function pluginCostAxes(): readonly ResolvedPluginCostAxis[] {\n  return PLUGIN_COST_AXES_DECLARED\n}\n\nexport function pluginUsageBands(): readonly ResolvedPluginUsageBand[] {\n  return PLUGIN_USAGE_BANDS_DECLARED\n}\n\n/** A declared band that is metered, with its one field and its counter. */\nexport type ResolvedPluginMeteredBand = ResolvedPluginUsageBand & {\n  metered: PluginMeteredBand\n  hostCounter: string\n}\n\n/**\n * Every band billed at cost past what the plan includes, in band order — the\n * infrastructure meters a plugin adds beside storage and bandwidth.\n */\nexport function meteredPluginBands(): readonly ResolvedPluginMeteredBand[] {\n  return PLUGIN_USAGE_BANDS_DECLARED.filter(\n    (band): band is ResolvedPluginMeteredBand =>\n      Boolean(band.metered && band.hostCounter),\n  )\n}\n\n/** A declared band measured by a per-site counter and never billed past it. */\nexport type ResolvedPluginCountedBand = ResolvedPluginUsageBand & {\n  hostCounter: string\n}\n\n/**\n * Every band measured by a per-site counter and not metered, in band order:\n * the usage sweep sums each across the workspace's sites and records it under\n * the band's first field, and the staff usage rows show the count. A metered\n * band's counter is read with the infrastructure meters instead.\n */\nexport function countedPluginBands(): readonly ResolvedPluginCountedBand[] {\n  return PLUGIN_USAGE_BANDS_DECLARED.filter(\n    (band): band is ResolvedPluginCountedBand =>\n      Boolean(band.hostCounter && !band.metered),\n  )\n}\n\n/** The rollup field a metered band records its count under. */\nexport function meteredBandField(band: ResolvedPluginMeteredBand): string {\n  return band.fields[0]!\n}\n\n/**\n * Where the rollup records a withheld band's verdict (`metered.withheldUntil`):\n * whether the month billed the band's overage, and what was forgone, at cost,\n * when it did not. Without the second a withheld month reads as a month that\n * stayed inside the band.\n */\nexport function meteredBandVerdictFields(band: ResolvedPluginMeteredBand): {\n  billed: string\n  withheldUsd: string\n} {\n  const field = meteredBandField(band)\n  return { billed: `${field}Billed`, withheldUsd: `${field}OverageWithheldUsd` }\n}\n\nexport function pluginSpendLines(): readonly ResolvedPluginSpendLine[] {\n  return PLUGIN_SPEND_LINES_DECLARED\n}\n\n/** A positive finite number, or 0 — the reading every meter is priced from. */\nfunction meterValue(value: unknown): number {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\n/**\n * What a rollup recorded for a declared meter: `fields` summed, or\n * `fallbackFields` summed when the rollup carries none of `fields` at all.\n *\n * \"Carries none\" is `null` or absent, never zero. A rollup that measured\n * zero has answered, and must not fall back to a figure recorded under an\n * older, narrower basis.\n */\nexport function declaredMeterReading(\n  source: Readonly<Record<string, unknown>> | null | undefined,\n  declared: {\n    fields: readonly string[]\n    fallbackFields?: readonly string[]\n  },\n): number {\n  const present = declared.fields.some((field) => source?.[field] != null)\n  const fields =\n    !present && declared.fallbackFields?.length\n      ? declared.fallbackFields\n      : declared.fields\n  return fields.reduce((sum, field) => sum + meterValue(source?.[field]), 0)\n}\n\n/**\n * The live reading a cost axis names: the first of its `live.fields` that is\n * a positive number on the month's document, or `undefined` when none is.\n * `undefined` is \"keep the rollup's snapshot\", never zero.\n */\nexport function liveMeterReading(\n  document: { get(field: string): unknown } | null | undefined,\n  live: { fields: readonly string[] },\n): number | undefined {\n  for (const field of live.fields) {\n    const value = meterValue(document?.get(field))\n    if (value > 0) return value\n  }\n  return undefined\n}\n\n/** Every rollup field the declared cost axes read or record, in order. */\nexport function pluginCostAxisFields(): string[] {\n  const fields: string[] = []\n  for (const axis of PLUGIN_COST_AXES_DECLARED) {\n    for (const field of [\n      ...axis.fields,\n      ...(axis.fallbackFields ?? []),\n      ...(axis.recordedFields ?? []),\n    ]) {\n      if (!fields.includes(field)) fields.push(field)\n    }\n  }\n  return fields\n}\n\n/**\n * A month's rollup as a staff reader is served it, one entry per field the\n * declared cost axes read, record or serve to staff (`get` reads one rollup\n * field).\n *\n * A field an axis prices reads zero where the rollup lacks it, as the cost\n * model reads it — except where the axis falls back to an older basis when\n * the rollup carries none of its fields: there absence is the answer that\n * selects the fallback, so it is served as `null`, and a reader pricing the\n * served row reads the month the way the sweep did. A field an axis only\n * records or serves reads `null` when the rollup never wrote it: \"not\n * recorded\" and \"recorded zero\" are different answers, and a projection\n * that collapses them invents history (AGL-2321).\n */\nexport function pluginCostAxisProjection(\n  get: (field: string) => unknown,\n): Record<string, number | null> {\n  const out: Record<string, number | null> = {}\n  for (const axis of PLUGIN_COST_AXES_DECLARED) {\n    const absentIsNull = [\n      ...(axis.fallbackFields?.length ? axis.fields : []),\n      ...(axis.recordedFields ?? []),\n      ...(axis.staffFields ?? []),\n    ]\n    for (const field of [\n      ...axis.fields,\n      ...(axis.fallbackFields ?? []),\n      ...(axis.recordedFields ?? []),\n      ...(axis.staffFields ?? []),\n    ]) {\n      if (field in out) continue\n      const value = get(field)\n      out[field] =\n        value != null ? Number(value) : absentIsNull.includes(field) ? null : 0\n    }\n  }\n  return out\n}\n"],"names":["PLUGIN_COST_AXES_DECLARED","PLUGIN_SPEND_LINES_DECLARED","PLUGIN_USAGE_BANDS_DECLARED","pluginCostAxes","pluginUsageBands","meteredPluginBands","filter","band","Boolean","metered","hostCounter","countedPluginBands","meteredBandField","fields","meteredBandVerdictFields","field","billed","withheldUsd","pluginSpendLines","meterValue","value","parsed","Number","isFinite","declaredMeterReading","source","declared","present","some","fallbackFields","length","reduce","sum","liveMeterReading","document","live","get","undefined","pluginCostAxisFields","axis","recordedFields","includes","push","pluginCostAxisProjection","out","absentIsNull","staffFields"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDC,GAGD,SACEA,yBAAyB,EACzBC,2BAA2B,EAC3BC,2BAA2B,QACtB,qCAAiC;AAsKxC,OAAO,SAASC;IACd,OAAOH;AACT;AAEA,OAAO,SAASI;IACd,OAAOF;AACT;AAQA;;;CAGC,GACD,OAAO,SAASG;IACd,OAAOH,4BAA4BI,MAAM,CACvC,CAACC,OACCC,QAAQD,KAAKE,OAAO,IAAIF,KAAKG,WAAW;AAE9C;AAOA;;;;;CAKC,GACD,OAAO,SAASC;IACd,OAAOT,4BAA4BI,MAAM,CACvC,CAACC,OACCC,QAAQD,KAAKG,WAAW,IAAI,CAACH,KAAKE,OAAO;AAE/C;AAEA,6DAA6D,GAC7D,OAAO,SAASG,iBAAiBL,IAA+B;IAC9D,OAAOA,KAAKM,MAAM,CAAC,EAAE;AACvB;AAEA;;;;;CAKC,GACD,OAAO,SAASC,yBAAyBP,IAA+B;IAItE,MAAMQ,QAAQH,iBAAiBL;IAC/B,OAAO;QAAES,QAAQ,GAAGD,MAAM,MAAM,CAAC;QAAEE,aAAa,GAAGF,MAAM,kBAAkB,CAAC;IAAC;AAC/E;AAEA,OAAO,SAASG;IACd,OAAOjB;AACT;AAEA,6EAA6E,GAC7E,SAASkB,WAAWC,KAAc;IAChC,MAAMC,SAASC,OAAOF,gBAAAA,QAAS;IAC/B,OAAOE,OAAOC,QAAQ,CAACF,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA;;;;;;;CAOC,GACD,OAAO,SAASG,qBACdC,MAA4D,EAC5DC,QAGC;QAIaA;IAFd,MAAMC,UAAUD,SAASb,MAAM,CAACe,IAAI,CAAC,CAACb,QAAUU,CAAAA,0BAAAA,MAAQ,CAACV,MAAM,KAAI;IACnE,MAAMF,SACJ,CAACc,aAAWD,2BAAAA,SAASG,cAAc,qBAAvBH,yBAAyBI,MAAM,IACvCJ,SAASG,cAAc,GACvBH,SAASb,MAAM;IACrB,OAAOA,OAAOkB,MAAM,CAAC,CAACC,KAAKjB,QAAUiB,MAAMb,WAAWM,0BAAAA,MAAQ,CAACV,MAAM,GAAG;AAC1E;AAEA;;;;CAIC,GACD,OAAO,SAASkB,iBACdC,QAA4D,EAC5DC,IAAmC;IAEnC,KAAK,MAAMpB,SAASoB,KAAKtB,MAAM,CAAE;QAC/B,MAAMO,QAAQD,WAAWe,4BAAAA,SAAUE,GAAG,CAACrB;QACvC,IAAIK,QAAQ,GAAG,OAAOA;IACxB;IACA,OAAOiB;AACT;AAEA,wEAAwE,GACxE,OAAO,SAASC;IACd,MAAMzB,SAAmB,EAAE;IAC3B,KAAK,MAAM0B,QAAQvC,0BAA2B;YAGtCuC,sBACAA;QAHN,KAAK,MAAMxB,SAAS;eACfwB,KAAK1B,MAAM;gBACV0B,uBAAAA,KAAKV,cAAc,YAAnBU,uBAAuB,EAAE;gBACzBA,uBAAAA,KAAKC,cAAc,YAAnBD,uBAAuB,EAAE;SAC9B,CAAE;YACD,IAAI,CAAC1B,OAAO4B,QAAQ,CAAC1B,QAAQF,OAAO6B,IAAI,CAAC3B;QAC3C;IACF;IACA,OAAOF;AACT;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAAS8B,yBACdP,GAA+B;IAE/B,MAAMQ,MAAqC,CAAC;IAC5C,KAAK,MAAML,QAAQvC,0BAA2B;YAGtCuC,sBACAA,mBAIAA,sBACAA,uBACAA;YARAA;QADN,MAAMM,eAAe;eACfN,EAAAA,wBAAAA,KAAKV,cAAc,qBAAnBU,sBAAqBT,MAAM,IAAGS,KAAK1B,MAAM,GAAG,EAAE;gBAC9C0B,uBAAAA,KAAKC,cAAc,YAAnBD,uBAAuB,EAAE;gBACzBA,oBAAAA,KAAKO,WAAW,YAAhBP,oBAAoB,EAAE;SAC3B;QACD,KAAK,MAAMxB,SAAS;eACfwB,KAAK1B,MAAM;gBACV0B,uBAAAA,KAAKV,cAAc,YAAnBU,uBAAuB,EAAE;gBACzBA,wBAAAA,KAAKC,cAAc,YAAnBD,wBAAuB,EAAE;gBACzBA,qBAAAA,KAAKO,WAAW,YAAhBP,qBAAoB,EAAE;SAC3B,CAAE;YACD,IAAIxB,SAAS6B,KAAK;YAClB,MAAMxB,QAAQgB,IAAIrB;YAClB6B,GAAG,CAAC7B,MAAM,GACRK,SAAS,OAAOE,OAAOF,SAASyB,aAAaJ,QAAQ,CAAC1B,SAAS,OAAO;QAC1E;IACF;IACA,OAAO6B;AACT"}