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

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

@@ -928,26 +928,51 @@ export declare const INFRA_COGS_PER_SITE_USD = 2;
  * where the page's generator can read it.
  *
  * The console keeps importing it from `usage-metering` unchanged.
+ *
+ * It is the margin KEPT: cost + 30% after Stripe's processor fee, not before
+ * it (AGL-3476). A price of cost × 1.3 kept cost × 1.26 once 2.9% came off,
+ * so the published rates are set by {@link METERED_PRICE_MULTIPLE}, and this
+ * stays the figure every full-utilization rule is held to.
  */
 export declare const METERED_MARKUP = 1.3;
 /**
- * What the CDN requests behind ONE page view cost once the platform is past
- * its hosting plan's included request allowance, at the DEAREST region the
- * CDN bills, in USD per view (AGL-1879, AGL-3444). A page view billed past a
- * plan's band is priced at `(perPageView + this) × METERED_MARKUP` — $0.70
- * per 1,000 — and every `bandwidthGb` band is sized with it counted.
+ * What a passed-through cost is multiplied by to reach its price, so that
+ * cost + 30% survives Stripe's percentage fee: 1.3 ÷ 0.971 ≈ 1.3388
+ * (AGL-3476). The fixed 30¢ is paid by the subscription charge the overage
+ * rides on, so only the percentage is grossed up.
+ */
+export declare const METERED_PRICE_MULTIPLE: number;
+/**
+ * A published overage price: `costPerQuotedUnitUsd` × {@link
+ * METERED_PRICE_MULTIPLE}, rounded UP at the `decimals` it is quoted in, so
+ * the price the page prints and the invoice bills is the same round figure
+ * and never less than the rule. The product is settled to six places before
+ * the ceiling so a figure that is exact in decimal — or a pinned cost carried
+ * to eleven places, like the page-view pair — is not lifted a step by its
+ * tail.
+ */
+export declare function publishedMeteredPrice(costPerQuotedUnitUsd: number, decimals: number): number;
+/**
+ * What the REQUESTS behind ONE page view cost once the platform is past its
+ * hosting plan's included request allowance, at the DEAREST region the CDN
+ * and functions bill, in USD per view (AGL-1879, AGL-3444): the CDN requests
+ * a cold load makes, and the one of them that reaches a function — the
+ * analytics beacon. A page view billed past a plan's band is priced at
+ * `(perPageView + this) × METERED_MARKUP` — $0.80 per 1,000 — and every
+ * `bandwidthGb` band is sized with it counted.
  *
  * ## Why a page view needs a second cost term
  *
- * `perPageView` prices what a view WEIGHS: the bytes it transfers at the
- * CDN's per-GB rate, plus the Firestore reads behind the render. The CDN also
- * charges per REQUEST once the team's monthly allowance is spent — Vercel Pro
- * includes 10,000,000 a month, then bills $2.00 to $3.20 per million by
- * region. A cold load of `aglyn.com/` makes 57 first-party requests to settle
- * (`tools/tenant-page-budget.json`, `wireCalibration.measuredAgainst`), so the
- * allowance is about 175,000 views of that page a month, platform-wide —
- * about 169 GB of included bandwidth — where the 1 TB transfer allowance
- * lasts about 1.4 million. The request allowance runs out first.
+ * `perPageView` prices what a view WEIGHS: the bytes it transfers, plus the
+ * Firestore reads behind the render. A view also costs per REQUEST, which is
+ * not proportional to weight: Vercel Pro includes 10,000,000 CDN requests a
+ * month, then bills $2.00 to $3.20 per million by region, and a cold load of
+ * `aglyn.com/` makes 57 first-party requests to settle
+ * (`tools/tenant-page-budget.json`, `wireCalibration.measuredAgainst`) — so
+ * the allowance is about 175,000 views a month, platform-wide, and runs out
+ * long before the transfer allowance. One of those requests is the analytics
+ * beacon (`apps/tenant/app/api/analytics/collect`), which runs a function on
+ * every view and writes two counter documents.
  *
  * ## Why the dearest region
  *
@@ -956,27 +981,29 @@ export declare const METERED_MARKUP = 1.3;
  * São Paulo or Cape Town costs what those regions cost, and nothing about a
  * plan can choose otherwise. The platform's rule is that no plan is under
  * water at any utilization and that "at cost + 30%" is true of every billed
- * unit, so both terms of a page view are priced where the CDN is dearest:
- * transfer at $0.35 per GB (in `perPageView`) and requests at $3.20 per
- * million (here). Past the allowance a view then costs:
- *
- * |                                   | weight     | requests  | cost / 1k | margin at $0.70 |
- * |-----------------------------------|------------|-----------|-----------|-----------------|
- * | the page as measured (748.5 KB)   | $0.262148  | $0.182400 | $0.4445   | +36.5%          |
- * | the priced basis (1012.8 KB)      | $0.354715  | $0.182400 | $0.5371   | +23.3%          |
- *
- * — at least 30% over cost in every region, which is the claim `/pricing`
- * makes.
+ * unit, so every Vercel-billed term of a page view is priced where Vercel is
+ * dearest.
  *
  * ## The figure
  *
- * $0.00018374681 is 57.42 requests at $3.20 per million — the measured 57,
- * with the basis set ABOVE the measurement as the weight basis is — pinned so
- * the billed price lands on a whole cent: ($0.354715 + $0.1824) × 1.3 is
- * $0.6982 per 1,000, rounded up to $0.70, and ($0.354715 + $0.183747) × 1.3
- * is exactly $0.70. Published as "Our cost $0.538462 / You pay $0.70", the
- * "at cost + 30%" claim stays true of the cost a billed view incurs in the
- * dearest region, and so in every other.
+ * Per view, past the allowance, at the dearest region:
+ *
+ * |                                                        |              |
+ * |--------------------------------------------------------|--------------|
+ * | 57 CDN requests at $3.20 per million                   | $0.00018240  |
+ * | the beacon's function: 0.4 s billed as active CPU at   | $0.00002922  |
+ * |   $0.221/hr, 2 GB at $0.0183/GB-hr, $0.60 per million  |              |
+ * | the beacon's two counter writes at nam5's $0.18/100k   | $0.00000360  |
+ * | the beacon's ~1 KB through the function at $0.43/GB    | $0.00000044  |
+ * | **requests, measured**                                 | $0.00021566  |
+ *
+ * ($0.399028 weight + $0.215662) × 1.3 is $0.7991 per 1,000, rounded up to
+ * $0.80, and this term is pinned so ($0.399028 + $0.216357) × 1.3 is exactly
+ * $0.80 — "Our cost $0.615385 / You pay $0.80" — with the basis set ABOVE the
+ * measurement as the weight basis is. "At cost + 30%" holds of the cost a
+ * billed view incurs in the dearest region, and so in every other. The 0.4 s
+ * is the one function duration on record (the form-submission route), billed
+ * whole as CPU because nothing measured splits it from I/O wait.
  *
  * ## ⛔ Not in {@link ORG_COGS_UNIT_RATES_USD}, deliberately
  *
@@ -989,16 +1016,16 @@ export declare const METERED_MARKUP = 1.3;
  * ## The INCLUDED bands carry it too
  *
  * A view inside a plan's band makes the same requests as one past it, and
- * once the platform is past the allowance the CDN bills them either way, so
- * the `bandwidthGb` bands are sized with this term counted: $0.190 per
- * included GB on top of $0.367 of weight. `tier-margin-floor.spec.ts`
+ * once the platform is past the allowance they cost the same either way, so
+ * the `bandwidthGb` bands are sized with this term counted: $0.224 per
+ * included GB on top of $0.413 of weight. `tier-margin-floor.spec.ts`
  * multiplies it in and pins every tier at 100% of every band.
  *
  * Lives HERE, beside the markup, for the reason the markup does: the
  * `/pricing` generator publishes the cost column from it and cannot import
  * anything under `apps/console`.
  */
