@volter/twin-moonshot 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,164 @@
+# @volter/twin-moonshot
+
+A local, faithful **Moonshot (Kimi) Platform API** twin your real `openai` / `anthropic` SDKs talk
+to **unmodified** — Moonshot ships no SDK of its own, and its documented integration path is the
+standard SDKs with a swapped base URL (platform.kimi.ai/docs/overview, read 2026-09-16). Point the
+client at the twin and chat completions, Responses, the Anthropic-compatible Messages surface,
+streaming, `models`, `files`, `batches`, the account balance, token counting and signature verify
+all work. Built on the shared `@volter/world-core` kernel (durable event/action log + projection);
+no parallel side store.
+
+```ts
+import OpenAI from 'openai';
+import { createMoonshotTwinServer } from '@volter/twin-moonshot';
+
+const { port } = createMoonshotTwinServer({});
+// Moonshot's base URL carries the version segment — the SDK builds every URL as
+// `${baseURL}/chat/completions`.
+const client = new OpenAI({ apiKey: 'sk-twin', baseURL: `http://127.0.0.1:${port}/v1` });
+const res = await client.chat.completions.create({
+  model: 'kimi-k3',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+// res.choices[0].message.content starts with "[twin-stub:kimi-k3]" — a deterministic stub,
+// clearly labeled. res.usage carries Moonshot's FLAT cache split: usage.cached_tokens, not
+// OpenAI's nested prompt_tokens_details.cached_tokens.
+```
+
+The Anthropic-compatible surface is a base-URL suffix, exactly as on the real vendor:
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+const anthropic = new Anthropic({ apiKey: 'sk-twin', baseURL: `http://127.0.0.1:${port}/anthropic` });
+```
+
+## Moonshot is not OpenAI — the differences this twin models
+
+Moonshot exposes an *OpenAI-compatible* surface, and treating "compatible" as "identical" is how a
+Moonshot twin gets built wrong. The load-bearing differences, each grounded in Moonshot's own
+OpenAPI 3.1.0 document (platform.kimi.ai/docs/openapi.json) and
+platform.kimi.ai/docs/{overview,api-reference,errors,models,pricing/limits,guides/context-caching},
+all read 2026-09-16:
+
+| | Moonshot | OpenAI |
+|---|---|---|
+| base path | **`https://api.moonshot.ai/v1/…`** (version segment in the base) | `https://api.openai.com/v1/…` |
+| second surface | **`/anthropic/v1/messages`** — the Anthropic-compatible Messages protocol on the SAME host | — |
+| `usage` cache split | **FLAT `usage.cached_tokens`** | nested `prompt_tokens_details.cached_tokens` |
+| streaming usage | the **usage tail chunk** (empty `choices[]`, whole usage object), then `data: [DONE]` — unconditional, per the OpenAPI's `ChatCompletionChunk.usage` ("Object in the final chunk with usage, null in ordinary chunks"); the prose chat doc mentions the chunk under `stream_options.include_usage`, so the two first-party sources disagree and the OpenAPI governs | opt-in extra chunk via `stream_options.include_usage` |
+| response signing | **`Msh-Request-Timestamp` + `Msh-Request-Signature`** (`reqsigv1_…`) headers on STREAMED model calls that carry `X-Msh-Request-Nonce` (a nonce-less call proceeds unsigned), verifiable at `POST /v1/signatures/verify` | — |
+| retired models | `moonshot-v1-*`, `kimi-latest`, `kimi-k2` are **gone from the catalog** — a stale client 400s/404s here like it does at the vendor | old ids keep serving |
+| thinking | `thinking` object **per-model**: kimi-k2.6 takes `{type:'enabled'\|'disabled', keep}`; kimi-k2.7-code refuses `'disabled'`; kimi-k3 has no `thinking` parameter | — |
+| reasoning | `reasoning_content` on the assistant message (and its own delta before content when streaming) | `reasoning` (Responses only) |
+| `reasoning_effort` | kimi-k3-only, closed set `'low'\|'high'\|'max'` | all reasoning models |
+| dynamic tools | kimi-k3 accepts a **system message carrying `tools` and no content** (dynamic tool loading); any other role is a 400 | — |
+| error envelope | `{ error: { message, type, … } }` with Moonshot's own type names (`invalid_authentication_error`, `rate_limit_reached_error`, `server_unavailable`, …) | `{ error: { message, type, param, code } }` |
+| balance | **`GET /v1/users/me/balance`** — its own envelope `{code, data:{cash_balance,voucher_balance,…}, scode, status}` | — |
+| token counting | **`POST /v1/tokenizers/estimate-token-count`** — a first-class endpoint, one tokenizer shared with chat's `prompt_tokens` | — |
+| statuses | 429 `rate_limit_reached_error` with the documented `X-RateLimit-*` header family; 503 `server_unavailable` | different type names |
+
+The twin serves `/v1/…` and `/anthropic/v1/…`. A request to the bare root (no version segment)
+404s, because Moonshot does not serve it either.
+
+## The generative-stub design (be honest)
+
+The twin **cannot run the model** — there are no weights here. So all three inference endpoints
+(`POST /v1/chat/completions`, `POST /v1/responses`, `POST /anthropic/v1/messages`) return a
+**deterministic STUB completion** that is unmistakably a twin stub (it carries a
+`[twin-stub:<model>]` marker and echoes your prompt), and the web-search tool endpoints return
+**deterministic labeled results**. They **never** pretend to be real model output.
+
+What **is** faithful is the **entire protocol envelope**:
+
+- chat response shape — `{ id:'chatcmpl-twin-…', object:'chat.completion', created, model, choices:[{index, message:{role:'assistant', content, reasoning_content?}, finish_reason}], usage:{prompt_tokens, completion_tokens, total_tokens, cached_tokens} }`
+- **streaming** via SSE — role delta → `reasoning_content` delta → content deltas → tool-call deltas → finish_reason chunk → Moonshot's **empty-choices usage tail** → `data: [DONE]` (driven through an injected sink — no real sockets in the handler)
+- **Responses** — the Responses envelope (object `response`, output items, `usage.input_tokens_details.cached_tokens`), `reasoning.effort`, `max_output_tokens` → `incomplete`, and its own SSE grammar (`response.created` → `output_item.added/done` → `response.completed`, `sequence_number` from 0)
+- **Messages (Anthropic-compatible)** — `{type:'message', content blocks, stop_reason, usage}` with a thinking block first, top-level `system`, `stop_sequences` (≤5, ≤32 bytes), and the Anthropic SSE grammar (`message_start` → thinking/text deltas → `message_delta` → `message_stop`, **no** `[DONE]` sentinel); kimi-k2.x refused with the **Messages** error envelope, never the `/v1` shape
+- **tool / function calling** — `tool_calls` + `finish_reason:'tool_calls'`, `tool_choice` (`none`/named), schema-shaped JSON arguments, tool-result turns, tool-name regex `^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$`
+- **structured outputs** — `response_format` `json_object` / `json_schema` (name + schema required) yield JSON stub content
+- `max_completion_tokens`/`max_tokens` (→ `finish_reason:'length'`; 0 is a 400), `stop` (earliest hit, ≤5 entries ≤32 bytes), `logprobs`/`top_logprobs` (accepted 0..20; `top_logprobs` without `logprobs:true` is a 400), `prompt_cache_key`, multi-turn history, system messages counted into `prompt_tokens`, vision gating (image parts on kimi-k3/kimi-k2.6, refused on kimi-k2.7-code), context-window overflow as a 400
+- **deterministic usage** — an identical request replays byte-identically
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- `GET /v1/models` (+ `/models/:id`) — the static catalog (kimi-k3, kimi-k2.7-code, kimi-k2.7-code-highspeed, kimi-k2.6); retired ids are NOT served
+- **Files** — `POST/GET/DELETE /v1/files` (+ `/content`), kernel-backed, purpose closed set, and a **dirty-state** proof that a deleted id is never re-minted. `POST /v1/files` is multipart on the real vendor and the server accepts the real multipart form (binary uploads travel base64 under the server's private `binary_content` marker and `GET /content` decodes before serving; text files round-trip byte for byte); a form with no `file` part is refused, and a pulled file's content read answers 501 — the vendor's list endpoint returns no content, so the twin honestly holds none
+- **Batches** — `POST/GET /v1/batches` (+ retrieve + cancel → `cancelling`, `cancelling_at` set, double cancel refused), input validated against an existing batch-purpose file, `endpoint` and `completion_window` closed sets
+- **Balance** — `GET /v1/users/me/balance` in Moonshot's own envelope shape
+- **Token counting** — `POST /v1/tokenizers/estimate-token-count` → `{data:{total_tokens}}`, and the estimate **equals** chat's `prompt_tokens` for the same input (one tokenizer, two doors)
+- **Signature verify** — `POST /v1/signatures/verify` recomputes the tuple; the server signs streamed model calls with `Msh-Request-Timestamp`/`Msh-Request-Signature`
+- **Web search tools** — `POST /v1/tools/search` (limit 1..20), `/v1/tools/search_pro` (sites ≤5, `time_window` validated), `/v1/tools/fetch` (http(s) URLs only)
+
+Vendor-shaped errors throughout: `400` / `401` / `404` / `405` (read-only guard) / `429` / `500` /
+`503`. Every `/v1` envelope carries `message` + `type` and only keys Moonshot's own error table
+declares; the Messages surface answers `{type:'error', error:{type,message}}`.
+
+## Connector (pull / push)
+
+`syncMoonshotFromReal` pulls real models / files / batches / balance into the twin;
+`pushPendingMoonshotActions` pushes pending local writes (create / cancel / delete) to the real API
+and confirms them. All vendor I/O is over an **injected client** (`liveMoonshotExecute(apiKey)`
+live; a fake in tests) — the pack holds no key and imports no SDK at runtime. Every live call is
+charged against the shared kernel `RateBudget` **before** it goes out, and the executor refuses any
+path outside `/v1/` and `/anthropic/v1/` before the budget is even charged.
+
+The rate budget's declaration is grounded in Moonshot's published tier table
+(platform.kimi.ai/docs/pricing/limits, read 2026-09-16): the LOWEST published row (Tier 0: RPM 3)
+is an order of magnitude under the kernel's 30-calls/minute fallback, so the ceiling is pinned AT
+the fallback and spent downward — the three inference endpoints and the three web-search endpoints
+(Moonshot meters the latter on their own QPS pool) price at 6 units each, reads at 2. A real 429's
+`X-RateLimit-*` headers arm a persisted cooldown that makes later calls fail fast without touching
+the vendor.
+
+## Coverage
+
+**Partial and honest.** The capability manifest is the *real Moonshot Platform API surface* as the
+denominator — enumerated from Moonshot's own OpenAPI 3.1.0 document (19 operations) reconciled
+against the prose docs, with the spec census
+(`moonshot-spec-census.json`) holding the exact bijection — not a list of what was built. The
+measurement lives in the repo-root coverage table (README.md /
+../../../docs/contributing/conformance.md, regenerated by
+`bun scripts/twin-capabilities.ts --write-docs moonshot`); run
+`bun scripts/manifest-baseline-one.ts moonshot` for this pack alone.
+
+The remaining `todo`s are real surface: per-request response ids (the twin derives `id` from a hash
+of the request, so two identical calls share one id), the asynchronous `cancelling` → `cancelled`
+batch settlement (settling on a READ would break the read-only contract), the multipart file-create
+push (the JSON executor cannot express a multipart body — the push is REFUSED rather than faked),
+and the unpushable-action drain (a permanently-unpushable action can never be acknowledged, so
+`pendingActions` never reaches empty).
+
+### No UI mirror
+
+Moonshot is an API-first vendor: an integrator POSTs `/v1/chat/completions` from code, and
+platform.kimi.ai is a keys/billing/usage console — incidental tooling, not where the work happens.
+So this pack ships no `client/` mirror and declares no UI capabilities. This matches the sibling
+generative packs (`openai`, `anthropic`, `deepseek`, `groq`, `xai`).
+
+## Scenario scripting (twin-only)
+
+The three inference endpoints can be scripted by MSW-shaped handlers in a world dir's
+`handlers/moonshot.json`, run by the ONE kernel scenario engine with this pack's adapter:
+
+```json
+{ "handlers": [
+  { "on": { "userTextIncludes": "summarize", "hasTool": "search_docs" },
+    "respond": { "text": "Scripted summary.", "reasoning": "scripted reasoning_content" }, "once": true },
+  { "on": { "thinkingTypeEquals": "disabled" }, "respond": { "error": { "type": "rate_limit_reached_error" } } }
+] }
+```
+
+Load it with `createMoonshotTwinServer({ scenarioPath })` / `TWIN_MOONSHOT_SCENARIO`. The read
+doors `GET /twin` and `GET /twin/scenario` explain and inspect it. A malformed file throws **at
+load**, never a silent fall-back. Scenario support is twin-only scaffolding for eval worlds, not
+vendor surface — it is kept OUT of the capability manifest (the coverage count above excludes
+it) and gated by `src/moonshot-scenario.test.ts`, including the kernel's fault grammar.
+
+## CLI
+
+```
+world-moonshot serve       [--port N] [--root DIR] [--read-only] [--scenario FILE]
+world-moonshot conformance
+```
+
+Both read their state root from `VOLTER_STATE_DIR` (`--root` overrides).

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createMoonshotTwinServer } from "./moonshot-server.js";
+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.js");
+    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/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export { handleMoonshotTwinRequest, streamChat, streamMessages, streamResponses, buildChatCompletion, buildMessagesResponse, buildResponsesResponse, MOONSHOT_API_PREFIX, MESSAGES_PREFIX, messagesSignature } from './moonshot-twin.js';
+export type { MoonshotRequest, MoonshotResponseEnvelope, MessagesSseSink } from './moonshot-twin.js';
+export { createMoonshotTwinFetch, createMoonshotTwinServer, type MoonshotTwinFetchOptions } from './moonshot-server.js';
+export { MOONSHOT_MODELS, findModel, BATCH_MODELS, REASONING_EFFORTS, K26_THINKING_TYPES, K27_THINKING_TYPES } from './moonshot-models.js';
+export { buildChatUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, stubAssistantText, stubCachedTokens, stubFetchedMarkdown, stubJsonObject, stubReasoningContent, stubSearchResults, stubSignature, stubToolArguments, stubToolCall, } from './moonshot-stub.js';
+export type { MoonshotAssistantMessage, MoonshotBatch, MoonshotChatChunk, MoonshotChatCompletion, MoonshotChoice, MoonshotError, MoonshotFile, MoonshotMessageParam, MoonshotMessagesBlock, MoonshotMessagesResponse, MoonshotModelObject, MoonshotResponsesOutputItem, MoonshotResponsesResponse, MoonshotResponsesUsage, MoonshotToolCall, MoonshotUsage, SseEvent, SseSink, MessagesSseEvent, } from './moonshot-types.js';
+export { createMoonshotScenarioEngine, moonshotScenarioAdapter, loadMoonshotScenarioDocument, realizeMoonshotRespond } from './moonshot-scenario.js';
+export type { MoonshotScenarioEngine, MoonshotScenarioRequest, MoonshotScenarioRespond, ScenarioToolCall, ScriptedResult } from './moonshot-scenario.js';
+export { fullSyncMoonshot, externalIdFor, liveMoonshotExecute, mapBalance, mapBatch, mapFile, mapModel, moonshotExecuteOver, moonshotRequestForAction, performMoonshotAction, pullMoonshotState, pushMoonshotAction, pushPendingMoonshotActions, syncMoonshotFromReal, syncMoonshotFromRemote, unpushableReason, } from './moonshot-connector.js';
+export type { MoonshotExecute, LiveMoonshotOptions } from './moonshot-connector.js';
+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.js';
+export type { MoonshotBudgetErrorKind, MoonshotBudgetOptions, MoonshotBudgetReservation, MoonshotBudgetSnapshot } from './moonshot-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,86 @@
+// @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.js";
+export { createMoonshotTwinFetch, createMoonshotTwinServer } from "./moonshot-server.js";
+export { MOONSHOT_MODELS, findModel, BATCH_MODELS, REASONING_EFFORTS, K26_THINKING_TYPES, K27_THINKING_TYPES } from "./moonshot-models.js";
+export { buildChatUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, stubAssistantText, stubCachedTokens, stubFetchedMarkdown, stubJsonObject, stubReasoningContent, stubSearchResults, stubSignature, stubToolArguments, stubToolCall, } from "./moonshot-stub.js";
+export { createMoonshotScenarioEngine, moonshotScenarioAdapter, loadMoonshotScenarioDocument, realizeMoonshotRespond } from "./moonshot-scenario.js";
+export { fullSyncMoonshot, externalIdFor, liveMoonshotExecute, mapBalance, mapBatch, mapFile, mapModel, moonshotExecuteOver, moonshotRequestForAction, performMoonshotAction, pullMoonshotState, pushMoonshotAction, pushPendingMoonshotActions, syncMoonshotFromReal, syncMoonshotFromRemote, unpushableReason, } from "./moonshot-connector.js";
+// 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.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { MOONSHOT_RATE_BUDGET as RATE_BUDGET } from "./moonshot-budget.js";
+import { performMoonshotAction, syncMoonshotFromRemote } from "./moonshot-connector.js";
+export const pack = {
+    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/dist/src/moonshot-budget.d.ts

@@ -0,0 +1,57 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const MOONSHOT_BUDGET_WINDOW_MS = 60000;
+/**
+ * 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 declare const MOONSHOT_BUDGET_CEILING = 60;
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export declare 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 declare 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. */
+    readonly 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. */
+    readonly webSearch: 6;
+    /** Everything else: models, files, batches, balance, token counting, signature verify. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only Moonshot-specific thing in the whole budget. */
+export declare const MOONSHOT_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * 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 declare function moonshotCallWeight(method: string, path: string): number;
+/** 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 declare function moonshotBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** 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 declare class MoonshotBudget extends RateBudget {
+    constructor(opts?: MoonshotBudgetOptions);
+}
+/** 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;