@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-conformance.d.ts

@@ -0,0 +1,14 @@
+export type ConformanceViolation = {
+    check: string;
+    detail: string;
+};
+export type MoonshotConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    probes: number;
+    violations: ConformanceViolation[];
+};
+/** Run the offline conformance checks against a fresh temp root. */
+export declare function checkMoonshotConformance(opts?: {
+    root?: string;
+}): Promise<MoonshotConformanceReport>;

package/dist/src/moonshot-conformance.js

@@ -0,0 +1,405 @@
+// 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 } from "./moonshot-twin.js";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const CHAT = { model: 'kimi-k3', messages: [{ role: 'user', content: 'hi' }] };
+const PROBES = [
+    {
+        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[0]?.message?.role === 'assistant'
+            && typeof b.choices[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.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[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.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.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.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.length === 3
+            && typeof b.search_results[0]?.url === 'string' && typeof b.search_results[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.length === 5
+            && Array.isArray(b.search_results[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 = [
+    { 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 = 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 = [
+    { 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 = {}) {
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => 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, path, body) => 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?.error?.message ?? res.body?.error?.message ?? '');
+            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;
+            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) => {
+                const mb = b;
+                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 && isObj(mErr.body.error) && 'code' in mErr.body.error)
+                    fail('messages.error_envelope', 'Messages error envelope carries a `code` key its schema does not declare');
+            }
+            const cross = [
+                ['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.error.type !== wantType)
+                    fail('messages.error_envelope', `the ${what} cross-cutting failure answered error.type ${res.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 = [];
+            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?.[0]?.delta?.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;
+            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 = [];
+            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.done === false && e.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.choices?.[0];
+            if (choice?.finish_reason !== 'tool_calls')
+                fail('chat.tool_calls', 'finish_reason not tool_calls');
+            const calls = choice?.message?.tool_calls;
+            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.choices?.[0]?.message;
+            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.choices?.[0]?.message;
+            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 };
+}

package/dist/src/moonshot-connector.d.ts

@@ -0,0 +1,168 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { MoonshotBudget, type MoonshotBudgetOptions } from './moonshot-budget.js';
+/**
+ * The injected real-Moonshot boundary. `request` issues ONE Moonshot REST call:
+ *   method  — 'GET' | 'POST' | 'DELETE'
+ *   path    — e.g. '/v1/files' or '/v1/batches/batch_123/cancel'
+ *   body    — JSON body for POST (omitted otherwise)
+ * Returns the parsed JSON (an object, a `{ data }` list, or an `{ error }` envelope).
+ */
+export type MoonshotExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<{
+    data?: any;
+    error?: {
+        message?: string;
+        type?: string;
+    };
+    [k: string]: unknown;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveMoonshotOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: MoonshotBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: MoonshotBudgetOptions;
+};
+/**
+ * A live executor against the real Moonshot REST API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.moonshot.ai` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `MoonshotBudgetError` instead of returning
+ * when the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 / `x-ratelimit-remaining: 0` signal becomes a persisted cooldown that makes
+ * every later call fail fast WITHOUT touching Moonshot. There is deliberately no OPTION to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client.
+ * What that does NOT claim is immunity from a caller who WANTS one: a fresh `budgetOptions.path`
+ * per construction, or an injected clock, restores the allowance, because the same seam tests
+ * need cannot be denied to a determined caller in the same process. See `moonshot-budget.ts` and
+ * the kernel header for the limits of the guarantee.
+ */
+export declare function liveMoonshotExecute(apiKey: string, base?: string, opts?: LiveMoonshotOptions): MoonshotExecute;
+/** Map a real-Moonshot model object → a twin sync resource. */
+export declare function mapModel(m: Record<string, unknown>): SyncResource;
+/** Map a real-Moonshot File object → a twin sync resource. */
+export declare function mapFile(f: Record<string, unknown>): SyncResource;
+/** Map a real-Moonshot Batch object → a twin sync resource. */
+export declare function mapBatch(b: Record<string, unknown>): SyncResource;
+/** Map the real-Moonshot balance → the twin's 'balance' resource (id 'me'). */
+export declare function mapBalance(b: Record<string, unknown>): SyncResource;
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export declare function pullMoonshotState(execute: MoonshotExecute): Promise<SyncResource[]>;
+/**
+ * Pull from real Moonshot and fold into the twin (mirror seeding). Observation entries are
+ * content-addressed, so a re-pull of identical state appends nothing.
+ *
+ * `occurredAt` has NO pinned default on purpose: the kernel hashes an observed event over
+ * (occurredAt + post-state), so under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the fold reports a phantom delta while the
+ * projection keeps the stale value (ADDING_A_TWIN.md §6). Callers pass a moving timestamp.
+ */
+export declare function syncMoonshotFromReal(execute: MoonshotExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export declare function unpushableReason(op: string): string | null;
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * The kernel records the vendor's minted id at landing time (`vendorSubjectId` → the landed copy
+ * carries the vendor's id, `aliasOf` the local one), and `resolveSubjectId` answers it — so a
+ * later delete/cancel addresses the vendor by THAT. A locally-minted subject with no recorded
+ * alias is refused rather than guessed at — addressing the real account by the twin's own mint
+ * would DELETE or CANCEL a resource the vendor never had.
+ */
+export declare function externalIdFor(subjectType: string, subjectId: string, root?: string): string | null;
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Moonshot REST
+ * surface:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export declare function moonshotRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>, 
+/** The id the VENDOR knows this subject by. Required for anything but a create — see
+ *  `externalIdFor`; passing the twin's own mint would address a resource the vendor never had. */
+externalId?: string): {
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+};
+/**
+ * Push ONE pending action to REAL Moonshot via the injected executor. Returns the real external
+ * id (the object id from the response; for a create that's a freshly minted id, otherwise it
+ * echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export declare function pushMoonshotAction(execute: MoonshotExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, opts?: {
+    externalId?: string;
+}): Promise<{
+    externalId: string;
+}>;
+/** The pack's executor over the kernel's: the same Moonshot call, carried by the head. The
+ *  credential never enters this file — the kernel's executor applies it to the authorization
+ *  header before this sees the request. */
+export declare function moonshotExecuteOver(execute: RemoteExecute): MoonshotExecute;
+/** The refresh adapter: pull the account's models / files / batches / balance through the executor. */
+export declare function syncMoonshotFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<ReturnType<typeof syncMoonshotFromReal>>;
+/**
+ * The PERFORM adapter: one deployable entry crosses to Moonshot, or settles with the reason it
+ * never could. `file.create` is unpushable-BY-DESIGN (the real endpoint is multipart with the
+ * file body; this executor sends JSON) — it settles without crossing rather than throwing, so it
+ * cannot wedge every later batch action behind it. A locally-minted subject with no vendor alias
+ * THROWS (the head records the failure): addressing the real account by the twin's own mint would
+ * delete or cancel a resource the vendor never had.
+ */
+export declare function performMoonshotAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+/**
+ * Push the twin's PENDING local actions to real Moonshot and CONFIRM each. Idempotency: a
+ * confirmed action is no longer deployable, so a re-push enacts NOTHING.
+ *
+ * Every action this pack records is SINGLE-RESOURCE (one file, one batch), so confirming with
+ * `fields` alone is correct — see ADDING_A_TWIN.md §5 on compound actions, which this pack has
+ * none of. If a compound write is ever added here, it must ride its extra resources in
+ * `additionalObservations` or the push will silently delete them.
+ */
+export declare function pushPendingMoonshotActions(execute: MoonshotExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every deployable local entry to
+ * real Moonshot and confirm it, then (2) PULL all modeled collections back and fold them onto
+ * the root's log. Pushing first means the pull observes the twin's own writes as confirmed
+ * external state (no double-count). Re-running with nothing deployable and identical real state
+ * is a no-op.
+ */
+export declare function fullSyncMoonshot(execute: MoonshotExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    observed: number;
+    deltasAppended: number;
+    collections: number;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;