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

package/README.md

@@ -251,7 +251,10 @@ await ai.meter(ctx,
   });
 ```
 
-### `ai.decisions` — structured decisions (Jev)
+### `ai.decisions` — structured decisions (Jev) · **experimental**
+
+> **Experimental** — the Decisions endpoint is alpha on the gateway; this API may
+> change without a major version bump.
 
 Budget the gateway's Decisions endpoint ([Jev](https://docs.typesafe.ai)) — typed
 `choice` / `score` / `boolean` questions evaluated against a `state` — with the
@@ -280,7 +283,10 @@ defaults to `defaultEvalModel` (`"typesafe/jev-1.13"`). Requires
 `experimental_evaluate` — both imported lazily, so callers who don't use
 `decisions` are unaffected.
 
-### `ai.begin` / `ai.settle` — long async jobs (video)
+### `ai.begin` / `ai.settle` — long async jobs (video) · **experimental**
+
+> **Experimental** — video generation depends on alpha gateway features; the
+> async surface (`reserveTtlMs`, `registerWebhook`) may change without a major bump.
 
 A video job is submit → wait minutes → poll/webhook → done, spanning multiple
 Convex functions, so the synchronous `meter` bracket doesn't fit. Reserve with
@@ -432,8 +438,11 @@ await ai.users.adjust(ctx, { userId, deltaNanos: -5 * 1_000_000_000, reason: "go
 await ai.users.adjustments(ctx, { userId });   // the audit log
 ```
 
-Negative = credit, positive = extra charge; it adjusts the live day/month/lifetime
-windows, the history, and an audit log.
+Positive = an extra charge (adds to **gross** spend). Negative = a credit/refund,
+which accrues in a **separate** credits balance and never reduces gross spend — so
+gross spend and durable history stay consistent. Caps enforce on **net = gross −
+credits**, so a credit gives the bucket real headroom. Both are written to the
+audit log.
 
 ### Alerts
 
@@ -490,9 +499,12 @@ ai.requests.get(ctx, { requestId })                               // one request
 ### Global cap
 
 ```ts
+// enforcement: "approximate" (default, best-effort block) | "soft" (warn only).
+// Pass null to clear a field; only the fields you pass change.
 ai.global.setLimits(ctx, { dailySpendLimitNanos?, lifetimeSpendLimitNanos?, enforcement? })
-ai.global.status(ctx)   // { limits, spentTodayNanos, spentTotalNanos, … }
+ai.global.status(ctx)   // { dailySpendLimitNanos, lifetimeSpendLimitNanos, enforcement, spentTodayNanos, spentTotalNanos, … }
 ai.global.bump(ctx, { dailyNanos?, lifetimeNanos? })
+ai.global.setPolicy(ctx, { allowUnpricedModels?, storeContent? })  // deployment data/pricing policy
 ```
 
 A best-effort killswitch across everything. Backed by a sharded counter for
@@ -755,6 +767,31 @@ metadata use their creation period and current capped buckets as a compatibility
 fallback. Exact historical hold ownership cannot be reconstructed if those caps
 changed before the upgrade. New requests always store explicit ownership.
 
