@pi-in-go/pigpen-pi-typesafe 0.1.0

package/port/oracle/src/auth.ts

@@ -0,0 +1,171 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_BACKEND, TYPESAFE_KEY_ENV, resolveBackend, usesTypesafeKey } from "./backends.js";
+import type { BackendSpec } from "./backends.js";
+import { credentialsPath, keySituation, keySourceLabel, piTypesafeDir } from "./credentials.js";
+import type { KeySource } from "./credentials.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import type { IntegrationErrorCode } from "./errors.js";
+
+const AUTH_VERSION = 1;
+const CODES: ReadonlySet<string> = new Set<IntegrationErrorCode>([
+  "configuration", "validation", "budget", "aborted", "timeout", "http", "connection", "response",
+]);
+/** Statuses that mean the key itself was refused, not that the service was busy. */
+const REJECTED_STATUSES = new Set([401, 403]);
+
+/** The last request that degraded TypeSafe, with no upstream body, header, key, or submitted state. */
+export interface AuthFailure {
+  readonly code: IntegrationErrorCode;
+  readonly status?: number;
+  readonly message: string;
+  readonly at: string;
+}
+
+/**
+ * The whole answer to "is Jev actually available right now": which key is in effect, whether it has been accepted, and
+ * the last failure that degraded it. Consumers must consult this instead of treating their own consent flag as proof
+ * that judgments will happen — an enabled extension with no key used to look identical to a working one.
+ */
+export interface AuthState {
+  /** The judgment backend this state describes; each backend has its own key. Holds the value the caller passed. */
+  readonly backend: BackendSpec;
+  /** Same kinds as KeySituation: where the key in effect comes from. */
+  readonly kind: "environment" | "stored" | "missing" | "unusable";
+  readonly source?: KeySource;
+  /** Where the key would be read from. */
+  readonly path: string;
+  /** Why a stored key cannot be used, when that is the case. */
+  readonly reason?: string;
+  /** Short human label for the key source: `TYPESAFE_API_KEY`, `OPENROUTER_API_KEY`, `/typesafe login`, `no key`, `unusable key`. */
+  readonly keyName: string;
+  /**
+   * True when the key in effect was accepted by the backend (login verifies a TypeSafe key; a successful request proves
+   * any key). The record is shared across backends: switching backends keeps the last outcome until the next request.
+   */
+  readonly verified: boolean;
+  readonly verifiedAt?: string;
+  /** The last failure, cleared by the next successful request. */
+  readonly lastFailure?: AuthFailure;
+  /** A key is present and the last authentication outcome was not a rejection. False means judgments are skipped. */
+  readonly usable: boolean;
+}
+
+/** The auth-state file: one small, owner-only record that outlives the process that wrote it. */
+export function authStatePath(): string {
+  return join(piTypesafeDir(), "auth-state.json");
+}
+
+function readState(path: string): { verifiedAt?: string; lastFailure?: AuthFailure } {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object") return {};
+    const raw = parsed as { verifiedAt?: unknown; lastFailure?: unknown };
+    const verifiedAt = typeof raw.verifiedAt === "string" && raw.verifiedAt.length <= 40 ? raw.verifiedAt : undefined;
+    const failure = raw.lastFailure && typeof raw.lastFailure === "object" ? raw.lastFailure as Record<string, unknown> : undefined;
+    const code = typeof failure?.code === "string" && CODES.has(failure.code) ? failure.code as IntegrationErrorCode : undefined;
+    const message = typeof failure?.message === "string" ? failure.message.slice(0, 300) : undefined;
+    const at = typeof failure?.at === "string" && failure.at.length <= 40 ? failure.at : undefined;
+    const status = typeof failure?.status === "number" && Number.isSafeInteger(failure.status) ? failure.status : undefined;
+    const lastFailure = code && message && at
+      ? { code, message, at, ...(status === undefined ? {} : { status }) }
+      : undefined;
+    return { ...(verifiedAt === undefined ? {} : { verifiedAt }), ...(lastFailure === undefined ? {} : { lastFailure }) };
+  } catch {
+    return {};
+  }
+}
+
+/** Owner-only, atomic, and best-effort: an unwritable auth record never changes how a request behaves. */
+function writeState(path: string, state: { verifiedAt?: string; lastFailure?: AuthFailure }): void {
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(piTypesafeDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(temporary, `${JSON.stringify({ version: AUTH_VERSION, ...state }, null, 2)}\n`, { mode: 0o600, flag: "w" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+  } catch {
+    try { rmSync(temporary, { force: true }); } catch { /* best-effort cleanup only */ }
+  }
+}
+
+/**
+ * What the key situation, the last outcome, and the clock add up to for a valid backend; it never throws for one. An
+ * invalid backend throws the same `configuration` error as resolveBackend(), so validate a user-supplied endpoint
+ * with resolveBackend() first.
+ */
+export function authState(options: { path?: string; backend?: BackendSpec } = {}): AuthState {
+  const path = options.path ?? authStatePath();
+  const backend = options.backend ?? DEFAULT_BACKEND;
+  const situation = keySituation(backend);
+  const stored = readState(path);
+  const source: KeySource | undefined = situation.kind === "environment" ? "environment" : situation.kind === "stored" ? "stored" : undefined;
+  const rejected = stored.lastFailure?.code === "http" && stored.lastFailure.status !== undefined && REJECTED_STATUSES.has(stored.lastFailure.status);
+  const usable = source !== undefined && !rejected;
+  return {
+    backend,
+    kind: situation.kind,
+    ...(source === undefined ? {} : { source }),
+    path: situation.kind === "unusable" ? situation.path : credentialsPath(),
+    ...(situation.kind === "unusable" ? { reason: situation.reason } : {}),
+    keyName: keySourceLabel(situation),
+    verified: stored.verifiedAt !== undefined && !rejected,
+    ...(stored.verifiedAt === undefined ? {} : { verifiedAt: stored.verifiedAt }),
+    ...(stored.lastFailure === undefined ? {} : { lastFailure: stored.lastFailure }),
+    usable,
+  };
+}
+
+/** Record that the key was accepted: login verification, or any successful request. Clears the last failure. */
+export function recordAuthVerified(at: Date = new Date()): void {
+  writeState(authStatePath(), { verifiedAt: at.toISOString() });
+}
+
+/** Record the failure that degraded TypeSafe. The verification timestamp is kept so a recovered key stays known. */
+export function recordAuthFailure(error: TypeSafeIntegrationError, at: Date = new Date()): void {
+  const current = readState(authStatePath());
+  const failure: AuthFailure = {
+    code: error.code,
+    message: error.message,
+    at: at.toISOString(),
+    ...(error.status === undefined ? {} : { status: error.status }),
+  };
+  writeState(authStatePath(), { ...(current.verifiedAt === undefined ? {} : { verifiedAt: current.verifiedAt }), lastFailure: failure });
+}
+
+/** Forget verification and degradation: used when the key itself changes (login or logout). */
+export function clearAuthState(): void {
+  try { rmSync(authStatePath(), { force: true }); } catch { /* nothing to clear */ }
+}
+
+export interface AuthReport {
+  /** `error` when judgments are skipped or were rejected, `warning` when the key is unverified, otherwise `ok`. */
+  readonly level: "ok" | "warning" | "error";
+  /** One line naming the key source and, when degraded, the reason. Safe to display. */
+  readonly text: string;
+}
+
+/**
+ * One line plus a level, so a status command, a headless log, or a consumer's own status line can call out a degraded
+ * state instead of reporting "enabled".
+ */
+export function describeAuth(state: AuthState = authState()): AuthReport {
+  const config = resolveBackend(state.backend);
+  const label = `${config.label} key`;
+  const since = state.lastFailure ? ` Last failure: ${state.lastFailure.message}${state.lastFailure.at ? ` (${state.lastFailure.at})` : ""}` : "";
+  if (state.kind === "missing") {
+    const how = usesTypesafeKey(config) ? `a key is configured (/typesafe login or ${TYPESAFE_KEY_ENV})` : `${config.keyEnv} is set in the environment`;
+    return { level: "error", text: `${label}: missing — every Jev judgment is skipped until ${how}.${since}` };
+  }
+  if (state.kind === "unusable") {
+    return { level: "error", text: `${label}: unusable (${state.reason ?? "unknown reason"}) — judgments are skipped until the key is fixed.${since}` };
+  }
+  const rejected = state.lastFailure?.code === "http" && state.lastFailure.status !== undefined && REJECTED_STATUSES.has(state.lastFailure.status);
+  if (rejected) {
+    return { level: "error", text: `${label}: ${state.keyName} was rejected.${since}` };
+  }
+  if (!state.verified) {
+    return { level: "warning", text: `${label}: ${state.keyName} (not verified yet — the first request proves it).${since}` };
+  }
+  return { level: "ok", text: `${label}: ${state.keyName} (verified${state.verifiedAt ? ` ${state.verifiedAt}` : ""}).${since}` };
+}

package/port/oracle/src/backends.ts

@@ -0,0 +1,196 @@
+import { TypeSafeIntegrationError } from "./errors.js";
+
+export type TypeSafeBackend = "typesafe" | "openrouter" | "commandcode";
+
+export interface BackendConfig {
+  /** Human name for status lines: "TypeSafe", "OpenRouter", "Command Code". */
+  label: string;
+  host: string;
+  /** The environment variable that carries this backend's key. Absent means the TypeSafe key resolution applies. */
+  keyEnv?: string;
+  /** Request path, when the backend does not serve the SDK's own `/v1/systemone`. */
+  path?: string;
+  /** Request path for the model list, when the backend does not serve the SDK's own `/v1/models`. */
+  modelsPath?: string;
+  /** Field the model list arrives in, when the backend does not use the SDK's own `models`. */
+  modelsField?: string;
+  /** Entry field carrying the id callers pass as `model:`, when the SDK's own `name` is only a label. */
+  modelsIdField?: string;
+  /** Whether the model list checks the key. A public list accepts any key, so it proves nothing. Absent means it does. */
+  modelsVerifyKey?: boolean;
+}
+
+/** A caller-supplied endpoint that serves the Jev decisions protocol. Passed per call; never added to the registry. */
+export interface BackendEndpoint extends BackendConfig {
+  /** Required. The environment variable with this endpoint's key. Must not be TYPESAFE_API_KEY. */
+  readonly keyEnv: string;
+  /** Model sent when the caller names none. Without it, `model` must be passed to createTypeSafe. */
+  readonly defaultModel?: string;
+}
+
+/** A registry name or a caller-supplied endpoint. */
+export type BackendSpec = TypeSafeBackend | BackendEndpoint;
+
+/** A backend resolved and validated: what the client will actually use. */
+export interface ResolvedBackend extends BackendConfig {
+  /** Registry name, absent for a caller-supplied endpoint. */
+  readonly name?: TypeSafeBackend;
+  /** Origin only: scheme, host, and port. */
+  readonly host: string;
+  readonly keyEnv: string;
+  /** The model id sent when the caller names none, already in the backend's form. Absent when the endpoint names none. */
+  readonly defaultModel?: string;
+  /** Always explicit after resolution. */
+  readonly modelsVerifyKey: boolean;
+}
+
+/** The backend every key and auth function assumes when none is named. */
+export const DEFAULT_BACKEND: TypeSafeBackend = "typesafe";
+
+/** The environment variable and login store that the default backend reads. */
+export const TYPESAFE_KEY_ENV = "TYPESAFE_API_KEY";
+
+/** Registry of known judgment backends. Callers pass a `BackendEndpoint` for a host this registry does not name. */
+export const DECISIONS_BACKENDS: Record<TypeSafeBackend, BackendConfig> = {
+  typesafe: { label: "TypeSafe", host: "https://api.typesafe.ai", keyEnv: TYPESAFE_KEY_ENV },
+  openrouter: {
+    label: "OpenRouter",
+    host: "https://openrouter.ai",
+    keyEnv: "OPENROUTER_API_KEY",
+    path: "/api/alpha/decisions",
+    modelsPath: "/api/v1/models",
+    modelsField: "data",
+    modelsIdField: "id",
+    modelsVerifyKey: false,
+  },
+  commandcode: {
+    label: "Command Code",
+    host: "https://api.commandcode.ai",
+    keyEnv: "COMMANDCODE_API_KEY",
+    path: "/provider/v1/systemone",
+    modelsPath: "/provider/v1/models",
+    modelsField: "data",
+    modelsIdField: "id",
+    modelsVerifyKey: false,
+  },
+};
+
+/** The registry entry for a backend name; a `configuration` error for a name the registry does not know. */
+export function backendConfig(name: TypeSafeBackend): BackendConfig {
+  const backend = DECISIONS_BACKENDS[name];
+  if (!backend) throw new TypeSafeIntegrationError("configuration", `Unknown judgment backend "${name}". Valid backends: ${Object.keys(DECISIONS_BACKENDS).join(", ")}.`);
+  return backend;
+}
+
+/** Each backend's default model id as the caller writes it, before mapping: OpenRouter pins a version, TypeSafe follows latest. */
+const DEFAULT_MODEL: Record<TypeSafeBackend, string> = {
+  typesafe: "jev-latest",
+  openrouter: "typesafe/jev-1.13",
+  commandcode: "typesafe/jev",
+};
+
+/**
+ * The model id to send for a caller's `model` on this backend. OpenRouter routes a bare Jev id under the `typesafe`
+ * author: `jev-latest` becomes its alias form `~typesafe/jev-latest`, and a bare `jev-<major>.<minor>` — with or
+ * without TypeSafe direct's optional `.<patch>` segment — becomes `typesafe/jev-<major>.<minor>`. An id that already
+ * carries an author (`vendor/model`), a bare id this rule does not know, and every model on a backend without a
+ * mapping go through unchanged. Every mapped id contains `/`, so mapping an already-mapped id changes nothing.
+ */
+export function backendModelId(backend: TypeSafeBackend, model: string): string {
+  if (model.includes("/")) return model;
+  if (backend !== "openrouter") return model;
+  if (model === "jev-latest") return "~typesafe/jev-latest";
+  const version = /^jev-(\d+)\.(\d+)(?:\.\d+)?$/.exec(model);
+  return version === null ? model : `typesafe/jev-${version[1]}.${version[2]}`;
+}
+
+/** The model a client sends when the caller names none: the backend's own default, in the form that backend accepts. */
+export function defaultModelId(backend: TypeSafeBackend): string {
+  return backendModelId(backend, DEFAULT_MODEL[backend]);
+}
+
+/**
+ * Whether a backend's key comes from the TypeSafe resolution (`TYPESAFE_API_KEY`, then the login store) or only from
+ * its own environment variable. Only the TypeSafe backend has a login store; every other backend is environment-only.
+ */
+export function usesTypesafeKey(backend: BackendConfig): boolean {
+  return (backend.keyEnv ?? TYPESAFE_KEY_ENV) === TYPESAFE_KEY_ENV;
+}
+
+const KEY_ENV_MESSAGE = "Backend keyEnv must name an environment variable: letters, digits, and underscores, not starting with a digit.";
+const HOST_MESSAGE = "Backend host must be an absolute https: URL with no user info, path, query, or fragment (http: is allowed only for localhost, 127.0.0.0/8, and [::1]).";
+
+function refuse(message: string): never {
+  throw new TypeSafeIntegrationError("configuration", message);
+}
+
+/** `https://gw.example.com?` and `https://gw.example.com#` parse clean, so the raw string itself must carry neither. */
+function hasRawQueryOrFragment(value: string): boolean {
+  return value.includes("?") || value.includes("#");
+}
+
+/**
+ * Resolve a registry name or a caller-supplied endpoint into the validated form the client uses. A name resolves to
+ * its registry entry unchanged; an endpoint is validated field by field and returned as a fresh object whose `host`
+ * is origin-only. Messages never quote a caller value — a host can carry credentials in its user info — except the
+ * label, and only after it is validated. Validation runs on every call; nothing is cached.
+ */
+export function resolveBackend(backend?: BackendSpec): ResolvedBackend {
+  const spec: BackendSpec = backend === undefined ? DEFAULT_BACKEND : backend;
+  if (typeof spec === "string") {
+    const entry = backendConfig(spec);
+    return {
+      ...entry,
+      name: spec,
+      host: entry.host,
+      keyEnv: entry.keyEnv ?? TYPESAFE_KEY_ENV,
+      defaultModel: defaultModelId(spec),
+      modelsVerifyKey: entry.modelsVerifyKey !== false,
+    };
+  }
+  if (spec === null || typeof spec !== "object") {
+    refuse("backend must be a registry name or a backend object.");
+  }
+  const label = typeof spec.label === "string" ? spec.label.trim() : "";
+  if (!label || label.length > 60) refuse("Backend label must be a nonempty string of at most 60 characters.");
+  let host: URL;
+  if (typeof spec.host !== "string" || hasRawQueryOrFragment(spec.host)) refuse(HOST_MESSAGE);
+  try {
+    host = new URL(spec.host);
+  } catch {
+    refuse(HOST_MESSAGE);
+  }
+  const loopback = host.hostname === "localhost" || host.hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(host.hostname);
+  if (host.protocol !== "https:" && !(host.protocol === "http:" && loopback)) refuse(HOST_MESSAGE);
+  if (host.username !== "" || host.password !== "" || host.pathname !== "/" || host.search !== "" || host.hash !== "") refuse(HOST_MESSAGE);
+  for (const [field, message] of [["path", 'Backend path must be a string that starts with "/".'], ["modelsPath", 'Backend modelsPath must be a string that starts with "/".']] as const) {
+    const value = spec[field];
+    if (value !== undefined && (typeof value !== "string" || !value.startsWith("/") || hasRawQueryOrFragment(value))) refuse(message);
+  }
+  if (spec.modelsField !== undefined && (typeof spec.modelsField !== "string" || !spec.modelsField)) refuse("Backend modelsField must be a nonempty string.");
+  if (spec.modelsIdField !== undefined && (typeof spec.modelsIdField !== "string" || !spec.modelsIdField)) refuse("Backend modelsIdField must be a nonempty string.");
+  if (spec.modelsVerifyKey !== undefined && typeof spec.modelsVerifyKey !== "boolean") refuse("Backend modelsVerifyKey must be a boolean.");
+  if (typeof spec.keyEnv !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(spec.keyEnv)) refuse(KEY_ENV_MESSAGE);
+  if (spec.keyEnv.toUpperCase() === TYPESAFE_KEY_ENV) {
+    refuse("Backend keyEnv must not be TYPESAFE_API_KEY: the TypeSafe key is only sent to the typesafe backend. Give this endpoint its own variable.");
+  }
+  if (spec.defaultModel !== undefined && (typeof spec.defaultModel !== "string" || !spec.defaultModel.trim() || spec.defaultModel.length > 100)) {
+    refuse("Backend defaultModel must be a nonempty string of at most 100 characters.");
+  }
+  return {
+    label,
+    host: host.origin,
+    keyEnv: spec.keyEnv,
+    modelsVerifyKey: spec.modelsVerifyKey === true,
+    ...(spec.path === undefined ? {} : { path: spec.path }),
+    ...(spec.modelsPath === undefined ? {} : { modelsPath: spec.modelsPath }),
+    ...(spec.modelsField === undefined ? {} : { modelsField: spec.modelsField }),
+    ...(spec.modelsIdField === undefined ? {} : { modelsIdField: spec.modelsIdField }),
+    ...(spec.defaultModel === undefined ? {} : { defaultModel: spec.defaultModel }),
+  };
+}
+
+/** The destination host only — scheme, host, and port, e.g. `api.commandcode.ai` — for consent text. */
+export function backendHost(backend?: BackendSpec): string {
+  return new URL(resolveBackend(backend).host).host;
+}

package/port/oracle/src/batch.ts

@@ -0,0 +1,170 @@
+import type { Questions, SystemOneRequest, Usage } from "@typesafe-ai/sdk";
+import type { Evaluation, TypeSafe } from "./client.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import { DEFAULT_MAX_QUESTIONS, prepareEvaluationRequest } from "./schema.js";
+
+/** Default number of requests in flight. TypeSafe answers in isolation, so a small pool is enough. */
+export const DEFAULT_CONCURRENCY = 4;
+
+/** One item's outcome. `skipped` marks work that was never started because of an abort or a stop rule. */
+export type Settled<T> =
+  | { readonly ok: true; readonly index: number; readonly value: T }
+  | { readonly ok: false; readonly index: number; readonly error: unknown; readonly skipped: boolean };
+
+export interface FanOutOptions {
+  /** Requests in flight at once. Default: DEFAULT_CONCURRENCY. */
+  concurrency?: number;
+  /** Stops starting new work once aborted; in-flight work still finishes. */
+  signal?: AbortSignal;
+  /** Stop launching new work once this returns true for a failure, e.g. a `budget` error. */
+  stopOn?: (error: unknown) => boolean;
+}
+
+/**
+ * Run `worker` over `items` with bounded concurrency, preserving input order. Never throws: every item comes back as a
+ * settled result. This is the pool the client's batching methods use, exported so script authors stop hand-rolling one.
+ */
+export async function fanOut<I, O>(items: readonly I[], worker: (item: I, index: number) => Promise<O>, options: FanOutOptions = {}): Promise<Settled<O>[]> {
+  const concurrency = Math.max(1, Math.floor(options.concurrency ?? DEFAULT_CONCURRENCY));
+  const results = new Array<Settled<O> | undefined>(items.length);
+  let next = 0;
+  let stopped = false;
+  const run = async (): Promise<void> => {
+    while (!stopped) {
+      const index = next++;
+      if (index >= items.length) return;
+      if (options.signal?.aborted) {
+        stopped = true;
+        return;
+      }
+      try {
+        results[index] = { ok: true, index, value: await worker(items[index] as I, index) };
+      } catch (error) {
+        results[index] = { ok: false, index, error, skipped: false };
+        if (options.stopOn?.(error)) stopped = true;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, run));
+  const reason = options.signal?.aborted ? "TypeSafe batch cancelled before this request was submitted." : "TypeSafe batch stopped after a failed request; this request was not submitted.";
+  for (let index = 0; index < items.length; index++) {
+    if (!results[index]) results[index] = { ok: false, index, error: new TypeSafeIntegrationError("aborted", reason), skipped: true };
+  }
+  return results as Settled<O>[];
+}
+
+export interface BatchOptions {
+  /** Requests in flight at once. Default: DEFAULT_CONCURRENCY. */
+  concurrency?: number;
+  signal?: AbortSignal;
+}
+
+/** Per-request outcomes plus the merged view callers usually want. */
+export interface BatchEvaluation<Q extends Questions = Questions> {
+  /** True when every request succeeded. */
+  readonly ok: boolean;
+  /** Per-request outcomes in input order. */
+  readonly results: readonly Settled<Evaluation<Q>>[];
+  /** Failures, including requests that were never submitted. */
+  readonly failures: number;
+  /** Work never started, because of an abort or a `budget` stop. */
+  readonly skipped: number;
+  /** Answers merged in input order; a repeated question id keeps the last answer. Empty when nothing succeeded. */
+  readonly answers: Partial<Evaluation<Q>["answers"]>;
+  /** The model of the first successful request, when there is one. */
+  readonly model?: string;
+  /** Usage summed over the requests that succeeded. */
+  readonly usage: Usage;
+  /** Wall-clock time for the whole batch. */
+  readonly elapsedMs: number;
+}
+
+function summarize<Q extends Questions>(results: readonly Settled<Evaluation<Q>>[], elapsedMs: number): BatchEvaluation<Q> {
+  const answers: Partial<Evaluation<Q>["answers"]> = {};
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let succeeded = 0;
+  let skipped = 0;
+  let model: string | undefined;
+  for (const result of results) {
+    if (!result.ok) {
+      if (result.skipped) skipped++;
+      continue;
+    }
+    succeeded++;
+    Object.assign(answers, result.value.answers);
+    inputTokens += result.value.usage.input_tokens;
+    outputTokens += result.value.usage.output_tokens;
+    model ??= result.value.model;
+  }
+  return {
+    ok: succeeded === results.length,
+    results,
+    failures: results.length - succeeded,
+    skipped,
+    answers,
+    ...(model === undefined ? {} : { model }),
+    usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+    elapsedMs,
+  };
+}
+
+/** A failure that is worth stopping the batch for: no more requests will be accepted, or the caller cancelled. */
+function stopsBatch(error: unknown): boolean {
+  return error instanceof TypeSafeIntegrationError && (error.code === "budget" || error.code === "aborted");
+}
+
+/**
+ * Send several requests with bounded concurrency, in input order, and merge what came back. Each request passes through
+ * the same admission seam as `evaluate`, so an invalid request is one settled failure, not a thrown error. A `budget` or
+ * cancellation failure stops the rest from being submitted. Never throws.
+ */
+export async function evaluateMany<Q extends Questions>(
+  client: TypeSafe,
+  requests: readonly SystemOneRequest<Q>[],
+  options: BatchOptions = {},
+): Promise<BatchEvaluation<Q>> {
+  const start = performance.now();
+  const results = await fanOut(requests, (request) => client.evaluate(prepareEvaluationRequest(request) as SystemOneRequest<Q>, options.signal ? { signal: options.signal } : {}), {
+    ...(options.concurrency === undefined ? {} : { concurrency: options.concurrency }),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    stopOn: stopsBatch,
+  });
+  return summarize(results, Math.round(performance.now() - start));
+}
+
+/**
+ * Split a request that asks more questions than one request may carry into chunks of at most `maxQuestions`. Sharing
+ * one state across several questions is one request; asking more than the per-request limit is the only reason to fan
+ * out, and the state is repeated in each chunk. The order of `questions` is preserved. A pure splitter: admission still
+ * happens once per chunk, in `evaluate` or `evaluateMany`, so what one accepts the others accept.
+ */
+export function chunkEvaluationRequest(
+  request: SystemOneRequest<Questions>,
+  options: { maxQuestions?: number } = {},
+): SystemOneRequest<Questions>[] {
+  const limit = Math.max(1, Math.floor(options.maxQuestions ?? DEFAULT_MAX_QUESTIONS));
+  const questions = request.questions as Record<string, unknown>;
+  const entries = questions && typeof questions === "object" && !Array.isArray(questions) ? Object.entries(questions) : undefined;
+  // Anything that is not a plain question map, or that already fits, is one chunk and is validated later.
+  if (!entries || entries.length <= limit) return [request];
+  const chunks: SystemOneRequest<Questions>[] = [];
+  for (let index = 0; index < entries.length; index += limit) {
+    const questions = Object.fromEntries(entries.slice(index, index + limit));
+    chunks.push({ ...request, questions } as SystemOneRequest<Questions>);
+  }
+  return chunks;
+}
+
+/**
+ * Ask any number of questions about one state: chunk to the per-request limit, fan out, and merge the answers, usage,
+ * and model. Use this when one coherent state carries many independent questions; use `evaluate` for one request.
+ */
+export async function evaluateAll<Q extends Questions>(
+  client: TypeSafe,
+  request: SystemOneRequest<Q>,
+  options: BatchOptions & { maxQuestions?: number } = {},
+): Promise<BatchEvaluation<Q>> {
+  const chunks = chunkEvaluationRequest(request as SystemOneRequest<Questions>, options.maxQuestions === undefined ? {} : { maxQuestions: options.maxQuestions }) as SystemOneRequest<Q>[];
+  return evaluateMany(client, chunks, options);
+}