@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/billing/ai-overage-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-ledger.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 * THE OVERAGE CHARGE LEDGER (AGL-3011).\n *\n * Every dollar of AI overage a workspace is charged mid-period passes\n * through here twice: once as a CLAIM, taken in a transaction before any\n * money is asked for, and once as a SETTLEMENT, recorded after Stripe\n * answers. Nothing in this module talks to Stripe.\n *\n * ## Why claim first\n *\n * The figure that decides a charge — the month's overage — is a counter many\n * requests move. Two requests crossing the threshold a millisecond apart\n * both read \"$25 unbilled\" and would both charge for it. The claim closes\n * that: inside one transaction it moves `overageInvoicedUsd` forward by the\n * amount it is about to charge and records an open charge, so the second\n * request reads an already-claimed balance and stands down. The invoice is\n * created afterwards, outside the transaction, because a Stripe call inside\n * a Firestore transaction would be retried by the transaction.\n *\n * ## What a lost process costs\n *\n * A claim that never became an invoice leaves `overageInvoicedUsd` ahead of\n * what was billed, which UNDER-charges rather than over-charges, and leaves\n * an open charge that blocks the next one. Both are repaired by the\n * reconcile sweep, which asks Stripe whether the claim ever became an\n * invoice and either records it or releases the claim. Under-charging while\n * confused is the direction this must err in.\n *\n * ## The documents\n *\n * `orgs/{orgId}/assistUsage/{YYYY-MM}` — the month's rollup, which the\n * reservation already reads, gains four fields so the gate costs no extra\n * read: `overageInvoicedUsd`, `overagePaidUsd`, `overageCharges` and\n * `overageInvoiceOpen`.\n *\n * `orgs/{orgId}/aiOverageCharges/{chargeId}` — one row per charge, the\n * audit trail staff read and the reconcile sweep walks.\n *\n * Both are server-written: the rules allow the same readers as\n * `aiAllotments` and no writer at all.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { assistMonthOverage } from '@aglyn/aglyn/app-utils/assist-credits'\nimport {\n  AI_OVERAGE_MIN_CHARGE_USD,\n  AI_OVERAGE_THRESHOLD_USD,\n  aiOverageCardOnFile,\n  readAiOverageStanding,\n  type AiOverageOrg,\n} from './ai-overage-standing'\n\n/** The subcollection and document the standing lives at. */\nexport const AI_BILLING_SUBCOLLECTION = 'aiBilling'\nexport const AI_BILLING_STANDING_DOC = 'standing'\n/** The subcollection one row per charge lives in. */\nexport const AI_OVERAGE_CHARGES_SUBCOLLECTION = 'aiOverageCharges'\n\n/** Which sweep asked for the charge. */\nexport type AiOverageChargeKind = 'threshold' | 'closeout'\n\n/** Where a charge is in its life. */\nexport type AiOverageChargeStatus =\n  | 'claimed'\n  | 'open'\n  | 'paid'\n  | 'failed'\n  | 'void'\n\n/** A claim taken, ready to be charged. */\nexport interface AiOverageClaim {\n  chargeId: string\n  orgId: string\n  month: string\n  seq: number\n  kind: AiOverageChargeKind\n  /** Floored to the cent — Stripe bills whole cents. */\n  amountUsd: number\n  /** The credits and rate the amount came from, for the audit row. */\n  credits: number\n  rateUsdPer1k: number | null\n}\n\n/** Why no claim was taken. Each one is a different thing to do about it. */\nexport type AiOverageClaimRefusal =\n  | 'below-threshold'\n  | 'charge-already-open'\n  | 'no-card'\n  | 'paused'\n  | 'not-sold'\n\nexport type AiOverageClaimResult =\n  | { claimed: AiOverageClaim; refused: null }\n  | { claimed: null; refused: AiOverageClaimRefusal }\n\nfunction money(value: unknown): number {\n  const number = Number(value)\n  return Number.isFinite(number) && number > 0 ? number : 0\n}\n\n/** Down to the cent. Never up: a rounded-up cent is a cent never accrued. */\nexport function floorToCent(usd: number): number {\n  return Math.floor(money(usd) * 100) / 100\n}\n\n/**\n * `{month}-{seq}` — readable, sortable, and unique per workspace-month.\n *\n * The id is also the Stripe idempotency key's payload and the metadata the\n * reconcile search matches on, so it must survive a URL and a Stripe search\n * query unescaped: digits, a hyphen, nothing else.\n */\nexport function aiOverageChargeId(month: string, seq: number): string {\n  return `${month}-${String(Math.max(1, Math.floor(seq))).padStart(3, '0')}`\n}\n\n/**\n * Takes a claim on the workspace's unbilled overage, or explains why not.\n *\n * The four conditions are the design's, in one transaction with the reads\n * they are decided from:\n *\n * - enough unbilled overage (the threshold, or the minimum for a close-out);\n * - no charge already open — one at a time, so a failure has one owner;\n * - a card on file, since the bound assumes a payment method that settles\n *   now rather than in days;\n * - not paused.\n *\n * The card condition abstains when the workspace's payment method has never\n * been observed, for the reason `AiOverageStanding.paymentMethodType` gives.\n * A charge attempted against a customer with no default simply fails, and\n * the failure pauses accrual like any other — the guard is an optimization\n * here, not the safety property.\n */\nexport async function claimAiOverageCharge(\n  firestore: FirebaseFirestore.Firestore,\n  request: {\n    orgId: string\n    org: AiOverageOrg\n    month: string\n    kind: AiOverageChargeKind\n    now?: Date\n  },\n): Promise<AiOverageClaimResult> {\n  const now = request.now ?? new Date()\n  const orgRef = firestore.collection('orgs').doc(request.orgId)\n  const usageRef = orgRef.collection('assistUsage').doc(request.month)\n  const standingRef = orgRef\n    .collection(AI_BILLING_SUBCOLLECTION)\n    .doc(AI_BILLING_STANDING_DOC)\n  // A close-out settles a month that is over: there is nothing left to\n  // accrue, so anything Stripe will accept is worth billing. A threshold\n  // charge waits for the threshold, which is what keeps the invoice count\n  // and its fees down.\n  const floorUsd =\n    request.kind === 'closeout' ? AI_OVERAGE_MIN_CHARGE_USD : AI_OVERAGE_THRESHOLD_USD\n\n  return firestore.runTransaction(async (tx) => {\n    const [usageSnapshot, standingSnapshot] = await Promise.all([\n      tx.get(usageRef),\n      tx.get(standingRef),\n    ])\n    const standing = readAiOverageStanding(\n      standingSnapshot.exists ? (standingSnapshot.data() ?? null) : null,\n    )\n    if (aiOverageCardOnFile(standing) === false) {\n      return { claimed: null, refused: 'no-card' as const }\n    }\n    if (standing.pause) return { claimed: null, refused: 'paused' as const }\n    if (usageSnapshot.get('overageInvoiceOpen')) {\n      return { claimed: null, refused: 'charge-already-open' as const }\n    }\n    const priced = assistMonthOverage(\n      request.org,\n      money(usageSnapshot.get('estCostUsd')),\n    )\n    // A plan that sells nothing past its band prices its overage to zero, so\n    // this is structural rather than a check that could be forgotten — but\n    // it is named, because \"we billed nothing\" and \"there is nothing to\n    // bill\" are different answers to a staff question.\n    if (priced.overageRateUsd === null) {\n      return { claimed: null, refused: 'not-sold' as const }\n    }\n    const invoicedUsd = money(usageSnapshot.get('overageInvoicedUsd'))\n    const unbilledUsd = floorToCent(priced.overageMonthlyUsd - invoicedUsd)\n    if (!(unbilledUsd >= floorUsd)) {\n      return { claimed: null, refused: 'below-threshold' as const }\n    }\n    const seq = Math.max(0, Math.floor(money(usageSnapshot.get('overageCharges')))) + 1\n    const chargeId = aiOverageChargeId(request.month, seq)\n    const claim: AiOverageClaim = {\n      chargeId,\n      orgId: request.orgId,\n      month: request.month,\n      seq,\n      kind: request.kind,\n      amountUsd: unbilledUsd,\n      credits: priced.overageCredits,\n      rateUsdPer1k: priced.overageRateUsd,\n    }\n    tx.set(\n      usageRef,\n      {\n        month: request.month,\n        overageInvoicedUsd: FieldValue.increment(unbilledUsd),\n        overageCharges: FieldValue.increment(1),\n        overageInvoiceOpen: {\n          chargeId,\n          invoiceId: null,\n          amountUsd: unbilledUsd,\n          since: now.toISOString(),\n        },\n        updatedAt: FieldValue.serverTimestamp(),\n      },\n      { merge: true },\n    )\n    tx.set(\n      orgRef.collection(AI_OVERAGE_CHARGES_SUBCOLLECTION).doc(chargeId),\n      {\n        month: request.month,\n        seq,\n        kind: request.kind,\n        amountUsd: unbilledUsd,\n        credits: priced.overageCredits,\n        rateUsdPer1k: priced.overageRateUsd,\n        invoiceId: null,\n        status: 'claimed' satisfies AiOverageChargeStatus,\n        createdAt: FieldValue.serverTimestamp(),\n        paidAt: null,\n        failedAt: null,\n      },\n      { merge: true },\n    )\n    return { claimed: claim, refused: null }\n  })\n}\n\n/** What Stripe said, as the ledger records it. */\nexport interface AiOverageSettlement {\n  chargeId: string\n  month: string\n  /** `null` only when no invoice was ever created. */\n  invoiceId: string | null\n  status: AiOverageChargeStatus\n  /**\n   * What Stripe actually collected, in dollars (AGL-3023).\n   *\n   * The month's paid total moves by THIS and never by the claim. The two are\n   * normally equal, and the case where they are not is the one that matters:\n   * an invoice that finalized at zero or collected less than it billed would\n   * otherwise clear a balance nobody paid, and the gate's unpaid bound would\n   * be satisfied by our own bookkeeping instead of by money.\n   *\n   * Omitted on a settlement that is not a payment, where it is not read.\n   */\n  paidUsd?: number\n}\n\n/**\n * Records what became of a claimed charge.\n *\n * `paid` adds the amount to the month's `overagePaidUsd`, which is what the\n * gate's unpaid bound subtracts — so paying is what lets a workspace keep\n * going, and nothing else does.\n *\n * An invoice that exists but is not paid KEEPS its claim on\n * `overageInvoicedUsd`: it is a real bill, Stripe's retries may still settle\n * it, and re-billing the same dollars on a second invoice would charge the\n * customer twice for one month's usage. Only a claim that never became an\n * invoice at all releases what it claimed, so those dollars can be charged\n * by a later attempt.\n *\n * The open-charge slot is always cleared. Leaving it set on a failure would\n * block the close-out and every later charge behind an invoice that is\n * never going to move on its own.\n */\nexport async function settleAiOverageCharge(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  settlement: AiOverageSettlement,\n): Promise<void> {\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const usageRef = orgRef.collection('assistUsage').doc(settlement.month)\n  const chargeRef = orgRef\n    .collection(AI_OVERAGE_CHARGES_SUBCOLLECTION)\n    .doc(settlement.chargeId)\n\n  await firestore.runTransaction(async (tx) => {\n    const [usageSnapshot, chargeSnapshot] = await Promise.all([\n      tx.get(usageRef),\n      tx.get(chargeRef),\n    ])\n    const amountUsd = money(chargeSnapshot.get('amountUsd'))\n    // What the month's paid total moves by: what Stripe took. A settlement\n    // that claims to be a payment and names no collected figure moves\n    // nothing — silence is not evidence of money (AGL-3023).\n    const paidUsd = money(settlement.paidUsd)\n    const open = usageSnapshot.get('overageInvoiceOpen') as\n      | { chargeId?: unknown }\n      | null\n      | undefined\n    const ownsTheSlot = String(open?.chargeId ?? '') === settlement.chargeId\n    // Already settled, or settled by another path (the webhook and the\n    // synchronous answer both arrive). Recording the status again is\n    // harmless; moving the money counters again is not.\n    const alreadyPaid = chargeSnapshot.get('status') === 'paid'\n    const releases = settlement.status === 'failed' && !settlement.invoiceId\n    tx.set(\n      chargeRef,\n      {\n        invoiceId: settlement.invoiceId,\n        status: settlement.status,\n        ...(settlement.status === 'paid' ? { paidUsd } : {}),\n        ...(settlement.status === 'paid'\n          ? { paidAt: FieldValue.serverTimestamp() }\n          : {}),\n        ...(settlement.status === 'failed'\n          ? { failedAt: FieldValue.serverTimestamp() }\n          : {}),\n      },\n      { merge: true },\n    )\n    tx.set(\n      usageRef,\n      {\n        month: settlement.month,\n        ...(settlement.status === 'paid' && !alreadyPaid && paidUsd > 0\n          ? { overagePaidUsd: FieldValue.increment(paidUsd) }\n          : {}),\n        ...(releases\n          ? {\n              overageInvoicedUsd: FieldValue.increment(-amountUsd),\n              overageCharges: FieldValue.increment(-1),\n            }\n          : {}),\n        ...(ownsTheSlot ? { overageInvoiceOpen: null } : {}),\n        updatedAt: FieldValue.serverTimestamp(),\n      },\n      { merge: true },\n    )\n  })\n}\n\n/** The month's charge counters, as the customer card and staff card read them. */\nexport interface AiOverageMonthLedger {\n  invoicedUsd: number\n  paidUsd: number\n  charges: number\n  open: { chargeId: string; invoiceId: string | null; amountUsd: number } | null\n}\n\n/** Reads the four fields off a month's rollup, defensively. */\nexport function readAiOverageMonthLedger(\n  data: Record<string, unknown> | null | undefined,\n): AiOverageMonthLedger {\n  const open = data?.['overageInvoiceOpen'] as Record<string, unknown> | null | undefined\n  const chargeId = typeof open?.['chargeId'] === 'string' ? open['chargeId'] : ''\n  return {\n    invoicedUsd: money(data?.['overageInvoicedUsd']),\n    paidUsd: money(data?.['overagePaidUsd']),\n    charges: Math.max(0, Math.floor(money(data?.['overageCharges']))),\n    open: chargeId\n      ? {\n          chargeId,\n          invoiceId:\n            typeof open?.['invoiceId'] === 'string' ? (open['invoiceId'] as string) : null,\n          amountUsd: money(open?.['amountUsd']),\n        }\n      : null,\n  }\n}\n"],"names":["FieldValue","assistMonthOverage","AI_OVERAGE_MIN_CHARGE_USD","AI_OVERAGE_THRESHOLD_USD","aiOverageCardOnFile","readAiOverageStanding","AI_BILLING_SUBCOLLECTION","AI_BILLING_STANDING_DOC","AI_OVERAGE_CHARGES_SUBCOLLECTION","money","value","number","Number","isFinite","floorToCent","usd","Math","floor","aiOverageChargeId","month","seq","String","max","padStart","claimAiOverageCharge","firestore","request","now","Date","orgRef","collection","doc","orgId","usageRef","standingRef","floorUsd","kind","runTransaction","tx","standingSnapshot","usageSnapshot","Promise","all","get","standing","exists","data","claimed","refused","pause","priced","org","overageRateUsd","invoicedUsd","unbilledUsd","overageMonthlyUsd","chargeId","claim","amountUsd","credits","overageCredits","rateUsdPer1k","set","overageInvoicedUsd","increment","overageCharges","overageInvoiceOpen","invoiceId","since","toISOString","updatedAt","serverTimestamp","merge","status","createdAt","paidAt","failedAt","settleAiOverageCharge","settlement","chargeRef","chargeSnapshot","paidUsd","open","ownsTheSlot","alreadyPaid","releases","overagePaidUsd","readAiOverageMonthLedger","charges"],"mappings":"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"}

