@ultimat3/ai 23.0.0 → 25.0.0

package/src/content-blocks.ts

@@ -0,0 +1,227 @@
+// The image and document blocks a user turn may carry: their shapes (the Messages API's own field
+// names, so the Anthropic body passes them through untouched), the screen every request runs them
+// through before it leaves, and what they add to the pre-flight token estimate.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AiContentUnsupportedError } from './content-errors';
+import { AiRequestInvalidError } from './errors';
+import type { ContentKind, ModelId } from './models';
+import { modelSpec } from './models';
+import type { AiContentBlock } from './provider';
+
+/** "JPEG, PNG, GIF, and WebP" — the one list both wire formats publish. */
+export const IMAGE_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'] as const;
+export type ImageMediaType = (typeof IMAGE_MEDIA_TYPES)[number];
+
+/**
+ * Ceilings on a base64 `data` string, in CHARACTERS — the encoded size, which is what the limits
+ * are stated in. Image: the Claude API's 10 MB per image (MiB, as its own refusal counts them).
+ * Document: 32 MiB, the Messages API's whole-request ceiling, so no single PDF can be legal on
+ * its own and still be a request the endpoint refuses. The OpenAI format allows more for a file
+ * (50 MB); one table for both, the stricter, so which provider answers never changes the verdict.
+ */
+export const MAX_IMAGE_BASE64_CHARS = 10 * 1024 * 1024;
+export const MAX_DOCUMENT_BASE64_CHARS = 32 * 1024 * 1024;
+
+/**
+ * An image's pre-flight token estimate: the most visual tokens Claude 4.7+ spends on one image
+ * after resizing (4,784 — vision guide, high-resolution tier). Pessimistic on purpose, like the
+ * rest of the estimate: the budget reserves it and `record` gives back what the call did not use.
+ */
+export const IMAGE_TOKEN_ESTIMATE = 4_784;
+
+export type AiImageSource =
+  | { readonly type: 'base64'; readonly media_type: ImageMediaType; readonly data: string }
+  | { readonly type: 'url'; readonly url: string };
+
+export type AiDocumentSource =
+  | { readonly type: 'base64'; readonly media_type: 'application/pdf'; readonly data: string }
+  | { readonly type: 'url'; readonly url: string }
+  | { readonly type: 'text'; readonly media_type: 'text/plain'; readonly data: string };
+
+export interface AiImageBlock {
+  readonly type: 'image';
+  readonly source: AiImageSource;
+}
+
+/** `title` is the Messages API's; on the OpenAI format it becomes the file's `filename`. */
+export interface AiDocumentBlock {
+  readonly type: 'document';
+  readonly source: AiDocumentSource;
+  readonly title?: string;
+}
+
+export type AiMediaBlock = AiImageBlock | AiDocumentBlock;
+
+/** The two kinds this module screens; a narrowing every consumer of `AiContentBlock` can reuse. */
+export function isMediaBlock(block: { readonly type: string }): block is AiMediaBlock {
+  return block.type === 'image' || block.type === 'document';
+}
+
+/** The fields of a message this screen reads — structural, so `provider.ts` stays the owner. */
+interface ScreenedMessage {
+  readonly role: string;
+  readonly content: string | readonly { readonly type: string }[];
+}
+
+/**
+ * Refuse every media block the target cannot take, and every one that is malformed, BEFORE the
+ * request is built. Blocks reach here from typed code and from replayed JSON alike, so the screen
+ * is at runtime: a media type outside the list, a URL that is not `https:`, a base64 string over
+ * its ceiling or outside the alphabet. A malformed block is `X_AI_REQUEST_INVALID`; a well-formed
+ * one the role or model cannot take is `X_AI_CONTENT_UNSUPPORTED`.
+ */
+export function assertMediaContent(
+  messages: readonly ScreenedMessage[],
+  target: { readonly provider: string; readonly model: ModelId },
+): void {
+  messages.forEach((message, m) => {
+    if (typeof message.content === 'string') return;
+    message.content.forEach((block, b) => {
+      if (!isMediaBlock(block)) return;
+      const at = `messages[${m}].content[${b}]`;
+      const kind: ContentKind = block.type;
+      if (message.role !== 'user') {
+        const refusal = { by: 'role', ...target, role: message.role } as const;
+        throw new AiContentUnsupportedError({ kind, at, refusal });
+      }
+      if (!(modelSpec(target.model).input ?? []).includes(kind)) {
+        throw new AiContentUnsupportedError({ kind, at, refusal: { by: 'model', ...target } });
+      }
+      assertSource(block, at);
+    });
+  });
+}
+
+function assertSource(block: AiMediaBlock, at: string): void {
+  const fields = fieldsOf(block.source);
+  const type = fields['type'];
+  // Read as untrusted: a replayed block's title is whatever the JSON held, on either kind.
+  const title: unknown = (block as { readonly title?: unknown }).title;
+  if (title !== undefined && typeof title !== 'string') {
+    throw invalid(
+      at,
+      `has a title of ${renderCauseValue(title)}`,
+      "title: 'q3.pdf'   # a string, or omit the field",
+    );
+  }
+  if (type === 'url') {
+    assertUrl(fields['url'], at);
+    return;
+  }
+  if (type === 'base64') {
+    assertBase64(block.type, fields, at);
+    return;
+  }
+  if (type === 'text' && block.type === 'document') {
+    assertText(fields, at);
+    return;
+  }
+  const legal = block.type === 'image' ? "'base64' or 'url'" : "'base64', 'url' or 'text'";
+  throw invalid(
+    at,
+    `has source.type ${renderCauseValue(type)}`,
+    `source: { type: 'base64', media_type, data }   # source.type is ${legal}`,
+  );
+}
+
+function assertUrl(url: unknown, at: string): void {
+  // `https:` only: a `data:` URL is the base64 source spelled a second way, and plain `http:` is a
+  // fetch the vendor makes over a channel anyone on the path can rewrite.
+  if (typeof url === 'string' && URL.canParse(url) && new URL(url).protocol === 'https:') return;
+  throw invalid(
+    at,
+    `has source.url ${renderCauseValue(url)}, which is not an https: URL`,
+    "source: { type: 'url', url: 'https://…' }   # or send the bytes as { type: 'base64', media_type, data }",
+  );
+}
+
+/** The standard alphabet with its padding, whole: no whitespace, no `data:` prefix, no URL-safe. */
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+
+function assertBase64(kind: ContentKind, fields: Record<string, unknown>, at: string): void {
+  const mediaType = fields['media_type'];
+  const legal: readonly unknown[] = kind === 'image' ? IMAGE_MEDIA_TYPES : ['application/pdf'];
+  if (!legal.includes(mediaType)) {
+    throw invalid(
+      at,
+      `has media_type ${renderCauseValue(mediaType)}, which a ${kind} block does not take`,
+      `media_type: '${String(legal[0])}'   # one of ${legal.join(', ')}${kind === 'document' ? "; text goes as { type: 'text', media_type: 'text/plain', data }" : ''}`,
+    );
+  }
+  const data = fields['data'];
+  const cap = kind === 'image' ? MAX_IMAGE_BASE64_CHARS : MAX_DOCUMENT_BASE64_CHARS;
+  if (
+    typeof data !== 'string' ||
+    data.length > cap ||
+    data.length % 4 !== 0 ||
+    !BASE64.test(data)
+  ) {
+    const size = typeof data === 'string' ? `${data.length} characters` : renderCauseValue(data);
+    throw invalid(
+      at,
+      `has source.data of ${size}: not one non-empty, padded, standard-alphabet base64 string of at most ${cap} characters`,
+      `data: Buffer.from(bytes).toString('base64')   # no data: prefix, at most ${cap} characters; a larger ${kind} goes as an https:// url source`,
+    );
+  }
+}
+
+function assertText(fields: Record<string, unknown>, at: string): void {
+  const data = fields['data'];
+  if (fields['media_type'] === 'text/plain' && typeof data === 'string' && data !== '') return;
+  throw invalid(
+    at,
+    'has a text source that is not { media_type: "text/plain", data: <non-empty string> }',
+    "source: { type: 'text', media_type: 'text/plain', data: text }   # the document's text, non-empty",
+  );
+}
+
+const invalid = (at: string, what: string, fix: string): AiRequestInvalidError =>
+  new AiRequestInvalidError({ detail: `${at} ${what}`, fix });
+
+/**
+ * The readable text of one block, for `messageText`. An image and a PDF have none — their cost is
+ * `mediaTokenEstimate`'s, never their base64 read as prose — and a text document's is its data.
+ */
+export function blockText(block: AiContentBlock): string {
+  if (block.type === 'text') return block.text;
+  if (block.type === 'tool_result') return block.content;
+  if (block.type === 'tool_use') return JSON.stringify(block.input);
+  if (block.type !== 'document') return '';
+  const source = fieldsOf(block.source);
+  return source['type'] === 'text' ? stringOr(source['data']) : '';
+}
+
+/**
+ * What the media blocks add to the pre-flight estimate. An image is `IMAGE_TOKEN_ESTIMATE`, its
+ * worst case. A base64 PDF is its encoded length over four — the same 4-characters-per-token rule
+ * as text, and in the published per-page range (text plus one page image) for an ordinary PDF. A
+ * text document's `data` is already counted by `messageText`. A PDF by URL is UNKNOWABLE before
+ * the vendor fetches it and adds nothing: `record` reconciles to the real usage afterwards.
+ *
+ * Runs BEFORE the screen (the gateway reserves, then the provider builds), so every field is read
+ * as untrusted — a malformed block is estimated as nothing and refused a moment later.
+ */
+export function mediaTokenEstimate(messages: readonly ScreenedMessage[]): number {
+  let tokens = 0;
+  for (const message of messages) {
+    if (typeof message.content === 'string') continue;
+    for (const block of message.content) {
+      if (!isMediaBlock(block)) continue;
+      if (block.type === 'image') {
+        tokens += IMAGE_TOKEN_ESTIMATE;
+        continue;
+      }
+      const source = fieldsOf(block.source);
+      if (source['type'] === 'base64') tokens += Math.ceil(stringOr(source['data']).length / 4);
+    }
+  }
+  return tokens;
+}
+
+const stringOr = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+/** A block's `source` as untrusted fields: a replayed block may carry none, or `null`. */
+function fieldsOf(source: unknown): Readonly<Record<string, unknown>> {
+  return typeof source === 'object' && source !== null ? (source as Record<string, unknown>) : {};
+}

