@ultimat3/ai 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -4,7 +4,12 @@ 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), `money`, `policy`, `schema`, `time`.
+`db` (pgvector), `jobs` (`agentJob()`), `money`, `policy`, `schema`, `time`.
+
+**`jobs` was declared 2026-08, for `agentJob()`.** `packages/action/src/job-handle.ts`'s header
+already named this package as the home: `isJobHandle` needs `kind === 'job'` plus membership of a
+WeakMap only `job()` writes, and `action` and `jobs` are both tier 3, so the bridge has to live at
+tier 4+. Downward edge, nothing new in the tier table.
 
 `mcp` is the same tier, so the LLM-tool projection is restated structurally in `tools.ts`
 rather than imported. Same contract, two wire formats — and the same *decision*: `toLlmTools` and
@@ -44,12 +49,20 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 | `pg-vector-sql.ts` | every pgvector statement: DDL, upsert, cosine, FTS, RRF fusion |
 | `pg-vector.ts` | `PgVectorStore` — the production store |
 | `rag.ts` | chunker, retriever, reranker, budgeted context assembler |
-| `tools.ts` | action → LLM tool definition; `runLlmToolCall` |
+| `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 |
 | `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 |
+| `agent-facts.ts` | `describeAgents()` — the agent registry and the row a manifest publishes |
+| `agent-job.ts` | `agentJob()` — an agent as a real `JobHandle`, composed from `job()` |
+| `hive.ts` | `hive()` — one action fanned out over many inputs, declared as an `action` |
+| `hive-result.ts` | `HiveMember` / `HiveResult`, and the SCHEMA built from the member's own `output` |
+| `hive-errors.ts` | the `X_HIVE_*` class; its code and title stay in `errors.ts` |
 | `redaction.ts` | the one gate between `vars()` and the provider: a `Secret` never reaches a prompt |
 | `eval-errors.ts` | the five `X_EVAL_*` classes; their codes and titles stay in `errors.ts` |
