@bendyline/gezel-inference 1.0.3 → 1.0.4

package/dist/models/image-fit.d.ts

@@ -0,0 +1,83 @@
+/**
+ * "Can this machine run that image model?" for the image catalog.
+ *
+ * Prices each catalog entry from the weight facts its gilde entry pins (core
+ * `media-memory.ts`) — never the network — and checks it against the same
+ * static ceilings the device ledger refuses at, so `wont-run` here means the
+ * launch path would refuse the model on this machine whatever else is
+ * running. The download pages hide those models and the pull routes refuse
+ * them. Contract: docs/media-model-memory.md.
+ *
+ * The video half lives with the video engine in the service, which shares
+ * the helpers here.
+ */
+import { type GezelConfig, type ImageModelManifest, type ImageQuality, type MediaCapacity, type MediaFitAssessment, type MediaMemoryPool, type MediaMemoryRequirement, type MediaModelFit, type MediaModelFitResponse, type MediaWeightFile } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { CapacityBudgetKind } from '../providers/native/capacity-budget.js';
+export interface MediaFitContext {
+    catalog: CatalogService;
+    readConfig: () => Promise<Pick<GezelConfig, 'localEngineMemoryGb'>>;
+}
+/**
+ * The 409 body a pull route answers with when the model cannot run here, or
+ * null to let the pull start. A failure to assess never blocks a download:
+ * the launch path still applies the same check.
+ */
+export declare function wontRunRefusal(assess: () => Promise<MediaFitAssessment | null>): Promise<{
+    error: string;
+    code: string;
+} | null>;
+/**
+ * Where sd-server keeps weights: Metal on Apple Silicon, CPU on Intel Macs,
+ * CUDA or Vulkan elsewhere, falling back to the processor when no GPU
+ * answers. Windows on Arm runs on the processor unless discovery picked its
+ * CUDA build, which only an RTX Spark gets.
+ */
+export declare function imageMediaPool(kind: CapacityBudgetKind, host?: {
+    platform: NodeJS.Platform;
+    arch: string;
+    sdServerBin?: string | undefined;
+}): MediaMemoryPool;
+/** The ceilings the device ledger applies on this machine, automatic and under the person's limit. */
+export declare function mediaCapacity(pool: MediaMemoryPool, readConfig: MediaFitContext['readConfig']): Promise<MediaCapacity>;
+/** The memory sd-server needs for one model, from its weight files and its launch profile. */
+export declare function sdServerRequirement(input: {
+    modelId: string;
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    files: readonly MediaWeightFile[];
+    pool: MediaMemoryPool;
+    /** The render size to price; the model's default size when absent. */
+    megapixels?: number;
+}): MediaMemoryRequirement;
+/**
+ * What a launched sd-server claims on the device ledger.
+ *
+ * On a discrete card the fit figures charge graphics memory for weights only,
+ * because sd-server can stream components from RAM, and the download page
+ * must not call a model that offloads "won't run". A running render holds its
+ * compute buffers on the card too, though: FLUX.2 Klein at 1024px held
+ * 9.4 GiB of a 12 GiB card's dedicated memory against 4.9 GiB of weights
+ * (RTX 5070 Ti Laptop, Vulkan, M0 spike 2026-10-25). Claiming weights only
+ * let a resident chat model keep its memory, and the render then failed at
+ * its first step. The claim is the estimated peak, capped at the card so a
+ * model that must offload is admitted once the card is otherwise free.
+ */
+export declare function sdServerLedgerClaim(requirement: MediaMemoryRequirement, cardBytes: number): {
+    bytes: number;
+    gpuBytes: number;
+};
+/** Megapixels a model renders at a quality tier, inside its range. */
+export declare function imageRenderMegapixels(manifest: Pick<ImageModelManifest, 'id' | 'widthRange' | 'heightRange'>, quality: ImageQuality): number;
+export interface FitPlan {
+    pool: MediaMemoryPool;
+    capacity: MediaCapacity;
+}
+export declare function mediaFitResponse(plan: FitPlan, models: MediaModelFit[]): MediaModelFitResponse;
+/**
+ * Every catalog image model's fit. With `quality`, each is priced at the size
+ * it renders at that tier rather than its default, which is how the direct
+ * image gezel's settings know whether High will fit.
+ */
+export declare function imageCatalogFits(ctx: MediaFitContext, quality?: ImageQuality): Promise<MediaModelFitResponse>;
+/** One catalog image model's fit, or null when the id is not in the catalog. */
+export declare function imageModelFit(ctx: MediaFitContext, id: string): Promise<MediaFitAssessment | null>;

