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

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")
@@ -235,9 +254,9 @@ function evaluateCaps(o) {
     // { code, projected usage (incl. this estimate), cap, human window label,
     //   whether it's a money cap (formatted as $), spend? for notices }
     const checks = [
-        { w: "daily_spend_limit", used: o.spendToday + o.reservedSpendToday + o.estCost, cap: o.dailySpendLimitNanos, label: "daily spend limit", money: true },
-        { w: "monthly_spend_limit", used: o.spendThisMonth + o.reservedSpendMonth + o.estCost, cap: o.monthlySpendLimitNanos, label: "monthly spend limit", money: true },
-        { w: "lifetime_spend_limit", used: o.totalSpend + o.reservedSpendTotal + o.estCost, cap: o.lifetimeSpendLimitNanos, label: "lifetime spend limit", money: true },
+        { w: "daily_spend_limit", used: o.spendToday + o.reservedSpendToday + o.estCost - (o.creditsToday ?? 0), cap: o.dailySpendLimitNanos, label: "daily spend limit", money: true },
+        { w: "monthly_spend_limit", used: o.spendThisMonth + o.reservedSpendMonth + o.estCost - (o.creditsThisMonth ?? 0), cap: o.monthlySpendLimitNanos, label: "monthly spend limit", money: true },
+        { w: "lifetime_spend_limit", used: o.totalSpend + o.reservedSpendTotal + o.estCost - (o.creditsTotal ?? 0), cap: o.lifetimeSpendLimitNanos, label: "lifetime spend limit", money: true },
         { w: "daily_token_limit", used: o.tokensToday + o.reservedTokensToday + o.estTokens, cap: o.dailyTokenLimit, label: "daily token limit", money: false },
         { w: "monthly_token_limit", used: o.tokensThisMonth + o.reservedTokensMonth + o.estTokens, cap: o.monthlyTokenLimit, label: "monthly token limit", money: false },
         { w: "lifetime_token_limit", used: o.totalTokens + o.reservedTokensTotal + o.estTokens, cap: o.lifetimeTokenLimit, label: "lifetime token limit", money: false },
@@ -379,7 +398,15 @@ 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);
+        // Set from settings below; when false we persist metadata but no prompt
+        // content (a deployment that opts out of storing prompts entirely).
+        let storeContent = true;
         // Record the blocked attempt and return a rejection (throwing would roll
         // back the record). `persist` is false for the high-frequency-by-design
         // rejections (rate limit, blocked user) that a client retries in a tight
@@ -392,7 +419,7 @@ export const startRequest = mutation({
                     actionName: args.actionName,
                     ...(extraTags.length ? { tags: extraTags } : {}),
                     model: args.model,
-                    messages: args.messages,
+                    messages: storeContent ? args.messages : [],
                     rerunOf: args.rerunOf,
                     status: "blocked",
                     error: reason,
@@ -422,6 +449,7 @@ export const startRequest = mutation({
         const notices = [];
         // Model allow/deny policy (component-wide).
         const settings = await getSettings(ctx);
+        storeContent = settings?.storeContent !== false;
         const defaultWarnAtPct = settings?.defaultWarnAtPct;
         if (settings) {
             const mode = settings.modelMode ?? "open";
@@ -432,6 +460,11 @@ export const startRequest = mutation({
             if (mode === "denylist" && list.includes(args.model)) {
                 return reject("model_denied", `Model "${args.model}" is denied`);
             }
+            // Optionally refuse models with no known/override price rather than
+            // charging the conservative fallback (which under-counts premium models).
+            if (settings.allowUnpricedModels === false && !priceInfo.known) {
+                return reject("model_unpriced", `Model "${args.model}" has no configured price; set one with setPrice or allow unpriced models`);
+            }
         }
         // Fetch/create every bucket this request is attributed to (user, action,
         // and any extra tags). Each may carry its own budget.
@@ -492,6 +525,9 @@ export const startRequest = mutation({
                 reservedSpendMonth: sameMonth ? b.reservedMonthNanos ?? 0 : 0,
                 totalSpend: b.totalSpendNanos,
                 reservedSpendTotal: b.reservedTotalNanos ?? 0,
+                creditsToday: sameDay ? b.creditsTodayNanos ?? 0 : 0,
+                creditsThisMonth: sameMonth ? b.creditsThisMonthNanos ?? 0 : 0,
+                creditsTotal: b.creditsNanos ?? 0,
                 tokensToday: sameDay ? b.tokensToday ?? 0 : 0,
                 reservedTokensToday: sameDay ? b.reservedTodayTokens ?? 0 : 0,
                 tokensThisMonth: sameMonth ? b.tokensThisMonth ?? 0 : 0,
@@ -518,35 +554,23 @@ export const startRequest = mutation({
         // throughput. The sum is transactional, but excludes unsettled usage and
         // has no cross-request reservation, so a hard global cap can overshoot. That's the deliberate consistency/throughput
         // trade for a deployment-wide killswitch; it's the only approximate scope.
+        // H4: don't read the sharded counter here — that per-admission read
+        // contended with every fold that writes it. The reconciler compares the
+        // total to the cap out-of-band and records trip flags on `settings`;
+        // admission just reads those (already-loaded) flags. The killswitch lag is
+        // bounded by the reconcile interval, which is the point of "approximate".
         if (settings &&
-            (settings.globalDailySpendLimitNanos !== undefined ||
-                settings.globalLifetimeSpendLimitNanos !== undefined)) {
-            const globalEval = evaluateCaps({
-                label: "global",
-                name: "deployment",
-                enforcement: settings.globalEnforcement ?? "hard",
-                warnAtPct: defaultWarnAtPct,
-                estCost: est.cost,
-                estTokens: est.tokens,
-                spendToday: await globalSpend.count(ctx, globalDayKey(today)),
-                reservedSpendToday: 0, // sharded holder: no cross-request reservation
-                spendThisMonth: 0, // global tracks daily + lifetime only
-                reservedSpendMonth: 0,
-                totalSpend: await globalSpend.count(ctx, GLOBAL_TOTAL),
-                reservedSpendTotal: 0,
-                tokensToday: 0,
-                reservedTokensToday: 0,
-                tokensThisMonth: 0,
-                reservedTokensMonth: 0,
-                totalTokens: 0,
-                reservedTokensTotal: 0,
-                dailySpendLimitNanos: withBump(settings.globalDailySpendLimitNanos, settings.globalBumpDayStamp === today ? settings.globalDailyBumpNanos : 0),
-                lifetimeSpendLimitNanos: withBump(settings.globalLifetimeSpendLimitNanos, settings.globalLifetimeBumpNanos),
-            });
-            if (globalEval.hard)
-                return reject(globalEval.hard.code, globalEval.hard.reason);
-            warnings.push(...globalEval.warnings);
-            notices.push(...globalEval.notices);
+            (settings.globalTrippedDaily || settings.globalTrippedLifetime)) {
+            const enforcement = settings.globalEnforcement ?? "approximate";
+            if (enforcement === "soft") {
+                warnings.push(`Global spend limit reached for the deployment (allowed — soft)`);
+            }
+            else {
+                return reject("global_spend_limit", "Global spend limit reached for the deployment");
+            }
+        }
+        else if (settings?.globalNearLimit) {
+            notices.push("Deployment approaching its global spend limit");
         }
         // Consume only after every admission check succeeds, in the same
         // transaction as the reservations and request insert. `throws: true` is
@@ -596,7 +620,7 @@ export const startRequest = mutation({
             actionName: args.actionName,
             ...(extraTags.length ? { tags: extraTags } : {}),
             model: args.model,
-            messages: args.messages,
+            messages: storeContent ? args.messages : [],
             rerunOf: args.rerunOf,
             ...(args.reserveTtlMs !== undefined ? { reserveTtlMs: args.reserveTtlMs } : {}),
             status: "pending",
@@ -662,14 +686,22 @@ export const finishRequest = mutation({
         // tool fees); otherwise price from tokens — discounting the cached
         // (prompt-cache-read) slice — plus any server-tool per-call fees. Require it
         // finite: +Infinity passes a bare `>= 0` and would corrupt the totals.
+        const settings = await getSettings(ctx);
+        const storeContent = settings?.storeContent !== false;
         let costNanos;
         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
@@ -679,7 +711,7 @@ export const finishRequest = mutation({
             reservationExpired: false,
             expiresAt: undefined,
             finishedAt: Date.now(),
-            responseText: args.responseText,
+            responseText: storeContent ? args.responseText : undefined,
             error: args.error,
             promptTokens,
             completionTokens,
@@ -711,13 +743,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 +805,87 @@ 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, {});
+        await ctx.scheduler.runAfter(0, internal.lib.globalPhase, {});
+        return null;
+    },
+});
+// H4: compute the deployment-wide global-cap trip flags out-of-band so admission
+// never reads the sharded counter on its hot path. One cheap counter read here
+// per interval; admission then consults the flags on `settings`.
+export const globalPhase = internalMutation({
+    args: {},
+    returns: v.null(),
+    handler: async (ctx) => {
+        const s = await getSettings(ctx);
+        if (!s)
+            return null;
+        const hasCap = s.globalDailySpendLimitNanos !== undefined ||
+            s.globalLifetimeSpendLimitNanos !== undefined;
+        if (!hasCap) {
+            // Clear stale flags when no global cap is configured.
+            if (s.globalTrippedDaily || s.globalTrippedLifetime || s.globalNearLimit)
+                await ctx.db.patch(s._id, {
+                    globalTrippedDaily: false,
+                    globalTrippedLifetime: false,
+                    globalNearLimit: false,
+                });
+            return null;
+        }
+        const today = dayStamp();
+        const dailyCap = withBump(s.globalDailySpendLimitNanos, s.globalBumpDayStamp === today ? s.globalDailyBumpNanos : 0);
+        const lifetimeCap = withBump(s.globalLifetimeSpendLimitNanos, s.globalLifetimeBumpNanos);
+        const spentToday = await globalSpend.count(ctx, globalDayKey(today));
+        const spentTotal = await globalSpend.count(ctx, GLOBAL_TOTAL);
+        const pct = s.defaultWarnAtPct;
+        const near = (spent, cap) => cap !== undefined && pct !== undefined && pct > 0 && pct < 1 && spent >= pct * cap;
+        await ctx.db.patch(s._id, {
+            globalTrippedDaily: dailyCap !== undefined && spentToday >= dailyCap,
+            globalTrippedLifetime: lifetimeCap !== undefined && spentTotal >= lifetimeCap,
+            globalNearLimit: near(spentToday, dailyCap) || near(spentTotal, lifetimeCap),
+        });
+        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 +893,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({
@@ -1040,15 +1156,25 @@ export const adjustBucket = mutation({
         const dSame = b.dayStamp === today;
         const mSame = b.monthStamp === month;
         const dt = tokens ?? 0;
+        // Gross-plus-credits ledger: a positive delta is a real extra charge (adds
+        // to GROSS spend); a negative delta is a credit/refund that accrues to a
+        // separate credits balance and NEVER reduces gross spend — so gross spend
+        // and durable history stay consistent, and net = gross - credits. Credits
+        // grant headroom because admission subtracts them from the cap check.
+        const debit = deltaNanos > 0 ? deltaNanos : 0;
+        const credit = deltaNanos < 0 ? -deltaNanos : 0;
         await ctx.db.patch(b._id, {
-            totalSpendNanos: Math.max(0, b.totalSpendNanos + deltaNanos),
+            totalSpendNanos: b.totalSpendNanos + debit,
             totalTokens: Math.max(0, b.totalTokens + dt),
             dayStamp: today,
             monthStamp: month,
-            spendTodayNanos: Math.max(0, (dSame ? b.spendTodayNanos : 0) + deltaNanos),
+            spendTodayNanos: (dSame ? b.spendTodayNanos : 0) + debit,
             tokensToday: Math.max(0, (dSame ? b.tokensToday ?? 0 : 0) + dt),
-            spendThisMonthNanos: Math.max(0, (mSame ? b.spendThisMonthNanos ?? 0 : 0) + deltaNanos),
+            spendThisMonthNanos: (mSame ? b.spendThisMonthNanos ?? 0 : 0) + debit,
             tokensThisMonth: Math.max(0, (mSame ? b.tokensThisMonth ?? 0 : 0) + dt),
+            creditsNanos: (b.creditsNanos ?? 0) + credit,
+            creditsTodayNanos: (dSame ? b.creditsTodayNanos ?? 0 : 0) + credit,
+            creditsThisMonthNanos: (mSame ? b.creditsThisMonthNanos ?? 0 : 0) + credit,
             // 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
@@ -1057,8 +1183,10 @@ export const adjustBucket = mutation({
             ...(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);
-        await addUsage(ctx, dimension, value, "month", month, deltaNanos, dt, 0);
+        // Durable history tracks GROSS spend only (debits); credits live in the
+        // adjustments log + bucket balance, so usage rollups never go negative.
+        await addUsage(ctx, dimension, value, "day", today, debit, dt, 0);
+        await addUsage(ctx, dimension, value, "month", month, debit, dt, 0);
         return null;
     },
 });
@@ -1099,6 +1227,31 @@ export const setAlertDefaults = mutation({
         return null;
     },
 });
+// Deployment-wide data/pricing policy. Only the fields you pass change.
+// - allowUnpricedModels: false rejects models with no configured price under
+//   hard enforcement (default true — charge the conservative fallback).
+// - storeContent: false stops persisting prompt/response content on request
+//   rows (default true).
+export const setDeploymentPolicy = mutation({
+    args: {
+        allowUnpricedModels: v.optional(v.boolean()),
+        storeContent: v.optional(v.boolean()),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const patch = {};
+        if ("allowUnpricedModels" in args)
+            patch.allowUnpricedModels = args.allowUnpricedModels;
+        if ("storeContent" in args)
+            patch.storeContent = args.storeContent;
+        const existing = await getSettings(ctx);
+        if (existing)
+            await ctx.db.patch(existing._id, patch);
+        else
+            await ctx.db.insert("settings", { key: "singleton", ...patch });
+        return null;
+    },
+});
 // Delete a bucket and (for the `user` dimension) all of that user's request
 // rows — e.g. account deletion / GDPR. Deletes requests in bounded batches and
 // self-reschedules so it never exceeds the per-transaction document limit.
@@ -1176,7 +1329,7 @@ export const getGlobalStatus = query({
     returns: v.object({
         dailySpendLimitNanos: v.union(v.number(), v.null()),
         lifetimeSpendLimitNanos: v.union(v.number(), v.null()),
-        enforcement: v.union(v.literal("hard"), v.literal("soft")),
+        enforcement: v.union(v.literal("approximate"), v.literal("soft")),
         spentTodayNanos: v.number(),
         spentTotalNanos: v.number(),
         // deployment-wide config (surfaced for the admin dashboard)
@@ -1191,7 +1344,7 @@ export const getGlobalStatus = query({
         return {
             dailySpendLimitNanos: s?.globalDailySpendLimitNanos ?? null,
             lifetimeSpendLimitNanos: s?.globalLifetimeSpendLimitNanos ?? null,
-            enforcement: s?.globalEnforcement ?? "hard",
+            enforcement: s?.globalEnforcement ?? "approximate",
             spentTodayNanos: await globalSpend.count(ctx, globalDayKey(dayStamp())),
             spentTotalNanos: await globalSpend.count(ctx, GLOBAL_TOTAL),
             retentionMs: s?.retentionMs ?? null,
@@ -1207,7 +1360,7 @@ export const setGlobalLimits = mutation({
         // 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())),
+        enforcement: v.optional(v.union(v.literal("approximate"), v.literal("soft"), v.null())),
     },
     returns: v.null(),
     handler: async (ctx, args) => {

package/dist/component/schema.d.ts

@@ -63,6 +63,9 @@ declare const _default: import("convex/server").SchemaDefinition<{
         lifetimeBumpNanos?: number | undefined;
         bumpDayStamp?: string | undefined;
         bumpMonthStamp?: string | undefined;
+        creditsNanos?: number | undefined;
+        creditsTodayNanos?: number | undefined;
+        creditsThisMonthNanos?: number | undefined;
         tokensToday?: number | undefined;
         monthStamp?: string | undefined;
         spendThisMonthNanos?: number | undefined;
@@ -103,6 +106,9 @@ declare const _default: import("convex/server").SchemaDefinition<{
         totalSpendNanos: import("convex/values").VFloat64<number, "required">;
         totalRequests: import("convex/values").VFloat64<number, "required">;
         totalTokens: import("convex/values").VFloat64<number, "required">;
+        creditsNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        creditsTodayNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        creditsThisMonthNanos: import("convex/values").VFloat64<number | undefined, "optional">;
         dayStamp: import("convex/values").VString<string, "required">;
         spendTodayNanos: import("convex/values").VFloat64<number, "required">;
         tokensToday: import("convex/values").VFloat64<number | undefined, "optional">;
@@ -116,7 +122,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
         reservedMonthTokens: import("convex/values").VFloat64<number | undefined, "optional">;
         reservedTotalTokens: import("convex/values").VFloat64<number | undefined, "optional">;
         pendingCount: import("convex/values").VFloat64<number | undefined, "optional">;
-    }, "required", "dimension" | "value" | "requestsPerMinute" | "maxConcurrent" | "dailySpendLimitNanos" | "monthlySpendLimitNanos" | "lifetimeSpendLimitNanos" | "dailyTokenLimit" | "monthlyTokenLimit" | "lifetimeTokenLimit" | "blocked" | "warnAtPct" | "enforcement" | "dailyBumpNanos" | "monthlyBumpNanos" | "lifetimeBumpNanos" | "bumpDayStamp" | "bumpMonthStamp" | "totalSpendNanos" | "totalRequests" | "totalTokens" | "dayStamp" | "spendTodayNanos" | "tokensToday" | "monthStamp" | "spendThisMonthNanos" | "tokensThisMonth" | "reservedTodayNanos" | "reservedMonthNanos" | "reservedTotalNanos" | "reservedTodayTokens" | "reservedMonthTokens" | "reservedTotalTokens" | "pendingCount">, {
+    }, "required", "dimension" | "value" | "requestsPerMinute" | "maxConcurrent" | "dailySpendLimitNanos" | "monthlySpendLimitNanos" | "lifetimeSpendLimitNanos" | "dailyTokenLimit" | "monthlyTokenLimit" | "lifetimeTokenLimit" | "blocked" | "warnAtPct" | "enforcement" | "dailyBumpNanos" | "monthlyBumpNanos" | "lifetimeBumpNanos" | "bumpDayStamp" | "bumpMonthStamp" | "totalSpendNanos" | "totalRequests" | "totalTokens" | "creditsNanos" | "creditsTodayNanos" | "creditsThisMonthNanos" | "dayStamp" | "spendTodayNanos" | "tokensToday" | "monthStamp" | "spendThisMonthNanos" | "tokensThisMonth" | "reservedTodayNanos" | "reservedMonthNanos" | "reservedTotalNanos" | "reservedTodayTokens" | "reservedMonthTokens" | "reservedTotalTokens" | "pendingCount">, {
         dim_value: ["dimension", "value", "_creationTime"];
         dimension: ["dimension", "_creationTime"];
     }, {}, {}>;
@@ -279,13 +285,18 @@ declare const _default: import("convex/server").SchemaDefinition<{
         models?: string[] | undefined;
         globalDailySpendLimitNanos?: number | undefined;
         globalLifetimeSpendLimitNanos?: number | undefined;
-        globalEnforcement?: "hard" | "soft" | undefined;
+        globalEnforcement?: "soft" | "approximate" | undefined;
         globalDailyBumpNanos?: number | undefined;
         globalLifetimeBumpNanos?: number | undefined;
         globalBumpDayStamp?: string | undefined;
+        globalTrippedDaily?: boolean | undefined;
+        globalTrippedLifetime?: boolean | undefined;
+        globalNearLimit?: boolean | undefined;
         retentionMs?: number | undefined;
         defaultWarnAtPct?: number | undefined;
         serverToolPrices?: Record<string, number> | undefined;
+        allowUnpricedModels?: boolean | undefined;
+        storeContent?: boolean | undefined;
         key: string;
     }, {
         key: import("convex/values").VString<string, "required">;
@@ -293,14 +304,19 @@ declare const _default: import("convex/server").SchemaDefinition<{
         models: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
         globalDailySpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
         globalLifetimeSpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
-        globalEnforcement: import("convex/values").VUnion<"hard" | "soft" | undefined, [import("convex/values").VLiteral<"hard", "required">, import("convex/values").VLiteral<"soft", "required">], "optional", never>;
+        globalEnforcement: import("convex/values").VUnion<"soft" | "approximate" | undefined, [import("convex/values").VLiteral<"approximate", "required">, import("convex/values").VLiteral<"soft", "required">], "optional", never>;
         globalDailyBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
         globalLifetimeBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
         globalBumpDayStamp: import("convex/values").VString<string | undefined, "optional">;
+        globalTrippedDaily: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        globalTrippedLifetime: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        globalNearLimit: import("convex/values").VBoolean<boolean | undefined, "optional">;
         retentionMs: import("convex/values").VFloat64<number | undefined, "optional">;
         defaultWarnAtPct: import("convex/values").VFloat64<number | undefined, "optional">;
         serverToolPrices: import("convex/values").VRecord<Record<string, number> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "optional", string>;
-    }, "required", "key" | "modelMode" | "models" | "globalDailySpendLimitNanos" | "globalLifetimeSpendLimitNanos" | "globalEnforcement" | "globalDailyBumpNanos" | "globalLifetimeBumpNanos" | "globalBumpDayStamp" | "retentionMs" | "defaultWarnAtPct" | "serverToolPrices" | `serverToolPrices.${string}`>, {
+        allowUnpricedModels: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        storeContent: import("convex/values").VBoolean<boolean | undefined, "optional">;
+    }, "required", "key" | "modelMode" | "models" | "globalDailySpendLimitNanos" | "globalLifetimeSpendLimitNanos" | "globalEnforcement" | "globalDailyBumpNanos" | "globalLifetimeBumpNanos" | "globalBumpDayStamp" | "globalTrippedDaily" | "globalTrippedLifetime" | "globalNearLimit" | "retentionMs" | "defaultWarnAtPct" | "serverToolPrices" | "allowUnpricedModels" | "storeContent" | `serverToolPrices.${string}`>, {
         key: ["key", "_creationTime"];
     }, {}, {}>;
 }, true>;

package/dist/component/schema.js

@@ -56,10 +56,17 @@ export default defineSchema({
         lifetimeBumpNanos: v.optional(v.number()),
         bumpDayStamp: v.optional(v.string()),
         bumpMonthStamp: v.optional(v.string()),
-        // settled totals (from finished requests)
+        // settled GROSS spend (real charges + positive adjustments). Credits never
+        // reduce these — they accrue separately below — so gross spend and durable
+        // history always agree. Cap checks and "net" use (gross - credits).
         totalSpendNanos: v.number(),
         totalRequests: v.number(),
         totalTokens: v.number(),
+        // manual credits (comps/refunds), tracked separately from gross spend and
+        // subtracted at admission so a credit grants real headroom under a cap.
+        creditsNanos: v.optional(v.number()),
+        creditsTodayNanos: v.optional(v.number()),
+        creditsThisMonthNanos: v.optional(v.number()),
         // daily window
         dayStamp: v.string(),
         spendTodayNanos: v.number(),
@@ -191,10 +198,21 @@ export default defineSchema({
         // killswitch; per-bucket concurrent admission is atomic via reserve/settle.
         globalDailySpendLimitNanos: v.optional(v.number()),
         globalLifetimeSpendLimitNanos: v.optional(v.number()),
-        globalEnforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
+        // "approximate" (default): a best-effort killswitch — it blocks once the
+        // sharded total crosses the cap, but with bounded overshoot (no per-request
+        // reservation). "soft": warn only. There is deliberately no "hard": a true
+        // to-the-dollar ceiling is a per-bucket cap.
+        globalEnforcement: v.optional(v.union(v.literal("approximate"), v.literal("soft"))),
         globalDailyBumpNanos: v.optional(v.number()),
         globalLifetimeBumpNanos: v.optional(v.number()),
         globalBumpDayStamp: v.optional(v.string()),
+        // H4: the reconciler compares the sharded global total to the cap and sets
+        // these, so admission reads ONE settings doc instead of the sharded counter
+        // (whose per-admission read contended with every fold). Killswitch lag is
+        // bounded by the reconcile interval — fine for a deployment-wide stop.
+        globalTrippedDaily: v.optional(v.boolean()),
+        globalTrippedLifetime: v.optional(v.boolean()),
+        globalNearLimit: v.optional(v.boolean()),
         // request-row retention window in ms (default 1h); 0 disables sweeping.
         retentionMs: v.optional(v.number()),
         // default approaching-limit alert threshold (fraction of a cap) for buckets
@@ -203,5 +221,13 @@ export default defineSchema({
         // per-call price (nanodollars) overrides for provider server tools, keyed by
         // tool name (e.g. { web_search: 12_000_000 }). Merged over the defaults.
         serverToolPrices: v.optional(v.record(v.string(), v.number())),
+        // When false, reject requests for a model with no known/override price under
+        // hard enforcement (instead of charging the conservative fallback). Default
+        // true (charge the fallback, keep the call working).
+        allowUnpricedModels: v.optional(v.boolean()),
+        // When false, don't persist prompt/response content on request rows (only
+        // metadata + cost). Default true. For teams that want zero prompt retention
+        // rather than short retention.
+        storeContent: v.optional(v.boolean()),
     }).index("key", ["key"]),
 });