@convex-dev/ai-budget 0.0.2-alpha.16 → 0.0.2-alpha.18

package/dist/component/lib.js

@@ -12,6 +12,34 @@ import { ShardedCounter } from "@convex-dev/sharded-counter";
 // currency code alongside these amounts and convert here, at the one boundary.
 const NANOS_PER_DOLLAR = 1e9;
 const fmtUsd = (nanos) => `$${(nanos / NANOS_PER_DOLLAR).toFixed(4)}`;
+// Convex's `v.number()` accepts NaN and ±Infinity. Those are poison here: a NaN
+// cap or count silently defeats every `used > cap` comparison (NaN > x is
+// false), so an unvalidated NaN would make admission fail OPEN and admit
+// unlimited spend; +Infinity in totals is just as corrupting. Validate every
+// externally-supplied accounting amount at the mutation boundary.
+function assertAmount(n, name, { signed = false } = {}) {
+    if (n === undefined)
+        return;
+    if (!Number.isFinite(n) || !Number.isSafeInteger(n)) {
+        throw new Error(`${name} must be a finite safe integer (got ${n})`);
+    }
+    if (!signed && n < 0)
+        throw new Error(`${name} must be nonnegative (got ${n})`);
+}
+function assertFraction(n, name) {
+    if (n === undefined)
+        return;
+    if (!Number.isFinite(n) || n < 0 || n > 1) {
+        throw new Error(`${name} must be a number in [0, 1] (got ${n})`);
+    }
+}
+// Coerce a caller/provider-supplied count to a finite nonnegative integer,
+// mapping NaN/Infinity/garbage to 0 rather than poisoning downstream totals.
+const safeCount = (n) => Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0;
+// Treat a non-finite stored accounting field as 0, so a bucket that was poisoned
+// before validation existed self-heals on its next reserve/release instead of
+// staying NaN forever.
+const fin = (n) => (Number.isFinite(n) ? n : 0);
 // Built-in attribution dimensions. `user` and `action` are always populated
 // from a request's userId/actionName; apps can add any other dimensions
 // (team, project, customer, env, …) as tags. These two names are reserved —
@@ -63,6 +91,16 @@ const STALE_PENDING_MS = 30 * 60 * 1000;
 // audit table — and the sensitive content in it — from growing without bound.
 // Override per-deployment via setRetention.
 const DEFAULT_RETENTION_MS = 60 * 60 * 1000; // 1 hour
+// Reconciliation runs as small, independently-rescheduling phases. Keeping the
+// batch small bounds the bytes read per transaction (each request row can carry
+// prompts/responses) so a burst can't push one phase past Convex's 8 MiB / 16k-
+// doc read limit and stall the whole reconciler. A phase that fills its batch
+// reschedules itself immediately, so throughput still scales with backlog.
+const RECONCILE_BATCH = 50;
+// Keep an expired billing tombstone (content already purged) this long so a very
+// late provider charge can still land against it, then delete it. A finish after
+// deletion is a graceful no-op.
+const LATE_SETTLE_HORIZON_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const dayStamp = () => new Date().toISOString().slice(0, 10); // "2026-09-04"
 const monthStamp = () => new Date().toISOString().slice(0, 7); // "2026-09"
 // Cached (prompt-cache-read) input tokens are billed far below the normal input
@@ -75,10 +113,15 @@ const CACHE_DISCOUNT = 0.1;
 // bills real money. Charging the conservative max instead keeps the caps honest
 // (over-counting is the safe direction); admins can pin an exact price via
 // setPrice, which also clears the `unpricedModel` flag on future requests.
