@volter/twin-deepseek 0.1.0

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

@@ -0,0 +1,168 @@
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { DeepSeekBudget, type DeepSeekBudgetOptions } from './deepseek-budget.js';
+/**
+ * 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;
+};
+/**
+ * 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 declare function liveDeepSeekExecute(apiKey: string, base?: string, opts?: LiveDeepSeekOptions): DeepSeekExecute;
+/**
+ * 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 declare function mapModel(m: Record<string, unknown>): SyncResource;
+/** Map a real-DeepSeek File object → a twin sync resource. */
+export declare function mapFile(f: Record<string, unknown>): SyncResource;
+/**
+ * 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 declare function mapBalance(b: Record<string, unknown>): SyncResource;
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export declare function pullDeepSeekState(execute: DeepSeekExecute): Promise<SyncResource[]>;
+/**
+ * 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 declare function syncDeepSeekFromReal(execute: DeepSeekExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export declare function unpushableReason(op: string): string | null;
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * 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 declare function externalIdFor(subjectType: string, subjectId: string, root?: string): string | 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 declare 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;
+};
+/**
+ * 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 declare function pushDeepSeekAction(execute: DeepSeekExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, opts?: {
+    externalId?: string;
+}): Promise<{
+    externalId: string;
+}>;
+/**
+ * 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 declare 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[];
+}>;
+/**
+ * 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 declare 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[];
+}>;

package/dist/src/deepseek-connector.js

@@ -0,0 +1,386 @@
+// 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 { DeepSeekBudget, DeepSeekBudgetError, deepseekCallWeight } from "./deepseek-budget.js";
+const SERVICE = 'deepseek';
+/**
+ * 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 = [
+    /^\/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, base = 'https://api.deepseek.com', opts = {}) {
+    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 = { authorization: `Bearer ${apiKey}` };
+        const init = { 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 = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const parsed = (await res.json());
+        // 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) {
+    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, ctx) {
+    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) {
+    return {
+        type: 'model',
+        id: String(m.id),
+        fields: { object: 'model', owned_by: m.owned_by ?? null },
+    };
+}
+/** Map a real-DeepSeek File object → a twin sync resource. */
+export function mapFile(f) {
+    return {
+        type: 'file',
+        id: String(f.id),
+        fields: {
+            object: 'file',
+            bytes: f.bytes ?? 0,
+            created_at: f.created_at ?? null,
+            filename: f.filename ?? null,
+            purpose: f.purpose ?? 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 } : {}),
+        },
+    };
+}
+/**
+ * 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) {
+    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 = [
+    { path: '/models', map: mapModel },
+    { path: '/files', map: mapFile },
+];
+/** Singleton endpoints whose reply IS the object. */
+const SINGLETONS = [
+    { 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) {
+    const out = [];
+    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));
+    }
+    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, opts) {
+    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) {
+    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) {
+    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 = {
+    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 = {
+    '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, subjectId, root) {
+    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, 
+/** 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) {
+    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, action, opts = {}) {
+    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.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) {
+    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, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    const refused = [];
+    const skippedInternal = [];
+    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;
+        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 }] : []));
+        // 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, opts) {
+    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/dist/src/deepseek-models.d.ts

@@ -0,0 +1,30 @@
+import type { DeepSeekModel } from './deepseek-types.js';
+/** The catalog DeepSeek publishes. */
+export declare const DEEPSEEK_MODELS: DeepSeekModel[];
+/** Resolve a model object by id, or undefined if DeepSeek does not publish it. */
+export declare function findModel(id: string): DeepSeekModel | undefined;
+/**
+ * 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 declare const RETIRED_MODEL_IDS: Set<string>;
+/**
+ * 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 declare const FIM_MODELS: Set<string>;
+/**
+ * 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 declare const VISION_MODELS: Set<string>;
+/**
+ * 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 declare function isThinkingModel(id: string): boolean;

package/dist/src/deepseek-models.js

@@ -0,0 +1,38 @@
+const model = (id) => ({ id, object: 'model', owned_by: 'deepseek' });
+/** The catalog DeepSeek publishes. */
+export const DEEPSEEK_MODELS = [
+    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) {
+    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) {
+    return id.includes('deepseek-v4');
+}