@ultimat3/ai 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# @ultimat3/ai 🧠
+
+The LLM gateway primitive. Every model call in an Ultimate app goes through it, so budgets
+and cost accounting cannot be bypassed by a stray `fetch`.
+
+```ts
+import { createGateway, AnthropicProvider, EchoProvider } from '@ultimat3/ai';
+
+export const ai = createGateway({
+  providers: [new AnthropicProvider(), new EchoProvider()],   // ANTHROPIC_API_KEY, or { apiKey }
+  budget: { request: 40_000, actor: 500_000, org: 20_000_000 },  // tokens
+  cache: memoCache,
+});
+
+// Budgets are scoped, and every nested call inside the scope shares one ledger.
+const answer = await ai.scope({ actorKey: actor.id, orgKey: actor.orgId }, async () => {
+  const { text } = await ai.generate({
+    model: 'claude-opus-5',
+    system: 'You summarise support tickets.',
+    messages: [{ role: 'user', content: ticket.body }],
+    maxTokens: 1_024,
+    effort: 'high',
+  });
+  return text;
+});
+```
+
+## Rules the gateway enforces
+
+| Rule | Why |
+|---|---|
+| A budget **refuses**, never truncates | a shortened prompt yields a confidently wrong answer with no signal |
+| Cost is **integer minor units** (`@ultimat3/money`) | token spend is money; the house rule has no exception |
+| Cost rounds **up** | a rounded-away fraction is money the framework absorbs and a budget under-reports |
+| `temperature` / `top_p` / `top_k` are never sent | rejected with a 400 on every current model — steer with the prompt |
+| `effort` goes in `output_config` | a top-level `effort` is silently ignored |
+| The reasoning half of the body is **per model** | `effort` and adaptive thinking arrived with 4.6; sending them to an older model is a 400 on every request |
+| A control the model lacks is **refused**, never dropped | a declaration reading `effort: 'max'` that quietly runs at the default is the failure nobody can see |
+| A control nobody asked for is **omitted**, never defaulted | a default sent as a request is indistinguishable on the wire from one that was declared |
+| A refusal is `X_LLM_REFUSED`, not a schema failure | it is a 200 with no answer in it, and a repair turn buys the same refusal again |
+| A refusal is never cached | a cached one keeps serving a classifier decision after the prompt was fixed |
+| Retries use **full jitter** | synchronised retries from N workers reproduce the rate limit |
+| A 4xx is never retried | the same body gets the same rejection and burns the budget |
+
+## Streaming
+
+`stream()` yields as the model writes and ends with one `done` chunk carrying the assembled
+result — so a consumer that only wants the answer can ignore everything before it. Required
+above `STREAM_ONLY_MAX_TOKENS` (16k): a non-streaming request that large hits the HTTP timeout
+after the completion has already been generated and billed. `generate()` switches to this
+transport by itself above the ceiling and returns the assembled result — the limit belongs to
+the transport, so it is not one the caller has to change API for.
+
+```ts
+for await (const chunk of ai.stream({ messages, maxTokens: 64_000 })) {
+  if (chunk.type === 'text') process.stdout.write(chunk.text);
+  if (chunk.type === 'tool-call') await runLlmToolCall(tools, chunk.call, actor);
+  if (chunk.type === 'done') debit(chunk.result.cost);   // real usage, not the estimate
+}
+```
+
+| Rule | Why |
+|---|---|
+| A `tool-call` chunk arrives whole | `input_json_delta` fragments are not arguments until the block closes |
+| `thinking` chunks never join `text` | concatenating every chunk must not ship the reasoning to the user |
+| A stream cut before `message_stop` **throws** | a truncated answer reporting `end_turn` is wrong with no signal |
+| An in-band `error` frame carries a status | `overloaded_error` mid-stream retries like a 529 on the handshake |
+
+## Embeddings
+
+`RemoteEmbedder` speaks the one `/v1/embeddings` shape every hosted and self-hosted embedder
+uses; `baseUrl` selects the provider. `HashEmbedder` is the deterministic offline twin `x dev`
+and the test suite run on.
+
+```ts
+const embedder = new RemoteEmbedder({ name: 'voyage-3', dimension: 1_024 });  // EMBEDDINGS_API_KEY
+```
+
+Vectors are L2-normalised on arrival, so `cosine` stays a dot product. A width other than the
+declared `dimension` is `X_VECTOR_DIM_MISMATCH` **before** anything reaches a store — a store
+half-written at the wrong width has no error to report, only worse answers.
+
+Models, `As of 2026-08`:
+
+| Model | Context | Max output | Input / MTok | Output / MTok | `effort` | adaptive thinking |
+|---|---|---|---|---|---|---|
+| `claude-opus-5` (default) | 1M | 128K | $5 | $25 | yes | yes, off only at `effort ≤ high` |
+| `claude-sonnet-5` | 1M | 128K | $3 | $15 | yes | yes |
+| `claude-haiku-4-5` | 200K | 64K | $1 | $5 | no — a 400 | no — a 400 |
+
+The last two columns are data on the spec, not prose: `body()` builds the reasoning half from
+them, so a downgrade for price cannot become a request the provider rejects.
+
+## `llm()` — a model call, declared as an action
+
+Not a ninth primitive. A model call has an input schema, an output schema and a policy, which
+is an `action` — so `llm()` returns one, and everything an action projects, it projects.
+
+```ts
+import { llm, t } from '@ultimat3/ai';
+import { can } from '@ultimat3/policy';
+
+export const summarize = llm({
+  model:  'claude-sonnet-5',
+  input:  t.object({ postId: t.uuid }),
+  output: t.object({ summary: t.string, tags: t.array(t.string) }),
+  prompt: summarizePrompt,                                       // versioned artifact
+  vars:   async ({ input, ctx }) => ({ body: await ctx.posts.body(input.postId) }),
+  cache:  { semantic: { threshold: 0.97, ttl: '7d', scope: ({ orgId }) => orgId } },
+  budget: { tokensIn: 8_000, costPerCall: { minor: 5, currency: 'USD' } },
+  policy: can('post:read'),
+});
+
+summarize.tool();        // an MCP tool, gated by the same policy object
+summarize.openapi();     // an HTTP operation
+summarize.job();         // a job handle, for the long chains
+summarize.contract();    // the contract tests
+```
+
+| Declared | Behaviour |
+|---|---|
+| `output` | projected into the one tool the model may answer through; prose with a fenced JSON block still parses |
+| a schema failure | **one** repair turn naming the issues, then `X_LLM_OUTPUT_INVALID` |
+| `budget` | reserved against the worst case **before** the provider is reached — nothing spent, nothing truncated |
+| `cache.semantic` | one store per scope, keyed by embedding; a prompt version bump reaches a different store, so the bump *is* the invalidation |
+| `policy` | the same object every surface evaluates — an MCP call and an HTTP call are denied identically |
+| `vars` | the one declared place a model call loads data, so a reader can see what was sent |
+
+The gateway is ambient, installed once at boot — a declaration is evaluated at module scope,
+long before a provider exists:
+
+```ts
+configureAi({ gateway: createGateway({ providers: [new AnthropicProvider()] }) });
+```
+
+Missing at call time is `X_AI_GATEWAY_MISSING`, never a silent default provider.
+
+## Evals are a test type
+
+Not a notebook, not a weekly report — a `bun test` case that fails CI. **Every prompt has an
+eval**; a `definePrompt` no `defineEval` names is `X_EVAL_MISSING` in `x verify`, because an
+unevaluated prompt is untested code that costs money and answers users.
+
+The gate is the **drop from a recorded baseline**, never an absolute score. An absolute floor
+fails every eval at once the day a provider ships a slightly different model, which teaches
+everyone to lower thresholds until they measure nothing.
+
+```ts
+// app/support/summarize.evals.ts — the declaration the gate reads
+import { defineEval, exact, jsonSchemaValid } from '@ultimat3/ai';
+import { summarize } from './prompts';
+
+export const summarizeEval = defineEval({
+  name: 'summarize',
+  prompt: summarize,
+  cases: [
+    { name: 'refund', vars: { ticket: 'I want my money back' }, expected: 'billing' },
+    { name: 'outage', vars: { ticket: 'the site is down' }, expected: 'incident' },
+  ],
+  scorers: [exact, jsonSchemaValid(['category', 'summary'])],
+  baseline: import.meta.resolve('./summarize.baseline.json'),   // committed scores
+  tolerance: 0.05,                                              // how far one may fall
+});
+```
+
+```ts
+// app/support/summarize.eval.test.ts — the suite `x verify` runs
+test('summarize holds its recorded scores', async () => {
+  await summarizeEval.assert(ai);   // throws X_EVAL_THRESHOLD on a drop past 0.05
+});
+```
+
+`ULTIMATE_EVAL_RECORD=1 x test eval` writes the baselines instead of gating on them, so
+accepting a new number is a reviewable diff. An eval that has never been recorded fails with
+`X_EVAL_BASELINE_MISSING` — gating on nothing is not passing — and `x verify` asks that question
+itself, so an eval no test happens to assert is still red.
+
+Recording and the gate are mutually exclusive: `x verify` with `ULTIMATE_EVAL_RECORD` set is
+`X_EVAL_RECORDING` and runs no suite. Recording passes by definition, and a gate that inherited
+the flag would report green over numbers it had just written over the committed ones.
+
+A failure names the score, what it fell from, the exact prompt hash, and every case that moved:
+
+```
+X_EVAL_THRESHOLD: an eval scored below its tolerance
+  cause: eval "summarize" scored 0.667 against a recorded baseline of 1.000
+         (tolerance 0.050) on prompt version summarize@1.0.0 (a3f1…);
+         regressed: overall 0.67 ← 1.00, refund 0.00 ← 1.00
+  fix:   x test summarize to see per-case scores, then fix the prompt — or
+         ULTIMATE_EVAL_RECORD=1 x test eval to accept the new numbers as a reviewed diff
+```
+
+Built-in scorers: `exact`, `contains`, `jsonValid`, `jsonSchemaValid(keys)`,
+`numericTolerance(t)`, `llmJudge({ judge })` — the judge prompt is itself versioned, so a
+judge that drifts is a measuring instrument that lies, and its hash is in the scorer name.
+
+## Prompts are versioned artifacts
+
+```ts
+export const summarize = definePrompt<{ ticket: string }>({
+  id: 'summarize',
+  version: '1.0.0',
+  system: 'You classify support tickets.',
+  template: 'Classify and summarise:\n\n{{ticket}}',
+  output: { type: 'object', properties: { category: { type: 'string' } } },
+});
+```
+
+Content-hashed over id, version, system, template, schemas, model, effort, and thinking mode.
+Edit the template without bumping the version and `definePrompt` throws — otherwise every
+score ever recorded against that version is silently invalid. An unfilled `{{variable}}`
+throws too, like an i18n miss.
+
+## Retrieval
+
+```ts
+const store = new PgVectorStore({ name: 'doc_chunks', dimension: 256 });   // MemoryVectorStore in dev
+await indexDocument({ store, embedder, document: { id: 'faq', text } });
+
+const hits = await retrieve({ store, embedder, query, k: 8 });
+const context = assembleContext({ hits, maxTokens: 8_000 });
+context.dropped;                                              // reported, never silent
+```
+
+Retrieval is **hybrid by default** — vector + lexical, fused by reciprocal rank. Pure vector
+search loses on exactly the queries users type: error codes, SKUs, identifiers, rare terms.
+RRF fuses by *rank*, so the two score scales never have to be reconciled.
+
+`PgVectorStore` is the production path: pgvector cosine (`<=>`, HNSW) and Postgres FTS
+(`websearch_to_tsquery` + `ts_rank_cd`, GIN) in **the same Postgres**, fused by `1/(k+rank)` in
+one statement. `MemoryVectorStore` is the dev twin — BM25 instead of `ts_rank_cd`, the same RRF,
+the same envelope. `store.ddl()` prints the table and both indexes; `x db gen` emits it.
+
+### The scope is the leak-proofing
+
+```ts
+const tenantStore = store.scoped({ tenant: orgId, allow: { visibility: ['public', 'internal'] } });
+```
+
+Every read, write and delete a scoped store emits carries `tenant = $n` and the allow-list **in
+SQL** — including *both* halves of the hybrid fusion, since an unfiltered lexical ranking fused
+into a filtered dense one leaks through the back door. `(tenant, id)` is the primary key, so a
+cross-tenant overwrite is impossible at the storage layer rather than by remembering to check.
+Allow-lists are default deny: a row missing the key is invisible, and an empty list matches
+nothing. `scoped()` only ever **tightens** — re-scoping to a different tenant is
+`X_VECTOR_SCOPE_WIDENED`, never a silent widening.
+
+`chunk()` is token-aware with overlap and splits at paragraph, then sentence, then hard wrap
+— a fact split across a boundary with no overlap is retrievable by neither chunk.
+
+## Tools: the same projection as MCP
+
+```ts
+const tools = toLlmTools([publishPost, suspendUser]);   // only those with mcp.expose
+const result = await runLlmToolCall(actions, call, actor);
+```
+
+An in-app agent and an external MCP agent both end at `action.run`, so they authorize
+identically. The actor comes from the request context, never from the model.
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `X_AI_PROVIDER_UNAVAILABLE` | every provider for the model failed; lists what each said |
+| `X_AI_BUDGET_EXCEEDED` | refused pre-flight, naming the scope and what remains |
+| `X_AI_GATEWAY_MISSING` | an `llm()` action ran before `configureAi` |
+| `X_AI_PROMPT_VERSION` | version drift, or a render missing a declared variable |
+| `X_LLM_OUTPUT_INVALID` | the model failed its `output` schema on the answer and on the repair turn |
+| `X_EVAL_THRESHOLD` | an eval scored below its bar |
+| `X_VECTOR_DIM_MISMATCH` | a vector's length disagrees with the store |
+| `X_VECTOR_SCOPE_WIDENED` | a derived vector scope tried to leave the tenant it was bound to |
+| `X_NOT_IMPLEMENTED` | a remote driver with no key or transport; the fix names the env var |

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ultimat3/ai",
+  "version": "1.0.0",
+  "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/ai"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/action": "1.0.0",
+    "@ultimat3/cache": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/db": "1.0.0",
+    "@ultimat3/money": "1.0.0",
+    "@ultimat3/policy": "1.0.0",
+    "@ultimat3/schema": "1.0.0",
+    "@ultimat3/time": "1.0.0"
+  }
+}

