@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/lib/distill.js

@@ -10,17 +10,19 @@
  * @module distill
  */
 import * as okf from "./okf.js";
+import { recordPipelineEvent } from "./pipeline-events.js";
 export const SYSTEM_PROMPT = [
     '你是 topic 记忆库的蒸馏引擎。输入是若干条未蒸馏的会话观察（JSON）和现有 topic 索引。',
     '任务：把观察沉淀成 Topic 操作。只输出一个 JSON 对象，不要任何其他文字、Markdown 代码块或解释。',
     '输出格式：{"ops": [...]}，每个元素：',
     '  {"op":"create","title":"主题名","description":"一句话","tags":["小写标签"],"triggers":["应想起本条的触发词"],"depends":["前置topic的slug"],',
-    '   "open_questions":["未决问题"],"impact":["影响面"],"conclusion":"当前结论(自含散文)","recommendations":"可执行建议","status":"draft",',
+    '   "open_questions":["未决问题"],"impact":["影响面"],"links":["关联topic的slug"],"conclusion":"当前结论(自含散文)","recommendations":"可执行建议","status":"draft",',
     '   "observed_ids":["obs-..."]}',
-    '  {"op":"update","slug":"已有slug","conclusion":"修订后的完整结论","open_questions":[...],"observed_ids":["obs-..."]}',
+    '  {"op":"update","slug":"已有slug","conclusion":"修订后的完整结论","open_questions":[...],"links":["关联topic的slug"],"observed_ids":["obs-..."]}',
     '规则：',
     '- 硬性要求：每个 op 必须带 observed_ids 字段，值只能从本次输入「未蒸馏观察」里列出的 id 中逐字复制（形如 "obs-..."）；create 填它所综合依据的观察 id，update 填促使本次修订的观察 id。含列表之外 id 的条目会被过滤；observed_ids 缺失、为空或过滤后不剩任何有效 id 的 op 会被整体丢弃。',
-    '- create 建议带 triggers：3-8 个「什么输入出现时应该想起这条记忆」的短语，写具体名词/术语，禁止 dsh、配置、错误 之类的泛词。',
+    '- 硬性要求：每个 create 必须带 description（一句话概括）与 triggers（恰好 3-8 个「什么输入出现时应该想起这条记忆」的短语，写具体名词/术语，禁止 dsh、配置、错误 之类的泛词）；缺失或数量不符的 create 会被补问一次，补全后仍不合规的 op 会被丢弃并落账。',
+    '- links（可选输出，不给不惩罚）：只建真实语义关联（依赖/同项目/同主题链），宁缺勿滥；每项只能是已存在 topic 的 slug 或本批其他 op 的 slug，列表之外的引用会被剔除并落账。没有真实关联就不要给 links。',
     '- conclusion 必须自含（不依赖观察原文也能读懂），写「目前有效的结论」，不是流水账。',
     '- 同一主题只允许一个 create；已有相近 topic 时用 update 修订它的 conclusion。',
     '- 观察里有价值就沉淀，没价值就跳过该观察（被跳过观察的 id 不要出现在任何 op 里）；没有可沉淀内容时输出 {"ops":[]}。',
@@ -31,6 +33,36 @@ const MIN_BATCH_SIZE = 5;
 /** Fallbacks when the config fields are absent (bare test harnesses). */
 const DEFAULT_BATCH_SIZE = 40;
 const DEFAULT_MAX_MODEL_CALLS = 8;
+// ---------------------------------------------------------------------
+// A6 §5.1 op schema gate + A2 links whitelist (always on, no config key:
+// the distill quality contract is not a behavior switch — failures are
+// ledgered via pipeline-events, never swallowed silently).
+// ---------------------------------------------------------------------
+/** create-op trigger bounds (the recall design's 3-8 strong-field contract). */
+const TRIGGERS_MIN = 3;
+const TRIGGERS_MAX = 8;
+/** Stable identity for matching an op against its schema-retry re-emission. */
+function opKey(op) {
+    if (op.op === 'update')
+        return typeof op.slug === 'string' ? okf.slugify(op.slug) : '';
+    return typeof op.title === 'string' ? okf.slugify(op.title) : '';
+}
+/**
+ * The A6 §5.1 schema check for create ops: description 必填 + triggers 3-8
+ * 条. Update ops keep their narrower contract (slug) — the prompt never
+ * required metadata fields on a conclusion revision, and gating those would
+ * drop every revision op.
+ */
+function checkCreateSchema(op) {
+    const problems = [];
+    if (typeof op.description !== 'string' || op.description.trim() === '')
+        problems.push('description');
+    const triggers = Array.isArray(op.triggers) ? op.triggers.filter((t) => typeof t === 'string' && t.trim() !== '') : [];
+    if (triggers.length < TRIGGERS_MIN || triggers.length > TRIGGERS_MAX) {
+        problems.push(`triggers(实际 ${triggers.length}，需 ${TRIGGERS_MIN}-${TRIGGERS_MAX})`);
+    }
+    return { valid: problems.length === 0, missing: problems.join('、') };
+}
 export class Distiller {
     inFlight = new Map();
     service;
@@ -160,6 +192,8 @@ export class Distiller {
         let failureDetail;
         let firstFetch = true;
         let filteredTotal = 0;
+        let invalidTotal = 0;
+        let rejectedTotal = 0;
         let stallDetail;
         // GC bookkeeping (store.recordUnconsumed): every id the model EVALUATED
         // this run (parseable answer, however useless) minus the ids an op
@@ -191,6 +225,8 @@ export class Distiller {
             for (const id of outcome.consumedIds ?? [])
                 consumedRunIds.add(id);
             filteredTotal += outcome.filteredIds ?? 0;
+            invalidTotal += outcome.invalidOps ?? 0;
+            rejectedTotal += outcome.rejectedLinks ?? 0;
             created.push(...outcome.created);
             updated.push(...outcome.updated);
             marked += outcome.marked;
@@ -272,6 +308,9 @@ export class Distiller {
                                 ? `后续批次未消费任何观察，本轮停止${stallDetail !== undefined ? `：${stallDetail}` : ''}`
                                 : undefined;
             const filteredNote = filteredTotal > 0 ? `；filtered ${filteredTotal} invalid observed_ids` : '';
+            const schemaNote = invalidTotal > 0 ? `；schema-dropped ${invalidTotal} create op(s)` : '';
+            const linkNote = rejectedTotal > 0 ? `；rejected ${rejectedTotal} invalid link ref(s)` : '';
+            const notes = `${filteredNote}${schemaNote}${linkNote}`;
             const base = head === undefined ? undefined : `partial: 已蒸馏标记 ${marked} 条观察（${calls} 次模型调用）；${head}`;
             result = {
                 ok: true,
@@ -279,10 +318,10 @@ export class Distiller {
                 updated,
                 marked,
                 detail: base === undefined
-                    ? filteredNote === ''
+                    ? notes === ''
                         ? undefined
-                        : filteredNote.replace(/^；/, '')
-                    : `${base}${filteredNote}`,
+                        : notes.replace(/^；/, '')
+                    : `${base}${notes}`,
             };
         }
         else {
@@ -369,6 +408,29 @@ export class Distiller {
         if (ops.length === 0) {
             return { created: [], updated: [], marked: 0, noOps: true, callsUsed: 1 };
         }
+        // A6 §5.1 schema gate BEFORE any write: deficient creates get exactly one
+        // 补问 retry (budget-guarded), still-deficient ops are dropped and
+        // ledgered — never a silent drop. Their observations simply stay
+        // unconsumed and walk the existing GC/corrective path (three strikes).
+        const schema = await this.enforceSchema(sessionId, user, ops, budgetLeft);
+        let callsUsed = 1 + schema.retrySpent;
+        for (const drop of schema.drops) {
+            await recordPipelineEvent(this.service.store.root, {
+                at: new Date().toISOString(),
+                kind: drop.kind,
+                detail: { op: drop.key, missing: drop.missing },
+            });
+        }
+        if (schema.finalOps.length === 0) {
+            return {
+                created: [],
+                updated: [],
+                marked: 0,
+                callsUsed,
+                invalidOps: schema.drops.length,
+                stallDetail: `全部 create op 未通过 schema 校验（description 必填 + triggers 3-8 条），已丢弃并落账（${schema.drops.length} 个）`,
+            };
+        }
         // observed_ids are the ONLY bridge between ops and marks — without a valid
         // id the store cannot mark anything and the batch head can never advance
         // (the real-machine zero-consumption livelock: topics landed, backlog
@@ -378,10 +440,18 @@ export class Distiller {
         // corrective retry re-emits it with fixed ids.
         const validIds = new Set(observations.map((o) => o.id));
         const idList = observations.map((o) => o.id);
-        let applied = await this.applyOps(ops, validIds);
-        let callsUsed = 1;
+        // Link whitelist universe (A2): slugs existing before this batch plus
+        // every same-batch op slug (predicted; the actual create slug joins as
+        // each op lands).
+        const knownSlugs = new Set(metas.map((m) => m.slug));
+        for (const op of schema.finalOps) {
+            const key = opKey(op);
+            if (key !== '')
+                knownSlugs.add(key);
+        }
+        let applied = await this.applyOps(schema.finalOps, validIds, knownSlugs);
         if (applied.consumedIds.length === 0 && applied.droppedForIds > 0) {
-            if (budgetLeft < 2) {
+            if (budgetLeft < callsUsed + 1) {
                 // No free lane: the retry must fit the same run budget.
                 return {
                     created: [],
@@ -389,12 +459,14 @@ export class Distiller {
                     marked: 0,
                     callsUsed,
                     filteredIds: applied.filteredIds,
-                    stallDetail: `ops 未包含有效 observed_ids（已过滤 ${applied.filteredIds} 个无效 id），且模型调用预算不足以纠错重试（剩余 ${budgetLeft - 1} 次）`,
+                    rejectedLinks: applied.rejectedLinks,
+                    invalidOps: schema.drops.length,
+                    stallDetail: `ops 未包含有效 observed_ids（已过滤 ${applied.filteredIds} 个无效 id），且模型调用预算不足以纠错重试（剩余 ${budgetLeft - callsUsed} 次）`,
                 };
             }
             const pass1 = applied;
-            const { applied: pass2, why } = await this.correctiveRetry(sessionId, user, idList, validIds);
-            callsUsed = 2;
+            const { applied: pass2, why } = await this.correctiveRetry(sessionId, user, idList, validIds, knownSlugs);
+            callsUsed += 1;
             if (pass2 === undefined || pass2.consumedIds.length === 0) {
                 const tail = pass2 === undefined
                     ? `纠错重试未产出可消费的 ops（${why}）`
@@ -405,6 +477,8 @@ export class Distiller {
                     marked: 0,
                     callsUsed,
                     filteredIds: pass1.filteredIds + (pass2?.filteredIds ?? 0),
+                    rejectedLinks: pass1.rejectedLinks + (pass2?.rejectedLinks ?? 0),
+                    invalidOps: schema.drops.length,
                     stallDetail: `${tail}；本批 ${observations.length} 条观察零消费`,
                 };
             }
@@ -415,6 +489,7 @@ export class Distiller {
                 consumedSlugs: pass2.consumedSlugs,
                 filteredIds: pass1.filteredIds + pass2.filteredIds,
                 droppedForIds: pass2.droppedForIds,
+                rejectedLinks: pass1.rejectedLinks + pass2.rejectedLinks,
             };
         }
         let marked = 0;
@@ -428,6 +503,8 @@ export class Distiller {
             marked,
             callsUsed,
             filteredIds: applied.filteredIds,
+            invalidOps: schema.drops.length,
+            rejectedLinks: applied.rejectedLinks,
             consumedIds: applied.consumedIds,
         };
     }
@@ -439,7 +516,7 @@ export class Distiller {
      * stop — a max-tokens correction does NOT trigger the batch halving (that
      * escape hatch belongs to the main pass).
      */
-    async correctiveRetry(sessionId, originalUser, idList, validIds) {
+    async correctiveRetry(sessionId, originalUser, idList, validIds, knownSlugs) {
         const caller = this.caller;
         if (caller === undefined)
             return { why: 'distill caller unavailable' };
@@ -468,7 +545,112 @@ export class Distiller {
         }
         if (retried.length === 0)
             return { why: '模型返回空 ops' };
-        return { applied: await this.applyOps(retried, validIds), why: '' };
+        return { applied: await this.applyOps(retried, validIds, knownSlugs), why: '' };
+    }
+    /**
+     * The A6 §5.1 schema gate, applied to the parsed batch BEFORE any write:
+     * create ops must carry description + triggers 3-8 条 (the prompt's standing
+     * requirement, now enforced). Deficient creates get exactly ONE 补问 retry
+     * that re-asks for just those ops completed — budget-guarded exactly like
+     * the corrective ids retry (`retrySpent` reports the extra call). Every
+     * still-deficient op is dropped and comes back as a SchemaDrop carrying the
+     * ledger kind: `distill-op-invalid` after a used-but-unsuccessful retry,
+     * `distill-op-retry-exhausted` when no retry could run or the retry call
+     * itself failed. Dropped ops' observations stay unconsumed — the existing
+     * GC/corrective path accounts for them, never a silent loss. Update ops
+     * keep their narrower contract (slug only).
+     */
+    async enforceSchema(sessionId, originalUser, ops, budgetLeft) {
+        const valid = [];
+        const invalid = [];
+        for (const op of ops) {
+            if (op.op !== 'create') {
+                valid.push(op);
+                continue;
+            }
+            const check = checkCreateSchema(op);
+            if (check.valid)
+                valid.push(op);
+            else
+                invalid.push({ op, key: opKey(op), missing: check.missing });
+        }
+        if (invalid.length === 0)
+            return { finalOps: valid, drops: [], retrySpent: 0 };
+        if (budgetLeft < 2) {
+            return {
+                finalOps: valid,
+                drops: invalid.map((c) => ({
+                    key: c.key,
+                    kind: 'distill-op-retry-exhausted',
+                    missing: `${c.missing}（模型调用预算不足以补问）`,
+                })),
+                retrySpent: 0,
+            };
+        }
+        const rescued = await this.schemaRetryCall(sessionId, originalUser, invalid);
+        if (rescued === undefined) {
+            return {
+                finalOps: valid,
+                drops: invalid.map((c) => ({
+                    key: c.key,
+                    kind: 'distill-op-retry-exhausted',
+                    missing: `${c.missing}（补问调用失败）`,
+                })),
+                retrySpent: 1,
+            };
+        }
+        const drops = [];
+        for (const c of invalid) {
+            const replacement = rescued.get(c.key);
+            if (replacement !== undefined && checkCreateSchema(replacement).valid) {
+                valid.push(replacement);
+            }
+            else {
+                drops.push({ key: c.key, kind: 'distill-op-invalid', missing: c.missing });
+            }
+        }
+        return { finalOps: valid, drops, retrySpent: 1 };
+    }
+    /**
+     * The one schema 补问: re-ask for exactly the deficient creates, completed.
+     * Returns key→op for what the model re-emitted (matched by slugified title),
+     * or undefined when the call itself failed / output was unparseable — the
+     * caller then ledgeres `distill-op-retry-exhausted` for every deficient op.
+     */
+    async schemaRetryCall(sessionId, originalUser, invalid) {
+        const caller = this.caller;
+        if (caller === undefined)
+            return undefined;
+        const list = invalid.map((c) => `- create「${typeof c.op.title === 'string' ? c.op.title : ''}」（缺：${c.missing}）`).join('\n');
+        const user = [
+            originalUser,
+            '',
+            '---',
+            'schema 补问：你上一次返回的以下 create op 缺少必填字段：',
+            list,
+            '请只重新输出这些 op 的补全版本（严格 JSON，{"ops":[...]}）：每个 create 必须带 description（一句话概括）与 triggers（恰好 3-8 条具体触发短语，禁止 dsh、配置、错误 之类的泛词），并保留原有的 title/conclusion/observed_ids 等字段。无法补全的 op 不要输出。',
+        ].join('\n');
+        let raw;
+        try {
+            raw = await caller({ system: SYSTEM_PROMPT, user, purpose: 'topics-distill', sessionId, maxTokens: 4000 });
+        }
+        catch {
+            return undefined;
+        }
+        let retried;
+        try {
+            retried = parseOps(raw);
+        }
+        catch {
+            return undefined;
+        }
+        const map = new Map();
+        for (const op of retried) {
+            const key = opKey(op);
+            if (key !== '')
+                map.set(key, op);
+        }
+        return map;
     }
     /**
      * Execute a batch's ops with observed_ids sanitized upfront. A scalar
@@ -481,8 +663,21 @@ export class Distiller {
      * failures (missing fields, unknown update slug) keep the per-op try/catch
      * isolation — one bad op never sinks the batch, and a stall they cause is
      * NOT attributed to observed_ids (no corrective retry for those).
+     *
+     * A2 links: every link target is whitelist-checked against `knownSlugs`
+     * (existing slugs ∪ same-batch op slugs); rejected refs are stripped and
+     * ledgered (`link-ref-rejected`), survivors ride the op's topic write into
+     * the store transaction (先落 topic 再建边 — one write, no separate edge
+     * pass). The set is locally seeded with this call's predicted op slugs and
+     * grows as creates land, so same-batch references resolve in op order.
      */
-    async applyOps(ops, validIds) {
+    async applyOps(ops, validIds, knownSlugs) {
+        const slugs = new Set(knownSlugs);
+        for (const op of ops) {
+            const key = opKey(op);
+            if (key !== '')
+                slugs.add(key);
+        }
         const applied = {
             created: [],
             updated: [],
@@ -490,6 +685,7 @@ export class Distiller {
             consumedSlugs: [],
             filteredIds: 0,
             droppedForIds: 0,
+            rejectedLinks: 0,
         };
         for (const op of ops) {
             try {
@@ -510,6 +706,8 @@ export class Distiller {
                     continue;
                 }
                 if (op.op === 'create' && typeof op.title === 'string' && typeof op.conclusion === 'string') {
+                    const links = await this.acceptLinks(op, slugs);
+                    applied.rejectedLinks += links.rejected;
                     const res = await this.service.saveTopic({
                         title: op.title,
                         conclusion: op.conclusion,
@@ -522,14 +720,18 @@ export class Distiller {
                         recommendations: op.recommendations,
                         status: op.status === 'stable' ? 'stable' : 'draft',
                         source: 'distill',
+                        links: links.targets,
                     });
                     applied.created.push(res.slug);
                     applied.consumedSlugs.push(res.slug);
+                    slugs.add(res.slug);
                 }
                 else if (op.op === 'update' && typeof op.slug === 'string') {
                     const existing = await this.service.store.readTopic(op.slug);
                     if (existing === undefined)
                         continue;
+                    const links = await this.acceptLinks(op, slugs);
+                    applied.rejectedLinks += links.rejected;
                     const res = await this.service.saveTopic({
                         title: existing.fm.title,
                         conclusion: typeof op.conclusion === 'string' ? op.conclusion : undefined,
@@ -537,9 +739,11 @@ export class Distiller {
                         status: op.status === 'stable' || op.status === 'deprecated' ? op.status : undefined,
                         slug: op.slug,
                         source: 'distill',
+                        links: links.targets,
                     });
                     applied.updated.push(res.slug);
                     applied.consumedSlugs.push(res.slug);
+                    slugs.add(res.slug);
                 }
                 else {
                     continue;
@@ -552,6 +756,37 @@ export class Distiller {
         }
         return applied;
     }
+    /**
+     * A2 links whitelist: a link survives only when its normalized target is a
+     * slug that already exists or belongs to this batch (`knownSlugs`), and not
+     * the op's own topic. Everything else is stripped and ledgered
+     * (`link-ref-rejected` — a dead edge must at least leave a trace). Returns
+     * the surviving targets (undefined when none — no Links section is written)
+     * plus the rejection count for the run detail.
+     */
+    async acceptLinks(op, knownSlugs) {
+        if (!Array.isArray(op.links) || op.links.length === 0)
+            return { targets: undefined, rejected: 0 };
+        const self = opKey(op);
+        const accepted = new Set();
+        let rejected = 0;
+        for (const raw of op.links) {
+            if (typeof raw !== 'string')
+                continue;
+            const target = okf.normalizeLinkTarget(raw);
+            if (target === undefined || target === self || !knownSlugs.has(target)) {
+                await recordPipelineEvent(this.service.store.root, {
+                    at: new Date().toISOString(),
+                    kind: 'link-ref-rejected',
+                    detail: { op: self, ref: raw },
+                });
+                rejected += 1;
+                continue;
+            }
+            accepted.add(target);
+        }
+        return { targets: accepted.size > 0 ? [...accepted] : undefined, rejected };
+    }
 }
 /** Extract the first balanced JSON object from model output (tolerates fences). */
 export function parseOps(raw) {

package/lib/embedding.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Local embedding client (ollama) — the semantic layer behind the nearFloor
+ * reranker (A4 决议 2, spec §3.1).
+ *
+ * Semantics (mirror of jev/client's outcome mode):
+ *  - every failure returns as a structured {ok:false, outcome} result, NEVER
+ *    a throw — the caller degrades explicitly to the pure-lexical path;
+ *  - one AbortSignal.timeout per request, NO retry (query 2s / batch 30s);
+ *  - localhost only in v1 (ADR 0017 local exception). Remote providers do
+ *    not exist here by design: a remote embedding may only ever enter a
+ *    slow-lane/offline path, never the fast lane (red line ①).
+ *
+ * @module embedding
+ */
+/** Default ollama bind (the plugin's own default; OLLAMA_HOST overrides). */
+export declare const DEFAULT_EMBED_HOST = "http://127.0.0.1:11434";
+/** Provider default model when embeddingModel is the '' sentinel
+ *  (spec §7: ollama → nomic-embed-text, 768 dims, A1 §5 measured). */
+export declare const DEFAULT_EMBED_MODEL = "nomic-embed-text";
+/** Query-side timeout — the reranker sits in the spliced hot path; a slow
+ *  ollama must lose the race, not the injection. */
+export declare const EMBED_QUERY_TIMEOUT_MS = 2000;
+/** Batch-side timeout (index rebuild: A1 measured ~9.5s for 137 topics). */
+export declare const EMBED_BATCH_TIMEOUT_MS = 30000;
+/** Per-text byte cap before anything leaves the process (query端 p50=153 tok
+ *  ~ well under this; the cap only bites on paste pollution). */
+export declare const MAX_TEXT_BYTES = 2048;
+/** The only provider v1 speaks. Anything else is an explicit
+ *  unsupported_provider outcome, not a silent attempt. */
+export declare const SUPPORTED_PROVIDER = "ollama";
+/** The config slice the embed functions need (pass straight from
+ *  TopicsConfigValue). '' sentinels: provider off / provider default model. */
+export interface EmbeddingConfig {
+    provider?: string;
+    model?: string;
+    /** Explicit host; absent → OLLAMA_HOST env → DEFAULT_EMBED_HOST. */
+    host?: string;
+}
+/** Resolve the ollama base URL: explicit arg wins, then OLLAMA_HOST, then
+ *  the localhost default. Bare `host:port` values get the http:// prefix
+ *  (ollama's own OLLAMA_HOST convention); trailing slashes are trimmed. */
+export declare function resolveEmbedHost(explicit?: string): string;
+/** '' sentinel → provider default model. */
+export declare function resolveEmbedModel(model?: string): string;
+/** Truncate a string to ≤ maxBytes UTF-8 bytes WITHOUT splitting a multibyte
+ *  character: cut at the byte cap, then back off over any continuation bytes
+ *  (0b10xxxxxx) so the decoded tail is never a replacement char. */
+export declare function truncateUtf8(text: string, maxBytes?: number): string;
+export type EmbeddingFailureOutcome = 'provider_off' | 'unsupported_provider' | 'empty_input' | 'network' | 'timeout' | 'model_missing' | 'http_4xx' | 'http_5xx' | 'bad_json' | 'bad_shape';
+export interface EmbedBatchOk {
+    ok: true;
+    /** Vectors aligned 1:1 with the (truncated) input texts. */
+    vectors: number[][];
+    model: string;
+    dim: number;
+    latencyMs: number;
+}
+export interface EmbedQueryOk {
+    ok: true;
+    vector: number[];
+    model: string;
+    dim: number;
+    latencyMs: number;
+}
+export interface EmbedFailure {
+    ok: false;
+    outcome: EmbeddingFailureOutcome;
+    message: string;
+    host: string;
+    model: string;
+    latencyMs: number;
+}
+export type EmbedResult = EmbedBatchOk | EmbedFailure;
+export type EmbedQueryResult = EmbedQueryOk | EmbedFailure;
+export type ProbeResult = {
+    ok: true;
+    host: string;
+    model: string;
+    dim: number;
+    latencyMs: number;
+} | EmbedFailure;
+/** Batch-embed texts (index build/rebuild path). Vectors align 1:1 with the
+ *  input order; each text is truncated to MAX_TEXT_BYTES first. */
+export declare function embedTexts(texts: readonly string[], config?: EmbeddingConfig, opts?: {
+    timeoutMs?: number;
+}): Promise<EmbedResult>;
+/** Embed one query (reranker hot path, 2s budget). Empty/whitespace queries
+ *  fail locally with 'empty_input' — nothing leaves the process. */
+export declare function embedQuery(query: string, config?: EmbeddingConfig, opts?: {
+    timeoutMs?: number;
+}): Promise<EmbedQueryResult>;
+/**
+ * Probe: is the server there, is the model pulled? One micro embed call —
+ * unlike a /api/tags listing it validates the FULL path (server + model +
+ * response shape) and yields the vector dim for index validation, at the
+ * same 15-30ms cost (A1 §5). Structured result; never throws.
+ */
+export declare function probeEmbedding(config?: EmbeddingConfig, opts?: {
+    timeoutMs?: number;
+}): Promise<ProbeResult>;
+/**
+ * Build an embedder handle for retrieval's `ensureIndexFresh` — a callable
+ * embedTexts bound to this config, carrying the RESOLVED model identity the
+ * index must match. ensureIndexFresh reads `.model` only; the actual
+ * rebuild stays with the caller.
+ */
+export declare function embedderWith(config: EmbeddingConfig): ((texts: readonly string[]) => Promise<EmbedResult>) & {
+    model: string;
+};
+/** Hard sync budget for the hot-lane query embed. Generous over the measured
+ *  15-30ms, merciless for a wedged server. */
+export declare const EMBED_QUERY_SYNC_TIMEOUT_MS = 250;
+export declare function embedQuerySync(query: string, config?: EmbeddingConfig): EmbedQueryResult;