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

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":"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"}

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

@@ -0,0 +1,108 @@
+/**
+ * @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 type { ReleaseFlagKey } from '../app-utils/release-flags';
+/** What the sweep tells a meter about one workspace's month. */
+export interface PluginUsageMeterContext {
+    orgId: string;
+    /** The workspace document, as the sweep read it for every decision. */
+    org: Readonly<Record<string, unknown>>;
+    /** `YYYY-MM`, the month being measured. */
+    month: string;
+    /**
+     * Whether the month has CLOSED. A closed month is the one an invoice is
+     * about; an open one is measured daily for the budget and never billed.
+     */
+    closed: boolean;
+    /**
+     * The month's rollup as it stood before this run — for a stock meter, the
+     * last reading an earlier sweep stamped inside the month.
+     */
+    previous: Readonly<Record<string, unknown>>;
+    /**
+     * A release flag's verdict for this workspace, resolved as the sweep
+     * resolves every flag it gates billing on: bucketed by workspace, with its
+     * overrides and its tier.
+     */
+    releaseFlagOn: (key: ReleaseFlagKey) => boolean;
+}
+/** What a meter answers for one workspace's month. */
+export interface PluginUsageMeterReading {
+    /**
+     * Written onto the month's rollup on every run, zeros included. A field the
+     * platform writes itself is never overwritten.
+     */
+    fields: Readonly<Record<string, unknown>>;
+    /**
+     * Written only while the month is OPEN — a stock meter's period-end reading,
+     * which a closed sweep then bills from. Never written for a closed month,
+     * so a re-run of a closed month reads the same input every time.
+     */
+    periodEndFields?: Readonly<Record<string, unknown>>;
+    /**
+     * Dollars that enter the month's billed figure. Rounded to cents per meter,
+     * like every plan-priced line beside it; 0 for a meter that bills nothing.
+     */
+    billedUsd: number;
+    /**
+     * For a stock meter on a CLOSED month: `true` when the reading came from a
+     * period-end stamp taken inside the month. The rollup's `stockBasis` is
+     * `period-end` when any stock reading was.
+     */
+    periodEndBasis?: boolean;
+}
+/** What a meter's close-out is told about one workspace's closed month. */
+export interface PluginUsageMeterCloseContext extends PluginUsageMeterContext {
+    /**
+     * The workspace's Stripe customer, or `null` when it has none. Read only
+     * when asked, so a close-out with nothing to settle costs no read.
+     */
+    stripeCustomerId: () => Promise<string | null>;
+}
+/** A plugin's meter in the monthly usage sweep. */
+export interface PluginUsageMeter {
+    pluginId: string;
+    /** As the plugin's `usageAxes` declaration names it under `meters`. */
+    id: string;
+    measure: (context: PluginUsageMeterContext) => Promise<PluginUsageMeterReading>;
+    /**
+     * Called once per workspace for a CLOSED month, every day the sweep runs,
+     * so a plugin that bills part of its usage itself can settle what is left
+     * of it. Idempotent by the plugin's own records; errors are logged.
+     */
+    closeMonth?: (context: PluginUsageMeterCloseContext) => Promise<void>;
+}
+/**
+ * Registers a meter. Idempotent per plugin and id: the same pair again
+ * replaces the earlier registration, so a declarations module evaluated twice
+ * measures once. A meter with no owner, no id or no `measure` throws.
+ */
+export declare function registerPluginUsageMeter(meter: Omit<PluginUsageMeter, 'pluginId'> & {
+    pluginId?: string;
+}): void;
+/**
+ * Every registered meter, in the order the sweep runs them: declared meters in
+ * catalog order, then any other in registration order. The order is fixed so
+ * two processes write one workspace's rollup the same way.
+ */
+export declare function listPluginUsageMeters(): PluginUsageMeter[];
+/**
+ * Every DECLARED meter nothing registered, as `pluginId:id`. The sweep refuses
+ * to report a workspace's month while this is not empty.
+ */
+export declare function unregisteredPluginUsageMeters(): string[];
+/** Test seam: forget every meter. */
+export declare function resetPluginUsageMetersForTests(): void;

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