package/src/budget.ts

@@ -0,0 +1,233 @@
+// Token and cost budgets, per request / per actor / per org.
+//
+// A budget REFUSES; it never truncates. A silently shortened prompt produces a confidently
+// 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.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Money } from '@ultimat3/money';
+import { assertSameCurrency } from '@ultimat3/money';
+import { AiBudgetExceededError } from './errors';
+import type { GenerateRequest, TokenUsage } from './provider';
+import { estimateCost, estimateInputTokens, estimateTokens, totalTokens } from './provider';
+
+/** Ceilings. An omitted scope is unlimited — declare the ones that matter. */
+export interface BudgetLimits {
+  /** Token ceiling for one `generate`/`stream` call, including its pre-flight estimate. */
+  readonly request?: number;
+  /**
+   * Prompt-token ceiling for ONE call. Distinct from `request`, which counts the completion
+   * too: a prompt is what the caller assembles and can shorten, a completion is not.
+   */
+  readonly tokensIn?: number;
+  /** Token ceiling for the acting identity across its whole window. */
+  readonly actor?: number;
+  /** Token ceiling for the organisation across its whole window. */
+  readonly org?: number;
+  /**
+   * Money ceiling for ONE call, checked against the worst-case estimate before the call.
+   * Per call rather than accumulated, because that is the knob an app can reason about:
+   * "no single answer may cost more than this". Integer minor units, never a float.
+   */
+  readonly costPerCall?: Money;
+}
+
+/**
+ * What one call is about to cost, priced before it happens. One object rather than a growing
+ * argument list, so a new scope is a new field here and never a new call site.
+ */
+export interface SpendEstimate {
+  /** Prompt tokens — what `tokensIn` caps. */
+  readonly inputTokens: number;
+  /** Prompt plus worst-case completion — what the request/actor/org scopes count. */
+  readonly tokens: number;
+  /** Worst-case price, in integer minor units. */
+  readonly cost: Money;
+}
+
+/** Price a request pre-flight. The pessimistic read on purpose — see `estimateCost`. */
+export function estimateSpend(request: GenerateRequest): SpendEstimate {
+  return {
+    inputTokens: estimateInputTokens(request),
+    tokens: estimateTokens(request),
+    cost: estimateCost(request),
+  };
+}
+
+/** Where cross-request counters live. Swap for Redis in a multi-process deployment. */
+export interface BudgetStore {
+  spent(key: string): Promise<number> | number;
+  add(key: string, tokens: number): Promise<void> | void;
+  reset(key?: string): Promise<void> | void;
+}
+
+export class MemoryBudgetStore implements BudgetStore {
+  private readonly counters = new Map<string, number>();
+
+  spent(key: string): number {
+    return this.counters.get(key) ?? 0;
+  }
+
+  add(key: string, tokens: number): void {
+    this.counters.set(key, this.spent(key) + tokens);
+  }
+
+  reset(key?: string): void {
+    if (key === undefined) this.counters.clear();
+    else this.counters.delete(key);
+  }
+}
+
+export interface BudgetLedgerInput {
+  readonly limits: BudgetLimits;
+  /** Stable identity keys. Omit a key to skip that scope even when a limit is set. */
+  readonly actorKey?: string;
+  readonly orgKey?: string;
+  readonly store?: BudgetStore;
+  readonly currency?: string;
+}
+
+export interface BudgetReport {
+  readonly requestTokens: number;
+  readonly cost: Money;
+  readonly limits: BudgetLimits;
+  readonly actorSpent: number;
+  readonly orgSpent: number;
+}
+
+export class BudgetLedger {
+  private readonly limits: BudgetLimits;
+  private readonly actorKey: string | undefined;
+  private readonly orgKey: string | undefined;
+  private readonly store: BudgetStore;
+  private requestTokens = 0;
+  private costMinor = 0;
+  private readonly currency: string;
+
+  constructor(input: BudgetLedgerInput) {
+    this.limits = input.limits;
+    this.actorKey = input.actorKey;
+    this.orgKey = input.orgKey;
+    this.store = input.store ?? new MemoryBudgetStore();
+    this.currency = input.currency ?? 'USD';
+  }
+
+  /**
+   * Check an estimate against every applicable scope BEFORE the call. Throws on the first
+   * scope that cannot cover it, naming that scope, so the fix line points at one knob rather
+   * than four. Nothing is debited here: `record` does that with the provider's real counts.
+   */
+  async reserve(estimate: SpendEstimate): Promise<void> {
+    this.assertScope('request', this.limits.request, this.requestTokens, estimate.tokens);
+    // Per call, so nothing is "already spent" against it.
+    this.assertScope('tokensIn', this.limits.tokensIn, 0, estimate.inputTokens);
+    if (this.limits.actor !== undefined && this.actorKey !== undefined) {
+      const spent = await this.store.spent(this.actorKey);
+      this.assertScope(`actor:${this.actorKey}`, this.limits.actor, spent, estimate.tokens);
+    }
+    if (this.limits.org !== undefined && this.orgKey !== undefined) {
+      const spent = await this.store.spent(this.orgKey);
+      this.assertScope(`org:${this.orgKey}`, this.limits.org, spent, estimate.tokens);
+    }
+    this.assertCost(estimate.cost);
+  }
+
+  /**
+   * A nested ledger for one call: the TIGHTER of each limit, the same identity keys and the
+   * same store. Tightening rather than replacing is the point — a per-call budget declared on
+   * an `llm()` action must not be able to widen the actor or org ceiling it runs inside.
+   */
+  derive(limits: BudgetLimits): BudgetLedger {
+    return new BudgetLedger({
+      limits: {
+        ...pick('request', tighterNumber(this.limits.request, limits.request)),
+        ...pick('tokensIn', tighterNumber(this.limits.tokensIn, limits.tokensIn)),
+        ...pick('actor', tighterNumber(this.limits.actor, limits.actor)),
+        ...pick('org', tighterNumber(this.limits.org, limits.org)),
+        ...pick('costPerCall', tighterMoney(this.limits.costPerCall, limits.costPerCall)),
+      },
+      ...(this.actorKey !== undefined ? { actorKey: this.actorKey } : {}),
+      ...(this.orgKey !== undefined ? { orgKey: this.orgKey } : {}),
+      store: this.store,
+      currency: this.currency,
+    });
+  }
+
+  /** Debit ACTUAL usage after the call, replacing the estimate `reserve` worked from. */
+  async record(usage: TokenUsage, cost: Money): Promise<void> {
+    const tokens = totalTokens(usage);
+    this.requestTokens += tokens;
+    this.costMinor += cost.minor;
+    if (this.actorKey !== undefined) await this.store.add(this.actorKey, tokens);
+    if (this.orgKey !== undefined) await this.store.add(this.orgKey, tokens);
+  }
+
+  async report(): Promise<BudgetReport> {
+    return {
+      requestTokens: this.requestTokens,
+      cost: { minor: this.costMinor, currency: this.currency },
+      limits: this.limits,
+      actorSpent: this.actorKey === undefined ? 0 : await this.store.spent(this.actorKey),
+      orgSpent: this.orgKey === undefined ? 0 : await this.store.spent(this.orgKey),
+    };
+  }
+
+  private assertScope(scope: string, limit: number | undefined, spent: number, want: number): void {
+    if (limit === undefined) return;
+    const remaining = limit - spent;
+    if (want > remaining) {
+      throw new AiBudgetExceededError({ scope, requested: want, remaining, limit });
+    }
+  }
+
+  /** Per-call, so `remaining` IS the limit. Currencies must match; a mismatch is a config bug. */
+  private assertCost(cost: Money): void {
+    const limit = this.limits.costPerCall;
+    if (limit === undefined) return;
+    assertSameCurrency(limit, cost);
+    if (cost.minor > limit.minor) {
+      throw new AiBudgetExceededError({
+        scope: 'costPerCall',
+        requested: cost.minor,
+        remaining: limit.minor,
+        limit: limit.minor,
+        unit: `${limit.currency} minor units`,
+      });
+    }
+  }
+}
+
+/** 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>);
+}
+
+function tighterNumber(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return Math.min(a, b);
+}
+
+function tighterMoney(a: Money | undefined, b: Money | undefined): Money | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  assertSameCurrency(a, b);
+  return a.minor <= b.minor ? a : b;
+}
+
+const storage = new AsyncLocalStorage<BudgetLedger>();
+
+/** Run `fn` with `ledger` as the ambient budget for everything it awaits. */
+export function withBudget<T>(ledger: BudgetLedger, fn: () => Promise<T>): Promise<T> {
+  return storage.run(ledger, fn);
+}
+
+/** The ambient ledger, or `undefined` outside a budget scope (spend is then unmetered). */
+export function currentBudget(): BudgetLedger | undefined {
+  return storage.getStore();
+}