package/src/content-errors.ts

@@ -0,0 +1,67 @@
+// The X_AI_CONTENT_UNSUPPORTED class, apart from ./errors because that catalogue is at its ceiling —
+// the split `hive-errors.ts` and `eval-errors.ts` made. Its code and title are registered in
+// ./errors with the rest: one owner, one registration, one place a duplicate can surface.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** Where a block was refused: a capability of the WIRE format, or of the model's own row. */
+export type ContentRefusal =
+  | { readonly by: 'model'; readonly model: string; readonly provider: string }
+  | {
+      readonly by: 'provider';
+      readonly model: string;
+      readonly provider: string;
+      /** What the wire format lacks — and, in `fix`, the block this provider DOES take instead. */
+      readonly why: string;
+      readonly fix: string;
+    }
+  | {
+      readonly by: 'role';
+      readonly model: string;
+      readonly provider: string;
+      readonly role: string;
+    };
+
+/**
+ * A message carries an image or document block the target cannot take. Refused before the request
+ * leaves, because the alternative is a 400 whose message names a JSON path, not the fix — or, on
+ * the endpoints that skip what they cannot parse, an answer about a document the model never saw.
+ *
+ * Never collected into `X_AI_PROVIDER_UNAVAILABLE`: the same blocks get the same refusal from
+ * every provider serving that model, so retrying burns attempts and discards this fix line.
+ */
+export class AiContentUnsupportedError extends UltimateError {
+  constructor(input: {
+    readonly kind: string;
+    readonly at: string;
+    readonly refusal: ContentRefusal;
+  }) {
+    const { kind, at, refusal } = input;
+    super({
+      code: 'X_AI_CONTENT_UNSUPPORTED',
+      cause: `${at} is a ${kind} block, and ${causeOf(kind, refusal)}`,
+      fix: fixOf(kind, refusal),
+      meta: { kind, at, by: refusal.by, model: refusal.model, provider: refusal.provider },
+    });
+  }
+}
+
+function causeOf(kind: string, refusal: ContentRefusal): string {
+  if (refusal.by === 'model') {
+    return `model "${refusal.model}" is registered without '${kind}' in its input list`;
+  }
+  if (refusal.by === 'role') {
+    return `a ${kind} block may only travel in a user turn, not a ${refusal.role} turn (provider "${refusal.provider}", model "${refusal.model}")`;
+  }
+  return `provider "${refusal.provider}" cannot send it to model "${refusal.model}": ${refusal.why}`;
+}
+
+function fixOf(kind: string, refusal: ContentRefusal): string {
+  if (refusal.by === 'model') {
+    return `registerModel({ ...modelSpec('${refusal.model}'), input: ['image', 'document'] })   # if its endpoint accepts ${kind}s; or route the request to a model that does`;
+  }
+  if (refusal.by === 'role') {
+    return `{ role: 'user', content: [/* the ${kind} block */] }   # move the block out of the ${refusal.role} turn`;
+  }
+  return refusal.fix;
+}

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

