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

package/src/lib/app-utils/plan-entitlements.d.ts

@@ -189,11 +189,13 @@ type NonQuotaEntitlementKeys = 'planComp';
  * `Required` is over the CORE halves on purpose (AGL-3124). It is what keeps
  * a plan table honest — a plan that forgets a platform quota or a platform
  * gate does not compile — and that reasoning does not carry to a plugin's
- * key: a plugin's band comes from its own seat-add-on declaration, and
- * requiring it here would mean every plan row in the core naming every
- * installed plugin's keys, which is the arrangement the seam retires. So the
- * plugin halves join as declared: present once a plugin declares them, and
- * optional, because a workspace without the plugin has no value for them.
+ * key: a plugin's figure per plan comes from its own `plan-entitlements`
+ * declaration (AGL-3080), whose rows are typed per plan and so cannot forget
+ * one either, and requiring it here would mean every plan row in the core
+ * naming every installed plugin's keys, which is the arrangement the seam
+ * retires. So the plugin halves join as declared: present once a plugin
+ * declares them, and optional, because core compiles without the plugin's
+ * type and a workspace without the plugin has no value for them.
  *
  * They join in their MAPPED form (`PluginOrgQuotas`, `PluginOrgFeatures`)
  * because an intersection with a bare interface has no implicit string index
@@ -204,80 +206,6 @@ type NonQuotaEntitlementKeys = 'planComp';
 export type ResolvedOrgEntitlements = Required<Omit<CoreOrgEntitlements, 'features' | LegacyEntitlementKeys | RetiredEntitlementKeys | NonQuotaEntitlementKeys>> & PluginOrgQuotas & {
     features: Required<CoreOrgFeatureFlags> & PluginOrgFeatures;
 };
-/**
- * Aglyn Assist credits an Enterprise agreement includes per month, before the
- * contract says otherwise.
- *
- * ## Never `UNLIMITED`, and the reason is not stylistic
- *
- * `UNLIMITED` is `Number.POSITIVE_INFINITY`, `JSON.stringify(Infinity)` is
- * `null`, and `Number(null)` is `0`. An unbounded assist band therefore
- * serialises to a band of ZERO through every route that does not also send
- * the explicit flag `restoreQuotaLimit` rebuilds from — which would hand the
- * only customers with a signed contract the one budget that refuses
- * everything. A finite number crosses the wire as itself.
- *
- * The band is also a real liability rather than a capacity we already own.
- * Storage and page views are infrastructure metered into the deal; assist is
- * a per-token charge from a third party, and generative building spends it in
- * units two orders of magnitude apart.
- *
- * ## Why this number
- *
- * Enterprise carries no list price, so the band cannot be sized the way every
- * self-serve tier's is — against what that tier's other cost terms leave out
- * of a known price. It is anchored to the top of the ladder instead: 116,000
- * credits is twice Agency's band, the rule every Enterprise fallback follows
- * since the 2026-09-07 pricing decision (see the `enterprise` row of
- * `PLAN_ENTITLEMENTS`). In cost that is $116 of provider spend a month, or
- * under 9% of any deal priced at or above the self-serve top. A deal below
- * that is sold as Agency, not written as an Enterprise agreement.
- *
- * ## It is a DEFAULT, and a contract raises it
- *
- * `resolveOrgEntitlements` applies a per-org `entitlements.assistCreditsPerMonth`
- * override ahead of this, so a deal that buys more assist buys it on that org
- * without moving the figure every other agreement is measured against — the
- * same mechanism the other contracted bands use.
- */
-export declare const ENTERPRISE_ASSIST_CREDITS_PER_MONTH = 116000;
-/**
- * The Free AI taste (AGL-2925): the assist credits a Free workspace draws
- * on each month, behind a hard wall.
- *
- * ## Why it exists
- *
- * So the AI landing pages can say "generate your first page free" and mean
- * it. Three hundred credits is one or two generated sections or a handful
- * of copy rewrites — enough to see what the assistant does, not enough to
- * build a site on. The band is a WALL: `PLAN_PRICING.free
- * .extraAssistCreditsUsdPer1k` stays `null`, so `assistBandRefuses` answers
- * true and the reservation refuses at 100% with no overage, no switch and no
- * invoice. Nothing about a Free workspace can produce a charge.
- *
- * ## What it costs, and why that is the number
- *
- * A credit is `ASSIST_CREDIT_COST_USD` of provider spend, so the band costs
- * at most **$0.30 per Free workspace per month** — asserted by
- * `apps/console/specs/tier-margin-floor.spec.ts`. It is the one AI band with
- * no invoice behind it, which is why the same issue closes every multiplier
- * a script could use before the flag flips:
- *
- *  - it is metered per ACCOUNT as well as per workspace, so the three free
- *    workspaces an account may hold (AGL-2265) share one 300-credit
- *    allowance rather than tripling it (`reserveAssistMessage`);
- *  - a fresh account waits `AI_FREE_MIN_ACCOUNT_AGE_HOURS` before it can
- *    spend, and every free request is bounded per IP, per uid and per
- *    account per day;
- *  - a platform-wide daily ceiling on free spend pauses the taste for
- *    everyone until the UTC day rolls, paid workspaces untouched.
- *
- * The account allowance reads THIS constant rather than the workspace's
- * resolved band, because a staff override that widens one workspace's band
- * is a decision about that workspace, not about how much one person may
- * draw across all of theirs.
- */
-export declare const FREE_AI_TASTE_CREDITS_PER_MONTH = 300;
 export declare const PLAN_ENTITLEMENTS: Record<OrgPlan, ResolvedOrgEntitlements>;
 /**
  * The tiers a customer can buy themselves — every plan EXCEPT `enterprise`
@@ -1115,36 +1043,24 @@ export declare const ORG_COGS_UNIT_RATES_USD: {
      */
     perRun: number;
 };
