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

package/README.md

@@ -584,19 +584,29 @@ import { AIBudget } from "@convex-dev/ai-budget";
 const ai = new AIBudget(components.aiBudget);
 const http = httpRouter();
 
-ai.registerRoutes(http, {
-  // Gate it — the endpoint is public. Recommended: check the caller is an admin.
-  authorize: async (ctx) => (await ctx.auth.getUserIdentity())?.role === "admin",
-});
+// Recommended: token mode. Set AI_BUDGET_DASHBOARD_TOKEN in the deployment env;
+// open the dashboard with ?token=<it> once and the page keeps using it.
+ai.registerRoutes(http);
 
 export default http;
 ```
 
 It lives at `https://<deployment>.convex.site/aibudget` (override with `path`).
-**It is a public internet endpoint, so you must gate it**: pass `authorize`
-(return `true` to allow) or set `AI_BUDGET_DASHBOARD_TOKEN` (sent as
-`Authorization: Bearer …`). With neither, every route returns 401. Everything the
-page shows is backed by the component's own functions — nothing else to wire up.
+**It is a public internet endpoint, so you must gate it**, one of two ways:
+
+- **Token (recommended, works end-to-end):** set the `AI_BUDGET_DASHBOARD_TOKEN`
+  env var. Open `…/aibudget?token=<token>` once; the page strips it from the URL
+  and sends it as a bearer on every API call. `?token=` is accepted only on the
+  page navigation, and the compare is constant-time.
+- **`authorize(ctx, request)` callback:** must authenticate from something the
+  **browser sends on a top-level navigation** — a cookie or a header *you*
+  control — because a page load carries no `Authorization` bearer. `ctx.auth`
+  (deployment JWT) is `null` for the HTML page, so `authorize: (ctx) => (await
+  ctx.auth.getUserIdentity())?.role === "admin"` will 401 the page. Use it only
+  when you have your own session cookie to check.
+
+With neither configured, every route returns 401. Everything the page shows is
+backed by the component's own functions — nothing else to wire up.
 
 ---
 
@@ -641,6 +651,19 @@ more tokens or costs more than estimated, settlement records the real amount and
 the final total can exceed a hard cap by that request's estimation delta. The next
 admission sees the settled total and blocks until there is headroom again.
 
+**Throughput characteristics (know these before you turn on a global cap).**
+Reconciliation runs as small, independently-rescheduling phases, so folding,
+expiry, and retention can't stall each other and each drains its own backlog.
+Two shared-write hot spots remain, by design:
+- The **global cap** reads a sharded counter *inside* admission, which contends
+  with every fold that writes it — so a configured global cap adds contention on
+  the hot path. It's a deployment-wide killswitch, not a high-throughput per-call
+  limit; prefer per-bucket caps for the common case.
+- **Settlement writes every attributed bucket**, including the per-request
+  `action` bucket that every call shares. That single row is written by every
+  settle, so an extremely high single-action settle rate can lag totals. Spread
+  load across naturally-sharded dimensions (per user/customer) where you can.
+
 The `error.md` file documents the adversarial audits this design survived, with
 live repros.
 

package/dist/client/index.js

@@ -39,10 +39,17 @@ function toTokenCount(x) {
 }
 function extractUsage(usage) {
     return {
-        // Cover AI SDK camelCase (v5/v7) AND raw OpenAI-compatible snake_case, so a
-        // `meter` caller passing a raw provider `usage` object still gets counts.
-        promptTokens: toTokenCount(usage?.inputTokens ?? usage?.promptTokens ?? usage?.prompt_tokens),
-        completionTokens: toTokenCount(usage?.outputTokens ?? usage?.completionTokens ?? usage?.completion_tokens),
+        // Cover AI SDK camelCase (v5/v7), raw OpenAI-compatible snake_case, AND raw
+        // Anthropic (`input_tokens`/`output_tokens`), so a `meter` caller passing any
+        // provider's raw `usage` object still gets counts.
+        promptTokens: toTokenCount(usage?.inputTokens ??
+            usage?.promptTokens ??
+            usage?.prompt_tokens ??
+            usage?.input_tokens),
+        completionTokens: toTokenCount(usage?.outputTokens ??
+            usage?.completionTokens ??
+            usage?.completion_tokens ??
+            usage?.output_tokens),
         // cached prompt tokens. The Convex gateway reports these at
         // `usage.inputTokenDetails.cacheReadTokens`; the other paths cover AI SDK v5
         // (`cachedInputTokens`) and raw OpenAI-compatible shapes.
@@ -50,7 +57,8 @@ function extractUsage(usage) {
             usage?.cachedInputTokens ??
             usage?.promptTokensDetails?.cachedTokens ??
             usage?.prompt_tokens_details?.cached_tokens ??
-            usage?.cached_tokens),
+            usage?.cached_tokens ??
+            usage?.cache_read_input_tokens),
     };
 }
 // The AI Gateway reports the authoritative dollar cost of each request.
