@ultimat3/ai 2.0.0 → 3.0.0

package/src/agent-transcript.ts

@@ -0,0 +1,94 @@
+/**
+ * The transcript one agent turn leaves behind: the assistant message replaying what the model
+ * emitted, and the user message answering it. One file because the Messages API's rule spans both
+ * halves — every `tool_use` block replayed here must be answered by a `tool_result` in the very
+ * 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 type { LlmToolCall, LlmToolResult } from './tools';
+
+/**
+ * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
+ * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
+ * because it has no `tool_result` to follow them with, and the API demands one.
+ */
+export function assistantTurn(result: GenerateResult): AiMessage {
+  const blocks: AiContentBlock[] = [];
+  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
+  for (const call of result.toolCalls) {
+    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
+  }
+  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
+  return blocks.length === 0
+    ? { role: 'assistant', content: '(no answer)' }
+    : { role: 'assistant', content: blocks };
+}
+
+/**
+ * What the model is told when it answered in the same turn it asked for a tool. Parallel tool use
+ * is normal, and the answer that comes with it was written before the tool result existed — so it
+ * is superseded, not wrong, and saying which is what stops the next turn repeating it verbatim.
+ */
+const SUPERSEDED = `This answer arrived in the same turn as the tool calls above, so it was written before their results existed. Read the results in this message, then call the "${RESPOND}" tool again.`;
+
+/**
+ * The tool results of one turn, plus a `tool_result` for every `respond` call the loop did not
+ * accept. The second half is not optional: `respond` is filtered out of the calls that get RUN,
+ * but it is replayed as a `tool_use` like any other, and a `tool_use` the next message does not
+ * answer is a 400 (`tool_use ids were found without tool_result blocks`) — the whole run lost to
+ * an `X_AI_PROVIDER_UNAVAILABLE` because the model did the ordinary thing.
+ *
+ * Real results stay first: they are what the model asked for, and the rejection reads as the
+ * instruction that follows them.
+ */
+export function toolResultTurn(
+  results: readonly LlmToolResult[],
+  chars: number,
+  unaccepted: readonly LlmToolCall[],
+): AiMessage {
+  return {
+    role: 'user',
+    content: [
+      ...results.map((result) => ({
+        type: 'tool_result' as const,
+        tool_use_id: result.toolUseId,
+        content: truncate(result.content, chars),
+        // A denial or a failure is an outcome the model should read and react to, flagged so it
+        // does not read as data.
+        ...(result.isError === true ? { is_error: true } : {}),
+      })),
+      ...rejections(unaccepted, SUPERSEDED),
+    ],
+  };
+}
+
+/**
+ * The correction after an answer that failed its schema, in whichever shape the turn it corrects
+ * demands: a `tool_result` when the answer came through `respond` (the dominant path, and a
+ * `tool_use` the API insists on seeing answered), a plain user message when the model answered in
+ * prose and there is no id to name. Framework text, so never truncated by `maxToolResultChars`.
+ */
+export function repairTurn(unaccepted: readonly LlmToolCall[], issues: string): AiMessage {
+  const text = `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
+  return unaccepted.length === 0
+    ? { role: 'user', content: text }
+    : { role: 'user', content: rejections(unaccepted, text) };
+}
+
+/** A `tool_result` saying an answer was not taken, flagged so the model does not read it as data. */
+function rejections(calls: readonly LlmToolCall[], text: string): readonly AiContentBlock[] {
+  return calls.map((call) => ({
+    type: 'tool_result' as const,
+    tool_use_id: call.id,
+    content: text,
+    is_error: true,
+  }));
+}
+
+/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
+function truncate(text: string, chars: number): string {
+  if (text.length <= chars) return text;
+  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
+}

package/src/agent.ts

@@ -20,10 +20,14 @@
 
 import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
-import type { Ctx } from '@ultimat3/core';
-import { withSpan } from '@ultimat3/core';
+import type { Ctx, Span } from '@ultimat3/core';
+import { isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
+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 {
@@ -38,11 +42,17 @@ import { answerAttributes, RESPOND, respondToolFor, structuredOutputOf } from '.
 import type { ModelId } from './models';
 import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
-import type { AiContentBlock, AiMessage, GenerateRequest, GenerateResult } from './provider';
+import type {
+  AiMessage,
+  GenerateRequest,
+  GenerateResult,
+  StopReason,
+  TokenUsage,
+} from './provider';
 import { assertNoSecrets } from './redaction';
 import { aiGateway, aiRedactor } from './runtime';
-import type { LlmTool, LlmToolResult, ProjectableAction } from './tools';
-import { runLlmToolCall, toLlmTools } from './tools';
+import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
+import { asProjectableAction, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
 /**
  * Turn ceiling when the declaration omits one. Low on purpose: a loop that needs more than this
@@ -91,7 +101,7 @@ export interface AgentDef<
    * exactly the same tools. Listing one that is not exposed is refused at declaration rather than
    * dropped, because a tool that reads as offered and silently is not is the worst of both.
    */
-  readonly tools: readonly ProjectableAction[];
+  readonly tools: readonly AgentTool[];
   /** Hard ceiling on model turns. Reaching it is `X_AGENT_MAX_TURNS`, never a partial answer. */
   readonly maxTurns?: number;
   readonly maxToolResultChars?: number;
@@ -100,6 +110,36 @@ export interface AgentDef<
   readonly mcp?: ActionMcp;
   /** Enforced completion ceiling PER TURN. The model never sees it. */
   readonly maxTokens?: number;
+  /**
+   * Called once per completed model turn, before the answer or the tool calls are acted on. The
+   * one thing a multi-turn run could not do until 2026-08: a 90-second loop emitted nothing until
+   * it returned, so a progress indicator, a per-turn spend line and a transcript log all had to be
+   * hand-rolled outside the framework — which is exactly the loop `agent()` exists to replace.
+   *
+   * Observation only: it cannot steer the loop, cannot see the transcript and cannot reach the
+   * actor. A throw from it FAILS the run rather than being swallowed — it is the app's code on the
+   * run's own path, and an observer that silently stopped working would be indistinguishable from
+   * one that is fine. The same facts land on the span as an `agent.turn` event, so a run that
+   * declares no hook is still readable in a trace.
+   *
+   * NOT `.stream()`. Tokens on a screen is a different contract, and `llm()`'s streamed half is
+   * one turn deep by construction; this is per TURN.
+   */
+  onTurn?(event: AgentTurn): void | Promise<void>;
+}
+
+/** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */
+export interface AgentTurn {
+  /** 1-based, so `turn === maxTurns` is the last one this run will take. */
+  readonly turn: number;
+  readonly maxTurns: number;
+  readonly model: ModelId;
+  /** Tools this turn asked for, in the order the model emitted them. `respond` is not one. */
+  readonly toolCalls: readonly string[];
+  readonly stopReason: StopReason;
+  readonly usage: TokenUsage;
+  /** This turn's cost alone, integer minor units — never the run's running total. */
+  readonly cost: Money;
 }
 
 export function agent<
@@ -109,21 +149,69 @@ export function agent<
 >(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
   const respond = respondToolFor(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.
-  const offered = toLlmTools(def.tools);
-  if (offered.length !== def.tools.length) {
+  // 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
+  // `action()` beside this one in the same module has none until `registerActions` runs at boot.
+  const unexposed = def.tools.filter((tool) => !isMcpExposed(tool.mcp));
+  if (unexposed.length > 0) {
     throw new AgentToolUnexposedError({
       agent: def.prompt.ref,
-      tools: def.tools.filter((a) => !offered.some((o) => o.name === a.name)).map((a) => a.name),
+      tools: unexposed.map(toolLabel),
     });
   }
-  return action<TInput, TOutput>({
+  // Projected on FIRST RUN, memoised, for the reason above: `agent()` is evaluated at module
+  // scope and a tool's name is stamped by `registerAction` at boot, so naming it here would make
+  // the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
+  let adapted: Adapted | undefined;
+  const adapt = (): Adapted => {
+    if (adapted === undefined) adapted = project(def.tools);
+    return adapted;
+  };
+  const built = action<TInput, TOutput>({
     input: def.input,
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
-    handle: (args) => run(def, respond, offered, args),
+    handle: (args) => run(def, respond, adapt(), args),
   });
+  // A thunk, resolved when the manifest asks: every name in the row is stamped at boot, and this
+  // line runs at module scope.
+  registerAgentFact(built, () => factsOf(def));
+  return built;
+}
+
+function factsOf<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>): Omit<AgentFact, 'name'> {
+  const budget = def.budget;
+  return {
+    prompt: def.prompt.ref,
+    promptId: def.prompt.id,
+    promptHash: def.prompt.hash,
+    model: def.model ?? def.prompt.model ?? DEFAULT_MODEL,
+    maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
+    maxToolResultChars: def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
+    tools: [...def.tools.map(toolLabel)].sort(),
+    budget: {
+      tokensIn: budget?.tokensIn ?? null,
+      tokensPerRun: budget?.tokensPerRun ?? null,
+      costPerCall: budget?.costPerCall ?? null,
+    },
+    mcp: isMcpExposed(def.mcp),
+  };
+}
+
+/** The tools as `runLlmToolCall` consumes them, and as the request offers them. One projection. */
+interface Adapted {
+  readonly tools: readonly ProjectableAction[];
+  readonly offered: readonly LlmTool[];
+}
+
+function project(tools: readonly AgentTool[]): Adapted {
+  const projected = tools.map(asProjectableAction);
+  return { tools: projected, offered: toLlmTools(projected) };
 }
 
 async function run<
@@ -133,7 +221,7 @@ async function run<
 >(
   def: AgentDef<TInput, TOutput, V>,
   respond: LlmTool,
-  offered: readonly LlmTool[],
+  adapted: Adapted,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
@@ -153,7 +241,7 @@ async function run<
       'agent.model': model,
       'agent.prompt': name,
       'agent.prompt.hash': prompt.hash,
-      'agent.tools': offered.length,
+      'agent.tools': adapted.offered.length,
       'agent.max_turns': maxTurns,
       'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
     });
@@ -167,7 +255,10 @@ async function run<
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      tools: [...offered, respond],
+      tools: [...adapted.offered, respond],
+      // 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,
     };
 
     return withBudget(ledger, async () => {
@@ -180,20 +271,57 @@ async function run<
       let issues: string | undefined;
 
       for (let turn = 1; turn <= maxTurns; turn += 1) {
+        // The caller is gone, so unwind instead of finishing. Every turn re-sends the WHOLE
+        // transcript, so a loop that keeps going after a disconnect spends the rest of the run's
+        // budget, runs every remaining tool's side effects, and discards the answer.
+        throwIfAborted(args.ctx);
         const result = await gateway.generate({ ...base, messages });
+        const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
+        // The same turn's `respond` calls, kept rather than forgotten: they are never RUN, but
+        // `assistantTurn` replays them, and every replayed `tool_use` has to be answered.
+        const answers = result.toolCalls.filter((call) => call.name === RESPOND);
         span.setAttributes({
           'agent.turns': turn,
           'agent.tool_calls': calls,
           ...answerAttributes(result),
         });
+        await observeTurn(def, span, {
+          turn,
+          maxTurns,
+          model: result.model,
+          toolCalls: requested.map((call) => call.name),
+          stopReason: result.stopReason,
+          usage: result.usage,
+          cost: result.cost,
+        });
         assertAnswerable(result, name);
 
-        const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
         if (requested.length > 0) {
-          const results: LlmToolResult[] = [];
-          for (const call of requested) results.push(await runLlmToolCall(def.tools, call, actor));
+          // 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
+          // in the types or the docs ever said so.
+          //
+          // Order is by INDEX, not by completion: `Promise.all` resolves positionally and each
+          // result carries the `tool_use` id `runLlmToolCall` was handed, so a fast tool answering
+          // first cannot be paired with a slow tool's call.
+          throwIfAborted(args.ctx);
+          const results: readonly LlmToolResult[] = await Promise.all(
+            requested.map((call) => runLlmToolCall(adapted.tools, call, actor)),
+          );
           calls += requested.length;
-          messages = [...messages, assistantTurn(result), toolResults(results, chars)];
+          messages = [
+            ...messages,
+            assistantTurn(result),
+            // Parallel tool use — one turn asking for a tool AND answering — is normal, and the
+            // answer is speculative: it was written before the result it asked for existed. So
+            // the loop continues, and the answer is REJECTED on the wire rather than dropped,
+            // because a replayed `respond` block with no `tool_result` is a 400 and the whole run
+            // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
+            toolResultTurn(results, chars, answers),
+          ];
           continue;
         }
 
@@ -205,7 +333,7 @@ async function run<
         if (result.stopReason === 'max_tokens') {
           throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
         }
-        messages = [...messages, assistantTurn(result), { role: 'user', content: repair(issues) }];
+        messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];
       }
 
       // Two different exhaustions, so two different causes: a loop that kept calling tools and
@@ -218,6 +346,28 @@ async function run<
   });
 }
 
+/**
+ * One turn, reported twice: onto the span every run already opens, and to the declaration's own
+ * hook. The span event is free — nothing to install, and a trace is where a stalled run is
+ * actually diagnosed — and the hook is what a progress indicator or a per-turn spend line reads.
+ *
+ * Awaited, and not guarded: a throw from `onTurn` fails the run. It is the app's code on the run's
+ * path, and an observer that quietly stopped working reads exactly like one that is fine.
+ */
+async function observeTurn<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>, span: Span, event: AgentTurn): Promise<void> {
+  span.addEvent('agent.turn', {
+    'agent.turn': event.turn,
+    'agent.turn.tool_calls': event.toolCalls.length,
+    'llm.stop': event.stopReason,
+    'llm.cost.minor': event.cost.minor,
+  });
+  await def.onTurn?.(event);
+}
+
 /** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
 function assertAnswerable(result: GenerateResult, name: string): void {
   if (result.stopReason !== 'refusal') return;
@@ -230,47 +380,6 @@ function assertAnswerable(result: GenerateResult, name: string): void {
   });
 }
 
-/**
- * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
- * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
- * because it has no `tool_result` to follow them with, and the API demands one.
- */
-function assistantTurn(result: GenerateResult): AiMessage {
-  const blocks: AiContentBlock[] = [];
-  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
-  for (const call of result.toolCalls) {
-    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
-  }
-  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
-  return blocks.length === 0
-    ? { role: 'assistant', content: '(no answer)' }
-    : { role: 'assistant', content: blocks };
-}
-
-function toolResults(results: readonly LlmToolResult[], chars: number): AiMessage {
-  return {
-    role: 'user',
-    content: results.map((result) => ({
-      type: 'tool_result' as const,
-      tool_use_id: result.toolUseId,
-      content: truncate(result.content, chars),
-      // A denial or a failure is an outcome the model should read and react to, flagged so it
-      // does not read as data.
-      ...(result.isError === true ? { is_error: true } : {}),
-    })),
-  };
-}
-
-/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
-function truncate(text: string, chars: number): string {
-  if (text.length <= chars) return text;
-  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
-}
-
-function repair(issues: string): string {
-  return `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
-}
-
 function limitsOf<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,