-/** The rollup fields `orgMonthlyCogsUsd` prices. All optional and all absent-safe. */
+/**
+ * The rollup fields `orgMonthlyCogsUsd` prices. All optional and all
+ * absent-safe.
+ *
+ * The named fields are the platform's own meters. A plugin's meter rides the
+ * index signature under the rollup field its declaration names
+ * (`plugin-usage-axes.ts`): the AI plugin's provider spend, the CRM's
+ * records, the forms plugin's submissions, the workflows plugin's runs.
+ */
 export interface OrgUsageRollupInput {
     hostCount?: number | null;
     storageGb?: number | null;
     pageViews?: number | null;
-    formSubmissions?: number | null;
     dataStorageMb?: number | null;
     apiRequests?: number | null;
-    /**
-     * Contacts alone — the figure every rollup carried before AGL-2611 widened
-     * the band, kept so a month written under the old basis still prices.
-     * Read only when `crmRecordsCount` is absent; see it.
-     */
-    contactsCount?: number | null;
-    /**
-     * Contacts + companies + deals, the CRM records band's own figure
-     * (AGL-2611). Priced at `perContactMonth` — the rate was measured on a
-     * contact, which is the most expensive of the three to hold, so it
-     * over-covers a company or a deal rather than under-pricing one. When
-     * present it REPLACES `contactsCount` in the model rather than adding to
-     * it: the contacts are inside this sum, and a model that priced both
-     * would charge the same people twice.
-     */
-    crmRecordsCount?: number | null;
-    /** The components of `crmRecordsCount`, recorded so the sum is legible. */
-    companiesCount?: number | null;
-    dealsCount?: number | null;
     /**
      * Every email the org sent this month, campaigns and transactional alike —
-     * the `emailSends` cost meter, not `campaignEmailSends`.
+     * the `emailSends` cost meter, not the campaign meter.
      *
      * The cost meter is the right input precisely because the campaign meter is
      * the one with a cap on it. What this org cost us is every message the
@@ -1153,24 +1069,13 @@ export interface OrgUsageRollupInput {
      */
     emailSends?: number | null;
     /**
-     * Aglyn Assist provider spend for the month, ALREADY IN DOLLARS (AGL-2280).
-     *
-     * Unlike every other field here this is not a meter to be priced — it is
-     * `orgs/{id}/assistUsage/{month}.estCostUsd`, our own cost estimate at the
-     * provider's list rates, computed where the tokens were counted. So it
-     * enters the model at ×1 and has no entry in `ORG_COGS_UNIT_RATES_USD`;
-     * inventing a second per-token rate here is precisely the drift AGL-1134
-     * removed.
-     */
-    assistCostUsd?: number | null;
-    /**
-     * Workflow and action runs this month — the two counters `report-usage`
-     * sums across the org's hosts. Priced together at `perRun`: a run is the
-     * same handful of reads, two writes and a moment of compute whichever
-     * builder produced it, and the bands differ only in which tier sells them.
+     * A plugin's meter, by the rollup field its declaration names. `unknown`
+     * because a rollup document carries its month and its audit fields beside
+     * the meters, and a caller may hand the document over whole; every meter
+     * is read through `declaredMeterReading`, which prices only a positive
+     * finite number.
      */
-    workflowRuns?: number | null;
-    actionRuns?: number | null;
+    [field: string]: unknown;
 }
 export interface OrgCogsResult {
     /** What the guardrail should charge against revenue. */
@@ -1226,9 +1131,9 @@ export declare function orgMonthlyCogsUsd(rollup: OrgUsageRollupInput | null | u
  * UNITS, because the field names do not all say: `storageGb` and
  * `dataStorageMb` are gigabytes and MEGABYTES respectively (the conversion
  * lives in `orgMonthlyCogsUsd`, with its own test); `pageViews`,
- * `formSubmissions`, `apiRequests` and `emailSends` are counts FOR THE MONTH;
- * `contactsCount` and `crmRecordsCount` are point-in-time levels, not monthly
- * flows.
+ * `apiRequests` and `emailSends` are counts FOR THE MONTH. A plugin's fields
+ * carry the unit its cost-axis declaration states — a monthly count, a
+ * point-in-time level, or dollars.
  */
 export declare function orgCogsInputFrom(source: Record<string, unknown> | null | undefined): OrgUsageRollupInput;
 /**
@@ -2731,14 +2636,24 @@ export declare function normalizeHostBandwidthCeiling(host: Record<string, any>
 /**
  * Is the render path required to serve the capped notice instead of the page?
  *
- * Both halves must hold: the flag is for THIS month, and the trip was
- * recorded as one that degrades. `degraded` is written by the evaluator from
- * {@link bandwidthCeilingDegradesRender} at trip time rather than re-derived
- * here, so a host that upgrades mid-month is not still being degraded by a
- * flag written while it was free — and, in the other direction, a flag from a
- * paying host can never take that host down.
+ * Three things must hold: the flag is for THIS month, the trip was recorded
+ * as one that degrades, and the org's CURRENT plan still degrades.
+ *
+ * The stored `degraded` alone cannot answer the last one. It is written once,
+ * at trip time, and nothing rewrites it: the beacon stops evaluating a host
+ * once it has tripped this month, and a contained site serves no pages to
+ * beacon from. So a host that upgraded mid-month stayed on the notice until
+ * the 1st, while the owner notice and the visitor notice both promised an
+ * upgrade would bring it back. Re-deriving from `org` on every read releases
+ * it on the next org-doc TTL with no write, the same asymmetry
+ * `bandwidthCapEngaged` keeps for the plan band.
+ *
+ * Both halves still hold in the other direction: a flag written for a paying
+ * host (`degraded: false`) can never take that host down, whatever its plan
+ * becomes later. An unknown org (`null`) resolves as unmetered, so a lookup
+ * failure keeps the containment rather than lifting it.
  */
-export declare function bandwidthCeilingDegradesHost(host: Record<string, any> | null | undefined, month: string): boolean;
+export declare function bandwidthCeilingDegradesHost(host: Record<string, any> | null | undefined, month: string, org: Partial<AglynOrgBilling> | null | undefined): boolean;
 /** UTC `YYYY-MM`, the key both the beacon and the render path agree on. */
 export declare function bandwidthCeilingMonthKey(now?: Date): string;
 /**