@@ -72,6 +80,10 @@ function extractGatewayCostNanos(result) {
     return undefined;
 }
 const NANOS_PER_DOLLAR = 1e9;
+// Cap stored prompt/response content so one row can't approach Convex's 1 MiB
+// document limit (which would fail the call) or bloat the reconciler's scans.
+const MAX_STORED_CONTENT = 32 * 1024;
+const capContent = (s) => s.length > MAX_STORED_CONTENT ? s.slice(0, MAX_STORED_CONTENT) + "…[truncated]" : s;
 // Flatten an AI SDK prompt (roles + content parts) into simple storable messages.
 function simplifyPrompt(prompt) {
     if (!Array.isArray(prompt))
@@ -83,13 +95,22 @@ function simplifyPrompt(prompt) {
         }
         else if (Array.isArray(m.content)) {
             content = m.content
-                .map((part) => part?.type === "text" ? part.text : JSON.stringify(part))
+                .map((part) => {
+                if (part?.type === "text")
+                    return part.text ?? "";
+                // NEVER inline a base64 image/file part — a data URL or Uint8Array here
+                // becomes megabytes, pushing the stored row past the 1 MiB doc limit
+                // (failing the call) and turning a 200 KB image into a ~50k-token
+                // estimate. Store a compact placeholder.
+                const bytes = part?.data?.length ?? part?.image?.length ?? part?.data?.byteLength;
+                return `[${part?.type ?? "part"}${typeof bytes === "number" ? ` ${bytes}b` : ""}]`;
+            })
                 .join("");
         }
         else {
             content = JSON.stringify(m.content);
         }
-        return { role: String(m.role), content };
+        return { role: String(m.role), content: capContent(content) };
     });
 }
 function extractText(result) {
@@ -491,6 +512,21 @@ export class AIBudget {
                             async flush() {
                                 await settle();
                             },
+                            // A cancelled/aborted stream (client disconnect, AbortSignal, or
+                            // breaking out of `for await`) does NOT run `flush`. Without this
+                            // the request would sit pending until the 30-min reservation
+                            // expiry and be recorded as $0 though the provider charged for
+                            // what streamed. Settle here with the text so far, estimating the
+                            // completion tokens when the provider gave no usage.
+                            // `cancel` is a newer Streams-spec transformer hook not yet in
+                            // the TS DOM lib types; cast the literal so it compiles (runtimes
+                            // without it simply won't call it, and the reconciler backstops).
+                            async cancel(reason) {
+                                if (usage === undefined && text) {
+                                    usage = { outputTokens: Math.ceil(text.length / 4) };
+                                }
+                                await settle(`cancelled: ${String(reason)}`);
+                            },
                         }));
                         return { ...result, stream: tapped };
                     }

package/dist/component/_generated/component.d.ts

@@ -117,9 +117,9 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             warnAtPct?: number;
         }, null, Name>;
         setGlobalLimits: FunctionReference<"mutation", "internal", {
-            dailySpendLimitNanos?: number;
-            enforcement?: "hard" | "soft";
-            lifetimeSpendLimitNanos?: number;
+            dailySpendLimitNanos?: number | null;
+            enforcement?: "hard" | "soft" | null;
+            lifetimeSpendLimitNanos?: number | null;
         }, null, Name>;
         setModelPolicy: FunctionReference<"mutation", "internal", {
             mode: "open" | "allowlist" | "denylist";

package/dist/component/lib.d.ts

@@ -39,9 +39,14 @@ export declare const finishRequest: import("convex/server").RegisteredMutation<"
 export declare const foldTotals: import("convex/server").RegisteredMutation<"internal", {
     requestId: import("convex/values").GenericId<"requests">;
 }, Promise<null>>;
-export declare const reconcile: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+export declare const reconcile: import("convex/server").RegisteredMutation<"internal", {}, Promise<null>>;
+export declare const foldPhase: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
     folded: number;
+}>>;
+export declare const expirePhase: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
     expired: number;
