@bendyline/gezel-inference 1.0.0 → 1.0.2

package/dist/http/routes/v1-models.js

@@ -1,6 +1,9 @@
-import { externalGezelModelId, isRecommendedModel, resolveDistributionProfile, } from '@bendyline/gezel';
+import { estimateManifestKvBytes, externalGezelModelId, isRecommendedModel, llamaCppBackendExclusion, localContextFloorTokens, rateModelsForDevice, resolveDistributionProfile, } from '@bendyline/gezel';
 import { resolveOnDeviceProvider } from '@bendyline/gezel/native';
 import { Hono } from 'hono';
+import { currentLlamaCppBackend } from '../../providers/llama-cpp/backend-health.js';
+import { CapacityBroker } from '../../providers/native/capacity-broker.js';
+import { detectMemoryProfileCached } from '../../system/memory.js';
 import { appleSystemModel } from '../openai-compat/apple-model.js';
 import { resolveFallbackGezelId } from '../openai-compat/chat-target.js';
 /**
@@ -30,34 +33,110 @@ const PROVIDERS_TO_ENUMERATE = [
     'ds4',
 ];
 const LOCAL_PROVIDERS = ['llama-cpp', 'mlx', 'ds4'];
+/**
+ * Engines that enforce `response_format` with a grammar: llama-server's
+ * `json_schema`, and the MLX sidecar's llguidance JSON grammar
+ * (`providers/mlx/python/response_format.py`). ds4 shares llama.cpp's request
+ * map, but nothing here shows its server enforces a schema, so it is not
+ * advertised.
+ */
+function enforcesResponseFormat(provider) {
+    return provider === 'llama-cpp' || provider === 'mlx';
+}
+function catalogCapabilities(manifest, provider) {
+    return {
+        text: true,
+        tools: manifest.supportsTools,
+        structuredOutput: enforcesResponseFormat(provider),
+        images: false,
+        foregroundOnly: false,
+    };
+}
 function catalogBackend(manifest) {
+    // ds4 has no portable fallback: `discoverNativeBinaries` stamps its binary
+    // only where a build for this host is on disk, which is the gate the
+    // Settings availability check reads too. Windows has none.
+    const ds4 = manifest.ds4 && process.env.GEZEL_DS4_SERVER_BIN ? 'ds4' : null;
     // Store hosts have no provisioned Python runtime. Only advertise models
     // backed by bundled native engines until a frozen MLX runtime ships.
     const store = resolveDistributionProfile().pythonProvisioning === 'frozen-only';
+    const llamaCpp = manifest.llamaCpp && !llamaCppBackendExclusion(manifest.llamaCpp, currentLlamaCppBackend());
     if (store)
-        return manifest.llamaCpp ? 'llama-cpp' : manifest.ds4 ? 'ds4' : null;
+        return llamaCpp ? 'llama-cpp' : ds4;
     const preferred = resolveOnDeviceProvider(process.platform, process.arch);
     if (preferred === 'mlx' && manifest.mlx && !manifest.mlx.disabledReason)
         return 'mlx';
-    if (preferred === 'llama-cpp' && manifest.llamaCpp)
+    if (preferred === 'llama-cpp' && llamaCpp)
         return 'llama-cpp';
-    if (manifest.llamaCpp)
+    if (llamaCpp)
         return 'llama-cpp';
     if (manifest.mlx && !manifest.mlx.disabledReason && process.platform === 'darwin')
         return 'mlx';
-    if (manifest.ds4)
-        return 'ds4';
-    return null;
+    return ds4;
+}
+/**
+ * What loading a catalog model would hold, priced as the capacity broker
+ * prices it: the catalog's measured pin when it has one, else the engine's
+ * estimate, plus KV at the context floor this machine launches with. ds4's
+ * figure already bounds its streamed working set, so it takes no extra KV.
+ */
+function footprintBytes({ manifest, provider, source }, memory) {
+    const mmprojBytes = provider === 'llama-cpp' ? manifest.llamaCpp?.mmproj?.sizeBytes : undefined;
+    const weights = source.residentBytes ??
+        CapacityBroker.estimateResidentBytes(provider, source.approxSizeBytes, mmprojBytes ? { mmprojBytes } : undefined);
+    if (provider === 'ds4')
+        return weights;
+    const ctxTokens = localContextFloorTokens({
+        totalRamBytes: memory.totalRamBytes,
+        gpuVramBytes: fastGpuBytes(memory),
+    });
+    // MLX keeps its cache in f16; llama.cpp's default q8_0 is the helper's default.
+    return (weights +
+        estimateManifestKvBytes(manifest, {
+            ctxTokens,
+            ...(provider === 'mlx' ? { cacheScale: 1 } : {}),
+        }));
+}
+/**
+ * An integrated adapter's advertised allocation is shared system RAM, not a
+ * fast pool beside it, so fit treats that host as RAM-paced (as Settings does).
+ */
+function fastGpuBytes(memory) {
+    return memory.gpuMemoryKind === 'integrated' ? null : memory.gpuVramBytes;
+}
+function recoDevice(memory) {
+    return {
+        platform: memory.platform,
+        gpuVramBytes: fastGpuBytes(memory),
+        gpuMemoryKind: memory.gpuMemoryKind,
+        totalRamBytes: memory.totalRamBytes,
+        usableBytes: memory.usableBytes,
+        budgetBytes: memory.budgetBytes,
+    };
 }
