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

package/src/component/lib.ts

@@ -60,7 +60,13 @@ const STALE_PENDING_MS = 30 * 60 * 1000;
 // 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
@@ -85,14 +91,21 @@ async function getPrice(ctx: MutationCtx, model: string) {
     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 };
+  if (known) return { ...known, cached: undefined, known: true };
+  return { ...CONSERVATIVE_PRICE, cached: undefined, known: false };
 }
 
+type Price = { input: number; output: number; cached?: number };
+// The per-Mtok rate for cached (prompt-cache-read) tokens: an explicit override,
+// else a discount off the input rate.
+const cachedRate = (p: Price) =>
+  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 = (
@@ -104,6 +117,66 @@ const costOf = (
     (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: number,
+  cachedTokens: number,
+  completionTokens: number,
+  price: 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: MutationCtx,
+  dimension: string,
+  value: string,
+  period: "day" | "month",
+  stamp: string,
+  spendNanos: number,
+  tokens: number,
+  requests: number
+) {
+  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(
@@ -158,57 +231,76 @@ function sanitizeExtraTags(
 }
 
 // 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: {
   label: string;
   name: string;
   enforcement: "hard" | "soft";
+  warnAtPct?: number;
   estCost: number;
   estTokens: number;
   spendToday: number;
   reservedSpendToday: number;
+  spendThisMonth: number;
+  reservedSpendMonth: number;
   totalSpend: number;
   reservedSpendTotal: number;
   tokensToday: number;
   reservedTokensToday: number;
+  tokensThisMonth: number;
+  reservedTokensMonth: number;
   totalTokens: number;
   reservedTokensTotal: number;
   dailySpendLimitNanos?: number;
+  monthlySpendLimitNanos?: number;
   lifetimeSpendLimitNanos?: number;
   dailyTokenLimit?: number;
+  monthlyTokenLimit?: number;
   lifetimeTokenLimit?: number;
-}): { hard?: { code: string; reason: string }; warnings: string[] } {
+}): {
+  hard?: { code: string; reason: string };
+  warnings: string[];
+  notices: string[];
+} {
+  // { 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: { code: string; reason: string }[] = [];
-  const push = (code: string, reason: string) =>
-    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}"`);
-
-  if (violations.length === 0) return { warnings: [] };
-  if (o.enforcement === "soft") return { warnings: violations.map((v) => v.reason) };
-  return { hard: violations[0], warnings: [] };
+  const notices: string[] = [];
+  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: [], notices };
+  if (o.enforcement === "soft")
+    return { warnings: violations.map((v) => v.reason), notices };
+  return { hard: violations[0], warnings: [], notices };
 }
 
+const cap = (s: string) => 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: number | undefined, bump: number | undefined) =>
@@ -216,15 +308,24 @@ const withBump = (base: number | undefined, bump: number | undefined) =>
 
 const hasAnyCap = (e: {
   dailySpendLimitNanos?: number;
+  monthlySpendLimitNanos?: number;
   lifetimeSpendLimitNanos?: number;
   dailyTokenLimit?: number;
+  monthlyTokenLimit?: number;
   lifetimeTokenLimit?: number;
 }) =>
   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: Parameters<typeof hasAnyCap>[0] & { maxConcurrent?: number }) =>
+  hasAnyCap(e) || e.maxConcurrent !== undefined;
+
 async function getBucketDoc(ctx: MutationCtx, dimension: string, value: string) {
   return await ctx.db
     .query("buckets")
@@ -260,11 +361,22 @@ async function getSettings(ctx: MutationCtx) {
     .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: MutationCtx, requestId: Doc<"requests">["_id"]) {
+  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),
@@ -309,12 +421,15 @@ export const startRequest = mutation({
     };
 
     const today = dayStamp();
+    const month = monthStamp();
     const priceInfo = await getPrice(ctx, args.model);
     const est = estimateUsage(args.messages, priceInfo);
     const warnings: string[] = [];
+    const notices: string[] = [];
 
     // 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 ?? [];
@@ -351,6 +466,19 @@ export const startRequest = mutation({
       }
     }
 
+    // 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)!;
@@ -385,33 +513,45 @@ 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
@@ -433,14 +573,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(
@@ -454,6 +599,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
@@ -462,15 +608,21 @@ 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)) continue;
+      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,
       });
@@ -488,7 +640,16 @@ export const startRequest = mutation({
       ...(priceInfo.known ? {} : { unpricedModel: true }),
       ...(warnings.length > 0 ? { overBudget: true } : {}),
     });
-    return { allowed: true as const, 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 as const, requestId, warnings, notices };
   },
 });
 
@@ -500,6 +661,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() }),
@@ -523,10 +688,17 @@ 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
@@ -562,26 +734,37 @@ async function foldOne(ctx: MutationCtx, req: Doc<"requests"> | null) {
   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
@@ -660,6 +843,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++;
         }
@@ -706,10 +890,19 @@ export const getRequest = query({
 });
 
 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")
@@ -717,6 +910,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 is Doc<"requests"> => r !== null);
+    }
     return await ctx.db.query("requests").order("desc").take(limit);
   },
 });
@@ -738,9 +955,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,
     }));
   },
 });
@@ -751,7 +970,12 @@ export const getBucket = query({
     const b = await getBucketDoc(ctx as any, args.dimension, args.value);
     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,
+    };
   },
 });
 
@@ -762,10 +986,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()),
   },
@@ -780,28 +1008,114 @@ 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.
@@ -817,7 +1131,10 @@ export const deleteBucket = mutation({
         .query("requests")
         .withIndex("userId", (q) => q.eq("userId", value))
         .take(DELETE_BATCH);
-      for (const r of rows) await ctx.db.delete(r._id);
+      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,
@@ -862,6 +1179,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
@@ -874,6 +1194,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,
     };
   },
 });
@@ -953,12 +1275,18 @@ 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
@@ -978,7 +1306,10 @@ export const listPrices = query({
   args: {},
   handler: async (ctx) => {
     const overrides = await ctx.db.query("prices").collect();
-    const merged: Record<string, { input: number; output: number; overridden: boolean }> = {};
+    const merged: Record<
+      string,
+      { input: number; output: number; cached?: number; overridden: boolean }
+    > = {};
     for (const [model, p] of Object.entries(DEFAULT_PRICES)) {
       merged[model] = { ...p, overridden: false };
     }
@@ -986,6 +1317,7 @@ export const listPrices = query({
       merged[o.model] = {
         input: o.inputNanosPerMTok,
         output: o.outputNanosPerMTok,
+        cached: o.cachedNanosPerMTok,
         overridden: true,
       };
     }