+}>>;
+export declare const retentionPhase: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
     purged: number;
 }>>;
 export declare const setRetention: import("convex/server").RegisteredMutation<"public", {

package/dist/component/lib.js

@@ -36,6 +36,10 @@ function assertFraction(n, name) {
 // 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 —
@@ -87,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
@@ -99,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")
@@ -379,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
@@ -668,8 +692,15 @@ export const finishRequest = mutation({
         }
         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
@@ -711,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 });
@@ -773,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, {
@@ -801,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({

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.17",
+  "version": "0.0.2-alpha.18",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [

package/src/client/index.ts

@@ -172,13 +172,20 @@ function extractUsage(usage: any): {
   cachedTokens: number;
 } {
   return {
-    // Cover AI SDK camelCase (v5/v7) AND raw OpenAI-compatible snake_case, so a
-    // `meter` caller passing a raw provider `usage` object still gets counts.
+    // Cover AI SDK camelCase (v5/v7), raw OpenAI-compatible snake_case, AND raw
+    // Anthropic (`input_tokens`/`output_tokens`), so a `meter` caller passing any
+    // provider's raw `usage` object still gets counts.
     promptTokens: toTokenCount(
-      usage?.inputTokens ?? usage?.promptTokens ?? usage?.prompt_tokens
+      usage?.inputTokens ??
+        usage?.promptTokens ??
+        usage?.prompt_tokens ??
+        usage?.input_tokens
     ),
     completionTokens: toTokenCount(
-      usage?.outputTokens ?? usage?.completionTokens ?? usage?.completion_tokens
+      usage?.outputTokens ??
+        usage?.completionTokens ??
+        usage?.completion_tokens ??
+        usage?.output_tokens
     ),
     // cached prompt tokens. The Convex gateway reports these at
     // `usage.inputTokenDetails.cacheReadTokens`; the other paths cover AI SDK v5
@@ -188,7 +195,8 @@ function extractUsage(usage: any): {
         usage?.cachedInputTokens ??
         usage?.promptTokensDetails?.cachedTokens ??
         usage?.prompt_tokens_details?.cached_tokens ??
-        usage?.cached_tokens
+        usage?.cached_tokens ??
+        usage?.cache_read_input_tokens
     ),
   };
 }
@@ -214,6 +222,12 @@ function extractGatewayCostNanos(result: any): number | undefined {
 
 const NANOS_PER_DOLLAR = 1e9;
 
+// Cap stored prompt/response content so one row can't approach Convex's 1 MiB
+// document limit (which would fail the call) or bloat the reconciler's scans.
+const MAX_STORED_CONTENT = 32 * 1024;
+const capContent = (s: string) =>
+  s.length > MAX_STORED_CONTENT ? s.slice(0, MAX_STORED_CONTENT) + "…[truncated]" : s;
+
 // Flatten an AI SDK prompt (roles + content parts) into simple storable messages.
 function simplifyPrompt(prompt: any): Message[] {
   if (!Array.isArray(prompt)) return [];
@@ -223,14 +237,20 @@ function simplifyPrompt(prompt: any): Message[] {
       content = m.content;
     } else if (Array.isArray(m.content)) {
       content = m.content
-        .map((part: any) =>
-          part?.type === "text" ? part.text : JSON.stringify(part)
-        )
+        .map((part: any) => {
+          if (part?.type === "text") return part.text ?? "";
+          // NEVER inline a base64 image/file part — a data URL or Uint8Array here
+          // becomes megabytes, pushing the stored row past the 1 MiB doc limit
+          // (failing the call) and turning a 200 KB image into a ~50k-token
+          // estimate. Store a compact placeholder.
+          const bytes = part?.data?.length ?? part?.image?.length ?? part?.data?.byteLength;
+          return `[${part?.type ?? "part"}${typeof bytes === "number" ? ` ${bytes}b` : ""}]`;
+        })
         .join("");
     } else {
       content = JSON.stringify(m.content);
     }
-    return { role: String(m.role), content };
+    return { role: String(m.role), content: capContent(content) };
   });
 }
 
@@ -781,7 +801,7 @@ export class AIBudget {
               }));
             const tapped = result.stream.pipeThrough(
               new TransformStream({
-                async transform(chunk: any, controller) {
+                async transform(chunk: any, controller: any) {
                   if (chunk?.type === "text-delta") {
                     text += chunk.delta ?? chunk.textDelta ?? "";
                   }
@@ -797,7 +817,22 @@ export class AIBudget {
                 async flush() {
                   await settle();
                 },
-              })
+                // A cancelled/aborted stream (client disconnect, AbortSignal, or
+                // breaking out of `for await`) does NOT run `flush`. Without this
+                // the request would sit pending until the 30-min reservation
+                // expiry and be recorded as $0 though the provider charged for
+                // what streamed. Settle here with the text so far, estimating the
+                // completion tokens when the provider gave no usage.
+                // `cancel` is a newer Streams-spec transformer hook not yet in
+                // the TS DOM lib types; cast the literal so it compiles (runtimes
+                // without it simply won't call it, and the reconciler backstops).
+                async cancel(reason: any) {
+                  if (usage === undefined && text) {
+                    usage = { outputTokens: Math.ceil(text.length / 4) };
+                  }
+                  await settle(`cancelled: ${String(reason)}`);
+                },
+              } as any)
             );
             return { ...result, stream: tapped };
           } catch (e) {

package/src/component/_generated/component.ts

@@ -185,9 +185,9 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "mutation",
         "internal",
         {
-          dailySpendLimitNanos?: number;
-          enforcement?: "hard" | "soft";
-          lifetimeSpendLimitNanos?: number;
+          dailySpendLimitNanos?: number | null;
+          enforcement?: "hard" | "soft" | null;
+          lifetimeSpendLimitNanos?: number | null;
         },
         null,
         Name

package/src/component/lib.test.ts

@@ -554,8 +554,9 @@ describe("F-04 fail-closed pricing", () => {
     expect(r.allowed).toBe(true);
     await settle(t, r.requestId, 1_000_000, 1_000_000);
     const u = await userOf(t, "u");
-    // conservative = max over table = {$3 in, $15 out}/Mtok => $18 = 18e9 nano.
-    expect(u.totalSpendNanos).toBe(18_000_000_000);
+    // Conservative fallback is a frontier ceiling of {$20 in, $100 out}/Mtok, so
+    // 1M in + 1M out => $120 = 120e9 nano (over-count is the safe direction).
+    expect(u.totalSpendNanos).toBe(120_000_000_000);
     const req = (await t.query(api.lib.getRequest, { requestId: r.requestId }))!;
     expect(req.unpricedModel).toBe(true);
   });
@@ -598,7 +599,7 @@ describe("accounting lifecycle regressions", () => {
       await setUserLimits(t, "u", { dailySpendLimitNanos: 1000 });
       const job = await start(t, { userId: "u", estimatedCostNanos: 100 });
       vi.advanceTimersByTime(2 * 60 * 60_000);
-      await t.mutation(internal.lib.reconcile, {});
+      await t.mutation(internal.lib.expirePhase, {});
       expect((await userOf(t, "u")).reservedTotalNanos).toBe(0);
       await start(t, { userId: "u", estimatedCostNanos: 100 });
       await t.mutation(api.lib.finishRequest, { requestId: job.requestId, costNanos: 75 });
@@ -625,7 +626,7 @@ describe("accounting lifecycle regressions", () => {
       });
       const short = await start(t, { userId: "short" });
       vi.advanceTimersByTime(31 * 60_000);
-      const result = await t.mutation(internal.lib.reconcile, {});
+      const result = await t.mutation(internal.lib.expirePhase, {});
       expect(result.expired).toBe(1);
       expect((await t.run(ctx => ctx.db.get(short.requestId))).reservationExpired).toBe(true);
     } finally { vi.useRealTimers(); }
@@ -664,9 +665,11 @@ test("legacy pending rows acquire deadlines without starving newer expired work"
     });
     const job = await start(t, { userId: "new" });
     vi.advanceTimersByTime(31 * 60_000);
-    expect((await t.mutation(internal.lib.reconcile, {})).expired).toBe(1);
+    expect((await t.mutation(internal.lib.expirePhase, {})).expired).toBe(1);
     expect((await t.run(ctx => ctx.db.get(job.requestId))).reservationExpired).toBe(true);
-    await t.mutation(internal.lib.reconcile, {});
+    // The phase self-reschedules to backfill the remaining legacy rows in
+    // batches; drain those scheduled continuations.
+    await t.finishAllScheduledFunctions(vi.runAllTimers);
     expect(await t.run(ctx => ctx.db.query("requests").withIndex("status_expires", q =>
       q.eq("status", "pending").eq("expiresAt", undefined)).take(1))).toHaveLength(0);
   } finally { vi.useRealTimers(); }
@@ -685,7 +688,7 @@ test("retention progresses past unresolved jobs", async () => {
     await t.mutation(api.lib.finishRequest, { requestId: job.requestId, costNanos: 0 });
     await t.mutation(internal.lib.foldTotals, { requestId: job.requestId });
     vi.advanceTimersByTime(2 * 60 * 60_000);
-    expect((await t.mutation(internal.lib.reconcile, {})).purged).toBe(1);
+    expect((await t.mutation(internal.lib.retentionPhase, {})).purged).toBe(1);
     expect(await t.run(ctx => ctx.db.get(job.requestId))).toBeNull();
   } finally { vi.useRealTimers(); }
 });
@@ -791,3 +794,53 @@ describe("v1 hardening", () => {
     ).rejects.toThrow(/dailySpendLimitNanos/);
   });
 });