@@ -0,0 +1,105 @@
+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.
+ */ /**
+ * A METER A PLUGIN MEASURES IN THE MONTHLY USAGE SWEEP (AGL-3080).
+ *
+ * The usage sweep (`/api/billing/report-usage`) writes one rollup per
+ * workspace and month — `orgs/{orgId}/usage/{month}` — and posts the month's
+ * billed figure as one Stripe meter event. The platform's own meters (storage,
+ * bandwidth, API requests, email) it measures itself. A plugin's meter it
+ * cannot: the plugin owns the collection the usage is recorded in, the band
+ * it is measured against and the price past the band.
+ *
+ * So the plugin registers a meter, and the sweep asks it once per workspace:
+ * `measure` answers the fields the plugin writes onto the rollup — under the
+ * names its usage axes declare, so the cost model and the utilization table
+ * read them — and the dollars that enter the month's billed figure. The sweep
+ * never learns what the meter counts or how it prices it, and the plugin
+ * never edits the sweep.
+ *
+ * ## Declared, then registered, and refused when missing
+ *
+ * A meter is a runtime registration because measuring is code — a read of the
+ * plugin's own storage, a band, a price. But a meter that failed to register
+ * is money the sweep would silently stop billing, so the plugin also DECLARES
+ * it (`usageAxes` → `meters`, compiled into the catalog file), and the sweep
+ * refuses to report a workspace's month while a declared meter is missing:
+ * the workspace fails loudly for this pass and is swept again tomorrow, which
+ * is late and visible, where a month billed without the meter would be short
+ * and final.
+ *
+ * ## A throw is the workspace's, not the sweep's
+ *
+ * `measure` throwing fails that workspace's pass the same way — a meter that
+ * could not measure has no figure worth billing. `closeMonth` is different:
+ * it settles what the plugin bills on its own, is logged when it fails, and
+ * never costs the platform's own metering.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { PLUGIN_USAGE_METERS_DECLARED } from "./first-party-plugins.generated.js";
+const meters = new Map();
+const keyOf = (pluginId, id)=>`${pluginId}:${id}`;
+/**
+ * Registers a meter. Idempotent per plugin and id: the same pair again
+ * replaces the earlier registration, so a declarations module evaluated twice
+ * measures once. A meter with no owner, no id or no `measure` throws.
+ */ export function registerPluginUsageMeter(meter) {
+    var _ref, _getRegisteringPluginId, _meter_id;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : meter.pluginId) != null ? _ref : '').trim();
+    const id = String((_meter_id = meter.id) != null ? _meter_id : '').trim();
+    if (!pluginId || !id) {
+        throw new Error('a usage meter needs a pluginId and an id');
+    }
+    if (typeof meter.measure !== 'function') {
+        throw new Error(`usage meter "${keyOf(pluginId, id)}" has no measure function`);
+    }
+    meters.set(keyOf(pluginId, id), _extends({
+        pluginId,
+        id,
+        measure: meter.measure
+    }, typeof meter.closeMonth === 'function' ? {
+        closeMonth: meter.closeMonth
+    } : {}));
+}
+/**
+ * Every registered meter, in the order the sweep runs them: declared meters in
+ * catalog order, then any other in registration order. The order is fixed so
+ * two processes write one workspace's rollup the same way.
+ */ export function listPluginUsageMeters() {
+    const declared = PLUGIN_USAGE_METERS_DECLARED.map((one)=>keyOf(one.pluginId, one.id));
+    const rank = (key)=>{
+        const index = declared.indexOf(key);
+        return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+    };
+    return [
+        ...meters.entries()
+    ].map(([key, meter], sequence)=>({
+            key,
+            meter,
+            sequence
+        })).sort((a, b)=>rank(a.key) - rank(b.key) || a.sequence - b.sequence).map(({ meter })=>_extends({}, meter));
+}
+/**
+ * Every DECLARED meter nothing registered, as `pluginId:id`. The sweep refuses
+ * to report a workspace's month while this is not empty.
+ */ export function unregisteredPluginUsageMeters() {
+    return PLUGIN_USAGE_METERS_DECLARED.map((one)=>keyOf(one.pluginId, one.id)).filter((key)=>!meters.has(key));
+}
+/** Test seam: forget every meter. */ export function resetPluginUsageMetersForTests() {
+    meters.clear();
+}
+
+//# sourceMappingURL=plugin-usage-meters.js.map