@volter/twin-cohere 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @volter/twin-cohere
+
+> **Legacy connector helpers:** this package still has callable helpers using the retired v1
+> `syncPull` API. Those paths require migration before use on the current kernel;
+> older helper descriptions below do not establish current compatibility. Check the
+> [generated index](../../../generated/INDEX.md) for protocol standing and use the
+> [shared model](../../../docs/concepts/the-model.md) for current state semantics.
+
+A local, faithful **Cohere** twin your real `cohere-ai` client and your real `@ai-sdk/cohere`
+provider talk to **unmodified** — point either at the twin and chat (v1 *and* v2), streaming, tool
+calls, embeddings, rerank, classify, tokenize, the model catalog, datasets, connectors and embed
+jobs all work. Built on the shared `@volter/world-core` kernel; see [the model](../../../docs/concepts/the-model.md) for storage and branching;
+no parallel side store.
+
+```ts
+import { CohereClientV2 } from 'cohere-ai';
+import { createCohereTwinServer } from '@volter/twin-cohere';
+
+const { port } = createCohereTwinServer({});
+const client = new CohereClientV2({ token: 'cohere-twin', environment: `http://127.0.0.1:${port}` });
+
+const res = await client.chat({
+  model: 'command-a-03-2025',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+// res.message.content[0].text starts with "[twin-stub:…]" — deterministic, clearly labeled.
+// res.finishReason === 'COMPLETE' — Cohere's UPPER-CASE reason, not OpenAI's 'stop'.
+```
+
+…and the Vercel AI SDK provider, through its own `baseURL` option:
+
+```ts
+import { createCohere } from '@ai-sdk/cohere';
+const cohere = createCohere({ apiKey: 'cohere-twin', baseURL: `http://127.0.0.1:${port}/v2` });
+```
+
+## Cohere is its OWN dialect — the refusals are the point
+
+Cohere is **not** OpenAI-compatible, and a twin built by copying an OpenAI-shaped pack's
+permissiveness would be wrong in exactly the places that matter. What distinguishes it, all of it
+modeled here and asserted by a named capability:
+
+| | Cohere | the OpenAI-shaped mistake |
+|---|---|---|
+| error body | a **bare** `{ "message": "…" }` — one key | `{ error: { message, type, code } }` |
+| finish reason | `COMPLETE` / `TOOL_CALL` / `MAX_TOKENS` / `STOP_SEQUENCE` / `ERROR` / `TIMEOUT` | `stop` / `tool_calls` |
+| chat response | one `message`, one `finish_reason`, no `choices`, no `object`, no `created` | a `choices[]` array |
+| usage | `usage.billed_units.*` **and** `usage.tokens.*` (v2); `meta.billed_units.*` (v1) | a flat `prompt_tokens` trio |
+| v1 vs v2 | **two different protocols** on one host — v1 chat takes a `message` STRING and answers flat `text`; v2 takes `messages[]` | "v2 is v1 with a prefix" |
+| embed | v2 **requires** `input_type`; v1 does not, but still refuses a v3/v4 model without one | one shape for both |
+| embed response | v1 defaults to `embeddings_floats` (a flat `number[][]`); v2 always answers `embeddings_by_type` | always by-type |
+| rerank | v2 `documents` must be **strings**; v1 accepts objects and has `return_documents` | one shape for both |
+| enums | UPPER-CASE — `truncate: NONE\|START\|END`, `tool_choice: REQUIRED\|NONE`, `safety_mode: CONTEXTUAL\|STRICT\|OFF` | lower-case |
+| `check-api-key` | a **POST**, despite the name | a GET |
+| streaming | v2 is SSE terminated by `data: [DONE]`; v1 is newline-delimited JSON tagged `event_type` | one wire |
+
+## The generative-stub design (be honest)
+
+The twin **cannot run the model** — there are no weights here. So every generative endpoint returns
+a **deterministic STUB** that is unmistakably a twin stub (it carries a `[twin-stub:<model>]` marker
+and echoes your prompt). It **never** pretends to be real model output, and that is an *invariant*
+rather than a gap: a realism upgrade that reached for a real model, local or remote, would cost
+serve-path determinism, which is the property the whole pack rests on.
+
+What **is** faithful is the **entire protocol envelope**:
+
+- the v2 response shape — `{ id, finish_reason, message:{role, content?, tool_plan?, tool_calls?}, usage:{billed_units,tokens} }`
+- **v2 streaming** — `message-start` → `content-start` → `content-delta`× → `content-end` →
+  `message-end` → the literal `data: [DONE]`, plus the `tool-plan-delta` /
+  `tool-call-start` / `tool-call-delta` / `tool-call-end` sequence when tools fire. Note the
+  shapes DIFFER between `content-start` (a full content block) and `content-delta` (just `{text}`),
+  which is exactly what `@ai-sdk/cohere`'s discriminated union rejects if you get it wrong. Driven
+  through an injected sink — no real sockets in the handler.
+- **v1 streaming** — the different wire: NDJSON objects tagged `event_type`
+  (`stream-start` / `text-generation` / `stream-end`), with no `[DONE]` sentinel.
+- **tool calls** — `tool_calls[{id, type:'function', function:{name, arguments}}]` with a
+  `tool_plan` alongside, `finish_reason: 'TOOL_CALL'`, and `tool_choice: 'NONE'` genuinely
+  forbidding a call
+- **all six `embedding_types`** — `float`, `int8`, `uint8`, `binary`, `ubinary`, `base64`, every one
+  a real view of the SAME vector (binary packs one BIT per dimension, 8 to a byte)
+- **deterministic token counts**, and byte-identical responses on replay
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- `GET /v1/models` (+ `/v1/models/{name}`) — the real catalog (ids, context lengths and
+  `endpoints` read from Cohere's own models page), filterable by `endpoint`
+- **Datasets** — create (name + type as query parameters, the file as multipart) / list (filtered by
+  `datasetType`, `validationStatus`, `limit`, `offset`) / retrieve / delete / `usage`, with Cohere's
+  closed 12-member `DatasetType` set enforced
+- **Connectors** — create / list (with `total_count`) / retrieve / **partial** PATCH / delete, plus
+  `oauth/authorize`, which builds the redirect from the connector's OWN stored configuration and
+  **refuses** a connector that has none
+- **Embed jobs** — create against a dataset that must actually exist, list, retrieve, cancel, with
+  the `processing → cancelling` state machine and a terminal job refusing a second cancel
+- **The tokenizer vocabulary** — `POST /v1/tokenize` OBSERVES each (id → segment) pair into the
+  event log and `POST /v1/detokenize` folds that projection. This is what makes detokenize honest
+  rather than a fabrication: the twin can only detokenize ids it has genuinely issued, and refuses
+  the rest with a 400 instead of inventing text.
+
+## Coverage
+
+**Partial and honest.** The capability manifest
+(`src/cohere-capabilities.ts`) is the vendor's **real** surface as the denominator, enumerated
+top-down from `cohere-ai@8.1.0`'s own operation inventory — every `client.<sub>.<method>` in its
+`reference.md`, cross-checked against the `core.url.join(..., "<path>")` literal in each generated
+client module.
+
+**One unit, throughout:** those **45 SDK methods** resolve to **42 distinct (method, path)
+operations** over 32 paths. The twin serves **27** of the 42 — the same 27 pairs that make up
+`COHERE_ROUTER_SURFACE` and the conformance snapshot. The **15** it does not: `POST /v1/generate`,
+`POST /v1/summarize`, `POST /v2/parse`, `POST /v2/audio/transcriptions`, the four `/v2/batches`
+operations and the seven `/v1/finetuning/*` operations — every one enumerated as a `todo`, because a
+denominator that omitted them would be a self-portrait rather than a measurement. Run
+`bun scripts/manifest-baseline-one.ts cohere` for the current numbers.
+
+**Wire-shape provenance.** Every response shape comes from the SDKs' own transcriptions, read from
+their published npm tarballs during the build: `cohere-ai@8.1.0`'s
+`serialization/**/*.d.ts` `interface Raw` blocks (which carry the **snake_case wire keys** — the TS
+types are camelCase and would mislead), cross-checked against `@ai-sdk/cohere@4.0.35`'s zod schemas,
+the stricter second transcription for chat/embed/rerank. Where the two disagree in strictness the
+twin satisfies **both**, and `src/cohere-sdk.integration.test.ts` drives both clients unmodified to
+prove it — including streaming through `cohere-ai`'s **own** SSE decoder and its typed error classes.
+
+### The stub is the answer, not a shortfall
+
+Chat returns a deterministic, clearly-labeled stub; embed returns deterministic pseudo-vectors
+seeded from the input hash; rerank scores with a deterministic lexical token-overlap heuristic; and
+classify uses a deterministic per-(input, label) hash normalized so the confidences sum to 1. Those
+**are** the twin's answers — the protocol envelope around each (shape, dimensionality, per-type
+quantization, descending order, `[0,1]` range, search-unit billing, determinism) is faithful, and
+only the learned meaning is absent. Every capability is `done` or `todo`.
+
+Two filed `todo`s worth naming:
+
+- **`cohere.tokenize.bpe_vocabulary`** — tokenize with Cohere's real published BPE vocabulary
+  (vendored tokenizer JSON) instead of the learned word-segment map. The tokenizers are published,
+  downloadable, static JSON, and this pack already serves their URLs.
+- **`cohere.deployments.aws_planes`** — `cohere-ai` also ships `BedrockClient` / `SagemakerClient` /
+  `AwsClient`, which SigV4-sign requests to **AWS** hosts rather than `api.cohere.com`. The pack does
+  not claim those hosts today, so a regionally-deployed client fails closed rather than being
+  half-served.
+
+### No UI mirror
+
+**The API is the product.** When someone does Cohere's core job they write code — chat, embed,
+rerank and classify calls from an application — not open a browser. Cohere's dashboard is incidental
+tooling for API keys, billing and usage graphs, the same shape as Anthropic's and OpenAI's consoles,
+and its playground is a REPL over the same API this twin already serves rather than a place work is
+stored. So this pack ships **no mirror** and declares **no UI capabilities**; coverage is API +
+connector. (`ui-scope.json` records `needsUi: false` with this reasoning.)
+
+## Scripting behaviour (scenario handlers)
+
+The default stub is generic. To script the exact deterministic answers a flow under test needs, put
+MSW-shaped rules in the world directory's `handlers/cohere.json` — run by the **kernel's** one
+scenario engine (`@volter/world-core` `scenario.ts`) with this pack's adapter, never a bespoke engine:
+
+```jsonc
+{
+  "handlers": [
+    { "on": { "userTextIncludes": "refund", "hasTool": "create_job" },
+      "respond": { "toolPlan": "I will file it.", "toolCalls": { "name": "create_job", "arguments": { "title": "Refund order" } } },
+      "once": true },
+    { "on": { "userTextIncludes": "throttle" }, "respond": { "error": { "type": "rate_limit", "retryAfter": 5 } } }
+  ]
+}
+```
+
+`on` accepts `modelEquals`, `userTextIncludes`, `anyTextIncludes`, `hasTool`, `toolResultFor`,
+`lastMessageIsToolResult` and the kernel's `nthCall`. `respond` accepts `text`, `thinking`,
+`toolPlan`, `toolCalls`, `finishReason` (Cohere's UPPER-CASE set), or an `error` that becomes a
+**real HTTP status** — a scripted `rate_limit` is a genuine 429 with a `retry-after` header, so
+`cohere-ai` raises `Cohere.TooManyRequestsError` rather than handing you a 200 with an error-shaped
+body. A malformed handlers file fails server startup **loudly**; it never silently falls back.
+
+**Mind the SDK's own retries when scripting an error.** `cohere-ai` auto-retries `408`/`429`/`5xx`
+**twice** (`requestWithRetries.js`, `DEFAULT_MAX_RETRIES = 2`) and *sleeps* for `retry-after`, so the
+engine fires three times per caller-visible call and a large `retryAfter` stalls the caller for real
+wall-clock seconds. Two corollaries: keep `retryAfter` small (the shipped defaults use `1`), and
+treat `once: true` beside an `error` as a **footgun** — the SDK's retry gets a normal 200, silently
+turning your scripted failure into a success.
+
+The read doors are `GET /twin` (what this twin is and how to script it) and `GET /twin/scenario`
+(active handlers, match counts, and the features of recent misses). Both are read-only: the handler
+**file** is the only write surface.
+
+## CLI
+
+```bash
+bun packages/twin/cohere/src/cli.ts serve [--port N] [--root DIR] [--read-only] [--scenario FILE]
+bun packages/twin/cohere/src/cli.ts conformance [--root DIR]
+```
+
+`--read-only` refuses every **POST/PATCH/DELETE** with a 405 while reads keep serving. The refusal is method-based, so a read-only Cohere world cannot chat or tokenize either — a defensible reading of "no POSTs", but not the same as "every mutation". `conformance` runs the
+offline check: one real request per claimed endpoint asserting the outcome a live handler produces,
+a two-way probe⇄claim bijection, and a router census pass that fails on served-but-unclaimed
+surface.
+
+## Interception and world wiring
+
+- **Hosts:** exactly one — `api.cohere.com`. That is the only entry in `cohere-ai`'s
+  `CohereEnvironment`, and `@ai-sdk/cohere`'s default `baseURL` is that host plus `/v2`. Declared on
+  the pack descriptor, so `volter-world` routes an unmodified SDK's traffic here with zero edits.
+- **Endpoint env: none, and that is a ruling rather than an omission.** Neither SDK reads a base-URL
+  environment variable — `cohere-ai` takes the override as the `baseUrl`/`environment` **constructor**
+  option and reads only `CO_API_KEY` from the environment; `@ai-sdk/cohere` takes `options.baseURL`
+  and reads only `COHERE_API_KEY`. Inventing a `COHERE_BASE_URL` nothing reads would make
+  `volter-world covers` report a world covered while the app still talked to the real vendor.
+- **Adoption:** both official clients (`cohere-ai`, `@ai-sdk/cohere`) and **both** credential stems
+  (`COHERE`, `CO`), because the two SDKs read different variables. No npm scope is claimed —
+  Cohere owns none, and `@ai-sdk/` belongs to Vercel and is shared by every provider.
+
+## Rate budget
+
+Live calls (the connector only) go through one guarded client with a durable, fail-closed spend
+ledger. Cohere publishes scalar per-minute limits **per endpoint and per key class**
+(<https://docs.cohere.com/docs/rate-limits>, read 2026-08-31): chat 20/min on a trial key and 500 on
+production, rerank 10/1,000, EmbedJob 5/50, tokenize 100/2,000, "default (other)" 500. The **trial**
+numbers bind, and they are *below* the kernel's undeclared fallback — so this declaration is
+deliberately **tighter** than the fallback rather than more permissive: 20 weighted units per 60s at
+a default weight of 2, i.e. 10 calls a minute. The per-endpoint weights reproduce the vendor's own
+scarcity (embed-jobs 8, rerank 4, chat/default 2, tokenize 1). The window bounds the 60-second
+average and does **not** pace; the vendor's first `429`/`retry-after` becomes a persisted cooldown
+that survives a restart.

package/defaults/handlers.json

@@ -0,0 +1,26 @@
+{
+  "$comment": "Starter handlers copied into your world by `volter-world init` — YOURS now: edit or delete (regenerate a fresh world for fresh defaults). Grammar: {on, respond, once?, scope?, phase?}; `GET <twin-url>/twin` explains this twin; `GET <twin-url>/twin/scenario` shows active handlers + matches/misses (unmatched asks also ledger their features — `volter-world tail`). These match narrowly on the [twin-demo] tag so they never shadow your app's real asks. They script `POST /v2/chat` only; datasets, connectors and embed jobs are STATE — create those through the vendor's own API instead.",
+  "handlers": [
+    {
+      "id": "demo-answer",
+      "on": { "userTextIncludes": "[twin-demo] hello" },
+      "respond": { "text": "Hello from a scripted handler. This twin's chat completions are yours to script: edit handlers/cohere.json in this world directory." }
+    },
+    {
+      "id": "demo-tool-call",
+      "$comment": "A scripted tool call: fires once, only when the caller offers a create_job tool. Cohere sends a `tool_plan` alongside its tool calls, so the handler scripts one.",
+      "on": { "userTextIncludes": "[twin-demo] tool", "hasTool": "create_job" },
+      "once": true,
+      "respond": {
+        "toolPlan": "I will call create_job to handle this request.",
+        "toolCalls": { "name": "create_job", "arguments": { "title": "Demo job from a scripted handler", "instructions": "Replace me: edit handlers/cohere.json" } }
+      }
+    },
+    {
+      "id": "demo-rate-limit",
+      "$comment": "A scripted API FAILURE, so retry/backoff paths can be exercised without waiting for a real 429. This is a genuine HTTP 429 with a retry-after header \u2014 cohere-ai raises Cohere.TooManyRequestsError, not a 200 carrying an error body. MIND THE SDK'S OWN RETRIES: cohere-ai auto-retries 429/408/5xx twice (requestWithRetries.js, DEFAULT_MAX_RETRIES = 2) and SLEEPS for retry-after, so this handler costs the caller ~2s of real wall clock before the typed error surfaces \u2014 retryAfter is 1 rather than 5 for exactly that reason. Corollary: `once: true` beside an `error` is a FOOTGUN, because the SDK's retry gets a normal 200 and your scripted failure silently becomes a success.",
+      "on": { "userTextIncludes": "[twin-demo] throttle" },
+      "respond": { "error": { "type": "rate_limit", "retryAfter": 1 } }
+    }
+  ]
+}

package/dist/defaults/handlers.json

@@ -0,0 +1,26 @@
+{
+  "$comment": "Starter handlers copied into your world by `volter-world init` — YOURS now: edit or delete (regenerate a fresh world for fresh defaults). Grammar: {on, respond, once?, scope?, phase?}; `GET <twin-url>/twin` explains this twin; `GET <twin-url>/twin/scenario` shows active handlers + matches/misses (unmatched asks also ledger their features — `volter-world tail`). These match narrowly on the [twin-demo] tag so they never shadow your app's real asks. They script `POST /v2/chat` only; datasets, connectors and embed jobs are STATE — create those through the vendor's own API instead.",
+  "handlers": [
+    {
+      "id": "demo-answer",
+      "on": { "userTextIncludes": "[twin-demo] hello" },
+      "respond": { "text": "Hello from a scripted handler. This twin's chat completions are yours to script: edit handlers/cohere.json in this world directory." }
+    },
+    {
+      "id": "demo-tool-call",
+      "$comment": "A scripted tool call: fires once, only when the caller offers a create_job tool. Cohere sends a `tool_plan` alongside its tool calls, so the handler scripts one.",
+      "on": { "userTextIncludes": "[twin-demo] tool", "hasTool": "create_job" },
+      "once": true,
+      "respond": {
+        "toolPlan": "I will call create_job to handle this request.",
+        "toolCalls": { "name": "create_job", "arguments": { "title": "Demo job from a scripted handler", "instructions": "Replace me: edit handlers/cohere.json" } }
+      }
+    },
+    {
+      "id": "demo-rate-limit",
+      "$comment": "A scripted API FAILURE, so retry/backoff paths can be exercised without waiting for a real 429. This is a genuine HTTP 429 with a retry-after header \u2014 cohere-ai raises Cohere.TooManyRequestsError, not a 200 carrying an error body. MIND THE SDK'S OWN RETRIES: cohere-ai auto-retries 429/408/5xx twice (requestWithRetries.js, DEFAULT_MAX_RETRIES = 2) and SLEEPS for retry-after, so this handler costs the caller ~2s of real wall clock before the typed error surfaces \u2014 retryAfter is 1 rather than 5 for exactly that reason. Corollary: `once: true` beside an `error` is a FOOTGUN, because the SDK's retry gets a normal 200 and your scripted failure silently becomes a success.",
+      "on": { "userTextIncludes": "[twin-demo] throttle" },
+      "respond": { "error": { "type": "rate_limit", "retryAfter": 1 } }
+    }
+  ]
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-cohere CLI: serve the Cohere API twin or run conformance. 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 is no `mirror` command.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createCohereTwinServer } from "./cohere-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted chat turns (JSON handlers file)
+if (cmd === 'serve') {
+    const s = await createCohereTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+    process.stdout.write(`cohere twin (v1 + v2; model output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+    const { checkCohereConformance } = await import("./cohere-conformance.js");
+    const report = await checkCohereConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    // NON-ZERO on an unknown command. `world-cohere bogus` exiting 0 makes a typo in a world's boot
+    // script look like a successful start (§9 round two, MINOR 10).
+    process.stdout.write('Usage: world-cohere serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,55 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const COHERE_BUDGET_WINDOW_MS = 60000;
+/**
+ * Weighted units allowed inside one window. 20/60s at the default weight of 2 is 10 calls a
+ * minute — HALF Cohere's tightest broadly-applicable published limit (chat, 20 req/min on a trial
+ * key) and tighter than the kernel's undeclared fallback, because Cohere's trial limits are below
+ * that fallback.
+ */
+export declare const COHERE_BUDGET_CEILING = 20;
+/** Seconds. A `retry-after` above this means the org is throttled hard — fail loudly, don't sleep. */
+export declare const COHERE_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for the arithmetic. */
+export declare const COHERE_CALL_WEIGHTS: {
+    /** `POST /v1/embed-jobs` — a 5 req/min trial allowance, the scarcest endpoint this pack drives. */
+    readonly embedJob: 8;
+    /** `POST /v2/rerank`, `POST /v1/rerank` — a 10 req/min trial allowance. */
+    readonly rerank: 4;
+    /** Chat and everything unclassified — the 20 req/min trial anchor. */
+    readonly other: 2;
+    /** `POST /v1/tokenize` — a 100 req/min trial allowance, the most generous endpoint modeled. */
+    readonly tokenize: 1;
+};
+/** THE PACK'S DECLARATION — pure data, the only Cohere-specific thing in the whole budget. */
+export declare const COHERE_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Cohere.
+ * An unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export declare function cohereCallWeight(method: string, path: string): number;
+/** Where Cohere's ledger lives. Token-keyed and cwd-independent by default (the limit is per API
+ *  key, so a cwd-scoped ledger would hand the same key a fresh allowance in every checkout,
+ *  worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export declare function cohereBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for Cohere's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type CohereBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * Cohere's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof CohereBudget` in `liveCohereExecute` means "a budget that
+ * accounts against COHERE's ledger under COHERE's ceiling": another vendor's `RateBudget` (with
+ * its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export declare class CohereBudget extends RateBudget {
+    constructor(opts?: CohereBudgetOptions);
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as CohereBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as CohereBudgetErrorKind } from '@volter/world-core';
+export type CohereBudgetReservation = RateBudgetReservation;
+export type CohereBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/cohere-budget.js

@@ -0,0 +1,171 @@
+// Cohere's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveCohereExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// Cohere DOES publish scalar per-minute limits, per endpoint AND per key class. Live-read from
+// https://docs.cohere.com/docs/rate-limits on 2026-08-31:
+//   • Chat: TRIAL key 20 req/min across every Command model; PRODUCTION key 500 req/min for
+//     Command A / R+ / R / R7B (the newer A-variants are sales-gated).
+//   • Rerank: TRIAL 10 req/min; production 1,000 req/min.
+//   • EmbedJob: TRIAL 5 req/min; production 50 req/min.
+//   • Audio Transcriptions: TRIAL 5 req/min.
+//   • Tokenize: TRIAL 100 req/min; production 2,000 req/min.
+//   • Embed (text): 2,000 INPUTS/min on both key classes; Embed (images) 5 inputs/min trial.
+//   • Parse and "Default (other)": 500 req/min on both classes.
+//
+// THE TRIAL NUMBERS BIND, and they are LOWER than the kernel's undeclared fallback. That fallback
+// (`DEFAULT_RATE_BUDGET`) is 60 units / 60s at defaultWeight 2 — 30 calls a minute — which already
+// exceeds Cohere's 20/min trial chat limit and is 6x its 5/min EmbedJob limit. A pack must only be
+// MORE PERMISSIVE than the fallback when the live first-party source justifies it; here the source
+// justifies being TIGHTER, so this declaration is tighter.
+//
+// The ceiling is 20 weighted units per 60s. At the default weight of 2 that is 10 calls a minute:
+// half of the tightest limit that applies to a plain call (chat, 20/min trial) and comfortably
+// under the 5/min EmbedJob floor once that endpoint's own weight is applied.
+//
+// The window bounds the 60-second AVERAGE; it does NOT pace (the kernel refuses, it never sleeps).
+// So the honest claim is "bounds the minute and converts the vendor's first 429/`retry-after` into
+// a hard stop", not "refuses before the vendor ever 429s".
+//
+// ── HOW THE WEIGHTS WERE CHOSEN ─────────────────────────────────────────────────────────────
+// Cohere counts REQUESTS per endpoint, and the per-endpoint limits differ by two orders of
+// magnitude, so pricing by endpoint is reproducing the vendor's own scheme rather than proxying
+// it. Each weight below is the fallback weight scaled by how much scarcer that endpoint's trial
+// allowance is than chat's:
+//   • `POST /v1/embed-jobs` costs 8 — a 5/min trial allowance, four times scarcer than chat's 20.
+//   • `POST /v2/rerank` / `POST /v1/rerank` cost 4 — a 10/min trial allowance, twice as scarce.
+//   • `POST /v2/chat` / `POST /v1/chat` cost 2 (the default) — the 20/min anchor.
+//   • `POST /v1/tokenize` costs 1 — a 100/min trial allowance, five times more generous.
+//
+// Everything unclassified costs `defaultWeight`; nothing is ever free. WHICH published row binds an
+// unclassified call is a deliberate choice worth stating, because the arithmetic is otherwise
+// uncheckable against the source it cites (§9 round 1, m5): the endpoints this connector actually
+// drives — `GET /v1/{datasets,connectors,embed-jobs}` and the connector CRUD — fall under Cohere's
+// "Default (other)" row at 500/min, NOT under chat's 20/min. They are nonetheless priced at the
+// CHAT anchor, i.e. 25x tighter than the vendor allows. That is deliberate: the per-endpoint
+// figures for this set are not individually published, and the cost asymmetry is stark — a
+// too-tight default costs a refused call plus a one-line declaration, a too-loose one costs days of
+// lockout.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'cohere';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const COHERE_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 20/60s at the default weight of 2 is 10 calls a
+ * minute — HALF Cohere's tightest broadly-applicable published limit (chat, 20 req/min on a trial
+ * key) and tighter than the kernel's undeclared fallback, because Cohere's trial limits are below
+ * that fallback.
+ */
+export const COHERE_BUDGET_CEILING = 20;
+/** Seconds. A `retry-after` above this means the org is throttled hard — fail loudly, don't sleep. */
+export const COHERE_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for the arithmetic. */
+export const COHERE_CALL_WEIGHTS = {
+    /** `POST /v1/embed-jobs` — a 5 req/min trial allowance, the scarcest endpoint this pack drives. */
+    embedJob: 8,
+    /** `POST /v2/rerank`, `POST /v1/rerank` — a 10 req/min trial allowance. */
+    rerank: 4,
+    /** Chat and everything unclassified — the 20 req/min trial anchor. */
+    other: 2,
+    /** `POST /v1/tokenize` — a 100 req/min trial allowance, the most generous endpoint modeled. */
+    tokenize: 1,
+};
+/** THE PACK'S DECLARATION — pure data, the only Cohere-specific thing in the whole budget. */
+export const COHERE_RATE_BUDGET = {
+    windowMs: COHERE_BUDGET_WINDOW_MS,
+    ceiling: COHERE_BUDGET_CEILING,
+    defaultWeight: COHERE_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: COHERE_BUDGET_MAX_RETRY_AFTER_S,
+    // Ordered, first match wins. Every pattern is ANCHORED at both ends so a longer path cannot
+    // borrow a cheaper endpoint's price.
+    rules: [
+        { match: '^POST /v1/embed-jobs$', weight: COHERE_CALL_WEIGHTS.embedJob },
+        { match: '^POST /v2/rerank$', weight: COHERE_CALL_WEIGHTS.rerank },
+        { match: '^POST /v1/rerank$', weight: COHERE_CALL_WEIGHTS.rerank },
+        { match: '^POST /v1/tokenize$', weight: COHERE_CALL_WEIGHTS.tokenize },
+    ],
+    reason: 'Cohere publishes scalar per-minute limits per endpoint AND per key class ' +
+        '(https://docs.cohere.com/docs/rate-limits, read 2026-08-31): chat 20 req/min on a TRIAL key ' +
+        'and 500 on production; rerank 10 trial / 1,000 production; EmbedJob 5 trial / 50 production; ' +
+        'tokenize 100 trial / 2,000 production; embed metered in inputs (2,000/min); "default (other)" ' +
+        '500. The TRIAL numbers bind, and they are BELOW the kernel fallback (30 calls/min), so this ' +
+        'declaration is deliberately TIGHTER than the fallback rather than more permissive: 20 weighted ' +
+        'units / 60s at defaultWeight 2 is 10 calls a minute, half the 20/min trial chat limit. Weights ' +
+        'reproduce the vendor\'s own per-endpoint scarcity — embed-jobs 8 (5/min), rerank 4 (10/min), ' +
+        'chat/default 2 (20/min), tokenize 1 (100/min). UNCLASSIFIED calls take the chat anchor rather ' +
+        'than the "default (other)" row that actually governs them (the connector\'s own endpoints are ' +
+        'in that 500/min bucket), i.e. 25x tighter than the vendor allows — deliberate, because those ' +
+        'per-endpoint figures are not individually published and a too-tight default costs a refused ' +
+        'call while a too-loose one costs days of lockout. The window bounds the 60s AVERAGE and does ' +
+        'not pace; the 429 / retry-after cooldown is the backstop for a shorter enforcement horizon.',
+};
+// Declared at module load, so merely importing this module (which `cohere-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET, which here is strictly LOOSER (30 calls/min vs 10), so the ordering genuinely
+// matters — constructing through the subclass below (which imports this module) is what makes it a
+// non-issue in practice.
+declareRateBudget(VENDOR, COHERE_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Cohere.
+ * An unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function cohereCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+    // `execute('post', …)` really does issue a POST and must be priced as one.
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the
+ * query.
+ *
+ * NORMALIZED, because the anchored rules are otherwise trivially evaded: `fetch` upper-cases a
+ * known method before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule
+ * would otherwise price as a read; and a trailing slash makes a path miss a `$` anchor while most
+ * routers treat it as the same endpoint. Both are input variations, not attacks, and either one
+ * silently voids the "scarce endpoints are priced up" claim the ceiling rests on.
+ */
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    const raw = at === -1 ? path : path.slice(0, at);
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where Cohere's ledger lives. Token-keyed and cwd-independent by default (the limit is per API
+ *  key, so a cwd-scoped ledger would hand the same key a fresh allowance in every checkout,
+ *  worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function cohereBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * Cohere's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof CohereBudget` in `liveCohereExecute` means "a budget that
+ * accounts against COHERE's ledger under COHERE's ceiling": another vendor's `RateBudget` (with
+ * its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class CohereBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as CohereBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,14 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+/**
+ * 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 declare const COHERE_AREAS: readonly ["audio", "auth", "batches", "chat", "chat_v1", "classify", "conformance", "connector", "connectors", "datasets", "deployments", "determinism", "embed", "embed_jobs", "errors", "finetuning", "generate", "models", "parse", "rerank", "summarize", "tokenize"];
+export declare const COHERE_CAPABILITIES: CapabilitySpec[];
+export declare function cohereCapabilities(): Promise<CapabilityReport>;