-export declare const PAGE_VIEW_CDN_REQUEST_COST_USD = 0.00018374681;
+export declare const PAGE_VIEW_CDN_REQUEST_COST_USD = 0.00021635711;
 /**
  * Monthly unit costs for the meters the rollup already records (AGL-1134).
  *
@@ -1031,14 +1058,18 @@ export declare const PAGE_VIEW_CDN_REQUEST_COST_USD = 0.00018374681;
  * ## Every Vercel-billed input is priced at Vercel's dearest region
  *
  * The CDN and functions bill by region, from $0.15 to $0.35 per GB of
- * transfer, $2.00 to $3.20 per million requests, and $0.128 to $0.221 per
- * hour of active CPU (memory $0.0106 to $0.0183 per GB-hour), and a plan
- * cannot choose where its visitors are. So the Vercel share of every rate
- * here is priced at the dearest region (AGL-3444): the transfer inside
- * `perPageView`, the function invocation inside `perFormSubmission`, and the
- * compute inside `perRun`. The GCP shares — object and Firestore storage, and
- * the Firestore reads and writes behind a render, a submission or a run —
- * are priced as they were.
+ * transfer (a decimal GB), $2.00 to $3.20 per million requests, and $0.128 to
+ * $0.221 per hour of active CPU (memory $0.0106 to $0.0183 per GB-hour), and
+ * a plan cannot choose where its visitors are. So the Vercel share of every
+ * rate here is priced at the dearest region (AGL-3444): the transfer inside
+ * `perPageView`, the function, CDN request and transfer inside
+ * `perFormSubmission` and `perApiRequest`, and the compute inside `perRun`.
+ *
+ * The GCP shares are priced at the database's own location. Production's
+ * Firestore is `nam5` (read from the Admin API 2026-10-01), at $0.06 per
+ * 100,000 reads, $0.18 per 100,000 writes and $0.18 per GiB-month — twice
+ * the single-region figures — and every Firestore operation in this table is
+ * priced there. Object storage is GCS US multi-region, `storagePerGbMonth`.
  *
  * Everything else here is a cost-model input ONLY. `dataStoragePerGbMonth`,
  * `perApiRequest`, `perContactMonth` and `perEmailSend` price what an org
@@ -1050,8 +1081,9 @@ export declare const PAGE_VIEW_CDN_REQUEST_COST_USD = 0.00018374681;
  * The first three were corrected 2026-08-09 (AGL-1280) — storage $0.03 →
  * $0.026 and form submissions $0.0005 → $0.00005 — `perPageView` was
  * re-pegged 2026-09-09 (AGL-2711), from $0.0001 to $0.00016153846, and the
- * last two were re-priced at Vercel's dearest region on 2026-10-01
- * (AGL-3444): page views $0.00035471473, form submissions $0.000053846154.
+ * last two were re-priced at Vercel's dearest region and Firestore's `nam5`
+ * on 2026-10-01 (AGL-3444): page views $0.00039902751, form submissions
+ * $0.000061538462.
  * 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.
@@ -1078,9 +1110,44 @@ export declare const ORG_COGS_UNIT_RATES_USD: {
      */
     perPageView: number;
     perFormSubmission: number;