+| `llm-cache.ts` | the semantic cache half of `llm()`: what a declaration may partition on, and the store it reaches |
+| `llm-fixture.ts` | the harness `llm.test.ts` and `llm-cache.test.ts` share. Not shipped (`!src/**/*-fixture.ts`) |
 | `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches |
 | `fix-line.ts` / `fix-line.evals.ts` / `fix-line.v1.baseline.json` / `fix-line.eval.test.ts` | the package's own dogfood eval — the first framework-level `*.eval.test.ts`, proving the `defineEval`/baseline convention actually fails a build |
 
@@ -67,6 +80,21 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 - Semantic scopes are separate cache INSTANCES, never a filter over a shared one — cosine
   similarity has no notion of a tenant. The instance key carries the prompt hash too, which is
   what makes a version bump invalidate the cache.
+- **The default scope is the calling ACTOR, and `scope` receives `{ input, ctx }`** (`As of
+  2026-08`). It defaulted to the literal string `'global'` and took the bare `input`, so the rule
+  in the bullet above was contradicted by the very default that shipped: `cache: { semantic: { ttl:
+  '1h' } }` put every tenant in one store, and `lookup` is a nearest neighbour with no tenant
+  predicate — proven by execution, tenant B asking a prompt within 0.92 cosine of tenant A's
+  received A's completion verbatim. And with only `input` to decide from, the one thing a partition
+  may never be chosen by (a value the caller sends) was the only thing it could be chosen by, while
+  `vars()` on the same declaration already took the pair. The default is
+  `JSON.stringify([actor.kind, actor.id, actor.orgId ?? null])` — `@ultimat3/query`'s
+  `readAuthority` rule, verbatim: a declaration that says nothing gets the NARROWEST key, and
+  widening is a written statement about what the answers are (`scope: () => 'global'`). **Breaking**
+  in both halves. `semanticCacheFor`'s instance map is bounded as a consequence
+  (`MAX_SEMANTIC_CACHE_SCOPES`, which IS core's `MAX_CACHED_FORMATTERS` — one bounded FIFO map in
+  the framework, whose name is about its first caller and not its contract): one entry per actor in
+  a process that never restarts is a leak where one entry per process was not.
 - A per-call budget `derive`s from the ambient ledger, so it can only TIGHTEN the actor and org
   ceilings it runs inside. Widening them from a declaration would be a budget that is not one.
   **A derived ledger reports back up the chain**: every debit and every recorded cost lands on it
@@ -92,6 +120,12 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   zero leaks the ceiling upward on every release.
 - Cost is `Money` (integer minor units), rounded **up**. Never a float, never a division
   that loses a fraction.
+- **The gateway's two reads of a provider's throw are total.** A `Provider` is the APP's object, so
+  the value it rejects with is one the framework did not build: `isRetryable` indexes it (a getter,
+  or a `Proxy` trap) and fails closed if the read raises, and the failure line goes through core's
+  `renderThrowable` rather than `error.message` / `String(error)` — a renderer that throws replaces
+  `X_AI_PROVIDER_UNAVAILABLE` with a bare `TypeError` nothing catches by code, and it bounds a
+  provider's 1MB body out of the `cause`.
 - Every non-2xx and every in-band `error` frame becomes `AiTransportError`, which carries a real
   `status` field — that field IS the gateway's retry rule. A body parsed as a message would read
   as an empty, successful answer, which is the one outcome nothing downstream can detect.
@@ -118,6 +152,15 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   *as* differences rather than flattening them.
 - A stream that ends without `message_stop` throws. A truncated answer that returns `end_turn`
   is a confidently wrong answer with no signal, which the budget rule already forbids.
+- **`readSse` caps the unterminated buffer** (`MAX_FRAME_CHARS`, `As of 2026-08`) and refuses with
+  `AiTransportError`. A peer that never sends a frame boundary — an HTML error page, a proxy on the
+  model's port — grew it without limit and no read deadline interrupted it, because every read
+  SUCCEEDED. Same call `@ultimat3/mail`'s `createReplyParser` makes: coded failure > OOM. `provider`
+  is a required argument for that reason — a transport error names the endpoint it is about.
+- **`llm()` forwards `ctx.signal` onto `GenerateRequest`**, `As of 2026-08`, the way `agent()`
+  always did. Without it a model call had no cancellation and no deadline: a caller that hung up
+  left the provider call in flight, billed and unread, and the repair turn bought a second one.
+  `.stream()` inherits it from the same `base`, which is where it matters most.
 - A tool call is emitted whole. `input_json_delta` fragments are not arguments until the block
   closes, so nothing partial reaches a caller.
 - Thinking chunks are never appended to `text`. A consumer concatenating every chunk must not
@@ -200,7 +243,13 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
     per-block stop event in this format.
   - `isComplete()` accepts `[DONE]` **or** a finish reason: plenty of servers in the family close
     the socket straight after the finish chunk, and a finish reason is the model saying why it
-    stopped, which a cut connection cannot produce.
+    stopped, which a cut connection cannot produce. **With one exception, `As of 2026-08`:
+    `[DONE]` while tool-call fragments are still pending is NOT complete.** `onFinish` is the only
+    drain of `pending` and the finish reason is the only close this format has, so the sentinel
+    alone cannot tell "the model finished asking" from "the connection died mid-arguments" —
+    reporting complete discarded a whole tool call and answered an empty, successful `end_turn`.
+    Refused rather than flushed, exactly as the Anthropic half refuses a missing `message_stop`:
+    emitting the fragments would run a tool's side effects from half a JSON object.
   - `role: 'system'`, not `developer` — the newer role is OpenAI's alone and every other server in
     the family knows only `system`.
   - **Only three models are priced** (`gpt-5.6-sol` / `-terra` / `-luna`, list price read
@@ -261,15 +310,156 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   (`X_AGENT_MAX_TURNS`, never a partial answer), by `budget.tokensPerRun` (the ledger's `request`
   scope, which accumulates across turns) and by `maxToolResultChars` — the transcript IS the
   request, so an untruncated tool result is re-billed once per remaining turn.
+  - **`tools` takes the real `action()`, adapted at this package's edge — decided 2026-08 (issue
+    #124).** It took `ProjectableAction` alone, which no `action()` structurally satisfies (an
+    action is `as`/`tool`/`openapi`/`job`/`contract` and the callable, never `run`), so the shape
+    the README documents was a `TS2741` and every test here hand-built a stand-in — which is why
+    the suite was green over an API that did not compile. `AgentTool = AnyAction |
+    ProjectableAction` and `asProjectableAction` are the fix, the same union `@ultimat3/mcp`'s
+    `ListedPrimitive` already accepted. **Not** a `run` member on the action facade, which was the
+    obvious alternative and is wrong three times over: it duplicates `.as()` (axiom 1), it would
+    offer a tool named `''` for an action `registerActions` has not named yet, and it would NOT
+    collapse `mcp`'s adapter, whose `toWireSchema` narrows to the subset that server's arg
+    validator can enforce while this one publishes the Messages API's (`packages/mcp/src/
+    from-action.ts` header). Two wire formats, two projections, one `invoke`.
+  - Projection happens on the FIRST RUN, memoised — never at declaration. `agent()` is evaluated at
+    module scope and `registerAction` stamps a name at boot, so `actionName()` at declaration would
+    make the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
+  - **An `agent()` is a tool of another `agent()`** — it returns an action, and an action is what a
+    tool is. That is the supervisor/sub-agent shape, with no `hive()` and no ninth primitive; the
+    sub-agent runs under the same actor, through its own policy.
   - A tool listed in `agent({ tools })` that is not `mcp: { expose: true }` is
     `X_AGENT_TOOL_UNEXPOSED` **at declaration**, not filtered at the call: a silently dropped tool
     reads as offered and is not. `isMcpExposed` is the one predicate, so an in-app agent and an
-    external MCP client see the same catalogue.
+    external MCP client see the same catalogue. Asked of the DECLARATION, not of the projection,
+    because exposure needs no name and the name does not exist yet.
+  - **`ctx.signal` is read, at three points.** `throwIfAborted` at the top of every turn and before
+    every tool batch, and `GenerateRequest.signal` forwarded into `fetch` by both providers. The
+    transcript IS the request, so a loop that keeps going after the caller disconnects re-sends it
+    once per remaining turn, runs every remaining tool's side effect and discards the answer —
+    eight provider calls for an answer nothing reads. `X_ABORTED` is core's, already shipped; no
+    new code. `signal` is deliberately absent from `cacheKeyFor` and from every estimate: it says
+    whether a call was ABANDONED, never what it asked for.
+  - **The tools of ONE turn run concurrently**, unbounded within the turn, results paired by index
+    so a fast tool cannot be matched to a slow tool's `tool_use` id. Serial cost 5x wall clock for a
+    turn that asked for five tools and nothing in the types or the docs said so. No second ceiling
+    here: the batch is what one model turn asked for, each entry is an action with its own `policy`
+    and `rateLimit`, and a tool that calls a model still queues on the ledger's root turnstile.
+    Guarantee is "no tool STARTS after the abort" — a tool already in flight unwinds through its
+    own handler's reading of `ctx.signal`, which is the action's to make.
+  - **`onTurn` is the per-turn observation, and `.stream()` on `agent()` is deliberately not shipped
+    yet.** A 90-second multi-turn run emitted nothing until it returned. `onTurn` reports facts
+    only — turn, model, tool names, stop reason, usage, that turn's cost — never the transcript and
+    never the actor, and the same facts land on the span as an `agent.turn` event so a run
+    declaring no hook is still readable in a trace. A throw from it FAILS the run: an observer that
+    quietly stopped working reads exactly like one that is fine. Tokens on a screen is a different
+    contract from turns in a loop, and half-shipping it would be the second path axiom 1 refuses.
   - **No semantic cache on `agent()`.** Similar prompts do not have similar answers once the answer
     depends on what `lookupOrder` returned this second.
+  - **Every `tool_use` block the transcript replays is answered by a `tool_result` in the very next
+    message** — the Messages API's own rule, and `agent-transcript.ts` owns both halves of it for
+    that reason. Two paths broke it, both through `respond`, which is filtered out of the calls
+    that RUN and replayed like any other block: a turn emitting a tool call AND `respond` together
+    (ordinary parallel tool use), and a `respond` whose input failed the output schema, followed by
+    a plain user message. Both were a 400 (`tool_use ids were found without tool_result blocks`),
+    i.e. `X_AI_PROVIDER_UNAVAILABLE` in place of a completed run, and `agent.test.ts` never mixed
+    the two so neither shipped visible. An unaccepted `respond` now comes back as its own
+    `tool_result`, `is_error`, saying why — the answer is SUPERSEDED, not wrong: it was written
+    before the results of the tools the same turn asked for existed, so the loop continues and the
+    model answers again with them in hand. Discarding the block instead would have been the other
+    legal fix and loses the record; USING the speculative answer would skip the tool results the
+    model itself asked for, after those tools already ran.
+  - **A tool result is rendered totally.** `runLlmToolCall` returns `content: string` and the loop
+    TRUNCATES it, so `JSON.stringify`'s other two answers both have to be handled: `undefined` for
+    an action that returns nothing (`'null'`), and a throw on a bigint, a cycle or a `toJSON` of
+    the value's own — reported as "the tool ran and its result is not JSON", never as a failure,
+    because a model told the tool failed calls it again and buys its side effects twice. The throw
+    it catches is read with `stringField`, never `typeof error.code === 'string'`: the value is an
+    app's, so the probe is a getter call or a `Proxy` trap inside the catch block.
   - `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