package/src/lib/billing/ai-overage-standing-writes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @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 AiOveragePauseReason } from './ai-overage-standing';
+/**
+ * Stops accrual.
+ *
+ * An existing pause is NOT overwritten: the first reason is the one that
+ * started it and the one the customer was told, and a `past_due` arriving
+ * behind a `charge_failed` would replace a sentence naming an invoice the
+ * customer can pay with one that names nothing. The exception is a dispute,
+ * which outranks everything because only staff may lift it.
+ */
+export declare function pauseAiOverage(firestore: FirebaseFirestore.Firestore, orgId: string, pause: {
+    reason: AiOveragePauseReason;
+    invoiceId?: string | null;
+    now: Date;
+}): Promise<void>;
+/**
+ * Lifts a pause — but only the pause the caller is entitled to lift.
+ *
+ * Scoped two ways, and the scoping is the point. `invoiceId` lifts only a
+ * pause that names that invoice, so paying an AI charge clears the pause it
+ * caused and nothing else. `reason` lifts only a pause of that kind, so a
+ * paid renewal clears `past_due` and leaves a failed AI charge paused — the
+ * AI invoice is still open, and resuming accrual against it would let the
+ * balance grow while it is unpaid.
+ *
+ * Unscoped clears whatever is there, which is the staff path and the voided
+ * invoice's. A dispute pause is never lifted by a payment of any kind: it
+ * needs `force`, which only staff pass.
+ */
+export declare function resumeAiOverage(firestore: FirebaseFirestore.Firestore, orgId: string, scope?: {
+    invoiceId?: string | null;
+    reason?: AiOveragePauseReason;
+    force?: boolean;
+}): Promise<void>;
+/**
+ * Records a paid invoice, which is what moves a workspace up the ladder.
+ *
+ * Two different things happen on a first payment and on a later one. The
+ * first sets `firstPaidMonth` — the baseline the ladder counts FROM, never a
+ * step on it, because every paid workspace pays one invoice the moment it
+ * subscribes and a ladder that counted it would start everyone a step up.
+ * Every later month with a real payment adds a step.
+ *
+ * `aiOverageQualifyingMonth` decides which is which, and refuses a payment
+ * that is not evidence: an invoice marked paid out of band is a staff
+ * action, and a zero payment is a credit.
+ */
+export declare function recordAiOveragePaidInvoice(firestore: FirebaseFirestore.Firestore, orgId: string, payment: {
+    month: string;
+    amountPaidCents: number;
+    paidOutOfBand: boolean;
+}): Promise<void>;
+/**
+ * Takes a month back off the ladder.
+ *
+ * The close-out sweep calls this for a month that ended with an AI charge
+ * still unpaid. A month in which the workspace both paid an invoice and left
+ * an AI charge unpaid is not evidence of the thing the ladder measures, and
+ * leaving it counted would raise a ceiling on the strength of a payment that
+ * did not happen.
+ */
+export declare function dropAiOverageQualifyingMonth(firestore: FirebaseFirestore.Firestore, orgId: string, month: string): Promise<void>;
+/**
+ * A dispute: the ladder goes back to the bottom and accrual stops.
+ *
+ * Both, not either. The reset is about the future — a workspace that
+ * disputes has not earned a raised ceiling — and the pause is about now.
+ * Only staff can lift the pause, because a dispute is a judgement about the
+ * relationship and no automatic event should end it.
+ */
+export declare function recordAiOverageDispute(firestore: FirebaseFirestore.Firestore, orgId: string, now: Date): Promise<void>;
+/**
+ * Mirrors the workspace's default payment method type.
+ *
+ * `null` means the customer has no default, which is a real answer and is
+ * written. The value is never written as `undefined` — that state means
+ * "nobody has looked", and once anyone has, it is gone for good.
+ */
+export declare function recordAiOveragePaymentMethod(firestore: FirebaseFirestore.Firestore, orgId: string, defaultType: string | null): Promise<void>;
+/** Sets or clears the staff ceiling override. */
+export declare function setAiOverageStaffOverride(firestore: FirebaseFirestore.Firestore, orgId: string, override: {
+    ceilingUsd: number;
+    reason: string;
+    setBy: string;
+    expiresAt: string | null;
+} | null, now: Date): Promise<void>;
+/**
+ * Puts the workspace back at the bottom of the ladder by hand.
+ *
+ * Staff-only, and separate from the dispute reset: this one does not pause,
+ * because staff resetting a step are correcting a standing, not responding
+ * to a chargeback.
+ */
+export declare function resetAiOverageStep(firestore: FirebaseFirestore.Firestore, orgId: string): Promise<void>;

