@cleocode/core 2026.9.22 → 2026.9.23

package/dist/build-provenance.json

@@ -0,0 +1,6 @@
+{
+  "schema": 1,
+  "gitHead": "3cce27b1da36cde459965b556608b68a4591a7ee",
+  "builtAt": "2026-09-29T12:04:14.801Z",
+  "linkedWorktree": null
+}

package/dist/decide/audit.d.ts

@@ -18,7 +18,7 @@ import type { DecisionAnswer, DecisionOutcome, DecisionOutcomeSource } from '@cl
 /** Project-relative path of the decision audit log. */
 export declare const DECISION_AUDIT_FILE = ".cleo/audit/decisions.jsonl";
 /** Why a fallback was used (absent for provider/cache outcomes). */
-export type DecisionFallbackReason = 'unconfigured' | 'invalid_request' | 'budget_exhausted' | 'budget_cooling_down' | 'budget_unavailable' | 'timeout' | 'unauthorized' | 'insufficient_credits' | 'rate_limited' | 'server_error' | 'network' | 'invalid_response' | 'provider_error';
+export type DecisionFallbackReason = 'unconfigured' | 'invalid_request' | 'budget_exhausted' | 'budget_cooling_down' | 'budget_unavailable' | 'timeout' | 'unauthorized' | 'insufficient_credits' | 'key_limit_exceeded' | 'budget' | 'rate_limited' | 'overloaded' | 'server_error' | 'network' | 'invalid_response' | 'provider_error';
 /** One audited answer: the decided value plus its distribution. */
 export interface DecisionAuditAnswer {
     /** Question type. */
@@ -89,6 +89,12 @@ export interface DecisionAuditEntry {
     readonly latencyMs: number;
     /** Provider-reported cost in USD, when known. */
     readonly costUsd?: number;
+    /** Provider-reported cost in integer micro-dollars, when known (T12664). */
+    readonly costMicros?: number;
+    /** Account balance in integer micro-dollars reported with the answer, when known. */
+    readonly balanceMicros?: number;
+    /** Provider model checkpoint that answered, when reported. */
+    readonly checkpoint?: string;
     /** Model the request named, when it named one. */
     readonly model?: string;
     /** Shadow-mode comparison, when the call site recorded one. */

package/dist/decide/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}

package/dist/decide/audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/decide/audit.ts"],"names":[],"mappings":"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"}

package/dist/decide/client.d.ts

@@ -11,10 +11,16 @@
  *    request with the contract schema (invalid → fallback).
  * 3. In-memory LRU cache hit → `source: 'cache'`.
  * 4. Within ONE per-site deadline (default {@link DEFAULT_DECISION_TIMEOUT_MS}):
- *    take a token from the machine-wide budget, then call the provider.
- *    Budget denial, timeout, 401/402/429/5xx, network failure or a malformed
- *    answer → fallback. A 429 also empties the shared budget for its
- *    `retry-after` so no other process piles on.
+ *    check the monthly spend cap (`./spend.ts`, D11159), take a token from the
+ *    machine-wide request budget, then call the provider. Spend cap reached
+ *    (`budget`), key monthly limit (`key_limit_exceeded`), budget denial,
+ *    timeout, 401/402/403/429/5xx, network failure or a malformed answer →
+ *    fallback. A 429 empties the shared budget for its `retry-after`; a
+ *    503/529 trips it as a short circuit breaker; a 403 key limit stops
+ *    decisions until the UTC month ends. Reported cost is added to the spend
+ *    ledger. A call aborted AFTER it was sent (deadline or caller) may still be
+ *    billed, so its reserved estimate is committed; only a failure before send
+ *    or an error response releases the reservation.
  * 5. Append one audit line (never containing the key or raw state).
  *
  * Provider-specific knowledge (endpoints, wire JSON) lives only in
@@ -28,8 +34,11 @@ import { type DecisionAuditSink } from './audit.js';
 import { type DecisionBudget } from './budget.js';
 import { type DecisionCache } from './cache.js';
 import { type DecisionProvider, type DecisionProviderConnection } from './provider.js';
+import { type SpendLedger } from './spend.js';
 /** Default per-site deadline for the budget + provider round trip, in ms. */
 export declare const DEFAULT_DECISION_TIMEOUT_MS = 300;
+/** Circuit-breaker trip after a 503/529 that carried no `retry-after`, ms. */
+export declare const OVERLOADED_COOLDOWN_MS = 30000;
 /**
  * A call site's local heuristic. It must be total and fast: it answers every
  * question in the request whenever no provider answer is available.
@@ -52,6 +61,10 @@ export interface DecideOptions {
     readonly cache?: DecisionCache | null;
     /** Request budget; `null` disables. Default: the machine-wide file bucket. */
     readonly budget?: DecisionBudget | null;
+    /** Monthly spend ledger; `null` disables the cap. Default: the machine-wide file ledger. */
+    readonly spend?: SpendLedger | null;
+    /** Monthly cap in micro-dollars. Default: `decide.budget.monthlyMicros`, else $1. */
+    readonly spendCapMicros?: number;
     /** Audit sink; `null` disables. Default: `<projectRoot>/.cleo/audit/decisions.jsonl`. */
     readonly audit?: DecisionAuditSink | null;
     /** Project root for the default audit sink. Default: the resolved CLEO project root. */
@@ -76,6 +89,12 @@ export declare function _resetDecideDefaultsForTest(): void;
  * @returns Redacted state of the same shape.
  */
 export declare function redactDecisionState(state: DecisionState): DecisionState;
+/**
+ * Cost reserved per question before a call, micro-dollars. Only a
+ * reservation: the provider-reported cost replaces it on commit, so this is
+ * never what is recorded (layahost bills 5–15 µ$ per decision, 2026-09).
+ */
+export declare const DECISION_COST_ESTIMATE_MICROS_PER_QUESTION = 15;
 /**
  * Ask a typed decision at call site `siteId`.
  *
@@ -100,4 +119,27 @@ export declare function redactDecisionState(state: DecisionState): DecisionState
  * ```
  */
 export declare function decide(siteId: string, req: DecisionRequest, fallback: DecisionHeuristic, opts?: DecideOptions): Promise<DecisionOutcome>;
+/** One request of a {@link decideBatch} call, with its own heuristic. */
+export interface DecisionBatchEntry {
+    /** Questions and state. */
+    readonly req: DecisionRequest;
+    /** The heuristic for this request. */
+    readonly fallback: DecisionHeuristic;
+}
+/**
+ * Ask several typed decisions at call site `siteId` under ONE deadline.
+ *
+ * When the provider reports a batch capability (`capabilities().batch`) and
+ * the entries fit its limits, the uncached ones go out as a single batch call
+ * (one spend check, one budget token). Otherwise it degrades to sequential
+ * {@link decide} calls that share the remaining deadline; entries the
+ * deadline cannot reach fall back with reason `timeout`. Never rejects; each
+ * entry is audited like a single decision.
+ *
+ * @param siteId - Stable call-site identifier.
+ * @param entries - Requests with their heuristics.
+ * @param opts - Same wiring as {@link decide}; `timeoutMs` covers the whole batch.
+ * @returns One outcome per entry, in order.
+ */
+export declare function decideBatch(siteId: string, entries: readonly DecisionBatchEntry[], opts?: DecideOptions): Promise<DecisionOutcome[]>;
 //# sourceMappingURL=client.d.ts.map

package/dist/decide/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/decide/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAEhC,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAEnG,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAeD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD;AAWD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAMvE;AAuHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAqD1B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/decide/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAGhC,MAAM,eAAe,CAAC;AAEvB,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAEnG,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAwCD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAKlD;AAWD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAMvE;AAsED;;;;GAIG;AACH,eAAO,MAAM,0CAA0C,KAAK,CAAC;AA2K7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAmED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CA8F5B"}

package/dist/decide/client.js

@@ -11,10 +11,16 @@
  *    request with the contract schema (invalid → fallback).
  * 3. In-memory LRU cache hit → `source: 'cache'`.
  * 4. Within ONE per-site deadline (default {@link DEFAULT_DECISION_TIMEOUT_MS}):
- *    take a token from the machine-wide budget, then call the provider.
- *    Budget denial, timeout, 401/402/429/5xx, network failure or a malformed
- *    answer → fallback. A 429 also empties the shared budget for its
- *    `retry-after` so no other process piles on.
+ *    check the monthly spend cap (`./spend.ts`, D11159), take a token from the
+ *    machine-wide request budget, then call the provider. Spend cap reached
+ *    (`budget`), key monthly limit (`key_limit_exceeded`), budget denial,
+ *    timeout, 401/402/403/429/5xx, network failure or a malformed answer →
+ *    fallback. A 429 empties the shared budget for its `retry-after`; a
+ *    503/529 trips it as a short circuit breaker; a 403 key limit stops
+ *    decisions until the UTC month ends. Reported cost is added to the spend
+ *    ledger. A call aborted AFTER it was sent (deadline or caller) may still be
+ *    billed, so its reserved estimate is committed; only a failure before send
+ *    or an error response releases the reservation.
  * 5. Append one audit line (never containing the key or raw state).
  *
  * Provider-specific knowledge (endpoints, wire JSON) lives only in
@@ -32,10 +38,16 @@ import { createDecisionCache, decisionCacheKey, hashCanonical, } from './cache.j
 import { loadDecideConnection } from './credentials.js';
 import { createJevProvider, JEV_ADAPTER_VERSION } from './jev-wire.js';
 import { DecisionProviderError, } from './provider.js';
+import { cachedCapabilities } from './provider-state.js';
+import { createFileSpendLedger, DEFAULT_MONTHLY_SPEND_CAP_MICROS, MONTHLY_SPEND_CAP_KEY, } from './spend.js';
 /** Default per-site deadline for the budget + provider round trip, in ms. */
 export const DEFAULT_DECISION_TIMEOUT_MS = 300;
+/** Circuit-breaker trip after a 503/529 that carried no `retry-after`, ms. */
+export const OVERLOADED_COOLDOWN_MS = 30_000;
 let defaultCache = null;
 let defaultBudget = null;
+let defaultSpend = null;
+let defaultSpendCap = null;
 function processCache() {
     defaultCache ??= createDecisionCache();
     return defaultCache;
@@ -44,6 +56,28 @@ function processBudget() {
     defaultBudget ??= createFileTokenBucket();
     return defaultBudget;
 }
+function processSpend() {
+    defaultSpend ??= createFileSpendLedger();
+    return defaultSpend;
+}
+/** The configured monthly cap, read once per process; the $1 default when unset or unreadable. */
+function processSpendCap(projectRoot) {
+    defaultSpendCap ??= (async () => {
+        try {
+            const { getConfigValue } = await import('../config/registry.js');
+            const value = await getConfigValue(MONTHLY_SPEND_CAP_KEY, {
+                projectRoot: projectRoot ?? getProjectRoot(),
+            });
+            return typeof value === 'number' && Number.isFinite(value) && value >= 0
+                ? value
+                : DEFAULT_MONTHLY_SPEND_CAP_MICROS;
+        }
+        catch {
+            return DEFAULT_MONTHLY_SPEND_CAP_MICROS;
+        }
+    })();
+    return defaultSpendCap;
+}
 /**
  * Reset the process-default cache and budget. Tests only.
  *
@@ -52,6 +86,8 @@ function processBudget() {
 export function _resetDecideDefaultsForTest() {
     defaultCache = null;
     defaultBudget = null;
+    defaultSpend = null;
+    defaultSpendCap = null;
 }
 function redactJson(value) {
     if (typeof value === 'string')
@@ -98,7 +134,8 @@ function resolveProvider(opts, connection) {
         return null;
     if (!decisionProviderConfigSchema.safeParse({ baseUrl: connection.baseUrl }).success)
         return null;
-    return createJevProvider(connection);
+    const capabilities = cachedCapabilities(connection);
+    return createJevProvider(connection, capabilities ? { capabilities } : {});
 }
 function resolveAudit(opts) {
     if (opts.audit !== undefined)
@@ -120,17 +157,54 @@ function reasonForError(err) {
             return err.kind;
     }
 }
+/**
+ * The gates for a call. The configured cap is read BEFORE the deadline
+ * starts (a cold config read is not provider wait), once per process.
+ */
+async function resolveGates(opts) {
+    const budget = opts.budget === undefined ? processBudget() : opts.budget;
+    const spend = opts.spend === undefined ? processSpend() : opts.spend;
+    const capMicros = opts.spendCapMicros ??
+        (spend ? await processSpendCap(opts.projectRoot) : Number.POSITIVE_INFINITY);
+    return { budget, spend, capMicros };
+}
 /** True when `outcome` is contract-valid and answers every question with the right type. */
 function coversRequest(outcome, req) {
     if (!decisionOutcomeSchema.safeParse(outcome).success)
         return false;
     return Object.entries(req.questions).every(([name, q]) => outcome.answers[name]?.type === q.type);
 }
-/** Budget + provider call; never rejects. */
-async function attempt(provider, budget, req, signal) {
-    if (budget) {
-        const grant = await budget.tryAcquire();
+/**
+ * Cost reserved per question before a call, micro-dollars. Only a
+ * reservation: the provider-reported cost replaces it on commit, so this is
+ * never what is recorded (layahost bills 5–15 µ$ per decision, 2026-09).
+ */
+export const DECISION_COST_ESTIMATE_MICROS_PER_QUESTION = 15;
+/** Estimated cost of asking `reqs`. */
+function estimateMicros(reqs) {
+    return reqs.reduce((n, r) => n + Object.keys(r.questions).length * DECISION_COST_ESTIMATE_MICROS_PER_QUESTION, 0);
+}
+/**
+ * Spend cap (check and reserve, atomically) then request budget. A
+ * reservation is released again when the budget refuses.
+ */
+async function passGates(gates, estimate) {
+    let reservation;
+    if (gates.spend) {
+        const r = await gates.spend.reserve(gates.capMicros, estimate);
+        if (r.verdict === 'over_budget')
+            return { ok: false, reason: 'budget' };
+        if (r.verdict === 'key_limited')
+            return { ok: false, reason: 'key_limit_exceeded' };
+        if (r.verdict === 'unavailable')
+            return { ok: false, reason: 'budget_unavailable' };
+        reservation = r.id;
+    }
+    if (gates.budget) {
+        const grant = await gates.budget.tryAcquire();
         if (!grant.granted) {
+            if (reservation !== undefined)
+                await gates.spend?.release(reservation);
             return {
                 ok: false,
                 reason: grant.reason === 'exhausted'
@@ -141,19 +215,82 @@ async function attempt(provider, budget, req, signal) {
             };
         }
     }
-    if (signal.aborted)
+    return { ok: true, ...(reservation !== undefined ? { reservation } : {}) };
+}
+/** Commit the reported cost against a reservation (or record it when there is none). */
+async function settle(gates, reservation, micros) {
+    if (!gates.spend)
+        return;
+    if (reservation !== undefined)
+        await gates.spend.commit(reservation, micros);
+    else
+        await gates.spend.record(micros);
+}
+/** Side effects of a provider error on the shared gates; the fallback reason. */
+async function onProviderError(err, gates) {
+    if (err.kind === 'rate_limited' && gates.budget)
+        await gates.budget.penalize(err.retryAfterMs);
+    if (err.kind === 'overloaded' && gates.budget) {
+        await gates.budget.penalize(err.retryAfterMs ?? OVERLOADED_COOLDOWN_MS);
+    }
+    if (err.kind === 'key_limit_exceeded' && gates.spend)
+        await gates.spend.markKeyLimited();
+    return reasonForError(err);
+}
+/**
+ * Whether a failed call may still have been billed: it was aborted (deadline
+ * or caller) AFTER the request was handed to the provider. The server may
+ * have answered and billed it, so its reservation is committed at the
+ * estimate rather than released. Every other failure is an error response or
+ * a transport failure, which the provider does not bill.
+ */
+function abortedAfterSend(err, signal) {
+    return signal.aborted || (err instanceof DecisionProviderError && err.kind === 'aborted');
+}
+/**
+ * Settle a reservation after a failed call: commit the estimate when the
+ * call was aborted after send ({@link abortedAfterSend}), else release it.
+ */
+async function settleFailure(gates, reservation, estimate, err, signal) {
+    if (reservation === undefined || !gates.spend)
+        return;
+    if (abortedAfterSend(err, signal))
+        await gates.spend.commit(reservation, estimate);
+    else
+        await gates.spend.release(reservation);
+}
+/** Micro-dollars an outcome reported, preferring the exact integer. */
+function reportedMicros(outcome) {
+    if (outcome.costMicros !== undefined)
+        return outcome.costMicros;
+    return outcome.costUsd !== undefined ? Math.round(outcome.costUsd * 1e6) : 0;
+}
+/** Spend gate + budget + provider call; never rejects. */
+async function attempt(provider, gates, req, signal) {
+    const estimate = estimateMicros([req]);
+    const gate = await passGates(gates, estimate);
+    if (!gate.ok)
+        return { ok: false, reason: gate.reason };
+    if (signal.aborted) {
+        // Pre-send: nothing left the machine, so nothing can be billed.
+        if (gate.reservation !== undefined)
+            await gates.spend?.release(gate.reservation);
         return { ok: false, reason: 'timeout' };
+    }
     try {
         const outcome = await provider.decide(req, signal);
+        // A 2xx is billed even when its body is unusable.
+        await settle(gates, gate.reservation, reportedMicros(outcome));
         if (!coversRequest(outcome, req))
             return { ok: false, reason: 'invalid_response' };
         return { ok: true, outcome };
     }
     catch (err) {
+        // Failed requests are not billed (provider docs), but one aborted after
+        // send may have been answered and billed: charge its estimate.
+        await settleFailure(gates, gate.reservation, estimate, err, signal);
         if (err instanceof DecisionProviderError) {
-            if (err.kind === 'rate_limited' && budget)
-                await budget.penalize(err.retryAfterMs);
-            return { ok: false, reason: reasonForError(err) };
+            return { ok: false, reason: await onProviderError(err, gates) };
         }
         return { ok: false, reason: signal.aborted ? 'timeout' : 'provider_error' };
     }
@@ -163,7 +300,7 @@ async function attempt(provider, budget, req, signal) {
  * deadline or the caller's signal fires, even if the provider ignores its
  * abort signal.
  */
-function withDeadline(run, timeoutMs, callerSignal) {
+function withDeadline(run, timeoutMs, callerSignal, timedOut, crashed) {
     const controller = new AbortController();
     return new Promise((resolve) => {
         let settled = false;
@@ -177,7 +314,7 @@ function withDeadline(run, timeoutMs, callerSignal) {
         };
         const onTimeout = () => {
             controller.abort();
-            finish({ ok: false, reason: 'timeout' });
+            finish(timedOut);
         };
         const onCallerAbort = () => onTimeout();
         const timer = setTimeout(onTimeout, Math.max(0, timeoutMs));
@@ -186,7 +323,7 @@ function withDeadline(run, timeoutMs, callerSignal) {
             return;
         }
         callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
-        run(controller.signal).then(finish, () => finish({ ok: false, reason: 'provider_error' }));
+        run(controller.signal).then(finish, () => finish(crashed));
     });
 }
 /**
@@ -213,10 +350,29 @@ function withDeadline(run, timeoutMs, callerSignal) {
  * ```
  */
 export async function decide(siteId, req, fallback, opts = {}) {
-    const started = performance.now();
-    const elapsed = () => Math.max(0, performance.now() - started);
     const audit = resolveAudit(opts);
     const connection = resolveConnection(opts);
+    const item = prepare(siteId, req, fallback, opts, audit, connection);
+    const provider = resolveProvider(opts, connection);
+    if (!provider)
+        return item.useFallback('unconfigured');
+    if (!item.valid)
+        return item.useFallback('invalid_request');
+    const cache = opts.cache === undefined ? processCache() : opts.cache;
+    const hit = cache?.get(item.key);
+    if (hit)
+        return item.finish({ ...hit, source: 'cache', latencyMs: item.elapsed() });
+    const gates = await resolveGates(opts);
+    const result = await withDeadline((signal) => attempt(provider, gates, item.sent, signal), opts.timeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS, opts.signal, { ok: false, reason: 'timeout' }, { ok: false, reason: 'provider_error' });
+    if (!result.ok)
+        return item.useFallback(result.reason);
+    cache?.set(item.key, result.outcome);
+    return item.finish({ ...result.outcome, source: 'provider', latencyMs: item.elapsed() });
+}
+/** Redact, validate, key and wire the audit for one request. */
+function prepare(siteId, req, fallback, opts, audit, connection) {
+    const started = performance.now();
+    const elapsed = () => Math.max(0, performance.now() - started);
     const defaultModel = req.model === undefined ? connection?.model : undefined;
     const sent = {
         ...req,
@@ -237,26 +393,165 @@ export async function decide(siteId, req, fallback, opts = {}) {
             ...(reason ? { fallbackReason: reason } : {}),
             latencyMs: outcome.latencyMs,
             ...(outcome.costUsd !== undefined ? { costUsd: outcome.costUsd } : {}),
+            ...(outcome.costMicros !== undefined ? { costMicros: outcome.costMicros } : {}),
+            ...(outcome.balanceMicros !== undefined ? { balanceMicros: outcome.balanceMicros } : {}),
+            ...(outcome.checkpoint !== undefined ? { checkpoint: outcome.checkpoint } : {}),
             ...(sent.model !== undefined ? { model: sent.model } : {}),
         });
         return outcome;
     };
-    const useFallback = (reason) => finish({ answers: fallback(req), source: 'fallback', latencyMs: elapsed() }, reason);
+    return {
+        sent,
+        valid: decisionRequestSchema.safeParse(sent).success,
+        key: decisionCacheKey(opts.adapterVersion ?? JEV_ADAPTER_VERSION, sent),
+        elapsed,
+        finish,
+        useFallback: (reason) => finish({ answers: fallback(req), source: 'fallback', latencyMs: elapsed() }, reason),
+    };
+}
+/**
+ * Ask several typed decisions at call site `siteId` under ONE deadline.
+ *
+ * When the provider reports a batch capability (`capabilities().batch`) and
+ * the entries fit its limits, the uncached ones go out as a single batch call
+ * (one spend check, one budget token). Otherwise it degrades to sequential
+ * {@link decide} calls that share the remaining deadline; entries the
+ * deadline cannot reach fall back with reason `timeout`. Never rejects; each
+ * entry is audited like a single decision.
+ *
+ * @param siteId - Stable call-site identifier.
+ * @param entries - Requests with their heuristics.
+ * @param opts - Same wiring as {@link decide}; `timeoutMs` covers the whole batch.
+ * @returns One outcome per entry, in order.
+ */
+export async function decideBatch(siteId, entries, opts = {}) {
+    if (entries.length === 0)
+        return [];
+    const started = performance.now();
+    const deadlineMs = opts.timeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
+    const remaining = () => Math.max(0, deadlineMs - (performance.now() - started));
+    const connection = resolveConnection(opts);
     const provider = resolveProvider(opts, connection);
-    if (!provider)
-        return useFallback('unconfigured');
-    if (!decisionRequestSchema.safeParse(sent).success)
-        return useFallback('invalid_request');
+    const limits = provider?.capabilities?.().batch;
+    const questions = entries.reduce((n, e) => n + Object.keys(e.req.questions).length, 0);
+    const batchable = provider !== null &&
+        provider.decideBatch !== undefined &&
+        limits !== undefined &&
+        entries.length > 1 &&
+        entries.length <= limits.maxRequests &&
+        questions <= limits.maxQuestions;
+    if (!batchable || !provider?.decideBatch) {
+        const out = [];
+        for (const entry of entries) {
+            const timeoutMs = remaining();
+            // model-site-allowed: plumbing — the caller's siteId is checked at its decideBatch call (gate 35)
+            const outcome = await decide(siteId, entry.req, entry.fallback, { ...opts, timeoutMs });
+            out.push(outcome);
+        }
+        return out;
+    }
+    const audit = resolveAudit(opts);
     const cache = opts.cache === undefined ? processCache() : opts.cache;
-    const key = decisionCacheKey(opts.adapterVersion ?? JEV_ADAPTER_VERSION, sent);
-    const hit = cache?.get(key);
-    if (hit)
-        return finish({ ...hit, source: 'cache', latencyMs: elapsed() });
-    const budget = opts.budget === undefined ? processBudget() : opts.budget;
-    const result = await withDeadline((signal) => attempt(provider, budget, sent, signal), opts.timeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS, opts.signal);
-    if (!result.ok)
-        return useFallback(result.reason);
-    cache?.set(key, result.outcome);
-    return finish({ ...result.outcome, source: 'provider', latencyMs: elapsed() });
+    const items = entries.map((e) => prepare(siteId, e.req, e.fallback, opts, audit, connection));
+    const out = items.map((item) => {
+        if (!item.valid)
+            return item.useFallback('invalid_request');
+        const hit = cache?.get(item.key);
+        return hit ? item.finish({ ...hit, source: 'cache', latencyMs: item.elapsed() }) : undefined;
+    });
+    const pending = items.flatMap((item, i) => (out[i] === undefined ? [{ item, i }] : []));
+    if (pending.length > 0) {
+        const gates = await resolveGates(opts);
+        const batch = provider.decideBatch.bind(provider);
+        const result = await withDeadline(async (signal) => {
+            const sent = pending.map((p) => p.item.sent);
+            const estimate = estimateMicros(sent);
+            const gate = await passGates(gates, estimate);
+            if (!gate.ok)
+                return { ok: false, reason: gate.reason };
+            if (signal.aborted) {
+                if (gate.reservation !== undefined)
+                    await gates.spend?.release(gate.reservation);
+                return { ok: false, reason: 'timeout' };
+            }
+            try {
+                const answered = await batch(sent, signal);
+                const billed = answered.reduce((n, a) => n + (a.ok ? reportedMicros(a.outcome) : 0), 0);
+                await settle(gates, gate.reservation, billed);
+                return { ok: true, items: answered };
+            }
+            catch (err) {
+                await settleFailure(gates, gate.reservation, estimate, err, signal);
+                if (err instanceof DecisionProviderError) {
+                    return { ok: false, reason: await onProviderError(err, gates) };
+                }
+                return { ok: false, reason: signal.aborted ? 'timeout' : 'provider_error' };
+            }
+        }, remaining(), opts.signal, { ok: false, reason: 'timeout' }, { ok: false, reason: 'provider_error' });
+        if (result.ok)
+            await applyBatchItemErrors(result.items, gates);
+        for (const [k, { item, i }] of pending.entries()) {
+            if (!result.ok) {
+                out[i] = item.useFallback(result.reason);
+                continue;
+            }
+            const answered = result.items[k];
+            if (answered?.ok && coversRequest(answered.outcome, item.sent)) {
+                cache?.set(item.key, answered.outcome);
+                out[i] = item.finish({
+                    ...answered.outcome,
+                    source: 'provider',
+                    latencyMs: item.elapsed(),
+                });
+            }
+            else {
+                out[i] = item.useFallback(answered && !answered.ok ? batchItemReason(answered.errorKind) : 'invalid_response');
+            }
+        }
+    }
+    return items.map((item, i) => out[i] ?? item.useFallback('provider_error'));
+}
+/** Fallback reason for a failed batch item. */
+function batchItemReason(kind) {
+    switch (kind) {
+        case 'unauthorized':
+        case 'insufficient_credits':
+        case 'key_limit_exceeded':
+        case 'rate_limited':
+        case 'overloaded':
+        case 'server_error':
+        case 'invalid_request':
+        case 'invalid_response':
+            return kind;
+        default:
+            return 'provider_error';
+    }
+}
+/** Batch item error kinds with a side effect on the shared gates. */
+const GATE_ERROR_KINDS = new Set(['key_limit_exceeded', 'rate_limited', 'overloaded']);
+/** The gate-affecting provider error kind named by a batch item, if any. */
+function gateErrorKind(kind) {
+    for (const k of GATE_ERROR_KINDS)
+        if (k === kind)
+            return k;
+    return null;
+}
+/**
+ * Give failed batch items the same gate side effects as a failed single
+ * call (key-limit stop, rate-limit and overload back-off), once per kind.
+ */
+async function applyBatchItemErrors(items, gates) {
+    const seen = new Set();
+    for (const item of items) {
+        if (item.ok)
+            continue;
+        const kind = gateErrorKind(item.errorKind);
+        if (kind === null || seen.has(kind))
+            continue;
+        seen.add(kind);
+        await onProviderError(new DecisionProviderError(kind, `batch item failed: ${kind}`, {
+            ...(item.status !== undefined ? { status: item.status } : {}),
+        }), gates);
+    }
 }
 //# sourceMappingURL=client.js.map