@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,2756 @@
+/**
+ * @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 { AglynOrgBilling, CoreOrgEntitlements, CoreOrgFeatureFlags, OrgDiscount, OrgFeatureFlags, OrgPlan, OrgSeatAddons } from '../foundation';
+import type { PluginOrgFeatures, PluginOrgQuotas } from '../plugin-manager/plugin-entitlement-keys';
+import { type OrgOverrideReasonCode } from './org-override-reason';
+import type { ResolvedBrandingProfile } from './platform-brand';
+/** Sentinel for quotas a plan does not cap; `checkQuota` always allows. */
+export declare const UNLIMITED: number;
+/**
+ * How many saved form definitions one site may hold, on every plan that can
+ * build them at all.
+ *
+ * ⛔ **Not a tier lever, and must not become one.** The website-building field
+ * does not meter form COUNT: Squarespace, HubSpot and Mailchimp publish no cap
+ * whatsoever, Webflow abandoned the lever above its free tier, and of the two
+ * that do meter it one is Wix (4/10/25/75) and the other is Jotform
+ * (5/25/50/100), a form-first product where a form IS the billable unit. What
+ * this platform meters on the forms axis is `formSubmissionsPerMonth`, which
+ * is tiered, metered and part of a charged price.
+ *
+ * So this is an abuse ceiling wearing an entitlement's clothes. It rides
+ * `formsPerHost` because that is where `checkQuota` can refuse a create inside
+ * the counting transaction, not because the number is sold — and it resolves
+ * to the same value on Starter through Enterprise. Only Free differs, and only
+ * because the form entity rides `reusableComponents`, which Free lacks.
+ *
+ * The value clears every published competitor number by 5x and the largest
+ * real catalog by far, and it stays STRICTLY below `FORMS_MAX_PER_HOST` — the
+ * page size two listing reads use. The gap is deliberate: a catalog can sit
+ * above this ceiling when a per-org override is withdrawn, and the two
+ * numbers must stay tellable apart so a surface reading the window where it
+ * means the ceiling is never accidentally right. `forms.spec.ts` pins both
+ * halves.
+ *
+ * A per-org `entitlements.formsPerHost` override still resolves ahead of this,
+ * so a contract can raise or lower it for one org without moving the ceiling
+ * everyone else is measured against.
+ */
+export declare const FORMS_PER_HOST_CEILING = 500;
+/**
+ * Is this quota value "no cap"? (AGL-2482; AGL-2223 is the same class.)
+ *
+ * WHY A PREDICATE AND NOT `x === UNLIMITED`. `UNLIMITED` is
+ * `Number.POSITIVE_INFINITY`, and `JSON.stringify(Infinity)` is **`null`** —
+ * so the moment an entitlement crosses a route boundary the sentinel is gone
+ * and `=== UNLIMITED` is false for a plan that really is uncapped. Worse, the
+ * client then reads `Number(null)`, which is `0`, and `Number.isFinite(0)` is
+ * TRUE: the value sails through every guard written to reject a payload that
+ * cannot state the terms, and the console renders a cap of zero for the most
+ * expensive plan on the price list.
+ *
+ * So: `Infinity`, `null`, `undefined` and `NaN` all read as unlimited here.
+ *
+ * THIS IS A BACKSTOP, NOT THE FIX. `null` on the wire genuinely cannot
+ * distinguish "unlimited" from "the field is missing", and answering
+ * "unlimited" for a missing field is the permissive direction — the same
+ * shape as `checkQuota(undefined)` resolving to Free. A route that serialises
+ * a quota must therefore send a FINITE number plus an explicit boolean flag
+ * (see `/api/billing/storage-overage`), and the client must rebuild the
+ * sentinel from the flag with `restoreQuotaLimit` before it does arithmetic.
+ * This predicate exists so that a surface which has not been given the flag
+ * still renders "Unlimited" instead of `0`, `null` or `Infinity`.
+ */
+export declare function isUnlimitedQuota(limit: number | null | undefined): boolean;
+/**
+ * A quota cap, written the way every surface in the console must write it:
+ * `Unlimited` for an uncapped plan, the number otherwise.
+ *
+ * ONE implementation on purpose. Six surfaces had grown their own copy of the
+ * `limit === UNLIMITED ? 'Unlimited' : String(limit)` line and a seventh
+ * category — the ones that interpolated the raw number — shipped
+ * "Every site can run null registers on your current plan" and
+ * "Screen limit reached (Infinity)" to customers.
+ *
+ * @param limit The cap. Non-finite, `null` and `undefined` are unlimited.
+ * @param unit Appended to a finite number only — `MB`, `registers`. Never
+ *   appended to `Unlimited`, because "Unlimited MB" reads as a typo.
+ */
+export declare function formatQuotaLimit(limit: number | null | undefined, unit?: string): string;
+/**
+ * Rebuild the `UNLIMITED` sentinel a JSON round-trip flattened, from the
+ * explicit flag the route sent alongside the number.
+ *
+ * The client half of the wire contract. Once this has run, every comparison
+ * downstream is ordinary arithmetic that happens to be correct: `used >
+ * Infinity` is false, `Math.max(0, used - Infinity)` is `0`, and nothing has
+ * to remember that this particular number might be a `null` in disguise.
+ *
+ * That mattered more than the display did. `1 > null` is **true**, so a site
+ * on an unlimited plan was reported "1 over the limit" while the readout
+ * beside it said `1/∞` — a false limit warning on a plan that has no limit.
+ *
+ * @param value The finite number the route sent (or the `null` it sent for a
+ *   pre-fix payload).
+ * @param unlimited The route's explicit flag. `undefined` means the route has
+ *   not been taught to send one, and then `value` decides — non-finite reads
+ *   as unlimited, which is the `isUnlimitedQuota` backstop.
+ */
+export declare function restoreQuotaLimit(value: number | null | undefined, unlimited?: boolean): number;
+/**
+ * Campaign emails an Enterprise agreement includes per month, before the
+ * contract says otherwise.
+ *
+ * ## Why the one Enterprise quota that is a number
+ *
+ * Every other Enterprise band is `UNLIMITED` because the thing behind it is
+ * infrastructure we already meter and price into the deal — storage, page
+ * views, seats. Email is not that. It is a per-message charge from a third
+ * party, so an unbounded allowance is an unbounded liability with no meter
+ * underneath it and no ceiling a negotiation ever had to name.
+ *
+ * `UNLIMITED` was also unrepresentable off-process. It is
+ * `Number.POSITIVE_INFINITY`, `JSON.stringify(Infinity)` is `null`, and
+ * `Number(null)` is `0` — so the most expensive plan on the price list
+ * serialised to a cap of ZERO through any route that did not also send the
+ * explicit flag `restoreQuotaLimit` rebuilds from. A finite number crosses
+ * the wire as itself.
+ *
+ * ## Why this number
+ *
+ * Twice Agency's band — the rule every Enterprise fallback follows since the
+ * 2026-09-07 pricing decision (see the `enterprise` row of
+ * `PLAN_ENTITLEMENTS`) — and inside what the sending platform can actually
+ * deliver to one workspace with room to spare. At the shipped constants a
+ * workspace's share is 500 messages an hour and a projected month is 720
+ * hours, so 360,000 is the ceiling nothing can exceed however it is sold.
+ * 260,000 spends 520 of those 720 hours, leaving the rest for bursts, retries
+ * and domain warm-up — `email-ceiling-dimensioning.spec.ts` holds that
+ * relation, and holds the platform rate still so the gap cannot be closed by
+ * quietly raising it.
+ *
+ * Selling more than that would be selling mail that cannot leave the
+ * building: the hourly ceiling DEFERS rather than refuses, so the excess does
+ * not bounce, it simply never sends.
+ *
+ * ## It is a DEFAULT, and a contract raises it
+ *
+ * `resolveOrgEntitlements` applies a per-org `entitlements.emailSendsPerMonth`
+ * override ahead of this, so a deal that buys more email buys it on that org
+ * without moving the figure every other agreement is measured against — the
+ * same mechanism every numeric entitlement uses.
+ */
+export declare const ENTERPRISE_EMAIL_SENDS_PER_MONTH = 260000;
+/**
+ * Plan → default entitlements. Versioned with the app so pricing changes are
+ * code-reviewed; per-org overrides live on `org.entitlements` and win
+ * key-by-key. Tier table aligned to the Tenant Billing & SaaS Plans proposal
+ * (AGL-67, 2026-07-07): storage-per-host is media storage; the published
+ * total-site-size cap it used to exceed by design was retired in AGL-2133.
+ * Metered costs are passed through
+ * from Firebase/Vercel at cost × 1.30 separately (AGL-41).
+ */
+/** Legacy host-keyed dataset overrides resolved into org keys (AGL-240). */
+type LegacyEntitlementKeys = 'datasetsPerHost' | 'maxDatasetsPerHost';
+/**
+ * Keys `OrgEntitlements` still carries so stored documents type-check, but
+ * that no plan declares and nothing resolves (AGL-2133). Kept as a named type
+ * rather than folded into `LegacyEntitlementKeys`: legacy keys are resolved
+ * INTO their replacements, retired ones are dropped, and conflating the two
+ * would eventually resolve a retired value into something.
+ *
+ * `RETIRED_ENTITLEMENT_KEYS` is the runtime half and must list the same keys.
+ */
+type RetiredEntitlementKeys = 'totalSiteSizeMb';
+/**
+ * Keys stored under `entitlements` that are not quotas at all (AGL-3034): the
+ * staff plan comp rides the same staff-owned map, and is read through
+ * `readOrgPlanComp` rather than resolved into a limit.
+ */
+type NonQuotaEntitlementKeys = 'planComp';
+/**
+ * Fully-resolved entitlements: every LIVE CORE quota present, the core
+ * features complete, and whatever the plugins declared beside them.
+ *
+ * `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.
+ *
+ * They join in their MAPPED form (`PluginOrgQuotas`, `PluginOrgFeatures`)
+ * because an intersection with a bare interface has no implicit string index
+ * signature, and readers that hand these objects to a `Record<string, …>`
+ * parameter — the quota line, the digest gates — would stop compiling for a
+ * plugin half that is empty.
+ */
+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`
+ * (AGL-1118), which is priced per deal and provisioned by staff (AGL-1110).
+ * Any surface that offers plans for sale (the console plan-cards grid, the
+ * marketing pricing table, the plan-change dialog) MUST iterate this rather
+ * than `Object.keys(PLAN_ENTITLEMENTS)`, so a custom-priced tier can never
+ * show a self-serve Upgrade button or a $0 headline price.
+ */
+export declare const SELF_SERVE_PLANS: OrgPlan[];
+/**
+ * Whether the plan has no list price and is quoted per deal (AGL-1118).
+ * `PLAN_PRICING` still carries a row for it — the record is exhaustive by
+ * type — but every figure there is 0/null and means "no list price", NOT
+ * "free". Revenue for such an org comes from `subscription.customMonthlyUsd`.
+ */
+export declare function isCustomPricedPlan(plan: OrgPlan | undefined | null): boolean;
+/** Human plan names — the ONE source every plan badge/label reads. */
+export declare const PLAN_LABELS: Record<OrgPlan, string>;
+/**
+ * Event Calendar add-on (AGL-145): first-party, Aglyn-supported, $9/mo
+ * **per organization** — cost×1.3 floor honored (mostly Firestore reads).
+ * Enabled via the `eventCalendar` entitlement override at purchase.
+ *
+ * NOT per host, despite what this comment said until AGL-1279. AGL-145
+ * shipped it per host; AGL-526 then made add-ons self-serve and capped this
+ * one at `return 1` in `app/api/billing/addons/route.ts`, and
+ * `resolveOrgEntitlements` flips a single org-level `features.eventCalendar`
+ * boolean from any quantity >= 1. One purchase covers every host in the org.
+ * The marketing copy on /pricing is written against that behaviour.
+ */
+export declare const EVENT_CALENDAR_ADDON_MONTHLY_USD = 9;
+/**
+ * POS Pro register add-on (AGL-329): $89/mo per extra register/location
+ * (Shopify POS Pro parity). Purchased add-ons land as a per-org
+ * `posRegisters` entitlement override, which
+ * `resolveOrgEntitlements` already applies over the plan default.
+ */
+export declare const POS_REGISTER_ADDON_MONTHLY_USD = 89;
+/**
+ * The Aglyn AI add-on's credit band (AGL-2896): the credits a month the
+ * add-on ADDS to the plan's `assistCreditsPerMonth` when
+ * `seatAddons.aiAddon` is set. One pool and one meter — the add-on widens
+ * the band the assist meter already draws on rather than opening a second
+ * one, so `resolveAssistCreditBudget`, the overage price and the hard-cap
+ * switch all see one number.
+ *
+ * ## Sized against the add-on's own price
+ *
+ * A credit is `ASSIST_CREDIT_COST_USD` of provider spend, so each band is a
+ * cost figure: 1,000 credits are $1.00. Every band here costs at most 50% of
+ * `PlanPricing.aiAddonMonthlyUsd` at full consumption — Starter $4 of $9,
+ * Pro $9 of $19, Business $19 of $39, Scale $34 of $69, Advanced $49 of
+ * $99, Agency $149 of $299 — which is the same line-margin floor
+ * (`ASSIST_CREDIT_MIN_MARGIN_PCT`) every retail assist rate clears.
+ * `tier-margin-floor.spec.ts` holds the whole tier non-negative with the
+ * add-on band at 100% and the add-on's revenue counted, and pins each band's
+ * share of its price.
+ *
+ * ## Free and Enterprise
+ *
+ * Free is 0: the plan sells no add-on (`aiAddonMonthlyUsd` is null), so a
+ * quantity written onto a Free org adds nothing. Enterprise is finite at
+ * twice Agency's, the rule every Enterprise fallback follows since the
+ * 2026-09-07 decision (AGL-2654) — never `UNLIMITED`, for the reason
+ * `ENTERPRISE_ASSIST_CREDITS_PER_MONTH` gives: an unbounded band reads back
+ * as zero off the wire. Enterprise carries `aiGenerative` in the agreement
+ * and its price is null too, so this figure is what a contract that names
+ * the add-on starts from before its own number is written.
+ */
+export declare const AI_ADDON_CREDITS_PER_MONTH: Record<OrgPlan, number>;
+/**
+ * The generative add-on's name as a person sees it (AGL-2896): the brand,
+ * then "AI". Read from the platform brand by default and from the org's
+ * resolved `productName` where the surface has one, for the reason every
+ * rendered product name is: a self-host operator renames the product by
+ * configuration, and a white-label org must not see ours.
+ */
+export declare const aiAddonName: (brand?: string) => string;
+/**
+ * Purchase ceilings for the two add-on kinds that have NO per-plan hard max
+ * (AGL-1738). They live here, beside the bands and the resolver they bound,
+ * because they ARE the bound — and until now they were two private literals
+ * in `app/api/billing/addons/route.ts`, seventeen hundred lines and one
+ * project away from the `+` they cap.
+ *
+ * That distance is why AGL-1738 read `resolveOrgEntitlements` as unbounded
+ * and proposed a `maxPosRegistersPerHost` clamp. Do not add one. Seats and
+ * datasets clamp at `checkSeatQuota` / `checkDatasetQuota` because their
+ * plans genuinely refuse to sell past a band (`upgradeRequired` flips and
+ * the answer is a plan change). Registers and extra sites are sold flat
+ * instead: `addonMax()` will sell an org up to these quantities on ANY plan
+ * carrying the feature, so a band-shaped clamp in the resolver would take
+ * back registers the merchant is being invoiced $89/mo each for — the
+ * expensive direction of a wrong clamp, and the reason the add stays open.
+ *
+ * The self-serve route is the only path that writes `seatAddons` from a
+ * purchase, so these are the real ceilings: a plan's band plus at most
+ * `POS_REGISTERS_ADDON_MAX` registers, or plus `EXTRA_HOSTS_ADDON_MAX` sites.
+ * Any console surface that windows a head-count must clear the SUM, not the
+ * band (`registers-card.component.tsx` still windows at 25; AGL-1738).
+ */
+export declare const EXTRA_HOSTS_ADDON_MAX = 100;
+/** @see EXTRA_HOSTS_ADDON_MAX — the flat register ceiling, per org. */
+export declare const POS_REGISTERS_ADDON_MAX = 50;
+export interface PlanPricing {
+    /** Flat monthly base price in USD (month-to-month billing). */
+    basePriceMonthlyUsd: number;
+    /**
+     * Effective per-month price when billed annually (AGL-278): the
+     * Squarespace/Shopify-parity headline number. Charged as ×12 up front.
+     */
+    basePriceAnnualMonthlyUsd: number;
+    /**
+     * Monthly price per host beyond `hostLimit` (AGL-68); null when the plan
+     * cannot buy extra hosts.
+     *
+     * ## It is not a discount ladder, because what it GRANTS is not constant
+     *
+     * `storagePerHostMb` and `formSubmissionsPerMonth` are per-HOST
+     * entitlements, and `meteredIncludedAllowance` expands both by `hostLimit`
+     * — so an extra host does not add a slot, it adds that tier's per-host
+     * bands to the org's included allowance. A tier that includes more per host
+     * therefore hands over more capacity for the same purchase.
+     *
+     * A ladder that stepped down with the tier inverted that: the tiers
+     * granting the most charged the least, and the two largest ran at 24% and
+     * 6% margin on a line sold as an add-on.
+     *
+     * ## It sits above every rung's step rate, or the rungs stop meaning anything
+     *
+     * The shape is a flat $20 on every plan, Starter included. A flat $8 above
+     * Starter, with no cap on how many hosts a plan may add, priced the
+     * marginal host below every step of the base ladder, which costs $8.57 to
+     * $16 per included host on annual prices and $12 to $22 on monthly: ten
+     * Business sites plus fifteen extras came to $219 against Advanced's $299,
+     * and plus ninety extras to $819 against Agency's $1,049, so on host count
+     * alone no plan was ever worth upgrading to. $20 clears the steepest step on
+     * both intervals: extra hosts are how a plan takes a few more sites, and
+     * the next plan is how it takes many more (2026-09-20).
+     */
+    extraHostMonthlyUsd: number | null;
+    /**
+     * Monthly price per org-manager seat beyond `managersPerOrg`
+     * (AGL-112); null when the plan cannot buy extra seats.
+     */
+    extraSeatMonthlyUsd: number | null;
+    /**
+     * Monthly price per site-collaborator seat beyond `membersPerHost`
+     * (AGL-112, renamed AGL-888): per-site console collaborators
+     * (`hosts/{id}/members`, viewer/editor/admin) — never end-user member
+     * accounts, which are unlimited on every plan. Null when the plan sells
+     * no extra seats. Persisted/external keys keep the legacy "member"
+     * spelling (`seatAddons.members`, `STRIPE_PRICE_*_EXTRA_MEMBER`).
+     */
+    extraCollaboratorMonthlyUsd: number | null;
+    /**
+     * Monthly price per org dataset beyond `datasetsPerOrg` (AGL-132/240);
+     * null when the plan cannot buy extra datasets.
+     */
+    extraDatasetMonthlyUsd: number | null;
+    /**
+     * Retail overage per GB-month of dataset storage beyond
+     * `dataStorageMbPerOrg` (AGL-240); null when the plan hard-blocks at the
+     * included size instead of metering.
+     *
+     * ⛔ **NOT the metered storage pass-through.** `/pricing` publishes two
+     * per-GB-month figures and they are different products: the pass-through
+     * is `METERED_BILLED_RATES_USD.storagePerGbMonth` at $0.0338, media bytes
+     * on GCS at cost + 30%; this is Firestore-backed DATASET bytes, an order
+     * of magnitude pricier to store, sold as a retail line. Confusing the two
+     * is the easiest way to corrupt a correct price, in either direction.
+     *
+     * Priced against `ORG_COGS_UNIT_RATES_USD.dataStoragePerGbMonth` ($0.18)
+     * at the 50% retail floor. It sat at $0.25 — a 28% line margin, close
+     * enough to the pass-through's 23% that the two looked like the same kind
+     * of number while being sold as opposites.
+     */
+    extraDataGbMonthlyUsd: number | null;
+    /**
+     * Metered overage per 1,000 customer REST API requests beyond
+     * `apiRequestsPerMonth` (AGL-634). API access starts at Business and every
+     * tier above it carries it, so Free, Starter and Pro are null (no API to
+     * meter).
+     */
+    extraApiRequestsUsdPer1k: number | null;
+    /**
+     * Retail overage per 1,000 Aglyn Assist credits beyond
+     * `assistCreditsPerMonth`.
+     *
+     * ## The rate is a multiplier on our own cost, and reads as one
+     *
+     * A credit is defined as a fixed quantity of provider spend
+     * (`ASSIST_CREDIT_COST_USD`), so 1,000 credits cost us exactly $1.00 and
+     * this figure IS the multiplier: $3.00 per 1,000 is cost x3, $2.00 is
+     * cost x2. That is the property worth having, because the alternative —
+     * a rate per message — prices a question and a generated screen the same
+     * when they differ by two orders of magnitude.
+     *
+     * ## The floor, and why the ladder stops descending
+     *
+     * Every retail line carries at least a 50% margin
+     * (`ASSIST_CREDIT_MIN_MARGIN_PCT`), which at $1.00 of cost per 1,000 is a
+     * floor of $2.00 per 1,000 — cost x2. The ladder steps down with the tier
+     * the way contacts and API requests do, and since AGL-3203 it begins on
+     * Starter: $3.00 on Starter and Pro together, then $2.75 -> $2.50 ->
+     * $2.25, stopping at the floor on Agency rather than running past it.
+     * Starter joins at Pro's figure rather than stepping above it, because the
+     * ladder descends with the tier and Starter is the rung below Pro.
+     *
+     * ## Where it is null, and why that is not "free overage"
+     *
+     * Null on Free because its band is a WALL by decision (AGL-2925): the
+     * 300-credit taste refuses at 100% with nothing sold past it, and a rate
+     * here would be a charge on a plan that must never produce one. Null on
+     * Enterprise, where every rate is the "not for sale" sentinel and the
+     * terms are contractual.
+     *
+     * Those two are the only nulls. Every self-serve PAID plan now includes a
+     * positive assist band and therefore carries a rate, Starter included —
+     * a finite band with no rate beside it is usage past a bound that is
+     * silently free, which `plan-entitlements.spec.ts` forbids.
+     *
+     * ## What the rate decides at the gate (AGL-2653)
+     *
+     * A plan WITH a rate sells past its band by default: `reserveAssistMessage`
+     * keeps reserving and `report-usage` bills the excess here, unless the org
+     * has switched on `assistOverage.hardCap` to be refused at the band
+     * instead. A plan with NO rate has nothing to sell the excess at, so its
+     * band stays the wall it always was, switch or no switch — see
+     * `assistBandRefuses`. Unlike email, a null here strands nothing: there is
+     * no unrefusable assist traffic to absorb.
+     */
+    extraAssistCreditsUsdPer1k: number | null;
+    /**
+     * The Aglyn AI add-on, flat per organization per month (AGL-2896); null
+     * when the plan does not sell it.
+     *
+     * ## What it buys
+     *
+     * `features.aiGenerative` — generative building and automation, the rung
+     * no self-serve tier includes — plus `AI_ADDON_CREDITS_PER_MONTH[plan]`
+     * added to the plan's assist band. It also switches `aiAssist` on, so on
+     * Starter it brings the two rungs the tier does not carry — the copy
+     * assist and the generative one — on top of the 750 credits the plan
+     * already includes (AGL-3203). It ADDS to that band; it does not replace
+     * it, on Starter or on any tier.
+     *
+     * ## Where the ladder sits
+     *
+     * Priced as an uplift on the plan rather than on its own cost: the field
+     * charges roughly 30% of the base price for an AI tier (Zylo's 2025
+     * survey puts the AI uplift at 20–37% across SaaS; aissist.io's benchmark
+     * and the Framer, Webflow and HubSpot credit add-ons sit in the same
+     * band), and the share DESCENDS with the tier — 36% of Starter's $25, 34%
+     * of Pro's, 28% of Business's, 28% of Scale's, 25% of Advanced's, 23% of
+     * Agency's — because the larger the plan the more of its price is already
+     * carrying the bands the assistant builds against.
+     *
+     * Annual is x12 of this with no discount, as every other add-on is
+     * (`orgListPriceMonthlyUsd`). The band it funds costs at most 50% of it in
+     * provider spend, the `ASSIST_CREDIT_MIN_MARGIN_PCT` floor every retail
+     * assist figure holds.
+     *
+     * Null on Free, which sells no add-on of any kind, and on Enterprise,
+     * where every figure is the "not for sale" sentinel and generative
+     * building is in the agreement.
+     */
+    aiAddonMonthlyUsd: number | null;
+    /**
+     * Metered overage per 1,000 CRM records beyond `contactsPerHost` (AGL-890,
+     * widened to contacts + companies + deals in AGL-2611): audience bands,
+     * Ghost-style. Paid plans meter (a growing audience is never dropped);
+     * free is null and hard-bands at the included count. The key keeps its
+     * name because it is a persisted Stripe-side vocabulary and a locked
+     * price; the band it prices was widened, the rate was not.
+     */
+    extraContactsUsdPer1k: number | null;
+    /**
+     * Retail overage per 1,000 emails beyond `emailSendsPerMonth`.
+     *
+     * ## What it prices, which is not what the cap refuses
+     *
+     * The cap is enforced against CAMPAIGN sends alone and refuses them at the
+     * band — a campaign is discretionary, so the plan is allowed to say no.
+     * Transactional mail is never refused at any tier, so an org finishes the
+     * month above its band whenever receipts, invites, booking reminders and
+     * workflow notifications carry it there. That excess is real provider spend
+     * that no gate could have stopped, and this is the rate it bills at.
+     *
+     * ## Retail, NOT the infrastructure pass-through
+     *
+     * `meteredInfraPassThrough` covers exactly three meters — storage, page
+     * views, form submissions — and the published term for those is "at cost +
+     * 30%", which makes the figure in `METERED_BILLED_RATES_USD` the claim
+     * itself. Email is not in that set and this rate is not derived from
+     * `METERED_MARKUP`: it is a price, set beside `extraContactsUsdPer1k` and
+     * `extraApiRequestsUsdPer1k`, and it descends with the tier the way both of
+     * those do. Describing it as "at cost" anywhere would make the pass-through
+     * sentence false about three meters that really are.
+     *
+     * Our own per-email cost is `ORG_COGS_UNIT_RATES_USD.perEmailSend`, and it
+     * is a cost-model input rather than anything a customer is quoted.
+     *
+     * ## The floor, and why the ladder stops descending
+     *
+     * Every retail line must carry at least a 50% margin, and at a cost of
+     * $0.90 per 1,000 that floor is $1.80. The ladder still steps down with
+     * volume the way contacts and API requests do — a larger plan pays less per
+     * message — it simply stops at the floor instead of running past it, which
+     * is what the contacts ladder did when it reached $0.25 against a $0.20
+     * cost.
+     *
+     * Null wherever the plan has no email band to be over, and null on
+     * enterprise, where every rate is the "not for sale" sentinel and the terms
+     * are contractual. Free and Starter are the two banded at 0: campaign email
+     * begins at Pro, and `emailSendsOverage` yields 0 against a non-positive
+     * band, so a rate on either would advertise a fee that can never be
+     * computed — the same defect as a rate beside an UNLIMITED band.
+     *
+     * Every tier whose band is POSITIVE carries one, Pro upward. A finite band
+     * with no rate is silently free past the band, and since transactional mail
+     * cannot be refused at any tier that would be unbounded absorbed spend
+     * rather than "no overage".
+     *
+     * The Starter null therefore leaves that tier's transactional mail — the
+     * only mail it can send — unbilled at any volume. Bounded in practice by
+     * `hostLimit: 1` and a 1,000-contact CRM, and the alternative prices a
+     * password reset, but it is the one place this axis absorbs cost by design.
+     */
+    extraEmailSendsUsdPer1k: number | null;
+    /**
+     * Whether the plan carries the metered infrastructure pass-through
+     * (AGL-41, turned on in AGL-1280): media storage, bandwidth (page views)
+     * and form submissions BEYOND the plan's included bands, billed at
+     * cost × `METERED_MARKUP`. The rates are platform-wide, not per-plan —
+     * this flag only says whether a plan is subject to them at all, which is
+     * why it is a boolean rather than another `extra*` rate.
+     *
+     * Free is `false` because there is no subscription to hang a metered item
+     * on; its bands stay hard caps, which is also what stops "metered means
+     * you're never cut off" from becoming unlimited free capacity.
+     *
+     * Enterprise is `false` because every band it has is `UNLIMITED` and its
+     * price is negotiated (`isCustomPricedPlan`) — there is no published
+     * pass-through to apply, and an overage can never arise anyway.
+     */
+    meteredInfraPassThrough: boolean;
+}
+/**
+ * Flat subscription pricing per tier (AGL-68). Kept beside the entitlements
+ * so price changes ride the same review path; Stripe price ids map to plans
+ * via `STRIPE_PRICE_*` env vars on the billing API routes.
+ */
+export declare const PLAN_PRICING: Record<OrgPlan, PlanPricing>;
+/**
+ * The prices the org's usage and add-ons are sold at (AGL-3034): its
+ * effective plan's row, or that row with nothing for sale when a staff comp
+ * is what grants the plan — see `compPricing`.
+ *
+ * EVERY reader that decides whether something past a band is sold, or what a
+ * purchasable seat costs, reads this rather than indexing `PLAN_PRICING` by
+ * the effective plan. Indexing it directly is how a comp would be quoted a
+ * rate nobody can be invoiced at.
+ */
+export declare function resolvePlanPricing(org: Partial<AglynOrgBilling> | null | undefined): PlanPricing;
+/**
+ * What the org's subscription contributes to deciding its plan (AGL-3034).
+ *
+ * - `live` — a status is mirrored and it is not one this module reads as
+ *   dead. The subscription decides the plan. `past_due` is live (dunning
+ *   grace), and so is a status this build does not recognize, for the reason
+ *   `DEAD_SUBSCRIPTION_STATUSES` gives: an unrecognized status must not take
+ *   away what a paying workspace bought, and handing the plan to a comp would
+ *   do exactly that.
+ * - `dead` — the status is in `DEAD_SUBSCRIPTION_STATUSES`. A stored paid
+ *   plan grants nothing (AGL-247).
+ * - `none` — no status at all: the workspace has never been subscribed, or
+ *   predates the mirror.
+ *
+ * `dead` and `none` are the only states a staff comp applies in.
+ */
+export type OrgSubscriptionState = 'live' | 'dead' | 'none';
+export declare function orgSubscriptionState(org: Partial<AglynOrgBilling> | null | undefined): OrgSubscriptionState;
+/** A staff plan comp, as every reader receives it (AGL-3034). */
+export interface ResolvedOrgPlanComp {
+    /** The plan granted — always a paid plan this build knows. */
+    plan: OrgPlan;
+    /**
+     * Whether the comp lifts every cap (AGL-3049) — see `isUncappedPlanComp`.
+     * `false` for anything but a stored `true`.
+     */
+    uncapped: boolean;
+    /** `null` when the stored code is not one of the override set's. */
+    reason: OrgOverrideReasonCode | null;
+    note: string | null;
+    grantedBy: string | null;
+    /** ISO instant, or `null` when the stored stamp does not read back. */
+    grantedAt: string | null;
+}
+/**
+ * The org's STORED comp (`entitlements.planComp`), whether or not it is in
+ * force, or `null` when there is none (AGL-3034).
+ *
+ * Strict about the one field that grants anything: `plan` must be a paid plan
+ * this build knows. A comp of `free` grants nothing and an unknown plan could
+ * grant anything, so both read as no comp at all — the org then resolves
+ * exactly as it would without one, which is the direction a malformed grant
+ * must fail in. The descriptive fields are narrowed and never block the plan:
+ * a comp whose note or stamp did not read back is still the comp staff wrote.
+ *
+ * `uncapped` is strict in the same direction (AGL-3049): it lifts every cap,
+ * so only a literal `true` does. A `"true"`, a `1` or a map written by hand
+ * reads as a capped comp — the plan still stands, and its bands stay walls.
+ */
+export declare function readOrgPlanComp(org: Partial<AglynOrgBilling> | null | undefined): ResolvedOrgPlanComp | null;
+/**
+ * The comp IN FORCE: the stored comp while no subscription decides the plan,
+ * and `null` otherwise (AGL-3034).
+ *
+ * A live subscription always wins. The comp is not removed by one starting —
+ * nothing but the staff override writes it — so it waits, dormant, and
+ * applies again if that subscription ends. Staff views say so.
+ */
+export declare function resolvePlanComp(org: Partial<AglynOrgBilling> | null | undefined): ResolvedOrgPlanComp | null;
+/**
+ * Whether an UNCAPPED comp is in force (AGL-3049): every band and quota the
+ * org resolves reads as `UNLIMITED`, whatever its plan row and its per-org
+ * overrides say — see `withEveryCapLifted`.
+ *
+ * In force only, like the comp itself. A live subscription decides the plan
+ * and its bands, so a dormant uncapped comp lifts nothing, and a canceled one
+ * lifts every cap again the moment the subscription ends.
+ *
+ * What it does NOT lift is anything that is not a plan band: the fee
+ * percentages (`PRICE_ENTITLEMENT_KEYS`) are prices, and the platform's own
+ * guards live outside the entitlements map and are not the plan's to give
+ * away — the form-submission and bandwidth abuse ceilings (which read an
+ * unlimited band as `FORM_ABUSE_CEILING_UNLIMITED` and
+ * `BANDWIDTH_ABUSE_CEILING_UNLIMITED`), the flat per-site caps on webhooks,
+ * actions and collection entries, the email send pacing, the assist runaway
+ * message cap, an operator's explicit spend ceiling, and staff pauses and
+ * lockdowns. It never sells anything either: the pricing stays the comp's,
+ * with every rate withheld, so an unbounded band is still billed nothing.
+ *
+ * The lifted value is `UNLIMITED` in process and nowhere else. Every route
+ * that sends a band off-process sends a finite number with an explicit flag,
+ * or `null` with a documented meaning, because `JSON.stringify(Infinity)` is
+ * `null` — and the comp itself is stored and sent as a boolean.
+ */
+export declare function isUncappedPlanComp(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * What decided the org's effective plan (AGL-3034):
+ *
+ * - `subscription` — a live subscription; the stored plan is its mirror.
+ * - `comp`         — a staff comp, on a dead or absent subscription.
+ * - `lapsed`       — a dead subscription and no comp: Free.
+ * - `stored-plan`  — no subscription and no comp, and a paid plan stored
+ *                    directly, the way staff granted plans before comps.
+ * - `no-plan`      — no subscription, no comp, no paid plan: Free.
+ */
+export type OrgPlanDecidedBy = 'subscription' | 'comp' | 'lapsed' | 'stored-plan' | 'no-plan';
+/** Everything a staff surface needs to say how an org's plan resolves. */
+export interface OrgPlanDescription {
+    effectivePlan: OrgPlan;
+    /** `org.plan` when it names a plan this build knows, else `null`. */
+    storedPlan: OrgPlan | null;
+    subscriptionStatus: string | null;
+    subscription: OrgSubscriptionState;
+    /** The STORED comp — in force or dormant; see `compInForce`. */
+    comp: ResolvedOrgPlanComp | null;
+    compInForce: boolean;
+    /**
+     * An uncapped comp is IN FORCE, so every band reads as unlimited
+     * (AGL-3049). A dormant uncapped comp is `false` here and `comp.uncapped`.
+     */
+    uncapped: boolean;
+    decidedBy: OrgPlanDecidedBy;
+}
+/**
+ * How a staff chip names a stored comp (AGL-3049): the plan, then whether it
+ * is uncapped and whether a live subscription holds it dormant —
+ * `Enterprise (uncapped)`, `Pro (dormant)`, `Agency (uncapped, dormant)`.
+ *
+ * One reading of the terms, so the orgs list, the org summary and the
+ * override dialog cannot describe the same grant differently. `name` is the
+ * plan as the surface already writes plans: the label by default, the stored
+ * key on the surfaces whose other chips show keys.
+ */
+export declare function planCompLabel(comp: Pick<ResolvedOrgPlanComp, 'plan' | 'uncapped'>, inForce: boolean, name?: string): string;
+/**
+ * A stored comp as a sentence names it (AGL-3049): `uncapped Enterprise
+ * comp`, `Pro comp`. Shared by the plan description and the override route's
+ * account of what it changed.
+ */
+export declare function planCompPhrase(comp: Pick<ResolvedOrgPlanComp, 'plan' | 'uncapped'>): string;
+/**
+ * The org's plan, described rather than only resolved (AGL-3034) — the ONE
+ * reading the staff override route answers with and the staff override
+ * dialog renders, so the response and the dialog cannot tell staff two
+ * different stories about the same document.
+ */
+export declare function describeOrgPlan(org: Partial<AglynOrgBilling> | null | undefined): OrgPlanDescription;
+/**
+ * One sentence for staff saying what decides the plan and what a plan set in
+ * the override dialog would do (AGL-3034). Shared by the route's response and
+ * the dialog, for the reason `describeOrgPlan` is.
+ *
+ * A comp in force also says whether its bands are walls or lifted
+ * (AGL-3049), because that is the question a comped workspace refused at a
+ * band brings to staff.
+ */
+export declare function orgPlanDescriptionSentence(description: OrgPlanDescription): string;
+/**
+ * Whether the org is actually being charged for its plan right now.
+ *
+ * This is deliberately stricter than `resolveEffectivePlan`: entitlement
+ * asks "what does this org get", revenue asks "who is paying us". A staff
+ * plan override (`/admin/orgs`) never writes `subscription` — before AGL-3034
+ * it wrote `plan`, and now it writes a comp — so a comped or dark-launched
+ * org resolves to a paid plan while billing nothing, and counting it inflates
+ * MRR (AGL-925). No subscription mirror means no Stripe subscription means no
+ * revenue.
+ *
+ * A comp never reaches this answer: it reads the stored `plan` and the
+ * status, never `entitlements.planComp`, and a comp is only ever in force
+ * where the status is dead or absent — both of which answer false here.
+ *
+ * `past_due` counts: Stripe is still retrying and the plan is still owed.
+ */
+export declare function isBillingSubscription(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * The org's monthly LIST price in USD — plan base plus every purchased add-on
+ * (manager/collaborator seats, datasets, extra hosts, POS registers, Event
+ * Calendar), BEFORE any applied discount, and 0 for anyone not actually
+ * billing. This is the sticker price the plan + add-ons would bill at.
+ *
+ * Annual subscriptions contribute their per-month equivalent
+ * (`basePriceAnnualMonthlyUsd`), not the month-to-month price, so a mixed
+ * book does not read high by the size of the annual discount. Add-ons bill
+ * per-month (annual variants are ×12 with no discount), so each contributes
+ * its monthly price on either interval.
+ *
+ * Pricing-v3 fix (2026-07): previously omitted the host, POS-register, and
+ * Event-Calendar add-ons, understating the total for every org carrying them.
+ *
+ * AGL-1105: split out of `orgMonthlyRevenueUsd`, which now subtracts an
+ * applied per-org discount on top of this. Callers wanting the pre-discount
+ * sticker (the margin guardrail, a "what would this bill at" quote) use this;
+ * callers wanting the actual money collected use `orgMonthlyRevenueUsd`.
+ */
+export declare function orgListPriceMonthlyUsd(org: Partial<AglynOrgBilling> | null | undefined): number;
+/**
+ * How many Aglyn AI add-ons a purchase map counts as: 0 or 1 (AGL-2896).
+ * The add-on is org-wide like Event Calendar, so a quantity above one — a
+ * hand edit, a doubled webhook item — is one purchase, and a non-number,
+ * `NaN` or a negative is none.
+ */
+export declare function aiAddonUnits(addons: OrgSeatAddons | null | undefined): 0 | 1;
+/**
+ * A list price net of a discount (AGL-1105). Percentage discounts scale the
+ * whole bill; fixed discounts subtract a flat USD amount. Never below 0, and
+ * a percentage is clamped to 0–100. Prefers `percentOff` when both are
+ * somehow set (Stripe coupons carry only one). Rounds to whole cents.
+ */
+export declare function applyDiscountUsd(listPriceUsd: number, discount: Pick<OrgDiscount, 'percentOff' | 'amountOffUsd'> | null | undefined): number;
+/**
+ * Whether an org should read as **"Enterprise"** everywhere the plan is shown.
+ * Three ways to qualify:
+ *  - **`plan === 'enterprise'`** — the real plan (AGL-1118). This is the path
+ *    every new enterprise org takes, and the only one that also grants
+ *    Enterprise *entitlements*; the two below are display-only overlays on a
+ *    lower base plan;
+ *  - a billing org on a **negotiated custom price** (`customMonthlyUsd > 0`) —
+ *    a paying enterprise deal still parked on its pre-AGL-1118 base plan; or
+ *  - an explicit **`org.enterprise`** marker — a *comped* enterprise account,
+ *    100%-discounted so it collects $0 while infra cost is still metered.
+ *
+ * ⚠️ This function answers ONE question — "does this org read as Enterprise" —
+ * and it is not the same question as "what does this org get". Only the first
+ * bullet grants anything: `resolveEffectivePlan` reads `org.plan` and nothing
+ * else, so `org.enterprise` and `customMonthlyUsd` are read NOWHERE but here.
+ * A comped or custom-priced org resolves its BASE plan's entitlements, and
+ * gets Enterprise capability through a per-org `entitlements` override — see
+ * `ssoEnabled`, whose docblock calls that "how enterprise orgs provisioned
+ * before that plan existed still get it".
+ *
+ * This paragraph replaces a parenthetical claiming the comped marker carried
+ * "full Enterprise capability + SSO" (AGL-2297). It never did, and the billing
+ * page believed it: the Enterprise card ticked five entitlements against any
+ * org this function marked, so a comped org whose overrides granted SSO but
+ * not white-label was shown a green tick for full white-label while the
+ * branding card correctly refused it.
+ *
+ * The last two are kept for orgs provisioned before `enterprise` was a plan;
+ * migrating such an org to `plan: 'enterprise'` is the clean end state and
+ * changes nothing about how it reads here. List-priced orgs with none of the
+ * three are not enterprise.
+ *
+ * A staff comp in force names the plan instead of the stored one (AGL-3034),
+ * exactly as it does for entitlements: a workspace comped to Enterprise reads
+ * as Enterprise, and one comped to a lower tier does not read as Enterprise
+ * because of a plan stored before the comp. The explicit marker still counts.
+ */
+export declare function isEnterpriseOrg(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * Human label shown for `enterprise` in plan badges. Kept as a named export
+ * for the surfaces that label a custom-priced org whose stored `plan` is still
+ * a lower tier; a real `plan: 'enterprise'` org gets the same string from
+ * `PLAN_LABELS`.
+ */
+export declare const ENTERPRISE_PLAN_LABEL: string;
+/**
+ * The org's monthly recurring revenue in USD — its LIST price
+ * (`orgListPriceMonthlyUsd`) net of any applied per-org discount
+ * (`org.discount`, AGL-1105), and 0 for anyone who is not actually billing. A
+ * comped enterprise deal genuinely collects less, so the discount belongs in
+ * MRR; the pre-discount sticker stays available as `orgListPriceMonthlyUsd`.
+ */
+export declare function orgMonthlyRevenueUsd(org: Partial<AglynOrgBilling> | null | undefined): number;
+/**
+ * Stripe's standard processing fee on Aglyn's OWN subscription charges
+ * (AGL-1108) — 2.9% + $0.30 per charge. This is the fee Aglyn pays Stripe to
+ * collect a subscription; it is DISTINCT from the storefront platform fee
+ * (`transactionFee*Pct`, the Connect `application_fee`) that a seller's own
+ * Stripe pays on their storefront sales. Revenue/margin should be reasoned on
+ * the NET figure, not gross.
+ */
+export declare const STRIPE_PROCESSOR_FEE_PCT = 0.029;
+export declare const STRIPE_PROCESSOR_FEE_FIXED_USD = 0.3;
+/**
+ * A gross monthly USD amount net of Stripe's processing fee. Annual
+ * subscriptions are charged once per year, so the fixed 30¢ amortizes to
+ * $0.30/12 per month; monthly subscriptions pay it every month. Never
+ * returns below 0.
+ */
+export declare function netOfProcessorFee(grossMonthlyUsd: number, annual?: boolean): number;
+/**
+ * The org's monthly recurring revenue NET of Stripe's processing fee
+ * (AGL-1108) — what Aglyn actually keeps before infra COGS, and the correct
+ * base for margin/discount reasoning. Gross is `orgMonthlyRevenueUsd`; this
+ * subtracts ~2.9%+30¢, interval-aware. 0 for anyone not actually billing.
+ */
+export declare function orgNetMonthlyRevenueUsd(org: Partial<AglynOrgBilling> | null | undefined): number;
+/**
+ * Net-margin floor for discount underwriting (AGL-1105). Mirrors the
+ * Enterprise-Pricing-Calculator's ~75% gross-margin target: a discounted
+ * subscription should still keep ≥75% of its net (post-processor-fee) revenue
+ * after infrastructure COGS. Below the floor a discount is warned; well below
+ * it is blocked without explicit sign-off.
+ *
+ * WHAT THIS IS A FLOOR ON (AGL-1930): net revenue less INFRASTRUCTURE COGS,
+ * and nothing else. It is a contribution margin — see `MARGIN_SCOPE_NOTE`,
+ * which is the sentence every staff surface quoting this number has to print
+ * beside it.
+ *
+ * Read as a dollar guard it says: net revenue must be at least
+ * `cogs / (1 − floor)` = **4 × COGS**, and blocks below
+ * `cogs / (1 − floor + band)` ≈ **2.86 × COGS**. That restatement is the point
+ * of AGL-1930 — the percentage is scale-invariant, so the only thing that
+ * moves the real guard line in dollars is the COGS figure fed into it, and on
+ * production today that figure is `INFRA_COGS_PER_SITE_USD × sites` for
+ * **every** org (14 of 14 usage rollups across all 6 orgs, measured
+ * 2026-08-24). Re-tuning this constant therefore re-tunes a multiplier on the
+ * flat floor, not on anything measured. Calibrate the floor first.
+ */
+export declare const NET_MARGIN_FLOOR_PCT = 0.75;
+/**
+ * How far under the floor a discount may sit and still only WARN (AGL-1105).
+ * Within `[floor − band, floor)` staff see a caution; below `floor − band`
+ * the guardrail blocks unless overridden. 10 points, matching the
+ * calculator's soft/hard split.
+ */
+export declare const NET_MARGIN_WARN_BAND_PCT = 0.1;
+/**
+ * What every "net margin" figure in the staff console actually measures
+ * (AGL-1930).
+ *
+ * `checkDiscountMargin`, the enterprise quote card and the coupon badge all
+ * compute `(net revenue − infrastructure COGS) / net revenue`. Support,
+ * acquisition and overhead are not in the model anywhere — no meter records
+ * them and no constant estimates them — so "net margin 78%" is a CONTRIBUTION
+ * margin, and a staff member signing a deal on it is reading a ceiling, not a
+ * profit.
+ *
+ * One exported string rather than three literals: the three surfaces that
+ * print a margin already drifted apart once (AGL-1134), and a caveat that is
+ * true on one screen and absent on the next is worse than none.
+ */
+export declare const MARGIN_SCOPE_NOTE: string;
+/**
+ * The `ok` / `warn` / `block` band a cost-recovery margin falls in (AGL-1930).
+ *
+ * Extracted so `NET_MARGIN_FLOOR_PCT` and `NET_MARGIN_WARN_BAND_PCT` have ONE
+ * reader. The staff org page's enterprise quote card had `>= 0.75` and
+ * `>= 0.65` written into its JSX, so re-tuning either constant — the whole
+ * subject of AGL-1930 — would have moved the discount guardrail and left that
+ * card rating deals against the old numbers, silently and with money on the
+ * line.
+ */
+export declare function netMarginRating(marginPct: number): DiscountMarginRating;
+/**
+ * Per-site monthly infrastructure COGS in USD (AGL-1105). The
+ * Enterprise-Pricing-Calculator's ~$2/site figure — Firebase + Vercel at
+ * cost — charged against every host the org runs. The margin guardrail
+ * subtracts this from net revenue before rating a discount.
+ */
+export declare const INFRA_COGS_PER_SITE_USD = 2;
+/**
+ * Platform markup on passed-through infrastructure costs (AGL-41).
+ *
+ * DEFINED HERE, not in `apps/console/utils/usage-metering.ts`, and re-exported
+ * from there — the same move AGL-2155 made for `pageViewsFromBandwidthGb`, and
+ * for the same reason (AGL-2194). The published `/pricing` pass-through table
+ * states both a cost column and a "you pay (+30%)" column, and
+ * `tools/marketing/build-pricing-tables.mts` must generate both from code so
+ * `npm run check:pricing-tables` can fail on drift. That generator resolves no
+ * `@aglyn/*` path alias, so it can import `plan-entitlements.ts` and nothing
+ * under `apps/console`. A constant the published page depends on must live
+ * where the page's generator can read it.
+ *
+ * The console keeps importing it from `usage-metering` unchanged.
+ */
+export declare const METERED_MARKUP = 1.3;
+/**
+ * Monthly unit costs for the meters the rollup already records (AGL-1134).
+ *
+ * These are OUR costs, not prices — the org is billed at cost × 1.30
+ * (`METERED_MARKUP`, AGL-41). Storage/page-view/form rates match
+ * `METERED_UNIT_RATES_USD` in the metering module on purpose: two files
+ * disagreeing about what a page view costs is exactly the drift this function
+ * exists to remove.
+ *
+ * The three added here are operator-tuned estimates of the same quality as
+ * the existing three — Firestore-backed dataset storage is priced well above
+ * object storage because it is, and API requests and contacts are priced off
+ * the reads behind them. Treat every operator-tuned figure here as
+ * provisional until validated against a real Firebase + Vercel invoice month;
+ * AGL-1134 says so out loud rather than implying the numbers are derived.
+ * `perEmailSend` is the exception and carries its own basis below.
+ *
+ * ## Three of these are shared with the billed table. The rest are NOT.
+ *
+ * `storagePerGbMonth`, `perPageView` and `perFormSubmission` are the metered
+ * infrastructure pass-through, and the customer is charged those figures
+ * times `METERED_MARKUP`. They therefore appear in `METERED_UNIT_RATES_USD`
+ * as well, with identical values, and must be changed in both places at once.
+ *
+ * Everything else here is a cost-model input ONLY. `dataStoragePerGbMonth`,
+ * `perApiRequest`, `perContactMonth` and `perEmailSend` price what an org
+ * costs us; what an org is CHARGED on those axes is a retail rate on
+ * `PLAN_PRICING` that descends with the tier and is not derived from cost.
+ * Adding one of them to `METERED_UNIT_RATES_USD` would put it inside the
+ * "at cost + 30%" claim, which is true of exactly three meters.
+ *
+ * The first three were corrected 2026-08-09 (AGL-1280) — storage $0.03 →
+ * $0.026 and form submissions $0.0005 → $0.00005 — and `perPageView` was
+ * re-pegged 2026-09-09 (AGL-2711), from $0.0001 to $0.00016153846. All three
+ * MUST be changed here and in `METERED_UNIT_RATES_USD` together. See that
+ * table for each figure's basis; it is the one a customer is billed against,
+ * so it is the one that carries the working.
+ *
+ * The page-view basis is no longer an open gap. The rate priced a 627 KB page
+ * against one that measured far more for weeks; the weight reduction that was
+ * preferred over a re-peg has now shipped, the page was re-measured at
+ * 976.1 KB, and the rate is pegged to a 1012.8 KB basis that sits ABOVE it.
+ * `npm run check:page-view-rate` holds that peg, and now fails if the basis
+ * ever drops back below what a published page measures.
+ *
+ * Raising the two here raises measured COGS, which changes no guardrail
+ * verdict: `INFRA_COGS_PER_SITE_USD × sites` is the floor, and it still
+ * outruns measured cost by orders of magnitude at real traffic.
+ */
+export declare const ORG_COGS_UNIT_RATES_USD: {
+    storagePerGbMonth: number;
+    /**
+     * ⛔ HALF OF A PAIR — see ESTIMATED_PAGE_TRANSFER_BYTES, which states the
+     * same page in bytes as this states it in dollars. Both are calibrated
+     * against a 1012.8 KB page and neither may move alone: their quotient is
+     * the cost of a gigabyte, and that is what every bandwidthGb band on the
+     * ladder was sized against.
+     */
+    perPageView: number;
+    perFormSubmission: number;
+    /** Firestore-backed dataset bytes — an order pricier than object storage. */
+    dataStoragePerGbMonth: number;
+    perApiRequest: number;
+    perContactMonth: number;
+    /**
+     * One delivered email, whatever produced it — $0.90 per 1,000.
+     *
+     * Unlike its five neighbours this is not an operator-tuned estimate. It is
+     * the provider's own blended rate at the tier above the account's current
+     * one ($90 / 100,000) and also the marginal overage rate on both that tier
+     * and the current one, so it does not fall as volume grows and is the
+     * conservative figure at any usage the platform can reach.
+     *
+     * It prices EVERY send on the cost meter — campaigns, receipts, invites,
+     * password resets — because every one of them is a message the provider
+     * charges for. The band on the plan and the retail overage rate beside it
+     * both concern a smaller quantity; this is the whole bill.
+     */
+    perEmailSend: number;
+    /**
+     * One workflow or action run — $12 per million.
+     *
+     * Derived from the run paths at list prices (2026-09-07), because nothing
+     * measurable exists yet: runs execute inside the Vercel request that fired
+     * the event, not in a function of their own, so Cloud Logging carries no
+     * per-run entry to count, and Firestore's operation counts are platform-wide
+     * and cannot be attributed to a run. Over the 14 days to 2026-09-07 the
+     * project logged no run at all.
+     *
+     * The ledger, for an event that executes one workflow on a site holding a
+     * handful of functions, variables and workflows (`runEventWorkflows`,
+     * `runEventActions` and the inbound-webhook run are the same shape):
+     *
+     *   - reads: the triggered query, the workflow map, the host → org lookup,
+     *     the run counter, the functions and the variables — about 12, at
+     *     nam5's $0.06 per 100,000 = $0.0000072
+     *   - writes: the activity row and the counter increment — 2, at $0.18 per
+     *     100,000 = $0.0000036
+     *   - compute: a few milliseconds of active CPU and memory on Fluid compute
+     *     for the expression evaluation, about $0.000001
+     *
+     * $0.0000118, carried as $0.000012. It scales with the catalog a site holds
+     * — every `limit(100)` read above is a query that costs one read per
+     * document returned — and a step that writes a dataset record or calls a
+     * webhook adds to it, so this is the typical figure, not the ceiling.
+     *
+     * It is a COST, not a price: no plan bills runs, and none refuses past the
+     * band on a metered plan. It exists so a tier's run bands reach
+     * `orgMonthlyCogsUsd` and `tier-margin-floor.spec.ts` — Agency's 3,000,000
+     * runs are $36 a month that read as nothing while this was absent.
+     */
+    perRun: number;
+};
+/** The rollup fields `orgMonthlyCogsUsd` prices. All optional and all absent-safe. */
+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 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
+     * provider charged for, and most of them are messages no quota could have
+     * refused.
+     */
+    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.
+     */
+    workflowRuns?: number | null;
+    actionRuns?: number | null;
+}
+export interface OrgCogsResult {
+    /** What the guardrail should charge against revenue. */
+    cogsUsd: number;
+    /** Which arm produced it — `floor` means the meters came in under the flat estimate. */
+    basis: 'measured' | 'floor';
+    /** Cost from the meters alone, before the floor is applied. */
+    measuredUsd: number;
+    /** `INFRA_COGS_PER_SITE_USD` × sites. */
+    floorUsd: number;
+    /** Per-meter contributions, for showing the working in staff UI. */
+    breakdown: Record<string, number>;
+}
+/**
+ * One org's monthly infrastructure COGS — the single cost model (AGL-1134).
+ *
+ * Replaces two things that had drifted apart: the discount guardrail read the
+ * rollup's `costUsd`, and the staff MRR views read the same field separately,
+ * so neither could be changed without silently changing the other's meaning.
+ *
+ * `costUsd` was also incomplete. The rollup records `dataStorageMb`,
+ * `apiRequests` and `contactsCount`, and `estimateMonthlyUsageCost` prices
+ * none of them — it sums storage, page views and form submissions only. So
+ * the "measured" cost omitted three meters the platform was already at the
+ * trouble of recording.
+ *
+ * The flat per-site figure stays a FLOOR rather than a fallback: measured
+ * cost wins only when it exceeds the estimate. A rollup that has not run, or
+ * an org with genuinely tiny usage, must not make the guardrail more generous
+ * — that is the one direction that costs money.
+ *
+ * Measured against production 2026-07-30, that floor is doing all the work:
+ * the largest real org's `costUsd` was **$0.0000054** against a $4.00 floor
+ * for two sites. Five orders of magnitude. So this function changes no verdict
+ * today, and will not until there is real traffic — which is the honest
+ * reason to build it now, while nothing depends on the answer.
+ */
+export declare function orgMonthlyCogsUsd(rollup: OrgUsageRollupInput | null | undefined, siteCount: number): OrgCogsResult;
+/**
+ * Pluck the fields `orgMonthlyCogsUsd` prices out of a raw usage rollup
+ * (AGL-1134) — a Firestore `snapshot.data()`, or the JSON a staff endpoint
+ * served from one. ONE list of field names, in one place.
+ *
+ * The hazard this closes is silent. Every caller previously hand-listed the
+ * six fields at its own call site — the discount route, the anomaly detector,
+ * the staff org page — and `/api/admin/org-usage` projected only three of
+ * them. A projection that drops a priced field does not error; the model just
+ * returns a smaller number, and a smaller COGS is the direction that APPROVES
+ * a discount. Same shape as the API projection that starved a predicate in
+ * AGL-1355, and the two-units usage figure that read 20-45% wrong for years
+ * in AGL-1402.
+ *
+ * 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.
+ */
+export declare function orgCogsInputFrom(source: Record<string, unknown> | null | undefined): OrgUsageRollupInput;
+/**
+ * A cost figure, or the explicit admission that the rollup has not loaded
+ * (AGL-1134).
+ *
+ * `pending` is not "no usage" and not "$0" — it is "do not answer yet".
+ */
+export type OrgCogsPreview = {
+    status: 'pending';
+} | {
+    status: 'ready';
+    cogs: OrgCogsResult;
+};
+/**
+ * `orgMonthlyCogsUsd` behind an explicit readiness flag (AGL-1134).
+ *
+ * The staff org page loads its rollup asynchronously, and an unfinished read
+ * and an absent document are the same `undefined`. Priced directly, both
+ * yield `basis: 'floor'` — so the enterprise pricing card printed "per-site
+ * floor — no usage recorded yet" during the loading window, a
+ * measurement-shaped sentence about an org whose measurements had simply not
+ * arrived. That is the AGL-1380 / AGL-1422 defect exactly: a question
+ * answered before its data is ready, and answered in the cheap direction.
+ *
+ * Returning a discriminated union rather than a nullable number is what makes
+ * the window unrepresentable — a caller cannot reach a cost without first
+ * handling `pending`, so the next call site cannot re-introduce this by
+ * forgetting a flag it was handed.
+ */
+export declare function orgCogsPreview(ready: boolean, rollup: OrgUsageRollupInput | null | undefined, siteCount: number): OrgCogsPreview;
+/**
+ * Where a cost figure came from, in a sentence a staff member can act on
+ * (AGL-1930).
+ *
+ * The staff quote card said `per-site floor — no usage recorded yet` for
+ * EVERY `basis: 'floor'` org. Measured against production 2026-08-24 that
+ * sentence is false on most of them: all 14 usage rollups across all 6 orgs
+ * price under the floor, and 9 of the 14 carry genuinely non-zero usage — the
+ * largest real org measured **$0.22** against its $2.00 floor. "No usage
+ * recorded" and "usage recorded, and it came in under the floor" are opposite
+ * facts about the cost model, and only the second one is evidence the meters
+ * are working at all.
+ *
+ * Same failure family as AGL-1380 / AGL-1422 — a measurement-shaped sentence
+ * printed over a measurement that was never consulted — one layer further in:
+ * here the measurement exists and the copy denies it.
+ */
+export declare function orgCogsBasisSummary(cogs: OrgCogsResult, month?: string | null): string;
+/**
+ * Percent-off at or above which creating a coupon needs explicit staff
+ * sign-off (AGL-1105). A ≥40%-off coupon is a real revenue commitment, so the
+ * creation route rejects it unless the caller passes a confirm flag; the UI
+ * surfaces a checkbox at this threshold.
+ */
+export declare const DISCOUNT_APPROVAL_THRESHOLD_PCT = 40;
+/**
+ * Discount DEPTH bands (AGL-1120) — how much of list price is being given
+ * away, which is a different question from whether the remainder covers
+ * infrastructure.
+ *
+ * The original guardrail asked only the second question, so a **93% off**
+ * coupon rated "OK — net margin 78.1% vs a 75% floor": $9.15 left against $2
+ * of infra really is a 78% contribution margin. The ratio is scale-invariant,
+ * so as long as the leftover dwarfs $2 the verdict stays green no matter how
+ * little is left. Depth never entered the verdict at all.
+ *
+ * Warn at the threshold that already requires sign-off, so the badge and the
+ * approval checkbox stop disagreeing with each other; block at 70%, where a
+ * deal is being given away rather than discounted.
+ */
+export declare const DISCOUNT_DEPTH_WARN_PCT = 40;
+export declare const DISCOUNT_DEPTH_BLOCK_PCT = 70;
+/** How many sites (hosts) the org runs — at least 1 for a billing org. */
+export declare function orgSiteCount(org: Partial<AglynOrgBilling> | null | undefined): number;
+/** The margin-guardrail verdict for a proposed or applied discount. */
+export type DiscountMarginRating = 'ok' | 'warn' | 'block';
+export interface DiscountMarginResult {
+    /** Pre-discount list price (`orgListPriceMonthlyUsd`). */
+    grossUsd: number;
+    /** List price net of the proposed discount. */
+    discountedUsd: number;
+    /** Discounted price net of Stripe's processing fee — what Aglyn keeps. */
+    netUsd: number;
+    /**
+     * Monthly COGS charged against this org: the org's MEASURED cost when the
+     * caller supplies one, else the flat `$/site × sites` estimate. The flat
+     * figure is a floor, never a ceiling — a measured cost below it is treated
+     * as the estimate, since a rollup that has not caught up must not make a
+     * deal look cheaper than the placeholder did.
+     */
+    infraCogsUsd: number;
+    /** True when `infraCogsUsd` came from measured usage, not the flat rate. */
+    cogsMeasured: boolean;
+    /**
+     * Cost recovery = (net − COGS) / net, as a fraction. 1 = COGS-free; -1 is
+     * the clamp for a fully-underwater discount (net ≤ 0), which always blocks.
+     *
+     * NOT a deal-quality number on its own — see `depthPct`. Kept under its
+     * original name because the staff UI reports it verbatim.
+     */
+    marginPct: number;
+    /** Share of list price given away, as a fraction (0.93 = 93% off). */
+    depthPct: number;
+    /** The worse of the depth and cost-recovery verdicts. */
+    rating: DiscountMarginRating;
+    /**
+     * Which test produced `rating`, so the UI can say why rather than showing a
+     * margin number that looks fine next to a red badge.
+     */
+    reason: 'none' | 'depth' | 'cogs' | 'underwater';
+    /** The cost-recovery floor this was rated against (`NET_MARGIN_FLOOR_PCT`). */
+    floorPct: number;
+}
+export interface DiscountMarginOptions {
+    /**
+     * The org's measured monthly cost, when the caller has it — the `costUsd`
+     * rollup at `orgs/{id}/usage/{month}`. Server callers and the staff org
+     * page can supply it; coupon creation cannot, because no org is chosen yet.
+     */
+    measuredCogsUsd?: number | null;
+}
+/**
+ * Rate a proposed discount (AGL-1105, re-shaped in AGL-1120) — the guardrail
+ * behind staff coupon creation and per-org application.
+ *
+ * Two independent questions, and the verdict is the WORSE of them:
+ *
+ *  1. **How deep is it?** `depthPct` against `DISCOUNT_DEPTH_WARN_PCT` /
+ *     `DISCOUNT_DEPTH_BLOCK_PCT`. This is the one that was missing. Cost
+ *     recovery alone is scale-invariant — 93% off $139 leaves $9.15 against
+ *     $2 of infra, a genuine 78% contribution margin — so the old verdict
+ *     rated a give-away "OK" and only warned at 94%.
+ *  2. **Does the remainder cover the cost of serving them?** `marginPct`
+ *     against `NET_MARGIN_FLOOR_PCT`, with `NET_MARGIN_WARN_BAND_PCT` below
+ *     it, and an automatic block once the discount drives net ≤ 0.
+ *
+ * Neither subsumes the other: a shallow discount on an org running twenty
+ * sites can still fail cost recovery, and a deep one on a cheap org can still
+ * clear it. `reason` reports which test bound, so the UI never shows a
+ * healthy-looking margin beside a red badge without explanation.
+ *
+ * `discount` is the PROPOSED change, independent of any discount already on
+ * the org — `grossUsd` is always the list price (`orgListPriceMonthlyUsd`),
+ * so this never double-counts an existing `org.discount`. A non-billing org
+ * (list price 0) has no revenue to protect and rates `ok`.
+ */
+export declare function checkDiscountMargin(org: Partial<AglynOrgBilling> | null | undefined, discount: Pick<OrgDiscount, 'percentOff' | 'amountOffUsd'>, options?: DiscountMarginOptions): DiscountMarginResult;
+/**
+ * The plan the org actually gets (AGL-247): missing/unknown plans resolve
+ * as `free`, and a paid plan whose subscription is canceled/unpaid/
+ * incomplete downgrades to `free` until the webhook restores it — plan
+ * fields alone are not entitlement.
+ *
+ * A STAFF COMP comes first (AGL-3034), and only where no subscription decides
+ * the plan: `resolvePlanComp` answers `null` while one is live, so a paying
+ * workspace's plan is always its subscription's. The comp is its own marker,
+ * never the stored `plan` — a canceled customer whose `plan` still names what
+ * they paid for resolves as Free exactly as before, because nothing about
+ * their document is a comp.
+ */
+export declare function resolveEffectivePlan(org: Partial<AglynOrgBilling> | null | undefined): OrgPlan;
+/**
+ * Whether the org's Aglyn AI add-on currently applies (AGL-2896): bought,
+ * and on a subscription that is still paying for it. The ONE reading of
+ * `seatAddons.aiAddon` — the entitlement fold and the assist overage rate
+ * both ask this, so a dead subscription drops the band and the rate
+ * together rather than leaving a rate on a band that has gone.
+ */
+export declare function hasAiAddon(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * Numeric entitlement keys that were REMOVED from `PLAN_ENTITLEMENTS` and
+ * must never be resolved again from a stored override (AGL-2133).
+ *
+ * `totalSiteSizeMb` is the first. It carried a value on all 8 plans and was
+ * enforced by nothing — no gate, no meter, no alert. AGL-1107 added it and
+ * AGL-1370 deleted its meter and its alert on measurement rather than taste:
+ * `measure-node-map.ts` refuses any node map over 900 KB (AGL-678), so the
+ * measurable org total tops out at 2.3–20.9% of the cap depending on plan.
+ * What survived was a WRITABLE staff override field for a number nothing
+ * read, so a support engineer resolving a "this site is too big" ticket
+ * raised it, got a success and an audit row, and changed nothing.
+ *
+ * WIRING IT WAS THE OTHER OPTION AND IT IS WORSE. A cap the measurement can
+ * reach a fifth of is a gate that refuses nobody — the same "reports success,
+ * does nothing" shape, moved from the staff dialog to the enforcement point,
+ * plus a new hard wall introduced days before launch. The per-site size
+ * ceiling that actually binds is AGL-678's 900 KB node map, and it is real.
+ *
+ * The rollup's `siteSizeMb` MEASUREMENT stays — host-usage and the usage
+ * audit read it, and it is a genuine internal signal. Only the entitlement
+ * goes.
+ */
+export declare const RETIRED_ENTITLEMENT_KEYS: ReadonlySet<string>;
+/**
+ * The numeric entitlements that are PRICES rather than caps (AGL-3049): the
+ * platform's percentage of a storefront or marketplace sale.
+ *
+ * Every other numeric key is a band — a count, a size, a monthly or daily
+ * allowance — and an uncapped comp lifts it to `UNLIMITED`. These three it
+ * must never touch. `transactionFee*Pct` becomes Stripe's
+ * `application_fee_amount` at checkout, so an unlimited one is a fee larger
+ * than the charge and every sale on the storefront fails; and "no cap" has
+ * no meaning for a price in the first place. An uncapped workspace pays its
+ * plan's percentages, or whatever a per-org override sets them to.
+ *
+ * Named rather than derived from the `Pct` suffix, so a new numeric key is a
+ * band unless someone decides here that it is a price. `plan-comp.spec.ts`
+ * pins these three by name and proves every other numeric key is lifted.
+ */
+export declare const PRICE_ENTITLEMENT_KEYS: ReadonlySet<string>;
+/**
+ * Effective entitlements for an org: plan defaults with the org doc's
+ * per-key overrides applied (features merge key-by-key too), then
+ * purchased add-ons stacked on top (AGL-524): `seatAddons.hosts` raises
+ * `hostLimit`, `seatAddons.eventCalendar` switches the `eventCalendar`
+ * feature on, and every seat add-on a plugin declared through
+ * `registerPluginEntitlements` (AGL-2940) widens the quota it names by its
+ * per-plan figure per unit and switches its features on — the Aglyn AI
+ * add-on (AGL-2896) is the first such declaration. (Seat/dataset add-ons
+ * instead fold in at `checkSeatQuota` / `checkDatasetQuota`, where the
+ * per-plan hard max clamps them.)
+ * Missing or unknown plans resolve as `free`.
+ *
+ * EVERY NUMERIC KEY of `OrgEntitlements` is an override axis, not a chosen
+ * few: the loop below copies any number it finds under the org's
+ * `entitlements`, so a contracted `bandwidthGb`, `apiRequestsPerMonth` or
+ * `workflowRunsPerMonth` resolves ahead of the plan default exactly as the
+ * long-documented `emailSendsPerMonth`, `formsPerHost` and
+ * `assistCreditsPerMonth` overrides do. Since 2026-09-07 this is what makes
+ * Enterprise's finite fallbacks safe to hold: the row in `PLAN_ENTITLEMENTS`
+ * is what an agreement gets before its numbers are written down, and the
+ * override is where they are written. `plan-entitlements.spec.ts` proves
+ * the precedence on every axis, so a resolver that started honoring a list
+ * would fail by the name of the axis it dropped.
+ *
+ * `hostLimit` is DELIBERATELY unclamped here (AGL-1738): there is no
+ * `maxHostsPerOrg` to clamp against, because extra sites are sold flat rather
+ * than up to a band. Their bound is the purchase ceiling,
+ * `EXTRA_HOSTS_ADDON_MAX`, and a band-shaped `Math.min` added here would
+ * silently disable sites the org is invoiced for. See that constant before
+ * "fixing" this add.
+ *
+ * `posRegisters` IS NOT ADDED HERE, and this is the fix, not an omission
+ * (AGL-1775). The register add-on is priced "per
+ * extra register/location" and enforced PER SITE, so folding the org-wide
+ * purchase into an org-level value every site inherits sold one register and
+ * delivered `hostLimit` of them. `seatAddons.posRegisters` is now a POOL and
+ * `org.registerAllocations` says which site holds each seat. The number this
+ * function returns for `posRegisters` is therefore **the plan's cap alone** —
+ * exactly what an unallocated site must resolve to. Per-site capacity comes
+ * from `resolveHostRegisterCap(org, hostId)`; nothing else may add the pool
+ * back in.
+ *
+ * (`eventCalendar` is still org-wide on purpose: it is documented and priced
+ * as "one purchase covers every host in the org". The register add-on never
+ * was, which is the whole difference.)
+ *
+ * AN UNCAPPED COMP IN FORCE (AGL-3049) resolves every band as `UNLIMITED`
+ * on top of all of the above — `withEveryCapLifted` — and leaves the
+ * features and the fee percentages exactly as resolved.
+ */
+export declare function resolveOrgEntitlements(org: Partial<AglynOrgBilling> | null | undefined): ResolvedOrgEntitlements;
+/**
+ * How many units of a plugin-declared seat add-on a purchase map counts as
+ * (AGL-2940): the stored quantity, capped at the declaration's `maxUnits`
+ * — 1 for an org-wide add-on, where a doubled webhook item or a hand edit
+ * above one is still one purchase. A non-number, `NaN`, a negative, or a
+ * key nothing declared is none.
+ */
+export declare function pluginSeatAddonUnits(addons: OrgSeatAddons | null | undefined, key: string): number;
+/**
+ * Whether a plugin-declared seat add-on currently applies to the org: bought,
+ * and on a subscription that is still paying for it — the one reading every
+ * surface that shows or charges for the add-on goes through, so a dead
+ * subscription drops the quota and the feature together.
+ */
+export declare function hasPluginSeatAddon(org: Partial<AglynOrgBilling> | null | undefined, key: string): boolean;
+/**
+ * The org's POS register pool (AGL-1775): how many seats were purchased, how
+ * many are assigned to a site, and how many are left to assign.
+ *
+ * `purchased` runs through `resolvePurchasedAddons`, so a dead subscription
+ * empties the pool exactly as it empties every other add-on — the seats stop
+ * counting when they stop billing.
+ *
+ * `byHost` is the SANITISED allocation, and it never sums past `purchased`.
+ * The write path validates before it stores, so an over-allocated map means
+ * the data is stale or corrupt (a purchase reduced without the allocation
+ * being trimmed, a partial write, a hand edit). Both directions of getting
+ * that wrong cost money, so it is resolved rather than trusted: hosts are
+ * walked in sorted-id order and granted what remains of the pool, which is
+ * deterministic — the same host gets the same answer on every reader — and
+ * cannot hand out capacity nobody paid for.
+ *
+ * Every value is coerced: a non-number, `NaN`, `Infinity` or a negative reads
+ * as zero seats. An `Infinity` in this map would otherwise become an
+ * unbounded per-site register cap, which is the one outcome the guard in
+ * `resolveHostRegisterCap` exists to make impossible.
+ */
+export declare function resolveRegisterSeatPool(org: Partial<AglynOrgBilling> | null | undefined): {
+    purchased: number;
+    allocated: number;
+    available: number;
+    byHost: Record<string, number>;
+};
+/**
+ * How many POS registers one SITE may run (AGL-1775): the plan's per-site cap
+ * plus whatever the org has assigned to that site out of the pool.
+ *
+ * THE GUARD, and the reason this is a function rather than a lookup. An
+ * unallocated host — no entry in `registerAllocations`, a missing map, a
+ * missing org, an org still loading — resolves to `resolveOrgEntitlements(org)
+ * .posRegisters`, which since AGL-1775 is the PLAN's cap and nothing else.
+ * Never the pooled total, and never `Infinity` unless the plan itself is
+ * `UNLIMITED` (enterprise, where an unbounded cap is what was sold).
+ *
+ * `checkQuota(undefined)` resolving to the Free tier is the lesson this
+ * inverts: an absent input there quietly answered a question in the
+ * PERMISSIVE direction on the day it mattered. Here the absent input answers
+ * in the direction of the plan, which is the conservative one — a site that
+ * has been assigned seats and whose allocation failed to load runs fewer
+ * registers than it paid for, which the console can say out loud, rather than
+ * more than it paid for, which nothing would ever notice.
+ *
+ * There is deliberately no separate read: the allocation lives on the org doc
+ * beside the entitlements, so a caller holding one holds the other.
+ */
+export declare function resolveHostRegisterCap(org: Partial<AglynOrgBilling> | null | undefined, hostId: string | null | undefined): number;
+/**
+ * The org's COLLABORATOR seat pool (AGL-2439): how many per-site collaborator
+ * seats were purchased, how many are assigned to a site, and how many are
+ * left to assign.
+ *
+ * The AGL-1775 register mechanism, applied to the key it was never applied to.
+ * `seatAddons.members` is bought once, org-wide; `membersPerHost` is enforced
+ * PER SITE. Adding one to the other handed the whole purchase to every site,
+ * so an org with 20 sites that bought ONE extra collaborator seat received 20.
+ * The quantity is now the size of an org-level pool and
+ * `org.collaboratorAllocations` says which site holds each seat.
+ *
+ * Everything about the resolution is deliberately identical to
+ * `resolveRegisterSeatPool` — the same clamp, the same sorted-id determinism,
+ * the same coercion of a non-number / `NaN` / `Infinity` / negative to zero.
+ * This is ONE mechanism used twice, not a second mechanism that happens to
+ * rhyme: a reader who has understood the register pool has understood this,
+ * and a fix to one is a fix to both.
+ *
+ * `purchased` runs through `resolvePurchasedAddons`, so a dead subscription
+ * empties the pool exactly as it empties every other add-on.
+ */
+export declare function resolveCollaboratorSeatPool(org: Partial<AglynOrgBilling> | null | undefined): {
+    purchased: number;
+    allocated: number;
+    available: number;
+    byHost: Record<string, number>;
+};
+/**
+ * How many console COLLABORATORS one SITE may hold (AGL-2439): the plan's
+ * per-site allowance plus whatever the org has assigned to that site out of
+ * the pool, clamped to the plan's hard `maxMembersPerHost`.
+ *
+ * THE GUARD, and the reason this is a function rather than a lookup. An
+ * unallocated host — no entry in `collaboratorAllocations`, a missing map, a
+ * missing org, an org still loading — resolves to the PLAN's `membersPerHost`
+ * and nothing else. Never the pooled total, and never `Infinity` unless the
+ * plan itself is `UNLIMITED` (enterprise, where an unbounded cap is what was
+ * sold). `checkQuota(undefined)` resolving to the Free tier is the lesson
+ * this inverts: the absent input answers in the direction of the plan, which
+ * is the conservative one.
+ *
+ * The clamp is what `checkSeatQuota` always did and is kept: collaborator
+ * seats are sold up to a BAND (`maxMembersPerHost`), unlike registers, which
+ * are sold flat. Assigning more pool seats to a site than the band allows
+ * cannot lift it past the band — the org must upgrade the plan.
+ *
+ * There is deliberately no separate read: the allocation lives on the org doc
+ * beside the entitlements, so a caller holding one holds the other.
+ */
+export declare function resolveHostCollaboratorCap(org: Partial<AglynOrgBilling> | null | undefined, hostId: string | null | undefined): number;
+/**
+ * Quota answer for a site's console COLLABORATORS (AGL-2439) — the
+ * host-scoped `checkSeatQuota`, in the same `SeatQuotaResult` shape so the
+ * existing call sites and refusal copy read identically.
+ *
+ * `checkSeatQuota(org, 'members', …)` is WRONG for a site now and this exists
+ * so nobody has to remember why: since AGL-2439 that helper no longer folds
+ * the org-wide purchase into a per-site number, so it answers the PLAN's cap
+ * and would refuse a site the seats it holds.
+ *
+ * ## THE GRANDFATHER BOUNDARY — explicit, and this field is it
+ *
+ * The cap is corrected, and no org already above it is evicted or locked
+ * out.
+ *
+ * The boundary is drawn between two different questions, and they are
+ * different lines of code rather than one number used for two purposes:
+ *
+ *   `allowed`           — may this site take on ANOTHER collaborator? Bound
+ *                         by `limit`, the corrected cap. This is the ONLY
+ *                         thing the cap decides.
+ *   `retainedOverCap`   — how many seats this site holds ABOVE `limit`. They
+ *                         are RETAINED. Nothing in this repo revokes a
+ *                         collaborator for being over a cap, and nothing may
+ *                         be added that does: the cap binds ALLOCATION, never
+ *                         ACCESS.
+ *
+ * So an over-cap site keeps every collaborator it has, cannot add another,
+ * and returns to normal by attrition, by buying pool seats and assigning them
+ * here, or by upgrading — at which point `limit` recomputes from the new plan
+ * or allocation and the retention lapses on its own. That is what "they keep
+ * what they have until they next change plan or seat count" means, resolved
+ * rather than stored: a stored floor would need a backfill over live orgs and
+ * would be a defaulted field on a `merge`-written document, which is the
+ * converter hazard that destroys the real value it was meant to protect.
+ *
+ * `retainedOverCap` is non-zero ONLY when the site is already over. It is not
+ * headroom and cannot be spent: it is a count the console says out loud so
+ * the customer sees why the next Add is refused while nobody loses access.
+ */
+export declare function checkHostCollaboratorQuota(org: Partial<AglynOrgBilling> | null | undefined, hostId: string | null | undefined, currentUsage: number): SeatQuotaResult & {
+    /** Seats held ABOVE `limit`, retained and never revoked (the grandfather). */
+    retainedOverCap: number;
+    /** Pool seats the org has assigned to THIS site. */
+    assignedSeats: number;
+};
+/**
+ * Quota answer for a site's POS registers (AGL-1775) — the register-shaped
+ * `checkQuota`, in the same `{ allowed, limit, remaining }` shape so callers
+ * read identically.
+ *
+ * `checkQuota(org, 'posRegisters', used)` is WRONG for registers now and this
+ * exists so nobody has to remember why: that helper resolves the org-level
+ * value, which is the plan cap with no pool in it, so it would refuse a site
+ * the seats it holds. Everything that gates a register creation calls this.
+ */
+export declare function checkHostRegisterQuota(org: Partial<AglynOrgBilling> | null | undefined, hostId: string | null | undefined, currentUsage: number): {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+};
+/**
+ * Platform transaction fee % for a storefront sale (AGL-278): resolved
+ * from the effective plan (with per-org overrides) by product type.
+ * Digital and service sales use the digital rate; AGL-307 turns this into
+ * the Stripe Connect `application_fee_amount` at charge time.
+ */
+export declare function resolveTransactionFeePct(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service'): number;
+/**
+ * Stripe's processing cost on ONE storefront destination charge, in cents
+ * (AGL-2152) — the dearest enabled method's percentage plus the fixed 30¢,
+ * rounded UP on the percentage so the answer is never a cent short of what
+ * Stripe actually debits.
+ *
+ * WHO PAYS THIS. Every storefront charge is a DESTINATION charge:
+ * `payment_intent_data[transfer_data][destination]` names the merchant's
+ * connected account and no `transfer_data[amount]` is sent, so Stripe moves
+ * the whole charge to the merchant and debits its processing fee from the
+ * PLATFORM's balance. Aglyn's net on an order is therefore
+ *
+ *     application_fee_amount − (processing% × charge + 30¢)
+ *
+ * and with `application_fee_amount` at 0 — which is what
+ * `transactionFeePhysicalPct: 0` produced on Pro, Business, Scale, Advanced,
+ * Agency and Enterprise — that net is NEGATIVE on every single sale. A flat
+ * percentage cannot repair it either: Starter's 2% is below even the cheapest
+ * processing rate, so Starter lost money at every order size too, and any rate
+ * above it still loses until the order clears `30¢ ÷ (take − processing)`. The
+ * fixed 30¢ is why a percentage alone can never reach break-even on small
+ * orders, and why this returns a CENTS amount rather than a rate.
+ *
+ * WHY THE DEAREST METHOD AND NOT 2.9%. The shopper picks how to pay AFTER the
+ * session is created, and `application_fee_amount` is a fixed number Stripe
+ * will not let us revise once the charge settles. No storefront path pins
+ * `payment_method_types`, so the platform's payment method configuration
+ * decides the set — and per AGL-2343 that configuration has `klarna` and
+ * `affirm` on beside the card family. Pricing this at the card rate would be
+ * wrong exactly on the orders where it cost the most, which is the same
+ * reasoning `marketplaceBreakEvenUsd` already applies to the listing floor;
+ * these are deliberately the SAME two constants so the two cannot drift.
+ *
+ * THE ONE-LINE LEVER. On a card-family order this over-recovers by the spread
+ * between the two rates. Pinning `payment_method_types` on the storefront
+ * sessions to the card family would make 2.9% the true binding rate, and
+ * `STOREFRONT_PROCESSING_PERCENT` below is then the single identifier to
+ * repoint. That is a product decision about which payment methods a storefront
+ * offers, not this one; it is recorded on AGL-2152 and in the Pricing Decision
+ * Log so it can be taken deliberately.
+ */
+export declare function storefrontProcessingCostCents(chargeCents: number): number;
+/**
+ * The Stripe Connect `application_fee_amount` for ONE storefront sale
+ * (AGL-2152) — the platform's advertised take PLUS Stripe's processing cost,
+ * passed through at cost.
+ *
+ *     fee = take%(feeBaseCents) + processing%(chargeCents) + 30¢
+ *
+ * so Aglyn's net per order is AT LEAST the advertised take, at every order
+ * size down to Stripe's own 50¢ charge minimum, and never negative. The
+ * September-1 price lock was lifted for this one change; see the Pricing
+ * Decision Log entry of 2026-08-19. No advertised PLATFORM rate moved — a 0% tier is still 0%
+ * platform take — what changed is that the card cost stops being absorbed
+ * silently by Aglyn.
+ *
+ * `feeBaseCents` is the GOODS the take is a cut of (discounts already applied,
+ * tax and shipping excluded — that has always been the basis, AGL-2317).
+ * `chargeCents` is what Stripe will actually run the card for, which is goods
+ * + tax + shipping, and defaults to `feeBaseCents` for the paths where they
+ * are the same number. Passing the goods figure for a charge that also carries
+ * tax would under-recover by the processing rate on the difference.
+ *
+ * Clamped to `chargeCents` because Stripe rejects an application fee larger
+ * than the charge. That clamp can only bind below ~32¢, under Stripe's own 50¢
+ * charge minimum, so it never trims a real order's fee.
+ */
+export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', feeBaseCents: number, chargeCents?: number): number;
+/**
+ * Stripe's processing cost on a RECURRING charge of `amountCents`, as the
+ * percent a Subscription's `application_fee_percent` can carry (AGL-2655).
+ *
+ * A Stripe Subscription accepts no `application_fee_amount` — only
+ * `application_fee_percent`, a rate with at most two decimal places — so the
+ * fixed 30¢ that `storefrontProcessingCostCents` adds in cents has to be
+ * folded into the rate. `(rate × amount + fixed) ÷ amount` is, with the
+ * amount cancelled,
+ *
+ *     percent = rate + fixed ÷ amount
+ *
+ * which is why a smaller recurring price carries a HIGHER percent: the 30¢
+ * is a bigger share of it. At 6% + 30¢ a $10 price carries 9%, $25 carries
+ * 7.2% and $100 carries 6.3%.
+ *
+ * Computed in hundredths of a percent on integers and rounded UP to the next
+ * hundredth. Up, for the reason the one-time helper rounds its percentage
+ * up: rounding to nearest would leave the recovery a fraction of a cent
+ * short of what Stripe debits half the time, and Stripe rejects a third
+ * decimal outright, so the only honest direction is over. Integers, because
+ * `0.09 * 100` is not `9` in floating point and a percent one ulp above a
+ * whole hundredth would round up to the next one. The same two constants as
+ * the one-time path, so repointing `STOREFRONT_PROCESSING_PERCENT` moves
+ * both surfaces together. Zero for a charge that is not a charge.
+ */
+export declare function storefrontProcessingPassThroughPercent(amountCents: number): number;
+/**
+ * The `application_fee_percent` for ONE storefront subscription (AGL-2655):
+ * the plan's advertised take PLUS Stripe's processing cost as a percent —
+ * the recurring twin of `resolveTransactionFeeCents`, under the same rule.
+ * Every tier carries the pass-through, a 0% tier included, because the
+ * tier's 0% is a platform take and the pass-through is not one; it is what
+ * Stripe charges to take the payment, which on a destination charge is
+ * debited from the platform's balance whatever the tier.
+ *
+ * `amountCents` is the recurring items the percent will be applied to —
+ * the goods after any discount, tax and shipping excluded, the AGL-2317
+ * basis. Stripe applies the percent to the whole invoice and the paid-invoice
+ * correction scales it back to items, so sizing on items is what makes the
+ * recovery come out at cost rather than under.
+ *
+ * Composed in hundredths so two decimals stay two decimals (`2 + 6.34` is
+ * not always `8.34` in floating point), and capped at 100, Stripe's ceiling
+ * for the parameter — the recurring twin of the clamp to the charge.
+ */
+export declare function resolveSubscriptionFeePercent(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', amountCents: number): number;
+/**
+ * Platform take rate % for a MARKETPLACE listing sale (AGL-1543), priced
+ * off the SELLER org. Resolved through `resolveOrgEntitlements` — so a
+ * dead subscription prices as free-plan (30%) even while the stale `plan`
+ * field still names a paid tier, and a negotiated per-org
+ * `entitlements.marketplaceFeePct` override wins over the plan default.
+ * Resolve per request from the org doc; never cache the answer.
+ *
+ * An out-of-range or missing value falls back to the FREE-plan rate — the
+ * conservative direction. A malformed override must never zero the
+ * platform's cut.
+ */
+export declare function resolveMarketplaceFeePct(org: Partial<AglynOrgBilling> | null | undefined): number;
+/**
+ * The marketplace take rate that breaks even LATEST, derived from the plan
+ * table rather than copied from it (AGL-2343).
+ *
+ * The lowest rate is the binding one: a smaller cut of the same price against
+ * the same processing cost needs a dearer listing to cover it, so advice quoted
+ * at this band holds for every publisher on every plan. Derived on each call
+ * because a hand-written second copy of a rate is exactly the artifact that
+ * decays into wrong money copy shown to a publisher — the same reason
+ * `planGrantingFeature` reads the table instead of a map.
+ */
+export declare function bindingMarketplaceFeePct(): number;
+/**
+ * What one marketplace sale costs the PLATFORM to process (AGL-2343).
+ *
+ * NONE OF THESE IS AN AGLYN PRICE. They are Stripe's published US rates and
+ * the Texas rate the platform remits, and they exist only as inputs to a
+ * figure shown to a publisher while they type. Nothing is billed from them —
+ * the charged amounts are `resolveMarketplaceFeePct` and Stripe's own
+ * invoicing — so changing one changes a sentence, never a bill.
+ *
+ * WHY THE PLATFORM PAYS THE PROCESSING FEE AT ALL. Marketplace checkout is a
+ * DESTINATION charge with a fixed `transfer_data[amount]` and deliberately no
+ * `application_fee_amount`, so that the sales tax stays with the platform that
+ * owes it (AGL-1544). On a destination charge Stripe debits its fee from the
+ * PLATFORM's balance, and it is charged on `amount_total` — the listing price
+ * plus the tax added on top of it.
+ *
+ * So a $1 listing at a 20% take rate is a loss: the buyer pays $1.08, the
+ * seller is transferred $0.80, $0.08 is owed to the state, Aglyn keeps $0.20
+ * and pays Stripe about $0.33. Net −$0.13.
+ *
+ * THE BNPL RATE IS THE ONE THAT BINDS, and it is not hypothetical: the live
+ * default payment method configuration has `klarna` and `affirm` enabled
+ * alongside `card`, `cashapp`, `link`, `amazon_pay` and `apple_pay`, and the
+ * marketplace session pins no `payment_method_types`, so a buyer may pay by
+ * either. Break-even is computed from the dearest enabled method, because a
+ * figure computed from the cheapest would be wrong exactly when it mattered.
+ * IF BNPL IS EVER TURNED OFF FOR MARKETPLACE SESSIONS, this constant is what
+ * has to move with it.
+ */
+export declare const MARKETPLACE_PROCESSING_PERCENT_CARD = 2.9;
+/** Klarna/Affirm, roughly. See the note above — this is the binding one. */
+export declare const MARKETPLACE_PROCESSING_PERCENT_BNPL = 6;
+/** Stripe's per-transaction fixed component, in cents. */
+export declare const MARKETPLACE_PROCESSING_FIXED_CENTS = 30;
+/**
+ * The tax rate the break-even figure assumes. Tax is added ON TOP of the
+ * listing price and enlarges the base Stripe charges its percentage against,
+ * so it makes the platform's cost slightly worse; the real rate is whatever
+ * `automatic_tax` computes for the buyer's address, and this is the
+ * platform's own Texas rate as a representative figure.
+ */
+export declare const MARKETPLACE_ASSUMED_TAX_PERCENT = 8.25;
+/**
+ * The processing rate a STOREFRONT destination charge is priced against
+ * (AGL-2152), and the one identifier to repoint if the storefront's payment
+ * method set changes.
+ *
+ * Deliberately its OWN name rather than a direct use of the marketplace
+ * constants, while being defined as one of them: the two surfaces share
+ * Stripe's published rates and today share the platform's payment method
+ * configuration, but they are separate product decisions. A future choice to
+ * pin `payment_method_types` on storefront sessions to the card family — and
+ * so to recover at `MARKETPLACE_PROCESSING_PERCENT_CARD` — must not silently
+ * lower the marketplace listing floor, which is derived from the same figure
+ * for a different flow.
+ */
+export declare const STOREFRONT_PROCESSING_PERCENT = 6;
+/** Stripe's per-transaction fixed component, in cents. Not rate-dependent. */
+export declare const STOREFRONT_PROCESSING_FIXED_CENTS = 30;
+/** Where the money goes on one sale of a paid listing (AGL-2343). */
+export interface MarketplaceSaleEconomics {
+    /** The listing price. */
+    priceCents: number;
+    /** Added on top, and owed to the state. */
+    taxCents: number;
+    /** What the buyer is charged. */
+    buyerPaysCents: number;
+    /** `transfer_data[amount]` — the seller's share of the pre-tax price. */
+    sellerReceivesCents: number;
+    /** The platform's take. */
+    platformFeeCents: number;
+    /** Stripe's fee, debited from the platform on a destination charge. */
+    processingCents: number;
+    /** `platformFeeCents - processingCents`. Negative is a loss on the sale. */
+    platformNetCents: number;
+}
+/**
+ * The funds flow for one sale, mirroring what `checkout.ts` actually builds
+ * (AGL-2343): tax exclusive and on top, a fixed transfer of the seller's share
+ * of the PRE-tax price, and Stripe's fee charged on the buyer's total.
+ */
+export declare function marketplaceSaleEconomics(priceUsd: number, feePercent: number, processingPercent?: number): MarketplaceSaleEconomics;
+/**
+ * The cheapest WHOLE-DOLLAR price at which the platform does not lose money on
+ * a sale (AGL-2343).
+ *
+ * Whole dollars because every publish route rounds `priceUsd` to one, so a
+ * fractional break-even is not a price anyone can actually set. Searched
+ * rather than solved algebraically so that it can never disagree with
+ * `marketplaceSaleEconomics` — the rounding in there is what decides the
+ * answer at these amounts, and a closed form would drift from it silently.
+ *
+ * THIS IS THE ENFORCED FLOOR: `marketplaceMinPriceUsd` returns this figure
+ * and every publish door refuses a paid listing under it. Recorded in the Pricing
+ * Decision Log and on AGL-2343.
+ */
+export declare function marketplaceBreakEvenUsd(feePercent?: number, processingPercent?: number): number;
+/**
+ * THE MINIMUM PRICE a paid marketplace listing may carry (AGL-2343).
+ *
+ * The floor is not a chosen round number — it is the break-even price itself,
+ * the
+ * cheapest whole dollar at which `marketplaceSaleEconomics` stops returning a
+ * negative platform net, computed at the take rate that breaks even LATEST and
+ * the dearest payment method the live configuration enables. Today that is $3.
+ *
+ * DERIVED, NEVER RESTATED. A second hand-written copy of this number in a
+ * publish route or a form is the artifact that decays into a route refusing a
+ * price a form invited, so both the server-side validator
+ * (`MARKETPLACE_MIN_PRICE_USD` in the marketplace model) and every price field
+ * read this. If the payment method set changes, or the plan table's lowest
+ * take rate moves, the floor moves with them on the next call.
+ *
+ * ZERO IS NOT BELOW THE FLOOR. A free listing takes no payment at all, so it
+ * costs nothing to process; the floor is a minimum on PAID listings only.
+ */
+export declare function marketplaceMinPriceUsd(): number;
+/**
+ * Whether a price is a PAID price that the floor refuses (AGL-2343) — the one
+ * predicate a form uses to mark its price field in error and hold its publish
+ * button, so that the button and the server agree about what is publishable.
+ *
+ * Rounds first because every publish route does, and a form's value is a
+ * string mid-type: `'2.6'` is stored as $3 and must read as allowed here, or
+ * the button would refuse a price the route accepts.
+ */
+export declare function isBelowMarketplacePriceFloor(priceUsd: unknown): boolean;
+/**
+ * The sentence a publish form shows under its price field when the price is
+ * below the floor (AGL-2343), or `undefined` when there is nothing to say.
+ *
+ * NOT ADVISORY ANY MORE. The same figure is enforced by every publish route
+ * through `publishPreconditionRefusal`, so this text has to read as a
+ * requirement rather than a warning — a publisher who is told "consider
+ * raising it" and then refused has been lied to by the form. It still explains
+ * WHY, because a bare minimum with no arithmetic behind it reads as an
+ * arbitrary tax on cheap listings.
+ *
+ * Shared by every publish form rather than written into each, because the
+ * figure has to be the same one in all of them and the wording is the only
+ * place a publisher ever sees it.
+ *
+ * Quoted at the take rate that breaks even LATEST, so the sentence holds for a
+ * free-plan publisher too.
+ */
+export declare function marketplacePriceCostNote(priceUsd: unknown): string | undefined;
+/**
+ * The standing helper sentence a price field shows when there is nothing wrong
+ * (AGL-2343): the minimum stated up front, so a publisher meets it while
+ * typing instead of discovering it as a refusal.
+ *
+ * A capability that is not surfaced in the console does not count as shipped,
+ * and that applies to a REFUSAL as much as to a feature: a floor only a route
+ * knows about is a trap.
+ *
+ * @param suffix whatever else that particular form needs to say, appended.
+ */
+export declare function marketplacePriceFloorHint(suffix?: string): string;
+/**
+ * The cheapest plan whose BASE features include `feature`, in ladder order —
+ * the answer to "which plan do I need for this?", which is the one thing an
+ * upsell has to say and the one thing no gate can hard-code without drifting
+ * from the table it is quoting.
+ *
+ * Returns `undefined` when NO plan carries it on the base tier. That is not
+ * an error: `eventCalendar` is an add-on purchased through
+ * `resolveOrgEntitlements`' override path and is false on all eight tiers, so
+ * "upgrade to X" is the wrong sentence for it. Callers must handle undefined
+ * rather than defaulting to a tier name.
+ *
+ * Derived from PLAN_ENTITLEMENTS on every call rather than from a
+ * hand-written map: a table of "feature → plan" is exactly the artifact that
+ * decays silently when a tier's flags are re-cut, and it would decay into
+ * pricing copy shown to a customer.
+ *
+ * Ladder order is `SELF_SERVE_PLANS` then `enterprise` — the same order the
+ * plan grid renders — so an enterprise-only feature (`ssoEnabled`) reports
+ * Enterprise rather than nothing.
+ */
+export declare function planGrantingFeature(feature: keyof OrgFeatureFlags): OrgPlan | undefined;
+/**
+ * The plan name an upsell should name, ready to interpolate — "Business",
+ * or undefined when {@link planGrantingFeature} has no answer.
+ */
+export declare function planLabelGrantingFeature(feature: keyof OrgFeatureFlags): string | undefined;
+/**
+ * True when the org's plan (or overrides) enables the boolean feature. A
+ * key outside `OrgFeatureFlags` is one a plugin declared (AGL-2940) and is
+ * answered the same way.
+ */
+export declare function checkEntitlement(org: Partial<AglynOrgBilling> | null | undefined, feature: keyof OrgFeatureFlags | (string & {})): boolean;
+/**
+ * The branding profile shape and the platform's own fallback, re-exported
+ * for every caller that reads them alongside the entitlement gate.
+ *
+ * They are DEFINED in `platform-brand.ts`, beside the environment-driven
+ * literals they are assembled from. A published tenant page renders the
+ * attribution badge from `PLATFORM_BRANDING_PROFILE` and needs nothing else
+ * in this module; importing it from here would put the whole plan, quota and
+ * entitlement table into every anonymous visitor's first load.
+ */
+export type { ResolvedBrandingProfile } from './platform-brand';
+export { PLATFORM_BRANDING_PROFILE } from './platform-brand';
+/**
+ * The effective brand for an org (White-Label Phase 1). EVERY branded
+ * surface — published-site branding, transactional email, console chrome —
+ * MUST read the brand through this one resolver so a white-label org can
+ * never partly-render as Aglyn (the multi-surface drift that dogged
+ * `removeBranding`, which each surface re-derived on its own).
+ *
+ * When the org carries the `whiteLabel` entitlement (Agency tier, or an
+ * Enterprise per-org override), the org's `brandingProfile` values win and
+ * any field it leaves blank falls back to the Aglyn default. Without the
+ * entitlement the stored profile is ignored entirely and the full Aglyn
+ * brand is returned — so an org that white-labeled and then downgraded
+ * reverts cleanly.
+ */
+export declare function resolveBrandingProfile(org: Partial<AglynOrgBilling> | null | undefined): ResolvedBrandingProfile;
+/**
+ * The brand as MERGE TOKENS, for a staff-designed system-email template
+ * (AGL-2139).
+ *
+ * White-label inverted precisely when staff published a template, which is
+ * that feature's normal steady state. Every org-context sender has the shape
+ * `subject: designed?.subject ?? <branded fallback>` — the DESIGNED template
+ * wins — and the catalog copy hard-coded "Aglyn" throughout. There was no
+ * brand token to design against either: the merge maps carried `org.name`,
+ * `invite.role`, `signInUrl` and friends and nothing about the brand, and
+ * `blankUnresolvedTokens` BLANKS any token the caller did not supply. So a
+ * designer who reached for `{{brand.productName}}` would have shipped an
+ * email with a hole in the sentence.
+ *
+ * Token bodies are namespaced `brand.*` so a designer can tell them from the
+ * per-send values, and they resolve for EVERY org — Aglyn's own included,
+ * since `PLATFORM_BRANDING_PROFILE.productName` is `'Aglyn'`. That is what makes
+ * a single template correct for both populations instead of one hard-coded
+ * for the majority.
+ *
+ * The email LOGO is deliberately absent. It is structural — `renderEmailHtml`
+ * emits it as a header row above the designed body, or emits nothing — so it
+ * travels as an option rather than as a token a template could forget to
+ * place, and there is no sample URL a staff test-send could render without
+ * showing a broken image.
+ */
+export declare function brandMergeTokens(branding: ResolvedBrandingProfile): Record<string, string>;
+/**
+ * The value of the `<meta name="generator">` tag and of the `x-powered-by`
+ * header on published sites (AGL-2088) — the canonical CMS signal WordPress,
+ * Squarespace, Drupal and Ghost all ship, and the thing tech-stack detectors
+ * key on.
+ *
+ * Deliberately VERSIONLESS. The accidental headers this replaced carried
+ * `1.0.0-alpha.0` and a Node version, which dated every deployment and named
+ * our runtime to no consumer. A detector needs the product name and nothing
+ * else.
+ */
+export declare const PLATFORM_GENERATOR_NAME: string;
+/**
+ * May this org's published pages say they were built with Aglyn? (AGL-2088)
+ *
+ * The gate for the `<meta name="generator">` tag and the `x-powered-by`
+ * header. It reads the SAME entitlement `resolveBrandingProfile` reads —
+ * `whiteLabel` — rather than inventing a parallel one, so an agency's
+ * concealment promise has exactly one definition.
+ *
+ * WHY `whiteLabel` AND NOT `showBranding`. The "Made with Aglyn" badge is
+ * gated on `removeBranding`, which every plan above free grants, so reusing
+ * that gate would confine the signal to free-tier sites — the corpus this
+ * exists to build would be almost empty on day one. The two promises are also
+ * different in kind: `removeBranding` buys a page with no Aglyn credit on it,
+ * an aesthetic commitment about what a VISITOR sees; `whiteLabel` buys
+ * concealment of who built the site, which is the promise a machine-readable
+ * fingerprint actually breaks. A paying customer on a mid plan has bought a
+ * clean page, not anonymity.
+ *
+ * ⚠️ AN UNRESOLVED ORG SUPPRESSES, and this is the whole reason the function
+ * exists instead of a bare `!checkEntitlement(org, 'whiteLabel')` at each call
+ * site. `resolveOrgEntitlements(null)` resolves to the FREE plan — a loading
+ * default answering a question it was never asked — so a null org reads as
+ * "no white-label" and would EMIT. That null is not hypothetical: the tenant's
+ * `getOrgBilling` fails open with `org: null` on a Firestore error, so a
+ * transient read failure on an Agency site would have stamped the generator
+ * tag onto it. The asymmetry decides the direction: suppressing wrongly costs
+ * us one detection sample, emitting wrongly breaks a paid promise on a
+ * customer's own domain. So the org must be PRESENT and lack the entitlement;
+ * absent is not the same as free here.
+ */
+export declare function showsPlatformAttribution(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * Whether the org has actually **configured** a white-label brand (AGL-1110) —
+ * a non-empty product name or logo. White-label chrome should activate only
+ * when this is true, not merely because the plan grants the `whiteLabel`
+ * entitlement: an Agency org (or a comped Enterprise org) that never set up a
+ * brand keeps the plain Aglyn wordmark — no product-name-text render, no
+ * flash — until it opts in on the branding page.
+ */
+export declare function hasBrandingProfile(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * Quota check: `allowed` is false once `currentUsage` meets the limit —
+ * call before creating the next resource (e.g. usage=hostCount before
+ * creating another host). `remaining` never goes negative.
+ */
+/**
+ * `members` = per-site collaborator seats (legacy key, AGL-888): the key
+ * matches persisted `seatAddons.members` and must not be renamed.
+ */
+export type SeatKind = 'managers' | 'members';
+export interface SeatQuotaResult {
+    /** False once usage meets the effective limit (included + purchased). */
+    allowed: boolean;
+    /** Effective seat limit: included + purchased addons, clamped to the max. */
+    limit: number;
+    remaining: number;
+    /** Included seats on the plan before addons. */
+    included: number;
+    /** Purchased addon seats currently applied. */
+    purchased: number;
+    /** Hard cap incl. addons; reaching it requires a plan upgrade. */
+    maxSeats: number;
+    /**
+     * True when buying more addon seats cannot raise the limit — either the
+     * plan sells no addons or the hard cap is reached. UI should prompt an
+     * upgrade instead of an addon purchase.
+     */
+    upgradeRequired: boolean;
+    /** Monthly price per addon seat; null when the plan sells none. */
+    addonPriceUsd: number | null;
+}
+/**
+ * Seat quota check (AGL-112): seats differ from plain quotas because orgs
+ * can buy addon seats (`org.seatAddons`) up to a per-plan hard max —
+ * beyond the max the only path is upgrading the plan. `managers` counts
+ * org-manager seats org-wide; `members` counts per-site COLLABORATORS
+ * (`hosts/{id}/members`, viewer/editor/admin — legacy key name, AGL-888).
+ * End-user member accounts (`siteMembers`) are unlimited and never pass
+ * through here.
+ *
+ * SINCE AGL-2439 THIS IS THE PLAN'S CAP FOR `members`, with no purchased
+ * seats in it — see the comment at the add below. A per-site answer must come
+ * from `checkHostCollaboratorQuota(org, hostId, used)`, which is the only
+ * thing that knows which site holds which pool seat. Every caller that has a
+ * `hostId` must use that one; this stays correct for a plan-level readout
+ * (what the plan includes per site, before anything is assigned).
+ */
+export declare function checkSeatQuota(org: Partial<AglynOrgBilling> | null | undefined, kind: SeatKind, currentUsage: number): SeatQuotaResult;
+export declare function checkQuota(org: Partial<AglynOrgBilling> | null | undefined, quota: keyof Omit<ResolvedOrgEntitlements, 'features'>, currentUsage: number): {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+};
+export interface DatasetQuotaResult {
+    /** False once usage meets the effective limit (included + purchased). */
+    allowed: boolean;
+    /** Effective dataset limit: included + purchased, clamped to the max. */
+    limit: number;
+    remaining: number;
+    included: number;
+    purchased: number;
+    maxDatasets: number;
+    /** True when addons cannot raise the limit — upgrade instead. */
+    upgradeRequired: boolean;
+    /** Monthly price per extra dataset; null when the plan sells none. */
+    addonPriceUsd: number | null;
+}
+/**
+ * Dataset quota check (AGL-132/240), mirroring `checkSeatQuota`: orgs can
+ * buy addon datasets (`org.seatAddons.datasets`, org-wide) up to the
+ * plan's hard max; beyond the max the only path is upgrading.
+ */
+export declare function checkDatasetQuota(org: Partial<AglynOrgBilling> | null | undefined, currentUsage: number): DatasetQuotaResult;
+export interface DataStorageQuotaResult {
+    /**
+     * False only when the plan hard-blocks (no overage pricing) and usage
+     * meets the included size; metered plans always allow and bill overage.
+     */
+    allowed: boolean;
+    /** Included dataset storage on the plan, MB. */
+    includedMb: number;
+    usedMb: number;
+    /** Remaining included storage, MB; 0 once into overage. */
+    remainingMb: number;
+    /** Usage beyond the included size, GB (0 when within the plan). */
+    overageGb: number;
+    /** Estimated overage this month at the plan's per-GB rate. */
+    overageMonthlyUsd: number;
+    /** Per-GB-month overage rate; null when the plan meters nothing. */
+    overageRateUsd: number | null;
+}
+/**
+ * Org dataset-storage meter (AGL-240): aggregate stored document bytes
+ * across `orgs/{orgId}/datasets`. Plans with an `extraDataGbMonthlyUsd`
+ * rate meter the overage onto the monthly invoice (cost-plus, AGL-41);
+ * plans without one (free) hard-block at the included size.
+ */
+export declare function checkDataStorageQuota(org: Partial<AglynOrgBilling> | null | undefined, usedMb: number): DataStorageQuotaResult;
+export interface ApiRequestQuotaResult {
+    /** Metered plans always allow; plans without API access block. */
+    allowed: boolean;
+    /** Included requests this month at the plan. */
+    included: number;
+    used: number;
+    /** Remaining included requests; 0 once into overage. */
+    remaining: number;
+    /** Requests beyond the included quota (0 within the plan). */
+    overageRequests: number;
+    /** Estimated overage this month at the plan's per-1,000 rate. */
+    overageMonthlyUsd: number;
+    /** Per-1,000 overage rate; null when the plan has no API. */
+    overageRateUsd: number | null;
+}
+/**
+ * Customer REST API request meter (AGL-634): the monthly request count for an
+ * org. Business and every tier above it carry `apiAccess` and an
+ * `extraApiRequestsUsdPer1k` rate, so requests past the included quota meter
+ * onto the monthly invoice
+ * (cost-plus, like storage overage — never a hard wall mid-integration); plans
+ * without API access have `included: 0` and always block.
+ */
+export declare function checkApiRequestQuota(org: Partial<AglynOrgBilling> | null | undefined, usedRequests: number): ApiRequestQuotaResult;
+export interface CrmRecordsQuotaResult {
+    /** Metered plans always allow; free hard-bands at the included count. */
+    allowed: boolean;
+    /** Included CRM records on the plan — the `contactsPerHost` band. */
+    included: number;
+    /** Contacts + companies + deals, as the caller counted them. */
+    used: number;
+    /** Remaining included records; 0 once into overage. */
+    remaining: number;
+    /** Records beyond the included band (0 within the plan). */
+    overageRecords: number;
+    /** Estimated overage this month at the plan's per-1,000 rate. */
+    overageMonthlyUsd: number;
+    /** Per-1,000 overage rate; null when the plan hard-bands (free). */
+    overageRateUsd: number | null;
+}
+/**
+ * The name this result carried while the band counted contacts alone.
+ * @deprecated Read `CrmRecordsQuotaResult`; the shape is the same.
+ */
+export type ContactQuotaResult = CrmRecordsQuotaResult;
+/**
+ * CRM records band meter (AGL-890, widened in AGL-2611): contacts, companies
+ * and deals, counted together across the org and measured against the ONE
+ * band `contactsPerHost` names. Paid plans carry an `extraContactsUsdPer1k`
+ * rate, so records past the included band meter onto the monthly invoice
+ * (cost-plus, like storage and API overage — a growing audience is never
+ * dropped); free has no rate and hard-bands at the included count, refusing
+ * the next record of any of the three kinds.
+ *
+ * ONE band for three collections, and not three bands, because a company or
+ * a deal costs less to hold than a contact — a ~2 KB document with few index
+ * entries and no dynamic-list scan — so counting them at the contacts rate
+ * over-covers them, and a second and third number to explain would buy
+ * nothing a customer could act on. The caller passes the SUM; the server
+ * helper that takes the three aggregate reads is `countCrmRecords`, and the
+ * billing meter shows the three components in its caption so the sum is
+ * legible rather than opaque. Tasks and activities are not counted: they
+ * are bounded by human effort, and the activity log is capped per record by
+ * `CRM_ACTIVITIES_PER_RECORD_CEILING` instead.
+ *
+ * End-user member ACCOUNTS are unlimited on every plan (AGL-889) — this
+ * meters only the CRM record.
+ */
+export declare function checkCrmRecordsQuota(org: Partial<AglynOrgBilling> | null | undefined, usedRecords: number): CrmRecordsQuotaResult;
+/**
+ * The name the band's gate carried while it counted contacts alone. The SAME
+ * function — every caller that still says "contact" is measuring the records
+ * band and must hand it the summed count, not the contacts aggregate.
+ * @deprecated Call `checkCrmRecordsQuota`.
+ */
+export declare const checkContactQuota: typeof checkCrmRecordsQuota;
+/**
+ * `orgs/{orgId}/crmEmailUsage/{YYYY-MM-DD}` — the durable per-day counter of
+ * one-to-one CRM emails, `{ count, day, updatedAt }`, server-written only and
+ * member-readable, exactly as `apiUsage/{month}` is for API requests.
+ */
+export declare const CRM_EMAIL_USAGE_COLLECTION = "crmEmailUsage";
+/**
+ * The document id of today's one-to-one email counter, `YYYY-MM-DD` in UTC.
+ *
+ * UTC rather than the workspace's zone, for the reason `apiUsageMonth` keys
+ * the API counter in UTC: the cap is enforced on a server that has no zone
+ * of the customer's to read, and a boundary that moved with a browser's
+ * clock would let one day's sends be counted against two.
+ */
+export declare function crmEmailUsageDayKey(now?: Date): string;
+export interface CrmEmailQuotaResult {
+    /** Whether ONE MORE send is inside today's cap. Enterprise always allows. */
+    allowed: boolean;
+    /** The plan's daily cap; 0 where the tier has no CRM. */
+    included: number;
+    /** Sends already counted today. */
+    used: number;
+    /** Sends left today; 0 at the cap. */
+    remaining: number;
+    /** When the counter rolls over — the next UTC midnight. */
+    resetsAt: Date;
+}
+/**
+ * One-to-one CRM email cap (AGL-2611): how many messages a workspace may
+ * still send from CRM records today, mirroring `checkApiRequestQuota`.
+ *
+ * A HARD cap with no overage rate, on every tier — the one respect in which
+ * it differs from the API meter it is shaped after. `allowed` is therefore
+ * `used < included` outright. Every paid tier's cap is finite, Enterprise's
+ * 2,000 included, and 0 on Free makes it false at zero, so a per-org
+ * `features.crm` grant does not send until `crmEmailsPerDay` is raised
+ * beside it.
+ *
+ * ## The contract for the send route
+ *
+ * The route that sends a one-to-one email takes the send as a SLOT on
+ * `orgs/{orgId}/crmEmailUsage/{crmEmailUsageDayKey()}` inside one Firestore
+ * transaction — `reserveCrmEmailSend` in `@aglyn/tenant-data-admin` reads
+ * `count`, calls this with that figure, REFUSES with the plan reason when
+ * `allowed` is false and otherwise writes `used + 1` in the same transaction
+ * (AGL-2645). A read-then-write cap let two reps at the last slot both pass
+ * one reading of it; the transaction re-runs the second on the raised
+ * figure. The slot is taken before the message leaves and handed back by
+ * `releaseCrmEmailSend` when the provider refuses it. A delivered send is
+ * then recorded on the org's `emailSends` cost meter through
+ * `recordEmailSends` as `transactional`, because every message the provider
+ * charged for is priced into COGS and the campaign cap does not govern it.
+ * The count enforced is the count billed, from one document, the way the
+ * API meter works.
+ *
+ * Read the counter with `used` from the server: the console meter on the
+ * billing page reads the same document, member-readable, so a rep is never
+ * told their limit by being refused.
+ */
+export declare function checkCrmEmailQuota(org: Partial<AglynOrgBilling> | null | undefined, usedToday: number, now?: Date): CrmEmailQuotaResult;
+/**
+ * Volume above the plan's included band, in emails.
+ *
+ * Transactional mail is never refused, so an org CAN and will finish a month
+ * over its included allowance. That is not an error and not a failed send —
+ * it is the overage the cap chose not to enforce, and recording it is what
+ * keeps it from being a surprise at invoicing. `UNLIMITED` (and any
+ * non-positive limit, which is how "no included allowance" is expressed)
+ * yields 0 rather than the whole month's volume.
+ *
+ * DEFINED HERE and re-exported from `email-metering.ts` (AGL-2155's move):
+ * the billing page renders this figure before anything is invoiced, and it
+ * is a client component that cannot pull in the Admin SDK. One subtraction,
+ * so the readout and the invoice cannot disagree.
+ */
+export declare function emailSendsOverage(total: number, limit: number): number;
+export interface EmailSendOveragePrice {
+    /** Emails past the plan's included band, as handed in. */
+    overageSends: number;
+    /** Estimated charge this month at the plan's per-1,000 rate. */
+    overageMonthlyUsd: number;
+    /** Per-1,000 rate; null when the plan carries no email overage price. */
+    overageRateUsd: number | null;
+}
+/**
+ * Prices email volume past a plan's included band.
+ *
+ * ## No `allowed`, deliberately
+ *
+ * Every other meter's helper here answers "may this proceed" alongside "what
+ * does it cost", because on those axes one gate decides both. Email has two
+ * gates that are not the same gate: `reserveCampaignEmailSends` refuses a
+ * CAMPAIGN at the band inside a transaction, and nothing at all refuses
+ * transactional mail at any tier. A field named `allowed` on this result
+ * would be a plausible-looking thing for a sender to consult, and a
+ * transactional sender consulting it is how a password reset stops going out.
+ * So the result carries money and nothing else.
+ *
+ * ## Takes the overage, does not recompute it
+ *
+ * `emailSendsOverage` already derives the excess from the cost meter and the
+ * resolved band, on the path that records it. Re-deriving it here from a raw
+ * total would be a second overage model to drift from the first — which is
+ * the shape AGL-1402 documented, where two figures that should have been one
+ * disagreed by 20-45% for years.
+ *
+ * A null rate yields zero, structurally rather than by a check, which is what
+ * keeps free at zero on this axis for the same reason it is zero on the other
+ * three.
+ */
+export declare function priceEmailSendOverage(org: Partial<AglynOrgBilling> | null | undefined, overageSends: number): EmailSendOveragePrice;
+/**
+ * Is this org's plan subject to the metered infrastructure pass-through
+ * (AGL-1280)? The single answer behind three otherwise-unrelated behaviours:
+ * whether storage/bandwidth/form usage past the included band is BILLED, and
+ * whether the form-submission cap is a wall or a meter.
+ *
+ * Deliberately a plan-level question, not an org-level one — an org with no
+ * plan resolves as free, so an unknown org meters nothing. Billing usage to
+ * someone with no subscription is the one error direction with no recovery.
+ * A staff comp is that someone too (AGL-3034): it grants a paid plan with no
+ * subscription behind it, so `resolvePlanPricing` answers `false` for it and
+ * its bands are walls.
+ */
+export declare function planMetersInfraOverage(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+export interface FormSubmissionQuotaResult {
+    /**
+     * False only when the plan hard-caps (no metered pass-through) and usage
+     * has reached the included count; metered plans always accept and bill
+     * the excess.
+     */
+    allowed: boolean;
+    /** Included submissions this month for this site. */
+    included: number;
+    used: number;
+    /** Remaining included submissions; 0 once into overage. */
+    remaining: number;
+    /** Submissions beyond the included count (0 within the plan). */
+    overageSubmissions: number;
+    /** True when overage meters instead of blocking. */
+    metered: boolean;
+}
+/**
+ * Monthly form-submission meter (AGL-76, made coherent in AGL-1280).
+ *
+ * Submissions were BOTH hard-capped at `formSubmissionsPerMonth` (429) and
+ * metered — which made the published promise that usage past the
+ * included band is billed rather than cut off false for the one meter where
+ * being cut off costs the customer a lead. Now it mirrors the other three
+ * overage meters exactly: a plan with the metered pass-through always accepts
+ * and prices the excess (`estimateMonthlyUsageCost`); free has no
+ * subscription to bill, so its included count stays a hard wall.
+ *
+ * Priced per ORG at cost-plus, but capped per SITE, because that is where the
+ * counter lives (`hosts/{id}/counters/formSubmissions`). Callers gating a
+ * single submission pass that site's month count.
+ */
+export declare function checkFormSubmissionQuota(org: Partial<AglynOrgBilling> | null | undefined, usedThisMonth: number): FormSubmissionQuotaResult;
+/**
+ * How far past a plan's own included band the abuse ceiling sits (AGL-1655).
+ * Ten times what the customer bought is not growth — a site that legitimately
+ * outgrows its band by an order of magnitude has an upgrade conversation
+ * waiting, not a silent invoice.
+ */
+export declare const FORM_ABUSE_CEILING_MULTIPLE = 10;
+/**
+ * Absolute floor for the abuse ceiling, so the small plans get real headroom
+ * rather than a second, tighter plan limit wearing a different name. Starter
+ * includes 200/month; 10× would be 2,000, which a genuinely busy site could
+ * reach. 5,000 is ~167 submissions a day on ONE site — no legitimate site on
+ * a small plan reaches that, and no small customer can be billed past
+ * 5,000 × $0.000065 ≈ $0.33 of abuse.
+ */
+export declare const FORM_ABUSE_CEILING_FLOOR = 5000;
+/**
+ * Ceiling for plans whose included count is UNLIMITED (Agency, Enterprise),
+ * where a multiple has nothing to multiply. Kept at or above the ceiling of
+ * every finite plan below it (Advanced includes 100,000 → 1,000,000) so the
+ * ladder never inverts and a bigger plan never gets the smaller ceiling.
+ */
+export declare const FORM_ABUSE_CEILING_UNLIMITED = 1000000;
+export interface FormAbuseCeilingResult {
+    /** True once this month's count for the SITE has reached the ceiling. */
+    exceeded: boolean;
+    /** The ceiling this site's plan resolves to. Always finite. */
+    ceiling: number;
+    used: number;
+}
+/**
+ * Per-site monthly abuse ceiling for form submissions (AGL-1655).
+ *
+ * Deliberately NOT part of `checkFormSubmissionQuota`. That function answers
+ * a plan question — "did the customer buy this?" — and AGL-1280 correctly
+ * made its answer on a metered plan always yes, because usage past the band
+ * bills rather than blocks. This one answers a different question: "is this
+ * still a customer's traffic at all?" Conflating them is how the plan gate
+ * ended up as the anti-abuse control it was never designed to be, and how
+ * `allowed: metered ? true : …` came to mean an unbounded bill.
+ *
+ * So the ceiling is containment, not capacity. It is far above anything a
+ * legitimate site reaches, it is the same shape on every plan, and crossing
+ * it is an INCIDENT: the caller is expected to refuse the write, leave the
+ * billable counter alone, and make the trip visible to the site's managers
+ * and to staff. A ceiling that silently absorbed submissions would only move
+ * the free plan's lost-lead failure up to a bigger number.
+ *
+ * Evaluated against the same month counter the plan gate reads — which is
+ * Admin-SDK-only (`counters` is excluded from every client write in
+ * `cloud/firebase-firestore.rules`), so the count behind the ceiling cannot
+ * be lowered to launder past it.
+ */
+export declare function checkFormSubmissionAbuseCeiling(org: Partial<AglynOrgBilling> | null | undefined, usedThisMonth: number): FormAbuseCeilingResult;
+/**
+ * Average transfer per page view (HTML + JS + a few images), the constant
+ * that turns the analytics view counter into a bandwidth number and back.
+ *
+ * ## ⛔ HALF OF A PAIR. It moves with `perPageView`, or neither moves.
+ *
+ * This is the BYTES one page view weighs;
+ * {@link ORG_COGS_UNIT_RATES_USD}`.perPageView` is the DOLLARS the same page
+ * view costs. They are one physical measurement written in two units, and
+ * what every `bandwidthGb` band is actually sized against is neither of them
+ * alone but their quotient — `(1 GB ÷ this) × perPageView`, the cost of a
+ * gigabyte. That quotient is stable even while the page's weight is not,
+ * which is precisely why moving one half re-prices every band on the ladder
+ * without touching a band: a heavier page costs more per view and buys fewer
+ * views per gigabyte, and the two cancel.
+ *
+ * Both are therefore stated against the SAME weight — **1012.8 KB**, the
+ * basis recorded in `tools/tenant-page-budget.json` and recoverable from the
+ * rate itself — and `npm run check:page-view-rate` compares the two and
+ * refuses a mismatch. There is no version of this constant that is correct
+ * against a `perPageView` calibrated for a different page.
+ *
+ * The basis is FIRST-PARTY encoded bytes at settle, because that is what an
+ * egress bill is denominated in: third-party tags leave someone else's
+ * network and cost the platform nothing, so counting them here would inflate
+ * a customer's measured bandwidth with bytes nobody pays us for.
+ *
+ * Lives HERE rather than beside the metering rates (AGL-2155). It used to sit
+ * in `apps/console/utils/usage-metering.ts`, which the console imports and the
+ * tenant app cannot — and the bandwidth ceiling below has to be evaluated in
+ * the tenant app, at the beacon that writes the counter. Re-deriving the
+ * conversion there would have been a fourth hand-rolled copy of
+ * `× 1024³ / page weight`, which is the exact drift AGL-1371 collapsed into
+ * one function. `usage-metering` now re-exports these three, so every existing
+ * importer is unchanged and there is still one definition.
+ */
+export declare const ESTIMATED_PAGE_TRANSFER_BYTES: number;
+/**
+ * Bandwidth ⇄ page views: the one conversion three surfaces used to each
+ * write out by hand (AGL-1371).
+ *
+ * `bandwidthGb` is not a second cap next to metered page views — it IS the
+ * included band of the page-view meter, expressed in the unit customers
+ * understand. It is therefore used in both directions: forward by
+ * `meteredIncludedAllowance` to size the band the invoice subtracts, backward
+ * by the usage-alerts cron and the console meter to render live page views as
+ * GB.
+ */
+export declare function pageViewsFromBandwidthGb(bandwidthGb: number): number;
+/** @see pageViewsFromBandwidthGb — the same constant, the other way. */
+export declare function bandwidthGbFromPageViews(pageViews: number): number;
+/**
+ * How far past a plan's own included bandwidth the abuse ceiling sits
+ * (AGL-2155). Three times the bandwidth the customer bought is not growth; it
+ * is an upgrade conversation, or it is not the customer's traffic at all.
+ *
+ * It is a CAP, not a price, and it is lower than {@link
+ * FORM_ABUSE_CEILING_MULTIPLE} because bandwidth is the largest cost line the
+ * platform carries and the one a stranger can spend on the customer's behalf.
+ * Past the band every 1,000 views bills $0.21 against about $0.16 of real
+ * cost, so the tail is no longer a loss — but a scraper, a hotlinked asset or
+ * a botnet still bills the account holder for traffic they did not ask for,
+ * and the ceiling is what bounds that before staff look at it. At 10× the
+ * band that tail was open-ended on Agency; at 3× it is bounded.
+ */
+export declare const BANDWIDTH_ABUSE_CEILING_MULTIPLE = 3;
+/**
+ * Absolute floor for the bandwidth ceiling, in PAGE VIEWS per month, so the
+ * small plans get real headroom instead of a second, tighter plan limit
+ * wearing a different name.
+ *
+ * Free includes 2 GB ≈ 2,071 views; 3× would be ~6,212, which a genuinely
+ * successful hobby site (a post that lands on Hacker News) reaches in an
+ * afternoon and would be a miserable first experience of the platform.
+ * 100,000 views/month ≈ 96.6 GB ≈ **$16 of real COGS** at
+ * `METERED_UNIT_RATES_USD.perPageView` — well above the free band, and an
+ * order of magnitude below the $162 a million views costs. It is the number
+ * that makes "free stays free" true without making it stingy.
+ */
+export declare const BANDWIDTH_ABUSE_CEILING_FLOOR = 100000;
+/**
+ * Ceiling for an org whose bandwidth band resolves to UNLIMITED — a
+ * contracted per-org override, since no plan row carries the sentinel any
+ * more — where a multiple has nothing to multiply. Kept at or above the
+ * ceiling of every finite band below it so the ladder never inverts and a
+ * bigger plan never inherits a smaller ceiling.
+ */
+export declare const BANDWIDTH_ABUSE_CEILING_UNLIMITED = 500000000;
+/**
+ * Machine-readable marker for a bandwidth containment, so a capped response
+ * is distinguishable from the maintenance/lockdown notices it shares a shell
+ * with. Deliberately NOT a {@link LockdownReasonCode}: a lockdown is a staff
+ * takedown, this is a billing containment that clears itself at the month
+ * boundary with nobody doing anything.
+ */
+export declare const BANDWIDTH_CEILING_CODE = "bandwidth_ceiling";
+export interface BandwidthAbuseCeilingResult {
+    /** True once this month's page views for the SITE reached the ceiling. */
+    exceeded: boolean;
+    /** The ceiling this site's plan resolves to, in page views. Finite. */
+    ceiling: number;
+    used: number;
+}
+/**
+ * Per-site monthly bandwidth abuse ceiling (AGL-2155).
+ *
+ * ## The hole this closes
+ *
+ * Every other free dimension had a runtime brace — `mediaStorageGate`,
+ * `checkFormSubmissionQuota`, a zero band for dataset storage and API, a
+ * hard band for contacts. Bandwidth had **none**: nothing anywhere refused a
+ * page view, so a free site that went viral served a million views — roughly
+ * **$162 of real COGS** — with no wall, no throttle and no alert. It was
+ * protected only by the structural zero on the billing side (free carries no
+ * rate, so the invoice stays $0), which protects the *bill* and not the
+ * *bleeding*. `free-tier-never-billed.spec.ts` said so in its own table.
+ *
+ * ## Why an abuse ceiling and not a plan gate
+ *
+ * Exactly the distinction {@link checkFormSubmissionAbuseCeiling} draws, and
+ * for the same reason. A plan gate answers "did the customer buy this?" — and
+ * for a metered plan the answer past the band is *yes, and we bill it*. This
+ * answers "is this still a customer's traffic at all?", and crossing it is an
+ * INCIDENT rather than a quota: the site is flagged, staff are told, and the
+ * render path degrades to a static notice instead of paying ~40 Firestore
+ * reads and ~1,013 KB of egress per view.
+ *
+ * ## Where it is evaluated
+ *
+ * NOT in the render path. The page-view counter is written *after* the render
+ * by `/api/analytics/collect`; that route evaluates this on a sampled cadence
+ * and stamps `bandwidthCeiling` onto the host document. The render path reads
+ * that field off a host doc **it already loads** (`load-page-data.ts` reads
+ * `hostRes.host` for the lockdown branch), so the containment costs the happy
+ * path exactly zero extra reads.
+ *
+ * An edge/CDN rule would be the other natural home and is deliberately not
+ * the answer here: it is not a repo change, nothing in this suite could
+ * verify it, and it cannot see which plan a host is on.
+ */
+export declare function checkBandwidthAbuseCeiling(org: Partial<AglynOrgBilling> | null | undefined, usedPageViewsThisMonth: number): BandwidthAbuseCeilingResult;
+/**
+ * Does crossing the ceiling **degrade what visitors see**, or only raise the
+ * incident? (AGL-2155)
+ *
+ * Only on a plan that does NOT meter the infra pass-through — which today is
+ * free/hobby, where the requirement is that free always actually stays free.
+ * On free the traffic is uncompensated, so serving it is a
+ * straight loss and the least destructive way to stop the bleeding is to stop
+ * paying for the expensive render.
+ *
+ * On a metered plan the same traffic is *invoiced*, so taking a paying
+ * customer's site off the air would trade a bill they agreed to for an outage
+ * they did not. Their ceiling still trips, still flags the host and still
+ * escalates to staff — it just does not change what a visitor gets. Whether a
+ * paying host past its OWN ceiling should also be degraded is a product call
+ * and is left open on purpose; flipping it is this one function.
+ *
+ * Enterprise does not meter either, and is NOT degraded, for the same reason
+ * a metered plan is not: its traffic is paid for, by agreement rather than by
+ * invoice. Since 2026-09-07 its bandwidth band is a finite fallback (twice
+ * Agency's), so without this exclusion the ceiling an agreement never named
+ * would have taken a contracted customer's site off the air three times past
+ * a default nobody chose for them. It still trips, flags and pages.
+ */
+export declare function bandwidthCeilingDegradesRender(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * `hosts/{id}.bandwidthCeiling` — the flag the beacon stamps and the render
+ * path reads. Month-scoped so it **self-clears at the month boundary** with
+ * no staff action and no write, the same property `LockdownState.untilMs`
+ * has: a site contained in August serves normally on September 1.
+ *
+ * Admin-SDK-only. It is frozen against client writes in
+ * `cloud/firebase-firestore.rules` alongside the `suspendedAt` family, for
+ * the identical reason: a site that could clear its own containment does not
+ * have one.
+ */
+export interface HostBandwidthCeiling {
+    /** `YYYY-MM` (UTC) the trip belongs to. */
+    month: string;
+    /** The ceiling that was crossed, in page views. */
+    ceiling: number;
+    /** The month count observed when it tripped. */
+    used: number;
+    trippedAtMs: number;
+    /** False when the plan meters the overage — flagged, not degraded. */
+    degraded: boolean;
+}
+/**
+ * Read the host document's containment flag, tolerantly. Returns null unless
+ * the flag is present, well-formed AND belongs to `month` — an August trip
+ * must not silence a September visitor.
+ */
+export declare function normalizeHostBandwidthCeiling(host: Record<string, any> | null | undefined, month: string): HostBandwidthCeiling | null;
+/**
+ * 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.
+ */
+export declare function bandwidthCeilingDegradesHost(host: Record<string, any> | null | undefined, month: string): boolean;
+/** UTC `YYYY-MM`, the key both the beacon and the render path agree on. */
+export declare function bandwidthCeilingMonthKey(now?: Date): string;
+/**
+ * Visitor-facing copy for a contained site. Says what happened and that it
+ * ends, and names nothing about the plan, the count or the owner — this is
+ * read by a stranger to the site, exactly like the form ceiling's refusal
+ * body (AGL-1666).
+ */
+export declare function bandwidthCeilingNotice(): {
+    title: string;
+    body: string;
+};
+/**
+ * What a quota check costs a caller that intends to ENFORCE it (AGL-2163).
+ *
+ * `checkDataStorageQuota` and `checkApiRequestQuota` each carry an `allowed`
+ * field, and their docblocks promise it refuses — "plans without one (free)
+ * hard-block at the included size", "plans without API access have
+ * `included: 0` and always block". Nothing read it. Both functions appeared
+ * only in `/api/billing/report-usage`, which reads `overageMonthlyUsd` and
+ * ignores `allowed`, so the promise was documentation and the free tier's
+ * "runtime braces" on those two dimensions did not exist.
+ *
+ * Enforcing them naively means measuring first, and for dataset storage the
+ * measurement is O(datasets) reads — far too much for a per-record write.
+ * This makes the cheap answer available: for every plan shipping today the
+ * verdict does not depend on the measurement at all, because a plan either
+ * has an overage RATE (then it always allows and meters) or a band of zero
+ * (then it always refuses). Measuring is required only for the shape a staff
+ * `entitlementOverrides` can create — a finite, non-zero band on a plan with
+ * no rate — and only then does the caller pay a read.
+ *
+ * - `'always-blocks'` — refuse now; no measurement, no read.
+ * - `'never-blocks'` — proceed; no measurement, no read. **This is every
+ *   metered/paid plan**, so enforcement costs a paying customer nothing and
+ *   can never refuse them.
+ * - `'measure'` — the verdict depends on usage; measure and call the check.
+ */
+export type QuotaEnforcementShape = 'always-blocks' | 'never-blocks' | 'measure';
+/**
+ * Enforcement shape of {@link checkDataStorageQuota} for this org, before
+ * anything has been measured. @see QuotaEnforcementShape
+ */
+export declare function dataStorageEnforcementShape(org: Partial<AglynOrgBilling> | null | undefined): QuotaEnforcementShape;
+/**
+ * Enforcement shape of {@link checkApiRequestQuota} for this org, before
+ * anything has been measured. @see QuotaEnforcementShape
+ */
+export declare function apiRequestEnforcementShape(org: Partial<AglynOrgBilling> | null | undefined): QuotaEnforcementShape;