@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/usage/assist-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/assist-usage.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * `FieldValue` comes straight from the SDK rather than through the admin\n * barrel (AGL-2073). This module serves every metered AI door — the chat\n * door, the besigner copy assistant and the generation jobs — and importing\n * the admin lib's `firebase-admin` module would drag the default-app\n * initialization (cert credential, RTDB, AppCheck) into every unit test that\n * touches a counter; `FieldValue`'s statics need no app at all.\n */\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  ASSIST_PROVIDER_COST_FIELD,\n  assistBandRefuses,\n  assistCreditsFromUsd,\n  assistMonthOverage,\n  assistOverageCapReached,\n  publicAssistCredits,\n  resolveAssistBudgetUsd,\n  resolveAssistOverageCapUsd,\n  resolveAssistOverageRateUsdPer1k,\n  type PublicAssistCredits,\n} from '@aglyn/aglyn/app-utils/assist-credits'\nimport {\n  aiOverageRefusal,\n  type AiOverageCapReason,\n} from '../billing/ai-overage-gate'\nimport {\n  aiOverageBillsByInvoice,\n  aiOverageGuardsApply,\n} from '../billing/ai-overage-cutover'\nimport {\n  AI_BILLING_STANDING_DOC,\n  AI_BILLING_SUBCOLLECTION,\n  readAiOverageMonthLedger,\n} from '../billing/ai-overage-ledger'\nimport { readAiOverageStanding } from '../billing/ai-overage-standing'\nimport type { AiRefusedBy } from '../model/ai-allotments'\nimport {\n  AI_HOST_CREDITS_FIELD,\n  readAiAllotmentGate,\n  type AiAllotmentGate,\n  type AiAllotmentRequestSubject,\n} from './ai-allotments'\nimport { isUncappedPlanComp } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport { assistMonthlyCeilingUsd } from './assist-ceiling'\nimport { estimateAiBilledUsd, estimateAiProviderCostUsd } from '../providers/catalog'\nimport { recordAssistRefusal } from './assist-refusals'\nimport {\n  announcePlatformFreeSpend,\n  freeAccountReservationWrite,\n  freeAccountUsageRef,\n  freeAssistAccount,\n  freeTasteMeterWrites,\n  freeTasteReadsFrom,\n  freeTasteRefusal,\n  platformFreeSpendRef,\n  type AssistMeteredOrg,\n  type FreeAssistAccount,\n} from './assist-free-taste'\nimport { aiTokenIncrements, recordUserAiUsage } from './ai-usage-by-user'\nimport { AI_USAGE_MONTH_KINDS_FIELD, AI_USAGE_TOKENS_FIELD } from '../model/ai-tokens'\nimport {\n  aiUsageKindFromRoute,\n  type AiUsageKind,\n} from '../model/ai-usage-by-user'\n\n// The ceiling composition lives beside the one other reader it has, the staff\n// refusal alert, in a module that writes nothing; the reservation's importers\n// keep reaching it here.\nexport { assistMonthlyCeilingUsd } from './assist-ceiling'\n\n/**\n * Aglyn Assist metering + the data loop (AGL-1860, phase 1).\n *\n * Collections (org-scoped, ABSENT from firebase-firestore.rules on purpose —\n * default-deny, the forumThreads precedent: every read/write passes the\n * assist API route via the Admin SDK):\n *\n *   orgs/{orgId}/assistUsage/{YYYY-MM}     per-org monthly cost telemetry:\n *     { month, messages, inputTokens, outputTokens, cacheReadTokens,\n *       cacheWriteTokens, estCostUsd, byHost: { hostId: credits },\n *       kinds: { kind: { requests, estCostUsd, tokens } }, updatedAt }\n *     (`byHost` is each site's credits, which a site's AI allotment is\n *     measured against — AGL-2942; `kinds` splits the tokens and the\n *     measured spend by what each model request was for — AGL-2937)\n *   orgs/{orgId}/counters/assistMessagesDaily\n *     fields keyed YYYY-MM-DD → integer (the free-tier daily cap counter;\n *       same field-per-period shape as the other `counters/*` docs)\n *   orgs/{orgId}/assistExchanges/{id}      the VERBATIM half of one exchange:\n *     { uid, question, answer, hostId, createdAt, expiresAt }\n *   orgs/{orgId}/assistSignals/{id}        the DERIVED half, same id:\n *     { route, hostId, model, tier, kind, inputTokens, outputTokens,\n *       cacheReadTokens, cacheWriteTokens, estCostUsd, docsPaths,\n *       stopReason, feedback: 'up'|'down'|null, createdAt }\n *\n * The Free taste (AGL-2925) adds two more, one under the workspace OWNER's\n * user document and one platform-wide, both documented and both closed to\n * clients in `assist-free-taste.ts`.\n *\n * Costs are OUR cost estimates at list rates (pricing-tunable telemetry),\n * mirrored after ORG_COGS_UNIT_RATES_USD's posture: cost visibility per org\n * from day one so the paid gate and caps can be tuned with data — the * \"must not eat margins\" constraint.\n *\n * ── Why the exchange is split in two (AGL-1972) ────────────────────────────\n *\n * One document carrying both halves forces one retention period onto two\n * kinds of data with opposite needs. The prose is what a person typed; the\n * data loop is what it cited and what it cost. Keeping them together means\n * either the prose is retained forever so the loop keeps its corpus, or the\n * loop's corpus is destroyed so the prose can expire. Neither is the answer,\n * and picking one number for both is how that false choice gets made.\n *\n * So: `assistExchanges` holds the question, the answer and the asking `uid`,\n * and carries `expiresAt` — a TTL policy reaps it after\n * ASSIST_EXCHANGE_RETENTION_DAYS. `assistSignals` holds no prose and NO uid,\n * carries no expiry, and is what the docs-gap view, the thumbs loop and the\n * cost meters actually read. The corpus the loop needs outlives the words\n * that produced it, because the corpus was never the words.\n *\n * Both subcollections sit under the org, so `recursiveDelete(orgRef)` still\n * takes them and an erasure still clears everything with no extra sweep. And\n * both are ABSENT from firebase-firestore.rules deliberately: the org block\n * matches its subcollections BY NAME and has no wildcard, so an unmatched\n * name is default-deny for every client (verified against the live ruleset —\n * the `{subcollection}/{document=**}` catch-all is under `hosts/{hostId}`,\n * not here).\n *\n * ⚠️ The TTL policy is MANUAL gcloud configuration, not repo state. It is\n * documented in `docs/FIRESTORE_MANUAL_CONFIG.md` and declared as a\n * `fieldOverrides` entry in `cloud/firebase-firestore.indexes.json` — the\n * declaration is not decoration, it is what stops the next unrelated index\n * deploy from DELETING the policy. `apps/console/specs/retention-ttl-config.spec.ts`\n * fails the build if either half goes missing.\n */\n\n/** Current billing month key, `YYYY-MM`, matching the usage rollup. */\nexport function assistUsageMonth(now = new Date()): string {\n  return now.toISOString().slice(0, 7)\n}\n\n/** Current day key, `YYYY-MM-DD` (UTC — same clock as the month key). */\nexport function assistUsageDay(now = new Date()): string {\n  return now.toISOString().slice(0, 10)\n}\n\n/**\n * How long the VERBATIM half of an exchange is kept — the question, the\n * answer and the asking uid (AGL-1972).\n *\n * 180 days, and the number is chosen against what actually reads this data\n * rather than against a round figure:\n *\n * - The docs-gap loop mines `docsPaths` and the thumbs rating. Both live on\n *   the signal document, which has no expiry, so shortening this period\n *   costs the loop nothing. That separation is what makes 180 affordable;\n *   without it the honest answer would have been \"forever\".\n * - Two full quarters is long enough to read a quarter's questions LATE, and\n *   long enough to diff what people asked before and after a docs rewrite —\n *   the one analysis that genuinely needs the prose and not the citations.\n * - It is short enough that a workspace open for years is not an indefinite\n *   archive of what its people typed into a text box.\n *\n * ⚠️ TTL deletion is best-effort within ~72h of expiry, so nothing may treat\n * an exchange's absence OR its presence as exact at the boundary. Nothing\n * does: the only reader addresses an exchange by id and tolerates a miss.\n */\nexport const ASSIST_EXCHANGE_RETENTION_DAYS = 180\n\nconst DAY_MS = 24 * 60 * 60 * 1000\n\n/**\n * When an exchange written at `now` expires. A `Date` rather than a number:\n * a TTL policy keys on a Firestore **Timestamp** and silently governs\n * nothing when the field is a number (`bookings.expiresAtMs` is the\n * documented non-target for exactly this reason). The Admin SDK converts a\n * JS `Date` to a Timestamp on write, which is how `cspViolationDaily` does\n * it and is why this module needs no firebase-admin type here.\n */\nexport function assistExchangeExpiry(now = new Date()): Date {\n  return new Date(now.getTime() + ASSIST_EXCHANGE_RETENTION_DAYS * DAY_MS)\n}\n\n/**\n * Free-tier daily message cap (level-1 answers only). Env-tunable without a\n * deploy of new code paths.\n *\n * What ten messages actually cost: about **$0.28 a day** at Sonnet list\n * rates, taking the worst case the clamps allow (see\n * `ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD` for the same arithmetic\n * carried to the monthly ceiling). A typical question costs a fraction of\n * that, because the worst case assumes a full 8,000-character history and a\n * 4,000-character question on every one of the ten.\n *\n * This docstring used to claim \"well under a cent a day\", which was the\n * pre-AGL-2441 figure and wrong by ~28x once the history clamp was measured\n * rather than assumed. It is restated here because it is the stated\n * justification for the size of this cap, and a justification that is off by\n * that much is how a cap ends up set by a number nobody re-derived.\n */\nexport function assistFreeDailyLimit(): number {\n  const raw = process.env.ASSIST_FREE_DAILY_LIMIT\n  // `Number('')` is 0, so an unset/empty var must fall through to the\n  // default rather than silently zeroing the free tier.\n  const parsed = raw ? Number(raw) : Number.NaN\n  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 10\n}\n\n/**\n * Entitled (Pro+/aiAssist) monthly message cap — a runaway guard, not a\n * product limit: high enough that no real user hits it, low enough that a\n * scripted client cannot turn one subscription into unbounded token spend.\n */\nexport function assistEntitledMonthlyLimit(): number {\n  const raw = process.env.ASSIST_ENTITLED_MONTHLY_LIMIT\n  const parsed = raw ? Number(raw) : Number.NaN\n  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 1000\n}\n\nexport interface AssistTokenUsage {\n  inputTokens: number\n  outputTokens: number\n  cacheReadTokens: number\n  cacheWriteTokens: number\n}\n\n/**\n * What one exchange DRAWS FROM THE CUSTOMER, at the serving model's billed\n * rates, rounded to 6dp — the figure `assistCreditsFromUsd` turns into\n * credits and the one the band, the cap and the invoice are measured in.\n *\n * The rates are the model catalog's (AGL-2939), keyed by model rather than\n * fixed at one model's because `ASSIST_MODEL` is an env override: a\n * one-line incident swap to a dearer model would otherwise keep reporting\n * the cheaper money, and per-org cost would read as roughly right — the\n * failure mode this whole meter exists to prevent. An unknown id is priced\n * at the dearest known tier on purpose, because an estimate that errs low is\n * worse than one that errs high, and a docs-only answer is metered under a\n * zero-priced sentinel (`AI_METER_SENTINELS`) so it lands in the same rollup\n * as a served one.\n *\n * NOT A COST (AGL-3015). A model may be billed above what its provider\n * charges, so this overstates what the exchange cost us by exactly that\n * markup. `estimateAssistProviderCostUsd` is the figure a margin or a spend\n * meter takes.\n */\nexport function estimateAssistCostUsd(\n  usage: AssistTokenUsage,\n  model: string,\n): number {\n  return estimateAiBilledUsd(usage, model)\n}\n\n/**\n * What one exchange COST US, at the serving model's provider rates, rounded\n * to 6dp — real money, recorded beside the billed figure so a margin is\n * taken against a bill we actually pay rather than against a price we\n * charge.\n *\n * At or below `estimateAssistCostUsd` for the same tokens, and equal to it\n * on every model billed at its provider's list.\n */\nexport function estimateAssistProviderCostUsd(\n  usage: AssistTokenUsage,\n  model: string,\n): number {\n  return estimateAiProviderCostUsd(usage, model)\n}\n\nexport interface AssistQuotaVerdict {\n  allowed: boolean\n  /** Which limit applied: free orgs meter daily, entitled orgs monthly. */\n  period: 'day' | 'month'\n  used: number\n  limit: number\n  remaining: number\n}\n\n/**\n * A reservation taken against the cap, carrying BOTH counter keys so it can\n * be handed back against the periods it actually moved rather than against\n * \"now\". A request that reserves at 23:59:59 and fails at 00:00:01 would\n * otherwise credit the NEXT day — capacity nobody paid for, arriving by the\n * one route a cap must never have.\n */\nexport interface AssistReservation extends AssistQuotaVerdict {\n  /** UTC day the daily counter was incremented for (`YYYY-MM-DD`). */\n  dayKey: string\n  /** Month the `assistUsage` doc was incremented for (`YYYY-MM`). */\n  monthKey: string\n  /**\n   * Which ceiling refused, or `null` when the message was reserved. The\n   * refusals need different words at the surface: a message cap resets on a\n   * clock the user can be told about, a spend ceiling does not, and the\n   * plan's own band (`'band'`, AGL-2653) is a line the org could have chosen\n   * to buy past — so its refusal has to name the switch that made it a wall.\n   * `'band'` is answered only when the figure that refused IS the band; an\n   * operator's lower figure refuses as `'budget'` even on a plan with one.\n   * `'cap'` (AGL-2898) is the org's own dollar ceiling on the overage it\n   * buys past the band — reachable only on a plan that sells past it.\n   * `'requests'`, `'refusals'`, `'account'` and `'platform'` (AGL-2925) are\n   * the Free taste's own precautions, and only a Free workspace can hear\n   * them. `'allotment'` (AGL-2942) is a hard allotment the person or the\n   * site has spent — see `allotment` for which.\n   *\n   * Only on the reservation, not on `AssistQuotaVerdict` — `checkAssistQuota`\n   * is a reporting read that never consults the spend ceiling, and widening\n   * the shared type would let a caller believe it had.\n   */\n  refusedBy: AiRefusedBy\n  /**\n   * WHICH dollar ceiling refused, when `refusedBy` is `'cap'` (AGL-3011).\n   *\n   * `'customer'` is the workspace's own ceiling (AGL-2898) and keeps the\n   * sentence and the 402 it has always had. The other four are Aglyn's own\n   * guards on the overage it extends between invoices: no card on file,\n   * accrual paused, this month's ceiling, and the unpaid balance at its\n   * limit. Absent on every other refusal and on an admitted request.\n   *\n   * The doors need it because the four answer differently: a missing card\n   * and a paused workspace are 402s a person can act on, and a ceiling or a\n   * settling balance are 429s they can only wait out.\n   */\n  capReason?: AiOverageCapReason | null\n  /**\n   * The figure the `cap` refusal was measured against — the month's ceiling\n   * for `'limit'`, the unpaid limit for `'settling'` — so the sentence the\n   * door renders quotes the number that actually refused rather than\n   * re-deriving one that could differ.\n   */\n  overageLimitUsd?: number | null\n  /** Overage accrued and not yet paid for, at the instant of the refusal. */\n  overageUnpaidUsd?: number | null\n  /**\n   * The allotments that applied to the person asking, measured (AGL-2942):\n   * which one refused, which one binds the usage strip, the caller's own\n   * credits this month, and the model allowlists. `null` when the request\n   * named nobody, and when a ceiling of the workspace's own refused before\n   * any allotment was read.\n   */\n  allotment?: AiAllotmentGate | null\n  /**\n   * The account the workspace's FREE spend is attributed to, or `null` for\n   * a workspace that is not on the Free plan (AGL-2925).\n   *\n   * Carried on the reservation so the door that meters the turn can hand\n   * the same attribution to `recordAssistCost` without resolving it twice:\n   * the reservation decided which account's allowance this request drew\n   * on, and the record must charge that account and no other.\n   */\n  free: FreeAssistAccount | null\n  /**\n   * Measured provider spend for `monthKey` in USD as read inside the\n   * transaction, or `null` when the transaction did not consult it.\n   *\n   * Nullable rather than defaulted to 0, and the difference is the whole\n   * point: an entitled reservation reads the monthly document anyway (it is\n   * the gate), but a free one gates on the daily counter and only opens the\n   * monthly document when a ceiling is configured — so there is a path with\n   * no figure to report. Reporting `0` there would be a constant wearing a\n   * measurement's name, and a caller could not tell \"this org has spent\n   * nothing\" from \"nobody looked\".\n   */\n  costUsd: number | null\n  /**\n   * The ceiling this reservation was measured against, or `null` when none\n   * applied — the plan's band, the operator's figure, or the lower of the\n   * two. See `assistMonthlyCeilingUsd`.\n   */\n  costLimitUsd: number | null\n  /**\n   * The org's PLAN assist band in USD, or `null` when its plan sells none.\n   *\n   * Separate from `costLimitUsd` because they answer different questions and\n   * a surface needs both. `costLimitUsd` is what refused; this is whether the\n   * org has a band at all, and therefore whether it can be shown a credit\n   * balance. An org with no band that met the operator's backstop must not be\n   * told it used up credits it was never sold, and an org whose band was\n   * undercut by an operator's figure must not be told it has credits left\n   * while being refused.\n   */\n  budgetUsd: number | null\n}\n\n/**\n * Reserve one assist message BEFORE the model is called (AGL-2057).\n *\n * This replaces `checkAssistQuota` on the request path, and the difference is\n * the whole point. `checkAssistQuota` READ the counter and let the request\n * through; the counter only moved in `recordAssistExchange`, at stream\n * COMPLETION. Two ways out of the cap followed, both of which spend real\n * provider tokens for an org that has no invoice to put them on:\n *\n * 1. **Concurrency.** N in-flight requests each read `used < limit` before any\n *    of them recorded. The per-uid rate limiter (20/min) was the only bound.\n * 2. **Abandoned streams.** Recording ran in the stream's completion handler,\n *    so a client that opened a request and dropped it never counted at all.\n *    Looped, that is UNBOUNDED spend on a free workspace — the cap simply\n *    never advanced. This is the fail-open that costs money silently.\n *\n * So the count moves to the front, inside a transaction: read and increment\n * are one atomic step, and a refused request never reaches the provider. The\n * lesson is AGL's own — fix WHEN the quota is evaluated, not how the counting\n * is done.\n *\n * Both counters move here (the daily one AND monthly `messages`) so message\n * counting has exactly one home. `recordAssistExchange` therefore records the\n * exchange, its tokens and its cost, and counts NO messages; calling it after\n * a reservation must not double-count.\n *\n * A plan-less org resolves as free upstream, so an unknown org gets the\n * SMALLER cap. That direction is deliberate.\n *\n * ## The spend gate is the one that matters now\n *\n * The message caps above are a runaway guard. The gate that decides what a\n * paying workspace gets is the SPEND ceiling, because assist actions differ\n * in cost by up to two orders of magnitude: a question is a few thousand\n * tokens and generating a screen carries a node tree, a component catalog and\n * theme tokens in and structured markup out. Counting both as one message\n * would let ten screen builds outspend a thousand questions while both read\n * as being within allowance.\n *\n * `org` is the billing document the caller already resolved `entitled` from.\n * It is optional and defaults to no org, which resolves as free — a band of\n * none, and therefore exactly the operator-backstop behaviour that predates\n * plan bands. Passing it is what makes a plan's own band bind.\n *\n * ## Refusal is legitimate here, unlike the transactional email carve-out\n *\n * A campaign send is refusable at its band and transactional mail is not,\n * because a blocked password reset locks somebody out of their own account.\n * Nothing assist does is that. It is help, not a person's data and not their\n * access: a refused question means the answer is not given, and a refused\n * build means the screen is built by hand in a besigner that still works. So\n * assist refuses at the band with no carve-out.\n *\n * What is never refused is what costs nothing. A docs-deflected answer and a\n * cache hit spend no tokens and take NO RESERVATION AT ALL — they return\n * before this function is reached — so a workspace at its band keeps getting\n * every answer the docs index can give it. That is not a carve-out inside\n * this gate; it is the reason those paths are ahead of it.\n *\n * ## The band is sold past by default (AGL-2653)\n *\n * Refusing at the band is legitimate; it is no longer the default. A plan\n * with an `extraAssistCreditsUsdPer1k` keeps reserving past its band and\n * `report-usage` bills the excess at that rate, unless the org's own\n * `assistOverage.hardCap` asks for the wall — `assistBandRefuses` is the one\n * place that rule lives. The ceiling below is composed from that answer, and\n * `refusedBy: 'band'` is how a refusal the switch caused is told apart from\n * one the operator's figure caused.\n *\n * ## The Free taste is metered twice (AGL-2925)\n *\n * A Free workspace's band is a wall, and a wall per workspace is not a\n * bound per person. So when `org` resolves to the Free plan the SAME\n * transaction also reads the workspace owner's account document and the\n * platform's day of free spend, and refuses on the account's daily request\n * cap, its refusal pause, its monthly allowance and the platform ceiling —\n * see `assist-free-taste.ts` for each. An admitted free reservation counts\n * the request on the account beside the org's own counters, so the release\n * path hands both back together.\n *\n * ## Allotments sit inside the band (AGL-2942)\n *\n * `subject` names the person asking and the site the request named. Once\n * the workspace's own ceilings — the message cap, the band or budget, the\n * overage cap — have admitted the request, the SAME transaction reads the\n * allotments that apply to that person and site and refuses as `allotment`\n * when a hard one is spent. After the workspace's rungs, so a workspace at\n * its band hears about its band and an allotment can never admit what the\n * band refused; before the Free taste's, which are precautions about the\n * account rather than decisions a manager made. Refusing moves no counter,\n * like every refusal above it. A soft allotment at 80% or 100% admits the\n * request and is announced once the transaction has committed.\n */\nexport async function reserveAssistMessage(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  entitled: boolean,\n  now = new Date(),\n  org: AssistMeteredOrg | null = null,\n  subject: AiAllotmentRequestSubject | null = null,\n): Promise<AssistReservation> {\n  const reservation = await reserveInTransaction(\n    firestore,\n    orgId,\n    entitled,\n    now,\n    org,\n    subject,\n  )\n  if (reservation.allotment?.alerts.length) {\n    announceAllotmentAlerts(firestore, orgId, org, reservation)\n  }\n  return reservation\n}\n\n/**\n * A soft allotment's crossing, told through the alert pipeline — off the\n * reservation's await path and never failing it: the request was admitted,\n * and a notification is not a reason to take that back. Loaded when the\n * first crossing arrives, so the modules that write notifications and send\n * mail are not part of every metered request.\n */\nfunction announceAllotmentAlerts(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  org: AssistMeteredOrg | null,\n  reservation: AssistReservation,\n): void {\n  const alerts = reservation.allotment?.alerts ?? []\n  void import('./ai-allotment-alerts')\n    .then(({ announceAiAllotmentAlerts }) =>\n      announceAiAllotmentAlerts(firestore, {\n        orgId,\n        orgSlug: typeof (org as { slug?: unknown } | null)?.slug === 'string'\n          ? String((org as { slug?: unknown }).slug)\n          : null,\n        month: reservation.monthKey,\n        alerts,\n      }),\n    )\n    .catch((error) => console.error('[ai-allotments] alert failed', orgId, error))\n}\n\n/**\n * The charge this turn may have earned (AGL-3011).\n *\n * Off the await path and never able to fail the turn: the tokens are already\n * spent, and making the answer wait on a Stripe round trip — or losing it to\n * one — would turn a billing problem into a product one. Loaded when the\n * first chargeable turn arrives, so the modules that read org billing and\n * call Stripe are not part of every metered request.\n *\n * Returns before loading anything at all while `AI_OVERAGE_INVOICED_FROM`\n * names no month, which is how this ships: AI overage bills through the\n * monthly meter exactly as it does today, and this costs one string compare.\n *\n * A turn whose process ends before this finishes is covered three ways: the\n * next turn tries again, the reconcile sweep finishes a half-made charge,\n * and the gate refuses at the unpaid limit regardless.\n */\nfunction chargeAccruedOverage(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  month: string,\n  now: Date,\n): void {\n  if (!aiOverageBillsByInvoice(month)) return\n  void import('../billing/ai-overage-trigger')\n    .then(({ chargeAccruedAiOverage }) =>\n      chargeAccruedAiOverage(firestore, orgId, month, now),\n    )\n    .catch((error) => console.error('[ai-overage] charge failed', orgId, error))\n}\n\nasync function reserveInTransaction(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  entitled: boolean,\n  now: Date,\n  org: AssistMeteredOrg | null,\n  subject: AiAllotmentRequestSubject | null,\n): Promise<AssistReservation> {\n  const increment = FieldValue.increment\n  const serverTimestamp = FieldValue.serverTimestamp\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const day = assistUsageDay(now)\n  const month = assistUsageMonth(now)\n  const dailyRef = orgRef.collection('counters').doc('assistMessagesDaily')\n  const monthlyRef = orgRef.collection('assistUsage').doc(month)\n  const limit = entitled ? assistEntitledMonthlyLimit() : assistFreeDailyLimit()\n  const period: 'day' | 'month' = entitled ? 'month' : 'day'\n  const gateRef = entitled ? monthlyRef : dailyRef\n  const gateField = entitled ? 'messages' : day\n  // The Free taste's attribution, resolved once and carried on every\n  // answer below: `null` for any paid plan, and for the paths that never\n  // consult it.\n  const free = freeAssistAccount(org)\n  const accountRef =\n    free?.accountUid ? freeAccountUsageRef(firestore, free.accountUid, month) : null\n\n  // The plan's band first, then whether it refuses at all, then whatever the\n  // operator did about it. Resolved OUTSIDE the transaction: it is pure\n  // arithmetic over a document the caller already holds, and a transaction\n  // that retries must not re-derive a ceiling that could have moved between\n  // attempts.\n  const budgetUsd = resolveAssistBudgetUsd(org)\n  const bandRefuses = assistBandRefuses(org)\n  // An uncapped staff comp has no band and no backstop default (AGL-3049).\n  const costLimitUsd = assistMonthlyCeilingUsd(\n    budgetUsd,\n    bandRefuses,\n    isUncappedPlanComp(org),\n  )\n  // The ceiling IS the band when the band refuses and nothing lower undercut\n  // it. That is the refusal the surface has to attribute to the org's own\n  // switch (or to a plan that sells no overage); a lower operator figure is\n  // the operator's decision and keeps the operator's word.\n  const ceilingIsBand =\n    bandRefuses && budgetUsd !== null && costLimitUsd === budgetUsd\n  // The org's own ceiling on the overage it buys (AGL-2898). Only a band\n  // that is SOLD past has an overage to cap, so a band that refuses leaves\n  // no ceiling to consult: past a wall there is nothing to be over.\n  const overageCapUsd = bandRefuses ? null : resolveAssistOverageCapUsd(org)\n  // AGLYN'S OWN GUARDS ON THE OVERAGE IT EXTENDS (AGL-3011), resolved here\n  // for the same reason the ceilings above are: pure arithmetic over a\n  // document the caller already holds, and a transaction that retries must\n  // not re-derive them.\n  //\n  // They apply only where there IS overage to guard — a band that is sold\n  // past, at a rate — and only from the month the platform bills that\n  // overage by invoice. Before that month nothing charges, so nothing is\n  // ever paid for, so an unpaid-balance guard would refuse every workspace\n  // with no invoice to pay. See `ai-overage-cutover.ts`.\n  const guardsOverage =\n    !bandRefuses &&\n    budgetUsd !== null &&\n    resolveAssistOverageRateUsdPer1k(org) !== null &&\n    aiOverageGuardsApply(month)\n\n  return firestore.runTransaction(async (tx) => {\n    // Every read before any write — Firestore requires that ordering, and it\n    // is also what makes check-and-increment a single atomic step.\n    const snapshot = await tx.get(gateRef)\n    // The spend ceiling reads the SAME monthly document the entitled gate\n    // already read, so an entitled reservation costs no extra read at all\n    // and a free one costs a second read only when a ceiling is configured.\n    const monthlySnapshot = entitled\n      ? snapshot\n      : costLimitUsd === null\n        ? null\n        : await tx.get(monthlyRef)\n    // The taste's two extra reads, only for a Free workspace: the owner's\n    // account month (when the org names an owner) and the platform's day.\n    // Inside the transaction with everything else, so the rungs they feed\n    // are decided against the same snapshot the counters move under.\n    // The workspace's overage standing (AGL-3011): one document, read only\n    // where the guards apply, beside the reads the gate already makes. The\n    // allotment gate reads a plugin document in this transaction the same\n    // way, and for the same reason — a guard decided against a snapshot the\n    // transaction did not take is a guard a concurrent burst walks past.\n    const standingSnapshot = guardsOverage\n      ? await tx.get(\n          orgRef.collection(AI_BILLING_SUBCOLLECTION).doc(AI_BILLING_STANDING_DOC),\n        )\n      : null\n    const accountSnapshot = accountRef ? await tx.get(accountRef) : null\n    const platformSnapshot = free\n      ? await tx.get(platformFreeSpendRef(firestore, day))\n      : null\n    const used = Number(snapshot.get(gateField) ?? 0)\n    const costUsd = monthlySnapshot\n      ? Number(monthlySnapshot.get('estCostUsd') ?? 0)\n      : null\n    if (!(used < limit)) {\n      recordAssistRefusal(firestore, orgId, month, 'messages')\n      return {\n        allowed: false,\n        refusedBy: 'messages' as const,\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: 0,\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n      }\n    }\n    // The dollar ceiling, checked AFTER the message cap so the cheaper and\n    // more explicable refusal wins when both apply. Refusing here leaves both\n    // counters untouched, exactly like the message refusal above: the point\n    // of a spend ceiling is that the org above it spends nothing more.\n    if (costLimitUsd !== null && costUsd !== null && !(costUsd < costLimitUsd)) {\n      recordAssistRefusal(firestore, orgId, month, ceilingIsBand ? 'band' : 'budget')\n      return {\n        allowed: false,\n        refusedBy: ceilingIsBand ? ('band' as const) : ('budget' as const),\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: Math.max(0, limit - used),\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n      }\n    }\n    // The org's ceiling on its OVERAGE (AGL-2898), checked after the band\n    // because it only exists on a band that is sold past. Same shape as the\n    // refusals above — inside the transaction, against the spend the\n    // transaction read, moving no counter — so a burst of concurrent\n    // requests at the ceiling cannot each read \"under\" and all proceed.\n    // `assistOverageCapReached` prices the month's overage the way the\n    // invoice will, so the figure that stops here is the figure that would\n    // have been billed.\n    if (\n      overageCapUsd !== null &&\n      costUsd !== null &&\n      assistOverageCapReached(org, costUsd)\n    ) {\n      recordAssistRefusal(firestore, orgId, month, 'cap')\n      return {\n        allowed: false,\n        refusedBy: 'cap' as const,\n        // Whose ceiling, for the doors (AGL-3011). This one is the\n        // workspace's own, and it keeps the sentence and the 402 it has had\n        // since AGL-2898 — the four below are Aglyn's and have their own.\n        capReason: 'customer' as const,\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: Math.max(0, limit - used),\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n      }\n    }\n    // AGLYN'S OWN OVERAGE GUARDS (AGL-3011), after the workspace's own\n    // ceiling so a workspace that set a limit is told about ITS limit.\n    //\n    // Four refusals, all `refusedBy: 'cap'` with a `capReason`: no card on\n    // file, accrual paused, this month's ceiling reached, and the unpaid\n    // balance at its limit. The last is the one that makes the bound a\n    // bound — it compares what the month accrued against what it PAID, so\n    // overage stops at the unpaid limit whether or not any charge ever ran.\n    //\n    // Inside the transaction, against the figures the transaction read,\n    // moving no counter: a burst of concurrent requests at the limit cannot\n    // each read \"under\" and all proceed.\n    const overageGuard =\n      guardsOverage && costUsd !== null && budgetUsd !== null && costUsd >= budgetUsd\n        ? aiOverageRefusal({\n            // Priced the way the invoice prices it, so the figure that\n            // stops here is the figure that would have been charged.\n            overageUsd: assistMonthOverage(org, costUsd).overageMonthlyUsd,\n            paidUsd: readAiOverageMonthLedger(\n              monthlySnapshot?.data() ?? null,\n            ).paidUsd,\n            standing: readAiOverageStanding(\n              standingSnapshot?.exists ? (standingSnapshot.data() ?? null) : null,\n            ),\n            now,\n          })\n        : null\n    if (overageGuard) {\n      recordAssistRefusal(firestore, orgId, month, 'cap')\n      return {\n        allowed: false,\n        refusedBy: 'cap' as const,\n        capReason: overageGuard.capReason,\n        overageLimitUsd: overageGuard.limitUsd,\n        overageUnpaidUsd: overageGuard.unpaidUsd,\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: Math.max(0, limit - used),\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n      }\n    }\n    // The allotments that apply to the person asking (AGL-2942): read only\n    // now that the workspace's own ceilings admitted the request, so an\n    // allotment is decided inside the band and a refusal at the band costs\n    // no allotment read. Reads, still — every write waits below.\n    const allotment = subject\n      ? await readAiAllotmentGate(\n          (ref) => tx.get(ref),\n          orgRef,\n          subject,\n          month,\n          monthlySnapshot,\n        )\n      : null\n    if (allotment?.refusal) {\n      recordAssistRefusal(firestore, orgId, month, 'allotment')\n      return {\n        allowed: false,\n        refusedBy: 'allotment' as const,\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: Math.max(0, limit - used),\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n        allotment,\n      }\n    }\n    // The Free taste's own rungs (AGL-2925), AFTER the workspace's, so a\n    // workspace at its own band is told about its own band. Same shape:\n    // decided inside the transaction, against what it read, moving nothing.\n    const tasteRefusal = free\n      ? freeTasteRefusal(freeTasteReadsFrom(accountSnapshot, platformSnapshot, day))\n      : null\n    if (tasteRefusal) {\n      recordAssistRefusal(firestore, orgId, month, tasteRefusal)\n      return {\n        allowed: false,\n        refusedBy: tasteRefusal,\n        period,\n        dayKey: day,\n        monthKey: month,\n        used,\n        limit,\n        remaining: Math.max(0, limit - used),\n        costUsd,\n        costLimitUsd,\n        budgetUsd,\n        free,\n        allotment,\n      }\n    }\n    // `set(…, { merge: true })` and never `update()`: the counter document\n    // does not exist before an org's first message, and `update()` throws\n    // NOT_FOUND on a missing doc where a merging set conjures it.\n    tx.set(dailyRef, { [day]: increment(1) }, { merge: true })\n    tx.set(\n      monthlyRef,\n      { month, messages: increment(1), updatedAt: serverTimestamp() },\n      { merge: true },\n    )\n    // The account's request, counted in the same commit as the org's\n    // message — one atomic step, or the daily request cap has the same\n    // read-then-write hole the message cap was moved here to close.\n    if (accountRef) {\n      tx.set(accountRef, freeAccountReservationWrite(month, day), { merge: true })\n    }\n    return {\n      allowed: true,\n      refusedBy: null,\n      period,\n      dayKey: day,\n      monthKey: month,\n      used: used + 1,\n      limit,\n      remaining: Math.max(0, limit - (used + 1)),\n      costUsd,\n      costLimitUsd,\n      budgetUsd,\n      free,\n      allotment,\n    }\n  })\n}\n\n/** A reservation with every dollar of provider spend removed. */\nexport interface PublicAssistQuota {\n  allowed: boolean\n  period: 'day' | 'month'\n  used: number\n  limit: number\n  remaining: number\n  refusedBy: AiRefusedBy\n  /**\n   * The credit standing, or `null` when the org's plan sells no assist band.\n   *\n   * Null rather than a converted backstop, because a Free workspace refused\n   * at the operator's ceiling has no credit balance to report and telling it\n   * \"0 of 40,000 credits left\" names a band it was never sold.\n   */\n  credits: PublicAssistCredits | null\n}\n\n/**\n * The reservation as a CUSTOMER may see it.\n *\n * `AssistReservation` carries `costUsd`, `costLimitUsd` and `budgetUsd`, and\n * all three are our provider bill at the serving model's list rates. Handing\n * the reservation itself to a browser publishes our model costs, and they\n * would move under customers on every model swap. Assist is surfaced in\n * CREDITS, whose meaning is fixed, and this is the one function that crosses\n * that boundary — every route returning quota to a client returns this.\n *\n * `limit` and `remaining` stay MESSAGES, unchanged: the free tier's daily\n * message cap is a real, separately-worded limit that the panel already\n * renders, and folding it into credits would make \"10 messages a day\"\n * unsayable.\n *\n * The credit view reads against the LOWER of the plan band and the effective\n * ceiling. The band, because it is the quantity the org was sold and the line\n * `report-usage` bills past — an org buying overage (AGL-2653) has no ceiling\n * at all, and reading against `null` would blank its standing at \"used 900 of\n * nothing\". The ceiling, because an org whose band was undercut by an\n * operator's figure must not be told it has credits left while being refused.\n * `remaining` clamps at zero, so a workspace past its band reads as spent\n * rather than as owed.\n */\nexport function publicAssistQuota(\n  reservation: AssistReservation,\n): PublicAssistQuota {\n  const { budgetUsd, costLimitUsd, costUsd } = reservation\n  const ceilingUsd =\n    budgetUsd === null\n      ? null\n      : costLimitUsd === null\n        ? budgetUsd\n        : Math.min(budgetUsd, costLimitUsd)\n  return {\n    allowed: reservation.allowed,\n    period: reservation.period,\n    used: reservation.used,\n    limit: reservation.limit,\n    remaining: reservation.remaining,\n    refusedBy: reservation.refusedBy,\n    credits: ceilingUsd === null ? null : publicAssistCredits(costUsd, ceilingUsd),\n  }\n}\n\n/**\n * Hand a reservation back when the provider was never reached (AGL-2057): an\n * upstream 502 spent no tokens, so it must not spend one of a free\n * workspace's ten messages a day either.\n *\n * Released against the keys the RESERVATION recorded — see\n * `AssistReservation`. Each counter is read first so neither can be driven\n * below zero, even if the same reservation were released twice: a negative\n * counter is extra capacity, and the release path must not become the\n * laundering route the reservation was added to close.\n */\nexport async function releaseAssistMessage(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  reservation: Pick<AssistReservation, 'allowed' | 'dayKey' | 'monthKey'> &\n    Partial<Pick<AssistReservation, 'free'>>,\n): Promise<void> {\n  if (!reservation.allowed) return\n  const increment = FieldValue.increment\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const dailyRef = orgRef.collection('counters').doc('assistMessagesDaily')\n  const monthlyRef = orgRef.collection('assistUsage').doc(reservation.monthKey)\n  // The account's request goes back with the org's message (AGL-2925) —\n  // against the same keys, read first for the same reason.\n  const accountRef = reservation.free?.accountUid\n    ? freeAccountUsageRef(firestore, reservation.free.accountUid, reservation.monthKey)\n    : null\n  await firestore.runTransaction(async (tx) => {\n    const dailySnapshot = await tx.get(dailyRef)\n    const monthlySnapshot = await tx.get(monthlyRef)\n    const accountSnapshot = accountRef ? await tx.get(accountRef) : null\n    if (Number(dailySnapshot.get(reservation.dayKey) ?? 0) > 0) {\n      tx.set(dailyRef, { [reservation.dayKey]: increment(-1) }, { merge: true })\n    }\n    if (Number(monthlySnapshot.get('messages') ?? 0) > 0) {\n      tx.set(monthlyRef, { messages: increment(-1) }, { merge: true })\n    }\n    if (accountRef && accountSnapshot) {\n      const days = (accountSnapshot.get('days') ?? {}) as Record<\n        string,\n        { requests?: unknown } | undefined\n      >\n      const today = Number(days[reservation.dayKey]?.requests ?? 0)\n      const month = Number(accountSnapshot.get('requests') ?? 0)\n      if (today > 0 || month > 0) {\n        tx.set(\n          accountRef,\n          {\n            ...(month > 0 ? { requests: increment(-1) } : {}),\n            ...(today > 0\n              ? { days: { [reservation.dayKey]: { requests: increment(-1) } } }\n              : {}),\n          },\n          { merge: true },\n        )\n      }\n    }\n  })\n}\n\n/**\n * READ-ONLY view of where an org stands against its cap.\n *\n * ⚠️ NOT the enforcement path any more (AGL-2057) — `reserveAssistMessage` is.\n * A read that is followed by a separate write is exactly the shape that let\n * concurrent requests and abandoned streams past the cap; this function is\n * kept for reporting and for tests that want the standing without consuming a\n * message. **Anything that decides whether to call the model must reserve.**\n *\n * Free orgs meter per UTC day; entitled orgs carry the monthly runaway guard.\n */\nexport async function checkAssistQuota(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  entitled: boolean,\n  now = new Date(),\n): Promise<AssistQuotaVerdict> {\n  if (entitled) {\n    const limit = assistEntitledMonthlyLimit()\n    const month = assistUsageMonth(now)\n    const snapshot = await firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('assistUsage')\n      .doc(month)\n      .get()\n    const used = Number(snapshot.get('messages') ?? 0)\n    return {\n      allowed: used < limit,\n      period: 'month',\n      used,\n      limit,\n      remaining: Math.max(0, limit - used),\n    }\n  }\n  const limit = assistFreeDailyLimit()\n  const day = assistUsageDay(now)\n  const snapshot = await firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection('counters')\n    .doc('assistMessagesDaily')\n    .get()\n  const used = Number(snapshot.get(day) ?? 0)\n  return {\n    allowed: used < limit,\n    period: 'day',\n    used,\n    limit,\n    remaining: Math.max(0, limit - used),\n  }\n}\n\n/**\n * The DERIVED half of one assist turn: what it cost, what it cited, how it\n * stopped. No prose and no uid, by construction — see the module header.\n *\n * Split out of `AssistExchangeRecord` (AGL-2073) because the besigner copy\n * assistant at `/api/ai/assist` needs the meters WITHOUT the verbatim half.\n * What a customer types into that surface is their own site copy and blog\n * bodies, and retaining it for 180 days is a data flow the published privacy\n * disclosure does not describe. The margin question — what did this org's\n * assist usage cost us — is answered entirely by this record.\n */\nexport interface AssistSignalRecord {\n  /** Console route the user asked from, e.g. `/org/acme/hosts`. */\n  route: string\n  hostId: string | null\n  model: string\n  /** Capability tier served: 'free' (level 1) or 'entitled' (level 1–2). */\n  tier: 'free' | 'entitled'\n  usage: AssistTokenUsage\n  /** Docs paths cited in grounding, for the docs-gap mining view. */\n  docsPaths: string[]\n  /**\n   * The model's own `stop_reason` (`end_turn` | `refusal` | `max_tokens` |\n   * …), or null when the stream ended without one. Stored because a\n   * refusal and a truncation both look like a short answer in the data —\n   * and a rising refusal rate is a prompt problem, while a rising\n   * max_tokens rate is a ceiling problem. They need different fixes.\n   */\n  stopReason: string | null\n  /**\n   * True when the answer came from the docs index with NO model call\n   * (AGL-2486).\n   *\n   * Optional only so the two existing callers need not be edited in the same\n   * breath; it is written as an explicit boolean either way, never left\n   * undefined on the document. An absent field would make \"this turn used no\n   * model\" and \"this turn predates the flag\" the same value, and the whole\n   * point of the field is that an operator can tell how much of the month was\n   * free.\n   */\n  deflected?: boolean\n  /**\n   * The Free taste's attribution (AGL-2925), copied from the reservation\n   * that admitted this turn: `null` or absent for a paid workspace, and for\n   * a turn that took no reservation. Present, the turn's cost also lands on\n   * the platform's day of free spend and — unless the model refused — on\n   * the owner's account allowance.\n   */\n  free?: FreeAssistAccount | null\n  /**\n   * Who asked, for the per-user rollup (AGL-2928) and NOTHING else: the\n   * signal document never carries it, for the reason the module header\n   * gives. Optional because a meter that cannot say who asked still owes\n   * the org its cost; such a request attributes to nobody.\n   */\n  uid?: string | null\n  /**\n   * What the request was for, as the per-user rollup buckets it. A job\n   * step names its job's kind; a meter without one is read off `route`.\n   */\n  kind?: AiUsageKind\n  /**\n   * How many canvas edits the answer proposed (AGL-2906), on a turn that\n   * proposed any. A count and nothing of the edits: the applied-edit door\n   * reads it back as the evidence that this turn issued a proposal, and a\n   * turn that proposed none carries no field at all.\n   */\n  editOps?: number\n}\n\n/** A signal PLUS the verbatim half — the question, the answer, the asker. */\nexport interface AssistExchangeRecord extends AssistSignalRecord {\n  uid: string\n  question: string\n  answer: string\n}\n\n/**\n * The signal document and the monthly cost rollup — the two writes every\n * assist turn owes regardless of whether its prose is kept. Shared by\n * `recordAssistExchange` and `recordAssistCost` so the meter has exactly one\n * writer and the two entrypoints can never drift into reporting different\n * money for the same tokens.\n */\nfunction writeSignalAndRollup(\n  firestore: FirebaseFirestore.Firestore,\n  batch: FirebaseFirestore.WriteBatch,\n  orgRef: FirebaseFirestore.DocumentReference,\n  signalRef: FirebaseFirestore.DocumentReference,\n  record: AssistSignalRecord,\n  now: Date,\n  /** What the request was for, as the caller's own rollup names it. */\n  kind: AiUsageKind,\n): void {\n  const increment = FieldValue.increment\n  const serverTimestamp = FieldValue.serverTimestamp\n  const estCostUsd = estimateAssistCostUsd(record.usage, record.model)\n  // What the same tokens COST US (AGL-3015). Recorded beside the billed\n  // figure rather than derived from it later: a month is a sum over models\n  // and a markup lives on the model, so once the exchanges are added up the\n  // mix is gone and the two can no longer be told apart.\n  const providerCostUsd = estimateAssistProviderCostUsd(record.usage, record.model)\n  const deflected = record.deflected === true\n  const free = record.free ?? null\n  // On the Free taste a `refusal` stop draws no credits (AGL-2925): the\n  // org's band and the account's allowance stay where they were, and the\n  // cost goes to the platform's day instead, where it is still our money.\n  // Everywhere else the tokens are metered as they always were.\n  const refusedFree = free !== null && record.stopReason === 'refusal'\n  // The site's credits for its allotment (AGL-2942), rounded as the person's\n  // own `byHost` rounds them, so a site's month equals the sum of its\n  // people's months on it. Not zeroed for a declined Free turn, for the same\n  // reason the person's month is not: the site did spend it.\n  const hostId = String(record.hostId ?? '').trim()\n  const hostCredits = hostId ? assistCreditsFromUsd(estCostUsd) : 0\n  // The analytic half. No prose and NO uid — deliberately, because a signal\n  // row that names the asker is just the exchange with the words removed,\n  // and would re-create as an access-request obligation exactly what the\n  // expiry was meant to retire. What survives answers \"which docs gaps, at\n  // what cost, rated how\", which is the whole of the data loop.\n  batch.set(signalRef, {\n    route: record.route,\n    hostId: record.hostId,\n    model: record.model,\n    tier: record.tier,\n    kind,\n    inputTokens: record.usage.inputTokens,\n    outputTokens: record.usage.outputTokens,\n    cacheReadTokens: record.usage.cacheReadTokens,\n    cacheWriteTokens: record.usage.cacheWriteTokens,\n    estCostUsd,\n    [ASSIST_PROVIDER_COST_FIELD]: providerCostUsd,\n    docsPaths: record.docsPaths,\n    stopReason: record.stopReason,\n    deflected,\n    feedback: null,\n    ...(record.editOps && record.editOps > 0\n      ? { editOps: Math.floor(record.editOps) }\n      : {}),\n    createdAt: serverTimestamp(),\n  })\n  // NO message counting here (AGL-2057). Both message counters are moved by\n  // `reserveAssistMessage`, BEFORE the provider is called — which is what\n  // makes the cap a cap. Counting again here would double every message, and\n  // more importantly would restore the belief that this is where the cap\n  // advances: it is not, and an exchange that never reaches this function\n  // (an abandoned stream) has already been counted.\n  batch.set(\n    orgRef.collection('assistUsage').doc(assistUsageMonth(now)),\n    {\n      month: assistUsageMonth(now),\n      // The free half of the month, counted where the paid half already is\n      // (AGL-2486). `messages` counts what the RESERVATION moved — model\n      // turns — and a deflected turn takes no reservation because it spends\n      // nothing, so without this counter the questions Assist answered for\n      // free are invisible and the deflection rate can only be guessed at.\n      // Total questions asked is `messages + deflected`; neither field alone\n      // is that number, and reading `messages` as it would understate usage\n      // by exactly the amount this work was done to create.\n      deflected: increment(deflected ? 1 : 0),\n      inputTokens: increment(record.usage.inputTokens),\n      outputTokens: increment(record.usage.outputTokens),\n      cacheReadTokens: increment(record.usage.cacheReadTokens),\n      cacheWriteTokens: increment(record.usage.cacheWriteTokens),\n      estCostUsd: increment(refusedFree ? 0 : estCostUsd),\n      // Our bill for the same turns, credited and refused alike on the same\n      // rule as `estCostUsd` above, so the month's two dollar figures always\n      // describe the same set of exchanges and a margin taken across them is\n      // a margin over one period.\n      [ASSIST_PROVIDER_COST_FIELD]: increment(refusedFree ? 0 : providerCostUsd),\n      // The refused half of a Free month, kept beside the credited half so\n      // the rollup still says what the month cost us in total. Its own field\n      // name (AGL-2986): `refusals` on this document is the gate's map of\n      // refusal counts by reason (`recordAssistRefusal`), and an increment\n      // over a map replaces the map with the operand.\n      refusedTurns: increment(refusedFree ? 1 : 0),\n      refusedCostUsd: increment(refusedFree ? estCostUsd : 0),\n      // What each model request was for, with its tokens (AGL-2937): cost\n      // per generation, tokens per kind and the cache hit rate are read off\n      // this map. A docs answer bought nothing and is left out. Both dollar\n      // figures are kept — what the kind drew and what it cost us — because\n      // the staff card reading this map is asking the second question and\n      // the credit meter beside it is asking the first.\n      // A declined Free turn is counted in both.\n      ...(deflected\n        ? {}\n        : {\n            [AI_USAGE_MONTH_KINDS_FIELD]: {\n              [kind]: {\n                requests: increment(1),\n                estCostUsd: increment(estCostUsd),\n                [ASSIST_PROVIDER_COST_FIELD]: increment(providerCostUsd),\n                [AI_USAGE_TOKENS_FIELD]: aiTokenIncrements(record.usage),\n              },\n            },\n          }),\n      ...(hostCredits > 0\n        ? { [AI_HOST_CREDITS_FIELD]: { [hostId]: increment(hostCredits) } }\n        : {}),\n      updatedAt: serverTimestamp(),\n    },\n    { merge: true },\n  )\n  if (free) {\n    const day = assistUsageDay(now)\n    const writes = freeTasteMeterWrites({\n      estCostUsd,\n      refused: refusedFree,\n      day,\n      month: assistUsageMonth(now),\n    })\n    batch.set(platformFreeSpendRef(firestore, day), writes.platform, { merge: true })\n    if (free.accountUid) {\n      batch.set(\n        freeAccountUsageRef(firestore, free.accountUid, assistUsageMonth(now)),\n        writes.account,\n        { merge: true },\n      )\n    }\n  }\n}\n\n/**\n * After a Free turn's batch commits: the ceiling's announcements, which\n * need the figure the batch just moved and must never fail the turn.\n */\nasync function announceFreeTurn(\n  firestore: FirebaseFirestore.Firestore,\n  record: AssistSignalRecord,\n  now: Date,\n): Promise<void> {\n  if (!record.free) return\n  await announcePlatformFreeSpend(firestore, assistUsageDay(now)).catch((error) =>\n    console.error('[ai-free-spend] announcement failed', error),\n  )\n}\n\n/**\n * Meter one assist turn that keeps NO verbatim record (AGL-2073) — the\n * besigner copy assistant at `/api/ai/assist`.\n *\n * Writes the signal and folds tokens/cost into the monthly rollup, and writes\n * nothing to `assistExchanges`. Same reason the console route splits the two:\n * the loop's corpus was never the words. Here there is no loop to feed and no\n * thumbs to collect, so the words are simply not taken.\n *\n * Like `recordAssistExchange` it counts NO message — the reservation did that\n * before the tokens were spent. Callers should not let a metering failure fail\n * the request: the tokens are already spent either way, and refusing the\n * answer the customer paid for would make an accounting problem a product one.\n */\nexport async function recordAssistCost(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  record: AssistSignalRecord,\n  now = new Date(),\n): Promise<string> {\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const signalRef = orgRef.collection('assistSignals').doc()\n  const batch = firestore.batch()\n  const kind = record.kind ?? aiUsageKindFromRoute(record.route)\n  writeSignalAndRollup(firestore, batch, orgRef, signalRef, record, now, kind)\n  // The person's month, on the SAME batch as the org's (AGL-2928), so the\n  // two rollups commit together or not at all.\n  recordUserAiUsage(batch, orgRef, {\n    uid: record.uid,\n    month: assistUsageMonth(now),\n    estCostUsd: estimateAssistCostUsd(record.usage, record.model),\n    hostId: record.hostId,\n    kind,\n    usage: record.usage,\n  })\n  await batch.commit()\n  chargeAccruedOverage(firestore, orgId, assistUsageMonth(now), now)\n  await announceFreeTurn(firestore, record, now)\n  return signalRef.id\n}\n\n/**\n * The data loop + meters, one batch: writes the two halves of the exchange\n * and folds tokens/cost into the monthly usage doc. It does NOT count the\n * message — `reserveAssistMessage` already did, before the tokens were spent.\n * Returns the shared id (the feedback route addresses it later). Callers\n * `await` this — an exchange that fails to record should surface in logs,\n * but the batch is one round trip so it does not add meaningful latency.\n *\n * The two halves share one id ON PURPOSE. It is what lets the feedback route\n * keep its single-id signature, and it is what makes an exchange and its\n * signal joinable for as long as both exist — without storing a second\n * pointer that could rot.\n */\nexport async function recordAssistExchange(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  record: AssistExchangeRecord,\n  now = new Date(),\n): Promise<string> {\n  const serverTimestamp = FieldValue.serverTimestamp\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const exchangeRef = orgRef.collection('assistExchanges').doc()\n  const signalRef = orgRef.collection('assistSignals').doc(exchangeRef.id)\n\n  const batch = firestore.batch()\n  // The personal half. Everything a person typed, everything we said back,\n  // and who asked — and nothing else. Expires.\n  batch.set(exchangeRef, {\n    uid: record.uid,\n    question: record.question,\n    answer: record.answer,\n    hostId: record.hostId,\n    createdAt: serverTimestamp(),\n    expiresAt: assistExchangeExpiry(now),\n  })\n  // A chat turn is an `assist` request whatever console route it was asked\n  // from — on the signal, the org's month and the asker's month alike.\n  const kind = record.kind ?? 'assist'\n  // The analytic half plus the meters — the same writer `recordAssistCost`\n  // uses, so the two assist entrypoints can never report different money for\n  // the same tokens.\n  writeSignalAndRollup(firestore, batch, orgRef, signalRef, record, now, kind)\n  // And the asker's month, on the same batch (AGL-2928).\n  recordUserAiUsage(batch, orgRef, {\n    uid: record.uid,\n    month: assistUsageMonth(now),\n    estCostUsd: estimateAssistCostUsd(record.usage, record.model),\n    hostId: record.hostId,\n    kind,\n    usage: record.usage,\n  })\n  await batch.commit()\n  chargeAccruedOverage(firestore, orgId, assistUsageMonth(now), now)\n  await announceFreeTurn(firestore, record, now)\n  return exchangeRef.id\n}\n\n/**\n * Record explicit thumbs feedback on an exchange. Only the exchange's own\n * org path is addressable, and only the two literal values are accepted —\n * the route validates membership before calling this.\n *\n * The rating lands on the SIGNAL document, not the exchange (AGL-1972). A\n * thumbs-down is the single most valuable row in the data loop and it is not\n * personal content, so it must not be reaped along with the prose that\n * earned it. Existence is checked on the signal too: it is the document\n * being written, and after the exchange expires it is the only one left.\n */\nexport async function recordAssistFeedback(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  exchangeId: string,\n  feedback: 'up' | 'down',\n): Promise<boolean> {\n  const ref = firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection('assistSignals')\n    .doc(exchangeId)\n  const snapshot = await ref.get()\n  if (!snapshot.exists) return false\n  await ref.update({ feedback })\n  return true\n}\n"],"names":["FieldValue","ASSIST_PROVIDER_COST_FIELD","assistBandRefuses","assistCreditsFromUsd","assistMonthOverage","assistOverageCapReached","publicAssistCredits","resolveAssistBudgetUsd","resolveAssistOverageCapUsd","resolveAssistOverageRateUsdPer1k","aiOverageRefusal","aiOverageBillsByInvoice","aiOverageGuardsApply","AI_BILLING_STANDING_DOC","AI_BILLING_SUBCOLLECTION","readAiOverageMonthLedger","readAiOverageStanding","AI_HOST_CREDITS_FIELD","readAiAllotmentGate","isUncappedPlanComp","assistMonthlyCeilingUsd","estimateAiBilledUsd","estimateAiProviderCostUsd","recordAssistRefusal","announcePlatformFreeSpend","freeAccountReservationWrite","freeAccountUsageRef","freeAssistAccount","freeTasteMeterWrites","freeTasteReadsFrom","freeTasteRefusal","platformFreeSpendRef","aiTokenIncrements","recordUserAiUsage","AI_USAGE_MONTH_KINDS_FIELD","AI_USAGE_TOKENS_FIELD","aiUsageKindFromRoute","assistUsageMonth","now","Date","toISOString","slice","assistUsageDay","ASSIST_EXCHANGE_RETENTION_DAYS","DAY_MS","assistExchangeExpiry","getTime","assistFreeDailyLimit","raw","process","env","ASSIST_FREE_DAILY_LIMIT","parsed","Number","NaN","isFinite","Math","floor","assistEntitledMonthlyLimit","ASSIST_ENTITLED_MONTHLY_LIMIT","estimateAssistCostUsd","usage","model","estimateAssistProviderCostUsd","reserveAssistMessage","firestore","orgId","entitled","org","subject","reservation","reserveInTransaction","allotment","alerts","length","announceAllotmentAlerts","then","announceAiAllotmentAlerts","orgSlug","slug","String","month","monthKey","catch","error","console","chargeAccruedOverage","chargeAccruedAiOverage","increment","serverTimestamp","orgRef","collection","doc","day","dailyRef","monthlyRef","limit","period","gateRef","gateField","free","accountRef","accountUid","budgetUsd","bandRefuses","costLimitUsd","ceilingIsBand","overageCapUsd","guardsOverage","runTransaction","tx","snapshot","monthlySnapshot","standingSnapshot","get","accountSnapshot","platformSnapshot","used","costUsd","allowed","refusedBy","dayKey","remaining","max","capReason","overageGuard","overageUsd","overageMonthlyUsd","paidUsd","data","standing","exists","overageLimitUsd","limitUsd","overageUnpaidUsd","unpaidUsd","ref","refusal","tasteRefusal","set","merge","messages","updatedAt","publicAssistQuota","ceilingUsd","min","credits","releaseAssistMessage","dailySnapshot","days","today","requests","checkAssistQuota","writeSignalAndRollup","batch","signalRef","record","kind","estCostUsd","providerCostUsd","deflected","refusedFree","stopReason","hostId","trim","hostCredits","route","tier","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","docsPaths","feedback","editOps","createdAt","refusedTurns","refusedCostUsd","writes","refused","platform","account","announceFreeTurn","recordAssistCost","uid","commit","id","recordAssistExchange","exchangeRef","question","answer","expiresAt","recordAssistFeedback","exchangeId","update"],"mappings":"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"}