package/src/embeddings.ts

@@ -0,0 +1,107 @@
+// The embedding interface, the vector maths every store shares, and a deterministic hash
+// embedder for tests and `x dev`. The remote one lives in ./remote-embedder.
+//
+// The dimension lives in the TYPE, not in a config file: a store built with one embedder and
+// 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 { AiEmbedderInvalidError } from './errors';
+
+export interface Embedder {
+  readonly name: string;
+  /** Declared once, checked everywhere. */
+  readonly dimension: number;
+  /** Batched: an embedder that only does one text at a time is a per-chunk round trip. */
+  embed(texts: readonly string[]): Promise<readonly Float32Array[]>;
+}
+
+/** Embed one text without building an array at the call site. */
+export async function embedOne(embedder: Embedder, text: string): Promise<Float32Array> {
+  const [vector] = await embedder.embed([text]);
+  if (vector === undefined) throw new AiEmbedderInvalidError({ embedder: embedder.name });
+  return vector;
+}
+
+/**
+ * Split a batch into chunks of `size`, preserving order. Providers cap batch size, and a
+ * caller that embeds a 50k-chunk corpus should not have to know each provider's cap.
+ */
+export async function embedBatched(
+  embedder: Embedder,
+  texts: readonly string[],
+  size = 96,
+): Promise<readonly Float32Array[]> {
+  const out: Float32Array[] = [];
+  for (let i = 0; i < texts.length; i += size) {
+    out.push(...(await embedder.embed(texts.slice(i, i + size))));
+  }
+  return out;
+}
+
+export interface HashEmbedderInput {
+  readonly dimension?: number;
+}
+
+/**
+ * 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
+ * what a test fixture and a `x dev` boot without an API key actually need. Shared words
+ * produce genuine similarity, so relevance tests are meaningful rather than tautological.
+ */
+export class HashEmbedder implements Embedder {
+  readonly name = 'hash';
+  readonly dimension: number;
+
+  constructor(input: HashEmbedderInput = {}) {
+    this.dimension = input.dimension ?? 256;
+  }
+
+  async embed(texts: readonly string[]): Promise<readonly Float32Array[]> {
+    return texts.map((text) => this.one(text));
+  }
+
+  private one(text: string): Float32Array {
+    const vector = new Float32Array(this.dimension);
+    for (const token of tokenize(text)) {
+      const slot = fnv1a(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;
+      vector[slot] = (vector[slot] ?? 0) + sign;
+    }
+    return normalize(vector);
+  }
+}
+
+/** Lowercased word tokens. Punctuation is dropped; digits are kept (versions, ids). */
+export function tokenize(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;
+}
+
+/** L2 normalise in place so cosine similarity reduces to a dot product. */
+export function normalize(vector: Float32Array): Float32Array {
+  let sum = 0;
+  for (const value of vector) sum += value * value;
+  if (sum === 0) return vector;
+  const inverse = 1 / Math.sqrt(sum);
+  for (let i = 0; i < vector.length; i += 1) vector[i] = (vector[i] ?? 0) * inverse;
+  return vector;
+}
+
+/** Dot product. Correct as cosine only for normalised vectors — which `normalize` ensures. */
+export function cosine(a: Float32Array, b: Float32Array): number {
+  let sum = 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;
+}