@ultimat3/ai 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -4,7 +4,8 @@ Tier 4. May import tier 0–3: `core schema i18n money time cache seo entity pol
 query jobs realtime`. **Never** `mcp manifest render pwa ui admin testing cli`.
 
 Declared today: `action` (the primitive `llm()` returns), `cache` (semantic cache), `core`,
-`db` (pgvector), `jobs` (`agentJob()`), `money`, `policy`, `schema`, `time`.
+`db` (pgvector), `http` (`statusFor`, so a tool result redacts a 5xx cause as a problem document
+does), `jobs` (`agentJob()`), `money`, `policy`, `schema`, `time`.
 
 `jobs` is declared for `agentJob()`: the action→job bridge has to live at tier 4+.
 
@@ -46,6 +47,7 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
 | `rag.ts` | chunker, retriever, reranker, budgeted context assembler |
 | `tools.ts` | action → LLM tool definition; the `AgentTool` union and `asProjectableAction`; `runLlmToolCall` |
 | `llm.ts` | `llm()` — the model call, declared as an `action`; and what a streamed answer must satisfy |
+| `respond.ts` | the `respond` tool for one `output` (a non-object one wrapped in `{ value }`), its reader, and `parseJsonish` |
 | `llm-stream.ts` | `.stream()`'s plumbing: the sink, the ambient mark, the one-turn drive |
 | `agent.ts` | `agent()` — the tool loop, declared as an `action` |
 | `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
@@ -75,7 +77,18 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
   before the ledger's `request`; `retrieve()`'s own `k`; `RemoteEmbedder`'s `maxResponseBytes`).
 - A per-call budget `derive`s from the ambient ledger and only TIGHTENS. **A derived ledger reports
   back up the chain** (every debit on every ancestor; `reserve` checks each `request` scope); the
-  STORE is written once, by the ledger the call was made on; reservations queue on the ROOT's turnstile.
+  STORE is written once, by the ledger the call was made on.
+- **`reserve` debits, then checks — never a read-then-write across an `await`.** The in-memory scopes
+  check and debit synchronously; the store's go through `BudgetStore.take(key, tokens, limit)`, which
+  is REQUIRED and must be atomic (no default over `spent` + `add` — that pair is the race). A refusal
+  at a later scope gives back what the earlier ones took.
+- **The store is touched only for a scope whose ceiling is DECLARED** (`takeScope`, `meteredKeys`):
+  every call carries keys, so a write per key grew the default store by one entry per caller.
+  `MemoryBudgetStore` has no window and no eviction (eviction is a ceiling bypass); a counter back
+  at zero is deleted.
+- **`llm()`, `agent()`, `hive()` root as `currentBudget() ?? gateway.callLedger(budgetKeysFor(ctx.actor))`**
+  — the gateway's ceilings, keyed `actor:<kind>:<id>` / `org:<orgId>`. `callLedger` is required on
+  `Gateway`; `hive()` asks `installedGateway()` so a hive of plain actions needs none.
 - **`BudgetStore` is where `actor` and `org` live; the default is per PROCESS**
   (`createGateway({ budgetStore })`). `add` takes a negative `tokens` for a release — a store that
   clamps at zero leaks the ceiling.
@@ -88,6 +101,9 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
 
 - **`llm()` returns an `action`**, never a ninth primitive; it adds only the model half: render the
   prompt, project `output` into the one `respond` tool, reserve the budget, consult the semantic cache.
+- **A non-object `output` is wrapped in `{ value }` and unwrapped** (`respond.ts`) — a tool's input is
+  an object; never refused, because `.stream()` serves `output: t.string`. `parseJsonish` is two
+  `indexOf` scans, never a backtracking pattern.
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim** (`index.test.ts`).
 - One repair turn, then `X_LLM_OUTPUT_INVALID`. A refusal (a 200 with no answer) is `X_LLM_REFUSED`
   before the parse, carrying `stopDetails.category`; a truncated invalid answer is `X_LLM_TRUNCATED`.
@@ -116,6 +132,11 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
 
 ## Invariants — providers and the gateway
 
+- **The response cache key is core's `fingerprint` over the request, each tool WHOLE** (every `llm()`
+  tool is `respond`); a throwing `cache.set` is logged (`ai.cache.write_failed`), never a failure.
+- **An unknown stop/finish reason FAILS CLOSED as `max_tokens` on both formats**, streamed or not.
+- **One failure-body reader** (`error-body.ts`'s `detailOf`, bounded at `READ_LIMIT`) and one
+  `withoutKey` scrub — the embedder included.
 - **`attempt` collects TRANSPORT failures only**: an `UltimateError` other than
   `X_AI_PROVIDER_UNAVAILABLE` is rethrown on the spot (the same misconfiguration everywhere). Read
   with `stringField(error, 'code')`.
@@ -188,9 +209,12 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
     ("superseded").
   - A tool result is rendered totally (`'null'` for `undefined`; a non-JSON result reported as such,
     never as a failure); the throw is read with `stringField`.
+  - **A 5xx code's cause reaches the model only when core's `hasPublicCause` allows it** (status from
+    `@ultimat3/http`'s `statusFor`) — else `CODE: HIDDEN_TOOL_CAUSE`, plus a branded `callerFix`. The
+    same verdict a problem document and `@ultimat3/mcp` give.
 - **`hive()` is a fan-out action** (`PRIMITIVE_FACTORIES`): `HiveResult` is a SCHEMA from the
   member's `output`; three arms (`ok`/`failed`/`skipped`) and three counters; `members` in SPLIT
-  order with `index`; the hive never names an actor; no hive budget code (the root turnstile holds
+  order with `index`; the hive never names an actor; no hive budget code (the reservation holds
   it); a member's throw is recorded via `isThrownError`/`stringField`; `skipped` reasons
   `SKIPPED_ABORTED` / `SKIPPED_NO_INPUT`; `onMemberError` is required; `concurrency` 4, `minMembers`
   2 (a below-floor split still runs serially); an empty split is `X_HIVE_EMPTY`; an aborted `ctx`
@@ -206,13 +230,17 @@ local `=== true`. An in-app agent and an external one must be offered exactly th
 - **No fix line may name `x ai`** (planned). An eval is selected with `x test eval --filter <name>`;
   `eval-errors.test.ts` asserts every `x test <word>` is one of the six types.
 - Every eval result carries the prompt hash. An eval gates on the DROP from its recorded baseline,
-  mean AND per case. Never-recorded is `X_EVAL_BASELINE_MISSING`, corrupt is `X_EVAL_BASELINE_INVALID`.
+  mean AND per case, both sides rounded as the baseline is written. Never-recorded is `X_EVAL_BASELINE_MISSING`, corrupt is `X_EVAL_BASELINE_INVALID`.
   `baseline` is `import.meta.resolve('./…')`. Every prompt is named by an eval (`X_EVAL_MISSING`, by
   prompt ID). `ULTIMATE_EVAL_RECORD=1` records; a deliberately-worse test calls `run`, never
   `assert`; `x verify` with the flag is `X_EVAL_RECORDING` and runs no eval. The gate asks for a
   recorded baseline, not only a declaration.
-- Retrieval is hybrid by default; no vector-only path. **`chunk()` hard-wraps**, and the overlap
-  carry stops at `buffer.length - 1`.
+- Retrieval is hybrid by default; no vector-only path. **`chunk()` hard-wraps**, the overlap
+  carry stops at `buffer.length - 1` and yields to a next unit it does not fit beside (no chunk over
+  `size`); `metadata.source` is written AFTER the caller's spread. `VectorStore.prune` is required.
+- **A store with no tenant bound, read inside a request whose actor has an `orgId`, is
+  `X_VECTOR_UNSCOPED`** (`assertTenantRead`, both stores, every read). `scope: UNSCOPED`
+  (`crossTenant: true`) is the named opt-in; an omitted scope is `UNBOUND`.
 - `PgVectorStore` is the only production vector path (pgvector + FTS in the app's Postgres);
   `MemoryVectorStore` enforces the same envelope. **`pg-vector.live.test.ts` refuses to skip** on a
   Postgres without the extension (CI uses `pgvector/pgvector:pg17`).

package/README.md

@@ -4,7 +4,7 @@ The LLM gateway primitive. Every model call in an Ultimate app goes through it,
 and cost accounting cannot be bypassed by a stray `fetch`.
 
 ```ts