package/src/lib/usage/staff-org-ai.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @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 { AiJobStatus } from '../model/ai-jobs.types';
+import type { AglynOrgBilling } from '@aglyn/aglyn/foundation';
+import { type DiscountMarginRating } from '@aglyn/aglyn/app-utils/plan-entitlements';
+import type { AssistRefusalCounts } from './assist-refusals';
+import { type AiKindMonth, type AiTokenTotals } from '../model/ai-tokens';
+/**
+ * THE STAFF AI CARD'S FIGURES (AGL-2930), composed from the same helpers the
+ * meter, the invoice and the customer's own billing page read.
+ *
+ * Nothing here runs a query and nothing here holds a rate of its own. The
+ * pool is `resolveAssistCreditBudget`, the overage is `assistMonthOverage`,
+ * the ceiling is `assistOverageCapReached` — the ONE derivation each of those
+ * already is — so the card cannot show a staff member a different band,
+ * rate or ceiling from the one the gate refused a customer at.
+ */
+/** The four ways the reservation refuses, plus their sum. */
+export type StaffOrgAiRefusals = AssistRefusalCounts;
+export interface StaffOrgAiAddon {
+    /** Bought and on a subscription still paying for it — `hasAiAddon`. */
+    on: boolean;
+    /** The add-on's list price on this plan, or null where the plan sells none. */
+    priceUsd: number | null;
+    /** ISO instant the subscription item was created, when Stripe could say. */
+    since: string | null;
+    /**
+     * Where `since` came from, so an absent date is legible: `stripe` answered,
+     * the org has no Stripe subscription to ask, or Stripe could not be asked
+     * (no key on this deployment, or the lookup failed).
+     */
+    sinceSource: 'stripe' | 'no-subscription' | 'unavailable';
+}
+export interface StaffOrgAiPool {
+    /** The plan's own band, from the catalogue row. */
+    planCredits: number;
+    /** A staff override of the band, or null when none is written. */
+    overrideCredits: number | null;
+    /** The add-on's band, 0 without the add-on. */
+    addonCredits: number;
+    /** The whole pool as the meter resolves it, or null where no band applies. */
+    totalCredits: number | null;
+    /**
+     * Whether an uncapped staff comp is why no band applies (AGL-3049) — a
+     * boolean, so "no band because uncapped" crosses JSON as itself rather
+     * than as the `null` an `Infinity` would become. Absent from a route older
+     * than the flag.
+     */
+    uncapped?: boolean;
+    /** Credits drawn this month, rounded up from the measured spend. */
+    usedCredits: number;
+    /**
+     * What the month DREW, at the catalog's billed rates — the dollars
+     * `usedCredits` is rounded up from, and the figure the overage line is
+     * priced off. Not a cost (AGL-3015).
+     */
+    billedUsd: number;
+    /**
+     * What the month COST US, at the provider's own rates: the one figure a
+     * margin or a spend alert may be taken against.
+     */
+    providerUsd: number;
+    /** Left in the pool, clamped at zero, or null where no band applies. */
+    remainingCredits: number | null;
+    /** Where `usedCredits` lands at month end at the pace so far. */
+    projectedCredits: number;
+    /** `projectedCredits` back in dollars — billed, as the credits were. */
+    projectedUsd: number;
+    /** Model turns and docs-deflected turns, off the month document. */
+    messages: number;
+    deflected: number;
+}
+export interface StaffOrgAiOverage {
+    overageCredits: number;
+    rateUsdPer1k: number | null;
+    accruedUsd: number;
+    /** Whether credits past the band are sold at all on this org. */
+    sellsOverage: boolean;
+    /** The org's own band switch — `assistOverage.hardCap`. */
+    hardCap: boolean;
+    /** The org's own dollar ceiling on overage — `assistOverage.capUsd`. */
+    capUsd: number | null;
+    capReached: boolean;
+    /** Whether the band is a wall for any reason (the switch, or no rate). */
+    bandRefuses: boolean;
+}
+export interface StaffOrgAiMargin {
+    /** The add-on's list price when it is on, else 0. */
+    addonRevenueUsd: number;
+    /**
+     * The dollar value of the plan's own band — what the plan price sets aside
+     * for assist. Each plan band is sized against the billed rate (a thousand
+     * credits are a dollar), so this is the share of the subscription that was
+     * sold as AI, and it belongs on the REVENUE side beside the add-on's price.
+     */
+    planAssistShareUsd: number;
+    /** Overage priced at the plan's rate, which the invoice will bill. */
+    overageRevenueUsd: number;
+    /** The three above, summed. */
+    revenueUsd: number;
+    /** What the month cost us: measured provider spend, never what it drew. */
+    spendUsd: number;
+    /**
+     * Spend past what the add-on and the plan's assist share bring in — the
+     * condition the card renders red. Overage revenue is left OUT of the
+     * comparison on purpose: it is billed at a margin, so an org deep in
+     * overage is not the one losing money.
+     */
+    underwater: boolean;
+    /** The staff review threshold and the multiple of it the spend has reached. */
+    thresholdUsd: number;
+    multiple: number;
+    /** The whole-org contribution margin, when a usage rollup exists. */
+    contribution: {
+        month: string | null;
+        marginPct: number | null;
+        rating: DiscountMarginRating | null;
+    };
+}
+/** The job model's own status set: the card renders every one by name. */
+export type StaffOrgAiJobStatus = AiJobStatus;
+export interface StaffOrgAiJob {
+    id: string;
+    kind: string;
+    status: StaffOrgAiJobStatus | string;
+    creditsReserved: number;
+    creditsSpent: number;
+    createdAt: string | null;
+    createdBy: string | null;
+}
+export interface StaffOrgAiJobs {
+    counts: Record<StaffOrgAiJobStatus, number>;
+    recent: StaffOrgAiJob[];
+    /** True when the scan stopped at its ceiling — the counts are a floor. */
+    truncated: boolean;
+}
+/** One row of the per-user rollup (AGL-2928), as the staff card lists it. */
+export interface StaffOrgAiUser {
+    uid: string;
+    /** The roster's name for them — display name, else email, else the uid. */
+    name: string;
+    credits: number;
+    /** The measured provider spend behind `credits`; staff may see dollars. */
+    estCostUsd: number;
+    /** Of the org's measured spend for the month, in `[0, 1]`. */
+    share: number;
+    requests: number;
+    refusals: number;
+    byKind: Record<string, number>;
+    byHost: Record<string, number>;
+}
+/** One kind of model request this month, as the card lists it (AGL-2937). */
+export interface StaffOrgAiKindTokens extends AiKindMonth {
+    /**
+     * What one request of this kind COST US on average; `null` with none. The
+     * provider figure, not what the kind drew — the reader is sizing a step
+     * against a bill, and a marked-up model would otherwise make the step look
+     * dearer to run than it is (AGL-3015).
+     */
+    costPerRequestUsd: number | null;
+    /** The share of this kind's prompt tokens the cache served — `aiCacheHitRate`. */
+    cacheHitRate: number | null;
+}
+/** The month's tokens (AGL-2937): its totals, its cache hit rate, and each kind. */
+export interface StaffOrgAiTokens {
+    /** The month document's own four totals. */
+    total: AiTokenTotals;
+    cacheHitRate: number | null;
+    /** Dearest first; empty for a month written before kinds were kept. */
+    kinds: StaffOrgAiKindTokens[];
+}
+export interface StaffOrgAiResponse {
+    month: string;
+    addon: StaffOrgAiAddon;
+    pool: StaffOrgAiPool;
+    overage: StaffOrgAiOverage;
+    refusals: StaffOrgAiRefusals;
+    /** Null when the jobs read failed — distinct from an org with no jobs. */
+    jobs: StaffOrgAiJobs | null;
+    /** The dearest people this month; empty when nobody's month is written. */
+    users: StaffOrgAiUser[];
+    margin: StaffOrgAiMargin;
+    /** Tokens by kind (AGL-2937); absent from a route older than the card. */
+    tokens?: StaffOrgAiTokens;
+}
+/** The UTC day-of-month and month length `projectMonthEnd` scales by. */
+export declare function monthProgress(now: Date): {
+    elapsed: number;
+    length: number;
+};
+/**
+ * Where a month-to-date figure lands at month end at the pace so far.
+ *
+ * Linear, on whole UTC days, and deliberately no cleverer: the reader is
+ * asking "will this org clear its band" and a straight line answers that
+ * within the margin the question needs. Day one projects the first day's
+ * spend across the month, which over-reads a burst — the direction a
+ * monitoring figure should err in.
+ */
+export declare function projectMonthEnd(usedSoFar: number, now: Date): number;
+export declare function composeStaffOrgAiPool(org: Partial<AglynOrgBilling> | null | undefined, monthDoc: Record<string, unknown> | null | undefined, now: Date): StaffOrgAiPool;
+/**
+ * The month's tokens as the card reads them: the totals the month document
+ * has always kept, and its `kinds` map (`model/ai-tokens.ts`) with the cost
+ * per request and the cache hit rate worked out per kind.
+ */
+export declare function composeStaffOrgAiTokens(monthDoc: Record<string, unknown> | null | undefined): StaffOrgAiTokens;
+/**
+ * Takes the BILLED figure, never the provider one (AGL-3015): every line
+ * here is what the customer owes — credits past the band, the rate they sell
+ * at, the dollars accrued, whether the org's own cap is reached — and an
+ * invoice priced off our cost would bill a different month than the meter
+ * the customer reads.
+ */
+export declare function composeStaffOrgAiOverage(org: Partial<AglynOrgBilling> | null | undefined, billedUsd: number): StaffOrgAiOverage;
+export declare function composeStaffOrgAiAddon(org: Partial<AglynOrgBilling> | null | undefined, since: Pick<StaffOrgAiAddon, 'since' | 'sinceSource'>): StaffOrgAiAddon;
+export declare function composeStaffOrgAiMargin(input: {
+    org: Partial<AglynOrgBilling> | null | undefined;
+    pool: StaffOrgAiPool;
+    overage: StaffOrgAiOverage;
+    addon: StaffOrgAiAddon;
+    thresholdUsd: number;
+    multiple: number;
+    contribution: StaffOrgAiMargin['contribution'];
+}): StaffOrgAiMargin;
+export declare const STAFF_ORG_AI_JOB_STATUSES: readonly StaffOrgAiJobStatus[];
+/** Zero-filled counts, so the card renders every status by name. */
+export declare function emptyJobCounts(): Record<StaffOrgAiJobStatus, number>;