package/src/lib/billing/ai-overage-standing-writes.js

@@ -0,0 +1,205 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * WRITING A WORKSPACE'S OVERAGE STANDING (AGL-3011).
+ *
+ * Every writer of `orgs/{orgId}/aiBilling/standing` is here, and each one is
+ * a transaction over the document it changes — the ladder and the pause are
+ * read by the gate on every request past the band, so a read-modify-write
+ * that lost a concurrent event would lose a pause or a step.
+ *
+ * `ai-overage-standing.ts` holds the shape and the arithmetic; this holds the
+ * writes. Nothing here decides a policy: what qualifies a month and what a
+ * ceiling resolves to are answered there, once, for the gate and the staff
+ * card as well as for these.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { AI_BILLING_STANDING_DOC, AI_BILLING_SUBCOLLECTION } from "./ai-overage-ledger.js";
+import { AI_OVERAGE_QUALIFYING_MONTHS_KEPT, aiOverageQualifyingMonth, aiOverageStep, readAiOverageStanding } from "./ai-overage-standing.js";
+function standingRef(firestore, orgId) {
+    return firestore.collection('orgs').doc(orgId).collection(AI_BILLING_SUBCOLLECTION).doc(AI_BILLING_STANDING_DOC);
+}
+/**
+ * Reads the standing, hands it to `change`, and writes back what comes out.
+ *
+ * `change` returning `null` writes nothing — which is how "this event does
+ * not move the standing" is said without a write that only restamps
+ * `updatedAt` and wakes every listener on the document.
+ */ async function updateStanding(firestore, orgId, change) {
+    const ref = standingRef(firestore, orgId);
+    await firestore.runTransaction(async (tx)=>{
+        var _snapshot_data;
+        const snapshot = await tx.get(ref);
+        const standing = readAiOverageStanding(snapshot.exists ? (_snapshot_data = snapshot.data()) != null ? _snapshot_data : null : null);
+        const write = change(standing);
+        if (!write) return;
+        tx.set(ref, _extends({}, write, {
+            updatedAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+    });
+}
+/** The mirrored `step`, kept beside the months it is derived from. */ function withStep(months) {
+    const kept = months.slice(-AI_OVERAGE_QUALIFYING_MONTHS_KEPT);
+    return {
+        qualifyingMonths: kept,
+        step: aiOverageStep({
+            qualifyingMonths: kept
+        })
+    };
+}
+/**
+ * Stops accrual.
+ *
+ * An existing pause is NOT overwritten: the first reason is the one that
+ * started it and the one the customer was told, and a `past_due` arriving
+ * behind a `charge_failed` would replace a sentence naming an invoice the
+ * customer can pay with one that names nothing. The exception is a dispute,
+ * which outranks everything because only staff may lift it.
+ */ export async function pauseAiOverage(firestore, orgId, pause) {
+    await updateStanding(firestore, orgId, (standing)=>{
+        var _pause_invoiceId;
+        if (standing.pause && standing.pause.reason === 'dispute') return null;
+        if (standing.pause && pause.reason !== 'dispute') return null;
+        return {
+            pause: {
+                reason: pause.reason,
+                invoiceId: (_pause_invoiceId = pause.invoiceId) != null ? _pause_invoiceId : null,
+                since: pause.now.toISOString()
+            }
+        };
+    });
+}
+/**
+ * Lifts a pause — but only the pause the caller is entitled to lift.
+ *
+ * Scoped two ways, and the scoping is the point. `invoiceId` lifts only a
+ * pause that names that invoice, so paying an AI charge clears the pause it
+ * caused and nothing else. `reason` lifts only a pause of that kind, so a
+ * paid renewal clears `past_due` and leaves a failed AI charge paused — the
+ * AI invoice is still open, and resuming accrual against it would let the
+ * balance grow while it is unpaid.
+ *
+ * Unscoped clears whatever is there, which is the staff path and the voided
+ * invoice's. A dispute pause is never lifted by a payment of any kind: it
+ * needs `force`, which only staff pass.
+ */ export async function resumeAiOverage(firestore, orgId, scope = {}) {
+    await updateStanding(firestore, orgId, (standing)=>{
+        if (!standing.pause) return null;
+        if (standing.pause.reason === 'dispute' && !scope.force) return null;
+        if (scope.invoiceId && standing.pause.invoiceId !== scope.invoiceId) return null;
+        if (scope.reason && standing.pause.reason !== scope.reason) return null;
+        return {
+            pause: null
+        };
+    });
+}
+/**
+ * Records a paid invoice, which is what moves a workspace up the ladder.
+ *
+ * Two different things happen on a first payment and on a later one. The
+ * first sets `firstPaidMonth` — the baseline the ladder counts FROM, never a
+ * step on it, because every paid workspace pays one invoice the moment it
+ * subscribes and a ladder that counted it would start everyone a step up.
+ * Every later month with a real payment adds a step.
+ *
+ * `aiOverageQualifyingMonth` decides which is which, and refuses a payment
+ * that is not evidence: an invoice marked paid out of band is a staff
+ * action, and a zero payment is a credit.
+ */ export async function recordAiOveragePaidInvoice(firestore, orgId, payment) {
+    await updateStanding(firestore, orgId, (standing)=>{
+        if (payment.paidOutOfBand || !(payment.amountPaidCents > 0)) return null;
+        if (!standing.firstPaidMonth) return {
+            firstPaidMonth: payment.month
+        };
+        const month = aiOverageQualifyingMonth(standing, payment);
+        if (!month) return null;
+        if (standing.qualifyingMonths.includes(month)) return null;
+        return withStep([
+            ...standing.qualifyingMonths,
+            month
+        ].sort());
+    });
+}
+/**
+ * Takes a month back off the ladder.
+ *
+ * The close-out sweep calls this for a month that ended with an AI charge
+ * still unpaid. A month in which the workspace both paid an invoice and left
+ * an AI charge unpaid is not evidence of the thing the ladder measures, and
+ * leaving it counted would raise a ceiling on the strength of a payment that
+ * did not happen.
+ */ export async function dropAiOverageQualifyingMonth(firestore, orgId, month) {
+    await updateStanding(firestore, orgId, (standing)=>{
+        if (!standing.qualifyingMonths.includes(month)) return null;
+        return withStep(standing.qualifyingMonths.filter((kept)=>kept !== month));
+    });
+}
+/**
+ * A dispute: the ladder goes back to the bottom and accrual stops.
+ *
+ * Both, not either. The reset is about the future — a workspace that
+ * disputes has not earned a raised ceiling — and the pause is about now.
+ * Only staff can lift the pause, because a dispute is a judgement about the
+ * relationship and no automatic event should end it.
+ */ export async function recordAiOverageDispute(firestore, orgId, now) {
+    await updateStanding(firestore, orgId, ()=>_extends({}, withStep([]), {
+            firstPaidMonth: null,
+            lastDisputeAt: now.toISOString(),
+            pause: {
+                reason: 'dispute',
+                invoiceId: null,
+                since: now.toISOString()
+            }
+        }));
+}
+/**
+ * Mirrors the workspace's default payment method type.
+ *
+ * `null` means the customer has no default, which is a real answer and is
+ * written. The value is never written as `undefined` — that state means
+ * "nobody has looked", and once anyone has, it is gone for good.
+ */ export async function recordAiOveragePaymentMethod(firestore, orgId, defaultType) {
+    await updateStanding(firestore, orgId, (standing)=>{
+        if (standing.paymentMethodType === defaultType) return null;
+        return {
+            paymentMethodType: defaultType
+        };
+    });
+}
+/** Sets or clears the staff ceiling override. */ export async function setAiOverageStaffOverride(firestore, orgId, override, now) {
+    await updateStanding(firestore, orgId, ()=>({
+            staffOverride: override ? {
+                ceilingUsd: override.ceilingUsd,
+                reason: override.reason,
+                setBy: override.setBy,
+                setAt: now.toISOString(),
+                expiresAt: override.expiresAt
+            } : null
+        }));
+}
+/**
+ * Puts the workspace back at the bottom of the ladder by hand.
+ *
+ * Staff-only, and separate from the dispute reset: this one does not pause,
+ * because staff resetting a step are correcting a standing, not responding
+ * to a chargeback.
+ */ export async function resetAiOverageStep(firestore, orgId) {
+    await updateStanding(firestore, orgId, ()=>withStep([]));
+}
+
+//# sourceMappingURL=ai-overage-standing-writes.js.map

package/src/lib/billing/ai-overage-standing-writes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-standing-writes.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 * WRITING A WORKSPACE'S OVERAGE STANDING (AGL-3011).\n *\n * Every writer of `orgs/{orgId}/aiBilling/standing` is here, and each one is\n * a transaction over the document it changes — the ladder and the pause are\n * read by the gate on every request past the band, so a read-modify-write\n * that lost a concurrent event would lose a pause or a step.\n *\n * `ai-overage-standing.ts` holds the shape and the arithmetic; this holds the\n * writes. Nothing here decides a policy: what qualifies a month and what a\n * ceiling resolves to are answered there, once, for the gate and the staff\n * card as well as for these.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  AI_BILLING_STANDING_DOC,\n  AI_BILLING_SUBCOLLECTION,\n} from './ai-overage-ledger'\nimport {\n  AI_OVERAGE_QUALIFYING_MONTHS_KEPT,\n  aiOverageQualifyingMonth,\n  aiOverageStep,\n  readAiOverageStanding,\n  type AiOveragePauseReason,\n  type AiOverageStanding,\n} from './ai-overage-standing'\n\nfunction standingRef(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n): FirebaseFirestore.DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(AI_BILLING_SUBCOLLECTION)\n    .doc(AI_BILLING_STANDING_DOC)\n}\n\n/**\n * Reads the standing, hands it to `change`, and writes back what comes out.\n *\n * `change` returning `null` writes nothing — which is how \"this event does\n * not move the standing\" is said without a write that only restamps\n * `updatedAt` and wakes every listener on the document.\n */\nasync function updateStanding(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  change: (standing: AiOverageStanding) => Record<string, unknown> | null,\n): Promise<void> {\n  const ref = standingRef(firestore, orgId)\n  await firestore.runTransaction(async (tx) => {\n    const snapshot = await tx.get(ref)\n    const standing = readAiOverageStanding(\n      snapshot.exists ? (snapshot.data() ?? null) : null,\n    )\n    const write = change(standing)\n    if (!write) return\n    tx.set(ref, { ...write, updatedAt: FieldValue.serverTimestamp() }, { merge: true })\n  })\n}\n\n/** The mirrored `step`, kept beside the months it is derived from. */\nfunction withStep(\n  months: string[],\n): { qualifyingMonths: string[]; step: number } {\n  const kept = months.slice(-AI_OVERAGE_QUALIFYING_MONTHS_KEPT)\n  return {\n    qualifyingMonths: kept,\n    step: aiOverageStep({ qualifyingMonths: kept } as AiOverageStanding),\n  }\n}\n\n/**\n * Stops accrual.\n *\n * An existing pause is NOT overwritten: the first reason is the one that\n * started it and the one the customer was told, and a `past_due` arriving\n * behind a `charge_failed` would replace a sentence naming an invoice the\n * customer can pay with one that names nothing. The exception is a dispute,\n * which outranks everything because only staff may lift it.\n */\nexport async function pauseAiOverage(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  pause: { reason: AiOveragePauseReason; invoiceId?: string | null; now: Date },\n): Promise<void> {\n  await updateStanding(firestore, orgId, (standing) => {\n    if (standing.pause && standing.pause.reason === 'dispute') return null\n    if (standing.pause && pause.reason !== 'dispute') return null\n    return {\n      pause: {\n        reason: pause.reason,\n        invoiceId: pause.invoiceId ?? null,\n        since: pause.now.toISOString(),\n      },\n    }\n  })\n}\n\n/**\n * Lifts a pause — but only the pause the caller is entitled to lift.\n *\n * Scoped two ways, and the scoping is the point. `invoiceId` lifts only a\n * pause that names that invoice, so paying an AI charge clears the pause it\n * caused and nothing else. `reason` lifts only a pause of that kind, so a\n * paid renewal clears `past_due` and leaves a failed AI charge paused — the\n * AI invoice is still open, and resuming accrual against it would let the\n * balance grow while it is unpaid.\n *\n * Unscoped clears whatever is there, which is the staff path and the voided\n * invoice's. A dispute pause is never lifted by a payment of any kind: it\n * needs `force`, which only staff pass.\n */\nexport async function resumeAiOverage(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  scope: {\n    invoiceId?: string | null\n    reason?: AiOveragePauseReason\n    force?: boolean\n  } = {},\n): Promise<void> {\n  await updateStanding(firestore, orgId, (standing) => {\n    if (!standing.pause) return null\n    if (standing.pause.reason === 'dispute' && !scope.force) return null\n    if (scope.invoiceId && standing.pause.invoiceId !== scope.invoiceId) return null\n    if (scope.reason && standing.pause.reason !== scope.reason) return null\n    return { pause: null }\n  })\n}\n\n/**\n * Records a paid invoice, which is what moves a workspace up the ladder.\n *\n * Two different things happen on a first payment and on a later one. The\n * first sets `firstPaidMonth` — the baseline the ladder counts FROM, never a\n * step on it, because every paid workspace pays one invoice the moment it\n * subscribes and a ladder that counted it would start everyone a step up.\n * Every later month with a real payment adds a step.\n *\n * `aiOverageQualifyingMonth` decides which is which, and refuses a payment\n * that is not evidence: an invoice marked paid out of band is a staff\n * action, and a zero payment is a credit.\n */\nexport async function recordAiOveragePaidInvoice(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  payment: { month: string; amountPaidCents: number; paidOutOfBand: boolean },\n): Promise<void> {\n  await updateStanding(firestore, orgId, (standing) => {\n    if (payment.paidOutOfBand || !(payment.amountPaidCents > 0)) return null\n    if (!standing.firstPaidMonth) return { firstPaidMonth: payment.month }\n    const month = aiOverageQualifyingMonth(standing, payment)\n    if (!month) return null\n    if (standing.qualifyingMonths.includes(month)) return null\n    return withStep([...standing.qualifyingMonths, month].sort())\n  })\n}\n\n/**\n * Takes a month back off the ladder.\n *\n * The close-out sweep calls this for a month that ended with an AI charge\n * still unpaid. A month in which the workspace both paid an invoice and left\n * an AI charge unpaid is not evidence of the thing the ladder measures, and\n * leaving it counted would raise a ceiling on the strength of a payment that\n * did not happen.\n */\nexport async function dropAiOverageQualifyingMonth(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  month: string,\n): Promise<void> {\n  await updateStanding(firestore, orgId, (standing) => {\n    if (!standing.qualifyingMonths.includes(month)) return null\n    return withStep(standing.qualifyingMonths.filter((kept) => kept !== month))\n  })\n}\n\n/**\n * A dispute: the ladder goes back to the bottom and accrual stops.\n *\n * Both, not either. The reset is about the future — a workspace that\n * disputes has not earned a raised ceiling — and the pause is about now.\n * Only staff can lift the pause, because a dispute is a judgement about the\n * relationship and no automatic event should end it.\n */\nexport async function recordAiOverageDispute(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  now: Date,\n): Promise<void> {\n  await updateStanding(firestore, orgId, () => ({\n    ...withStep([]),\n    firstPaidMonth: null,\n    lastDisputeAt: now.toISOString(),\n    pause: { reason: 'dispute' as const, invoiceId: null, since: now.toISOString() },\n  }))\n}\n\n/**\n * Mirrors the workspace's default payment method type.\n *\n * `null` means the customer has no default, which is a real answer and is\n * written. The value is never written as `undefined` — that state means\n * \"nobody has looked\", and once anyone has, it is gone for good.\n */\nexport async function recordAiOveragePaymentMethod(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  defaultType: string | null,\n): Promise<void> {\n  await updateStanding(firestore, orgId, (standing) => {\n    if (standing.paymentMethodType === defaultType) return null\n    return { paymentMethodType: defaultType }\n  })\n}\n\n/** Sets or clears the staff ceiling override. */\nexport async function setAiOverageStaffOverride(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  override:\n    | { ceilingUsd: number; reason: string; setBy: string; expiresAt: string | null }\n    | null,\n  now: Date,\n): Promise<void> {\n  await updateStanding(firestore, orgId, () => ({\n    staffOverride: override\n      ? {\n          ceilingUsd: override.ceilingUsd,\n          reason: override.reason,\n          setBy: override.setBy,\n          setAt: now.toISOString(),\n          expiresAt: override.expiresAt,\n        }\n      : null,\n  }))\n}\n\n/**\n * Puts the workspace back at the bottom of the ladder by hand.\n *\n * Staff-only, and separate from the dispute reset: this one does not pause,\n * because staff resetting a step are correcting a standing, not responding\n * to a chargeback.\n */\nexport async function resetAiOverageStep(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n): Promise<void> {\n  await updateStanding(firestore, orgId, () => withStep([]))\n}\n"],"names":["FieldValue","AI_BILLING_STANDING_DOC","AI_BILLING_SUBCOLLECTION","AI_OVERAGE_QUALIFYING_MONTHS_KEPT","aiOverageQualifyingMonth","aiOverageStep","readAiOverageStanding","standingRef","firestore","orgId","collection","doc","updateStanding","change","ref","runTransaction","tx","snapshot","get","standing","exists","data","write","set","updatedAt","serverTimestamp","merge","withStep","months","kept","slice","qualifyingMonths","step","pauseAiOverage","pause","reason","invoiceId","since","now","toISOString","resumeAiOverage","scope","force","recordAiOveragePaidInvoice","payment","paidOutOfBand","amountPaidCents","firstPaidMonth","month","includes","sort","dropAiOverageQualifyingMonth","filter","recordAiOverageDispute","lastDisputeAt","recordAiOveragePaymentMethod","defaultType","paymentMethodType","setAiOverageStaffOverride","override","staffOverride","ceilingUsd","setBy","setAt","expiresAt","resetAiOverageStep"],"mappings":"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"}

package/src/lib/billing/ai-overage-standing.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
+/** The billing fields of an org, as every resolver in this folder takes it. */
+export type AiOverageOrg = Partial<AglynOrgBilling> | null | undefined;
+/**
+ * The unbilled overage at which the card on file is charged.
+ *
+ * Fifty times Stripe's minimum charge, so no charge is refused for being too
+ * small; low enough that what is outstanding between charges stays near the
+ * bound below; high enough that per-invoice fees stay a few percent.
+ */
+export declare const AI_OVERAGE_THRESHOLD_USD = 25;
+/**
+ * The most overage a workspace may have accrued and not paid for.
+ *
+ * Twice the threshold, so one charge in flight plus one accruing is inside
+ * it, and a workspace doing ordinary work never meets it. Meeting it means
+ * the charges are not settling, and that is exactly when accrual must stop.
+ */
+export declare const AI_OVERAGE_UNPAID_LIMIT_USD = 50;
+/**
+ * The monthly ceiling, by step. It rises one step for each later calendar
+ * month in which the workspace paid an invoice with a real charge.
+ *
+ * Months, not invoices: every paid workspace pays an invoice the moment it
+ * subscribes, and threshold invoices can arrive several times a day, so
+ * counting invoices would reach the top step in an afternoon. Counting
+ * months takes at least two, which covers much of the window in which a
+ * stolen card is reported.
+ */
+export declare const AI_OVERAGE_CEILING_LADDER_USD: readonly [50, 150, 500];
+/** The top index of the ladder; `step` is clamped to it. */
+export declare const AI_OVERAGE_MAX_STEP: number;
+/**
+ * The smallest amount worth an invoice — Stripe's own minimum charge. A
+ * close-out remainder under it is carried, not billed: an invoice that
+ * cannot be paid is a document that dunning chases forever.
+ */
+export declare const AI_OVERAGE_MIN_CHARGE_USD = 0.5;
+/** Bounds on a ceiling staff may write by hand, the customer ceiling's. */
+export declare const AI_OVERAGE_STAFF_CEILING_MIN_USD = 1;
+export declare const AI_OVERAGE_STAFF_CEILING_MAX_USD = 100000;
+/** Why overage is paused. Each one is payment trust dropping, differently. */
+export type AiOveragePauseReason = 'charge_failed' | 'past_due' | 'dispute' | 'staff';
+/** A staff ceiling that outranks the ladder. */
+export interface AiOverageStaffOverride {
+    ceilingUsd: number;
+    reason: string;
+    setBy: string;
+    setAt: string | null;
+    /** ISO instant, or `null` to stand until staff clear it. */
+    expiresAt: string | null;
+}
+/** Accrual stopped, and why. */
+export interface AiOveragePause {
+    reason: AiOveragePauseReason;
+    /** The invoice that failed, when a charge is what stopped it. */
+    invoiceId: string | null;
+    since: string | null;
+}
+/**
+ * `orgs/{orgId}/aiBilling/standing`, normalized.
+ *
+ * Written only by the server, read by the gate on every request past the
+ * band. The Firestore rules deny every client write and allow the same reads
+ * as `aiAllotments`.
+ */
+export interface AiOverageStanding {
+    /**
+     * The workspace's default payment method type, `null` when it has none,
+     * and `undefined` when nobody has looked yet.
+     *
+     * THREE states, not two, and the third is the important one. A workspace
+     * that has been paying for a year has no standing document until something
+     * writes one, and reading that absence as "no card" would refuse a paying
+     * customer's work over a document we never wrote. So "never observed"
+     * declines to answer the card question and lets the other guards bind —
+     * the unpaid bound does not rest on the card check, which is why it can
+     * afford to abstain. A pre-cutover backfill is what turns `undefined` into
+     * a real answer for existing workspaces.
+     */
+    paymentMethodType: string | null | undefined;
+    /** The first month (`YYYY-MM`) an invoice of this workspace's was paid. */
+    firstPaidMonth: string | null;
+    /**
+     * Later months with a paid invoice, ascending, the most recent 12 kept. A
+     * month is dropped again if an AI charge of that month was still unpaid
+     * when the month ended.
+     */
+    qualifyingMonths: string[];
+    staffOverride: AiOverageStaffOverride | null;
+    pause: AiOveragePause | null;
+    lastDisputeAt: string | null;
+}
+/** The standing of a workspace nothing has written a document for. */
+export declare const EMPTY_AI_OVERAGE_STANDING: AiOverageStanding;
+/** How many qualifying months the document keeps. */
+export declare const AI_OVERAGE_QUALIFYING_MONTHS_KEPT = 12;
+/**
+ * Reads the stored document into the shape above, strictly.
+ *
+ * Strictly, because every field here decides whether a workspace may spend
+ * money: a string `"true"` that read as a boolean, or a `NaN` ceiling that
+ * every comparison passes, is a guard that is not there. Anything that does
+ * not narrow is the empty standing's value for that field — which is the
+ * conservative answer in each case except the card, where the deliberate
+ * answer is "nobody has looked".
+ */
+export declare function readAiOverageStanding(data: Record<string, unknown> | null | undefined): AiOverageStanding;
+/**
+ * The workspace's step on the ladder — one per qualifying month, clamped.
+ *
+ * Derived rather than stored, so a stored `step` cannot disagree with the
+ * months it was supposed to have been derived from. The document carries a
+ * mirrored copy for readers that want one figure, and this is what writes it.
+ */
+export declare function aiOverageStep(standing: AiOverageStanding): number;
+/** Is a staff override still standing at this instant? */
+export declare function aiOverageOverrideApplies(override: AiOverageStaffOverride | null, now: Date): boolean;
+/**
+ * Aglyn's own ceiling on this month's overage, in retail dollars.
+ *
+ * The staff override when one stands, and the ladder otherwise. This is the
+ * platform's limit; the customer's own `capUsd` is a separate figure and the
+ * lower of the two binds — see `aiOverageEffectiveCeilingUsd`.
+ */
+export declare function aiOverageStandingCeilingUsd(standing: AiOverageStanding, now: Date): number;
+/**
+ * The ceiling that actually binds: the lower of the workspace's own and
+ * Aglyn's. For display and for staff; the gate consults the two separately,
+ * because the customer's ceiling and the platform's need different words.
+ */
+export declare function aiOverageEffectiveCeilingUsd(org: AiOverageOrg, standing: AiOverageStanding, now: Date): number;
+/**
+ * Whether a card is the default payment method, as far as anyone has looked.
+ *
+ * `undefined` when nobody has, and callers must handle that third answer
+ * rather than coercing it — see `paymentMethodType`.
+ */
+export declare function aiOverageCardOnFile(standing: AiOverageStanding): boolean | undefined;
+/**
+ * The month a qualifying step is recorded under, from a paid invoice.
+ *
+ * `null` when the payment is not evidence that money moved or that time has
+ * passed: an invoice marked paid out of band is a staff action, a zero
+ * payment is a credit, and the first paid month is the baseline the ladder
+ * counts FROM rather than a step on it.
+ */
+export declare function aiOverageQualifyingMonth(standing: AiOverageStanding, payment: {
+    month: string;
+    amountPaidCents: number;
+    paidOutOfBand: boolean;
+}): string | null;