@ultimat3/ai 24.0.0 → 25.1.0

package/src/echo-provider.ts

@@ -0,0 +1,102 @@
+// `EchoProvider`: the deterministic `Provider` tests, evals and `x dev` without a key run on. Apart
+// from ./provider, which owns the real Messages API, because a double and the socket it stands in
+// for are two jobs — and the request half had reached its line ceiling holding both.
+
+import { resolveModel } from './model-resolve';
+import type { ModelId } from './models';
+import { modelIds } from './models';
+import type {
+  AiMessage,
+  GenerateRequest,
+  GenerateResult,
+  Provider,
+  StreamChunk,
+  TokenUsage,
+} from './provider';
+import { costOf, estimateTextTokens, estimateTokens, messageText } from './provider';
+
+export interface EchoProviderInput {
+  /** Fixed replies keyed by the last user message, for eval fixtures. */
+  readonly replies?: Readonly<Record<string, string>>;
+  /** Fallback when no key matches. Defaults to echoing the last user message. */
+  readonly fallback?: (prompt: string) => string;
+  readonly tokensPerCall?: number;
+}
+
+/** The deterministic test provider — the one way to build one; the class is a type only. */
+export function echoProvider(config: EchoProviderInput = {}): EchoProvider {
+  return new EchoProvider(config);
+}
+
+/**
+ * Deterministic provider. Same input, same output, same usage — which is what makes an eval
+ * suite a test rather than a sample. Token counts are derived from length, so a budget test
+ * can assert a refusal without a network.
+ */
+export class EchoProvider implements Provider {
+  readonly name = 'echo';
+  /**
+   * A getter over the whole registry, not a snapshot: the test double has to serve whatever the
+   * test registered, and a field read at construction time would miss a model registered after.
+   */
+  get models(): readonly ModelId[] {
+    return modelIds();
+  }
+
+  private readonly config: EchoProviderInput;
+
+  constructor(config: EchoProviderInput = {}) {
+    this.config = config;
+  }
+
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    // No model of its own: the double must not choose one for an app any more than the real
+    // providers do. The gateway resolves before it routes; a direct call names one or is refused.
+    const model = resolveModel('echo-provider', request.model);
+    const prompt = lastUserMessage(request.messages);
+    const text = this.fixedReply(prompt) ?? this.config.fallback?.(prompt) ?? prompt;
+    const usage: TokenUsage = {
+      inputTokens: this.config.tokensPerCall ?? estimateTokens({ ...request, model }),
+      outputTokens: estimateTextTokens(text),
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    };
+    return {
+      model,
+      text,
+      toolCalls: [],
+      stopReason: 'end_turn',
+      stopDetails: undefined,
+      usage,
+      cost: costOf(model, usage),
+    };
+  }
+
+  /**
+   * The fixture reply for this prompt. `Object.hasOwn`, never `replies?.[prompt]`: the key is
+   * MESSAGE TEXT, so a prompt of `toString` read a function off the prototype chain and returned
+   * it as the model's answer — a double that answers with JS source is worse than one that cannot.
+   */
+  private fixedReply(prompt: string): string | undefined {
+    const { replies } = this.config;
+    if (replies === undefined || !Object.hasOwn(replies, prompt)) return undefined;
+    return replies[prompt];
+  }
+
+  async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
+    const result = await this.generate(request);
+    // One word per chunk: enough to exercise a consumer's assembly logic.
+    for (const word of result.text.split(' ')) {
+      if (word !== '') yield { type: 'text', text: `${word} ` };
+    }
+    yield { type: 'done', result };
+  }
+}
+
+function lastUserMessage(messages: readonly AiMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (message !== undefined && message.role === 'user') return messageText(message);
+  }
+  return '';
+}

package/src/embeddings.ts

@@ -64,6 +64,11 @@ export interface HashEmbedderInput {
   readonly dimension?: number;
 }
 
