@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/memory/embed-core.js

@@ -0,0 +1,398 @@
+/**
+ * Core embedding inference, shared by the worker-thread host and the
+ * in-process fallback (see embeddings.ts). Loads the transformers.js
+ * feature-extraction pipeline (all-MiniLM-L6-v2, 384-dim) lazily and runs it
+ * in BOUNDED sub-batches.
+ *
+ * The sub-batching is the fix for the crash that took down the Electron main
+ * process: `enrichFile` embeds every chunk of a file in one call, and a large
+ * doc produces hundreds of chunks. transformers.js pads the whole batch to its
+ * longest sequence and hands ONNX a single tensor whose size scales with the
+ * batch, so a many-chunk file triggered a multi-gigabyte allocation in
+ * `onnxruntime::BFCArena::Extend` → `posix_memalign` → SIGTRAP. Capping the
+ * batch bounds peak allocation regardless of how many texts a caller passes.
+ */
+import { createHash } from 'node:crypto';
+import { createLogger, embeddingProfileArtifacts, } from '@bendyline/gezel';
+import { EmbedderUnavailableError, KNOWLEDGE_EMBEDDING_PROFILES, createProfileEmbedder, resolveTransformersModelOptions, verifyProfileArtifacts, } from '@bendyline/gezel-knowledge';
+import { HF_CACHE_DIR_ENV, ModelFileDownloadError, TRANSFORMERS_MODULE, ensureVerifiedModelFile, isCorruptTransformersCacheFailure, isMissingModule, loadTransformersModelWithCacheRecovery, pinTransformersCacheDir, } from '../transformers-cache.js';
+export const log = createLogger('memory');
+/**
+ * Max texts handed to a single ONNX `Run`. The sub-batch is padded to its
+ * longest sequence (≤ the model's 512-token window), so peak transient memory
+ * is ~MAX_BATCH × 512² × heads × 4B. 8 keeps that comfortably under ~150 MB no
+ * matter how many chunks a file produces. Sub-batching does not change the
+ * per-text output — mean-pooling + normalize are per-text and attention masks
+ * ignore padding — so vectors are bit-identical to a single big batch.
+ */
+const MAX_BATCH = 8;
+/**
+ * Hard char cap per text before tokenization. The tokenizer already truncates
+ * to the model's 512-token window, but a pathologically large chunk (e.g. a
+ * minified blob that slipped past the indexer's 4 KB-per-chunk cap) would still
+ * cost O(n) just to tokenize. 8 KB ≈ 2 K tokens, well above the 512 the model
+ * keeps, so this only ever trims genuine outliers.
+ */
+const MAX_CHARS = 8_000;
+/**
+ * Feature-extraction model. Default bge-small-en-v1.5 (384-dim) — the
+ * index-bench embedding A/B measured it at semantic recall@5 75% vs MiniLM-L6's
+ * 50% on the squisq corpus (evals/runs/INDEX-BENCH-2026-07-06.md). Overridable
+ * via `GEZEL_EMBED_MODEL`; any transformers.js feature-extraction model works.
+ * A same-dim swap (MiniLM, gte-small, bge-small are all 384) is a pure drop-in;
+ * a different dim needs `GEZEL_EMBED_DIM` set. Existing indexes stamp the
+ * embedder and re-embed on a model change (content: IndexStore.open's
+ * `reconcileEmbedModel`; memory: MemoryHealthMonitor via the mem_meta stamp) —
+ * they're regenerable caches, so the cutover costs a one-time re-embed (no
+ * re-summarize; enrichFile reuses stored summaries).
+ */
+const DEFAULT_EMBED_MODEL = 'Xenova/bge-small-en-v1.5';
+export function embedModelId() {
+    return process.env.GEZEL_EMBED_MODEL || DEFAULT_EMBED_MODEL;
+}
+/**
+ * The registered knowledge profile the daemon's own model IS, when the
+ * configured model is one of them (the default bge install; `null` for a
+ * custom `GEZEL_EMBED_MODEL`). The pin fixes how the pipeline is loaded —
+ * the exact graph and precision, never a runtime default — and, once its
+ * cached files hash to the pin's digests, lets knowledge catalogs in that
+ * profile reuse the daemon's query vectors instead of loading a second copy.
+ */
+export function daemonEmbedderPin() {
+    const modelId = embedModelId();
+    return KNOWLEDGE_EMBEDDING_PROFILES.find((p) => p.model.repo === modelId) ?? null;
+}
+/**
+ * Load options for the daemon's own pipeline. A pinned model names its graph
+ * and precision explicitly (`onnx/model.onnx`, fp32 — what transformers.js
+ * happens to default to on Node, now stated rather than assumed). The
+ * revision stays `main` on purpose: pinning it would change the cache key
+ * and re-download the model on every existing install, while the digest
+ * check in `daemonEmbedderVerified` already proves the bytes are the pin's.
+ */
+function daemonLoadOptions() {
+    const pin = daemonEmbedderPin();
+    if (!pin)
+        return {};
+    const { dtype, subfolder, model_file_name } = resolveTransformersModelOptions(pin);
+    return { dtype, subfolder, model_file_name };
+}
+/**
+ * Asymmetric-retrieval query prefix. The bge-* family was trained with a
+ * query-side instruction ("Represent this sentence for searching relevant
+ * passages:") prepended to the *query* only — passages (the indexed chunks)
+ * get none. Applying it lifts retrieval on the model's own benchmark; our
+ * initial bge promotion measured recall WITHOUT it, so this is pure upside on
+ * top. Returns '' for models that weren't trained this way (MiniLM, gte-small
+ * are symmetric) so `embed`/`embedQuery` collapse to identical behavior there.
+ * `GEZEL_EMBED_NO_QUERY_INSTRUCTION=1` disables it for A/B isolation.
+ */
+export function queryInstruction() {
+    if (process.env.GEZEL_EMBED_NO_QUERY_INSTRUCTION === '1')
+        return '';
+    const model = embedModelId();
+    if (/bge-/i.test(model))
+        return 'Represent this sentence for searching relevant passages: ';
+    // The e5 family (incl. multilingual-e5-*) is trained with BOTH sides
+    // prefixed — "query: " / "passage: " — and measurably underperforms
+    // without them (its model card calls unprefixed use an error).
+    if (/(^|\/|-)e5-/i.test(model) || /multilingual-e5/i.test(model))
+        return 'query: ';
+    return '';
+}
+/**
+ * Passage-side counterpart to {@link queryInstruction}. Empty for every
+ * model family except e5, whose training prefixes BOTH sides; bge prefixes
+ * only queries, and symmetric models (MiniLM, gte) prefix nothing — so the
+ * default install's behavior is unchanged by this hook existing.
+ */
+export function passageInstruction() {
+    if (process.env.GEZEL_EMBED_NO_QUERY_INSTRUCTION === '1')
+        return '';
+    const model = embedModelId();
+    if (/(^|\/|-)e5-/i.test(model) || /multilingual-e5/i.test(model))
+        return 'passage: ';
+    return '';
+}
+/**
+ * The full embedding-profile identity — everything that determines whether
+ * two stored vectors live in the same space: model id, dimension, pooling,
+ * normalization, and BOTH instruction prefixes (hashed — an instruction
+ * change silently changes vectors, which the bare model-id stamp never
+ * caught; audit finding C5). This string is what the reconcile-on-mismatch
+ * stamps compare (content index `meta.embed_model`, memory `mem_meta`), so
+ * a dim/pooling/prefix change now correctly invalidates vectors the same
+ * way a model swap always has. Old bare-model-id stamps mismatch once and
+ * trigger the already-supported drop-and-re-embed.
+ *
+ * Pooling and normalization are compile-time constants of this pipeline
+ * (`runEmbed` always uses mean+normalize) — encoded literally so a future
+ * change to that call site is forced to bump the profile.
+ */
+export function embedProfileId() {
+    const sha8 = (s) => createHash('sha256').update(s, 'utf8').digest('hex').slice(0, 8);
+    const dim = Number(process.env.GEZEL_EMBED_DIM) || 384;
+    return `${embedModelId()}|d${dim}|mean|norm|q:${sha8(queryInstruction())}|p:${sha8(passageInstruction())}`;
+}
+/**
+ * Thrown when the model itself can't be loaded. Distinguished from a transient
+ * inference error so the host can permanently disable embeddings rather than
+ * retry the full failure on every chunk.
+ */
+export class PipelineLoadError extends Error {
+    code = 'PIPELINE_LOAD_FAILED';
+    /**
+     * The optional peer is simply not installed — a documented, supported npm
+     * configuration. Callers use this to degrade quietly instead of reporting a
+     * damaged runtime.
+     */
+    optionalPeerMissing;
+    /**
+     * Network/model-registry failures can clear without a process restart. The
+     * host uses this bit to apply a short retry cooldown instead of permanently
+     * disabling embeddings after one failed first-use download.
+     */
+    retryable;
+    constructor(message, optionalPeerMissing = false, retryable = false) {
+        super(message);
+        this.name = 'PipelineLoadError';
+        this.optionalPeerMissing = optionalPeerMissing;
+        this.retryable = retryable;
+    }
+}
+/**
+ * Keep the retry classification deliberately narrow. Bad model ids, missing
+ * native libraries, and incompatible runtimes need operator action; transport
+ * failures and registry throttling commonly recover on their own.
+ *
+ * The undici mid-stream abort family (`terminated`, `other side closed`,
+ * `premature close`, `aborted`) is here because its absence was a wild-caught
+ * product bug: a model download killed at ~103s surfaced as a bare
+ * `TypeError: terminated`, classified FATAL, and stickily disabled semantic
+ * search for the daemon's lifetime — silently, since search degrades to
+ * keyword instead of erroring (evals/runs/EMBED-CALIBRATION-2026-08-19.md).
+ */
+export function isRetryablePipelineLoadFailure(error) {
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    const code = error?.code ?? '';
+    return /(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|UND_ERR_|ERR_STREAM_PREMATURE_CLOSE|fetch failed|network(?: request)? failed|socket hang up|timed?\s*out|terminated|other side closed|premature close|aborted|HTTP\s+(?:408|425|429|5\d\d)|TLS|SSL|certificate)/i.test(`${code} ${message}`);
+}
+/**
+ * Whether a load died on a download it made itself — bytes that were cut
+ * short, or a graph that failed to parse right after being fetched. Those
+ * clear on a fresh attempt. A graph already proven against its pin that still
+ * will not parse is a runtime problem instead, and retrying cannot fix it.
+ */
+export function isFreshDownloadFailure(error, graphVerified) {
+    if (error instanceof ModelFileDownloadError)
+        return true;
+    return !graphVerified && isCorruptTransformersCacheFailure(error);
+}
+/** Fresh starts after a failed download, per process, before vector memory is switched off. */
+const MAX_FRESH_DOWNLOAD_RETRIES = 3;
+let freshDownloadFailures = 0;
+/** The daemon pin's ONNX graph, when it names one with a digest. */
+function pinnedGraph() {
+    const pin = daemonEmbedderPin();
+    if (!pin)
+        return null;
+    const { onnxFile, onnxDigest } = embeddingProfileArtifacts(pin);
+    return onnxDigest ? { file: onnxFile, digest: onnxDigest, revision: pin.model.revision } : null;
+}
+let pipelinePromise = null;
+/** Lazily create the feature-extraction pipeline; cached for the process. */
+export async function loadPipeline() {
+    if (!pipelinePromise) {
+        pipelinePromise = (async () => {
+            let graphVerified = false;
+            try {
+                // Pin transformers.js to gezel's writable managed cache dir before
+                // the first load. Without it, a bundled runtime's default (module-
+                // relative, read-only) cache makes the model download fail to cache
+                // and throws "Unable to get model file path or buffer". The dir is
+                // passed via env so this works in the embed worker thread too, which
+                // inherits `process.env` but has no other view of the gezel home.
+                const cacheDir = process.env[HF_CACHE_DIR_ENV];
+                if (cacheDir)
+                    await pinTransformersCacheDir(cacheDir);
+                const { pipeline, env } = await import('@huggingface/transformers');
+                const modelId = embedModelId();
+                if (modelId !== DEFAULT_EMBED_MODEL)
+                    log.info(`[embed] using model ${modelId}`);
+                const createPipeline = () => pipeline('feature-extraction', modelId, daemonLoadOptions());
+                if (!cacheDir)
+                    return await createPipeline();
+                const graph = pinnedGraph();
+                return await loadTransformersModelWithCacheRecovery(cacheDir, modelId, async () => {
+                    // The graph is the one file onnxruntime opens by path, so it
+                    // must never be read while transformers is still writing it.
+                    if (graph) {
+                        const outcome = await ensureVerifiedModelFile(cacheDir, modelId, graph, {
+                            remoteHost: env.remoteHost,
+                            remotePathTemplate: env.remotePathTemplate,
+                        });
+                        graphVerified = true;
+                        if (outcome === 'downloaded')
+                            log.info(`[embed] downloaded ${modelId}/${graph.file}`);
+                    }
+                    return await createPipeline();
+                }, () => {
+                    log.warn(`[embed] discarded corrupt cached model files for ${modelId}; retrying once`);
+                });
+            }
+            catch (err) {
+                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).'
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                let retryable = !missing && isRetryablePipelineLoadFailure(err);
+                if (!missing && !retryable && isFreshDownloadFailure(err, graphVerified)) {
+                    freshDownloadFailures += 1;
+                    retryable = freshDownloadFailures <= MAX_FRESH_DOWNLOAD_RETRIES;
+                }
+                throw new PipelineLoadError(message, missing, retryable);
+            }
+        })();
+        // A transient load failure (e.g. network blip during the first download)
+        // shouldn't wedge the process forever — drop the rejected promise so a
+        // later call can retry. Permanent failures are made sticky by the host.
+        pipelinePromise.catch(() => {
+            pipelinePromise = null;
+        });
+    }
+    return pipelinePromise;
+}
+/**
+ * Embed `texts` into 384-dim unit vectors — one per input, order-preserving.
+ * Runs in sub-batches of at most MAX_BATCH so peak ONNX allocation stays
+ * bounded no matter how many texts are passed in one call.
+ */
+export async function runEmbed(texts) {
+    if (texts.length === 0)
+        return [];
+    const pipe = await loadPipeline();
+    const out = [];
+    for (let i = 0; i < texts.length; i += MAX_BATCH) {
+        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())
+            out.push(v);
+    }
+    return out;
+}
+let daemonVerification = null;
+/**
+ * Whether the files behind the daemon's own pipeline hash to its pin's
+ * digests. Call it after the pipeline has embedded once, so the cache is
+ * populated wherever the pipeline lives (the worker's cache dir is this
+ * process's). Checked once per process: the cached files do not change
+ * underneath a running daemon, and hashing the graph is not free.
+ */
+export function daemonEmbedderVerified() {
+    if (!daemonVerification)
+        daemonVerification = verifyDaemonPipeline();
+    return daemonVerification;
+}
+/** Test seam: forget the memoized verdict. */
+export function resetDaemonEmbedderVerification() {
+    daemonVerification = null;
+}
+async function verifyDaemonPipeline() {
+    const pin = daemonEmbedderPin();
+    if (!pin)
+        return false;
+    try {
+        const cacheDir = process.env[HF_CACHE_DIR_ENV] ?? (await defaultTransformersCacheDir());
+        const result = await verifyProfileArtifacts(pin, { cacheDir, revision: 'main' });
+        if (result.status !== 'verified')
+            return false;
+        log.info(`[embed] ${pin.id}: the daemon's model files match the profile pin`);
+        return true;
+    }
+    catch (err) {
+        log.warn(`[embed] ${pin.id}: the daemon's model files do not verify against the profile pin, so knowledge catalogs load their own pinned copy: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+async function defaultTransformersCacheDir() {
+    const { env } = await import('@huggingface/transformers');
+    // 4.x types it nullable: null only where there is no filesystem cache.
+    return env.cacheDir ?? '';
+}
+// ── knowledge-catalog profiles ─────────────────────────────────────────────
+//
+// A catalog searches in the vector space its publisher embedded it in. When
+// that is not the daemon's own model (a multilingual public catalog on a
+// default bge install), the query must be embedded by the catalog's profile —
+// same repo, same pinned revision, same graph, same instruction prefix — or
+// the vectors never meet. Profiles load lazily, are cached per id, verify
+// their files against the profile's digests, and are dropped after idling so
+// a second ONNX session does not stay resident forever.
+const PROFILE_IDLE_MS = 10 * 60 * 1000;
+const profileEmbedders = new Map();
+function armIdleDisposal(id, entry) {
+    if (entry.idleTimer)
+        clearTimeout(entry.idleTimer);
+    entry.idleTimer = setTimeout(() => {
+        profileEmbedders.delete(id);
+        void entry.promise.then((embedder) => embedder.dispose()).catch(() => { });
+    }, PROFILE_IDLE_MS);
+    entry.idleTimer.unref();
+}
+/** Load (and cache) a catalog profile's embedder; typed load failures like the default pipeline's. */
+export async function loadProfileEmbedder(profile, onDownloadProgress, localFilesOnly = false) {
+    let entry = profileEmbedders.get(profile.id);
+    if (!entry) {
+        const cacheDir = process.env[HF_CACHE_DIR_ENV];
+        const progressListeners = new Set();
+        const promise = createProfileEmbedder(profile, {
+            localFilesOnly,
+            ...(cacheDir ? { cacheDir } : {}),
+            onDownloadProgress: (progress) => {
+                for (const listener of progressListeners)
+                    listener(progress);
+            },
+        }).catch((err) => {
+            profileEmbedders.delete(profile.id);
+            if (err instanceof PipelineLoadError)
+                throw err;
+            const missing = err instanceof EmbedderUnavailableError || isMissingModule(err, TRANSFORMERS_MODULE);
+            throw new PipelineLoadError(err instanceof Error ? err.message : String(err), missing, !missing && isRetryablePipelineLoadFailure(err));
+        });
+        entry = { promise, progressListeners };
+        profileEmbedders.set(profile.id, entry);
+        log.info(`[embed] loading knowledge profile ${profile.id} (${profile.model.repo})`);
+    }
+    armIdleDisposal(profile.id, entry);
+    if (!onDownloadProgress)
+        return entry.promise;
+    const { progressListeners } = entry;
+    progressListeners.add(onDownloadProgress);
+    try {
+        return await entry.promise;
+    }
+    finally {
+        progressListeners.delete(onDownloadProgress);
+    }
+}
+/** Embed SEARCH QUERIES with a catalog's own profile (its query instruction applied). */
+export async function runProfileQueryEmbed(texts, profile, onDownloadProgress, localFilesOnly = false) {
+    if (texts.length === 0)
+        return [];
+    const embedder = await loadProfileEmbedder(profile, onDownloadProgress, localFilesOnly);
+    const out = [];
+    for (const text of texts)
+        out.push(Array.from(await embedder.embedQuery(capText(text))));
+    return out;
+}
+/** Bound a single text's length, and stand in for an empty string. */
+function capText(s) {
+    // The tokenizer is unhappy with an empty string inside a padded batch; a
+    // single space is a near-zero-cost stand-in that still yields a valid vector
+    // (callers get a deterministic vector back rather than a thrown batch).
+    if (!s)
+        return ' ';
+    return s.length > MAX_CHARS ? s.slice(0, MAX_CHARS) : s;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Worker-thread host for embedding inference. Runs the transformers.js /
+ * onnxruntime pipeline OFF the Electron main thread so the synchronous native
+ * `InferenceSession.Run` — which used to execute on `CrBrowserMain` and, on a
+ * large allocation, trapped and killed the whole app — now executes here. A
+ * long enrichment batch also no longer janks the UI.
+ *
+ * Protocol (structured-clone messages over the worker port):
+ *   host → worker:  { id, texts, profile?,          — profile: embed as a
+ *                     reportProgress? }               knowledge-catalog QUERY
+ *                                                     with that profile;
+ *                                                     reportProgress: send the
+ *                                                     model download's bytes
+ *   worker → host:  { id, progress }                — interim, zero or more
+ *                   { id, vectors }                 — success
+ *                   { id, error, fatal,             — failure (fatal ⇒ model
+ *                     retryable, optionalPeerMissing } unloadable, disable for
+ *                                                     good; optionalPeerMissing
+ *                                                     ⇒ the peer is just not
+ *                                                     installed; retryable ⇒ a
+ *                                                     short host-side cooldown)
+ */
+export {};

package/dist/memory/embed-worker.js

@@ -0,0 +1,49 @@
+/**
+ * Worker-thread host for embedding inference. Runs the transformers.js /
+ * onnxruntime pipeline OFF the Electron main thread so the synchronous native
+ * `InferenceSession.Run` — which used to execute on `CrBrowserMain` and, on a
+ * large allocation, trapped and killed the whole app — now executes here. A
+ * long enrichment batch also no longer janks the UI.
+ *
+ * Protocol (structured-clone messages over the worker port):
+ *   host → worker:  { id, texts, profile?,          — profile: embed as a
+ *                     reportProgress? }               knowledge-catalog QUERY
+ *                                                     with that profile;
+ *                                                     reportProgress: send the
+ *                                                     model download's bytes
+ *   worker → host:  { id, progress }                — interim, zero or more
+ *                   { id, vectors }                 — success
+ *                   { id, error, fatal,             — failure (fatal ⇒ model
+ *                     retryable, optionalPeerMissing } unloadable, disable for
+ *                                                     good; optionalPeerMissing
+ *                                                     ⇒ the peer is just not
+ *                                                     installed; retryable ⇒ a
+ *                                                     short host-side cooldown)
+ */
+import { parentPort } from 'node:worker_threads';
+import { PipelineLoadError, 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) => {
+    void (async () => {
+        try {
+            const vectors = msg.profile
+                ? await runProfileQueryEmbed(msg.texts, msg.profile, msg.reportProgress
+                    ? (progress) => port.postMessage({ id: msg.id, progress })
+                    : undefined, msg.localFilesOnly)
+                : await runEmbed(msg.texts);
+            port.postMessage({ id: msg.id, vectors });
+        }
+        catch (err) {
+            port.postMessage({
+                id: msg.id,
+                error: err instanceof Error ? err.message : String(err),
+                fatal: err instanceof PipelineLoadError && !err.retryable,
+                retryable: err instanceof PipelineLoadError && err.retryable,
+                optionalPeerMissing: err instanceof PipelineLoadError && err.optionalPeerMissing,
+            });
+        }
+    })();
+});

package/dist/memory/embeddings.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Public embedding API. Generates 384-dimensional vectors from text using a
+ * local transformers.js model (all-MiniLM-L6-v2) — runs entirely on-device, no
+ * API keys. The model downloads on first use (~23 MB) and is cached in the OS
+ * cache directory.
+ *
+ * Two robustness properties live here, both added after an out-of-memory in the
+ * model crashed the whole Electron app (a many-chunk file made ONNX attempt a
+ * multi-gigabyte allocation in `BFCArena::Extend`, which trapped — SIGTRAP — on
+ * the main thread):
+ *
+ *   1. Inference runs in BOUNDED sub-batches (see `embed-core`) so no single
+ *      ONNX `Run` can balloon, regardless of how many texts a caller passes.
+ *   2. Inference runs in a WORKER THREAD (`embed-worker`), keeping the heavy
+ *      synchronous native call off the Electron main/UI thread. When the worker
+ *      can't be created — under vitest there's no built worker file, and a raw
+ *      `new Worker('*.ts')` wouldn't load through vitest's transform — we
+ *      degrade to in-process inference, which is still bounded by (1).
+ */
+import { type KnowledgeEmbeddingProfile } from '@bendyline/gezel';
+import type { ModelDownloadProgress } from '@bendyline/gezel-knowledge';
+/**
+ * Marker class so callers can tell "the indexer is off on purpose" apart from a
+ * new failure worth logging. The extractor uses this to stay silent after the
+ * first failure.
+ */
+export declare class EmbeddingsDisabledError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(reason: string);
+}
+/** A recoverable model-load outage currently held behind a retry cooldown. */
+export declare class EmbeddingsUnavailableError extends EmbeddingsDisabledError {
+    readonly code = "EMBEDDINGS_UNAVAILABLE";
+    readonly retryable = true;
+    constructor(reason: string);
+}
+export type EmbeddingPipelineStatus = 'cold' | 'warming' | 'ready' | 'disabled' | 'unavailable';
+export declare function embeddingsDisabledReason(): string | null;
+export declare function embeddingPipelineStatus(): EmbeddingPipelineStatus;
+/**
+ * The status + reason pair as one wire-ready object — what `/api/health` and
+ * every project's `/index/status` surface so a dead embedder is
+ * distinguishable from an index that is merely still building.
+ */
+export declare function embeddingsHealth(): {
+    status: EmbeddingPipelineStatus;
+    reason?: string;
+};
+/**
+ * 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`.
+ */
+export declare function shutdownEmbeddings(drainMs: number): Promise<void>;
+/** Reopen after shutdown — an embedded service can be started again in the same process. */
+export declare function openEmbeddings(): void;
+/**
+ * True when a catalog's profile IS the daemon's own embedder — the same
+ * pinned model files, tokenizer, pooling, instruction and width — so query
+ * vectors from `embedQuery` can be reused without loading a second model.
+ * A bare repo-string match is not enough: an instruction-prefix or precision
+ * difference silently changes vectors. This is the declarative half; whether
+ * the daemon's cached files really are those bytes is `daemonEmbedderVerified`'s
+ * call, made once the pipeline has run.
+ */
+export declare function sharesDaemonEmbedder(profile: KnowledgeEmbeddingProfile): boolean;
+/**
+ * Embed a knowledge-catalog QUERY in the catalog's own vector space. Reuses
+ * the daemon pipeline when the profile matches it; otherwise loads the
+ * profile's model (worker-first, in-process fallback) under a per-profile
+ * outage cooldown, so one catalog's missing model never darkens the others.
+ */
+export declare function embedKnowledgeQuery(text: string, profile: KnowledgeEmbeddingProfile, opts?: {
+    onDownloadProgress?: (progress: ModelDownloadProgress) => void;
+    localFilesOnly?: boolean;
+}): Promise<number[]>;
+export declare function embed(text: string): Promise<number[]>;
+/**
+ * Embed a SEARCH QUERY. Same pipeline as `embed`, but prepends the model's
+ * query-side retrieval instruction when it has one (bge-*: an English
+ * instruction sentence; e5-*: "query: "); for symmetric models this is
+ * identical to `embed`. Indexed passages go through `embed`/`embedBatch`,
+ * which apply the PASSAGE-side prefix where the family has one (e5 only) —
+ * the asymmetry is the whole point. Every query-side call site (content
+ * search, memory recall, unified search) routes here so the prefixes stay in
+ * exactly one place. NOTE: this must NOT delegate to `embed`, which would
+ * stack the passage prefix onto the query.
+ */
+export declare function embedQuery(text: string): Promise<number[]>;
+export declare function embedBatch(texts: string[]): Promise<number[][]>;
+/**
+ * Load the embedding pipeline ahead of the first real caller.
+ *
+ * The model loads lazily on first use, and that load was measured at ~41s on
+ * a fresh install. Whoever arrives first pays it — and the unified search sits
+ * in the titlebar, so it was routinely the user's first keystroke, with the
+ * search box appearing to ignore them. The first chat turn loads the same
+ * pipeline for memory extraction anyway, so warming moves the cost off an
+ * interactive path rather than adding one.
+ *
+ * Never throws: embeddings being disabled or unavailable is a supported
+ * configuration, and the callers already degrade to keyword-only search.
+ */
+export declare function warmEmbeddings(): Promise<boolean>;