-async function downloadableCatalogEntries(ctx, created, existingIds) {
-    const items = await ctx.catalog.list('chat-model').catch(() => []);
-    return items
-        .flatMap((item) => {
+/** Curated order, for when this machine's memory could not be read. */
+function byCuratedScore(a, b) {
+    const aRecommended = isRecommendedModel(a.manifest);
+    const bRecommended = isRecommendedModel(b.manifest);
+    if (aRecommended !== bRecommended)
+        return aRecommended ? -1 : 1;
+    const score = (b.manifest.recoScore ?? 0) - (a.manifest.recoScore ?? 0);
+    return score || (a.entry.name ?? a.entry.id).localeCompare(b.entry.name ?? b.entry.id);
+}
+/**
+ * Downloadable models, each rated against this machine (`fit`,
+ * `recommendation`) and listed best first. A model too big to run here stays
+ * listed with `fit.tier: 'too-big'` and a 0 score, so a client decides
+ * whether to hide it.
+ */
+async function downloadableCatalogEntries(items, created, existingIds, memoryProfile) {
+    const candidates = items.flatMap((item) => {
         const manifest = item.manifest;
         if (manifest.kind !== 'chat-model')
             return [];
         const provider = catalogBackend(manifest);
-        if (!provider)
+        const source = provider === 'mlx' ? manifest.mlx : provider === 'ds4' ? manifest.ds4 : manifest.llamaCpp;
+        if (!provider || !source)
             return [];
         const id = `${provider}:${manifest.id}`;
         if (existingIds.has(id))
@@ -65,6 +144,8 @@ async function downloadableCatalogEntries(ctx, created, existingIds) {
         return [
             {
                 manifest,
+                provider,
+                source,
                 entry: {
                     id,
                     object: 'model',
@@ -78,26 +159,41 @@ async function downloadableCatalogEntries(ctx, created, existingIds) {
                     locality: 'on-device',
                     download_bytes: manifest.approxSizeBytes,
                     ...(manifest.contextWindow ? { context_window: manifest.contextWindow } : {}),
-                    capabilities: {
-                        text: true,
-                        tools: manifest.supportsTools,
-                        structuredOutput: false,
-                        images: false,
-                        foregroundOnly: false,
-                    },
+                    capabilities: catalogCapabilities(manifest, provider),
                 },
             },
         ];
-    })
-        .sort((a, b) => {
-        const aRecommended = isRecommendedModel(a.manifest);
-        const bRecommended = isRecommendedModel(b.manifest);
-        if (aRecommended !== bRecommended)
-            return aRecommended ? -1 : 1;
-        const score = (b.manifest.recoScore ?? 0) - (a.manifest.recoScore ?? 0);
-        return score || (a.entry.name ?? a.entry.id).localeCompare(b.entry.name ?? b.entry.id);
-    })
-        .map(({ entry }) => entry);
+    });
+    if (candidates.length === 0)
+        return [];
+    const memory = await memoryProfile().catch(() => null);
+    if (!memory)
+        return candidates.sort(byCuratedScore).map(({ entry }) => entry);
+    const rated = candidates.map((candidate) => {
+        const { entry, manifest, source } = candidate;
+        return {
+            id: entry.id,
+            residentBytes: footprintBytes(candidate, memory),
+            tags: manifest.tags,
+            supportsTools: manifest.supportsTools,
+            ...(manifest.recoScore !== undefined ? { recoScore: manifest.recoScore } : {}),
+            ...(manifest.licenseClass ? { licenseClass: manifest.licenseClass } : {}),
+            ...(source.quantization ? { quantization: source.quantization } : {}),
+        };
+    });
+    const entries = new Map(candidates.map(({ entry }) => [entry.id, entry]));
+    return rateModelsForDevice(rated, recoDevice(memory)).flatMap((rating) => {
+        const entry = entries.get(rating.id);
+        if (!entry)
+            return [];
+        return [
+            {
+                ...entry,
+                fit: { tier: rating.fit.tier, label: rating.fit.label, detail: rating.fit.detail },
+                recommendation: { score: rating.score, recommended: rating.recommended },
+            },
+        ];
+    });
 }
 async function buildModelEntries(ctx, created, options) {
     // Advertise every gezel as a selectable OpenAI "model". Keep the
@@ -128,6 +224,14 @@ async function buildModelEntries(ctx, created, options) {
             ...(gezel.id === fallbackGezelId ? { is_fallback: true } : {}),
         }));
     }
+    const catalogItems = await ctx.catalog.list('chat-model').catch(() => []);
+    // An installed model carries the capabilities its catalog entry
+    // advertised before download; a model with no entry stays unflagged
+    // rather than guessing its tools or images support.
+    const manifests = new Map();
+    for (const item of catalogItems)
+        if (item.manifest.kind === 'chat-model')
+            manifests.set(item.manifest.id, item.manifest);
     const providers = (options.localOnly ? LOCAL_PROVIDERS : PROVIDERS_TO_ENUMERATE).filter((provider) => provider !== 'mlx' || resolveDistributionProfile().pythonProvisioning !== 'frozen-only');
     const buckets = await Promise.all(providers.map(async (provider) => {
         try {
@@ -146,6 +250,9 @@ async function buildModelEntries(ctx, created, options) {
                     : {}),
                 ...(m.contextWindow ? { context_window: m.contextWindow } : {}),
                 ...(m.supportsReasoning ? { supports_reasoning: true } : {}),
+                ...(enforcesResponseFormat(provider) && manifests.has(m.id)
+                    ? { capabilities: catalogCapabilities(manifests.get(m.id), provider) }
+                    : {}),
             }));
         }
         catch {
@@ -156,7 +263,7 @@ async function buildModelEntries(ctx, created, options) {
     }));
     const availableEntries = buckets.flat();
     const existingIds = new Set([...gezelEntries, ...availableEntries].map((entry) => entry.id));