+/** The hashing embedder — the one way to build one; the class is a type only. */
+export function hashEmbedder(input: HashEmbedderInput = {}): HashEmbedder {
+  return new HashEmbedder(input);
+}
+
 /**
  * Deterministic bag-of-words hashing embedder. Not semantic — two paraphrases share no
  * vocabulary and land far apart — but it IS stable, dependency-free, and fast, which is
@@ -76,7 +81,7 @@ export class HashEmbedder implements Embedder {
 
   constructor(input: HashEmbedderInput = {}) {
     // 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 —
+    // empty, `cosine` answers `NaN` 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);
   }
@@ -87,19 +92,19 @@ export class HashEmbedder implements Embedder {
 
   private one(text: string): Float32Array {
     const vector = new Float32Array(this.dimension);
-    for (const token of tokenize(text)) {
+    for (const token of wordTokens(text)) {
       const slot = hashOf(token) % this.dimension;
       // Signed accumulation: without it every vector is non-negative and cosine
       // similarity compresses into a narrow band where nothing ranks apart.
       const sign = hashOf(`${token}#sign`) % 2 === 0 ? 1 : -1;
       vector[slot] = (vector[slot] ?? 0) + sign;
     }
-    return normalize(vector);
+    return normalizeVector(vector);
   }
 }
 
 /** Lowercased word tokens. Punctuation is dropped; digits are kept (versions, ids). */
