@atomic-chat/core 0.5.1 → 0.13.6

package/dist/embedding/readiness.js

@@ -0,0 +1,114 @@
+/**
+ * "Is this an embedding model I can serve?": `GET /health` answers 200, then one real
+ * `POST /v1/embeddings` of a single word answers vectors, then `GET /props` says what an input may
+ * hold. The vector's length is the model's (EmbeddingGemma 2's header says 512 where it answers 768),
+ * and the probe also warms the graph, so the first client request does not pay for it.
+ *
+ * `/health` answers 503 while the engine loads, so the chain is polled until the startup deadline.
+ * Only a clear verdict refuses: 501 on the probe is a server without `--embedding` (a stranger on the
+ * port, a build that ignored the flag), any other 4xx is the model itself refusing (a pooling the
+ * OpenAI endpoint cannot serve). A transport error, a timeout or a 5xx says nothing and counts as
+ * still loading. The parsers are pure; `checkEmbeddingReadiness` does one round over the injected HTTP.
+ */
+export const HEALTH_PATH = '/health';
+export const EMBEDDINGS_PATH = '/v1/embeddings';
+export const PROPS_PATH = '/props';
+/** Each readiness request on its own; the startup deadline bounds the whole wait. */
+export const READINESS_REQUEST_TIMEOUT_MS = 2_000;
+/** The probe runs the model once: the first pass compiles kernels on some GPUs. */
+export const PROBE_REQUEST_TIMEOUT_MS = 60_000;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The length of the first vector of an OpenAI embeddings answer; `undefined` when there is none. */
+export function dimsOf(body) {
+    const list = isRecord(body) ? body['data'] : undefined;
+    const first = Array.isArray(list) && isRecord(list[0]) ? list[0]['embedding'] : undefined;
+    return Array.isArray(first) && first.length > 0 ? first.length : undefined;
+}
+/** What one input may hold, from `/props.modalities`; text always. */
+export function modalitiesOf(props) {
+    const block = isRecord(props) ? props['modalities'] : undefined;
+    const out = ['text'];
+    if (!isRecord(block))
+        return out;
+    if (block['vision'] === true)
+        out.push('image');
+    if (block['audio'] === true)
+        out.push('audio');
+    if (block['video'] === true)
+        out.push('video');
+    return out;
+}
+/** The engine's own words from an error answer, for the details. */
+function engineMessage(text) {
+    const body = parseJson(text);
+    const error = isRecord(body) ? body['error'] : undefined;
+    const message = isRecord(error) ? error['message'] : undefined;
+    return typeof message === 'string' ? message : text.slice(0, 300);
+}
+/** The verdict on the probe and `/props` after health. Pure. `status: 0` is a transport error. */
+export function judgeEmbeddingProbe(probe, props) {
+    if (probe.status === 501)
+        return {
+            kind: 'unsupported',
+            detail: `${EMBEDDINGS_PATH} answered 501: ${engineMessage(probe.text)}`,
+        };
+    if (probe.status >= 400 && probe.status < 500)
+        return {
+            kind: 'refused',
+            detail: `${EMBEDDINGS_PATH} answered ${probe.status}: ${engineMessage(probe.text)}`,
+        };
+    if (probe.status !== 200)
+        return { kind: 'loading', detail: notAVerdict(EMBEDDINGS_PATH, probe) };
+    const dims = dimsOf(parseJson(probe.text));
+    if (dims === undefined)
+        return { kind: 'refused', detail: `${EMBEDDINGS_PATH} answered 200 without a vector` };
+    if (props.status !== 200)
+        return { kind: 'loading', detail: notAVerdict(PROPS_PATH, props) };
+    const body = parseJson(props.text);
+    if (body === undefined)
+        return { kind: 'loading', detail: notAVerdict(PROPS_PATH, props) };
+    return { kind: 'ready', dims, modalities: modalitiesOf(body) };
+}
+/** Why an answer is not a verdict, for the timeout's details. */
+function notAVerdict(path, answer) {
+    if (answer.status === 0)
+        return `${path}: ${answer.text}`;
+    if (answer.status !== 200)
+        return `${path} answered ${answer.status}`;
+    return `${path} answered 200 with a body that is not JSON`;
+}
+/**
+ * One round of the chain against `baseUrl`. A transport error or a request timeout is "still
+ * loading": the port may not be bound yet, or the engine is too busy loading to answer in time.
+ */
+export async function checkEmbeddingReadiness(http, baseUrl, apiKey, modelId, timeoutMs = READINESS_REQUEST_TIMEOUT_MS, probeTimeoutMs = PROBE_REQUEST_TIMEOUT_MS) {
+    const call = (path, method, body, timeout) => http
+        .request(`${baseUrl}${path}`, {
+        method,
+        apiKey,
+        timeoutMs: timeout,
+        ...(body !== undefined ? { body } : {}),
+    })
+        .catch((error) => ({
+        status: 0,
+        text: error instanceof Error ? error.message : String(error),
+    }));
+    const health = await call(HEALTH_PATH, 'GET', undefined, timeoutMs);
+    if (health.status !== 200)
+        return {
+            kind: 'loading',
+            detail: health.status === 0 ? health.text : `${HEALTH_PATH} answered ${health.status}`,
+        };
+    const probe = await call(EMBEDDINGS_PATH, 'POST', JSON.stringify({ input: ['ping'], model: modelId, encoding_format: 'float' }), probeTimeoutMs);
+    const props = probe.status === 200 ? await call(PROPS_PATH, 'GET', undefined, timeoutMs) : probe;
+    return judgeEmbeddingProbe(probe, props);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/embedding/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../src/embedding/readiness.ts"],"names":[],"mappings":"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"}

package/dist/embedding/request.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What the public `/v1/embeddings` checks before it passes a body to the embedding process. Pure.
+ *
+ * The body goes on as the client sent it; these checks only refuse:
+ *  - media by reference: llama-server fetches an `http(s)` URL itself (and a `file://` one with
+ *    `--media-path`), so an API open to the LAN would fetch whatever a client names. Only inline media
+ *    (`data:` URLs, bare base64) is passed;
+ *  - inline media the engine would fail to read for its form alone: no data, a `data:` URL it does not
+ *    parse, a placeholder, base64 it stops reading early (its decoder ends at the first character outside
+ *    the standard alphabet, so a line break or URL-safe base64 leaves a truncated file). The engine
+ *    answers each of these with a 500; a client error is a 400 that names the field;
+ *  - media the running model cannot read: the engine answers a 500 for it, a client error is a 400
+ *    (for video, which also needs `ffmpeg` on this computer, the message says so);
+ *  - a content part sent as an input of its own, outside `{content: [...]}`: llama.cpp refuses it
+ *    with a message about prompt shapes, this one names the fix;
+ *  - a `dimensions` the model does not produce: the engine ignores the field, and a client that asked
+ *    for 256 numbers would store 768 without knowing (the model's shorter Matryoshka lengths are the
+ *    client's to cut, as the app's catalog says).
+ *
+ * Bytes that pass all of this and still are no image, audio or video the engine decodes come back
+ * from it as a 500; `undecodableMediaVerdict` turns that answer into the same kind of 400.
+ */
+import type { EmbeddingModality } from '../contracts/index.js';
+export type EmbeddingRequestVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    param?: string;
+};
+/** A reference rather than inline bytes: anything with a scheme other than `data:`. */
+export declare function isMediaReference(value: string): boolean;
+/** The verdict on a parsed request body for a running model of `dims` that reads `modalities`. */
+export declare function checkEmbeddingRequest(body: unknown, modalities: readonly EmbeddingModality[], dims: number | null): EmbeddingRequestVerdict;
+/**
+ * The client error for the engine's 500 about media it could not decode, naming the media fields of the
+ * request that carried it (the field itself when there is one); `undefined` for any other answer, and
+ * for a request without media, whose 500 stays the engine's.
+ */
+export declare function undecodableMediaVerdict(status: number, engineBody: string, body: unknown, modalities: readonly EmbeddingModality[]): {
+    message: string;
+    param?: string;
+} | undefined;