@@ -5,7 +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 { fingerprint, finiteCount } from '@ultimat3/core';
 import { AiEmbedderInvalidError } from './errors';
 
 export interface Embedder {
@@ -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,34 +92,33 @@ export class HashEmbedder implements Embedder {
 
   private one(text: string): Float32Array {
     const vector = new Float32Array(this.dimension);
-    for (const token of tokenize(text)) {
-      const slot = fnv1a(token) % this.dimension;
+    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 = fnv1a(`${token}#sign`) % 2 === 0 ? 1 : -1;
+      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) ?? [];
 }
 
-/** FNV-1a 32-bit. Chosen for stability across runtimes, not for cryptographic strength. */
-export function fnv1a(text: string): number {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    hash ^= text.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash;
+/**
+ * A token's slot hash: 32 bits of core's `fingerprint`, never a local FNV-1a. FNV-1a/32 collides on
+ * ordinary words (`costarring` / `liquid`), and two colliding words embed IDENTICALLY here — cosine
+ * 1, so a semantic lookup answered one with the other's entry.
+ */
+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;
@@ -123,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/error-body.ts

@@ -11,13 +11,20 @@ import { REDACTED } from '@ultimat3/core';
 /** Enough of an error body to name the field that was wrong, not enough to fill a log. */
 const DETAIL_LIMIT = 300;
 
+/**
+ * How much of a failure body is READ. Larger than what is shown, because the message sits inside a
+ * JSON envelope that has to parse; bounded, because a provider streaming an endless 5xx body held
+ * the call and its memory for as long as it kept sending.
+ */
+const READ_LIMIT = 4 * 1024;
+
 /**
  * The provider's own message, when it sent one — it names the offending field, we name the fix.
  * Falls back to the raw text because a proxy or a gateway timeout page is not JSON and is still
- * the best evidence there is.
+ * the best evidence there is. One reader for every transport, the embedder included.
  */
 export async function detailOf(response: Response): Promise<string> {
-  const body = await response.text().catch(() => '');
+  const body = await boundedText(response.body);
   try {
     const parsed: unknown = JSON.parse(body);
     if (typeof parsed === 'object' && parsed !== null) {
@@ -28,11 +35,39 @@ export async function detailOf(response: Response): Promise<string> {
       }
     }
   } catch {
-    // Not JSON — a proxy or a gateway timeout page. The raw text is still the best evidence.
+    // Not JSON — a proxy or a gateway timeout page, or a body cut at the read limit.
   }
   return body === '' ? response.statusText : body.slice(0, DETAIL_LIMIT);
 }
 
+/** The start of a body, never more than `READ_LIMIT` bytes of it; the rest is cancelled. */
+async function boundedText(body: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (body === null) return '';
+  const reader = body.getReader();
+  const kept: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (total < READ_LIMIT) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      kept.push(value);
+      total += value.byteLength;
+    }
+  } catch {
+    // A body that fails mid-read still has whatever arrived; the status is the error's substance.
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of kept) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
 /**
  * Every occurrence of the credential replaced with `[redacted]`. Cheap, and the one leak path:
  * a proxy that echoes the request headers into its own 400 body puts the key in an error, and an

package/src/errors.ts

@@ -27,6 +27,9 @@ export const AI_ERROR_CODES = [
   'X_VECTOR_DIM_MISMATCH',
   '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];
@@ -55,6 +58,9 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_VECTOR_DIM_MISMATCH: 'embedding dimensions differ from the store',
   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
@@ -128,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.
@@ -259,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.
      */
@@ -276,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-baseline.ts

@@ -91,7 +91,11 @@ export function regressionsAgainst(input: {
   readonly tolerance: number;
 }): readonly Regression[] {
   const found: Regression[] = [];
-  const fell = (was: number, now: number): boolean => now < was - input.tolerance;
+  // Both sides at the precision the baseline is WRITTEN at, and the drop rounded too: a raw 2/3
+  // against its own recorded 0.667 fell at `tolerance: 0`, and `0.9 - 0.05` is not `0.85` in
+  // binary — a drop of exactly the tolerance must read as within it.
+  const fell = (was: number, now: number): boolean =>
+    round(round(was) - round(now)) > input.tolerance;
   if (fell(input.baseline.score, input.score)) {
     found.push({ case: OVERALL, baseline: input.baseline.score, score: input.score });
   }