-    /** Firestore-backed dataset bytes — an order pricier than object storage. */
+    /**
+     * Firestore-backed dataset bytes — nam5's $0.18 per GiB-month, an order
+     * pricier than object storage.
+     */
     dataStoragePerGbMonth: number;
+    /**
+     * One `/v1` request — $117 per million (AGL-3444).
+     *
+     * Every request is a function invocation behind a CDN request, and it reads
+     * before it answers (`apps/console/utils/api-v1.ts`). The ledger for a
+     * default list page — 25 records, read as 26 — at Vercel's dearest region
+     * and nam5's list prices:
+     *
+     *   - reads: the key, the rate-limit window, the org, the month's quota
+     *     counter, the site the resource sits under, and the page — 31, at
+     *     $0.06 per 100,000 = $0.0000186
+     *   - writes: the rate-limit window and the usage counter — 2, at $0.18 per
+     *     100,000 = $0.0000036
+     *   - the function, 0.4 s billed as active CPU at $0.221/hr, 2 GB at
+     *     $0.0183/GB-hr, $0.60 per million invocations = $0.0000292
+     *   - the CDN request: $3.20 per million = $0.0000032
+     *   - the response, 25 records at 3 KB — the largest mean document size
+     *     measured on production across the collections `/v1` lists (leads,
+     *     3.0 KB; records, contacts, media and the rest 1.0–1.5 KB) — plus 2 KB
+     *     of request and envelope, through Fast Data Transfer ($0.35 a GB) and
+     *     Fast Origin Transfer ($0.43 a GB), decimal GB = $0.0000615
+     *
+     * $0.0001161, carried up to $0.000117. A page of 100 — the most a client
+     * may ask for — costs about three times that, so the figure is the default
+     * request rather than the ceiling; see the 2026-10-01 decision entry.
+     */
     perApiRequest: number;
