@volter/twin-moonshot 0.1.0

package/src/moonshot-twin.ts

@@ -0,0 +1,1670 @@
+// 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, type ScenarioDecision, worldNow } from '@volter/world-core';
+import {
+  findModel,
+  K26_THINKING_TYPES,
+  K27_THINKING_TYPES,
+  MOONSHOT_MODELS,
+  REASONING_EFFORTS,
+  type ReasoningEffort,
+} from './moonshot-models.ts';
+import {
+  buildChatUsage,
+  contentToText,
+  countPromptTokens,
+  estimateTokens,
+  fnv1a,
+  lastUserText,
+  stableSuffix,
+  stubAssistantText,
+  stubCachedTokens,
+  stubFetchedMarkdown,
+  stubJsonObject,
+  stubReasoningContent,
+  stubSearchResults,
+  stubSignature,
+  stubToolArguments,
+  stubToolCall,
+} from './moonshot-stub.ts';
+import { type MoonshotScenarioEngine, type MoonshotScenarioRespond, realizeMoonshotRespond, type ScriptedResult } from './moonshot-scenario.ts';
+import type {
+  MessagesSseEvent,
+  MoonshotAssistantMessage,
+  MoonshotChatCompletion,
+  MoonshotChoice,
+  MoonshotMessageParam,
+  MoonshotMessagesResponse,
+  MoonshotResponsesOutputItem,
+  MoonshotResponsesResponse,
+  MoonshotToolCall,
+  MoonshotUsage,
+  SseEvent,
+  SseSink,
+} from './moonshot-types.ts';
+
+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';
+
+export type MoonshotRequest = {
+  /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts the three
+   *  inference endpoints. */
+  scenarioEngine?: MoonshotScenarioEngine;
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The credential the caller presents (the bearer `Authorization` header). When a request
+   *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the
+   *  real vendor rule: a credential is required → 401 on missing/invalid. In-process trusted
+   *  calls (capability verify, connector) omit BOTH and are not auth-gated. */
+  apiKey?: string;
+  /** Lower-cased request headers the HTTP server passes through so the handler can model auth
+   *  (401), the rate-limit trigger (429), and the signature headers the /v1/signatures/verify
+   *  contract references. */
+  headers?: Record<string, string>;
+  /** When set on a streaming POST, chunks/events are written here (no sockets). */
+  sseSink?: SseSink;
+  /** When set on a streaming /anthropic/v1/messages POST, Anthropic-grammar events are written
+   *  here (event name + data; no sockets). */
+  messagesSseSink?: MessagesSseSink;
+};
+
+/** The handler response. `headers` (when present) are response headers the HTTP server should
+ *  set — e.g. `retry-after` + Moonshot's `x-ratelimit-*` family on a modeled 429. */
+export type MoonshotResponseEnvelope = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── 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: string, message: string, code?: string) {
+  return { error: { message, ...(type !== undefined ? { type } : {}), ...(code !== undefined ? { code } : {}) } };
+}
+function invalidRequest(message: string, code?: string): MoonshotResponseEnvelope {
+  return { status: 400, body: errBody('invalid_request_error', message, code) };
+}
+function notFound(message: string): MoonshotResponseEnvelope {
+  return { status: 404, body: errBody('resource_not_found_error', message) };
+}
+function authError(message: string, type: string): MoonshotResponseEnvelope {
+  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: MoonshotRequest): MoonshotResponseEnvelope | null {
+  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: string): boolean {
+  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(): MoonshotResponseEnvelope {
+  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(): MoonshotResponseEnvelope {
+  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: MoonshotRequest, header: string): boolean {
+  const v = req.headers?.[header];
+  return v === '1' || v === 'true';
+}
+
+function nowEpoch(occurredAt?: string): number {
+  return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  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: string, prefix: string, root?: string): string {
+  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?: string): Array<Record<string, unknown>> {
+  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?: string): Array<Record<string, unknown>> {
+  const pulled = pulledModels(root);
+  const byId = new Map<string, Record<string, unknown>>();
+  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: string, id: string, root?: string): Record<string, unknown> | undefined {
+  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: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  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?: string): Record<string, unknown> {
+  if (!body || !body.trim()) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+// ── chat completions: validate the request the way Moonshot does ────────────────────────
+type ToolChoice = 'auto' | 'none' | 'required' | { name: string };
+type ResponseFormat = { kind: 'text' } | { kind: 'json_object' } | { kind: 'json_schema'; schema: unknown };
+type Thinking = { type: 'enabled' | 'disabled'; keep?: string | null };
+
+/** 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;
+
+type ChatArgs = {
+  model: string;
+  messages: MoonshotMessageParam[];
+  tools?: unknown[];
+  n: number;
+  maxTokens?: number;
+  stop?: string[];
+  stream: boolean;
+  streamOptions?: { includeUsage: boolean };
+  toolChoice?: ToolChoice;
+  responseFormat: ResponseFormat;
+  logprobs: boolean;
+  topLogprobs?: number;
+  /** kimi-k3 only: 'low' | 'high' | 'max' (default 'max'). */
+  reasoningEffort?: string;
+  /** kimi-k2.6 / kimi-k2.7-code: the `thinking` object. */
+  thinking?: Thinking;
+  promptCacheKey?: string;
+};
+
+/** Validate `thinking` per model. Returns the parsed value or an error envelope. */
+function validateThinking(model: string, raw: unknown): { value?: Thinking; error?: MoonshotResponseEnvelope } {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) return { error: invalidRequest("'thinking' must be an object") };
+  const o = raw as Record<string, unknown>;
+  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 as 'enabled' | 'disabled')) {
+      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 as 'enabled')) {
+      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: string | null | undefined;
+  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 as string | null;
+  }
+  return { value: { type: type as 'enabled' | 'disabled', ...(keep !== undefined ? { keep } : {}) } };
+}
+
+function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { error: MoonshotResponseEnvelope } {
+  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 as MoonshotMessageParam[];
+  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 as { tools?: unknown }).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 as { type?: string })?.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: number | undefined;
+  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: number | undefined;
+  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: string[] | undefined;
+  if (params.stop !== undefined && params.stop !== null) {
+    if (typeof params.stop === 'string') stop = [params.stop];
+    else if (Array.isArray(params.stop)) stop = params.stop as string[];
+    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: ToolChoice | undefined;
+  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 as ToolChoice;
+    } else if (typeof tcRaw === 'object') {
+      const name = (tcRaw as { function?: { name?: unknown } }).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: ResponseFormat = { kind: 'text' };
+  const rf = params.response_format as { type?: unknown; json_schema?: unknown } | undefined;
+  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 as { name?: unknown; schema?: unknown } | undefined;
+      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 as { function?: { name?: unknown } })?.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: string | undefined;
+  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 as ReasoningEffort)) {
+      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 as { include_usage?: unknown } | undefined;
+  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 as unknown[] } : {}),
+      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: ChatArgs, idx: number): { choice: MoonshotChoice; completionTokens: number } {
+  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 as unknown[];
+    const calls: MoonshotToolCall[] = [];
+    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: MoonshotChoice['finish_reason'] = '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: MoonshotAssistantMessage = { 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: ChatArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotChatCompletion | MoonshotResponseEnvelope {
+  const promptTokens = countPromptTokens(args.messages);
+  let scripted: ScriptedResult | null = 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 as MoonshotScenarioRespond;
+      // 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: MoonshotChoice[] = [];
+  let completionTokens = 0;
+  for (let i = 0; i < args.n; i++) {
+    if (scripted) {
+      const message: MoonshotAssistantMessage = 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: MoonshotUsage = 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: NonNullable<MoonshotScenarioRespond['error']>): MoonshotResponseEnvelope {
+  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: object): v is MoonshotResponseEnvelope =>
+  typeof (v as MoonshotResponseEnvelope).status === 'number' && 'body' in v;
+
+/** Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order. */
+function chunkText(text: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  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: ChatArgs, sink: SseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotChatCompletion | MoonshotResponseEnvelope {
+  const built = buildChatCompletion(args, occurredAt, decision);
+  if (isEnvelope(built)) return built;
+  const full = built;
+  const base = { id: full.id, object: 'chat.completion.chunk' as const, 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: Record<string, unknown>): MoonshotResponseEnvelope {
+  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 as MoonshotMessageParam[];
+  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: Record<string, unknown>, req: MoonshotRequest): MoonshotResponseEnvelope {
+  for (const field of ['nonce', 'timestamp', 'model', 'signature'] as const) {
+    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: string, timestamp: number, model: string): string {
+  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: unknown): MoonshotResponseEnvelope | null {
+  if (raw === undefined) return null;
+  if (typeof raw !== 'object' || raw === null) return invalidRequest("'time_window' must be an object");
+  const o = raw as { start?: unknown; end?: unknown };
+  for (const k of ['start', 'end'] as const) {
+    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: Record<string, unknown>, pro: boolean): MoonshotResponseEnvelope {
+  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: Record<string, unknown>): MoonshotResponseEnvelope {
+  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: Record<string, unknown>, req: MoonshotRequest): Promise<MoonshotResponseEnvelope> {
+  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: Record<string, unknown>): Record<string, unknown> {
+  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: string): number | null {
+  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: Record<string, unknown>, req: MoonshotRequest): Promise<MoonshotResponseEnvelope> {
+  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 as Record<string, unknown>);
+    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: Record<string, unknown>): Record<string, unknown> {
+  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?: string): MoonshotResponseEnvelope {
+  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 },
+  };
+}
+
+// ── Anthropic-compatible Messages (/anthropic/v1/messages) ──────────────────────────────
+type MessagesArgs = {
+  model: string;
+  messages: Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }>;
+  maxTokens: number;
+  system?: string;
+  stopSequences?: string[];
+  stream: boolean;
+  /** Anthropic's MessagesTool shape: { name, input_schema } (nested inside type:'custom'). */
+  tools?: Array<Record<string, unknown>>;
+  /** Anthropic's ToolChoice: type 'tool' names one tool (`name` REQUIRED, validated against
+   *  `tools` — the sibling pack's rule). */
+  toolChoice?: { type: 'auto' | 'any' | 'tool' | 'none'; name?: string };
+  outputEffort?: string;
+};
+
+/** Extract the tool name from an Anthropic Messages tool definition ({type:'custom', name, …}). */
+function messagesToolName(t: unknown): string {
+  const o = t as { name?: unknown } | undefined;
+  return typeof o?.name === 'string' ? o.name : '';
+}
+
+/** Validate the Anthropic-compatible request. kimi-k3 only; max_tokens REQUIRED. */
+function validateMessages(params: Record<string, unknown>): { args: MessagesArgs } | { error: MoonshotResponseEnvelope } {
+  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: Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }> = [];
+  for (const m of params.messages as Array<Record<string, unknown>>) {
+    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 as string | Array<Record<string, unknown>> });
+  }
+  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: string | undefined;
+  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 as { text?: unknown })?.text ?? '')).join('\n');
+    else return { error: messagesError(400, 'invalid_request_error', "'system' must be a string or an array of text blocks") }
+  }
+  let stopSequences: string[] | undefined;
+  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: Array<Record<string, unknown>> | undefined;
+  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 as { input_schema?: unknown }).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 as Array<Record<string, unknown>>;
+  }
+  // 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: MessagesArgs['toolChoice'] | undefined;
+  if (params.tool_choice !== undefined) {
+    const t = (params.tool_choice as { type?: unknown })?.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 as { name?: unknown }).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 as 'auto' | 'any' | 'none' };
+    }
+  }
+  let outputEffort: string | undefined;
+  const oc = params.output_config as { effort?: unknown } | undefined;
+  if (oc && typeof oc === 'object' && oc.effort !== undefined) {
+    if (typeof oc.effort !== 'string' || !REASONING_EFFORTS.includes(oc.effort as ReasoningEffort)) {
+      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: number, type: string, message: string): MoonshotResponseEnvelope {
+  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: number, moonshotBody: unknown): unknown {
+  const e = (moonshotBody as { error?: { message?: string; type?: string } })?.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: MessagesArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotMessagesResponse | MoonshotResponseEnvelope {
+  let scripted: ScriptedResult | null = 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 as MoonshotScenarioRespond;
+      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 as never })) as MoonshotMessageParam[]);
+  let content: MoonshotMessagesResponse['content'];
+  let stopReason: MoonshotMessagesResponse['stop_reason'];
+  let outputTokens: number;
+  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) as Record<string, unknown> });
+    }
+    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 as { type?: string })?.type === 'tool_result');
+    const forceTool = choice === 'any' || choice === 'tool';
+    const toolCalls = hasTools && !suppress && (forceTool || !toolResultTurn)
+      ? [stubToolCall(args.tools, 1, forcedName)].filter((tc): tc is MoonshotToolCall => 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 })) as MoonshotMessageParam[], 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) as Record<string, unknown> });
+      });
+    } else {
+      content.push({ type: 'text', text: stubAssistantText(args.messages.map((m) => ({ role: m.role, content: m.content })) as MoonshotMessageParam[], 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: MoonshotMessagesResponse['content'][number]): number =>
+    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: string | null = 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: NonNullable<MoonshotScenarioRespond['error']>): MoonshotResponseEnvelope {
+  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: MessagesArgs, sink: MessagesSseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotMessagesResponse | MoonshotResponseEnvelope {
+  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;
+}
+
+// ── Responses (/v1/responses) — kimi-k3 only ────────────────────────────────────────────
+type ResponsesArgs = {
+  model: string;
+  input: string | Array<Record<string, unknown>>;
+  instructions?: string;
+  maxOutputTokens?: number;
+  reasoningEffort?: string;
+  stream: boolean;
+};
+
+function validateResponses(params: Record<string, unknown>): { args: ResponsesArgs } | { error: MoonshotResponseEnvelope } {
+  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: string | undefined;
+  const r = params.reasoning as { effort?: unknown } | undefined;
+  if (r && typeof r === 'object' && r.effort !== undefined) {
+    if (typeof r.effort !== 'string' || !REASONING_EFFORTS.includes(r.effort as ReasoningEffort)) {
+      return { error: invalidRequest(`'reasoning.effort' must be one of ${REASONING_EFFORTS.map((t) => `'${t}'`).join(', ')}`) }
+    }
+    reasoningEffort = r.effort;
+  }
+  let maxOutputTokens: number | undefined;
+  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 as string | Array<Record<string, unknown>>,
+      ...(typeof params.instructions === 'string' ? { instructions: params.instructions } : {}),
+      ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+      ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+      stream: params.stream === true,
+    },
+  };
+}
+
+function responsesInputText(input: string | Array<Record<string, unknown>>): string {
+  if (typeof input === 'string') return input;
+  return input.map((item) => {
+    if ((item as { type?: string }).type === 'message' || (item as { type?: string }).type === undefined) {
+      const content = (item as { content?: unknown }).content;
+      return contentToText(content);
+    }
+    return JSON.stringify(item);
+  }).join('\n');
+}
+
+export function buildResponsesResponse(args: ResponsesArgs, occurredAt?: string, decision?: ScenarioDecision): MoonshotResponsesResponse | MoonshotResponseEnvelope {
+  let scripted: ScriptedResult | null = 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 as MoonshotScenarioRespond;
+      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: MoonshotMessageParam[] = [{ role: 'user', content: inputText }];
+  const inputTokens = countPromptTokens(asMessages);
+  const output: MoonshotResponsesOutputItem[] = [];
+  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: MoonshotResponsesResponse['status'] = 'completed';
+  let incompleteDetails: MoonshotResponsesResponse['incomplete_details'] = 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 as Array<{ text?: string }>).map((c) => c.text ?? '').join('')
+          : item.type === 'reasoning' ? (item.summary as Array<{ text?: string }>).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 as Array<{ text?: string }>).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: ResponsesArgs, sink: MessagesSseSink, occurredAt?: string, decision?: ScenarioDecision): MoonshotResponsesResponse | MoonshotResponseEnvelope {
+  const built = buildResponsesResponse(args, occurredAt, decision);
+  if (isEnvelope(built)) return built;
+  const full = built;
+  let seq = 0;
+  const emit = (type: string, data: Record<string, unknown>) => 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: MoonshotRequest): Promise<MoonshotResponseEnvelope> {
+  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 as { error: { message: string } }).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 as { error: { message: string } }).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 ?? '') as { model?: unknown }).model === 'string' ? (JSON.parse(req.body ?? '') as { model: string }).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: MoonshotRequest, method: string): Promise<MoonshotResponseEnvelope> {
+  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+  const params = parseJson(req.body);
+  const dec = (s: string) => 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: ScenarioDecision | undefined;
+    if (req.scenarioEngine) {
+      const served = await req.scenarioEngine.serve({ model: args.model, messages: args.messages.map((m) => ({ role: m.role, content: m.content })) as MoonshotMessageParam[], 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: ScenarioDecision | undefined;
+    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: ScenarioDecision | undefined;
+    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}.`);
+}
+
+// ── streaming sink types (exported for the server) ─────────────────────────────────────
+/** A sink the Messages/Responses streaming paths write events into. `event` is the SSE event
+ *  name (Anthropic/Responses grammar); `data` the JSON payload; `done: true` ends the stream. */
+export type MessagesSseSink = (event: MessagesSseEvent) => void;