@ultimat3/ai 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -63,11 +63,42 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 | `eval-errors.ts` | the five `X_EVAL_*` classes; their codes and titles stay in `errors.ts` |
 | `llm-cache.ts` | the semantic cache half of `llm()`: what a declaration may partition on, and the store it reaches |
 | `llm-fixture.ts` | the harness `llm.test.ts` and `llm-cache.test.ts` share. Not shipped (`!src/**/*-fixture.ts`) |
+| `bounds-fixture.ts` | the one `refusal`/`asyncRefusal` every numeric-bound suite here asserts through. Not shipped, same rule |
+| `agent-bounds.test.ts` | the agent loop's ceilings, split out because `agent.test.ts` is at the 500-line ceiling |
 | `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches |
 | `fix-line.ts` / `fix-line.evals.ts` / `fix-line.v1.baseline.json` / `fix-line.eval.test.ts` | the package's own dogfood eval — the first framework-level `*.eval.test.ts`, proving the `defineEval`/baseline convention actually fails a build |
 
 ## Invariants
 
+- **Every numeric option in this package is screened, and `??` is not the screen — `As of
+  2026-08-26`.** `NaN` is not nullish, so a default never fires for it, and `Math.max`, `Math.min`
+  and `Math.floor` all PROPAGATE it. `finiteOption`/`finiteCount` from `@ultimat3/core` are the one
+  form (never a local copy — `scripts/flight-copies.ts` exists because four grew once), and
+  `bun run finite-bounds` is the ratchet — it saw 21 of these sites, and the ones it CANNOT see (a
+  required option with no `??`, a default parameter, a cross-field product like
+  `Math.max(input.k * 4, 20)`) were the worse half. What they DID:
+  `chunk({ size: NaN })` was a synchronous infinite loop past every `AbortSignal`;
+  `embedBatched(…, 0)` re-issued the same empty batch to a paid endpoint forever;
+  `hive({ concurrency: NaN })` ran `Array.from({ length: NaN })` workers, i.e. none, and returned
+  `0 ok / 0 failed / 0 skipped` as a clean run; `RemoteEmbedder({ batchSize: NaN })` sent ONE
+  request of zero inputs and answered zero vectors; `k1`, `k`, `rrfK` each turned a search into an
+  empty list or an unranked one. **The worst is `maxTokens`, and it is not about the request**: it
+  IS the pre-flight estimate, `BudgetLedger.assertScope` asks `want > remaining`, every comparison
+  against a `NaN` is false, and `debit` then writes that `NaN` onto the ambient ledger AND the
+  per-process `BudgetStore` — measured, a 5,000,000-token call passed a 1,000-token ceiling on the
+  next reserve. One unscreened declaration turns every actor and org ceiling in the process off for
+  the life of the process. Hence `Gateway.generate`/`stream` screen it at the one seam every model
+  call passes, `registerModel` screens `maxOutput` (which reaches the same estimate through
+  `Math.min`), and `llm()`/`agent()` screen theirs at DECLARATION, beside `respondToolFor` and the
+  `X_AGENT_TOOL_UNEXPOSED` check, so a module-scope declaration fails the boot rather than the
+  ninetieth second of a run.
+- **A bound is screened under the key the DECLARATION uses, even when that costs a second check.**
+  `budget.tokensPerRun` reaches `BudgetLimits` as `request`, so `limitsOf` in `llm.ts`, `agent.ts`
+  and `hive.ts` screens it before the ledger's own constructor does — a `fix:` naming a key the app
+  never wrote is not a fix. Same reason `retrieve()` screens its own `k` rather than letting the
+  store refuse the `k * 3` it becomes, and `RemoteEmbedder` screens `maxResponseBytes` itself
+  rather than letting core's reader answer `readWithinLimit was given a limit of NaN` — which is
+  correct, unactionable, and only arrives after the request has been paid for.
 - **`llm()` returns an `action`. It is not a ninth primitive** (root `CLAUDE.md`, 2026-08). It
   never re-implements parse, authz or invoke — `action()` owns those and `invoke` runs them.
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so an `llm` file imports one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "16.0.0",
+  "version": "18.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -25,21 +25,21 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "16.0.0",
-    "@ultimat3/cache": "16.0.0",
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/db": "16.0.0",
-    "@ultimat3/jobs": "16.0.0",
-    "@ultimat3/money": "16.0.0",
-    "@ultimat3/policy": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/time": "16.0.0"
+    "@ultimat3/action": "18.0.0",
+    "@ultimat3/cache": "18.0.0",
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/db": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/money": "18.0.0",
+    "@ultimat3/policy": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/time": "18.0.0"
   }
 }

package/src/agent.ts

@@ -23,7 +23,7 @@
 import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
 import type { Ctx, Span } from '@ultimat3/core';
-import { isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
+import { finiteCount, isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
@@ -73,6 +73,9 @@ const DEFAULT_MAX_TOKENS = 4_096;
  */
 const DEFAULT_TOOL_RESULT_CHARS = 4_000;
 
+/** Named in every bound refusal, so the fix names the key the declaration carries. */
+const SUBJECT = 'agent';
+
 export interface AgentBudget extends LlmBudget {
   /**
    * Token ceiling for the WHOLE run, every turn counted. The one ceiling `llm()` does not need:
@@ -161,6 +164,21 @@ export function agent<
       tools: unexposed.map(toolLabel),
     });
   }
+  // The three loop bounds, screened at DECLARATION for the same reason the tool check above is:
+  // the values are here, and an `agent()` runs at module scope, so a bound that is not one fails
+  // the boot instead of the ninetieth second of a run. None of them is checked by what it lands
+  // on — `turn <= NaN` is false on the FIRST comparison, so the loop takes zero turns and reports
+  // `X_AGENT_MAX_TURNS` about a model that was never called; `slice(0, NaN)` is `''`, so every
+  // tool result reaches the model empty while the run keeps paying for turns; and `maxTokens`
+  // becomes the pre-flight estimate, where a `NaN` disables the ledger for the whole process.
+  finiteCount(SUBJECT, 'maxTurns', def.maxTurns ?? DEFAULT_MAX_TURNS, 1);
+  finiteCount(
+    SUBJECT,
+    'maxToolResultChars',
+    def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
+    1,
+  );
+  finiteCount(SUBJECT, 'maxTokens', def.maxTokens ?? DEFAULT_MAX_TOKENS, 1);
   // Projected on FIRST RUN, memoised, for the reason above: `agent()` is evaluated at module
   // scope and a tool's name is stamped by `registerAction` at boot, so naming it here would make
   // the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
@@ -389,10 +407,16 @@ function limitsOf<
 >(def: AgentDef<TInput, TOutput, V>): BudgetLimits {
   const budget = def.budget;
   return {
-    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    // Screened under the names the DECLARATION uses, not the ledger's: `tokensPerRun` arrives at
+    // `BudgetLimits` as `request`, and a fix line naming a key the app never wrote is not a fix.
+    ...(budget?.tokensIn === undefined
+      ? {}
+      : { tokensIn: finiteCount(SUBJECT, 'budget.tokensIn', budget.tokensIn) }),
     ...(budget?.costPerCall === undefined ? {} : { 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 ? {} : { request: budget.tokensPerRun }),
+    ...(budget?.tokensPerRun === undefined
+      ? {}
+      : { request: finiteCount(SUBJECT, 'budget.tokensPerRun', budget.tokensPerRun) }),
   };
 }

package/src/budget.ts

@@ -10,7 +10,7 @@
 // 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 } from '@ultimat3/core';
+import { asyncContext, finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { assertSameCurrency } from '@ultimat3/money';
 import { AiBudgetExceededError } from './errors';
@@ -138,7 +138,13 @@ export class BudgetLedger {
   private turnstile: Promise<unknown> = Promise.resolve();
 
   constructor(input: BudgetLedgerInput) {
-    this.limits = input.limits;
+    // 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,
+    // where these ARE the names the caller wrote.
+    this.limits = assertFiniteLimits(input.limits);
     this.actorKey = input.actorKey;
     this.orgKey = input.orgKey;
     this.store = input.store ?? new MemoryBudgetStore();
@@ -290,6 +296,19 @@ export class BudgetLedger {
   }
 }
 
+/**
+ * Every declared token ceiling, proven to be a number. 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.
+ */
+function assertFiniteLimits(limits: BudgetLimits): BudgetLimits {
+  for (const scope of ['request', 'tokensIn', 'actor', 'org'] as const) {
+    const limit = limits[scope];
+    if (limit !== undefined) finiteCount('the AI budget', scope, limit);
+  }
+  return limits;
+}
+
 /** 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>);

package/src/embeddings.ts

@@ -5,6 +5,7 @@
 // queried with another is a silent relevance collapse, and the only place to catch it is
 // where the two meet. `VectorStore` compares the declared dimension and refuses.
 
+import { finiteCount } from '@ultimat3/core';
 import { AiEmbedderInvalidError } from './errors';
 
 export interface Embedder {
@@ -29,8 +30,14 @@ export async function embedOne(embedder: Embedder, text: string): Promise<Float3
 export async function embedBatched(
   embedder: Embedder,
   texts: readonly string[],
-  size = 96,
+  size: number = 96,
 ): Promise<readonly Float32Array[]> {
+  // A default PARAMETER is a bound like any option, and this one is the loop's stride: `size: 0`
+  // never advances `i` and issues the same empty batch to a paid endpoint forever — measured, a
+  // synchronous-looking `await` loop that never returns — while `size: NaN` sends ONE request of
+  // zero inputs and answers with zero vectors for however many texts it was given. Hence a floor
+  // of 1: there is no batch of nothing.
+  finiteCount('embedBatched', 'size', size, 1);
   const out: Float32Array[] = [];
   for (let i = 0; i < texts.length; i += size) {
     out.push(...(await embedder.embed(texts.slice(i, i + size))));
@@ -53,7 +60,10 @@ export class HashEmbedder implements Embedder {
   readonly dimension: number;
 
   constructor(input: HashEmbedderInput = {}) {
-    this.dimension = input.dimension ?? 256;
+    // Floored at 1: `new Float32Array(NaN)` is a vector of LENGTH ZERO, so every embedding is
+    // empty, `cosine` answers 0 for every pair, and the ranking collapses with nothing thrown —
+    // the silent relevance collapse this file's own header says the dimension exists to catch.
+    this.dimension = finiteCount('HashEmbedder', 'dimension', input.dimension ?? 256, 1);
   }
 
   async embed(texts: readonly string[]): Promise<readonly Float32Array[]> {

package/src/evals.ts

@@ -11,6 +11,7 @@
 // Every result is filed against a prompt's content hash, so a score is always attributable
 // to an exact prompt rather than "whatever was in main that day".
 
+import { finiteCount } from '@ultimat3/core';
 import type { EvalBaseline, Regression } from './eval-baseline';
 import {
   baselinePath,
@@ -179,7 +180,10 @@ async function runEval<V extends PromptVars>(
   for (const testCase of input.cases) {
     const generated = await gateway.generate({
       messages: [{ role: 'user' as const, content: input.prompt.render(testCase.vars) }],
-      maxTokens: input.maxTokens ?? 1_024,
+      // A ceiling of `NaN` is not a ceiling: it becomes the pre-flight estimate, passes every
+      // budget check and then poisons the ledger it was checked against. Refused here, per RUN,
+      // because `defineEval` takes it as a plain field and there is no earlier seam.
+      maxTokens: finiteCount('defineEval', 'maxTokens', input.maxTokens ?? 1_024, 1),
       ...(input.prompt.system !== undefined ? { system: input.prompt.system } : {}),
       ...(input.prompt.model !== undefined ? { model: input.prompt.model } : {}),
       ...(input.prompt.effort !== undefined ? { effort: input.prompt.effort } : {}),

package/src/gateway.ts

@@ -7,6 +7,7 @@
 import type { Random } from '@ultimat3/core';
 import {
   backoffDelay,
+  finiteCount,
   isRetryableStatus,
   isUltimateError,
   renderThrowable,
@@ -91,6 +92,15 @@ class GatewayImpl implements Gateway {
   constructor(config: CreateGatewayInput) {
     this.config = config;
     this.retry = config.retry ?? DEFAULT_RETRY;
+    // `attempts` is the retry loop's only exit condition and nothing screened it: `attempt <= NaN`
+    // is false on the first comparison, so `attempt()` calls no provider at all and raises
+    // `X_AI_PROVIDER_UNAVAILABLE` with an EMPTY attempt list — measured, "no provider could serve
+    // model claude-opus-5 ()" for a provider that was never asked. A floor of 1 because the field
+    // is documented as total attempts INCLUDING the first, so zero of them is not a policy.
+    // `baseDelayMs` and `maxDelayMs` are deliberately not screened here: `backoffDelay` refuses a
+    // non-finite one already, and a NEGATIVE base is clamped to a zero wait on purpose
+    // (`gateway-backoff.test.ts` pins it), which a count check here would start refusing.
+    finiteCount('createGateway', 'retry.attempts', this.retry.attempts, 1);
     this.sleep = config.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     this.random = config.random;
   }
@@ -113,7 +123,7 @@ class GatewayImpl implements Gateway {
 
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     const model = request.model ?? this.config.defaultModel ?? DEFAULT_MODEL;
-    const resolved: GenerateRequest = { ...request, model };
+    const resolved: GenerateRequest = { ...request, model, maxTokens: ceilingOf(request) };
 
     const cacheKey = cacheKeyFor(resolved);
     const cached = await this.config.cache?.get(cacheKey);
@@ -150,7 +160,7 @@ class GatewayImpl implements Gateway {
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = request.model ?? this.config.defaultModel ?? DEFAULT_MODEL;
-    const resolved: GenerateRequest = { ...request, model };
+    const resolved: GenerateRequest = { ...request, model, maxTokens: ceilingOf(request) };
 
     // Routed BEFORE the reservation, not after it. `providerFor` throws for a registered model no
     // configured provider serves — an ordinary boot misconfiguration — and a debit taken first has
@@ -258,6 +268,21 @@ class GatewayImpl implements Gateway {
   }
 }
 
+/**
+ * The request's completion ceiling, screened at the one seam every model call in an app passes
+ * through — `llm()`, `agent()`, an eval, a judge and a hand-built `generate()` alike.
+ *
+ * It is not the request that a `NaN` here breaks, and that is why it is refused before anything
+ * else happens: `maxTokens` IS the pre-flight estimate, `want > remaining` is false for a `NaN`
+ * want, and `BudgetLedger.debit` then writes it onto the ambient ledger and the per-process
+ * `BudgetStore`. Both counters are `NaN` from then on, so every later comparison against them is
+ * false too — one unscreened declaration turns off every actor and org ceiling in the process,
+ * permanently, and reports nothing. Screened before the reservation, so the ledger never sees it.
+ */
+function ceilingOf(request: GenerateRequest): number {
+  return finiteCount('the AI gateway', 'maxTokens', request.maxTokens, 1);
+}
+
 /**
  * Full jitter: a uniform pick from [0, exponential], capped BEFORE the roll.
  *
@@ -265,8 +290,12 @@ class GatewayImpl implements Gateway {
  * onto it, and nothing else. Two things came with the delegation and neither is cosmetic: the
  * result is ROUNDED where this floored it (a shift of at most 1ms, and the same rounding
  * `@ultimat3/jobs` and `@ultimat3/realtime` already use), and a policy carrying a `NaN` — which is
- * what `Number(process.env.…)` answers for an unset variable — waits 0 instead of handing
- * `setTimeout` a `NaN` it fires on the next tick, i.e. a backoff that is a tight spin.
+ * what `Number(process.env.…)` answers for an unset variable — is REFUSED rather than clamped.
+ * This paragraph said "waits 0" until 2026-08-26, which was the safe answer to the wrong question
+ * and had already stopped being true: a schedule of zeroes still spins, it just spins on purpose,
+ * so core's `backoffDelay` refuses a non-finite bound before it clamps and this gateway inherits
+ * the refusal with the curve. `gateway-backoff.test.ts` pins both halves — the refusal, and the
+ * negative base that IS still clamped to zero.
  */
 export function backoffMs(policy: RetryPolicy, attempt: number, random?: Random): number {
   return backoffDelay({

package/src/hive.ts

@@ -17,7 +17,7 @@
 import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
 import { action, actionName } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
-import { throwIfAborted, withSpan } from '@ultimat3/core';
+import { finiteCount, throwIfAborted, withSpan } from '@ultimat3/core';
 import type { AnySchema, InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { BudgetLimits } from './budget';
 import { BudgetLedger, currentBudget, withBudget } from './budget';
@@ -42,6 +42,9 @@ const DEFAULT_CONCURRENCY = 4;
  */
 const DEFAULT_MIN_MEMBERS = 2;
 
+/** Named in every bound refusal, so the fix names the key the declaration carries. */
+const SUBJECT = 'hive';
+
 export interface HiveSplitArgs<TInput extends StandardSchemaV1> {
   readonly input: InferOutput<TInput>;
   readonly ctx: Ctx;
@@ -108,13 +111,18 @@ async function run<
   const inputs = await def.split({ input: args.input, ctx: args.ctx });
   if (inputs.length === 0) throw new HiveEmptyError({ member: name });
 
-  const floor = def.minMembers ?? DEFAULT_MIN_MEMBERS;
+  // Both bounds screened before either clamp reads them, because neither clamp is a screen:
+  // `Math.max` and `Math.min` PROPAGATE a `NaN`, so `concurrency: NaN` survived both and reached
+  // `Array.from({ length: NaN }, worker)` — an empty worker list, a `members` array of holes, and
+  // `0 ok / 0 failed / 0 skipped` returned as a clean run over inputs nothing ever touched.
+  // `minMembers: NaN` is quieter and the same shape: `inputs.length < NaN` is false, so the floor
+  // stops existing rather than being wrong. The floor stays 0 for both — `Math.max(1, …)` already
+  // reads a declared 0 as "one worker", and refusing it here would be a new rule, not a repair.
+  const floor = finiteCount(SUBJECT, 'minMembers', def.minMembers ?? DEFAULT_MIN_MEMBERS);
+  const declared = finiteCount(SUBJECT, 'concurrency', def.concurrency ?? DEFAULT_CONCURRENCY);
   // A split below the floor still runs every input it produced — dropping one would be silent
   // data loss — it just stops paying for a pool to do it.
-  const width =
-    inputs.length < floor
-      ? 1
-      : Math.max(1, Math.min(def.concurrency ?? DEFAULT_CONCURRENCY, inputs.length));
+  const width = inputs.length < floor ? 1 : Math.max(1, Math.min(declared, inputs.length));
 
   return withSpan('ai.hive', async (span) => {
     span.setAttributes({
@@ -170,10 +178,16 @@ function limitsOf<
 >(def: HiveDef<TInput, MIn, MOut>): BudgetLimits {
   const budget = def.budget;
   return {
-    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    // Under the declaration's own key names — `tokensPerRun` is the ledger's `request`, and a fix
+    // line has to name what the app wrote.
+    ...(budget?.tokensIn === undefined
+      ? {}
+      : { tokensIn: finiteCount(SUBJECT, 'budget.tokensIn', budget.tokensIn) }),
     ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
     // The ledger's `request` scope accumulates across every call made under it, which for a hive
     // under `withBudget` is every member's every turn.
-    ...(budget?.tokensPerRun === undefined ? {} : { request: budget.tokensPerRun }),
+    ...(budget?.tokensPerRun === undefined
+      ? {}
+      : { request: finiteCount(SUBJECT, 'budget.tokensPerRun', budget.tokensPerRun) }),
   };
 }

package/src/llm.ts

@@ -24,7 +24,7 @@
 import type { Action, ActionMcp, ActionPolicy, InvokeOptions } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
 import type { Ctx, Span, SpanAttributes } from '@ultimat3/core';
-import { withSpan } from '@ultimat3/core';
+import { finiteCount, withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
@@ -138,6 +138,15 @@ export function llm<
   V extends PromptVars,
 >(def: LlmDef<TInput, TOutput, V>): LlmAction<TInput, TOutput> {
   const respond = respondToolFor(def.output);
+  // Screened at DECLARATION, beside `respondToolFor`'s own refusal and for the same reason: an
+  // `llm()` is evaluated at module scope, so a bound that is not one fails the boot rather than
+  // the first request. It is the read at `generate` below that makes it urgent — `maxTokens`
+  // becomes the pre-flight ESTIMATE, a `NaN` estimate passes every `want > remaining` check, and
+  // `debit` then writes that `NaN` onto the ambient ledger AND the per-process `BudgetStore`,
+  // where it never expires: one bad declaration turns every actor and org ceiling in the process
+  // off for the life of the process. A floor of 1 because a completion ceiling of zero tokens is
+  // a call that cannot answer.
+  finiteCount('llm', 'maxTokens', def.maxTokens ?? DEFAULT_MAX_TOKENS, 1);
   const built = action<TInput, TOutput>({
     input: def.input,
     output: def.output,
@@ -378,7 +387,12 @@ function repair(issues: string): AiMessage {
 
 function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
   return {
-    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    // Screened under the name the DECLARATION uses. `BudgetLedger` screens its own `limits` too,
+    // but its field is called `tokensIn` there by coincidence and `request` for `tokensPerRun` —
+    // a fix line has to name the key the app actually wrote.
+    ...(budget?.tokensIn === undefined
+      ? {}
+      : { tokensIn: finiteCount('llm', 'budget.tokensIn', budget.tokensIn) }),
     ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
   };
 }

package/src/models.ts

@@ -3,6 +3,7 @@
 // has never heard of — a closed union made them untypeable, so the only way past `tsc` was to
 // claim a Claude id and be billed Anthropic list prices for a model nobody ran. As of 2026-08.
 
+import { finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { AiModelUnknownError, AiRequestInvalidError } from './errors';
 
@@ -103,6 +104,9 @@ const usd = (minor: number): Money => ({ minor, currency: 'USD' });
  */
 const registry = new Map<ModelId, ModelSpec>();
 
+/** Named in every bound refusal, so the fix names the call an app makes at boot. */
+const SUBJECT = 'registerModel';
+
 /**
  * Add a model to the catalogue, or restate one that is already in it. **The three built-ins
  * register through this same call**, at the bottom of this file — so the default path is the
@@ -119,6 +123,19 @@ const registry = new Map<ModelId, ModelSpec>();
  * catalogue in the order it wants, re-registering the built-in ids it keeps.
  */
 export function registerModel(spec: ModelSpec): ModelSpec {
+  // Screened at the ONE seam every model in the catalogue passes through, and at boot, which is
+  // the earliest a wrong row can be caught. Not a formality: `maxOutput` reaches the pre-flight
+  // estimate through `Math.min(request.maxTokens, spec.maxOutput)` — which propagates a `NaN`
+  // rather than screening it — and a `NaN` estimate passes every `want > remaining` budget check
+  // and then writes itself onto the ledger and the per-process `BudgetStore`, where every later
+  // comparison against it is false too. A price is the same story for the money ceiling, and
+  // `costOf` answers confidently either way, so a row nobody can price is refused rather than
+  // billed. Minor units are whole by the framework's money rule, so `finiteCount` is the check.
+  finiteCount(SUBJECT, `${spec.id} contextWindow`, spec.contextWindow, 1);
+  finiteCount(SUBJECT, `${spec.id} maxOutput`, spec.maxOutput, 1);
+  finiteCount(SUBJECT, `${spec.id} cacheMinimumTokens`, spec.cacheMinimumTokens);
+  finiteCount(SUBJECT, `${spec.id} inputPerMillion.minor`, spec.inputPerMillion.minor);
+  finiteCount(SUBJECT, `${spec.id} outputPerMillion.minor`, spec.outputPerMillion.minor);
   registry.set(spec.id, spec);
   return spec;
 }

package/src/pg-vector.ts

@@ -3,6 +3,7 @@
 // the tenant and policy envelope has to be un-bypassable — every statement it emits is built on
 // `conditionsSql`, and the fusion happens in SQL rather than after the rows are already loaded.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import { type DbClient, db, type SqlFragment } from '@ultimat3/db';
 import { VectorDimMismatchError } from './errors';
 import {
@@ -36,6 +37,9 @@ export interface PgVectorStoreInput {
   readonly scope?: VectorScope | undefined;
 }
 
+/** Named in every bound refusal here, matching `vector.ts`: one store contract, one subject. */
+const HYBRID = 'hybrid search';
+
 /** The row every statement projects. `metadata` arrives as jsonb; drivers differ on parsing it. */
 interface HitRow {
   readonly id: string;
@@ -103,7 +107,12 @@ export class PgVectorStore implements VectorStore {
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
     this.assertDimension(vector.length);
-    return this.run(searchSql(this.target, vector, { scope: this.scope, filter, k }));
+    // `k` is the statement's `limit` and reaches Postgres as a bound parameter, so a `NaN` is the
+    // database's error to report rather than this store's — and a fractional one is an error there
+    // too. Refused here instead, before a connection is taken, naming the argument the caller wrote.
+    return this.run(
+      searchSql(this.target, vector, { scope: this.scope, filter, k: finiteCount(HYBRID, 'k', k) }),
+    );
   }
 
   async searchText(
@@ -111,17 +120,24 @@ export class PgVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
-    return this.run(textSql(this.target, query, { scope: this.scope, filter, k }));
+    return this.run(
+      textSql(this.target, query, { scope: this.scope, filter, k: finiteCount(HYBRID, 'k', k) }),
+    );
   }
 
   async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
     this.assertDimension(input.vector.length);
+    // The same three bounds `MemoryVectorStore.hybrid` screens, and they have to be screened in
+    // BOTH stores: `rrfK` lands in `1.0 / (rrfK + rank)`, Postgres has a float8 `NaN`, and it
+    // sorts as the LARGEST value — so every fused score ties, the order collapses to the `id`
+    // tiebreak, and the fusion this method exists for is gone with nothing raised anywhere.
+    const k = finiteCount(HYBRID, 'k', input.k);
     const args: PgHybridArgs = {
       scope: this.scope,
       filter: input.filter,
-      k: input.k,
-      candidates: input.candidates ?? Math.max(input.k * 4, 20),
-      rrfK: input.rrfK ?? 60,
+      k,
+      candidates: finiteCount(HYBRID, 'candidates', input.candidates ?? Math.max(k * 4, 20)),
+      rrfK: finiteOption(HYBRID, 'rrfK', input.rrfK ?? 60),
     };
     return this.run(hybridSql(this.target, input.query, input.vector, args));
   }

package/src/rag.ts

@@ -4,6 +4,7 @@
 // discover at request time that they don't fit is a truncation bug waiting to happen; the
 // assembler fills to a declared ceiling and reports what it dropped.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { embedBatched, embedOne } from './embeddings';
 import { estimateTextTokens as estimateChunkTokens } from './provider';
@@ -34,8 +35,14 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
   // Floored at one token: `size: 0` makes every comparison below meaningless and the wrap's cut
   // point zero-width, which is a loop that never advances rather than a chunker that produces
   // nothing. A budget under one token is not a budget.
-  const size = Math.max(1, Math.floor(input.size ?? 512));
-  const overlap = Math.min(input.overlap ?? 64, size - 1);
+  //
+  // The floor is not a SCREEN, and that is a separate line for a separate reason: `Math.max` and
+  // `Math.floor` both propagate a `NaN`, so `size: NaN` walked past both, made `<= size` false at
+  // every cut point and put `cutToBudget` in a loop with no exit — measured, a SYNCHRONOUS spin
+  // past every `AbortSignal`, on a worker's only thread. `finiteOption` and not `finiteCount`,
+  // because the `Math.floor` above is a deliberate acceptance of a fractional budget.
+  const size = Math.max(1, Math.floor(finiteOption('chunk', 'size', input.size ?? 512)));
+  const overlap = Math.min(finiteOption('chunk', 'overlap', input.overlap ?? 64), size - 1);
   const units = splitUnits(input.text, size);
   const chunks: Chunk[] = [];
   let buffer: string[] = [];
@@ -196,7 +203,10 @@ export interface RetrieveInput {
 
 /** Hybrid retrieval then rerank. Hybrid by default because pure vector loses on exact terms. */
 export async function retrieve(input: RetrieveInput): Promise<readonly SearchHit[]> {
-  const k = input.k ?? 8;
+  // Screened here as well as in the store, so the refusal names the argument this caller wrote
+  // rather than the `k * 3` it becomes: `k: NaN` retrieved nothing and reported a successful
+  // retrieval of zero documents, which downstream is an answer given with no context at all.
+  const k = finiteCount('retrieve', 'k', input.k ?? 8);
   const vector = await embedOne(input.embedder, input.query);
   const hits = await input.store.hybrid({
     query: input.query,
@@ -248,6 +258,10 @@ export function assembleContext(input: {
   /** Between BLOCKS, never inside one — the block fence is what separates documents. */
   readonly separator?: string;
 }): AssembledContext {
+  // The one bound in this function, and it carries no default — so nothing screened it: `tokens +
+  // cost > NaN` is false for every hit, every document is accepted, and the ceiling that exists to
+  // keep an assembled context inside the model's window stops existing while `dropped` stays empty.
+  const maxTokens = finiteCount('assembleContext', 'maxTokens', input.maxTokens);
   const separator = input.separator ?? '\n\n';
   const separatorTokens = estimateChunkTokens(separator);
   const parts: string[] = [];
