@convex-dev/ai-budget 0.0.2-alpha.4 → 0.0.2-alpha.6

package/dist/component/lib.js

@@ -48,7 +48,12 @@ 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
-const dayStamp = () => new Date().toISOString().slice(0, 10);
+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
+// rate. When a model's price has no explicit cachedNanosPerMTok, charge this
+// fraction of its input rate (providers commonly discount ~90%).
+const CACHE_DISCOUNT = 0.1;
 // Conservative fallback for any model not in the price table: the max of every
 // known price dimension. Falling back to 0 would be fail-open — an unpriced
 // model would reserve 0, pass every cap, and log 0¢ while the AI Gateway still
@@ -68,17 +73,62 @@ async function getPrice(ctx, model) {
         return {
             input: override.inputNanosPerMTok,
             output: override.outputNanosPerMTok,
+            cached: override.cachedNanosPerMTok,
             known: true,
         };
     }
     const known = DEFAULT_PRICES[model];
     if (known)
-        return { ...known, known: true };
-    return { ...CONSERVATIVE_PRICE, known: false };
+        return { ...known, cached: undefined, known: true };
+    return { ...CONSERVATIVE_PRICE, cached: undefined, known: false };
 }
+// The per-Mtok rate for cached (prompt-cache-read) tokens: an explicit override,
+// else a discount off the input rate.
+const cachedRate = (p) => p.cached ?? Math.round(p.input * CACHE_DISCOUNT);
 // Integer nanodollars. Divide-before-multiply keeps the intermediate product
 // within 2^53 even for large token counts × large per-Mtok prices.
 const costOf = (inputTokens, outputTokens, price) => Math.round((inputTokens / 1e6) * price.input + (outputTokens / 1e6) * price.output);
+// Cache-aware settle cost: the cached slice of the prompt is billed at the
+// (discounted) cache rate, the rest of the prompt at the input rate, and
+// completions at the output rate. `cachedTokens` is the gateway's real
+// prompt-cache-read count (usage.inputTokenDetails.cacheReadTokens).
+const settleCost = (promptTokens, cachedTokens, completionTokens, price) => {
+    const cached = Math.min(Math.max(0, cachedTokens), Math.max(0, promptTokens));
+    const fresh = Math.max(0, promptTokens - cached);
+    return Math.round((fresh / 1e6) * price.input +
+        (cached / 1e6) * cachedRate(price) +
+        (completionTokens / 1e6) * price.output);
+};
+// Upsert-add a settled amount into the durable per-(bucket, period) usage row.
+// These rows are never swept by request retention, so spend history survives.
+async function addUsage(ctx, dimension, value, period, stamp, spendNanos, tokens, requests) {
+    const existing = await ctx.db
+        .query("usage")
+        .withIndex("bucket_period_stamp", (q) => q
+        .eq("dimension", dimension)
+        .eq("value", value)
+        .eq("period", period)
+        .eq("stamp", stamp))
+        .unique();
+    if (existing) {
+        await ctx.db.patch(existing._id, {
+            spendNanos: existing.spendNanos + spendNanos,
+            tokens: existing.tokens + tokens,
+            requests: existing.requests + requests,
+        });
+    }
+    else {
+        await ctx.db.insert("usage", {
+            dimension,
+            value,
+            period,
+            stamp,
+            spendNanos,
+            tokens,
+            requests,
+        });
+    }
+}
 // Up-front estimate of a request's cost and token count, reserved before the
 // call so concurrent in-flight requests are visible to each other's caps.
 function estimateUsage(messages, price) {
@@ -125,36 +175,56 @@ function sanitizeExtraTags(extra) {
     return out;
 }
 // Evaluate a bucket's spend + token budgets against committed + reserved + this
-// request's estimate. Returns a hard rejection (block) or a list of soft
-// warnings (allow), per the bucket's enforcement.
+// request's estimate. Returns a hard rejection (block), soft warnings (allow),
+// and threshold notices (approaching a cap — see warnAtPct). Each window (daily,
+// monthly, lifetime) × kind (spend, token) is one check.
 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_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 },
+    ];
     const violations = [];
