@volter/twin-cohere 0.1.0

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

@@ -0,0 +1,226 @@
+/**
+ * Cohere's API error envelope. It is a BARE object with ONE key — exactly as
+ * @ai-sdk/cohere@4.0.35's `cohereErrorDataSchema` transcribes it:
+ *   `cohereErrorDataSchema = z.object({ message: z.string() })`
+ * There is no `error` wrapper, no `type`, and no `code`. A twin that emitted OpenAI's
+ * `{ error: { message, type } }` here would be caught by that schema on every failure path.
+ */
+export type CohereApiError = {
+    message: string;
+};
+/** A v2 chat message as the caller sends it. `content` is a string OR a content-part array. */
+export type CohereMessageV2 = {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content?: string | Array<Record<string, unknown>> | null;
+    tool_calls?: CohereToolCallV2[] | null;
+    tool_plan?: string | null;
+    tool_call_id?: string | null;
+};
+/**
+ * `ToolCallV2`. The vendor's own serializer declares `function?: ToolCallV2Function.Raw | null`,
+ * with `name` and `arguments` optional INSIDE it — but this type deliberately declares all three
+ * REQUIRED, because that is what the twin EMITS and what a caller may rely on.
+ *
+ * The narrowing is the right way round: @ai-sdk/cohere's `cohereChatResponseSchema` requires
+ * `function.name` and `function.arguments` on every tool call, and its `tool-call-start` chunk
+ * schema requires them too — so a twin that emitted the vendor's loosest legal shape would fail
+ * the stricter of its two clients. Narrower on OUTPUT, never on input. (§9 round 1, finding 9
+ * caught the comment here saying the opposite of the code.)
+ */
+export type CohereToolCallV2 = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/**
+ * The reason a chat request finished. Cohere's values are UPPER-CASE and are its own set — this
+ * is the single most conspicuous place an OpenAI-shaped copy goes wrong (`stop` / `tool_calls`
+ * are NOT Cohere values). Source: `api/types/ChatFinishReason.d.ts`.
+ */
+export type CohereFinishReason = 'COMPLETE' | 'STOP_SEQUENCE' | 'MAX_TOKENS' | 'TOOL_CALL' | 'ERROR' | 'TIMEOUT';
+export declare const COHERE_FINISH_REASONS: readonly CohereFinishReason[];
+/** `Usage` — TWO nested counters, `billed_units` and `tokens`, not a flat `prompt_tokens` trio. */
+export type CohereUsage = {
+    billed_units: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    tokens: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+/** A content item on an assistant response message. */
+export type CohereAssistantContentItem = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    thinking: string;
+};
+/** `AssistantMessageResponse`. */
+export type CohereAssistantMessage = {
+    role: 'assistant';
+    content?: CohereAssistantContentItem[];
+    tool_plan?: string;
+    tool_calls?: CohereToolCallV2[];
+};
+/** The unary `POST /v2/chat` envelope — NO `choices`, NO `object`, NO `created`. */
+export type CohereChatV2Response = {
+    id: string;
+    finish_reason: CohereFinishReason;
+    message: CohereAssistantMessage;
+    usage: CohereUsage;
+};
+/**
+ * The v2 streaming event `type` values, in the order `cohereChatChunkSchema`'s discriminated
+ * union declares them. The twin emits a subset; the SET is the vendor's.
+ */
+export type CohereStreamEventType = 'message-start' | 'content-start' | 'content-delta' | 'content-end' | 'tool-plan-delta' | 'tool-call-start' | 'tool-call-delta' | 'tool-call-end' | 'citation-start' | 'citation-end' | 'message-end' | 'debug';
+/**
+ * v1's OWN finish-reason set. It is NOT the v2 `ChatFinishReason` set, which is the sort of
+ * conflation that looks harmless until a value crosses over: `NonStreamedChatResponse.finish_reason`
+ * is `FinishReason` — all EIGHT of `COMPLETE | STOP_SEQUENCE | ERROR | ERROR_TOXIC | ERROR_LIMIT |
+ * USER_CANCEL | MAX_TOKENS | TIMEOUT` (`api/types/FinishReason.d.ts`), with **no `TOOL_CALL`** and
+ * with three members v2 does not have. Typing the v1 body with the v2 union invited `TOOL_CALL`
+ * onto a response the vendor's union rejects (§9 round 1, finding 9) — and the first correction
+ * then transcribed only six of the eight, which §9 round two caught: this const is public API, so a
+ * consumer validating a v1 body against a short set rejects two legal vendor values.
+ * The twin only ever emits `COMPLETE` on v1, which is valid in this set, in the v2 set, and in the
+ * narrower `ChatStreamEndEventFinishReason` the v1 stream terminator uses.
+ */
+export type CohereV1FinishReason = 'COMPLETE' | 'STOP_SEQUENCE' | 'ERROR' | 'ERROR_TOXIC' | 'ERROR_LIMIT' | 'USER_CANCEL' | 'MAX_TOKENS' | 'TIMEOUT';
+export declare const COHERE_V1_FINISH_REASONS: readonly CohereV1FinishReason[];
+/**
+ * `NonStreamedChatResponse`. v1 answers a FLAT `text` string with `meta` (not `usage`), and takes
+ * a single `message` string plus `chat_history` — it is a different protocol from v2, sharing
+ * only the host. Modeling it as "v2 with a prefix" is the trap.
+ */
+export type CohereChatV1Response = {
+    text: string;
+    generation_id: string;
+    response_id: string;
+    finish_reason: CohereV1FinishReason;
+    chat_history: Array<{
+        role: string;
+        message: string;
+    }>;
+    meta: CohereApiMeta;
+};
+export type CohereApiMeta = {
+    api_version: {
+        version: string;
+    };
+    billed_units: Partial<{
+        input_tokens: number;
+        output_tokens: number;
+        search_units: number;
+        classifications: number;
+        images: number;
+        image_tokens: number;
+        pages: number;
+    }>;
+    tokens?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+    warnings?: string[];
+};
+/** The six `EmbeddingType` values Cohere accepts. `float` is the default and the only one
+ *  @ai-sdk/cohere requests. */
+export declare const COHERE_EMBEDDING_TYPES: readonly ["float", "int8", "uint8", "binary", "ubinary", "base64"];
+export type CohereEmbeddingType = (typeof COHERE_EMBEDDING_TYPES)[number];
+/** The five `EmbedInputType` values. v2 embed REQUIRES one; v1 does not. */
+export declare const COHERE_INPUT_TYPES: readonly ["search_document", "search_query", "classification", "clustering", "image"];
+export type CohereInputType = (typeof COHERE_INPUT_TYPES)[number];
+/** `V2EmbedRequestTruncate` / `EmbedRequestTruncate` — UPPER-CASE, unlike most vendors' enums. */
+export declare const COHERE_TRUNCATE: readonly ["NONE", "START", "END"];
+/** `EmbedByTypeResponse` — v2 keys the vectors BY TYPE under `embeddings`. */
+export type CohereEmbedV2Response = {
+    id: string;
+    embeddings: Partial<Record<CohereEmbeddingType, number[][] | string[]>>;
+    texts: string[];
+    response_type: 'embeddings_by_type';
+    meta: CohereApiMeta;
+};
+/** `EmbedFloatsResponse` — v1's DEFAULT answer puts a flat `number[][]` at `embeddings`. The two
+ *  shapes are not interchangeable, and the v1 caller only gets the by-type shape when it asks for
+ *  `embedding_types`. */
+export type CohereEmbedV1FloatsResponse = {
+    id: string;
+    embeddings: number[][];
+    texts: string[];
+    response_type: 'embeddings_floats';
+    meta: CohereApiMeta;
+};
+export type CohereRerankResult = {
+    index: number;
+    relevance_score: number;
+    document?: {
+        text: string;
+    };
+};
+export type CohereRerankResponse = {
+    id: string;
+    results: CohereRerankResult[];
+    meta: CohereApiMeta;
+};
+export type CohereClassification = {
+    id: string;
+    input: string;
+    prediction: string;
+    predictions: string[];
+    confidence: number;
+    confidences: number[];
+    labels: Record<string, {
+        confidence: number;
+    }>;
+    classification_type: 'single-label' | 'multi-label';
+};
+export type CohereClassifyResponse = {
+    id: string;
+    classifications: CohereClassification[];
+    meta: CohereApiMeta;
+};
+export type CohereTokenizeResponse = {
+    tokens: number[];
+    token_strings: string[];
+    meta: CohereApiMeta;
+};
+export type CohereDetokenizeResponse = {
+    text: string;
+    meta: CohereApiMeta;
+};
+export type CohereCheckApiKeyResponse = {
+    valid: boolean;
+    organization_id: string;
+    owner_id: string;
+};
+/** `CompatibleEndpoint` — the closed set of endpoint names a model card may list. */
+export declare const COHERE_ENDPOINTS: readonly ["chat", "embed", "classify", "summarize", "rerank", "rate", "generate"];
+export type CohereEndpoint = (typeof COHERE_ENDPOINTS)[number];
+export type CohereModelCard = {
+    name: string;
+    endpoints: CohereEndpoint[];
+    finetuned: boolean;
+    context_length: number;
+    tokenizer_url: string | null;
+    default_endpoints: CohereEndpoint[];
+    is_deprecated?: boolean;
+};
+/**
+ * A single Server-Sent Event the streaming path emits (collected in tests, socketed by the
+ * server). `data` is the JSON payload; the terminator is signalled with `done: true` — cohere-ai's
+ * `core.Stream` is constructed with `eventShape: { type: 'sse', streamTerminator: '[DONE]' }`, so
+ * `data: [DONE]` is what ends a v2 chat stream.
+ */
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** A sink the streaming path writes events into (an injected collector in tests / a real HTTP SSE
+ *  writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/dist/src/cohere-types.js

@@ -0,0 +1,40 @@
+// Shared wire-shape types for the Cohere API surface. These mirror the real vendor JSON shapes
+// (not an SDK's internal types — the twin never imports a vendor SDK at runtime; the SDKs are
+// exercised only in *.test.ts). Kept minimal but faithful.
+//
+// COHERE SPEAKS ITS OWN DIALECT. It is NOT OpenAI-compatible and copying an OpenAI-shaped pack's
+// permissiveness would be exactly the bug: Cohere's chat response has no `choices` array, its
+// finish reasons are UPPER-CASE (`COMPLETE`/`TOOL_CALL`/`MAX_TOKENS`), its usage lives under
+// `usage.billed_units`/`usage.tokens` (v2) or `meta.billed_units` (v1), and its error envelope is
+// a BARE `{ "message": "…" }` with no `error` wrapper, no `type`, no `code`.
+//
+// PROVENANCE for every shape below: the two SDKs this pack is built against, read from their
+// published npm tarballs during this build (2026-08-31):
+//   • cohere-ai@8.1.0 — the Fern-generated client. The WIRE keys come from its
+//     `serialization/**/*.d.ts` `interface Raw` blocks (Fern's serializers map snake_case wire
+//     keys onto camelCase TS properties, so the TS types alone would be MISLEADING here):
+//     `V2ChatResponse`, `AssistantMessageResponse`, `Usage`, `UsageTokens`, `UsageBilledUnits`,
+//     `ChatFinishReason`, `V2ChatStreamResponse` (+ its twelve event members),
+//     `EmbedByTypeResponse`, `EmbedByTypeResponseEmbeddings`, `EmbedFloatsResponse`,
+//     `V2RerankResponse`, `V2RerankResponseResultsItem`, `ClassifyResponse`, `TokenizeResponse`,
+//     `DetokenizeResponse`, `CheckApiKeyResponse`, `ListModelsResponse`, `GetModelResponse`,
+//     `ApiMeta`, `ApiMetaBilledUnits`, `ApiMetaApiVersion`, `NonStreamedChatResponse`, `Dataset`,
+//     `Connector`, `EmbedJob`, `ToolCallV2`.
+//   • @ai-sdk/cohere@4.0.35 — the SECOND independent transcription of the same wire, and the
+//     STRICTER one for chat/embed/rerank: `cohereChatResponseSchema`, `cohereChatChunkSchema`
+//     (a `z.discriminatedUnion("type", …)` over the stream events), `cohereUsageSchema`,
+//     `cohereTextEmbeddingResponseSchema`, `cohereRerankingResponseSchema` and
+//     `cohereErrorDataSchema`. Where the two disagree in strictness the twin satisfies BOTH.
+export const COHERE_FINISH_REASONS = ['COMPLETE', 'STOP_SEQUENCE', 'MAX_TOKENS', 'TOOL_CALL', 'ERROR', 'TIMEOUT'];
+export const COHERE_V1_FINISH_REASONS = ['COMPLETE', 'STOP_SEQUENCE', 'ERROR', 'ERROR_TOXIC', 'ERROR_LIMIT', 'USER_CANCEL', 'MAX_TOKENS', 'TIMEOUT'];
+// ── Embed ───────────────────────────────────────────────────────────────────────────────
+/** The six `EmbeddingType` values Cohere accepts. `float` is the default and the only one
+ *  @ai-sdk/cohere requests. */
+export const COHERE_EMBEDDING_TYPES = ['float', 'int8', 'uint8', 'binary', 'ubinary', 'base64'];
+/** The five `EmbedInputType` values. v2 embed REQUIRES one; v1 does not. */
+export const COHERE_INPUT_TYPES = ['search_document', 'search_query', 'classification', 'clustering', 'image'];
+/** `V2EmbedRequestTruncate` / `EmbedRequestTruncate` — UPPER-CASE, unlike most vendors' enums. */
+export const COHERE_TRUNCATE = ['NONE', 'START', 'END'];
+// ── Models ──────────────────────────────────────────────────────────────────────────────
+/** `CompatibleEndpoint` — the closed set of endpoint names a model card may list. */
+export const COHERE_ENDPOINTS = ['chat', 'embed', 'classify', 'summarize', 'rerank', 'rate', 'generate'];

package/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export { handleCohereTwinRequest, buildChatV2, streamChatV2, COHERE_ROUTER_SURFACE, COHERE_CLOSED_SETS } from './cohere-twin.js';
+export type { CohereRequest, CohereResponseEnvelope, ChatV2Args } from './cohere-twin.js';
+export { createCohereTwinFetch, createCohereTwinServer, type CohereTwinFetchOptions } from './cohere-server.js';
+export { cohereScenarioAdapter, createCohereScenarioEngine, loadCohereScenarioDocument, realizeCohereRespond } from './cohere-scenario.js';
+export type { CohereScenarioEngine, CohereScenarioRequest, CohereScenarioRespond, ScenarioToolCall, ScriptedResult } from './cohere-scenario.js';
+export { COHERE_MODELS, COHERE_ENDPOINTS, findModel, modelServes } from './cohere-models.js';
+export { base64Embedding, classifyText, COHERE_OUTPUT_DIMENSIONS, cohereId, contentToText, countInputTokens, embedDimensions, estimateTokens, fnv1a, lastUserText, preferredTokenId, pseudoEmbedding, quantizeEmbedding, rerankScore, segmentText, stubAssistantText, stubToolArguments, stubToolCall, stubToolPlan, stubV1Text, toolCallId, toolNames, } from './cohere-stub.js';
+export { COHERE_EMBEDDING_TYPES, COHERE_ENDPOINTS as COHERE_COMPATIBLE_ENDPOINTS, COHERE_FINISH_REASONS, COHERE_INPUT_TYPES, COHERE_TRUNCATE, COHERE_V1_FINISH_REASONS, } from './cohere-types.js';
+export type { CohereApiError, CohereApiMeta, CohereAssistantContentItem, CohereAssistantMessage, CohereChatV1Response, CohereChatV2Response, CohereClassifyResponse, CohereEmbedV1FloatsResponse, CohereEmbedV2Response, CohereEmbeddingType, CohereFinishReason, CohereInputType, CohereMessageV2, CohereModelCard, CohereRerankResponse, CohereToolCallV2, CohereUsage, CohereV1FinishReason, SseEvent, SseSink, } from './cohere-types.js';
+export { COHERE_API_BASE, cohereRequestForAction, fullSyncCohere, liveCohereExecute, mapConnector, mapDataset, mapEmbedJob, pollTimestamp, pullCohereState, pushCohereAction, pushPendingCohereActions, syncCohereFromReal, unpushableReason, } from './cohere-connector.js';
+export type { CohereExecute, LiveCohereOptions } from './cohere-connector.js';
+export { COHERE_BUDGET_CEILING, COHERE_BUDGET_MAX_RETRY_AFTER_S, COHERE_BUDGET_WINDOW_MS, COHERE_CALL_WEIGHTS, COHERE_RATE_BUDGET, CohereBudget, CohereBudgetError, cohereBudgetPath, cohereCallWeight, } from './cohere-budget.js';
+export type { CohereBudgetErrorKind, CohereBudgetOptions, CohereBudgetReservation, CohereBudgetSnapshot } from './cohere-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,84 @@
+// @volter/twin-cohere — the Cohere twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. Cohere's API is TWO protocols on one host: the v1 surface
+// (`/v1/chat` with a single `message` string, `/v1/embed` answering flat float vectors,
+// `/v1/rerank`, `/v1/classify`, `/v1/tokenize`, `/v1/models`, datasets, connectors, embed jobs)
+// and the v2 surface (`/v2/chat` with structured `messages[]`, `/v2/embed` keyed by embedding
+// type, `/v2/rerank`). Both are modeled — vendor-faithfully, and as the DIFFERENT protocols they
+// are rather than as a versioned alias. (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.)
+//
+// THE HONEST CARVE-OUT: the twin cannot run the model, so every generative endpoint returns a
+// DETERMINISTIC STUB (clearly labeled `[twin-stub:<model>]`), never pretending to be real
+// inference. Everything around it — the wire protocol — is faithful. (Conformance + capability
+// tooling live in @volter/world-tooling, a dev dependency — NOT re-exported here, per E2.)
+export { handleCohereTwinRequest, buildChatV2, streamChatV2, COHERE_ROUTER_SURFACE, COHERE_CLOSED_SETS } from "./cohere-twin.js";
+export { createCohereTwinFetch, createCohereTwinServer } from "./cohere-server.js";
+export { cohereScenarioAdapter, createCohereScenarioEngine, loadCohereScenarioDocument, realizeCohereRespond } from "./cohere-scenario.js";
+export { COHERE_MODELS, COHERE_ENDPOINTS, findModel, modelServes } from "./cohere-models.js";
+export { base64Embedding, classifyText, COHERE_OUTPUT_DIMENSIONS, cohereId, contentToText, countInputTokens, embedDimensions, estimateTokens, fnv1a, lastUserText, preferredTokenId, pseudoEmbedding, quantizeEmbedding, rerankScore, segmentText, stubAssistantText, stubToolArguments, stubToolCall, stubToolPlan, stubV1Text, toolCallId, toolNames, } from "./cohere-stub.js";
+export { COHERE_EMBEDDING_TYPES, COHERE_ENDPOINTS as COHERE_COMPATIBLE_ENDPOINTS, COHERE_FINISH_REASONS, COHERE_INPUT_TYPES, COHERE_TRUNCATE, COHERE_V1_FINISH_REASONS, } from "./cohere-types.js";
+export { COHERE_API_BASE, cohereRequestForAction, fullSyncCohere, liveCohereExecute, mapConnector, mapDataset, mapEmbedJob, pollTimestamp, pullCohereState, pushCohereAction, pushPendingCohereActions, syncCohereFromReal, unpushableReason, } from "./cohere-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveCohereExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Cohere's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `CohereBudgetError` by type; there is deliberately no export that disables the guard.
+export { COHERE_BUDGET_CEILING, COHERE_BUDGET_MAX_RETRY_AFTER_S, COHERE_BUDGET_WINDOW_MS, COHERE_CALL_WEIGHTS, COHERE_RATE_BUDGET, CohereBudget, CohereBudgetError, cohereBudgetPath, cohereCallWeight, } from "./cohere-budget.js";
+import { COHERE_RATE_BUDGET as RATE_BUDGET } from "./cohere-budget.js";
+export const pack = {
+    vendor: 'cohere',
+    // The SAME object cohere-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-cohere',
+    // The subject types this twin projects. `token` is the LEARNED TOKENIZER VOCABULARY that
+    // `/v1/tokenize` observes and `/v1/detokenize` folds — twin-local state with no vendor
+    // endpoint, which is why the connector refuses to push it type-wide.
+    resources: ['dataset', 'connector', 'embed_job', 'token'],
+    specSource: 'Cohere API v1 + v2, grounded in the two installed SDKs (cohere-ai@8.1.0 — the Fern-generated client, whose serialization/**/*.d.ts `interface Raw` blocks carry the snake_case WIRE keys — and @ai-sdk/cohere@4.0.35, whose zod schemas are the stricter second transcription of chat/embed/rerank); envelope-faithful, model output is a labeled stub',
+    description: 'Cohere twin — faithful v1 AND v2 protocol envelopes (chat with SSE and NDJSON streaming, tool calls, UPPER-CASE finish reasons, two-level usage), deterministic embeddings across all six embedding_types, rerank/classify, a learned tokenizer vocabulary, the real model catalog, and stateful datasets / connectors / embed jobs; generative output is a labeled stub.',
+    // cohere-ai addresses the same origin with `v1/…` and `v2/…` paths (`core.url.join(environment,
+    // "v2/chat")`); @ai-sdk/cohere's default baseURL is 'https://api.cohere.com/v2'. The common
+    // prefix both share is the origin root, so the browser-routing prefix is '/'.
+    browserRouting: { apiPathPrefix: '/', loaderHost: 'https://api.cohere.com' },
+    // ADOPTION — how an app repo betrays that it talks to this vendor (§7 point 11), declared HERE
+    // rather than in the central SDK_TWINS / ENV_STEM_VENDORS maps (declaring a fact in both homes
+    // throws at module init).
+    //   • sdks — the TWO official npm clients of the surface this pack models: Cohere's own
+    //     Fern-generated client and the Vercel AI SDK provider. `cohere-ai` was on covers.ts's
+    //     UNKNOWN_DEP_KNOWN_SERVICES list (the curated "well-known client with NO twin pack" set)
+    //     until this pack was born; that entry is deleted in the same commit, because
+    //     scripts/packless-claims.test.ts is RED on any name both packless-listed and pack-claimed.
+    //   • envStems — the two SDKs read DIFFERENT variables and both are claimed: cohere-ai's
+    //     `BearerAuthProvider` falls back to `CO_API_KEY` (`const ENV_TOKEN = "CO_API_KEY"`), while
+    //     @ai-sdk/cohere calls `loadApiKey({ environmentVariableName: 'COHERE_API_KEY' })`. Claiming
+    //     only one would let an app configured for the other read as uncovered. The stems are
+    //     written bare because the overlay lowercases and the detector strips non-alphanumerics.
+    //   • NO `scopes` entry: Cohere owns no npm scope. `@ai-sdk/` belongs to Vercel and is shared by
+    //     every provider, so claiming it would attribute openai/anthropic/mistral traffic here.
+    adoption: {
+        // Cohere's official Python SDK (`cohere-ai` on npm, `cohere` on PyPI).
+        pypi: ['cohere'],
+        sdks: ['cohere-ai', '@ai-sdk/cohere'],
+        envStems: ['COHERE', 'CO'],
+    },
+    // INTERCEPTION (§7 point 8). ONE host: `CohereEnvironment` in cohere-ai@8.1.0's
+    // environments.d.ts declares exactly `Production: "https://api.cohere.com"` and nothing else —
+    // no regional or staging siblings — and @ai-sdk/cohere's default baseURL is that host plus
+    // `/v2`. The Bedrock/SageMaker clients the SDK also ships (`AwsClient`, `BedrockClient`,
+    // `SagemakerClient`) address AWS hosts, which are a different vendor's plane and deliberately
+    // NOT claimed here.
+    hosts: [{ host: 'api.cohere.com' }],
+    // WORLD WIRING (§7 point 12) — the ruling is NONE, and it is grounded, not skipped.
+    // NEITHER SDK reads a base-URL environment variable. cohere-ai takes the override as a
+    // CONSTRUCTOR option (`baseUrl` / `environment`, resolved through `core.Supplier.get`) and the
+    // only env var anywhere in its source is `CO_API_KEY` (plus the AWS credential names its Bedrock
+    // client uses); @ai-sdk/cohere takes `options.baseURL` and reads only `COHERE_API_KEY`.
+    // Inventing a `COHERE_BASE_URL` would make `covers` report the world covered — any app-read env
+    // counts — while the app, reading no such var, still talked to the real vendor. Interception is
+    // therefore host-based, via the `hosts` entry above, which is the truth.
+    endpointEnvNone: 'neither official SDK reads a base-URL env var: cohere-ai@8.1.0 takes the override as the `baseUrl`/`environment` CONSTRUCTOR option and reads only CO_API_KEY from the environment (auth/BearerAuthProvider.js), and @ai-sdk/cohere@4.0.35 takes `options.baseURL` and reads only COHERE_API_KEY. Interception is host-based on api.cohere.com; inventing a COHERE_BASE_URL nothing reads would make `covers` claim a world it does not cover.',
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@volter/twin-cohere",
+  "version": "0.1.0",
+  "description": "Local Cohere twin — a faithful, stateful local Cohere API your real cohere-ai / @ai-sdk/cohere client talks to unmodified. Both protocol versions are modeled (v1 chat/embed/rerank/classify/tokenize + v2 chat/embed/rerank), with deterministic stubs for model output and vendor-faithful envelopes, streaming, errors and refusals. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "defaults",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/cohere"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/cohere#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-cohere": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/cohere": "^4.0.35",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "cohere-ai": "^8.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "cohere",
+    "command",
+    "rerank",
+    "embed",
+    "llm"
+  ]
+}

package/src/cli.ts

@@ -0,0 +1,30 @@
+#!/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.ts';
+
+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.ts');
+  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;
+}