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

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

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-usage-meters.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A METER A PLUGIN MEASURES IN THE MONTHLY USAGE SWEEP (AGL-3080).\n *\n * The usage sweep (`/api/billing/report-usage`) writes one rollup per\n * workspace and month — `orgs/{orgId}/usage/{month}` — and posts the month's\n * billed figure as one Stripe meter event. The platform's own meters (storage,\n * bandwidth, API requests, email) it measures itself. A plugin's meter it\n * cannot: the plugin owns the collection the usage is recorded in, the band\n * it is measured against and the price past the band.\n *\n * So the plugin registers a meter, and the sweep asks it once per workspace:\n * `measure` answers the fields the plugin writes onto the rollup — under the\n * names its usage axes declare, so the cost model and the utilization table\n * read them — and the dollars that enter the month's billed figure. The sweep\n * never learns what the meter counts or how it prices it, and the plugin\n * never edits the sweep.\n *\n * ## Declared, then registered, and refused when missing\n *\n * A meter is a runtime registration because measuring is code — a read of the\n * plugin's own storage, a band, a price. But a meter that failed to register\n * is money the sweep would silently stop billing, so the plugin also DECLARES\n * it (`usageAxes` → `meters`, compiled into the catalog file), and the sweep\n * refuses to report a workspace's month while a declared meter is missing:\n * the workspace fails loudly for this pass and is swept again tomorrow, which\n * is late and visible, where a month billed without the meter would be short\n * and final.\n *\n * ## A throw is the workspace's, not the sweep's\n *\n * `measure` throwing fails that workspace's pass the same way — a meter that\n * could not measure has no figure worth billing. `closeMonth` is different:\n * it settles what the plugin bills on its own, is logged when it fails, and\n * never costs the platform's own metering.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport type { ReleaseFlagKey } from '../app-utils/release-flags'\nimport { PLUGIN_USAGE_METERS_DECLARED } from './first-party-plugins.generated'\n\n/** What the sweep tells a meter about one workspace's month. */\nexport interface PluginUsageMeterContext {\n  orgId: string\n  /** The workspace document, as the sweep read it for every decision. */\n  org: Readonly<Record<string, unknown>>\n  /** `YYYY-MM`, the month being measured. */\n  month: string\n  /**\n   * Whether the month has CLOSED. A closed month is the one an invoice is\n   * about; an open one is measured daily for the budget and never billed.\n   */\n  closed: boolean\n  /**\n   * The month's rollup as it stood before this run — for a stock meter, the\n   * last reading an earlier sweep stamped inside the month.\n   */\n  previous: Readonly<Record<string, unknown>>\n  /**\n   * A release flag's verdict for this workspace, resolved as the sweep\n   * resolves every flag it gates billing on: bucketed by workspace, with its\n   * overrides and its tier.\n   */\n  releaseFlagOn: (key: ReleaseFlagKey) => boolean\n}\n\n/** What a meter answers for one workspace's month. */\nexport interface PluginUsageMeterReading {\n  /**\n   * Written onto the month's rollup on every run, zeros included. A field the\n   * platform writes itself is never overwritten.\n   */\n  fields: Readonly<Record<string, unknown>>\n  /**\n   * Written only while the month is OPEN — a stock meter's period-end reading,\n   * which a closed sweep then bills from. Never written for a closed month,\n   * so a re-run of a closed month reads the same input every time.\n   */\n  periodEndFields?: Readonly<Record<string, unknown>>\n  /**\n   * Dollars that enter the month's billed figure. Rounded to cents per meter,\n   * like every plan-priced line beside it; 0 for a meter that bills nothing.\n   */\n  billedUsd: number\n  /**\n   * For a stock meter on a CLOSED month: `true` when the reading came from a\n   * period-end stamp taken inside the month. The rollup's `stockBasis` is\n   * `period-end` when any stock reading was.\n   */\n  periodEndBasis?: boolean\n}\n\n/** What a meter's close-out is told about one workspace's closed month. */\nexport interface PluginUsageMeterCloseContext extends PluginUsageMeterContext {\n  /**\n   * The workspace's Stripe customer, or `null` when it has none. Read only\n   * when asked, so a close-out with nothing to settle costs no read.\n   */\n  stripeCustomerId: () => Promise<string | null>\n}\n\n/** A plugin's meter in the monthly usage sweep. */\nexport interface PluginUsageMeter {\n  pluginId: string\n  /** As the plugin's `usageAxes` declaration names it under `meters`. */\n  id: string\n  measure: (context: PluginUsageMeterContext) => Promise<PluginUsageMeterReading>\n  /**\n   * Called once per workspace for a CLOSED month, every day the sweep runs,\n   * so a plugin that bills part of its usage itself can settle what is left\n   * of it. Idempotent by the plugin's own records; errors are logged.\n   */\n  closeMonth?: (context: PluginUsageMeterCloseContext) => Promise<void>\n}\n\nconst meters = new Map<string, PluginUsageMeter>()\n\nconst keyOf = (pluginId: string, id: string) => `${pluginId}:${id}`\n\n/**\n * Registers a meter. Idempotent per plugin and id: the same pair again\n * replaces the earlier registration, so a declarations module evaluated twice\n * measures once. A meter with no owner, no id or no `measure` throws.\n */\nexport function registerPluginUsageMeter(\n  meter: Omit<PluginUsageMeter, 'pluginId'> & { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? meter.pluginId ?? '').trim()\n  const id = String(meter.id ?? '').trim()\n  if (!pluginId || !id) {\n    throw new Error('a usage meter needs a pluginId and an id')\n  }\n  if (typeof meter.measure !== 'function') {\n    throw new Error(`usage meter \"${keyOf(pluginId, id)}\" has no measure function`)\n  }\n  meters.set(keyOf(pluginId, id), {\n    pluginId,\n    id,\n    measure: meter.measure,\n    ...(typeof meter.closeMonth === 'function'\n      ? { closeMonth: meter.closeMonth }\n      : {}),\n  })\n}\n\n/**\n * Every registered meter, in the order the sweep runs them: declared meters in\n * catalog order, then any other in registration order. The order is fixed so\n * two processes write one workspace's rollup the same way.\n */\nexport function listPluginUsageMeters(): PluginUsageMeter[] {\n  const declared = PLUGIN_USAGE_METERS_DECLARED.map((one) =>\n    keyOf(one.pluginId, one.id),\n  )\n  const rank = (key: string) => {\n    const index = declared.indexOf(key)\n    return index === -1 ? Number.MAX_SAFE_INTEGER : index\n  }\n  return [...meters.entries()]\n    .map(([key, meter], sequence) => ({ key, meter, sequence }))\n    .sort((a, b) => rank(a.key) - rank(b.key) || a.sequence - b.sequence)\n    .map(({ meter }) => ({ ...meter }))\n}\n\n/**\n * Every DECLARED meter nothing registered, as `pluginId:id`. The sweep refuses\n * to report a workspace's month while this is not empty.\n */\nexport function unregisteredPluginUsageMeters(): string[] {\n  return PLUGIN_USAGE_METERS_DECLARED.map((one) =>\n    keyOf(one.pluginId, one.id),\n  ).filter((key) => !meters.has(key))\n}\n\n/** Test seam: forget every meter. */\nexport function resetPluginUsageMetersForTests(): void {\n  meters.clear()\n}\n"],"names":["getRegisteringPluginId","PLUGIN_USAGE_METERS_DECLARED","meters","Map","keyOf","pluginId","id","registerPluginUsageMeter","meter","trim","String","Error","measure","set","closeMonth","listPluginUsageMeters","declared","map","one","rank","key","index","indexOf","Number","MAX_SAFE_INTEGER","entries","sequence","sort","a","b","unregisteredPluginUsageMeters","filter","has","resetPluginUsageMetersForTests","clear"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAExE,SAASC,4BAA4B,QAAQ,qCAAiC;AA4E9E,MAAMC,SAAS,IAAIC;AAEnB,MAAMC,QAAQ,CAACC,UAAkBC,KAAe,GAAGD,SAAS,CAAC,EAAEC,IAAI;AAEnE;;;;CAIC,GACD,OAAO,SAASC,yBACdC,KAAiE;QAE/CR,MAAAA,yBACAQ;IADlB,MAAMH,WAAW,EAACL,QAAAA,0BAAAA,oCAAAA,0BAA4BQ,MAAMH,QAAQ,YAA1CL,OAA8C,IAAIS,IAAI;IACxE,MAAMH,KAAKI,QAAOF,YAAAA,MAAMF,EAAE,YAARE,YAAY,IAAIC,IAAI;IACtC,IAAI,CAACJ,YAAY,CAACC,IAAI;QACpB,MAAM,IAAIK,MAAM;IAClB;IACA,IAAI,OAAOH,MAAMI,OAAO,KAAK,YAAY;QACvC,MAAM,IAAID,MAAM,CAAC,aAAa,EAAEP,MAAMC,UAAUC,IAAI,yBAAyB,CAAC;IAChF;IACAJ,OAAOW,GAAG,CAACT,MAAMC,UAAUC,KAAK;QAC9BD;QACAC;QACAM,SAASJ,MAAMI,OAAO;OAClB,OAAOJ,MAAMM,UAAU,KAAK,aAC5B;QAAEA,YAAYN,MAAMM,UAAU;IAAC,IAC/B,CAAC;AAET;AAEA;;;;CAIC,GACD,OAAO,SAASC;IACd,MAAMC,WAAWf,6BAA6BgB,GAAG,CAAC,CAACC,MACjDd,MAAMc,IAAIb,QAAQ,EAAEa,IAAIZ,EAAE;IAE5B,MAAMa,OAAO,CAACC;QACZ,MAAMC,QAAQL,SAASM,OAAO,CAACF;QAC/B,OAAOC,UAAU,CAAC,IAAIE,OAAOC,gBAAgB,GAAGH;IAClD;IACA,OAAO;WAAInB,OAAOuB,OAAO;KAAG,CACzBR,GAAG,CAAC,CAAC,CAACG,KAAKZ,MAAM,EAAEkB,WAAc,CAAA;YAAEN;YAAKZ;YAAOkB;QAAS,CAAA,GACxDC,IAAI,CAAC,CAACC,GAAGC,IAAMV,KAAKS,EAAER,GAAG,IAAID,KAAKU,EAAET,GAAG,KAAKQ,EAAEF,QAAQ,GAAGG,EAAEH,QAAQ,EACnET,GAAG,CAAC,CAAC,EAAET,KAAK,EAAE,GAAM,aAAKA;AAC9B;AAEA;;;CAGC,GACD,OAAO,SAASsB;IACd,OAAO7B,6BAA6BgB,GAAG,CAAC,CAACC,MACvCd,MAAMc,IAAIb,QAAQ,EAAEa,IAAIZ,EAAE,GAC1ByB,MAAM,CAAC,CAACX,MAAQ,CAAClB,OAAO8B,GAAG,CAACZ;AAChC;AAEA,mCAAmC,GACnC,OAAO,SAASa;IACd/B,OAAOgC,KAAK;AACd"}