+    /**
+     * One CRM record held for a month. An operator-tuned estimate (AGL-1134),
+     * not built from a per-operation price: at `nam5`'s $0.06 per 100,000 it
+     * covers about 333 reads a record a month, plus the record's storage at
+     * $0.18 per GiB-month — well beyond what a record is read.
+     */
     perContactMonth: number;
     /**
      * One delivered email, whatever produced it — $0.90 per 1,000.
@@ -2473,6 +2540,109 @@ export declare const ESTIMATED_PAGE_TRANSFER_BYTES: number;
 export declare function pageViewsFromBandwidthGb(bandwidthGb: number): number;
 /** @see pageViewsFromBandwidthGb — the same constant, the other way. */
 export declare function bandwidthGbFromPageViews(pageViews: number): number;
+/**
+ * What ONE DECIMAL GB of video, audio or a file costs to SERVE FROM ORIGIN, by
+ * term, at the dearest region every Vercel term is billed in (AGL-3474).
+ *
+ * The media CDN serves every type the edge must never hold (AGL-1515) on
+ * every request, from origin, so a GB of it pays both of Vercel's transfer
+ * meters and Storage's egress — where a page's GB is mostly answered by the
+ * edge. This is the basis {@link ORIGIN_MEDIA_BANDWIDTH_WEIGHT} is derived
+ * from, and the figure the published "at cost + 30%" has to be true of.
+ *
+ * | term | basis | per decimal GB |
+ * |---|---|---|
+ * | `fastDataTransfer` | Vercel Fast Data Transfer, dearest region, decimal GB | $0.35 |
+ * | `fastOriginTransfer` | Vercel Fast Origin Transfer, dearest region, decimal GB | $0.43 |
+ * | `storageEgress` | GCS internet egress at list, $0.12 per GiB (0–1 TiB) | $0.111759 |
+ * | `streamingMemory` | 2 GB (the function default) at $0.0183/GB-hour, held 1,600 s | $0.016267 |
+ * | `streamingCpu` | 60 s of active CPU at $0.221/hour — an allowance, see below | $0.003683 |
+ * | `requests` | 1,000 range requests × $0.0000070 | $0.007 |
+ * | **total** | | **$0.918709** |
+ *
+ * Each request is a CDN request ($3.20 per million), a function invocation
+ * ($0.60 per million), the media document's read ($0.0000006 at `nam5`), the
+ * day document's counter write ($0.0000018) and two Storage Class B
+ * operations, the metadata read and the object read ($0.0000004 each). The
+ * lockdown, quarantine and rate-limit reads are cached across requests and
+ * cost nothing a request.
+ *
+ * `streamingCpu` is the one unmeasured term. The bytes are copied, not
+ * computed — piping a GB through Node is a few seconds of CPU — and the
+ * minute allowed here is chosen to err high, as every other basis in this
+ * file does.
+ *
+ * ## Storing the bytes is NOT here
+ *
+ * A file in the library is already metered as storage (`storagePerGbMonth`)
+ * and billed past the plan's storage at cost + 30% after card fees; serving
+ * it does not store it again. Adding storage here would charge for the same
+ * bytes twice.
+ */
+export declare const ORIGIN_MEDIA_SERVE_COST_USD_PER_GB: {
+    readonly fastDataTransfer: 0.35;
+    readonly fastOriginTransfer: 0.43;
+    readonly storageEgress: number;
+    readonly streamingMemory: number;
+    readonly streamingCpu: number;
+    readonly requests: number;
+};
+/** {@link ORIGIN_MEDIA_SERVE_COST_USD_PER_GB}, summed: about $0.9187 a decimal GB. */
+export declare const ORIGIN_MEDIA_COST_USD_PER_GB: number;
+/**
+ * The published page-view overage, per view: what a billed view costs us
+ * (`perPageView` and the request term) at {@link METERED_PRICE_MULTIPLE},
+ * rounded up to the cent per 1,000 it is quoted in — $0.83 per 1,000. The
+ * same expression as the console's `METERED_BILLED_RATES_USD.perPageView`,
+ * computed here because the weight below is, and a spec holds the two equal.
+ */
+export declare const PAGE_VIEW_PUBLISHED_PRICE_USD: number;
+/**
+ * (a) THE OVERAGE: does counting origin media at `weight` bill a GB of it past
+ * the band at cost + 30%, kept after Stripe's percentage fee?
+ *
+ * A counted GB is `weight` GB of page views at {@link PAGE_VIEW_PUBLISHED_PRICE_USD}.
+ */
+export declare function originMediaOverageHolds(weight: number): boolean;
+/**
+ * (b) THE BAND: does counting origin media at `weight` keep a plan that spends
+ * its whole bandwidth band on it inside what the band was sized on?
+ *
+ * Every `bandwidthGb` band is sized at the cost of the views one GiB buys —
+ * their weight (`perPageView`) and their requests
+ * (`PAGE_VIEW_CDN_REQUEST_COST_USD`), $0.63712 a GiB — and
+ * `tier-margin-floor.spec.ts` holds every tier at 1.3× its full-use cost on
+ * that figure. A GiB of origin media spends `weight` GiB of the band, so the
+ * band holds while `weight` GiB of band costs at least one GiB of media.
+ */
+export declare function originMediaBandHolds(weight: number): boolean;
+/**
+ * How many GB of bandwidth one GB of video, audio or a file served from origin
+ * counts as (AGL-3474, decided by the account owner 2026-10-02): the smallest
+ * weight, in tenths and never below 1, that satisfies BOTH
+ * {@link originMediaOverageHolds} and {@link originMediaBandHolds}.
+ *
+ * One weight rather than a second meter or a second rate, because it moves
+ * the band and the overage together: the Free wall, the abuse ceiling, the
+ * meters, the alerts and the invoice all read media through
+ * `pageViewsFromMediaBytes`, which applies it. At today's bases the overage
+ * needs 1.54 and the band 1.55, so it is 1.6 — the published sentence names
+ * it, and the docs and `/pricing` have to change before it does.
+ *
+ * Derived, never written down: a rate or a band basis that moves re-derives
+ * it, and `media-bandwidth.spec.ts` pins the figure so that a move is a
+ * decision with a red test attached rather than a silent re-price.
+ */
+export declare const ORIGIN_MEDIA_BANDWIDTH_WEIGHT: number;
+/**
+ * The sentence every customer surface states the weight in — `/pricing`
+ * beside the metered rates (`tools/marketing/build-pricing-tables.mts`), and
+ * the bandwidth, billing and media docs, which
+ * `media-bandwidth-weight-copy.spec.ts` holds to this exact text. Built from
+ * the derived figure, so a weight that moves turns those red before it can
+ * bill anyone.
+ */
+export declare const ORIGIN_MEDIA_BANDWIDTH_SENTENCE: string;
 /**
  * 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
@@ -2481,7 +2651,7 @@ export declare function bandwidthGbFromPageViews(pageViews: number): number;
  * 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.70 against at most $0.54 of real
+ * Past the band every 1,000 views bills $0.80 against at most $0.62 of real
  * cost — the dearest region's — once the CDN's request allowance is spent
  * ({@link PAGE_VIEW_CDN_REQUEST_COST_USD}), so the tail is not a loss — but a
  * scraper, a hotlinked asset or a botnet still bills the account holder for
@@ -2498,10 +2668,10 @@ export declare const BANDWIDTH_ABUSE_CEILING_MULTIPLE = 3;
  * 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 ≈ **$54 of real COGS** at the dearest
+ * 100,000 views/month ≈ 96.6 GB ≈ **$62 of real COGS** at the dearest
  * region (`METERED_UNIT_RATES_USD.perPageView` plus
  * `PAGE_VIEW_CDN_REQUEST_COST_USD`) — well above the free band, and an order
- * of magnitude below the $538 a million views costs. It is the number
+ * of magnitude below the $615 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;