+## Stability (v1)
+
+**Stable (frozen for 1.0)** — these keep backward compatibility within the 1.x line:
+`ai.chat`, `ai.meter`, `ai.begin`/`ai.settle`, `ai.languageModel`, and the admin
+namespaces `ai.users` / `ai.actions` / `ai.tag` / `ai.global` / `ai.models` /
+`ai.prices` / `ai.requests`, plus `ai.registerRoutes`. The stored schema is frozen;
+new fields will only be added as optional.
+
+**Experimental (may change without a major bump):** `ai.decisions` (the Jev /
+Decisions endpoint) and video generation (`begin`/`settle` with `reserveTtlMs` +
+`registerWebhook`). Both depend on gateway features that are still alpha.
+
+**Semantics worth knowing:**
+- **Spend caps** admit on an *estimate*, so a token-priced cap can be exceeded by
+  one request's estimate-vs-actual delta; pass `estimatedCostNanos` for an exact
+  reservation. The **global cap** is a best-effort killswitch (`enforcement:
+  "approximate"` | `"soft"`), not a to-the-dollar ceiling.
+- **Credits** (`ai.tag(d).adjust` / negative `deltaNanos`) accrue in a separate
+  balance and never reduce gross spend; caps enforce on **net = gross − credits**,
+  so a credit grants real headroom while spend history stays consistent.
+- **Deployment policy** (`ai.global.setPolicy`): `allowUnpricedModels: false`
+  rejects models with no configured price under hard enforcement (default charges
+  the conservative fallback); `storeContent: false` persists metadata but no
+  prompt/response content (for teams that want zero prompt retention).
+
 ## Development
 
 ```sh

package/dist/client/index.d.ts

@@ -495,6 +495,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -536,6 +539,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -632,6 +638,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -673,6 +682,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -768,6 +780,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -809,6 +824,9 @@ export declare class AIBudget {
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
             bumpMonthStamp?: string | undefined;
+            creditsNanos?: number | undefined;
+            creditsTodayNanos?: number | undefined;
+            creditsThisMonthNanos?: number | undefined;
             tokensToday?: number | undefined;
             monthStamp?: string | undefined;
             tokensThisMonth?: number | undefined;
@@ -886,17 +904,21 @@ export declare class AIBudget {
         status: (ctx: RunQueryCtx) => Promise<{
             dailySpendLimitNanos: number | null;
             lifetimeSpendLimitNanos: number | null;
-            enforcement: "hard" | "soft";
+            enforcement: "soft" | "approximate";
             spentTodayNanos: number;
             spentTotalNanos: number;
             retentionMs: number | null;
             defaultWarnAtPct: number | null;
         }>;
-        /** A killswitch spend cap across all users/actions (enforced approximately). */
+        /**
+         * A killswitch spend cap across all users/actions. Enforced
+         * **approximately** (bounded overshoot, no per-request reservation) — for
+         * an exact ceiling use a per-bucket cap. Pass `null` to clear a field.
+         */
         setLimits: (ctx: RunMutationCtx, args: {
-            dailySpendLimitNanos?: number;
-            lifetimeSpendLimitNanos?: number;
-            enforcement?: "hard" | "soft";
+            dailySpendLimitNanos?: number | null;
+            lifetimeSpendLimitNanos?: number | null;
+            enforcement?: "approximate" | "soft" | null;
         }) => Promise<null>;
         bump: (ctx: RunMutationCtx, args: {
             dailyNanos?: number;
@@ -910,6 +932,17 @@ export declare class AIBudget {
         setRetention: (ctx: RunMutationCtx, args: {
             retentionMs: number;
         }) => Promise<null>;
+        /**
+         * Deployment-wide data/pricing policy (only the fields you pass change):
+         * - `allowUnpricedModels: false` rejects models with no configured price
+         *   under hard enforcement (default true — charge the conservative fallback).
+         * - `storeContent: false` stops persisting prompt/response content on
+         *   request rows (default true).
+         */
+        setPolicy: (ctx: RunMutationCtx, args: {
+            allowUnpricedModels?: boolean;
+            storeContent?: boolean;
+        }) => Promise<null>;
     };
     /** Model allow/deny policy. */
     get models(): {

package/dist/client/index.js

@@ -648,13 +648,25 @@ export class AIBudget {
         return {
             /** Limits + spend today/total. */
             status: (ctx) => ctx.runQuery(c.lib.getGlobalStatus, {}),
-            /** A killswitch spend cap across all users/actions (enforced approximately). */
+            /**
+             * A killswitch spend cap across all users/actions. Enforced
+             * **approximately** (bounded overshoot, no per-request reservation) — for
+             * an exact ceiling use a per-bucket cap. Pass `null` to clear a field.
+             */
             setLimits: (ctx, args) => ctx.runMutation(c.lib.setGlobalLimits, args),
             bump: (ctx, args) => ctx.runMutation(c.lib.bumpGlobal, args),
             /** Default approaching-limit alert threshold (fraction of a cap, e.g. 0.8). */
             setAlertDefaults: (ctx, args) => ctx.runMutation(c.lib.setAlertDefaults, args),
             /** Request-row retention window in ms (default 1h; 0 disables). */
             setRetention: (ctx, args) => ctx.runMutation(c.lib.setRetention, args),
+            /**
+             * 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).
+             */
+            setPolicy: (ctx, args) => ctx.runMutation(c.lib.setDeploymentPolicy, args),
         };
     }
     /** Model allow/deny policy. */

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

@@ -66,7 +66,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         getGlobalStatus: FunctionReference<"query", "internal", {}, {
             dailySpendLimitNanos: number | null;
             defaultWarnAtPct: number | null;
-            enforcement: "hard" | "soft";
+            enforcement: "approximate" | "soft";
             lifetimeSpendLimitNanos: number | null;
             retentionMs: number | null;
             spentTodayNanos: number;
@@ -116,9 +116,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             value: string;
             warnAtPct?: number;
         }, null, Name>;
+        setDeploymentPolicy: FunctionReference<"mutation", "internal", {
+            allowUnpricedModels?: boolean;
+            storeContent?: boolean;
+        }, null, Name>;
         setGlobalLimits: FunctionReference<"mutation", "internal", {
             dailySpendLimitNanos?: number | null;
-            enforcement?: "hard" | "soft" | null;
+            enforcement?: "approximate" | "soft" | null;
             lifetimeSpendLimitNanos?: number | null;
         }, null, Name>;
         setModelPolicy: FunctionReference<"mutation", "internal", {

package/dist/component/lib.d.ts

@@ -40,6 +40,7 @@ export declare const foldTotals: import("convex/server").RegisteredMutation<"int
     requestId: import("convex/values").GenericId<"requests">;
 }, Promise<null>>;
 export declare const reconcile: import("convex/server").RegisteredMutation<"internal", {}, Promise<null>>;
+export declare const globalPhase: import("convex/server").RegisteredMutation<"internal", {}, Promise<null>>;
 export declare const foldPhase: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
     folded: number;
 }>>;
@@ -242,6 +243,9 @@ export declare const listBuckets: import("convex/server").RegisteredQuery<"publi
     lifetimeBumpNanos?: number | undefined;
     bumpDayStamp?: string | undefined;
     bumpMonthStamp?: string | undefined;
+    creditsNanos?: number | undefined;
+    creditsTodayNanos?: number | undefined;
+    creditsThisMonthNanos?: number | undefined;
     tokensToday?: number | undefined;
     monthStamp?: string | undefined;
     tokensThisMonth?: number | undefined;
@@ -283,6 +287,9 @@ export declare const getBucket: import("convex/server").RegisteredQuery<"public"
     lifetimeBumpNanos?: number | undefined;
     bumpDayStamp?: string | undefined;
     bumpMonthStamp?: string | undefined;
+    creditsNanos?: number | undefined;
+    creditsTodayNanos?: number | undefined;
+    creditsThisMonthNanos?: number | undefined;
     tokensToday?: number | undefined;
     monthStamp?: string | undefined;
     tokensThisMonth?: number | undefined;
@@ -361,6 +368,10 @@ export declare const usageHistory: import("convex/server").RegisteredQuery<"publ
 export declare const setAlertDefaults: import("convex/server").RegisteredMutation<"public", {
     warnAtPct?: number | undefined;
 }, Promise<null>>;
+export declare const setDeploymentPolicy: import("convex/server").RegisteredMutation<"public", {
+    allowUnpricedModels?: boolean | undefined;
+    storeContent?: boolean | undefined;
+}, Promise<null>>;
 export declare const deleteBucket: import("convex/server").RegisteredMutation<"public", {
     dimension: string;
     value: string;
@@ -375,7 +386,7 @@ export declare const getModelPolicy: import("convex/server").RegisteredQuery<"pu
 export declare const getGlobalStatus: import("convex/server").RegisteredQuery<"public", {}, Promise<{
     dailySpendLimitNanos: number | null;
     lifetimeSpendLimitNanos: number | null;
-    enforcement: "hard" | "soft";
+    enforcement: "soft" | "approximate";
     spentTodayNanos: number;
     spentTotalNanos: number;
     retentionMs: number | null;
@@ -384,7 +395,7 @@ export declare const getGlobalStatus: import("convex/server").RegisteredQuery<"p
 export declare const setGlobalLimits: import("convex/server").RegisteredMutation<"public", {
     dailySpendLimitNanos?: number | null | undefined;
     lifetimeSpendLimitNanos?: number | null | undefined;
-    enforcement?: "hard" | "soft" | null | undefined;
+    enforcement?: "soft" | "approximate" | null | undefined;
 }, Promise<null>>;
 export declare const bumpGlobal: import("convex/server").RegisteredMutation<"public", {
     dailyNanos?: number | undefined;

package/dist/component/lib.js

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

package/dist/component/schema.d.ts

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

package/dist/component/schema.js

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

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/ai-budget/issues"
   },
-  "version": "0.0.2-alpha.18",
+  "version": "0.0.2-alpha.19",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [

package/src/client/index.ts

@@ -991,13 +991,17 @@ export class AIBudget {
     return {
       /** Limits + spend today/total. */
       status: (ctx: RunQueryCtx) => ctx.runQuery(c.lib.getGlobalStatus, {}),
-      /** A killswitch spend cap across all users/actions (enforced approximately). */
+      /**
+       * A killswitch spend cap across all users/actions. Enforced
+       * **approximately** (bounded overshoot, no per-request reservation) — for
+       * an exact ceiling use a per-bucket cap. Pass `null` to clear a field.
+       */
       setLimits: (
         ctx: RunMutationCtx,
         args: {
-          dailySpendLimitNanos?: number;
-          lifetimeSpendLimitNanos?: number;
-          enforcement?: "hard" | "soft";
+          dailySpendLimitNanos?: number | null;
+          lifetimeSpendLimitNanos?: number | null;
+          enforcement?: "approximate" | "soft" | null;
         }
       ) => ctx.runMutation(c.lib.setGlobalLimits, args),
       bump: (
@@ -1010,6 +1014,17 @@ export class AIBudget {
       /** Request-row retention window in ms (default 1h; 0 disables). */
       setRetention: (ctx: RunMutationCtx, args: { retentionMs: number }) =>
         ctx.runMutation(c.lib.setRetention, args),
+      /**
+       * 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).
+       */
+      setPolicy: (
+        ctx: RunMutationCtx,
+        args: { allowUnpricedModels?: boolean; storeContent?: boolean }
+      ) => ctx.runMutation(c.lib.setDeploymentPolicy, args),
     };
   }
 

package/src/component/_generated/component.ts

@@ -95,7 +95,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         {
           dailySpendLimitNanos: number | null;
           defaultWarnAtPct: number | null;
-          enforcement: "hard" | "soft";
+          enforcement: "approximate" | "soft";
           lifetimeSpendLimitNanos: number | null;
           retentionMs: number | null;
           spentTodayNanos: number;
@@ -181,12 +181,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         null,
         Name
       >;
+      setDeploymentPolicy: FunctionReference<
+        "mutation",
+        "internal",
+        { allowUnpricedModels?: boolean; storeContent?: boolean },
+        null,
+        Name
+      >;
       setGlobalLimits: FunctionReference<
         "mutation",
         "internal",
         {
           dailySpendLimitNanos?: number | null;
-          enforcement?: "hard" | "soft" | null;
+          enforcement?: "approximate" | "soft" | null;
           lifetimeSpendLimitNanos?: number | null;
         },
         null,

package/src/component/lib.test.ts

@@ -245,7 +245,7 @@ describe("durable usage history", () => {
 });
 
 describe("manual adjustments", () => {
-  test("a credit reduces spend and is logged", async () => {
+  test("a credit accrues separately from gross spend and grants headroom", async () => {
     const t = initTest();
     const r = await start(t, { userId: "u" });
     await settleWith(t, r.requestId, { promptTokens: 1_000_000, completionTokens: 1_000_000 });
@@ -256,11 +256,26 @@ describe("manual adjustments", () => {
       reason: "goodwill credit",
     });
     const u = await userOf(t, "u");
-    expect(u.totalSpendNanos).toBe(500_000_000); // 750M - 250M
+    // Gross spend is unchanged (credits never reduce it); the credit is tracked
+    // separately. Net = gross - credits = 500M.
+    expect(u.totalSpendNanos).toBe(750_000_000);
+    expect(u.creditsNanos).toBe(250_000_000);
     const log = await t.query(api.lib.listAdjustments, { dimension: "user", value: "u" });
     expect(log.length).toBe(1);
     expect(log[0].deltaNanos).toBe(-250_000_000);
   });
+
+  test("a credit grants headroom under a cap; a debit consumes gross spend", async () => {
+    const t = initTest();
+    await setUserLimits(t, "u", { lifetimeSpendLimitNanos: 1_000_000_000 });
+    const r = await start(t, { userId: "u" });
+    await settleWith(t, r.requestId, { costNanos: 900_000_000 }); // $0.90 gross
+    // Right at the edge: a $0.20 estimate would exceed the $1 cap...
+    expect((await start(t, { userId: "u", estimatedCostNanos: 200_000_000 })).allowed).toBe(false);
+    // ...but a $0.30 credit (net spend $0.60) reopens headroom.
+    await t.mutation(api.lib.adjustBucket, { dimension: "user", value: "u", deltaNanos: -300_000_000 });
+    expect((await start(t, { userId: "u", estimatedCostNanos: 200_000_000 })).allowed).toBe(true);
+  });
 });
 
 describe("threshold alerts", () => {
@@ -639,6 +654,11 @@ describe("accounting lifecycle regressions", () => {
     await t.mutation(internal.lib.foldTotals, { requestId: job.requestId });
     expect((await t.query(api.lib.getGlobalStatus, {})).spentTotalNanos).toBe(100);
     await t.mutation(api.lib.setGlobalLimits, { lifetimeSpendLimitNanos: 100 });
+    // The killswitch trips out-of-band (H4): the reconciler's globalPhase
+    // compares the sharded total to the cap and flags settings; admission reads
+    // the flag. So a request admits until the flag is set, then blocks.
+    expect((await start(t, { userId: "u", estimatedCostNanos: 1 })).allowed).toBe(true);
+    await t.mutation(internal.lib.globalPhase, {});
     expect((await start(t, { userId: "u", estimatedCostNanos: 1 })).allowed).toBe(false);
   });
 
@@ -844,3 +864,30 @@ describe("v1 hardening (round 3): reconcile phases", () => {
     }
   });
 });
+
+describe("v1: deployment policy (unpriced models, content storage)", () => {
+  test("blocking unpriced models rejects a model with no configured price", async () => {
+    const t = initTest();
+    await t.mutation(api.lib.setDeploymentPolicy, { allowUnpricedModels: false });
+    const r = await start(t, { userId: "u", model: "made/up-model" });
+    expect(r.allowed).toBe(false);
+    expect(r.code).toBe("model_unpriced");
+    // A priced model still admits.
+    expect((await start(t, { userId: "u", model: MODEL })).allowed).toBe(true);
+  });
+
+  test("storeContent:false keeps metadata but drops prompt/response content", async () => {
+    const t = initTest();
+    await t.mutation(api.lib.setDeploymentPolicy, { storeContent: false });
+    const r = await start(t, { userId: "u" });
+    await settleWith(t, r.requestId, {
+      promptTokens: 10,
+      completionTokens: 5,
+      responseText: "secret answer",
+    });
+    const req = (await t.query(api.lib.getRequest, { requestId: r.requestId }))!;
+    expect(req.messages).toEqual([]); // prompt not stored
+    expect(req.responseText ?? undefined).toBe(undefined); // response not stored
+    expect(req.promptTokens).toBe(10); // metadata/cost still recorded
+  });
+});

package/src/component/lib.ts

@@ -316,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;
@@ -326,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;
@@ -346,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 },
@@ -525,6 +530,9 @@ export const startRequest = mutation({
     // (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
@@ -537,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,
@@ -569,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";
@@ -582,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,
@@ -660,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,
@@ -695,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
@@ -781,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",
@@ -849,11 +853,12 @@ 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);
       const priced =
         settleCost(
           promptTokens,
@@ -879,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,
@@ -986,6 +991,52 @@ export const reconcile = internalMutation({
     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;
   },
 });
@@ -1302,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
@@ -1319,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;
   },
 });
@@ -1367,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.
@@ -1448,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)
@@ -1463,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,
@@ -1481,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"]),
 });