-    const downloadable = await downloadableCatalogEntries(ctx, created, existingIds);
+    const downloadable = await downloadableCatalogEntries(catalogItems, created, existingIds, options.memoryProfile ?? (() => detectMemoryProfileCached()));
     const apple = await appleSystemModel(created);
     return [...gezelEntries, ...apple, ...availableEntries, ...downloadable];
 }

package/dist/http/routes/v1-responses.js

@@ -3,10 +3,12 @@ import { Hono } from 'hono';
 import { bodyLimit } from 'hono/body-limit';
 import { streamSSE } from 'hono/streaming';
 import { ZodError } from 'zod';
+import { UnsupportedResponseFormatError } from '../../providers/mlx/runtime-diagnostics.js';
 import { ExternalToolsUnsupportedError, ModelNotInstalledError, } from '../../providers/types.js';
 import { appendCallerOwnedActionLedger } from '../openai-compat/action-ledger.js';
 import { profileForCallerOwnedInference } from '../openai-compat/caller-owned-profile.js';
-import { resolveChatTarget } from '../openai-compat/chat-target.js';
+import { resolveChatTarget, resolvePinnedModelTarget, } from '../openai-compat/chat-target.js';
+import { engineFailure } from '../openai-compat/engine-failure.js';
 import { runResponsesNonStreaming, runResponsesStreaming, } from '../openai-compat/responses-streaming.js';
 import { ResponsesRequestSchema, translateResponsesRequest, } from '../openai-compat/responses-translate.js';
 import { flattenTranscriptIntoPrompt, parseGezelModelRef, resolveModelTarget, } from '../openai-compat/translate.js';
