@ultimat3/ai 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -302,8 +302,9 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   - `.stream()` is LAZY. Nothing is authorised, budgeted or sent until the first pull. `named()` is
     re-narrowed for the same reason `stream` is assigned in place: `action()`'s `named` builds a
     fresh twin that would silently not stream.
-- **`agent()` is a job for the tool loop, and the third instance of the factory rule** (after
-  `llm()` and `backfill()`) — it returns an `action`, never a ninth primitive. It exists because
+- **`agent()` is a job for the tool loop, and one of the factory rule's instances** — the list is
+  `PRIMITIVE_FACTORIES` in `@ultimat3/core`, never an ordinal in a header — it returns an `action`,
+  never a ninth primitive. It exists because
   the alternative is a hand-rolled loop, and a hand-rolled loop is where the dangerous mistake
   lives: **taking the actor from the model's output.** `ctx.actor` is read once and is the only
   identity any tool runs as; nothing the model emits can reach it. Bounded by `maxTurns`
@@ -379,8 +380,8 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   - `AiMessage.content` widened to `string | readonly AiContentBlock[]` for this: a `tool_result`
     has to name the `tool_use` it answers and a string has nowhere to put the id. The block field
     names are the Messages API's, so `body()` passes them through untouched.
-- **`hive()` is a fan-out, and the FOURTH instance of the factory rule** (after `llm()`,
-  `backfill()` and `agent()`) — it returns an `action`, never a ninth primitive. It exists because
+- **`hive()` is a fan-out, and another of the factory rule's instances** (`PRIMITIVE_FACTORIES`
+  again) — it returns an `action`, never a ninth primitive. It exists because
   the alternative is a hand-rolled `Promise.all` over `agent()` calls, and that loop gets four
   things wrong every time: the actor, the order, the difference between ran-and-failed and
   never-ran, and the ceiling.
@@ -487,7 +488,20 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 - Server-side `fallbacks` (beta) are deliberately NOT sent. The provider speaks the stable
   `2023-06-01` surface, and a 1.0 package that promises semver cannot pin a beta wire contract;
   the typed refusal plus the gateway's own model routing is the framework's answer instead.