+  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.
+  - **`HiveResult` is a SCHEMA, not an interface**, built from the member action's own `output` and
+    embedded in the `ok` arm. That is what makes a hive project to OpenAPI, the typed client, the
+    MCP `outputSchema` and the manifest like any other action; a hand-written interface would have
+    given the type and none of the six projections, which is the whole reason it is a factory.
+  - **Three arms — `ok` / `failed` / `skipped` — never two.** A member that ran and threw and a
+    member that never ran are different facts, and an aborted sibling is the second. Two arms make
+    "the hive stopped early" indistinguishable from "every remaining item is bad data", which is
+    the difference between retrying the tail and fixing the source. `skipped` gets its own counter
+    beside `ok` and `failed` for the same reason: three arms and two counters means every caller
+    writes `members.length - ok - failed` once, and writes it wrong once.
+  - **`members` is in SPLIT order, always**, filled by index rather than pushed on settle, with
+    `index` on every arm so a caller can join a result back to its row without depending on array
+    position surviving a filter.
+  - **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. There is no `as(actor)` in the factory —
+    the same boundary `agent()` holds, and the reason both belong in the framework.
+  - **No hive-specific budget code, deliberately.** One derived ledger for the run, `withBudget`
+    around the pool, each member's `agent()` deriving again — and the ceiling holds under
+    parallelism because `reserve` DEBITS on the root's turnstile before the call. Three members
+    against a ceiling only one fits leave exactly one `ok`; that is asserted through the hive
+    rather than asserted about the ledger, because the ledger already promised it.
+  - **A member's throw is RECORDED, whatever it is.** `failureOf` reads it with `isThrownError` and
+    `stringField` from core, never `error instanceof Error` and `.message`: a member is an app's
+    action, so a `Proxy` makes `instanceof` run a `getPrototypeOf` trap, and a throw there takes
+    down the whole hive — the one outcome the three arms exist to prevent. `skipped` has two
+    reasons, because they are two facts: `SKIPPED_ABORTED` (a sibling failed under `'abort'`) and
+    `SKIPPED_NO_INPUT` (the split produced nothing at that index). One string for both sent a
+    caller to retry a tail that was never cut.
+  - **`onMemberError` is required.** `'abort'` stops and leaves the rest `skipped`; `'collect'`
+    harvests. Both are right for somebody, so neither may be inherited silently.
+  - `concurrency` defaults to 4 and `minMembers` to 2, and neither number is measured off any run —
+    the framework cannot know a provider's concurrency allowance. A below-floor split still runs
+    every input it produced, serially: dropping one would be silent data loss.
+  - An empty split is `X_HIVE_EMPTY`, never a successful run of zero members — "0 ok, 0 failed"
+    cannot be told apart from a query that returned no rows and nobody noticed.
+  - An aborted `ctx` unwinds the whole hive with `X_ABORTED`, which is a DIFFERENT event from
+    `onMemberError: 'abort'`: the latter is a completed run with a partial harvest worth returning,
+    the former has nobody left to hand it to.
+- **`describeAgents()` publishes what an `ActionDescriptor` cannot.** An agent projects to the same
+  descriptor as any other action, and that descriptor knows nothing about turns, tools, models or
+  prompt hashes — so "how far can this loop and what may it call" had no answer outside the source.
+  Same shape as `describePrompts()` / `describeEvals()`, and deliberately NOT a new
+  `ActionDescriptor` field: `@ultimat3/action` is tier 3 and knows nothing about models.
+  The facts are a THUNK, resolved when asked: `agent()` runs at module scope beside the actions it
+  lists, and every name in a row is stamped by `registerAction` at boot. An agent still carrying no
+  name has no row — not a silent drop, but the absence of a capability: an action with no name
+  reaches no route, no tool catalogue and no queue. `named()` builds a TWIN where registration
+  names in place, so an agent renamed that way is absent for the same reason; register it instead.
+- **`agentJob()` closes #125 for the agent case, by COMPOSING `job()`** — the returned value is one
+  `job()` seated in that package's own registry, so `.enqueue()`, the outbox, the worker's
+  cancellation, the dead-letter path, `x jobs show` and its manifest row arrive without a line here.
+  Never an imitation handle: `isJobHandle` needs `kind === 'job'` plus membership of a WeakMap only
+  `job()` writes, which is exactly what stops a second execution path existing.
+  - `name`, `tenant` and `retry` are REQUIRED, no defaults. `name` because a job name is the durable
+    queue key that queued, retrying and dead-lettered rows already carry — deriving it from the
+    export name would move delivery when somebody renames a variable. `tenant` and `retry` because
+    `jobs` states that every candidate default for `tenant` is a cross-tenant read waiting for the
+    first job that takes an org id in its input. Both are `TS2741` when omitted AND have runtime
+    backstops (`X_JOB_TENANT_REQUIRED`, the `retry.attempts` assert), for generated and JS callers.
+  - **Both reads of `target.job()` are LAZY**, and that is load-bearing: `actionName()` throws
+    `X_ACTION_UNREGISTERED` until boot stamps the export name, and `agentJob()` is evaluated at
+    module scope right beside the `agent()` it wraps. Same rule as `agent()`'s tool projection and
+    `describeAgents()`' thunk — third instance in this package.
+  - **The at-least-once trap is DOCUMENTED, not enforced, and that is a decision with evidence.**
+    `idempotencyKey` dedupes the ENQUEUE, never the ATTEMPT: a lost lease re-runs the agent from the
+    top, as does every page `backfill()` replays. So every tool an `agentJob()`'d agent may call has
+    to be idempotent. The framework cannot check it: `mutates` is not a fact an `action()` declares
+    — it exists only in `@ultimat3/mcp`, whose `projectable.ts` sets it to `true` for EVERY action —
+    so a read-only `lookupOrder` and a destructive `issueRefund` are indistinguishable, and
+    `ActionFacade`'s `Pick<>` carries no `idempotent` either (only `describe()` does, and that needs
+    a name). `isMutator` IS legible without a name, but `mutator()` is the local-first write
+    primitive: refusing only those would catch almost none of the risk while reading as if it caught
+    all of it. A wrong refusal is worse than a stated obligation, so the obligation is stated — in
+    `AgentJobOptions.idempotencyKey`'s doc comment and in the README, both naming the second refund.
+
 - **`configureAi({ redact })` is the one seam between `vars()` and the provider.** `vars()` is the
   one declared place a model call loads data, so it is the one place a redactor can see the row
   before it leaves the process; the redactor sees the whole RENDERED prompt and the system prompt,
