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

package/src/component/lib.ts

@@ -46,6 +46,10 @@ function assertFraction(n: number | undefined, name: string) {
 // mapping NaN/Infinity/garbage to 0 rather than poisoning downstream totals.
 const safeCount = (n: number | undefined) =>
   Number.isFinite(n) ? Math.max(0, Math.floor(n as number)) : 0;
+// Treat a non-finite stored accounting field as 0, so a bucket that was poisoned
+// before validation existed self-heals on its next reserve/release instead of
+// staying NaN forever.
+const fin = (n: number | undefined) => (Number.isFinite(n) ? (n as number) : 0);
 
 // Built-in attribution dimensions. `user` and `action` are always populated
 // from a request's userId/actionName; apps can add any other dimensions
@@ -103,6 +107,16 @@ const STALE_PENDING_MS = 30 * 60 * 1000;
 // audit table — and the sensitive content in it — from growing without bound.
 // Override per-deployment via setRetention.
 const DEFAULT_RETENTION_MS = 60 * 60 * 1000; // 1 hour
+// Reconciliation runs as small, independently-rescheduling phases. Keeping the
+// batch small bounds the bytes read per transaction (each request row can carry
+// prompts/responses) so a burst can't push one phase past Convex's 8 MiB / 16k-
+// doc read limit and stall the whole reconciler. A phase that fills its batch
+// reschedules itself immediately, so throughput still scales with backlog.
+const RECONCILE_BATCH = 50;
+// Keep an expired billing tombstone (content already purged) this long so a very
+// late provider charge can still land against it, then delete it. A finish after
+// deletion is a graceful no-op.
+const LATE_SETTLE_HORIZON_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 const dayStamp = () => new Date().toISOString().slice(0, 10); // "2026-09-04"
 const monthStamp = () => new Date().toISOString().slice(0, 7); // "2026-09"
@@ -118,12 +132,17 @@ const CACHE_DISCOUNT = 0.1;
 // bills real money. Charging the conservative max instead keeps the caps honest
 // (over-counting is the safe direction); admins can pin an exact price via
 // setPrice, which also clears the `unpricedModel` flag on future requests.
+// Seed with a true frontier ceiling ($20/$100 per Mtok), not just the max of the
+// small built-in table — otherwise premium models (Opus-class $15/$75, etc.) not
+// in the table would be under-counted several-fold whenever the gateway's
+// authoritative cost isn't available. Over-counting an unpriced model is the safe
+// direction; admins pin the exact rate with setPrice.
 const CONSERVATIVE_PRICE = Object.values(DEFAULT_PRICES).reduce(
   (m, p) => ({
     input: Math.max(m.input, p.input),
     output: Math.max(m.output, p.output),
   }),
-  { input: 0, output: 0 }
+  { input: 20_000_000_000, output: 100_000_000_000 }
 );
 
 async function getPrice(ctx: MutationCtx, model: string) {
@@ -297,7 +316,8 @@ function sanitizeExtraTags(
 function evaluateCaps(o: {
   label: string;
   name: string;
-  enforcement: "hard" | "soft";
+  // "approximate" is the global killswitch mode; it blocks like "hard" here.
+  enforcement: "hard" | "soft" | "approximate";
   warnAtPct?: number;
   estCost: number;
   estTokens: number;
@@ -307,6 +327,10 @@ function evaluateCaps(o: {
   reservedSpendMonth: number;
   totalSpend: number;
   reservedSpendTotal: number;
+  // Manual credits (subtracted from spend so a credit grants headroom).
+  creditsToday?: number;
+  creditsThisMonth?: number;
+  creditsTotal?: number;
   tokensToday: number;
   reservedTokensToday: number;
   tokensThisMonth: number;
@@ -327,9 +351,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 },
@@ -500,7 +524,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
@@ -513,7 +545,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" as const,
           error: reason,
@@ -545,6 +577,7 @@ export const startRequest = mutation({
 
     // 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";
@@ -558,6 +591,14 @@ 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,
@@ -636,6 +677,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,
@@ -671,42 +715,26 @@ 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)
+      (settings.globalTrippedDaily || settings.globalTrippedLifetime)
     ) {
-      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);
+      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
@@ -757,7 +785,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",
@@ -825,18 +853,27 @@ 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: number;
     if (args.costNanos !== undefined && Number.isFinite(args.costNanos) && args.costNanos >= 0) {
       costNanos = Math.round(args.costNanos);
     } else {
-      const settings = await getSettings(ctx);
-      costNanos =
+      const priced =
         settleCost(
           promptTokens,
           cachedTokens,
           completionTokens,
           await getPrice(ctx, request.model)
         ) + serverToolCost(args.serverToolUses, settings?.serverToolPrices);
+      // Fail closed: if the settle carried NO usable cost signal — no tokens and
+      // no priced server-tool fee (an unpriced tool like `video_seconds`, or a
+      // bare settle()) — fall back to the reserved estimate rather than recording
+      // $0. Known-cost calls (image/video/audio) set estimatedCostNanos at
+      // reserve time precisely so this floor is their real cost. A caller that
+      // truly wants $0 passes an explicit authoritative costNanos: 0 above.
+      const noSignal = promptTokens === 0 && completionTokens === 0 && priced === 0;
+      costNanos = noSignal ? (request.estimatedNanos ?? 0) : priced;
     }
 
     // Durable write to the request's OWN row only — uncontended, so it always
@@ -847,7 +884,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,
@@ -879,13 +916,13 @@ async function releaseReservation(ctx: MutationCtx, req: Doc<"requests">) {
     const b = await getBucketDoc(ctx, t.dimension, t.value);
     if (!b || (req.heldBucketIds ? !req.heldBucketIds.includes(b._id) : !needsReserve(b))) continue;
     await ctx.db.patch(b._id, {
-      reservedTodayNanos: Math.max(0, (b.reservedTodayNanos ?? 0) - (b.dayStamp === day ? cost : 0)),
-      reservedMonthNanos: Math.max(0, (b.reservedMonthNanos ?? 0) - (b.monthStamp === month ? cost : 0)),
-      reservedTotalNanos: Math.max(0, (b.reservedTotalNanos ?? 0) - cost),
-      reservedTodayTokens: Math.max(0, (b.reservedTodayTokens ?? 0) - (b.dayStamp === day ? tokens : 0)),
-      reservedMonthTokens: Math.max(0, (b.reservedMonthTokens ?? 0) - (b.monthStamp === month ? tokens : 0)),
-      reservedTotalTokens: Math.max(0, (b.reservedTotalTokens ?? 0) - tokens),
-      pendingCount: Math.max(0, (b.pendingCount ?? 0) - 1),
+      reservedTodayNanos: Math.max(0, fin(b.reservedTodayNanos) - (b.dayStamp === day ? cost : 0)),
+      reservedMonthNanos: Math.max(0, fin(b.reservedMonthNanos) - (b.monthStamp === month ? cost : 0)),
+      reservedTotalNanos: Math.max(0, fin(b.reservedTotalNanos) - cost),
+      reservedTodayTokens: Math.max(0, fin(b.reservedTodayTokens) - (b.dayStamp === day ? tokens : 0)),
+      reservedMonthTokens: Math.max(0, fin(b.reservedMonthTokens) - (b.monthStamp === month ? tokens : 0)),
+      reservedTotalTokens: Math.max(0, fin(b.reservedTotalTokens) - tokens),
+      pendingCount: Math.max(0, fin(b.pendingCount) - 1),
     });
   }
   await ctx.db.patch(req._id, { reservationReleased: true });
@@ -943,29 +980,98 @@ 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: number, cap?: number) =>
+      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);
+      q.eq("status", "pending").eq("expiresAt", undefined)).take(RECONCILE_BATCH);
     for (const req of legacy) {
       await ctx.db.patch(req._id, { expiresAt: req._creationTime + Math.max(STALE_PENDING_MS, req.reserveTtlMs ?? 0) });
     }
     const candidates = await ctx.db.query("requests").withIndex("status_expires", q =>
-      q.eq("status", "pending").gt("expiresAt", 0).lte("expiresAt", Date.now())).take(200);
+      q.eq("status", "pending").gt("expiresAt", 0).lte("expiresAt", Date.now())).take(RECONCILE_BATCH);
     for (const req of candidates) {
       await releaseReservation(ctx, req);
       await ctx.db.patch(req._id, {
@@ -973,37 +1079,58 @@ export const reconcile = internalMutation({
         reservationExpired: true, expiresAt: undefined, settled: true,
       });
     }
-    const expired = candidates.length;
+    if (legacy.length === RECONCILE_BATCH || candidates.length === RECONCILE_BATCH)
+      await ctx.scheduler.runAfter(0, internal.lib.expirePhase, {});
+    return { expired: candidates.length };
+  },
+});
 
-    // Retention: delete terminal, fully-accounted request rows past the window.
+// Delete terminal, fully-accounted request rows past the retention window; purge
+// content from expired tombstones; and finally delete tombstones past the
+// late-settle horizon so they can't accumulate forever.
+export const retentionPhase = internalMutation({
+  args: {},
+  returns: v.object({ purged: v.number() }),
+  handler: async (ctx) => {
     const settings = await getSettings(ctx);
     const retentionMs = settings?.retentionMs ?? DEFAULT_RETENTION_MS;
+    if (retentionMs <= 0) return { purged: 0 };
+    const retentionCutoff = Date.now() - retentionMs;
     let purged = 0;
-    if (retentionMs > 0) {
-      const retentionCutoff = Date.now() - retentionMs;
-      // Query eligible states directly. Long-lived pending jobs and expired
-      // billing tombstones must not repeatedly occupy the front of a scan.
-      const old = [];
-      for (const expiredFlag of [undefined, false]) {
-        old.push(...await ctx.db.query("requests").withIndex("retention", q =>
-          q.eq("reservationExpired", expiredFlag).eq("settled", true)
-            .lt("_creationTime", retentionCutoff)).take(200));
-      }
-      old.push(...await ctx.db.query("requests").withIndex("status", q =>
-        q.eq("status", "blocked").lt("_creationTime", retentionCutoff)).take(100));
-      for (const req of old) {
+    let more = false;
+    const sweep = async (rows: Doc<"requests">[]) => {
+      for (const req of rows) {
         await deleteRequestTags(ctx, req._id);
         await ctx.db.delete(req._id);
         purged++;
       }
-      const expiredContent = await ctx.db.query("requests").withIndex("expired_content", q =>
-        q.eq("reservationExpired", true).eq("contentPurged", undefined)
-          .lt("_creationTime", retentionCutoff)).take(200);
-      for (const req of expiredContent) {
-        await ctx.db.patch(req._id, { messages: [], responseText: undefined, contentPurged: true });
-      }
+      if (rows.length === RECONCILE_BATCH) more = true;
+    };
+    // Settled, non-expired terminal rows past the window.
+    for (const expiredFlag of [undefined, false] as const) {
+      await sweep(await ctx.db.query("requests").withIndex("retention", q =>
+        q.eq("reservationExpired", expiredFlag).eq("settled", true)
+          .lt("_creationTime", retentionCutoff)).take(RECONCILE_BATCH));
     }
-    return { folded: toFold.length, expired, purged };
+    // 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 });
+    }
+    if (expiredContent.length === RECONCILE_BATCH) more = true;
+    if (more) await ctx.scheduler.runAfter(0, internal.lib.retentionPhase, {});
+    return { purged };
   },
 });
 
@@ -1226,15 +1353,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
@@ -1243,8 +1380,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;
   },
 });
@@ -1291,6 +1430,28 @@ export const setAlertDefaults = mutation({
   },
 });
 
+// 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: Record<string, unknown> = {};
+    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.
@@ -1372,7 +1533,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)
@@ -1387,7 +1548,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,
@@ -1405,7 +1566,7 @@ export const setGlobalLimits = mutation({
     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())
+      v.union(v.literal("approximate"), v.literal("soft"), v.null())
     ),
   },
   returns: v.null(),

package/src/component/schema.ts

@@ -59,10 +59,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(),
@@ -211,12 +218,23 @@ export default defineSchema({
     // killswitch; per-bucket concurrent admission is atomic via reserve/settle.
     globalDailySpendLimitNanos: v.optional(v.number()),
     globalLifetimeSpendLimitNanos: v.optional(v.number()),
+    // "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("hard"), v.literal("soft"))
+      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
@@ -225,5 +243,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"]),
 });