@@ -220,7 +222,7 @@ export function v1ResponsesRoutes(ctx, opts = {}) {
                             event: 'error',
                             data: JSON.stringify({
                                 type: 'error',
-                                code: 'provider_error',
+                                code: engineFailure(err).code,
                                 message: 'The response stream ended unexpectedly.',
                                 param: null,
                             }),
@@ -259,7 +261,15 @@ export function v1ResponsesRoutes(ctx, opts = {}) {
             if (err instanceof ExternalToolsUnsupportedError) {
                 return invalidRequest(c, err.message, 'tools_not_supported_for_provider');
             }
+            if (err instanceof UnsupportedResponseFormatError) {
+                return invalidRequest(c, err.message, err.code);
+            }
             const message = err instanceof Error ? err.message : String(err);
+            const failure = engineFailure(err);
+            if (failure.code !== 'provider_error') {
+                log.warn(`Responses request failed (${failure.code}): ${message}`);
+                return c.json({ error: { message, type: failure.type, code: failure.code } }, failure.status);
+            }
             if (message.includes('messages must') ||
                 message.includes('empty') ||
                 message.includes('cannot be an assistant turn')) {
@@ -284,7 +294,10 @@ async function resolveResponsesTarget(model, ctx) {
             systemPrefix: '',
         };
     }
-    throw new Error(`Unknown model "${model}". Use an explicit <provider>:<model> id or advertised gezel:<role>-<name> alias.`);
+    const pinned = await resolvePinnedModelTarget(ctx, model);
+    if (pinned)
+        return pinned;
+    throw new Error(`Unknown model "${model}". Use an explicit <provider>:<model> id, a model pinned as a default, or an advertised gezel:<role>-<name> alias.`);
 }
 function prependSystemPrefix(input, prefix) {
     if (!prefix)

package/dist/in-flight-requests.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The in-process transport's open requests, and the one handle that keeps Node
+ * running while any of them is open.
+ *
+ * The direct transport has no socket, so nothing a request awaits is
+ * guaranteed to hold the event loop: engine supervisors and workers unref their
+ * timers and threads so that an idle host never blocks exit. A plain Node
+ * script exited with code 13 ("unsettled top-level await") inside `chat()`
+ * while llama-server cold-started; Electron's own handles had hidden it.
+ */
+export declare class InFlightRequests {
+    private readonly open;
+    private keepAlive;
+    get size(): number;
+    add(controller: AbortController): void;
+    delete(controller: AbortController): void;
+    /** Abort and forget every open request, including a body nobody will read. */
+    abortAll(): void;
+}

package/dist/in-flight-requests.js

@@ -0,0 +1,34 @@
+/**
+ * The in-process transport's open requests, and the one handle that keeps Node
+ * running while any of them is open.
+ *
+ * The direct transport has no socket, so nothing a request awaits is
+ * guaranteed to hold the event loop: engine supervisors and workers unref their
+ * timers and threads so that an idle host never blocks exit. A plain Node
+ * script exited with code 13 ("unsettled top-level await") inside `chat()`
+ * while llama-server cold-started; Electron's own handles had hidden it.
+ */
+export class InFlightRequests {
+    open = new Set();
+    keepAlive;
+    get size() {
+        return this.open.size;
+    }
+    add(controller) {
+        this.open.add(controller);
+        this.keepAlive ??= setInterval(() => { }, 2 ** 30);
+    }
+    delete(controller) {
+        if (!this.open.delete(controller) || this.open.size > 0)
+            return;
+        clearInterval(this.keepAlive);
+        this.keepAlive = undefined;
+    }
+    /** Abort and forget every open request, including a body nobody will read. */
+    abortAll() {
+        for (const controller of [...this.open]) {
+            controller.abort();
+            this.delete(controller);
+        }
+    }
+}

package/dist/inference-service.js

@@ -18,6 +18,7 @@ import { v1KnowledgeRoutes } from './http/routes/v1-knowledge.js';
 import { v1ModelsEnsureRoutes } from './http/routes/v1-models-ensure.js';
 import { v1ModelsRoutes } from './http/routes/v1-models.js';
 import { v1ResponsesRoutes } from './http/routes/v1-responses.js';
+import { InFlightRequests } from './in-flight-requests.js';
 import { KnowledgeManager } from './knowledge/manager.js';
 import { createWorkerCatalogHost } from './knowledge/worker-host.js';
 import { embeddingsHealth, openEmbeddings, shutdownEmbeddings } from './memory/embeddings.js';
@@ -44,14 +45,13 @@ export async function startService(options = {}) {
     const runtimeDir = join(home, 'runtime');
     const lock = await acquireSingleInstanceLock({ runtimeDir, lockPath: join(runtimeDir, 'lock') });
     const cleanup = [() => lock.release()];
-    const requests = new Set();
+    const requests = new InFlightRequests();
     let stopping;
     let closed = false;
     const stop = () => {
         stopping ??= (async () => {
             closed = true;
-            for (const controller of requests)
-                controller.abort();
+            requests.abortAll();
             const errors = [];
             for (const close of cleanup.reverse())
                 try {

package/dist/knowledge/catalog-host.d.ts

@@ -7,7 +7,7 @@
  * (docs/gezk-format.md). The in-process implementation is test/CLI-only;
  * production fails closed if its worker becomes unavailable.
  */
-import type { CatalogAssetFile, CatalogAssetInfo, CatalogAssetRead, CatalogChunkHit, CatalogDocumentMeta, CatalogTopic, CatalogValidationReport } from '@bendyline/gezel-knowledge';
+import type { CatalogAssetFile, CatalogAssetInfo, CatalogAssetRead, CatalogChunkHit, CatalogDocumentInitial, CatalogDocumentMeta, CatalogTopic, CatalogValidationReport } from '@bendyline/gezel-knowledge';
 import type { KnowledgeRadius } from '@bendyline/gezel';
 import type { SpatialMatch } from '@bendyline/gezel-knowledge';
 export interface MountSpec {
@@ -78,6 +78,14 @@ export interface KnowledgeCatalogHost {
         documents: CatalogDocumentMeta[];
         total: number;
     }>;
+    documentInitials(key: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): Promise<CatalogDocumentInitial[]>;
+    documentPosition(key: string, documentId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): Promise<number | null>;
     nearbyDocuments(key: string, radius: KnowledgeRadius, opts: {
         offset?: number;
         limit?: number;

package/dist/knowledge/catalog-host.js

@@ -158,6 +158,8 @@ export async function createInProcessCatalogHost() {
         validate: async (rootDir, deep) => validateExtractedCatalog(rootDir, { deep }),
         topics: async (key) => mustGet(handles, key).topics(),
         documentsPage: async (key, opts) => mustGet(handles, key).documentsPage(opts),
+        documentInitials: async (key, opts) => mustGet(handles, key).documentInitials(opts),
+        documentPosition: async (key, documentId, opts) => mustGet(handles, key).documentPosition(documentId, opts),
         nearbyDocuments: async (key, radius, opts) => mustGet(handles, key).nearbyDocuments(radius, opts),
         getDocument: async (key, documentId) => mustGet(handles, key).getDocument(documentId),
         getChunk: async (key, documentId, chunkUid) => mustGet(handles, key).getChunk(documentId, chunkUid),

package/dist/knowledge/manager.d.ts

@@ -121,6 +121,12 @@ export declare class KnowledgeManager {
      * what the Knowledge screen's browser renders. Offline-safe: gilde is local.
      */
     available(): Promise<KnowledgeAvailableCatalog[]>;
+    /**
+     * The search model an install of a catalog with this profile would also
+     * download. None when the catalog searches with the daemon's own embedder
+     * (an install never fetches that) or the profile's pinned files are cached.
+     */
+    private searchModelDownloadBytes;
     /** Resolve a catalogId (URI authority) to its mounted info, or null. */
     mountedCatalog(catalogId: string): MountedInfo | null;
     /**
@@ -206,6 +212,14 @@ export declare class KnowledgeManager {
         limit?: number;
         descendants?: boolean;
     }): ReturnType<KnowledgeCatalogHost['documentsPage']>;
+    documentInitials(catalogId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): ReturnType<KnowledgeCatalogHost['documentInitials']>;
+    documentPosition(catalogId: string, documentId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): ReturnType<KnowledgeCatalogHost['documentPosition']>;
     getDocument(catalogId: string, documentId: string): ReturnType<KnowledgeCatalogHost['getDocument']>;
     /** One passage by its citation id, with the document's title and origin. */
     getPassage(catalogId: string, documentId: string, chunkUid: string): Promise<KnowledgePassageRead | null>;

package/dist/knowledge/manager.js

@@ -13,7 +13,7 @@ import { readFile, readdir, rm, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { KnowledgeMachineInventorySchema, KnowledgeNearbyRequestSchema, createLogger, formatKnowledgeUri, parseKnowledgeUri, resolveSecurityPolicy, sameVectorSpace, } from '@bendyline/gezel';
-import { compareCatalogVersions, knowledgeEmbeddingProfile, readGezkManifest, } from '@bendyline/gezel-knowledge';
+import { compareCatalogVersions, knowledgeEmbeddingProfile, knowledgeProfileQueryModelBytes, missingPinnedFiles, readGezkManifest, } from '@bendyline/gezel-knowledge';
 import { knowledgeCatalogVersionDir, knowledgeCatalogsDir, knowledgeDownloadsDir, } from '@bendyline/gezel/paths';
 import { HANDBOEK_KNOWLEDGE_CATALOG, HANDBOEK_KNOWLEDGE_PUBLISHER } from './bundled-catalog.js';
 import { scoreResult } from '@bendyline/gezel';
@@ -21,10 +21,11 @@ import { sharedKnowledgeRoot, sharedKnowledgeVersionDir, } from '../machine-engi
 import { embedKnowledgeQuery, sharesDaemonEmbedder } from '../memory/embeddings.js';
 import { ChatModelInstallRegistry } from '../models/install-registry.js';
 import { beginPerfWork } from '../perf/responsiveness.js';
+import { HF_CACHE_DIR_ENV, transformersCacheDir } from '../transformers-cache.js';
 import { resolveKnowledgeCatalogSource } from './catalog-source.js';
 import { KNOWLEDGE_DOWNLOAD_KEY_PATTERN, installKnowledgeCatalog, knowledgeDownloadKey, pruneOtherKnowledgeCatalogVersions, } from './install.js';
 import { KnowledgeRegistry } from './registry.js';
-import { KnowledgeSpatialCursorError, encodeNearbyCursor, nearbyCursorOffset, regionalDocumentIdentity, } from './spatial-query.js';
+import { KnowledgeSpatialCursorError, encodeNearbyCursor, nearbyCursorOffset, spatialDocumentIdentity, } from './spatial-query.js';
 import { resolveKnowledgeVectorFloors } from './vector-floors.js';
 const log = createLogger('knowledge');
 /** Explicit-search shard budget (S) across every active catalog (§3.4). */
@@ -59,6 +60,9 @@ function semanticSearchModeFor(profile) {
         return 'profile';
     return 'keyword-only';
 }
+function searchModelOf(profile) {
+    return { profileId: profile.id, repo: profile.model.repo };
+}
 /**
  * Explicit search fuses three arms per catalog by reciprocal rank (k = 60):
  * the vector chunks (best chunk per document, by rerank cosine), the
@@ -409,10 +413,18 @@ export class KnowledgeManager {
         const shared = await this.sharedInventoryKeys();
         const activeIds = new Set(this.installs.active().map((a) => a.id));
         const partials = await this.partialDownloadKeys();
+        const modelBytes = new Map();
+        for (const item of gilde.values()) {
+            const profileId = item.embeddingProfile.id;
+            if (!modelBytes.has(profileId)) {
+                modelBytes.set(profileId, await this.searchModelDownloadBytes(profileId));
+            }
+        }
         return [...gilde.values()]
             .sort((a, b) => a.name.localeCompare(b.name))
             .map((item) => {
             const entry = registry.find((c) => c.ref.publisherId === item.publisherId && c.ref.catalogId === item.id);
+            const searchModelDownloadBytes = modelBytes.get(item.embeddingProfile.id);
             return {
                 id: item.id,
                 publisherId: item.publisherId,
@@ -451,9 +463,24 @@ export class KnowledgeManager {
                 sharedOnDevice: shared.has(`${item.publisherId}/${item.id}/${item.version}/${item.sha256}`),
                 installing: activeIds.has(item.id),
                 incompleteDownload: partials.has(item.sha256.slice(0, 16)),
+                ...(searchModelDownloadBytes ? { searchModelDownloadBytes } : {}),
             };
         });
     }
+    /**
+     * The search model an install of a catalog with this profile would also
+     * download. None when the catalog searches with the daemon's own embedder
+     * (an install never fetches that) or the profile's pinned files are cached.
+     */
+    async searchModelDownloadBytes(profileId) {
+        const profile = knowledgeEmbeddingProfile(profileId);
+        const bytes = knowledgeProfileQueryModelBytes(profileId);
+        if (!profile || bytes === null || semanticSearchModeFor(profile) !== 'profile')
+            return undefined;
+        const cacheDir = process.env[HF_CACHE_DIR_ENV] ?? transformersCacheDir(this.opts.home);
+        const missing = await missingPinnedFiles(profile, { cacheDir });
+        return missing.length > 0 ? bytes : undefined;
+    }
     /** Resolve a catalogId (URI authority) to its mounted info, or null. */
     mountedCatalog(catalogId) {
         for (const info of this.mountedByKey.values()) {
@@ -676,7 +703,13 @@ export class KnowledgeManager {
         let warning;
         const mounted = this.mountedByKey.get(key);
         if (mounted?.semanticSearch === 'profile') {
-            yield { type: 'progress', phase: 'embedder', bytesDone: 0, bytesTotal: 0 };
+            yield {
+                type: 'progress',
+                phase: 'embedder',
+                bytesDone: 0,
+                bytesTotal: 0,
+                searchModel: searchModelOf(mounted.embedding),
+            };
             warning = yield* this.prewarmProfile(mounted.embedding);
         }
         yield { ...event, ...(warning ? { warning } : {}) };
@@ -746,7 +779,12 @@ export class KnowledgeManager {
                     (settled || Date.now() - lastReportAt >= EMBEDDER_PROGRESS_INTERVAL_MS)) {
                     progress.reported = latest;
                     lastReportAt = Date.now();
-                    yield { type: 'progress', phase: 'embedder', ...latest };
+                    yield {
+                        type: 'progress',
+                        phase: 'embedder',
+                        ...latest,
+                        searchModel: searchModelOf(profile),
+                    };
                     continue;
                 }
                 if (settled)
@@ -802,6 +840,9 @@ export class KnowledgeManager {
                 phase,
                 bytesDone: lastEvent?.type === 'progress' ? lastEvent.bytesDone : 0,
                 bytesTotal: lastEvent?.type === 'progress' ? lastEvent.bytesTotal : 0,
+                ...(lastEvent?.type === 'progress' && lastEvent.searchModel
+                    ? { searchModel: lastEvent.searchModel }
+                    : {}),
             };
         });
     }
@@ -1035,6 +1076,12 @@ export class KnowledgeManager {
     async documentsPage(catalogId, opts) {
         return this.opts.host.documentsPage(this.requireMounted(catalogId).key, opts);
     }
+    async documentInitials(catalogId, opts) {
+        return this.opts.host.documentInitials(this.requireMounted(catalogId).key, opts);
+    }
+    async documentPosition(catalogId, documentId, opts) {
+        return this.opts.host.documentPosition(this.requireMounted(catalogId).key, documentId, opts);
+    }
     async getDocument(catalogId, documentId) {
         return this.opts.host.getDocument(this.requireMounted(catalogId).key, documentId);
     }
@@ -1145,7 +1192,7 @@ export class KnowledgeManager {
                             documentId: document.id,
                         }),
                     };
-                    const identity = regionalDocumentIdentity(info.ref.publisherId, info.ref.catalogId, document.id);
+                    const identity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, document.id);
                     const previous = unique.get(identity);
                     if (!previous || result.distanceMeters < previous.distanceMeters)
                         unique.set(identity, result);
@@ -1383,7 +1430,7 @@ export class KnowledgeManager {
             const count = perCatalogCount.get(entry.catalogKey) ?? 0;
             if (capPerCatalog && count >= PER_CATALOG_CAP)
                 continue;
-            const spatialIdentity = regionalDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
+            const spatialIdentity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
             if (opts.spatial && seenSpatial.has(spatialIdentity))
                 continue;
             const relevance = fusedRankRelevance(out.length);

package/dist/knowledge/search-worker.d.ts

@@ -12,6 +12,6 @@
  */
 export interface KnowledgeWorkerRequest {
     id: number;
-    op: 'mount' | 'unmount' | 'mounted' | 'prewarm' | 'validate' | 'topics' | 'documentsPage' | 'nearbyDocuments' | 'getDocument' | 'getChunk' | 'assets' | 'readAsset' | 'assetFile' | 'search' | 'dispose';
+    op: 'mount' | 'unmount' | 'mounted' | 'prewarm' | 'validate' | 'topics' | 'documentsPage' | 'documentInitials' | 'documentPosition' | 'nearbyDocuments' | 'getDocument' | 'getChunk' | 'assets' | 'readAsset' | 'assetFile' | 'search' | 'dispose';
     args: unknown[];
 }

package/dist/knowledge/spatial-query.d.ts

@@ -1,11 +1,10 @@
 /**
  * Radius pagination binds offsets to the authorized catalog snapshot and
  * query. Cursors confer no authority; the manager recalculates scope on
- * every request. Regional replicas share identity only under Qualla's
- * declared regional catalog and source-document naming convention.
+ * every request.
  */
 export declare class KnowledgeSpatialCursorError extends Error {
 }
 export declare function encodeNearbyCursor(snapshot: string, offset: number): string;
 export declare function nearbyCursorOffset(cursor: string | undefined, snapshot: string): number;
-export declare function regionalDocumentIdentity(publisherId: string, catalogId: string, documentId: string): string;
+export declare function spatialDocumentIdentity(publisherId: string, catalogId: string, documentId: string): string;

package/dist/knowledge/spatial-query.js

@@ -1,8 +1,7 @@
 /**
  * Radius pagination binds offsets to the authorized catalog snapshot and
  * query. Cursors confer no authority; the manager recalculates scope on
- * every request. Regional replicas share identity only under Qualla's
- * declared regional catalog and source-document naming convention.
+ * every request.
  */
 export class KnowledgeSpatialCursorError extends Error {
 }
@@ -24,10 +23,17 @@ export function nearbyCursorOffset(cursor, snapshot) {
         throw new KnowledgeSpatialCursorError('Invalid or stale nearby cursor; restart the query.');
     }
 }
-export function regionalDocumentIdentity(publisherId, catalogId, documentId) {
-    const regional = catalogId.startsWith('qualla-region-') &&
-        /^qualla-(wikipedia|wikivoyage)-[0-9]+$/.test(documentId);
-    return regional
+/**
+ * Source-article ids (`wikipedia-<page-id>`) name the same article in every
+ * catalog of one publisher, and regional catalogs overlap heavily — Pacific
+ * Northwest and Canada & Alaska share 683 of the former's 1,106 articles — so
+ * those copies are one result. Any other id is unique only within its catalog.
+ * Keyed on the id, not the catalog name: an earlier catalog-name match never
+ * fired for the published `regional-*` catalogs, so every copy came through.
+ */
+const SOURCE_ARTICLE_ID = /^(wikipedia|wikivoyage)-[0-9]+$/;
+export function spatialDocumentIdentity(publisherId, catalogId, documentId) {
+    return SOURCE_ARTICLE_ID.test(documentId)
         ? `${publisherId}\u0000${documentId}`
         : `${publisherId}\u0000${catalogId}\u0000${documentId}`;
 }

package/dist/knowledge/worker-host.js

@@ -141,6 +141,8 @@ export function createWorkerCatalogHost() {
         documentsPage: async (key, opts) => 
         // biome-ignore lint/suspicious/noExplicitAny: structured-clone round trip preserves the shape
         (await call('documentsPage', [key, opts])),
+        documentInitials: async (key, opts) => (await call('documentInitials', [key, opts])),
+        documentPosition: async (key, documentId, opts) => (await call('documentPosition', [key, documentId, opts])),
         nearbyDocuments: async (key, radius, opts) => (await call('nearbyDocuments', [key, radius, opts])),
         getDocument: async (key, documentId) => 
         // biome-ignore lint/suspicious/noExplicitAny: structured-clone round trip preserves the shape