@volter/twin-moonshot 0.1.0

package/src/moonshot-conformance.ts

@@ -0,0 +1,416 @@
+// Moonshot twin conformance — an offline check with REAL TEETH: delete a handler branch and it
+// goes RED. Moonshot publishes its own OpenAPI document, so the claimed surface has a first-party
+// denominator; the harness still does not compare two constants (the false-green ADDING_A_TWIN.md
+// §6 documents). Instead it runs THREE passes:
+//
+//   1. PROBES — one real request per CLAIMED endpoint, graded on the OUTCOME a live handler
+//      produces: an expected status set PLUS a predicate over the body. A handler that returned
+//      `{}`, or whose branch was deleted (so the router falls through to its not-found), fails.
+//   2. BIJECTION — the probe table and the claimed-endpoint snapshot must match two ways, so a
+//      claim with no probe and a probe with no claim are both RED.
+//   3. ROUTER_SURFACE — a HAND-AUTHORED census of every method/path pair `routeMoonshot` branches
+//      on, each carrying a live request that must actually REACH that branch (not fall through to
+//      the router's not-found). Plus MUST_NOT_SERVE: paths the vendor does not serve, which must
+//      answer the vendor-shaped not-found envelope.
+//
+// Fully offline + deterministic (drives the local handler against a temp root) so it runs without
+// an API key. Honest scope: it checks the protocol envelope, NOT model output (a deterministic
+// labeled stub by design).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleMoonshotTwinRequest, MESSAGES_PREFIX, MOONSHOT_API_PREFIX, type MoonshotResponseEnvelope } from './moonshot-twin.ts';
+import type { MessagesSseEvent, SseEvent } from './moonshot-types.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type MoonshotConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  probes: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, any>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * THE CLAIMED SURFACE. Every entry is a real request plus the OUTCOME a live handler produces.
+ * The expected values are LITERALS here, never imported from the handler — an assertion against
+ * the module's own constant is a tautology that cannot catch the value drifting.
+ */
+type Probe = {
+  /** `"<METHOD> <path>"` — the claim key, and the bijection key. */
+  key: string;
+  method: string;
+  path: string;
+  body?: unknown;
+  /** Which statuses a live handler may answer with. */
+  statuses: number[];
+  /** What a live handler's body must look like. */
+  ok: (body: unknown, status: number) => boolean;
+  /** Seed the root before probing (returns nothing; failures surface as probe failures). */
+  seed?: (h: (m: string, p: string, b?: unknown) => Promise<MoonshotResponseEnvelope>) => Promise<void>;
+};
+
+const CHAT = { model: 'kimi-k3', messages: [{ role: 'user', content: 'hi' }] };
+
+const PROBES: Probe[] = [
+  {
+    key: 'POST /v1/chat/completions',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: CHAT, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'chat.completion' && Array.isArray(b.choices)
+      && (b.choices as Body[])[0]?.message?.role === 'assistant'
+      && typeof (b.choices as Body[])[0]?.message?.content === 'string'
+      && isObj(b.usage) && typeof b.usage.total_tokens === 'number' && typeof b.usage.cached_tokens === 'number',
+  },
+  {
+    key: 'POST /v1/responses',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/responses`, body: { model: 'kimi-k3', input: 'hi' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'response' && b.status === 'completed' && Array.isArray(b.output)
+      && (b.output as Body[]).some((o) => o.type === 'message')
+      && isObj(b.usage) && typeof b.usage.total_tokens === 'number',
+  },
+  {
+    key: 'POST /anthropic/v1/messages',
+    method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: { model: 'kimi-k3', messages: [{ role: 'user', content: 'hi' }], max_tokens: 100 }, statuses: [200],
+    ok: (b) => isObj(b) && b.type === 'message' && b.role === 'assistant' && Array.isArray(b.content)
+      && (b.content as Body[])[0]?.type === 'thinking'
+      && typeof b.stop_reason === 'string' && isObj(b.usage) && typeof b.usage.input_tokens === 'number',
+  },
+  {
+    key: 'GET /v1/models',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/models`, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data) && (b.data as Body[]).some((m) => m.id === 'kimi-k3' && m.object === 'model' && m.owned_by === 'moonshot'),
+  },
+  {
+    key: 'POST /v1/files',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/files`, body: { purpose: 'batch', filename: 'in.jsonl', content: '{}' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'file' && b.purpose === 'batch' && b.status === 'ready' && String(b.id).startsWith('file_twin_'),
+  },
+  {
+    key: 'GET /v1/files',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/files`, statuses: [200],
+    seed: async (h) => { await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'seed.jsonl', content: '{}' }); },
+    ok: (b) => isObj(b) && b.object === 'list' && (b.data as Body[]).some((f) => f.filename === 'seed.jsonl'),
+  },
+  {
+    key: 'GET /v1/files/{file_id}',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1`, statuses: [200],
+    seed: async (h) => { await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'one.jsonl', content: 'x' }); },
+    ok: (b) => isObj(b) && b.id === 'file_twin_1' && b.filename === 'one.jsonl',
+  },
+  {
+    key: 'GET /v1/files/{file_id}/content',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1/content`, statuses: [200],
+    seed: async (h) => { await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'one.jsonl', content: '{"custom_id":"a"}' }); },
+    ok: (b) => b === '{"custom_id":"a"}',
+  },
+  {
+    key: 'DELETE /v1/files/{file_id}',
+    method: 'DELETE', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1`, statuses: [200],
+    seed: async (h) => { await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'one.jsonl', content: 'x' }); },
+    ok: (b) => isObj(b) && b.deleted === true && b.id === 'file_twin_1' && b.object === 'file',
+  },
+  {
+    key: 'POST /v1/batches',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/batches`, body: { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions', completion_window: '24h' }, statuses: [200],
+    seed: async (h) => { await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'in.jsonl', content: 'x' }); },
+    ok: (b) => isObj(b) && b.object === 'batch' && b.status === 'validating' && b.endpoint === '/v1/chat/completions' && typeof b.expires_at === 'number',
+  },
+  {
+    key: 'GET /v1/batches',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/batches`, statuses: [200],
+    seed: async (h) => {
+      await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'in.jsonl', content: 'x' });
+      await h('POST', `${MOONSHOT_API_PREFIX}/batches`, { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions', completion_window: '24h' });
+    },
+    ok: (b) => isObj(b) && b.object === 'list' && (b.data as Body[]).some((x) => x.id === 'batch_twin_1'),
+  },
+  {
+    key: 'GET /v1/batches/{batch_id}',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/batches/batch_twin_1`, statuses: [200],
+    seed: async (h) => {
+      await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'in.jsonl', content: 'x' });
+      await h('POST', `${MOONSHOT_API_PREFIX}/batches`, { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions', completion_window: '24h' });
+    },
+    ok: (b) => isObj(b) && b.id === 'batch_twin_1' && b.input_file_id === 'file_twin_1',
+  },
+  {
+    key: 'POST /v1/batches/{batch_id}/cancel',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/batches/batch_twin_1/cancel`, statuses: [200],
+    seed: async (h) => {
+      await h('POST', `${MOONSHOT_API_PREFIX}/files`, { purpose: 'batch', filename: 'in.jsonl', content: 'x' });
+      await h('POST', `${MOONSHOT_API_PREFIX}/batches`, { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions', completion_window: '24h' });
+    },
+    ok: (b) => isObj(b) && b.status === 'cancelling' && typeof b.cancelling_at === 'number',
+  },
+  {
+    key: 'GET /v1/users/me/balance',
+    method: 'GET', path: `${MOONSHOT_API_PREFIX}/users/me/balance`, statuses: [200],
+    ok: (b) => isObj(b) && b.code === 0 && b.scode === '0x0' && b.status === true
+      && isObj(b.data) && typeof b.data.available_balance === 'number' && typeof b.data.voucher_balance === 'number' && typeof b.data.cash_balance === 'number',
+  },
+  {
+    key: 'POST /v1/tokenizers/estimate-token-count',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/tokenizers/estimate-token-count`, body: { model: 'kimi-k3', messages: [{ role: 'user', content: 'hello world, estimate me' }] }, statuses: [200],
+    ok: (b) => isObj(b) && isObj(b.data) && typeof b.data.total_tokens === 'number' && b.data.total_tokens > 0,
+  },
+  {
+    key: 'POST /v1/signatures/verify',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/signatures/verify`, body: { nonce: 'n-1', timestamp: 1786338000123, model: 'kimi-k2.7-code', signature: 'reqsigv1_not-a-real-token' }, statuses: [200],
+    ok: (b) => isObj(b) && b.valid === false,
+  },
+  {
+    key: 'POST /v1/tools/search',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/search`, body: { text_query: 'kimi api limits', limit: 3 }, statuses: [200],
+    ok: (b) => isObj(b) && Array.isArray(b.search_results) && (b.search_results as Body[]).length === 3
+      && typeof (b.search_results as Body[])[0]?.url === 'string' && typeof (b.search_results as Body[])[0]?.snippet === 'string',
+  },
+  {
+    key: 'POST /v1/tools/search_pro',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/search_pro`, body: { text_query: 'kimi api limits', sites: ['platform.kimi.ai'] }, statuses: [200],
+    ok: (b) => isObj(b) && Array.isArray(b.search_results) && (b.search_results as Body[]).length === 5
+      && Array.isArray((b.search_results as Body[])[0]?.chunks),
+  },
+  {
+    key: 'POST /v1/tools/fetch',
+    method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/fetch`, body: { url: 'https://platform.kimi.ai/docs' }, statuses: [200],
+    ok: (b) => isObj(b) && b.url === 'https://platform.kimi.ai/docs' && typeof b.markdown === 'string' && b.markdown.includes('[twin-stub]'),
+  },
+];
+
+/**
+ * THE ROUTER CENSUS — hand-authored from `routeMoonshot`'s dispatch branches, paired with a
+ * request that REACHES that branch. Each entry is checked live: the router must BRANCH on it
+ * (i.e. not fall through to its own `Unknown request URL` not-found) — so deleting a handler
+ * branch reddens the census by name, independently of that endpoint's own probe.
+ */
+const ROUTER_SURFACE: Array<{ key: string; method: string; path: string; body?: unknown }> = [
+  { key: 'GET /v1/models', method: 'GET', path: `${MOONSHOT_API_PREFIX}/models` },
+  { key: 'POST /v1/chat/completions', method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: CHAT },
+  { key: 'POST /v1/responses', method: 'POST', path: `${MOONSHOT_API_PREFIX}/responses`, body: { model: 'kimi-k3', input: 'x' } },
+  { key: 'POST /v1/tokenizers/estimate-token-count', method: 'POST', path: `${MOONSHOT_API_PREFIX}/tokenizers/estimate-token-count`, body: { model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }] } },
+  { key: 'POST /v1/signatures/verify', method: 'POST', path: `${MOONSHOT_API_PREFIX}/signatures/verify`, body: { nonce: 'n', timestamp: 1, model: 'kimi-k3', signature: 's' } },
+  { key: 'POST /v1/tools/search', method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/search`, body: { text_query: 'x' } },
+  { key: 'POST /v1/tools/search_pro', method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/search_pro`, body: { text_query: 'x' } },
+  { key: 'POST /v1/tools/fetch', method: 'POST', path: `${MOONSHOT_API_PREFIX}/tools/fetch`, body: { url: 'https://x.example' } },
+  { key: 'GET /v1/users/me/balance', method: 'GET', path: `${MOONSHOT_API_PREFIX}/users/me/balance` },
+  { key: 'POST /v1/files', method: 'POST', path: `${MOONSHOT_API_PREFIX}/files`, body: { purpose: 'batch', filename: 'a.jsonl', content: 'x' } },
+  { key: 'GET /v1/files', method: 'GET', path: `${MOONSHOT_API_PREFIX}/files` },
+  { key: 'GET /v1/files/{file_id}', method: 'GET', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1` },
+  { key: 'GET /v1/files/{file_id}/content', method: 'GET', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1/content` },
+  { key: 'DELETE /v1/files/{file_id}', method: 'DELETE', path: `${MOONSHOT_API_PREFIX}/files/file_twin_1` },
+  { key: 'POST /v1/batches', method: 'POST', path: `${MOONSHOT_API_PREFIX}/batches`, body: { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions', completion_window: '24h' } },
+  { key: 'GET /v1/batches', method: 'GET', path: `${MOONSHOT_API_PREFIX}/batches` },
+  { key: 'GET /v1/batches/{batch_id}', method: 'GET', path: `${MOONSHOT_API_PREFIX}/batches/batch_twin_1` },
+  { key: 'POST /v1/batches/{batch_id}/cancel', method: 'POST', path: `${MOONSHOT_API_PREFIX}/batches/batch_twin_1/cancel` },
+  { key: 'POST /anthropic/v1/messages', method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: { model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 } },
+];
+
+/** The literal the router falls through to when NO branch matched. A census entry answering this
+ *  means its branch is gone. Kept as a LITERAL — importing the handler's string would be a
+ *  tautology that could not catch the message drifting. */
+const ROUTER_MISS = 'Unknown request URL';
+
+const ROUTER_SURFACE_KEYS: string[] = ROUTER_SURFACE.map((e) => e.key);
+
+/**
+ * Surface the twin must NOT serve: the bare `/openai/v1` prefix (that is GROQ's shape, not
+ * Moonshot's), paths outside both prefixes, and the kimi-k2.x models on the kimi-k3-only
+ * endpoints (the OpenAPI's per-request model enums are the closed sets). Each must answer the
+ * vendor-shaped not-found/error envelope.
+ */
+const MUST_NOT_SERVE: Array<{ method: string; path: string; body?: unknown; why: string }> = [
+  { method: 'POST', path: '/openai/v1/chat/completions', body: CHAT, why: 'the /openai/v1 prefix is GroqCloud\'s shape; Moonshot serves /v1' },
+  { method: 'GET', path: '/v1/fine_tuning/jobs', why: 'OpenAI has this endpoint; Moonshot\'s OpenAPI does not' },
+  { method: 'GET', path: '/v1/embeddings', why: 'Moonshot publishes no embeddings endpoint' },
+  { method: 'GET', path: `${MOONSHOT_API_PREFIX}/models/kimi-k3`, why: 'Moonshot\'s OpenAPI declares NO /v1/models/{model} retrieve operation — serving a 200 here was a 200 for an unmodeled route' },
+  { method: 'POST', path: `${MOONSHOT_API_PREFIX}/responses`, body: { model: 'kimi-k2.6', input: 'x' }, why: 'the Responses API is kimi-k3 only' },
+  { method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: { model: 'kimi-k2.7-code', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 }, why: 'the Messages API is kimi-k3 only' },
+];
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkMoonshotConformance(opts: { root?: string } = {}): Promise<MoonshotConformanceReport> {
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+
+  // ── 1. PROBES: each in its OWN throwaway root, so a probe's seed can't leak into another. ──
+  for (const probe of PROBES) {
+    checksRun++;
+    // A FRESH root per probe, always. `opts.root` is the PARENT directory, never a shared root:
+    // sharing it let `nextId` ratchet across probes, so the `files/file_twin_1` probe read the id
+    // an earlier probe had minted and `world-moonshot conformance --root DIR` reported false
+    // violations (the groq pack's §9 round-two finding, back-applied here from the start).
+    const root = mkdtempSync(join(opts.root ?? tmpdir(), 'moonshot-conf-'));
+    const h = (method: string, path: string, body?: unknown) =>
+      handleMoonshotTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root });
+    try {
+      if (probe.seed) await probe.seed(h);
+      const res = await h(probe.method, probe.path, probe.body);
+      if (!probe.statuses.includes(res.status)) {
+        fail(`probe:${probe.key}`, `status ${res.status} (expected one of ${probe.statuses.join('/')}) body=${JSON.stringify(res.body).slice(0, 200)}`);
+      } else if (!probe.ok(res.body, res.status)) {
+        fail(`probe:${probe.key}`, `body did not satisfy the live-handler predicate: ${JSON.stringify(res.body).slice(0, 300)}`);
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 2. BIJECTION: probe table ⇄ router census, both directions. ──
+  checksRun++;
+  const probeKeys = new Set(PROBES.map((p) => p.key));
+  for (const key of ROUTER_SURFACE_KEYS) if (!probeKeys.has(key)) fail('bijection', `router branch "${key}" has no probe`);
+  for (const key of probeKeys) if (!ROUTER_SURFACE_KEYS.includes(key)) fail('bijection', `probe "${key}" is not in the hand-authored router census`);
+  if (PROBES.length !== new Set(PROBES.map((p) => p.key)).size) fail('bijection', 'duplicate probe key');
+  if (ROUTER_SURFACE.length !== ROUTER_SURFACE_KEYS.length) fail('bijection', 'the router census and its key list disagree');
+
+  // ── 2b. THE CENSUS HAS TEETH: every declared branch must actually be REACHED. A branch whose
+  //       handler was deleted falls through to the router's own not-found, which is what this
+  //       catches — independently of that endpoint's own probe.
+  for (const entry of ROUTER_SURFACE) {
+    checksRun++;
+    const root = mkdtempSync(join(opts.root ?? tmpdir(), 'moonshot-conf-'));
+    try {
+      const res = await handleMoonshotTwinRequest({ method: entry.method, path: entry.path, ...(entry.body === undefined ? {} : { body: JSON.stringify(entry.body) }), root });
+      const message = String(((res.body as Body)?.error as Body)?.message ?? ((res.body as Body)?.error?.message as string) ?? '');
+      if (message.includes(ROUTER_MISS)) {
+        fail('router_surface', `${entry.key} fell through to the router's not-found — the branch is gone (answered ${res.status}: ${message})`);
+      }
+      if (!ROUTER_SURFACE_KEYS.includes(entry.key)) fail('router_surface', `${entry.key} is exercised but not declared`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 3. The twin must not serve surface it does not model (or the vendor does not have). ──
+  {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'moonshot-conf-'));
+    try {
+      for (const entry of MUST_NOT_SERVE) {
+        checksRun++;
+        const res = await handleMoonshotTwinRequest({ method: entry.method, path: entry.path, ...(entry.body === undefined ? {} : { body: JSON.stringify(entry.body) }), root });
+        if (res.status < 400) fail('must_not_serve', `${entry.method} ${entry.path} answered ${res.status} — ${entry.why}`);
+      }
+
+      // ── 4. The error envelope on /v1 carries `error.message` (REQUIRED) plus only keys
+      //      Moonshot's ErrorResponse schema declares: message, type, code. The key list is a
+      //      LITERAL here — asserting against the handler's own constant would be a tautology.
+      checksRun++;
+      const ERROR_OBJECT_KEYS = new Set(['message', 'type', 'code']);
+      const bad = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ messages: [] }), root });
+      const eb = bad.body as Body;
+      if (bad.status !== 400 || !isObj(eb?.error)) {
+        fail('error.envelope', `missing model did not yield a 400 with an error envelope (status ${bad.status})`);
+      } else {
+        const undeclared = Object.keys(eb.error).filter((k) => !ERROR_OBJECT_KEYS.has(k));
+        if (undeclared.length) fail('error.envelope', `error object carries key(s) Moonshot's ErrorResponse schema does not declare: ${undeclared.join(', ')}`);
+        if (typeof eb.error.message !== 'string' || !eb.error.message) fail('error.envelope', 'error.message is not a non-empty string');
+        if (eb.error.type !== 'invalid_request_error') fail('error.envelope', `error.type is ${String(eb.error.type)}`);
+      }
+
+      // ── 4b. The Messages surface answers its OWN envelope ({type:'error',error:{type,message}})
+      //      on EVERY failure — the validation 400 AND the cross-cutting 401/429/503/405 that
+      //      fire before routing (each of which used to leak the /v1 envelope regardless of
+      //      prefix, the round-two finding). Anthropic's own error types apply here.
+      checksRun++;
+      const anthropicShape = (b: unknown): boolean => {
+        const mb = b as Body;
+        return mb?.type === 'error' && isObj(mb.error) && typeof mb.error.type === 'string' && typeof mb.error.message === 'string' && !('code' in mb.error);
+      };
+      const mErr = await handleMoonshotTwinRequest({ method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }] }), root });
+      if (mErr.status !== 400) fail('messages.error_envelope', `missing max_tokens answered ${mErr.status}, not 400`);
+      else {
+        if (!anthropicShape(mErr.body)) fail('messages.error_envelope', 'Messages error body is not the MessagesErrorResponse shape { type, error:{type,message} }');
+        if ('error' in (mErr.body as Body) && isObj((mErr.body as Body).error) && 'code' in (mErr.body as Body).error) fail('messages.error_envelope', 'Messages error envelope carries a `code` key its schema does not declare');
+      }
+      const cross: Array<[string, MoonshotResponseEnvelope, string]> = [
+        ['401', await handleMoonshotTwinRequest({ method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 }), root, headers: { 'x-api-key': '' } }), 'authentication_error'],
+        ['429', await handleMoonshotTwinRequest({ method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 }), root, headers: { authorization: 'Bearer sk-twin', 'x-twin-force-rate-limit': '1' } }), 'rate_limit_error'],
+        ['503', await handleMoonshotTwinRequest({ method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 }), root, headers: { authorization: 'Bearer sk-twin', 'x-twin-force-server-unavailable': '1' } }), 'overloaded_error'],
+        ['405', await handleMoonshotTwinRequest({ method: 'POST', path: `${MESSAGES_PREFIX}/messages`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 10 }), root, readOnly: true }), 'invalid_request_error'],
+      ];
+      for (const [what, res, wantType] of cross) {
+        if (res.status !== Number(what)) fail('messages.error_envelope', `the ${what} cross-cutting failure answered ${res.status}`);
+        else if (!anthropicShape(res.body)) fail('messages.error_envelope', `the ${what} cross-cutting failure leaked a non-Anthropic envelope: ${JSON.stringify(res.body).slice(0, 120)}`);
+        else if ((res.body as Body).error.type !== wantType) fail('messages.error_envelope', `the ${what} cross-cutting failure answered error.type ${(res.body as Body).error.type}, not ${wantType}`);
+      }
+
+      // ── 5. Per-model parameter gating, straight from the OpenAPI's per-request schemas: ──
+      //      kimi-k2.7-code REJECTS thinking.type 'disabled'; kimi-k2.6 accepts it; kimi-k3 has
+      //      no thinking parameter at all; reasoning_effort is kimi-k3-only.
+      checksRun++;
+      const k27Disabled = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k2.7-code', messages: [{ role: 'user', content: 'x' }], thinking: { type: 'disabled' } }), root });
+      const k26Disabled = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k2.6', messages: [{ role: 'user', content: 'x' }], thinking: { type: 'disabled' } }), root });
+      const k3Thinking = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], thinking: { type: 'enabled' } }), root });
+      const k3Effort = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], reasoning_effort: 'low' }), root });
+      const k26Effort = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k2.6', messages: [{ role: 'user', content: 'x' }], reasoning_effort: 'low' }), root });
+      if (k27Disabled.status !== 400) fail('chat.per_model_gating', `kimi-k2.7-code thinking.type 'disabled' answered ${k27Disabled.status}, not 400`);
+      if (k26Disabled.status !== 200) fail('chat.per_model_gating', `kimi-k2.6 thinking.type 'disabled' answered ${k26Disabled.status}, not 200`);
+      if (k3Thinking.status !== 400) fail('chat.per_model_gating', `kimi-k3 'thinking' answered ${k3Thinking.status}, not 400 (kimi-k3 uses reasoning_effort)`);
+      if (k3Effort.status !== 200) fail('chat.per_model_gating', `kimi-k3 reasoning_effort answered ${k3Effort.status}, not 200`);
+      if (k26Effort.status !== 400) fail('chat.per_model_gating', `kimi-k2.6 reasoning_effort answered ${k26Effort.status}, not 400`);
+
+      // ── 6. The streaming chunk sequence, including Moonshot's usage-bearing tail chunk. ──
+      checksRun++;
+      const events: SseEvent[] = [];
+      await handleMoonshotTwinRequest({
+        method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, root,
+        body: JSON.stringify({ ...CHAT, stream: true }),
+        sseSink: (e) => events.push(e),
+      });
+      const hasRole = events.some((e) => !e.done && ((e.data!.choices as Body[])?.[0]?.delta as Body)?.role === 'assistant');
+      const done = events.length > 0 && events[events.length - 1]!.done === true;
+      const firstObj = events[0]?.data?.object;
+      const tail = events[events.length - 2]?.data as Body | undefined;
+      if (!hasRole) fail('chat.stream', 'no role delta chunk');
+      if (!done) fail('chat.stream', 'stream did not end with [DONE]');
+      if (firstObj !== 'chat.completion.chunk') fail('chat.stream', `first chunk object is ${String(firstObj)}`);
+      if (!tail || !Array.isArray(tail.choices) || tail.choices.length !== 0 || !isObj(tail.usage)) {
+        fail('chat.stream', 'final chunk is not Moonshot\'s empty-choices usage tail');
+      }
+
+      // ── 7. The Anthropic-compatible streaming grammar: named events, message_start →
+      //       thinking/text deltas → message_delta → message_stop, NO [DONE] sentinel. ──
+      checksRun++;
+      const mEvents: MessagesSseEvent[] = [];
+      await handleMoonshotTwinRequest({
+        method: 'POST', path: `${MESSAGES_PREFIX}/messages`, root,
+        body: JSON.stringify({ model: 'kimi-k3', messages: [{ role: 'user', content: 'x' }], max_tokens: 200, stream: true }),
+        messagesSseSink: (e) => mEvents.push(e),
+      });
+      const names = mEvents.filter((e) => !e.done).map((e) => e.event ?? '');
+      if (names[0] !== 'message_start') fail('messages.stream', `first event is ${String(names[0])}, not message_start`);
+      if (!names.includes('content_block_delta') || !names.includes('content_block_stop')) fail('messages.stream', 'no content_block deltas');
+      if (names[names.length - 1] !== 'message_stop') fail('messages.stream', `last event is ${String(names[names.length - 1])}, not message_stop`);
+      if (mEvents.some((e) => (e as SseEvent).done === false && (e as SseEvent).data === undefined && e.event === undefined)) fail('messages.stream', 'unnamed event in the Anthropic grammar');
+
+      // ── 8. tool_calls envelope when tools are provided. ──
+      checksRun++;
+      const tool = await handleMoonshotTwinRequest({
+        method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, root,
+        body: JSON.stringify({ ...CHAT, tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }] }),
+      });
+      const choice = ((tool.body as Body).choices as Body[])?.[0];
+      if (choice?.finish_reason !== 'tool_calls') fail('chat.tool_calls', 'finish_reason not tool_calls');
+      const calls = choice?.message?.tool_calls as Body[];
+      if (!Array.isArray(calls) || calls[0]?.type !== 'function' || calls[0]?.function?.name !== 'get_weather') fail('chat.tool_calls', 'no get_weather function tool_call');
+
+      // ── 9. Thinking mode surfaces reasoning_content; disabled k2.6 does not. ──
+      checksRun++;
+      const k3 = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify(CHAT), root });
+      const k3Msg = ((k3.body as Body).choices as Body[])?.[0]?.message as Body;
+      if (typeof k3Msg?.reasoning_content !== 'string' || !k3Msg.reasoning_content.includes('[twin-stub:kimi-k3]')) {
+        fail('chat.reasoning_content', 'kimi-k3 (always thinking) did not surface reasoning_content');
+      }
+      const k26off = await handleMoonshotTwinRequest({ method: 'POST', path: `${MOONSHOT_API_PREFIX}/chat/completions`, body: JSON.stringify({ model: 'kimi-k2.6', messages: [{ role: 'user', content: 'x' }], thinking: { type: 'disabled' } }), root });
+      const k26Msg = ((k26off.body as Body).choices as Body[])?.[0]?.message as Body;
+      if ('reasoning_content' in (k26Msg ?? {})) fail('chat.reasoning_content', "kimi-k2.6 with thinking.type 'disabled' surfaced reasoning_content");
+    } finally {
+      if (opts.root === undefined) rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  return { ok: violations.length === 0, checksRun, probes: PROBES.length, violations };
+}