-    const push = (code, reason) => violations.push({ code: `${o.label}_${code}`, reason });
-    if (o.dailySpendLimitNanos !== undefined &&
-        o.spendToday + o.reservedSpendToday + o.estCost > o.dailySpendLimitNanos)
-        push("daily_spend_limit", `Daily spend limit reached for ${o.label} "${o.name}" (${fmtUsd(o.dailySpendLimitNanos)}/day)`);
-    if (o.lifetimeSpendLimitNanos !== undefined &&
-        o.totalSpend + o.reservedSpendTotal + o.estCost > o.lifetimeSpendLimitNanos)
-        push("lifetime_spend_limit", `Lifetime spend limit reached for ${o.label} "${o.name}"`);
-    if (o.dailyTokenLimit !== undefined &&
-        o.tokensToday + o.reservedTokensToday + o.estTokens > o.dailyTokenLimit)
-        push("daily_token_limit", `Daily token limit reached for ${o.label} "${o.name}" (${o.dailyTokenLimit}/day)`);
-    if (o.lifetimeTokenLimit !== undefined &&
-        o.totalTokens + o.reservedTokensTotal + o.estTokens > o.lifetimeTokenLimit)
-        push("lifetime_token_limit", `Lifetime token limit reached for ${o.label} "${o.name}"`);
+    const notices = [];
+    const pct = o.warnAtPct;
+    for (const c of checks) {
+        if (c.cap === undefined)
+            continue;
+        const capStr = c.money ? `${fmtUsd(c.cap)}` : `${c.cap} tokens`;
+        if (c.used > c.cap) {
+            violations.push({
+                code: `${o.label}_${c.w}`,
+                reason: `${cap(c.label)} reached for ${o.label} "${o.name}" (${capStr})`,
+            });
+        }
+        else if (pct !== undefined && pct > 0 && pct < 1 && c.used >= pct * c.cap) {
+            notices.push(`${o.label} "${o.name}" at ${Math.round((c.used / c.cap) * 100)}% of ${c.label} (${capStr})`);
+        }
+    }
     if (violations.length === 0)
-        return { warnings: [] };
+        return { warnings: [], notices };
     if (o.enforcement === "soft")
-        return { warnings: violations.map((v) => v.reason) };
-    return { hard: violations[0], warnings: [] };
+        return { warnings: violations.map((v) => v.reason), notices };
+    return { hard: violations[0], warnings: [], notices };
 }
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 // A cap plus any one-time bump. Returns undefined when there's no base cap
 // (a bump alone never creates a cap).
 const withBump = (base, bump) => base === undefined ? undefined : base + (bump ?? 0);
 const hasAnyCap = (e) => e.dailySpendLimitNanos !== undefined ||
+    e.monthlySpendLimitNanos !== undefined ||
     e.lifetimeSpendLimitNanos !== undefined ||
     e.dailyTokenLimit !== undefined ||
+    e.monthlyTokenLimit !== undefined ||
     e.lifetimeTokenLimit !== undefined;