@@ -258,7 +272,7 @@ export function assembleContext(input: {
   for (const hit of input.hits) {
     const block = documentBlock(hit.id, hit.text);
     const cost = estimateChunkTokens(block) + (parts.length === 0 ? 0 : separatorTokens);
-    if (tokens + cost > input.maxTokens) {
+    if (tokens + cost > maxTokens) {
       dropped.push(hit.id);
       continue;
     }

package/src/remote-embedder.ts

@@ -6,7 +6,7 @@
 // vendor: `baseUrl` selects the provider and nothing else changes. A second class per vendor
 // would be a second thing to learn for a difference that does not exist on the wire.
 
-import { readWithinLimit, renderThrowable } from '@ultimat3/core';
+import { finiteCount, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { normalize } from './embeddings';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
@@ -25,6 +25,8 @@ const DETAIL_LIMIT = 300;
  */
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+/** Named in every bound refusal, so the fix names the constructor argument the app wrote. */
+const SUBJECT = 'RemoteEmbedder';
 
 export interface RemoteEmbedderInput {
   /** The provider's model id. Doubles as the embedder name, so a store records what wrote it. */
@@ -52,10 +54,33 @@ export class RemoteEmbedder implements Embedder {
   readonly name: string;
   readonly dimension: number;
   private readonly config: RemoteEmbedderInput;
+  /**
+   * The three numeric bounds, resolved and SCREENED once when the embedder is built rather than
+   * read fresh per batch. Each of the three failed differently and none of them raised anything a
+   * caller could act on: `batchSize: 0` never advanced the loop and issued the same empty request
+   * to a paid endpoint forever, `batchSize: NaN` sent ONE request of zero inputs and answered zero
+   * vectors for however many texts it was handed, `timeoutMs: NaN` threw a `TypeError` out of
+   * `AbortSignal.timeout` that this file's own `catch` re-dressed as `X_AI_PROVIDER_UNAVAILABLE` —
+   * a config typo reported as a transport failure, which the gateway then RETRIES — and
+   * `maxResponseBytes: NaN` reached core's reader, which refuses it correctly but only after the
+   * request has been paid for, in a message about `readWithinLimit` rather than about this option.
+   */
+  private readonly batchSize: number;
+  private readonly timeoutMs: number;
+  private readonly maxResponseBytes: number;
 
   constructor(input: RemoteEmbedderInput) {
     this.name = input.name;
-    this.dimension = input.dimension;
+    this.dimension = finiteCount(SUBJECT, 'dimension', input.dimension, 1);
+    this.batchSize = finiteCount(SUBJECT, 'batchSize', input.batchSize ?? DEFAULT_BATCH_SIZE, 1);
+    // A floor of 1 rather than 0: `AbortSignal.timeout(0)` aborts on the next tick, so a zero here
+    // is not "no deadline" — it is every request failing before the socket is even opened.
+    this.timeoutMs = finiteCount(SUBJECT, 'timeoutMs', input.timeoutMs ?? DEFAULT_TIMEOUT_MS, 1);
+    this.maxResponseBytes = finiteCount(
+      SUBJECT,
+      'maxResponseBytes',
+      input.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
+    );
     this.config = input;
   }
 
@@ -65,7 +90,7 @@ export class RemoteEmbedder implements Embedder {
    */
   async embed(texts: readonly string[]): Promise<readonly Float32Array[]> {
     if (texts.length === 0) return [];
-    const size = this.config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const size = this.batchSize;
     const vectors: Float32Array[] = [];
     for (let start = 0; start < texts.length; start += size) {
       vectors.push(...(await this.batch(texts.slice(start, start + size))));
@@ -79,7 +104,7 @@ export class RemoteEmbedder implements Embedder {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
     }
     const doFetch: AiFetch = this.config.fetch ?? fetch;
-    const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutMs = this.timeoutMs;
     const url = `${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`;
     let response: Response;
     try {
@@ -113,7 +138,7 @@ export class RemoteEmbedder implements Embedder {
     }
     // Read through core's counting reader rather than `response.json()`: a body is buffered whole
     // before anything measures it otherwise, and a `content-length` a remote wrote is not a bound.
-    const maxBytes = this.config.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const maxBytes = this.maxResponseBytes;
     const read = await readWithinLimit(response.body, maxBytes);
     if ('over' in read) {
       throw new AiTransportError({

package/src/scorers.ts

@@ -4,6 +4,7 @@
 // is a model call, which means it is itself a measuring instrument that can drift — so its
 // prompt is a versioned artifact and its hash is part of the scorer's name.
 
+import { finiteCount } from '@ultimat3/core';
 import type { Gateway } from './gateway';
 import type { Prompt } from './prompt';
 
@@ -109,7 +110,10 @@ export function llmJudge(input: {
             content: input.judge.render({ output, expected: expected ?? '' }),
           },
         ],
-        maxTokens: input.maxTokens ?? 256,
+        // Same rule as every other completion ceiling here, and this one is read per SCORE: a
+        // `NaN` reaches the gateway as the estimate, and an estimate that is not a number turns
+        // the ambient budget off rather than exceeding it.
+        maxTokens: finiteCount('llmJudge', 'maxTokens', input.maxTokens ?? 256, 1),
         ...(input.judge.system !== undefined ? { system: input.judge.system } : {}),
         ...(input.judge.model !== undefined ? { model: input.judge.model } : {}),
         // The judge prompt's hash is this scorer's NAME, and `contentHash` covers `effort` and

package/src/vector.ts

@@ -8,6 +8,7 @@
 // Reciprocal-rank fusion combines the two rankings without needing the two score scales to
 // be comparable — which they never are.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import { cosine, tokenize } from './embeddings';
 import { VectorDimMismatchError } from './errors';
 import { NO_TENANT, narrowScope, scopeAdmits, UNSCOPED, type VectorScope } from './vector-scope';
@@ -69,6 +70,12 @@ export interface MemoryVectorStoreInput {
   readonly records?: Map<string, StoredRecord>;
 }
 
+/** Named in every bound refusal below, so a caller knows which call it is about to edit. */
+const SUBJECT = 'MemoryVectorStore';
+
+/** The same subject for the hybrid read, whose options are the caller's per-call arguments. */
+const HYBRID = 'hybrid search';
+
 /** A record plus the tenant it was written under — the in-memory twin of the `tenant` column. */
 export interface StoredRecord extends VectorRecord {
   readonly tenant: string;
@@ -89,8 +96,12 @@ export class MemoryVectorStore implements VectorStore {
     this.dimension = input.dimension;
     this.scope = input.scope ?? UNSCOPED;
     this.records = input.records ?? new Map<string, StoredRecord>();
-    this.k1 = input.k1 ?? 1.2;
-    this.b = input.b ?? 0.75;
+    // Screened, not clamped: a `NaN` here makes every BM25 score `NaN`, `hit.score > 0` reads
+    // false for every document, and `searchText` answers an empty list — zero work reported as a
+    // successful search. `finiteOption` and not `finiteCount`, because both are tuning constants
+    // and fractional by nature (1.2 and 0.75 are the values the BM25 paper settled on).
+    this.k1 = finiteOption(SUBJECT, 'k1', input.k1 ?? 1.2);
+    this.b = finiteOption(SUBJECT, 'b', input.b ?? 0.75);
   }
 
   /**
@@ -119,10 +130,12 @@ export class MemoryVectorStore implements VectorStore {
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
     this.assertDimension(vector.length);
+    // `k` carries no default, so `??` never sees it and nothing else does either: `slice(0, NaN)`
+    // is `[]`, which is a search that answers "no matches" for every query and reports success.
     return this.candidates(filter)
       .map((record) => this.hit(record, cosine(vector, record.vector)))
       .sort(byScoreDesc)
-      .slice(0, k);
+      .slice(0, finiteCount(SUBJECT, 'k', k));
   }
 
   /** BM25 over the stored text. Real lexical scoring, so a rare exact term actually wins. */
@@ -131,6 +144,7 @@ export class MemoryVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    const width = finiteCount(SUBJECT, 'k', k);
     const candidates = this.candidates(filter);
     if (candidates.length === 0) return [];
     const docs = candidates.map((record) => ({ record, tokens: tokenize(record.text) }));
@@ -152,7 +166,7 @@ export class MemoryVectorStore implements VectorStore {
       })
       .filter((hit) => hit.score > 0)
       .sort(byScoreDesc)
-      .slice(0, k);
+      .slice(0, width);
   }
 
   /**
@@ -161,13 +175,17 @@ export class MemoryVectorStore implements VectorStore {
    * by exact term match beats one that merely leads a flat vector ranking.
    */
   async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
-    const width = input.candidates ?? Math.max(input.k * 4, 20);
-    const rrfK = input.rrfK ?? 60;
+    // Three bounds, none of which `Math.max` screens — it PROPAGATES a `NaN`. A `NaN` `k` collapses
+    // both candidate widths and the final slice to `[]`; a `NaN` `rrfK` makes every fused score
+    // `NaN`, and the ranking this method exists to produce becomes whatever order the sort left.
+    const k = finiteCount(HYBRID, 'k', input.k);
+    const width = finiteCount(HYBRID, 'candidates', input.candidates ?? Math.max(k * 4, 20));
+    const rrfK = finiteOption(HYBRID, 'rrfK', input.rrfK ?? 60);
     const [dense, lexical] = await Promise.all([
       this.search(input.vector, width, input.filter),
       this.searchText(input.query, width, input.filter),
     ]);
-    return fuse([dense, lexical], rrfK).slice(0, input.k);
+    return fuse([dense, lexical], rrfK).slice(0, k);
   }
 
   /** Scoped, exactly like the SQL `delete ... where id in (...) and <scope>`. */
@@ -203,8 +221,17 @@ export class MemoryVectorStore implements VectorStore {
   }
 }
 
-/** Fuse ranked lists by reciprocal rank. Exported so a reranker can reuse it. */
-export function fuse(rankings: readonly (readonly SearchHit[])[], rrfK = 60): readonly SearchHit[] {
+/**
+ * Fuse ranked lists by reciprocal rank. Exported so a reranker can reuse it — which is why the
+ * damping is screened HERE too and not only in `hybrid`: a default parameter is a bound like any
+ * other, and `1 / (NaN + rank)` scores every document `NaN`, so the fused order is no longer a
+ * ranking while every caller still reads a full result list.
+ */
+export function fuse(
+  rankings: readonly (readonly SearchHit[])[],
+  rrfK: number = 60,
+): readonly SearchHit[] {
+  finiteOption('fuse', 'rrfK', rrfK);
   const scores = new Map<string, number>();
   const hits = new Map<string, SearchHit>();
   for (const ranking of rankings) {