+
+describe("v1 hardening (round 2)", () => {
+  test("a non-finite estimatedCostNanos is rejected before it can poison a bucket", async () => {
+    const t = initTest();
+    for (const estimatedCostNanos of [Infinity, NaN, -1]) {
+      await expect(
+        start(t, { userId: "u", estimatedCostNanos })
+      ).rejects.toThrow(/estimatedCostNanos/);
+    }
+  });
+
+  test("a settle with no cost signal falls back to the reserved estimate, not $0", async () => {
+    const t = initTest();
+    // $2 reserved up front (e.g. a video job).
+    const r = await start(t, { userId: "u", estimatedCostNanos: 2_000_000_000 });
+    // Settle with an unpriced server tool and no tokens/authoritative cost.
+    const out = await t.mutation(api.lib.finishRequest, {
+      requestId: r.requestId,
+      serverToolUses: { video_seconds: 8 }, // no configured price
+    });
+    expect(out.costNanos).toBe(2_000_000_000); // NOT 0
+    vi.useFakeTimers();
+    await t.finishAllScheduledFunctions(vi.runAllTimers);
+    vi.useRealTimers();
+    const u = await userOf(t, "u");
+    expect(u.totalSpendNanos).toBe(2_000_000_000);
+  });
+});
+
+describe("v1 hardening (round 3): reconcile phases", () => {
+  test("expired tombstones are deleted after the late-settle horizon", async () => {
+    vi.useFakeTimers();
+    try {
+      const t = initTest();
+      const job = await start(t, { userId: "u", estimatedCostNanos: 100 });
+      vi.advanceTimersByTime(31 * 60_000);
+      // Expire it into a billing tombstone (reservationExpired + settled).
+      await t.mutation(internal.lib.expirePhase, {});
+      // Within the 7-day late-settle horizon: retention keeps the tombstone.
+      await t.mutation(internal.lib.retentionPhase, {});
+      expect(await t.run((ctx) => ctx.db.get(job.requestId))).not.toBeNull();
+      // Past the horizon: the tombstone is deleted so they can't accumulate.
+      vi.advanceTimersByTime(8 * 24 * 60 * 60_000);
+      await t.mutation(internal.lib.retentionPhase, {});
+      expect(await t.run((ctx) => ctx.db.get(job.requestId))).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/component/lib.ts

@@ -46,6 +46,10 @@ function assertFraction(n: number | undefined, name: string) {
 // mapping NaN/Infinity/garbage to 0 rather than poisoning downstream totals.
 const safeCount = (n: number | undefined) =>
   Number.isFinite(n) ? Math.max(0, Math.floor(n as number)) : 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 | undefined) => (Number.isFinite(n) ? (n as number) : 0);
 
 // Built-in attribution dimensions. `user` and `action` are always populated
 // from a request's userId/actionName; apps can add any other dimensions
@@ -103,6 +107,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"
@@ -118,12 +132,17 @@ 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: MutationCtx, model: string) {
@@ -500,6 +519,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
@@ -830,13 +854,21 @@ export const finishRequest = mutation({
       costNanos = Math.round(args.costNanos);
     } else {
       const settings = await getSettings(ctx);
-      costNanos =
+      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
@@ -879,13 +911,13 @@ async function releaseReservation(ctx: MutationCtx, req: Doc<"requests">) {
     const b = await getBucketDoc(ctx, t.dimension, t.value);
     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 });
@@ -943,29 +975,52 @@ 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);
+      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);
+      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, {
@@ -973,37 +1028,58 @@ export const reconcile = internalMutation({
         reservationExpired: true, expiresAt: undefined, settled: true,
       });
     }
-    const expired = candidates.length;
+    if (legacy.length === RECONCILE_BATCH || candidates.length === RECONCILE_BATCH)
+      await ctx.scheduler.runAfter(0, internal.lib.expirePhase, {});
+    return { expired: candidates.length };
+  },
+});
 
-    // Retention: delete terminal, fully-accounted request rows past the window.
+// 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: Doc<"requests">[]) => {
+      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] as const) {
+      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 };
   },
 });