+// A bucket needs a reservation row-write if it has any spend/token cap OR a
+// concurrency cap (which reads pendingCount, incremented at reserve time).
+const needsReserve = (e) => hasAnyCap(e) || e.maxConcurrent !== undefined;
 async function getBucketDoc(ctx, dimension, value) {
     return await ctx.db
         .query("buckets")
@@ -182,10 +252,21 @@ async function getSettings(ctx) {
         .withIndex("key", (q) => q.eq("key", "singleton"))
         .unique();
 }
+// Delete the reverse-index rows for a request (called when the request row is
+// deleted, so the tag index never outlives the request it points at).
+async function deleteRequestTags(ctx, requestId) {
+    const tags = await ctx.db
+        .query("requestTags")
+        .withIndex("requestId", (q) => q.eq("requestId", requestId))
+        .collect();
+    for (const t of tags)
+        await ctx.db.delete(t._id);
+}
 const vStartResult = v.union(v.object({
     allowed: v.literal(true),
     requestId: v.id("requests"),
-    warnings: v.array(v.string()),
+    warnings: v.array(v.string()), // soft caps exceeded (allowed with a warning)
+    notices: v.array(v.string()), // approaching a cap (warnAtPct threshold)
 }), v.object({
     allowed: v.literal(false),
     code: v.string(),
@@ -226,11 +307,14 @@ export const startRequest = mutation({
             return { allowed: false, code, reason };
         };
         const today = dayStamp();
+        const month = monthStamp();
         const priceInfo = await getPrice(ctx, args.model);
         const est = estimateUsage(args.messages, priceInfo);
         const warnings = [];
+        const notices = [];
         // Model allow/deny policy (component-wide).
         const settings = await getSettings(ctx);
+        const defaultWarnAtPct = settings?.defaultWarnAtPct;
         if (settings) {
             const mode = settings.modelMode ?? "open";
             const list = settings.models ?? [];
@@ -257,6 +341,14 @@ export const startRequest = mutation({
                 return reject(`${b.dimension}_blocked`, `${label} "${b.value}" is blocked`, b.dimension !== USER_DIM);
             }
         }
+        // Concurrency cap: reject when a bucket already has maxConcurrent requests
+        // in flight (pendingCount). A transient limit like rate-limiting, so it
+        // isn't persisted (the caller retries once something settles).
+        for (const b of buckets) {
+            if (b.maxConcurrent !== undefined && (b.pendingCount ?? 0) >= b.maxConcurrent) {
+                return reject(`${b.dimension}_max_concurrent`, `Too many concurrent requests for ${b.dimension} "${b.value}" (max ${b.maxConcurrent})`, false);
+            }
+        }
         // Rate limit is enforced on the `user` dimension (the requests table is
         // indexed by userId, so the 60s window is a bounded index read).
         const userBucket = buckets.find((b) => b.dimension === USER_DIM);
@@ -282,28 +374,37 @@ export const startRequest = mutation({
         // warning instead of a block.
         for (const b of buckets) {
             const sameDay = b.dayStamp === today;
+            const sameMonth = b.monthStamp === month;
             const ev = evaluateCaps({
                 label: b.dimension,
                 name: b.value,
                 enforcement: b.enforcement ?? "hard",
+                warnAtPct: b.warnAtPct ?? defaultWarnAtPct,
                 estCost: est.cost,
                 estTokens: est.tokens,
                 spendToday: sameDay ? b.spendTodayNanos : 0,
                 reservedSpendToday: sameDay ? b.reservedTodayNanos ?? 0 : 0,
+                spendThisMonth: sameMonth ? b.spendThisMonthNanos ?? 0 : 0,
+                reservedSpendMonth: sameMonth ? b.reservedMonthNanos ?? 0 : 0,
                 totalSpend: b.totalSpendNanos,
                 reservedSpendTotal: b.reservedTotalNanos ?? 0,
                 tokensToday: sameDay ? b.tokensToday ?? 0 : 0,
                 reservedTokensToday: sameDay ? b.reservedTodayTokens ?? 0 : 0,
+                tokensThisMonth: sameMonth ? b.tokensThisMonth ?? 0 : 0,
+                reservedTokensMonth: sameMonth ? b.reservedMonthTokens ?? 0 : 0,
                 totalTokens: b.totalTokens,
                 reservedTokensTotal: b.reservedTotalTokens ?? 0,
                 dailySpendLimitNanos: withBump(b.dailySpendLimitNanos, b.bumpDayStamp === today ? b.dailyBumpNanos : 0),
+                monthlySpendLimitNanos: withBump(b.monthlySpendLimitNanos, b.bumpMonthStamp === month ? b.monthlyBumpNanos : 0),
                 lifetimeSpendLimitNanos: withBump(b.lifetimeSpendLimitNanos, b.lifetimeBumpNanos),
                 dailyTokenLimit: b.dailyTokenLimit,
+                monthlyTokenLimit: b.monthlyTokenLimit,
                 lifetimeTokenLimit: b.lifetimeTokenLimit,
             });
             if (ev.hard)
                 return reject(ev.hard.code, ev.hard.reason);
             warnings.push(...ev.warnings);
+            notices.push(...ev.notices);
         }
         // Deployment-wide ("global") spend cap — same reserve-then-settle model and
         // the SAME evaluateCaps logic as the per-bucket caps above, so the guarantee
@@ -322,14 +423,19 @@ export const startRequest = mutation({
                 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),
@@ -338,6 +444,7 @@ export const startRequest = mutation({
             if (globalEval.hard)
                 return reject(globalEval.hard.code, globalEval.hard.reason);
             warnings.push(...globalEval.warnings);
+            notices.push(...globalEval.notices);
         }
         // Passed — reserve, but ONLY on buckets that actually have a cap. Writing an
         // uncapped bucket's row here would serialize every request that shares it
@@ -345,16 +452,22 @@ export const startRequest = mutation({
         // there's no reserved amount to consult. Totals are still accrued later,
         // asynchronously, in foldOne — for every bucket, capped or not.
         for (const b of buckets) {
-            if (!hasAnyCap(b))
+            if (!needsReserve(b))
                 continue;
             const sameDay = b.dayStamp === today;
+            const sameMonth = b.monthStamp === month;
             await ctx.db.patch(b._id, {
                 dayStamp: today,
+                monthStamp: month,
                 spendTodayNanos: sameDay ? b.spendTodayNanos : 0,
                 tokensToday: sameDay ? b.tokensToday ?? 0 : 0,
+                spendThisMonthNanos: sameMonth ? b.spendThisMonthNanos ?? 0 : 0,
+                tokensThisMonth: sameMonth ? b.tokensThisMonth ?? 0 : 0,
                 reservedTodayNanos: (sameDay ? b.reservedTodayNanos ?? 0 : 0) + est.cost,
+                reservedMonthNanos: (sameMonth ? b.reservedMonthNanos ?? 0 : 0) + est.cost,
                 reservedTotalNanos: (b.reservedTotalNanos ?? 0) + est.cost,
                 reservedTodayTokens: (sameDay ? b.reservedTodayTokens ?? 0 : 0) + est.tokens,
+                reservedMonthTokens: (sameMonth ? b.reservedMonthTokens ?? 0 : 0) + est.tokens,
                 reservedTotalTokens: (b.reservedTotalTokens ?? 0) + est.tokens,
                 pendingCount: (b.pendingCount ?? 0) + 1,
             });
@@ -372,7 +485,16 @@ export const startRequest = mutation({
             ...(priceInfo.known ? {} : { unpricedModel: true }),
             ...(warnings.length > 0 ? { overBudget: true } : {}),
         });
-        return { allowed: true, requestId, warnings };
+        // Reverse index so the request log can be filtered by any extra tag
+        // dimension (user/action are already indexed on the requests table).
+        for (const t of extraTags) {
+            await ctx.db.insert("requestTags", {
+                dimension: t.dimension,
+                value: t.value,
+                requestId,
+            });
+        }
+        return { allowed: true, requestId, warnings, notices };
     },
 });
 export const finishRequest = mutation({
@@ -383,6 +505,10 @@ export const finishRequest = mutation({
         promptTokens: v.optional(v.number()),
         completionTokens: v.optional(v.number()),
         cachedTokens: v.optional(v.number()),
+        // Authoritative cost from the gateway, if it ever reports one. When present
+        // it's recorded verbatim (no token-based estimate); when absent we price
+        // from tokens (cache-aware). Wired now so adopting a real cost is one line.
+        costNanos: v.optional(v.number()),
         latencyMs: v.optional(v.number()),
     },
     returns: v.object({ costNanos: v.number() }),
@@ -405,7 +531,11 @@ export const finishRequest = mutation({
         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));
-        const costNanos = Math.max(0, costOf(promptTokens, completionTokens, await getPrice(ctx, request.model)));
+        // Prefer an authoritative gateway cost when supplied; otherwise price from
+        // tokens, discounting the cached (prompt-cache-read) slice of the prompt.
+        const costNanos = args.costNanos !== undefined && args.costNanos >= 0
+            ? Math.round(args.costNanos)
+            : settleCost(promptTokens, cachedTokens, completionTokens, await getPrice(ctx, request.model));
         // 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
         // orphaned in "pending" even if the totals update below fails and retries.
@@ -439,25 +569,36 @@ async function foldOne(ctx, req) {
     const tokens = (req.promptTokens ?? 0) + (req.completionTokens ?? 0);
     const estTokens = req.estimatedTokens ?? 0;
     const today = dayStamp();
+    const month = monthStamp();
     // Accrue into every attributed bucket (user, action, and each tag) — capped
     // or not. Buckets that never held a reservation have their reserved fields
     // clamped at 0 by Math.max, so subtracting an estimate is a harmless no-op.
+    // Also write the durable per-(bucket, day/month) usage rows that survive
+    // request retention, so spend history outlives the raw request log.
     for (const t of requestBuckets(req.userId, req.actionName, req.tags)) {
         const b = await getOrCreateBucket(ctx, t.dimension, t.value);
         const sameDay = b.dayStamp === today;
+        const sameMonth = b.monthStamp === month;
         await ctx.db.patch(b._id, {
             totalSpendNanos: b.totalSpendNanos + actual,
             totalRequests: b.totalRequests + 1,
             totalTokens: b.totalTokens + tokens,
             dayStamp: today,
+            monthStamp: month,
             spendTodayNanos: (sameDay ? b.spendTodayNanos : 0) + actual,
             tokensToday: (sameDay ? b.tokensToday ?? 0 : 0) + tokens,
+            spendThisMonthNanos: (sameMonth ? b.spendThisMonthNanos ?? 0 : 0) + actual,
+            tokensThisMonth: (sameMonth ? b.tokensThisMonth ?? 0 : 0) + tokens,
             reservedTodayNanos: Math.max(0, (sameDay ? b.reservedTodayNanos ?? 0 : 0) - estCost),
+            reservedMonthNanos: Math.max(0, (sameMonth ? b.reservedMonthNanos ?? 0 : 0) - estCost),
             reservedTotalNanos: Math.max(0, (b.reservedTotalNanos ?? 0) - estCost),
             reservedTodayTokens: Math.max(0, (sameDay ? b.reservedTodayTokens ?? 0 : 0) - estTokens),
+            reservedMonthTokens: Math.max(0, (sameMonth ? b.reservedMonthTokens ?? 0 : 0) - estTokens),
             reservedTotalTokens: Math.max(0, (b.reservedTotalTokens ?? 0) - estTokens),
             pendingCount: Math.max(0, (b.pendingCount ?? 0) - 1),
         });
+        await addUsage(ctx, t.dimension, t.value, "day", today, actual, tokens, 1);
+        await addUsage(ctx, t.dimension, t.value, "month", month, actual, tokens, 1);
     }
     // Deployment-wide totals via the sharded counter (only when a global cap is
     // configured — otherwise skip the writes entirely). Distributed across shards,
@@ -526,6 +667,7 @@ export const reconcile = internalMutation({
                 // Only rows that are done and accounted: folded (settled === true) or a
                 // blocked attempt (never needs folding). Never a pending/unfolded row.
                 if (req.settled === true || req.status === "blocked") {
+                    await deleteRequestTags(ctx, req._id);
                     await ctx.db.delete(req._id);
                     purged++;
                 }
@@ -571,10 +713,19 @@ export const getRequest = query({
     handler: async (ctx, args) => ctx.db.get(args.requestId),
 });
 export const listRequests = query({
-    args: { userId: v.optional(v.string()), limit: v.optional(v.number()) },
+    args: {
+        userId: v.optional(v.string()),
+        // Filter by any attribution dimension (user/action indexed on the request;
+        // custom tag dimensions resolved via the requestTags reverse index).
+        dimension: v.optional(v.string()),
+        value: v.optional(v.string()),
+        limit: v.optional(v.number()),
+    },
     handler: async (ctx, args) => {
         const limit = args.limit ?? 50;
-        if (args.userId !== undefined) {
+        const dim = args.dimension;
+        const val = args.value ?? args.userId;
+        if (dim === undefined && args.userId !== undefined) {
             const userId = args.userId;
             return await ctx.db
                 .query("requests")
@@ -582,6 +733,30 @@ export const listRequests = query({
                 .order("desc")
                 .take(limit);
         }
+        if (dim !== undefined && val !== undefined) {
+            if (dim === USER_DIM) {
+                return await ctx.db
+                    .query("requests")
+                    .withIndex("userId", (q) => q.eq("userId", val))
+                    .order("desc")
+                    .take(limit);
+            }
+            if (dim === ACTION_DIM) {
+                return await ctx.db
+                    .query("requests")
+                    .withIndex("actionName", (q) => q.eq("actionName", val))
+                    .order("desc")
+                    .take(limit);
+            }
+            // Custom tag dimension: walk the reverse index, then fetch each request.
+            const tagRows = await ctx.db
+                .query("requestTags")
+                .withIndex("dim_value", (q) => q.eq("dimension", dim).eq("value", val))
+                .order("desc")
+                .take(limit);
+            const rows = await Promise.all(tagRows.map((t) => ctx.db.get(t.requestId)));
+            return rows.filter((r) => r !== null);
+        }
         return await ctx.db.query("requests").order("desc").take(limit);
     },
 });
@@ -600,9 +775,11 @@ export const listBuckets = query({
                 .take(ADMIN_LIST_CAP)
             : await ctx.db.query("buckets").take(ADMIN_LIST_CAP);
         const today = dayStamp();
+        const month = monthStamp();
         return rows.map((b) => ({
             ...b,
             spendTodayNanos: b.dayStamp === today ? b.spendTodayNanos : 0,
+            spendThisMonthNanos: b.monthStamp === month ? b.spendThisMonthNanos ?? 0 : 0,
         }));
     },
 });
@@ -613,7 +790,12 @@ export const getBucket = query({
         if (!b)
             return null;
         const today = dayStamp();
-        return { ...b, spendTodayNanos: b.dayStamp === today ? b.spendTodayNanos : 0 };
+        const month = monthStamp();
+        return {
+            ...b,
+            spendTodayNanos: b.dayStamp === today ? b.spendTodayNanos : 0,
+            spendThisMonthNanos: b.monthStamp === month ? b.spendThisMonthNanos ?? 0 : 0,
+        };
     },
 });
 // Set a bucket's limits/controls. `user` and `action` are just dimensions here;
@@ -623,10 +805,14 @@ export const setBucketLimits = mutation({
         dimension: v.string(),
         value: v.string(),
         requestsPerMinute: v.optional(v.number()),
+        maxConcurrent: v.optional(v.number()),
         dailySpendLimitNanos: v.optional(v.number()),
+        monthlySpendLimitNanos: v.optional(v.number()),
         lifetimeSpendLimitNanos: v.optional(v.number()),
         dailyTokenLimit: v.optional(v.number()),
+        monthlyTokenLimit: v.optional(v.number()),
         lifetimeTokenLimit: v.optional(v.number()),
+        warnAtPct: v.optional(v.number()),
         enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
         blocked: v.optional(v.boolean()),
     },
@@ -640,25 +826,104 @@ export const setBucketLimits = mutation({
 });
 const vBumpArgs = {
     dailyNanos: v.optional(v.number()),
+    monthlyNanos: v.optional(v.number()),
     lifetimeNanos: v.optional(v.number()),
 };
 // One-time "approve another $X" bumps, added on top of a bucket's standing cap
-// without changing it. Daily bumps apply to today only; lifetime bumps persist.
+// without changing it. Daily/monthly bumps apply to the current window only;
+// lifetime bumps persist.
 export const bumpBucket = mutation({
     args: { dimension: v.string(), value: v.string(), ...vBumpArgs },
     returns: v.null(),
-    handler: async (ctx, { dimension, value, dailyNanos, lifetimeNanos }) => {
+    handler: async (ctx, { dimension, value, dailyNanos, monthlyNanos, lifetimeNanos }) => {
         const bucket = await getOrCreateBucket(ctx, dimension, value);
         const today = dayStamp();
+        const month = monthStamp();
         const curDaily = bucket.bumpDayStamp === today ? bucket.dailyBumpNanos ?? 0 : 0;
+        const curMonthly = bucket.bumpMonthStamp === month ? bucket.monthlyBumpNanos ?? 0 : 0;
         await ctx.db.patch(bucket._id, {
             bumpDayStamp: today,
             dailyBumpNanos: curDaily + (dailyNanos ?? 0),
+            bumpMonthStamp: month,
+            monthlyBumpNanos: curMonthly + (monthlyNanos ?? 0),
             lifetimeBumpNanos: (bucket.lifetimeBumpNanos ?? 0) + (lifetimeNanos ?? 0),
         });
         return null;
     },
 });
+// Manually credit or debit a bucket (comp a user, correct an overcharge).
+// Negative deltaNanos = credit/refund, positive = extra charge. Adjusts the
+// live day/month/lifetime windows AND the durable usage history, and records an
+// audit row. Does not touch the global sharded total or reservations.
+export const adjustBucket = mutation({
+    args: {
+        dimension: v.string(),
+        value: v.string(),
+        deltaNanos: v.number(),
+        tokens: v.optional(v.number()),
+        reason: v.optional(v.string()),
+    },
+    returns: v.null(),
+    handler: async (ctx, { dimension, value, deltaNanos, tokens, reason }) => {
+        const b = await getOrCreateBucket(ctx, dimension, value);
+        const today = dayStamp();
+        const month = monthStamp();
+        const dSame = b.dayStamp === today;
+        const mSame = b.monthStamp === month;
+        const dt = tokens ?? 0;
+        await ctx.db.patch(b._id, {
+            totalSpendNanos: Math.max(0, b.totalSpendNanos + deltaNanos),
+            totalTokens: Math.max(0, b.totalTokens + dt),
+            dayStamp: today,
+            monthStamp: month,
+            spendTodayNanos: Math.max(0, (dSame ? b.spendTodayNanos : 0) + deltaNanos),
+            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),
+        });
+        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);
+        return null;
+    },
+});
+export const listAdjustments = query({
+    args: { dimension: v.string(), value: v.string(), limit: v.optional(v.number()) },
+    handler: async (ctx, { dimension, value, limit }) => ctx.db
+        .query("adjustments")
+        .withIndex("dim_value", (q) => q.eq("dimension", dimension).eq("value", value))
+        .order("desc")
+        .take(limit ?? 50),
+});
+// Durable spend history for a bucket: per-day or per-month rows, newest first.
+// Survives request retention.
+export const usageHistory = query({
+    args: {
+        dimension: v.string(),
+        value: v.string(),
+        period: v.union(v.literal("day"), v.literal("month")),
+        limit: v.optional(v.number()),
+    },
+    handler: async (ctx, { dimension, value, period, limit }) => ctx.db
+        .query("usage")
+        .withIndex("bucket_period_stamp", (q) => q.eq("dimension", dimension).eq("value", value).eq("period", period))
+        .order("desc")
+        .take(limit ?? 90),
+});
+// Deployment-wide default threshold for approaching-limit alerts (fraction of a
+// cap, e.g. 0.8). Buckets can override with their own warnAtPct.
+export const setAlertDefaults = mutation({
+    args: { warnAtPct: v.optional(v.number()) },
+    returns: v.null(),
+    handler: async (ctx, { warnAtPct }) => {
+        const existing = await getSettings(ctx);
+        if (existing)
+            await ctx.db.patch(existing._id, { defaultWarnAtPct: warnAtPct });
+        else
+            await ctx.db.insert("settings", { key: "singleton", defaultWarnAtPct: warnAtPct });
+        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.
@@ -674,8 +939,10 @@ export const deleteBucket = mutation({
                 .query("requests")
                 .withIndex("userId", (q) => q.eq("userId", value))
                 .take(DELETE_BATCH);
-            for (const r of rows)
+            for (const r of rows) {
+                await deleteRequestTags(ctx, r._id);
                 await ctx.db.delete(r._id);
+            }
             if (rows.length === DELETE_BATCH) {
                 await ctx.scheduler.runAfter(0, api.lib.deleteBucket, {
                     dimension,
@@ -716,6 +983,9 @@ export const getGlobalStatus = query({
         enforcement: v.union(v.literal("hard"), v.literal("soft")),
         spentTodayNanos: v.number(),
         spentTotalNanos: v.number(),
+        // deployment-wide config (surfaced for the admin dashboard)
+        retentionMs: v.union(v.number(), v.null()),
+        defaultWarnAtPct: v.union(v.number(), v.null()),
     }),
     handler: async (ctx) => {
         const s = await ctx.db
@@ -728,6 +998,8 @@ export const getGlobalStatus = query({
             enforcement: s?.globalEnforcement ?? "hard",
             spentTodayNanos: await globalSpend.count(ctx, globalDayKey(dayStamp())),
             spentTotalNanos: await globalSpend.count(ctx, GLOBAL_TOTAL),
+            retentionMs: s?.retentionMs ?? null,
+            defaultWarnAtPct: s?.defaultWarnAtPct ?? null,
         };
     },
 });
@@ -803,12 +1075,16 @@ export const setPrice = mutation({
         model: v.string(),
         inputNanosPerMTok: v.number(),
         outputNanosPerMTok: v.number(),
+        // optional cache-read rate; if omitted, a default discount off input applies
+        cachedNanosPerMTok: v.optional(v.number()),
     },
     returns: v.null(),
     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) {
+        if (args.inputNanosPerMTok < 0 ||
+            args.outputNanosPerMTok < 0 ||
+            (args.cachedNanosPerMTok ?? 0) < 0) {
             throw new Error("Prices must be non-negative");
         }
         const existing = await ctx.db
@@ -836,6 +1112,7 @@ export const listPrices = query({
             merged[o.model] = {
                 input: o.inputNanosPerMTok,
                 output: o.outputNanosPerMTok,
+                cached: o.cachedNanosPerMTok,
                 overridden: true,
             };
         }