@@ -323,6 +513,17 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   recorded — one no test asserts, one whose `baseline:` is a cwd-relative string — would otherwise
   satisfy `X_EVAL_MISSING` while gating on nothing.
 - Retrieval is hybrid by default. Do not add a vector-only convenience path.
+- **`chunk()` performs all three splits its header names — paragraph, sentence, HARD WRAP** (`As of
+  2026-08`). The wrap is what bounds a unit, and an oversized unit is one the size check can never
+  flush (it only fires when something is already in the buffer), so it re-seeded every following
+  chunk: a ~1,000-token document indexed as nine chunks totalling ~9,000, each carrying the same
+  sentence. The overlap carry stops at `buffer.length - 1` for the same reason — a flushed unit may
+  never become the whole of the next buffer.
+- **A caller's string is never used as an object KEY.** A `Record` lookup on one answers
+  `constructor`, `toString` and `valueOf` off the prototype chain, and every read here is of a
+  string a provider, a template author or a test fixture chose: the two wire tables are `Map`s,
+  `prompt.render` uses `Object.hasOwn` (a `{{constructor}}` slot rendered JS source into a billed
+  prompt and hashed it into the cache key), and so does `EchoProvider`'s `replies`.
 - `PgVectorStore` is the ONLY production vector path — pgvector and Postgres FTS in the app's own
   Postgres, never a second datastore. `MemoryVectorStore` is the dev twin and enforces the same
   envelope; a leak that only reproduces against real Postgres is a leak nobody finds.

