@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/usage-budget.js

@@ -0,0 +1,421 @@
+/**
+ * @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.
+ */ // The ONE unit conversion between our provider bill and what a customer is
+// shown. Imported here so `publicOrgMonthlySpend` cannot grow a second copy of
+// it — see that function, and the module header of `assist-credits.ts`.
+import { assistCreditsFromUsd } from "./assist-credits.js";
+/**
+ * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).
+ *
+ * ## the directive, 2026-08-18, verbatim
+ *
+ *   "*our usage metering, usage alerts, budgets for usage alerts, similar to
+ *   how google cloud charges*"
+ *
+ * and, on the org-library storage decision the same day: bill from today
+ * "*but with overage protection + usage alerts, so customers don't get a
+ * surprise bill*".
+ *
+ * ## What a GCP billing budget actually is, and what this copies
+ *
+ * A GCP budget is **an amount plus a set of percentage alert rules**. It is
+ * not a cap: crossing 100% of a budget stops nothing, it sends the email that
+ * makes the bill stop being a surprise. Each rule fires **once per budget
+ * period per rule** — the console shows the budget and its progress, and the
+ * same rules push mail.
+ *
+ * This module is that shape, and only that shape:
+ *
+ *   - an **amount** (`amountUsd`), chosen by the customer;
+ *   - **threshold rules** as percentages of the amount (default 50/90/100 —
+ *     GCP's own default trio);
+ *   - one alert per threshold per **month**, which is our budget period
+ *     because every meter underneath it (`orgs/{id}/usage/{month}`,
+ *     `assistUsage/{month}`, the counters' `YYYY-MM` fields) already resets
+ *     monthly. A budget period the meters do not share would silently compare
+ *     a month of spend against a quarter of budget.
+ *
+ * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT
+ *
+ * `utils/storage-overage.ts` owns the customer's optional **hard cap**: past
+ * it uploads are refused. That is a wall, it is off by default, and it exists
+ * because the requirement was for a control "*by the end user*".
+ *
+ * A budget is the OTHER half and the softer one — it never refuses anything.
+ * The distinction is load-bearing in both directions: a budget that quietly
+ * became a cap would take a customer's site down to save them $2 (the failure
+ * mode AGL-1529 rejected on arrival), and a cap with no budget beneath it
+ * means the only warning a customer gets is the refusal itself.
+ *
+ * ## WHY DOLLARS AND NOT PERCENT-OF-QUOTA
+ *
+ * `usage-alerts` has warned at 80%/100% of individual QUOTAS since AGL-276 —
+ * sites, media storage, email sends, bandwidth. Those answer "am I near a
+ * band". They cannot answer "what will I owe", which is the question a
+ * metered customer actually has, and no sum of per-quota percentages produces
+ * it: an org at 60% of four different bands may owe nothing at all, and an
+ * org at 101% of one band may owe $40. Dollars are the customer's unit.
+ *
+ * ## THE SPEND FIGURE IS READ, NEVER RE-DERIVED
+ *
+ * `report-usage` already computes `billedCents` daily onto
+ * `orgs/{orgId}/usage/{month}` — metered infra excess at cost x 1.3, plus the
+ * data, API and contacts overages. That document is the invoice's own
+ * arithmetic, and this module takes it verbatim.
+ *
+ * A second aggregation here is the specific mistake AGL-1371 exists about:
+ * the console meter and the warning email each summed their own figures and
+ * disagreed by up to `hostLimit`x. A budget alert quoting a number the
+ * invoice will not show is worse than no budget alert, because it is believed.
+ */ /** GCP's own default budget alert rules, and the same three here. */ export const DEFAULT_BUDGET_THRESHOLD_PCTS = [
+    50,
+    90,
+    100
+];
+/** Bounds on the amount a self-serve org may set as its own budget. */ export const BUDGET_MIN_USD = 1;
+export const BUDGET_MAX_USD = 100000;
+/**
+ * Bounds on a threshold rule, as a percentage of the amount.
+ *
+ * The ceiling is 200 rather than 100 because GCP allows rules above the
+ * budget and they are the useful ones on a runaway: an org that set $20 and
+ * is at $45 wants to hear about 200%, and a ladder that stops at 100 says
+ * exactly as much at $45 as it did at $20.
+ */ export const BUDGET_THRESHOLD_MIN_PCT = 1;
+export const BUDGET_THRESHOLD_MAX_PCT = 200;
+/** At most this many rules, so one org cannot mail its admins 40 times. */ export const BUDGET_MAX_THRESHOLDS = 6;
+/** The guard key this budget dedupes under, inside `orgs/{id}.usageAlerts`. */ export const BUDGET_GUARD_KEY = 'budget';
+/**
+ * Coerces whatever is stored (or posted) into a usable ascending rule set.
+ *
+ * FAILS TO THE DEFAULT, never to empty. Every rejection path here — a blank,
+ * a string, a negative, a duplicate, an over-long list — lands on
+ * {@link DEFAULT_BUDGET_THRESHOLD_PCTS} rather than on `[]`, because an empty
+ * ladder is silence that reads as coverage.
+ */ export function normalizeBudgetThresholds(input) {
+    const list = Array.isArray(input) ? input : [];
+    const cleaned = [
+        ...new Set(list.map((entry)=>Math.round(Number(entry))).filter((pct)=>Number.isFinite(pct) && pct >= BUDGET_THRESHOLD_MIN_PCT && pct <= BUDGET_THRESHOLD_MAX_PCT))
+    ].sort((a, b)=>a - b);
+    if (!cleaned.length) return [
+        ...DEFAULT_BUDGET_THRESHOLD_PCTS
+    ];
+    return cleaned.slice(0, BUDGET_MAX_THRESHOLDS);
+}
+/**
+ * The budget this org has in force, from its raw org document.
+ *
+ * `null` amount means no budget — deliberately `null` rather than `Infinity`,
+ * matching `resolveStorageCap`: the value is serialised into the budget
+ * route's JSON and `JSON.stringify(Infinity)` is `null` anyway, so one
+ * spelling for "no budget" on both sides of the wire.
+ *
+ * An amount that is present but unusable (blank, negative, `NaN`) reads as NO
+ * budget, which is the opposite of how `resolveStorageCap` treats a corrupt
+ * CAP — and deliberately so. A corrupt cap must fall back to a low ceiling
+ * because failing open there bills someone who asked not to be billed. A
+ * budget refuses nothing, so the only cost of failing open is a missing
+ * warning, whereas inventing an amount nobody typed produces alerts about a
+ * number the customer never chose.
+ */ export function resolveUsageBudget(org) {
+    const raw = org == null ? void 0 : org.usageBudget;
+    const amount = Number(raw == null ? void 0 : raw.amountUsd);
+    if (!raw || !Number.isFinite(amount) || amount <= 0) {
+        return {
+            budgetSet: false,
+            amountUsd: null,
+            thresholdPcts: [
+                ...DEFAULT_BUDGET_THRESHOLD_PCTS
+            ]
+        };
+    }
+    return {
+        budgetSet: true,
+        amountUsd: amount,
+        thresholdPcts: normalizeBudgetThresholds(raw == null ? void 0 : raw.thresholdPcts)
+    };
+}
+/**
+ * The HIGHEST rule this spend has crossed, or 0 for none.
+ *
+ * Highest rather than all-of-them because the dedupe guard stores one number
+ * per key (the shape `usage-alerts` has used since AGL-276), and because an
+ * org that goes from $0 to $80 against a $50 budget between two cron ticks
+ * wants one email saying 160%, not three saying 50, 90 and 100. GCP behaves
+ * the same way — the rules are notification points on one number, not a queue.
+ */ export function budgetThresholdCrossed(spendUsd, budget) {
+    if (!budget.budgetSet || budget.amountUsd == null) return 0;
+    if (!Number.isFinite(budget.amountUsd) || budget.amountUsd <= 0) return 0;
+    if (!Number.isFinite(spendUsd) || spendUsd <= 0) return 0;
+    const pct = spendUsd / budget.amountUsd * 100;
+    let crossed = 0;
+    for (const rule of budget.thresholdPcts){
+        if (pct >= rule && rule > crossed) crossed = rule;
+    }
+    return crossed;
+}
+/**
+ * The rule to alert on RIGHT NOW, or 0 for silence.
+ *
+ * This is the whole of the idempotency requirement and it is one expression,
+ * so a caller cannot implement half of it:
+ *
+ *   - nothing crossed -> silent;
+ *   - crossed, but a guard from THIS month already recorded that rule or a
+ *     higher one -> silent. A cron that ticks hourly must not mail hourly.
+ *   - crossed, and the guard is from a PREVIOUS month -> alert. The budget
+ *     period rolled over, and a customer who exceeded last month's budget
+ *     must hear about this month's too.
+ *
+ * The comparison is `>=` on purpose: after alerting at 100 an org that climbs
+ * to 200 alerts again (200 > 100), and an org that stays at 100 does not.
+ */ export function budgetAlertDue(input) {
+    var _ref;
+    const { spendUsd, budget, guard, month } = input;
+    const crossed = budgetThresholdCrossed(spendUsd, budget);
+    if (!crossed) return 0;
+    if ((guard == null ? void 0 : guard.month) === month && Number((_ref = guard == null ? void 0 : guard.threshold) != null ? _ref : 0) >= crossed) {
+        return 0;
+    }
+    return crossed;
+}
+/**
+ * Whether `month`'s invoice charges for Assist tokens.
+ *
+ * Same START-MONTH shape and the same fail-closed posture as
+ * `billsOrgLibraryStorage`, and for the identical reason: a boolean flipped
+ * mid-period would retroactively bill a re-run of an earlier month at that
+ * month's accumulated tokens. A start month cannot reach backwards.
+ *
+ * `BILL_ASSIST_TOKENS_FROM=YYYY-MM`. Anything else — `true`, `1`, a date, a
+ * typo — bills nothing.
+ */ export function billsAssistTokens(month, configuredStart) {
+    const start = String(configuredStart != null ? configuredStart : '').trim();
+    if (!/^\d{4}-\d{2}$/.test(start)) return false;
+    if (!/^\d{4}-\d{2}$/.test(month)) return false;
+    return month >= start;
+}
+/**
+ * Builds the month's spend from figures already read elsewhere.
+ *
+ * `rollupMonth` is compared to `month` rather than trusted: see
+ * {@link OrgSpendBreakdown.meteredFresh}.
+ */ export function orgMonthlySpend(input) {
+    const { month, rollupBilledCents, rollupMonth, assistEstCostUsd } = input;
+    const meteredFresh = Boolean(rollupMonth) && rollupMonth === month;
+    const cents = Number(rollupBilledCents);
+    const meteredUsd = meteredFresh && Number.isFinite(cents) && cents > 0 ? cents / 100 : 0;
+    const assistRaw = Number(assistEstCostUsd);
+    const assistUsd = Number.isFinite(assistRaw) && assistRaw > 0 ? assistRaw : 0;
+    const assistBilled = billsAssistTokens(month, input.assistBilledFrom);
+    return {
+        meteredUsd,
+        assistUsd,
+        assistBilled,
+        totalUsd: meteredUsd + (assistBilled ? assistUsd : 0),
+        meteredFresh
+    };
+}
+/**
+ * The projection that crosses the boundary to a customer's browser.
+ *
+ * `OrgSpendBreakdown.assistUsd` is `orgs/{id}/assistUsage/{month}.estCostUsd`
+ * verbatim — our provider bill at the serving model's list rates, not a price
+ * and not a rate the platform publishes. Serving it to an org-scoped caller
+ * puts our model choice, our per-token rates and our margin on a billing page,
+ * which is the boundary `publicAssistCredits` and `publicAssistQuota` already
+ * exist to hold on the assist routes. This is the same boundary, one route
+ * over, and it was the last place the dollar figure still crossed it.
+ *
+ * `assistCreditsFromUsd` is the ONE conversion between the two units, so this
+ * cannot come to disagree with the credits meter about the same month's
+ * consumption.
+ *
+ * `meteredUsd` and `totalUsd` stay dollars: `billedCents` is what an invoice
+ * charges, which is the customer's own money and the whole subject of a budget.
+ *
+ * The two units are deliberately not summed. A budget is a dollar rule, credits
+ * are not dollars, and folding one into the other would republish the cost the
+ * conversion just removed.
+ */ export function publicOrgMonthlySpend(spend) {
+    return {
+        meteredUsd: spend.meteredUsd,
+        assistCredits: assistCreditsFromUsd(spend.assistUsd),
+        totalUsd: spend.totalUsd,
+        assistBilled: spend.assistBilled,
+        meteredFresh: spend.meteredFresh
+    };
+}
+/**
+ * The MARGIN GUARD (the other half of the ask, and the live half).
+ *
+ * A customer budget protects the customer. This protects us, from the one
+ * meter on the platform whose unit cost is real money paid to a third party
+ * and whose ceiling is a message count rather than a dollar figure:
+ * `assistEntitledMonthlyLimit` caps an entitled org at 1,000 MESSAGES a
+ * month, and a thousand long, cache-cold Opus-class exchanges is a
+ * three-figure bill against a subscription that did not move.
+ *
+ * So one org's Assist COGS crossing this threshold notifies STAFF, not the
+ * customer — the customer is not being charged and has done nothing wrong.
+ * Returns the threshold crossed, or 0.
+ *
+ * `ASSIST_ORG_MONTHLY_COGS_ALERT_USD` overrides the default and FAILS TO THE
+ * DEFAULT: a blank or malformed value that disabled the guard would be
+ * another alert that cannot fire.
+ */ export const ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT = 25;
+export function assistCogsAlertThresholdUsd(configured) {
+    const parsed = Number(String(configured != null ? configured : '').trim());
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT;
+    }
+    return parsed;
+}
+/**
+ * The repo default spend ceiling: **$40 per org per month** (AGL-2264).
+ *
+ * The number is arithmetic rather than pricing. After AGL-2441 the
+ * 1,000-message entitled guard bounds roughly $28/org/month of worst-case
+ * spend at Sonnet, and the staff margin alert already fires at $25. $40
+ * therefore sits ABOVE anything the message cap can produce at the current
+ * model, so it changes no charged amount and no plan's behaviour — it is a
+ * ceiling on OUR cost, not a customer price, which is why it is outside the
+ * Sept-1 pricing lock. It binds only when an assumption behind that
+ * arithmetic has moved: an `ASSIST_MODEL` swap to an Opus-class tier, a
+ * longer prompt, or a caller finding another way to inflate input. That is
+ * the failure it exists for.
+ *
+ * It ships as a DEFAULT rather than as an environment variable someone must
+ * remember, because an unset ceiling is the fail-open this issue was opened
+ * about: a fresh deployment and a self-hoster both inherit a sane bound
+ * without knowing the variable exists.
+ *
+ * The free tier gets no separate figure and needs none — its 10 messages a
+ * UTC day bound it at roughly $0.28/day, so this is a backstop it cannot
+ * reach rather than a cap it runs into.
+ *
+ * ⚠️ It applies only to an org whose plan sells NO assist band. Agency and
+ * Enterprise include more assist than $40 of spend, so the meter's
+ * `assistMonthlyCeilingUsd` keeps this default off every plan that sells a
+ * band — see there for which figure binds when.
+ */ export const ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD = 40;
+/**
+ * The per-org monthly PROVIDER-SPEND ceiling in USD — the dollar half of
+ * the cap (AGL-2264), from `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` as the caller
+ * read it. Defaults to {@link ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD};
+ * `off` removes it.
+ *
+ * Pure over the configured value, like {@link assistCogsAlertThresholdUsd}:
+ * the meter that refuses at the ceiling and the cron that announces the
+ * refusal read the one variable and must agree on what it means.
+ *
+ * The meter's message caps bound spend only through an assumed cost per
+ * message, and that assumption is exactly what drifts: `ASSIST_MODEL` is an
+ * env override, prompts grow, and a client controls how much history it
+ * posts. The ceiling is measured against the real figure instead: the
+ * running `estCostUsd` on the month's assist usage document, which the meter
+ * increments at the SERVING model's rates. So it bounds the actual bill
+ * rather than a forecast of it.
+ *
+ * The refusal is deliberately the same shape as the message refusal (a
+ * reservation that did not move the counter), so an org at the ceiling
+ * spends nothing at all rather than spending less. It refuses — it does
+ * NOT quietly swap to a cheaper model. A silent quality drop is worse than
+ * an honest stop, because nobody can tell it happened.
+ *
+ * ⚠️ **Fails to the DEFAULT, never to “no ceiling”.** An empty, negative or
+ * unparseable value reads as unconfigured and takes the repo default, so a
+ * typo cannot reopen the fail-open this exists to close. It cannot become a
+ * ceiling of `$0` either — a value of zero is not “refuse everyone”, it is
+ * “not a number I will honour” — because an outage across every workspace
+ * would be worse than the overspend being guarded.
+ *
+ * Removing the ceiling therefore takes a WORD rather than a number:
+ * `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD=off`. A deployment paying its own
+ * provider bill may genuinely want none, and that is a decision someone
+ * should have to write down rather than reach by mistyping a digit.
+ */ export function assistOrgMonthlyCostLimitUsd(configured) {
+    const operator = assistOperatorCeilingUsd(configured);
+    return operator === undefined ? ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD : operator;
+}
+/**
+ * The operator's ceiling exactly as CONFIGURED — three states, not two:
+ * a number, `null` for the word `off`, and `undefined` for unset or
+ * unparseable.
+ *
+ * `assistOrgMonthlyCostLimitUsd` collapses `undefined` onto the repo default
+ * and is the reading every existing caller wants. The composition with a
+ * plan's own band needs the third state, because "the operator wrote a
+ * number" and "nobody configured anything" have to bind differently against a
+ * band that was sold: an operator's figure is a decision, and the repo
+ * default is a backstop for orgs that have no band of their own.
+ */ export function assistOperatorCeilingUsd(configured) {
+    const raw = String(configured != null ? configured : '').trim();
+    if (raw === '') return undefined;
+    if (raw.toLowerCase() === 'off') return null;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+/**
+ * Whether this org's Assist spend has newly crossed the margin threshold.
+ *
+ * Dedupes through the same guard shape and the same month semantics as the
+ * customer budget, under its own key, so a staff alert and a customer alert
+ * can never suppress one another.
+ */ export function assistMarginBreach(input) {
+    var _ref;
+    const { assistUsd, thresholdUsd, guard, month } = input;
+    if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return false;
+    if (thresholdUsd <= 0 || assistUsd < thresholdUsd) return false;
+    // The guard records how many WHOLE multiples of the threshold have been
+    // announced, so an org at 1x is announced once and an org that climbs to 2x
+    // is announced again — an escalating cost must not go quiet because it
+    // already spoke.
+    const multiple = Math.floor(assistUsd / thresholdUsd);
+    if ((guard == null ? void 0 : guard.month) === month && Number((_ref = guard == null ? void 0 : guard.threshold) != null ? _ref : 0) >= multiple) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Whether this org has newly crossed the HARD spend ceiling — the one that
+ * refuses (AGL-2264), as distinct from {@link assistMarginBreach}'s review
+ * threshold, which only warns.
+ *
+ * It needs its own guard and its own announcement because the margin alert
+ * cannot carry this news. That alert speaks in WHOLE MULTIPLES of its $25
+ * threshold, so an org that climbs from $25 to the $40 ceiling is still at
+ * 1x and stays silent — staff would learn that the assistant had stopped
+ * answering for a customer only when someone complained. A ceiling that
+ * refuses quietly is the same defect as a ceiling that does not refuse.
+ *
+ * Once per org per month: crossing is a state, not an escalating figure, and
+ * the org is refused from here to the month boundary regardless of how far
+ * past it the recorded spend sits.
+ */ export function assistCeilingBreach(input) {
+    const { assistUsd, ceilingUsd, guard, month } = input;
+    if (ceilingUsd === null) return false;
+    if (!Number.isFinite(assistUsd) || !Number.isFinite(ceilingUsd)) return false;
+    if (ceilingUsd <= 0 || assistUsd < ceilingUsd) return false;
+    return (guard == null ? void 0 : guard.month) !== month;
+}
+/** The multiple {@link assistMarginBreach} would record. */ export function assistMarginMultiple(assistUsd, thresholdUsd) {
+    if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return 0;
+    if (thresholdUsd <= 0) return 0;
+    return Math.max(0, Math.floor(assistUsd / thresholdUsd));
+}
+
+//# sourceMappingURL=usage-budget.js.map

package/src/lib/app-utils/usage-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/usage-budget.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// The ONE unit conversion between our provider bill and what a customer is\n// shown. Imported here so `publicOrgMonthlySpend` cannot grow a second copy of\n// it — see that function, and the module header of `assist-credits.ts`.\nimport { assistCreditsFromUsd } from './assist-credits'\n\n/**\n * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).\n *\n * ## the directive, 2026-08-18, verbatim\n *\n *   \"*our usage metering, usage alerts, budgets for usage alerts, similar to\n *   how google cloud charges*\"\n *\n * and, on the org-library storage decision the same day: bill from today\n * \"*but with overage protection + usage alerts, so customers don't get a\n * surprise bill*\".\n *\n * ## What a GCP billing budget actually is, and what this copies\n *\n * A GCP budget is **an amount plus a set of percentage alert rules**. It is\n * not a cap: crossing 100% of a budget stops nothing, it sends the email that\n * makes the bill stop being a surprise. Each rule fires **once per budget\n * period per rule** — the console shows the budget and its progress, and the\n * same rules push mail.\n *\n * This module is that shape, and only that shape:\n *\n *   - an **amount** (`amountUsd`), chosen by the customer;\n *   - **threshold rules** as percentages of the amount (default 50/90/100 —\n *     GCP's own default trio);\n *   - one alert per threshold per **month**, which is our budget period\n *     because every meter underneath it (`orgs/{id}/usage/{month}`,\n *     `assistUsage/{month}`, the counters' `YYYY-MM` fields) already resets\n *     monthly. A budget period the meters do not share would silently compare\n *     a month of spend against a quarter of budget.\n *\n * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT\n *\n * `utils/storage-overage.ts` owns the customer's optional **hard cap**: past\n * it uploads are refused. That is a wall, it is off by default, and it exists\n * because the requirement was for a control \"*by the end user*\".\n *\n * A budget is the OTHER half and the softer one — it never refuses anything.\n * The distinction is load-bearing in both directions: a budget that quietly\n * became a cap would take a customer's site down to save them $2 (the failure\n * mode AGL-1529 rejected on arrival), and a cap with no budget beneath it\n * means the only warning a customer gets is the refusal itself.\n *\n * ## WHY DOLLARS AND NOT PERCENT-OF-QUOTA\n *\n * `usage-alerts` has warned at 80%/100% of individual QUOTAS since AGL-276 —\n * sites, media storage, email sends, bandwidth. Those answer \"am I near a\n * band\". They cannot answer \"what will I owe\", which is the question a\n * metered customer actually has, and no sum of per-quota percentages produces\n * it: an org at 60% of four different bands may owe nothing at all, and an\n * org at 101% of one band may owe $40. Dollars are the customer's unit.\n *\n * ## THE SPEND FIGURE IS READ, NEVER RE-DERIVED\n *\n * `report-usage` already computes `billedCents` daily onto\n * `orgs/{orgId}/usage/{month}` — metered infra excess at cost x 1.3, plus the\n * data, API and contacts overages. That document is the invoice's own\n * arithmetic, and this module takes it verbatim.\n *\n * A second aggregation here is the specific mistake AGL-1371 exists about:\n * the console meter and the warning email each summed their own figures and\n * disagreed by up to `hostLimit`x. A budget alert quoting a number the\n * invoice will not show is worse than no budget alert, because it is believed.\n */\n\n/** GCP's own default budget alert rules, and the same three here. */\nexport const DEFAULT_BUDGET_THRESHOLD_PCTS: readonly number[] = [50, 90, 100]\n\n/** Bounds on the amount a self-serve org may set as its own budget. */\nexport const BUDGET_MIN_USD = 1\nexport const BUDGET_MAX_USD = 100_000\n\n/**\n * Bounds on a threshold rule, as a percentage of the amount.\n *\n * The ceiling is 200 rather than 100 because GCP allows rules above the\n * budget and they are the useful ones on a runaway: an org that set $20 and\n * is at $45 wants to hear about 200%, and a ladder that stops at 100 says\n * exactly as much at $45 as it did at $20.\n */\nexport const BUDGET_THRESHOLD_MIN_PCT = 1\nexport const BUDGET_THRESHOLD_MAX_PCT = 200\n/** At most this many rules, so one org cannot mail its admins 40 times. */\nexport const BUDGET_MAX_THRESHOLDS = 6\n\n/** The guard key this budget dedupes under, inside `orgs/{id}.usageAlerts`. */\nexport const BUDGET_GUARD_KEY = 'budget'\n\nexport interface UsageBudget {\n  /** Whether the customer has set a budget at all. Absent by default. */\n  budgetSet: boolean\n  /** The amount in USD, or `null` when no budget is set. */\n  amountUsd: number | null\n  /**\n   * Threshold rules as percentages, ascending and deduplicated. Always the\n   * default trio when a budget exists but named no rules — a budget with an\n   * empty rule set is a budget that cannot alert, which is the defect this\n   * whole file exists to remove.\n   */\n  thresholdPcts: number[]\n}\n\n/**\n * Coerces whatever is stored (or posted) into a usable ascending rule set.\n *\n * FAILS TO THE DEFAULT, never to empty. Every rejection path here — a blank,\n * a string, a negative, a duplicate, an over-long list — lands on\n * {@link DEFAULT_BUDGET_THRESHOLD_PCTS} rather than on `[]`, because an empty\n * ladder is silence that reads as coverage.\n */\nexport function normalizeBudgetThresholds(\n  input: unknown,\n): number[] {\n  const list = Array.isArray(input) ? input : []\n  const cleaned = [\n    ...new Set(\n      list\n        .map((entry) => Math.round(Number(entry)))\n        .filter(\n          (pct) =>\n            Number.isFinite(pct) &&\n            pct >= BUDGET_THRESHOLD_MIN_PCT &&\n            pct <= BUDGET_THRESHOLD_MAX_PCT,\n        ),\n    ),\n  ].sort((a, b) => a - b)\n  if (!cleaned.length) return [...DEFAULT_BUDGET_THRESHOLD_PCTS]\n  return cleaned.slice(0, BUDGET_MAX_THRESHOLDS)\n}\n\n/**\n * The budget this org has in force, from its raw org document.\n *\n * `null` amount means no budget — deliberately `null` rather than `Infinity`,\n * matching `resolveStorageCap`: the value is serialised into the budget\n * route's JSON and `JSON.stringify(Infinity)` is `null` anyway, so one\n * spelling for \"no budget\" on both sides of the wire.\n *\n * An amount that is present but unusable (blank, negative, `NaN`) reads as NO\n * budget, which is the opposite of how `resolveStorageCap` treats a corrupt\n * CAP — and deliberately so. A corrupt cap must fall back to a low ceiling\n * because failing open there bills someone who asked not to be billed. A\n * budget refuses nothing, so the only cost of failing open is a missing\n * warning, whereas inventing an amount nobody typed produces alerts about a\n * number the customer never chose.\n */\nexport function resolveUsageBudget(\n  org: Record<string, unknown> | null | undefined,\n): UsageBudget {\n  const raw = (org as any)?.usageBudget\n  const amount = Number(raw?.amountUsd)\n  if (!raw || !Number.isFinite(amount) || amount <= 0) {\n    return { budgetSet: false, amountUsd: null, thresholdPcts: [...DEFAULT_BUDGET_THRESHOLD_PCTS] }\n  }\n  return {\n    budgetSet: true,\n    amountUsd: amount,\n    thresholdPcts: normalizeBudgetThresholds(raw?.thresholdPcts),\n  }\n}\n\n/**\n * The HIGHEST rule this spend has crossed, or 0 for none.\n *\n * Highest rather than all-of-them because the dedupe guard stores one number\n * per key (the shape `usage-alerts` has used since AGL-276), and because an\n * org that goes from $0 to $80 against a $50 budget between two cron ticks\n * wants one email saying 160%, not three saying 50, 90 and 100. GCP behaves\n * the same way — the rules are notification points on one number, not a queue.\n */\nexport function budgetThresholdCrossed(\n  spendUsd: number,\n  budget: UsageBudget,\n): number {\n  if (!budget.budgetSet || budget.amountUsd == null) return 0\n  if (!Number.isFinite(budget.amountUsd) || budget.amountUsd <= 0) return 0\n  if (!Number.isFinite(spendUsd) || spendUsd <= 0) return 0\n  const pct = (spendUsd / budget.amountUsd) * 100\n  let crossed = 0\n  for (const rule of budget.thresholdPcts) {\n    if (pct >= rule && rule > crossed) crossed = rule\n  }\n  return crossed\n}\n\n/** One entry of `orgs/{orgId}.usageAlerts` — the existing guard shape. */\nexport interface UsageAlertGuard {\n  month?: string\n  threshold?: number\n}\n\n/**\n * The rule to alert on RIGHT NOW, or 0 for silence.\n *\n * This is the whole of the idempotency requirement and it is one expression,\n * so a caller cannot implement half of it:\n *\n *   - nothing crossed -> silent;\n *   - crossed, but a guard from THIS month already recorded that rule or a\n *     higher one -> silent. A cron that ticks hourly must not mail hourly.\n *   - crossed, and the guard is from a PREVIOUS month -> alert. The budget\n *     period rolled over, and a customer who exceeded last month's budget\n *     must hear about this month's too.\n *\n * The comparison is `>=` on purpose: after alerting at 100 an org that climbs\n * to 200 alerts again (200 > 100), and an org that stays at 100 does not.\n */\nexport function budgetAlertDue(input: {\n  spendUsd: number\n  budget: UsageBudget\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): number {\n  const { spendUsd, budget, guard, month } = input\n  const crossed = budgetThresholdCrossed(spendUsd, budget)\n  if (!crossed) return 0\n  if (guard?.month === month && Number(guard?.threshold ?? 0) >= crossed) {\n    return 0\n  }\n  return crossed\n}\n\n/**\n * What an org is spending this month, split by where it comes from.\n *\n * Every field is a figure some other module already owns; nothing here is\n * re-derived (see the header). The split exists because a budget alert that\n * says only \"$62\" invites a support ticket asking what the $62 was.\n */\nexport interface OrgSpendBreakdown {\n  /**\n   * Metered infrastructure + plan-priced overages, from the invoice's own\n   * `billedCents`. This is the part that reaches a Stripe invoice.\n   */\n  meteredUsd: number\n  /**\n   * Aglyn Assist token spend for the month, at the serving model's list\n   * rates (`orgs/{id}/assistUsage/{month}.estCostUsd`).\n   *\n   * ALWAYS REPORTED, and counted toward the budget only when\n   * {@link billsAssistTokens} says this month invoices for it — which today\n   * it does not, because Assist is a plan ENTITLEMENT (`aiAssist: true`) with\n   * no per-token price anywhere in the platform. Adding it to a customer's\n   * \"you will owe\" figure would be a surprise bill invented by a\n   * notification, which is precisely the thing this feature exists to stop.\n   *\n   * It is nonetheless carried here rather than left out, for two reasons that\n   * both bite: the day Assist is priced this is a one-line switch instead of\n   * a new pipeline, and — live today — {@link assistMarginBreach} reads this\n   * same number as OUR cost, which is the margin-guard half of the job.\n   */\n  assistUsd: number\n  /** What counts against the budget: metered, plus assist when it bills. */\n  totalUsd: number\n  /** Whether `assistUsd` entered `totalUsd`. */\n  assistBilled: boolean\n  /**\n   * FALSE when no rollup exists for this month yet, so `meteredUsd` is 0\n   * because nothing has been computed rather than because nothing was spent.\n   *\n   * The distinction is the difference between a quiet budget and a broken\n   * one, and it is not theoretical: `usage-alerts` reads the LATEST usage\n   * rollup by `computedAt`, which on the first days of a month is still LAST\n   * month's document. Alerting from that would compare August's budget\n   * against July's spend; suppressing the alert without recording why would\n   * make a budget that never fires look like a budget that never needed to.\n   */\n  meteredFresh: boolean\n}\n\n/**\n * Whether `month`'s invoice charges for Assist tokens.\n *\n * Same START-MONTH shape and the same fail-closed posture as\n * `billsOrgLibraryStorage`, and for the identical reason: a boolean flipped\n * mid-period would retroactively bill a re-run of an earlier month at that\n * month's accumulated tokens. A start month cannot reach backwards.\n *\n * `BILL_ASSIST_TOKENS_FROM=YYYY-MM`. Anything else — `true`, `1`, a date, a\n * typo — bills nothing.\n */\nexport function billsAssistTokens(\n  month: string,\n  configuredStart: string | null | undefined,\n): boolean {\n  const start = String(configuredStart ?? '').trim()\n  if (!/^\\d{4}-\\d{2}$/.test(start)) return false\n  if (!/^\\d{4}-\\d{2}$/.test(month)) return false\n  return month >= start\n}\n\n/**\n * Builds the month's spend from figures already read elsewhere.\n *\n * `rollupMonth` is compared to `month` rather than trusted: see\n * {@link OrgSpendBreakdown.meteredFresh}.\n */\nexport function orgMonthlySpend(input: {\n  month: string\n  /** `billedCents` off the latest `orgs/{id}/usage/*` document. */\n  rollupBilledCents: number | null | undefined\n  /** The `month` field of that same document. */\n  rollupMonth: string | null | undefined\n  /** `estCostUsd` off `orgs/{id}/assistUsage/{month}`. */\n  assistEstCostUsd: number | null | undefined\n  /** `BILL_ASSIST_TOKENS_FROM`, verbatim. */\n  assistBilledFrom?: string | null\n}): OrgSpendBreakdown {\n  const { month, rollupBilledCents, rollupMonth, assistEstCostUsd } = input\n  const meteredFresh = Boolean(rollupMonth) && rollupMonth === month\n  const cents = Number(rollupBilledCents)\n  const meteredUsd =\n    meteredFresh && Number.isFinite(cents) && cents > 0 ? cents / 100 : 0\n  const assistRaw = Number(assistEstCostUsd)\n  const assistUsd = Number.isFinite(assistRaw) && assistRaw > 0 ? assistRaw : 0\n  const assistBilled = billsAssistTokens(month, input.assistBilledFrom)\n  return {\n    meteredUsd,\n    assistUsd,\n    assistBilled,\n    totalUsd: meteredUsd + (assistBilled ? assistUsd : 0),\n    meteredFresh,\n  }\n}\n\n/**\n * The customer-facing half of {@link OrgSpendBreakdown} — dollars the customer\n * is charged, and Assist consumption in CREDITS.\n */\nexport interface PublicOrgSpend {\n  /** Metered infrastructure and plan overages, from the invoice's own figure. */\n  meteredUsd: number\n  /**\n   * Assist consumption this month, in credits. The stored figure is\n   * `estCostUsd` — our provider bill — and a credit is the unit that expresses\n   * it without publishing it.\n   */\n  assistCredits: number\n  /** What counts against the budget. */\n  totalUsd: number\n  /** Whether Assist consumption entered `totalUsd`. */\n  assistBilled: boolean\n  meteredFresh: boolean\n}\n\n/**\n * The projection that crosses the boundary to a customer's browser.\n *\n * `OrgSpendBreakdown.assistUsd` is `orgs/{id}/assistUsage/{month}.estCostUsd`\n * verbatim — our provider bill at the serving model's list rates, not a price\n * and not a rate the platform publishes. Serving it to an org-scoped caller\n * puts our model choice, our per-token rates and our margin on a billing page,\n * which is the boundary `publicAssistCredits` and `publicAssistQuota` already\n * exist to hold on the assist routes. This is the same boundary, one route\n * over, and it was the last place the dollar figure still crossed it.\n *\n * `assistCreditsFromUsd` is the ONE conversion between the two units, so this\n * cannot come to disagree with the credits meter about the same month's\n * consumption.\n *\n * `meteredUsd` and `totalUsd` stay dollars: `billedCents` is what an invoice\n * charges, which is the customer's own money and the whole subject of a budget.\n *\n * The two units are deliberately not summed. A budget is a dollar rule, credits\n * are not dollars, and folding one into the other would republish the cost the\n * conversion just removed.\n */\nexport function publicOrgMonthlySpend(spend: OrgSpendBreakdown): PublicOrgSpend {\n  return {\n    meteredUsd: spend.meteredUsd,\n    assistCredits: assistCreditsFromUsd(spend.assistUsd),\n    totalUsd: spend.totalUsd,\n    assistBilled: spend.assistBilled,\n    meteredFresh: spend.meteredFresh,\n  }\n}\n\n/**\n * The MARGIN GUARD (the other half of the ask, and the live half).\n *\n * A customer budget protects the customer. This protects us, from the one\n * meter on the platform whose unit cost is real money paid to a third party\n * and whose ceiling is a message count rather than a dollar figure:\n * `assistEntitledMonthlyLimit` caps an entitled org at 1,000 MESSAGES a\n * month, and a thousand long, cache-cold Opus-class exchanges is a\n * three-figure bill against a subscription that did not move.\n *\n * So one org's Assist COGS crossing this threshold notifies STAFF, not the\n * customer — the customer is not being charged and has done nothing wrong.\n * Returns the threshold crossed, or 0.\n *\n * `ASSIST_ORG_MONTHLY_COGS_ALERT_USD` overrides the default and FAILS TO THE\n * DEFAULT: a blank or malformed value that disabled the guard would be\n * another alert that cannot fire.\n */\nexport const ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT = 25\n\nexport function assistCogsAlertThresholdUsd(\n  configured?: string | null,\n): number {\n  const parsed = Number(String(configured ?? '').trim())\n  if (!Number.isFinite(parsed) || parsed <= 0) {\n    return ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT\n  }\n  return parsed\n}\n\n/**\n * The repo default spend ceiling: **$40 per org per month** (AGL-2264).\n *\n * The number is arithmetic rather than pricing. After AGL-2441 the\n * 1,000-message entitled guard bounds roughly $28/org/month of worst-case\n * spend at Sonnet, and the staff margin alert already fires at $25. $40\n * therefore sits ABOVE anything the message cap can produce at the current\n * model, so it changes no charged amount and no plan's behaviour — it is a\n * ceiling on OUR cost, not a customer price, which is why it is outside the\n * Sept-1 pricing lock. It binds only when an assumption behind that\n * arithmetic has moved: an `ASSIST_MODEL` swap to an Opus-class tier, a\n * longer prompt, or a caller finding another way to inflate input. That is\n * the failure it exists for.\n *\n * It ships as a DEFAULT rather than as an environment variable someone must\n * remember, because an unset ceiling is the fail-open this issue was opened\n * about: a fresh deployment and a self-hoster both inherit a sane bound\n * without knowing the variable exists.\n *\n * The free tier gets no separate figure and needs none — its 10 messages a\n * UTC day bound it at roughly $0.28/day, so this is a backstop it cannot\n * reach rather than a cap it runs into.\n *\n * ⚠️ It applies only to an org whose plan sells NO assist band. Agency and\n * Enterprise include more assist than $40 of spend, so the meter's\n * `assistMonthlyCeilingUsd` keeps this default off every plan that sells a\n * band — see there for which figure binds when.\n */\nexport const ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD = 40\n\n/**\n * The per-org monthly PROVIDER-SPEND ceiling in USD — the dollar half of\n * the cap (AGL-2264), from `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` as the caller\n * read it. Defaults to {@link ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD};\n * `off` removes it.\n *\n * Pure over the configured value, like {@link assistCogsAlertThresholdUsd}:\n * the meter that refuses at the ceiling and the cron that announces the\n * refusal read the one variable and must agree on what it means.\n *\n * The meter's message caps bound spend only through an assumed cost per\n * message, and that assumption is exactly what drifts: `ASSIST_MODEL` is an\n * env override, prompts grow, and a client controls how much history it\n * posts. The ceiling is measured against the real figure instead: the\n * running `estCostUsd` on the month's assist usage document, which the meter\n * increments at the SERVING model's rates. So it bounds the actual bill\n * rather than a forecast of it.\n *\n * The refusal is deliberately the same shape as the message refusal (a\n * reservation that did not move the counter), so an org at the ceiling\n * spends nothing at all rather than spending less. It refuses — it does\n * NOT quietly swap to a cheaper model. A silent quality drop is worse than\n * an honest stop, because nobody can tell it happened.\n *\n * ⚠️ **Fails to the DEFAULT, never to “no ceiling”.** An empty, negative or\n * unparseable value reads as unconfigured and takes the repo default, so a\n * typo cannot reopen the fail-open this exists to close. It cannot become a\n * ceiling of `$0` either — a value of zero is not “refuse everyone”, it is\n * “not a number I will honour” — because an outage across every workspace\n * would be worse than the overspend being guarded.\n *\n * Removing the ceiling therefore takes a WORD rather than a number:\n * `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD=off`. A deployment paying its own\n * provider bill may genuinely want none, and that is a decision someone\n * should have to write down rather than reach by mistyping a digit.\n */\nexport function assistOrgMonthlyCostLimitUsd(\n  configured?: string | null,\n): number | null {\n  const operator = assistOperatorCeilingUsd(configured)\n  return operator === undefined\n    ? ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD\n    : operator\n}\n\n/**\n * The operator's ceiling exactly as CONFIGURED — three states, not two:\n * a number, `null` for the word `off`, and `undefined` for unset or\n * unparseable.\n *\n * `assistOrgMonthlyCostLimitUsd` collapses `undefined` onto the repo default\n * and is the reading every existing caller wants. The composition with a\n * plan's own band needs the third state, because \"the operator wrote a\n * number\" and \"nobody configured anything\" have to bind differently against a\n * band that was sold: an operator's figure is a decision, and the repo\n * default is a backstop for orgs that have no band of their own.\n */\nexport function assistOperatorCeilingUsd(\n  configured?: string | null,\n): number | null | undefined {\n  const raw = String(configured ?? '').trim()\n  if (raw === '') return undefined\n  if (raw.toLowerCase() === 'off') return null\n  const parsed = Number(raw)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined\n}\n\n/**\n * Whether this org's Assist spend has newly crossed the margin threshold.\n *\n * Dedupes through the same guard shape and the same month semantics as the\n * customer budget, under its own key, so a staff alert and a customer alert\n * can never suppress one another.\n */\nexport function assistMarginBreach(input: {\n  assistUsd: number\n  thresholdUsd: number\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): boolean {\n  const { assistUsd, thresholdUsd, guard, month } = input\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return false\n  if (thresholdUsd <= 0 || assistUsd < thresholdUsd) return false\n  // The guard records how many WHOLE multiples of the threshold have been\n  // announced, so an org at 1x is announced once and an org that climbs to 2x\n  // is announced again — an escalating cost must not go quiet because it\n  // already spoke.\n  const multiple = Math.floor(assistUsd / thresholdUsd)\n  if (guard?.month === month && Number(guard?.threshold ?? 0) >= multiple) {\n    return false\n  }\n  return true\n}\n\n/**\n * Whether this org has newly crossed the HARD spend ceiling — the one that\n * refuses (AGL-2264), as distinct from {@link assistMarginBreach}'s review\n * threshold, which only warns.\n *\n * It needs its own guard and its own announcement because the margin alert\n * cannot carry this news. That alert speaks in WHOLE MULTIPLES of its $25\n * threshold, so an org that climbs from $25 to the $40 ceiling is still at\n * 1x and stays silent — staff would learn that the assistant had stopped\n * answering for a customer only when someone complained. A ceiling that\n * refuses quietly is the same defect as a ceiling that does not refuse.\n *\n * Once per org per month: crossing is a state, not an escalating figure, and\n * the org is refused from here to the month boundary regardless of how far\n * past it the recorded spend sits.\n */\nexport function assistCeilingBreach(input: {\n  assistUsd: number\n  ceilingUsd: number | null\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): boolean {\n  const { assistUsd, ceilingUsd, guard, month } = input\n  if (ceilingUsd === null) return false\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(ceilingUsd)) return false\n  if (ceilingUsd <= 0 || assistUsd < ceilingUsd) return false\n  return guard?.month !== month\n}\n\n/** The multiple {@link assistMarginBreach} would record. */\nexport function assistMarginMultiple(\n  assistUsd: number,\n  thresholdUsd: number,\n): number {\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return 0\n  if (thresholdUsd <= 0) return 0\n  return Math.max(0, Math.floor(assistUsd / thresholdUsd))\n}\n"],"names":["assistCreditsFromUsd","DEFAULT_BUDGET_THRESHOLD_PCTS","BUDGET_MIN_USD","BUDGET_MAX_USD","BUDGET_THRESHOLD_MIN_PCT","BUDGET_THRESHOLD_MAX_PCT","BUDGET_MAX_THRESHOLDS","BUDGET_GUARD_KEY","normalizeBudgetThresholds","input","list","Array","isArray","cleaned","Set","map","entry","Math","round","Number","filter","pct","isFinite","sort","a","b","length","slice","resolveUsageBudget","org","raw","usageBudget","amount","amountUsd","budgetSet","thresholdPcts","budgetThresholdCrossed","spendUsd","budget","crossed","rule","budgetAlertDue","guard","month","threshold","billsAssistTokens","configuredStart","start","String","trim","test","orgMonthlySpend","rollupBilledCents","rollupMonth","assistEstCostUsd","meteredFresh","Boolean","cents","meteredUsd","assistRaw","assistUsd","assistBilled","assistBilledFrom","totalUsd","publicOrgMonthlySpend","spend","assistCredits","ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT","assistCogsAlertThresholdUsd","configured","parsed","ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD","assistOrgMonthlyCostLimitUsd","operator","assistOperatorCeilingUsd","undefined","toLowerCase","assistMarginBreach","thresholdUsd","multiple","floor","assistCeilingBreach","ceilingUsd","assistMarginMultiple","max"],"mappings":"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"}

package/src/lib/app-utils/variables.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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 HostFunction } from './functions';
+/**
+ * Host variables (Component Builder, AGL-91): typed values authored in the
+ * console and bound into component text props with `{{name}}` — and, since
+ * AGL-93, function results with `{{fn:name(args)}}`. Pure data module
+ * shared by the console editor UI and the tenant compose pipeline.
+ */
+/** Types from the mockup's Edit Variable dialog ("Function" lands with AGL-92). */
+export type HostVariableType = 'date' | 'time' | 'text' | 'number' | 'boolean' | 'dictionary' | 'collection';
+export declare const HOST_VARIABLE_TYPE_LABELS: Record<HostVariableType, string>;
+/** `hosts/{hostId}/variables/{id}` doc. */
+export interface HostVariable {
+    /** Binding identifier — `{{name}}`. */
+    name: string;
+    type: HostVariableType;
+    /** Persisted as a string; formatted per type at resolve time. */
+    value?: string;
+    /**
+     * Workflow (by name) whose result becomes this variable's value at
+     * compose time (AGL-129); `value` acts as the fallback when the
+     * workflow is missing or fails.
+     */
+    workflowName?: string;
+    /** Computed source by workflow doc id (AGL-261); wins over the name. */
+    workflowId?: string;
+}
+export declare const VARIABLE_NAME_PATTERN: RegExp;
+/** Human-readable rendering of a variable's value for text interpolation. */
+export declare function formatVariableValue(variable: HostVariable): string;
+/** A function definition lookup keyed by function name (AGL-93). */
+export type HostFunctionLookup = Record<string, HostFunction>;
+/**
+ * Replaces binding tokens with values (AGL-91/93/185/194): id forms
+ * `{{var:id}}` / `{{fn:id(args)}}` resolve through id-keyed lookup maps.
+ * Function args are expressions over literals and variable NAMES (the
+ * scope keys by each doc's name). Unknown function refs keep the literal
+ * token; unknown variable ids render empty; bare `{{name}}` strings are
+ * plain text since the legacy fallback retired.
+ */
+export declare function resolveBindings(text: string, variables: Record<string, HostVariable>, functions?: HostFunctionLookup): string;
+/** Fast pre-check so binding-free content skips the walk entirely. */
+export declare function hasBindings(text: string): boolean;
+/**
+ * Applies `resolveBindings` to every string prop across a normalized nodes
+ * map (mutating a shallow copy). String props only — objects/arrays (sx,
+ * option lists) pass through untouched; unsafe values in hrefs remain
+ * covered by the render-time SAFE_HREF/sanitizer checks.
+ */
+/** Component id of the interactive function widget (plugins-mui). */
+export declare const FUNCTION_WIDGET_COMPONENT_ID = "functionWidget";
+/**
+ * Component id of the Calculator container (plugins-mui, AGL-3202): the
+ * other element that runs a function in the visitor's browser, and so the
+ * other one compose hands a definition to.
+ */
+export declare const FUNCTION_SCOPE_COMPONENT_ID = "functionScope";
+/**
+ * The site variables ONE function reads, by name (AGL-3202).
+ *
+ * A widget runs in the visitor's browser, so whatever it may read has to be
+ * on the page. Handing it the whole variable list would publish every value
+ * a site holds to every page that places a calculator; this hands over the
+ * names the function's own expressions use and nothing else. A name the
+ * function declares itself is not a variable read — its parameter or local
+ * shadows the variable — so it is not shipped either.
+ */
+export declare function functionGlobals(definition: HostFunction, variables: Record<string, HostVariable>): Record<string, number | string | boolean>;
+/**
+ * Injects each function widget's definition into its props at compose time
+ * (AGL-93): the client runs the shared evaluator locally, so the published
+ * page carries the definition instead of calling home. Unknown names leave
+ * the node untouched (the widget renders its editor placeholder).
+ *
+ * With `variables`, the site variables that function reads ride along as
+ * `globals` (AGL-3202) — see {@link functionGlobals} for why it is only
+ * those. The key is omitted when the function reads none, so a page built
+ * before this existed serializes exactly as it did.
+ */
+export declare function attachFunctionDefinitions<T extends Record<string, any>>(nodes: T, functions: HostFunctionLookup, variables?: Record<string, HostVariable>): T;
+export declare function resolveNodesBindings<T extends Record<string, any>>(nodes: T, variables: Record<string, HostVariable>, functions?: HostFunctionLookup): T;