package/dist/models/image-fit.js

@@ -0,0 +1,163 @@
+/**
+ * "Can this machine run that image model?" for the image catalog.
+ *
+ * Prices each catalog entry from the weight facts its gilde entry pins (core
+ * `media-memory.ts`) — never the network — and checks it against the same
+ * static ceilings the device ledger refuses at, so `wont-run` here means the
+ * launch path would refuse the model on this machine whatever else is
+ * running. The download pages hide those models and the pull routes refuse
+ * them. Contract: docs/media-model-memory.md.
+ *
+ * The video half lives with the video engine in the service, which shares
+ * the helpers here.
+ */
+import { totalmem } from 'node:os';
+import { MEDIA_MODEL_WONT_RUN_CODE, assessMediaFit, createLogger, imageMemoryRequirement, imageModelDefaultSide, resolveImageSize, } from '@bendyline/gezel';
+import { isCudaArchivePath } from '@bendyline/gezel/native';
+import { sdServerLoadProfile } from '../providers/image/sd-cpp.js';
+import { configuredEngineMemoryBytes, staticCapacityCeilings, } from '../providers/native/device-capacity.js';
+import { measuredCapacityBudget } from '../providers/native/measured-budget.js';
+import { detectMemoryProfileCached } from '../system/memory.js';
+import { imageCatalogWeightFiles, sdCppMainComponent } from './weight-facts.js';
+const log = createLogger('media-fit');
+/**
+ * The 409 body a pull route answers with when the model cannot run here, or
+ * null to let the pull start. A failure to assess never blocks a download:
+ * the launch path still applies the same check.
+ */
+export async function wontRunRefusal(assess) {
+    try {
+        const fit = await assess();
+        if (fit?.verdict !== 'wont-run')
+            return null;
+        return {
+            error: `This model is too large for this machine. ${fit.reason}`,
+            code: MEDIA_MODEL_WONT_RUN_CODE,
+        };
+    }
+    catch (error) {
+        log.warn(`[media-fit] could not assess a pull, letting it start: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Where sd-server keeps weights: Metal on Apple Silicon, CPU on Intel Macs,
+ * CUDA or Vulkan elsewhere, falling back to the processor when no GPU
+ * answers. Windows on Arm runs on the processor unless discovery picked its
+ * CUDA build, which only an RTX Spark gets.
+ */
+export function imageMediaPool(kind, host = {
+    platform: process.platform,
+    arch: process.arch,
+    sdServerBin: process.env.GEZEL_SD_SERVER_BIN,
+}) {
+    if (host.platform === 'darwin')
+        return host.arch === 'arm64' ? 'unified' : 'cpu';
+    if (host.platform === 'win32' &&
+        host.arch === 'arm64' &&
+        !(host.sdServerBin && isCudaArchivePath(host.sdServerBin))) {
+        return 'cpu';
+    }
+    return kind === 'discrete-gpu' ? 'discrete' : kind === 'unified' ? 'unified' : 'cpu';
+}
+/** The ceilings the device ledger applies on this machine, automatic and under the person's limit. */
+export async function mediaCapacity(pool, readConfig) {
+    const budget = await measuredCapacityBudget();
+    const ram = totalmem();
+    const auto = staticCapacityCeilings(budget, ram);
+    const configured = configuredEngineMemoryBytes(await readConfig().catch(() => ({})));
+    const limited = configured === undefined ? undefined : staticCapacityCeilings(budget, ram, configured);
+    const profile = pool === 'discrete' ? await detectMemoryProfileCached().catch(() => null) : null;
+    return {
+        pool,
+        ...auto,
+        ...(limited && limited.budgetBytes < auto.budgetBytes ? { limit: limited } : {}),
+        totalRamBytes: ram,
+        ...(profile?.gpuLargestDeviceBytes ? { gpuDeviceBytes: profile.gpuLargestDeviceBytes } : {}),
+    };
+}
+/** The memory sd-server needs for one model, from its weight files and its launch profile. */
+export function sdServerRequirement(input) {
+    const profile = sdServerLoadProfile(input.modelId);
+    return imageMemoryRequirement({
+        files: input.files,
+        pool: input.pool,
+        vaeDecode: profile.vaeDecode,
+        // The rule names the diffusion weights, which are the main file.
+        bf16Components: profile.bf16TensorPattern ? [sdCppMainComponent(input.weightsKind)] : [],
+        megapixels: input.megapixels ?? profile.defaultSidePx ** 2 / 1024 ** 2,
+    });
+}
+/**
+ * What a launched sd-server claims on the device ledger.
+ *
+ * On a discrete card the fit figures charge graphics memory for weights only,
+ * because sd-server can stream components from RAM, and the download page
+ * must not call a model that offloads "won't run". A running render holds its
+ * compute buffers on the card too, though: FLUX.2 Klein at 1024px held
+ * 9.4 GiB of a 12 GiB card's dedicated memory against 4.9 GiB of weights
+ * (RTX 5070 Ti Laptop, Vulkan, M0 spike 2026-10-25). Claiming weights only
+ * let a resident chat model keep its memory, and the render then failed at
+ * its first step. The claim is the estimated peak, capped at the card so a
+ * model that must offload is admitted once the card is otherwise free.
+ */
+export function sdServerLedgerClaim(requirement, cardBytes) {
+    if (requirement.pool !== 'discrete') {
+        return { bytes: requirement.bytes, gpuBytes: requirement.gpuBytes };
+    }
+    const gpuBytes = Math.min(Math.max(requirement.gpuPeakBytes, requirement.gpuBytes), cardBytes);
+    return { bytes: Math.max(requirement.bytes, gpuBytes), gpuBytes };
+}
+/** Megapixels a model renders at a quality tier, inside its range. */
+export function imageRenderMegapixels(manifest, quality) {
+    const { width, height } = resolveImageSize({ quality }, {
+        defaultSidePx: imageModelDefaultSide(manifest.id),
+        widthRange: manifest.widthRange,
+        heightRange: manifest.heightRange,
+    });
+    return (width * height) / 1024 ** 2;
+}
+async function imagePlan(ctx) {
+    const budget = await measuredCapacityBudget();
+    const pool = imageMediaPool(budget.kind);
+    return { pool, capacity: await mediaCapacity(pool, ctx.readConfig) };
+}
+function assessImageManifest(plan, manifest, quality) {
+    return assessMediaFit(sdServerRequirement({
+        modelId: manifest.id,
+        weightsKind: manifest.weightsKind,
+        files: imageCatalogWeightFiles(manifest),
+        pool: plan.pool,
+        ...(quality ? { megapixels: imageRenderMegapixels(manifest, quality) } : {}),
+    }), plan.capacity);
+}
+export function mediaFitResponse(plan, models) {
+    return {
+        pool: plan.pool,
+        budgetBytes: plan.capacity.budgetBytes,
+        gpuBudgetBytes: plan.capacity.gpuBudgetBytes,
+        totalRamBytes: plan.capacity.totalRamBytes,
+        models,
+    };
+}
+/**
+ * Every catalog image model's fit. With `quality`, each is priced at the size
+ * it renders at that tier rather than its default, which is how the direct
+ * image gezel's settings know whether High will fit.
+ */
+export async function imageCatalogFits(ctx, quality) {
+    const plan = await imagePlan(ctx);
+    const items = await ctx.catalog.list('image-model');
+    const models = items
+        .map((item) => item.manifest)
+        .filter((m) => m.kind === 'image-model')
+        .map((m) => ({ id: m.id, ...assessImageManifest(plan, m, quality) }));
+    return mediaFitResponse(plan, models);
+}
+/** One catalog image model's fit, or null when the id is not in the catalog. */
+export async function imageModelFit(ctx, id) {
+    const item = await ctx.catalog.get('image-model', id);
+    if (!item || item.manifest.kind !== 'image-model')
+        return null;
+    return assessImageManifest(await imagePlan(ctx), item.manifest);
+}

package/dist/models/weight-facts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Weight facts for media-model memory pricing: each weight file's size and
+ * how many elements it stores at every precision. Core `media-memory.ts`
+ * turns them into a requirement.
+ *
+ * Two sources that must agree. A catalog entry carries the facts as
+ * `tensors` beside each file's sha256, written by gilde's `pin-weight-tensors`
+ * tool when the model was authored; the launch path reads the same facts
+ * from the header of the file on disk. Files are pinned by sha256, so both
+ * describe the same bytes. Nothing here touches the network: an entry
+ * without the facts is priced by its plausible range instead.
+ */
+import { type ImageModelManifest, type MediaWeightFile, type VideoModelManifest, type WeightTensors } from '@bendyline/gezel';
+/** Length of the JSON header from a safetensors file's first 8 bytes, or null when implausible. */
+export declare function safetensorsHeaderLength(prefix: Uint8Array, fileBytes: number): number | null;
+/** The `tensors` facts of a safetensors file on disk; undefined when it cannot be read as one. */
+export declare function readLocalWeightTensors(path: string): Promise<WeightTensors | undefined>;
+export declare function videoCatalogWeightFiles(manifest: VideoModelManifest): MediaWeightFile[];
+/**
+ * The weight files of an installed diffusers tree, headers read from disk.
+ * diffusers loads only the shards a directory's index names, so an unsharded
+ * duplicate beside them is never resident and is left out.
+ */
+export declare function localDiffusersWeightFiles(modelDir: string): Promise<MediaWeightFile[]>;
+/** The sd-cpp component the main weights load as: the flag they ride on. */
+export declare function sdCppMainComponent(weightsKind: 'checkpoint' | 'diffusion-model'): string;
+export declare function imageCatalogWeightFiles(manifest: ImageModelManifest): MediaWeightFile[];
+/** The weight files of an installed sd-cpp model, headers read from disk. */
+export declare function localSdCppWeightFiles(model: {
+    weightsPath: string;
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    auxiliaryFiles: ReadonlyArray<{
+        role: string;
+        path: string;
+    }>;
+}): Promise<MediaWeightFile[]>;

package/dist/models/weight-facts.js

@@ -0,0 +1,171 @@
+/**
+ * Weight facts for media-model memory pricing: each weight file's size and
+ * how many elements it stores at every precision. Core `media-memory.ts`
+ * turns them into a requirement.
+ *
+ * Two sources that must agree. A catalog entry carries the facts as
+ * `tensors` beside each file's sha256, written by gilde's `pin-weight-tensors`
+ * tool when the model was authored; the launch path reads the same facts
+ * from the header of the file on disk. Files are pinned by sha256, so both
+ * describe the same bytes. Nothing here touches the network: an entry
+ * without the facts is priced by its plausible range instead.
+ */
+import { open, readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tallySafetensorsHeader, weightFileFormat, } from '@bendyline/gezel';
+/** A header larger than this is not a safetensors header. */
+const MAX_HEADER_BYTES = 100 * 1024 * 1024;
+/** Length of the JSON header from a safetensors file's first 8 bytes, or null when implausible. */
+export function safetensorsHeaderLength(prefix, fileBytes) {
+    if (prefix.byteLength < 8)
+        return null;
+    const view = new DataView(prefix.buffer, prefix.byteOffset, 8);
+    const length = Number(view.getBigUint64(0, true));
+    if (!Number.isSafeInteger(length) || length <= 0 || length > MAX_HEADER_BYTES)
+        return null;
+    if (length + 8 > fileBytes)
+        return null;
+    return length;
+}
+/** The `tensors` facts of a safetensors file on disk; undefined when it cannot be read as one. */
+export async function readLocalWeightTensors(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const size = (await handle.stat()).size;
+        const prefix = Buffer.alloc(8);
+        const { bytesRead } = await handle.read(prefix, 0, 8, 0);
+        const length = safetensorsHeaderLength(prefix.subarray(0, bytesRead), size);
+        if (length === null)
+            return undefined;
+        const header = Buffer.alloc(length);
+        await handle.read(header, 0, length, 8);
+        return tallySafetensorsHeader(JSON.parse(header.toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function catalogFile(component, fileName, sizeBytes, tensors) {
+    const format = weightFileFormat(fileName);
+    if (!format)
+        return null;
+    return { component, sizeBytes, format, ...(tensors ? { tensors } : {}) };
+}
+// ─ Video: diffusers trees ───────────────────────────────────────────
+/** The diffusers component a repo-relative file belongs to: its top-level folder. */
+function diffusersComponent(name) {
+    const slash = name.indexOf('/');
+    return slash < 0 ? '' : name.slice(0, slash);
+}
+export function videoCatalogWeightFiles(manifest) {
+    return manifest.source.files.flatMap((file) => {
+        const priced = catalogFile(diffusersComponent(file.name), file.name, file.sizeBytes, file.tensors);
+        return priced ? [priced] : [];
+    });
+}
+/**
+ * The weight files of an installed diffusers tree, headers read from disk.
+ * diffusers loads only the shards a directory's index names, so an unsharded
+ * duplicate beside them is never resident and is left out.
+ */
+export async function localDiffusersWeightFiles(modelDir) {
+    const out = [];
+    const walk = async (dir, component, depth) => {
+        if (depth > 6)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true });
+        const indexed = await indexedShards(dir, entries.map((e) => e.name));
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(path, component || entry.name, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const format = weightFileFormat(entry.name);
+            if (!format)
+                continue;
+            if (format === 'safetensors' && indexed && !indexed.has(entry.name))
+                continue;
+            const sizeBytes = (await stat(path)).size;
+            const tensors = format === 'safetensors' ? await readLocalWeightTensors(path) : undefined;
+            out.push({ component, sizeBytes, format, ...(tensors ? { tensors } : {}) });
+        }
+    };
+    await walk(modelDir, '', 0);
+    return out;
+}
+async function indexedShards(dir, names) {
+    const index = names.find((n) => n.endsWith('.safetensors.index.json'));
+    if (!index)
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(join(dir, index), 'utf8'));
+        const shards = new Set(Object.values(parsed.weight_map ?? {}));
+        return shards.size > 0 ? shards : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─ Image: stable-diffusion.cpp files ────────────────────────────────
+/** The sd-cpp component the main weights load as: the flag they ride on. */
+export function sdCppMainComponent(weightsKind) {
+    return weightsKind === 'diffusion-model' ? 'diffusion_model' : 'model';
+}
+function urlFileName(url) {
+    try {
+        return decodeURIComponent(new URL(url).pathname.split('/').pop() ?? '');
+    }
+    catch {
+        return '';
+    }
+}
+export function imageCatalogWeightFiles(manifest) {
+    const entries = [
+        {
+            component: sdCppMainComponent(manifest.weightsKind),
+            url: manifest.downloadUrl,
+            sizeBytes: manifest.approxSizeBytes,
+            tensors: manifest.tensors,
+        },
+        ...manifest.auxiliaryFiles.map((aux) => ({
+            component: aux.role,
+            url: aux.downloadUrl,
+            sizeBytes: aux.approxSizeBytes,
+            tensors: aux.tensors,
+        })),
+    ];
+    return entries.flatMap((e) => {
+        const priced = catalogFile(e.component, urlFileName(e.url), e.sizeBytes, e.tensors);
+        return priced ? [priced] : [];
+    });
+}
+/** The weight files of an installed sd-cpp model, headers read from disk. */
+export async function localSdCppWeightFiles(model) {
+    const entries = [
+        { component: sdCppMainComponent(model.weightsKind), path: model.weightsPath },
+        ...model.auxiliaryFiles.map((a) => ({ component: a.role, path: a.path })),
+    ];
+    const out = [];
+    for (const entry of entries) {
+        const format = weightFileFormat(entry.path);
+        if (!format)
+            continue;
+        let sizeBytes;
+        try {
+            sizeBytes = (await stat(entry.path)).size;
+        }
+        catch {
+            continue;
+        }
+        const tensors = format === 'safetensors' ? await readLocalWeightTensors(entry.path) : undefined;
+        out.push({ component: entry.component, sizeBytes, format, ...(tensors ? { tensors } : {}) });
+    }
+    return out;
+}

package/dist/providers/ds4/build-provider.js

@@ -7,7 +7,7 @@ import { pickFreePort } from '../native/port.js';
 import { NativeEngineSupervisor } from '../native/supervisor.js';
 import { patientFetch } from '../patient-fetch.js';
 import { nativeVisionEnabledFor } from '../vision-capability.js';
-import { ds4DsparkArgs, resolveDs4Dspark } from './dspark.js';
+import { DS4_V41_DRAFTER_RUNTIME_BYTES, ds4DsparkArgs, ds4DsparkStreamsWithSsd, resolveDs4Dspark, } from './dspark.js';
 import { ds4MtpArgs, resolveDs4Mtp } from './mtp.js';
 import { Ds4Provider } from './provider.js';
 const log = createLogger('chat');
@@ -307,36 +307,50 @@ export async function buildDs4Provider(opts) {
     if (config.ds4SsdStreaming === true && ds4Source?.ssdStreamingSupported === false) {
         log.warn(`[ds4] ignored SSD-streaming override for ${effectiveModelId ?? modelPath}; this model keeps its lookup tables on disk but does not implement routed-expert streaming`);
     }
+    const cachePlanWith = (extraResidentBytes) => planDs4ExpertCache({
+        configuredGb: config.ds4CacheExpertsGb,
+        catalogCacheBytes: ds4Source?.cacheExpertsBytes,
+        catalogResidentBytes: (ds4Source?.residentBytes ?? 0) + visionResidentBytes + extraResidentBytes,
+        totalRamBytes: totalRamGb * 1024 ** 3,
+    });
     // DSpark speculative decoding. Resolved here, beside the residency decision
-    // it depends on: ds4 aborts at startup if an external `--mtp-model` is combined with
-    // `--ssd-streaming`, so this can only ever draft on a fully resident launch.
+    // it depends on: ds4 aborts at startup if an external `--mtp-model` is
+    // combined with `--ssd-streaming` for any family but DeepSeek V4.1.
+    const targetArchitecture = installedModel?.architecture;
+    const streamedDrafting = ssdStreaming && ds4DsparkStreamsWithSsd(targetArchitecture);
     const dsparkSupportPath = config.ds4DsparkModelPath ?? installedModel?.draftModelPath;
     // Residency is decided on the weights alone, then the companion is priced
     // against what is left. That precedence is deliberate and not symmetric:
     // residency is worth ~9.5x and drafting ~1.05x, so a companion that would
     // push the model out of memory loses its own flag rather than costing the
-    // launch its residency.
+    // launch its residency. A streamed V4.1 launch keeps its drafter resident
+    // too, so it must still leave room for a minimum expert cache.
     let companionFitsMemory = true;
     let dsparkCompanionBytes = 0;
-    if (dsparkSupportPath && !ssdStreaming) {
+    if (dsparkSupportPath && (!ssdStreaming || streamedDrafting)) {
         const { canUseDs4FullResidency } = await import('./residency.js');
         const { stat: statCompanion } = await import('node:fs/promises');
         const companionBytes = await statCompanion(dsparkSupportPath)
             .then((st) => st.size)
             .catch(() => undefined);
-        dsparkCompanionBytes = companionBytes ?? 0;
-        companionFitsMemory = canUseDs4FullResidency({
-            modelSizeBytes: residentWeightBytes,
-            totalRamBytes,
-            ...(companionBytes !== undefined || visionResidentBytes > 0
-                ? { companionBytes: (companionBytes ?? 0) + visionResidentBytes }
-                : {}),
-        });
+        dsparkCompanionBytes =
+            (companionBytes ?? 0) +
+                (ds4DsparkStreamsWithSsd(targetArchitecture) ? DS4_V41_DRAFTER_RUNTIME_BYTES : 0);
+        companionFitsMemory = ssdStreaming
+            ? cachePlanWith(dsparkCompanionBytes).safe
+            : canUseDs4FullResidency({
+                modelSizeBytes: residentWeightBytes,
+                totalRamBytes,
+                ...(companionBytes !== undefined || visionResidentBytes > 0
+                    ? { companionBytes: dsparkCompanionBytes + visionResidentBytes }
+                    : {}),
+            });
     }
     const dspark = resolveDs4Dspark({
         mode: config.ds4Dspark,
         backend: backendFlag.slice(2),
         ssdStreaming,
+        ...(targetArchitecture ? { targetArchitecture } : {}),
         companionFitsMemory,
         ...(dsparkSupportPath ? { supportModelPath: dsparkSupportPath } : {}),
     });
@@ -365,14 +379,7 @@ export async function buildDs4Provider(opts) {
     });
     if (mtp.unmetRequest)
         log.warn(`[ds4] ${mtp.unmetRequest}`);
-    const cachePlan = planDs4ExpertCache({
-        configuredGb: config.ds4CacheExpertsGb,
-        catalogCacheBytes: ds4Source?.cacheExpertsBytes,
-        catalogResidentBytes: ds4Source?.residentBytes !== undefined || visionResidentBytes > 0
-            ? (ds4Source?.residentBytes ?? 0) + visionResidentBytes
-            : undefined,
-        totalRamBytes: totalRamGb * 1024 ** 3,
-    });
+    const cachePlan = cachePlanWith(dspark.enabled && ssdStreaming ? dsparkCompanionBytes : 0);
     if (ssdStreaming && !cachePlan.safe) {
         const err = new Error(`DwarfStar (ds4) engine: ${effectiveModelId ?? 'the selected model'} cannot keep a safe minimum expert cache while preserving memory for the operating system. Choose a lighter model in Settings → DwarfStar (ds4).`);
         err.isActionable = true;

package/dist/providers/ds4/dspark.d.ts

@@ -6,9 +6,12 @@
  * one measurement shape the policy here:
  *
  *  - **The engine refuses an external MTP model alongside `--ssd-streaming`**,
- *    aborting at startup. Streaming
- *    is gezel's safe default and the only way the 153 GiB Q4 GGUF runs at all
- *    on a 128 GiB machine, so drafting is unreachable for most installs.
+ *    aborting at startup, for every family except DeepSeek V4.1
+ *    (`general.architecture` `deepseek41`, upstream ee7e840). Streaming is the
+ *    only way the 153 GiB Q4 GGUF runs at all on a 128 GiB machine, so
+ *    drafting is unreachable there. V4.1 keeps its 8.04 GiB drafter resident
+ *    while the target's experts stream, but upstream warns it can still be
+ *    slower than plain decoding, so `auto` never drafts a streamed launch.
  *  - **A support model is required.** Without one there is nothing to draft
  *    with, and ds4 exits on `--dspark` alone ("--dspark requires --mtp-model FILE").
  *  - **It does not pay on Metal.** Measured 2026-08-26, M5 Max, DeepSeek V4
@@ -25,6 +28,18 @@
  */
 /** Which acceleration backend ds4 was launched with. */
 export type Ds4Backend = 'metal' | 'cuda';
+/**
+ * Whether ds4 accepts `--mtp-model` alongside `--ssd-streaming` for a target
+ * with this GGUF `general.architecture`. Mirrors the engine's own check
+ * (`DS4_MODEL_FAMILY != DS4_MODEL_FAMILY_DEEPSEEK41` in `ds4_engine_open`);
+ * an unknown architecture is treated as unsupported because the engine aborts.
+ */
+export declare function ds4DsparkStreamsWithSsd(architecture: string | undefined): boolean;
+/**
+ * Buffers ds4 allocates beside a V4.1 drafter's weights; its startup memory
+ * plan charges `mtp_model.size + 64 MiB` for them.
+ */
+export declare const DS4_V41_DRAFTER_RUNTIME_BYTES: number;
 export type Ds4DsparkMode = 'off' | 'on' | 'auto';
 export interface Ds4DsparkOptions {
     /** `config.ds4Dspark`. Absent → `auto`. */
@@ -33,12 +48,15 @@ export interface Ds4DsparkOptions {
     backend: Ds4Backend;
     /** Whether this launch streams experts from SSD. */
     ssdStreaming: boolean;
+    /** The target GGUF's `general.architecture`, when known. */
+    targetArchitecture?: string;
     /** Absolute path to a DSpark support GGUF, if one resolved. */
     supportModelPath?: string;
     /**
-     * Whether the companion still fits once the resident weights are accounted
+     * Whether the companion still fits once the resident weights (or, when
+     * streaming, the resident set plus a minimum expert cache) are accounted
      * for. Defaults to true so callers that cannot weigh it keep the old
-     * behavior. When false the launch keeps its residency and drops drafting —
+     * behavior. When false the launch keeps its memory plan and drops drafting —
      * residency is worth ~9.5x and drafting ~1.05x, so the flag is what yields.
      */
     companionFitsMemory?: boolean;