@volter/twin-cohere 0.1.0

package/src/cohere-twin.ts

@@ -0,0 +1,1290 @@
+// Cohere twin REQUEST HANDLER — the canonical Cohere API surface for the twin. Contract:
+// handleCohereTwinRequest({method, path, body}) -> {status, body}. It is the faithful Cohere API
+// that the real `cohere-ai` client (constructed with `environment: 'http://127.0.0.1:<port>'`) and
+// the real `@ai-sdk/cohere` provider (`createCohere({ baseURL: '…/v2' })`) talk to UNMODIFIED.
+//
+// ── COHERE IS ITS OWN DIALECT, AND THE REFUSALS ARE THE FIDELITY SURFACE ────────────────
+// This is NOT an OpenAI-compatible API and copying an OpenAI-shaped pack's permissiveness is
+// precisely the bug (ADDING_A_TWIN.md §0). What distinguishes Cohere is what it REFUSES and what
+// its envelopes look like:
+//   • the error body is a BARE `{ "message": "…" }` — no `error` wrapper, no `type`, no `code`
+//     (@ai-sdk/cohere's `cohereErrorDataSchema` is literally `z.object({ message: z.string() })`);
+//   • `finish_reason` is UPPER-CASE from Cohere's own set (COMPLETE / TOOL_CALL / MAX_TOKENS /
+//     STOP_SEQUENCE / ERROR / TIMEOUT) — `stop` and `tool_calls` are not Cohere values;
+//   • a v2 chat response has NO `choices` array: one `message`, one `finish_reason`, one `usage`
+//     with `billed_units` AND `tokens` sub-objects;
+//   • v1 and v2 are DIFFERENT PROTOCOLS on one host, not a versioned alias — v1 chat takes a
+//     single `message` STRING and answers a flat `text`; v2 takes `messages[]` and answers a
+//     structured assistant message;
+//   • `POST /v2/embed` REQUIRES `input_type`; `POST /v1/embed` does not, but refuses a v3/v4 embed
+//     model without one;
+//   • v1 embed defaults to `embeddings_floats` (a flat `number[][]`) while v2 always answers
+//     `embeddings_by_type` (keyed by `float`/`int8`/…);
+//   • v2 rerank `documents` must be STRINGS; v1 accepts objects and has `return_documents`;
+//   • `POST /v1/check-api-key` is a POST, not the GET its name suggests;
+//   • the enums are UPPER-CASE (`truncate: NONE|START|END`, `tool_choice: REQUIRED|NONE`,
+//     `safety_mode: CONTEXTUAL|STRICT|OFF`) where most vendors' are lower.
+// Every one of those is asserted by a manifest verify, so an accidental drift toward the
+// OpenAI shape reddens by name.
+//
+// ── THE HONEST DESIGN ──────────────────────────────────────────────────────────────────
+// The twin cannot run the model, so `/v2/chat`, `/v1/chat`, `/v2/embed`, `/v1/embed`,
+// `/v2/rerank`, `/v1/rerank`, `/v1/classify` and `/v1/tokenize` return DETERMINISTIC STUBS
+// (cohere-stub.ts) clearly labeled as such — never real model output. But the ENTIRE PROTOCOL
+// ENVELOPE is vendor-faithful, including the SSE event sequence terminated by `data: [DONE]`.
+//
+// The genuinely stateful + static surface is real, not stubbed:
+//   • GET /v1/models (+ /{name}) — the static real catalog (cohere-models.ts)
+//   • Datasets   — POST/GET/DELETE /v1/datasets (+ /usage, /{id}), stateful
+//   • Connectors — POST/GET/PATCH/DELETE /v1/connectors (+ /{id}/oauth/authorize), stateful
+//   • Embed jobs — POST/GET /v1/embed-jobs (+ /{id}, /{id}/cancel), stateful, cross-referencing
+//                  a real dataset id
+//   • The tokenizer VOCABULARY — `/v1/tokenize` observes (segment → id) pairs into the log, and
+//     `/v1/detokenize` folds that projection. That is what makes detokenize honest rather than a
+//     fabrication: the twin can only detokenize what it has actually seen, and says so otherwise.
+//
+// State lives in the kernel action log (D1): all writes are local actions, reads are the
+// projection. No real Cohere is ever called from this path (D4). Streaming uses an INJECTED sink
+// — no real sockets / setTimeout (D5 verify is offline + deterministic).
+//
+// ID MINTING: deterministic, and the ordinal is scanned from the id-SET INCLUDING TOMBSTONES
+// (`_deleted` rows are retained in the projection and filtered out of reads) so a
+// delete-then-create can never re-issue a live id — the failure mode three packs' §9 reviews each
+// found in a count-mint.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { COHERE_MODELS, findModel, modelServes } from './cohere-models.ts';
+import {
+  base64Embedding,
+  classifyText,
+  COHERE_OUTPUT_DIMENSIONS,
+  cohereId,
+  contentToText,
+  countInputTokens,
+  embedDimensions,
+  estimateTokens,
+  fnv1a,
+  lastUserText,
+  preferredTokenId,
+  pseudoEmbedding,
+  quantizeEmbedding,
+  rerankScore,
+  segmentText,
+  stubAssistantText,
+  stubToolCall,
+  stubToolPlan,
+  stubV1Text,
+  toolNames,
+} from './cohere-stub.ts';
+import { type CohereScenarioEngine, type CohereScenarioRespond, realizeCohereRespond, type ScriptedResult } from './cohere-scenario.ts';
+import {
+  COHERE_EMBEDDING_TYPES,
+  COHERE_INPUT_TYPES,
+  COHERE_TRUNCATE,
+  type CohereApiMeta,
+  type CohereAssistantContentItem,
+  type CohereChatV2Response,
+  type CohereEmbeddingType,
+  type CohereFinishReason,
+  type CohereV1FinishReason,
+  type CohereMessageV2,
+  type CohereToolCallV2,
+  type CohereUsage,
+  type SseSink,
+} from './cohere-types.ts';
+
+const SERVICE = 'cohere';
+
+/** The API version string Cohere stamps into every `meta.api_version`. */
+const API_VERSION = '1';
+
+export type CohereRequest = {
+  /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+  scenarioEngine?: CohereScenarioEngine;
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** Lower-cased request headers (e.g. `authorization`) the HTTP server passes through so the
+   *  handler can model auth (401). In-process trusted calls (capability verifies, the connector)
+   *  omit them and are not auth-gated — the twin cannot validate against real keys, so the
+   *  modeled failure is the CHECKABLE missing/sentinel-invalid case. */
+  headers?: Record<string, string>;
+  /** When set on a streaming POST, chunks are written here (no sockets). */
+  sseSink?: SseSink;
+};
+
+/** The handler response. `headers` (when present) are response headers the HTTP server should
+ *  set — e.g. `Retry-After` on a scripted 429. */
+export type CohereResponseEnvelope = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── vendor-shaped errors ────────────────────────────────────────────────────────────────
+/**
+ * THE error envelope. One key, `message`, and nothing else — the shape
+ * @ai-sdk/cohere@4.0.35 pins with `cohereErrorDataSchema = z.object({ message: z.string() })`,
+ * and the shape cohere-ai@8.1.0 hands to every typed error class (`new Cohere.BadRequestError(
+ * _response.error.body)`) without unwrapping.
+ *
+ * The STATUS codes below are the vendor's; the message TEXT for the twin's own refusals follows
+ * Cohere's `invalid request: …` idiom but is authored here — a twin cannot know the vendor's exact
+ * prose for every input, and inventing a `type`/`code` field to look more official would be
+ * serving surface the vendor does not have.
+ */
+function apiError(status: number, message: string): CohereResponseEnvelope {
+  return { status, body: { message } };
+}
+
+/** `invalid request: …` — Cohere's 400 idiom for a malformed body. */
+function invalidRequest(detail: string): CohereResponseEnvelope {
+  return apiError(400, `invalid request: ${detail}`);
+}
+
+/**
+ * The vendor's 404 for a model the endpoint cannot serve. Cohere answers the same way for a model
+ * that does not exist AND for one that exists but is not available on the endpoint being called —
+ * from the endpoint's point of view the model is simply not found — so the twin does not invent a
+ * separate "incompatible model" status.
+ */
+function modelNotFound(model: string): CohereResponseEnvelope {
+  return apiError(404, `model '${model}' not found, make sure the correct model ID was used and that you have access to the model.`);
+}
+
+function notFound(message: string): CohereResponseEnvelope {
+  return apiError(404, message);
+}
+
+/** The 404 an unrouted path answers. Written as one function so conformance can assert the
+ *  envelope as a literal predicate without importing this. */
+function routeNotFound(method: string, path: string): CohereResponseEnvelope {
+  return apiError(404, `not found: ${method} ${path}`);
+}
+
+/** Read-only mode refuses every mutation (D3). Cohere has no 405 idiom of its own, so the twin
+ *  answers its own `{message}` envelope with the standard 405 status. */
+function readOnlyRefusal(): CohereResponseEnvelope {
+  return apiError(405, 'this twin is running read-only; writes are refused.');
+}
+
+// ── modeled authentication (401) ────────────────────────────────────────────────────────
+/** The obvious-invalid sentinel a caller can use to exercise the 401 path deterministically. */
+const INVALID_KEY_SENTINEL = 'invalid';
+
+/**
+ * 401 when a request carries an auth SURFACE (headers present) but no usable bearer token. The
+ * twin cannot validate against real Cohere keys, so the modeled failure is the CHECKABLE
+ * missing / sentinel-invalid case; any other non-empty token is accepted (auth is faked, D3).
+ *
+ * cohere-ai sends `Authorization: Bearer <token>`, sourcing the token from the constructor's
+ * `token` option or the `CO_API_KEY` env var (`auth/BearerAuthProvider.js`, `const ENV_TOKEN =
+ * "CO_API_KEY"`); @ai-sdk/cohere sends the same header from `COHERE_API_KEY`.
+ */
+function checkAuth(req: CohereRequest): CohereResponseEnvelope | null {
+  if (req.headers === undefined) return null;
+  const raw = req.headers.authorization ?? '';
+  const token = raw.toLowerCase().startsWith('bearer ') ? raw.slice(7).trim() : '';
+  if (token === '' || token === INVALID_KEY_SENTINEL) {
+    return apiError(401, 'invalid api token');
+  }
+  return null;
+}
+
+// ── time ────────────────────────────────────────────────────────────────────────────────
+/** A FIXED default instant. The served response must be a pure function of (request, stored
+ *  state) — reading the wall clock here would make replay non-byte-identical. Callers that want a
+ *  moving clock pass `occurredAt` explicitly. */
+const PINNED_EPOCH_MS = 1_800_000_000_000;
+function nowIso(occurredAt?: string): string {
+  return occurredAt ?? new Date(PINNED_EPOCH_MS).toISOString();
+}
+
+// ── meta ────────────────────────────────────────────────────────────────────────────────
+function meta(billed: CohereApiMeta['billed_units'], tokens?: CohereApiMeta['tokens'], warnings?: string[]): CohereApiMeta {
+  return {
+    api_version: { version: API_VERSION },
+    billed_units: billed,
+    ...(tokens ? { tokens } : {}),
+    ...(warnings && warnings.length ? { warnings } : {}),
+  };
+}
+
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+/** EVERY row of a type, tombstones included — the id-mint denominator. */
+function allRows(type: string, root?: string): Array<Record<string, unknown>> {
+  return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+/** The LIVE rows of a type — what reads serve (a `_deleted` tombstone is invisible). */
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  return allRows(type, root).filter((r) => r._deleted !== true);
+}
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+
+/**
+ * Mint the next id for `type`. The ordinal is the max already seen ACROSS TOMBSTONES, so
+ * delete-then-create never re-issues a live id, and it is scanned from the id SET rather than
+ * derived from a row count or a module-level counter — a count-mint collides the moment a pulled
+ * vendor id sits in a gap above the row count.
+ *
+ * Cohere's own ids are UUIDs, so the twin's are UUID-SHAPED too (vendor-faithful ids are part of
+ * the surface) but derived from a namespaced, ordinal-bearing seed. The `-twin-` marker in the
+ * seed is what keeps a locally minted id from ever colliding with a pulled vendor id in either
+ * direction: the twin's ids live in a namespace no Cohere UUID occupies.
+ */
+function nextId(type: string, root?: string): string {
+  const seen = new Set<string>();
+  for (const r of allRows(type, root)) seen.add(String(r.id));
+  let ordinal = seen.size + 1;
+  // Probe upward until the derived id is genuinely unused. Bounded, deterministic, and it cannot
+  // spin: each iteration tries a different ordinal and the set is finite.
+  for (let guard = 0; guard <= seen.size + 1; guard++, ordinal++) {
+    const candidate = cohereId(`cohere-twin-${type}-${ordinal}`);
+    if (!seen.has(candidate)) return candidate;
+  }
+  /* c8 ignore next */
+  throw new Error(`cohere: could not mint a free ${type} id`);
+}
+
+/** Drop the kernel housekeeping fields (`type`/`updatedAt` are RESERVED by the projection and
+ *  never survive it) and the twin's private underscore-prefixed fields, so the served view is
+ *  exactly the vendor's. */
+function strip(r: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r)) {
+    if (k === 'type' || k === 'updatedAt' || k.startsWith('_')) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+async function write(req: CohereRequest, operation: string, subjectType: string, subjectId: string, fields: Record<string, unknown>): Promise<void> {
+  await applyTwinWrite(SERVICE, {
+    operation,
+    subjectType,
+    subjectId,
+    fields,
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'agent' },
+  }, req.root);
+}
+
+/**
+ * The next per-subject write ordinal — the kernel's content+millisecond dedupe hazard, closed.
+ *
+ * `applyTwinWrite`'s action id is (content + `occurredAt` millisecond), so a write that returns a
+ * subject to a value it PREVIOUSLY HELD at the same instant collides with the earlier action and is
+ * silently dropped as `replayed`: the reply reports the new value while the projection keeps the
+ * old one. That is not theoretical here — a world running under a FROZEN clock
+ * (`TWIN_WORLD_CLOCK_FILE`) gives every request in it one `occurredAt`, so
+ * `PATCH name:'A'` → `PATCH name:'B'` → `PATCH name:'A'` makes the third action byte-identical to
+ * the first, and the handler answers 200 carrying `'B'` — the value the caller did NOT ask for
+ * (§9 round 1, finding 4).
+ *
+ * Folding a monotonically increasing ordinal into the write's fields makes every genuine write
+ * distinct by content, so no real write can be mistaken for a replay. It is underscore-prefixed and
+ * therefore stripped from every served view. (`upstash-store.ts`'s `rev` is the precedent.)
+ *
+ * Only revisitable paths need it: a CREATE mints a fresh id and a DELETE is one-way, so
+ * `connector.update` is the single write in this twin whose (subject, fields) can revisit a prior
+ * value. `token.observe` deliberately does NOT get one — an (id → segment) pair is immutable, so a
+ * repeat genuinely IS a replay and the kernel's dedupe is the correct behaviour there.
+ */
+function nextRev(type: string, id: string, root?: string): number {
+  const row = getRow(type, id, root);
+  const rev = row?._rev;
+  return (typeof rev === 'number' ? rev : 0) + 1;
+}
+
+function parseJson(body?: string): Record<string, unknown> {
+  if (!body) return {};
+  try {
+    const v = JSON.parse(body) as unknown;
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// CHAT v2
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+export type ChatV2Args = {
+  model: string;
+  messages: CohereMessageV2[];
+  tools?: unknown;
+  toolChoice?: 'REQUIRED' | 'NONE';
+  maxTokens?: number;
+  stream: boolean;
+  thinking: boolean;
+};
+
+const V2_ROLES = new Set(['user', 'assistant', 'system', 'tool']);
+const TOOL_CHOICES = new Set(['REQUIRED', 'NONE']);
+const SAFETY_MODES = new Set(['CONTEXTUAL', 'STRICT', 'OFF']);
+
+/**
+ * Validate a v2 chat body. Every rejection below is a CLOSED SET the SDK itself declares, so the
+ * check is an oracle rather than a guess: `ChatMessageV2` is a four-member union discriminated on
+ * `role`, `V2ChatRequestToolChoice` is exactly {REQUIRED, NONE}, and `V2ChatRequestSafetyMode` is
+ * exactly {CONTEXTUAL, STRICT, OFF}.
+ */
+function validateChatV2(params: Record<string, unknown>): { args: ChatV2Args } | { error: CohereResponseEnvelope } {
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return { error: invalidRequest('model is required') };
+  const messages = params.messages;
+  if (!Array.isArray(messages)) return { error: invalidRequest('messages is required') };
+  if (messages.length === 0) return { error: invalidRequest('messages must not be empty') };
+  for (const [i, m] of messages.entries()) {
+    const role = (m as { role?: unknown })?.role;
+    if (typeof role !== 'string' || !V2_ROLES.has(role)) {
+      return { error: invalidRequest(`messages[${i}].role must be one of ${[...V2_ROLES].join(', ')}`) };
+    }
+  }
+  if (params.tool_choice !== undefined && (typeof params.tool_choice !== 'string' || !TOOL_CHOICES.has(params.tool_choice))) {
+    return { error: invalidRequest(`tool_choice must be one of ${[...TOOL_CHOICES].join(', ')}`) };
+  }
+  if (params.safety_mode !== undefined && (typeof params.safety_mode !== 'string' || !SAFETY_MODES.has(params.safety_mode))) {
+    return { error: invalidRequest(`safety_mode must be one of ${[...SAFETY_MODES].join(', ')}`) };
+  }
+  if (!modelServes(model, 'chat')) return { error: modelNotFound(model) };
+  const thinking = (params.thinking as { type?: unknown } | undefined)?.type === 'enabled';
+  return {
+    args: {
+      model,
+      messages: messages as CohereMessageV2[],
+      ...(params.tools !== undefined ? { tools: params.tools } : {}),
+      ...(typeof params.tool_choice === 'string' ? { toolChoice: params.tool_choice as 'REQUIRED' | 'NONE' } : {}),
+      ...(typeof params.max_tokens === 'number' ? { maxTokens: params.max_tokens } : {}),
+      stream: params.stream === true,
+      thinking,
+    },
+  };
+}
+
+/** The outcome of ONE engine advance. `missTeach` is appended to the stub so an in-world agent
+ *  that never matched a handler is told what features it would have to match on. */
+type ScenarioOutcome = { scripted?: ScriptedResult; error?: CohereResponseEnvelope; missTeach?: string };
+
+/** Ask the scenario engine (if any) what this turn should say. ONE advance per request — the
+ *  kernel's `next()` mutates scope state (call counter, `once`, `phase`) exactly like serving, so
+ *  calling it twice for one request would double-count every handler. */
+function scenarioDecision(args: ChatV2Args, engine: CohereScenarioEngine): ScenarioOutcome {
+  const decision = engine.next({
+    model: args.model,
+    messages: args.messages,
+    ...(args.tools !== undefined ? { tools: args.tools } : {}),
+  });
+  if (decision.kind !== 'handler') {
+    return { missTeach: `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/cohere.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]` };
+  }
+  const respond = decision.respond as CohereScenarioRespond;
+  if (respond.error) {
+    // A scripted API error is served INSTEAD of a completion — the vendor's own status and
+    // `{message}` envelope, on both the unary and the streaming path. Deciding it here is what
+    // lets it be a real HTTP status rather than a 200 carrying an error-shaped body.
+    const kind = respond.error.type;
+    if (kind === 'rate_limit') {
+      const retry = respond.error.retryAfter ?? 1;
+      return { error: { ...apiError(429, 'too many requests'), headers: { 'retry-after': String(retry) } } };
+    }
+    if (kind === 'service_unavailable') return { error: apiError(503, 'service unavailable') };
+    return { error: apiError(500, 'internal server error') };
+  }
+  return { scripted: realizeCohereRespond(respond) };
+}
+
+/** The assistant turn (scripted or stubbed) plus the finish reason it implies. */
+function assistantTurn(args: ChatV2Args, scripted?: ScriptedResult, missTeach = ''): { content: CohereAssistantContentItem[]; toolCalls: CohereToolCallV2[]; toolPlan?: string; finish: CohereFinishReason } {
+  if (scripted) {
+    return {
+      content: scripted.content,
+      toolCalls: scripted.toolCalls,
+      ...(scripted.toolPlan !== undefined ? { toolPlan: scripted.toolPlan } : {}),
+      finish: scripted.finishReason,
+    };
+  }
+  const names = toolNames(args.tools);
+  // `tool_choice: 'NONE'` forbids a tool call even when tools are declared — the vendor honours it
+  // and so must the twin, or a caller testing the NONE path gets a tool call it explicitly banned.
+  const wantsTool = names.length > 0 && args.toolChoice !== 'NONE';
+  const seed = JSON.stringify(args.messages);
+  if (wantsTool) {
+    const call = stubToolCall(args.tools, seed, 0);
+    return { content: [], toolCalls: call ? [call] : [], toolPlan: stubToolPlan(names), finish: 'TOOL_CALL' };
+  }
+  const content: CohereAssistantContentItem[] = [];
+  if (args.thinking) content.push({ type: 'thinking', thinking: `[twin-stub] deterministic reasoning trace for ${args.model}.` });
+  content.push({ type: 'text', text: stubAssistantText(args.messages, args.model) + missTeach });
+  return { content, toolCalls: [], finish: 'COMPLETE' };
+}
+
+function usageFor(args: ChatV2Args, outputText: string): CohereUsage {
+  const input = countInputTokens(args.messages);
+  const output = estimateTokens(outputText);
+  // Cohere reports the SAME counts twice, under `billed_units` and `tokens`. They are distinct
+  // objects on the wire (a caller may read either), so both are emitted.
+  return { billed_units: { input_tokens: input, output_tokens: output }, tokens: { input_tokens: input, output_tokens: output } };
+}
+
+function outputTextOf(content: CohereAssistantContentItem[], toolCalls: CohereToolCallV2[], toolPlan?: string): string {
+  const parts = content.map((c) => (c.type === 'text' ? c.text : c.thinking));
+  if (toolPlan) parts.push(toolPlan);
+  for (const tc of toolCalls) parts.push(tc.function.arguments);
+  return parts.join('');
+}
+
+/** Build the unary `POST /v2/chat` envelope. */
+export function buildChatV2(args: ChatV2Args, outcome: ScenarioOutcome = {}): CohereChatV2Response {
+  const turn = assistantTurn(args, outcome.scripted, outcome.missTeach ?? '');
+  const text = outputTextOf(turn.content, turn.toolCalls, turn.toolPlan);
+  const message: CohereChatV2Response['message'] = { role: 'assistant' };
+  // Cohere OMITS the empty halves rather than sending nulls: an assistant turn that made a tool
+  // call carries `tool_calls` + `tool_plan` and no `content`, and a plain turn carries `content`
+  // and neither of the others.
+  if (turn.content.length > 0) message.content = turn.content;
+  if (turn.toolPlan !== undefined) message.tool_plan = turn.toolPlan;
+  if (turn.toolCalls.length > 0) message.tool_calls = turn.toolCalls;
+  return {
+    id: cohereId(`chat-v2|${args.model}|${JSON.stringify(args.messages)}`),
+    finish_reason: turn.finish,
+    message,
+    usage: usageFor(args, text),
+  };
+}
+
+/**
+ * Stream `POST /v2/chat` into the injected sink and return the same body the unary path would.
+ *
+ * The event sequence is Cohere's own, and it is asserted key-for-key against
+ * @ai-sdk/cohere's `cohereChatChunkSchema` — a `z.discriminatedUnion('type', …)`, so a wrong
+ * `type` or a missing `delta.message.content` is a hard parse failure in the real provider, not a
+ * soft mismatch. Note the shapes differ between `content-start` (a full content BLOCK under
+ * `delta.message.content`) and `content-delta` (just `{ text }`), which is exactly the sort of
+ * detail a hand-written stream gets wrong.
+ */
+export function streamChatV2(args: ChatV2Args, sink: SseSink, outcome: ScenarioOutcome = {}): CohereChatV2Response {
+  const full = buildChatV2(args, outcome);
+  sink({ data: { type: 'message-start', id: full.id, delta: { message: { role: 'assistant' } } } });
+
+  const toolPlan = full.message.tool_plan;
+  if (toolPlan !== undefined) {
+    for (const piece of chunkText(toolPlan)) {
+      sink({ data: { type: 'tool-plan-delta', delta: { message: { tool_plan: piece } } } });
+    }
+  }
+
+  const blocks = full.message.content ?? [];
+  for (const [index, block] of blocks.entries()) {
+    const kind = block.type;
+    const whole = kind === 'text' ? block.text : block.thinking;
+    sink({ data: { type: 'content-start', index, delta: { message: { content: kind === 'text' ? { type: 'text', text: '' } : { type: 'thinking', thinking: '' } } } } });
+    for (const piece of chunkText(whole)) {
+      sink({ data: { type: 'content-delta', index, delta: { message: { content: kind === 'text' ? { text: piece } : { thinking: piece } } } } });
+    }
+    sink({ data: { type: 'content-end', index } });
+  }
+
+  for (const [index, call] of (full.message.tool_calls ?? []).entries()) {
+    sink({ data: { type: 'tool-call-start', index, delta: { message: { tool_calls: { id: call.id, type: 'function', function: { name: call.function.name, arguments: '' } } } } } });
+    for (const piece of chunkText(call.function.arguments)) {
+      sink({ data: { type: 'tool-call-delta', index, delta: { message: { tool_calls: { function: { arguments: piece } } } } } });
+    }
+    sink({ data: { type: 'tool-call-end', index } });
+  }
+
+  sink({ data: { type: 'message-end', id: full.id, delta: { finish_reason: full.finish_reason, usage: full.usage } } });
+  sink({ done: true });
+  return full;
+}
+
+/** Split text into deterministic streaming pieces. Deterministic chunking is what makes a
+ *  streamed replay byte-identical to the previous one. */
+function chunkText(text: string): string[] {
+  if (text === '') return [];
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += 24) out.push(text.slice(i, i + 24));
+  return out;
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// CHAT v1 — a DIFFERENT protocol, not a versioned alias
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+function handleChatV1(params: Record<string, unknown>, req: CohereRequest): CohereResponseEnvelope {
+  const message = params.message;
+  // v1's required field is `message` (a STRING) — a caller that sends v2's `messages` array here
+  // gets this refusal, which is the honest answer: it is talking the wrong protocol version.
+  if (typeof message !== 'string' || message === '') return invalidRequest('message is required');
+  const model = typeof params.model === 'string' && params.model !== '' ? params.model : 'command-a-03-2025';
+  if (!modelServes(model, 'chat')) return modelNotFound(model);
+  const history = Array.isArray(params.chat_history) ? (params.chat_history as Array<Record<string, unknown>>) : [];
+  const text = stubV1Text(message, model);
+  const inputTokens = estimateTokens(message) + history.reduce((a, h) => a + estimateTokens(String(h.message ?? '')), 0);
+  const outputTokens = estimateTokens(text);
+  const seed = `chat-v1|${model}|${message}|${JSON.stringify(history)}`;
+  if (params.stream === true) {
+    if (!req.sseSink) return invalidRequest('stream:true requires a streaming transport');
+    return { status: 200, body: streamChatV1(text, seed, req.sseSink, inputTokens, outputTokens, model, message, history) };
+  }
+  return { status: 200, body: v1ChatBody(text, seed, inputTokens, outputTokens, message, history) };
+}
+
+function v1ChatBody(text: string, seed: string, inputTokens: number, outputTokens: number, message: string, history: Array<Record<string, unknown>>): Record<string, unknown> {
+  return {
+    text,
+    generation_id: cohereId(`${seed}|gen`),
+    response_id: cohereId(`${seed}|res`),
+    finish_reason: 'COMPLETE' satisfies CohereV1FinishReason,  // valid in v1's set, v2's, and the stream-end set
+    chat_history: [
+      ...history.map((h) => ({ role: String(h.role ?? 'USER'), message: String(h.message ?? '') })),
+      { role: 'USER', message },
+      { role: 'CHATBOT', message: text },
+    ],
+    meta: meta({ input_tokens: inputTokens, output_tokens: outputTokens }, { input_tokens: inputTokens, output_tokens: outputTokens }),
+  };
+}
+
+/**
+ * v1's stream is a DIFFERENT wire from v2's: newline-delimited JSON objects discriminated on
+ * `event_type` (`stream-start` / `text-generation` / `stream-end`), not v2's `type`-tagged SSE.
+ * The twin emits it through the same sink; the server frames v1 as NDJSON and v2 as SSE, which is
+ * what the two halves of cohere-ai actually decode.
+ */
+function streamChatV1(text: string, seed: string, sink: SseSink, inputTokens: number, outputTokens: number, model: string, message: string, history: Array<Record<string, unknown>>): Record<string, unknown> {
+  const full = v1ChatBody(text, seed, inputTokens, outputTokens, message, history);
+  void model;
+  sink({ data: { is_finished: false, event_type: 'stream-start', generation_id: full.generation_id } });
+  for (const piece of chunkText(text)) {
+    sink({ data: { is_finished: false, event_type: 'text-generation', text: piece } });
+  }
+  sink({ data: { is_finished: true, event_type: 'stream-end', finish_reason: 'COMPLETE', response: full } });
+  return full;
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// EMBED
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+const EMBEDDING_TYPES = new Set<string>(COHERE_EMBEDDING_TYPES);
+const INPUT_TYPES = new Set<string>(COHERE_INPUT_TYPES);
+const TRUNCATE = new Set<string>(COHERE_TRUNCATE);
+
+/** Which embed models require an explicit `input_type` on v1. Cohere's v3+ embed models do; the
+ *  legacy v2 ones did not, which is exactly why the v1 endpoint keeps the field optional and
+ *  refuses at request time instead. */
+function requiresInputType(model: string): boolean {
+  return /-v[34](\.\d+)?$|v3\.0$|^embed-v4\.0$/.test(model) || model.includes('v3.0') || model === 'embed-v4.0';
+}
+
+function embedVectors(texts: string[], model: string, outputDimension?: number): number[][] {
+  const dim = outputDimension ?? embedDimensions(model);
+  return texts.map((t) => pseudoEmbedding(t, dim));
+}
+
+/** Build the `embeddings` object keyed by the requested types. */
+function embeddingsByType(floats: number[][], types: CohereEmbeddingType[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const t of types) {
+    if (t === 'float') out.float = floats;
+    else if (t === 'base64') out.base64 = floats.map(base64Embedding);
+    else out[t] = floats.map((v) => quantizeEmbedding(v, t));
+  }
+  return out;
+}
+
+function collectEmbedInputs(params: Record<string, unknown>): string[] | null {
+  const texts = params.texts;
+  if (Array.isArray(texts)) return texts.map((t) => String(t));
+  // v2 also accepts `inputs: EmbedInput[]`, each carrying a `content` part array.
+  const inputs = params.inputs;
+  if (Array.isArray(inputs)) {
+    return inputs.map((i) => contentToText((i as { content?: CohereMessageV2['content'] })?.content ?? ''));
+  }
+  const images = params.images;
+  if (Array.isArray(images)) return images.map((i) => String(i));
+  return null;
+}
+
+function validateEmbedShared(params: Record<string, unknown>): CohereResponseEnvelope | null {
+  const types = params.embedding_types;
+  if (types !== undefined) {
+    if (!Array.isArray(types) || types.length === 0) return invalidRequest('embedding_types must be a non-empty list');
+    for (const t of types) {
+      if (typeof t !== 'string' || !EMBEDDING_TYPES.has(t)) {
+        return invalidRequest(`embedding_types must be a subset of ${[...EMBEDDING_TYPES].join(', ')}`);
+      }
+    }
+  }
+  if (params.input_type !== undefined && (typeof params.input_type !== 'string' || !INPUT_TYPES.has(params.input_type))) {
+    return invalidRequest(`input_type must be one of ${[...INPUT_TYPES].join(', ')}`);
+  }
+  if (params.truncate !== undefined && (typeof params.truncate !== 'string' || !TRUNCATE.has(params.truncate))) {
+    return invalidRequest(`truncate must be one of ${[...TRUNCATE].join(', ')}`);
+  }
+  if (params.output_dimension !== undefined) {
+    const d = params.output_dimension;
+    if (typeof d !== 'number' || !(COHERE_OUTPUT_DIMENSIONS as readonly number[]).includes(d)) {
+      return invalidRequest(`output_dimension must be one of ${COHERE_OUTPUT_DIMENSIONS.join(', ')}`);
+    }
+  }
+  return null;
+}
+
+/** `POST /v2/embed`. `model` AND `input_type` are both REQUIRED here — the v2 request type
+ *  declares them non-optional, and this is the sharpest v1-vs-v2 difference. */
+function handleEmbedV2(params: Record<string, unknown>): CohereResponseEnvelope {
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return invalidRequest('model is required');
+  if (typeof params.input_type !== 'string' || params.input_type === '') return invalidRequest('input_type is required');
+  const shared = validateEmbedShared(params);
+  if (shared) return shared;
+  if (!modelServes(model, 'embed')) return modelNotFound(model);
+  const texts = collectEmbedInputs(params);
+  if (texts === null || texts.length === 0) return invalidRequest('one of texts, images or inputs is required');
+  const types = (Array.isArray(params.embedding_types) ? params.embedding_types : ['float']) as CohereEmbeddingType[];
+  const floats = embedVectors(texts, model, typeof params.output_dimension === 'number' ? params.output_dimension : undefined);
+  const inputTokens = texts.reduce((a, t) => a + estimateTokens(t), 0);
+  return {
+    status: 200,
+    body: {
+      id: cohereId(`embed-v2|${model}|${JSON.stringify(texts)}|${types.join(',')}`),
+      embeddings: embeddingsByType(floats, types),
+      texts,
+      response_type: 'embeddings_by_type',
+      // NO `output_tokens`: an embed call has no output side, and Cohere's embed `billed_units`
+      // carries only `input_tokens` (plus images/image_tokens for image inputs). Emitting a zero
+      // would be an invented key in a pack whose whole thesis is that it invents none.
+      meta: meta({ input_tokens: inputTokens }, { input_tokens: inputTokens }),
+    },
+  };
+}
+
+/**
+ * `POST /v1/embed`. Two things differ from v2 and BOTH are load-bearing:
+ *   • `input_type` is optional in the schema — but a v3/v4 embed model still refuses without one,
+ *     so the check moves from the schema to the handler;
+ *   • the DEFAULT response is `embeddings_floats` — a FLAT `number[][]` at `embeddings`. Only when
+ *     the caller asks for `embedding_types` does v1 answer the by-type shape. A twin that always
+ *     answered by-type would break every default v1 caller.
+ */
+function handleEmbedV1(params: Record<string, unknown>): CohereResponseEnvelope {
+  const model = typeof params.model === 'string' && params.model !== '' ? params.model : 'embed-english-v3.0';
+  const shared = validateEmbedShared(params);
+  if (shared) return shared;
+  if (!modelServes(model, 'embed')) return modelNotFound(model);
+  if (requiresInputType(model) && params.input_type === undefined) {
+    return invalidRequest(`input_type is required for model '${model}'`);
+  }
+  const texts = collectEmbedInputs(params);
+  if (texts === null || texts.length === 0) return invalidRequest('one of texts or images is required');
+  const floats = embedVectors(texts, model, typeof params.output_dimension === 'number' ? params.output_dimension : undefined);
+  const inputTokens = texts.reduce((a, t) => a + estimateTokens(t), 0);
+  const id = cohereId(`embed-v1|${model}|${JSON.stringify(texts)}`);
+  const m = meta({ input_tokens: inputTokens }, { input_tokens: inputTokens });  // embed has no output side
+  if (params.embedding_types === undefined) {
+    return { status: 200, body: { id, embeddings: floats, texts, response_type: 'embeddings_floats', meta: m } };
+  }
+  const types = params.embedding_types as CohereEmbeddingType[];
+  return { status: 200, body: { id, embeddings: embeddingsByType(floats, types), texts, response_type: 'embeddings_by_type', meta: m } };
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// RERANK
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+function rankAll(query: string, docs: string[]): Array<{ index: number; relevance_score: number }> {
+  return docs
+    .map((d, index) => ({ index, relevance_score: rerankScore(query, d) }))
+    .sort((a, b) => b.relevance_score - a.relevance_score);
+}
+
+/** `POST /v2/rerank`. `documents` is `string[]` in v2 — an object element is refused. */
+function handleRerankV2(params: Record<string, unknown>): CohereResponseEnvelope {
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return invalidRequest('model is required');
+  const query = params.query;
+  if (typeof query !== 'string' || query === '') return invalidRequest('query is required');
+  const documents = params.documents;
+  if (!Array.isArray(documents) || documents.length === 0) return invalidRequest('documents is required');
+  for (const [i, d] of documents.entries()) {
+    if (typeof d !== 'string') return invalidRequest(`documents[${i}] must be a string`);
+  }
+  if (!modelServes(model, 'rerank')) return modelNotFound(model);
+  const docs = documents as string[];
+  const topN = typeof params.top_n === 'number' && params.top_n > 0 ? Math.min(params.top_n, docs.length) : docs.length;
+  const results = rankAll(query, docs).slice(0, topN);
+  return {
+    status: 200,
+    body: {
+      id: cohereId(`rerank-v2|${model}|${query}|${JSON.stringify(docs)}`),
+      results,
+      // Rerank is billed in SEARCH UNITS, not tokens — one per (query, up to 100 documents) call.
+      meta: meta({ search_units: 1 }),
+    },
+  };
+}
+
+/** `POST /v1/rerank`. Accepts object documents and honours `return_documents`, neither of which
+ *  exists in v2. */
+function handleRerankV1(params: Record<string, unknown>): CohereResponseEnvelope {
+  const query = params.query;
+  if (typeof query !== 'string' || query === '') return invalidRequest('query is required');
+  const documents = params.documents;
+  if (!Array.isArray(documents) || documents.length === 0) return invalidRequest('documents is required');
+  const model = typeof params.model === 'string' && params.model !== '' ? params.model : 'rerank-v3.5';
+  if (!modelServes(model, 'rerank')) return modelNotFound(model);
+  const rankFields = Array.isArray(params.rank_fields) ? (params.rank_fields as string[]) : undefined;
+  const texts = documents.map((d) => {
+    if (typeof d === 'string') return d;
+    const o = d as Record<string, unknown>;
+    if (rankFields) return rankFields.map((f) => String(o[f] ?? '')).join(' ');
+    if (typeof o.text === 'string') return o.text;
+    return JSON.stringify(o);
+  });
+  const topN = typeof params.top_n === 'number' && params.top_n > 0 ? Math.min(params.top_n, texts.length) : texts.length;
+  const ranked = rankAll(query, texts).slice(0, topN);
+  const returnDocuments = params.return_documents === true;
+  return {
+    status: 200,
+    body: {
+      id: cohereId(`rerank-v1|${model}|${query}|${JSON.stringify(texts)}`),
+      results: ranked.map((r) => (returnDocuments ? { ...r, document: { text: texts[r.index]! } } : r)),
+      meta: meta({ search_units: 1 }),
+    },
+  };
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// CLASSIFY / TOKENIZE / DETOKENIZE / CHECK-API-KEY
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+function handleClassify(params: Record<string, unknown>): CohereResponseEnvelope {
+  const inputs = params.inputs;
+  if (!Array.isArray(inputs) || inputs.length === 0) return invalidRequest('inputs is required');
+  const examples = params.examples;
+  const preset = params.preset;
+  // Cohere's classify needs a way to know the label space: either training `examples` or a saved
+  // `preset`. With neither there is nothing to classify against, and it refuses.
+  if (!Array.isArray(examples) && typeof preset !== 'string') {
+    return invalidRequest('one of examples or preset is required');
+  }
+  let labels: string[];
+  if (Array.isArray(examples)) {
+    const seen: string[] = [];
+    for (const e of examples) {
+      const label = (e as { label?: unknown })?.label;
+      if (typeof label !== 'string' || label === '') return invalidRequest('each example requires a label');
+      if (!seen.includes(label)) seen.push(label);
+    }
+    // The vendor's documented minimum: a classifier needs at least two distinct classes.
+    if (seen.length < 2) return invalidRequest('at least 2 unique labels are required');
+    labels = seen;
+  } else {
+    // NEVER A FAKE SUCCESS. An earlier version invented `['positive','negative']` as the label space
+    // for ANY preset string, returning confident-looking classifications against labels the caller
+    // never named — the exact class the detokenize path treats as a hard rule and that
+    // `cohere.errors.unmodeled_ops_404` claims pack-wide. Presets are a filed todo
+    // (`cohere.classify.preset`); until they are modeled, an unmodeled op fails like the vendor.
+    return notFound(`preset '${String(preset)}' not found — this twin does not model saved classify presets`);
+  }
+  const texts = inputs.map((i) => String(i));
+  const classifications = texts.map((input, i) => {
+    const { prediction, confidences } = classifyText(input, labels);
+    const labelMap: Record<string, { confidence: number }> = {};
+    labels.forEach((l, j) => { labelMap[l] = { confidence: confidences[j]! }; });
+    return {
+      id: cohereId(`classify|${input}|${i}`),
+      input,
+      prediction,
+      predictions: [prediction],
+      confidence: Math.max(...confidences),
+      confidences: [Math.max(...confidences)],
+      labels: labelMap,
+      classification_type: 'single-label' as const,
+    };
+  });
+  return {
+    status: 200,
+    body: {
+      id: cohereId(`classify-call|${JSON.stringify(texts)}|${labels.join(',')}`),
+      classifications,
+      // Classify is billed per CLASSIFICATION, not per token.
+      meta: meta({ classifications: texts.length }),
+    },
+  };
+}
+
+/**
+ * `POST /v1/tokenize` — and the place the twin's vocabulary is LEARNED.
+ *
+ * The twin has no BPE vocabulary yet (`cohere.tokenize.bpe_vocabulary` is a todo), so it
+ * cannot invent a reverse mapping for `detokenize` out of thin air without fabricating. Instead
+ * tokenize OBSERVES each (id → segment) pair into the kernel log; detokenize folds that
+ * projection. The result is a twin that can only detokenize what it has genuinely seen — and says
+ * so, with a 400, otherwise.
+ */
+async function handleTokenize(params: Record<string, unknown>, req: CohereRequest): Promise<CohereResponseEnvelope> {
+  const text = params.text;
+  // Both fields are REQUIRED in `TokenizeRequest` — `model` is not optional here, unlike on
+  // /v1/embed and /v1/rerank.
+  if (typeof text !== 'string' || text === '') return invalidRequest('text is required');
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return invalidRequest('model is required');
+  if (findModel(model) === undefined) return modelNotFound(model);
+
+  const segments = segmentText(text);
+  // Read the vocabulary ONCE, then resolve every segment against the same in-memory view. Reading
+  // per segment would make an id assigned earlier in THIS request invisible to a later one, so a
+  // text repeating a colliding pair would mint two ids for one string.
+  const vocab = new Map<string, number>();
+  const taken = new Map<number, string>();
+  for (const r of rows('token', req.root)) {
+    const seg = String(r.segment);
+    const tid = Number(r.token_id);
+    vocab.set(seg, tid);
+    taken.set(tid, seg);
+  }
+  const tokens: number[] = [];
+  const fresh: Array<{ id: number; segment: string }> = [];
+  for (const segment of segments) {
+    const existing = vocab.get(segment);
+    if (existing !== undefined) { tokens.push(existing); continue; }
+    const id = assignToken(segment, taken);
+    vocab.set(segment, id);
+    taken.set(id, segment);
+    fresh.push({ id, segment });
+    tokens.push(id);
+  }
+  for (const f of fresh) {
+    // One row per token, keyed by the id — the subject id IS the token id, so a re-observation of
+    // the same pair dedupes in the kernel rather than growing the log.
+    await write(req, 'token.observe', 'token', `tok_${f.id}`, { token_id: f.id, segment: f.segment });
+  }
+  const inputTokens = estimateTokens(text);
+  return {
+    status: 200,
+    body: { tokens, token_strings: segments, meta: meta({ input_tokens: inputTokens }, { input_tokens: inputTokens }) },
+  };
+}
+
+/**
+ * Resolve a segment's token id. The preferred id is a pure hash of the segment; when a DIFFERENT
+ * segment already holds it, probe upward until a free id is found.
+ *
+ * Without the probe the second segment would silently overwrite the first's row and `detokenize`
+ * would then return the WRONG text for every earlier caller — a dirty-state bug invisible to any
+ * fresh-root verify, which is exactly why `cohere.tokenize.collision_probe` builds the collision
+ * up deliberately.
+ */
+function assignToken(segment: string, taken: Map<number, string>): number {
+  let id = preferredTokenId(segment);
+  // BOUNDED, like `nextId`. The id space is [1, 250_000]; an unbounded probe would spin FOREVER
+  // once the learned vocabulary filled it, hanging the server's fetch callback rather than failing
+  // (§9 round 1, finding 5). The bound is the occupied-set size + 1, so it can only be reached when
+  // every id genuinely is taken — and then it says so loudly.
+  for (let guard = 0; guard <= taken.size; guard++) {
+    if (!taken.has(id) || taken.get(id) === segment) return id;
+    id = (id % 250_000) + 1;
+  }
+  throw new Error('cohere: token vocabulary exhausted — every id in [1, 250000] is assigned to a different segment');
+}
+
+async function handleDetokenize(params: Record<string, unknown>, req: CohereRequest): Promise<CohereResponseEnvelope> {
+  const tokens = params.tokens;
+  if (!Array.isArray(tokens)) return invalidRequest('tokens is required');
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return invalidRequest('model is required');
+  if (findModel(model) === undefined) return modelNotFound(model);
+  const vocab = new Map<number, string>();
+  for (const r of rows('token', req.root)) vocab.set(Number(r.token_id), String(r.segment));
+  const parts: string[] = [];
+  for (const t of tokens) {
+    const seg = vocab.get(Number(t));
+    // NEVER a fake success. The twin's vocabulary is what it has observed; an id it has never
+    // issued is not something it can honestly decode, and silently dropping it (or emitting a
+    // placeholder) would hand the caller text the twin invented.
+    if (seg === undefined) return invalidRequest(`unknown token id ${String(t)} — this twin detokenizes only ids it has issued via POST /v1/tokenize`);
+    parts.push(seg);
+  }
+  const text = parts.join('');
+  return { status: 200, body: { text, meta: meta({ input_tokens: tokens.length }, { input_tokens: tokens.length }) } };
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// DATASETS (stateful)
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+/** `DatasetType` — the vendor's CLOSED set (`api/types/DatasetType.d.ts`). A literal allowlist is
+ *  an ORACLE here: the accepted values must biject exactly with this documented set. */
+const DATASET_TYPES = new Set([
+  'embed-input', 'embed-result', 'cluster-result', 'cluster-outliers',
+  'reranker-finetune-input', 'single-label-classification-finetune-input',
+  'chat-finetune-input', 'multi-label-classification-finetune-input',
+  'batch-chat-input', 'batch-openai-chat-input', 'batch-embed-v2-input', 'batch-chat-v2-input',
+]);
+
+/** `DatasetValidationStatus` — the vendor's closed set. */
+const VALIDATION_STATUSES = new Set(['unknown', 'queued', 'processing', 'failed', 'validated', 'skipped']);
+
+async function createDataset(params: Record<string, unknown>, query: URLSearchParams, req: CohereRequest): Promise<CohereResponseEnvelope> {
+  // `name` and `type` travel as QUERY parameters on this endpoint — the body is the multipart
+  // file. The server folds both into the handler's JSON contract, and the handler accepts either
+  // home so an in-process caller need not synthesize a query string.
+  const name = query.get('name') ?? (typeof params.name === 'string' ? params.name : '');
+  const type = query.get('type') ?? (typeof params.type === 'string' ? params.type : '');
+  if (!name) return invalidRequest('name is required');
+  if (!type) return invalidRequest('type is required');
+  if (!DATASET_TYPES.has(type)) return invalidRequest(`type must be one of ${[...DATASET_TYPES].join(', ')}`);
+  // The `data` file is REQUIRED: `datasets.create(data, evalData, request)` unconditionally does
+  // `_body.appendFile("data", data)` in cohere-ai@8.1.0, so the vendor never sees a fileless
+  // create. Accepting one would be an unmodeled input NOT failing like the vendor (§9 round 1,
+  // finding 6) — and it would have let the closed-DatasetType oracle be built on the lenient path.
+  const content = params.content;
+  if (typeof content !== 'string' || content === '') return invalidRequest('the data file is required');
+  const id = nextId('dataset', req.root);
+  const at = nowIso(req.occurredAt);
+  await write(req, 'dataset.create', 'dataset', id, {
+    // THE TWIN MINTED THIS ID, and the vendor has never heard of it. The connector reads this
+    // marker to refuse pushing an update/cancel/delete against a subject that has no vendor
+    // identity — without it a local delete fires the twin's own UUID at the REAL account
+    // (§9 round 1, connector B1/M1). It is underscore-prefixed, so no served view carries it, and
+    // the push-confirm strips it when it rebuilds the row under the vendor's id.
+    _twin_minted: true,
+    name,
+    dataset_type: type,
+    created_at: at,
+    updated_at: at,
+    validation_status: 'validated',
+    validation_error: null,
+    validation_warnings: [],
+    required_fields: [],
+    preserve_fields: [],
+    dataset_parts: [],
+    _content: content,
+  });
+  // Cohere's create answers ONLY `{ id }` — not the dataset. A twin returning the whole object
+  // here would be more "helpful" and less faithful.
+  return { status: 200, body: { id } };
+}
+
+function datasetView(r: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.id, ...strip(r) };
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// CONNECTORS (stateful)
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+async function createConnector(params: Record<string, unknown>, req: CohereRequest): Promise<CohereResponseEnvelope> {
+  const name = params.name;
+  if (typeof name !== 'string' || name === '') return invalidRequest('name is required');
+  const url = params.url;
+  if (typeof url !== 'string' || url === '') return invalidRequest('url is required');
+  const id = nextId('connector', req.root);
+  const at = nowIso(req.occurredAt);
+  const oauth = params.oauth as Record<string, unknown> | undefined;
+  await write(req, 'connector.create', 'connector', id, {
+    _twin_minted: true,  // see the note on dataset.create — the connector refuses to push a
+    _rev: 1,             // twin-minted subject's later mutations at a real account.
+    organization_id: 'org_twin',
+    name,
+    description: typeof params.description === 'string' ? params.description : null,
+    url,
+    created_at: at,
+    updated_at: at,
+    excludes: Array.isArray(params.excludes) ? params.excludes : [],
+    // `auth_type` is derived, not caller-supplied — it reports HOW the connector authenticates.
+    auth_type: oauth ? 'oauth' : params.service_auth ? 'service_auth' : 'none',
+    oauth: oauth ? { client_id: String(oauth.client_id ?? ''), authorize_url: String(oauth.authorize_url ?? ''), token_url: String(oauth.token_url ?? ''), scope: oauth.scope ?? null } : null,
+    auth_status: oauth ? 'expired' : 'valid',
+    active: params.active === undefined ? true : params.active === true,
+    continue_on_failure: params.continue_on_failure === true,
+  });
+  const row = getRow('connector', id, req.root)!;
+  return { status: 200, body: { connector: connectorView(row) } };
+}
+
+function connectorView(r: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.id, ...strip(r) };
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// EMBED JOBS (stateful)
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+const EMBED_JOB_STATUSES = new Set(['processing', 'complete', 'cancelling', 'cancelled', 'failed']);
+
+async function createEmbedJob(params: Record<string, unknown>, req: CohereRequest): Promise<CohereResponseEnvelope> {
+  const model = params.model;
+  if (typeof model !== 'string' || model === '') return invalidRequest('model is required');
+  const datasetId = params.dataset_id;
+  if (typeof datasetId !== 'string' || datasetId === '') return invalidRequest('dataset_id is required');
+  const inputType = params.input_type;
+  if (typeof inputType !== 'string' || inputType === '') return invalidRequest('input_type is required');
+  if (!INPUT_TYPES.has(inputType)) return invalidRequest(`input_type must be one of ${[...INPUT_TYPES].join(', ')}`);
+  if (params.truncate !== undefined && (typeof params.truncate !== 'string' || !TRUNCATE.has(params.truncate))) {
+    return invalidRequest(`truncate must be one of ${[...TRUNCATE].join(', ')}`);
+  }
+  if (!modelServes(model, 'embed')) return modelNotFound(model);
+  // The job's input must be a dataset that actually exists — a cross-resource invariant the
+  // vendor enforces and a twin that skipped it would let a caller queue work over nothing.
+  if (getRow('dataset', datasetId, req.root) === undefined) return notFound(`dataset '${datasetId}' not found`);
+  const id = nextId('embed_job', req.root);
+  await write(req, 'embed_job.create', 'embed_job', id, {
+    _twin_minted: true,  // see the note on dataset.create
+    job_id: id,
+    name: typeof params.name === 'string' ? params.name : null,
+    status: 'processing',
+    created_at: nowIso(req.occurredAt),
+    input_dataset_id: datasetId,
+    output_dataset_id: null,
+    model,
+    truncate: typeof params.truncate === 'string' ? params.truncate : 'END',
+  });
+  // Cohere's create answers `{ job_id, meta }` — not the job object.
+  return { status: 200, body: { job_id: id, meta: meta({}) } };
+}
+
+function embedJobView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = strip(r);
+  delete v.id; // the vendor's key for an embed job is `job_id`, and there is no `id` alongside it.
+  return v;
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// THE ROUTER CENSUS
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Every method/path pair the dispatch below branches on. HAND-AUTHORED (the honest limit): a
+ * branch added to the handler and to neither this list nor the conformance snapshot is invisible
+ * to the conformance check's third direction. The mechanical backstop for that lives in
+ * `cohere-twin.test.ts` ("covers every literal path the handler dispatches on"), which reads this
+ * module's own source; segment-matched sub-routes still rest on review.
+ *
+ * `{id}` stands for one path segment.
+ */
+export const COHERE_ROUTER_SURFACE: ReadonlyArray<{ method: string; path: string }> = [
+  { method: 'POST', path: '/v2/chat' },
+  { method: 'POST', path: '/v2/embed' },
+  { method: 'POST', path: '/v2/rerank' },
+  { method: 'POST', path: '/v1/chat' },
+  { method: 'POST', path: '/v1/embed' },
+  { method: 'POST', path: '/v1/rerank' },
+  { method: 'POST', path: '/v1/classify' },
+  { method: 'POST', path: '/v1/tokenize' },
+  { method: 'POST', path: '/v1/detokenize' },
+  { method: 'POST', path: '/v1/check-api-key' },
+  { method: 'GET', path: '/v1/models' },
+  { method: 'GET', path: '/v1/models/{id}' },
+  { method: 'POST', path: '/v1/datasets' },
+  { method: 'GET', path: '/v1/datasets' },
+  { method: 'GET', path: '/v1/datasets/usage' },
+  { method: 'GET', path: '/v1/datasets/{id}' },
+  { method: 'DELETE', path: '/v1/datasets/{id}' },
+  { method: 'POST', path: '/v1/connectors' },
+  { method: 'GET', path: '/v1/connectors' },
+  { method: 'GET', path: '/v1/connectors/{id}' },
+  { method: 'PATCH', path: '/v1/connectors/{id}' },
+  { method: 'DELETE', path: '/v1/connectors/{id}' },
+  { method: 'POST', path: '/v1/connectors/{id}/oauth/authorize' },
+  { method: 'POST', path: '/v1/embed-jobs' },
+  { method: 'GET', path: '/v1/embed-jobs' },
+  { method: 'GET', path: '/v1/embed-jobs/{id}' },
+  { method: 'POST', path: '/v1/embed-jobs/{id}/cancel' },
+];
+
+// ════════════════════════════════════════════════════════════════════════════════════════
+// DISPATCH
+// ════════════════════════════════════════════════════════════════════════════════════════
+
+export async function handleCohereTwinRequest(req: CohereRequest): Promise<CohereResponseEnvelope> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery = ''] = req.path.split('?');
+  const path = (rawPath ?? '').replace(/\/+$/, '') || '/';
+  const query = new URLSearchParams(rawQuery);
+  const seg = path.split('/').filter(Boolean);
+  const params = parseJson(req.body);
+  const readOnly = req.readOnly === true;
+
+  const authFailure = checkAuth(req);
+  if (authFailure) return authFailure;
+
+  const isWrite = method === 'POST' || method === 'DELETE' || method === 'PATCH' || method === 'PUT';
+  if (readOnly && isWrite) return readOnlyRefusal();
+
+  // ── chat ──────────────────────────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v2/chat') {
+    const validated = validateChatV2(params);
+    if ('error' in validated) return validated.error;
+    const args = validated.args;
+    // ONE engine advance, here, before anything branches on it.
+    const outcome = req.scenarioEngine ? scenarioDecision(args, req.scenarioEngine) : {};
+    if (outcome.error) return outcome.error;
+    if (args.stream) {
+      if (!req.sseSink) return invalidRequest('stream:true requires a streaming transport');
+      return { status: 200, body: streamChatV2(args, req.sseSink, outcome) };
+    }
+    return { status: 200, body: buildChatV2(args, outcome) };
+  }
+  if (method === 'POST' && path === '/v1/chat') return handleChatV1(params, req);
+
+  // ── embed / rerank / classify ─────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v2/embed') return handleEmbedV2(params);
+  if (method === 'POST' && path === '/v1/embed') return handleEmbedV1(params);
+  if (method === 'POST' && path === '/v2/rerank') return handleRerankV2(params);
+  if (method === 'POST' && path === '/v1/rerank') return handleRerankV1(params);
+  if (method === 'POST' && path === '/v1/classify') return handleClassify(params);
+
+  // ── tokenizer ─────────────────────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v1/tokenize') return handleTokenize(params, req);
+  if (method === 'POST' && path === '/v1/detokenize') return handleDetokenize(params, req);
+
+  // ── auth probe. A POST despite the name — `Client.js` sends `method: "POST"`. ──────────
+  if (method === 'POST' && path === '/v1/check-api-key') {
+    return { status: 200, body: { valid: true, organization_id: 'org_twin', owner_id: 'owner_twin' } };
+  }
+
+  // ── models ────────────────────────────────────────────────────────────────────────────
+  if (method === 'GET' && path === '/v1/models') {
+    const endpoint = query.get('endpoint');
+    let models = COHERE_MODELS;
+    if (endpoint) models = models.filter((m) => m.endpoints.includes(endpoint as never));
+    const pageSize = Number(query.get('page_size') ?? '0');
+    if (Number.isFinite(pageSize) && pageSize > 0) models = models.slice(0, pageSize);
+    return { status: 200, body: { models, next_page_token: null } };
+  }
+  if (method === 'GET' && seg[0] === 'v1' && seg[1] === 'models' && seg.length === 3) {
+    const name = decodeURIComponent(seg[2]!);
+    const card = findModel(name);
+    return card ? { status: 200, body: card } : modelNotFound(name);
+  }
+
+  // ── datasets ──────────────────────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v1/datasets') return createDataset(params, query, req);
+  if (method === 'GET' && path === '/v1/datasets') {
+    let items = rows('dataset', req.root);
+    const dt = query.get('datasetType');
+    if (dt) {
+      // The SAME closed set the create path enforces. Real Cohere serializes this parameter through
+      // `serializers.DatasetType` and 400s on a miss; answering `200 {datasets:[]}` would report an
+      // empty account for what is actually a rejected request (§9 round two, MINOR 9).
+      if (!DATASET_TYPES.has(dt)) return invalidRequest(`datasetType must be one of ${[...DATASET_TYPES].join(', ')}`);
+      items = items.filter((r) => r.dataset_type === dt);
+    }
+    const vs = query.get('validationStatus');
+    if (vs) {
+      if (!VALIDATION_STATUSES.has(vs)) return invalidRequest(`validationStatus must be one of ${[...VALIDATION_STATUSES].join(', ')}`);
+      items = items.filter((r) => r.validation_status === vs);
+    }
+    const limit = Number(query.get('limit') ?? '0');
+    const offset = Number(query.get('offset') ?? '0');
+    if (Number.isFinite(offset) && offset > 0) items = items.slice(offset);
+    if (Number.isFinite(limit) && limit > 0) items = items.slice(0, limit);
+    return { status: 200, body: { datasets: items.map(datasetView) } };
+  }
+  // `/usage` is a LITERAL sibling of `/{id}` and must be matched first, or a dataset could never
+  // be named `usage` and the usage endpoint would be shadowed by the id lookup.
+  if (method === 'GET' && path === '/v1/datasets/usage') {
+    const used = rows('dataset', req.root).reduce((a, r) => a + String(r._content ?? '').length, 0);
+    return { status: 200, body: { organization_usage: used } };
+  }
+  if (seg[0] === 'v1' && seg[1] === 'datasets' && seg.length === 3) {
+    const id = decodeURIComponent(seg[2]!);
+    const row = getRow('dataset', id, req.root);
+    if (method === 'GET') return row ? { status: 200, body: { dataset: datasetView(row) } } : notFound(`dataset '${id}' not found`);
+    if (method === 'DELETE') {
+      if (!row) return notFound(`dataset '${id}' not found`);
+      await write(req, 'dataset.delete', 'dataset', id, { _deleted: true });
+      // Cohere's delete answers an EMPTY object (`Record<string, unknown>` in the SDK), not the
+      // `{deleted:true}` envelope most vendors send.
+      return { status: 200, body: {} };
+    }
+  }
+
+  // ── connectors ────────────────────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v1/connectors') return createConnector(params, req);
+  if (method === 'GET' && path === '/v1/connectors') {
+    let items = rows('connector', req.root);
+    const total = items.length;
+    const offset = Number(query.get('offset') ?? '0');
+    const limit = Number(query.get('limit') ?? '0');
+    if (Number.isFinite(offset) && offset > 0) items = items.slice(offset);
+    if (Number.isFinite(limit) && limit > 0) items = items.slice(0, limit);
+    return { status: 200, body: { connectors: items.map(connectorView), total_count: total } };
+  }
+  if (seg[0] === 'v1' && seg[1] === 'connectors' && seg.length === 3) {
+    const id = decodeURIComponent(seg[2]!);
+    const row = getRow('connector', id, req.root);
+    if (method === 'GET') return row ? { status: 200, body: { connector: connectorView(row) } } : notFound(`connector '${id}' not found`);
+    if (method === 'PATCH') {
+      if (!row) return notFound(`connector '${id}' not found`);
+      const patch: Record<string, unknown> = { updated_at: nowIso(req.occurredAt), _rev: nextRev('connector', id, req.root) };
+      for (const k of ['name', 'url', 'excludes', 'active', 'continue_on_failure'] as const) {
+        if (params[k] !== undefined) patch[k] = params[k];
+      }
+      await write(req, 'connector.update', 'connector', id, patch);
+      return { status: 200, body: { connector: connectorView(getRow('connector', id, req.root)!) } };
+    }
+    if (method === 'DELETE') {
+      if (!row) return notFound(`connector '${id}' not found`);
+      await write(req, 'connector.delete', 'connector', id, { _deleted: true });
+      return { status: 200, body: {} };
+    }
+  }
+  if (method === 'POST' && seg[0] === 'v1' && seg[1] === 'connectors' && seg.length === 5 && seg[3] === 'oauth' && seg[4] === 'authorize') {
+    const id = decodeURIComponent(seg[2]!);
+    const row = getRow('connector', id, req.root);
+    if (!row) return notFound(`connector '${id}' not found`);
+    // A connector with no OAuth configuration has nothing to authorize. Answering a fabricated
+    // redirect URL would be a fake success on a path the vendor refuses.
+    if (row.auth_type !== 'oauth') return invalidRequest(`connector '${id}' is not configured for oauth`);
+    const oauth = row.oauth as { authorize_url?: string; client_id?: string } | null;
+    const after = query.get('after_token_redirect');
+    const u = new URL(String(oauth?.authorize_url || 'https://auth.example.test/authorize'));
+    u.searchParams.set('client_id', String(oauth?.client_id ?? ''));
+    u.searchParams.set('state', cohereId(`oauth|${id}`));
+    if (after) u.searchParams.set('after_token_redirect', after);
+    return { status: 200, body: { redirect_url: u.toString() } };
+  }
+
+  // ── embed jobs ────────────────────────────────────────────────────────────────────────
+  if (method === 'POST' && path === '/v1/embed-jobs') return createEmbedJob(params, req);
+  if (method === 'GET' && path === '/v1/embed-jobs') {
+    return { status: 200, body: { embed_jobs: rows('embed_job', req.root).map(embedJobView) } };
+  }
+  if (method === 'GET' && seg[0] === 'v1' && seg[1] === 'embed-jobs' && seg.length === 3) {
+    const id = decodeURIComponent(seg[2]!);
+    const row = getRow('embed_job', id, req.root);
+    return row ? { status: 200, body: embedJobView(row) } : notFound(`embed job '${id}' not found`);
+  }
+  if (method === 'POST' && seg[0] === 'v1' && seg[1] === 'embed-jobs' && seg.length === 4 && seg[3] === 'cancel') {
+    const id = decodeURIComponent(seg[2]!);
+    const row = getRow('embed_job', id, req.root);
+    if (!row) return notFound(`embed job '${id}' not found`);
+    // The vendor's state machine: only a job still in flight can be cancelled. A terminal job
+    // answers a 400 rather than pretending the cancel took.
+    if (row.status !== 'processing') return invalidRequest(`embed job '${id}' is ${String(row.status)} and cannot be cancelled`);
+    await write(req, 'embed_job.cancel', 'embed_job', id, { status: 'cancelling' });
+    // `embedJobs.cancel` is declared `-> void` in the SDK: an empty 200 body.
+    return { status: 200, body: {} };
+  }
+
+  return routeNotFound(method, path);
+}
+
+/** Re-exported so tests can assert the twin's closed sets against the vendor's without importing
+ *  the private constants by name. */
+export const COHERE_CLOSED_SETS = {
+  datasetTypes: [...DATASET_TYPES],
+  validationStatuses: [...VALIDATION_STATUSES],
+  embedJobStatuses: [...EMBED_JOB_STATUSES],
+  toolChoices: [...TOOL_CHOICES],
+  safetyModes: [...SAFETY_MODES],
+  v2Roles: [...V2_ROLES],
+} as const;
+
+/** Exported for the connector's shared FNV seed and for tests that need the twin's id derivation. */
+export { fnv1a };