@volter/twin-cohere 0.1.0

package/src/cohere-capabilities.ts

@@ -0,0 +1,1855 @@
+// Cohere capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored TOP-DOWN
+// from what the Cohere API actually does — NOT from what this twin has built. This is the honest
+// denominator: most entries start as `todo` and coverage reads LOW until the twin truly reaches
+// 100% of the API. `verify()` (required to count as done) is ground truth; `expected:'done'` only
+// on capabilities we genuinely claim, so a broken one shows as a regression.
+//
+// ── HOW THE DENOMINATOR WAS ENUMERATED (so it is not a self-portrait) ───────────────────
+// Every operation cohere-ai@8.1.0 can issue was extracted during this build, from the SDK's own
+// `reference.md` operation index cross-checked against the `core.url.join(..., "<path>")` literal
+// in each generated client. That is **45 SDK methods over 33 distinct HTTP endpoints**:
+//
+//   root client (11) : chat, chatStream, generate, generateStream, embed, rerank, classify,
+//                      summarize, tokenize, detokenize, checkApiKey
+//   v2 (5)           : chat, chatStream, parse, embed, rerank
+//   batches (4)      : list, create, retrieve, cancel
+//   connectors (6)   : list, create, get, delete, update, oAuthAuthorize
+//   datasets (5)     : list, create, getUsage, get, delete
+//   embedJobs (4)    : list, create, get, cancel
+//   finetuning (7)   : listFinetunedModels, createFinetunedModel, getFinetunedModel,
+//                      deleteFinetunedModel, updateFinetunedModel, listEvents,
+//                      listTrainingStepMetrics
+//   models (2)       : get, list
+//   audio (1)        : transcriptions.create
+//
+// The twin serves 27 of those 33 endpoints. The six it does NOT serve (`/v1/generate` ×2,
+// `/v1/summarize`, `/v2/parse`, `/v2/audio/transcriptions`, and the seven finetuning paths, plus
+// the four batches paths) are enumerated below as `todo` — they are REAL Cohere surface, and a
+// denominator that omitted them would be a self-portrait. So are the deployment planes the SDK
+// also ships clients for (`AwsClient` / `BedrockClient` / `SagemakerClient`), which are Cohere
+// models served through AWS rather than through api.cohere.com.
+//
+// ── THERE ARE NO CARVE-OUTS ─────────────────────────────────────────────────────────────
+// The twin returns DETERMINISTIC STUBS for model generation, pseudo-vectors for embeddings, a
+// lexical-overlap score for rerank and a hash heuristic for classify — and those ARE the twin's
+// answer, not a shortfall from a "real" one. The protocol envelope (shapes, streaming, tool calls,
+// UPPER-CASE finish reasons, two-level usage) is faithful. Every entry here is done or todo.
+//
+// The tokenizer is a TODO: Cohere's tokenizers are published, downloadable, static JSON artifacts,
+// and this pack already SERVES their URLs from the model catalog, so vendoring one is fully offline
+// and fully deterministic (`cohere.tokenize.bpe_vocabulary`).
+//
+// (Cohere is an API-first vendor: its dashboard is incidental tooling for keys, billing and usage,
+// not where the work happens — docs/contributing/architecture.md C1b — so this pack ships no mirror, and there are
+// no UI capabilities to verify.)
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { projectResources } from '@volter/world-core';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary, isInfrastructureError, harnessError } from '@volter/world-tooling';
+import { CohereBudget, CohereBudgetError, cohereCallWeight } from './cohere-budget.ts';
+import { checkCohereConformance } from './cohere-conformance.ts';
+import {
+  cohereRequestForAction,
+  fullSyncCohere,
+  liveCohereExecute,
+  mapConnector,
+  mapDataset,
+  mapEmbedJob,
+  pollTimestamp,
+  pushPendingCohereActions,
+  syncCohereFromReal,
+  unpushableReason,
+  type CohereExecute,
+} from './cohere-connector.ts';
+import { COHERE_MODELS, COHERE_ENDPOINTS } from './cohere-models.ts';
+import { createCohereScenarioEngine } from './cohere-scenario.ts';
+import { handleCohereTwinRequest, type CohereResponseEnvelope } from './cohere-twin.ts';
+import type { SseEvent } from './cohere-types.ts';
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
+type Step = { m: string; p: string; b?: unknown; h?: Record<string, string>; ro?: boolean };
+type Body = Record<string, any>;
+
+/** A FIXED `occurredAt` keeps ids/timestamps deterministic across runs. */
+const PINNED_AT = '2026-08-31T12:00:00.000Z';
+
+/** Run a sequence of real Cohere requests against an ISOLATED root; return all responses. The
+ *  root is threaded EVERYWHERE — an omitted root silently falls back to the operator's real
+ *  `~/.volter` state dir, which is gitignored, so the verify would pass while poisoning later
+ *  runs. */
+async function withRoot(steps: (h: (s: Step) => Promise<CohereResponseEnvelope>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'cohere-cap-'));
+  const h = (s: Step) => handleCohereTwinRequest({
+    method: s.m, path: s.p, root, occurredAt: PINNED_AT,
+    ...(s.b === undefined ? {} : { body: JSON.stringify(s.b) }),
+    ...(s.h ? { headers: s.h } : {}),
+    ...(s.ro ? { readOnly: true } : {}),
+  });
+  try {
+    return await verifyBoundary('cohere.withRoot', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Collect the streaming events for a request against an isolated root. */
+function withStream(path: string, body: unknown, fn: (events: SseEvent[], final: CohereResponseEnvelope) => boolean): Promise<boolean> {
+  return new Promise<boolean>((resolve, reject) => {
+    const root = mkdtempSync(join(tmpdir(), 'cohere-cap-'));
+    const events: SseEvent[] = [];
+    handleCohereTwinRequest({ method: 'POST', path, body: JSON.stringify(body), root, occurredAt: PINNED_AT, sseSink: (e) => events.push(e) })
+      .then((final) => resolve(fn(events, final)))
+      .catch((err) => { if (isInfrastructureError(err)) reject(harnessError('cohere.withStream', err)); else resolve(false); })
+      .finally(() => rmSync(root, { recursive: true, force: true }));
+  });
+}
+
+/** A connector verify against a recording fake executor + an isolated root. */
+async function withConnector(
+  fn: (execute: CohereExecute, calls: Array<{ method: string; path: string; body?: Record<string, unknown> }>, root: string) => Promise<boolean>,
+  reply?: (method: string, path: string) => unknown,
+): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'cohere-conn-'));
+  const calls: Array<{ method: string; path: string; body?: Record<string, unknown> }> = [];
+  const execute: CohereExecute = async (method, path, body) => {
+    calls.push({ method, path, ...(body ? { body } : {}) });
+    return reply ? reply(method, path) : defaultVendorReply(method, path);
+  };
+  try {
+    return await verifyBoundary('cohere.withConnector', () => fn(execute, calls, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// REAL-SHAPED vendor rows. A connector verify green over an input the vendor could not emit has
+// proven fidelity against a client that does not exist, so these carry the FULL field set each
+// mapper reads — every key the vendor's own schema declares required, not the subset a lax `?? null`
+// default would paper over.
+const REAL_DATASET = { id: 'ds-real-1', name: 'real-dataset', created_at: '2026-08-01T00:00:00Z', updated_at: '2026-08-02T00:00:00Z', dataset_type: 'embed-input', validation_status: 'validated', validation_error: null, validation_warnings: [], required_fields: ['text'], preserve_fields: [], dataset_parts: [], schema: null };
+const REAL_CONNECTOR = { id: 'conn-real-1', organization_id: 'org-real', name: 'real-connector', description: 'the real one', url: 'https://real.test/search', created_at: '2026-08-01T00:00:00Z', updated_at: '2026-08-03T00:00:00Z', excludes: ['secret'], auth_type: 'oauth', oauth: { client_id: 'cid', authorize_url: 'https://a.test', token_url: 'https://t.test', scope: null }, auth_status: 'valid', active: true, continue_on_failure: false };
+const REAL_EMBED_JOB = { job_id: 'job-real-1', name: 'real-job', status: 'processing', created_at: '2026-08-04T00:00:00Z', input_dataset_id: 'ds-real-1', output_dataset_id: null, model: 'embed-english-v3.0', truncate: 'END', meta: null };
+
+/**
+ * The fake vendor's reply, keyed on METHOD **and** path.
+ *
+ * The method half is load-bearing: a path-only fake would answer `POST /v1/connectors` with the
+ * LIST envelope, so `pushCohereAction`'s id extraction would never once be exercised against a
+ * realistic create response and would silently fall back to the local subject id on every run —
+ * which is precisely the bug the duplicate-on-pull finding turns on. A LIST answers the collection;
+ * a CREATE answers the vendor's own (per-type, NON-uniform) create envelope.
+ */
+function defaultVendorReply(method: string, path: string): unknown {
+  const bare = path.split('?')[0]!;
+  if (method === 'GET') {
+    if (bare === '/v1/datasets') return { datasets: [REAL_DATASET] };
+    if (bare === '/v1/connectors') return { connectors: [REAL_CONNECTOR], total_count: 1 };
+    if (bare === '/v1/embed-jobs') return { embed_jobs: [REAL_EMBED_JOB] };
+    return {};
+  }
+  if (method === 'POST') {
+    // Three DIFFERENT create envelopes, exactly as the vendor's schemas declare them.
+    if (bare === '/v1/connectors') return { connector: { ...REAL_CONNECTOR, id: 'conn-vendor-minted' } };
+    if (bare === '/v1/embed-jobs') return { job_id: 'job-vendor-minted', meta: null };
+    if (bare === '/v1/datasets') return { id: 'ds-vendor-minted' };
+    if (bare.endsWith('/cancel')) return {};
+    return {};
+  }
+  if (method === 'PATCH') return { connector: { ...REAL_CONNECTOR, name: 'patched' } };
+  if (method === 'DELETE') return {};
+  return {};
+}
+
+const ok = (r: CohereResponseEnvelope) => r.status >= 200 && r.status < 300;
+const field = (r: CohereResponseEnvelope, k: string) => (r.body as Body)?.[k];
+const message = (r: CohereResponseEnvelope) => String((r.body as Body)?.message ?? '');
+/** Cohere's error envelope has EXACTLY one key. Asserting the count is what catches a drift toward
+ *  the OpenAI `{error:{...}}` shape, which no positive assertion on `message` would notice. */
+const bareError = (r: CohereResponseEnvelope, status: number) =>
+  r.status === status && !!r.body && typeof r.body === 'object' && Object.keys(r.body as object).join(',') === 'message';
+
+// ── shorthands (mirror the anthropic/mistral manifests) ──
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+/** The multipart `data` part every dataset create must carry — `datasets.create` in cohere-ai
+ *  unconditionally appends it, so the vendor never sees a fileless create (§9 round 1, finding 6). */
+const DATA_FILE = { content: '{"text":"a"}' };
+
+const CHAT = (extra: Record<string, unknown> = {}) => ({ model: 'command-a-03-2025', messages: [{ role: 'user', content: 'hello twin' }], ...extra });
+const TOOL = { type: 'function', function: { name: 'get_weather', description: 'w', parameters: { type: 'object', properties: { city: { type: 'string' }, days: { type: 'integer' } } } } };
+
+/**
+ * THE AREAS CENSUS (TWIN-87). Enumerated TOP-DOWN from cohere-ai@8.1.0's own client surface — the
+ * root client's method groups plus every sub-client directory under `api/resources/`
+ * (v2, batches, connectors, datasets, embedJobs, finetuning, models, audio) and the three
+ * deployment clients the package also ships (`AwsClient`, `BedrockClient`, `SagemakerClient`) —
+ * NOT from this manifest's own `area` values, which would make the bijection a tautology.
+ *
+ * `connectors` is Cohere's PRODUCT (its RAG connector registry); `connector` is this twin's
+ * pull/push plane. Two different things that unfortunately share a word; both are real areas.
+ */
+export const COHERE_AREAS = [
+  'audio',
+  'auth',
+  'batches',
+  'chat',
+  'chat_v1',
+  'classify',
+  'conformance',
+  'connector',
+  'connectors',
+  'datasets',
+  'deployments',
+  'determinism',
+  'embed',
+  'embed_jobs',
+  'errors',
+  'finetuning',
+  'generate',
+  'models',
+  'parse',
+  'rerank',
+  'summarize',
+  'tokenize',
+] as const;
+
+export const COHERE_CAPABILITIES: CapabilitySpec[] = [
+  // ══ THE HONEST CARVE-OUTS ═════════════════════════════════════════════════════════════
+  todo('cohere.tokenize.bpe_vocabulary', 'tokenize', "Tokenize with Cohere's REAL published BPE vocabulary (vendored tokenizer JSON), not a learned word-segment map", 'api', 'common'),
+  todo('cohere.deployments.aws_planes', 'deployments', 'Serve the Bedrock and SageMaker planes the cohere-ai SDK also targets (BedrockClient/SagemakerClient/AwsClient, SigV4-signed against AWS hosts), so a regionally-deployed client reaches the twin instead of failing closed', 'api', 'niche'),
+
+  // ══ CHAT v2 — the protocol envelope, faithful ═════════════════════════════════════════
+  done('cohere.chat.create', 'chat', 'v2 chat: the faithful envelope (id/finish_reason/message/usage, and NO `choices`)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      // The three keys an OpenAI-shaped copy would add, asserted ABSENT. A positive assertion on
+      // `message` alone would not notice a `choices` array riding alongside it.
+      if (b.choices !== undefined || b.object !== undefined || b.created !== undefined) return false;
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(String(b.id))) return false;
+      if (b.finish_reason !== 'COMPLETE' || b.message?.role !== 'assistant') return false;
+      if (b.message?.content?.[0]?.type !== 'text') return false;
+      return typeof b.message.content[0].text === 'string' && b.message.content[0].text.includes('hello twin');
+    }),
+  ),
+  done('cohere.chat.stub_labeled', 'chat', 'v2 chat: the stub is clearly labeled as a twin stub (not real output)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
+      const text = (r.body as Body).message?.content?.[0]?.text as string;
+      return ok(r) && text.includes('[twin-stub:command-a-03-2025]') && text.includes('no model weights are run');
+    }),
+  ),
+  done('cohere.chat.usage_two_levels', 'chat', 'v2 chat: usage carries BOTH `billed_units` and `tokens` sub-objects', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const short = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
+      const long = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ messages: [{ role: 'user', content: 'x'.repeat(400) }] }) });
+      const a = (short.body as Body).usage;
+      const c = (long.body as Body).usage;
+      // @ai-sdk/cohere's `cohereUsageSchema` marks `billed_units` nullish but `tokens` REQUIRED,
+      // and `convertCohereUsage` reads `usage.tokens.*` — a flat OpenAI-shaped usage dies there.
+      if (typeof a?.billed_units?.input_tokens !== 'number' || typeof a?.tokens?.input_tokens !== 'number') return false;
+      if (typeof a?.billed_units?.output_tokens !== 'number' || typeof a?.tokens?.output_tokens !== 'number') return false;
+      // The count MOVES with the input — a hardcoded constant would satisfy the shape checks above.
+      return c.tokens.input_tokens > a.tokens.input_tokens * 5;
+    }),
+  ),
+  done('cohere.chat.tool_calls', 'chat', 'v2 chat: tools → `tool_calls` + `tool_plan` + finish_reason TOOL_CALL', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL] }) });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (b.finish_reason !== 'TOOL_CALL') return false;
+      if (typeof b.message?.tool_plan !== 'string' || !b.message.tool_plan.includes('get_weather')) return false;
+      const call = b.message?.tool_calls?.[0];
+      if (call?.type !== 'function' || call?.function?.name !== 'get_weather') return false;
+      // `arguments` is a STRING on the wire, and it parses to the tool's declared schema shape.
+      const args = JSON.parse(call.function.arguments);
+      if (args.city !== '' || args.days !== 0) return false;
+      // A tool turn carries NO `content` — Cohere omits the empty half rather than sending null.
+      return b.message.content === undefined;
+    }),
+  ),
+  done('cohere.chat.tool_choice_none', 'chat', 'v2 chat: `tool_choice: NONE` forbids a tool call even with tools declared', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const forced = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL] }) });
+      const none = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], tool_choice: 'NONE' }) });
+      // Both halves: the tool DOES fire without the flag, and does NOT with it. Asserting only the
+      // second would pass on a twin that never made tool calls at all.
+      return (forced.body as Body).finish_reason === 'TOOL_CALL'
+        && (none.body as Body).finish_reason === 'COMPLETE'
+        && (none.body as Body).message?.tool_calls === undefined
+        && typeof (none.body as Body).message?.content?.[0]?.text === 'string';
+    }),
+  ),
+  done('cohere.chat.thinking', 'chat', 'v2 chat: `thinking: {type:enabled}` prepends a `thinking` content item', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const off = await h({ m: 'POST', p: '/v2/chat', b: CHAT() });
+      const on = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ thinking: { type: 'enabled' } }) });
+      const offTypes = ((off.body as Body).message?.content ?? []).map((c: Body) => c.type);
+      const onTypes = ((on.body as Body).message?.content ?? []).map((c: Body) => c.type);
+      return JSON.stringify(offTypes) === '["text"]' && JSON.stringify(onTypes) === '["thinking","text"]';
+    }),
+  ),
+  done('cohere.chat.stream_events', 'chat', 'v2 chat streaming: the vendor event sequence, terminated by [DONE]', 'api', 'core', () =>
+    withStream('/v2/chat', CHAT({ stream: true }), (events, final) => {
+      const types = events.filter((e) => !e.done).map((e) => String(e.data!.type));
+      if (types[0] !== 'message-start') return false;
+      if (!types.includes('content-start') || !types.includes('content-delta') || !types.includes('content-end')) return false;
+      if (types[types.length - 1] !== 'message-end') return false;
+      // The `[DONE]` terminator cohere-ai's `core.Stream` is constructed to look for.
+      if (events[events.length - 1]?.done !== true) return false;
+      // `content-start` carries a full content BLOCK; `content-delta` carries just `{text}`. The
+      // two shapes DIFFER, and @ai-sdk/cohere's discriminated union rejects a mix-up.
+      const start = events.find((e) => e.data?.type === 'content-start')!.data as Body;
+      if (start.delta?.message?.content?.type !== 'text' || start.delta.message.content.text !== '') return false;
+      const delta = events.find((e) => e.data?.type === 'content-delta')!.data as Body;
+      if (delta.delta?.message?.content?.type !== undefined) return false;
+      // The reassembled deltas equal the unary answer — the chunking is a SPLIT, not a second
+      // generation, which is the property a streaming caller actually relies on.
+      const joined = events.filter((e) => e.data?.type === 'content-delta').map((e) => (e.data as Body).delta.message.content.text).join('');
+      return joined === (final.body as Body).message.content[0].text;
+    }),
+  ),
+  done('cohere.chat.stream_message_end', 'chat', 'v2 chat streaming: `message-end` carries finish_reason + the full usage', 'api', 'core', () =>
+    withStream('/v2/chat', CHAT({ stream: true }), (events, final) => {
+      const end = events.find((e) => e.data?.type === 'message-end')?.data as Body | undefined;
+      if (!end) return false;
+      return end.delta?.finish_reason === 'COMPLETE'
+        && end.delta?.usage?.tokens?.output_tokens === (final.body as Body).usage.tokens.output_tokens
+        && end.id === (final.body as Body).id;
+    }),
+  ),
+  done('cohere.chat.stream_tool_calls', 'chat', 'v2 chat streaming: tool-plan/tool-call event triple reassembles the call', 'api', 'common', () =>
+    withStream('/v2/chat', CHAT({ stream: true, tools: [TOOL] }), (events, final) => {
+      const types = events.filter((e) => !e.done).map((e) => String(e.data!.type));
+      if (!types.includes('tool-plan-delta') || !types.includes('tool-call-start') || !types.includes('tool-call-delta') || !types.includes('tool-call-end')) return false;
+      const start = events.find((e) => e.data?.type === 'tool-call-start')!.data as Body;
+      // The START frame carries the id and name with EMPTY arguments; the deltas carry the
+      // argument string in pieces, which the caller accumulates.
+      if (start.delta?.message?.tool_calls?.function?.name !== 'get_weather') return false;
+      if (start.delta.message.tool_calls.function.arguments !== '') return false;
+      const args = events.filter((e) => e.data?.type === 'tool-call-delta')
+        .map((e) => (e.data as Body).delta.message.tool_calls.function.arguments).join('');
+      if (args !== (final.body as Body).message.tool_calls[0].function.arguments) return false;
+      const end = events.find((e) => e.data?.type === 'message-end')!.data as Body;
+      return end.delta.finish_reason === 'TOOL_CALL';
+    }),
+  ),
+  done('cohere.chat.stream_needs_transport', 'chat', 'v2 chat: `stream:true` with no streaming transport is refused, not silently unary', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ stream: true }) });
+      return bareError(r, 400) && message(r).includes('streaming transport');
+    }),
+  ),
+  done('cohere.chat.validation_model', 'chat', 'v2 chat: missing model → the bare `{message}` 400', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/chat', b: { messages: [{ role: 'user', content: 'x' }] } });
+      return bareError(r, 400) && message(r) === 'invalid request: model is required';
+    }),
+  ),
+  done('cohere.chat.validation_messages', 'chat', 'v2 chat: missing / empty / bad-role messages each 400 with their own message', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const missing = await h({ m: 'POST', p: '/v2/chat', b: { model: 'command-a-03-2025' } });
+      const empty = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ messages: [] }) });
+      const badRole = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ messages: [{ role: 'developer', content: 'x' }] }) });
+      return bareError(missing, 400) && message(missing) === 'invalid request: messages is required'
+        && bareError(empty, 400) && message(empty) === 'invalid request: messages must not be empty'
+        && bareError(badRole, 400) && message(badRole).includes('messages[0].role must be one of');
+    }),
+  ),
+  done('cohere.chat.model_not_found', 'chat', 'v2 chat: unknown model AND wrong-endpoint model both 404 like the vendor', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const unknown = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ model: 'gpt-4o' }) });
+      // The sharper case: a REAL Cohere model that serves a different endpoint. An OpenAI-shaped
+      // twin would happily generate from it.
+      const wrongEndpoint = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ model: 'embed-v4.0' }) });
+      return bareError(unknown, 404) && message(unknown) === "model 'gpt-4o' not found, make sure the correct model ID was used and that you have access to the model."
+        && bareError(wrongEndpoint, 404) && message(wrongEndpoint).includes("model 'embed-v4.0' not found");
+    }),
+  ),
+  done('cohere.chat.closed_enums', 'chat', 'v2 chat: `tool_choice` and `safety_mode` are the vendor\'s CLOSED UPPER-CASE sets', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // The documented sets are literals here, never imported from the handler — an imported
+      // constant could not catch the set drifting.
+      for (const v of ['REQUIRED', 'NONE']) {
+        if (!ok(await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], tool_choice: v }) }))) return false;
+      }
+      for (const v of ['CONTEXTUAL', 'STRICT', 'OFF']) {
+        if (!ok(await h({ m: 'POST', p: '/v2/chat', b: CHAT({ safety_mode: v }) }))) return false;
+      }
+      // …and a value OUTSIDE each set is refused. Cohere's enums are UPPER-CASE, so the
+      // lower-case spelling most vendors use is exactly the wrong-looking-plausible input.
+      const lowerChoice = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL], tool_choice: 'none' }) });
+      const badMode = await h({ m: 'POST', p: '/v2/chat', b: CHAT({ safety_mode: 'contextual' }) });
+      return bareError(lowerChoice, 400) && bareError(badMode, 400);
+    }),
+  ),
+  todo('cohere.chat.citations', 'chat', 'v2 chat: `documents` + citation_options → grounded citations on the response', 'api', 'core'),
+  todo('cohere.chat.response_format_json', 'chat', 'v2 chat: `response_format` json_object / json_schema constrained output', 'api', 'core'),
+  todo('cohere.chat.logprobs', 'chat', 'v2 chat: `logprobs: true` → the LogprobItem array on the response', 'api', 'niche'),
+  todo('cohere.chat.strict_tools', 'chat', 'v2 chat: `strict_tools` schema-constrained tool arguments', 'api', 'niche'),
+  todo('cohere.chat.stop_sequences', 'chat', 'v2 chat: `stop_sequences` → finish_reason STOP_SEQUENCE', 'api', 'core'),
+  todo('cohere.chat.max_tokens_truncation', 'chat', 'v2 chat: `max_tokens` truncation → finish_reason MAX_TOKENS', 'api', 'core'),
+  todo('cohere.chat.image_content', 'chat', 'v2 chat: image content parts for the vision models (command-a-vision)', 'api', 'common'),
+  todo('cohere.chat.priority', 'chat', 'v2 chat: the `priority` request parameter', 'api', 'niche'),
+
+  // ══ CHAT v1 — a DIFFERENT protocol, not a versioned alias ═════════════════════════════
+  done('cohere.chat_v1.create', 'chat_v1', 'v1 chat: flat `text` + chat_history + meta (NOT the v2 envelope)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat', b: { message: 'v1 hello', model: 'command-r-08-2024' } });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      // v1 has NO `message` object and NO `usage`; it has `text` and `meta`. A twin that served
+      // one envelope for both versions would fail exactly here.
+      if (b.message !== undefined || b.usage !== undefined) return false;
+      if (typeof b.text !== 'string' || !b.text.includes('[twin-stub:command-r-08-2024]') || !b.text.includes('v1 hello')) return false;
+      if (b.finish_reason !== 'COMPLETE') return false;
+      return b.meta?.api_version?.version === '1' && b.meta?.billed_units?.input_tokens > 0;
+    }),
+  ),
+  done('cohere.chat_v1.chat_history', 'chat_v1', 'v1 chat: the reply appends USER + CHATBOT turns onto the supplied history', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat', b: { message: 'second', chat_history: [{ role: 'USER', message: 'first' }, { role: 'CHATBOT', message: 'reply' }] } });
+      const hist = (r.body as Body).chat_history as Body[];
+      return ok(r) && hist.length === 4
+        && hist[0]!.message === 'first' && hist[1]!.message === 'reply'
+        && hist[2]!.role === 'USER' && hist[2]!.message === 'second'
+        && hist[3]!.role === 'CHATBOT' && String(hist[3]!.message).includes('[twin-stub:');
+    }),
+  ),
+  done('cohere.chat_v1.validation_message', 'chat_v1', "v1 chat: a v2-shaped `messages` array is refused — v1 requires `message`", 'api', 'core', () =>
+    withRoot(async (h) => {
+      const v2shaped = await h({ m: 'POST', p: '/v1/chat', b: { messages: [{ role: 'user', content: 'x' }], model: 'command-r-08-2024' } });
+      const empty = await h({ m: 'POST', p: '/v1/chat', b: { message: '' } });
+      return bareError(v2shaped, 400) && message(v2shaped) === 'invalid request: message is required'
+        && bareError(empty, 400);
+    }),
+  ),
+  done('cohere.chat_v1.stream_ndjson', 'chat_v1', 'v1 chat streaming: NDJSON `event_type` frames, a DIFFERENT wire from v2 SSE', 'api', 'common', () =>
+    withStream('/v1/chat', { message: 'stream v1', stream: true }, (events, final) => {
+      const kinds = events.filter((e) => !e.done).map((e) => String(e.data!.event_type));
+      if (kinds[0] !== 'stream-start' || kinds[kinds.length - 1] !== 'stream-end') return false;
+      if (!kinds.includes('text-generation')) return false;
+      // v1's frames are tagged `event_type`, NOT v2's `type` — the discriminator differs.
+      if (events.some((e) => !e.done && e.data!.type !== undefined)) return false;
+      const first = events[0]!.data as Body;
+      if (first.is_finished !== false) return false;
+      const end = events[events.length - 1]!.data as Body;
+      if (end.is_finished !== true || end.finish_reason !== 'COMPLETE') return false;
+      const joined = events.filter((e) => e.data?.event_type === 'text-generation').map((e) => (e.data as Body).text).join('');
+      return joined === (final.body as Body).text && end.response.text === (final.body as Body).text;
+    }),
+  ),
+  todo('cohere.chat_v1.connectors', 'chat_v1', 'v1 chat: `connectors` RAG retrieval → search_queries / search_results / documents', 'api', 'common'),
+  todo('cohere.chat_v1.tool_results', 'chat_v1', 'v1 chat: `tools` + `tool_results` multi-step tool loop', 'api', 'common'),
+  todo('cohere.chat_v1.citations', 'chat_v1', 'v1 chat: `documents` + citation_quality → the ChatCitation array', 'api', 'common'),
+  todo('cohere.chat_v1.prompt_truncation', 'chat_v1', 'v1 chat: `prompt_truncation` AUTO/OFF over an oversized history', 'api', 'niche'),
+  todo('cohere.chat_v1.conversation_id', 'chat_v1', 'v1 chat: server-side `conversation_id` history persistence', 'api', 'niche'),
+
+  // ══ EMBED ═════════════════════════════════════════════════════════════════════════════
+  done('cohere.embed.v2_by_type', 'embed', 'v2 embed: vectors keyed BY TYPE, every requested type present and agreeing', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', texts: ['alpha', 'beta'], embedding_types: ['float', 'int8', 'uint8', 'binary', 'ubinary', 'base64'], output_dimension: 256 } });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (b.response_type !== 'embeddings_by_type') return false;
+      const e = b.embeddings;
+      if (e.float?.length !== 2 || e.float[0].length !== 256) return false;
+      if (e.int8?.[0]?.length !== 256 || e.uint8?.[0]?.length !== 256) return false;
+      // binary packs ONE BIT per dimension, 8 to a byte — so its array is dim/8 long, not dim.
+      if (e.binary?.[0]?.length !== 32 || e.ubinary?.[0]?.length !== 32) return false;
+      if (typeof e.base64?.[0] !== 'string') return false;
+      // binary vs ubinary is a SIGNEDNESS difference over the same packed bytes, and it is the only
+      // property separating them. Without this the signing branch could be deleted and every verify
+      // would stay green (§9 round two, MINOR 8).
+      const bin = e.binary[0] as number[];
+      const ubin = e.ubinary[0] as number[];
+      for (let i = 0; i < bin.length; i++) {
+        if (((bin[i]! + 256) % 256) !== ubin[i]!) return false;   // same bits
+        if (ubin[i]! < 0 || ubin[i]! > 255) return false;          // unsigned range
+        if (bin[i]! < -128 || bin[i]! > 127) return false;         // signed range
+      }
+      // …and the two really do DIFFER somewhere, or "signed" would be vacuous over this input.
+      if (!bin.some((v, i) => v !== ubin[i])) return false;
+      // Every type is a view of the SAME vector, not an independently generated one.
+      if (e.int8[0][0] !== Math.max(-128, Math.min(127, Math.round(e.float[0][0] * 127)))) return false;
+      if (e.uint8[0][0] !== Math.max(0, Math.min(255, Math.round((e.float[0][0] + 1) * 127.5)))) return false;
+      // Distinct inputs give distinct vectors — otherwise "deterministic per input" is vacuous.
+      return JSON.stringify(e.float[0]) !== JSON.stringify(e.float[1]) && JSON.stringify(b.texts) === '["alpha","beta"]';
+    }),
+  ),
+  done('cohere.embed.v1_floats_default', 'embed', 'v1 embed: the DEFAULT answer is the FLAT float shape, not the by-type one', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const flat = await h({ m: 'POST', p: '/v1/embed', b: { model: 'embed-english-v3.0', input_type: 'search_query', texts: ['gamma'] } });
+      const byType = await h({ m: 'POST', p: '/v1/embed', b: { model: 'embed-english-v3.0', input_type: 'search_query', texts: ['gamma'], embedding_types: ['float'] } });
+      const fb = flat.body as Body;
+      const tb = byType.body as Body;
+      // cohere-ai models `EmbedResponse` as a union discriminated on `response_type`; always
+      // answering by-type would land every default v1 caller in the wrong union arm.
+      if (fb.response_type !== 'embeddings_floats' || !Array.isArray(fb.embeddings) || !Array.isArray(fb.embeddings[0])) return false;
+      if (fb.embeddings[0].length !== 1024) return false;
+      if (tb.response_type !== 'embeddings_by_type' || !Array.isArray(tb.embeddings?.float)) return false;
+      // The two shapes carry the SAME vector — asking for a type changes the packaging only.
+      return JSON.stringify(tb.embeddings.float[0]) === JSON.stringify(fb.embeddings[0]);
+    }),
+  ),
+  done('cohere.embed.v2_requires_input_type', 'embed', 'v2 embed REQUIRES `input_type`; v1 does not — the sharpest version difference', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const v2Missing = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', texts: ['x'] } });
+      const v2Present = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', texts: ['x'] } });
+      // v1 with a LEGACY-shaped call still needs one for a v3 model — that refusal lives in the
+      // handler, not the schema, which is why both halves are asserted here.
+      const v1MissingV3 = await h({ m: 'POST', p: '/v1/embed', b: { model: 'embed-english-v3.0', texts: ['x'] } });
+      return bareError(v2Missing, 400) && message(v2Missing) === 'invalid request: input_type is required'
+        && ok(v2Present)
+        && bareError(v1MissingV3, 400) && message(v1MissingV3).includes("input_type is required for model 'embed-english-v3.0'");
+    }),
+  ),
+  done('cohere.embed.closed_enums', 'embed', 'embed: embedding_types / input_type / truncate / output_dimension are closed sets', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const base = { model: 'embed-v4.0', input_type: 'search_query', texts: ['x'] };
+      // The documented sets, as LITERALS. Each accepted value is exercised, and one value outside
+      // each set is refused — a bijection with the vendor's documented set, not a spot check.
+      for (const t of ['float', 'int8', 'uint8', 'binary', 'ubinary', 'base64']) {
+        if (!ok(await h({ m: 'POST', p: '/v2/embed', b: { ...base, embedding_types: [t] } }))) return false;
+      }
+      for (const it of ['search_document', 'search_query', 'classification', 'clustering', 'image']) {
+        if (!ok(await h({ m: 'POST', p: '/v2/embed', b: { ...base, input_type: it } }))) return false;
+      }
+      for (const tr of ['NONE', 'START', 'END']) {
+        if (!ok(await h({ m: 'POST', p: '/v2/embed', b: { ...base, truncate: tr } }))) return false;
+      }
+      for (const d of [256, 512, 1024, 1536]) {
+        if (!ok(await h({ m: 'POST', p: '/v2/embed', b: { ...base, output_dimension: d } }))) return false;
+      }
+      const badType = await h({ m: 'POST', p: '/v2/embed', b: { ...base, embedding_types: ['float16'] } });
+      const badInput = await h({ m: 'POST', p: '/v2/embed', b: { ...base, input_type: 'search' } });
+      const badTrunc = await h({ m: 'POST', p: '/v2/embed', b: { ...base, truncate: 'end' } });
+      const badDim = await h({ m: 'POST', p: '/v2/embed', b: { ...base, output_dimension: 999 } });
+      return bareError(badType, 400) && bareError(badInput, 400) && bareError(badTrunc, 400) && bareError(badDim, 400)
+        && message(badDim) === 'invalid request: output_dimension must be one of 256, 512, 1024, 1536';
+    }),
+  ),
+  done('cohere.embed.dimensions_by_model', 'embed', 'embed: each model produces its own documented dimensionality', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const dim = async (model: string) => {
+        const r = await h({ m: 'POST', p: '/v1/embed', b: { model, input_type: 'search_query', texts: ['x'] } });
+        return ok(r) ? ((r.body as Body).embeddings[0] as number[]).length : -1;
+      };
+      // The `light` models are 384-dimensional, the full v3 models 1024, embed-v4.0 1536.
+      return await dim('embed-english-v3.0') === 1024
+        && await dim('embed-english-light-v3.0') === 384
+        && await dim('embed-multilingual-light-v3.0') === 384
+        && await dim('embed-v4.0') === 1536;
+    }),
+  ),
+  done('cohere.embed.normalized', 'embed', 'embed: the pseudo-vectors are L2-normalized, like real embeddings', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', texts: ['norm me'] } });
+      const v = (r.body as Body).embeddings.float[0] as number[];
+      const norm = Math.sqrt(v.reduce((a, x) => a + x * x, 0));
+      return ok(r) && Math.abs(norm - 1) < 1e-9;
+    }),
+  ),
+  done('cohere.embed.validation_inputs', 'embed', 'embed: no texts/images/inputs → 400; wrong-endpoint model → 404', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const none = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query' } });
+      const chatModel = await h({ m: 'POST', p: '/v2/embed', b: { model: 'command-a-03-2025', input_type: 'search_query', texts: ['x'] } });
+      return bareError(none, 400) && message(none).includes('one of texts, images or inputs')
+        && bareError(chatModel, 404);
+    }),
+  ),
+  done('cohere.embed.v2_inputs_form', 'embed', 'v2 embed: the structured `inputs` form (content parts), not just `texts`', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const viaInputs = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', inputs: [{ content: [{ type: 'text', text: 'structured' }] }] } });
+      const viaTexts = await h({ m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', texts: ['structured'] } });
+      // The two spellings of the same input produce the SAME vector — proof `inputs` is really
+      // flattened rather than hashed as a JSON blob.
+      return ok(viaInputs)
+        && JSON.stringify((viaInputs.body as Body).embeddings.float[0]) === JSON.stringify((viaTexts.body as Body).embeddings.float[0]);
+    }),
+  ),
+  todo('cohere.embed.images', 'embed', 'embed: real image inputs (base64 data URIs) with image_tokens billing', 'api', 'common'),
+  todo('cohere.embed.max_tokens', 'embed', 'v2 embed: the `max_tokens` per-input cap and its truncation semantics', 'api', 'niche'),
+  todo('cohere.embed.token_limit_refusal', 'embed', 'embed: refuse an input past the model context length when truncate=NONE', 'api', 'core'),
+
+  // ══ RERANK ════════════════════════════════════════════════════════════════════════════
+  done('cohere.rerank.v2_order', 'rerank', 'v2 rerank: results ordered by descending relevance, scores in [0,1]', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'apple pie recipe', documents: ['how to service a car engine', 'a recipe for apple pie', 'apple orchard tours'] } });
+      if (!ok(r)) return false;
+      const results = (r.body as Body).results as Array<{ index: number; relevance_score: number }>;
+      if (results.length !== 3) return false;
+      // The lexically-closest document wins, and the order is strictly descending.
+      if (results[0]!.index !== 1) return false;
+      for (let i = 1; i < results.length; i++) if (results[i]!.relevance_score > results[i - 1]!.relevance_score) return false;
+      if (results.some((x) => x.relevance_score < 0 || x.relevance_score > 1)) return false;
+      // Rerank is billed in SEARCH UNITS, not tokens.
+      return (r.body as Body).meta?.billed_units?.search_units === 1 && (r.body as Body).meta?.billed_units?.input_tokens === undefined;
+    }),
+  ),
+  done('cohere.rerank.v2_strings_only', 'rerank', 'v2 rerank: `documents` must be STRINGS (v1 accepts objects)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const objV2 = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'q', documents: [{ text: 'y' }] } });
+      const objV1 = await h({ m: 'POST', p: '/v1/rerank', b: { query: 'q', documents: [{ text: 'y' }] } });
+      // Both halves: v2 REFUSES the object form and v1 ACCEPTS it. Asserting only the refusal
+      // would pass on a twin that refused object documents everywhere.
+      return bareError(objV2, 400) && message(objV2) === 'invalid request: documents[0] must be a string'
+        && ok(objV1);
+    }),
+  ),
+  done('cohere.rerank.top_n', 'rerank', 'rerank: `top_n` truncates to the N best, keeping original indices', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'apple pie', documents: ['engine oil', 'apple pie recipe', 'orchard', 'pie crust'], top_n: 2 } });
+      const results = (r.body as Body).results as Array<{ index: number }>;
+      // The indices are positions in the ORIGINAL document list, not in the truncated result.
+      return ok(r) && results.length === 2 && results[0]!.index === 1 && results.every((x) => x.index >= 0 && x.index < 4);
+    }),
+  ),
+  done('cohere.rerank.v1_return_documents', 'rerank', 'v1 rerank: `return_documents` rides the text back; v2 has no such option', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const withDocs = await h({ m: 'POST', p: '/v1/rerank', b: { query: 'apple', documents: ['apple pie', 'engine'], return_documents: true } });
+      const without = await h({ m: 'POST', p: '/v1/rerank', b: { query: 'apple', documents: ['apple pie', 'engine'] } });
+      const v2 = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'apple', documents: ['apple pie', 'engine'], return_documents: true } });
+      return (withDocs.body as Body).results[0].document?.text === 'apple pie'
+        && (without.body as Body).results[0].document === undefined
+        // v2 IGNORES the option rather than honouring an option its schema does not declare.
+        && (v2.body as Body).results[0].document === undefined;
+    }),
+  ),
+  done('cohere.rerank.v1_rank_fields', 'rerank', 'v1 rerank: `rank_fields` selects which object fields are scored', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const docs = [{ title: 'engine oil', body: 'apple pie recipe' }, { title: 'apple pie recipe', body: 'engine oil' }];
+      const onTitle = await h({ m: 'POST', p: '/v1/rerank', b: { query: 'apple pie', documents: docs, rank_fields: ['title'] } });
+      const onBody = await h({ m: 'POST', p: '/v1/rerank', b: { query: 'apple pie', documents: docs, rank_fields: ['body'] } });
+      // Scoring different fields of the SAME documents must produce different winners, or
+      // `rank_fields` is not actually being honoured.
+      return (onTitle.body as Body).results[0].index === 1 && (onBody.body as Body).results[0].index === 0;
+    }),
+  ),
+  done('cohere.rerank.validation', 'rerank', 'rerank: missing query / empty documents / wrong-endpoint model each refused', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noQuery = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', documents: ['x'] } });
+      const noDocs = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'q', documents: [] } });
+      const wrongModel = await h({ m: 'POST', p: '/v2/rerank', b: { model: 'command-a-03-2025', query: 'q', documents: ['x'] } });
+      return bareError(noQuery, 400) && bareError(noDocs, 400) && bareError(wrongModel, 404);
+    }),
+  ),
+  todo('cohere.rerank.max_tokens_per_doc', 'rerank', 'v2 rerank: `max_tokens_per_doc` chunking of long documents', 'api', 'niche'),
+  todo('cohere.rerank.max_chunks_per_doc', 'rerank', 'v1 rerank: `max_chunks_per_doc` and its billing effect', 'api', 'niche'),
+
+  // ══ CLASSIFY ══════════════════════════════════════════════════════════════════════════
+  done('cohere.classify.create', 'classify', 'classify: the full classification shape, confidences summing to 1', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['a great day', 'a terrible day'], examples: [{ text: 'good', label: 'positive' }, { text: 'bad', label: 'negative' }] } });
+      if (!ok(r)) return false;
+      const cs = (r.body as Body).classifications as Body[];
+      if (cs.length !== 2 || cs[0]!.input !== 'a great day') return false;
+      if (!['positive', 'negative'].includes(cs[0]!.prediction)) return false;
+      if (cs[0]!.classification_type !== 'single-label') return false;
+      // `labels` is a MAP from label to `{confidence}`, and every declared label appears.
+      if (Object.keys(cs[0]!.labels).sort().join(',') !== 'negative,positive') return false;
+      const sum = Object.values(cs[0]!.labels as Record<string, { confidence: number }>).reduce((a, l) => a + l.confidence, 0);
+      if (Math.abs(sum - 1) > 1e-3) return false;
+      // The prediction really is the argmax of the label map, not an unrelated pick.
+      const best = Object.entries(cs[0]!.labels as Record<string, { confidence: number }>).sort((a, b) => b[1].confidence - a[1].confidence)[0]![0];
+      if (best !== cs[0]!.prediction) return false;
+      return (r.body as Body).meta?.billed_units?.classifications === 2;
+    }),
+  ),
+  done('cohere.classify.validation', 'classify', 'classify: no inputs / no examples-or-preset / one label each refused', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noInputs = await h({ m: 'POST', p: '/v1/classify', b: { examples: [{ text: 'a', label: 'x' }, { text: 'b', label: 'y' }] } });
+      const noLabelSpace = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['x'] } });
+      const oneLabel = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['x'], examples: [{ text: 'a', label: 'only' }, { text: 'b', label: 'only' }] } });
+      const noLabel = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['x'], examples: [{ text: 'a' }] } });
+      return bareError(noInputs, 400) && bareError(noLabelSpace, 400) && message(noLabelSpace).includes('examples or preset')
+        && bareError(oneLabel, 400) && message(oneLabel).includes('at least 2 unique labels')
+        && bareError(noLabel, 400);
+    }),
+  ),
+  done('cohere.classify.preset_is_not_fabricated', 'classify', 'classify: an unmodeled `preset` fails like the vendor — it never invents a label space', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // §9 round two, m-R2.5. An earlier version accepted ANY preset string and invented
+      // ['positive','negative'], returning confident-looking classifications against labels the
+      // caller never named — a fake success on a path filed as `cohere.classify.preset`, and the
+      // same class the detokenize path treats as a hard rule.
+      const r = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['x'], preset: 'my-saved-preset' } });
+      if (!bareError(r, 404) || !message(r).includes("preset 'my-saved-preset' not found")) return false;
+      // …and the EXAMPLES path still works, so this is a refusal of the unmodeled option rather
+      // than of classification itself.
+      const withExamples = await h({ m: 'POST', p: '/v1/classify', b: { inputs: ['x'], examples: [{ text: 'a', label: 'p' }, { text: 'b', label: 'n' }] } });
+      return ok(withExamples) && ((withExamples.body as Body).classifications as Body[]).length === 1;
+    }),
+  ),
+  todo('cohere.classify.preset', 'classify', 'classify: a saved `preset` as the label space instead of inline examples', 'api', 'niche'),
+  todo('cohere.classify.multi_label', 'classify', 'classify: multi-label classification against a finetuned model', 'api', 'niche'),
+  todo('cohere.classify.truncate', 'classify', 'classify: the `truncate` parameter over oversized inputs', 'api', 'niche'),
+
+  // ══ TOKENIZE / DETOKENIZE ═════════════════════════════════════════════════════════════
+  done('cohere.tokenize.round_trip', 'tokenize', 'tokenize → detokenize round-trips the exact input, whitespace included', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const text = 'hello  brave\nnew world ';
+      const tok = await h({ m: 'POST', p: '/v1/tokenize', b: { text, model: 'command-a-03-2025' } });
+      if (!ok(tok)) return false;
+      const tb = tok.body as Body;
+      if (tb.tokens.length !== tb.token_strings.length || tb.tokens.length === 0) return false;
+      if ((tb.token_strings as string[]).join('') !== text) return false;
+      const back = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: tb.tokens, model: 'command-a-03-2025' } });
+      return ok(back) && (back.body as Body).text === text;
+    }),
+  ),
+  done('cohere.tokenize.vocabulary_is_learned', 'tokenize', 'detokenize refuses an id the twin never issued (never fabricates text)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // A FRESH root has an empty vocabulary, so ANY id is unknown — the honest answer is a 400,
+      // never a placeholder string that the caller would read as real detokenized text.
+      const cold = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: [12345], model: 'command-a-03-2025' } });
+      if (!bareError(cold, 400) || !message(cold).includes('unknown token id 12345')) return false;
+      await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'known words', model: 'command-a-03-2025' } });
+      // …and after a tokenize, an id INSIDE the learned vocabulary works while one outside still
+      // does not. Both halves, so "it always 400s" cannot pass.
+      const warm = await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'known words', model: 'command-a-03-2025' } });
+      const good = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: (warm.body as Body).tokens, model: 'command-a-03-2025' } });
+      const stillBad = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: [(warm.body as Body).tokens[0], 999_999], model: 'command-a-03-2025' } });
+      return ok(good) && (good.body as Body).text === 'known words' && bareError(stillBad, 400);
+    }),
+  ),
+  done('cohere.tokenize.dirty_state_vocabulary', 'tokenize', 'DIRTY STATE: a later tokenize never breaks an earlier call\'s detokenize', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // A fresh-root verify structurally CANNOT catch this class. The vocabulary is built up over
+      // MANY calls, and the hazard is a later segment claiming an id an earlier segment already
+      // holds — after which the earlier caller's detokenize silently returns the WRONG text.
+      const first = await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'alpha beta gamma', model: 'command-a-03-2025' } });
+      const firstTokens = (first.body as Body).tokens as number[];
+      // Twenty more tokenizes, growing the vocabulary well past the first call's segments.
+      for (let i = 0; i < 20; i++) {
+        await h({ m: 'POST', p: '/v1/tokenize', b: { text: `filler${i} words ${i} more`, model: 'command-a-03-2025' } });
+      }
+      const back = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: firstTokens, model: 'command-a-03-2025' } });
+      if (!ok(back) || (back.body as Body).text !== 'alpha beta gamma') return false;
+      // …and the ids are STABLE: re-tokenizing the original text yields the same ids, so a client
+      // that cached them is not silently invalidated by other traffic.
+      const again = await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'alpha beta gamma', model: 'command-a-03-2025' } });
+      return JSON.stringify((again.body as Body).tokens) === JSON.stringify(firstTokens);
+    }),
+  ),
+  done('cohere.tokenize.collision_probe', 'tokenize', 'two segments preferring the same id get DISTINCT ids (no silent overwrite)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // Build the collision deliberately rather than hoping for one: every segment's preferred id
+      // is a pure hash, so a large vocabulary makes a collision near-certain, and the invariant
+      // under test is that EVERY distinct segment maps to its OWN id and back.
+      const words: string[] = [];
+      for (let i = 0; i < 400; i++) words.push(`w${i}`);
+      const text = words.join(' ');
+      const tok = await h({ m: 'POST', p: '/v1/tokenize', b: { text, model: 'command-a-03-2025' } });
+      if (!ok(tok)) return false;
+      const ids = (tok.body as Body).tokens as number[];
+      const strings = (tok.body as Body).token_strings as string[];
+      // Distinct segments must have distinct ids — a silent overwrite shows up as a duplicate id
+      // for two different strings.
+      const pairs = new Map<number, string>();
+      for (let i = 0; i < ids.length; i++) {
+        const prev = pairs.get(ids[i]!);
+        if (prev !== undefined && prev !== strings[i]) return false;
+        pairs.set(ids[i]!, strings[i]!);
+      }
+      const back = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: ids, model: 'command-a-03-2025' } });
+      return ok(back) && (back.body as Body).text === text;
+    }),
+  ),
+  done('cohere.tokenize.validation', 'tokenize', 'tokenize/detokenize: `model` is REQUIRED on both (unlike v1 embed/rerank)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noModel = await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'x' } });
+      const noText = await h({ m: 'POST', p: '/v1/tokenize', b: { model: 'command-a-03-2025' } });
+      const badModel = await h({ m: 'POST', p: '/v1/tokenize', b: { text: 'x', model: 'nope' } });
+      const detNoModel = await h({ m: 'POST', p: '/v1/detokenize', b: { tokens: [1] } });
+      const detNoTokens = await h({ m: 'POST', p: '/v1/detokenize', b: { model: 'command-a-03-2025' } });
+      return bareError(noModel, 400) && message(noModel) === 'invalid request: model is required'
+        && bareError(noText, 400) && bareError(badModel, 404)
+        && bareError(detNoModel, 400) && bareError(detNoTokens, 400);
+    }),
+  ),
+
+  // ══ MODELS ════════════════════════════════════════════════════════════════════════════
+  done('cohere.models.list', 'models', 'GET /v1/models: the real catalog with `next_page_token`', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/models' });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (!Array.isArray(b.models) || b.next_page_token !== null) return false;
+      // Real, checkable catalog facts — not just "an array came back".
+      const chat = b.models.find((m: Body) => m.name === 'command-a-03-2025');
+      const embed = b.models.find((m: Body) => m.name === 'embed-v4.0');
+      return chat?.context_length === 256000 && JSON.stringify(chat.endpoints) === '["chat"]'
+        && embed?.context_length === 128000 && embed.finetuned === false;
+    }),
+  ),
+  done('cohere.models.filter_by_endpoint', 'models', 'GET /v1/models?endpoint=: filters to models serving that endpoint', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const all = await h({ m: 'GET', p: '/v1/models' });
+      const rerank = await h({ m: 'GET', p: '/v1/models?endpoint=rerank' });
+      const chat = await h({ m: 'GET', p: '/v1/models?endpoint=chat' });
+      const allN = ((all.body as Body).models as Body[]).length;
+      const rr = (rerank.body as Body).models as Body[];
+      const ch = (chat.body as Body).models as Body[];
+      // A real filter: strictly fewer than the whole catalog, disjoint from the other endpoint,
+      // and every row genuinely serves it.
+      return rr.length > 0 && rr.length < allN && rr.every((m) => m.endpoints.includes('rerank'))
+        && ch.length > 0 && ch.every((m) => m.endpoints.includes('chat'))
+        && !rr.some((m) => ch.some((c) => c.name === m.name));
+    }),
+  ),
+  done('cohere.models.get', 'models', 'GET /v1/models/{name}: one card, 404 for an unknown name', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const one = await h({ m: 'GET', p: '/v1/models/rerank-v3.5' });
+      const missing = await h({ m: 'GET', p: '/v1/models/not-a-model' });
+      const b = one.body as Body;
+      return ok(one) && b.name === 'rerank-v3.5' && b.context_length === 4000
+        && String(b.tokenizer_url).startsWith('https://')
+        && bareError(missing, 404) && message(missing).includes("model 'not-a-model' not found");
+    }),
+  ),
+  done('cohere.models.closed_endpoint_set', 'models', "every SERVED model's `endpoints` is in Cohere's closed CompatibleEndpoint set", 'api', 'common', () =>
+    withRoot(async (h) => {
+      // The claim is about what the twin SERVES, so the catalog is read back off the wire rather
+      // than out of the module. An earlier version asserted over the imported `COHERE_MODELS`
+      // array and had no request on its path at all — the mutation gate reported it as a SURVIVOR,
+      // correctly: it would have stayed green with the whole handler deleted.
+      const listed = await h({ m: 'GET', p: '/v1/models' });
+      if (!ok(listed)) return false;
+      const models = (listed.body as Body).models as Body[];
+      if (!Array.isArray(models) || models.length === 0) return false;
+      // A LITERAL of the vendor's documented set, written here rather than imported from the models
+      // module — importing the constant the catalog is built from would be a tautology.
+      const documented = new Set(['chat', 'embed', 'classify', 'summarize', 'rerank', 'rate', 'generate']);
+      for (const m of models) {
+        if (!Array.isArray(m.endpoints) || m.endpoints.length === 0) return false;
+        for (const e of m.endpoints) if (!documented.has(String(e))) return false;
+      }
+      // Every documented endpoint the twin's catalog actually uses is FILTERABLE, and one it does
+      // not use returns an empty list rather than the whole catalog — so the served `endpoints`
+      // values and the filter agree, in both directions.
+      const served = new Set(models.flatMap((m) => m.endpoints as string[]));
+      for (const e of served) {
+        const filtered = await h({ m: 'GET', p: `/v1/models?endpoint=${e}` });
+        const got = (filtered.body as Body).models as Body[];
+        if (got.length === 0 || got.length >= models.length) return false;
+        if (!got.every((m) => (m.endpoints as string[]).includes(e))) return false;
+      }
+      for (const e of [...documented].filter((d) => !served.has(d))) {
+        if (((await h({ m: 'GET', p: `/v1/models?endpoint=${e}` })).body as Body).models.length !== 0) return false;
+      }
+      // …and the module's own exported set bijects with the documented one, so a future addition to
+      // either side is caught rather than silently diverging.
+      return [...COHERE_ENDPOINTS].sort().join(',') === [...documented].sort().join(',');
+    }),
+  ),
+  todo('cohere.models.pagination', 'models', 'GET /v1/models: real `page_token` cursor pagination', 'api', 'niche'),
+  todo('cohere.models.finetuned_in_catalog', 'models', 'GET /v1/models: finetuned models appear with finetuned:true and default_endpoints', 'api', 'common'),
+  todo('cohere.models.default_only', 'models', 'GET /v1/models?default_only=true filtering', 'api', 'niche'),
+
+  // ══ DATASETS (stateful) ═══════════════════════════════════════════════════════════════
+  done('cohere.datasets.create_read', 'datasets', 'datasets: create → get, with the create answering ONLY `{id}`', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/v1/datasets?name=ds-one&type=embed-input', b: { content: 'a\nb' } });
+      if (!ok(created)) return false;
+      // The vendor's `DatasetsCreateResponse` is `{ id }` and nothing else — a twin returning the
+      // whole dataset here would be more helpful and less faithful.
+      if (Object.keys(created.body as object).join(',') !== 'id') return false;
+      const id = field(created, 'id') as string;
+      const got = await h({ m: 'GET', p: `/v1/datasets/${id}` });
+      const d = (got.body as Body).dataset;
+      // The dataset is NESTED under `dataset` — `DatasetsGetResponse` is `{ dataset }`.
+      return ok(got) && (got.body as Body).id === undefined
+        && d?.id === id && d.name === 'ds-one' && d.dataset_type === 'embed-input'
+        && d.validation_status === 'validated' && d.created_at === PINNED_AT;
+    }),
+  ),
+  done('cohere.datasets.closed_type_set', 'datasets', "datasets: `type` biject with Cohere's closed DatasetType set", 'api', 'common', () =>
+    withRoot(async (h) => {
+      // The vendor's documented set as a LITERAL — the oracle that makes "the twin serves surface
+      // the vendor does not have" checkable in the ACCEPT direction too, not just the reject one.
+      const documented = ['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'];
+      for (const t of documented) {
+        if (!ok(await h({ m: 'POST', p: `/v1/datasets?name=x&type=${t}`, b: DATA_FILE }))) return false;
+      }
+      const bad = await h({ m: 'POST', p: '/v1/datasets?name=x&type=not-a-real-type', b: DATA_FILE });
+      const noType = await h({ m: 'POST', p: '/v1/datasets?name=x', b: DATA_FILE });
+      const noName = await h({ m: 'POST', p: '/v1/datasets?type=embed-input', b: DATA_FILE });
+      // …and the multipart `data` file the vendor's own client always appends is REQUIRED, so the
+      // closed-set oracle above is not resting on a lenient path the vendor would 400
+      // (§9 round 1, finding 6).
+      const noFile = await h({ m: 'POST', p: '/v1/datasets?name=x&type=embed-input' });
+      return bareError(bad, 400) && message(bad).includes('type must be one of')
+        && bareError(noType, 400) && bareError(noName, 400)
+        && bareError(noFile, 400) && message(noFile) === 'invalid request: the data file is required';
+    }),
+  ),
+  done('cohere.datasets.list_filter', 'datasets', 'datasets: list, filtered by datasetType / validationStatus, with limit+offset', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/v1/datasets?name=a&type=embed-input', b: DATA_FILE });
+      await h({ m: 'POST', p: '/v1/datasets?name=b&type=chat-finetune-input', b: DATA_FILE });
+      await h({ m: 'POST', p: '/v1/datasets?name=c&type=embed-input', b: DATA_FILE });
+      const all = await h({ m: 'GET', p: '/v1/datasets' });
+      const embed = await h({ m: 'GET', p: '/v1/datasets?datasetType=embed-input' });
+      const paged = await h({ m: 'GET', p: '/v1/datasets?limit=1&offset=1' });
+      const badStatus = await h({ m: 'GET', p: '/v1/datasets?validationStatus=nonsense' });
+      // The LIST filter honours the same closed DatasetType set the CREATE path does. An earlier
+      // version applied `datasetType` raw and answered `200 {datasets:[]}` for a value the vendor
+      // rejects — reporting an empty account for what is actually a refused request, and leaving
+      // the two paths asymmetric for no reason (§9 round two, MINOR 9).
+      const badType = await h({ m: 'GET', p: '/v1/datasets?datasetType=not-a-real-type' });
+      if (!bareError(badType, 400) || !message(badType).includes('datasetType must be one of')) return false;
+      const names = (r: CohereResponseEnvelope) => ((r.body as Body).datasets as Body[]).map((d) => d.name);
+      return names(all).join(',') === 'a,b,c'
+        && names(embed).join(',') === 'a,c'
+        && names(paged).join(',') === 'b'
+        && bareError(badStatus, 400);
+    }),
+  ),
+  done('cohere.datasets.usage', 'datasets', 'datasets: GET /v1/datasets/usage folds real stored bytes (and is not shadowed by /{id})', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/v1/datasets/usage' });
+      if (!ok(empty) || field(empty, 'organization_usage') !== 0) return false;
+      await h({ m: 'POST', p: '/v1/datasets?name=a&type=embed-input', b: { content: '12345' } });
+      await h({ m: 'POST', p: '/v1/datasets?name=b&type=embed-input', b: { content: '123' } });
+      const used = await h({ m: 'GET', p: '/v1/datasets/usage' });
+      // A real fold over stored state, not a constant — and `usage` is a literal sibling of
+      // `/{id}`, so this also pins the route-ordering that keeps it from being shadowed.
+      return ok(used) && field(used, 'organization_usage') === 8 && (used.body as Body).dataset === undefined;
+    }),
+  ),
+  done('cohere.datasets.delete', 'datasets', 'datasets: delete answers `{}` and the row really leaves the list', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/v1/datasets?name=gone&type=embed-input', b: DATA_FILE });
+      const id = field(created, 'id') as string;
+      const del = await h({ m: 'DELETE', p: `/v1/datasets/${id}` });
+      // Cohere's delete answers an EMPTY object, not the `{deleted:true}` envelope most vendors
+      // send — and the row must actually be gone, which a status-only assertion would not catch.
+      if (!ok(del) || Object.keys(del.body as object).length !== 0) return false;
+      const after = await h({ m: 'GET', p: `/v1/datasets/${id}` });
+      const list = await h({ m: 'GET', p: '/v1/datasets' });
+      const delAgain = await h({ m: 'DELETE', p: `/v1/datasets/${id}` });
+      return bareError(after, 404) && ((list.body as Body).datasets as Body[]).length === 0 && bareError(delAgain, 404);
+    }),
+  ),
+  done('cohere.datasets.id_survives_delete', 'datasets', 'DIRTY STATE: a deleted dataset\'s id is never re-issued to a new one', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // The count-mint bug three packs' §9 reviews each found: delete a row, create a new one, and
+      // a row-count-derived id lands back on the tombstone. Only a build-up-then-assert verify can
+      // see it; a fresh-root one structurally cannot.
+      const a = field(await h({ m: 'POST', p: '/v1/datasets?name=a&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const b = field(await h({ m: 'POST', p: '/v1/datasets?name=b&type=embed-input', b: DATA_FILE }), 'id') as string;
+      await h({ m: 'DELETE', p: `/v1/datasets/${b}` });
+      await h({ m: 'DELETE', p: `/v1/datasets/${a}` });
+      const c = field(await h({ m: 'POST', p: '/v1/datasets?name=c&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const d = field(await h({ m: 'POST', p: '/v1/datasets?name=d&type=embed-input', b: DATA_FILE }), 'id') as string;
+      if (c === a || c === b || d === a || d === b || c === d) return false;
+      // …and the live row really is the new one, not a resurrected tombstone.
+      const got = await h({ m: 'GET', p: `/v1/datasets/${c}` });
+      return ok(got) && (got.body as Body).dataset.name === 'c';
+    }),
+  ),
+  todo('cohere.datasets.validation_pipeline', 'datasets', 'datasets: real upload validation (queued → processing → validated/failed) with row errors', 'api', 'core'),
+  todo('cohere.datasets.parts', 'datasets', 'datasets: `dataset_parts` splits (train/eval) and their row counts', 'api', 'common'),
+  todo('cohere.datasets.metrics', 'datasets', 'datasets: the `metrics` block (label distribution, token counts)', 'api', 'niche'),
+  todo('cohere.datasets.date_filters', 'datasets', 'datasets: the `before` / `after` timestamp list filters', 'api', 'niche'),
+  todo('cohere.datasets.csv_and_separators', 'datasets', 'datasets: csv_delimiter / text_separator / keep_fields upload options', 'api', 'niche'),
+
+  // ══ CONNECTORS (Cohere's RAG connector registry) ══════════════════════════════════════
+  done('cohere.connectors.create_read', 'connectors', 'connectors: create → get, both NESTED under `connector`', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'search', url: 'https://e.test/s', excludes: ['secret'], description: 'd' } });
+      if (!ok(created)) return false;
+      const c = (created.body as Body).connector;
+      // `CreateConnectorResponse` is `{ connector }` — a bare object would break every SDK caller.
+      if ((created.body as Body).id !== undefined || c === undefined) return false;
+      if (c.name !== 'search' || c.url !== 'https://e.test/s' || c.description !== 'd') return false;
+      // `auth_type`/`auth_status` are DERIVED server-side, not caller-supplied.
+      if (c.auth_type !== 'none' || c.auth_status !== 'valid' || c.active !== true) return false;
+      const got = await h({ m: 'GET', p: `/v1/connectors/${c.id}` });
+      return ok(got) && (got.body as Body).connector?.id === c.id && JSON.stringify((got.body as Body).connector.excludes) === '["secret"]';
+    }),
+  ),
+  done('cohere.connectors.list_total_count', 'connectors', 'connectors: list carries `total_count`, and limit/offset page it', 'api', 'common', () =>
+    withRoot(async (h) => {
+      for (const n of ['a', 'b', 'c']) await h({ m: 'POST', p: '/v1/connectors', b: { name: n, url: `https://e.test/${n}` } });
+      const all = await h({ m: 'GET', p: '/v1/connectors' });
+      const paged = await h({ m: 'GET', p: '/v1/connectors?limit=1&offset=1' });
+      // `total_count` is the UNPAGED total — a twin returning the page size here would be wrong in
+      // exactly the way that breaks a paginating client.
+      return ((all.body as Body).connectors as Body[]).length === 3 && (all.body as Body).total_count === 3
+        && ((paged.body as Body).connectors as Body[]).length === 1
+        && (paged.body as Body).connectors[0].name === 'b'
+        && (paged.body as Body).total_count === 3;
+    }),
+  ),
+  done('cohere.connectors.update', 'connectors', 'connectors: PATCH is a partial update — untouched fields survive', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'orig', url: 'https://e.test/s', excludes: ['x'] } });
+      const id = (created.body as Body).connector.id as string;
+      const patched = await h({ m: 'PATCH', p: `/v1/connectors/${id}`, b: { name: 'renamed', active: false } });
+      const c = (patched.body as Body).connector;
+      // A whole-row replace would lose `url` and `excludes` — the failure a status-only assertion
+      // would sail past.
+      if (c.name !== 'renamed' || c.active !== false || c.url !== 'https://e.test/s' || JSON.stringify(c.excludes) !== '["x"]') return false;
+      const reread = await h({ m: 'GET', p: `/v1/connectors/${id}` });
+      const missing = await h({ m: 'PATCH', p: '/v1/connectors/nope', b: { name: 'x' } });
+      return (reread.body as Body).connector.name === 'renamed' && bareError(missing, 404);
+    }),
+  ),
+  done('cohere.connectors.update_revert_is_not_a_replay', 'connectors', 'A PATCH reverting a field under a FROZEN clock is a real write, not a swallowed replay', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // §9 round 1, finding 4. `applyTwinWrite`'s action id is (content + `occurredAt` millisecond).
+      // A world under a frozen clock (TWIN_WORLD_CLOCK_FILE) gives every request ONE occurredAt, so
+      // A → B → A makes the third action byte-identical to the first: the kernel drops it as
+      // `replayed` while the handler answers 200 carrying B, the value the caller did not ask for.
+      // Every request below shares the same pinned instant, which is exactly that world.
+      const created = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'A', url: 'https://e.test/s' } });
+      const id = (created.body as Body).connector.id as string;
+      // THE SEQUENCE IS ODD-LENGTH ON PURPOSE. `B → A → B` is the shortest revisit whose deduped
+      // outcome DIFFERS from its correct one: the third update is byte-identical to the first, so
+      // a twin without the ordinal drops it as `replayed` and the projection stays at A, while a
+      // correct twin lands B. An EVEN-length cycle (B → A → B → A) ends at A either way — which is
+      // precisely how the first version of this pin came out HOLLOW in the revert matrix: its cell
+      // stayed green with the ordinal removed, because the assertion could not tell the two apart.
+      const toB = await h({ m: 'PATCH', p: `/v1/connectors/${id}`, b: { name: 'B' } });
+      if ((toB.body as Body).connector.name !== 'B') return false;
+      const backToA = await h({ m: 'PATCH', p: `/v1/connectors/${id}`, b: { name: 'A' } });
+      if ((backToA.body as Body).connector.name !== 'A') return false;
+      const againB = await h({ m: 'PATCH', p: `/v1/connectors/${id}`, b: { name: 'B' } });
+      // The reply must say B…
+      if ((againB.body as Body).connector.name !== 'B') return false;
+      // …and so must the STORED state. Reply-and-state disagreeing is the failure mode, and only
+      // the re-read can see it.
+      const reread = await h({ m: 'GET', p: `/v1/connectors/${id}` });
+      if ((reread.body as Body).connector.name !== 'B') return false;
+      // A longer odd cycle, so the ordinal is shown to keep MOVING rather than merely alternating
+      // between two values that would themselves collide on the next revisit.
+      for (const n of ['A', 'B', 'A']) await h({ m: 'PATCH', p: `/v1/connectors/${id}`, b: { name: n } });
+      const final = await h({ m: 'GET', p: `/v1/connectors/${id}` });
+      // The ordinal is twin bookkeeping and must never reach the wire.
+      return (final.body as Body).connector.name === 'A' && (final.body as Body).connector._rev === undefined;
+    }),
+  ),
+  done('cohere.connectors.oauth_authorize', 'connectors', 'connectors: oauth/authorize builds a real redirect, and refuses a non-oauth connector', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const plain = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'plain', url: 'https://e.test/s' } });
+      const plainId = (plain.body as Body).connector.id as string;
+      const refused = await h({ m: 'POST', p: `/v1/connectors/${plainId}/oauth/authorize` });
+      // 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 (!bareError(refused, 400) || !message(refused).includes('not configured for oauth')) return false;
+      const oauth = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'oauth', url: 'https://e.test/o', oauth: { client_id: 'cid-9', client_secret: 's', authorize_url: 'https://auth.test/go', token_url: 'https://auth.test/tok' } } });
+      const oc = (oauth.body as Body).connector;
+      if (oc.auth_type !== 'oauth' || oc.auth_status !== 'expired') return false;
+      const authz = await h({ m: 'POST', p: `/v1/connectors/${oc.id}/oauth/authorize?after_token_redirect=https://app.test/done` });
+      const url = field(authz, 'redirect_url') as string;
+      // The redirect is built from the connector's OWN stored configuration, not a constant.
+      return ok(authz) && url.startsWith('https://auth.test/go?')
+        && url.includes('client_id=cid-9')
+        && url.includes('after_token_redirect=https%3A%2F%2Fapp.test%2Fdone')
+        && (await h({ m: 'POST', p: '/v1/connectors/nope/oauth/authorize' })).status === 404;
+    }),
+  ),
+  done('cohere.connectors.delete', 'connectors', 'connectors: delete answers `{}` and the row really leaves the list', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'gone', url: 'https://e.test/s' } });
+      const id = (created.body as Body).connector.id as string;
+      const del = await h({ m: 'DELETE', p: `/v1/connectors/${id}` });
+      if (!ok(del) || Object.keys(del.body as object).length !== 0) return false;
+      const after = await h({ m: 'GET', p: `/v1/connectors/${id}` });
+      const list = await h({ m: 'GET', p: '/v1/connectors' });
+      return bareError(after, 404) && (list.body as Body).total_count === 0;
+    }),
+  ),
+  done('cohere.connectors.validation', 'connectors', 'connectors: name and url are both required', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noName = await h({ m: 'POST', p: '/v1/connectors', b: { url: 'https://e.test' } });
+      const noUrl = await h({ m: 'POST', p: '/v1/connectors', b: { name: 'x' } });
+      return bareError(noName, 400) && message(noName) === 'invalid request: name is required'
+        && bareError(noUrl, 400) && message(noUrl) === 'invalid request: url is required';
+    }),
+  ),
+  todo('cohere.connectors.service_auth', 'connectors', 'connectors: `service_auth` bearer/basic configuration and its auth_status', 'api', 'common'),
+  todo('cohere.connectors.oauth_token_exchange', 'connectors', 'connectors: the OAuth callback token exchange that flips auth_status to valid', 'api', 'common'),
+  todo('cohere.connectors.search_invocation', 'connectors', 'connectors: the twin CALLING a connector\'s search URL during a v1 chat', 'api', 'common'),
+  todo('cohere.connectors.continue_on_failure', 'connectors', 'connectors: `continue_on_failure` semantics when a connector search errors', 'api', 'niche'),
+
+  // ══ EMBED JOBS (stateful) ═════════════════════════════════════════════════════════════
+  done('cohere.embed_jobs.create_read', 'embed_jobs', 'embed jobs: create answers `{job_id, meta}`; the job reads back with NO `id`', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=in&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const created = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document', name: 'j1' } });
+      if (!ok(created)) return false;
+      const b = created.body as Body;
+      // A DIFFERENT create envelope again: `job_id`, not `id`, and a `meta` alongside.
+      if (typeof b.job_id !== 'string' || b.id !== undefined || b.meta === undefined) return false;
+      const got = await h({ m: 'GET', p: `/v1/embed-jobs/${b.job_id}` });
+      const j = got.body as Body;
+      // The vendor's EmbedJob schema has NO `id` key at all; emitting one would be invented
+      // surface, and a connector subjecting on `.id` would collapse the whole collection.
+      return ok(got) && j.job_id === b.job_id && j.id === undefined
+        && j.status === 'processing' && j.input_dataset_id === ds && j.model === 'embed-english-v3.0'
+        && j.truncate === 'END' && j.name === 'j1' && j.created_at === PINNED_AT;
+    }),
+  ),
+  done('cohere.embed_jobs.requires_real_dataset', 'embed_jobs', 'embed jobs: `dataset_id` must reference a dataset that exists', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const missing = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: 'does-not-exist', input_type: 'search_document' } });
+      if (!bareError(missing, 404) || !message(missing).includes("dataset 'does-not-exist' not found")) return false;
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=in&type=embed-input', b: DATA_FILE }), 'id') as string;
+      // …and once the dataset EXISTS the same call succeeds — so the refusal is about the missing
+      // reference, not about the endpoint being broken.
+      const okJob = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document' } });
+      // A DELETED dataset must fail the same way a never-created one does.
+      await h({ m: 'DELETE', p: `/v1/datasets/${ds}` });
+      const afterDelete = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document' } });
+      return ok(okJob) && bareError(afterDelete, 404);
+    }),
+  ),
+  done('cohere.embed_jobs.cancel_state_machine', 'embed_jobs', 'embed jobs: cancel moves processing → cancelling, and a terminal job is refused', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=in&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const job = field(await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document' } }), 'job_id') as string;
+      const cancel = await h({ m: 'POST', p: `/v1/embed-jobs/${job}/cancel` });
+      // `embedJobs.cancel` is declared `-> void`: an empty body — and the STATE must have moved,
+      // which a status-only assertion would not catch.
+      if (!ok(cancel) || Object.keys(cancel.body as object).length !== 0) return false;
+      const after = await h({ m: 'GET', p: `/v1/embed-jobs/${job}` });
+      if ((after.body as Body).status !== 'cancelling') return false;
+      const again = await h({ m: 'POST', p: `/v1/embed-jobs/${job}/cancel` });
+      const missing = await h({ m: 'POST', p: '/v1/embed-jobs/nope/cancel' });
+      return bareError(again, 400) && message(again).includes('cannot be cancelled') && bareError(missing, 404);
+    }),
+  ),
+  done('cohere.embed_jobs.validation', 'embed_jobs', 'embed jobs: model / dataset_id / input_type required, closed enums enforced', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=in&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const base = { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document' };
+      const noModel = await h({ m: 'POST', p: '/v1/embed-jobs', b: { dataset_id: ds, input_type: 'search_document' } });
+      const noDataset = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', input_type: 'search_document' } });
+      const noInput = await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds } });
+      const badInput = await h({ m: 'POST', p: '/v1/embed-jobs', b: { ...base, input_type: 'search' } });
+      const badTrunc = await h({ m: 'POST', p: '/v1/embed-jobs', b: { ...base, truncate: 'middle' } });
+      const chatModel = await h({ m: 'POST', p: '/v1/embed-jobs', b: { ...base, model: 'command-a-03-2025' } });
+      return bareError(noModel, 400) && bareError(noDataset, 400) && bareError(noInput, 400)
+        && bareError(badInput, 400) && bareError(badTrunc, 400) && bareError(chatModel, 404);
+    }),
+  ),
+  done('cohere.embed_jobs.list', 'embed_jobs', 'embed jobs: list under the `embed_jobs` key (not `data`)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/v1/embed-jobs' });
+      if (!ok(empty) || JSON.stringify((empty.body as Body).embed_jobs) !== '[]' || (empty.body as Body).data !== undefined) return false;
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=in&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const job = field(await h({ m: 'POST', p: '/v1/embed-jobs', b: { model: 'embed-english-v3.0', dataset_id: ds, input_type: 'search_document' } }), 'job_id') as string;
+      const list = await h({ m: 'GET', p: '/v1/embed-jobs' });
+      const jobs = (list.body as Body).embed_jobs as Body[];
+      return jobs.length === 1 && jobs[0]!.job_id === job && jobs[0]!.id === undefined;
+    }),
+  ),
+  todo('cohere.embed_jobs.completion', 'embed_jobs', 'embed jobs: a job actually completing and minting its `output_dataset_id`', 'api', 'common'),
+  todo('cohere.embed_jobs.failure', 'embed_jobs', 'embed jobs: the `failed` terminal state and its error reporting', 'api', 'niche'),
+
+  // ══ SURFACE THE TWIN DOES NOT SERVE (real vendor endpoints, honestly filed) ═══════════
+  todo('cohere.generate.create', 'generate', 'POST /v1/generate: the legacy completion endpoint (deprecated but still served)', 'api', 'niche'),
+  todo('cohere.generate.stream', 'generate', 'POST /v1/generate with stream: the GenerateStreamedResponse wire', 'api', 'niche'),
+  todo('cohere.summarize.create', 'summarize', 'POST /v1/summarize: the legacy summarization endpoint (deprecated but still served)', 'api', 'niche'),
+  todo('cohere.parse.create', 'parse', 'POST /v2/parse: document parsing into structured output', 'api', 'common'),
+  todo('cohere.audio.transcriptions', 'audio', 'POST /v2/audio/transcriptions: multipart audio → transcript', 'api', 'common'),
+  todo('cohere.batches.create', 'batches', 'POST /v2/batches: submit a batch of chat/embed requests', 'api', 'common'),
+  todo('cohere.batches.list', 'batches', 'GET /v2/batches: list batches with their status counts', 'api', 'common'),
+  todo('cohere.batches.retrieve', 'batches', 'GET /v2/batches/{id}: one batch with its output file references', 'api', 'common'),
+  todo('cohere.batches.cancel', 'batches', 'POST /v2/batches/{id}:cancel — note the COLON verb suffix, not a path segment', 'api', 'common'),
+  todo('cohere.finetuning.create', 'finetuning', 'POST /v1/finetuning/finetuned-models: start a finetune from a dataset', 'api', 'common'),
+  todo('cohere.finetuning.list', 'finetuning', 'GET /v1/finetuning/finetuned-models: list finetuned models', 'api', 'common'),
+  todo('cohere.finetuning.get', 'finetuning', 'GET /v1/finetuning/finetuned-models/{id}: one finetuned model and its status', 'api', 'common'),
+  todo('cohere.finetuning.update', 'finetuning', 'PATCH /v1/finetuning/finetuned-models/{id}: rename / re-point a finetune', 'api', 'niche'),
+  todo('cohere.finetuning.delete', 'finetuning', 'DELETE /v1/finetuning/finetuned-models/{id}', 'api', 'niche'),
+  todo('cohere.finetuning.events', 'finetuning', 'GET /v1/finetuning/finetuned-models/{id}/events: the training event log', 'api', 'niche'),
+  todo('cohere.finetuning.metrics', 'finetuning', 'GET /v1/finetuning/finetuned-models/{id}/training-step-metrics', 'api', 'niche'),
+
+  // ══ ERRORS / AUTH / READ-ONLY ═════════════════════════════════════════════════════════
+  done('cohere.auth.check_api_key', 'auth', 'POST /v1/check-api-key: a POST despite the name, answering {valid, organization_id, owner_id}', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // §9 round two, MAJOR 2: this endpoint was served, probed by conformance, driven through the
+      // real SDK and headlined in the README's "asserted by a named capability" table — with NO
+      // manifest entry and no area. The area census could not catch it, because it asserts a
+      // bijection between COHERE_AREAS and the manifest's areas: a surface missing from BOTH sides
+      // passes silently. That is the census's documented blind spot, found live.
+      const r = await h({ m: 'POST', p: '/v1/check-api-key' });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (b.valid !== true || typeof b.organization_id !== 'string' || typeof b.owner_id !== 'string') return false;
+      // THE VERB IS THE POINT. `checkApiKey()` sends `method: "POST"` in cohere-ai's Client.js —
+      // the name invites a GET, and a twin that served one would break every real caller.
+      const asGet = await h({ m: 'GET', p: '/v1/check-api-key' });
+      if (!bareError(asGet, 404)) return false;
+      // …and it is auth-gated like every other endpoint when an auth surface is present.
+      return bareError(await h({ m: 'POST', p: '/v1/check-api-key', h: {} }), 401);
+    }),
+  ),
+  done('cohere.errors.bare_message_envelope', 'errors', "every error body is Cohere's BARE `{message}` — one key, no wrapper", 'api', 'core', () =>
+    withRoot(async (h) => {
+      // Sample every distinct failure the twin can produce and assert the SHAPE of each. A single
+      // spot check would not notice one path drifting to the OpenAI `{error:{...}}` envelope.
+      const cases: CohereResponseEnvelope[] = [
+        await h({ m: 'POST', p: '/v2/chat', b: {} }),
+        await h({ m: 'POST', p: '/v2/chat', b: CHAT({ model: 'nope' }) }),
+        await h({ m: 'GET', p: '/v1/models/nope' }),
+        await h({ m: 'GET', p: '/v1/datasets/nope' }),
+        await h({ m: 'GET', p: '/v1/nowhere' }),
+        await h({ m: 'GET', p: '/v1/models', h: {} }),
+        await h({ m: 'POST', p: '/v2/chat', b: CHAT(), ro: true }),
+      ];
+      for (const r of cases) {
+        if (r.status < 400) return false;
+        if (!r.body || typeof r.body !== 'object') return false;
+        if (Object.keys(r.body as object).join(',') !== 'message') return false;
+        if (typeof (r.body as Body).message !== 'string' || (r.body as Body).message === '') return false;
+      }
+      // …and the statuses really are the vendor's, not all one code.
+      return cases.map((r) => r.status).join(',') === '400,404,404,404,404,401,405';
+    }),
+  ),
+  done('cohere.errors.auth_401', 'errors', 'auth: a request with an auth SURFACE but no usable bearer token 401s', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const none = await h({ m: 'GET', p: '/v1/models', h: {} });
+      const empty = await h({ m: 'GET', p: '/v1/models', h: { authorization: 'Bearer ' } });
+      const sentinel = await h({ m: 'GET', p: '/v1/models', h: { authorization: 'Bearer invalid' } });
+      const good = await h({ m: 'GET', p: '/v1/models', h: { authorization: 'Bearer sk-anything' } });
+      // The twin cannot validate real keys, so the modeled failure is the CHECKABLE
+      // missing/sentinel case — and a plausible token must still be ACCEPTED, or the twin would be
+      // unusable rather than faithful.
+      return bareError(none, 401) && bareError(empty, 401) && bareError(sentinel, 401) && ok(good);
+    }),
+  ),
+  done('cohere.errors.read_only_405', 'errors', 'readOnly: every POST/PATCH/DELETE is refused 405 while reads still serve', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // Seed with writes ENABLED, then prove the same reads still work read-only while every
+      // mutating VERB is refused. Note the refusal is method-based, so the write-free inference
+      // POSTs (`/v2/chat`, `/v1/tokenize`) are refused too — a read-only Cohere world cannot chat.
+      // That is a defensible D3 reading of "no POSTs" but it is NOT "every mutation", which is why
+      // the title says POST/PATCH/DELETE rather than over-claiming (§9 round 1, finding 8).
+      const ds = field(await h({ m: 'POST', p: '/v1/datasets?name=a&type=embed-input', b: DATA_FILE }), 'id') as string;
+      const writes: Step[] = [
+        { m: 'POST', p: '/v2/chat', b: CHAT(), ro: true },
+        { m: 'POST', p: '/v1/datasets?name=b&type=embed-input', ro: true },
+        { m: 'DELETE', p: `/v1/datasets/${ds}`, ro: true },
+        { m: 'PATCH', p: '/v1/connectors/x', b: { name: 'y' }, ro: true },
+        { m: 'POST', p: '/v1/tokenize', b: { text: 'x', model: 'command-a-03-2025' }, ro: true },
+      ];
+      for (const w of writes) {
+        const r = await h(w);
+        if (!bareError(r, 405)) return false;
+      }
+      const read = await h({ m: 'GET', p: '/v1/datasets', ro: true });
+      return ok(read) && ((read.body as Body).datasets as Body[]).length === 1;
+    }),
+  ),
+  done('cohere.errors.unmodeled_ops_404', 'errors', 'unmodeled operations fail like the vendor (404), never a fake success', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // Real Cohere endpoints this twin does NOT model. Each must 404 rather than fake-succeed —
+      // and each is filed as a `todo` above, so the manifest and the handler agree.
+      const unmodeled: Step[] = [
+        { m: 'POST', p: '/v1/generate', b: { prompt: 'x' } },
+        { m: 'POST', p: '/v1/summarize', b: { text: 'x' } },
+        { m: 'POST', p: '/v2/parse', b: {} },
+        { m: 'POST', p: '/v2/audio/transcriptions', b: {} },
+        { m: 'GET', p: '/v2/batches' },
+        { m: 'POST', p: '/v2/batches' },
+        { m: 'GET', p: '/v1/finetuning/finetuned-models' },
+        { m: 'POST', p: '/v1/finetuning/finetuned-models', b: {} },
+      ];
+      for (const u of unmodeled) {
+        const r = await h(u);
+        if (!bareError(r, 404)) return false;
+      }
+      // …and a method the twin does not serve on a path it DOES is equally a 404, not a silent
+      // fall-through to the GET branch.
+      const wrongMethod = await h({ m: 'DELETE', p: '/v1/models/rerank-v3.5' });
+      return bareError(wrongMethod, 404);
+    }),
+  ),
+  done('cohere.errors.malformed_body', 'errors', 'a malformed JSON body is refused, never treated as an empty object', 'api', 'common', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cohere-cap-'));
+    return verifyBoundary('cohere.malformed', async () => {
+      try {
+        const r = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: '{not json', root, occurredAt: PINNED_AT });
+        // An unparseable body yields no `model`, so the vendor-shaped required-field refusal is
+        // the correct answer — and a 200 here would mean the twin generated from nothing.
+        return bareError(r, 400) && message(r) === 'invalid request: model is required';
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    });
+  }),
+
+  // ══ DETERMINISM — the serve-path invariant ════════════════════════════════════════════
+  done('cohere.determinism.replay_two_roots', 'determinism', 'the served response is byte-identical across two INDEPENDENT state roots', 'api', 'core', () => {
+    const a = mkdtempSync(join(tmpdir(), 'cohere-det-a-'));
+    const b = mkdtempSync(join(tmpdir(), 'cohere-det-b-'));
+    return verifyBoundary('cohere.determinism', async () => {
+      try {
+        const requests: Step[] = [
+          { m: 'POST', p: '/v2/chat', b: CHAT() },
+          { m: 'POST', p: '/v2/chat', b: CHAT({ tools: [TOOL] }) },
+          { m: 'POST', p: '/v1/chat', b: { message: 'v1 det' } },
+          { m: 'POST', p: '/v2/embed', b: { model: 'embed-v4.0', input_type: 'search_query', texts: ['det'], embedding_types: ['float', 'int8', 'base64'] } },
+          { m: 'POST', p: '/v2/rerank', b: { model: 'rerank-v3.5', query: 'q', documents: ['a q', 'b'] } },
+          { m: 'POST', p: '/v1/classify', b: { inputs: ['x'], examples: [{ text: 'a', label: 'p' }, { text: 'b', label: 'n' }] } },
+          { m: 'POST', p: '/v1/tokenize', b: { text: 'det tokens here', model: 'command-a-03-2025' } },
+        ];
+        const run = async (root: string) => {
+          const out: string[] = [];
+          for (const s of requests) {
+            const r = await handleCohereTwinRequest({ method: s.m, path: s.p, root, occurredAt: PINNED_AT, ...(s.b === undefined ? {} : { body: JSON.stringify(s.b) }) });
+            out.push(`${r.status} ${JSON.stringify(r.body)}`);
+          }
+          return out;
+        };
+        const first = await run(a);
+        const second = await run(b);
+        // Two independent roots, same requests, byte-identical answers — and the payloads are
+        // non-trivial, so this cannot pass on a twin that answers `{}` to everything.
+        if (first.join('\n') !== second.join('\n')) return false;
+        if (first.some((s) => s.length < 40)) return false;
+        // Replaying the FIRST root a second time must also be identical: the stored state grew
+        // (the tokenize wrote rows) without perturbing any answer.
+        const third = await run(a);
+        return third.join('\n') === first.join('\n');
+      } finally {
+        rmSync(a, { recursive: true, force: true });
+        rmSync(b, { recursive: true, force: true });
+      }
+    });
+  }),
+  done('cohere.determinism.no_wall_clock', 'determinism', 'no wall-clock or randomness in served content: an unpinned run is stable, and TIMESTAMPS are pinned', 'api', 'core', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cohere-det-c-'));
+    return verifyBoundary('cohere.determinism_clock', async () => {
+      try {
+        // NOTHING here threads `occurredAt`, so anything reading `Date.now()` or `Math.random()` on
+        // the serve path differs between calls.
+        const one = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT()), root });
+        await new Promise((r) => setTimeout(r, 5));
+        const two = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT()), root });
+        if (JSON.stringify(one.body) !== JSON.stringify(two.body)) return false;
+        // A DIFFERENT prompt must give a different answer, so "identical" is not trivially true.
+        const other = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT({ messages: [{ role: 'user', content: 'different' }] })), root });
+        if (JSON.stringify(other.body) === JSON.stringify(one.body)) return false;
+
+        // THE HALF THAT ACTUALLY REFUTES THE CLAIM (§9 round 1, finding 1). `/v2/chat` carries no
+        // timestamp at all, so the three calls above would stay green with `nowIso` rewritten to
+        // `new Date().toISOString()` — the pack's own headline invariant had a surviving mutant.
+        // Datasets are the endpoint that DOES stamp a clock, so an unpinned pair of creates is
+        // where a wall clock becomes visible. Both halves matter: the two timestamps must AGREE
+        // across a real 5ms gap, and they must equal the pinned instant written here as a LITERAL
+        // (importing the handler's own constant could not catch it drifting).
+        const mk = (name: string) => handleCohereTwinRequest({ method: 'POST', path: `/v1/datasets?name=${name}&type=embed-input`, body: JSON.stringify({ content: 'x' }), root });
+        const a = await mk('clock-a');
+        await new Promise((r) => setTimeout(r, 5));
+        const b = await mk('clock-b');
+        const read = async (r: CohereResponseEnvelope) => (await handleCohereTwinRequest({ method: 'GET', path: `/v1/datasets/${(r.body as Body).id}`, root })).body as Body;
+        const rowA = await read(a);
+        const rowB = await read(b);
+        const stamped = rowA.dataset?.created_at as string;
+        if (typeof stamped !== 'string' || stamped !== rowB.dataset?.created_at) return false;
+        if (stamped !== '2027-01-15T08:00:00.000Z') return false;
+        if (rowA.dataset?.updated_at !== stamped) return false;
+        // …and an EXPLICIT occurredAt still wins, so the pin is a default rather than a hardcode.
+        const pinned = await handleCohereTwinRequest({ method: 'POST', path: '/v1/datasets?name=clock-c&type=embed-input', body: JSON.stringify({ content: 'x' }), root, occurredAt: PINNED_AT });
+        const rowC = await read(pinned);
+        return rowC.dataset?.created_at === PINNED_AT;
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    });
+  }),
+  done('cohere.determinism.stream_matches_unary', 'determinism', 'the streamed and unary answers to the same request agree exactly', 'api', 'common', () =>
+    withStream('/v2/chat', CHAT({ stream: true, tools: [TOOL] }), (events, final) => {
+      const end = events.find((e) => e.data?.type === 'message-end')?.data as Body | undefined;
+      const start = events.find((e) => e.data?.type === 'message-start')?.data as Body | undefined;
+      const f = final.body as Body;
+      // Ids and usage must be the SAME object the unary path would have produced — a separate
+      // generation for the stream would show up here.
+      return start?.id === f.id && end?.id === f.id
+        && JSON.stringify(end?.delta?.usage) === JSON.stringify(f.usage)
+        && end?.delta?.finish_reason === f.finish_reason;
+    }),
+  ),
+
+  // ══ CONNECTOR (the twin's pull/push plane) ════════════════════════════════════════════
+  done('cohere.connector.pull_all_collections', 'connector', 'Connector: pull folds datasets + connectors + embed jobs into the projection', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      const res = await syncCohereFromReal(execute, { root, occurredAt: PINNED_AT });
+      if (res.observed !== 3 || res.deltasAppended !== 3) return false;
+      // Every modeled collection is actually fetched — a pull that quietly skipped one would still
+      // report a plausible count without this.
+      if (calls.map((c) => `${c.method} ${c.path}`).sort().join('|') !== 'GET /v1/connectors|GET /v1/datasets|GET /v1/embed-jobs') return false;
+      // …and the pulled rows are SERVABLE through the twin's own read paths under the VENDOR's ids.
+      const ds = await handleCohereTwinRequest({ method: 'GET', path: '/v1/datasets/ds-real-1', root });
+      const conn = await handleCohereTwinRequest({ method: 'GET', path: '/v1/connectors/conn-real-1', root });
+      const job = await handleCohereTwinRequest({ method: 'GET', path: '/v1/embed-jobs/job-real-1', root });
+      return (ds.body as Body).dataset?.name === 'real-dataset'
+        && (conn.body as Body).connector?.auth_type === 'oauth'
+        && (job.body as Body).job_id === 'job-real-1' && (job.body as Body).input_dataset_id === 'ds-real-1';
+    }),
+  ),
+  done('cohere.connector.pull_idempotent', 'connector', 'Connector: re-pulling identical state appends NOTHING (shadow-diff)', 'connector', 'core', () =>
+    withConnector(async (execute, _calls, root) => {
+      const first = await syncCohereFromReal(execute, { root, occurredAt: PINNED_AT });
+      const second = await syncCohereFromReal(execute, { root, occurredAt: '2026-08-31T13:00:00.000Z' });
+      if (first.deltasAppended !== 3 || second.deltasAppended !== 0 || second.observed !== 3) return false;
+      // The projection still serves exactly one row per collection — a re-pull that duplicated
+      // would show up here rather than in the delta count.
+      const list = await handleCohereTwinRequest({ method: 'GET', path: '/v1/datasets', root });
+      return ((list.body as Body).datasets as Body[]).length === 1;
+    }),
+  ),
+  done('cohere.connector.pull_refuses_error_envelope', 'connector', "Connector: a REFUSED pull throws — it is never an empty account", 'connector', 'core', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cohere-refuse-'));
+    return verifyBoundary('cohere.pull_refuses', async () => {
+      try {
+        // Each executor is built INLINE rather than through `withConnector`, because the outcome
+        // under test is a THROW: `verifyBoundary` converts a non-infrastructure throw into a
+        // `false`, so a nested helper would swallow the very rejection being asserted.
+        const executorFor = (reply: (m: string, p: string) => unknown): CohereExecute =>
+          async (method, path) => reply(method, path);
+
+        // 1. Cohere answers a failure with its bare `{message}` envelope. Mapping that to "no
+        //    resources" would fold an EMPTY account over real observed state and delete the mirror.
+        let refusalMsg = '';
+        try {
+          await syncCohereFromReal(executorFor(() => ({ message: 'rate limited' })), { root, occurredAt: PINNED_AT });
+        } catch (e) { refusalMsg = (e as Error).message; }
+        if (!refusalMsg.includes('pull /v1/datasets failed') || !refusalMsg.includes('rate limited')) return false;
+
+        // 2. An UNRECOGNIZED envelope (no error, but no collection key either) is also a throw,
+        //    not a zero-row pull — "I do not understand this response" is not "the account is
+        //    empty", and only the throw keeps the two apart.
+        let unknownMsg = '';
+        try {
+          await syncCohereFromReal(executorFor(() => ({ unexpected: [] })), { root, occurredAt: PINNED_AT });
+        } catch (e) { unknownMsg = (e as Error).message; }
+        if (!unknownMsg.includes('no "datasets" key')) return false;
+
+        // 3. …but an EXPLICIT `null` genuinely means empty ON THE COLLECTIONS WHOSE SCHEMA SAYS SO,
+        //    and must NOT throw. Without this half the check would pass on a connector that threw
+        //    on everything. Nullability is read PER COLLECTION from the vendor's own serializers:
+        //    `DatasetsListResponse.datasets` and `ListEmbedJobResponse.embed_jobs` are
+        //    `?: Raw[] | null`, so null means empty there.
+        const empty = await syncCohereFromReal(
+          executorFor((m, p) => (m === 'GET' && p === '/v1/datasets' ? { datasets: null } : m === 'GET' && p === '/v1/connectors' ? { connectors: [], total_count: 0 } : { embed_jobs: null })),
+          { root, occurredAt: PINNED_AT },
+        );
+        if (empty.observed !== 0 || empty.deltasAppended !== 0) return false;
+
+        // 3b. …and `ListConnectorsResponse.connectors` is declared REQUIRED and NON-nullable, so a
+        //     null THERE is a response the vendor says cannot occur. Treating it as an empty
+        //     account would fold an empty list over real observed connector state — the exact
+        //     hazard this whole check exists to close, admitted through a door that an earlier
+        //     version justified with a premise that was false for this one collection
+        //     (§9 round 1, connector m1).
+        let nullConnMsg = '';
+        try {
+          await syncCohereFromReal(executorFor((m, p) => (m === 'GET' && p === '/v1/datasets' ? { datasets: [] } : m === 'GET' && p === '/v1/connectors' ? { connectors: null } : { embed_jobs: [] })), { root, occurredAt: PINNED_AT });
+        } catch (e) { nullConnMsg = (e as Error).message; }
+        if (!nullConnMsg.includes('required and non-nullable')) return false;
+
+        // 4. And a NON-list under the key is a throw too, not a coerced empty.
+        let badListMsg = '';
+        try {
+          await syncCohereFromReal(executorFor(() => ({ datasets: 'nope' })), { root, occurredAt: PINNED_AT });
+        } catch (e) { badListMsg = (e as Error).message; }
+        return badListMsg.includes('is not a list');
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    });
+  }),
+  done('cohere.connector.map_shapes', 'connector', 'Connector: the mappers carry every REQUIRED vendor field, and key embed jobs on `job_id`', 'connector', 'core', () =>
+    verifyBoundary('cohere.map_shapes', async () => {
+      const d = mapDataset(REAL_DATASET);
+      const c = mapConnector(REAL_CONNECTOR);
+      const j = mapEmbedJob(REAL_EMBED_JOB);
+      if (d.type !== 'dataset' || d.id !== 'ds-real-1') return false;
+      // Every key the vendor's `Dataset` schema declares REQUIRED — a pulled row missing one is
+      // unparseable by the official SDK the moment the twin serves it back.
+      for (const k of ['name', 'created_at', 'updated_at', 'dataset_type', 'validation_status']) {
+        if (d.fields[k] === undefined || d.fields[k] === null) return false;
+      }
+      if (c.type !== 'connector' || c.id !== 'conn-real-1' || c.fields.auth_type !== 'oauth') return false;
+      for (const k of ['name', 'url', 'created_at', 'updated_at']) if (c.fields[k] === undefined || c.fields[k] === null) return false;
+      // THE EMBED-JOB TRAP: the vendor's schema has NO `id` — subjecting on `.id` would land every
+      // pulled job under the string "undefined" and collapse the collection onto one row.
+      if (j.type !== 'embed_job' || j.id !== 'job-real-1' || j.fields.job_id !== 'job-real-1') return false;
+      // A row with `updated_at` MISSING must fall back rather than emit null: both vendor schemas
+      // declare it required-without-default.
+      const noUpdated = mapDataset({ ...REAL_DATASET, updated_at: undefined });
+      return noUpdated.fields.updated_at === REAL_DATASET.created_at;
+    }),
+  ),
+  done('cohere.connector.push_create_uses_vendor_id', 'connector', 'Connector: push confirms under the VENDOR-minted id, per-type envelope', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      const created = await handleCohereTwinRequest({ method: 'POST', path: '/v1/connectors', body: JSON.stringify({ name: 'local', url: 'https://e.test/s' }), root, occurredAt: PINNED_AT });
+      const localId = (created.body as Body).connector.id as string;
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      if (push.pushed !== 1) return false;
+      // The create envelope is NESTED (`{connector:{id}}`) — a generic `res.id` read would fall
+      // back to the local id here and silently serve one account row as two after the next pull.
+      const external = Object.values(push.externalIds)[0];
+      if (external !== 'conn-vendor-minted' || external === localId) return false;
+      if (calls[0]!.method !== 'POST' || calls[0]!.path !== '/v1/connectors') return false;
+      // The payload is the vendor's CREATE schema — derived fields the endpoint does not accept
+      // must not be replayed.
+      if (calls[0]!.body!.name !== 'local' || calls[0]!.body!.auth_type !== undefined || calls[0]!.body!.auth_status !== undefined) return false;
+      // The row now lives under the VENDOR's id, and the superseded local id is tombstoned so the
+      // next mint can never re-issue it.
+      const atVendor = await handleCohereTwinRequest({ method: 'GET', path: '/v1/connectors/conn-vendor-minted', root });
+      const atLocal = await handleCohereTwinRequest({ method: 'GET', path: `/v1/connectors/${localId}`, root });
+      const list = await handleCohereTwinRequest({ method: 'GET', path: '/v1/connectors', root });
+      if (!ok(atVendor) || atLocal.status !== 404 || (list.body as Body).total_count !== 1) return false;
+      // A 404 is equally true of a row that is simply ABSENT, which is what projection suppression
+      // alone produces — so the 404 cannot distinguish "tombstoned" from "gone", and tombstoned is
+      // the whole property (§9 round 1, m4).
+      //
+      // The check that CAN tell them apart reads the PROJECTION, where a tombstone is visible and an
+      // absence is not — and asserts the SUPERSEDE LINK, which is the tombstone's actual value:
+      // an auditable record that this local id became that vendor id. (The revert matrix is what
+      // forced this to be honest: a first attempt asserted that the next mint does not re-issue
+      // `localId`, and its cell stayed GREEN — because `nextId`'s ordinal only ever moves UPWARD
+      // from the row-set size, so the superseded id is not a candidate either way. That claim was
+      // over-stated; this one is the property the tombstone genuinely carries.)
+      const rows = projectResources('cohere', root).filter((r) => r.type === 'connector');
+      const tomb = rows.find((r) => r.id === localId);
+      if (tomb === undefined) return false;                       // suppressed, not tombstoned
+      if (tomb._deleted !== true) return false;                   // present but not marked dead
+      if (tomb._superseded_by !== 'conn-vendor-minted') return false; // no provenance link
+      // …and the tombstone is genuinely invisible to every READ path, not just to the id lookup.
+      const listed = ((list.body as Body).connectors as Body[]).map((c) => c.id);
+      return !listed.includes(localId) && listed.includes('conn-vendor-minted');
+    }),
+  ),
+  done('cohere.connector.push_embed_job_key', 'connector', "Connector: an embed-job push reads the vendor id from `job_id`, and renames the dataset FK to the write shape", 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // The dataset is PULLED, so it is vendor-known under its own id. (An earlier version created
+      // it locally and asserted the twin-minted id went out in `dataset_id` — §9 round two found it
+      // was pinning the bug rather than the behaviour.)
+      await syncCohereFromReal(execute, { root, occurredAt: PINNED_AT });
+      await handleCohereTwinRequest({ method: 'POST', path: '/v1/embed-jobs', body: JSON.stringify({ model: 'embed-english-v3.0', dataset_id: 'ds-real-1', input_type: 'search_document' }), root, occurredAt: PINNED_AT });
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      if (push.pushed !== 1 || push.refused.length !== 0) return false;
+      if (Object.values(push.externalIds)[0] !== 'job-vendor-minted') return false;
+      const jobCall = calls.find((c) => c.method === 'POST' && c.path === '/v1/embed-jobs')!;
+      // The CREATE schema's field is `dataset_id`; the READ schema's is `input_dataset_id`. A
+      // connector replaying the stored read-shape would send a field the endpoint does not declare.
+      return jobCall.body!.dataset_id === 'ds-real-1' && jobCall.body!.input_dataset_id === undefined
+        && jobCall.body!.input_type === 'search_document';
+    }),
+  ),
+  done('cohere.connector.push_refuses_twin_minted_foreign_key', 'connector', 'Connector: a payload that REFERENCES a twin-minted id is refused, not posted', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // §9 round two, MAJOR. The identity guard covers `subject.id` — and a FOREIGN KEY carries an
+      // id just as capably. `dataset.create` is an un-pushable multipart gap, so a locally created
+      // dataset is PERMANENTLY vendor-unknown; the embed-job create copied its `input_dataset_id`
+      // straight into the vendor's `dataset_id`, so `{"dataset_id":"<twin-uuid>"}` went to the REAL
+      // account, where Cohere rejects the unknown dataset and the batch wedges exactly as B1 did.
+      const ds = await handleCohereTwinRequest({ method: 'POST', path: '/v1/datasets?name=local&type=embed-input', body: JSON.stringify(DATA_FILE), root, occurredAt: PINNED_AT });
+      const dsId = (ds.body as Body).id as string;
+      await handleCohereTwinRequest({ method: 'POST', path: '/v1/embed-jobs', body: JSON.stringify({ model: 'embed-english-v3.0', dataset_id: dsId, input_type: 'search_document' }), root, occurredAt: PINNED_AT });
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      // Both the dataset create (filed multipart gap) and the embed job (twin-minted FK) refuse.
+      if (push.pushed !== 0 || push.refused.length !== 2) return false;
+      const fk = push.refused.find((r) => r.operation === 'embed_job.create');
+      if (!fk || !fk.reason.includes(`references dataset '${dsId}'`)) return false;
+      // NOT ONE REQUEST went out, and the twin-minted id appears nowhere — not in a path, and not
+      // in a BODY, which is the half a path-only assertion cannot see.
+      if (calls.length !== 0) return false;
+      return !JSON.stringify(calls).includes(dsId);
+    }),
+  ),
+  done('cohere.connector.push_refuses_idless_create_response', 'connector', 'Connector: a create response with NO vendor id is an error — never confirmed under the twin\'s own id', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // §9 round two, m-R2.1. Falling back to the local id would MANUFACTURE a vendor identity:
+      // no supersede tombstone is written, so `vendorIdentity` would afterwards report that id as
+      // vendor-known and every later mutation would push the twin's own UUID at the real account —
+      // re-opening the BLOCKER through a side door.
+      await handleCohereTwinRequest({ method: 'POST', path: '/v1/connectors', body: JSON.stringify({ name: 'x', url: 'https://e.test/s' }), root, occurredAt: PINNED_AT });
+      let msg = '';
+      try {
+        await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      } catch (e) { msg = (e as Error).message; }
+      if (!msg.includes('carried no vendor id') || !msg.includes("refusing to confirm under the twin's own id")) return false;
+      // The malformed create WAS sent (this is a response-shape failure, not a refusal to call)…
+      if (calls.length !== 1) return false;
+      // …and nothing was confirmed, so the action is still pending rather than silently "done".
+      const { pendingActions } = await import('@volter/world-core');
+      return pendingActions('cohere', root).length === 1;
+    }, (m, p) => (m === 'POST' && p === '/v1/connectors' ? { connector: { name: 'x' } } : {})),
+  ),
+  done('cohere.connector.push_refuses_unknown_op', 'connector', 'Connector: an operation nobody reasoned about STOPS the run (never a silent skip)', 'connector', 'core', () =>
+    withConnector(async (execute) => {
+      const { pushCohereAction } = await import('./cohere-connector.ts');
+      let msg = '';
+      try {
+        await pushCohereAction(execute, { operation: 'connector.archive', subject: { type: 'connector', id: 'c1' }, fields: {} } as never);
+      } catch (e) { msg = (e as Error).message; }
+      // The SPECIFIC refusal, not merely "something threw" — a dead connector seam's own throw
+      // would otherwise read as a pass and the capability would survive sabotage.
+      if (!msg.includes("unsupported operation 'connector.archive'") || !msg.includes('refusing to silently drop')) return false;
+      // A FILED gap answers with ITS OWN reason instead of the generic one, so a caller can tell a
+      // thought-about gap from a hole nobody has looked at.
+      let filed = '';
+      try {
+        await pushCohereAction(execute, { operation: 'dataset.create', subject: { type: 'dataset', id: 'd1' }, fields: {} } as never);
+      } catch (e) { filed = (e as Error).message; }
+      return filed.includes('cannot faithfully push') && filed.includes('multipart/form-data');
+    }),
+  ),
+  done('cohere.connector.token_type_unpushable', 'connector', 'Connector: the tokenizer vocabulary is refused push-wide, by TYPE not by verb', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // Tokenize writes `token.observe` rows. A verb-keyed refusal would let a hypothetical
+      // `token.delete` through, and the `/v1/${type}s` fallback would then fire `DELETE
+      // /v1/tokens/<id>` — an endpoint Cohere does not have — at a REAL account.
+      await handleCohereTwinRequest({ method: 'POST', path: '/v1/tokenize', body: JSON.stringify({ text: 'push me', model: 'command-a-03-2025' }), root, occurredAt: PINNED_AT });
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      if (push.pushed !== 0 || push.refused.length === 0) return false;
+      if (!push.refused.every((r) => r.reason.includes('no vendor endpoint'))) return false;
+      // NOT ONE REQUEST went out. "It refused" is not proof; the count is what shows nothing
+      // reached the vendor.
+      if (calls.length !== 0) return false;
+      // …and the type-wide rule holds for a verb that IS otherwise pushable.
+      return unpushableReason('token.delete', 'token') !== undefined && unpushableReason('token.create', 'token') !== undefined;
+    }),
+  ),
+  done('cohere.connector.push_request_shape', 'connector', 'Connector: the REST (method, path) for each pushable verb is the vendor\'s', 'connector', 'common', () =>
+    verifyBoundary('cohere.request_shape', async () => {
+      const at = (operation: string, type: string, id: string) => cohereRequestForAction({ operation, subject: { type, id } } as never);
+      const create = at('connector.create', 'connector', 'c1');
+      const update = at('connector.update', 'connector', 'c1');
+      const del = at('dataset.delete', 'dataset', 'd1');
+      const cancel = at('embed_job.cancel', 'embed_job', 'j1');
+      return create.method === 'POST' && create.path === '/v1/connectors'
+        && update.method === 'PATCH' && update.path === '/v1/connectors/c1'
+        && del.method === 'DELETE' && del.path === '/v1/datasets/d1'
+        && cancel.method === 'POST' && cancel.path === '/v1/embed-jobs/j1/cancel';
+    }),
+  ),
+  done('cohere.connector.full_sync_converges', 'connector', 'Connector: push→pull converges — a second full sync is a total no-op', 'connector', 'core', () =>
+    withConnector(async (execute, _calls, root) => {
+      await handleCohereTwinRequest({ method: 'POST', path: '/v1/connectors', body: JSON.stringify({ name: 'local', url: 'https://e.test/s' }), root, occurredAt: PINNED_AT });
+      const first = await fullSyncCohere(execute, { root, occurredAt: PINNED_AT });
+      if (first.pushed !== 1 || first.collections !== 3) return false;
+      const second = await fullSyncCohere(execute, { root, occurredAt: '2026-08-31T14:00:00.000Z' });
+      // Nothing pending and identical real state ⇒ a complete no-op. A push that did not confirm,
+      // or a pull that double-counted, both show up right here.
+      if (second.pushed !== 0 || second.deltasAppended !== 0) return false;
+      const list = await handleCohereTwinRequest({ method: 'GET', path: '/v1/connectors', root });
+      // ONE row, not two: the locally-created connector and the pulled vendor row are the same
+      // account object and must not both be served.
+      return (list.body as Body).total_count === 1 && (list.body as Body).connectors[0].id === 'conn-real-1';
+    }, (m, p) => (m === 'GET' && p === '/v1/datasets' ? { datasets: [] } : m === 'GET' && p === '/v1/connectors' ? { connectors: [REAL_CONNECTOR], total_count: 1 } : m === 'GET' ? { embed_jobs: [] } : m === 'POST' && p === '/v1/connectors' ? { connector: REAL_CONNECTOR } : {})),
+  ),
+  done('cohere.connector.pull_timestamp_moves', 'connector', 'Connector: the default poll timestamp MOVES (a pinned one hides reverting values)', 'connector', 'common', () =>
+    verifyBoundary('cohere.poll_timestamp', async () => {
+      const a = pollTimestamp();
+      const b = pollTimestamp();
+      const c = pollTimestamp();
+      // Strictly increasing WITHIN the process, even when the wall clock has not ticked: the
+      // kernel hashes an observed event over (occurredAt + post-state), so under a fixed poll time
+      // a vendor value that reverts A→B→A collides with its own earlier observation and syncPull
+      // reports a phantom delta while the projection keeps serving the stale value.
+      return a < b && b < c;
+    }),
+  ),
+  done('cohere.connector.budget_refuses_before_calling', 'connector', 'Budget: the ceiling THROWS instead of calling, with the fake\'s count unchanged', 'connector', 'core', () =>
+    verifyBoundary('cohere.budget_ceiling', async () => {
+      const ledger = join(mkdtempSync(join(tmpdir(), 'cohere-budget-')), 'ledger.json');
+      let calls = 0;
+      const fetchImpl = (async () => { calls++; return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch;
+      // The ledger path is INJECTED: a suite that spent against the operator's real
+      // ~/.volter/cohere file would poison every later run on this machine.
+      const budget = new CohereBudget({ path: ledger, now: () => 1_800_000_000_000 });
+      const execute = liveCohereExecute('k', 'https://api.cohere.com', { fetchImpl, budget });
+      // Ceiling 20 at the tokenize weight of 1 ⇒ exactly 20 calls fit.
+      for (let i = 0; i < 20; i++) await execute('POST', '/v1/tokenize', {});
+      if (calls !== 20) return false;
+      let threw = false;
+      try { await execute('POST', '/v1/tokenize', {}); } catch (e) { threw = e instanceof CohereBudgetError; }
+      // "It threw" is NOT the proof. The COUNT is what shows nothing reached the vendor.
+      return threw && calls === 20;
+    }),
+  ),
+  done('cohere.connector.budget_prices_by_endpoint', 'connector', "Budget: weights reproduce Cohere's own per-endpoint scarcity", 'connector', 'core', () =>
+    verifyBoundary('cohere.budget_weights', async () => {
+      // The published per-minute allowances (trial key) that these weights encode:
+      // embed-jobs 5, rerank 10, chat 20, tokenize 100 — so the prices must be strictly ordered
+      // the other way round.
+      const embedJob = cohereCallWeight('POST', '/v1/embed-jobs');
+      const rerank = cohereCallWeight('POST', '/v2/rerank');
+      const chat = cohereCallWeight('POST', '/v2/chat');
+      const tokenize = cohereCallWeight('POST', '/v1/tokenize');
+      if (!(embedJob > rerank && rerank > chat && chat > tokenize)) return false;
+      // An UNCLASSIFIED endpoint is never free — it costs the default.
+      if (cohereCallWeight('POST', '/v1/anything-else') !== chat) return false;
+      // NORMALIZATION: a lower-case method and a trailing slash are input variations, not attacks,
+      // and either would otherwise slip an expensive call past an anchored rule at the read price.
+      return cohereCallWeight('post', '/v1/embed-jobs') === embedJob
+        && cohereCallWeight('POST', '/v1/embed-jobs/') === embedJob
+        && cohereCallWeight('POST', '/v1/embed-jobs?x=1') === embedJob
+        // …and a LONGER path must not borrow the anchored rule's price.
+        && cohereCallWeight('POST', '/v1/embed-jobs/j1/cancel') === chat;
+    }),
+  ),
+  done('cohere.connector.budget_guard_cannot_be_swapped', 'connector', 'Budget: a duck-typed / subclassed / proxied budget is REFUSED at construction', 'connector', 'core', () =>
+    verifyBoundary('cohere.budget_guard', async () => {
+      const fetchImpl = (async () => new Response('{}', { status: 200 })) as unknown as typeof fetch;
+      const refuses = (budget: unknown) => {
+        try { liveCohereExecute('k', 'https://api.cohere.com', { fetchImpl, budget: budget as CohereBudget }); return false; } catch { return true; }
+      };
+      const duck = { checkBudget: () => ({}), recordCall: () => {} };
+      class Loose extends CohereBudget { override checkBudget(): never { return undefined as never; } }
+      const proxied = new Proxy(new CohereBudget({ path: join(mkdtempSync(join(tmpdir(), 'cb-')), 'l.json') }), { get: (t, k) => (k === 'checkBudget' ? () => ({}) : Reflect.get(t, k)) });
+      // Each is a one-liner that would otherwise hand back a client with NO ceiling.
+      if (!refuses(duck) || !refuses(new Loose({ path: join(mkdtempSync(join(tmpdir(), 'cb-')), 'l.json') })) || !refuses(proxied)) return false;
+      // …and an UNMODIFIED budget is still accepted, so the guard is not simply refusing
+      // everything.
+      const real = new CohereBudget({ path: join(mkdtempSync(join(tmpdir(), 'cb-')), 'l.json') });
+      return typeof liveCohereExecute('k', 'https://api.cohere.com', { fetchImpl, budget: real }) === 'function';
+    }),
+  ),
+  done('cohere.connector.push_remaps_to_vendor_id', 'connector', 'Connector: a create-then-UPDATE push addresses the VENDOR id, never the twin-minted one', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // §9 round 1 BLOCKER. Create locally, PATCH locally, push once. The create confirms under the
+      // vendor's id — but the QUEUED update still carries the twin-minted id, and the twin's ids are
+      // UUID-SHAPED, so `PATCH /v1/connectors/<twin-uuid>` fired at the REAL account is
+      // indistinguishable from a legitimate request in an operator's logs. Real Cohere 404s, the
+      // batch aborts mid-run, and the update stays PENDING — so every later push re-issues the same
+      // doomed request forever.
+      const created = await handleCohereTwinRequest({ method: 'POST', path: '/v1/connectors', body: JSON.stringify({ name: 'local', url: 'https://e.test/s' }), root, occurredAt: PINNED_AT });
+      const localId = (created.body as Body).connector.id as string;
+      await handleCohereTwinRequest({ method: 'PATCH', path: `/v1/connectors/${localId}`, body: JSON.stringify({ name: 'renamed' }), root, occurredAt: PINNED_AT });
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      if (push.pushed !== 2 || push.refused.length !== 0) return false;
+      const paths = calls.map((c) => `${c.method} ${c.path}`);
+      // THE ASSERTION: the PATCH went to the vendor's id.
+      if (paths[0] !== 'POST /v1/connectors' || paths[1] !== 'PATCH /v1/connectors/conn-vendor-minted') return false;
+      // …and the twin-minted id was NEVER put on the wire, in any request.
+      if (calls.some((c) => c.path.includes(localId))) return false;
+      // The PATCH payload is the vendor's UPDATE schema — the twin's own bookkeeping never rides.
+      const patch = calls[1]!.body!;
+      return patch.name === 'renamed' && patch._twin_minted === undefined && patch._rev === undefined && patch.auth_status === undefined;
+    }),
+  ),
+  done('cohere.connector.push_identity_survives_an_aborted_batch', 'connector', 'Connector: the vendor-id mapping is DURABLE — a second push after an abort still addresses the vendor', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // §9 ROUND TWO, BLOCKER — the two round-one fixes destroying each other. `confirmAction`
+      // suppresses the confirmed create's projection, and the supersede tombstone carries only
+      // `{_deleted,_superseded_by}` — so `_twin_minted` VANISHES with the create it lived on. The
+      // in-loop map was then the only guard, and it dies with the batch:
+      //   push #1 confirms the create, the PATCH throws (a budget refusal, a retry-after past the
+      //   cap, a network blip, any vendor `{message}`) → the batch aborts, the PATCH stays pending
+      //   → push #2 has an EMPTY map and a marker-less tombstone → the twin's own UUID goes to the
+      //   real account, every run, forever.
+      // Neither the B1 capability nor its revert-matrix cell could see this: both are single-batch.
+      const created = await handleCohereTwinRequest({ method: 'POST', path: '/v1/connectors', body: JSON.stringify({ name: 'local', url: 'https://e.test/s' }), root, occurredAt: PINNED_AT });
+      const localId = (created.body as Body).connector.id as string;
+      await handleCohereTwinRequest({ method: 'PATCH', path: `/v1/connectors/${localId}`, body: JSON.stringify({ name: 'renamed' }), root, occurredAt: PINNED_AT });
+
+      // PUSH #1 — the create succeeds, then the PATCH throws, aborting the batch mid-run.
+      let aborted = false;
+      const failingOnPatch: CohereExecute = async (method, path, body) => {
+        if (method === 'PATCH') throw new Error('simulated mid-batch failure');
+        return execute(method, path, body);
+      };
+      try {
+        await pushPendingCohereActions(failingOnPatch, { root, occurredAt: PINNED_AT });
+      } catch { aborted = true; }
+      if (!aborted) return false;
+      // The create really did land, and the update really is still pending.
+      const afterFirst = calls.filter((c) => c.method === 'POST' && c.path === '/v1/connectors');
+      if (afterFirst.length !== 1) return false;
+
+      // PUSH #2 — a FRESH call, so the in-memory map is empty. The durable supersede tombstone is
+      // the only thing that can resolve the identity now.
+      calls.length = 0;
+      const second = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      if (second.pushed !== 1 || second.refused.length !== 0) return false;
+      // THE ASSERTION: the vendor's id, and the twin-minted id NOWHERE on the wire.
+      if (calls.length !== 1 || calls[0]!.path !== '/v1/connectors/conn-vendor-minted') return false;
+      return !JSON.stringify(calls).includes(localId);
+    }),
+  ),
+  done('cohere.connector.push_refuses_subject_with_no_vendor_id', 'connector', 'Connector: an action on a subject the vendor has never seen is REFUSED, not fired at the account', 'connector', 'core', () =>
+    withConnector(async (execute, calls, root) => {
+      // §9 round 1 MAJOR, and the sharpest "what did the fix make newly REACHABLE" case in the pack.
+      // `dataset.create` is a FILED multipart gap, so it is skipped rather than aborting the run —
+      // and skipping it is precisely what made the following delete reachable:
+      // `DELETE /v1/datasets/<twin-minted-uuid>` went to the REAL account, addressing whatever (if
+      // anything) happens to carry that id there. Aborting would have prevented it; the skip did not.
+      const ds = await handleCohereTwinRequest({ method: 'POST', path: '/v1/datasets?name=doomed&type=embed-input', body: JSON.stringify(DATA_FILE), root, occurredAt: PINNED_AT });
+      const dsId = (ds.body as Body).id as string;
+      await handleCohereTwinRequest({ method: 'DELETE', path: `/v1/datasets/${dsId}`, root, occurredAt: PINNED_AT });
+      const push = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      // BOTH are refused by name, and NOT ONE REQUEST went out. "It refused" is not the proof; the
+      // call count is what shows nothing reached the vendor.
+      if (push.pushed !== 0 || push.refused.length !== 2 || calls.length !== 0) return false;
+      const del = push.refused.find((r) => r.operation === 'dataset.delete');
+      if (!del || !del.reason.includes('minted by this twin') || del.subjectId !== dsId) return false;
+      // …and the run does NOT abort: the filed create is still reported alongside it.
+      if (!push.refused.some((r) => r.operation === 'dataset.create' && r.reason.includes('multipart'))) return false;
+      // THE OTHER DIRECTION, so this is not just "the connector refuses deletes": a row that came
+      // from a PULL is vendor-known under its own id, and a mutation on it pushes normally.
+      await syncCohereFromReal(execute, { root, occurredAt: PINNED_AT });
+      await handleCohereTwinRequest({ method: 'PATCH', path: '/v1/connectors/conn-real-1', body: JSON.stringify({ name: 'renamed' }), root, occurredAt: PINNED_AT });
+      const second = await pushPendingCohereActions(execute, { root, occurredAt: PINNED_AT });
+      return second.pushed === 1 && calls.some((c) => c.method === 'PATCH' && c.path === '/v1/connectors/conn-real-1');
+    }),
+  ),
+  todo('cohere.connector.pull_finetuned_models', 'connector', 'Connector: pull finetuned models (needs the finetuning endpoints first)', 'connector', 'common'),
+  todo('cohere.connector.pull_batches', 'connector', 'Connector: pull batch jobs (needs the /v2/batches endpoints first)', 'connector', 'common'),
+  todo('cohere.connector.push_dataset_multipart', 'connector', 'Connector: push a dataset create as the multipart/form-data upload the endpoint requires', 'connector', 'common'),
+  todo('cohere.connector.pull_dataset_parts', 'connector', 'Connector: pull a dataset\'s PARTS and validation errors, not just the dataset row', 'connector', 'niche'),
+  todo('cohere.connector.push_connector_oauth', 'connector', 'Connector: push a connector\'s oauth/service_auth configuration on create', 'connector', 'common'),
+
+  // ══ CONFORMANCE ══════════════════════════════════════════════════════════════════════
+  done('cohere.conformance.probes', 'conformance', 'Conformance: every claimed endpoint is probed for a live OUTCOME, not just a dispatch', 'api', 'core', async () =>
+    verifyBoundary('cohere.conformance', async () => {
+      const report = await checkCohereConformance();
+      return report.ok && report.claimed === 27 && report.checksRun >= 58 && report.violations.length === 0;
+    }),
+  ),
+  done('cohere.conformance.scenario_engine_is_the_kernel', 'conformance', 'Scenario scripting runs on THE kernel engine with a pack adapter (never a bespoke one)', 'api', 'common', () =>
+    verifyBoundary('cohere.scenario_kernel', async () => {
+      const engine = createCohereScenarioEngine();
+      const remove = engine.use({ on: { userTextIncludes: 'refund' }, respond: { text: 'scripted refund reply' } });
+      const root = mkdtempSync(join(tmpdir(), 'cohere-scn-'));
+      try {
+        const hit = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT({ messages: [{ role: 'user', content: 'I need a refund' }] })), root, occurredAt: PINNED_AT, scenarioEngine: engine });
+        const miss = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT()), root, occurredAt: PINNED_AT, scenarioEngine: engine });
+        remove();
+        const after = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT({ messages: [{ role: 'user', content: 'I need a refund' }] })), root, occurredAt: PINNED_AT, scenarioEngine: engine });
+        const text = (r: CohereResponseEnvelope) => String((r.body as Body).message?.content?.[0]?.text ?? '');
+        // The scripted turn fires; an unmatched one falls back to the labeled stub AND ledgers the
+        // miss with its features; removing the handler restores the stub.
+        const status = engine.status();
+        return text(hit) === 'scripted refund reply'
+          && text(miss).includes('[twin-stub:') && text(miss).includes('twin-scenario miss')
+          && text(after).includes('[twin-stub:')
+          && status.vendor === 'cohere'
+          // Two misses: the unmatched request, and the refund request AFTER the handler was
+          // removed. The handler row is gone from the status, and it fired exactly once.
+          && status.misses === 2 && status.handlers.length === 0;
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    }),
+  ),
+];
+
+export function cohereCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('cohere', COHERE_CAPABILITIES);
+}