+// Seed with a true frontier ceiling ($20/$100 per Mtok), not just the max of the
+// small built-in table — otherwise premium models (Opus-class $15/$75, etc.) not
+// in the table would be under-counted several-fold whenever the gateway's
+// authoritative cost isn't available. Over-counting an unpriced model is the safe
+// direction; admins pin the exact rate with setPrice.
 const CONSERVATIVE_PRICE = Object.values(DEFAULT_PRICES).reduce((m, p) => ({
     input: Math.max(m.input, p.input),
     output: Math.max(m.output, p.output),
-}), { input: 0, output: 0 });
+}), { input: 20_000_000_000, output: 100_000_000_000 });
 async function getPrice(ctx, model) {
     const override = await ctx.db
         .query("prices")
@@ -355,6 +398,11 @@ export const startRequest = mutation({
         if (args.reserveTtlMs !== undefined && (!Number.isFinite(args.reserveTtlMs) || args.reserveTtlMs < 0)) {
             throw new Error("reserveTtlMs must be finite and nonnegative");
         }
+        // Infinity/NaN here is catastrophic: it's reserved onto the bucket, and a
+        // later release computes `Infinity - Infinity = NaN`, leaving the reserved
+        // fields NaN forever — after which every `used > cap` check is `NaN > cap`
+        // (false) and the bucket admits unlimited spend. Reject it up front.
+        assertAmount(args.estimatedCostNanos, "estimatedCostNanos");
         const extraTags = sanitizeExtraTags(args.tags);
         // Record the blocked attempt and return a rejection (throwing would roll
         // back the record). `persist` is false for the high-frequency-by-design
@@ -525,8 +573,14 @@ export const startRequest = mutation({
             notices.push(...globalEval.notices);
         }
         // Consume only after every admission check succeeds, in the same
-        // transaction as the reservations and request insert. An unexpected
-        // rejection throws to roll back all previously consumed dimensions.
+        // transaction as the reservations and request insert. `throws: true` is
+        // deliberate, not a rough edge: we already `.check`ed every bucket above in
+        // this same serializable transaction, so a `.limit` here cannot fail on a
+        // bucket that passed check — and if it somehow did (or a later bucket did),
+        // throwing rolls back the WHOLE transaction, including the rate we already
+        // consumed on earlier buckets. Converting this to a graceful `{allowed:false}`
+        // return would COMMIT the partial consumption and leak rate capacity, so keep
+        // the throw.
         for (const b of buckets) {
             if (b.requestsPerMinute !== undefined) {
                 await requestRateLimiter.limit(ctx, "requests", {
@@ -612,29 +666,41 @@ export const finishRequest = mutation({
     returns: v.object({ costNanos: v.number() }),
     handler: async (ctx, args) => {
         const request = await ctx.db.get(args.requestId);
+        // The request may be gone — retention purged it, or the owning bucket was
+        // deleted. A late/duplicate webhook must be an idempotent no-op, not a 500
+        // (the caller can't do anything useful with the error, and it triggers retries).
         if (!request)
-            throw new Error("Unknown request");
+            return { costNanos: 0 };
         // Expiry releases capacity, but is not evidence that the provider charged
         // nothing. Accept one final result even after expiry; duplicates stay no-ops.
         if (request.status !== "pending" && !request.reservationExpired) {
             return { costNanos: request.costNanos ?? 0 };
         }
-        // Clamp caller-supplied token counts: negatives would produce negative cost
-        // and could refund a user below their cap.
-        const promptTokens = Math.max(0, args.promptTokens ?? 0);
-        const completionTokens = Math.max(0, args.completionTokens ?? 0);
-        const cachedTokens = Math.min(promptTokens, Math.max(0, args.cachedTokens ?? 0));
+        // Coerce caller/provider-supplied token counts to finite nonnegative
+        // integers: negatives would refund below a cap, and NaN/Infinity (which
+        // v.number() allows) would poison every downstream total and cap check.
+        const promptTokens = safeCount(args.promptTokens);
+        const completionTokens = safeCount(args.completionTokens);
+        const cachedTokens = Math.min(promptTokens, safeCount(args.cachedTokens));
         // Prefer an authoritative gateway cost when supplied (it already includes
         // tool fees); otherwise price from tokens — discounting the cached
-        // (prompt-cache-read) slice — plus any server-tool per-call fees.
+        // (prompt-cache-read) slice — plus any server-tool per-call fees. Require it
+        // finite: +Infinity passes a bare `>= 0` and would corrupt the totals.
         let costNanos;
-        if (args.costNanos !== undefined && args.costNanos >= 0) {
+        if (args.costNanos !== undefined && Number.isFinite(args.costNanos) && args.costNanos >= 0) {
             costNanos = Math.round(args.costNanos);
         }
         else {
             const settings = await getSettings(ctx);
-            costNanos =
-                settleCost(promptTokens, cachedTokens, completionTokens, await getPrice(ctx, request.model)) + serverToolCost(args.serverToolUses, settings?.serverToolPrices);
+            const priced = settleCost(promptTokens, cachedTokens, completionTokens, await getPrice(ctx, request.model)) + serverToolCost(args.serverToolUses, settings?.serverToolPrices);
+            // Fail closed: if the settle carried NO usable cost signal — no tokens and
+            // no priced server-tool fee (an unpriced tool like `video_seconds`, or a
+            // bare settle()) — fall back to the reserved estimate rather than recording
+            // $0. Known-cost calls (image/video/audio) set estimatedCostNanos at
+            // reserve time precisely so this floor is their real cost. A caller that
+            // truly wants $0 passes an explicit authoritative costNanos: 0 above.
+            const noSignal = promptTokens === 0 && completionTokens === 0 && priced === 0;
+            costNanos = noSignal ? (request.estimatedNanos ?? 0) : priced;
         }
         // Durable write to the request's OWN row only — uncontended, so it always
         // lands. `settled: false` hands it to the fold step; the row is never left
@@ -676,13 +742,13 @@ async function releaseReservation(ctx, req) {
         if (!b || (req.heldBucketIds ? !req.heldBucketIds.includes(b._id) : !needsReserve(b)))
             continue;
         await ctx.db.patch(b._id, {
-            reservedTodayNanos: Math.max(0, (b.reservedTodayNanos ?? 0) - (b.dayStamp === day ? cost : 0)),
-            reservedMonthNanos: Math.max(0, (b.reservedMonthNanos ?? 0) - (b.monthStamp === month ? cost : 0)),
-            reservedTotalNanos: Math.max(0, (b.reservedTotalNanos ?? 0) - cost),
-            reservedTodayTokens: Math.max(0, (b.reservedTodayTokens ?? 0) - (b.dayStamp === day ? tokens : 0)),
-            reservedMonthTokens: Math.max(0, (b.reservedMonthTokens ?? 0) - (b.monthStamp === month ? tokens : 0)),
-            reservedTotalTokens: Math.max(0, (b.reservedTotalTokens ?? 0) - tokens),
-            pendingCount: Math.max(0, (b.pendingCount ?? 0) - 1),
+            reservedTodayNanos: Math.max(0, fin(b.reservedTodayNanos) - (b.dayStamp === day ? cost : 0)),
+            reservedMonthNanos: Math.max(0, fin(b.reservedMonthNanos) - (b.monthStamp === month ? cost : 0)),
+            reservedTotalNanos: Math.max(0, fin(b.reservedTotalNanos) - cost),
+            reservedTodayTokens: Math.max(0, fin(b.reservedTodayTokens) - (b.dayStamp === day ? tokens : 0)),
+            reservedMonthTokens: Math.max(0, fin(b.reservedMonthTokens) - (b.monthStamp === month ? tokens : 0)),
+            reservedTotalTokens: Math.max(0, fin(b.reservedTotalTokens) - tokens),
+            pendingCount: Math.max(0, fin(b.pendingCount) - 1),
         });
     }
     await ctx.db.patch(req._id, { reservationReleased: true });
@@ -738,27 +804,49 @@ export const foldTotals = internalMutation({
 // Backstop for both failure modes: folds finished requests whose scheduled fold
 // lost the retry race, and releases reservations for requests that never
 // settled (their action crashed). Runs on a cron.
+// Cron entry: kick off each reconciliation phase as its OWN transaction so a
+// failure in one (e.g. an oversized retention scan) can't stall the others, and
+// so the hot fold path doesn't share a transaction with retention. Each phase
+// self-reschedules while it has a full batch of backlog.
 export const reconcile = internalMutation({
     args: {},
-    returns: v.object({
-        folded: v.number(),
-        expired: v.number(),
-        purged: v.number(),
-    }),
+    returns: v.null(),
+    handler: async (ctx) => {
+        await ctx.scheduler.runAfter(0, internal.lib.foldPhase, {});
+        await ctx.scheduler.runAfter(0, internal.lib.expirePhase, {});
+        await ctx.scheduler.runAfter(0, internal.lib.retentionPhase, {});
+        return null;
+    },
+});
+// Fold finished-but-unfolded requests whose scheduled fold lost the OCC race.
+export const foldPhase = internalMutation({
+    args: {},
+    returns: v.object({ folded: v.number() }),
     handler: async (ctx) => {
         const toFold = await ctx.db
             .query("requests")
             .withIndex("settled", (q) => q.eq("settled", false))
-            .take(200);
+            .take(RECONCILE_BATCH);
         for (const req of toFold)
             await foldOne(ctx, req);
+        if (toFold.length === RECONCILE_BATCH)
+            await ctx.scheduler.runAfter(0, internal.lib.foldPhase, {});
+        return { folded: toFold.length };
+    },
+});
+// Release reservations for requests that never settled (their action crashed),
+// and lazily backfill deadlines on legacy pending rows.
+export const expirePhase = internalMutation({
+    args: {},
+    returns: v.object({ expired: v.number() }),
+    handler: async (ctx) => {
         // Lazily migrate old pending rows in bounded batches. Once indexed, long
         // TTL jobs cannot hide expired jobs behind them in creation-time order.
-        const legacy = await ctx.db.query("requests").withIndex("status_expires", q => q.eq("status", "pending").eq("expiresAt", undefined)).take(200);
+        const legacy = await ctx.db.query("requests").withIndex("status_expires", q => q.eq("status", "pending").eq("expiresAt", undefined)).take(RECONCILE_BATCH);
         for (const req of legacy) {
             await ctx.db.patch(req._id, { expiresAt: req._creationTime + Math.max(STALE_PENDING_MS, req.reserveTtlMs ?? 0) });
         }
-        const candidates = await ctx.db.query("requests").withIndex("status_expires", q => q.eq("status", "pending").gt("expiresAt", 0).lte("expiresAt", Date.now())).take(200);
+        const candidates = await ctx.db.query("requests").withIndex("status_expires", q => q.eq("status", "pending").gt("expiresAt", 0).lte("expiresAt", Date.now())).take(RECONCILE_BATCH);
         for (const req of candidates) {
             await releaseReservation(ctx, req);
             await ctx.db.patch(req._id, {
@@ -766,33 +854,57 @@ export const reconcile = internalMutation({
                 reservationExpired: true, expiresAt: undefined, settled: true,
             });
         }
-        const expired = candidates.length;
-        // Retention: delete terminal, fully-accounted request rows past the window.
+        if (legacy.length === RECONCILE_BATCH || candidates.length === RECONCILE_BATCH)
+            await ctx.scheduler.runAfter(0, internal.lib.expirePhase, {});
+        return { expired: candidates.length };
+    },
+});
+// Delete terminal, fully-accounted request rows past the retention window; purge
+// content from expired tombstones; and finally delete tombstones past the
+// late-settle horizon so they can't accumulate forever.
+export const retentionPhase = internalMutation({
+    args: {},
+    returns: v.object({ purged: v.number() }),
+    handler: async (ctx) => {
         const settings = await getSettings(ctx);
         const retentionMs = settings?.retentionMs ?? DEFAULT_RETENTION_MS;
+        if (retentionMs <= 0)
+            return { purged: 0 };
+        const retentionCutoff = Date.now() - retentionMs;
         let purged = 0;
-        if (retentionMs > 0) {
-            const retentionCutoff = Date.now() - retentionMs;
-            // Query eligible states directly. Long-lived pending jobs and expired
-            // billing tombstones must not repeatedly occupy the front of a scan.
-            const old = [];
-            for (const expiredFlag of [undefined, false]) {
-                old.push(...await ctx.db.query("requests").withIndex("retention", q => q.eq("reservationExpired", expiredFlag).eq("settled", true)
-                    .lt("_creationTime", retentionCutoff)).take(200));
-            }
-            old.push(...await ctx.db.query("requests").withIndex("status", q => q.eq("status", "blocked").lt("_creationTime", retentionCutoff)).take(100));
-            for (const req of old) {
+        let more = false;
+        const sweep = async (rows) => {
+            for (const req of rows) {
                 await deleteRequestTags(ctx, req._id);
                 await ctx.db.delete(req._id);
                 purged++;
             }
-            const expiredContent = await ctx.db.query("requests").withIndex("expired_content", q => q.eq("reservationExpired", true).eq("contentPurged", undefined)
-                .lt("_creationTime", retentionCutoff)).take(200);
-            for (const req of expiredContent) {
-                await ctx.db.patch(req._id, { messages: [], responseText: undefined, contentPurged: true });
-            }
+            if (rows.length === RECONCILE_BATCH)
+                more = true;
+        };
+        // Settled, non-expired terminal rows past the window.
+        for (const expiredFlag of [undefined, false]) {
+            await sweep(await ctx.db.query("requests").withIndex("retention", q => q.eq("reservationExpired", expiredFlag).eq("settled", true)
+                .lt("_creationTime", retentionCutoff)).take(RECONCILE_BATCH));
+        }
+        // Blocked attempts past the window.
+        await sweep(await ctx.db.query("requests").withIndex("status", q => q.eq("status", "blocked").lt("_creationTime", retentionCutoff)).take(RECONCILE_BATCH));
+        // Expired billing tombstones past the late-settle horizon (content already
+        // gone). Without this they'd live forever (one per crashed request).
+        const tombstoneCutoff = Date.now() - Math.max(retentionMs, LATE_SETTLE_HORIZON_MS);
+        await sweep(await ctx.db.query("requests").withIndex("retention", q => q.eq("reservationExpired", true).eq("settled", true)
+            .lt("_creationTime", tombstoneCutoff)).take(RECONCILE_BATCH));
+        // Strip PII from expired tombstones still inside the horizon.
+        const expiredContent = await ctx.db.query("requests").withIndex("expired_content", q => q.eq("reservationExpired", true).eq("contentPurged", undefined)
+            .lt("_creationTime", retentionCutoff)).take(RECONCILE_BATCH);
+        for (const req of expiredContent) {
+            await ctx.db.patch(req._id, { messages: [], responseText: undefined, contentPurged: true });
         }
-        return { folded: toFold.length, expired, purged };
+        if (expiredContent.length === RECONCILE_BATCH)
+            more = true;
+        if (more)
+            await ctx.scheduler.runAfter(0, internal.lib.retentionPhase, {});
+        return { purged };
     },
 });
 export const setRetention = mutation({
@@ -937,10 +1049,15 @@ export const setBucketLimits = mutation({
     },
     returns: v.null(),
     handler: async (ctx, args) => {
-        if (args.requestsPerMinute !== undefined &&
-            (!Number.isSafeInteger(args.requestsPerMinute) || args.requestsPerMinute < 0)) {
-            throw new Error("requestsPerMinute must be a nonnegative safe integer");
-        }
+        assertAmount(args.requestsPerMinute, "requestsPerMinute");
+        assertAmount(args.maxConcurrent, "maxConcurrent");
+        assertAmount(args.dailySpendLimitNanos, "dailySpendLimitNanos");
+        assertAmount(args.monthlySpendLimitNanos, "monthlySpendLimitNanos");
+        assertAmount(args.lifetimeSpendLimitNanos, "lifetimeSpendLimitNanos");
+        assertAmount(args.dailyTokenLimit, "dailyTokenLimit");
+        assertAmount(args.monthlyTokenLimit, "monthlyTokenLimit");
+        assertAmount(args.lifetimeTokenLimit, "lifetimeTokenLimit");
+        assertFraction(args.warnAtPct, "warnAtPct");
         const bucket = await getOrCreateBucket(ctx, args.dimension, args.value);
         const { dimension: _d, value: _v, ...limits } = args;
         await ctx.db.patch(bucket._id, limits);
@@ -960,6 +1077,9 @@ export const bumpBucket = mutation({
     args: { dimension: v.string(), value: v.string(), ...vBumpArgs },
     returns: v.null(),
     handler: async (ctx, { dimension, value, dailyNanos, monthlyNanos, lifetimeNanos }) => {
+        assertAmount(dailyNanos, "dailyNanos");
+        assertAmount(monthlyNanos, "monthlyNanos");
+        assertAmount(lifetimeNanos, "lifetimeNanos");
         const bucket = await getOrCreateBucket(ctx, dimension, value);
         const today = dayStamp();
         const month = monthStamp();
@@ -989,6 +1109,8 @@ export const adjustBucket = mutation({
     },
     returns: v.null(),
     handler: async (ctx, { dimension, value, deltaNanos, tokens, reason }) => {
+        assertAmount(deltaNanos, "deltaNanos", { signed: true });
+        assertAmount(tokens, "tokens", { signed: true });
         const b = await getOrCreateBucket(ctx, dimension, value);
         const today = dayStamp();
         const month = monthStamp();
@@ -1004,6 +1126,12 @@ export const adjustBucket = mutation({
             tokensToday: Math.max(0, (dSame ? b.tokensToday ?? 0 : 0) + dt),
             spendThisMonthNanos: Math.max(0, (mSame ? b.spendThisMonthNanos ?? 0 : 0) + deltaNanos),
             tokensThisMonth: Math.max(0, (mSame ? b.tokensThisMonth ?? 0 : 0) + dt),
+            // Advancing the window here must also clear the OLD window's reserved
+            // holds, or an in-flight request from the previous day/month would be
+            // treated as reserving against the new window and its later release would
+            // no longer match — stranding those reserved nanos/tokens.
+            ...(dSame ? {} : { reservedTodayNanos: 0, reservedTodayTokens: 0 }),
+            ...(mSame ? {} : { reservedMonthNanos: 0, reservedMonthTokens: 0 }),
         });
         await ctx.db.insert("adjustments", { dimension, value, deltaNanos, tokens: dt, reason });
         await addUsage(ctx, dimension, value, "day", today, deltaNanos, dt, 0);
@@ -1064,6 +1192,17 @@ export const deleteBucket = mutation({
                 .withIndex("userId", (q) => q.eq("userId", value))
                 .take(DELETE_BATCH);
             for (const r of rows) {
+                // Before dropping the row, free or settle any hold it placed on OTHER
+                // (shared) buckets — an action/customer bucket this user's request
+                // reserved against. Otherwise deleting the only row that could release
+                // that hold strands the shared bucket's reservation + pendingCount
+                // forever, and a late finish would throw. A finished-but-unfolded row
+                // is folded (the charge lands on the shared buckets); a still-pending
+                // one just has its reservation released.
+                if (r.settled === false)
+                    await foldOne(ctx, r);
+                else if (r.status === "pending")
+                    await releaseReservation(ctx, r);
                 await deleteRequestTags(ctx, r._id);
                 await ctx.db.delete(r._id);
             }
@@ -1139,18 +1278,29 @@ export const getGlobalStatus = query({
 });
 export const setGlobalLimits = mutation({
     args: {
-        dailySpendLimitNanos: v.optional(v.number()),
-        lifetimeSpendLimitNanos: v.optional(v.number()),
-        enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
+        // Absent = leave unchanged; explicit null = clear that limit. (A bare
+        // v.optional(number) that always rebuilt the full patch would let a
+        // one-field edit — exactly what the dashboard sends — silently wipe the
+        // other global controls by patching them to undefined.)
+        dailySpendLimitNanos: v.optional(v.union(v.number(), v.null())),
+        lifetimeSpendLimitNanos: v.optional(v.union(v.number(), v.null())),
+        enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"), v.null())),
     },
     returns: v.null(),
     handler: async (ctx, args) => {
-        // The settings fields are "global"-prefixed; map the friendly arg names.
-        const patch = {
-            globalDailySpendLimitNanos: args.dailySpendLimitNanos,
-            globalLifetimeSpendLimitNanos: args.lifetimeSpendLimitNanos,
-            globalEnforcement: args.enforcement,
-        };
+        if (typeof args.dailySpendLimitNanos === "number")
+            assertAmount(args.dailySpendLimitNanos, "dailySpendLimitNanos");
+        if (typeof args.lifetimeSpendLimitNanos === "number")
+            assertAmount(args.lifetimeSpendLimitNanos, "lifetimeSpendLimitNanos");
+        // The settings fields are "global"-prefixed; map the friendly arg names,
+        // touching ONLY the keys the caller actually passed. null -> clear.
+        const patch = {};
+        if ("dailySpendLimitNanos" in args)
+            patch.globalDailySpendLimitNanos = args.dailySpendLimitNanos ?? undefined;
+        if ("lifetimeSpendLimitNanos" in args)
+            patch.globalLifetimeSpendLimitNanos = args.lifetimeSpendLimitNanos ?? undefined;
+        if ("enforcement" in args)
+            patch.globalEnforcement = args.enforcement ?? undefined;
         const existing = await getSettings(ctx);
         if (existing) {
             await ctx.db.patch(existing._id, patch);
@@ -1216,11 +1366,11 @@ export const setPrice = mutation({
     handler: async (ctx, args) => {
         // Negative prices would make costOf return a negative cost, which folds
         // into totals as a spend *refund* — pushing a user back under their cap.
-        if (args.inputNanosPerMTok < 0 ||
-            args.outputNanosPerMTok < 0 ||
-            (args.cachedNanosPerMTok ?? 0) < 0) {
-            throw new Error("Prices must be non-negative");
-        }
+        // NaN/Infinity (allowed by v.number()) are just as corrupting — a NaN rate
+        // poisons every settled cost for the model — so require finite integers.
+        assertAmount(args.inputNanosPerMTok, "inputNanosPerMTok");
+        assertAmount(args.outputNanosPerMTok, "outputNanosPerMTok");
+        assertAmount(args.cachedNanosPerMTok, "cachedNanosPerMTok");
         const existing = await ctx.db
             .query("prices")
             .withIndex("model", (q) => q.eq("model", args.model))

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/ai-budget/issues"
   },
-  "version": "0.0.2-alpha.16",
+  "version": "0.0.2-alpha.18",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [

package/src/client/dashboard.ts

@@ -97,8 +97,18 @@ async function renderBuckets() {
   const dims = ["user", "action"];
   const state = { dimension: window.__dim ?? "" };
   const rows = await get("/buckets", state.dimension ? { dimension: state.dimension } : {});
-  const grand = rows.reduce((s, b) => s + b.totalSpendNanos, 0);
-  document.getElementById("total").textContent = rows.length + " buckets · " + usd(grand) + " total";
+  // Within ONE dimension each request bills exactly one bucket, so summing is a
+  // true total. Across dimensions a request bills several buckets (user + action
+  // + tags), so summing multi-counts — use the deployment-wide spend instead.
+  let totalText;
+  if (state.dimension) {
+    const grand = rows.reduce((s, b) => s + b.totalSpendNanos, 0);
+    totalText = rows.length + " buckets · " + usd(grand) + " total (" + state.dimension + ")";
+  } else {
+    const g = await get("/global", {});
+    totalText = rows.length + " buckets · " + usd(g.spentTotalNanos ?? 0) + " spent (deployment)";
+  }
+  document.getElementById("total").textContent = totalText;
   const dimSet = [...new Set(rows.map((b) => b.dimension).concat(dims))];
   const sel = el("select", { value: state.dimension, style: "width:140px",
     onchange: (e) => { window.__dim = e.target.value; render(); } },