package/src/lib/usage/staff-org-ai.js

@@ -0,0 +1,173 @@
+/**
+ * @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.
+ */ // Imported from BOTH graphs — the staff card (client) and the App Route that
+// serves it — so it may import neither entry barrel, for the reason
+// `margin-utilization.ts` states at its own head.
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { ASSIST_PROVIDER_COST_FIELD, assistBandRefuses, assistCreditsFromUsd, assistProviderCostUsd, assistMonthOverage, assistOverageCapReached, assistUsdFromCredits, resolveAssistCreditBudget, resolveAssistHardCap, resolveAssistOverageCapUsd } from "@aglyn/aglyn/app-utils/assist-credits";
+import { AI_ADDON_CREDITS_PER_MONTH, hasAiAddon, isUncappedPlanComp, PLAN_ENTITLEMENTS, resolveEffectivePlan, resolvePlanPricing } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { AI_USAGE_MONTH_KINDS_FIELD, aiCacheHitRate, readAiKindMonths } from "../model/ai-tokens.js";
+const finite = (value)=>{
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+/** The UTC day-of-month and month length `projectMonthEnd` scales by. */ export function monthProgress(now) {
+    const year = now.getUTCFullYear();
+    const month = now.getUTCMonth();
+    return {
+        elapsed: now.getUTCDate(),
+        length: new Date(Date.UTC(year, month + 1, 0)).getUTCDate()
+    };
+}
+/**
+ * Where a month-to-date figure lands at month end at the pace so far.
+ *
+ * Linear, on whole UTC days, and deliberately no cleverer: the reader is
+ * asking "will this org clear its band" and a straight line answers that
+ * within the margin the question needs. Day one projects the first day's
+ * spend across the month, which over-reads a burst — the direction a
+ * monitoring figure should err in.
+ */ export function projectMonthEnd(usedSoFar, now) {
+    const { elapsed, length } = monthProgress(now);
+    if (!(usedSoFar > 0) || elapsed <= 0) return 0;
+    return Math.ceil(usedSoFar / elapsed * length);
+}
+/** The staff override of the assist band, or null when none is written. */ function assistBandOverride(org) {
+    var _org_entitlements;
+    const raw = org == null ? void 0 : (_org_entitlements = org.entitlements) == null ? void 0 : _org_entitlements['assistCreditsPerMonth'];
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) return null;
+    return Math.floor(raw);
+}
+export function composeStaffOrgAiPool(org, monthDoc, now) {
+    var _PLAN_ENTITLEMENTS_plan;
+    const plan = resolveEffectivePlan(org);
+    const addon = hasAiAddon(org);
+    // Two questions, two figures (AGL-3015). What the workspace DREW is the
+    // billed figure, because that is what its credits came out of and what its
+    // band is measured in. What the month COST US is the provider figure, and
+    // it is the only one a margin below may be taken against.
+    const billedUsd = finite(monthDoc == null ? void 0 : monthDoc['estCostUsd']);
+    const providerUsd = assistProviderCostUsd(billedUsd, monthDoc == null ? void 0 : monthDoc[ASSIST_PROVIDER_COST_FIELD]);
+    const usedCredits = assistCreditsFromUsd(billedUsd);
+    const totalCredits = resolveAssistCreditBudget(org);
+    const projectedCredits = projectMonthEnd(usedCredits, now);
+    return {
+        planCredits: finite((_PLAN_ENTITLEMENTS_plan = PLAN_ENTITLEMENTS[plan]) == null ? void 0 : _PLAN_ENTITLEMENTS_plan.assistCreditsPerMonth),
+        overrideCredits: assistBandOverride(org),
+        addonCredits: addon ? AI_ADDON_CREDITS_PER_MONTH[plan] : 0,
+        totalCredits,
+        uncapped: isUncappedPlanComp(org),
+        usedCredits,
+        billedUsd,
+        providerUsd,
+        remainingCredits: totalCredits === null ? null : Math.max(0, totalCredits - usedCredits),
+        projectedCredits,
+        projectedUsd: assistUsdFromCredits(projectedCredits),
+        messages: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['messages'])),
+        deflected: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['deflected']))
+    };
+}
+/**
+ * The month's tokens as the card reads them: the totals the month document
+ * has always kept, and its `kinds` map (`model/ai-tokens.ts`) with the cost
+ * per request and the cache hit rate worked out per kind.
+ */ export function composeStaffOrgAiTokens(monthDoc) {
+    const total = {
+        input: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['inputTokens'])),
+        cached: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['cacheReadTokens'])),
+        cacheWrite: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['cacheWriteTokens'])),
+        output: Math.floor(finite(monthDoc == null ? void 0 : monthDoc['outputTokens']))
+    };
+    return {
+        total,
+        cacheHitRate: aiCacheHitRate(total),
+        kinds: readAiKindMonths(monthDoc == null ? void 0 : monthDoc[AI_USAGE_MONTH_KINDS_FIELD]).map((row)=>_extends({}, row, {
+                costPerRequestUsd: row.requests > 0 ? Math.round(row.providerCostUsd / row.requests * 1000000) / 1000000 : null,
+                cacheHitRate: aiCacheHitRate(row.tokens)
+            }))
+    };
+}
+/**
+ * Takes the BILLED figure, never the provider one (AGL-3015): every line
+ * here is what the customer owes — credits past the band, the rate they sell
+ * at, the dollars accrued, whether the org's own cap is reached — and an
+ * invoice priced off our cost would bill a different month than the meter
+ * the customer reads.
+ */ export function composeStaffOrgAiOverage(org, billedUsd) {
+    const overage = assistMonthOverage(org, billedUsd);
+    return {
+        overageCredits: overage.overageCredits,
+        rateUsdPer1k: overage.overageRateUsd,
+        accruedUsd: overage.overageMonthlyUsd,
+        sellsOverage: overage.bandCredits !== null && overage.overageRateUsd !== null,
+        hardCap: resolveAssistHardCap(org),
+        capUsd: resolveAssistOverageCapUsd(org),
+        capReached: assistOverageCapReached(org, billedUsd),
+        bandRefuses: assistBandRefuses(org)
+    };
+}
+export function composeStaffOrgAiAddon(org, since) {
+    var _resolvePlanPricing_aiAddonMonthlyUsd;
+    return _extends({
+        on: hasAiAddon(org),
+        // What this workspace would be charged — none for a staff comp, which
+        // has no subscription to carry the item (AGL-3034).
+        priceUsd: (_resolvePlanPricing_aiAddonMonthlyUsd = resolvePlanPricing(org).aiAddonMonthlyUsd) != null ? _resolvePlanPricing_aiAddonMonthlyUsd : null
+    }, since);
+}
+export function composeStaffOrgAiMargin(input) {
+    var _pool_overrideCredits;
+    const { pool, overage, addon } = input;
+    const addonRevenueUsd = addon.on ? finite(addon.priceUsd) : 0;
+    // The band the PLAN sells — the override, when one is written, is what the
+    // customer was actually given, so it is the figure the price is carrying.
+    const planAssistShareUsd = assistUsdFromCredits((_pool_overrideCredits = pool.overrideCredits) != null ? _pool_overrideCredits : pool.planCredits);
+    const overageRevenueUsd = overage.accruedUsd;
+    // THE ONE PLACE THE TWO RATES MEET (AGL-3015). Revenue is what the
+    // customer pays — an add-on price, a band sized in credits, overage at the
+    // retail rate — and spend is what the provider charges us. Taking both
+    // sides off one figure was what made a fully-drawn band read as exactly
+    // break-even no matter what the tokens actually cost.
+    const revenueUsd = Math.round((addonRevenueUsd + planAssistShareUsd + overageRevenueUsd) * 100) / 100;
+    return {
+        addonRevenueUsd,
+        planAssistShareUsd,
+        overageRevenueUsd,
+        revenueUsd,
+        spendUsd: pool.providerUsd,
+        underwater: pool.providerUsd > addonRevenueUsd + planAssistShareUsd,
+        thresholdUsd: input.thresholdUsd,
+        multiple: input.multiple,
+        contribution: input.contribution
+    };
+}
+export const STAFF_ORG_AI_JOB_STATUSES = [
+    'queued',
+    'running',
+    'needs_input',
+    'needs_review',
+    'done',
+    'failed',
+    'canceled'
+];
+/** Zero-filled counts, so the card renders every status by name. */ export function emptyJobCounts() {
+    return Object.fromEntries(STAFF_ORG_AI_JOB_STATUSES.map((status)=>[
+            status,
+            0
+        ]));
+}
+
+//# sourceMappingURL=staff-org-ai.js.map