-- `definePrompt` refuses a re-registered version whose hash moved.
+- `definePrompt` refuses a re-registered version whose hash moved, and the hash is taken over
+  `@ultimat3/core`'s `canonicalJson` (`As of 2026-08-22`). It was a local sorted-key
+  `JSON.stringify` — the framework's third copy of one canonical form — which spells `-0` as `0`
+  and every non-finite number as `null`: a schema `default` the model is told about could move
+  while the ref did not, and every score already filed goes on claiming to describe the new prompt.
+  Ordinary JSON hashes byte-identically between the two, so **no committed baseline is
+  invalidated**; `prompt.test.ts` pins one hash literally to keep it that way. An ABSENT schema
+  stays the empty string rather than `canonicalJson(undefined)`'s `null`, for the same reason.
+- **A caught value is read with `renderThrowable`, never `error instanceof Error ? error.message :
+  String(error)`.** `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap, and a throw there escapes
+  the very `catch` that exists to produce a coded refusal — proven against `RemoteEmbedder`, whose
+  injected `fetch` made it reachable from app config. Five sites in this package
+  (`remote-embedder.ts`, `wire.ts` x2, `openai-wire.ts` x2); `scripts/error-render.ts` cannot see
+  any of them, because it reads PARAMETERS typed `unknown` and these are `catch` bindings.
 - Every eval result carries the prompt hash. A score without one is not a measurement.
 - An eval gates on the DROP from its recorded baseline, never on an absolute score. An absolute
   floor fails every eval at once the day a provider ships a slightly different model, which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,14 +32,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "6.0.0",
-    "@ultimat3/cache": "6.0.0",
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/db": "6.0.0",
-    "@ultimat3/jobs": "6.0.0",
-    "@ultimat3/money": "6.0.0",
-    "@ultimat3/policy": "6.0.0",
-    "@ultimat3/schema": "6.0.0",
-    "@ultimat3/time": "6.0.0"
+    "@ultimat3/action": "8.0.0",
+    "@ultimat3/cache": "8.0.0",
+    "@ultimat3/core": "8.0.0",
+    "@ultimat3/db": "8.0.0",
+    "@ultimat3/jobs": "8.0.0",
+    "@ultimat3/money": "8.0.0",
+    "@ultimat3/policy": "8.0.0",
+    "@ultimat3/schema": "8.0.0",
+    "@ultimat3/time": "8.0.0"
   }
 }

package/src/agent.ts

@@ -1,8 +1,10 @@
 /**
  * `agent()` — a multi-turn tool-using model call, declared as an `action`.
  *
- * The third instance of the framework's rule, after `llm()` and `backfill()`: a new capability
- * arrives as a FACTORY over an existing primitive, never as a ninth kind. A tool-using run is
+ * One more instance of the framework's rule — the whole list is `PRIMITIVE_FACTORIES` in
+ * `@ultimat3/core`: a new capability arrives as a FACTORY over an existing primitive, never as a
+ * ninth kind, and the list is what a reader counts instead of a sentence in one of them that
+ * cannot see the rest. A tool-using run is
  * still one server-authoritative operation with an input schema, an output schema and a policy —
  * so this returns an `action`, and inherits `.tool()`, `.openapi()`, `.client()`, `.job()`,
  * `.contract()` and its manifest row without a line here.

package/src/budget.ts

@@ -4,12 +4,13 @@
 // wrong answer that looks like a real one, and the caller has no signal anything happened.
 // A thrown X_AI_BUDGET_EXCEEDED with the remaining count is strictly more useful.
 //
-// The carrier is an AsyncLocalStorage so nested calls (a RAG retrieval, a tool call that
-// generates, an eval judge) all debit the same ledger without threading it through every
-// signature. `node:async_hooks` is used directly because Bun implements it natively and the
-// framework's ALS context is established at the HTTP boundary, above this package.
+// The carrier is an async context so nested calls (a RAG retrieval, a tool call that generates,
+// an eval judge) all debit the same ledger without threading it through every signature. It opens
+// through `@ultimat3/core`'s one lazy seam rather than constructing an `AsyncLocalStorage` here: a
+// 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 { AsyncLocalStorage } from 'node:async_hooks';
+import { asyncContext } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { assertSameCurrency } from '@ultimat3/money';
 import { AiBudgetExceededError } from './errors';
@@ -307,7 +308,7 @@ function tighterMoney(a: Money | undefined, b: Money | undefined): Money | undef
   return a.minor <= b.minor ? a : b;
 }
 
-const storage = new AsyncLocalStorage<BudgetLedger>();
+const storage = asyncContext<BudgetLedger>('an AI budget');
 
 /** Run `fn` with `ledger` as the ambient budget for everything it awaits. */
 export function withBudget<T>(ledger: BudgetLedger, fn: () => Promise<T>): Promise<T> {
@@ -316,5 +317,5 @@ export function withBudget<T>(ledger: BudgetLedger, fn: () => Promise<T>): Promi
 
 /** The ambient ledger, or `undefined` outside a budget scope (spend is then unmetered). */
 export function currentBudget(): BudgetLedger | undefined {
-  return storage.getStore();
+  return storage.get();
 }

package/src/hive.ts

@@ -1,10 +1,12 @@
 /**
  * `hive()` — one action fanned out over many inputs, declared as an `action`.
  *
- * The fourth instance of the framework's factory rule, after `llm()`, `backfill()` and `agent()`:
- * 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.
+ * One more instance of the framework's factory rule — the whole list is `PRIMITIVE_FACTORIES` in
+ * `@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.
  *
  * 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,

package/src/llm-stream.ts

@@ -21,7 +21,7 @@
  *     async chain — abandoning the iterator stops delivery, never the accounting.
  */
 
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { asyncContext } from '@ultimat3/core';
 import { AiTransportError } from './errors';
 import type { Gateway } from './gateway';
 import type { GenerateRequest, GenerateResult } from './provider';
@@ -102,7 +102,9 @@ export class LlmSink {
   }
 }
 
