@bendyline/gezel-inference 1.0.7 → 1.0.9

package/dist/knowledge/unified-search.js

@@ -0,0 +1,373 @@
+/**
+ * Explicit knowledge search across mounted catalogs: each catalog searched in
+ * its own embedding space, the lexical and vector arms fused by reciprocal
+ * rank. Platform-neutral — the daemon's KnowledgeManager and the on-device
+ * Capacitor host both run it over their own KnowledgeCatalogHost.
+ */
+import { formatKnowledgeUri, scoreResult, } from '@bendyline/gezel';
+import { spatialDocumentIdentity } from './spatial-query.js';
+/** Explicit-search shard budget (S) across every active catalog (§3.4). */
+const ROUTE_BUDGET_EXPLICIT = 6;
+/**
+ * Shards added beyond that budget for pages the query names by title (the
+ * catalog host's title-assisted routing): the centroids alone left the ABBA
+ * article unscanned for "Who were the members of ABBA?". Two, not one per
+ * catalog, so twenty mounted catalogs cannot add twenty scans.
+ */
+const TITLE_ROUTE_EXPLICIT = 2;
+const FINAL_K = 24;
+/**
+ * Explicit search fuses three arms per catalog by reciprocal rank (k = 60):
+ * the vector chunks (best chunk per document, by rerank cosine), the
+ * doc-title FTS hits, and the chunk-body FTS hits. Rank fusion instead of
+ * score comparison because the arms' scores are not commensurable — e5
+ * cosines sit in a narrow 0.7–0.9 band for everything, so a cosine-first
+ * ordering buried an exact title match under any vaguely related passage
+ * ("Who painted the Mona Lisa?" listed three other Mona Lisa copies above
+ * the article whose title the question names). Two lexical arms agreeing
+ * on a document now outrank one vector arm; a document every arm names
+ * comes first.
+ */
+const RRF_K = 60;
+const ARM_WEIGHTS = { vector: 1, docFts: 1, chunkFts: 0.5 };
+/**
+ * Media rows fuse per row, not per document: a document's own text chunk
+ * (cosine ≈ 0.9) would otherwise always stand in for its image (≈ 0.7). Each
+ * modality is ranked on its own scale, past its own measured floor.
+ */
+const MEDIA_ARM_WEIGHTS = { vector: 0.5, chunkFts: 0.25 };
+/** Media rows asked of each catalog, per modality, on an explicit search. */
+const MEDIA_K = 2;
+/** Media results one search returns at most, and per document. */
+const MEDIA_RESULT_CAP = 4;
+const MEDIA_PER_DOCUMENT = 1;
+/**
+ * Fused documents per catalog when several are in scope: keeps one catalog
+ * from monopolizing the merged list. A search scoped to one catalog has
+ * nothing to share the list with, and the cap cut the Knowledge browser's
+ * search for "blob" in an Azure-docs catalog — 348 matching titles — to six.
+ */
+const PER_CATALOG_CAP = 6;
+/** Lexical candidates fetched per arm before fusion, at the least. */
+const DOC_FTS_MIN = 6;
+const CHUNK_FTS_MIN = 8;
+/** Rank-anchored relevance for a fused knowledge result: the best hit is a strong 1.0, decaying RRF-style. */
+function fusedRankRelevance(rank) {
+    return 11 / (11 + rank);
+}
+/**
+ * The first prose paragraph of a document body, for a hit that no chunk
+ * carries (a title-only match): the model gets something to read, not just
+ * a summary line. Skips the title heading and a key-facts list.
+ */
+function leadExcerpt(markdown, max = 600) {
+    const body = markdown.replace(/^#\s[^\n]*\n+/, '');
+    const paragraph = body
+        .split(/\n\s*\n/)
+        .map((part) => part.trim())
+        .find((part) => part.length > 0 && !part.startsWith('#') && !part.startsWith('- ')) ??
+        body.trim();
+    return paragraph.length > max ? `${paragraph.slice(0, max - 1)}…` : paragraph;
+}
+export async function searchUnifiedCatalogs(deps, active, query, opts) {
+    if (active.length === 0)
+        return [];
+    const groups = [];
+    const shared = [];
+    const keyword = [];
+    const byProfile = new Map();
+    for (const key of active) {
+        const info = deps.catalog(key);
+        if (!info)
+            continue;
+        if (info.semanticSearch === 'shared' && !opts.localModelsOnly)
+            shared.push(key);
+        else if (info.semanticSearch === 'profile' || info.semanticSearch === 'shared') {
+            const group = byProfile.get(info.embedding.id) ?? { profile: info.embedding, keys: [] };
+            group.keys.push(key);
+            byProfile.set(info.embedding.id, group);
+        }
+        else
+            keyword.push(key);
+    }
+    if (shared.length > 0) {
+        groups.push({
+            keys: shared,
+            ...(opts.vector ? { vector: Float32Array.from(opts.vector) } : {}),
+        });
+    }
+    for (const group of byProfile.values()) {
+        const vector = await deps.embedForProfile(query, group.profile, opts.queryEmbedBudgetMs, opts.localModelsOnly);
+        groups.push({ keys: group.keys, ...(vector ? { vector } : {}) });
+    }
+    if (keyword.length > 0)
+        groups.push({ keys: keyword });
+    const response = {
+        chunks: [],
+        documents: [],
+    };
+    for (const group of groups) {
+        const request = {
+            query,
+            shardBudget: ROUTE_BUDGET_EXPLICIT,
+            titleRouteShards: TITLE_ROUTE_EXPLICIT,
+            finalK: FINAL_K,
+            includeChunkFts: true,
+            catalogKeys: group.keys,
+            // A pool no deeper than the page asked for: six title hits could
+            // never fill a twenty-result browse search.
+            docFtsLimit: Math.max(DOC_FTS_MIN, opts.maxResults),
+            chunkFtsLimit: Math.max(CHUNK_FTS_MIN, opts.maxResults),
+            spatial: opts.spatial,
+        };
+        let part;
+        try {
+            part = await deps.host.search(group.vector
+                ? { ...request, vector: group.vector, ...(opts.media ? { mediaK: MEDIA_K } : {}) }
+                : request);
+        }
+        catch (error) {
+            // A catalog that refuses the query vector (a width the catalog does
+            // not store, say) is an embedding failure, not a search failure: the
+            // worker forwards only the message, so any vector-arm error falls
+            // back to the keyword arms for this group.
+            if (!group.vector)
+                throw error;
+            deps.warn(`[knowledge] semantic search failed for ${group.keys.join(', ')}; keyword-only: ${error instanceof Error ? error.message : String(error)}`);
+            part = await deps.host.search(request);
+        }
+        response.chunks.push(...part.chunks);
+        response.documents.push(...part.documents);
+    }
+    // ── fuse the arms per document ──────────────────────────────────────
+    const fused = new Map();
+    const bump = (catalogKey, documentId, weight, rank, chunk) => {
+        const key = `${catalogKey}\u0000${documentId}`;
+        const entry = fused.get(key) ?? { catalogKey, documentId, score: 0 };
+        entry.score += weight / (RRF_K + rank);
+        // The document's representative chunk: its best vector chunk, else
+        // whichever chunk-FTS row named it.
+        if (chunk && (!entry.chunk || (chunk.cosine ?? -1) > (entry.chunk.cosine ?? -1))) {
+            entry.chunk = chunk;
+        }
+        fused.set(key, entry);
+    };
+    // Every text passage the arms found, per document, best vector match first,
+    // for `chunksPerDocument`. Fusion still ranks documents, not passages.
+    const passagesByDocument = new Map();
+    if ((opts.chunksPerDocument ?? 1) > 1) {
+        for (const hit of response.chunks
+            .filter((h) => !h.media)
+            .sort((a, b) => (b.cosine ?? -1) - (a.cosine ?? -1))) {
+            const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+            const passages = passagesByDocument.get(key) ?? [];
+            if (!passages.some((known) => known.chunkUid === hit.chunkUid))
+                passages.push(hit);
+            passagesByDocument.set(key, passages);
+        }
+    }
+    // Vector arm: one rank per document, in rerank-cosine order. A hit under
+    // its profile's floor is not evidence at all — KNN always returns its
+    // nearest rows, and a rank-0 row fuses to relevance 1.0 however far away
+    // it is (see vector-floors.ts).
+    const textChunks = response.chunks.filter((h) => !h.media);
+    const mediaChunks = response.chunks.filter((h) => h.media);
+    const seenVector = new Set();
+    let vectorRank = 0;
+    for (const hit of textChunks
+        .filter((h) => h.cosine !== undefined)
+        .sort((a, b) => (b.cosine ?? 0) - (a.cosine ?? 0))) {
+        const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+        if (seenVector.has(key))
+            continue;
+        const cosine = hit.cosine ?? 0;
+        const floor = deps.vectorFloorFor(hit.catalogKey);
+        if (floor !== null && cosine < floor)
+            continue;
+        seenVector.add(key);
+        bump(hit.catalogKey, hit.documentId, ARM_WEIGHTS.vector, vectorRank++, hit);
+        const entry = fused.get(key);
+        if (entry && floor !== null && cosine > (entry.similarity ?? Number.NEGATIVE_INFINITY)) {
+            entry.similarity = cosine;
+        }
+    }
+    // Chunk-body FTS arm: BM25 order as the shards returned it, ranked per catalog.
+    const chunkFtsRank = new Map();
+    const seenChunkFts = new Set();
+    for (const hit of textChunks.filter((h) => h.cosine === undefined)) {
+        const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+        if (seenChunkFts.has(key))
+            continue;
+        seenChunkFts.add(key);
+        const rank = chunkFtsRank.get(hit.catalogKey) ?? 0;
+        chunkFtsRank.set(hit.catalogKey, rank + 1);
+        bump(hit.catalogKey, hit.documentId, ARM_WEIGHTS.chunkFts, rank, hit);
+    }
+    // Doc-title FTS arm: exact-name evidence, ranked per catalog by the host.
+    for (const doc of response.documents) {
+        bump(doc.catalogKey, doc.documentId, ARM_WEIGHTS.docFts, doc.rank);
+    }
+    // Media rows: their own vector arm per modality (a modality with no
+    // measured floor gives no vector evidence — nearest-neighbour search
+    // always returns some image, and a media row has no query words to be
+    // grounded in) and a caption FTS arm.
+    const mediaFused = new Map();
+    const bumpMedia = (hit, weight, rank) => {
+        const key = `${hit.catalogKey}\u0000${hit.chunkUid}`;
+        const entry = mediaFused.get(key) ?? {
+            catalogKey: hit.catalogKey,
+            documentId: hit.documentId,
+            score: 0,
+            chunk: hit,
+        };
+        entry.score += weight / (RRF_K + rank);
+        if ((hit.cosine ?? -1) > (entry.chunk?.cosine ?? -1))
+            entry.chunk = hit;
+        mediaFused.set(key, entry);
+    };
+    const mediaVectorRank = new Map();
+    for (const hit of mediaChunks
+        .filter((h) => h.cosine !== undefined)
+        .sort((a, b) => (b.cosine ?? 0) - (a.cosine ?? 0))) {
+        const modality = hit.media?.modality;
+        const floor = deps.vectorFloorFor(hit.catalogKey, modality);
+        if (floor === null || (hit.cosine ?? 0) < floor)
+            continue;
+        const rank = mediaVectorRank.get(modality) ?? 0;
+        mediaVectorRank.set(modality, rank + 1);
+        bumpMedia(hit, MEDIA_ARM_WEIGHTS.vector, rank);
+        const entry = mediaFused.get(`${hit.catalogKey}\u0000${hit.chunkUid}`);
+        if (entry)
+            entry.similarity = Math.max(entry.similarity ?? -1, hit.cosine ?? 0);
+    }
+    let mediaFtsRank = 0;
+    for (const hit of mediaChunks.filter((h) => h.cosine === undefined)) {
+        bumpMedia(hit, MEDIA_ARM_WEIGHTS.chunkFts, mediaFtsRank++);
+    }
+    const ordered = [...fused.values(), ...mediaFused.values()].sort((a, b) => b.score - a.score ||
+        (b.chunk?.cosine ?? -1) - (a.chunk?.cosine ?? -1) ||
+        a.documentId.localeCompare(b.documentId));
+    const matches = new Map([...response.documents, ...response.chunks]
+        .filter((hit) => hit.matchedLocation)
+        .map((hit) => [
+        `${hit.catalogKey}\u0000${hit.documentId}`,
+        { distanceMeters: hit.distanceMeters, matchedLocation: hit.matchedLocation },
+    ]));
+    const seenSpatial = new Set();
+    const out = [];
+    const perCatalogCount = new Map();
+    const capPerCatalog = !opts.spatial && active.length > 1;
+    const mediaPerDocument = new Map();
+    let mediaResults = 0;
+    for (const entry of ordered) {
+        const info = deps.catalog(entry.catalogKey);
+        if (!info)
+            continue;
+        if (entry.chunk?.media) {
+            const docKey = `${entry.catalogKey}\u0000${entry.documentId}`;
+            const forDocument = mediaPerDocument.get(docKey) ?? 0;
+            if (mediaResults >= MEDIA_RESULT_CAP || forDocument >= MEDIA_PER_DOCUMENT)
+                continue;
+            const evidence = entry.similarity !== undefined
+                ? { arm: 'vector', similarity: entry.similarity }
+                : { arm: 'fts' };
+            mediaPerDocument.set(docKey, forDocument + 1);
+            mediaResults++;
+            out.push(knowledgeChunkResult(info, entry.chunk, fusedRankRelevance(out.length), evidence));
+            if (out.length >= Math.max(10, opts.maxResults))
+                break;
+            continue;
+        }
+        const count = perCatalogCount.get(entry.catalogKey) ?? 0;
+        if (capPerCatalog && count >= PER_CATALOG_CAP)
+            continue;
+        const spatialIdentity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
+        if (opts.spatial && seenSpatial.has(spatialIdentity))
+            continue;
+        const relevance = fusedRankRelevance(out.length);
+        // `vector` only when the hit cleared a measured floor; everything else
+        // is lexical evidence, which proactive injection asks to be grounded.
+        const evidence = entry.similarity !== undefined
+            ? { arm: 'vector', similarity: entry.similarity }
+            : { arm: 'fts' };
+        const result = entry.chunk
+            ? knowledgeChunkResult(info, entry.chunk, relevance, evidence)
+            : await knowledgeDocumentResult(deps.host, info, entry.documentId, relevance, evidence);
+        if (!result)
+            continue;
+        perCatalogCount.set(entry.catalogKey, count + 1);
+        seenSpatial.add(spatialIdentity);
+        const docKey = `${entry.catalogKey}\u0000${entry.documentId}`;
+        out.push({ ...result, ...matches.get(docKey) });
+        if (out.length >= Math.max(10, opts.maxResults))
+            break;
+        // The document's other passages, each labelled by its own evidence: a
+        // sibling is vector evidence only if it clears the floor by itself.
+        const siblings = (passagesByDocument.get(docKey) ?? [])
+            .filter((hit) => hit.chunkUid !== entry.chunk?.chunkUid)
+            .slice(0, Math.max(0, (opts.chunksPerDocument ?? 1) - 1));
+        const floor = deps.vectorFloorFor(entry.catalogKey);
+        for (const sibling of siblings) {
+            const own = floor !== null && sibling.cosine !== undefined && sibling.cosine >= floor
+                ? { arm: 'vector', similarity: sibling.cosine }
+                : { arm: 'fts' };
+            out.push(knowledgeChunkResult(info, sibling, fusedRankRelevance(out.length), own));
+            if (out.length >= Math.max(10, opts.maxResults))
+                break;
+        }
+        if (out.length >= Math.max(10, opts.maxResults))
+            break;
+    }
+    return out;
+}
+/** A document the lexical arms named but no chunk carries: cite it with its lead paragraph. */
+export async function knowledgeDocumentResult(host, info, documentId, relevance, evidence) {
+    const doc = await host.getDocument(info.key, documentId).catch(() => null);
+    if (!doc)
+        return null;
+    const snippet = leadExcerpt(doc.markdown) || doc.summary || '';
+    return {
+        kind: 'knowledge',
+        id: `knowledge:${info.ref.catalogId}:doc:${documentId}`,
+        title: doc.title,
+        subtitle: `${info.name} · ${info.topicNames.get(doc.topicId) ?? doc.topicId}`,
+        ...(snippet ? { snippet } : {}),
+        retrievalSource: 'knowledge',
+        catalogId: info.ref.catalogId,
+        catalogVersion: info.ref.version,
+        documentId,
+        topicPath: [info.topicNames.get(doc.topicId) ?? doc.topicId],
+        uri: formatKnowledgeUri({
+            publisherId: info.ref.publisherId,
+            catalogId: info.ref.catalogId,
+            documentId,
+        }),
+        ...(doc.sourceUrl ? { sourceUrl: doc.sourceUrl } : {}),
+        ...evidence,
+        ...scoreResult('knowledge', relevance),
+    };
+}
+export function knowledgeChunkResult(info, hit, relevance, evidence) {
+    return {
+        kind: 'knowledge',
+        id: `knowledge:${info.ref.catalogId}:${hit.chunkUid}`,
+        title: hit.headingPath.length > 0 ? `${hit.title} › ${hit.headingPath.join(' › ')}` : hit.title,
+        subtitle: info.name,
+        snippet: hit.text,
+        retrievalSource: 'knowledge',
+        catalogId: info.ref.catalogId,
+        catalogVersion: info.ref.version,
+        documentId: hit.documentId,
+        uri: formatKnowledgeUri({
+            publisherId: info.ref.publisherId,
+            catalogId: info.ref.catalogId,
+            documentId: hit.documentId,
+            fragment: { chunk: hit.chunkUid },
+        }),
+        line: hit.lineStart,
+        lineEnd: hit.lineEnd,
+        ...(hit.media ? { media: hit.media } : {}),
+        ...evidence,
+        ...scoreResult('knowledge', relevance),
+    };
+}

package/dist/models/catalog-drift.d.ts

@@ -36,6 +36,8 @@ export interface EvaluateCatalogDriftOptions {
     installedVersion?: string;
     installed: InstalledPayloadRecord;
     manifest: ChatModelManifest;
+    /** The backend a llama.cpp copy runs on. Defaults to the process's own. */
+    llamaCppBackend?: string | undefined;
     /**
      * False for models resolved out of a read-only overlay (the machine asset
      * store) and while an install is in flight for this id — the verdict still

package/dist/models/catalog-drift.js

@@ -30,7 +30,7 @@ export async function evaluateCatalogDrift(opts) {
     if (!opts.installedVersion || !currentVersion || opts.installedVersion === currentVersion) {
         return { updateAvailable: false };
     }
-    const catalog = describeCatalogPayload(opts.manifest, opts.engine);
+    const catalog = describeCatalogPayload(opts.manifest, opts.engine, opts.llamaCppBackend);
     if (!catalog) {
         // The catalog no longer describes this engine's payload at all (a source
         // block was pulled). Nothing to download, so nothing to offer.

package/dist/models/catalog-payload-identity.d.ts

@@ -30,7 +30,7 @@
  * over what the install already recorded, and its answers steer UI, never
  * trust.
  */
-import type { ChatModelManifest, GezmodelEngine } from '@bendyline/gezel';
+import { type ChatModelManifest, type GezmodelEngine } from '@bendyline/gezel';
 /** One file the catalog expects to land in the model directory. */
 export interface CatalogPayloadFile {
     /** Name as it lands on disk ('/'-joined for nested files, as in `fileSha256`). */
@@ -103,5 +103,5 @@ export declare function catalogPayloadFingerprint(payload: CatalogPayload): stri
  * The single place that knows each source block's shape, so callers compare
  * like for like without re-deriving filenames.
  */
-export declare function describeCatalogPayload(manifest: ChatModelManifest, engine: GezmodelEngine): CatalogPayload | null;
+export declare function describeCatalogPayload(manifest: ChatModelManifest, engine: GezmodelEngine, llamaCppBackend?: string | undefined): CatalogPayload | null;
 export declare function comparePayloadIdentity(opts: ComparePayloadOptions): Promise<PayloadIdentityResult>;

package/dist/models/catalog-payload-identity.js

@@ -33,6 +33,8 @@
 import { createHash } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+import { llamaCppDraftModelApplies, } from '@bendyline/gezel';
+import { currentLlamaCppBackend } from '../providers/llama-cpp/backend-health.js';
 /**
  * Stable hash of a catalog payload description. Deliberately excludes
  * `revision`: it is a fetch coordinate, and identical hashes mean identical
@@ -53,7 +55,7 @@ export function catalogPayloadFingerprint(payload) {
  * The single place that knows each source block's shape, so callers compare
  * like for like without re-deriving filenames.
  */
-export function describeCatalogPayload(manifest, engine) {
+export function describeCatalogPayload(manifest, engine, llamaCppBackend = currentLlamaCppBackend()) {
     if (engine === 'mlx') {
         const src = manifest.mlx;
         if (!src)
@@ -96,10 +98,13 @@ export function describeCatalogPayload(manifest, engine) {
             sizeBytes: src.approxSizeBytes,
         });
     }
-    // Draft companions exist on both engine sources and are fetched
-    // unconditionally by `buildDownloadPlan`, so read them off the already
-    // engine-selected `src` rather than re-narrowing to one engine.
-    if (src.draftModel) {
+    // Draft companions exist on both engine sources, so read them off the
+    // already engine-selected `src`. A llama.cpp drafter limited to some backends
+    // is no part of this install elsewhere: counting it would offer every other
+    // machine an update for a file it never downloads.
+    const draftApplies = engine !== 'llama-cpp' ||
+        llamaCppDraftModelApplies(manifest.llamaCpp?.draftModel, llamaCppBackend);
+    if (src.draftModel && draftApplies) {
         files.push({
             name: basename(src.draftModel.filename),
             sha256: src.draftModel.sha256,

package/dist/providers/active-install-message.js

@@ -37,7 +37,7 @@ export function notReadyError(message, code) {
  */
 export function noModelYetMessage(engineLabel, active) {
     if (!active) {
-        return `${engineLabel}: no model is installed yet. Download one from Settings → Artificial Intelligence, then try again.`;
+        return `${engineLabel}: no model is installed yet. Download one from Settings → Artificial intelligence, then try again.`;
     }
     if (active.phase !== 'downloading') {
         const verb = active.phase === 'verifying' ? 'being verified' : 'being prepared';

package/dist/providers/catalog-model-config.d.ts

@@ -59,5 +59,33 @@ export declare function resolveCatalogLlamaCppEngineConfig(catalog: CatalogServi
         mtp?: boolean | undefined;
         draftModelId?: string | undefined;
         nMax?: number | undefined;
+        sampling?: "greedy" | "probabilistic" | undefined;
+        byBackend?: {
+            cuda?: {
+                type?: "none" | "draft-mtp" | "draft-eagle3" | "draft-dflash" | "draft-simple" | "ngram-mod" | "ngram-simple" | "ngram-map-k" | "ngram-map-k4v" | "ngram-cache" | undefined;
+                nMax?: number | undefined;
+                sampling?: "greedy" | "probabilistic" | undefined;
+            } | undefined;
+            rocm?: {
+                type?: "none" | "draft-mtp" | "draft-eagle3" | "draft-dflash" | "draft-simple" | "ngram-mod" | "ngram-simple" | "ngram-map-k" | "ngram-map-k4v" | "ngram-cache" | undefined;
+                nMax?: number | undefined;
+                sampling?: "greedy" | "probabilistic" | undefined;
+            } | undefined;
+            vulkan?: {
+                type?: "none" | "draft-mtp" | "draft-eagle3" | "draft-dflash" | "draft-simple" | "ngram-mod" | "ngram-simple" | "ngram-map-k" | "ngram-map-k4v" | "ngram-cache" | undefined;
+                nMax?: number | undefined;
+                sampling?: "greedy" | "probabilistic" | undefined;
+            } | undefined;
+            metal?: {
+                type?: "none" | "draft-mtp" | "draft-eagle3" | "draft-dflash" | "draft-simple" | "ngram-mod" | "ngram-simple" | "ngram-map-k" | "ngram-map-k4v" | "ngram-cache" | undefined;
+                nMax?: number | undefined;
+                sampling?: "greedy" | "probabilistic" | undefined;
+            } | undefined;
+            cpu?: {
+                type?: "none" | "draft-mtp" | "draft-eagle3" | "draft-dflash" | "draft-simple" | "ngram-mod" | "ngram-simple" | "ngram-map-k" | "ngram-map-k4v" | "ngram-cache" | undefined;
+                nMax?: number | undefined;
+                sampling?: "greedy" | "probabilistic" | undefined;
+            } | undefined;
+        } | undefined;
     } | undefined;
 } | undefined>;

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

@@ -1,5 +1,5 @@
 import { basename, dirname, join } from 'node:path';
-import { DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS, createLogger, } from '@bendyline/gezel';
+import { DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS, createLogger, ds4SsdStreamingSupported, } from '@bendyline/gezel';
 import { gezelPaths } from '@bendyline/gezel/paths';
 import { LlamaCppProvider } from '../llama-cpp/index.js';
 import { minViableLocalContextTokens, pressureIdleGraceMs } from '../native/capacity-broker.js';
@@ -282,7 +282,7 @@ export async function buildDs4Provider(opts) {
     // build). `shouldUseDs4SsdStreaming` still refuses a model that cannot fit,
     // which is what keeps the flip safe: overriding that on a 90.89 GiB build
     // OOM-killed the engine mid-load on a 121.63 GiB host.
-    const { ds4VisionResidentBytes, planDs4ExpertCache, shouldUseDs4SsdStreaming } = await import('./residency.js');
+    const { ds4VisionResidentBytes, planDs4ExpertCache, planDs4MeasuredLaunch, shouldUseDs4SsdStreaming, } = await import('./residency.js');
     let visionEncoderSizeBytes = installedModel?.visionEncoderSizeBytes;
     if (vision.enabled && vision.visionEncoderPath && !visionEncoderSizeBytes) {
         const { stat: statVisionEncoder } = await import('node:fs/promises');
@@ -291,11 +291,10 @@ export async function buildDs4Provider(opts) {
             .catch(() => undefined);
     }
     const visionResidentBytes = ds4VisionResidentBytes(vision.enabled ? visionEncoderSizeBytes : undefined);
+    const streamingSupported = ds4SsdStreamingSupported(ds4Source, process.platform);
     const ssdStreaming = shouldUseDs4SsdStreaming({
         configured: config.ds4SsdStreaming,
-        ...(ds4Source?.ssdStreamingSupported !== undefined
-            ? { ssdStreamingSupported: ds4Source.ssdStreamingSupported }
-            : {}),
+        ...(streamingSupported !== undefined ? { ssdStreamingSupported: streamingSupported } : {}),
         modelSizeBytes: residentWeightBytes,
         totalRamBytes,
         ...(visionResidentBytes > 0 ? { companionBytes: visionResidentBytes } : {}),
@@ -304,15 +303,30 @@ export async function buildDs4Provider(opts) {
         log.warn(`[ds4] ignored unsafe full-residency override for ${effectiveModelId ?? modelPath}; ` +
             `model=${modelSizeBytes ?? 'unknown'} bytes, system=${Math.round(totalRamGb)} GiB`);
     }
-    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`);
+    if (config.ds4SsdStreaming === true && streamingSupported === false) {
+        log.warn(`[ds4] ignored SSD-streaming override for ${effectiveModelId ?? modelPath}; ds4 cannot stream this model's routed experts on this backend`);
     }
-    const cachePlanWith = (extraResidentBytes) => planDs4ExpertCache({
-        configuredGb: config.ds4CacheExpertsGb,
-        catalogCacheBytes: ds4Source?.cacheExpertsBytes,
-        catalogResidentBytes: (ds4Source?.residentBytes ?? 0) + visionResidentBytes + extraResidentBytes,
+    // A measured footprint prices the launch for its mode; a measured streamed
+    // footprint also sizes the expert cache against the local-model budget.
+    const modelBudgetBytes = ssdStreaming && ds4Source?.streamingMemory
+        ? await (await import('../native/device-capacity.js')).deviceModelBudgetBytes(config)
+        : undefined;
+    const measuredLaunchWith = (extraResidentBytes) => planDs4MeasuredLaunch({
+        source: ds4Source,
+        numCtx,
+        ssdStreaming,
         totalRamBytes: totalRamGb * 1024 ** 3,
+        budgetBytes: modelBudgetBytes,
+        sidecarBytes: visionResidentBytes + extraResidentBytes,
+        configuredCacheGb: config.ds4CacheExpertsGb,
     });
+    const cachePlanWith = (extraResidentBytes) => measuredLaunchWith(extraResidentBytes)?.cache ??
+        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` for any family but DeepSeek V4.1.
@@ -386,7 +400,9 @@ export async function buildDs4Provider(opts) {
         throw err;
     }
     if (cachePlan.clamped) {
-        log.warn(`[ds4] clamped expert cache ${cachePlan.requestedGb} → ${cachePlan.cacheGb} GiB to preserve system headroom`);
+        log.warn(`[ds4] clamped expert cache ${cachePlan.requestedGb} → ${cachePlan.cacheGb} GiB to ${cachePlan.limit === 'model-budget'
+            ? "fit this device's local-model budget"
+            : 'preserve system headroom'}`);
     }
     const cacheExpertsGb = cachePlan.cacheGb;
     const kvDir = join(home, 'engines', 'ds4', 'kv');
@@ -433,6 +449,11 @@ export async function buildDs4Provider(opts) {
                 ? 'interactive'
                 : 'background',
             requirement: async () => {
+                // A measured launch is reserved at exactly its working set: no
+                // full-residency floor, and the expert cache this launch was given.
+                const measured = measuredLaunchWith(dspark.enabled ? dsparkCompanionBytes : 0);
+                if (measured)
+                    return { bytes: measured.workingSetBytes, exclusive: !ssdStreaming };
                 const { ds4AdmissionGpuBytes, ds4BaseResidentBytes, ds4ResidentLine, ds4ProjectedResidentBytes, ds4ResidentBytesForMode, } = await import('./residency.js');
                 const line = ds4ResidentLine(ds4Source ?? {});
                 const projected = line ? ds4ProjectedResidentBytes(line, numCtx) : ds4Source?.residentBytes;
@@ -444,7 +465,7 @@ export async function buildDs4Provider(opts) {
                         modelSizeBytes: residentWeightBytes,
                     });
                 const workingSetBytes = base + visionResidentBytes + (dspark.enabled ? dsparkCompanionBytes : 0);
-                const bytes = ds4ResidentBytesForMode(workingSetBytes, ssdStreaming, ds4Source?.ssdStreamingSupported);
+                const bytes = ds4ResidentBytesForMode(workingSetBytes, ssdStreaming, streamingSupported);
                 const gpuBytes = ds4AdmissionGpuBytes({
                     workingSetBytes,
                     reservationBytes: bytes,
@@ -528,6 +549,7 @@ export async function buildDs4Provider(opts) {
                 `backend=${backendFlag.slice(2)} ctx=${numCtx} ` +
                 `prefillChunk=${ds4Source?.prefillChunk ?? 'engine-default'} ` +
                 `ssdStreaming=${ssdStreaming} cacheExpertsGiB=${ssdStreaming ? cacheExpertsGb : 0} ` +
+                `memory=${measuredLaunchWith(0) ? 'measured' : 'catalog'} ` +
                 `vision=${vision.enabled} mtp=${mtp.enabled} exactSampling=${mtp.exactSampling} (${mtp.reason}) ` +
                 `dspark=${dspark.enabled} (${dspark.reason})`);
             return { command: binary, args, baseUrl: `http://127.0.0.1:${port}`, cwd: ds4BundleDir };