package/README.md

@@ -108,6 +108,8 @@ for await (const chunk of ai.stream({ messages, maxTokens: 64_000 })) {
 | 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 |
+| `[DONE]` with a tool call still open **throws** | the OpenAI format has no per-call stop event, so the finish reason is the only close there is; the sentinel alone cannot tell "finished asking" from "cut mid-arguments" |
+| A body with no frame boundary in it **throws** | an SSE peer that never completes a frame is an unbounded allocation no read deadline interrupts |
 | An in-band `error` frame carries a status | `overloaded_error` mid-stream retries like a 529 on the handshake |
 
 ## Embeddings
@@ -249,7 +251,7 @@ export const summarize = llm({
   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 } },
+  cache:  { semantic: { threshold: 0.97, ttl: '7d' } },   // scope defaults to the ACTOR
   budget: { tokensIn: 8_000, costPerCall: { minor: 5, currency: 'USD' } },
   policy: can('post:read'),
 });
@@ -265,7 +267,7 @@ summarize.contract();    // the contract tests
 | `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 |
+| `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 one declared place a model call loads data, so a reader can see what was sent — and the one place a redactor sees it, and where a `Secret` is refused |
 
@@ -300,23 +302,161 @@ export const support = agent({
   output: t.object({ answer: t.string }),
   prompt: supportPrompt,
   vars:   ({ input }) => ({ orderId: input.orderId }),
-  tools:  [lookupOrder, issueRefund],          // actions, each mcp.expose
+  tools:  [lookupOrder, issueRefund],          // real actions, each mcp.expose
   maxTurns: 6,
   maxToolResultChars: 4_000,
   budget: { tokensPerRun: 200_000, costPerCall: { minor: 50, currency: 'USD' } },
   policy: can('order:support'),
+  onTurn: ({ turn, toolCalls, cost }) => progress.push({ turn, toolCalls, cost }),
 });
 ```
 
+`tools` takes the `action()` an app already wrote — `[lookupOrder, issueRefund]`, the imports
+themselves. `As of 2026-08`: it took a hand-shaped `ProjectableAction` until then, so the line
+above was a `TS2741` against every real action (issue #124) and the only thing that satisfied it
+was a stand-in written for a test.
+
+An `agent()` returns an action, so **an agent is a tool of another agent** — a supervisor lists a
+sub-agent in its own `tools` and the sub-agent runs under the same actor, through the same policy.
+No `hive()`, no supervisor primitive: it falls out of the factory rule.
+
 | Rule | Why |
 |---|---|
 | the actor is **`ctx.actor`**, read once, never from the model | this is the mistake a hand-rolled loop ships, and the reason the loop belongs in the framework |
+| an aborted `ctx` unwinds the run — at the top of every turn, before every tool batch, and on the socket | the transcript IS the request, so a loop that keeps going after the caller disconnects re-sends it once per remaining turn, runs every remaining side effect and discards the answer. `ctx.signal` rides on `GenerateRequest` too, so a call already in flight is cut rather than paid for |
+| the tools of **one turn** run concurrently, results paired by `tool_use` id | a turn asking for five tools cost 5x wall clock and nothing said so. Order is positional, never by completion; the batch is bounded by what one turn asked for, and each tool is an action with its own `policy` and `rateLimit`, so a second ceiling here would be a throttle competing with those |
+| `onTurn` reports each completed turn as it happens (and an `agent.turn` span event, always) | a 90-second run emitted nothing until it returned. Observation only — it cannot steer the loop, see the transcript or reach the actor — and a throw from it fails the run rather than being swallowed |
 | a tool that is not `mcp: { expose: true }` is `X_AGENT_TOOL_UNEXPOSED` **at declaration** | a silently dropped tool reads as offered and is not; `isMcpExposed` is the one predicate, so an in-app agent and an external MCP client see the same catalogue |
 | running out of turns is `X_AGENT_MAX_TURNS`, never a partial answer | a half-finished transcript returned as a result is working notes presented as a decision |
 | `budget.tokensPerRun` caps the **whole run** | a single call is bounded by `maxTokens`; a loop is bounded by nothing until this is set |
 | a tool result is truncated, and says so | the transcript IS the request, so an untruncated result is re-billed once per remaining turn |
 | **no semantic cache** | similar prompts do not have similar answers once the answer depends on what `lookupOrder` returned this second |
 
+## `hive()` — many members, one action
+
+Fan an action out over many inputs. The fourth factory over a primitive, after `llm()`,
+`backfill()` and `agent()`: a fan-out is still one server-authoritative operation with an input
+schema, an output schema and a policy.
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { hive } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = action({
+  input: t.object({ postId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  policy: allow(),
+  mcp: { expose: true },
+  handle: ({ input }) => ({ summary: input.postId }),
+});
+
+export const summariseBacklog = hive({
+  input: t.object({ postIds: t.array(t.uuid) }),
+  member: summarisePost,
+  split: ({ input }) => input.postIds.map((postId) => ({ postId })),
+  concurrency: 8,
+  minMembers: 2,
+  onMemberError: 'collect',
+  budget: { tokensPerRun: 500_000 },
+  policy: allow(),
+});
+```
+
+`member` is any action — most usefully an `agent()`, which makes a hive a **supervisor over
+sub-agents** with no supervisor primitive anywhere.
+
+| Rule | Why |
+|---|---|
+| `members` comes back in **split order**, with `index` on every arm | a hand-rolled `Promise.all` reports in completion order, so joining a result back to the row it came from silently depends on nothing having failed |
+| 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 |
+| 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 |
+
+## `agentJob()` — an agent as durable background work
+
+Run an agent over a million rows as resumable, retried, budgeted queue work. `As of 2026-08` this
+is the only way an agent reaches a queue at all: `.job()` hands back `kind: 'action-job'`, and
+`isJobHandle` needs `kind === 'job'` plus membership of a `WeakMap` only `job()` writes, so nothing
+externally shaped has ever reached the registry, the worker or the dead-letter path (issue #125).
+
+```ts
+import { t } from '@ultimat3/action';
+import { agent, agentJob, definePrompt } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = agent({
+  input: t.object({ postId: t.uuid, orgId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  prompt: definePrompt<{ postId: string }>({
+    id: 'summarise-post',
+    version: '1.0.0',
+    template: 'Summarise post {{postId}}.',
+  }),
+  vars: ({ input }) => ({ postId: input.postId }),
+  tools: [],
+  policy: allow(),
+});
+
+export const summariseBacklog = agentJob(summarisePost, {
+  name: 'summarise-backlog',
+  tenant: (input) => input.orgId,
+  retry: { attempts: 3, backoff: 'exponential' },
+});
+```
+
+It composes `job()` rather than imitating a handle, so `.enqueue()`, the outbox, the worker's
+cancellation, `x jobs show` and its manifest row all arrive for free. Pair it with `backfill()` for
+the sweep and `hive()` for the fan-out inside one page.
+
+| Rule | Why |
+|---|---|
+| `name` is required, and is the queue key | a job name is what queued, retrying and dead-lettered rows already carry, so renaming an export must not move where they are delivered |
+| `tenant` and `retry` are required, no default | `jobs` states it: every candidate default for `tenant` is a cross-tenant read waiting for the first job that takes an org id in its input. `tenant: 'none'` is the explicit statement that it touches no scoped table |
+| the action projection is read **lazily** | `agentJob()` runs at module scope beside the `agent()` it wraps, and names are stamped by `registerAction` at boot — reading `.job()` eagerly makes that ordinary file `X_ACTION_UNREGISTERED` |
+| one execution path, and it is the action's | `run` is `invoke(agent, input, { surface: 'job', ctx })`, so the agent's policy, input parse, budget scope and span all apply — and the `ctx` is the worker's, so an attempt timing out aborts the agent's turn loop |
+| the actor is the worker context's, never the model's | the job body runs with system authority and the org comes from the job's declared `tenant`; nothing a model emits can reach either |
+
+### The at-least-once trap, said plainly
+
+**`idempotencyKey` dedupes the ENQUEUE, never the ATTEMPT.** Two enqueues with the same payload are
+one row. One row that a worker claims, half-runs and loses the lease on is claimed again, and **the
+agent runs a second time from the top** — as does every page a `backfill()` replays, since its
+`handle` is at-least-once by construction.
+
+So every tool the agent may call has to be idempotent: an `upsertAll`, an `updateWhere`, a statement
+whose second run changes nothing. Otherwise a replayed attempt issues a second refund.
+
+**The framework does not check this, and the reason is worth knowing.** `mutates` is not a fact an
+`action()` declares — it exists only in `@ultimat3/mcp`, which sets it to `true` for *every* action
+it projects — so a read-only `lookupOrder` and a destructive `issueRefund` are indistinguishable
+here. A rule refusing every tool that has not declared `idempotent: true` would refuse the reads
+too, and a wrong refusal is worse than a stated obligation. `isMutator` is legible, but `mutator()`
+is the local-first write primitive and catches almost none of the risk while reading as if it
+caught all of it. This is a contract you keep, not one the compiler keeps for you.
+
+## `describeAgents()` — what the manifest can say
+
+```ts
+import { describeAgents } from '@ultimat3/ai';
+
+describeAgents();
+// [{ name: 'supportAgent', prompt: 'support@1.0.0', promptHash: '…', model: 'claude-opus-5',
+//    maxTurns: 6, maxToolResultChars: 4000, tools: ['issueRefund', 'lookupOrder'],
+//    budget: { tokensIn: null, tokensPerRun: 200000, costPerCall: { minor: 50, currency: 'USD' } },
+//    mcp: true }]
+```
+
+An agent projects to an `ActionDescriptor` like any other action, and that descriptor knows nothing
+about turns or tools — so "how far can this loop, and what may it call" had no answer outside the
+source. Names are read when you ask, not when the agent was declared: `registerAction` stamps them
+at boot, long after `agent()` ran at module scope. An agent nothing registered has no row, because
+an action with no name reaches no route, no tool catalogue and no queue.
+
 ## Redaction: one declared seam
 
 `vars()` is the one place a model call loads data, so it is the one place anything can sit between
@@ -462,7 +602,12 @@ nothing. `scoped()` only ever **tightens** — re-scoping to a different tenant
 `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.
+— 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.
 
 ## Tools: the same projection as MCP
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,13 +32,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/cache": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/money": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/action": "4.0.0",
+    "@ultimat3/cache": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/money": "4.0.0",
+    "@ultimat3/policy": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/agent-facts.ts

@@ -0,0 +1,70 @@
+// What an `agent()` IS, published for the manifest — turns, tools, budget, model, prompt hash.
+//
+// Nothing agent-shaped was visible anywhere before this: an agent projects to `ActionDescriptor`
+// like every other action, and that descriptor deliberately knows nothing about turns or tools,
+// so "which agents does this app have, how far can each one loop, and what may it call" had no
+// answer outside reading the source. Same shape as `describePrompts()` / `describeEvals()`, and
+// deliberately NOT a new `ActionDescriptor` field: @ultimat3/action is tier 3 and knows nothing
+// about models.
+
+import type { AnyAction } from '@ultimat3/action';
+import type { Money } from '@ultimat3/money';
+
+/** The declared ceilings, flattened so a manifest row is plain JSON. `null` is "not declared". */
+export interface AgentBudgetFact {
+  readonly tokensIn: number | null;
+  readonly tokensPerRun: number | null;
+  readonly costPerCall: Money | null;
+}
+
+export interface AgentFact {
+  /** The export name registration stamped — the same name `.tool()` and `tools/call` answer to. */
+  readonly name: string;
+  readonly prompt: string;
+  readonly promptId: string;
+  /**
+   * The prompt's content hash. An agent's behaviour is its prompt, so a row without one records
+   * which agent ran and not which agent it was — the same reason every eval result carries it.
+   */
+  readonly promptHash: string;
+  readonly model: string;
+  readonly maxTurns: number;
+  readonly maxToolResultChars: number;
+  /** Tool names, sorted — the catalogue this agent may call, which is its blast radius. */
+  readonly tools: readonly string[];
+  readonly budget: AgentBudgetFact;
+  /** Whether the agent itself is offered as a tool, so a supervisor could call it. */
+  readonly mcp: boolean;
+}
+
+/**
+ * Keyed by the action, and the facts are a THUNK: every name in a row — the agent's and its
+ * tools' — is stamped by `registerAction` at boot, long after `agent()` ran at module scope.
+ * Reading them here rather than at declaration is what makes a row name what an app can call.
+ */
+const registry = new Map<AnyAction, () => Omit<AgentFact, 'name'>>();
+
+export function registerAgentFact(target: AnyAction, facts: () => Omit<AgentFact, 'name'>): void {
+  registry.set(target, facts);
+}
+
+/**
+ * Every registered agent, by name.
+ *
+ * An agent still carrying no name is left out, and that is not a silent drop: a name is stamped by
+ * `registerAction`, an action without one reaches no route, no tool catalogue and no queue, so
+ * there is no capability for a row to describe. `named()` builds a TWIN rather than naming in
+ * place — registration names in place — so an agent renamed that way is absent for the same
+ * reason. Register it instead: `registerAction('supportAgent', support)`.
+ */
+export function describeAgents(): readonly AgentFact[] {
+  return [...registry.entries()]
+    .filter(([target]) => target.name !== '')
+    .map(([target, facts]) => ({ name: target.name, ...facts() }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/** Test-only reset. A module-level registry otherwise leaks between test files. */
+export function resetAgents(): void {
+  registry.clear();
+}