@volter/twin-cohere 0.1.0

package/dist/src/cohere-conformance.d.ts

@@ -0,0 +1,17 @@
+export type ConformanceViolation = {
+    check: string;
+    detail: string;
+};
+export type CohereConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    claimed: number;
+    violations: ConformanceViolation[];
+};
+/** 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 declare const COHERE_TWIN_SNAPSHOT: ReadonlyArray<string>;
+/** Run the offline conformance checks against a fresh temp root. */
+export declare function checkCohereConformance(opts?: {
+    root?: string;
+}): Promise<CohereConformanceReport>;

package/dist/src/cohere-conformance.js

@@ -0,0 +1,464 @@
+// 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 } from "./cohere-twin.js";
+const isObj = (v) => !!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 = [
+    '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',
+];
+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 = [
+    {
+        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).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) => typeof t === 'number' && t > 0),
+        capture: (b, ctx) => { ctx.tokens = b.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) => Array.isArray(m.endpoints) && m.endpoints.includes('rerank'))
+            && b.models.some((m) => 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.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.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) => 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.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, body) {
+    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) {
+    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 = {}) {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'cohere-conf-'));
+    const owned = opts.root === undefined;
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => violations.push({ check, detail });
+    const H = (r, at = root) => 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 = {};
+        // 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?.connector?.id);
+        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;
+            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?.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?.connectors;
+        // 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?.total_count !== remaining?.length) {
+            fail('connector_delete.effective', `total_count (${String(afterConnectorDelete.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?.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;
+        // 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;
+        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;
+        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 };
+}

package/dist/src/cohere-connector.d.ts

@@ -0,0 +1,150 @@
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { CohereBudget, type CohereBudgetOptions } from './cohere-budget.js';
+/** The real Cohere API base — `CohereEnvironment.Production` in cohere-ai@8.1.0's
+ *  `environments.d.ts`, which is the ONLY host either SDK ships. */
+export declare const COHERE_API_BASE = "https://api.cohere.com";
+/**
+ * The injected real-Cohere boundary. `request` issues ONE Cohere REST call:
+ *   method  — 'GET' | 'POST' | 'PATCH' | 'DELETE'
+ *   path    — e.g. '/v1/datasets' or '/v1/embed-jobs/<id>/cancel'
+ *   body    — JSON body for POST/PATCH (omitted otherwise)
+ * Returns the parsed JSON: one of Cohere's per-collection list envelopes, a single object, or its
+ * `{ message }` error envelope.
+ */
+export type CohereExecute = (method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<unknown>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveCohereOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: CohereBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: CohereBudgetOptions;
+};
+/**
+ * A live executor against the real Cohere REST API (the user's own API key). Sends
+ * `Authorization: Bearer <key>` — the scheme BOTH SDKs use (cohere-ai's `BearerAuthProvider`,
+ * which falls back to the `CO_API_KEY` env var, and @ai-sdk/cohere's provider, which reads
+ * `COHERE_API_KEY`). Never imported by the pack's own serving path — only constructed by a caller
+ * that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live api.cohere.com request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `CohereBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 signal becomes a persisted cooldown that makes every later call fail fast
+ * WITHOUT touching Cohere. There is deliberately no OPTION to disable the guard, and no value a
+ * caller can pass for `budget` that yields an unguarded client. What that does NOT claim is
+ * immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an
+ * injected clock, restores the allowance, because the same seam tests need cannot be denied to a
+ * determined caller in the same process. See `cohere-budget.ts` and the kernel's `rateBudget.ts`
+ * header for the limits of the guarantee.
+ */
+export declare function liveCohereExecute(apiKey: string, base?: string, opts?: LiveCohereOptions): CohereExecute;
+/** Map a real-Cohere Dataset → a twin sync resource. Every field the vendor's `Dataset` schema
+ *  declares REQUIRED (`id`, `name`, `created_at`, `updated_at`, `dataset_type`,
+ *  `validation_status`) is carried; a pulled row that lost one would be unparseable by the
+ *  official SDK the moment the twin served it back. */
+export declare function mapDataset(d: Record<string, unknown>): SyncResource;
+/** Map a real-Cohere Connector → a twin sync resource. */
+export declare function mapConnector(c: Record<string, unknown>): SyncResource;
+/**
+ * Map a real-Cohere EmbedJob → a twin sync resource.
+ *
+ * The vendor's key for an embed job is `job_id`, NOT `id` — there is no `id` on the schema at all.
+ * Subjecting the resource under `d.id` would make every pulled job land under the string
+ * "undefined" and collapse the whole collection onto one row.
+ */
+export declare function mapEmbedJob(j: Record<string, unknown>): SyncResource;
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export declare function pullCohereState(execute: CohereExecute): Promise<SyncResource[]>;
+export declare function pollTimestamp(): string;
+/**
+ * Pull from real Cohere and fold into the twin (mirror seeding). syncPull's shadow-diff makes a
+ * re-pull of identical state a no-op.
+ */
+export declare function syncCohereFromReal(execute: CohereExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * Why this op is a KNOWN, filed, un-pushable gap — or undefined if the connector can push it.
+ *
+ * This answers only for gaps that have been REASONED ABOUT. An operation the connector has simply
+ * never heard of is NOT this function's business: it is a coding gap, and `assertPushable` throws
+ * on it, loudly. Routing every unknown verb through the skip-and-count path would turn a genuine
+ * unhandled write into an anonymous integer that ticks up and tells nobody.
+ */
+export declare function unpushableReason(op: string, subjectType?: string): string | undefined;
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Cohere REST
+ * surface for every write op the twin records:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.update → PATCH  <collection>/:id
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export declare function cohereRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+};
+/**
+ * Push ONE pending action to REAL Cohere via the injected executor. Returns the real external id.
+ * WRITES TO THE REAL ACCOUNT.
+ */
+export declare function pushCohereAction(execute: CohereExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): Promise<{
+    externalId: string;
+}>;
+/**
+ * Push the twin's PENDING local actions to real Cohere and CONFIRM each: for every pending action,
+ * call the real API; on success, confirmAction records the confirmed fields as an observed event
+ * and maps action → event (suppressing the local projection — counted exactly once). Idempotency:
+ * a confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * COMPOUND-ACTION AUDIT (the `confirmAction` hazard in ADDING_A_TWIN.md §5): every action this
+ * connector pushes is SINGLE-RESOURCE — a connector or embed-job create/update, an embed-job
+ * cancel, a dataset or connector delete — so `fields` alone is the complete post-state and no
+ * `additionalObservations` are needed for the payload. The one write this twin makes that touches
+ * several resources at once is a TOKENIZE (one `token.observe` per fresh segment) — and those are
+ * separate single-resource actions on a type that is refused push-wide, so the hazard cannot
+ * arise here.
+ */
+export declare function pushPendingCohereActions(execute: CohereExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        subjectId: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * Cohere and confirm it, then (2) PULL all modeled collections back and fold them into the event
+ * log. Pushing first means the pull observes the twin's own writes as confirmed external state (no
+ * double-count). Re-running with no pending writes and identical real state is a no-op (push 0,
+ * deltasAppended 0). Same code path offline (fake executor) and live (real key).
+ */
+export declare function fullSyncCohere(execute: CohereExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        subjectId: string;
+        reason: string;
+    }>;
+    observed: number;
+    deltasAppended: number;
+    collections: number;
+}>;