@volter/twin-moonshot 0.1.0

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

@@ -0,0 +1,251 @@
+/** A chat message param as the caller sends it (Message schema). Content is a string OR a
+ *  content-part array (text / image_url / video_url — Moonshot's multimodal form). */
+export type MoonshotMessageParam = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | Array<Record<string, unknown>> | null;
+    name?: string;
+    /** Partial Mode: set `partial: true` on the last ASSISTANT message to continue it. */
+    partial?: boolean;
+    tool_calls?: MoonshotToolCall[];
+    tool_call_id?: string;
+    /** kimi-k3's dynamic tool loading message: role 'system' with `tools` and NO content. */
+    tools?: unknown[];
+};
+/** A function tool_call (faithful shape). */
+export type MoonshotToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/** The chat `usage` object: token counts plus Moonshot's automatic context-cache split. */
+export type MoonshotUsage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    /** Tokens served from the automatic context cache (>256 prompt tokens to hit). */
+    cached_tokens?: number;
+};
+/** The assistant message Moonshot returns. `reasoning_content` is present when thinking mode
+ *  is enabled (kimi-k3 always; kimi-k2.6/k2.7-code when `thinking.type` is 'enabled'). */
+export type MoonshotAssistantMessage = {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: MoonshotToolCall[];
+    reasoning_content?: string | null;
+};
+export type MoonshotChoice = {
+    index: number;
+    message: MoonshotAssistantMessage;
+    logprobs?: unknown;
+    finish_reason: 'stop' | 'length' | 'tool_calls';
+};
+/** The unary chat.completion response envelope (faithful shape). */
+export type MoonshotChatCompletion = {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: MoonshotChoice[];
+    usage: MoonshotUsage;
+};
+/** A streaming chat chunk (ChatCompletionChunk schema). */
+export type MoonshotChatChunk = {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string;
+            reasoning_content?: string;
+            tool_calls?: Array<{
+                index?: number;
+                id?: string;
+                type?: 'function';
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason: 'stop' | 'length' | 'tool_calls' | null;
+        usage: MoonshotUsage | null;
+    }>;
+    /** The FINAL chunk carries the whole usage object (stream_options.include_usage / Moonshot's
+     *  documented final-chunk usage); ordinary chunks carry null. */
+    usage?: MoonshotUsage | null;
+};
+/** The served model object (OpenAI-shaped; Moonshot's /v1/models rows). */
+export type MoonshotModelObject = {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+};
+/** File purposes — a CLOSED documented set (FileObject schema). */
+export declare const FILE_PURPOSES: readonly ["file-extract", "image", "video", "batch"];
+export type MoonshotFilePurpose = (typeof FILE_PURPOSES)[number];
+export type MoonshotFile = {
+    id: string;
+    object: 'file';
+    bytes: number;
+    created_at: number;
+    filename: string;
+    purpose: MoonshotFilePurpose;
+    status: string;
+    status_details?: string;
+};
+export type MoonshotBatchCounts = {
+    completed: number;
+    failed: number;
+    total: number;
+};
+export type MoonshotBatch = {
+    id: string;
+    object: 'batch';
+    endpoint: string;
+    input_file_id: string;
+    completion_window: string;
+    status: 'validating' | 'failed' | 'in_progress' | 'finalizing' | 'completed' | 'expired' | 'cancelling' | 'cancelled';
+    output_file_id: string | null;
+    error_file_id: string | null;
+    created_at: number;
+    in_progress_at: number | null;
+    expires_at: number | null;
+    finalizing_at: number | null;
+    completed_at: number | null;
+    failed_at: number | null;
+    cancelling_at: number | null;
+    cancelled_at: number | null;
+    request_counts: MoonshotBatchCounts;
+    metadata: Record<string, string> | null;
+};
+/**
+ * Moonshot's OpenAI-surface error envelope (ErrorResponse schema): `error.message` REQUIRED,
+ * `type` and `code` optional. The `type` values are Moonshot's documented error-code page
+ * (platform.kimi.ai/docs/api/errors, read 2026-09-16) — see moonshot-twin.ts for the mapping.
+ */
+export type MoonshotError = {
+    error: {
+        message: string;
+        type?: string;
+        code?: string;
+    };
+};
+/** A Messages content block the RESPONSE emits, ordered thinking → text → tool_use. */
+export type MoonshotMessagesBlock = {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+export type MoonshotMessagesResponse = {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    model: string;
+    content: MoonshotMessagesBlock[];
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'refusal' | null;
+    stop_sequence: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    };
+};
+/** A Messages SSE event. `data` is the JSON payload; there is no [DONE] sentinel — the stream
+ *  ends after `message_stop` (Anthropic's grammar, which this surface follows). */
+export type MessagesSseEvent = {
+    event?: string;
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** An output item, ordered web_search_call → reasoning → message → tool calls. */
+export type MoonshotResponsesOutputItem = {
+    type: 'reasoning';
+    id: string;
+    summary: Array<{
+        type: 'summary_text';
+        text: string;
+    }>;
+    status?: 'completed';
+} | {
+    type: 'message';
+    id: string;
+    role: 'assistant';
+    status: 'completed';
+    content: Array<{
+        type: 'output_text';
+        text: string;
+        annotations: unknown[];
+    }>;
+} | {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+    status?: 'completed';
+} | {
+    type: 'custom_tool_call';
+    id: string;
+    call_id: string;
+    name: string;
+    input: string;
+} | {
+    type: 'web_search_call';
+    id: string;
+    status: 'completed';
+};
+export type MoonshotResponsesUsage = {
+    input_tokens: number;
+    input_tokens_details?: {
+        cached_tokens: number;
+        cache_write_tokens: number;
+    };
+    output_tokens: number;
+    output_tokens_details?: {
+        reasoning_tokens: number;
+    };
+    total_tokens: number;
+};
+export type MoonshotResponsesResponse = {
+    id: string;
+    object: 'response';
+    created_at: number;
+    completed_at: number | null;
+    status: 'in_progress' | 'completed' | 'incomplete' | 'failed';
+    model: string;
+    output: MoonshotResponsesOutputItem[];
+    usage: MoonshotResponsesUsage | null;
+    incomplete_details: {
+        reason: 'max_output_tokens' | 'content_filter';
+    } | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    store: false;
+};
+/** A single Server-Sent Event the OpenAI-compatible streaming paths emit. `data` is the JSON
+ *  payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/dist/src/moonshot-types.js

@@ -0,0 +1,19 @@
+// Shared wire-shape types for the Moonshot (Kimi) API surface, transcribed from Moonshot's own
+// OpenAPI 3.1.0 document (https://platform.kimi.ai/docs/openapi.json, read 2026-09-16) — the
+// first-party artifact, not an SDK's internal types (no official Moonshot SDK exists; clients
+// are the standard `openai` / `anthropic` SDKs pointed at Moonshot's base URLs, so THIS document
+// is the only generated contract).
+//
+// MOONSHOT IS NOT OPENAI, and the differences below are load-bearing:
+//   • THREE inference protocols share one host: OpenAI-compatible `/v1/chat/completions` +
+//     `/v1/responses`, and an Anthropic-compatible `/anthropic/v1/messages` whose envelope,
+//     content blocks and SSE event grammar are Anthropic's, not OpenAI's;
+//   • chat responses carry `reasoning_content` (thinking mode) — not Groq's `reasoning`, not
+//     OpenAI's `refusal`;
+//   • `usage` carries `cached_tokens` (Moonshot's automatic context caching);
+//   • the error envelope is `{ error: { message, type, code? } }` (ErrorResponse schema);
+//   • the Messages surface answers `{ type:'error', error:{type,message}, request_id? }`
+//     (MessagesErrorResponse schema) — a DIFFERENT envelope on the same host.
+// ── Files ───────────────────────────────────────────────────────────────────────────────
+/** File purposes — a CLOSED documented set (FileObject schema). */
+export const FILE_PURPOSES = ['file-extract', 'image', 'video', 'batch'];

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@volter/twin-moonshot",
+  "version": "0.1.0",
+  "description": "Local Moonshot (Kimi) twin — a faithful, stateful local Moonshot Platform API your real `openai` / `anthropic` SDKs (swapped base URL) talk to unmodified. The model is stubbed (deterministic), but the protocol envelope across three inference protocols (OpenAI chat completions + Responses, Anthropic-compatible Messages, with streaming grammars, tool calls and cache-split usage), models, files, batches, balance, token counting and signature verify are vendor-faithful. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/moonshot"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/moonshot#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-moonshot": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.69.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "openai": "^6.16.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createMoonshotTwinServer } from './moonshot-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === 'serve') {
+  const root = optionValue(rest, '--root') || process.env.VOLTER_STATE_DIR;
+  const port = Number(optionValue(rest, '--port') || 0) || undefined;
+  const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+  const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON file)
+  const server = await createMoonshotTwinServer({
+    ...(root ? { root } : {}), ...(port ? { port } : {}), readOnly, ...(scenario ? { scenarioPath: scenario } : {}),
+  });
+  process.stdout.write(`moonshot twin (Moonshot Platform API at /v1 and /anthropic/v1; model output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${server.port}\n`);
+} else if (cmd === 'conformance') {
+  // Lazy — the conformance module is DEV-ONLY and must not be reachable from the runtime
+  // entrypoints (recipe §3/§4, enforced by scripts/architecture.test.ts).
+  const { checkMoonshotConformance } = await import('./moonshot-conformance.ts');
+  const report = await checkMoonshotConformance({ root: process.env.VOLTER_STATE_DIR });
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.ok ? 0 : 1);
+} else {
+  console.log('usage: world-moonshot serve [--port N] [--root DIR] [--read-only] [--scenario FILE] | conformance');
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+// @volter/twin-moonshot — the Moonshot (Kimi) twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The Moonshot Platform API: a vendor-faithful protocol envelope on
+// THREE inference protocols (OpenAI-compatible /v1/chat/completions + /v1/responses, and the
+// Anthropic-compatible /anthropic/v1/messages), a static models catalog, STATEFUL files +
+// batches + account balance, and the deterministic stateless helpers (token counting, signature
+// verify, web-search tools) — over an event/action log.
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so the three inference endpoints
+// return a DETERMINISTIC STUB completion (clearly labeled), never pretending to be real
+// inference. Everything around them — the wire protocol, the rejections, the stateful objects —
+// is faithful.
+//
+// MOONSHOT SHIPS NO SDK OF ITS OWN: its documented integration path is the standard `openai` /
+// `anthropic` SDKs with a swapped base URL (platform.kimi.ai/docs/overview, read 2026-09-16), so
+// the pack claims no vendor SDK in `adoption.sdks` and the fidelity test drives the real
+// `openai` SDK at the twin. (Conformance + capability tooling live in @volter/world-tooling, a
+// dev dependency — NOT re-exported here, per E2.)
+export { handleMoonshotTwinRequest, streamChat, streamMessages, streamResponses, buildChatCompletion, buildMessagesResponse, buildResponsesResponse, MOONSHOT_API_PREFIX, MESSAGES_PREFIX, messagesSignature } from './moonshot-twin.ts';
+export type { MoonshotRequest, MoonshotResponseEnvelope, MessagesSseSink } from './moonshot-twin.ts';
+export { createMoonshotTwinFetch, createMoonshotTwinServer, type MoonshotTwinFetchOptions } from './moonshot-server.ts';
+export { MOONSHOT_MODELS, findModel, BATCH_MODELS, REASONING_EFFORTS, K26_THINKING_TYPES, K27_THINKING_TYPES } from './moonshot-models.ts';
+export {
+  buildChatUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText,
+  stubAssistantText, stubCachedTokens, stubFetchedMarkdown, stubJsonObject, stubReasoningContent,
+  stubSearchResults, stubSignature, stubToolArguments, stubToolCall,
+} from './moonshot-stub.ts';
+export type {
+  MoonshotAssistantMessage, MoonshotBatch, MoonshotChatChunk, MoonshotChatCompletion, MoonshotChoice,
+  MoonshotError, MoonshotFile, MoonshotMessageParam, MoonshotMessagesBlock, MoonshotMessagesResponse,
+  MoonshotModelObject, MoonshotResponsesOutputItem, MoonshotResponsesResponse, MoonshotResponsesUsage,
+  MoonshotToolCall, MoonshotUsage, SseEvent, SseSink, MessagesSseEvent,
+} from './moonshot-types.ts';
+export { createMoonshotScenarioEngine, moonshotScenarioAdapter, loadMoonshotScenarioDocument, realizeMoonshotRespond } from './moonshot-scenario.ts';
+export type { MoonshotScenarioEngine, MoonshotScenarioRequest, MoonshotScenarioRespond, ScenarioToolCall, ScriptedResult } from './moonshot-scenario.ts';
+export {
+  fullSyncMoonshot,
+  externalIdFor,
+  liveMoonshotExecute,
+  mapBalance,
+  mapBatch,
+  mapFile,
+  mapModel,
+  moonshotExecuteOver,
+  moonshotRequestForAction,
+  performMoonshotAction,
+  pullMoonshotState,
+  pushMoonshotAction,
+  pushPendingMoonshotActions,
+  syncMoonshotFromReal,
+  syncMoonshotFromRemote,
+  unpushableReason,
+} from './moonshot-connector.ts';
+export type { MoonshotExecute, LiveMoonshotOptions } from './moonshot-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveMoonshotExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Moonshot's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `MoonshotBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  MOONSHOT_BUDGET_CEILING,
+  MOONSHOT_BUDGET_MAX_RETRY_AFTER_S,
+  MOONSHOT_BUDGET_WINDOW_MS,
+  MOONSHOT_CALL_WEIGHTS,
+  MOONSHOT_RATE_BUDGET,
+  MoonshotBudget,
+  MoonshotBudgetError,
+  moonshotBudgetPath,
+  moonshotCallWeight,
+} from './moonshot-budget.ts';
+export type { MoonshotBudgetErrorKind, MoonshotBudgetOptions, MoonshotBudgetReservation, MoonshotBudgetSnapshot } from './moonshot-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { MOONSHOT_RATE_BUDGET as RATE_BUDGET } from './moonshot-budget.ts';
+import { performMoonshotAction, syncMoonshotFromRemote } from './moonshot-connector.ts';
+export const pack: TwinPack = {
+  vendor: 'moonshot',
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system: perform one entry against Moonshot, refresh the root from it.
+  protocol: '2',
+  refresh: { every: '5m', onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performMoonshotAction, refresh: syncMoonshotFromRemote },
+  // the round trip: a file — the one thing this API mints an id for and keeps, and a fresh id each
+  // time, so it repeats cleanly on a branch. (A batch needs a seeded input file; a completion is
+  // answered, not kept.)
+  roundTrip: { method: 'POST', path: '/v1/files', body: { purpose: 'batch', filename: 'round-trip.jsonl', content: 'x' }, headers: { authorization: 'Bearer sk-round-trip' } },
+  // The SAME object moonshot-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-moonshot',
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    'model': 'the vendor catalog',
+    'balance': 'the account ledger the vendor keeps; read-only',
+  },
+  resources: ['file', 'batch', 'balance', 'model'],
+  specSource: 'Moonshot Platform API — enumerated from Moonshot\'s own OpenAPI 3.1.0 document (https://platform.kimi.ai/docs/openapi.json, read 2026-09-16; 19 operations) + platform.kimi.ai/docs/{overview,api-reference,errors,models,pricing/limits,guides/context-caching} (read 2026-09-16). Envelope-faithful across the OpenAI-compatible /v1 and Anthropic-compatible /anthropic/v1 surfaces; model output is a labeled deterministic stub.',
+  description: 'Moonshot (Kimi) API twin — faithful protocol envelope across three inference protocols (OpenAI chat completions, Responses, Anthropic-compatible Messages) with streaming grammars, tool calls and cache-split usage; models catalog; stateful files/batches/balance; deterministic token counting, signature verify and web-search tool stubs; Moonshot\'s own documented rejections.',
+  // Moonshot serves BOTH surfaces on one host. browserRouting points the browser lane at the
+  // OpenAI-compatible prefix, which is the dominant client form.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.moonshot.ai' },
+  // ADOPTION (adding-a-twin.md §3): how an app repo betrays that it talks to Moonshot. Declared
+  // HERE, not in world-runtime's central SDK_TWINS/ENV_STEM_VENDORS maps — declaring in both
+  // throws. Moonshot ships NO SDK of its own: its documented clients are the standard `openai`
+  // and `anthropic` SDKs with a swapped base URL, and BOTH of those npm names belong to their
+  // own vendors' packs (openai → @volter/twin-openai, anthropic → @volter/twin-anthropic) — a
+  // repo depending on `openai` is an OpenAI repo unless its base URL says otherwise. What
+  // betrays Moonshot specifically is the ENV STEM (`MOONSHOT_API_KEY` / `MOONSHOT_BASE_URL`)
+  // and the deepseek precedent: no sdk claim, envStems only.
+  adoption: {
+    // No official Moonshot PyPI client is documented (the docs name the OpenAI Python SDK).
+    pypi: [],
+    sdks: [], envStems: ['MOONSHOT'],
+  },
+  // INTERCEPTION: the ONE host both documented clients address (the openai SDK pointed at
+  // https://api.moonshot.ai/v1 and the anthropic SDK pointed at https://api.moonshot.ai/anthropic).
+  hosts: [{ host: 'api.moonshot.ai' }],
+  // No app-read endpoint env, deliberately. Moonshot documents no MOONSHOT_BASE_URL-style env
+  // var: the standard SDKs take their base URL as a CONSTRUCTOR option (`new OpenAI({
+  // baseURL })`), not from the environment, so an app-read var would cover only env-configured
+  // callers while disabling the interception that covers all of them (the deepseek/groq
+  // precedent). Emitting both would quietly forgo interception (`init.test.ts`, "the app-read
+  // endpoint table cannot go stale behind the injector").
+  endpointEnvNone: 'Moonshot ships no SDK of its own; its documented clients (the standard openai/anthropic SDKs) take their base URL as a constructor option and read no MOONSHOT_BASE_URL env, so an app-read var would cover only env-configured callers while disabling the api.moonshot.ai interception that covers all traffic.',
+};
+
+registerPack(pack);

package/src/moonshot-budget.ts

@@ -0,0 +1,163 @@
+// The client-side rate budget — the fail-closed backstop `liveMoonshotExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Moonshot's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings, exactly as every other pack does.
+//
+// THE GROUNDING (platform.kimi.ai/docs/pricing/limits, read 2026-09-16): Moonshot publishes a
+// per-tier table whose LOWEST published row (Tier 0, deposit ≥ $1) is concurrency 1, RPM 3,
+// TPM 500,000, TPD 1,500,000. RPM 3 is an order of magnitude UNDER the kernel's undeclared
+// fallback (30 calls/min), so the declaration buys resolution DOWNWARD from the fallback, never
+// headroom: the ceiling is pinned at the kernel fallback in units, and the INFERENCE rules price
+// the model-facing endpoints at a weight that keeps the real RPM-3 worst case inside the window.
+// The tier table scales up to Tier 5 (RPM 300), but no caller's tier is knowable here — the
+// budget protects the LOWEST tier by construction, and a higher tier is only ever under-spent.
+// Web-search endpoints (POST /v1/tools/search, /v1/tools/search_pro, /v1/tools/fetch) are
+// metered on their OWN QPS (QPS 1 at Tier 0), independent of the inference RPM — they get their
+// own rule so a search sweep cannot be priced as a cheap read.
+//
+// THE 429 SHAPE (same limits page): a real 429 carries `X-RateLimit-Limit` /
+// `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers. `recordCall` reads the standard
+// `retry-after` backstop plus these.
+import {
+  declareRateBudget, rateBudgetPath, rateBudgetWeight,
+  RateBudget, RateBudgetError, type RateBudgetDeclaration, type RateBudgetOptions,
+  type RateBudgetReservation, type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'moonshot';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const MOONSHOT_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback. Moonshot DOES publish an RPM scalar (3 at Tier 0),
+ * but it is a CALL ceiling, not a weight-unit ceiling; pricing every call 2 keeps the fallback
+ * shape and lets the inference rules spend the allowance where the vendor actually meters it.
+ */
+export const MOONSHOT_BUDGET_CEILING = 60;
+
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const MOONSHOT_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const MOONSHOT_CALL_WEIGHTS = {
+  /** Model-facing inference: /v1/chat/completions, /v1/responses, /anthropic/v1/messages.
+   *  At 60/6 that is at most 10 inference calls a window — inside Tier 0's RPM 3×window shape
+   *  for a single burst while leaving room for the interleaved reads a real client issues. */
+  inference: 6,
+  /** The web-search tool endpoints — Moonshot meters them on their OWN QPS (1 at Tier 0),
+   *  independent of inference RPM. Priced like inference so a sweep cannot ride the read weight. */
+  webSearch: 6,
+  /** Everything else: models, files, batches, balance, token counting, signature verify. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Moonshot-specific thing in the whole budget. */
+export const MOONSHOT_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: MOONSHOT_BUDGET_WINDOW_MS,
+  ceiling: MOONSHOT_BUDGET_CEILING,
+  defaultWeight: MOONSHOT_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: MOONSHOT_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    // Anchored on Moonshot's REAL paths. Inference is token-metered (TPM 500,000 at Tier 0
+    // dwarfs RPM 3 as the binding constraint on real traffic), so model-facing POSTs cost 6.
+    { match: '^POST /v1/chat/completions$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+    { match: '^POST /v1/responses$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+    { match: '^POST /anthropic/v1/messages$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+    // Web-search tools: own QPS pool at the vendor, priced at inference weight here.
+    { match: '^POST /v1/tools/search$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+    { match: '^POST /v1/tools/search_pro$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+    { match: '^POST /v1/tools/fetch$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+  ],
+  reason:
+    'Moonshot publishes a per-tier limit table (platform.kimi.ai/docs/pricing/limits, read ' +
+    '2026-09-16): Tier 0 (deposit ≥ $1) is concurrency 1, RPM 3, TPM 500,000, TPD 1,500,000, ' +
+    'Web Search QPS 1; Tier 5 (≥ $3000) is 100/300/5M/Unlimited/50. A 429 carries ' +
+    'X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset. Because the LOWEST published ' +
+    'RPM (3) is far under the kernel fallback of 30 calls/min, the ceiling is pinned AT the ' +
+    'fallback (60 units / 60s, defaultWeight 2) and the declaration spends it downward: the three ' +
+    'model-facing inference endpoints (POST /v1/chat/completions, POST /v1/responses, ' +
+    'POST /anthropic/v1/messages) cost 6 each — at most 10 land in a window — because those calls ' +
+    'are token-metered (TPM) at the vendor and one call spends far more of a real account\'s ' +
+    'allowance than a list poll. The web-search tool endpoints get their own 6-weight rule ' +
+    'because Moonshot meters them on a SEPARATE QPS pool (1 at Tier 0), so a search sweep must ' +
+    'not be priceable as a cheap read. The per-tier judgment call is the strict direction: the ' +
+    'budget protects Tier 0 by construction and only ever under-spends a higher tier. The window ' +
+    'bounds the 60s AVERAGE and does not pace; a `retry-after` read off a real 429 is the ' +
+    'persisted cooldown backstop.',
+};
+
+// Declared at module load, so merely importing this module (which `moonshot-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, MOONSHOT_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Moonshot. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function moonshotCallWeight(method: string, path: string): number {
+  const { bare, query } = moonshotSplitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/v1/chat/completions?a=1` -> `{ bare: '/v1/chat/completions', query: { a: '1' } }`. Rules
+ * match the path; NORMALIZED, because the anchored rules are otherwise trivially evaded: `fetch`
+ * upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE that a
+ * `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor while
+ * most routers treat it as the same endpoint.
+ */
+function moonshotSplitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  // Collapse REPEATED slashes as well as a trailing one: `//v1/chat/completions` reaches the
+  // same endpoint on most routers but misses a `^POST /v1/...$` rule, which would price an
+  // inference call as a 2-unit read.
+  const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Moonshot's ledger lives. Token-keyed and cwd-independent by default (Moonshot's limits
+ *  are per ACCOUNT, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function moonshotBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Moonshot's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type MoonshotBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Moonshot's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof MoonshotBudget` in `liveMoonshotExecute` means
+ * "a budget that accounts against MOONSHOT's ledger under MOONSHOT's ceiling".
+ */
+export class MoonshotBudget extends RateBudget {
+  constructor(opts: MoonshotBudgetOptions = {}) {
+    super({
+      ...opts,
+      // Field-per-line so the mutation gate can neuter the vendor binding: a budget whose
+      // `vendor` is not 'moonshot' accounts against another vendor's ledger, and the ceiling
+      // verify reads `err.vendor` off the refusal — the neuter must redden THAT assertion.
+      vendor: VENDOR,
+    });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as MoonshotBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as MoonshotBudgetErrorKind } from '@volter/world-core';
+/** Re-exported so a caller can age a window out against the DECLARED window, not a hard-coded 60_000. */
+export { MOONSHOT_BUDGET_WINDOW_MS as MOONSHOT_RATE_BUDGET_WINDOW_MS };
+export type MoonshotBudgetReservation = RateBudgetReservation;
+export type MoonshotBudgetSnapshot = RateBudgetSnapshot;