@bendyline/gezel-inference 1.0.1 → 1.0.3

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);
@@ -1268,6 +1315,20 @@ export class KnowledgeManager {
             }
             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
@@ -1383,7 +1444,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);
@@ -1399,7 +1460,24 @@ export class KnowledgeManager {
                 continue;
             perCatalogCount.set(entry.catalogKey, count + 1);
             seenSpatial.add(spatialIdentity);
-            out.push({ ...result, ...matches.get(`${entry.catalogKey}\u0000${entry.documentId}`) });
+            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 = this.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(this.toResult(info, sibling, fusedRankRelevance(out.length), own));
+                if (out.length >= Math.max(10, opts.maxResults))
+                    break;
+            }
             if (out.length >= Math.max(10, opts.maxResults))
                 break;
         }

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

package/dist/memory/embed-core.d.ts

@@ -106,6 +106,22 @@ export declare function isRetryablePipelineLoadFailure(error: unknown): boolean;
  * will not parse is a runtime problem instead, and retrying cannot fix it.
  */
 export declare function isFreshDownloadFailure(error: unknown, graphVerified: boolean): boolean;
+/** Work abandoned because the host asked, at service shutdown. Not a model fault. */
+export declare class ModelWorkCancelledError extends Error {
+    constructor();
+}
+/**
+ * Abandon the model download in flight and stop embedding runs at their next
+ * sub-batch, so the worker reaches idle and can be terminated safely.
+ *
+ * Shutdown cannot simply terminate a busy worker (that aborts the process
+ * inside onnxruntime), and a first-run model download outlasted every drain:
+ * quitting during it held the app for 30 s, until the quit timeout. A download
+ * is plain network I/O, outside onnxruntime, so stopping it is safe; session
+ * creation and a single sub-batch still finish. Work that starts afterwards
+ * gets a fresh signal.
+ */
+export declare function cancelInFlightModelWork(): void;
 /** Lazily create the feature-extraction pipeline; cached for the process. */
 export declare function loadPipeline(): Promise<Pipeline>;
 /**

package/dist/memory/embed-core.js

@@ -191,6 +191,29 @@ export function isFreshDownloadFailure(error, graphVerified) {
 /** Fresh starts after a failed download, per process, before vector memory is switched off. */
 const MAX_FRESH_DOWNLOAD_RETRIES = 3;
 let freshDownloadFailures = 0;