-const sinks = new AsyncLocalStorage<LlmSink>();
+// Core's one lazy seam, never a construction here: a module-scope `new` threw at EVALUATION in a
+// browser bundle, where the bundler stubs `node:async_hooks` to `{}`.
+const sinks = asyncContext<LlmSink>('an LLM stream sink');
 
 /** Mark everything `fn` awaits as a streamed invocation. */
 export function withLlmSink<T>(sink: LlmSink, fn: () => Promise<T>): Promise<T> {
@@ -111,7 +113,7 @@ export function withLlmSink<T>(sink: LlmSink, fn: () => Promise<T>): Promise<T>
 
 /** The sink of the streamed invocation this call belongs to, or `undefined` for a plain one. */
 export function currentLlmSink(): LlmSink | undefined {
-  return sinks.getStore();
+  return sinks.get();
 }
 
 /**

package/src/openai-wire.ts

@@ -6,6 +6,7 @@
 // order, or stops half way. An LLM response is untrusted input, so every field is parsed and
 // nothing is cast.
 
+import { renderThrowable } from '@ultimat3/core';
 import { AiTransportError } from './errors';
 import type { StopDetails, StopReason, StreamChunk, TokenUsage } from './provider';
 import type { SseFrame } from './sse';
@@ -148,9 +149,7 @@ function parseArguments(raw: unknown, name: string, provider: string): Record<st
   } catch (error) {
     throw malformed(
       provider,
-      `tool "${name}" returned arguments that are not JSON: ${
-        error instanceof Error ? error.message : 'unreadable'
-      }`,
+      `tool "${name}" returned arguments that are not JSON: ${renderThrowable(error)}`,
     );
   }
 }
@@ -321,9 +320,7 @@ export class ChatCompletionStream {
     } catch (error) {
       throw malformed(
         this.provider,
-        `unreadable "${frame.event}" frame: ${
-          error instanceof Error ? error.message : 'unreadable'
-        }`,
+        `unreadable "${frame.event}" frame: ${renderThrowable(error)}`,
       );
     }
   }

package/src/prompt.ts

@@ -9,6 +9,7 @@
 // So: edit the template, bump the version. Re-registering a version whose hash moved is a
 // build error, not a warning.
 
+import { canonicalJson } from '@ultimat3/core';
 import { AiPromptRenderError, AiPromptVersionError } from './errors';
 import type { Effort, ModelId, ThinkingMode } from './models';
 import type { JsonSchema } from './tools';
@@ -141,34 +142,31 @@ function render(template: string, vars: PromptVars, ref: string): string {
 }
 
 /**
- * Canonical serialisation then sha256. Keys are written in a fixed order rather than
- * `JSON.stringify(object)` so the hash never depends on property insertion order.
+ * Canonical serialisation then sha256, over `@ultimat3/core`'s `canonicalJson` — the framework's
+ * one INJECTIVE form, so a schema that changed cannot hash as the schema it replaced. A local
+ * sorted-key `JSON.stringify` was here and spelled `-0` as `0` and every non-finite number as
+ * `null`, which is a `default` the model is told about moving under a ref that did not: every eval
+ * score already filed goes on claiming to describe the new prompt.
+ *
+ * An absent schema stays the empty string rather than becoming `canonicalJson(undefined)`'s
+ * `null` — that is what keeps every hash already recorded in a baseline the same value.
  */
 export function contentHash<V extends PromptVars>(input: DefinePromptInput<V>): string {
-  const canonical = [
+  const fields = [
     `id:${input.id}`,
     `version:${input.version}`,
     `system:${input.system ?? ''}`,
     `template:${input.template}`,
-    `input:${stableJson(input.input)}`,
-    `output:${stableJson(input.output)}`,
+    `input:${schemaField(input.input)}`,
+    `output:${schemaField(input.output)}`,
     `model:${input.model ?? ''}`,
     `effort:${input.effort ?? ''}`,
     `thinking:${input.thinking ?? ''}`,
   ].join('\n');
   const hasher = new Bun.CryptoHasher('sha256');
-  hasher.update(canonical);
+  hasher.update(fields);
   return hasher.digest('hex').slice(0, 32);
 }
 
-/** Sorted-key JSON so two structurally equal schemas hash identically. */
-function stableJson(value: unknown): string {
-  if (value === undefined) return '';
-  return JSON.stringify(value, (_key, val: unknown) => {
-    if (typeof val !== 'object' || val === null || Array.isArray(val)) return val;
-    const record = val as Record<string, unknown>;
-    const sorted: Record<string, unknown> = {};
-    for (const key of Object.keys(record).sort()) sorted[key] = record[key];
-    return sorted;
-  });
-}
+const schemaField = (schema: JsonSchema | undefined): string =>
+  schema === undefined ? '' : canonicalJson(schema);

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 } from '@ultimat3/core';
+import { readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { normalize } from './embeddings';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
@@ -95,7 +95,11 @@ export class RemoteEmbedder implements Embedder {
     } catch (error) {
       throw new AiTransportError({
         provider: this.name,
-        detail: `${error instanceof Error ? error.message : 'the request failed before a response'} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
+        // `renderThrowable`, never `error instanceof Error` and `.message`: `fetch` is injected
+        // and the endpoint is app config, so the rejection is a value this package did not build —
+        // and `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap, whose throw escapes this very
+        // `catch` and replaces a coded refusal with an uncoded crash.
+        detail: `${renderThrowable(error)} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
         envVar: API_KEY_ENV,
       });
     }

package/src/wire.ts

@@ -7,6 +7,7 @@
 // with no socket, which is the only way to cover a stream that arrives out of order or stops
 // half way. Imports from provider.ts are types only — the dependency runs one way.
 
+import { renderThrowable } from '@ultimat3/core';
 import { AiTransportError } from './errors';
 import type { StopDetails, StopReason, StreamChunk, TokenUsage } from './provider';
 import type { SseFrame } from './sse';
@@ -205,9 +206,7 @@ export class MessageStream {
     } catch (error) {
       throw new AiTransportError({
         provider: 'anthropic',
-        detail: `unreadable "${frame.event}" frame: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        detail: `unreadable "${frame.event}" frame: ${renderThrowable(error)}`,
       });
     }
   }
@@ -275,9 +274,7 @@ export class MessageStream {
     } catch (error) {
       throw new AiTransportError({
         provider: 'anthropic',
-        detail: `tool "${tool.name}" streamed arguments that are not JSON: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        detail: `tool "${tool.name}" streamed arguments that are not JSON: ${renderThrowable(error)}`,
       });
     }
   }