@volter/twin-moonshot 0.1.0

package/src/moonshot-connector.ts

@@ -0,0 +1,465 @@
+// Moonshot CONNECTOR — the live-vendor pull/push path that gives the Moonshot twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// 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.
+//   REFRESH (real → twin): fetch the real Models / Files / Batches / Balance, map them to
+//                          observed resources, and fold them onto the root's log through the
+//                          kernel's `observeResources` (content-addressed entries, so re-pulling
+//                          identical state appends nothing).
+//   PERFORM (twin → real): the HEAD calls `performMoonshotAction` per deployable entry; the
+//                          vendor's minted id comes back as the `externalId` the kernel adopts.
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO
+// Moonshot key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveMoonshotExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources, resolveSubjectId } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { MoonshotBudget, MoonshotBudgetError, moonshotCallWeight, type MoonshotBudgetOptions } from './moonshot-budget.ts';
+
+const SERVICE = 'moonshot';
+
+/**
+ * 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 function liveMoonshotExecute(
+  apiKey: string,
+  base = 'https://api.moonshot.ai',
+  opts: LiveMoonshotOptions = {},
+): MoonshotExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED MoonshotBudget — a duck-typed stand-in, a SUBCLASS overriding
+  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+  // would otherwise hand back a client with no ceiling. The default ledger is keyed by a hash of
+  // THIS key: Moonshot limits per account, so a cwd-scoped ledger would hand the same key a
+  // fresh allowance per checkout/worktree/CI leg.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, MoonshotBudget, 'liveMoonshotExecute')
+    : new MoonshotBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    // A path this pack never modelled is refused BEFORE the budget is even charged: an executor
+    // that will happily issue any URL is how a careless script reaches an unpriced endpoint.
+    if (!path.startsWith('/v1/') && !path.startsWith('/anthropic/v1/')) {
+      throw new Error(`moonshot: refusing to call an unmodeled path "${path}" — Moonshot serves /v1 and /anthropic/v1`);
+    }
+    const headers: Record<string, string> = { authorization: `Bearer ${apiKey}` };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method === 'POST') {
+      headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(body ?? {});
+    }
+    const weight = moonshotCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const parsed = (await res.json()) as { data?: any; error?: { message?: string; type?: string } };
+    // Settles the reservation and, on a back-off signal, arms the cooldown.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Moonshot ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof MoonshotBudgetError) || !res.ok) throw error;
+    }
+    return parsed;
+  };
+}
+
+function listOf(res: { data?: unknown }): any[] {
+  return Array.isArray(res.data) ? res.data : [];
+}
+/**
+ * A REFUSED pull is NOT an empty account. Moonshot answers failures with its documented
+ * `{ error: { message, type } }` envelope, so a status check alone is not enough — throw on the
+ * envelope rather than folding an empty list over real observed state.
+ */
+function throwIfError(res: { error?: { message?: string; type?: string } }, ctx: string): void {
+  if (res.error) throw new Error(`moonshot ${ctx} failed: ${res.error.message ?? res.error.type ?? 'unknown error'}`);
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/** Map a real-Moonshot model object → a twin sync resource. */
+export function mapModel(m: Record<string, unknown>): SyncResource {
+  return {
+    type: 'model',
+    id: String(m.id),
+    fields: {
+      object: 'model',
+      created: (m.created as number) ?? null,
+      owned_by: (m.owned_by as string) ?? null,
+    },
+  };
+}
+
+/** Map a real-Moonshot File object → a twin sync resource. */
+export function mapFile(f: Record<string, unknown>): SyncResource {
+  return {
+    type: 'file',
+    id: String(f.id),
+    fields: {
+      object: 'file',
+      bytes: (f.bytes as number) ?? 0,
+      created_at: (f.created_at as number) ?? null,
+      filename: (f.filename as string) ?? null,
+      purpose: (f.purpose as string) ?? null,
+      status: (f.status as string) ?? null,
+    },
+  };
+}
+
+/** Map a real-Moonshot Batch object → a twin sync resource. */
+export function mapBatch(b: Record<string, unknown>): SyncResource {
+  const counts = (b.request_counts && typeof b.request_counts === 'object') ? (b.request_counts as Record<string, unknown>) : {};
+  return {
+    type: 'batch',
+    id: String(b.id),
+    fields: {
+      object: 'batch',
+      endpoint: (b.endpoint as string) ?? null,
+      input_file_id: (b.input_file_id as string) ?? null,
+      completion_window: (b.completion_window as string) ?? null,
+      status: (b.status as string) ?? null,
+      output_file_id: (b.output_file_id as string) ?? null,
+      created_at: (b.created_at as number) ?? null,
+      completed_at: (b.completed_at as number) ?? null,
+      request_counts: counts,
+    },
+  };
+}
+
+/** Map the real-Moonshot balance → the twin's 'balance' resource (id 'me'). */
+export function mapBalance(b: Record<string, unknown>): SyncResource {
+  const d = (b.data && typeof b.data === 'object') ? (b.data as Record<string, unknown>) : {};
+  return {
+    type: 'balance',
+    id: 'me',
+    fields: {
+      available_balance: (d.available_balance as number) ?? null,
+      voucher_balance: (d.voucher_balance as number) ?? null,
+      cash_balance: (d.cash_balance as number) ?? null,
+    },
+  };
+}
+
+const COLLECTIONS: Array<{ path: string; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { path: '/v1/models', map: mapModel },
+  { path: '/v1/files', map: mapFile },
+  { path: '/v1/batches', map: mapBatch },
+];
+
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullMoonshotState(execute: MoonshotExecute): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const c of COLLECTIONS) {
+    const res = await execute('GET', c.path);
+    throwIfError(res, `pull ${c.path}`);
+    for (const item of listOf(res)) out.push(c.map(item));
+  }
+  // The balance is its own envelope ({code, data:{…}, scode, status}) — no `data` list.
+  const bal = await execute('GET', '/v1/users/me/balance');
+  throwIfError(bal, 'pull /v1/users/me/balance');
+  out.push(mapBalance(bal as Record<string, unknown>));
+  return out;
+}
+
+/**
+ * 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 async function syncMoonshotFromReal(
+  execute: MoonshotExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await pullMoonshotState(execute);
+  const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+  });
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────
+
+// The twin operations this connector knows how to push to real Moonshot. Anything not here must
+// FAIL LOUDLY rather than be silently dropped — pushing an unrecognized op risks hitting the
+// wrong endpoint or no-op'ing a real change.
+const PUSHABLE_VERBS = new Set(['create', 'cancel', 'delete']);
+
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op: string): void {
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (!PUSHABLE_VERBS.has(verb)) {
+    throw new Error(`moonshot push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+  const why = UNPUSHABLE[op];
+  if (why) throw new Error(`moonshot push: cannot push '${op}' — ${why}`);
+}
+
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export function unpushableReason(op: string): string | null {
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (!PUSHABLE_VERBS.has(verb)) return `unsupported operation '${op}'`;
+  return UNPUSHABLE[op] ?? null;
+}
+
+// Map a subject type → its REST collection path.
+const COLLECTION_PATH: Record<string, string> = {
+  file: '/v1/files',
+  batch: '/v1/batches',
+};
+
+/**
+ * Pushes this connector must REFUSE rather than fake, keyed `"<type>.<verb>"`.
+ *
+ * `file.create` is the case: real Moonshot's `POST /v1/files` is multipart/form-data carrying
+ * the actual file body, while this executor sends JSON. Pushing `{purpose, filename}` as JSON
+ * would 400 at the vendor, and the twin stores no binary content to upload anyway. Refusing
+ * loudly is the honest answer; the gap is filed as `moonshot.connector.push_file_create`.
+ */
+const UNPUSHABLE: Record<string, string> = {
+  'file.create': "real Moonshot's POST /v1/files is multipart/form-data with the file body; this JSON executor cannot express it, and the twin stores no real bytes to send",
+};
+
+/**
+ * The twin's LOCALLY-MINTED id namespace (`file_twin_1`, `batch_twin_3` — see `nextId` in
+ * moonshot-twin.ts). A subject still bearing one has no counterpart in the real account.
+ */
+const LOCAL_ID = /_twin_\d+$/;
+
+/**
+ * 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 function externalIdFor(subjectType: string, subjectId: string, root?: string): string | null {
+  if (!LOCAL_ID.test(subjectId)) return subjectId; // already a vendor id (e.g. observed by a pull)
+  const resolved = resolveSubjectId(SERVICE, subjectType, subjectId, root);
+  return resolved !== subjectId ? resolved : 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 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 } {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  const collection = COLLECTION_PATH[action.subject.type];
+  if (!collection) throw new Error(`moonshot push: no REST collection for subject type '${action.subject.type}'`);
+  if (verb === 'create') return { method: 'POST', path: collection };
+  const vendorId = externalId ?? action.subject.id;
+  if (LOCAL_ID.test(vendorId)) {
+    throw new Error(`moonshot push: refusing to address the real account by the twin's own id '${vendorId}' — no vendor id was ever recorded for this subject`);
+  }
+  if (verb === 'cancel') return { method: 'POST', path: `${collection}/${vendorId}/cancel` };
+  if (verb === 'delete') return { method: 'DELETE', path: `${collection}/${vendorId}` };
+  // assertPushable rejects anything else, so this is only reached for the pushable verbs above.
+  return { method: 'POST', path: collection };
+}
+
+/**
+ * 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 async function pushMoonshotAction(
+  execute: MoonshotExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+  opts: { externalId?: string } = {},
+): Promise<{ externalId: string }> {
+  assertPushable(action.operation ?? `${action.subject.type}.update`);
+  const { method, path } = moonshotRequestForAction(action, opts.externalId);
+  const verb = (action.operation ?? '').includes('.') ? action.operation!.slice(action.operation!.indexOf('.') + 1) : '';
+  const payload = verb === 'create' ? createPayload(action) : undefined;
+  const res = await execute(method, path, payload);
+  throwIfError(res, `push ${action.subject.type}`);
+  const id = (res as { id?: unknown }).id;
+  return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+
+function createPayload(action: Pick<TwinAction, 'subject' | 'fields'>): Record<string, unknown> {
+  const f = (action.fields ?? {}) as Record<string, unknown>;
+  switch (action.subject.type) {
+    case 'batch':
+      return { input_file_id: f.input_file_id, endpoint: f.endpoint, completion_window: f.completion_window, ...(f.metadata ? { metadata: f.metadata } : {}) };
+    default:
+      return {};
+  }
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** 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 function moonshotExecuteOver(execute: RemoteExecute): MoonshotExecute {
+  return async (method, path, body) => {
+    const res = await execute({
+      method, path,
+      headers: { accept: 'application/json', authorization: 'Bearer twin', ...(method === 'POST' ? { 'content-type': 'application/json' } : {}) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (res.body === '') return {};
+    try { return JSON.parse(res.body) as Record<string, unknown>; } catch { return { error: { type: 'server_error', message: res.body.slice(0, 200) } }; }
+  };
+}
+
+/** The refresh adapter: pull the account's models / files / batches / balance through the executor. */
+export async function syncMoonshotFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<ReturnType<typeof syncMoonshotFromReal>> {
+  return syncMoonshotFromReal(moonshotExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+
+/**
+ * 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 async function performMoonshotAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const why = unpushableReason(op);
+  if (why) return { externalId: action.subject.id, data: { performed: false, reason: why } };
+  const vendorId = ctx.resolve(action.subject.type, action.subject.id);
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (verb !== 'create' && LOCAL_ID.test(vendorId)) {
+    throw new Error(`moonshot push: refusing to address the real account by the twin's own id '${vendorId}' — no vendor id was ever recorded for this subject`);
+  }
+  const { externalId } = await pushMoonshotAction(moonshotExecuteOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} }, ...(verb !== 'create' ? [{ externalId: vendorId }] as const : [] as const));
+  return { externalId };
+}
+
+/**
+ * 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 async 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 }> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  const refused: Array<{ actionId: string; operation: string; reason: string }> = [];
+  for (const action of deployableEntries(SERVICE, opts.root)) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    // An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed
+    // and never silently dropped: it stays deployable, and it is named in `refused` so a caller
+    // can see it. Throwing instead meant ONE unpushable action — e.g. the local file create,
+    // whose real endpoint is multipart — aborted the whole sweep and took every unrelated
+    // pending write down with it.
+    const why = unpushableReason(op);
+    if (why) { refused.push({ actionId: action.id, operation: op, reason: why }); continue; }
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    // Anything but a create must address the vendor by the id the vendor issued. A locally-minted
+    // subject with none recorded is REFUSED, never guessed.
+    let external: string | undefined;
+    if (verb !== 'create') {
+      const resolved = externalIdFor(action.subject.type, action.subject.id, opts.root);
+      if (resolved === null) {
+        refused.push({ actionId: action.id, operation: op, reason: `no vendor id recorded for ${action.subject.type} '${action.subject.id}' — it was never pushed to the real account, so there is nothing there to ${verb}` });
+        continue;
+      }
+      external = resolved;
+    }
+    const { externalId } = await pushMoonshotAction(execute, action, ...(external !== undefined ? [{ externalId: external }] as const : [] as const));
+    // The kernel records the vendor's id as the subject ALIAS (the landed copy carries the
+    // vendor's id, aliasOf the local one), so a later delete/cancel resolves through
+    // `resolveSubjectId` — no `_external_id` field to read back.
+    confirmAction({
+      service: SERVICE, actionId: action.id, subject: action.subject,
+      fields: action.fields ?? {},
+      occurredAt: opts.occurredAt, vendorSubjectId: externalId, receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(action.id);
+    externalIds[action.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds, refused };
+}
+
+// ── FULL bi-directional sync ─────────────────────────────────────────────────
+/**
+ * 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 async 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 }> }> {
+  const push = await pushPendingMoonshotActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  const resources = await pullMoonshotState(execute);
+  const pull = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+  });
+  return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.appended, collections: COLLECTIONS.length + 1, refused: push.refused };
+}

package/src/moonshot-models.ts

@@ -0,0 +1,89 @@
+// Moonshot model catalog — the static `GET /v1/models` surface. The real platform serves a list
+// of OpenAI-shaped model objects; the twin returns a faithful, deterministic slice so
+// `client.models.list()` / `client.models.retrieve(id)` round-trip like the vendor.
+//
+// PROVENANCE (what is sourced, and what is not — §9 discipline):
+//   • the model ids are the exact strings Moonshot's own OpenAPI enumerates per request schema:
+//     KimiK3ChatRequest['model'] = 'kimi-k3'; KimiK27CodeChatRequest['model'] =
+//     'kimi-k2.7-code' | 'kimi-k2.7-code-highspeed'; KimiK26ChatRequest['model'] = 'kimi-k2.6';
+//     EstimateTokenRequest['model'] repeats the same four. (platform.kimi.ai/docs/openapi.json,
+//     read 2026-09-16.)
+//   • `context_length` comes from Moonshot's published model table
+//     (platform.kimi.ai/docs/models, read 2026-09-16): kimi-k3 1M (1,048,576); kimi-k2.7-code
+//     and kimi-k2.7-code-highspeed 256k (262,144); kimi-k2.6 256k.
+//   • `created` is NOT sourced — Moonshot publishes no per-model creation timestamp. The values
+//     are deterministic placeholders and no capability asserts them beyond `typeof === number`.
+//     Calling that out is the point: the rest of this table is sourced, this column is not.
+//   • RETIRED ids are deliberately ABSENT: moonshot-v1-*, kimi-latest (2026-01-28) and the
+//     kimi-k2 series (2026-05-25) are shut down per the same models page. A twin that still
+//     served them would let a stale client "work" locally and then 404 against the vendor.
+//
+// Moonshot has NO embeddings, audio, or image-generation models — chat, Responses, Messages,
+// files, batches, token counting, signatures and web-search tools are the whole surface.
+export type MoonshotModel = {
+  id: string;
+  object: 'model';
+  created: number;
+  owned_by: string;
+  /** The OpenAPI request schema's enum for this id — which endpoints accept it. */
+  supports: {
+    /** POST /v1/chat/completions (all four). */
+    chat: boolean;
+    /** POST /v1/responses — kimi-k3 only ("This endpoint currently supports kimi-k3"). */
+    responses: boolean;
+    /** POST /anthropic/v1/messages — kimi-k3 only (MessagesRequest['model'] enum). */
+    messages: boolean;
+    /** POST /v1/batches — only kimi-k2.7-code(-highspeed) and kimi-k2.6, NOT kimi-k3. */
+    batch: boolean;
+    /** Vision (image_url parts in chat messages). kimi-k3 and kimi-k2.6 are vision models. */
+    vision: boolean;
+  };
+  context_length: number;
+  /** Max output tokens. kimi-k3: default 131072, up to 1048576 (ChatRequestCommon
+   *  max_completion_tokens description). The k2.6/k2.7-code models share the 256k window. */
+  max_completion_tokens: number;
+};
+
+const K3_CTX = 1_048_576;
+const K2_CTX = 262_144;
+
+export const MOONSHOT_MODELS: MoonshotModel[] = [
+  {
+    id: 'kimi-k3', object: 'model', created: 1_760_000_000, owned_by: 'moonshot',
+    supports: { chat: true, responses: true, messages: true, batch: false, vision: true },
+    context_length: K3_CTX, max_completion_tokens: 1_048_576,
+  },
+  {
+    id: 'kimi-k2.7-code', object: 'model', created: 1_760_000_001, owned_by: 'moonshot',
+    supports: { chat: true, responses: false, messages: false, batch: true, vision: false },
+    context_length: K2_CTX, max_completion_tokens: K2_CTX,
+  },
+  {
+    id: 'kimi-k2.7-code-highspeed', object: 'model', created: 1_760_000_002, owned_by: 'moonshot',
+    supports: { chat: true, responses: false, messages: false, batch: true, vision: false },
+    context_length: K2_CTX, max_completion_tokens: K2_CTX,
+  },
+  {
+    id: 'kimi-k2.6', object: 'model', created: 1_760_000_003, owned_by: 'moonshot',
+    supports: { chat: true, responses: false, messages: false, batch: true, vision: true },
+    context_length: K2_CTX, max_completion_tokens: K2_CTX,
+  },
+];
+
+/** Resolve a model by id, or undefined if the twin doesn't model it. */
+export function findModel(id: string): MoonshotModel | undefined {
+  return MOONSHOT_MODELS.find((m) => m.id === id);
+}
+
+/** The ids that accept a batch job's chat/completions requests. */
+export const BATCH_MODELS = new Set(MOONSHOT_MODELS.filter((m) => m.supports.batch).map((m) => m.id));
+
+/** kimi-k3's `reasoning_effort` — a CLOSED documented set (KimiK3ChatRequest). */
+export const REASONING_EFFORTS = ['low', 'high', 'max'] as const;
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+/** kimi-k2.6 `thinking.type` — enabled and disabled are BOTH supported. */
+export const K26_THINKING_TYPES = ['enabled', 'disabled'] as const;
+/** kimi-k2.7-code `thinking.type` — ONLY 'enabled'; 'disabled' returns an error (OpenAPI:
+ *  "Unlike kimi-k2.6, `\"disabled\"` is NOT supported — passing it returns an error."). */
+export const K27_THINKING_TYPES = ['enabled'] as const;