@volter/twin-cohere 0.1.0

package/src/cohere-conformance.ts

@@ -0,0 +1,489 @@
+// Cohere twin CONFORMANCE — an offline, deterministic check with REAL TEETH.
+//
+// The bar (docs/contributing/adding-a-twin.md §6, "The conformance check needs the same teeth"): delete the
+// handler branch and this must go RED. Two known false-green shapes are avoided by construction:
+//
+//   1. NOT "two constants asserting about each other." Every claim is exercised by a REAL request
+//      against a throwaway root, and each expectation is a LITERAL written here — never a value
+//      imported from the handler it is certifying (that would be a tautology that could not catch
+//      the value drifting).
+//   2. NOT "graded only on the router's own miss." Grading a probe as "not the 404 envelope" has
+//      teeth at the dispatch and nowhere deeper: a sub-handler that lost its body would still fall
+//      through to its own 4xx. So every probe asserts an expected STATUS SET **plus a predicate
+//      over the BODY** — the outcome a live handler produces.
+//
+// THREE DIRECTIONS, closed:
+//   • probe → claim   : every probe names a claimed endpoint.
+//   • claim → probe   : every claimed endpoint has a probe (a two-way bijection).
+//   • router → claim  : every method/path pair the router branches on (`COHERE_ROUTER_SURFACE`) is
+//                       exercised; anything that answers something OTHER than the vendor's
+//                       not-found envelope without a matching claim is SERVED-BUT-UNCLAIMED
+//                       surface and fails. Probe⇄claim alone is blind to that direction.
+//                       HONEST LIMIT: `COHERE_ROUTER_SURFACE` is HAND-authored, so a branch added
+//                       to the handler and to neither list is invisible here. The mechanical
+//                       backstop for that lives in cohere-twin.test.ts ("covers every literal path
+//                       the handler dispatches on"), which reads the dispatch source itself;
+//                       segment-matched sub-routes still rest on review.
+//
+// Honest scope: this certifies the PROTOCOL ENVELOPE and the dispatch, NOT model output (a
+// deterministic, clearly-labeled stub by design).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { COHERE_ROUTER_SURFACE, handleCohereTwinRequest, type CohereResponseEnvelope } from './cohere-twin.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type CohereConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  claimed: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, any>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The endpoints this twin CLAIMS to serve — hand-written, one line per claim. `{id}` stands for
+ *  one path segment, matching `COHERE_ROUTER_SURFACE`'s notation. */
+export const COHERE_TWIN_SNAPSHOT: ReadonlyArray<string> = [
+  'POST /v2/chat',
+  'POST /v2/embed',
+  'POST /v2/rerank',
+  'POST /v1/chat',
+  'POST /v1/embed',
+  'POST /v1/rerank',
+  'POST /v1/classify',
+  'POST /v1/tokenize',
+  'POST /v1/detokenize',
+  'POST /v1/check-api-key',
+  'GET /v1/models',
+  'GET /v1/models/{id}',
+  'POST /v1/datasets',
+  'GET /v1/datasets',
+  'GET /v1/datasets/usage',
+  'GET /v1/datasets/{id}',
+  'DELETE /v1/datasets/{id}',
+  'POST /v1/connectors',
+  'GET /v1/connectors',
+  'GET /v1/connectors/{id}',
+  'PATCH /v1/connectors/{id}',
+  'DELETE /v1/connectors/{id}',
+  'POST /v1/connectors/{id}/oauth/authorize',
+  'POST /v1/embed-jobs',
+  'GET /v1/embed-jobs',
+  'GET /v1/embed-jobs/{id}',
+  'POST /v1/embed-jobs/{id}/cancel',
+];
+
+/** Live ids the seeding probes hand to the later ones. */
+type Ctx = { dataset?: string; connector?: string; oauthConnector?: string; job?: string; tokens?: number[] };
+
+type Probe = {
+  /** The claim this probe certifies — must appear verbatim in COHERE_TWIN_SNAPSHOT. */
+  claim: string;
+  /** Build the real request (may read ids seeded by earlier probes). */
+  request: (ctx: Ctx) => { method: string; path: string; body?: unknown };
+  /** The status codes a LIVE handler may answer with. */
+  status: number[];
+  /** The outcome predicate over the response body — the teeth below the dispatch. */
+  expect: (body: unknown, ctx: Ctx) => boolean;
+  /** Record an id for later probes. */
+  capture?: (body: unknown, ctx: Ctx) => void;
+};
+
+const CHAT = { model: 'command-a-03-2025', messages: [{ role: 'user', content: 'conformance probe' }] };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/**
+ * The probe list, in SEEDING ORDER. A dataset is created before the embed job that references it
+ * and before the reads that expect exactly one row; the OAuth connector is created before the
+ * authorize probe. The order is the contract, not an accident of list position.
+ */
+const PROBES: Probe[] = [
+  {
+    claim: 'POST /v2/chat',
+    request: () => ({ method: 'POST', path: '/v2/chat', body: CHAT }),
+    status: [200],
+    expect: (b) => isObj(b) && UUID.test(String(b.id))
+      // NO `choices`, NO `object`, NO `created` — the three keys an OpenAI-shaped copy would add.
+      && b.choices === undefined && b.object === undefined && b.created === undefined
+      && b.finish_reason === 'COMPLETE'
+      && b.message?.role === 'assistant'
+      && b.message?.content?.[0]?.type === 'text'
+      && String(b.message.content[0].text).includes('[twin-stub:command-a-03-2025]')
+      && String(b.message.content[0].text).includes('conformance probe')
+      // Usage is TWO nested counters, both present, and they agree.
+      && b.usage?.billed_units?.input_tokens > 0 && b.usage?.tokens?.input_tokens === b.usage.billed_units.input_tokens
+      && b.usage?.tokens?.output_tokens > 0,
+  },
+  {
+    claim: 'POST /v1/chat',
+    request: () => ({ method: 'POST', path: '/v1/chat', body: { message: 'v1 probe', model: 'command-r-08-2024' } }),
+    status: [200],
+    // v1 is a DIFFERENT envelope: flat `text`, `chat_history`, `meta` (not `usage`), no `message`.
+    expect: (b) => isObj(b) && typeof b.text === 'string' && b.text.includes('[twin-stub:command-r-08-2024]')
+      && b.message === undefined && b.usage === undefined
+      && UUID.test(String(b.generation_id)) && UUID.test(String(b.response_id))
+      && b.finish_reason === 'COMPLETE'
+      && Array.isArray(b.chat_history) && b.chat_history.length === 2
+      && b.chat_history[0].role === 'USER' && b.chat_history[0].message === 'v1 probe'
+      && b.chat_history[1].role === 'CHATBOT'
+      && b.meta?.api_version?.version === '1' && b.meta?.billed_units?.input_tokens > 0,
+  },
+  {
+    claim: 'POST /v2/embed',
+    request: () => ({ method: 'POST', path: '/v2/embed', body: { model: 'embed-v4.0', input_type: 'search_query', texts: ['alpha', 'beta'], embedding_types: ['float', 'int8', 'base64'], output_dimension: 256 } }),
+    status: [200],
+    expect: (b) => isObj(b) && b.response_type === 'embeddings_by_type'
+      && Array.isArray(b.embeddings?.float) && b.embeddings.float.length === 2 && b.embeddings.float[0].length === 256
+      && Array.isArray(b.embeddings?.int8) && b.embeddings.int8[0].length === 256
+      && typeof b.embeddings?.base64?.[0] === 'string'
+      // int8 really is a QUANTIZATION of the same vector, not a second unrelated one.
+      && b.embeddings.int8[0][0] === Math.max(-128, Math.min(127, Math.round(b.embeddings.float[0][0] * 127)))
+      && JSON.stringify(b.embeddings.float[0]) !== JSON.stringify(b.embeddings.float[1])
+      && JSON.stringify(b.texts) === '["alpha","beta"]'
+      && b.meta?.billed_units?.input_tokens > 0,
+  },
+  {
+    claim: 'POST /v1/embed',
+    request: () => ({ method: 'POST', path: '/v1/embed', body: { model: 'embed-english-v3.0', input_type: 'search_query', texts: ['gamma'] } }),
+    status: [200],
+    // v1's DEFAULT is the FLAT shape — the union arm `embeddings_by_type` would put a caller in
+    // the wrong branch of cohere-ai's discriminated `EmbedResponse`.
+    expect: (b) => isObj(b) && b.response_type === 'embeddings_floats'
+      && Array.isArray(b.embeddings) && Array.isArray(b.embeddings[0]) && b.embeddings[0].length === 1024,
+  },
+  {
+    claim: 'POST /v2/rerank',
+    request: () => ({ method: 'POST', path: '/v2/rerank', body: { model: 'rerank-v3.5', query: 'apple pie recipe', documents: ['a recipe for apple pie', 'how to service a car engine', 'apple orchard tours'], top_n: 2 } }),
+    status: [200],
+    expect: (b) => isObj(b) && Array.isArray(b.results) && b.results.length === 2
+      && b.results[0].index === 0 && b.results[0].relevance_score > b.results[1].relevance_score
+      // v2 rerank has NO `return_documents`, so no `document` rides on a result.
+      && b.results[0].document === undefined
+      // Rerank is billed in SEARCH UNITS, not tokens.
+      && b.meta?.billed_units?.search_units === 1 && b.meta?.billed_units?.input_tokens === undefined,
+  },
+  {
+    claim: 'POST /v1/rerank',
+    request: () => ({ method: 'POST', path: '/v1/rerank', body: { query: 'apple pie', documents: [{ text: 'apple pie recipe' }, { text: 'engine oil' }], return_documents: true } }),
+    status: [200],
+    // v1 accepts OBJECT documents and honours `return_documents` — neither exists in v2.
+    expect: (b) => isObj(b) && Array.isArray(b.results) && b.results.length === 2
+      && b.results[0].document?.text === 'apple pie recipe'
+      && b.meta?.billed_units?.search_units === 1,
+  },
+  {
+    claim: 'POST /v1/classify',
+    request: () => ({ method: 'POST', path: '/v1/classify', body: { inputs: ['a great day', 'a terrible day'], examples: [{ text: 'good', label: 'positive' }, { text: 'bad', label: 'negative' }] } }),
+    status: [200],
+    expect: (b) => isObj(b) && Array.isArray(b.classifications) && b.classifications.length === 2
+      && b.classifications[0].input === 'a great day'
+      && ['positive', 'negative'].includes(b.classifications[0].prediction)
+      && Object.keys(b.classifications[0].labels).sort().join(',') === 'negative,positive'
+      // The label confidences are normalized — they sum to 1, like a real single-label result's.
+      && Math.abs(Object.values(b.classifications[0].labels as Record<string, { confidence: number }>).reduce((a, l) => a + l.confidence, 0) - 1) < 1e-3
+      && b.classifications[0].classification_type === 'single-label'
+      && b.meta?.billed_units?.classifications === 2,
+  },
+  {
+    claim: 'POST /v1/tokenize',
+    request: () => ({ method: 'POST', path: '/v1/tokenize', body: { text: 'hello brave new world', model: 'command-a-03-2025' } }),
+    status: [200],
+    expect: (b) => isObj(b) && Array.isArray(b.tokens) && Array.isArray(b.token_strings)
+      && b.tokens.length === b.token_strings.length && b.tokens.length === 4
+      && b.token_strings.join('') === 'hello brave new world'
+      && b.tokens.every((t: unknown) => typeof t === 'number' && (t as number) > 0),
+    capture: (b, ctx) => { ctx.tokens = (b as Body).tokens; },
+  },
+  {
+    claim: 'POST /v1/detokenize',
+    request: (ctx) => ({ method: 'POST', path: '/v1/detokenize', body: { tokens: ctx.tokens, model: 'command-a-03-2025' } }),
+    status: [200],
+    // The round trip is the whole property: the twin's vocabulary was LEARNED by the probe above.
+    expect: (b) => isObj(b) && b.text === 'hello brave new world',
+  },
+  {
+    claim: 'POST /v1/check-api-key',
+    request: () => ({ method: 'POST', path: '/v1/check-api-key' }),
+    status: [200],
+    expect: (b) => isObj(b) && b.valid === true && typeof b.organization_id === 'string' && typeof b.owner_id === 'string',
+  },
+  {
+    claim: 'GET /v1/models',
+    request: () => ({ method: 'GET', path: '/v1/models?endpoint=rerank' }),
+    status: [200],
+    expect: (b) => isObj(b) && Array.isArray(b.models) && b.next_page_token === null
+      && b.models.length >= 3
+      && b.models.every((m: Body) => Array.isArray(m.endpoints) && m.endpoints.includes('rerank'))
+      && b.models.some((m: Body) => m.name === 'rerank-v3.5' && m.context_length === 4000),
+  },
+  {
+    claim: 'GET /v1/models/{id}',
+    request: () => ({ method: 'GET', path: '/v1/models/embed-v4.0' }),
+    status: [200],
+    expect: (b) => isObj(b) && b.name === 'embed-v4.0' && b.context_length === 128000
+      && JSON.stringify(b.endpoints) === '["embed"]' && b.finetuned === false
+      && String(b.tokenizer_url).startsWith('https://'),
+  },
+  {
+    claim: 'POST /v1/datasets',
+    request: () => ({ method: 'POST', path: '/v1/datasets?name=conf-ds&type=embed-input', body: { content: '{"text":"a"}' } }),
+    status: [200],
+    // Cohere's create answers ONLY `{ id }` — not the dataset object.
+    expect: (b) => isObj(b) && UUID.test(String(b.id)) && Object.keys(b).length === 1,
+    capture: (b, ctx) => { ctx.dataset = (b as Body).id; },
+  },
+  {
+    claim: 'GET /v1/datasets',
+    request: () => ({ method: 'GET', path: '/v1/datasets?datasetType=embed-input' }),
+    status: [200],
+    expect: (b, ctx) => isObj(b) && Array.isArray(b.datasets) && b.datasets.length === 1
+      && b.datasets[0].id === ctx.dataset && b.datasets[0].name === 'conf-ds',
+  },
+  {
+    claim: 'GET /v1/datasets/usage',
+    request: () => ({ method: 'GET', path: '/v1/datasets/usage' }),
+    status: [200],
+    // Real bytes, folded from the stored content — a constant would not move with the seed.
+    expect: (b) => isObj(b) && b.organization_usage === 12,
+  },
+  {
+    claim: 'GET /v1/datasets/{id}',
+    request: (ctx) => ({ method: 'GET', path: `/v1/datasets/${ctx.dataset}` }),
+    status: [200],
+    // The dataset is NESTED under `dataset` — `DatasetsGetResponse` is `{ dataset }`.
+    expect: (b, ctx) => isObj(b) && b.dataset?.id === ctx.dataset && b.dataset?.dataset_type === 'embed-input'
+      && b.dataset?.validation_status === 'validated' && typeof b.dataset?.created_at === 'string'
+      && b.id === undefined,
+  },
+  {
+    claim: 'POST /v1/connectors',
+    request: () => ({ method: 'POST', path: '/v1/connectors', body: { name: 'conf-conn', url: 'https://example.test/search', excludes: ['x'] } }),
+    status: [200],
+    // NESTED under `connector` — `CreateConnectorResponse` is `{ connector }`.
+    expect: (b) => isObj(b) && b.connector?.name === 'conf-conn' && b.connector?.url === 'https://example.test/search'
+      && b.connector?.auth_type === 'none' && b.connector?.auth_status === 'valid'
+      && b.connector?.active === true && UUID.test(String(b.connector?.id)),
+    capture: (b, ctx) => { ctx.connector = (b as Body).connector.id; },
+  },
+  {
+    claim: 'GET /v1/connectors',
+    request: () => ({ method: 'GET', path: '/v1/connectors' }),
+    status: [200],
+    expect: (b, ctx) => isObj(b) && Array.isArray(b.connectors) && b.total_count === b.connectors.length
+      && b.connectors.some((c: Body) => c.id === ctx.connector),
+  },
+  {
+    claim: 'GET /v1/connectors/{id}',
+    request: (ctx) => ({ method: 'GET', path: `/v1/connectors/${ctx.connector}` }),
+    status: [200],
+    expect: (b, ctx) => isObj(b) && b.connector?.id === ctx.connector && JSON.stringify(b.connector?.excludes) === '["x"]',
+  },
+  {
+    claim: 'PATCH /v1/connectors/{id}',
+    request: (ctx) => ({ method: 'PATCH', path: `/v1/connectors/${ctx.connector}`, body: { name: 'conf-renamed', active: false } }),
+    status: [200],
+    // The patch really lands AND the untouched field survives — a whole-row replace would lose it.
+    expect: (b, ctx) => isObj(b) && b.connector?.id === ctx.connector && b.connector?.name === 'conf-renamed'
+      && b.connector?.active === false && b.connector?.url === 'https://example.test/search',
+  },
+  {
+    claim: 'POST /v1/connectors/{id}/oauth/authorize',
+    request: (ctx) => ({ method: 'POST', path: `/v1/connectors/${ctx.oauthConnector}/oauth/authorize?after_token_redirect=https://app.test/done` }),
+    status: [200],
+    expect: (b) => isObj(b) && typeof b.redirect_url === 'string'
+      && b.redirect_url.startsWith('https://auth.example.test/authorize?')
+      && b.redirect_url.includes('client_id=cid-1')
+      && b.redirect_url.includes('after_token_redirect=https%3A%2F%2Fapp.test%2Fdone'),
+  },
+  {
+    claim: 'POST /v1/embed-jobs',
+    request: (ctx) => ({ method: 'POST', path: '/v1/embed-jobs', body: { model: 'embed-english-v3.0', dataset_id: ctx.dataset, input_type: 'search_document', name: 'conf-job' } }),
+    status: [200],
+    // The create answers `{ job_id, meta }` — a different key from every other create here.
+    expect: (b) => isObj(b) && UUID.test(String(b.job_id)) && b.id === undefined && isObj(b.meta),
+    capture: (b, ctx) => { ctx.job = (b as Body).job_id; },
+  },
+  {
+    claim: 'GET /v1/embed-jobs',
+    request: () => ({ method: 'GET', path: '/v1/embed-jobs' }),
+    status: [200],
+    expect: (b, ctx) => isObj(b) && Array.isArray(b.embed_jobs) && b.embed_jobs.length === 1
+      && b.embed_jobs[0].job_id === ctx.job,
+  },
+  {
+    claim: 'GET /v1/embed-jobs/{id}',
+    request: (ctx) => ({ method: 'GET', path: `/v1/embed-jobs/${ctx.job}` }),
+    status: [200],
+    expect: (b, ctx) => isObj(b) && b.job_id === ctx.job && b.status === 'processing'
+      && b.input_dataset_id === ctx.dataset && b.model === 'embed-english-v3.0'
+      && b.truncate === 'END' && b.name === 'conf-job'
+      // The vendor's EmbedJob schema has NO `id` key; emitting one would be invented surface.
+      && b.id === undefined,
+  },
+  {
+    claim: 'POST /v1/embed-jobs/{id}/cancel',
+    request: (ctx) => ({ method: 'POST', path: `/v1/embed-jobs/${ctx.job}/cancel` }),
+    status: [200],
+    // `embedJobs.cancel` is declared `-> void`: an empty body, and the STATE moved.
+    expect: (b) => isObj(b) && Object.keys(b).length === 0,
+  },
+  {
+    claim: 'DELETE /v1/connectors/{id}',
+    request: (ctx) => ({ method: 'DELETE', path: `/v1/connectors/${ctx.connector}` }),
+    status: [200],
+    expect: (b) => isObj(b) && Object.keys(b).length === 0,
+  },
+  {
+    claim: 'DELETE /v1/datasets/{id}',
+    request: (ctx) => ({ method: 'DELETE', path: `/v1/datasets/${ctx.dataset}` }),
+    status: [200],
+    // Cohere's delete answers an EMPTY object, not the `{deleted:true}` envelope most vendors send.
+    expect: (b) => isObj(b) && Object.keys(b).length === 0,
+  },
+];
+
+/** The vendor not-found envelope this twin answers unmodeled surface with — written as a LITERAL
+ *  predicate here, never imported from the handler that produces it. Cohere's error body has
+ *  EXACTLY ONE key. */
+function isNotFoundEnvelope(status: number, body: unknown): boolean {
+  return status === 404 && isObj(body) && typeof body.message === 'string' && Object.keys(body).length === 1;
+}
+
+/** A concrete request for a router-census entry — `{id}` becomes a deliberately nonexistent id, so
+ *  a LIVE branch answers its own 404 while a MISSING branch answers the router's 404. Both are
+ *  not-found envelopes, which is exactly why this direction only asks "is anything OTHER than a
+ *  not-found envelope served here, unclaimed?" */
+function censusRequest(entry: { method: string; path: string }): { method: string; path: string; body?: unknown } {
+  const path = entry.path.replace('{id}', 'zzz-nonexistent-zzz');
+  return { method: entry.method, path, body: entry.method === 'GET' || entry.method === 'DELETE' ? undefined : {} };
+}
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkCohereConformance(opts: { root?: string } = {}): Promise<CohereConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'cohere-conf-'));
+  const owned = opts.root === undefined;
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const H = (r: { method: string; path: string; body?: unknown }, at = root): Promise<CohereResponseEnvelope> =>
+    handleCohereTwinRequest({ method: r.method, path: r.path, root: at, ...(r.body === undefined ? {} : { body: JSON.stringify(r.body) }) });
+
+  try {
+    // ── DIRECTION 1+2: probe ⇄ claim, a two-way bijection ──────────────────────────────
+    const claims = new Set(COHERE_TWIN_SNAPSHOT);
+    const probed = new Set(PROBES.map((p) => p.claim));
+    for (const p of PROBES) if (!claims.has(p.claim)) fail('probe.unclaimed', `probe certifies "${p.claim}", which is not in COHERE_TWIN_SNAPSHOT`);
+    for (const c of COHERE_TWIN_SNAPSHOT) if (!probed.has(c)) fail('claim.unprobed', `claimed endpoint "${c}" has no probe — an unexercised claim certifies nothing`);
+    if (probed.size !== PROBES.length) fail('probe.duplicate', 'two probes certify the same claim');
+
+    const ctx: Ctx = {};
+    // The oauth-authorize probe needs a connector that HAS an oauth configuration, which the
+    // ordinary `POST /v1/connectors` probe deliberately does not create (its own claim is the
+    // no-auth shape). Seeding it here keeps each probe's assertions about one thing.
+    const oauthCreate = await H({ method: 'POST', path: '/v1/connectors', body: { name: 'conf-oauth', url: 'https://example.test/oauth', oauth: { client_id: 'cid-1', client_secret: 's', authorize_url: 'https://auth.example.test/authorize', token_url: 'https://auth.example.test/token' } } });
+    ctx.oauthConnector = ((oauthCreate.body as Body)?.connector?.id) as string | undefined;
+    if (ctx.oauthConnector === undefined) fail('seed.oauth_connector', `seeding an oauth connector failed: ${oauthCreate.status} ${JSON.stringify(oauthCreate.body).slice(0, 200)}`);
+
+    for (const p of PROBES) {
+      checksRun++;
+      const res = await H(p.request(ctx));
+      if (!p.status.includes(res.status)) {
+        fail('probe.status', `${p.claim}: status ${res.status} (expected one of ${p.status.join(', ')}) — body ${JSON.stringify(res.body).slice(0, 200)}`);
+        continue;
+      }
+      let outcomeOk: boolean;
+      try { outcomeOk = p.expect(res.body, ctx); } catch (e) { outcomeOk = false; void e; }
+      if (!outcomeOk) {
+        fail('probe.outcome', `${p.claim}: status was right but the body is not what a live handler produces — ${JSON.stringify(res.body).slice(0, 300)}`);
+        continue;
+      }
+      p.capture?.(res.body, ctx);
+    }
+
+    // The deletes above must have actually removed the rows — a delete that answered `{}` while
+    // leaving the row standing would satisfy its own probe. This reads the state AFTER.
+    checksRun++;
+    const afterDelete = await H({ method: 'GET', path: '/v1/datasets' });
+    if (JSON.stringify((afterDelete.body as Body)?.datasets) !== '[]') {
+      fail('delete.effective', `DELETE /v1/datasets/{id} answered 200 but the row is still listed: ${JSON.stringify(afterDelete.body).slice(0, 200)}`);
+    }
+    checksRun++;
+    // The three `{}`-bodied claims (both deletes and the cancel) are each satisfied by a handler
+    // that answered `{status:200, body:{}}` with its `applyTwinWrite` deleted, so each needs a
+    // post-hoc re-read. The connectors one was missing (§9 round 1, finding 3) — and its probe runs
+    // AFTER the list probe, so nothing else re-read connectors either.
+    const afterConnectorDelete = await H({ method: 'GET', path: '/v1/connectors' });
+    const remaining = (afterConnectorDelete.body as Body)?.connectors as Body[] | undefined;
+    // The oauth-seeded connector is the only one that must survive; the probed one must be gone.
+    if (!Array.isArray(remaining) || remaining.some((c) => c.id === ctx.connector)) {
+      fail('connector_delete.effective', `DELETE /v1/connectors/{id} answered 200 but the row is still listed: ${JSON.stringify(afterConnectorDelete.body).slice(0, 200)}`);
+    }
+    if ((afterConnectorDelete.body as Body)?.total_count !== remaining?.length) {
+      fail('connector_delete.effective', `total_count (${String((afterConnectorDelete.body as Body)?.total_count)}) disagrees with the listed rows after a delete`);
+    }
+
+    checksRun++;
+    const jobAfterCancel = await H({ method: 'GET', path: `/v1/embed-jobs/${ctx.job}` });
+    if ((jobAfterCancel.body as Body)?.status !== 'cancelling') {
+      fail('cancel.effective', `POST /v1/embed-jobs/{id}/cancel answered 200 but the status did not move: ${JSON.stringify(jobAfterCancel.body).slice(0, 200)}`);
+    }
+
+    // ── DIRECTION 3: router → claim (served-but-unclaimed surface) ─────────────────────
+    const censusRoot = mkdtempSync(join(tmpdir(), 'cohere-conf-census-'));
+    try {
+      for (const entry of COHERE_ROUTER_SURFACE) {
+        checksRun++;
+        const key = `${entry.method} ${entry.path}`;
+        const res = await H(censusRequest(entry), censusRoot);
+        const inert = isNotFoundEnvelope(res.status, res.body);
+        if (!inert && !claims.has(key)) {
+          fail('router.unclaimed', `${key} serves a response (${res.status}) but COHERE_TWIN_SNAPSHOT never claims it`);
+        }
+      }
+      // …and the other way: a claim the router census has never heard of is a claim about a
+      // branch that does not exist.
+      const census = new Set(COHERE_ROUTER_SURFACE.map((e) => `${e.method} ${e.path}`));
+      for (const c of COHERE_TWIN_SNAPSHOT) if (!census.has(c)) fail('claim.unrouted', `claimed endpoint "${c}" is not a branch in COHERE_ROUTER_SURFACE`);
+    } finally {
+      rmSync(censusRoot, { recursive: true, force: true });
+    }
+
+    // ── The vendor's error envelopes, asserted as LITERALS ─────────────────────────────
+    checksRun++;
+    const badBody = await H({ method: 'POST', path: '/v2/chat', body: { model: 'command-a-03-2025' } });
+    const bb = badBody.body as Body;
+    // ONE key. Asserting the ABSENCE of `error`/`type`/`code` is what stops the envelope drifting
+    // toward the OpenAI shape, which no positive assertion would catch.
+    if (badBody.status !== 400 || !isObj(bb) || Object.keys(bb).join(',') !== 'message'
+      || bb.message !== 'invalid request: messages is required') {
+      fail('error.invalid_request', `a v2 chat with no messages did not yield Cohere's bare {message} 400 — got ${badBody.status} ${JSON.stringify(badBody.body).slice(0, 300)}`);
+    }
+
+    checksRun++;
+    const badModel = await H({ method: 'POST', path: '/v2/chat', body: { model: 'gpt-4o', messages: [{ role: 'user', content: 'x' }] } });
+    const bm = badModel.body as Body;
+    if (badModel.status !== 404 || bm?.message !== "model 'gpt-4o' not found, make sure the correct model ID was used and that you have access to the model.") {
+      fail('error.model_not_found', `an unknown model did not yield the live 404 envelope — got ${badModel.status} ${JSON.stringify(badModel.body).slice(0, 300)}`);
+    }
+
+    checksRun++;
+    const nf = await H({ method: 'GET', path: '/v1/nonexistent' });
+    if (!isNotFoundEnvelope(nf.status, nf.body)) fail('error.not_found', `an unknown route did not answer the 404 error envelope — got ${nf.status}`);
+
+    checksRun++;
+    const unauthorized = await handleCohereTwinRequest({ method: 'GET', path: '/v1/models', root, headers: {} });
+    const ub = unauthorized.body as Body;
+    if (unauthorized.status !== 401 || Object.keys(ub ?? {}).join(',') !== 'message') {
+      fail('error.unauthorized', `a request with no bearer token did not 401 with the bare {message} envelope — got ${unauthorized.status}`);
+    }
+
+    checksRun++;
+    const readOnly = await handleCohereTwinRequest({ method: 'POST', path: '/v2/chat', body: JSON.stringify(CHAT), root, readOnly: true });
+    if (readOnly.status !== 405) fail('error.read_only', `a read-only twin did not refuse a write with 405 — got ${readOnly.status}`);
+  } finally {
+    if (owned) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: violations.length === 0, checksRun, claimed: COHERE_TWIN_SNAPSHOT.length, violations };
+}