-export function tokenize(text: string): readonly string[] {
+export function wordTokens(text: string): readonly string[] {
   return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
 }
 
@@ -112,8 +117,8 @@ function hashOf(text: string): number {
   return Number.parseInt(fingerprint(text).slice(0, 8), 16);
 }
 
-/** L2 normalise in place so cosine similarity reduces to a dot product. */
-export function normalize(vector: Float32Array): Float32Array {
+/** L2 normalise in place, so every embedder hands a store unit vectors whatever its scale. */
+export function normalizeVector(vector: Float32Array): Float32Array {
   let sum = 0;
   for (const value of vector) sum += value * value;
   if (sum === 0) return vector;
@@ -122,10 +127,25 @@ export function normalize(vector: Float32Array): Float32Array {
   return vector;
 }
 
-/** Dot product. Correct as cosine only for normalised vectors — which `normalize` ensures. */
+/**
+ * Cosine similarity — pgvector's `1 - (a <=> b)`, computed the way pgvector computes it, so the dev
+ * store and production rank alike. A bare dot product was cosine only for unit vectors, and a
+ * store accepts whatever an app upserts. A zero-norm side is `0 / 0`: `NaN`, as pgvector answers,
+ * never a `0` that would rank a vector with no direction above every opposed one. Clamped to
+ * [-1, 1] as pgvector clamps, so float error never reports a similarity past identical.
+ */
 export function cosine(a: Float32Array, b: Float32Array): number {
-  let sum = 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
   const length = Math.min(a.length, b.length);
-  for (let i = 0; i < length; i += 1) sum += (a[i] ?? 0) * (b[i] ?? 0);
-  return sum;
+  for (let i = 0; i < length; i += 1) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  const similarity = dot / Math.sqrt(normA * normB);
+  return similarity > 1 ? 1 : similarity < -1 ? -1 : similarity;
 }

package/src/errors.ts

@@ -28,6 +28,8 @@ export const AI_ERROR_CODES = [
   'X_VECTOR_SCOPE_WIDENED',
   'X_AI_EMBEDDER_INVALID',
   'X_VECTOR_UNSCOPED',
+  'X_AI_CONTENT_UNSUPPORTED',
+  'X_AI_MODEL_UNRESOLVED',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -57,6 +59,8 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_VECTOR_SCOPE_WIDENED: 'a derived vector scope tried to leave its tenant',
   X_AI_EMBEDDER_INVALID: 'an Embedder returned fewer vectors than texts it was given',
   X_VECTOR_UNSCOPED: 'a vector store was read with no tenant bound inside an org request',
+  X_AI_CONTENT_UNSUPPORTED: 'an image or document block the role, model or wire format cannot take',
+  X_AI_MODEL_UNRESOLVED: 'a model call named no model',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and
@@ -130,25 +134,27 @@ export class AiGatewayMissingError extends UltimateError {
   constructor(input: { prompt: string }) {
     super({
       code: 'X_AI_GATEWAY_MISSING',
-      cause: `an llm action on prompt "${input.prompt}" ran before any gateway was configured`,
-      fix: 'configureAi({ gateway: createGateway({ providers: [new AnthropicProvider()] }) }) at boot',
+      // The provider is the app's choice, so no vendor is the default (M12): the fix is the shape
+      // and the cause names what `provider` is — one of the peers, or the app's own.
+      cause: `an llm action on prompt "${input.prompt}" ran before any gateway was configured (provider: anthropicProvider({ models }) for the Anthropic Messages format, openAiProvider({ baseUrl, models }) for the OpenAI chat-completions format on any compatible server, or your own Provider)`,
+      fix: 'configureAi({ gateway: providerGateway({ providers: [provider] }) }) at boot',
     });
   }
 }
 
 /**
- * A model id nothing put in the catalogue. This is what replaced the closed `ModelId` union: the
- * union made a company's own model id inexpressible, so the only way past `tsc` was to claim a
- * Claude id — and then `costOf` priced an internal model at Anthropic list rates and the budget
- * ledger reserved against a number belonging to a model nobody ran. A wrong id is still refused;
- * it is refused HERE, at the first read of the spec, instead of by making a right one impossible.
+ * A model id the app never registered. The framework registers none, so every id a call names —
+ * any vendor's — is one the app's own `registerModel` wrote: priced, reserved and recorded by the
+ * app's numbers, never by a list this package shipped. Refused HERE, at the first read of the spec
+ * (`costOf`, the budget's estimate, the request builders), before anything is sent or charged.
  */
 export class AiModelUnknownError extends UltimateError {
   constructor(input: { model: string; registered: readonly string[] }) {
     super({
       code: 'X_AI_MODEL_UNKNOWN',
       cause:
-        `model "${input.model}" has no registered spec, so nothing can price it ` +
+        `model "${input.model}" has no registered spec, so nothing can price or budget it — ` +
+        `the framework registers no model of its own ` +
         `(registered: ${input.registered.length > 0 ? input.registered.join(', ') : 'none'})`,
       // The `errors` gate blanks every interpolation, so the literal half alone has to name the
       // call. Which ids ARE registered is a fact of the failure, and cause is where facts live.
@@ -261,8 +267,8 @@ export class LlmRefusedError extends UltimateError {
     prompt: string;
     model: string;
     /**
-     * A blessed model MORE capable than the one that refused, or `undefined` when the refusal
-     * came from the most capable one this build knows. Retrying a refusal on a weaker model is
+     * A model the APP registered, in the same family, MORE capable than the one that refused —
+     * or `undefined` when the app registered none above it. Retrying a refusal on a weaker model is
      * the one retry that cannot help, so the fix line drops the suggestion rather than inventing
      * a downgrade.
      */
@@ -278,7 +284,7 @@ export class LlmRefusedError extends UltimateError {
         `${input.explanation === undefined ? '' : `: ${input.explanation}`}`,
       fix:
         input.alternative === undefined
-          ? `edit the template in definePrompt('${input.prompt}') and bump its version — no blessed model is more capable than '${input.model}'`
+          ? `edit the template in definePrompt('${input.prompt}') and bump its version — no model your app registered in its family is more capable than '${input.model}'`
           : `set model: '${input.alternative}' on the llm() declaration, or edit the template in definePrompt('${input.prompt}') and bump its version`,
       meta: { model: input.model, category: input.category },
     });

package/src/eval-errors.ts

@@ -61,7 +61,9 @@ export class EvalBaselineInvalidError extends UltimateError {
     super({
       code: 'X_EVAL_BASELINE_INVALID',
       cause: `the recorded baseline ${input.path} ${input.problem}`,
-      fix: `ULTIMATE_EVAL_RECORD=1 x test eval to re-record ${input.path}`,
+      // The command is the record run; the path is named behind the `#`, where it is read and
+      // never run — `x test eval` takes no path, and a file name may carry `$(…)` (sweep 1c).
+      fix: `ULTIMATE_EVAL_RECORD=1 x test eval   # re-records ${input.path}`,
     });
   }
 }

package/src/evals.ts

@@ -187,7 +187,7 @@ async function runEval<V extends PromptVars>(
       ...(input.prompt.system !== undefined ? { system: input.prompt.system } : {}),
       ...(input.prompt.model !== undefined ? { model: input.prompt.model } : {}),
       ...(input.prompt.effort !== undefined ? { effort: input.prompt.effort } : {}),
-      // `thinking` too, and not because it is tidy: `contentHash` covers it, so the baseline is
+      // `thinking` too, and not because it is tidy: `promptHash` covers it, so the baseline is
       // filed under a hash describing a configuration the measurement did not use. `llm()` and
       // `agent()` have always sent both.
       ...(input.prompt.thinking !== undefined ? { thinking: input.prompt.thinking } : {}),

package/src/failure-disclosure.ts

@@ -0,0 +1,90 @@
+// The one rule for what of a thrown value a remote reader may see: an LLM tool result and a hive
+// member's reason both reach someone outside this process, so both ask this file — and the half
+// it withholds goes to the log as content-free facts (code, name, frames) — never its text.
+
+import type { Logger } from '@ultimat3/core';
+import { hasPublicCause, isUltimateError, stringField } from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
+
+/**
+ * What may be shown. `code` is absent for an uncoded throw — a foreign `.message` is the server's
+ * (a pg `Key (email)=(…)`), so nothing of it is carried. `cause` is absent when it is withheld:
+ * the caller substitutes its own fixed sentence, because who is reading decides the wording.
+ */
+export interface DisclosedFailure {
+  readonly code: string | undefined;
+  readonly cause: string | undefined;
+  readonly fix: string | undefined;
+}
+
+/**
+ * Read STRUCTURALLY and totally — `stringField`, never `typeof e.code` or `.message`: the value is
+ * whatever an app's handler, its driver or its SDK threw, so each read is a getter call or a
+ * `Proxy` trap, and this runs inside a catch block with nothing left to answer if a probe raises.
+ *
+ * A 5xx code's cause is shown only when core's `hasPublicCause` allows it — the rule a production
+ * problem document follows (`@ultimat3/http`'s `toProblem`). Hidden, the developer's `fix` goes
+ * with it (a driver writes it from the statement it failed on); a `callerFix` an `UltimateError`
+ * built in this process is authored for a remote reader and stays.
+ */
+export function discloseFailure(
+  error: unknown,
+  logger: Logger | undefined,
+  where: string,
+): DisclosedFailure {
+  const code = stringField(error, 'code');
+  if (code === undefined) return withheld(error, logger, where, undefined, undefined);
+  if (statusFor(code) >= 500 && !hasPublicCause(code)) {
+    const callerFix = isUltimateError(error) ? stringField(error, 'callerFix') : undefined;
+    return withheld(error, logger, where, code, callerFix);
+  }
+  const fix = stringField(error, 'fix');
+  return {
+    code,
+    cause: stringField(error, 'cause') ?? 'unknown',
+    fix: fix === undefined || fix === '' ? undefined : fix,
+  };
+}
+
+/**
+ * A stack's FRAMES and nothing else: every line that is a frame (`    at …`), none that is not.
+ * The message is the first line — and, when it spans several, the lines after it until the first
+ * frame — so keeping only frame-shaped lines drops all of it, whatever it held. A frame is code
+ * position, which carries no caller data.
+ */
+const FRAME = /^\s+at\s/;
+
+function framesOf(error: unknown): string | null {
+  const stack = stringField(error, 'stack');
+  if (stack === undefined) return null;
+  const lines = stack.split('\n');
+  // Skip to the first frame line that FOLLOWS the message: a message may itself contain text
+  // shaped like a frame, and only lines after the message block are the stack.
+  const message = stringField(error, 'message') ?? '';
+  const skip = message === '' ? 1 : message.split('\n').length;
+  const frames = lines.slice(skip).filter((line) => FRAME.test(line));
+  return frames.length === 0 ? null : frames.join('\n');
+}
+
+/**
+ * The withheld half, logged as FACTS ONLY — the code, the error's name, and its frames. Never the
+ * message and never the cause: the logger redacts by field NAME, not by content, so a pg
+ * `Key (email)=(ceo@corp.com)` logged as text reached the logs whole. What identifies the failure
+ * is the code and where it was thrown, both of which survive this.
+ */
+function withheld(
+  error: unknown,
+  logger: Logger | undefined,
+  where: string,
+  code: string | undefined,
+  fix: string | undefined,
+): DisclosedFailure {
+  logger?.error('ai.failure.withheld', {
+    where,
+    code: code ?? 'uncoded',
+    // `name`, read structurally: what kind of throw it was (`Error`, `TypeError`, a driver's own).
+    name: stringField(error, 'name') ?? typeof error,
+    frames: framesOf(error),
+  });
+  return { code, cause: undefined, fix };
+}

package/src/gateway.ts

@@ -17,10 +17,16 @@ import {
 } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { BudgetKeys, BudgetLimits, BudgetStore } from './budget';
-import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
+import {
+  assertFiniteLimits,
+  BudgetLedger,
+  currentBudget,
+  estimateSpend,
+  withBudget,
+} from './budget';
 import { AiProviderUnavailableError } from './errors';
+import { resolveModel } from './model-resolve';
 import type { ModelId } from './models';
-import { DEFAULT_MODEL } from './models';
 import type { GenerateRequest, GenerateResult, Provider, StreamChunk } from './provider';
 
 /**
@@ -34,7 +40,7 @@ export interface GatewayCache {
 
 /**
  * A gateway's retry budget. NOT core's `RetryPolicy`, and deliberately still its own declaration:
- * these three field names are what an app writes in `createGateway({ retry })`, so renaming them
+ * these three field names are what an app writes in `providerGateway({ retry })`, so renaming them
  * onto `base`/`max`/`jitter` would break every caller for no behaviour. What WAS a duplicate is the
  * arithmetic, and that is gone — `backoffMs` is core's `backoffDelay` with this shape mapped onto
  * it, so there is one curve in the framework and one place a jitter bug can live.
@@ -47,12 +53,16 @@ export interface RetryPolicy {
   readonly maxDelayMs: number;
 }
 
-export const DEFAULT_RETRY: RetryPolicy = { attempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 };
+export const DEFAULT_GATEWAY_RETRY: RetryPolicy = {
+  attempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 8_000,
+};
 
 /** The one code `attempt` may collect into. Every other coded refusal is the caller's answer. */
 const PROVIDER_UNAVAILABLE = 'X_AI_PROVIDER_UNAVAILABLE';
 
-export interface CreateGatewayInput {
+export interface ProviderGatewayInput {
   /** Tried in order for a given model. First provider that lists the model wins. */
   readonly providers: readonly Provider[];
   readonly budget?: BudgetLimits;
@@ -72,6 +82,13 @@ export interface CreateGatewayInput {
 }
 
 export interface Gateway {
+  /**
+   * The model a call with none declared runs on — `providerGateway({ defaultModel })`. Read by
+   * `llm()` and `agent()` after the declaration and its prompt, so the app's choice is the one
+   * fallback; absent, a call naming no model is refused (`X_AI_MODEL_UNRESOLVED`) — never routed to
+   * a vendor the framework picked.
+   */
+  readonly defaultModel?: ModelId | undefined;
   generate(request: GenerateRequest): Promise<GenerateResult>;
   stream(request: GenerateRequest): AsyncIterable<StreamChunk>;
   /** Open a budget scope. Nested gateway calls inside `fn` share one ledger. */
@@ -87,36 +104,43 @@ export interface Gateway {
   callLedger(keys: BudgetKeys): BudgetLedger;
 }
 
-export function createGateway(input: CreateGatewayInput): Gateway {
+export function providerGateway(input: ProviderGatewayInput): Gateway {
   return new GatewayImpl(input);
 }
 
 class GatewayImpl implements Gateway {
-  private readonly config: CreateGatewayInput;
+  private readonly config: ProviderGatewayInput;
   private readonly retry: RetryPolicy;
   private readonly sleep: (ms: number) => Promise<void>;
   /** Left `undefined` rather than defaulted, so `backoffDelay` owns the one fallback to `Math.random`. */
   private readonly random: Random | undefined;
 
-  constructor(config: CreateGatewayInput) {
+  get defaultModel(): ModelId | undefined {
+    return this.config.defaultModel;
+  }
+
+  constructor(config: ProviderGatewayInput) {
     this.config = config;
-    this.retry = config.retry ?? DEFAULT_RETRY;
+    this.retry = config.retry ?? DEFAULT_GATEWAY_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
+    // model <id> ()" 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);
+    finiteCount('gateway', 'retry.attempts', this.retry.attempts, 1);
+    // Screened here, under the config's own key, rather than by the ledger `callLedger` builds:
+    // that refused on the first CALL and named `the AI budget`, not the `gateway` to edit.
+    if (config.budget !== undefined) assertFiniteLimits(config.budget, 'gateway', 'budget.');
     this.sleep = config.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     this.random = config.random;
   }
 
   /**
    * `budget` held with no scope open. It was enforced ONLY inside `scope()`, which nothing in the
-   * framework calls — so `createGateway({ budget: { request: 100 } })` capped no call any app made.
+   * framework calls — so `providerGateway({ budget: { request: 100 } })` capped no call any app made.
    * A raw `generate` / `stream` outside any scope passes no keys: it has no caller to count.
    */
   callLedger(keys: BudgetKeys): BudgetLedger {
@@ -139,10 +163,10 @@ class GatewayImpl implements Gateway {
   }
 
   async generate(request: GenerateRequest): Promise<GenerateResult> {
-    const model = request.model ?? this.config.defaultModel ?? DEFAULT_MODEL;
+    const model = resolveModel('gateway', request.model, this.config.defaultModel);
     const resolved: GenerateRequest = { ...request, model, maxTokens: ceilingOf(request) };
 
-    const cacheKey = cacheKeyFor(resolved);
+    const cacheKey = promptCacheKey(resolved);
     const cached = await this.config.cache?.get(cacheKey);
     if (cached !== undefined) {
       // A cache hit costs nothing, so it is deliberately NOT debited from the budget.
@@ -186,7 +210,7 @@ class GatewayImpl implements Gateway {
   }
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
-    const model = request.model ?? this.config.defaultModel ?? DEFAULT_MODEL;
+    const model = resolveModel('gateway', request.model, this.config.defaultModel);
     const resolved: GenerateRequest = { ...request, model, maxTokens: ceilingOf(request) };
 
     // Routed BEFORE the reservation, not after it. `providerFor` throws for a registered model no
@@ -382,7 +406,7 @@ export function isRetryable(error: unknown): boolean {
  * after the schema changed. Core's `fingerprint`, so key order never splits one request in two and
  * the width is the one every other sharing key in the framework has.
  */
-export function cacheKeyFor(request: GenerateRequest): string {
+export function promptCacheKey(request: GenerateRequest): string {
   return fingerprint({
     model: request.model,
     system: request.system ?? '',

package/src/hive-pool.ts

@@ -5,7 +5,8 @@
 // happens to the siblings when one throws". Nothing here knows what a model is.
 
 import type { Ctx } from '@ultimat3/core';
-import { isThrownError, isUltimateError, stringField, withChildContext } from '@ultimat3/core';
+import { withChildContext } from '@ultimat3/core';
+import { discloseFailure } from './failure-disclosure';
 import type { HiveMember, HiveMemberError } from './hive-result';
 import { SKIPPED_ABORTED, SKIPPED_NO_INPUT } from './hive-result';
 
@@ -57,7 +58,7 @@ export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly Hi
         );
         members[index] = { status: 'ok', index, value };
       } catch (error) {
-        members[index] = { status: 'failed', index, ...failureOf(error) };
+        members[index] = { status: 'failed', index, ...failureOf(error, ctx, index) };
         if (input.onMemberError === 'abort') controller.abort();
       }
     }
@@ -72,19 +73,26 @@ export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly Hi
 }
 
 /**
- * What a member threw, as two data fields — never as an error's `cause:`, which is why the thrown
- * value is read structurally and never interpolated. A foreign throw gets `'unknown'` rather than
- * an invented `X_` code: a code nothing declares is a code no `x errors explain` can answer.
+ * What the caller may read of a member's throw, as two data fields — never as an error's `cause:`.
+ * The reason ships in the hive action's 200 answer, so it is `discloseFailure`'s verdict, the one
+ * the tool result gets: a 5xx cause or a foreign `.message` (a pg `Key (email)=(…)`) is withheld
+ * and logged whole. A throw with no code gets `'unknown'` rather than an invented `X_` code: a code
+ * nothing declares is a code no `x errors explain` can answer.
  */
-function failureOf(error: unknown): { readonly code: string; readonly reason: string } {
-  if (isUltimateError(error)) return { code: error.code, reason: error.cause };
-  // `isThrownError` and `stringField`, never `error instanceof Error` and `.message`: a member
-  // is an app's action, so the value is one the framework did not build — `instanceof` runs a
-  // `Proxy`'s `getPrototypeOf` trap and `.message` is a getter call. A throw HERE would take the
-  // whole hive down with it, which is the one outcome the three arms exist to prevent.
-  const message = stringField(error, 'message');
-  if (isThrownError(error) && message !== undefined && message !== '') {
-    return { code: 'unknown', reason: message };
-  }
-  return { code: 'unknown', reason: 'the member threw a value that is not an Error' };
+function failureOf(
+  error: unknown,
+  ctx: Ctx,
+  index: number,
+): { readonly code: string; readonly reason: string } {
+  // `fix` is not carried: `reason` has always been the cause alone, and a member's caller acts on
+  // the code. What `discloseFailure` withholds stays withheld either way.
+  const shown = discloseFailure(error, ctx.logger, `hive member ${index}`);
+  return { code: shown.code ?? 'unknown', reason: shown.cause ?? HIDDEN_MEMBER_CAUSE };
 }
+
+/**
+ * What a caller reads in place of a reason it may not see. Fixed, so nothing of the throw rides on
+ * it — the hive's answer goes wherever its caller sends it, a model's context included.
+ */
+export const HIDDEN_MEMBER_CAUSE =
+  'the member failed inside the server; the details are withheld from this answer; the server log records its code and where it failed';

package/src/hive-result.ts

@@ -23,7 +23,10 @@ export type HiveMember<O> =
   | {
       readonly status: 'failed';
       readonly index: number;
-      /** The `UltimateError` code the member threw, or `'unknown'` for a foreign throw. */
+      /**
+       * The code the member threw — read structurally, so a foreign throw carrying a string `code`
+       * (a driver's SQLSTATE) reports it — or `'unknown'` for a throw with none.
+       */
       readonly code: string;
       readonly reason: string;
     }

package/src/hive.ts

@@ -5,8 +5,8 @@
  * `@ultimat3/core`, and it is a list rather than a sentence because the ordinal a file writes for
  * itself is wrong the day the next one lands and no file can see the others. A fan-out 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.
+ * returns an `action` and inherits `.openapi()`, `.client()`, `.job()`, `.contract()`, its MCP
+ * tool and its manifest row without a line here.
  *
  * It exists because the alternative is a hand-rolled `Promise.all` over `agent()` calls, and that
  * loop gets four things wrong every time: it takes the actor from somewhere other than the request,
@@ -20,7 +20,7 @@ import type { Ctx } 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, budgetKeysFor, currentBudget, withBudget } from './budget';
+import { BudgetLedger, budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import { HiveEmptyError } from './hive-errors';
 import { runPool } from './hive-pool';
 import type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
@@ -191,7 +191,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 it, which for a hive
     // under `withBudget` is every member's every turn.
     ...(budget?.tokensPerRun === undefined