-import { createGateway, AnthropicProvider, EchoProvider } from '@ultimat3/ai';
+import { budgetKeysFor, createGateway, AnthropicProvider, EchoProvider } from '@ultimat3/ai';
 
 export const ai = createGateway({
   providers: [new AnthropicProvider(), new EchoProvider()],   // ANTHROPIC_API_KEY, or { apiKey }
@@ -12,8 +12,9 @@ export const ai = createGateway({
   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 () => {
+// Budgets are scoped, and every nested call inside the scope shares one ledger. `llm()`, `agent()`
+// and `hive()` open one keyed on their caller (`budgetKeysFor(ctx.actor)`) without being asked.
+const answer = await ai.scope(budgetKeysFor(actor), async () => {
   const { text } = await ai.generate({
     model: 'claude-opus-5',
     system: 'You summarise support tickets.',
@@ -27,8 +28,8 @@ const answer = await ai.scope({ actorKey: actor.id, orgKey: actor.orgId }, async
 
 ## Budgets — and which of the three is fleet-wide
 
-`request` is one call chain. `actor` and `orgs` are counters across calls, so where they live
-decides what they mean:
+`request` is one call chain. `actor` and `org` are counters across calls, keyed
+`actor:<kind>:<id>` and `org:<orgId>` (`budgetKeysFor`), so where they live decides what they mean:
 
 | `budgetStore` | `actor` / `org` counts | Right for |
 |---|---|---|
@@ -40,15 +41,25 @@ import { AnthropicProvider, type BudgetStore, createGateway } from '@ultimat3/ai
 
 declare const redis: {
   incrby(key: string, by: number): Promise<number>;
+  eval(script: string, keys: readonly string[], args: readonly string[]): Promise<number>;
   del(key: string): Promise<unknown>;
   flushdb(): Promise<unknown>;
 };
 
+// Add only if the total stays within the limit, in ONE step on the server; answers what was spent before.
+const TAKE = `local s = tonumber(redis.call('get', KEYS[1]) or '0')
+if s + tonumber(ARGV[1]) > tonumber(ARGV[2]) then return -1 - s end
+redis.call('incrby', KEYS[1], ARGV[1]) return s`;
+
 const sharedBudget: BudgetStore = {
   spent: (key) => redis.incrby(key, 0),
   add: async (key, tokens) => {
     await redis.incrby(key, tokens);
   },
+  take: async (key, tokens, limit) => {
+    const answer = await redis.eval(TAKE, [key], [String(tokens), String(limit)]);
+    return answer < 0 ? { taken: false, spent: -1 - answer } : { taken: true, spent: answer };
+  },
   reset: async (key) => {
     await (key === undefined ? redis.flushdb() : redis.del(key));
   },
@@ -61,8 +72,14 @@ export const sharedGateway = createGateway({
 });
 ```
 
-Three methods, and `add` takes a **negative** `tokens` — releasing a reservation the call never
-spent is a credit, so a store that clamps at zero leaks the ceiling. `org: 20_000_000` on the
+The store is touched only for a scope whose ceiling is **declared** — no `actor` / `org` in
+`budget`, no counter and no write, however many callers. There is no window: a counter lives until
+`reset()` or (on the default store) a restart, and is never evicted, because forgetting a counter
+hands that caller its ceiling back. A per-day or per-month window is a shared store whose keys expire.
+
+Four methods. `take` is the reservation and must be **atomic** — a `spent` then an `add` is the
+read-then-write two concurrent requests both pass. `add` takes a **negative** `tokens` — releasing a
+reservation the call never spent is a credit, so a store that clamps at zero leaks the ceiling. `org: 20_000_000` on the
 default store at `replicas: 6` is six ledgers of twenty million, which is a budget that is not one.
 
 ## Rules the gateway enforces
@@ -82,7 +99,8 @@ default store at `replicas: 6` is six ledgers of twenty million, which is a budg
 | A local refusal is never collected into `X_AI_PROVIDER_UNAVAILABLE` | `X_AI_KEY_MISSING` and `X_AI_REQUEST_INVALID` are raised before the request leaves; retrying them across providers burns attempts on the same answer and discards the runnable `fix:`. `generate()` and `stream()` therefore answer the same misconfiguration the same way |
 | Fallback is across **providers serving one model**, never across models | a silent model swap changes what answered, what it cost and which eval baseline the answer belongs to; the gateway stamps `result.provider`, and `llm()` puts it on the span as `llm.provider`, so the fallback that does exist is never silent |
 | The repair turn replays the tool call's arguments, never an empty `text` | an answer through the `respond` tool leaves `text` empty, and an empty text block is a 400 — the repair came back as `X_AI_PROVIDER_UNAVAILABLE` |
-| `reserve()` **debits** the estimate and takes a turn | three concurrent calls otherwise read the same `spent()`, all pass, and all three record against a ceiling only one of them fitted; `record` reconciles and `release` gives it back |
+| `reserve()` **debits, then checks** | the in-memory scopes check and debit with no `await` between, the store's through its atomic `take`; a read-then-write let concurrent calls — one request per scope racing one org key — all read the same `spent()` and all pass. `record` reconciles and `release` gives it back |
+| The cache key is every tool **whole**, through core's `fingerprint` | every `llm()` tool is named `respond`, so a key over names served an answer shaped for an old `output` schema; a cache `set` that throws is logged, never turned into a failure of a call already paid for |
 | A refusal is never cached | a cached one keeps serving a classifier decision after the prompt was fixed |
 | Retries use **full jitter**, from core's one curve | synchronised retries from N workers reproduce the rate limit. `backoffMs` is `@ultimat3/core`'s `backoffDelay` with the gateway's field names mapped onto it, and the roll is `createGateway({ random })` — injectable, so the schedule is a unit test rather than a range |
 | A 4xx is never retried **except 408, 409 and 425** | the same body gets the same rejection and burns the budget — but a request the server stopped reading (408), a round a concurrent writer won (409) and a handshake that had not finished (425) are transient by construction, and core's `isRetryableStatus` is the one table that says so |
@@ -265,9 +283,9 @@ 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 |
+| `output` | projected into the one tool the model may answer through; a non-object `output` (`t.string`, `t.number`, an array) travels wrapped in `{ value }` and comes back unwrapped, because a tool's input must be an object; 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 |
+| `budget` | reserved against the worst case **before** the provider is reached — nothing spent, nothing truncated. The gateway's `actor` / `org` ceilings count the CALLER (`budgetKeysFor(ctx.actor)`) |
 | `cache.semantic` | one store per scope, keyed by embedding; a prompt version bump reaches a different store, so the bump *is* the invalidation. `scope` receives `{ input, ctx }` and **defaults to the calling actor** — the narrowest key, `@ultimat3/query`'s `readAuthority` rule; a shared store is `scope: () => 'global'`, written down |
 | `policy` | the same object every surface evaluates — an MCP call and an HTTP call are denied identically |
 | `vars` | the declared place an `llm()` call loads data, so a reader can see what was sent — the redactor sees it (and every `agent()` tool result), and a `Secret` is refused here |
@@ -373,7 +391,7 @@ sub-agents** with no supervisor primitive anywhere.
 | three arms — `ok`, `failed`, `skipped` — never two | *ran and threw* and *never ran* are different facts, and an aborted sibling is the second. Collapsing them makes "the hive stopped early" read as "every remaining item is bad data" |
 | `onMemberError` is **required** | `'abort'` stops and leaves the rest `skipped`; `'collect'` harvests the rest. Both are right for somebody, so neither is a default |
 | the hive **never names an actor** | `split` derives member inputs from `input` and `ctx` and from nothing a model emitted; each member runs through its own callable, so `invoke` applies the member's own policy with `ctx.actor` untouched |
-| `concurrency` bounds the fan-out; one derived ledger bounds the spend | the ceiling holds under parallelism because the budget's root turnstile debits before the call, so three members against a ceiling only one fits leave exactly one `ok` — no hive-specific budget code exists |
+| `concurrency` bounds the fan-out; one derived ledger bounds the spend | rooted as `llm()` and `agent()` root theirs — the gateway's ceilings, keyed on the caller — and the reservation debits before it checks, so three members against a ceiling only one fits leave exactly one `ok` — no hive-specific budget code exists |
 | an empty split is `X_HIVE_EMPTY` | "0 ok, 0 failed" cannot be told apart from a query that returned no rows and nobody noticed |
 | `minMembers` (default 2) stops fanning out, and **drops nothing** | a member's fixed cost dominates trivial work; below the floor every input still runs, serially |
 | an aborted `ctx` unwinds the whole hive with `X_ABORTED` | distinct from `onMemberError: 'abort'`, which is a completed run with a partial harvest worth returning — here there is nobody left to hand it to |
@@ -609,13 +627,20 @@ Allow-lists are default deny: a row missing the key is invisible, and an empty l
 nothing. `scoped()` only ever **tightens** — re-scoping to a different tenant is
 `X_VECTOR_SCOPE_WIDENED`, never a silent widening.
 
+A store opened without a scope binds no tenant, and **reading it inside a request acting for an
+org is `X_VECTOR_UNSCOPED`** — the forgotten `.scoped()` that searched every tenant's rows. Outside a
+request, or for an actor with no org, it reads as before. The backfill path opts in by name:
+`new PgVectorStore({ name, dimension, scope: UNSCOPED })`, or `store.scoped(UNSCOPED)`.
+
 `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. All three
 splits are load-bearing: the wrap is what bounds a UNIT (a base64 blob, a minified line, a CJK
 paragraph the sentence alphabet cannot see), and a unit larger than `size` is one the size check
 can never flush, so it rode every chunk after it — `As of 2026-08`, a ~1,000-token document
 indexed as nine chunks of the same sentence. The overlap carries a tail forward and never the
-whole buffer, for the same reason.
+whole buffer, for the same reason — and it yields, oldest unit first, to a next unit it does not fit
+beside: no chunk exceeds `size`. Every chunk's `metadata.source` is the document id, written over
+any `source` the caller passed, because `indexDocument` prunes a re-index by it.
 
 ## Tools: the same projection as MCP
 
@@ -629,6 +654,12 @@ An in-app agent and an external MCP agent both end at the same `invoke` — `run
 carries it, and an action facade has no `.run` of its own. So they authorize identically. The
 actor comes from the request context, never from the model.
 
+A failed tool reads back as `CODE: cause (fix: …)` — except a 5xx code whose cause core's
+`hasPublicCause` does not declare public, which reads `CODE: ` plus a fixed sentence (and a
+`callerFix`, when the `UltimateError` declared one): the rule a production problem document follows,
+and the one `@ultimat3/mcp` applies. The model's provider keeps every request it is sent, so a
+database message in a tool result is a disclosure nothing can recall.
+
 ## Errors
 
 **`X_AI_PROVIDER_UNAVAILABLE` carries `retry: "retryable"` in `--json`, `As of 2026-08-23`**
@@ -654,6 +685,7 @@ fail-closed `terminal` default.
 | `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_VECTOR_UNSCOPED` | a store with no tenant bound was read inside a request acting for an org; `scope: UNSCOPED` is the named opt-out |
 | `X_NOT_IMPLEMENTED` | a remote driver with no key or transport; the fix names the env var |
 
 ### Error classes
@@ -688,3 +720,4 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `LlmTruncatedError` | `X_LLM_TRUNCATED` | `src/errors.ts` |
 | `VectorDimMismatchError` | `X_VECTOR_DIM_MISMATCH` | `src/errors.ts` |
 | `VectorScopeWidenedError` | `X_VECTOR_SCOPE_WIDENED` | `src/errors.ts` |
+| `VectorUnscopedError` | `X_VECTOR_UNSCOPED` | `src/vector-scope.ts` |

package/package.json

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

package/src/agent-transcript.ts

@@ -5,8 +5,8 @@
  * next message — and a rule split across two call sites is a rule one of them will miss.
  */
 
-import { RESPOND } from './llm';
 import type { AiContentBlock, AiMessage, GenerateResult } from './provider';
+import { RESPOND } from './respond';
 import type { LlmToolCall, LlmToolResult } from './tools';
 
 /**

package/src/agent.ts

@@ -31,7 +31,7 @@ import type { AgentFact } from './agent-facts';
 import { registerAgentFact } from './agent-facts';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import type { BudgetLimits } from './budget';
-import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, withBudget } from './budget';
 import {
   AgentMaxTurnsError,
   AgentToolUnexposedError,
@@ -40,7 +40,7 @@ import {
   LlmTruncatedError,
 } from './errors';
 import type { LlmBudget } from './llm';
-import { answerAttributes, RESPOND, respondToolFor, structuredOutputOf } from './llm';
+import { answerAttributes } from './llm';
 import type { ModelId } from './models';
 import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
@@ -53,6 +53,8 @@ import type {
 } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
+import type { Respond } from './respond';
+import { RESPOND, respondFor } from './respond';
 import { aiGateway, aiRedactor } from './runtime';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
 import { asProjectableAction, runLlmToolCall, toLlmTools, toolLabel } from './tools';
@@ -153,7 +155,7 @@ export function agent<
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
 >(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
-  const respond = respondToolFor(def.output);
+  const respond = respondFor(def.output);
   // At declaration, because the tools are values by then and a run that discovers this at the
   // first request has already been declared, registered and projected as if it worked. Asked of
   // the DECLARATION rather than of the projection: `isMcpExposed` needs no name, and a real
@@ -241,7 +243,7 @@ async function run<
   V extends PromptVars,
 >(
   def: AgentDef<TInput, TOutput, V>,
-  respond: LlmTool,
+  respond: Respond,
   adapted: Adapted,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
@@ -271,11 +273,10 @@ async function run<
     const limits = limitsOf(def);
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
-    const ledger = (
-      currentBudget() ??
-      gateway.callLedger?.() ??
-      new BudgetLedger({ limits: {} })
-    ).derive(limits);
+    // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
+    const ledger = (currentBudget() ?? gateway.callLedger(budgetKeysFor(args.ctx.actor))).derive(
+      limits,
+    );
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
@@ -283,7 +284,7 @@ async function run<
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      tools: [...adapted.offered, respond],
+      tools: [...adapted.offered, respond.tool],
       // The caller's own signal, forwarded to the transport. A disconnect has to reach the socket,
       // not just the top of the next turn: a provider call already in flight is the expensive one.
       signal: args.ctx.signal,
@@ -328,8 +329,8 @@ async function run<
           // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
           // model turn asked for, each entry is an ordinary `action` carrying its own policy and
           // its own `rateLimit`, and a second ceiling here would be a throttle competing with
-          // those. A tool that calls a model still queues on the ledger's root turnstile, so the
-          // budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
+          // those. A tool that calls a model still reserves on the same ledger chain, which
+          // debits before it checks, so the budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
           // in the types or the docs ever said so.
           //
           // Order is by INDEX, not by completion: `Promise.all` resolves positionally and each
@@ -353,7 +354,7 @@ async function run<
           continue;
         }
 
-        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        const parsed = await validateAsync(def.output, respond.read(result));
         if (parsed.issues === undefined) return parsed.value;
         // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
         // turns left by construction — and unlike a tool result, the correction is the message.

package/src/budget.ts

@@ -10,7 +10,8 @@
 // module-scope `new` threw at EVALUATION in a browser bundle, where the bundler stubs
 // `node:async_hooks` to `{}`, and took every importer of `@ultimat3/ai` with it.
 
-import { asyncContext, finiteCount } from '@ultimat3/core';
+import type { Actor } from '@ultimat3/core';
+import { assert, asyncContext, finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { assertSameCurrency } from '@ultimat3/money';
 import { AiBudgetExceededError } from './errors';
@@ -64,14 +65,48 @@ export function estimateSpend(request: GenerateRequest): SpendEstimate {
   };
 }
 
+/**
+ * What one `take` found. `spent` is the counter as the store read it, BEFORE this take — so a
+ * refusal can say how much was left.
+ */
+export interface BudgetTake {
+  readonly taken: boolean;
+  readonly spent: number;
+}
+
 /** Where cross-request counters live. Swap for Redis in a multi-process deployment. */
 export interface BudgetStore {
   spent(key: string): Promise<number> | number;
   /** `tokens` may be NEGATIVE: releasing a reservation the call never spent is a credit. */
   add(key: string, tokens: number): Promise<void> | void;
+  /**
+   * Add `tokens` to `key` only if the total stays at or under `limit`, in ONE atomic step — a
+   * Redis `EVAL`, a SQL `update … set spent = spent + $2 where key = $1 and spent + $2 <= $3`.
+   * Required, with no default built on `spent` + `add`: that pair is the read-then-write two
+   * concurrent requests both pass, which is the overspend this member exists to close.
+   */
+  take(key: string, tokens: number, limit: number): Promise<BudgetTake> | BudgetTake;
   reset(key?: string): Promise<void> | void;
 }
 
+/**
+ * The store keys a call's identity is counted under: the acting identity (kind and id — one window
+ * per actor, whichever org it acts in) and its org, when it has one. Derived, never taken from a
+ * declaration, so every `llm()`, `agent()` and `hive()` binds the gateway's `actor` / `org` ceilings
+ * to whoever called it. An anonymous caller is one identity: every anonymous call shares its window.
+ */
+export interface BudgetKeys {
+  readonly actorKey?: string;
+  readonly orgKey?: string;
+}
+
+export function budgetKeysFor(actor: Actor): BudgetKeys {
+  return {
+    actorKey: `actor:${actor.kind}:${actor.id}`,
+    ...(actor.orgId === undefined ? {} : { orgKey: `org:${actor.orgId}` }),
+  };
+}
+
 /**
  * What `reserve` debited, so `record` can reconcile it against the provider's real counts and
  * `release` can give it back. Held by the caller rather than the ledger because one ledger serves
@@ -81,6 +116,13 @@ export interface BudgetReservation {
   readonly tokens: number;
 }
 
+/**
+ * The per-process default. There is NO window: a counter lives until `reset()` or a restart, so an
+ * `actor` / `org` ceiling here is "per process lifetime". It holds one entry per caller that has
+ * spent under a DECLARED ceiling (none at all without one), and deliberately no eviction: dropping
+ * a counter hands that caller its whole ceiling back, which is the bypass the ceiling exists to
+ * stop. A window — per day, per month — is a shared store whose keys expire.
+ */
 export class MemoryBudgetStore implements BudgetStore {
   private readonly counters = new Map<string, number>();
 
@@ -88,8 +130,27 @@ export class MemoryBudgetStore implements BudgetStore {
     return this.counters.get(key) ?? 0;
   }
 
+  /** A counter back at zero is deleted: absent and zero are the same answer, and an entry costs. */
   add(key: string, tokens: number): void {
-    this.counters.set(key, this.spent(key) + tokens);
+    this.write(key, this.spent(key) + tokens);
+  }
+
+  /** Atomic because it is synchronous: nothing else runs between the read and the write. */
+  take(key: string, tokens: number, limit: number): BudgetTake {
+    const spent = this.spent(key);
+    if (spent + tokens > limit) return { taken: false, spent };
+    this.write(key, spent + tokens);
+    return { taken: true, spent };
+  }
+
+  /** How many counters are held — one per caller that has spent under a declared ceiling. */
+  size(): number {
+    return this.counters.size;
+  }
+
+  private write(key: string, total: number): void {
+    if (total === 0) this.counters.delete(key);
+    else this.counters.set(key, total);
   }
 
   reset(key?: string): void {
@@ -133,13 +194,6 @@ export class BudgetLedger {
    * inside it, and its `request` ceiling was re-granted in full to every one of them.
    */
   private parent: BudgetLedger | undefined;
-  /**
-   * Reservations take turns. Check-then-debit spans an `await store.spent()`, and three callers
-   * interleaving inside it is the bypass this ledger exists to close — one event loop, so a
-   * promise chain IS the lock. A store shared across PROCESSES needs an atomic increment of its
-   * own; this closes the parallelism inside one.
-   */
-  private turnstile: Promise<unknown> = Promise.resolve();
 
   constructor(input: BudgetLedgerInput) {
     // The ceilings are screened where they LAND, because `assertScope` compares with `>`: a `NaN`
@@ -156,35 +210,19 @@ export class BudgetLedger {
   }
 
   /**
-   * Check an estimate against every applicable scope BEFORE the call, then DEBIT it. Throws on
-   * the first scope that cannot cover it, naming that scope, so the fix line points at one knob
-   * rather than four.
+   * Check an estimate against every applicable scope BEFORE the call, and DEBIT it in the same
+   * step. Throws on the first scope that cannot cover it, naming that scope, so the fix line points
+   * at one knob rather than four.
    *
-   * The debit is what makes the ceiling hold under parallelism. Checking without debiting meant
-   * three concurrent calls under one ledger all read `spent() === 0`, all passed, and all three
-   * recorded against a ceiling only one of them fitted — an "un-bypassable" org budget bypassed
-   * by `Promise.all`. `record` replaces the estimate with the real counts; `release` gives it
-   * back when the call never happened.
+   * Debit-then-check, never check-then-debit: the in-memory scopes are checked and debited with no
+   * `await` between (one event loop, so that IS atomic), and the store's scopes go through its
+   * atomic `take`. Any read-then-write across an `await` lets concurrent calls — `Promise.all` of
+   * derived ledgers, or one request per scope racing one org key — all read the same `spent`, all
+   * pass, and all debit a ceiling only one fitted. A refusal at a later scope gives back what the
+   * earlier ones took. `record` replaces the estimate with the real counts; `release` gives it back
+   * when the call never happened.
    */
   async reserve(estimate: SpendEstimate): Promise<BudgetReservation> {
-    // The ROOT's turnstile, not this ledger's: reservations under one scope take turns even when
-    // each call derived its own ledger, which is every `llm()` call. A per-ledger queue serialised
-    // nothing once `derive` existed — `Promise.all` of three derived ledgers all read the chain
-    // before any of them debited it.
-    const gate = this.rootLedger();
-    const turn = gate.turnstile.then(() => this.reserveNow(estimate));
-    // Chained on a settled shadow: one refusal must not reject every reservation queued behind it.
-    gate.turnstile = turn.catch(() => undefined);
-    return await turn;
-  }
-
-  private rootLedger(): BudgetLedger {
-    let ledger: BudgetLedger = this;
-    while (ledger.parent !== undefined) ledger = ledger.parent;
-    return ledger;
-  }
-
-  private async reserveNow(estimate: SpendEstimate): Promise<BudgetReservation> {
     // Every ledger in the chain, because each keeps its own counter and the tightest limit is not
     // always the one with the most spent against it.
     for (let l: BudgetLedger | undefined = this; l !== undefined; l = l.parent) {
@@ -192,19 +230,53 @@ export class BudgetLedger {
     }
     // 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);
-    await this.debit(estimate.tokens);
+    this.debitChain(estimate.tokens);
+    const taken: string[] = [];
+    try {
+      await this.takeScope('actor', this.limits.actor, this.actorKey, estimate.tokens, taken);
+      await this.takeScope('org', this.limits.org, this.orgKey, estimate.tokens, taken);
+    } catch (error) {
+      this.debitChain(-estimate.tokens);
+      for (const key of taken) await this.store.add(key, -estimate.tokens);
+      throw error;
+    }
     return { tokens: estimate.tokens };
   }
 
+  /**
+   * One store scope, and only when its ceiling is DECLARED: every `llm()` / `agent()` / `hive()`
+   * carries its caller's keys, so writing per key grew `MemoryBudgetStore` by one entry per caller
+   * forever — and cost a shared store two writes a call — for counters no ceiling reads. Records
+   * the key it took, so a refusal further on can give it back.
+   */
+  private async takeScope(
+    scope: 'actor' | 'org',
+    limit: number | undefined,
+    key: string | undefined,
+    tokens: number,
+    taken: string[],
+  ): Promise<void> {
+    if (key === undefined || limit === undefined) return;
+    const outcome: unknown = await this.store.take(key, tokens, limit);
+    // The store is the app's: a shape it did not promise must be a coded refusal, never a
+    // `TypeError` from reading `.taken` off `undefined` inside the reservation.
+    assert(
+      isBudgetTake(outcome),
+      `BudgetStore.take("${key}") answered ${typeof outcome}, not { taken: boolean, spent: number }`,
+      'return { taken, spent } from take(key, tokens, limit), spent being the counter before this take',
+    );
+    if (!outcome.taken) {
+      throw new AiBudgetExceededError({
+        scope: `${scope}:${key}`,
+        requested: tokens,
+        remaining: limit - outcome.spent,
+        limit,
+      });
+    }
+    taken.push(key);
+  }
+
   /** Give a reservation back: a provider that threw, a stream abandoned before `done`. */
   async release(reservation: BudgetReservation | undefined): Promise<void> {
     if (reservation === undefined) return;
@@ -258,11 +330,25 @@ export class BudgetLedger {
    */
   private async debit(tokens: number): Promise<void> {
     if (tokens === 0) return;
+    this.debitChain(tokens);
+    // The keys `reserve` took — a scope with a declared ceiling — and no others, so a reconcile
+    // never creates the counter `takeScope` declined to.
+    for (const key of this.meteredKeys()) await this.store.add(key, tokens);
+  }
+
+  /** The store keys this ledger meters: a key whose scope declares a ceiling. */
+  private meteredKeys(): readonly string[] {
+    const keys: string[] = [];
+    if (this.actorKey !== undefined && this.limits.actor !== undefined) keys.push(this.actorKey);
+    if (this.orgKey !== undefined && this.limits.org !== undefined) keys.push(this.orgKey);
+    return keys;
+  }
+
+  /** The in-memory half: this ledger's `request` counter and every ancestor's. */
+  private debitChain(tokens: number): void {
     for (let l: BudgetLedger | undefined = this; l !== undefined; l = l.parent) {
       l.requestTokens += tokens;
     }
-    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> {
@@ -313,6 +399,12 @@ function assertFiniteLimits(limits: BudgetLimits): BudgetLimits {
   return limits;
 }
 
+function isBudgetTake(value: unknown): value is BudgetTake {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record['taken'] === 'boolean' && Number.isFinite(record['spent']);
+}
+
 /** 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>);