+/** Work abandoned because the host asked, at service shutdown. Not a model fault. */
+export class ModelWorkCancelledError extends Error {
+    constructor() {
+        super('model work was cancelled for shutdown');
+        this.name = 'ModelWorkCancelledError';
+    }
+}
+let cancelController = new AbortController();
+/**
+ * Abandon the model download in flight and stop embedding runs at their next
+ * sub-batch, so the worker reaches idle and can be terminated safely.
+ *
+ * Shutdown cannot simply terminate a busy worker (that aborts the process
+ * inside onnxruntime), and a first-run model download outlasted every drain:
+ * quitting during it held the app for 30 s, until the quit timeout. A download
+ * is plain network I/O, outside onnxruntime, so stopping it is safe; session
+ * creation and a single sub-batch still finish. Work that starts afterwards
+ * gets a fresh signal.
+ */
+export function cancelInFlightModelWork() {
+    cancelController.abort();
+    cancelController = new AbortController();
+}
 /** The daemon pin's ONNX graph, when it names one with a digest. */
 function pinnedGraph() {
     const pin = daemonEmbedderPin();
@@ -203,6 +226,7 @@ let pipelinePromise = null;
 /** Lazily create the feature-extraction pipeline; cached for the process. */
 export async function loadPipeline() {
     if (!pipelinePromise) {
+        const signal = cancelController.signal;
         pipelinePromise = (async () => {
             let graphVerified = false;
             try {
@@ -230,6 +254,7 @@ export async function loadPipeline() {
                         const outcome = await ensureVerifiedModelFile(cacheDir, modelId, graph, {
                             remoteHost: env.remoteHost,
                             remotePathTemplate: env.remotePathTemplate,
+                            signal,
                         });
                         graphVerified = true;
                         if (outcome === 'downloaded')
@@ -241,6 +266,9 @@ export async function loadPipeline() {
                 });
             }
             catch (err) {
+                // Before the retry bookkeeping: a cancelled download is not a failed one.
+                if (signal.aborted)
+                    throw new ModelWorkCancelledError();
                 const missing = isMissingModule(err, TRANSFORMERS_MODULE);
                 const message = missing
                     ? 'Local memory embeddings are an optional npm feature. Install @huggingface/transformers@^4.3.1 alongside @bendyline/gezel-service (see the service README).'
@@ -272,9 +300,12 @@ export async function loadPipeline() {
 export async function runEmbed(texts) {
     if (texts.length === 0)
         return [];
+    const signal = cancelController.signal;
     const pipe = await loadPipeline();
     const out = [];
     for (let i = 0; i < texts.length; i += MAX_BATCH) {
+        if (signal.aborted)
+            throw new ModelWorkCancelledError();
         const slice = texts.slice(i, i + MAX_BATCH).map(capText);
         const result = await pipe(slice, { pooling: 'mean', normalize: true });
         for (const v of result.tolist())

package/dist/memory/embed-worker.d.ts

@@ -11,13 +11,17 @@
  *                                                     with that profile;
  *                                                     reportProgress: send the
  *                                                     model download's bytes
+ *                   { cancel: true }                — shutdown: stop the
+ *                                                     download and runs in flight
  *   worker → host:  { id, progress }                — interim, zero or more
  *                   { id, vectors }                 — success
  *                   { id, error, fatal,             — failure (fatal ⇒ model
- *                     retryable, optionalPeerMissing } unloadable, disable for
- *                                                     good; optionalPeerMissing
+ *                     retryable, optionalPeerMissing, unloadable, disable for
+ *                     cancelled }                     good; optionalPeerMissing
  *                                                     ⇒ the peer is just not
  *                                                     installed; retryable ⇒ a
- *                                                     short host-side cooldown)
+ *                                                     short host-side cooldown;
+ *                                                     cancelled ⇒ stopped by a
+ *                                                     cancel, not a fault)
  */
 export {};

package/dist/memory/embed-worker.js

@@ -11,22 +11,30 @@
  *                                                     with that profile;
  *                                                     reportProgress: send the
  *                                                     model download's bytes
+ *                   { cancel: true }                — shutdown: stop the
+ *                                                     download and runs in flight
  *   worker → host:  { id, progress }                — interim, zero or more
  *                   { id, vectors }                 — success
  *                   { id, error, fatal,             — failure (fatal ⇒ model
- *                     retryable, optionalPeerMissing } unloadable, disable for
- *                                                     good; optionalPeerMissing
+ *                     retryable, optionalPeerMissing, unloadable, disable for
+ *                     cancelled }                     good; optionalPeerMissing
  *                                                     ⇒ the peer is just not
  *                                                     installed; retryable ⇒ a
- *                                                     short host-side cooldown)
+ *                                                     short host-side cooldown;
+ *                                                     cancelled ⇒ stopped by a
+ *                                                     cancel, not a fault)
  */
 import { parentPort } from 'node:worker_threads';
-import { PipelineLoadError, runEmbed, runProfileQueryEmbed } from './embed-core.js';
+import { ModelWorkCancelledError, PipelineLoadError, cancelInFlightModelWork, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
 if (!parentPort) {
     throw new Error('embed-worker must be run as a worker thread');
 }
 const port = parentPort;
 port.on('message', (msg) => {
+    if ('cancel' in msg) {
+        cancelInFlightModelWork();
+        return;
+    }
     void (async () => {
         try {
             const vectors = msg.profile
@@ -43,6 +51,7 @@ port.on('message', (msg) => {
                 fatal: err instanceof PipelineLoadError && !err.retryable,
                 retryable: err instanceof PipelineLoadError && err.retryable,
                 optionalPeerMissing: err instanceof PipelineLoadError && err.optionalPeerMissing,
+                cancelled: err instanceof ModelWorkCancelledError,
             });
         }
     })();

package/dist/memory/embeddings.d.ts

@@ -35,6 +35,15 @@ export declare class EmbeddingsUnavailableError extends EmbeddingsDisabledError
     readonly retryable = true;
     constructor(reason: string);
 }
+/**
+ * The service is stopping. Callers that keep per-item retry budgets check
+ * `shuttingDown` so a quit never counts against a file the way a real model
+ * failure does.
+ */
+export declare class EmbeddingsShuttingDownError extends EmbeddingsUnavailableError {
+    readonly shuttingDown = true;
+    constructor();
+}
 export type EmbeddingPipelineStatus = 'cold' | 'warming' | 'ready' | 'disabled' | 'unavailable';
 export declare function embeddingsDisabledReason(): string | null;
 export declare function embeddingPipelineStatus(): EmbeddingPipelineStatus;
@@ -49,8 +58,14 @@ export declare function embeddingsHealth(): {
 };
 /**
  * Close for service shutdown: refuse new work (it would start a worker, or
- * load the model in-process, as the process exits), then terminate the worker
- * once its in-flight work has finished, waiting at most `drainMs`.
+ * load the model in-process, as the process exits), cancel what is in flight,
+ * then terminate the worker once it is idle, waiting at most `drainMs`.
+ *
+ * The cancel is what makes the wait short: a first-run model download stops at
+ * once, and an embedding run stops at its next sub-batch. Without it the drain
+ * expired with the download still going, and every caller awaiting that
+ * embedding (index enrichment among them) held shutdown until the app's quit
+ * timeout.
  */
 export declare function shutdownEmbeddings(drainMs: number): Promise<void>;
 /** Reopen after shutdown — an embedded service can be started again in the same process. */

package/dist/memory/embeddings.js

@@ -21,7 +21,7 @@ import { Worker } from 'node:worker_threads';
 import { createLogger, sameVectorSpace } from '@bendyline/gezel';
 import { retireModelWorker } from '../utils/retire-model-worker.js';
 import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
-import { PipelineLoadError, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
+import { ModelWorkCancelledError, PipelineLoadError, cancelInFlightModelWork, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
 const log = createLogger('memory');
 /**
  * Marker class so callers can tell "the indexer is off on purpose" apart from a
@@ -46,6 +46,18 @@ export class EmbeddingsUnavailableError extends EmbeddingsDisabledError {
         this.message = `memory embeddings temporarily unavailable: ${reason}`;
     }
 }
+/**
+ * The service is stopping. Callers that keep per-item retry budgets check
+ * `shuttingDown` so a quit never counts against a file the way a real model
+ * failure does.
+ */
+export class EmbeddingsShuttingDownError extends EmbeddingsUnavailableError {
+    shuttingDown = true;
+    constructor() {
+        super('the service is shutting down');
+        this.name = 'EmbeddingsShuttingDownError';
+    }
+}
 // Once the model fails to load, we permanently flip into a disabled state.
 // Every subsequent call throws the short marker error instead of re-attempting
 // the import and re-printing the full model-load error on every chat turn.
@@ -142,6 +154,11 @@ function onMessage(msg) {
     pending.delete(msg.id);
     if (pending.size === 0)
         worker?.unref();
+    if (msg.cancelled) {
+        // Our own shutdown cancel: no cooldown, no profile outage, nothing disabled.
+        p.reject(new EmbeddingsShuttingDownError());
+        return;
+    }
     if (msg.error) {
         if (p.profileId) {
             if (!p.localFilesOnly && (msg.fatal || msg.retryable))
@@ -214,6 +231,8 @@ async function embedInProcess(texts) {
         return await runEmbed(texts);
     }
     catch (err) {
+        if (err instanceof ModelWorkCancelledError)
+            throw new EmbeddingsShuttingDownError();
         if (err instanceof PipelineLoadError) {
             if (err.retryable) {
                 markTemporarilyUnavailable(err.message);
@@ -256,17 +275,27 @@ function markDisabled(message, optionalPeerMissing = false) {
     log.error('[memory] failed to load embedding pipeline; vector memory is now disabled for this process.');
     log.error('[memory] underlying error:', message);
 }
-const SHUTTING_DOWN = 'the service is shutting down';
 /**
  * Close for service shutdown: refuse new work (it would start a worker, or
- * load the model in-process, as the process exits), then terminate the worker
- * once its in-flight work has finished, waiting at most `drainMs`.
+ * load the model in-process, as the process exits), cancel what is in flight,
+ * then terminate the worker once it is idle, waiting at most `drainMs`.
+ *
+ * The cancel is what makes the wait short: a first-run model download stops at
+ * once, and an embedding run stops at its next sub-batch. Without it the drain
+ * expired with the download still going, and every caller awaiting that
+ * embedding (index enrichment among them) held shutdown until the app's quit
+ * timeout.
  */
 export async function shutdownEmbeddings(drainMs) {
     closed = true;
     const w = worker;
-    if (!w)
+    if (!w) {
+        // In-process fallback: any run in flight is on this thread.
+        cancelInFlightModelWork();
         return;
+    }
+    if (pending.size > 0)
+        w.postMessage({ cancel: true });
     if (await retireModelWorker(w, () => pending.size === 0, drainMs)) {
         if (worker === w)
             worker = null;
@@ -281,7 +310,7 @@ export function openEmbeddings() {
 /** Embed `texts`, preferring the worker and degrading to in-process. */
 async function embedMany(texts) {
     if (closed)
-        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+        throw new EmbeddingsShuttingDownError();
     if (disabledByEnv())
         throw new EmbeddingsDisabledError(ENV_DISABLED_REASON);
     if (disabledReason)
@@ -368,7 +397,7 @@ export function sharesDaemonEmbedder(profile) {
 export async function embedKnowledgeQuery(text, profile, opts = {}) {
     const { onDownloadProgress, localFilesOnly = false } = opts;
     if (closed)
-        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+        throw new EmbeddingsShuttingDownError();
     // The default daemon pipeline may fetch weights on a cold load.
     if (!localFilesOnly && sharesDaemonEmbedder(profile)) {
         const vector = await embedQuery(text);

package/dist/models/ensure.d.ts

@@ -111,6 +111,8 @@ export interface CreateEnsureModelOptions {
         backend: EnsureBackend;
         catalogId: string;
     }) => void;
+    /** Test seam for catalog backend exclusions — defaults to the process's own. */
+    resolveLlamaBackend?: () => string | undefined;
 }
 /**
  * Parse a qualified id (`<backend>:<catalogId>`) into its parts. Bare

package/dist/models/ensure.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { llamaCppBackendExclusion, llamaCppBackendLabel } from '@bendyline/gezel';
+import { currentLlamaCppBackend } from '../providers/llama-cpp/backend-health.js';
 /**
  * Error class with a structured `code` so the route can pick the
  * right HTTP status. Avoids regex-matching error message strings.
@@ -160,6 +162,13 @@ export async function createEnsureModelOrchestrator(opts) {
                 ].filter((id) => Boolean(id));
                 throw new KnownEnsureError('no_source_for_backend', `chat-model "${catalogId}" has no ${backend} source${alternatives.length > 0 ? ` — try ${alternatives.map((id) => `"${id}"`).join(' or ')}` : ''}`);
             }
+            if (backend === 'llama-cpp') {
+                const engineBackend = (opts.resolveLlamaBackend ?? currentLlamaCppBackend)();
+                const excluded = llamaCppBackendExclusion(detail.manifest.llamaCpp, engineBackend);
+                if (excluded && engineBackend) {
+                    throw new KnownEnsureError('no_source_for_backend', `chat-model "${catalogId}" is not available on the ${llamaCppBackendLabel(engineBackend)} llama.cpp engine: ${excluded}${detail.manifest.mlx ? ` Try "mlx:${catalogId}".` : ''}`);
+                }
+            }
             if (await isInstalled(backend, catalogId)) {
                 return { status: 'ready', modelId: qualifiedModelId };
             }

package/dist/perf/responsiveness.d.ts

@@ -2,7 +2,7 @@ import { type ClientPerfReport, type PerfSnapshot, type PerfWork } from '@bendyl
 /**
  * A gap is measured to within one beat, so this has to stay well inside
  * `STALL_RECORD_MS`. At the same period, a pause long enough to log leaves the
- * watchdog late by more than half the gap, which is what `isMainThreadBlock`
+ * watchdog late by more than half the heartbeat's lateness, which is what `isMainThreadBlock`
  * needs to rule the main thread out.
  */
 export declare const BEAT_MS = 250;
@@ -18,8 +18,21 @@ interface WatchdogReport {
  * A stale heartbeat is a main-thread block only when the watchdog itself kept
  * time. When the watchdog was late by a comparable amount, the process or the
  * host was paused, and blaming whatever was in flight would be a false lead.
+ *
+ * Lateness against lateness: both threads sleep a beat between checks, so a
+ * pause delays each by about its length. Comparing the watchdog's lateness
+ * with the whole gap, beat included, filed short pauses as blocks.
  */
 export declare function isMainThreadBlock(report: WatchdogReport): boolean;
+/** What a gap cost: the main thread's CPU, and the process's major page faults. */
+export interface StallCost {
+    /** Null where the runtime has no per-thread CPU accounting. */
+    cpuMs: number | null;
+    pageFaults: number;
+}
+/** Running code when it used at least half the stall; otherwise paging or waiting on something. */
+export declare function stallVerdict(durationMs: number, cost: StallCost): 'running code' | 'paging' | 'blocked waiting' | undefined;
+export declare function describeStallCost(durationMs: number, cost: StallCost): string;
 interface ActiveWork {
     label: string;
     startedAt: number;