@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-twin.js

@@ -0,0 +1,1647 @@
+// Moonshot twin REQUEST HANDLER — the canonical Moonshot (Kimi) API surface for the twin.
+// Contract: handleMoonshotTwinRequest({method, path, body}) -> {status, body}. It is the faithful
+// Moonshot API the real clients (the standard `openai` SDK pointed at
+// `https://api.moonshot.ai/v1`, the `anthropic` SDK pointed at `https://api.moonshot.ai/anthropic`,
+// and plain HTTP callers) talk to UNMODIFIED — Moonshot ships no SDK of its own; its documented
+// integration path is the standard OpenAI/Anthropic clients with a swapped base URL
+// (platform.kimi.ai/docs/overview, read 2026-09-16).
+//
+// THE HONEST DESIGN: the twin cannot run the model, so the three inference endpoints
+// (`POST /v1/chat/completions`, `POST /v1/responses`, `POST /anthropic/v1/messages`) return a
+// DETERMINISTIC STUB completion (moonshot-stub.ts) clearly labeled a twin stub — it NEVER pretends
+// to be real model output. But the ENTIRE PROTOCOL ENVELOPE is vendor-faithful: all three response
+// shapes, all three streaming grammars (OpenAI chunks, Responses SSE events with
+// `sequence_number`, Anthropic message events), tool_calls / tool_use, finish_reason /
+// stop_reason, `reasoning_content` / thinking blocks, and Moonshot's cache-split usage. The
+// genuinely stateful + static surface is real:
+//   • GET /v1/models            — static catalog (moonshot-models.ts)
+//   • POST/GET/DELETE /v1/files (+ /content) — stateful (kernel action log)
+//   • POST/GET /v1/batches (+ /cancel)       — stateful
+//   • GET /v1/users/me/balance  — stateful (a mutable account balance)
+// plus the deterministic stateless helpers: POST /v1/tokenizers/estimate-token-count,
+// POST /v1/signatures/verify, POST /v1/tools/{search,search_pro,fetch}.
+//
+// TWO PATH PREFIXES, BOTH REAL: Moonshot serves its OpenAI-compatible surface under `/v1` and its
+// Anthropic-compatible surface under `/anthropic/v1` on the same host (api.moonshot.ai). The
+// Anthropic surface's error envelope is `{ type:'error', error:{type,message}, request_id? }` —
+// a DIFFERENT envelope from `/v1`'s `{ error: { message, type, code? } }` — and its streaming
+// grammar is Anthropic's event-name SSE, not OpenAI's `data:`-only frames.
+//
+// State lives in the kernel action log (D1): all writes are local actions, reads are the
+// projection. No real Moonshot is ever called from this path (D4). Streaming uses an INJECTED
+// sink — no real sockets / setTimeout (D5 verify is offline + deterministic).
+import { applyTwinWrite, projectResources, resolveSubjectId, worldNow } from '@volter/world-core';
+import { findModel, K26_THINKING_TYPES, K27_THINKING_TYPES, MOONSHOT_MODELS, REASONING_EFFORTS, } from "./moonshot-models.js";
+import { buildChatUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, stableSuffix, stubAssistantText, stubCachedTokens, stubFetchedMarkdown, stubJsonObject, stubReasoningContent, stubSearchResults, stubSignature, stubToolCall, } from "./moonshot-stub.js";
+import { realizeMoonshotRespond } from "./moonshot-scenario.js";
+const SERVICE = 'moonshot';
+/** The base path Moonshot's OpenAI-compatible surface hangs off. The Anthropic-compatible
+ *  surface hangs off MESSAGES_PREFIX; both are served by the same host. */
+export const MOONSHOT_API_PREFIX = '/v1';
+export const MESSAGES_PREFIX = '/anthropic/v1';
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+/**
+ * Moonshot's OpenAI-surface error envelope (ErrorResponse schema): `error.message` REQUIRED,
+ * `type` and `code` optional. The `type` strings below are Moonshot's OWN documented error-code
+ * page (platform.kimi.ai/docs/api/errors, read 2026-09-16) — a CLOSED published set:
+ *   400 invalid_request_error / content_filter
+ *   401 invalid_authentication_error / incorrect_api_key_error
+ *   403 permission_denied_error
+ *   404 resource_not_found_error
+ *   429 engine_overloaded_error / exceeded_current_quota_error / rate_limit_reached_error
+ *   499 client_closed_request
+ *   500 server_error / unexpected_output
+ *   503 server_unavailable
+ *   504 timeout_error? — the page names 504 but the twin models no timeout path; see the 429/503
+ *   helpers below for the ones it does.
+ */
+function errBody(type, message, code) {
+    return { error: { message, ...(type !== undefined ? { type } : {}), ...(code !== undefined ? { code } : {}) } };
+}
+function invalidRequest(message, code) {
+    return { status: 400, body: errBody('invalid_request_error', message, code) };
+}
+function notFound(message) {
+    return { status: 404, body: errBody('resource_not_found_error', message) };
+}
+function authError(message, type) {
+    return { status: 401, body: errBody(type, message) };
+}
+// ── modeled authentication (401) ────────────────────────────────────────────────────────
+// Real Moonshot requires a credential on every request and returns 401 when it is missing or
+// invalid (platform.kimi.ai/docs/api/errors: 401 = invalid_authentication_error when the key
+// is absent/malformed, incorrect_api_key_error when the key is wrong). The twin can't validate
+// against real keys, so it models the CHECKABLE failures: a missing credential →
+// invalid_authentication_error, and a reserved sentinel ('sk_invalid'/'invalid') for the
+// wrong-key path → incorrect_api_key_error. Any other non-empty key is accepted. Trusted
+// in-process calls carry NEITHER `headers` nor `apiKey` and are NOT auth-gated; both real
+// clients always send a key → they pass.
+//
+// THE KEY FOLLOWS THE PREFIX: the Anthropic-compatible surface's documented client is the
+// unmodified `@anthropic-ai/sdk`, which authenticates with `x-api-key` (never a bearer) — a
+// bearer-only check made the whole /anthropic surface 401-dead for it. On MESSAGES_PREFIX the
+// key candidates and the error envelope are Anthropic's own grammar (x-api-key first,
+// `authentication_error` in the {type:'error',error:{…}} envelope), exactly as the anthropic
+// pack's checkAuth reads them; on /v1 the bearer leads and Moonshot's own error types apply.
+function checkAuth(req) {
+    const onMessages = onMessagesPath(req.path);
+    const auth = req.headers?.['authorization'];
+    const bearer = typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '';
+    const xApiKey = typeof req.headers?.['x-api-key'] === 'string' ? req.headers['x-api-key'].trim() : '';
+    const key = (req.apiKey ?? '').trim() || (onMessages ? xApiKey || bearer : bearer || xApiKey);
+    if (!key) {
+        return onMessages
+            ? messagesError(401, 'authentication_error', 'missing API key. Provide an x-api-key header (or Authorization: Bearer …).')
+            : authError('The API key is missing or malformed. Please check your API key.', 'invalid_authentication_error');
+    }
+    if (key === 'sk_invalid' || key === 'invalid') {
+        return onMessages
+            ? messagesError(401, 'authentication_error', 'invalid x-api-key.')
+            : authError('The API key is invalid. Please check your API key.', 'incorrect_api_key_error');
+    }
+    return null;
+}
+/** True when the request targets the Anthropic-compatible surface — the prefix that owns its
+ *  OWN error envelope, auth header and error-type vocabulary (see the two-prefixes note). */
+function onMessagesPath(path) {
+    const bare = path.split('?')[0] ?? '';
+    return bare === MESSAGES_PREFIX || bare.startsWith(`${MESSAGES_PREFIX}/`);
+}
+// ── modeled rate limiting (429) ────────────────────────────────────────────────────────
+// Non-deterministic in production, so the twin exposes a DETERMINISTIC opt-in trigger:
+// `x-twin-force-rate-limit: 1` returns the faithful 429 envelope plus Moonshot's own documented
+// header family (platform.kimi.ai/docs/pricing/limits: a 429 carries X-RateLimit-Limit /
+// X-RateLimit-Remaining / X-RateLimit-Reset) and `retry-after`. The Tier-0 figures are the
+// LOWEST published row (RPM 3, TPM 500,000) — the same grounding the budget declaration uses.
+function rateLimitError() {
+    return {
+        status: 429,
+        body: errBody('rate_limit_reached_error', 'Request rate limit reached: 3 requests per minute (Tier 0). Please retry after 20 seconds.'),
+        headers: {
+            'retry-after': '20',
+            'x-ratelimit-limit': '3',
+            'x-ratelimit-remaining': '0',
+            'x-ratelimit-reset': '20s',
+        },
+    };
+}
+/** Moonshot documents 503 as `server_unavailable` (platform.kimi.ai/docs/api/errors). The twin
+ *  exposes it as a deterministic trigger so a caller can script the vendor's outage shape. */
+function serverUnavailable() {
+    return { status: 503, body: errBody('server_unavailable', 'The server is overloaded or not ready to handle the request. Please try again later.') };
+}
+function triggered(req, header) {
+    const v = req.headers?.[header];
+    return v === '1' || v === 'true';
+}
+function nowEpoch(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+/**
+ * Mint the next local id for `type`. Derived from the ID SET ALREADY IN STATE (a scan of the
+ * projection), never a row count — a count-mint silently clobbers a pulled vendor id sitting in a
+ * gap above the count (ADDING_A_TWIN.md §5). Two further properties matter:
+ *   • the `_twin_` infix namespaces LOCAL mints, so a pulled Moonshot id can never be matched by
+ *     this regex and therefore can never be re-minted;
+ *   • the scan includes TOMBSTONED rows (a soft-deleted file keeps its projection row), so the
+ *     counter RATCHETS across delete→recreate and a deleted id is never handed out twice.
+ */
+function nextId(type, prefix, root) {
+    let max = 0;
+    for (const r of rows(type, root)) {
+        const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(String(r.id));
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `${prefix}_twin_${max + 1}`;
+}
+/** Models observed by a connector pull (mapModel), reshaped into the served model object. */
+function pulledModels(root) {
+    return rows('model', root)
+        .filter((r) => !r._deleted)
+        .map((r) => ({ id: r.id, object: 'model', created: r.created, owned_by: r.owned_by }));
+}
+/** The catalog a request sees: the static table, with any PULLED row of the same id OVERRIDING it. */
+function servedModels(root) {
+    const pulled = pulledModels(root);
+    const byId = new Map();
+    for (const m of MOONSHOT_MODELS)
+        byId.set(m.id, { id: m.id, object: 'model', created: m.created, owned_by: m.owned_by });
+    for (const m of pulled)
+        byId.set(String(m.id), m);
+    return [...byId.values()];
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+/** Strip the kernel's housekeeping fields and the twin's private underscore-prefixed fields. */
+function strip(r) {
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (k === 'type' || k === 'updatedAt' || k.startsWith('_'))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+// ── request parsing ─────────────────────────────────────────────────────────────────────
+function parseJson(body) {
+    if (!body || !body.trim())
+        return {};
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Moonshot's documented tool-name regex (ToolDefinition / MessagesTool schemas). */
+const TOOL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$/;
+/** `stop`: "A maximum of 5 strings is allowed, and each string must not exceed 32 bytes"
+ *  (ChatRequestBase.stop description). */
+const STOP_MAX_ITEMS = 5;
+const STOP_MAX_BYTES = 32;
+/** Validate `thinking` per model. Returns the parsed value or an error envelope. */
+function validateThinking(model, raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        return { error: invalidRequest("'thinking' must be an object") };
+    const o = raw;
+    const type = o.type;
+    if (typeof type !== 'string')
+        return { error: invalidRequest("'thinking.type' is required") };
+    if (model === 'kimi-k2.6') {
+        if (!K26_THINKING_TYPES.includes(type)) {
+            return { error: invalidRequest(`'thinking.type' must be one of ${K26_THINKING_TYPES.map((t) => `'${t}'`).join(', ')} for kimi-k2.6`) };
+        }
+    }
+    else if (model === 'kimi-k2.7-code' || model === 'kimi-k2.7-code-highspeed') {
+        // Moonshot's OpenAPI: "For kimi-k2.7-code, only `\"enabled\"` is accepted; passing
+        // `\"disabled\"` returns an error. This differs from kimi-k2.6."
+        if (!K27_THINKING_TYPES.includes(type)) {
+            return { error: invalidRequest(`'thinking.type' must be 'enabled' for ${model} — 'disabled' is not supported and returns an error`) };
+        }
+    }
+    else {
+        return { error: invalidRequest(`'thinking' is not a parameter of ${model}`) };
+    }
+    let keep;
+    if (o.keep !== undefined) {
+        if (o.keep !== null && o.keep !== 'all') {
+            // kimi-k2.7-code: only "all" (or null/omitted) is valid; any other value errors.
+            // kimi-k2.6: same closed set {all, null}.
+            return { error: invalidRequest(`'thinking.keep' must be 'all' or null`) };
+        }
+        keep = o.keep;
+    }
+    return { value: { type: type, ...(keep !== undefined ? { keep } : {}) } };
+}
+function validateChat(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: invalidRequest("'model' is a required property") };
+    if (typeof params.model !== 'string')
+        return { error: invalidRequest("'model' must be a string") };
+    const model = findModel(params.model);
+    if (!model)
+        return { error: invalidRequest(`The model '${params.model}' does not exist or you do not have access to it.`) };
+    if (!Array.isArray(params.messages))
+        return { error: invalidRequest("'messages' is a required property") };
+    if (params.messages.length === 0)
+        return { error: invalidRequest("[] is too short - 'messages'") };
+    const messages = params.messages;
+    for (const m of messages) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
+            return { error: invalidRequest("each message must have a valid 'role'") };
+        }
+        if (!['system', 'user', 'assistant', 'tool'].includes(m.role)) {
+            return { error: invalidRequest(`'${m.role}' is not one of ['system', 'user', 'assistant', 'tool']`) };
+        }
+    }
+    // kimi-k3's dynamic tool loading message: role 'system', `tools` present, NO content.
+    // Any OTHER message with `tools` and no content is malformed.
+    for (const m of messages) {
+        const hasTools = Array.isArray(m.tools);
+        if (m.role === 'system' && hasTools && m.content === undefined)
+            continue; // the dynamic-tool shape
+        if (hasTools && m.content === undefined) {
+            return { error: invalidRequest("a dynamic tool message must use the 'system' role") };
+        }
+    }
+    // Vision: image_url parts are only valid on a vision model (kimi-k3, kimi-k2.6).
+    if (!model.supports.vision) {
+        for (const m of messages) {
+            const parts = m.content;
+            if (Array.isArray(parts) && parts.some((p) => p?.type === 'image_url')) {
+                return { error: invalidRequest(`The model '${params.model}' does not support image input`) };
+            }
+        }
+    }
+    // logprobs: Moonshot's OpenAPI ACCEPTS logprobs (boolean) + top_logprobs (0..20) — unlike
+    // Groq, this is real surface. The twin models acceptance (a logprobs echo on the choice) only
+    // as far as the shape goes: `top_logprobs` without `logprobs:true` contradicts the documented
+    // coupling ("logprobs must be set to true when this parameter is used").
+    const logprobs = params.logprobs === true;
+    let topLogprobs;
+    if (params.top_logprobs !== undefined && params.top_logprobs !== null) {
+        const n = Number(params.top_logprobs);
+        if (!Number.isInteger(n) || n < 0 || n > 20)
+            return { error: invalidRequest("'top_logprobs' must be an integer between 0 and 20") };
+        if (!logprobs)
+            return { error: invalidRequest("'logprobs' must be set to true when 'top_logprobs' is used") };
+        topLogprobs = n;
+    }
+    const maxRaw = params.max_completion_tokens ?? params.max_tokens;
+    let maxTokens;
+    if (maxRaw !== undefined) {
+        maxTokens = Number(maxRaw);
+        if (!Number.isInteger(maxTokens) || maxTokens < 1)
+            return { error: invalidRequest("'max_completion_tokens' must be an integer >= 1") };
+        // "If input plus max_completion_tokens exceeds the model context window, the API returns
+        // invalid_request_error" (ChatRequestCommon).
+        const promptTokens = countPromptTokens(messages);
+        if (promptTokens + maxTokens > model.context_length) {
+            return { error: invalidRequest(`'max_completion_tokens' plus input tokens (${promptTokens + maxTokens}) exceeds the model context window (${model.context_length})`) };
+        }
+    }
+    let stop;
+    if (params.stop !== undefined && params.stop !== null) {
+        if (typeof params.stop === 'string')
+            stop = [params.stop];
+        else if (Array.isArray(params.stop))
+            stop = params.stop;
+        else
+            return { error: invalidRequest("'stop' must be a string or an array of strings") };
+        if (stop.length > STOP_MAX_ITEMS)
+            return { error: invalidRequest(`'stop' must not exceed ${STOP_MAX_ITEMS} strings`) };
+        for (const s of stop) {
+            if (typeof s !== 'string')
+                return { error: invalidRequest("'stop' must be a string or an array of strings") };
+            if (Buffer.byteLength(s, 'utf8') > STOP_MAX_BYTES)
+                return { error: invalidRequest(`'stop' entries must not exceed ${STOP_MAX_BYTES} bytes`) };
+        }
+    }
+    let toolChoice;
+    const tcRaw = params.tool_choice;
+    if (tcRaw !== undefined && tcRaw !== null) {
+        if (typeof tcRaw === 'string') {
+            if (!['auto', 'none', 'required'].includes(tcRaw))
+                return { error: invalidRequest("'tool_choice' must be one of 'none', 'auto', 'required' or a named function") };
+            toolChoice = tcRaw;
+        }
+        else if (typeof tcRaw === 'object') {
+            const name = tcRaw.function?.name;
+            if (typeof name !== 'string' || !name)
+                return { error: invalidRequest("'tool_choice.function.name' is required for a named tool choice") };
+            toolChoice = { name };
+        }
+    }
+    let responseFormat = { kind: 'text' };
+    const rf = params.response_format;
+    if (rf && typeof rf === 'object') {
+        if (rf.type === 'json_object')
+            responseFormat = { kind: 'json_object' };
+        else if (rf.type === 'json_schema') {
+            // json_schema REQUIRES the json_schema object (name + schema required by the OpenAPI).
+            const js = rf.json_schema;
+            if (!js || typeof js !== 'object')
+                return { error: invalidRequest("'response_format.json_schema' is required when 'response_format.type' is 'json_schema'") };
+            if (typeof js.name !== 'string' || !js.name)
+                return { error: invalidRequest("'response_format.json_schema.name' is required") };
+            if (!js.schema || typeof js.schema !== 'object')
+                return { error: invalidRequest("'response_format.json_schema.schema' is required") };
+            responseFormat = { kind: 'json_schema', schema: js.schema };
+        }
+        else if (rf.type !== undefined && rf.type !== 'text')
+            return { error: invalidRequest("'response_format.type' must be one of 'text', 'json_object', 'json_schema'") };
+    }
+    // Tools: validate the documented name regex on every provided function tool.
+    if (params.tools !== undefined) {
+        if (!Array.isArray(params.tools))
+            return { error: invalidRequest("'tools' must be an array") };
+        for (const t of params.tools) {
+            const name = t?.function?.name;
+            if (typeof name !== 'string' || !TOOL_NAME_RE.test(name)) {
+                return { error: invalidRequest(`'tools[].function.name' must match ${TOOL_NAME_RE.source}`) };
+            }
+        }
+    }
+    // kimi-k3's reasoning_effort: a CLOSED set, default 'max'.
+    let reasoningEffort;
+    if (params.reasoning_effort !== undefined && params.reasoning_effort !== null) {
+        if (params.model !== 'kimi-k3')
+            return { error: invalidRequest(`'reasoning_effort' is not a parameter of ${params.model}`) };
+        if (typeof params.reasoning_effort !== 'string' || !REASONING_EFFORTS.includes(params.reasoning_effort)) {
+            return { error: invalidRequest(`'reasoning_effort' must be one of ${REASONING_EFFORTS.map((t) => `'${t}'`).join(', ')}`) };
+        }
+        reasoningEffort = params.reasoning_effort;
+    }
+    const thinking = validateThinking(params.model, params.thinking);
+    if (thinking.error)
+        return { error: thinking.error };
+    const streamOptionsRaw = params.stream_options;
+    if (streamOptionsRaw !== undefined && (typeof streamOptionsRaw !== 'object' || streamOptionsRaw === null)) {
+        return { error: invalidRequest("'stream_options' must be an object") };
+    }
+    return {
+        args: {
+            model: params.model,
+            messages,
+            ...(params.tools !== undefined ? { tools: params.tools } : {}),
+            n: 1,
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            stream: params.stream === true,
+            ...(streamOptionsRaw?.include_usage === true ? { streamOptions: { includeUsage: true } } : {}),
+            ...(toolChoice !== undefined ? { toolChoice } : {}),
+            responseFormat,
+            logprobs,
+            ...(topLogprobs !== undefined ? { topLogprobs } : {}),
+            ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+            ...(thinking.value !== undefined ? { thinking: thinking.value } : {}),
+            ...(typeof params.prompt_cache_key === 'string' ? { promptCacheKey: params.prompt_cache_key } : {}),
+        },
+    };
+}
+/** Build ONE deterministic stub choice. Thinking mode follows the model/params: kimi-k3 always
+ *  thinks; k2.6 thinks unless `thinking.type:'disabled'`; k2.7-code always thinks. */
+function buildChoice(args, idx) {
+    const hasTools = Array.isArray(args.tools) && args.tools.length > 0;
+    const forbidTools = args.toolChoice === 'none';
+    const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
+    if (hasTools && !forbidTools) {
+        const list = args.tools;
+        const calls = [];
+        if (forcedName) {
+            const tc = stubToolCall(args.tools, idx + 1, forcedName);
+            if (tc)
+                calls.push(tc);
+        }
+        else {
+            for (let t = 0; t < list.length; t++) {
+                const tc = stubToolCall([list[t]], idx * 100 + t + 1);
+                if (tc)
+                    calls.push(tc);
+            }
+        }
+        if (calls.length) {
+            return {
+                choice: { index: idx, message: { role: 'assistant', content: null, tool_calls: calls }, finish_reason: 'tool_calls' },
+                completionTokens: estimateTokens(JSON.stringify(calls)),
+            };
+        }
+    }
+    let text = args.responseFormat.kind === 'json_object'
+        ? stubJsonObject(args.messages, args.model)
+        : args.responseFormat.kind === 'json_schema'
+            ? stubJsonObject(args.messages, args.model, args.responseFormat.schema)
+            : stubAssistantText(args.messages, args.model);
+    let finish = 'stop';
+    // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list.
+    let stopAt = -1;
+    for (const s of args.stop ?? []) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    if (stopAt >= 0)
+        text = text.slice(0, stopAt);
+    if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+        text = text.slice(0, args.maxTokens * 4);
+        finish = 'length';
+    }
+    const message = { role: 'assistant', content: text };
+    // Thinking mode: kimi-k3 ALWAYS (Preserved Thinking); k2.7-code ALWAYS (type only accepts
+    // 'enabled'); k2.6 when thinking.type is not 'disabled'.
+    const thinkingOn = args.model === 'kimi-k3'
+        || args.model === 'kimi-k2.7-code' || args.model === 'kimi-k2.7-code-highspeed'
+        || (args.model === 'kimi-k2.6' && args.thinking?.type !== 'disabled');
+    if (thinkingOn) {
+        message.reasoning_content = stubReasoningContent(args.messages, args.model);
+        // The cap applies to EVERYTHING the model emits — reasoning is output tokens at the vendor
+        // too — so truncate it as well and let completion_tokens count only what was returned.
+        // finish_reason stays 'length': the cap is what truncated, whichever field hit it.
+        if (args.maxTokens !== undefined) {
+            const textTokens = estimateTokens(String(message.content ?? ''));
+            if (textTokens >= args.maxTokens) {
+                delete message.reasoning_content;
+            }
+            else {
+                const budget = args.maxTokens - textTokens;
+                const reasoning = message.reasoning_content;
+                if (estimateTokens(reasoning) > budget)
+                    message.reasoning_content = reasoning.slice(0, budget * 4);
+            }
+        }
+    }
+    return {
+        choice: { index: idx, message, finish_reason: finish },
+        completionTokens: estimateTokens(String(message.content ?? '')) + estimateTokens(message.reasoning_content ?? ''),
+    };
+}
+export function buildChatCompletion(args, occurredAt, decision) {
+    const promptTokens = countPromptTokens(args.messages);
+    let scripted = null;
+    let missTeach = '';
+    if (decision) {
+        // The route served the request through the engine (R15: serve() honors the handler's fault
+        // before any content exists); this realizer only sees the content decision.
+        if (decision.kind === 'handler') {
+            const respond = decision.respond;
+            // A scripted FAILURE short-circuits into Moonshot's own error envelope + status.
+            if (respond.error)
+                return scriptedError(respond.error);
+            scripted = realizeMoonshotRespond(respond);
+        }
+        else {
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/moonshot.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+        }
+    }
+    const choices = [];
+    let completionTokens = 0;
+    for (let i = 0; i < args.n; i++) {
+        if (scripted) {
+            const message = scripted.toolCalls.length
+                ? { role: 'assistant', content: scripted.text, tool_calls: scripted.toolCalls }
+                : { role: 'assistant', content: scripted.text ?? '' };
+            if (scripted.reasoning !== null)
+                message.reasoning_content = scripted.reasoning;
+            choices.push({ index: i, message, finish_reason: scripted.finishReason });
+            completionTokens += estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? ''));
+            continue;
+        }
+        const { choice, completionTokens: ct } = buildChoice(args, i);
+        if (missTeach && typeof choice.message.content === 'string')
+            choice.message.content += missTeach;
+        choices.push(choice);
+        completionTokens += ct;
+    }
+    const usage = buildChatUsage(promptTokens, completionTokens, args.promptCacheKey);
+    const id = `chatcmpl-twin-${stableSuffix(args.messages, args.model)}`;
+    return {
+        id,
+        object: 'chat.completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices,
+        usage,
+    };
+}
+/** Map a scripted scenario failure onto Moonshot's real status + envelope. */
+function scriptedError(err) {
+    if (err.type === 'rate_limit_reached_error') {
+        const base = rateLimitError();
+        return err.message ? { ...base, body: errBody('rate_limit_reached_error', err.message) } : base;
+    }
+    if (err.type === 'server_unavailable')
+        return err.message ? { ...serverUnavailable(), body: errBody('server_unavailable', err.message) } : serverUnavailable();
+    return { status: 500, body: errBody('server_error', err.message ?? 'Internal Server Error') };
+}
+const isEnvelope = (v) => typeof v.status === 'number' && 'body' in v;
+/** Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order. */
+function chunkText(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (let i = 0; i < text.length; i += 20)
+        out.push(text.slice(i, i + 20));
+    return out;
+}
+/**
+ * Emit the vendor-faithful Moonshot streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). Moonshot's order: a first chunk with `delta:{role:'assistant'}`, then
+ * `delta:{content}` / `delta:{reasoning_content}` / tool_calls deltas, then a chunk carrying
+ * `finish_reason`, then — because Moonshot's ChatCompletionChunk.usage is "Object in the final
+ * chunk with usage, null in ordinary chunks" (the OpenAPI's own wording, the first-party
+ * denominator; the prose chat doc mentions the chunk under stream_options.include_usage, so the
+ * two sources disagree and the OpenAPI governs) — a FINAL chunk whose `choices:[]` and `usage`
+ * hold the whole usage object, then `data: [DONE]`. `stream_options` is ACCEPTED (validated as
+ * an object) but the tail is not gated on it. Deterministic + synchronous.
+ */
+export function streamChat(args, sink, occurredAt, decision) {
+    const built = buildChatCompletion(args, occurredAt, decision);
+    if (isEnvelope(built))
+        return built;
+    const full = built;
+    const base = { id: full.id, object: 'chat.completion.chunk', created: full.created, model: full.model };
+    for (const choice of full.choices) {
+        const idx = choice.index;
+        sink({ data: { ...base, choices: [{ index: idx, delta: { role: 'assistant', content: '' }, finish_reason: null, usage: null }] } });
+        if (choice.message.reasoning_content) {
+            sink({ data: { ...base, choices: [{ index: idx, delta: { reasoning_content: choice.message.reasoning_content }, finish_reason: null, usage: null }] } });
+        }
+        if (choice.message.tool_calls && choice.message.tool_calls.length) {
+            choice.message.tool_calls.forEach((tc, tIdx) => {
+                sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: '' } }] }, finish_reason: null, usage: null }] } });
+                sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, finish_reason: null, usage: null }] } });
+            });
+        }
+        else {
+            for (const piece of chunkText(choice.message.content ?? '')) {
+                sink({ data: { ...base, choices: [{ index: idx, delta: { content: piece }, finish_reason: null, usage: null }] } });
+            }
+        }
+        sink({ data: { ...base, choices: [{ index: idx, delta: {}, finish_reason: choice.finish_reason, usage: null }] } });
+    }
+    // Moonshot's usage tail: a final chunk with an EMPTY choices array carrying the usage object.
+    sink({ data: { ...base, choices: [], finish_reason: null, usage: full.usage } });
+    sink({ done: true });
+    return full;
+}
+// ── /v1/tokenizers/estimate-token-count (stateless, deterministic) ──────────────────────
+function handleEstimateTokens(params) {
+    if (params.model === undefined || typeof params.model !== 'string' || !params.model)
+        return invalidRequest("'model' is a required property");
+    if (!findModel(params.model))
+        return invalidRequest(`The model '${params.model}' does not exist or you do not have access to it.`);
+    if (!Array.isArray(params.messages))
+        return { status: 400, body: errBody('invalid_request_error', "'messages' is a required property") };
+    const messages = params.messages;
+    for (const m of messages) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string')
+            return invalidRequest("each message must have a valid 'role'");
+        // The OpenAPI: "content must not be empty".
+        if (m.content === undefined || m.content === null || (typeof m.content === 'string' && m.content === '')) {
+            return invalidRequest("'messages[].content' must not be empty");
+        }
+    }
+    return { status: 200, body: { data: { total_tokens: countPromptTokens(messages) } } };
+}
+// ── /v1/signatures/verify (stateless, deterministic) ────────────────────────────────────
+// Moonshot's request-signing contract: a model call carries `X-Msh-Request-Nonce`; the response
+// carries `Msh-Request-Timestamp` (unix ms) and `Msh-Request-Signature` (`reqsigv1_<opaque>`).
+// POST /v1/signatures/verify checks a (nonce, timestamp, model, signature) tuple. The twin has
+// no real signing key, so it models the CHECKABLE part: a well-formed tuple whose signature
+// carries the documented `reqsigv1_` prefix AND whose signature recomputes exactly under the
+// twin's own deterministic scheme (messagesSignature over nonce/timestamp/model) answers
+// `valid:true`; anything else answers `valid:false`. The twin ALSO emits the two Msh- headers
+// on its own streaming model responses WHEN the request carried a nonce (see the server) so the
+// round-trip is exercisable end to end.
+function handleSignatureVerify(params, req) {
+    for (const field of ['nonce', 'timestamp', 'model', 'signature']) {
+        if (params[field] === undefined || params[field] === null || params[field] === '') {
+            return invalidRequest(`'${field}' is a required property`);
+        }
+    }
+    if (typeof params.nonce !== 'string' || typeof params.model !== 'string' || typeof params.signature !== 'string') {
+        return invalidRequest("'nonce', 'model' and 'signature' must be strings");
+    }
+    const ts = Number(params.timestamp);
+    if (!Number.isFinite(ts) || ts < 1)
+        return invalidRequest("'timestamp' must be a positive integer");
+    const sig = String(params.signature);
+    if (!sig.startsWith('reqsigv1_'))
+        return { status: 200, body: { valid: false } };
+    // The twin's own signatures are derived from the tuple (see messagesSignature); a signature
+    // that recomputes exactly answers valid:true.
+    const expected = messagesSignature(String(params.nonce), ts, String(params.model));
+    return { status: 200, body: { valid: sig === expected } };
+}
+/** The deterministic signature the twin issues on inference responses and verifies here. */
+export function messagesSignature(nonce, timestamp, model) {
+    return `reqsigv1_twin_${fnv1a(`${nonce}|${timestamp}|${model}`).toString(36)}`;
+}
+// ── Web-search tools (stateless, deterministic labeled stubs) ───────────────────────────
+const TIME_WINDOW_RE = /^\d{4}(-\d{2})?(-\d{2})?$/;
+function validateTimeWindow(raw) {
+    if (raw === undefined)
+        return null;
+    if (typeof raw !== 'object' || raw === null)
+        return invalidRequest("'time_window' must be an object");
+    const o = raw;
+    for (const k of ['start', 'end']) {
+        if (o[k] !== undefined && (typeof o[k] !== 'string' || !TIME_WINDOW_RE.test(o[k]))) {
+            return invalidRequest(`'time_window.${k}' must be in YYYY, YYYY-MM or YYYY-MM-DD format`);
+        }
+    }
+    return null;
+}
+function handleToolsSearch(params, pro) {
+    if (typeof params.text_query !== 'string' || !params.text_query)
+        return invalidRequest("'text_query' is a required property and must not be empty");
+    if (params.limit !== undefined) {
+        const n = Number(params.limit);
+        if (!Number.isInteger(n) || n < 1 || n > 20)
+            return invalidRequest("'limit' must be an integer between 1 and 20");
+    }
+    if (params.timeout_seconds !== undefined) {
+        const n = Number(params.timeout_seconds);
+        if (!Number.isInteger(n) || n < 1 || n > 60)
+            return invalidRequest("'timeout_seconds' must be an integer between 1 and 60");
+    }
+    if (pro) {
+        if (params.sites !== undefined) {
+            if (!Array.isArray(params.sites) || params.sites.length > 5)
+                return invalidRequest("'sites' must be an array of at most 5 strings");
+            for (const s of params.sites) {
+                if (typeof s !== 'string' || !s || /\s|\(|\)/.test(s))
+                    return invalidRequest("'sites' entries must be non-empty and contain no whitespace or parentheses");
+            }
+        }
+        const tw = validateTimeWindow(params.time_window);
+        if (tw)
+            return tw;
+    }
+    else {
+        // search (not search_pro) takes include_content; search_pro does not declare it.
+        if (params.include_content !== undefined && typeof params.include_content !== 'boolean') {
+            return invalidRequest("'include_content' must be a boolean");
+        }
+    }
+    const limit = params.limit === undefined ? 5 : Number(params.limit);
+    // `include_content: true` SERVES content (the option's documented meaning): the results carry
+    // a labeled deterministic page stub. Default (false) is the vendor's bare shape — `text: ''`.
+    // A no-op 200 that accepted the flag and always served '' was the round-two finding.
+    const includeContent = pro ? false : params.include_content === true;
+    const results = stubSearchResults(String(params.text_query), limit, pro, includeContent);
+    return { status: 200, body: { search_results: results } };
+}
+function handleToolsFetch(params) {
+    if (typeof params.url !== 'string' || !params.url)
+        return invalidRequest("'url' is a required property");
+    if (!/^https?:\/\//.test(params.url))
+        return invalidRequest("'url' must be an http or https URL");
+    return { status: 200, body: stubFetchedMarkdown(params.url) };
+}
+// ── Files (stateful) ────────────────────────────────────────────────────────────────────
+/** FileObject.purpose — a CLOSED documented set: file-extract, image, video, batch. */
+const FILE_CREATE_PURPOSES = new Set(['file-extract', 'image', 'video', 'batch']);
+async function createFile(params, req) {
+    const purpose = String(params.purpose ?? '');
+    if (!purpose)
+        return invalidRequest("'purpose' is a required property");
+    if (!FILE_CREATE_PURPOSES.has(purpose))
+        return invalidRequest(`'purpose' must be one of ${[...FILE_CREATE_PURPOSES].map((p) => `'${p}'`).join(', ')} (got '${purpose}')`);
+    // The multipart adapter marks a form with no `file` part (§9 round two, F3): the vendor's
+    // Upload File requires the file body, so the twin refuses rather than minting an empty
+    // 'ready' file.
+    if (params._multipart_missing_file === true)
+        return invalidRequest("the multipart form carries no 'file' part");
+    const filename = String(params.filename ?? params.file ?? 'upload');
+    const content = typeof params.content === 'string' ? params.content : '';
+    // `binary_content` is the SERVER's multipart-adapter marker (moonshot-server.ts): the JSON
+    // contract cannot carry raw bytes, so an uploaded binary travels base64-encoded under it and
+    // is stored with the marker; GET /content decodes before serving. A JSON-door create (plain
+    // text) stores the text as-is with no marker. A caller forging the marker through the JSON
+    // door gets strict validation: the content must actually be base64 (§9 round two, F6).
+    const binary = params.binary_content === true;
+    if (binary && !/^[A-Za-z0-9+/]*={0,2}$/.test(content) || (binary && content.length % 4 !== 0)) {
+        return invalidRequest("'binary_content' content must be base64-encoded");
+    }
+    // `bytes` is the vendor's byte count — a text file's UTF-8 length, not the JS string's
+    // UTF-16 code-unit count (a §9-round-two finding: the two doors disagreed on the same field;
+    // the multipart door already counted real bytes).
+    const bytes = typeof params.bytes === 'number' ? params.bytes : binary ? Buffer.from(content, 'base64').length : Buffer.byteLength(content, 'utf8');
+    const id = nextId('file', 'file', req.root);
+    await applyTwinWrite(SERVICE, {
+        operation: 'file.create',
+        subjectType: 'file',
+        subjectId: id,
+        fields: { object: 'file', bytes, created_at: nowEpoch(req.occurredAt), filename, purpose, status: 'ready', _content: content, ...(binary ? { _content_encoding: 'base64' } : {}) },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    const row = getRow('file', id, req.root);
+    return { status: 200, body: fileView(row ?? {}) };
+}
+function fileView(r) {
+    const s = strip(r);
+    return { id: r.id, object: 'file', bytes: s.bytes, created_at: s.created_at, filename: s.filename, purpose: s.purpose, status: s.status ?? 'ready' };
+}
+// ── Batches (stateful) ──────────────────────────────────────────────────────────────────
+/** BatchCreateRequest.endpoint — a CLOSED documented set: only /v1/chat/completions. */
+const BATCH_ENDPOINTS = new Set(['/v1/chat/completions']);
+/** "supports formats like 12h, 1d, 3d, minimum 12h, maximum 7d" (BatchCreateRequest). */
+const COMPLETION_WINDOW = /^(\d+)(h|d)$/;
+function completionWindowHours(w) {
+    const m = COMPLETION_WINDOW.exec(w);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return m[2] === 'd' ? n * 24 : n;
+}
+async function createBatch(params, req) {
+    const inputFileId = params.input_file_id;
+    if (typeof inputFileId !== 'string' || !inputFileId)
+        return invalidRequest("'input_file_id' is a required property");
+    const endpoint = params.endpoint;
+    if (typeof endpoint !== 'string' || !BATCH_ENDPOINTS.has(endpoint)) {
+        return invalidRequest(`'endpoint' must be one of ${[...BATCH_ENDPOINTS].map((e) => `'${e}'`).join(', ')}`);
+    }
+    const window = params.completion_window;
+    if (typeof window !== 'string')
+        return invalidRequest("'completion_window' is a required property");
+    const hours = completionWindowHours(window);
+    if (hours === null || hours < 12 || hours > 168)
+        return invalidRequest("'completion_window' must be a duration from '12h' to '7d'");
+    if (params.metadata !== undefined) {
+        const md = params.metadata;
+        if (!md || typeof md !== 'object' || Array.isArray(md))
+            return invalidRequest("'metadata' must be an object");
+        const entries = Object.entries(md);
+        if (entries.length > 16)
+            return invalidRequest("'metadata' must not exceed 16 key-value pairs");
+        for (const [k, v] of entries) {
+            if (k.length > 64)
+                return invalidRequest("'metadata' keys must not exceed 64 characters");
+            if (typeof v !== 'string' || v.length > 512)
+                return invalidRequest("'metadata' values must be strings of at most 512 characters");
+        }
+    }
+    const file = getRow('file', inputFileId, req.root);
+    if (!file || file._deleted)
+        return notFound(`No such File object: ${inputFileId}`);
+    if (file.purpose !== 'batch')
+        return invalidRequest(`File ${inputFileId} must have purpose 'batch' (has '${String(file.purpose)}')`);
+    const created = nowEpoch(req.occurredAt);
+    const id = nextId('batch', 'batch', req.root);
+    await applyTwinWrite(SERVICE, {
+        operation: 'batch.create',
+        subjectType: 'batch',
+        subjectId: id,
+        fields: {
+            object: 'batch',
+            endpoint,
+            input_file_id: inputFileId,
+            completion_window: window,
+            status: 'validating',
+            output_file_id: null,
+            error_file_id: null,
+            created_at: created,
+            in_progress_at: null,
+            expires_at: created + hours * 3600,
+            finalizing_at: null,
+            completed_at: null,
+            failed_at: null,
+            cancelling_at: null,
+            cancelled_at: null,
+            request_counts: { total: 0, completed: 0, failed: 0 },
+            metadata: params.metadata ?? null,
+        },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: batchView(getRow('batch', id, req.root) ?? {}) };
+}
+function batchView(r) {
+    return { id: r.id, ...strip(r) };
+}
+// ── Balance (stateful) ──────────────────────────────────────────────────────────────────
+// GET /v1/users/me/balance returns Moonshot's own envelope ({code, data:{available_balance,
+// voucher_balance, cash_balance}, scode, status}) — NOT the OpenAI envelope. The balance is
+// STATEFUL: the connector's pull can fold a real account's balance into the log (type 'balance',
+// id 'me'), and the served figure is that row when present, else a deterministic positive stub.
+function balanceView(root) {
+    const row = getRow('balance', 'me', root);
+    const b = row && !row._deleted
+        ? { available_balance: Number(row.available_balance), voucher_balance: Number(row.voucher_balance), cash_balance: Number(row.cash_balance) }
+        : { available_balance: 49.58894, voucher_balance: 46.58893, cash_balance: 3.00001 };
+    return {
+        status: 200,
+        body: { code: 0, data: b, scode: '0x0', status: true },
+    };
+}
+/** Extract the tool name from an Anthropic Messages tool definition ({type:'custom', name, …}). */
+function messagesToolName(t) {
+    const o = t;
+    return typeof o?.name === 'string' ? o.name : '';
+}
+/** Validate the Anthropic-compatible request. kimi-k3 only; max_tokens REQUIRED. */
+function validateMessages(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: messagesError(400, 'invalid_request_error', "'model' is a required property") };
+    // MessagesRequest['model'] enum (kimi-k3 only) — read from the catalog's own supports flag.
+    if (!findModel(String(params.model))?.supports.messages) {
+        return { error: messagesError(400, 'invalid_request_error', `The endpoint currently supports 'kimi-k3' only (got '${String(params.model)}')`) };
+    }
+    if (!Array.isArray(params.messages))
+        return { error: messagesError(400, 'invalid_request_error', "'messages' is a required property") };
+    if (params.messages.length === 0)
+        return { error: messagesError(400, 'invalid_request_error', "'messages' must not be empty") };
+    const messages = [];
+    for (const m of params.messages) {
+        if (!m || typeof m !== 'object')
+            return { error: messagesError(400, 'invalid_request_error', 'each message must be an object') };
+        if (m.role !== 'user' && m.role !== 'assistant') {
+            // Anthropic's grammar: the top-level `system` field owns the system prompt.
+            return { error: messagesError(400, 'invalid_request_error', `'${String(m.role)}' is not one of ['user', 'assistant'] — use the top-level 'system' field for the system prompt`) };
+        }
+        messages.push({ role: m.role, content: m.content });
+    }
+    if (params.max_tokens === undefined || params.max_tokens === null)
+        return { error: messagesError(400, 'invalid_request_error', "'max_tokens' is a required property") };
+    const maxTokens = Number(params.max_tokens);
+    if (!Number.isInteger(maxTokens) || maxTokens < 1)
+        return { error: messagesError(400, 'invalid_request_error', "'max_tokens' must be an integer >= 1") };
+    let system;
+    if (params.system !== undefined) {
+        if (typeof params.system === 'string')
+            system = params.system;
+        else if (Array.isArray(params.system))
+            system = params.system.map((b) => String(b?.text ?? '')).join('\n');
+        else
+            return { error: messagesError(400, 'invalid_request_error', "'system' must be a string or an array of text blocks") };
+    }
+    let stopSequences;
+    if (params.stop_sequences !== undefined) {
+        if (!Array.isArray(params.stop_sequences))
+            return { error: messagesError(400, 'invalid_request_error', "'stop_sequences' must be an array of strings") };
+        if (params.stop_sequences.length > 5)
+            return { error: messagesError(400, 'invalid_request_error', "'stop_sequences' must not exceed 5 entries") };
+        for (const s of params.stop_sequences) {
+            if (typeof s !== 'string')
+                return { error: messagesError(400, 'invalid_request_error', "'stop_sequences' entries must be strings") };
+            if (Buffer.byteLength(s, 'utf8') > 32)
+                return { error: messagesError(400, 'invalid_request_error', "'stop_sequences' entries must not exceed 32 bytes") };
+        }
+        stopSequences = params.stop_sequences;
+    }
+    // Tools: Anthropic's MessagesTool shape, with the SAME documented name regex the /v1 surface
+    // enforces (a bad tool name is a 400 here too — never a silent acceptance the stub then
+    // ignores).
+    let tools;
+    if (params.tools !== undefined) {
+        if (!Array.isArray(params.tools))
+            return { error: messagesError(400, 'invalid_request_error', "'tools' must be an array") };
+        for (const t of params.tools) {
+            if (!t || typeof t !== 'object' || Array.isArray(t))
+                return { error: messagesError(400, 'invalid_request_error', 'each tool must be an object') };
+            const name = messagesToolName(t);
+            if (!name || !TOOL_NAME_RE.test(name)) {
+                return { error: messagesError(400, 'invalid_request_error', `'tools[].name' must match ${TOOL_NAME_RE.source}`) };
+            }
+            const schema = t.input_schema;
+            if (schema !== undefined && (!schema || typeof schema !== 'object' || Array.isArray(schema))) {
+                return { error: messagesError(400, 'invalid_request_error', "'tools[].input_schema' must be an object") };
+            }
+        }
+        tools = params.tools;
+    }
+    // tool_choice: Anthropic's closed type set INCLUDING type:'tool' with its required `name`
+    // (the sibling pack's rule: a named choice must name a tool that is actually in `tools`).
+    let toolChoice;
+    if (params.tool_choice !== undefined) {
+        const t = params.tool_choice?.type;
+        if (typeof t !== 'string' || !['auto', 'any', 'tool', 'none'].includes(t))
+            return { error: messagesError(400, 'invalid_request_error', "'tool_choice.type' must be one of 'auto', 'any', 'tool', 'none'") };
+        // A tool_choice WITHOUT tools is a contradiction — Anthropic's own surface refuses it.
+        if (!tools)
+            return { error: messagesError(400, 'invalid_request_error', "'tool_choice' requires 'tools' to be set") };
+        if (t === 'tool') {
+            const name = params.tool_choice.name;
+            if (typeof name !== 'string' || !tools.some((tool) => messagesToolName(tool) === name)) {
+                return { error: messagesError(400, 'invalid_request_error', `'tool_choice' names tool '${typeof name === 'string' ? name : String(name)}', which is not in tools`) };
+            }
+            toolChoice = { type: 'tool', name };
+        }
+        else {
+            toolChoice = { type: t };
+        }
+    }
+    let outputEffort;
+    const oc = params.output_config;
+    if (oc && typeof oc === 'object' && oc.effort !== undefined) {
+        if (typeof oc.effort !== 'string' || !REASONING_EFFORTS.includes(oc.effort)) {
+            return { error: messagesError(400, 'invalid_request_error', `'output_config.effort' must be one of ${REASONING_EFFORTS.map((t) => `'${t}'`).join(', ')}`) };
+        }
+        outputEffort = oc.effort;
+    }
+    return {
+        args: {
+            model: String(params.model),
+            messages,
+            maxTokens,
+            ...(system !== undefined ? { system } : {}),
+            ...(stopSequences !== undefined ? { stopSequences } : {}),
+            stream: params.stream === true,
+            ...(tools !== undefined ? { tools } : {}),
+            ...(toolChoice !== undefined ? { toolChoice } : {}),
+            ...(outputEffort !== undefined ? { outputEffort } : {}),
+        },
+    };
+}
+/** The Messages surface's OWN error envelope (MessagesErrorResponse schema) — different from /v1. */
+function messagesError(status, type, message) {
+    return { status, body: { type: 'error', error: { type, message } } };
+}
+/** Re-wear a scripted fault's Moonshot-shaped body in the Anthropic envelope for the /anthropic
+ *  surface: the fault result carries the Moonshot error body the adapter rendered; this surface
+ *  serves {type:'error', error:{type,message}} with the equivalent Anthropic type. */
+function messagesErrorBody(status, moonshotBody) {
+    const e = moonshotBody?.error;
+    const message = e?.message ?? `The request was refused by a scripted fault (${status}).`;
+    const type = e?.type === 'rate_limit_reached_error' ? 'rate_limit_error'
+        : e?.type === 'server_unavailable' || e?.type === 'server_error' ? 'api_error'
+            : 'invalid_request_error';
+    return { type: 'error', error: { type, message } };
+}
+export function buildMessagesResponse(args, occurredAt, decision) {
+    let scripted = null;
+    let missTeach = '';
+    if (decision) {
+        // The route served the request through the engine (R15); tools/thinking rode into the
+        // match there — a handler keyed on `hasTool`/`toolResultFor` fires on this surface exactly
+        // as it fires on /v1 (the sibling pack wires the same request features through on its
+        // Messages surface).
+        if (decision.kind === 'handler') {
+            const respond = decision.respond;
+            if (respond.error)
+                return scriptedMessagesError(respond.error);
+            scripted = realizeMoonshotRespond(respond);
+        }
+        else {
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in handlers/moonshot.json.]`;
+        }
+    }
+    const inputTokens = countPromptTokens(args.messages.map((m) => ({ role: m.role, content: m.content })));
+    let content;
+    let stopReason;
+    let outputTokens;
+    if (scripted) {
+        content = [];
+        if (scripted.reasoning !== null)
+            content.push({ type: 'thinking', thinking: scripted.reasoning, signature: stubSignature(args.messages, args.model) });
+        if (scripted.text)
+            content.push({ type: 'text', text: scripted.text + (missTeach && scripted.text ? missTeach : '') });
+        for (const tc of scripted.toolCalls) {
+            content.push({ type: 'tool_use', id: tc.id, name: tc.function.name, input: JSON.parse(tc.function.arguments) });
+        }
+        stopReason = scripted.finishReason === 'tool_calls' ? 'tool_use' : scripted.finishReason === 'length' ? 'max_tokens' : 'end_turn';
+    }
+    else {
+        // Tools on the Messages surface are REAL surface: tool_choice 'any'/'auto' (with tools
+        // present) yields a tool_use block the SDK's own decoder reads; a named 'tool' choice calls
+        // THAT tool; 'none' suppresses. The tautology that silently answered text regardless (the
+        // round-two finding) is gone.
+        const hasTools = Array.isArray(args.tools) && args.tools.length > 0;
+        const choice = args.toolChoice?.type ?? 'auto';
+        const suppress = choice === 'none';
+        const forcedName = choice === 'tool' ? args.toolChoice?.name : undefined;
+        // A tool_result turn is ANSWERED, not re-tooled: once the client returns the tool_result the
+        // model's next turn is text with stop_reason end_turn — deciding tool_use from tools.length
+        // alone made an agent loop emit tool_use forever (the round-three finding). An EXPLICIT
+        // forced choice ('any'/'tool') still calls, because the caller demanded one.
+        const last = args.messages[args.messages.length - 1];
+        const toolResultTurn = last?.role === 'user' && Array.isArray(last.content)
+            && last.content.some((b) => b?.type === 'tool_result');
+        const forceTool = choice === 'any' || choice === 'tool';
+        const toolCalls = hasTools && !suppress && (forceTool || !toolResultTurn)
+            ? [stubToolCall(args.tools, 1, forcedName)].filter((tc) => tc !== null)
+            : [];
+        // kimi-k3 ALWAYS thinks (Preserved Thinking — the same rule the /v1 surface applies), and
+        // Moonshot's Messages doc has NO thinking parameter: reasoning is tuned through
+        // output_config.effort (default max) and the content array is documented
+        // "ordered thinking → text → tool_use" (platform.kimi.ai/docs/api/messages, read
+        // 2026-09-16) — so the thinking block leads unconditionally, like the vendor's.
+        content = [
+            { type: 'thinking', thinking: stubReasoningContent(args.messages.map((m) => ({ role: m.role, content: m.content })), args.model), signature: stubSignature(args.messages, args.model) },
+        ];
+        if (toolCalls.length) {
+            toolCalls.forEach((tc, seq) => {
+                // Anthropic's tool_use id prefix is `toolu_` (the sibling pack's grammar —
+                // `toolu_twin_${seq}`), NOT the `call_` prefix the OpenAI-compatible /v1 surface uses.
+                content.push({ type: 'tool_use', id: `toolu_twin_${seq + 1}`, name: tc.function.name, input: JSON.parse(tc.function.arguments) });
+            });
+        }
+        else {
+            content.push({ type: 'text', text: stubAssistantText(args.messages.map((m) => ({ role: m.role, content: m.content })), args.model) + (missTeach || '') });
+        }
+        stopReason = toolCalls.length ? 'tool_use' : 'end_turn';
+    }
+    // max_tokens caps the OUTPUT ITSELF, not merely the report: truncate the emitted blocks to the
+    // cap and count usage off what remains (the vendor stops emitting at the cap — usage.output_tokens
+    // is what was emitted, never a fabricated agreement with a text block it did not produce).
+    // Tokens are counted per-block off the block's own payload (thinking/text/tool input), NOT off
+    // JSON.stringify of the whole array — JSON scaffolding would keep a capped answer above its cap.
+    const blockTokens = (b) => b.type === 'thinking' ? estimateTokens(b.thinking)
+        : b.type === 'text' ? estimateTokens(b.text)
+            : estimateTokens(JSON.stringify(b.input));
+    const totalTokens = () => content.reduce((n, b) => n + blockTokens(b), 0);
+    if (args.maxTokens !== undefined && totalTokens() > args.maxTokens) {
+        // THE CAP WALKS THE BLOCKS IN ORDER (the sibling pack's method): the emitted content is a
+        // PREFIX of what the stub would have said. Each block is kept only as far as the remaining
+        // budget allows — text and thinking truncate mid-string, a tool_use that does not fit ends
+        // the turn (everything after it is never emitted). Anthropic NEVER returns a zero-block
+        // assistant message: the FIRST block is kept truncated to at least one token, so
+        // output_tokens > 0 and content is non-empty at any cap >= 1. The walk is BOUNDED — one
+        // pass, one truncation — so no estimate can spin it.
+        let spent = 0;
+        let cut = false;
+        for (let i = 0; i < content.length; i++) {
+            const block = content[i];
+            const cost = blockTokens(block);
+            if (spent + cost <= args.maxTokens) {
+                spent += cost;
+                continue;
+            }
+            const budget = args.maxTokens - spent;
+            cut = true;
+            if ((block.type === 'text' || block.type === 'thinking') && (budget >= 1 || i === 0)) {
+                // Truncate to the remaining budget (~4 chars/token), keeping at least one token so the
+                // message never loses its last block — the floor a zero-block message is forbidden by.
+                const keep = Math.max(1, budget);
+                if (block.type === 'text')
+                    block.text = block.text.slice(0, keep * 4);
+                else
+                    block.thinking = block.thinking.slice(0, keep * 4);
+                spent += blockTokens(block);
+                content.length = i + 1;
+                break;
+            }
+            // The budget ran out exactly at this block's boundary, or the block is a tool_use that
+            // cannot be cut: the block was never emitted. A retained whole block here shipped 57
+            // tokens under max_tokens 23 (round-four review) — the cap is a prefix, never a rounding.
+            content.length = i;
+            if (content.length === 0)
+                content.push({ type: 'text', text: '' });
+            break;
+        }
+        outputTokens = spent;
+        if (cut)
+            stopReason = 'max_tokens';
+    }
+    else {
+        outputTokens = totalTokens();
+    }
+    // A stop_sequence match truncates the text at the hit and reports stop_reason 'stop_sequence'
+    // with the matched string (Anthropic's documented shape — 'end_turn' would misreport WHY the
+    // turn ended). The RECOUNT happens AFTER the truncation: usage.output_tokens is what was
+    // emitted, so a 113-char answer reported as 54 tokens (counted before the cut) contradicted
+    // its own usage (the round-three finding).
+    let stopSequence = null;
+    if (args.stopSequences?.length) {
+        const textBlock = content.find((b) => b.type === 'text');
+        if (textBlock && textBlock.type === 'text') {
+            for (const s of args.stopSequences) {
+                const i = textBlock.text.indexOf(s);
+                if (i >= 0) {
+                    textBlock.text = textBlock.text.slice(0, i);
+                    stopSequence = s;
+                    stopReason = 'stop_sequence';
+                    break;
+                }
+            }
+            outputTokens = totalTokens();
+        }
+    }
+    return {
+        id: `msg_twin_${stableSuffix(args.messages, args.model)}`,
+        type: 'message',
+        role: 'assistant',
+        model: args.model,
+        content,
+        stop_reason: stopReason,
+        stop_sequence: stopSequence,
+        usage: {
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            cache_read_input_tokens: stubCachedTokens(inputTokens),
+            cache_creation_input_tokens: 0,
+        },
+    };
+}
+function scriptedMessagesError(err) {
+    if (err.type === 'rate_limit_reached_error')
+        return messagesError(429, 'rate_limit_reached_error', err.message ?? 'Request rate limit reached');
+    if (err.type === 'server_unavailable')
+        return messagesError(503, 'server_unavailable', err.message ?? 'The server is overloaded');
+    return messagesError(500, 'server_error', err.message ?? 'Internal Server Error');
+}
+/**
+ * Emit the Anthropic-compatible streaming grammar into the injected sink: message_start →
+ * ping → content_block_start(thinking) → thinking_delta → signature_delta → content_block_stop →
+ * content_block_start(text) → text_delta → content_block_stop → message_delta(stop_reason) →
+ * message_stop. No [DONE] sentinel — the stream ends after message_stop.
+ *
+ * message_start carries the EMPTY message (content: [], stop_reason: null, output_tokens small)
+ * and the blocks stream in one at a time — the real grammar (and the sibling pack's frames). A
+ * message_start carrying the COMPLETE final message made the SDK's own accumulator double every
+ * block: it pushes one block per content_block_start ON TOP of what message_start already held
+ * (the round-three BLOCKER).
+ */
+export function streamMessages(args, sink, occurredAt, decision) {
+    const built = buildMessagesResponse(args, occurredAt, decision);
+    if (isEnvelope(built))
+        return built;
+    const full = built;
+    sink({
+        event: 'message_start',
+        data: {
+            type: 'message_start',
+            message: {
+                id: full.id, type: 'message', role: 'assistant', model: full.model,
+                content: [], stop_reason: null, stop_sequence: null,
+                usage: { input_tokens: full.usage.input_tokens, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+            },
+        },
+    });
+    // The heartbeat the real API interleaves (and the sibling pack emits); the SDK's SSE decoder
+    // skips `event: ping` frames by name, so it is inert to every consumer.
+    sink({ event: 'ping', data: { type: 'ping' } });
+    full.content.forEach((block, index) => {
+        if (block.type === 'thinking') {
+            sink({ event: 'content_block_start', data: { type: 'content_block_start', index, content_block: { type: 'thinking', thinking: '' } } });
+            for (const piece of chunkText(block.thinking))
+                sink({ event: 'content_block_delta', data: { type: 'content_block_delta', index, delta: { type: 'thinking_delta', thinking: piece } } });
+            sink({ event: 'content_block_delta', data: { type: 'content_block_delta', index, delta: { type: 'signature_delta', signature: block.signature ?? '' } } });
+            sink({ event: 'content_block_stop', data: { type: 'content_block_stop', index } });
+        }
+        else if (block.type === 'text') {
+            sink({ event: 'content_block_start', data: { type: 'content_block_start', index, content_block: { type: 'text', text: '' } } });
+            for (const piece of chunkText(block.text))
+                sink({ event: 'content_block_delta', data: { type: 'content_block_delta', index, delta: { type: 'text_delta', text: piece } } });
+            sink({ event: 'content_block_stop', data: { type: 'content_block_stop', index } });
+        }
+        else {
+            sink({ event: 'content_block_start', data: { type: 'content_block_start', index, content_block: { type: 'tool_use', id: block.id, name: block.name, input: {} } } });
+            const json = JSON.stringify(block.input);
+            sink({ event: 'content_block_delta', data: { type: 'content_block_delta', index, delta: { type: 'input_json_delta', partial_json: json } } });
+            sink({ event: 'content_block_stop', data: { type: 'content_block_stop', index } });
+        }
+    });
+    sink({ event: 'message_delta', data: { type: 'message_delta', delta: { stop_reason: full.stop_reason, stop_sequence: full.stop_sequence }, usage: { output_tokens: full.usage.output_tokens } } });
+    sink({ event: 'message_stop', data: { type: 'message_stop' } });
+    sink({ done: true });
+    return full;
+}
+function validateResponses(params) {
+    if (params.model === undefined || params.model === '')
+        return { error: invalidRequest("'model' is a required property") };
+    // "This endpoint currently supports `kimi-k3`" (ResponsesRequest.model) — read from the
+    // catalog's own supports flag, so the enum and the catalog cannot drift apart.
+    const responsesModel = findModel(String(params.model));
+    if (!responsesModel?.supports.responses)
+        return { error: invalidRequest(`This endpoint currently supports 'kimi-k3' only (got '${String(params.model)}')`) };
+    if (params.input === undefined || params.input === null)
+        return { error: invalidRequest("'input' is a required property") };
+    if (typeof params.input !== 'string' && !Array.isArray(params.input))
+        return { error: invalidRequest("'input' must be a string or an array of items") };
+    let reasoningEffort;
+    const r = params.reasoning;
+    if (r && typeof r === 'object' && r.effort !== undefined) {
+        if (typeof r.effort !== 'string' || !REASONING_EFFORTS.includes(r.effort)) {
+            return { error: invalidRequest(`'reasoning.effort' must be one of ${REASONING_EFFORTS.map((t) => `'${t}'`).join(', ')}`) };
+        }
+        reasoningEffort = r.effort;
+    }
+    let maxOutputTokens;
+    if (params.max_output_tokens !== undefined) {
+        maxOutputTokens = Number(params.max_output_tokens);
+        if (!Number.isInteger(maxOutputTokens) || maxOutputTokens < 1)
+            return { error: invalidRequest("'max_output_tokens' must be an integer >= 1") };
+    }
+    return {
+        args: {
+            model: String(params.model),
+            input: params.input,
+            ...(typeof params.instructions === 'string' ? { instructions: params.instructions } : {}),
+            ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+            ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+            stream: params.stream === true,
+        },
+    };
+}
+function responsesInputText(input) {
+    if (typeof input === 'string')
+        return input;
+    return input.map((item) => {
+        if (item.type === 'message' || item.type === undefined) {
+            const content = item.content;
+            return contentToText(content);
+        }
+        return JSON.stringify(item);
+    }).join('\n');
+}
+export function buildResponsesResponse(args, occurredAt, decision) {
+    let scripted = null;
+    let missTeach = '';
+    if (decision) {
+        // The route served the request through the engine (R15); this realizer only sees the
+        // content decision.
+        if (decision.kind === 'handler') {
+            const respond = decision.respond;
+            if (respond.error)
+                return scriptedError(respond.error);
+            scripted = realizeMoonshotRespond(respond);
+        }
+        else {
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in handlers/moonshot.json.]`;
+        }
+    }
+    const inputText = responsesInputText(args.input);
+    const asMessages = [{ role: 'user', content: inputText }];
+    const inputTokens = countPromptTokens(asMessages);
+    const output = [];
+    let outputTokens = 0;
+    if (scripted) {
+        if (scripted.reasoning !== null) {
+            output.push({ type: 'reasoning', id: `rs_twin_${stableSuffix(args.input, 'reasoning')}`, summary: [{ type: 'summary_text', text: scripted.reasoning }], status: 'completed' });
+            outputTokens += estimateTokens(scripted.reasoning);
+        }
+        if (scripted.toolCalls.length) {
+            for (const tc of scripted.toolCalls) {
+                output.push({ type: 'function_call', id: `fc_twin_${stableSuffix(tc)}`, call_id: tc.id, name: tc.function.name, arguments: tc.function.arguments, status: 'completed' });
+                outputTokens += estimateTokens(tc.function.arguments);
+            }
+        }
+        else {
+            const text = (scripted.text ?? '') + (missTeach || '');
+            output.push({ type: 'message', id: `msg_twin_${stableSuffix(args.input, 'message')}`, role: 'assistant', status: 'completed', content: [{ type: 'output_text', text, annotations: [] }] });
+            outputTokens += estimateTokens(text);
+        }
+    }
+    else {
+        output.push({ type: 'reasoning', id: `rs_twin_${stableSuffix(inputText, 'reasoning')}`, summary: [{ type: 'summary_text', text: stubReasoningContent(asMessages, args.model) }], status: 'completed' });
+        const text = stubAssistantText(asMessages, args.model) + (missTeach || '');
+        output.push({ type: 'message', id: `msg_twin_${stableSuffix(inputText, 'message')}`, role: 'assistant', status: 'completed', content: [{ type: 'output_text', text, annotations: [] }] });
+        outputTokens = estimateTokens(stubReasoningContent(asMessages, args.model)) + estimateTokens(text);
+    }
+    let status = 'completed';
+    let incompleteDetails = null;
+    // max_output_tokens caps the OUTPUT ITSELF: the vendor stops emitting at the cap, so truncate
+    // the emitted items (dropping whole items from the tail — the Responses API emits complete
+    // items) and let usage.output_tokens count what remains. Reporting status 'incomplete' with
+    // usage.output_tokens still above the cap was the round-two finding: the envelope contradicted
+    // its own usage.
+    if (args.maxOutputTokens !== undefined && outputTokens > args.maxOutputTokens) {
+        // THE CAP IS A PREFIX, LIKE THE MESSAGES SURFACE'S: items are emitted in order until the
+        // budget is exhausted; a text-carrying item truncates to the remaining budget rather than
+        // vanishing, so a tight cap still yields a non-empty output with output_tokens > 0 — a
+        // zero-item `output: []` (the round-three finding at max_output_tokens 2) is a message the
+        // vendor never sends. One bounded pass; nothing after the cut is emitted.
+        let spent = 0;
+        let cut = false;
+        for (let i = 0; i < output.length; i++) {
+            const item = output[i];
+            const cost = estimateTokens(item.type === 'message' ? item.content.map((c) => c.text ?? '').join('')
+                : item.type === 'reasoning' ? item.summary.map((s) => s.text ?? '').join('')
+                    : item.type === 'function_call' ? item.arguments : item.type === 'custom_tool_call' ? item.input : '');
+            if (spent + cost <= args.maxOutputTokens) {
+                spent += cost;
+                continue;
+            }
+            const budget = args.maxOutputTokens - spent;
+            const keep = Math.max(1, budget) * 4;
+            if ((item.type === 'message' || item.type === 'reasoning') && budget >= 1) {
+                if (item.type === 'message')
+                    item.content[0].text = (item.content[0].text ?? '').slice(0, keep);
+                else
+                    item.summary[0].text = (item.summary[0].text ?? '').slice(0, keep);
+                spent += estimateTokens(item.type === 'message' ? item.content[0].text ?? '' : item.summary[0].text ?? '');
+            }
+            output.length = i + 1;
+            cut = true;
+            break;
+        }
+        outputTokens = spent;
+        if (cut) {
+            status = 'incomplete';
+            incompleteDetails = { reason: 'max_output_tokens' };
+        }
+    }
+    return {
+        id: `resp_twin_${stableSuffix(inputText, args.model)}`,
+        object: 'response',
+        created_at: nowEpoch(occurredAt),
+        completed_at: status === 'completed' || status === 'incomplete' ? nowEpoch(occurredAt) : null,
+        status,
+        model: args.model,
+        output,
+        usage: {
+            input_tokens: inputTokens,
+            input_tokens_details: { cached_tokens: stubCachedTokens(inputTokens), cache_write_tokens: 0 },
+            output_tokens: outputTokens,
+            // reasoning_tokens counts the REASONING items only (the /anthropic thinking_tokens path
+            // does the same): reporting the whole output_tokens as reasoning claimed every text token
+            // was reasoning (the round-three finding).
+            output_tokens_details: {
+                reasoning_tokens: output
+                    .filter((o) => o.type === 'reasoning')
+                    .reduce((n, o) => n + estimateTokens(o.summary.map((s) => s.text ?? '').join('')), 0),
+            },
+            total_tokens: inputTokens + outputTokens,
+        },
+        incomplete_details: incompleteDetails,
+        error: null,
+        store: false,
+    };
+}
+/**
+ * Emit the Responses SSE grammar into the injected sink: response.created →
+ * response.in_progress → output_item.added/done per item → response.completed. Each frame
+ * carries `event: <type>` and a monotonically increasing `sequence_number` from 0.
+ */
+export function streamResponses(args, sink, occurredAt, decision) {
+    const built = buildResponsesResponse(args, occurredAt, decision);
+    if (isEnvelope(built))
+        return built;
+    const full = built;
+    let seq = 0;
+    const emit = (type, data) => sink({ event: type, data: { type, sequence_number: seq++, ...data } });
+    emit('response.created', { response: { ...full, status: 'in_progress', output: [], usage: null } });
+    emit('response.in_progress', { response: { ...full, status: 'in_progress', output: [], usage: null } });
+    for (const item of full.output) {
+        emit('response.output_item.added', { output_index: full.output.indexOf(item), output_item: item });
+        emit('response.output_item.done', { output_index: full.output.indexOf(item), output_item: item });
+    }
+    emit(full.status === 'completed' ? 'response.completed' : 'response.incomplete', { response: full });
+    sink({ done: true });
+    return full;
+}
+// ── public entry: cross-cutting protocol (auth / rate-limit) then route ─────────────────
+export async function handleMoonshotTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    // EVERY cross-cutting failure answers in the prefix's OWN envelope: the /anthropic surface's
+    // documented client decodes Anthropic's {type:'error',error:{…}} grammar, so a 401/429/503
+    // there carrying the /v1 envelope would be unparseable to it (the clone's lie, cross-cutting
+    // edition). checkAuth applies this itself; the two deterministic fault triggers follow.
+    const onMessages = onMessagesPath(req.path);
+    if (req.headers !== undefined || req.apiKey !== undefined) {
+        const authErr = checkAuth(req);
+        if (authErr)
+            return authErr;
+    }
+    if (triggered(req, 'x-twin-force-rate-limit')) {
+        const base = rateLimitError();
+        // The HEADERS ride along on the re-enveloped 429: retry-after and the X-RateLimit-* family
+        // are part of the refusal a real client reads, whatever envelope the body wears — dropping
+        // them on /anthropic left the documented SDK blind to the back-off (the round-three finding).
+        return onMessages
+            ? { ...messagesError(429, 'rate_limit_error', base.body.error.message), headers: base.headers }
+            : base;
+    }
+    if (triggered(req, 'x-twin-force-server-unavailable')) {
+        const base = serverUnavailable();
+        return onMessages ? messagesError(503, 'overloaded_error', base.body.error.message) : base;
+    }
+    const res = await routeMoonshot(req, method);
+    // Moonshot's request-signing contract, in the HANDLER so every surface (server, fetch
+    // adapter, in-process callers) signs identically (§9 round two, F8): a STREAMED model call
+    // that carries `X-Msh-Request-Nonce` gets `Msh-Request-Timestamp` + `Msh-Request-Signature`
+    // response headers; a nonce-less call proceeds unsigned. The server forwards these headers
+    // on the SSE response it frames.
+    const nonce = req.headers?.['x-msh-request-nonce'];
+    if (nonce && req.sseSink && req.method.toUpperCase() === 'POST' && (req.path === `${MOONSHOT_API_PREFIX}/chat/completions`)) {
+        const model = (() => { try {
+            return typeof JSON.parse(req.body ?? '').model === 'string' ? JSON.parse(req.body ?? '').model : null;
+        }
+        catch {
+            return null;
+        } })();
+        if (model) {
+            const ts = Date.parse(req.occurredAt ?? worldNow());
+            return { ...res, headers: { ...(res.headers ?? {}), 'msh-request-timestamp': String(ts), 'msh-request-signature': messagesSignature(nonce, ts, model) } };
+        }
+    }
+    return res;
+}
+// ── router ──────────────────────────────────────────────────────────────────────────────
+async function routeMoonshot(req, method) {
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    const params = parseJson(req.body);
+    const dec = (s) => decodeURIComponent(s);
+    const onOpenai = path === MOONSHOT_API_PREFIX || path.startsWith(`${MOONSHOT_API_PREFIX}/`);
+    const onMessages = path === MESSAGES_PREFIX || path.startsWith(`${MESSAGES_PREFIX}/`);
+    if (!onOpenai && !onMessages) {
+        return notFound(`Unknown request URL: ${method} ${path}.`);
+    }
+    // D3: a read-only twin rejects any mutation with a vendor-shaped error — in the prefix's OWN
+    // envelope (the Messages surface decodes Anthropic's grammar, not /v1's), so a read-only twin
+    // never hands the anthropic SDK an envelope it cannot parse. Computed AFTER the prefix so the
+    // envelope follows the path, not the call order.
+    if (req.readOnly && method !== 'GET') {
+        const message = 'twin is read-only; omit readOnly to accept writes';
+        return onMessages ? messagesError(405, 'invalid_request_error', message) : { status: 405, body: errBody('invalid_request_error', message) };
+    }
+    // ---- Anthropic-compatible Messages surface ----
+    if (onMessages) {
+        if (path !== `${MESSAGES_PREFIX}/messages`)
+            return messagesError(404, 'not_found_error', `Unknown request URL: ${method} ${path}.`);
+        if (method !== 'POST')
+            return messagesError(405, 'invalid_request_error', `${method} is not supported on /anthropic/v1/messages`);
+        const validated = validateMessages(params);
+        if ('error' in validated)
+            return validated.error;
+        const args = validated.args;
+        // R15 — the scenario engine decides AND honors a fault here, before any message exists:
+        // a `status` fault is this vendor's own refusal envelope re-worn in the Anthropic shape,
+        // a `slow` has already held the answer, a `drop` never returns.
+        let messagesDecision;
+        if (req.scenarioEngine) {
+            const served = await req.scenarioEngine.serve({ model: args.model, messages: args.messages.map((m) => ({ role: m.role, content: m.content })), tools: args.tools, thinking: undefined });
+            if (served.kind === 'fault')
+                return { status: served.result.status, body: messagesErrorBody(served.result.status, served.result.body), headers: served.result.headers };
+            messagesDecision = served;
+        }
+        const result = args.stream && req.messagesSseSink
+            ? streamMessages(args, req.messagesSseSink, req.occurredAt, messagesDecision)
+            : buildMessagesResponse(args, req.occurredAt, messagesDecision);
+        if (isEnvelope(result))
+            return result;
+        return { status: 200, body: result };
+    }
+    const seg = path.slice(MOONSHOT_API_PREFIX.length).replace(/^\/+/, '').split('/').filter(Boolean); // ["chat","completions"]
+    // protocol 2: after a landing adopted Moonshot's id for a file or a batch, a caller on a branch
+    // may still address it by the local id — resolved through the alias map once, here at the boundary
+    if (seg[0] === 'files' && seg[1])
+        seg[1] = resolveSubjectId(SERVICE, 'file', dec(seg[1]), req.root);
+    if (seg[0] === 'batches' && seg[1])
+        seg[1] = resolveSubjectId(SERVICE, 'batch', dec(seg[1]), req.root);
+    // ---- models (static catalog) ----
+    // LIST only: Moonshot's own OpenAPI declares GET /v1/models and NO retrieve-by-id operation
+    // (the fixture's 19 operations have no /v1/models/{model}) — serving a 200 retrieve here was a
+    // 200 for an unmodeled route. An unknown/unmodeled sub-path falls through to the router's
+    // vendor-shaped not-found below.
+    if (seg[0] === 'models' && seg.length === 1 && method === 'GET') {
+        return { status: 200, body: { object: 'list', data: servedModels(req.root) } };
+    }
+    // ---- chat completions (the generative stub; envelope is faithful) ----
+    if (seg[0] === 'chat' && seg[1] === 'completions' && seg.length === 2 && method === 'POST') {
+        const validated = validateChat(params);
+        if ('error' in validated)
+            return validated.error;
+        const args = validated.args;
+        // R15 — the scenario engine decides AND honors a fault here, before any completion exists:
+        // a `status` fault is this vendor's own refusal envelope, a `slow` has already held the
+        // answer, a `drop` never returns. The realizers below only see a content decision.
+        let chatDecision;
+        if (req.scenarioEngine) {
+            const served = await req.scenarioEngine.serve({ model: args.model, messages: args.messages, tools: args.tools, thinking: args.thinking });
+            if (served.kind === 'fault')
+                return { status: served.result.status, body: served.result.body, headers: served.result.headers };
+            chatDecision = served;
+        }
+        const result = args.stream && req.sseSink
+            ? streamChat(args, req.sseSink, req.occurredAt, chatDecision)
+            : buildChatCompletion(args, req.occurredAt, chatDecision);
+        if (isEnvelope(result))
+            return result;
+        return { status: 200, body: result };
+    }
+    // ---- responses (kimi-k3 only) ----
+    if (seg[0] === 'responses' && seg.length === 1 && method === 'POST') {
+        const validated = validateResponses(params);
+        if ('error' in validated)
+            return validated.error;
+        const args = validated.args;
+        // R15 — the same serve-and-honor as chat completions: the Responses door serves the same
+        // scripted brain from the same handlers document.
+        let responsesDecision;
+        if (req.scenarioEngine) {
+            const served = await req.scenarioEngine.serve({ model: args.model, messages: [{ role: 'user', content: responsesInputText(args.input) }], tools: undefined, thinking: undefined });
+            if (served.kind === 'fault')
+                return { status: served.result.status, body: served.result.body, headers: served.result.headers };
+            responsesDecision = served;
+        }
+        const result = args.stream && req.messagesSseSink
+            ? streamResponses(args, req.messagesSseSink, req.occurredAt, responsesDecision)
+            : buildResponsesResponse(args, req.occurredAt, responsesDecision);
+        if (isEnvelope(result))
+            return result;
+        return { status: 200, body: result };
+    }
+    // ---- token counting ----
+    if (seg[0] === 'tokenizers' && seg[1] === 'estimate-token-count' && seg.length === 2 && method === 'POST') {
+        return handleEstimateTokens(params);
+    }
+    // ---- signatures ----
+    if (seg[0] === 'signatures' && seg[1] === 'verify' && seg.length === 2 && method === 'POST') {
+        return handleSignatureVerify(params, req);
+    }
+    // ---- web-search tools ----
+    if (seg[0] === 'tools' && seg[1] === 'search' && seg.length === 2 && method === 'POST')
+        return handleToolsSearch(params, false);
+    if (seg[0] === 'tools' && seg[1] === 'search_pro' && seg.length === 2 && method === 'POST')
+        return handleToolsSearch(params, true);
+    if (seg[0] === 'tools' && seg[1] === 'fetch' && seg.length === 2 && method === 'POST')
+        return handleToolsFetch(params);
+    // ---- balance (Moonshot's own envelope) ----
+    if (seg[0] === 'users' && seg[1] === 'me' && seg[2] === 'balance' && seg.length === 3 && method === 'GET') {
+        return balanceView(req.root);
+    }
+    // ---- files (stateful) ----
+    if (seg[0] === 'files' && seg.length === 1 && method === 'POST')
+        return createFile(params, req);
+    if (seg[0] === 'files' && seg.length === 1 && method === 'GET') {
+        const data = rows('file', req.root).filter((r) => !r._deleted).map(fileView);
+        return { status: 200, body: { object: 'list', data } };
+    }
+    if (seg[0] === 'files' && seg.length === 2 && method === 'GET') {
+        const f = getRow('file', dec(seg[1]), req.root);
+        return f && !f._deleted ? { status: 200, body: fileView(f) } : notFound(`No such File object: ${dec(seg[1])}`);
+    }
+    if (seg[0] === 'files' && seg.length === 3 && seg[2] === 'content' && method === 'GET') {
+        const f = getRow('file', dec(seg[1]), req.root);
+        if (!f || f._deleted)
+            return notFound(`No such File object: ${dec(seg[1])}`);
+        // A PULLED file (the connector's mapFile) carries metadata only — the real list endpoint
+        // returns no content, so the twin holds none. Serving an empty 200 here was a §9-round-two
+        // finding (F2): a fake success for bytes the twin does not have. The honest answer is a
+        // vendor-shaped refusal naming the gap.
+        if (f._content === undefined && Number(f.bytes) > 0) {
+            return { status: 501, body: errBody('server_error', `the twin holds no content for pulled file ${dec(seg[1])} (the vendor's list endpoint does not return file content; re-create the file locally to read it back)`) };
+        }
+        // The server turns the body STRING into bytes; this header tells it how (§9 round two, F1):
+        // a binary upload (the multipart adapter's `binary_content` marker → `_content_encoding`)
+        // is decoded from its stored base64 and carried latin1 (every byte value intact through a
+        // JS string, re-materialized by the server); anything else is TEXT and travels as the
+        // string itself — the server writes it UTF-8, so a non-ASCII text file round-trips.
+        if (f._content_encoding === 'base64') {
+            const raw = Buffer.from(String(f._content ?? ''), 'base64').toString('latin1');
+            return { status: 200, body: raw, headers: { 'content-type': 'application/octet-stream', 'x-twin-content-binary': '1' } };
+        }
+        return { status: 200, body: String(f._content ?? ''), headers: { 'content-type': 'application/octet-stream' } };
+    }
+    if (seg[0] === 'files' && seg.length === 2 && method === 'DELETE') {
+        const fid = dec(seg[1]);
+        const f = getRow('file', fid, req.root);
+        if (!f || f._deleted)
+            return notFound(`No such File object: ${fid}`);
+        await applyTwinWrite(SERVICE, {
+            operation: 'file.delete', subjectType: 'file', subjectId: fid, fields: { _deleted: true, object: 'file' },
+            ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+        }, req.root);
+        return { status: 200, body: { id: fid, object: 'file', deleted: true } };
+    }
+    // ---- batches (stateful) ----
+    if (seg[0] === 'batches' && seg.length === 1 && method === 'POST')
+        return createBatch(params, req);
+    if (seg[0] === 'batches' && seg.length === 1 && method === 'GET') {
+        return { status: 200, body: { object: 'list', data: rows('batch', req.root).map(batchView), has_more: false } };
+    }
+    if (seg[0] === 'batches' && seg.length === 2 && method === 'GET') {
+        const b = getRow('batch', dec(seg[1]), req.root);
+        if (!b)
+            return notFound(`No such Batch object: ${dec(seg[1])}`);
+        return { status: 200, body: batchView(b) };
+    }
+    if (seg[0] === 'batches' && seg.length === 3 && seg[2] === 'cancel' && method === 'POST') {
+        const bid = dec(seg[1]);
+        const b = getRow('batch', bid, req.root);
+        if (!b)
+            return notFound(`No such Batch object: ${bid}`);
+        if (b.status === 'cancelling' || b.status === 'cancelled')
+            return invalidRequest(`Cannot cancel a batch with status '${String(b.status)}'.`);
+        // NOTE: the twin does not simulate the asynchronous cancelling→cancelled settlement (the
+        // groq pack's §9 finding applies identically here: settling on a READ would break the
+        // read-only contract). The terminal transition is filed as
+        // `moonshot.batches.cancellation_settles` (todo).
+        await applyTwinWrite(SERVICE, {
+            operation: 'batch.cancel', subjectType: 'batch', subjectId: bid,
+            fields: { status: 'cancelling', cancelling_at: nowEpoch(req.occurredAt) },
+            ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+        }, req.root);
+        return { status: 200, body: batchView(getRow('batch', bid, req.root) ?? {}) };
+    }
+    // Unmodeled operation → fail like the vendor (never a fake success). A /anthropic path that
+    // is not /messages was already refused in the Messages branch; anything falling through here
+    // is on the OpenAI-compatible surface, whose 404 envelope this is.
+    return notFound(`Unknown request URL: ${method} ${path}.`);
+}