@ultimat3/ai 23.0.0 → 25.0.0

package/src/agent-facts.ts

@@ -9,6 +9,7 @@
 
 import type { AnyAction } from '@ultimat3/action';
 import type { Money } from '@ultimat3/money';
+import type { ModelSource } from './model-resolve';
 
 /** The declared ceilings, flattened so a manifest row is plain JSON. `null` is "not declared". */
 export interface AgentBudgetFact {
@@ -18,7 +19,7 @@ export interface AgentBudgetFact {
 }
 
 export interface AgentFact {
-  /** The export name registration stamped — the same name `.tool()` and `tools/call` answer to. */
+  /** The export name registration stamped — the same name `toolFrom` and `tools/call` answer to. */
   readonly name: string;
   readonly prompt: string;
   readonly promptId: string;
@@ -27,7 +28,13 @@ export interface AgentFact {
    * which agent ran and not which agent it was — the same reason every eval result carries it.
    */
   readonly promptHash: string;
-  readonly model: string;
+  /**
+   * The model a call runs on: the declaration's, its prompt's, then the gateway's `defaultModel`.
+   * `null` when none names one yet — a call in that state is refused (`X_AI_MODEL_UNRESOLVED`).
+   */
+  readonly model: string | null;
+  /** Which of those answered; `gateway` and `null` are as of the gateway installed at read time. */
+  readonly modelFrom: ModelSource | null;
   readonly maxTurns: number;
   readonly maxToolResultChars: number;
   /** Tool names, sorted — the catalogue this agent may call, which is its blast radius. */

package/src/agent-transcript.ts

@@ -5,8 +5,8 @@
  * next message — and a rule split across two call sites is a rule one of them will miss.
  */
 
-import { RESPOND } from './llm';
 import type { AiContentBlock, AiMessage, GenerateResult } from './provider';
+import { RESPOND } from './respond';
 import type { LlmToolCall, LlmToolResult } from './tools';
 
 /**

package/src/agent.ts

@@ -6,8 +6,8 @@
  * ninth kind, and the list is what a reader counts instead of a sentence in one of them that
  * cannot see the rest. A tool-using run is
  * still one server-authoritative operation with an input schema, an output schema and a policy —
- * so this returns an `action`, and inherits `.tool()`, `.openapi()`, `.client()`, `.job()`,
- * `.contract()` and its manifest row without a line here.
+ * so this returns an `action`, and inherits `.openapi()`, `.client()`, `.job()`, `.contract()`,
+ * its MCP tool (`@ultimat3/mcp`'s `toolFrom`) and its manifest row without a line here.
  *
  * It exists because the alternative is a hand-rolled loop outside the framework, and a hand-rolled
  * loop is where the dangerous mistake lives: taking the ACTOR from the model's output. Here the
@@ -31,7 +31,7 @@ import type { AgentFact } from './agent-facts';
 import { registerAgentFact } from './agent-facts';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import type { BudgetLimits } from './budget';
-import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import {
   AgentMaxTurnsError,
   AgentToolUnexposedError,
@@ -40,9 +40,10 @@ import {
   LlmTruncatedError,
 } from './errors';
 import type { LlmBudget } from './llm';
-import { answerAttributes, RESPOND, respondToolFor, structuredOutputOf } from './llm';
+import { answerAttributes } from './llm';
+import { describedModel, type ModelSource, modelForCall } from './model-resolve';
 import type { ModelId } from './models';
-import { DEFAULT_MODEL, moreCapableThan } from './models';
+import { moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type {
   AiMessage,
@@ -53,7 +54,9 @@ import type {
 } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
-import { aiGateway, aiRedactor } from './runtime';
+import type { Respond } from './respond';
+import { RESPOND, respondFor } from './respond';
+import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
 import { asProjectableAction, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
@@ -153,7 +156,7 @@ export function agent<
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
 >(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
-  const respond = respondToolFor(def.output);
+  const respond = respondFor(def.output);
   // At declaration, because the tools are values by then and a run that discovers this at the
   // first request has already been declared, registered and projected as if it worked. Asked of
   // the DECLARATION rather than of the projection: `isMcpExposed` needs no name, and a real
@@ -201,6 +204,16 @@ export function agent<
   return built;
 }
 
+// `null`, not `undefined`, for a row naming no model yet: the row is a published fact, and an
+// absent key reads as a reader that forgot to ask.
+const modelFact = (described: {
+  readonly model: string | undefined;
+  readonly from: ModelSource | undefined;
+}): Pick<AgentFact, 'model' | 'modelFrom'> => ({
+  model: described.model ?? null,
+  modelFrom: described.from ?? null,
+});
+
 function factsOf<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
@@ -211,7 +224,10 @@ function factsOf<
     prompt: def.prompt.ref,
     promptId: def.prompt.id,
     promptHash: def.prompt.hash,
-    model: def.model ?? def.prompt.model ?? DEFAULT_MODEL,
+    // The run's own precedence, so the row names the model a call would use NOW: read when the
+    // facts are, at describe time, like every name in the row. `modelFrom` says which place
+    // answered — `gateway` (or `null`, none yet) depends on the gateway installed at that moment.
+    ...modelFact(describedModel(def.model, def.prompt.model, installedGateway()?.defaultModel)),
     maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
     maxToolResultChars: def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
     tools: [...def.tools.map(toolLabel)].sort(),
@@ -241,13 +257,16 @@ async function run<
   V extends PromptVars,
 >(
   def: AgentDef<TInput, TOutput, V>,
-  respond: LlmTool,
+  respond: Respond,
   adapted: Adapted,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
   const name = prompt.ref;
-  const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
+  // Screened first: a bad declaration is refused whether or not a gateway exists.
+  const limits = limitsOf(def);
+  // The declaration, its prompt, then the gateway's `defaultModel` — the app's three places.
+  const model = modelForCall('agent', name, def.model, prompt.model);
   const vars = await def.vars({ input: args.input, ctx: args.ctx });
   assertNoSecrets(name, vars);
   const redact = aiRedactor();
@@ -267,15 +286,12 @@ async function run<
       'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
     });
 
-    // Screened first, as before: a bad declaration is refused whether or not a gateway exists.
-    const limits = limitsOf(def);
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
-    const ledger = (
-      currentBudget() ??
-      gateway.callLedger?.() ??
-      new BudgetLedger({ limits: {} })
-    ).derive(limits);
+    // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
+    const ledger = (currentBudget() ?? gateway.callLedger(budgetKeysFor(args.ctx.actor))).derive(
+      limits,
+    );
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
@@ -283,7 +299,7 @@ async function run<
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      tools: [...adapted.offered, respond],
+      tools: [...adapted.offered, respond.tool],
       // The caller's own signal, forwarded to the transport. A disconnect has to reach the socket,
       // not just the top of the next turn: a provider call already in flight is the expensive one.
       signal: args.ctx.signal,
@@ -322,14 +338,14 @@ async function run<
           usage: result.usage,
           cost: result.cost,
         });
-        assertAnswerable(result, name);
+        assertAnswerable(result, name, base);
 
         if (requested.length > 0) {
           // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
           // model turn asked for, each entry is an ordinary `action` carrying its own policy and
           // its own `rateLimit`, and a second ceiling here would be a throttle competing with
-          // those. A tool that calls a model still queues on the ledger's root turnstile, so the
-          // budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
+          // those. A tool that calls a model still reserves on the same ledger chain, which
+          // debits before it checks, so the budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
           // in the types or the docs ever said so.
           //
           // Order is by INDEX, not by completion: `Promise.all` resolves positionally and each
@@ -353,7 +369,7 @@ async function run<
           continue;
         }
 
-        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        const parsed = await validateAsync(def.output, respond.read(result));
         if (parsed.issues === undefined) return parsed.value;
         // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
         // turns left by construction — and unlike a tool result, the correction is the message.
@@ -397,12 +413,12 @@ async function observeTurn<
 }
 
 /** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
-function assertAnswerable(result: GenerateResult, name: string): void {
+function assertAnswerable(result: GenerateResult, name: string, request: GenerateRequest): void {
   if (result.stopReason !== 'refusal') return;
   throw new LlmRefusedError({
     prompt: name,
     model: result.model,
-    alternative: moreCapableThan(result.model),
+    alternative: moreCapableThan(result.model, request),
     category: result.stopDetails?.category,
     explanation: result.stopDetails?.explanation,
   });
@@ -420,7 +436,9 @@ function limitsOf<
     ...(budget?.tokensIn === undefined
       ? {}
       : { tokensIn: finiteCount(SUBJECT, 'budget.tokensIn', budget.tokensIn) }),
-    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    ...(budget?.costPerCall === undefined
+      ? {}
+      : { costPerCall: screenedMoney(SUBJECT, 'budget.costPerCall', budget.costPerCall) }),
     // The ledger's `request` scope accumulates across every call made under one ledger, which for
     // a run under `withBudget` is exactly "the whole run".
     ...(budget?.tokensPerRun === undefined

package/src/budget.ts

@@ -10,7 +10,8 @@
 // module-scope `new` threw at EVALUATION in a browser bundle, where the bundler stubs
 // `node:async_hooks` to `{}`, and took every importer of `@ultimat3/ai` with it.
 
-import { asyncContext, finiteCount } from '@ultimat3/core';
+import type { Actor } from '@ultimat3/core';
+import { assert, asyncContext, finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { assertSameCurrency } from '@ultimat3/money';
 import { AiBudgetExceededError } from './errors';
@@ -64,14 +65,59 @@ export function estimateSpend(request: GenerateRequest): SpendEstimate {
   };
 }
 
+/**
+ * What one `take` found. `spent` is the counter as the store read it, BEFORE this take — so a
+ * refusal can say how much was left.
+ */
+export interface BudgetTake {
+  readonly taken: boolean;
+  readonly spent: number;
+}
+
 /** Where cross-request counters live. Swap for Redis in a multi-process deployment. */
 export interface BudgetStore {
   spent(key: string): Promise<number> | number;
   /** `tokens` may be NEGATIVE: releasing a reservation the call never spent is a credit. */
   add(key: string, tokens: number): Promise<void> | void;
+  /**
+   * Add `tokens` to `key` only if the total stays at or under `limit`, in ONE atomic step — a
+   * Redis `EVAL`, a SQL `update … set spent = spent + $2 where key = $1 and spent + $2 <= $3`.
+   * Required, with no default built on `spent` + `add`: that pair is the read-then-write two
+   * concurrent requests both pass, which is the overspend this member exists to close.
+   */
+  take(key: string, tokens: number, limit: number): Promise<BudgetTake> | BudgetTake;
   reset(key?: string): Promise<void> | void;
 }
 
+/**
+ * The store keys a call's identity is counted under: the acting identity (kind and id — one window
+ * per actor, whichever org it acts in) and its org, when it has one. Derived, never taken from a
+ * declaration, so every `llm()`, `agent()` and `hive()` binds the gateway's `actor` / `org` ceilings
+ * to whoever called it. An anonymous caller is one identity: every anonymous call shares its window.
+ */
+export interface BudgetKeys {
+  readonly actorKey?: string;
+  readonly orgKey?: string;
+}
+
+export function budgetKeysFor(actor: Actor): BudgetKeys {
+  const orgId: string | null | undefined = actor.orgId;
+  return {
+    actorKey: `actor:${actor.kind}:${actor.id}`,
+    ...(orgless(orgId) ? {} : { orgKey: `org:${orgId}` }),
+  };
+}
+
+/**
+ * "Inside no org", in all three spellings `orgId` arrives in: it is a value off the wire (a decoded
+ * session row, an app's adapter), so `null` and `''` reach here despite core's
+ * `string | undefined`. Testing `undefined` alone turned the other two into the real keys `org:null`
+ * and `org:` — ONE org window shared by every org-less caller in the deployment. The same predicate
+ * as `@ultimat3/query`'s `cache.ts`, restated because that one is module-private.
+ */
+const orgless = (orgId: string | null | undefined): boolean =>
+  orgId === undefined || orgId === null || orgId === '';
+
 /**
  * What `reserve` debited, so `record` can reconcile it against the provider's real counts and
  * `release` can give it back. Held by the caller rather than the ledger because one ledger serves
@@ -81,6 +127,13 @@ export interface BudgetReservation {
   readonly tokens: number;
 }
 
+/**
+ * The per-process default. There is NO window: a counter lives until `reset()` or a restart, so an
+ * `actor` / `org` ceiling here is "per process lifetime". It holds one entry per caller that has
+ * spent under a DECLARED ceiling (none at all without one), and deliberately no eviction: dropping
+ * a counter hands that caller its whole ceiling back, which is the bypass the ceiling exists to
+ * stop. A window — per day, per month — is a shared store whose keys expire.
+ */
 export class MemoryBudgetStore implements BudgetStore {
   private readonly counters = new Map<string, number>();
 
@@ -88,8 +141,27 @@ export class MemoryBudgetStore implements BudgetStore {
     return this.counters.get(key) ?? 0;
   }
 
+  /** A counter back at zero is deleted: absent and zero are the same answer, and an entry costs. */
   add(key: string, tokens: number): void {
-    this.counters.set(key, this.spent(key) + tokens);
+    this.write(key, this.spent(key) + tokens);
+  }
+
+  /** Atomic because it is synchronous: nothing else runs between the read and the write. */
+  take(key: string, tokens: number, limit: number): BudgetTake {
+    const spent = this.spent(key);
+    if (spent + tokens > limit) return { taken: false, spent };
+    this.write(key, spent + tokens);
+    return { taken: true, spent };
+  }
+
+  /** How many counters are held — one per caller that has spent under a declared ceiling. */
+  size(): number {
+    return this.counters.size;
+  }
+
+  private write(key: string, total: number): void {
+    if (total === 0) this.counters.delete(key);
+    else this.counters.set(key, total);
   }
 
   reset(key?: string): void {
@@ -98,6 +170,11 @@ export class MemoryBudgetStore implements BudgetStore {
   }
 }
 
+/** The one way to build the per-process store; the class is a type in the barrel only. */
+export function memoryBudgetStore(): MemoryBudgetStore {
+  return new MemoryBudgetStore();
+}
+
 export interface BudgetLedgerInput {
   readonly limits: BudgetLimits;
   /** Stable identity keys. Omit a key to skip that scope even when a limit is set. */
@@ -133,20 +210,13 @@ export class BudgetLedger {
    * inside it, and its `request` ceiling was re-granted in full to every one of them.
    */
   private parent: BudgetLedger | undefined;
-  /**
-   * Reservations take turns. Check-then-debit spans an `await store.spent()`, and three callers
-   * interleaving inside it is the bypass this ledger exists to close — one event loop, so a
-   * promise chain IS the lock. A store shared across PROCESSES needs an atomic increment of its
-   * own; this closes the parallelism inside one.
-   */
-  private turnstile: Promise<unknown> = Promise.resolve();
 
   constructor(input: BudgetLedgerInput) {
     // The ceilings are screened where they LAND, because `assertScope` compares with `>`: a `NaN`
     // limit makes `limit - spent` a `NaN`, `want > NaN` false, and the scope silently unlimited —
     // the ceiling does not become wrong, it stops existing. `llm()`, `agent()` and `hive()` screen
     // the same numbers first under the key names their declarations use (`tokensPerRun` is this
-    // `request`), so this is the backstop for a `createGateway({ budget })` or a hand-built ledger,
+    // `request`), so this is the backstop for a `providerGateway({ budget })` or a hand-built ledger,
     // where these ARE the names the caller wrote.
     this.limits = assertFiniteLimits(input.limits);
     this.actorKey = input.actorKey;
@@ -156,35 +226,19 @@ export class BudgetLedger {
   }
 
   /**
-   * Check an estimate against every applicable scope BEFORE the call, then DEBIT it. Throws on
-   * the first scope that cannot cover it, naming that scope, so the fix line points at one knob
-   * rather than four.
+   * Check an estimate against every applicable scope BEFORE the call, and DEBIT it in the same
+   * step. Throws on the first scope that cannot cover it, naming that scope, so the fix line points
+   * at one knob rather than four.
    *
-   * The debit is what makes the ceiling hold under parallelism. Checking without debiting meant
-   * three concurrent calls under one ledger all read `spent() === 0`, all passed, and all three
-   * recorded against a ceiling only one of them fitted — an "un-bypassable" org budget bypassed
-   * by `Promise.all`. `record` replaces the estimate with the real counts; `release` gives it
-   * back when the call never happened.
+   * Debit-then-check, never check-then-debit: the in-memory scopes are checked and debited with no
+   * `await` between (one event loop, so that IS atomic), and the store's scopes go through its
+   * atomic `take`. Any read-then-write across an `await` lets concurrent calls — `Promise.all` of
+   * derived ledgers, or one request per scope racing one org key — all read the same `spent`, all
+   * pass, and all debit a ceiling only one fitted. A refusal at a later scope gives back what the
+   * earlier ones took. `record` replaces the estimate with the real counts; `release` gives it back
+   * when the call never happened.
    */
   async reserve(estimate: SpendEstimate): Promise<BudgetReservation> {
-    // The ROOT's turnstile, not this ledger's: reservations under one scope take turns even when
-    // each call derived its own ledger, which is every `llm()` call. A per-ledger queue serialised
-    // nothing once `derive` existed — `Promise.all` of three derived ledgers all read the chain
-    // before any of them debited it.
-    const gate = this.rootLedger();
-    const turn = gate.turnstile.then(() => this.reserveNow(estimate));
-    // Chained on a settled shadow: one refusal must not reject every reservation queued behind it.
-    gate.turnstile = turn.catch(() => undefined);
-    return await turn;
-  }
-
-  private rootLedger(): BudgetLedger {
-    let ledger: BudgetLedger = this;
-    while (ledger.parent !== undefined) ledger = ledger.parent;
-    return ledger;
-  }
-
-  private async reserveNow(estimate: SpendEstimate): Promise<BudgetReservation> {
     // Every ledger in the chain, because each keeps its own counter and the tightest limit is not
     // always the one with the most spent against it.
     for (let l: BudgetLedger | undefined = this; l !== undefined; l = l.parent) {
@@ -192,19 +246,53 @@ export class BudgetLedger {
     }
     // Per call, so nothing is "already spent" against it.
     this.assertScope('tokensIn', this.limits.tokensIn, 0, estimate.inputTokens);
-    if (this.limits.actor !== undefined && this.actorKey !== undefined) {
-      const spent = await this.store.spent(this.actorKey);
-      this.assertScope(`actor:${this.actorKey}`, this.limits.actor, spent, estimate.tokens);
-    }
-    if (this.limits.org !== undefined && this.orgKey !== undefined) {
-      const spent = await this.store.spent(this.orgKey);
-      this.assertScope(`org:${this.orgKey}`, this.limits.org, spent, estimate.tokens);
-    }
     this.assertCost(estimate.cost);
-    await this.debit(estimate.tokens);
+    this.debitChain(estimate.tokens);
+    const taken: string[] = [];
+    try {
+      await this.takeScope('actor', this.limits.actor, this.actorKey, estimate.tokens, taken);
+      await this.takeScope('org', this.limits.org, this.orgKey, estimate.tokens, taken);
+    } catch (error) {
+      this.debitChain(-estimate.tokens);
+      for (const key of taken) await this.store.add(key, -estimate.tokens);
+      throw error;
+    }
     return { tokens: estimate.tokens };
   }
 
+  /**
+   * One store scope, and only when its ceiling is DECLARED: every `llm()` / `agent()` / `hive()`
+   * carries its caller's keys, so writing per key grew `MemoryBudgetStore` by one entry per caller
+   * forever — and cost a shared store two writes a call — for counters no ceiling reads. Records
+   * the key it took, so a refusal further on can give it back.
+   */
+  private async takeScope(
+    scope: 'actor' | 'org',
+    limit: number | undefined,
+    key: string | undefined,
+    tokens: number,
+    taken: string[],
+  ): Promise<void> {
+    if (key === undefined || limit === undefined) return;
+    const outcome: unknown = await this.store.take(key, tokens, limit);
+    // The store is the app's: a shape it did not promise must be a coded refusal, never a
+    // `TypeError` from reading `.taken` off `undefined` inside the reservation.
+    assert(
+      isBudgetTake(outcome),
+      `BudgetStore.take("${key}") answered ${typeof outcome}, not { taken: boolean, spent: number }`,
+      'return { taken, spent } from take(key, tokens, limit), spent being the counter before this take',
+    );
+    if (!outcome.taken) {
+      throw new AiBudgetExceededError({
+        scope: `${scope}:${key}`,
+        requested: tokens,
+        remaining: limit - outcome.spent,
+        limit,
+      });
+    }
+    taken.push(key);
+  }
+
   /** Give a reservation back: a provider that threw, a stream abandoned before `done`. */
   async release(reservation: BudgetReservation | undefined): Promise<void> {
     if (reservation === undefined) return;
@@ -217,6 +305,9 @@ export class BudgetLedger {
    * an `llm()` action must not be able to widen the actor or org ceiling it runs inside.
    */
   derive(limits: BudgetLimits): BudgetLedger {
+    // Screened BEFORE tightening, not only by the child's constructor: a `NaN` that won
+    // `tighterMoney` would otherwise reach the child as the parent's ceiling, widened.
+    assertFiniteLimits(limits);
     const child = new BudgetLedger({
       limits: {
         ...pick('request', tighterNumber(this.limits.request, limits.request)),
@@ -258,11 +349,25 @@ export class BudgetLedger {
    */
   private async debit(tokens: number): Promise<void> {
     if (tokens === 0) return;
+    this.debitChain(tokens);
+    // The keys `reserve` took — a scope with a declared ceiling — and no others, so a reconcile
+    // never creates the counter `takeScope` declined to.
+    for (const key of this.meteredKeys()) await this.store.add(key, tokens);
+  }
+
+  /** The store keys this ledger meters: a key whose scope declares a ceiling. */
+  private meteredKeys(): readonly string[] {
+    const keys: string[] = [];
+    if (this.actorKey !== undefined && this.limits.actor !== undefined) keys.push(this.actorKey);
+    if (this.orgKey !== undefined && this.limits.org !== undefined) keys.push(this.orgKey);
+    return keys;
+  }
+
+  /** The in-memory half: this ledger's `request` counter and every ancestor's. */
+  private debitChain(tokens: number): void {
     for (let l: BudgetLedger | undefined = this; l !== undefined; l = l.parent) {
       l.requestTokens += tokens;
     }
-    if (this.actorKey !== undefined) await this.store.add(this.actorKey, tokens);
-    if (this.orgKey !== undefined) await this.store.add(this.orgKey, tokens);
   }
 
   async report(): Promise<BudgetReport> {
@@ -301,18 +406,40 @@ export class BudgetLedger {
 }
 
 /**
- * Every declared token ceiling, proven to be a number. A limit is optional and an absent one is
+ * Every declared ceiling, proven to be a whole count. A limit is optional and an absent one is
  * "unlimited" by design — which is exactly why a `NaN` one is the dangerous value: it reads as a
- * declared ceiling everywhere (`report()`, a manifest row, a log line) and enforces nothing.
+ * declared ceiling everywhere (`report()`, a manifest row, a log line) and enforces nothing. The
+ * money one most of all: `tighterMoney` asks `a.minor <= b.minor`, false against a `NaN`, so an
+ * unscreened `costPerCall` won every `derive` and WIDENED the stricter ceiling it ran inside.
+ * `subject` and `prefix` let a caller name the key its own declaration wrote (`gateway`'s
+ * `budget.org`), because a fix line naming a key the app never typed is not a fix.
  */
-function assertFiniteLimits(limits: BudgetLimits): BudgetLimits {
+export function assertFiniteLimits(
+  limits: BudgetLimits,
+  subject = 'the AI budget',
+  prefix = '',
+): BudgetLimits {
   for (const scope of ['request', 'tokensIn', 'actor', 'org'] as const) {
     const limit = limits[scope];
-    if (limit !== undefined) finiteCount('the AI budget', scope, limit);
+    if (limit !== undefined) finiteCount(subject, `${prefix}${scope}`, limit);
   }
+  const money = limits.costPerCall;
+  if (money !== undefined) finiteCount(subject, `${prefix}costPerCall.minor`, money.minor);
   return limits;
 }
 
+/** One money ceiling screened under `key`, for a declaration whose field names differ from ours. */
+export function screenedMoney(subject: string, key: string, money: Money): Money {
+  finiteCount(subject, `${key}.minor`, money.minor);
+  return money;
+}
+
+function isBudgetTake(value: unknown): value is BudgetTake {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record['taken'] === 'boolean' && Number.isFinite(record['spent']);
+}
+
 /** Spreadable single-key record, so an absent limit stays absent under exactOptionalPropertyTypes. */
 function pick<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
   return value === undefined ? {} : ({ [key]: value } as Record<K, V>);