package/dist/embedding/request.js

@@ -0,0 +1,285 @@
+/**
+ * What the public `/v1/embeddings` checks before it passes a body to the embedding process. Pure.
+ *
+ * The body goes on as the client sent it; these checks only refuse:
+ *  - media by reference: llama-server fetches an `http(s)` URL itself (and a `file://` one with
+ *    `--media-path`), so an API open to the LAN would fetch whatever a client names. Only inline media
+ *    (`data:` URLs, bare base64) is passed;
+ *  - inline media the engine would fail to read for its form alone: no data, a `data:` URL it does not
+ *    parse, a placeholder, base64 it stops reading early (its decoder ends at the first character outside
+ *    the standard alphabet, so a line break or URL-safe base64 leaves a truncated file). The engine
+ *    answers each of these with a 500; a client error is a 400 that names the field;
+ *  - media the running model cannot read: the engine answers a 500 for it, a client error is a 400
+ *    (for video, which also needs `ffmpeg` on this computer, the message says so);
+ *  - a content part sent as an input of its own, outside `{content: [...]}`: llama.cpp refuses it
+ *    with a message about prompt shapes, this one names the fix;
+ *  - a `dimensions` the model does not produce: the engine ignores the field, and a client that asked
+ *    for 256 numbers would store 768 without knowing (the model's shorter Matryoshka lengths are the
+ *    client's to cut, as the app's catalog says).
+ *
+ * Bytes that pass all of this and still are no image, audio or video the engine decodes come back
+ * from it as a 500; `undecodableMediaVerdict` turns that answer into the same kind of 400.
+ */
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The modality a content part carries, by its `type`; `undefined` for text and for types the engine judges. */
+const PART_MODALITY = {
+    image_url: 'image',
+    input_audio: 'audio',
+    input_video: 'video',
+    video_url: 'video',
+};
+/** Every content part type the engine reads, for spotting one sent outside `content`. */
+const PART_TYPES = new Set(['text', ...Object.keys(PART_MODALITY)]);
+/** A `data:` URL of the right kind, for the messages. */
+const DATA_URL_EXAMPLE = {
+    image: 'data:image/png;base64,<base64>',
+    audio: 'data:audio/wav;base64,<base64>',
+    video: 'data:video/mp4;base64,<base64>',
+};
+/** The `data:` URL media types llama-server reads (`handle_media`). */
+const DATA_URL_TYPES = ['data:image/', 'data:audio/', 'data:video/'];
+/** A reference rather than inline bytes: anything with a scheme other than `data:`. */
+export function isMediaReference(value) {
+    const scheme = /^\s*([a-z][a-z0-9+.-]*):/i.exec(value);
+    return scheme !== null && scheme[1].toLowerCase() !== 'data';
+}
+/**
+ * The string llama-server reads a content part's media from: `image_url.url`; `data`, else `url`, of
+ * `input_audio` and the video parts. A holder that is not an object, or a field that is not a string,
+ * reads as `''`.
+ */
+function partField(part, type, at) {
+    const holder = part[type];
+    const fields = isRecord(holder) ? holder : {};
+    const key = type === 'image_url' || (typeof fields['data'] !== 'string' && typeof fields['url'] === 'string')
+        ? 'url'
+        : 'data';
+    const value = fields[key];
+    return {
+        path: `${at}.${type}.${key}`,
+        value: typeof value === 'string' ? value : '',
+        modality: PART_MODALITY[type],
+        form: 'url',
+    };
+}
+/** The bare base64 entries of the legacy multimodal shape, `{prompt_string, multimodal_data: [base64]}`. */
+function multimodalFields(item, where) {
+    const data = item['multimodal_data'];
+    if (!Array.isArray(data))
+        return [];
+    return data.flatMap((entry, k) => typeof entry === 'string'
+        ? [
+            {
+                path: `${where}.multimodal_data[${k}]`,
+                value: entry,
+                modality: 'image',
+                form: 'base64',
+            },
+        ]
+        : []);
+}
+/** Every string a part names its media by, read or not: a link in any of them is refused. */
+function partReferences(part, type) {
+    const holder = part[type];
+    if (typeof holder === 'string')
+        return [holder];
+    if (!isRecord(holder))
+        return [];
+    return [holder['url'], holder['data']].filter((v) => typeof v === 'string');
+}
+/** Why bare base64 would not reach the engine whole, or `undefined` when it would. */
+function base64Problem(data, path) {
+    if (data === '')
+        return `${path} has no data: put the file's base64 there.`;
+    if (/\.\.\.|…|^<.*>$/.test(data))
+        return `${path} holds a placeholder ("${data.length > 24 ? `${data.slice(0, 24)}…` : data}") where the file's base64 belongs: put the whole file there, base64-encoded.`;
+    const body = data.replace(/={1,2}$/, '');
+    const bad = /[^A-Za-z0-9+/]/.exec(body);
+    if (bad) {
+        const at = `character ${bad.index + 1} of its base64`;
+        if (/\s/.test(bad[0]))
+            return `${path} has a line break or space at ${at}, where the engine stops reading: send the base64 on one line.`;
+        if (bad[0] === '-' || bad[0] === '_')
+            return `${path} is URL-safe base64 ('${bad[0]}' at ${at}): send standard base64, with + and /.`;
+        return `${path} is not base64: '${bad[0]}' at ${at}. Send the file's bytes base64-encoded (A–Z, a–z, 0–9, +, /).`;
+    }
+    if (body.length % 4 === 1)
+        return `${path} is cut short: its base64 ends partway through. Send the whole file.`;
+    return undefined;
+}
+/** Why `field` would fail in the engine for its form alone, or `undefined`. */
+function fieldProblem(field) {
+    const { path, value, modality, form } = field;
+    if (form === 'base64') {
+        if (/^\s*data:/i.test(value))
+            return `${path} takes bare base64, without the data: header.`;
+        return base64Problem(value, path);
+    }
+    if (value === '')
+        return `${path} is missing: send the file inline, as a data: URL (${DATA_URL_EXAMPLE[modality]}) or bare base64.`;
+    if (!value.startsWith('data:')) {
+        if (/^\s*data:/i.test(value))
+            return `${path} must start with "data:" in lower case, with nothing before it.`;
+        return base64Problem(value, path);
+    }
+    const parts = value.split(',');
+    if (parts.length !== 2)
+        return `${path} must have one comma, between the header and the base64: ${DATA_URL_EXAMPLE[modality]}.`;
+    const [header, data] = parts;
+    if (!DATA_URL_TYPES.some((prefix) => header.startsWith(prefix)))
+        return `${path} is a "${header.slice(0, 40)}" URL; the engine reads image/, audio/ and video/ ones: ${DATA_URL_EXAMPLE[modality]}.`;
+    if (!header.endsWith('base64'))
+        return `${path} must be base64-encoded: ${DATA_URL_EXAMPLE[modality]}.`;
+    return base64Problem(data, path);
+}
+/** The items of `input`, each with where it is. */
+function inputItems(input) {
+    return Array.isArray(input)
+        ? input.map((item, i) => ({ item, where: `input[${i}]` }))
+        : [{ item: input, where: 'input' }];
+}
+/** Every media string of `body` the engine would read, in order. */
+function mediaFields(body) {
+    if (!isRecord(body))
+        return [];
+    const fields = [];
+    for (const { item, where } of inputItems(body['input'])) {
+        if (!isRecord(item))
+            continue;
+        const content = item['content'];
+        if (Array.isArray(content))
+            for (const [i, part] of content.entries()) {
+                if (!isRecord(part) || typeof part['type'] !== 'string')
+                    continue;
+                if (PART_MODALITY[part['type']] === undefined)
+                    continue;
+                fields.push(partField(part, part['type'], `${where}.content[${i}]`));
+            }
+        fields.push(...multimodalFields(item, where));
+    }
+    return fields;
+}
+function checkParts(parts, where, modalities) {
+    for (const [i, part] of parts.entries()) {
+        if (!isRecord(part) || typeof part['type'] !== 'string')
+            continue;
+        const type = part['type'];
+        const modality = PART_MODALITY[type];
+        if (modality === undefined)
+            continue;
+        const at = `${where}.content[${i}]`;
+        if (!modalities.includes(modality))
+            return {
+                ok: false,
+                message: `The running embedding model does not read ${modality === 'image' ? 'images' : modality} (${at}.type is "${type}").` +
+                    (modality === 'video' ? ' Video input also needs ffmpeg installed on this computer.' : ''),
+                param: at,
+            };
+        if (partReferences(part, type).some(isMediaReference))
+            return {
+                ok: false,
+                message: `Media must be sent inline, as a data: URL or base64; links are not fetched (${at}).`,
+                param: at,
+            };
+        const field = partField(part, type, at);
+        const problem = fieldProblem(field);
+        if (problem !== undefined)
+            return { ok: false, message: problem, param: field.path };
+    }
+    return { ok: true };
+}
+/** The verdict on a parsed request body for a running model of `dims` that reads `modalities`. */
+export function checkEmbeddingRequest(body, modalities, dims) {
+    if (!isRecord(body))
+        return { ok: false, message: 'The request body must be a JSON object.' };
+    const input = body['input'];
+    if (input === undefined)
+        return { ok: false, message: "The request needs an 'input'.", param: 'input' };
+    const dimensions = body['dimensions'];
+    if (dimensions !== undefined && dimensions !== null && dims !== null && dimensions !== dims)
+        return {
+            ok: false,
+            message: `The model returns ${dims}-dimension vectors and this server does not shorten them: drop 'dimensions' or send ${dims}. ` +
+                'For a shorter length the model was trained for, keep the first values of each vector and L2-normalize them in your application.',
+            param: 'dimensions',
+        };
+    for (const { item, where } of inputItems(input)) {
+        if (!isRecord(item))
+            continue;
+        if (typeof item['type'] === 'string' && item['content'] === undefined && PART_TYPES.has(item['type']))
+            return {
+                ok: false,
+                message: `${where} is a content part on its own; wrap it in an input item: {"content": [${JSON.stringify({ type: item['type'] })}]}.`,
+                param: where,
+            };
+        const content = item['content'];
+        if (Array.isArray(content)) {
+            const verdict = checkParts(content, where, modalities);
+            if (!verdict.ok)
+                return verdict;
+        }
+        // The legacy multimodal shape: bare base64 only, never a link.
+        const data = item['multimodal_data'];
+        if (Array.isArray(data) && data.some((d) => typeof d === 'string' && isMediaReference(d)))
+            return {
+                ok: false,
+                message: `Media must be sent inline, as base64; links are not fetched (${where}.multimodal_data).`,
+                param: `${where}.multimodal_data`,
+            };
+        for (const field of multimodalFields(item, where)) {
+            const problem = fieldProblem(field);
+            if (problem !== undefined)
+                return { ok: false, message: problem, param: field.path };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * What llama-server says, with a 500, for media it could not decode (`process_mtmd_prompt`) and for
+ * bare base64 that decodes to nothing (`handle_media`).
+ */
+const UNDECODABLE_MEDIA = ['failed to load image or audio file', 'invalid base64 value'];
+/** The formats the engine decodes, for the modalities the model reads. */
+function readableFormats(modalities) {
+    const formats = [];
+    if (modalities.includes('image'))
+        formats.push('PNG, JPEG, GIF or BMP images (WebP needs ffmpeg on this computer)');
+    if (modalities.includes('audio'))
+        formats.push('WAV, MP3 or FLAC audio');
+    if (modalities.includes('video'))
+        formats.push('video ffmpeg reads');
+    return formats.join('; ');
+}
+/**
+ * The client error for the engine's 500 about media it could not decode, naming the media fields of the
+ * request that carried it (the field itself when there is one); `undefined` for any other answer, and
+ * for a request without media, whose 500 stays the engine's.
+ */
+export function undecodableMediaVerdict(status, engineBody, body, modalities) {
+    if (status !== 500)
+        return undefined;
+    let message;
+    try {
+        const parsed = JSON.parse(engineBody);
+        message = isRecord(parsed) && isRecord(parsed['error']) ? parsed['error']['message'] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof message !== 'string')
+        return undefined;
+    const said = message.toLowerCase();
+    if (!UNDECODABLE_MEDIA.some((words) => said.includes(words)))
+        return undefined;
+    const paths = mediaFields(body).map((field) => field.path);
+    if (paths.length === 0)
+        return undefined;
+    const where = paths.length === 1 ? paths[0] : `One of ${paths.join(', ')}`;
+    const formats = readableFormats(modalities);
+    return {
+        message: `${where} could not be decoded as an image, audio or video file (the engine said: "${message}"). ` +
+            `Send the file's own bytes, base64-encoded${formats ? `: ${formats}` : ''}.`,
+        ...(paths.length === 1 ? { param: paths[0] } : {}),
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/embedding/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/embedding/request.ts"],"names":[],"mappings":"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"}

package/dist/embedding/service.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The embedding module's surface: one embedding `llama-server` at most (stock llama.cpp), its
+ * lifecycle, and the target the public `/v1/embeddings` forwards to.
+ *
+ * Outside the sessions registry on purpose, like the decision model
+ * (ADR 2026-10-07-embedding-models-are-their-own-core-module): a chat model switch unloads every
+ * other session of its provider, and the model the API serves must stay up across it. So nothing here
+ * is a `LocalRuntime`; the module borrows only process mechanics.
+ *
+ * What it guarantees (the decision module's rules, minus the fail-open calls):
+ *  - start and stop are serialized, and a stop aborts a start still waiting for readiness;
+ *  - a process that dies after it was ready is restarted with backoff, at most `MAX_RESTARTS` times in
+ *    a row; a start that fails is not retried until a setting changes, `load` is asked for, or a
+ *    llama.cpp build is installed (`onEnginesChanged`); an `unsupported` module is also retried in
+ *    the background by a request, at most once per `UNSUPPORTED_RETRY_MS`, quietly;
+ *  - a request to a module that is enabled but idle starts it and waits for it (`acquire`);
+ *  - every state change is an `embedding:state` event, and a failure nobody awaits an `embedding:error`.
+ */
+import type { CoreEvents, EmbeddingEmbedResponse, EmbeddingEngineInfo, EmbeddingSettings, EmbeddingState, EmbeddingStatus } from '../contracts/index.js';
+import type { DecisionHttp } from '../decision/index.js';
+import type { EmbeddingBackend } from '../server/index.js';
+import type { EmbeddingModelFacts } from './model-facts.js';
+import type { EmbeddingProcessHandle, EmbeddingServerSpec } from './process.js';
+/** How often a request may retry an `unsupported` module in the background. */
+export declare const UNSUPPORTED_RETRY_MS: number;
+/** The control route's own request budget, once the model runs. */
+export declare const EMBED_REQUEST_TIMEOUT_MS = 120000;
+export type EmbeddingEmitter = <K extends 'embedding:state' | 'embedding:error'>(name: K, payload: CoreEvents[K]) => void;
+export type EmbeddingLogger = (level: 'info' | 'warn' | 'debug', msg: string) => void;
+export interface EmbeddingServiceDeps {
+    /** The core's data folder: relative model paths are resolved against it. */
+    dataFolder: string;
+    readSettings: () => EmbeddingSettings;
+    /** A checked write of the `embedding` settings section (`SettingsStore.updateEmbedding`). */
+    writeSettings: (patch: Record<string, unknown>) => Promise<unknown>;
+    /** The engine gate (`EmbeddingEngineResolver.resolve`). */
+    resolveEngine: (enginePath: string, minBuild: number) => Promise<EmbeddingEngineInfo>;
+    /** A resolved build that readiness refused: skipped from now on (`EmbeddingEngineResolver.reject`). */
+    rejectEngine?: (exe: string, why: string) => Promise<void>;
+    /** Try every refused build again (`EmbeddingEngineResolver.forgetRejected`). */
+    forgetRejectedEngines?: () => void;
+    /** Start one process and wait for readiness (`spawnEmbeddingServer` plus the journal). */
+    spawn: (spec: EmbeddingServerSpec, signal: AbortSignal) => Promise<EmbeddingProcessHandle>;
+    http: DecisionHttp;
+    emit: EmbeddingEmitter;
+    log: EmbeddingLogger;
+    now?: () => number;
+    /** Whether a file exists. */
+    fileExists?: (path: string) => Promise<boolean>;
+    /** What the GGUF header says (`readEmbeddingModelFacts`); `undefined` when it cannot be read. */
+    readModelFacts?: (path: string) => Promise<EmbeddingModelFacts | undefined>;
+    /** Run `fn` after `ms`; returns the cancel. The default timer never keeps the process alive. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+}
+/** The settings a running process was started with; any change means a restart. */
+export declare function embeddingLaunchKey(settings: EmbeddingSettings): string;
+/** The name API clients pass as `model`: the setting, else the file name; `null` without a model. */
+export declare function embeddingModelIdOf(settings: EmbeddingSettings): string | null;
+/** Why a request cannot reach the model in `state`, for the public route's 503. */
+export declare function embeddingRefusal(state: EmbeddingState, configured: boolean): string;
+export declare class EmbeddingService {
+    private readonly deps;
+    private state;
+    private handle;
+    private runningKey;
+    /** `embeddingLaunchKey` of the start in flight, from the moment it read the settings. */
+    private loadingKey;
+    private readySince;
+    /** `embeddingLaunchKey` of the last start: a start with another one tries the refused builds again. */
+    private lastLaunchKey;
+    /** When a request last retried an `unsupported` module; a quiet retry that changes nothing emits nothing. */
+    private lastQuietRetry;
+    private loading;
+    private loadAbort;
+    private cancelRestart;
+    private cancelIdle;
+    private inFlight;
+    private stopping;
+    /** Called on every state change and when a start settles: the public route's waits. */
+    private readonly waiters;
+    /** Start and stop, one at a time. */
+    private chain;
+    private readonly now;
+    private readonly schedule;
+    constructor(deps: EmbeddingServiceDeps);
+    /** Called once by the owner: an enabled and configured module starts in the background. */
+    start(): void;
+    getStatus(): EmbeddingStatus;
+    getConfig(): EmbeddingSettings;
+    /** Write settings, then bring the process in line with them. */
+    configure(patch: Record<string, unknown>): Promise<EmbeddingStatus>;
+    /**
+     * After a settings change: turned off → stop; started (or starting) with other launch settings →
+     * restart; enabled and not running → start in the background. The crash count starts over. A change
+     * that does not touch the launch (`idle_unload_secs`, `startup_timeout_secs`) leaves a running
+     * process alone; `idle_unload_secs` takes effect at once.
+     */
+    reconcile(): Promise<EmbeddingStatus>;
+    /**
+     * A llama.cpp build was installed: a module that is `unsupported` or `failed` tries again, since the
+     * new build may be the first new enough for the model. Installs of other providers are ignored.
+     */
+    onEnginesChanged(provider?: string): Promise<EmbeddingStatus>;
+    /** Start now (or join the start in flight) and answer once it is ready; a failure is thrown. */
+    load(): Promise<EmbeddingStatus>;
+    /** Stop the process (or the start in flight). The module stays enabled: the next request starts it again. */
+    unload(): Promise<EmbeddingStatus>;
+    /**
+     * One `/v1/embeddings` request for the app (`POST /atomic/v1/embedding/embed`): the module is
+     * started when it is enabled and idle, the body is sent with the running model's name, and the
+     * engine's answer comes back as it is. `EMBEDDING_UNAVAILABLE` when the model cannot be reached.
+     */
+    embed(body: Record<string, unknown>): Promise<EmbeddingEmbedResponse>;
+    /** What the public server forwards `/embeddings` to. */
+    publicBackend(): EmbeddingBackend;
+    /** Stop everything for good: timers, a start in flight, the process. No events after this. */
+    shutdown(): Promise<void>;
+    private setState;
+    private notifyWaiters;
+    private serial;
+    /** `quietCode`: a background retry of a state the app already heard about (see `startProcess`). */
+    private startInBackground;
+    /** An `unsupported` module whose state is older than `UNSUPPORTED_RETRY_MS` tries again, quietly. */
+    private retryUnsupported;
+    private reportUnawaited;
+    private ensureLoaded;
+    /**
+     * `quiet`: a background retry of an `unsupported` module. It does not announce `starting` and, when
+     * it fails the same way again, leaves the state as it was without an event.
+     */
+    private startProcess;
+    /**
+     * Resolve an engine and spawn it; a build that readiness refuses as unsupported or that dies while
+     * loading (a ROCm build without kernels for the card) is handed to `rejectEngine` and the next one is
+     * tried (`spawnOnFirstGoodEngine`). An explicit `engine_path` has nothing to fall back to.
+     */
+    private spawnOnFirstGoodEngine;
+    private onExit;
+    private onRestartFailed;
+    private scheduleRestart;
+    private stopProcess;
+    /** (Re)arm the idle unload; a request in flight pushes it back. */
+    private armIdle;
+    /**
+     * The public route's target. An enabled, configured module that is idle is started (a failure is an
+     * `embedding:error`); one that is starting or restarting is waited on, up to `waitMs`, until it is
+     * ready or lands in a state no start will leave, or the client leaves (`signal`).
+     */
+    private acquire;
+    /** The handle once there is one; `undefined` on timeout, on `signal`, or once no start is on its way. */
+    private waitForHandle;
+}