@volter/twin-deepseek 0.1.0

package/src/deepseek-connector.ts

@@ -0,0 +1,440 @@
+// DeepSeek CONNECTOR — the live-vendor pull/push path that gives the DeepSeek twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// PULL  (real → twin):  fetch the real Models / Files / user balance, map them to SyncResource[], and
+//                       fold into the event log via syncPull (shadow-diff dedup, so re-pulling
+//                       identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action (create / delete), call the real DeepSeek
+//                       REST API and confirmAction on success.
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO DeepSeek
+// key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveDeepSeekExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, pendingActions, projectResources, syncPull } from '@volter/world-core';
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { DeepSeekBudget, DeepSeekBudgetError, deepseekCallWeight, type DeepSeekBudgetOptions } from './deepseek-budget.ts';
+
+const SERVICE = 'deepseek';
+
+/**
+ * The injected real-DeepSeek boundary. `request` issues ONE DeepSeek REST call:
+ *   method  — 'GET' | 'POST' | 'DELETE'
+ *   path    — e.g. '/files' or '/files/file-api-abc'. NOTE: DeepSeek's base_url carries NO `/v1`
+ *             segment (api-docs.deepseek.com, "Your First API Call") — an executor built on the
+ *             OpenAI habit of prefixing `/v1` would 404 every call.
+ *   body    — JSON body for POST (omitted otherwise)
+ * Returns the parsed JSON (an object, a `{ data }` list, or an `{ error }` envelope).
+ */
+export type DeepSeekExecute = (
+  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 LiveDeepSeekOptions = {
+  /** 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?: DeepSeekBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: DeepSeekBudgetOptions;
+};
+
+/**
+ * The ONLY real paths this connector may address. An executor that will happily issue any URL is
+ * how a careless script reaches an unpriced endpoint — and, on this vendor, how an OpenAI-shaped
+ * `/v1/...` path silently escapes both the budget rules and the vendor's own routing.
+ */
+const MODELED_LIVE_PATHS: RegExp[] = [
+  /^\/models$/,
+  /^\/user\/balance$/,
+  /^\/files(\?|$)/,
+  /^\/files\/[^/]+$/,
+];
+
+/**
+ * A live executor against the real DeepSeek 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.deepseek.com` 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 `DeepSeekBudgetError` 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-requests: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching DeepSeek. 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 `deepseek-budget.ts` and the kernel header for the limits
+ * of the guarantee.
+ */
+export function liveDeepSeekExecute(
+  apiKey: string,
+  base = 'https://api.deepseek.com',
+  opts: LiveDeepSeekOptions = {},
+): DeepSeekExecute {
+  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 DeepSeekBudget — 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: DeepSeek limits
+  // per organization, 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, DeepSeekBudget, 'liveDeepSeekExecute')
+    : new DeepSeekBudget({ 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 (!MODELED_LIVE_PATHS.some((re) => re.test(path))) {
+      throw new Error(`deepseek: refusing to call an unmodeled path "${path}" — this connector only addresses ${MODELED_LIVE_PATHS.map((re) => re.source).join(', ')}`);
+    }
+    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 = deepseekCallWeight(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 DeepSeek 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 DeepSeekBudgetError) || !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. DeepSeek 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(`deepseek ${ctx} failed: ${res.error.message ?? res.error.type ?? 'unknown error'}`);
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/**
+ * Map a real-DeepSeek Model object → a twin sync resource.
+ *
+ * THREE keys, because that is the whole object DeepSeek's `GET /models` returns
+ * (api-docs.deepseek.com/api/list-models). The exemplar this pack was cloned from also folded
+ * `created`, `active` and `context_window`; carrying those over would have written nulls into the
+ * projection for fields the vendor never sends and then served them back as if observed.
+ */
+export function mapModel(m: Record<string, unknown>): SyncResource {
+  return {
+    type: 'model',
+    id: String(m.id),
+    fields: { object: 'model', owned_by: (m.owned_by as string) ?? null },
+  };
+}
+
+/** Map a real-DeepSeek 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,
+      // Present only when the upload requested an expiry — folding `null` in would make a permanent
+      // file look like an expiring one whose `expires_at` the vendor forgot.
+      ...(f.expires_at !== undefined ? { expires_at: f.expires_at as number } : {}),
+    },
+  };
+}
+
+/**
+ * Map `GET /user/balance` → the SINGLETON `balance/account` resource. Unlike models and files this
+ * endpoint answers ONE object, not a `{ data: [] }` list, so it gets its own pull step. It is real
+ * observable remote state and it is load-bearing: the twin's 402 "You have run out of balance" path
+ * reads `is_available` off this projection, so pulling a drained account makes the twin refuse
+ * completions exactly the way the real one would.
+ */
+export function mapBalance(b: Record<string, unknown>): SyncResource {
+  return {
+    type: 'balance',
+    id: 'account',
+    fields: {
+      is_available: b.is_available === true,
+      balance_infos: Array.isArray(b.balance_infos) ? b.balance_infos : [],
+    },
+  };
+}
+
+/** List endpoints whose reply is `{ object: 'list', data: [...] }`. */
+const COLLECTIONS: Array<{ path: string; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { path: '/models', map: mapModel },
+  { path: '/files', map: mapFile },
+];
+/** Singleton endpoints whose reply IS the object. */
+const SINGLETONS: Array<{ path: string; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { path: '/user/balance', map: mapBalance },
+];
+
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullDeepSeekState(execute: DeepSeekExecute): 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));
+  }
+  for (const sgl of SINGLETONS) {
+    const res = await execute('GET', sgl.path);
+    throwIfError(res, `pull ${sgl.path}`);
+    out.push(sgl.map(res as Record<string, unknown>));
+  }
+  return out;
+}
+
+/**
+ * Pull from real DeepSeek and fold into the twin (mirror seeding). syncPull's shadow-diff makes a
+ * re-pull of identical state a no-op.
+ *
+ * `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 `syncPull` reports a phantom delta while the
+ * projection keeps the stale value (ADDING_A_TWIN.md §6). Callers pass a moving timestamp.
+ */
+export async function syncDeepSeekFromReal(
+  execute: DeepSeekExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await pullDeepSeekState(execute);
+  const result = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────
+
+// The twin operations this connector knows how to push to real DeepSeek. 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', 'delete']);
+
+/**
+ * Subject types that are the TWIN'S OWN bookkeeping and have no vendor counterpart at all.
+ *
+ * `cache_prefix` is the context-cache ledger (deepseek-cache.ts). DeepSeek's cache is server-side
+ * and exposed only as two numbers on `usage` — there is no endpoint that creates, reads or deletes
+ * a cache prefix, so these actions are not a push GAP, they are not vendor writes. They are skipped
+ * by NAME and reported in `skippedInternal`, never silently dropped and never counted as refusals:
+ * every chat completion mints one, so folding them into `refused` would bury the real gaps.
+ */
+const INTERNAL_SUBJECT_TYPES = new Set(['cache_prefix']);
+
+/** 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(`deepseek push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+  const why = UNPUSHABLE[op];
+  if (why) throw new Error(`deepseek 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: '/files',
+};
+
+/**
+ * Pushes this connector must REFUSE rather than fake, keyed `"<type>.<verb>"`.
+ *
+ * `file.create` is the case: real DeepSeek's `POST /files` is multipart/form-data carrying the
+ * actual image bytes (`@ai-sdk/deepseek` builds a `FormData` with the blob and `purpose=user_data`,
+ * src/files/deepseek-files.ts), while this executor sends JSON. Pushing `{purpose, filename}` as
+ * JSON would be refused at the vendor, and the twin stores no real image bytes to upload anyway
+ * (the twin stores no uploaded bytes yet — `deepseek.files.binary_content`). Refusing loudly is the honest answer; the gap is
+ * filed as `deepseek.connector.push_file_create`.
+ */
+const UNPUSHABLE: Record<string, string> = {
+  'file.create': "real DeepSeek's POST /files is multipart/form-data carrying the image bytes; this JSON executor cannot express it, and the twin stores no real bytes to send",
+};
+
+/**
+ * The twin's LOCALLY-MINTED id namespace (`file-api-twin000000000001` — see `nextFileId` in
+ * deepseek-twin.ts). A subject still bearing one has no counterpart in the real account. The
+ * pattern is anchored on the `twin` infix a real DeepSeek id (`file-api-<16 chars>`) cannot
+ * produce for a local mint, so a PULLED vendor id is never mistaken for one.
+ */
+const LOCAL_ID = /^file-api-twin\d{12}$/;
+
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * A locally-minted subject has no counterpart in the real account, so the vendor path can never be
+ * built from `action.subject.id`. A create's real id is written into the resource as
+ * `_external_id` at confirm time, and every later delete addresses the vendor by THAT — otherwise
+ * a local `file.delete` would issue `DELETE /files/file-api-twin000000000001` against the REAL
+ * account for a file this connector explicitly refused to create there (the exact class of defect
+ * the exemplar's own §9 round two caught: a fix that made the rest of the push sweep reachable also
+ * made the twin's own minted ids reachable as live vendor paths).
+ *
+ * Now a create's real id is written into the resource as `_external_id` at confirm time, and every
+ * later delete/cancel addresses the vendor by THAT. A locally-minted subject with no recorded
+ * external id is refused rather than guessed at.
+ */
+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 row = projectResources(SERVICE, root).find((r) => r.type === subjectType && r.id === subjectId);
+  const ext = row?._external_id;
+  return typeof ext === 'string' && ext ? ext : null;
+}
+
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real DeepSeek REST surface:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export function deepseekRequestForAction(
+  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(`deepseek 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(`deepseek 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 === '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 DeepSeek 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 pushDeepSeekAction(
+  execute: DeepSeekExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+  opts: { externalId?: string } = {},
+): Promise<{ externalId: string }> {
+  assertPushable(action.operation ?? `${action.subject.type}.update`);
+  const { method, path } = deepseekRequestForAction(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 };
+}
+
+/**
+ * The JSON body a create push sends. Every create this pack can record is a `file.create`, and that
+ * one is in UNPUSHABLE — so this function is only ever reached if a new pushable create type is
+ * added later, and it deliberately returns an EMPTY body rather than inventing one for a shape it
+ * has never seen.
+ */
+function createPayload(_action: Pick<TwinAction, 'subject' | 'fields'>): Record<string, unknown> {
+  return {};
+}
+
+/**
+ * Push the twin's PENDING local actions to real DeepSeek and CONFIRM each. Idempotency: a confirmed
+ * action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * Every action this pack records is SINGLE-RESOURCE (one file, one cache prefix), 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 pushPendingDeepSeekActions(
+  execute: DeepSeekExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string>; refused: Array<{ actionId: string; operation: string; reason: string }>; skippedInternal: string[] }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  const refused: Array<{ actionId: string; operation: string; reason: string }> = [];
+  const skippedInternal: string[] = [];
+  for (const action of pendingActions(SERVICE, opts.root)) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    // Twin-internal bookkeeping (the context-cache ledger) is not a vendor write and is skipped by
+    // NAME — reported, never silently dropped, and never mixed into `refused` where the real gaps live.
+    if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) { skippedInternal.push(action.id); continue; }
+    // An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed
+    // and never silently dropped: it stays pending, and it is named in `refused` so a caller can
+    // see it. Throwing instead (the first cut) 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 (§9 round one, finding 5).
+    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 (§9 round two, blocker).
+    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 pushDeepSeekAction(execute, action, ...(external !== undefined ? [{ externalId: external }] as const : [] as const));
+    // Record the id the vendor issued ON the resource, so a later delete/cancel can address it.
+    confirmAction({
+      service: SERVICE, actionId: action.id, subject: action.subject,
+      fields: { ...(action.fields ?? {}), ...(verb === 'create' ? { _external_id: externalId } : {}) },
+      occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(action.id);
+    externalIds[action.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds, refused, skippedInternal };
+}
+
+// ── FULL bi-directional sync ─────────────────────────────────────────────────
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * DeepSeek and confirm it, then (2) PULL all modeled collections back and fold them into the event
+ * log. Pushing first means the pull observes the twin's own writes as confirmed external state (no
+ * double-count). Re-running with no pending writes and identical real state is a no-op.
+ */
+export async function fullSyncDeepSeek(
+  execute: DeepSeekExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; observed: number; deltasAppended: number; collections: number; refused: Array<{ actionId: string; operation: string; reason: string }>; skippedInternal: string[] }> {
+  const push = await pushPendingDeepSeekActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  const resources = await pullDeepSeekState(execute);
+  const pull = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.deltasAppended, collections: COLLECTIONS.length + SINGLETONS.length, refused: push.refused, skippedInternal: push.skippedInternal };
+}

package/src/deepseek-models.ts

@@ -0,0 +1,65 @@
+// DeepSeek model catalog — the static `GET /models` surface.
+//
+// PROVENANCE (what is sourced, and what is deliberately ABSENT):
+//   • the three ids are the ones DeepSeek's own docs list as the current models
+//     (api-docs.deepseek.com "Your First API Call" + /quick_start/pricing, read 2026-08-31) and are
+//     the exact strings `@ai-sdk/deepseek@3.0.37` gives first-class suggestions for
+//     (`DeepSeekChatModelId`, src/chat/deepseek-chat-language-model-options.ts);
+//   • a row is `{id, object, owned_by}` and NOTHING else — that is the whole object in DeepSeek's
+//     own `GET /models` example response (api-docs.deepseek.com/api/list-models). OpenAI's row also
+//     carries `created`; DeepSeek's does not, so this twin does not invent one. `DeepSeekModel` in
+//     deepseek-types.ts has exactly those three keys, so an added field would not typecheck.
+//   • `deepseek-chat` and `deepseek-reasoner` are NOT here. `@ai-sdk/deepseek`'s own docs page
+//     (docs/30-deepseek.mdx, shipped inside the npm tarball) states: "DeepSeek retired the
+//     `deepseek-chat` and `deepseek-reasoner` aliases on July 24, 2026." A catalog that still
+//     served them would be surface the vendor no longer has.
+//
+// This is a STATIC surface (the registry does not change at runtime), so it is a plain data table
+// rather than kernel state — listing models is a pure read. A connector pull can still OBSERVE an
+// account's rows and those override/extend this table (deepseek-twin.ts `servedModels`).
+import type { DeepSeekModel } from './deepseek-types.ts';
+
+const model = (id: string): DeepSeekModel => ({ id, object: 'model', owned_by: 'deepseek' });
+
+/** The catalog DeepSeek publishes. */
+export const DEEPSEEK_MODELS: DeepSeekModel[] = [
+  model('deepseek-v4-flash'),
+  model('deepseek-v4-pro'),
+  model('deepseek-v4-flash-vision-exp'),
+];
+
+/** Resolve a model object by id, or undefined if DeepSeek does not publish it. */
+export function findModel(id: string): DeepSeekModel | undefined {
+  return DEEPSEEK_MODELS.find((m) => m.id === id);
+}
+
+/**
+ * The ids DeepSeek retired on 2026-07-24 (`@ai-sdk/deepseek` docs/30-deepseek.mdx). They are kept
+ * here ONLY so the twin can refuse them by name with an accurate message — never to serve them.
+ */
+export const RETIRED_MODEL_IDS = new Set(['deepseek-chat', 'deepseek-reasoner']);
+
+/**
+ * The one model DeepSeek's beta FIM endpoint accepts. "Only value: `deepseek-v4-pro`"
+ * (api-docs.deepseek.com/api/create-completion, read 2026-08-31) — a closed set of one, so any
+ * other id is a checkable rejection rather than a stub.
+ */
+export const FIM_MODELS = new Set(['deepseek-v4-pro']);
+
+/**
+ * The models that accept image inputs. DeepSeek's own model-capability table marks image input on
+ * `deepseek-v4-flash-vision-exp` ONLY (`@ai-sdk/deepseek` docs/30-deepseek.mdx "Model
+ * Capabilities"), and the Files API guide says uploaded files "work with
+ * `deepseek-v4-flash-vision-exp`".
+ */
+export const VISION_MODELS = new Set(['deepseek-v4-flash-vision-exp']);
+
+/**
+ * Every model in the catalog is a DeepSeek V4 model, and `@ai-sdk/deepseek` keys its thinking
+ * behaviour on the id containing `deepseek-v4` (src/chat/deepseek-chat-language-model.ts:
+ * `this.modelId.includes('deepseek-v4')`). The twin uses the SAME predicate so its thinking rules
+ * and the SDK's request shaping can never disagree about which turn is a thinking turn.
+ */
+export function isThinkingModel(id: string): boolean {
+  return id.includes('deepseek-v4');
+}