package/src/lib/plugin-manager/usage-alert-contributors.d.ts

@@ -15,14 +15,22 @@
  * limitations under the License.
  */
 /**
- * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
+ * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
  *
  * The usage-alerts cron walks every org, reads its usage once, and sends
  * core's own alerts: the plan quotas, the customer's budget and the free
  * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling
  * core knows nothing about registers a contributor here from its
- * `serverDeclarations` entry, and the sweep hands the contributor each org's
- * reading after the budget alert and before the bandwidth cap.
+ * `serverDeclarations` entry, in either or both of two shapes:
+ *
+ * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used
+ *   figure against a limit, how often it may be announced, what happens at
+ *   it, and the words for approaching and reaching it. The sweep runs them
+ *   after its own quota checks, through the same approach threshold, guards
+ *   and both channels, so a plugin's band warns exactly as a platform band
+ *   does.
+ * - `evaluate` decides STAFF alerts, and the sweep hands it each org's
+ *   reading after the budget alert and before the bandwidth cap.
  *
  * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due
  * and what it says; the context does everything else:
@@ -57,6 +65,7 @@
  * loaded the declarations, and a list that followed it could send and report
  * one org's alerts in a different order per process.
  */
+import type { NotificationLevel } from '../app-utils/notifications';
 import type { OrgSpendBreakdown, UsageAlertGuard } from '../app-utils/usage-budget';
 /** One staff alert, as the sweep delivers and reports it. */
 export interface UsageStaffAlert {
@@ -72,6 +81,12 @@ export interface UsageStaffAlert {
     link: string;
     /** The email's tag and log label. */
     emailContext: string;
+    /**
+     * How loud the bell draws it (AGL-3437). A contributor's threshold is its
+     * own unit, not a percentage, so only the contributor can say; absent, the
+     * `billing.usage` default answers.
+     */
+    level?: NotificationLevel;
 }
 /** What the sweep hands a contributor for one org. */
 export interface UsageAlertContext {
@@ -94,19 +109,74 @@ export interface UsageAlertContext {
     /** Delivers one staff alert through the sweep's senders and reports it. */
     alertStaff: (alert: UsageStaffAlert) => Promise<void>;
 }
+/**
+ * One band a workspace is warned about as it approaches and reaches it — the
+ * shape of a plugin's quota check.
+ *
+ * The sweep owns everything past the numbers and the words: the approach
+ * percentage, the guard under `key`, the first-sweep seeding, both channels,
+ * and the sentence every notice opens with — the workspace, then the figures,
+ * then `noun` ("The Acme workspace has used 2,300 of the 2,750 AI assist
+ * credits your plan includes this month").
+ */
+export interface UsageQuotaCheck {
+    /** The guard key; named for what it measures, never one of core's. */
+    key: string;
+    /** How the alert's title names the band: "AI assist credits". */
+    label: string;
+    /** What the figures count, in the opening sentence. */
+    noun: string;
+    used: number;
+    /** `UNLIMITED` or anything not above 0 is skipped. */
+    limit: number;
+    /**
+     * How often one threshold may be announced: `crossing` for something the
+     * workspace HAS, announced once when reached and again only after usage
+     * falls back below; `monthly` for a meter that resets on the 1st.
+     */
+    cadence: 'crossing' | 'monthly';
+    /**
+     * What happens at the band, which the notice has to say because the three
+     * call for different actions: `stops` (new use is refused, nothing is
+     * charged), `bills` (it keeps working and starts charging) or `continues`
+     * (nothing is refused and nothing is charged).
+     */
+    outcome: 'stops' | 'bills' | 'continues';
+    /** What is true now, at or past the band. */
+    reached: string;
+    /** What will happen at the band, said while approaching it. */
+    approach: string;
+    /** Replaces the generic title at 100%, when that would not be true. */
+    reachedTitle?: string;
+}
+/** What the sweep hands a contributor's quota checks for one org. */
+export interface UsageQuotaContext {
+    orgId: string;
+    /** The org document as the sweep read it. */
+    org: Readonly<Record<string, unknown>>;
+    /** The `YYYY-MM` month the sweep dedupes against. */
+    month: string;
+    /** The org's spend this month, built from the figures the sweep read. */
+    spend: Readonly<OrgSpendBreakdown>;
+}
 /** A plugin's rule for the usage-alerts sweep. */
 export interface UsageAlertContributor {
     pluginId: string;
     /** Unique within the plugin; two plugins may use the same id. */
     id: string;
-    /** Evaluates one org, sending only through the context. */
-    evaluate: (context: UsageAlertContext) => Promise<void>;
+    /** Evaluates one org's STAFF alerts, sending only through the context. */
+    evaluate?: (context: UsageAlertContext) => Promise<void>;
+    /**
+     * The bands the WORKSPACE is warned about, which the sweep runs after its
+     * own through the same thresholds, guards and senders.
+     */
+    quotaChecks?: (context: UsageQuotaContext) => Promise<readonly UsageQuotaCheck[]>;
 }
 /**
  * Registers a contributor. Idempotent per plugin and id: registering the same
  * pair again replaces the earlier contributor in place, so a declarations
  * module evaluated twice does not alert twice. A contributor with no plugin,
- * no id or no `evaluate` throws.
+ * no id, or neither `evaluate` nor `quotaChecks` throws.
  */
 export declare function registerUsageAlertContributor(contributor: UsageAlertContributor): void;
 /** Every registered contributor, in the order the sweep runs them. */

package/src/lib/plugin-manager/usage-alert-contributors.js

@@ -14,14 +14,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
+ * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
  *
  * The usage-alerts cron walks every org, reads its usage once, and sends
  * core's own alerts: the plan quotas, the customer's budget and the free
  * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling
  * core knows nothing about registers a contributor here from its
- * `serverDeclarations` entry, and the sweep hands the contributor each org's
- * reading after the budget alert and before the bandwidth cap.
+ * `serverDeclarations` entry, in either or both of two shapes:
+ *
+ * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used
+ *   figure against a limit, how often it may be announced, what happens at
+ *   it, and the words for approaching and reaching it. The sweep runs them
+ *   after its own quota checks, through the same approach threshold, guards
+ *   and both channels, so a plugin's band warns exactly as a platform band
+ *   does.
+ * - `evaluate` decides STAFF alerts, and the sweep hands it each org's
+ *   reading after the budget alert and before the bandwidth cap.
  *
  * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due
  * and what it says; the context does everything else:
@@ -73,7 +81,7 @@ function catalogRank(pluginId) {
  * Registers a contributor. Idempotent per plugin and id: registering the same
  * pair again replaces the earlier contributor in place, so a declarations
  * module evaluated twice does not alert twice. A contributor with no plugin,
- * no id or no `evaluate` throws.
+ * no id, or neither `evaluate` nor `quotaChecks` throws.
  */ export function registerUsageAlertContributor(contributor) {
     var _contributor_pluginId, _contributor_id;
     const pluginId = String((_contributor_pluginId = contributor.pluginId) != null ? _contributor_pluginId : '').trim();
@@ -81,14 +89,19 @@ function catalogRank(pluginId) {
     if (!pluginId || !id) {
         throw new Error('a usage alert contributor needs a pluginId and an id');
     }
-    if (typeof contributor.evaluate !== 'function') {
-        throw new Error(`usage alert contributor "${pluginId}:${id}" has no evaluate function`);
+    const evaluate = typeof contributor.evaluate === 'function' ? contributor.evaluate : undefined;
+    const quotaChecks = typeof contributor.quotaChecks === 'function' ? contributor.quotaChecks : undefined;
+    if (!evaluate && !quotaChecks) {
+        throw new Error(`usage alert contributor "${pluginId}:${id}" has neither an evaluate ` + 'nor a quotaChecks function');
     }
-    const entry = {
+    const entry = _extends({
         pluginId,
-        id,
-        evaluate: contributor.evaluate
-    };
+        id
+    }, evaluate ? {
+        evaluate
+    } : {}, quotaChecks ? {
+        quotaChecks
+    } : {});
     const index = registrations.findIndex((existing)=>existing.pluginId === pluginId && existing.id === id);
     if (index >= 0) registrations[index] = entry;
     else registrations.push(entry);

package/src/lib/plugin-manager/usage-alert-contributors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/usage-alert-contributors.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 * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).\n *\n * The usage-alerts cron walks every org, reads its usage once, and sends\n * core's own alerts: the plan quotas, the customer's budget and the free\n * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling\n * core knows nothing about registers a contributor here from its\n * `serverDeclarations` entry, and the sweep hands the contributor each org's\n * reading after the budget alert and before the bandwidth cap.\n *\n * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due\n * and what it says; the context does everything else:\n *\n * - `recordAlert(key, threshold)` records the dedupe guard and answers\n *   whether the alert may be SENT. On an org's first, silent evaluation it\n *   records the guard as though the alert went out and answers `false`, so a\n *   contributor that sends only on `true` honors the first-sweep seeding\n *   without knowing when it applies.\n * - `alertStaff(alert)` is the sweep's own sender: the staff bell, then the\n *   staff inbox, then a row in the run's report saying whether the mail went\n *   out. On an org's first, silent evaluation it sends nothing, whoever calls\n *   it.\n * - `guards` is the org's guard map as the sweep read it. A contributor reads\n *   it to dedupe and never writes a guard itself: the sweep writes what\n *   `recordAlert` recorded, once, with the rest of the org's update.\n *\n * Guard keys share one map with core's own checks (`hosts`, `bandwidth`,\n * `budget` and the rest), so a contributor names its keys for what it\n * measures and never reuses one of core's.\n *\n * Contributors run one at a time and are ISOLATED: a throw is logged against\n * the contributor and the next one runs. A guard the failed contributor\n * recorded for an alert it never delivered is dropped rather than written, so\n * the next sweep tries that alert again instead of counting it as announced.\n * One plugin's failure costs no other plugin's alert, none of core's, and not\n * the rest of the sweep.\n *\n * The order is deterministic: the catalog order of `FIRST_PARTY_PLUGINS`,\n * then any other plugin id in code-unit order, then registration order within\n * a plugin. The order contributors REGISTER in depends on how each process\n * loaded the declarations, and a list that followed it could send and report\n * one org's alerts in a different order per process.\n */\n\nimport type {\n  OrgSpendBreakdown,\n  UsageAlertGuard,\n} from '../app-utils/usage-budget'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\n\n/** One staff alert, as the sweep delivers and reports it. */\nexport interface UsageStaffAlert {\n  /** The guard key the alert was recorded under; the report row's `quota`. */\n  quota: string\n  /** The threshold passed to `recordAlert`; the report row's `threshold`. */\n  threshold: number\n  /** The bell's title and the email's subject: one set of words for both. */\n  title: string\n  /** The bell's body. The email carries it verbatim, followed by the link. */\n  body: string\n  /** A console path. The bell links it; the email makes it absolute. */\n  link: string\n  /** The email's tag and log label. */\n  emailContext: string\n}\n\n/** What the sweep hands a contributor for one org. */\nexport interface UsageAlertContext {\n  orgId: string\n  /** The org's slug, or `null` when the document carries none. */\n  orgSlug: string | null\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against, fixed for the whole run. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n  /** The org's guard map as the sweep read it, before this run's updates. */\n  guards: Readonly<Record<string, Readonly<UsageAlertGuard>>>\n  /**\n   * Records the guard for `key` at `threshold` and answers whether the alert\n   * may be sent. Call it once the alert is due, and send only on `true`.\n   */\n  recordAlert: (key: string, threshold: number) => boolean\n  /** Delivers one staff alert through the sweep's senders and reports it. */\n  alertStaff: (alert: UsageStaffAlert) => Promise<void>\n}\n\n/** A plugin's rule for the usage-alerts sweep. */\nexport interface UsageAlertContributor {\n  pluginId: string\n  /** Unique within the plugin; two plugins may use the same id. */\n  id: string\n  /** Evaluates one org, sending only through the context. */\n  evaluate: (context: UsageAlertContext) => Promise<void>\n}\n\nconst registrations: UsageAlertContributor[] = []\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\n/** Code-unit order, which no locale can reorder. */\nfunction codeUnitOrder(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\n/**\n * Registers a contributor. Idempotent per plugin and id: registering the same\n * pair again replaces the earlier contributor in place, so a declarations\n * module evaluated twice does not alert twice. A contributor with no plugin,\n * no id or no `evaluate` throws.\n */\nexport function registerUsageAlertContributor(\n  contributor: UsageAlertContributor,\n): void {\n  const pluginId = String(contributor.pluginId ?? '').trim()\n  const id = String(contributor.id ?? '').trim()\n  if (!pluginId || !id) {\n    throw new Error('a usage alert contributor needs a pluginId and an id')\n  }\n  if (typeof contributor.evaluate !== 'function') {\n    throw new Error(\n      `usage alert contributor \"${pluginId}:${id}\" has no evaluate function`,\n    )\n  }\n  const entry: UsageAlertContributor = {\n    pluginId,\n    id,\n    evaluate: contributor.evaluate,\n  }\n  const index = registrations.findIndex(\n    (existing) => existing.pluginId === pluginId && existing.id === id,\n  )\n  if (index >= 0) registrations[index] = entry\n  else registrations.push(entry)\n}\n\n/** Every registered contributor, in the order the sweep runs them. */\nexport function listUsageAlertContributors(): UsageAlertContributor[] {\n  return registrations\n    .map((entry, sequence) => ({ entry, sequence }))\n    .sort(\n      (a, b) =>\n        catalogRank(a.entry.pluginId) - catalogRank(b.entry.pluginId) ||\n        codeUnitOrder(a.entry.pluginId, b.entry.pluginId) ||\n        a.sequence - b.sequence,\n    )\n    .map(({ entry }) => ({ ...entry }))\n}\n\n/** Test seam: forget every contributor. */\nexport function resetUsageAlertContributorsForTests(): void {\n  registrations.length = 0\n}\n"],"names":["FIRST_PARTY_PLUGINS","registrations","CATALOG_ORDER","Map","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","codeUnitOrder","a","b","registerUsageAlertContributor","contributor","String","trim","Error","evaluate","entry","findIndex","existing","push","listUsageAlertContributors","sequence","sort","resetUsageAlertContributorsForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CC;AAMD,SAASA,mBAAmB,QAAQ,uBAAmB;AAiDvD,MAAMC,gBAAyC,EAAE;AAEjD,MAAMC,gBAAgB,IAAIC,IACxBH,oBAAoBI,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BP;IAAP,QAAOA,qBAAAA,cAAcQ,GAAG,CAACD,qBAAlBP,qBAA+BS,OAAOC,gBAAgB;AAC/D;AAEA,kDAAkD,GAClD,SAASC,cAAcC,CAAS,EAAEC,CAAS;IACzC,OAAOD,IAAIC,IAAI,CAAC,IAAID,IAAIC,IAAI,IAAI;AAClC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,8BACdC,WAAkC;QAEVA,uBACNA;IADlB,MAAMR,WAAWS,QAAOD,wBAAAA,YAAYR,QAAQ,YAApBQ,wBAAwB,IAAIE,IAAI;IACxD,MAAMZ,KAAKW,QAAOD,kBAAAA,YAAYV,EAAE,YAAdU,kBAAkB,IAAIE,IAAI;IAC5C,IAAI,CAACV,YAAY,CAACF,IAAI;QACpB,MAAM,IAAIa,MAAM;IAClB;IACA,IAAI,OAAOH,YAAYI,QAAQ,KAAK,YAAY;QAC9C,MAAM,IAAID,MACR,CAAC,yBAAyB,EAAEX,SAAS,CAAC,EAAEF,GAAG,0BAA0B,CAAC;IAE1E;IACA,MAAMe,QAA+B;QACnCb;QACAF;QACAc,UAAUJ,YAAYI,QAAQ;IAChC;IACA,MAAMf,QAAQL,cAAcsB,SAAS,CACnC,CAACC,WAAaA,SAASf,QAAQ,KAAKA,YAAYe,SAASjB,EAAE,KAAKA;IAElE,IAAID,SAAS,GAAGL,aAAa,CAACK,MAAM,GAAGgB;SAClCrB,cAAcwB,IAAI,CAACH;AAC1B;AAEA,oEAAoE,GACpE,OAAO,SAASI;IACd,OAAOzB,cACJG,GAAG,CAAC,CAACkB,OAAOK,WAAc,CAAA;YAAEL;YAAOK;QAAS,CAAA,GAC5CC,IAAI,CACH,CAACd,GAAGC,IACFP,YAAYM,EAAEQ,KAAK,CAACb,QAAQ,IAAID,YAAYO,EAAEO,KAAK,CAACb,QAAQ,KAC5DI,cAAcC,EAAEQ,KAAK,CAACb,QAAQ,EAAEM,EAAEO,KAAK,CAACb,QAAQ,KAChDK,EAAEa,QAAQ,GAAGZ,EAAEY,QAAQ,EAE1BvB,GAAG,CAAC,CAAC,EAAEkB,KAAK,EAAE,GAAM,aAAKA;AAC9B;AAEA,yCAAyC,GACzC,OAAO,SAASO;IACd5B,cAAc6B,MAAM,GAAG;AACzB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/usage-alert-contributors.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 * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).\n *\n * The usage-alerts cron walks every org, reads its usage once, and sends\n * core's own alerts: the plan quotas, the customer's budget and the free\n * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling\n * core knows nothing about registers a contributor here from its\n * `serverDeclarations` entry, in either or both of two shapes:\n *\n * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used\n *   figure against a limit, how often it may be announced, what happens at\n *   it, and the words for approaching and reaching it. The sweep runs them\n *   after its own quota checks, through the same approach threshold, guards\n *   and both channels, so a plugin's band warns exactly as a platform band\n *   does.\n * - `evaluate` decides STAFF alerts, and the sweep hands it each org's\n *   reading after the budget alert and before the bandwidth cap.\n *\n * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due\n * and what it says; the context does everything else:\n *\n * - `recordAlert(key, threshold)` records the dedupe guard and answers\n *   whether the alert may be SENT. On an org's first, silent evaluation it\n *   records the guard as though the alert went out and answers `false`, so a\n *   contributor that sends only on `true` honors the first-sweep seeding\n *   without knowing when it applies.\n * - `alertStaff(alert)` is the sweep's own sender: the staff bell, then the\n *   staff inbox, then a row in the run's report saying whether the mail went\n *   out. On an org's first, silent evaluation it sends nothing, whoever calls\n *   it.\n * - `guards` is the org's guard map as the sweep read it. A contributor reads\n *   it to dedupe and never writes a guard itself: the sweep writes what\n *   `recordAlert` recorded, once, with the rest of the org's update.\n *\n * Guard keys share one map with core's own checks (`hosts`, `bandwidth`,\n * `budget` and the rest), so a contributor names its keys for what it\n * measures and never reuses one of core's.\n *\n * Contributors run one at a time and are ISOLATED: a throw is logged against\n * the contributor and the next one runs. A guard the failed contributor\n * recorded for an alert it never delivered is dropped rather than written, so\n * the next sweep tries that alert again instead of counting it as announced.\n * One plugin's failure costs no other plugin's alert, none of core's, and not\n * the rest of the sweep.\n *\n * The order is deterministic: the catalog order of `FIRST_PARTY_PLUGINS`,\n * then any other plugin id in code-unit order, then registration order within\n * a plugin. The order contributors REGISTER in depends on how each process\n * loaded the declarations, and a list that followed it could send and report\n * one org's alerts in a different order per process.\n */\n\nimport type { NotificationLevel } from '../app-utils/notifications'\nimport type {\n  OrgSpendBreakdown,\n  UsageAlertGuard,\n} from '../app-utils/usage-budget'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\n\n/** One staff alert, as the sweep delivers and reports it. */\nexport interface UsageStaffAlert {\n  /** The guard key the alert was recorded under; the report row's `quota`. */\n  quota: string\n  /** The threshold passed to `recordAlert`; the report row's `threshold`. */\n  threshold: number\n  /** The bell's title and the email's subject: one set of words for both. */\n  title: string\n  /** The bell's body. The email carries it verbatim, followed by the link. */\n  body: string\n  /** A console path. The bell links it; the email makes it absolute. */\n  link: string\n  /** The email's tag and log label. */\n  emailContext: string\n  /**\n   * How loud the bell draws it (AGL-3437). A contributor's threshold is its\n   * own unit, not a percentage, so only the contributor can say; absent, the\n   * `billing.usage` default answers.\n   */\n  level?: NotificationLevel\n}\n\n/** What the sweep hands a contributor for one org. */\nexport interface UsageAlertContext {\n  orgId: string\n  /** The org's slug, or `null` when the document carries none. */\n  orgSlug: string | null\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against, fixed for the whole run. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n  /** The org's guard map as the sweep read it, before this run's updates. */\n  guards: Readonly<Record<string, Readonly<UsageAlertGuard>>>\n  /**\n   * Records the guard for `key` at `threshold` and answers whether the alert\n   * may be sent. Call it once the alert is due, and send only on `true`.\n   */\n  recordAlert: (key: string, threshold: number) => boolean\n  /** Delivers one staff alert through the sweep's senders and reports it. */\n  alertStaff: (alert: UsageStaffAlert) => Promise<void>\n}\n\n/**\n * One band a workspace is warned about as it approaches and reaches it — the\n * shape of a plugin's quota check.\n *\n * The sweep owns everything past the numbers and the words: the approach\n * percentage, the guard under `key`, the first-sweep seeding, both channels,\n * and the sentence every notice opens with — the workspace, then the figures,\n * then `noun` (\"The Acme workspace has used 2,300 of the 2,750 AI assist\n * credits your plan includes this month\").\n */\nexport interface UsageQuotaCheck {\n  /** The guard key; named for what it measures, never one of core's. */\n  key: string\n  /** How the alert's title names the band: \"AI assist credits\". */\n  label: string\n  /** What the figures count, in the opening sentence. */\n  noun: string\n  used: number\n  /** `UNLIMITED` or anything not above 0 is skipped. */\n  limit: number\n  /**\n   * How often one threshold may be announced: `crossing` for something the\n   * workspace HAS, announced once when reached and again only after usage\n   * falls back below; `monthly` for a meter that resets on the 1st.\n   */\n  cadence: 'crossing' | 'monthly'\n  /**\n   * What happens at the band, which the notice has to say because the three\n   * call for different actions: `stops` (new use is refused, nothing is\n   * charged), `bills` (it keeps working and starts charging) or `continues`\n   * (nothing is refused and nothing is charged).\n   */\n  outcome: 'stops' | 'bills' | 'continues'\n  /** What is true now, at or past the band. */\n  reached: string\n  /** What will happen at the band, said while approaching it. */\n  approach: string\n  /** Replaces the generic title at 100%, when that would not be true. */\n  reachedTitle?: string\n}\n\n/** What the sweep hands a contributor's quota checks for one org. */\nexport interface UsageQuotaContext {\n  orgId: string\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n}\n\n/** A plugin's rule for the usage-alerts sweep. */\nexport interface UsageAlertContributor {\n  pluginId: string\n  /** Unique within the plugin; two plugins may use the same id. */\n  id: string\n  /** Evaluates one org's STAFF alerts, sending only through the context. */\n  evaluate?: (context: UsageAlertContext) => Promise<void>\n  /**\n   * The bands the WORKSPACE is warned about, which the sweep runs after its\n   * own through the same thresholds, guards and senders.\n   */\n  quotaChecks?: (context: UsageQuotaContext) => Promise<readonly UsageQuotaCheck[]>\n}\n\nconst registrations: UsageAlertContributor[] = []\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\n/** Code-unit order, which no locale can reorder. */\nfunction codeUnitOrder(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\n/**\n * Registers a contributor. Idempotent per plugin and id: registering the same\n * pair again replaces the earlier contributor in place, so a declarations\n * module evaluated twice does not alert twice. A contributor with no plugin,\n * no id, or neither `evaluate` nor `quotaChecks` throws.\n */\nexport function registerUsageAlertContributor(\n  contributor: UsageAlertContributor,\n): void {\n  const pluginId = String(contributor.pluginId ?? '').trim()\n  const id = String(contributor.id ?? '').trim()\n  if (!pluginId || !id) {\n    throw new Error('a usage alert contributor needs a pluginId and an id')\n  }\n  const evaluate =\n    typeof contributor.evaluate === 'function' ? contributor.evaluate : undefined\n  const quotaChecks =\n    typeof contributor.quotaChecks === 'function'\n      ? contributor.quotaChecks\n      : undefined\n  if (!evaluate && !quotaChecks) {\n    throw new Error(\n      `usage alert contributor \"${pluginId}:${id}\" has neither an evaluate ` +\n        'nor a quotaChecks function',\n    )\n  }\n  const entry: UsageAlertContributor = {\n    pluginId,\n    id,\n    ...(evaluate ? { evaluate } : {}),\n    ...(quotaChecks ? { quotaChecks } : {}),\n  }\n  const index = registrations.findIndex(\n    (existing) => existing.pluginId === pluginId && existing.id === id,\n  )\n  if (index >= 0) registrations[index] = entry\n  else registrations.push(entry)\n}\n\n/** Every registered contributor, in the order the sweep runs them. */\nexport function listUsageAlertContributors(): UsageAlertContributor[] {\n  return registrations\n    .map((entry, sequence) => ({ entry, sequence }))\n    .sort(\n      (a, b) =>\n        catalogRank(a.entry.pluginId) - catalogRank(b.entry.pluginId) ||\n        codeUnitOrder(a.entry.pluginId, b.entry.pluginId) ||\n        a.sequence - b.sequence,\n    )\n    .map(({ entry }) => ({ ...entry }))\n}\n\n/** Test seam: forget every contributor. */\nexport function resetUsageAlertContributorsForTests(): void {\n  registrations.length = 0\n}\n"],"names":["FIRST_PARTY_PLUGINS","registrations","CATALOG_ORDER","Map","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","codeUnitOrder","a","b","registerUsageAlertContributor","contributor","String","trim","Error","evaluate","undefined","quotaChecks","entry","findIndex","existing","push","listUsageAlertContributors","sequence","sort","resetUsageAlertContributorsForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDC;AAOD,SAASA,mBAAmB,QAAQ,uBAAmB;AAgHvD,MAAMC,gBAAyC,EAAE;AAEjD,MAAMC,gBAAgB,IAAIC,IACxBH,oBAAoBI,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BP;IAAP,QAAOA,qBAAAA,cAAcQ,GAAG,CAACD,qBAAlBP,qBAA+BS,OAAOC,gBAAgB;AAC/D;AAEA,kDAAkD,GAClD,SAASC,cAAcC,CAAS,EAAEC,CAAS;IACzC,OAAOD,IAAIC,IAAI,CAAC,IAAID,IAAIC,IAAI,IAAI;AAClC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,8BACdC,WAAkC;QAEVA,uBACNA;IADlB,MAAMR,WAAWS,QAAOD,wBAAAA,YAAYR,QAAQ,YAApBQ,wBAAwB,IAAIE,IAAI;IACxD,MAAMZ,KAAKW,QAAOD,kBAAAA,YAAYV,EAAE,YAAdU,kBAAkB,IAAIE,IAAI;IAC5C,IAAI,CAACV,YAAY,CAACF,IAAI;QACpB,MAAM,IAAIa,MAAM;IAClB;IACA,MAAMC,WACJ,OAAOJ,YAAYI,QAAQ,KAAK,aAAaJ,YAAYI,QAAQ,GAAGC;IACtE,MAAMC,cACJ,OAAON,YAAYM,WAAW,KAAK,aAC/BN,YAAYM,WAAW,GACvBD;IACN,IAAI,CAACD,YAAY,CAACE,aAAa;QAC7B,MAAM,IAAIH,MACR,CAAC,yBAAyB,EAAEX,SAAS,CAAC,EAAEF,GAAG,0BAA0B,CAAC,GACpE;IAEN;IACA,MAAMiB,QAA+B;QACnCf;QACAF;OACIc,WAAW;QAAEA;IAAS,IAAI,CAAC,GAC3BE,cAAc;QAAEA;IAAY,IAAI,CAAC;IAEvC,MAAMjB,QAAQL,cAAcwB,SAAS,CACnC,CAACC,WAAaA,SAASjB,QAAQ,KAAKA,YAAYiB,SAASnB,EAAE,KAAKA;IAElE,IAAID,SAAS,GAAGL,aAAa,CAACK,MAAM,GAAGkB;SAClCvB,cAAc0B,IAAI,CAACH;AAC1B;AAEA,oEAAoE,GACpE,OAAO,SAASI;IACd,OAAO3B,cACJG,GAAG,CAAC,CAACoB,OAAOK,WAAc,CAAA;YAAEL;YAAOK;QAAS,CAAA,GAC5CC,IAAI,CACH,CAAChB,GAAGC,IACFP,YAAYM,EAAEU,KAAK,CAACf,QAAQ,IAAID,YAAYO,EAAES,KAAK,CAACf,QAAQ,KAC5DI,cAAcC,EAAEU,KAAK,CAACf,QAAQ,EAAEM,EAAES,KAAK,CAACf,QAAQ,KAChDK,EAAEe,QAAQ,GAAGd,EAAEc,QAAQ,EAE1BzB,GAAG,CAAC,CAAC,EAAEoB,KAAK,EAAE,GAAM,aAAKA;AAC9B;AAEA,yCAAyC,GACzC,OAAO,SAASO;IACd9B,cAAc+B,MAAM,GAAG;AACzB"}