package/src/errors.ts

@@ -18,6 +18,7 @@ export const AI_ERROR_CODES = [
   'X_LLM_STREAM_INVALID',
   'X_AGENT_MAX_TURNS',
   'X_AGENT_TOOL_UNEXPOSED',
+  'X_HIVE_EMPTY',
   'X_EVAL_THRESHOLD',
   'X_EVAL_BASELINE_MISSING',
   'X_EVAL_BASELINE_INVALID',
@@ -45,6 +46,7 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_LLM_STREAM_INVALID: 'a streamed answer failed its output schema, and a stream cannot repair',
   X_AGENT_MAX_TURNS: 'an agent hit its turn ceiling without answering',
   X_AGENT_TOOL_UNEXPOSED: 'an agent lists a tool that is not an MCP-exposed action',
+  X_HIVE_EMPTY: 'a hive split produced no members, so the run did nothing',
   X_EVAL_THRESHOLD: 'an eval scored below its tolerance',
   X_EVAL_BASELINE_MISSING: 'an eval has no recorded baseline to gate against',
   X_EVAL_BASELINE_INVALID: 'a recorded baseline cannot be read',

package/src/gateway.ts

@@ -4,6 +4,7 @@
 // budgeted, and cost-accounted in integer minor units. Everything an app does with a model
 // goes through here, so budgets and accounting cannot be bypassed by a stray fetch.
 
+import { renderThrowable } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { BudgetLimits, BudgetStore } from './budget';
 import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
@@ -183,7 +184,11 @@ class GatewayImpl implements Gateway {
         try {
           return { ...(await call(provider)), provider: provider.name };
         } catch (error) {
-          failures.push(`${provider.name}#${attempt}: ${messageOf(error)}`);
+          // `renderThrowable`, never `error.message` or `String(error)`: this line becomes the
+          // `cause` of `X_AI_PROVIDER_UNAVAILABLE`, and a renderer that throws replaces the coded
+          // refusal with a `TypeError` nothing downstream can catch by code. It bounds the text
+          // too — a provider's 1MB body is not a cause.
+          failures.push(`${provider.name}#${attempt}: ${renderThrowable(error)}`);
           if (!isRetryable(error) || attempt === this.retry.attempts) break;
           await this.sleep(backoffMs(this.retry, attempt));
         }
@@ -205,14 +210,17 @@ export function backoffMs(policy: RetryPolicy, attempt: number): number {
  */
 export function isRetryable(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
-  const e = error as { status?: unknown; code?: unknown };
-  if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
-  return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
-}
-
-function messageOf(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  return String(error);
+  // A `Provider` is the APP's object, so the value it rejected with is one the framework did not
+  // build: `e.status` is a getter call and, on a `Proxy`, a trap. A value that fights being read
+  // cannot be SHOWN to be retryable, and this runs inside the catch block that has nothing left
+  // to answer with — so it fails closed rather than raising.
+  try {
+    const e = error as { status?: unknown; code?: unknown };
+    if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
+    return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/hive-errors.ts

@@ -0,0 +1,30 @@
+// The X_HIVE_* codes, apart from ./errors only because one file has one job and that catalogue is
+// already at its ceiling — the same split `eval-errors.ts` made. The codes, their titles and the
+// single `registerErrorCodes` call stay in ./errors: one owner, one registration, one place a
+// duplicate can surface.
+
+import { UltimateError } from '@ultimat3/core';
+import type { AiErrorCode } from './errors';
+
+const docsFor = (code: AiErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * `split` handed back an empty list, so the hive fanned out to nobody and would have reported a
+ * successful run of zero members.
+ *
+ * Refused rather than returned, because the two readings of "0 ok, 0 failed" are "there was
+ * genuinely nothing to do" and "the query behind `split` returned no rows and nobody noticed",
+ * and only the caller can tell them apart. A hive whose empty case is legitimate says so by not
+ * being called: guard the `split` source at the call site, where the emptiness is visible.
+ */
+export class HiveEmptyError extends UltimateError {
+  constructor(input: { member: string }) {
+    super({
+      code: 'X_HIVE_EMPTY',
+      cause: `the hive over "${input.member}" split into 0 members, so no member ran`,
+      fix: `return at least one member input from the hive's split() over "${input.member}", or skip the hive call when the source is empty — a hive reporting 0 ok and 0 failed cannot be told apart from one whose query returned no rows`,
+      docs: docsFor('X_HIVE_EMPTY'),
+      meta: { member: input.member },
+    });
+  }
+}

package/src/hive-pool.ts

@@ -0,0 +1,90 @@
+// The bounded, order-preserving, cancellation-linked worker pool a hive fans out through.
+//
+// Apart from `hive.ts` because it is a different job with a different failure mode: that file owns
+// the declaration and the budget scope, this one owns "how many at once, in what order, and what
+// happens to the siblings when one throws". Nothing here knows what a model is.
+
+import type { Ctx } from '@ultimat3/core';
+import { isThrownError, isUltimateError, stringField, withChildContext } from '@ultimat3/core';
+import type { HiveMember, HiveMemberError } from './hive-result';
+import { SKIPPED_ABORTED, SKIPPED_NO_INPUT } from './hive-result';
+
+export interface PoolInput<I, O> {
+  readonly inputs: readonly I[];
+  readonly width: number;
+  readonly ctx: Ctx;
+  readonly onMemberError: HiveMemberError;
+  /** One member run. The caller supplies it already bound, so this file never sees an action. */
+  member(payload: I): Promise<O>;
+}
+
+/**
+ * A bounded pool of `width` workers over one shared cursor. Results land BY INDEX, so the answer is
+ * in split order however the members interleave — `Promise.all` over a mapped array would give the
+ * same ordering but no ceiling, and a settle-ordered push would give neither.
+ *
+ * The controller is linked to `ctx.signal` in both directions that matter: the caller going away
+ * aborts every member, and `onMemberError: 'abort'` aborts the siblings without touching the
+ * caller's own signal. Each member runs under `withChildContext({ signal })`, which carries the
+ * actor forward untouched — the hive never names an identity.
+ */
+export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly HiveMember<O>[]> {
+  const { inputs, width, ctx } = input;
+  const members = new Array<HiveMember<O>>(inputs.length);
+  const controller = new AbortController();
+  const relay = (): void => controller.abort();
+  if (ctx.signal.aborted) controller.abort();
+  ctx.signal.addEventListener('abort', relay, { once: true });
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= inputs.length) return;
+      const payload = inputs[index];
+      // Every index is claimed by exactly one worker and assigned exactly once, so the array has
+      // no holes for a caller to trip over — `skipped` is a recorded outcome, never an absence.
+      // Two reasons, because they are two facts: the run stopped, or the split had nothing here.
+      if (controller.signal.aborted || payload === undefined) {
+        const reason = controller.signal.aborted ? SKIPPED_ABORTED : SKIPPED_NO_INPUT;
+        members[index] = { status: 'skipped', index, reason };
+        continue;
+      }
+      try {
+        const value = await withChildContext({ signal: controller.signal }, () =>
+          input.member(payload),
+        );
+        members[index] = { status: 'ok', index, value };
+      } catch (error) {
+        members[index] = { status: 'failed', index, ...failureOf(error) };
+        if (input.onMemberError === 'abort') controller.abort();
+      }
+    }
+  };
+
+  try {
+    await Promise.all(Array.from({ length: width }, worker));
+  } finally {
+    ctx.signal.removeEventListener('abort', relay);
+  }
+  return members;
+}
+
+/**
+ * What a member threw, as two data fields — never as an error's `cause:`, which is why the thrown
+ * value is read structurally and never interpolated. A foreign throw gets `'unknown'` rather than
+ * an invented `X_` code: a code nothing declares is a code no `x errors explain` can answer.
+ */
+function failureOf(error: unknown): { readonly code: string; readonly reason: string } {
+  if (isUltimateError(error)) return { code: error.code, reason: error.cause };
+  // `isThrownError` and `stringField`, never `error instanceof Error` and `.message`: a member
+  // is an app's action, so the value is one the framework did not build — `instanceof` runs a
+  // `Proxy`'s `getPrototypeOf` trap and `.message` is a getter call. A throw HERE would take the
+  // whole hive down with it, which is the one outcome the three arms exist to prevent.
+  const message = stringField(error, 'message');
+  if (isThrownError(error) && message !== undefined && message !== '') {
+    return { code: 'unknown', reason: message };
+  }
+  return { code: 'unknown', reason: 'the member threw a value that is not an Error' };
+}