@modusensus/dsh-mneme 0.8.3 → 0.8.5

package/src/dream.js

@@ -1,11 +1,11 @@
 import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts, cosineSimilarity } from "./dream/clustering.js";
+import { clusterByTag, intersectEvidence } from "./dream/narratives.js";
 import { scopeKeyOf } from "./scope.js";
 import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
 export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
 
-
 // Extract the first JSON array from LLM output, tolerating markdown fences,
 // leading/trailing prose, and common wrapper noise. Returns an array or null.
 function extractJsonArray(text) {
@@ -231,7 +231,12 @@ async function streamText(ctx, options, onUsage, onStreamError) {
   let text = "";
   for await (const chunk of ctx.llm.stream(options)) {
     if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-    if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk);
+    // DSH 的 StreamChunk 契约把用量嵌在 chunk.usage（TokenUsage：inputTokens /
+    // outputTokens / …），chunk 顶层没有 token 字段——把整个 chunk 当用量对象交给
+    // reporter，input/output 恒为 undefined，审计行落 0（v0.8.4 实测：7 天 49 次
+    // success 调用 token 全 0，面板「LLM 消耗」长期显示 0）。`?? chunk` 兜底把用量
+    // 平铺在顶层的替身。
+    if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk.usage ?? chunk);
     if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
       // dsh-llm rc.1 turns adapter-stage failures (unknown provider route,
       // UNSUPPORTED_REASONING_EFFORT from resolveCallWithInfo, …) into a
@@ -362,6 +367,85 @@ async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError
   }
 }
 
+/** 向量索引同步（总览与叙述条共用）：fail-safe，失败只 warn 不反噬主流程。 */
+async function reEmbedMemory(semantic, memory, logger) {
+  if (!semantic?.embedder || !semantic?.vectorIndex || !memory) return;
+  try {
+    const v = await semantic.embedder.embedSingle([memory.title, memory.content].filter(Boolean).join("\n"));
+    if (v?.length) semantic.vectorIndex.saveEmbedding(memory.id, v);
+    if (semantic.embedder.modelHash) semantic.vectorIndex.markModel?.(semantic.embedder.modelHash, semantic.embedder.dimension);
+  } catch (error) {
+    logger?.warn?.(`dsh-mneme dream: re-embed failed: ${String(error)}`);
+  }
+}
+
+/**
+ * 叙述条阶段（#164 对齐，opt-in dreamNarrativeEnabled）：共享 tag 主题聚类 →
+ * 单次 LLM 调用按簇合成叙述 → 证据求交（防捏造，dream/narratives.js 纯函数）
+ * → saveWithDedupe(source="narrative", _overwrite) 落库。按需检索不常驻注入。
+ * 任何失败降级为 0 条，绝不反噬 dream 主流程。
+ */
+async function generateNarratives({ ctx, service, config, route, language, effort, semantic, logger }) {
+  const inputs = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
+  const clusters = clusterByTag(inputs, { minCluster: config.dreamNarrativeMinCluster ?? 3 });
+  if (!clusters.length) return 0;
+
+  const listing = clusters
+    .map(({ tag, members }) =>
+      [`# ${tag}`, ...members.map((m) => `- id=${m.id} | title=${m.title} | ${m.content}`)].join("\n"))
+    .join("\n\n");
+  let streamFailure = "";
+  const runNarratives = (withEffort) => {
+    streamFailure = "";
+    return runAuditedLlm(ctx, service, config, {
+      triggerSource: "autoDream",
+      operationType: "dream_narrative",
+      modelId: `${route.provider}:${route.model}`,
+      relatedMemoryIds: clusters.flatMap((c) => c.members.map((m) => m.id)),
+      streamError: () => streamFailure
+    }, (reportUsage) => streamText(ctx, {
+      provider: route.provider,
+      model: route.model,
+      purpose: "compaction",
+      maxTokens: config.dreamMaxTokens ?? 2048,
+      ...(withEffort && effort ? { reasoningEffort: effort } : {}),
+      messages: [
+        { role: "system", content: [{ type: "text", text: STR.prompts.narrative[language] }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+        { role: "user", content: [{ type: "text", text: listing }], source: { kind: "plugin", plugin: "dsh-mneme" } }
+      ]
+    }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
+  };
+  const text = await withEffortFallback(ctx, effort, () => runNarratives(true), () => runNarratives(false), () => streamFailure);
+
+  const entries = extractJsonArray(text);
+  if (!Array.isArray(entries)) return 0;
+  const clusterByOfferedTag = new Map(clusters.map((c) => [c.tag, c]));
+  const now = new Date().toISOString();
+  let stored = 0;
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const cluster = clusterByOfferedTag.get(typeof entry.tag === "string" ? entry.tag : "");
+    const content = String(entry.content ?? "").trim();
+    if (!cluster || !content) continue; // 未提供的 tag / 空叙述 → 跳过
+    const evidenceIds = intersectEvidence(entry.evidence, cluster.members);
+    const { memory } = service.saveWithDedupe({
+      type: "summary",
+      title: STR.narrativeTitle[language](cluster.tag),
+      content,
+      importance: 3,
+      tags: [cluster.tag],
+      source: "narrative",
+      evidence: evidenceIds.map((id) => ({ memory_id: id, op: "support", at: now })),
+      _overwrite: true
+    });
+    if (!memory) continue;
+    stored++;
+    // 叙述条按需可检索：向量索引同步（与总览共用 reEmbedMemory，fail-safe）。
+    await reEmbedMemory(semantic, memory, logger);
+  }
+  return stored;
+}
+
 /**
  * Resolve the reasoning effort to actually send for a dream/sleep route.
  *
@@ -671,7 +755,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   let lastRunAt = 0;
 
   function shouldTrigger(service) {
-    const memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    const memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
     const count = memories.length;
     const chars = totalChars(memories);
     const overBase = count >= baseline.count + thresholdCount || chars >= baseline.chars + thresholdChars;
@@ -734,7 +818,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   async function runDream(ctx, service, config) {
     const language = langOf(config);
     const logger = ctx.logger;
-    let memories = service.all().filter((m) => !m.archived && m.type !== "summary");
+    let memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
     if (memories.length === 0) return { ok: true, applied: 0, skipped: true, summary: false };
     // v0.4.4 滑动窗口：只 consolidation 最近 dreamMaxSnapshotSize 条记忆，
     // 窗口外的旧记忆不进 snapshot（大记忆量下全量快照会撑爆 LLM 输入，配合
@@ -1126,24 +1210,59 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     let summaryStreamFailure = "";
     const runSummary = (withEffort) => {
       summaryStreamFailure = "";
+      // Issue #258：总览阶段可用 dreamSummaryProvider/dreamSummaryModel 走独立路由
+      //（默认空 = 沿用 dream 路由）；输入侧有 dreamSummaryMaxInputs 硬上限，
+      // 按窗口同款 updated_at 倒序保留最新的（见下方 summaryInputs）。
+      const summaryRoute = (config.dreamSummaryProvider && config.dreamSummaryModel)
+        ? { provider: config.dreamSummaryProvider, model: config.dreamSummaryModel }
+        : route;
       return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
       operationType: "dream_summarize",
-      modelId: `${route.provider}:${route.model}`,
+      modelId: `${summaryRoute.provider}:${summaryRoute.model}`,
       relatedMemoryIds: [],
       streamError: () => summaryStreamFailure
     }, (reportUsage) => streamText(ctx, {
-      provider: route.provider,
-      model: route.model,
+      provider: summaryRoute.provider,
+      model: summaryRoute.model,
       purpose: "compaction",
       maxTokens: config.dreamMaxTokens ?? 2048,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: STR.prompts.dreamSummary[language] }], source: { kind: "plugin", plugin: "dsh-mneme" } },
-        { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }], source: { kind: "plugin", plugin: "dsh-mneme" } }
+        { role: "user", content: [{ type: "text", text: summaryInputs.map((m) => `- ${m.title}: ${m.content}`).join("\n") }], source: { kind: "plugin", plugin: "dsh-mneme" } }
       ]
     }, reportUsage, (reason) => { summaryStreamFailure = describeStreamFailure(reason); }));
     };
+    // Resident status bar (#164 alignment): the overview is THE one resident
+    // narrative — summary tier 0, refreshed every run via _overwrite (supersede
+    // v1, content_history traceable). Its 口径 (what snapshot produced it) is
+    // stamped into the content so the standing answer is always auditable; the
+    // formal evidence column lands with the narrative-bars batch.
+    // Issue #258：输入硬上限（条数）——原全库无界，把 dream 路由指向小 ctx
+    // 模型时 120k token 当场 CONTEXT_WINDOW_EXCEEDED（#258 实测），且随库增长
+    // 渐进恶化。倒序排序与 consolidate 窗口同款（updated_at desc, id tiebreak），
+    // 保留最新的；0 = 关闭上限（回归全库行为，调用方自担 ctx）。
+    // #230：document 指针行不进总览（与 dream/sleep 五个候选池的同款排除）。
+    const summaryAll = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    const summaryMaxInputs = Number.isInteger(config.dreamSummaryMaxInputs) ? config.dreamSummaryMaxInputs : 0;
+    const summaryInputs = summaryMaxInputs > 0 && summaryAll.length > summaryMaxInputs
+      ? [...summaryAll]
+        .sort((a, b) => {
+          const ta = String(a.updated_at ?? "");
+          const tb = String(b.updated_at ?? "");
+          if (ta < tb) return 1;
+          if (ta > tb) return -1;
+          return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        })
+        .slice(0, summaryMaxInputs)
+      : summaryAll;
+
+    const summaryScope = STR.summaryScope[language](
+      summaryInputs.length,
+      runId.slice(0, 8),
+      new Date().toISOString().slice(0, 10)
+    );
     try {
       // Bug8: the summary call is audited too (operation dream_summarize).
       summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false), () => summaryStreamFailure);
@@ -1156,21 +1275,32 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       // Bug5 carve-out: the library overview is regenerated every run, so it
       // must REPLACE the previous overview (not append — that would grow the
       // summary unboundedly). `_overwrite` still archives the old overview into
-      // content_history before replacing it.
-      service.saveWithDedupe({ type: "summary", title: STR.summaryTitle[language], content: summaryText.trim(), importance: 5, source: "dream", _overwrite: true });
+      // content_history before replacing it. Content carries the snapshot-scope
+      // footer computed above — the resident bar states its own 口径.
+      service.saveWithDedupe({ type: "summary", title: STR.summaryTitle[language], content: `${summaryText.trim()}${summaryScope}`, importance: 5, source: "dream", _overwrite: true });
       summaryStored = true;
       // Re-embed the fresh summary so the index stays in sync with the store.
       if (semantic?.embedder && semantic?.vectorIndex) {
         try {
-          const summary = service.all().find((m) => m.type === "summary");
-          if (summary) {
-            const v = await semantic.embedder.embedSingle([summary.title, summary.content].filter(Boolean).join("\n"));
-            if (v?.length) semantic.vectorIndex.saveEmbedding(summary.id, v);
-            if (semantic.embedder.modelHash) semantic.vectorIndex.markModel?.(semantic.embedder.modelHash, semantic.embedder.dimension);
-          }
+          // source="dream" 限定：叙述条（source=narrative）同为 summary 类型，
+          // 不加限定时 find 可能截胡，把总览的 re-embed 花在叙述条上。
+          const summary = service.all().find((m) => m.type === "summary" && m.source === "dream");
+          if (summary) await reEmbedMemory(semantic, summary, logger);
         } catch { /* best-effort */ }
       }
     }
+    // Narrative bars (#164 alignment, opt-in dreamNarrativeEnabled): per-topic
+    // on-demand narratives after consolidation + summary. Additive phase —
+    // failures degrade to zero narratives, never break the run.
+    let narrativesStored = 0;
+    if (config.dreamNarrativeEnabled === true) {
+      try {
+        narrativesStored = await generateNarratives({ ctx, service, config, route, language, effort, semantic, logger });
+      } catch (error) {
+        logger?.warn?.(`dsh-mneme dream: narrative phase failed: ${String(error)}`);
+      }
+    }
+
     // Honest status assignment (never a fake ok):
     //   reconcile — some decisions validated but did not commit (CAS/rollback).
     //   noop      — nothing changed and no summary persisted: truly an empty
@@ -1206,6 +1336,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       failures,
       frozen: frozenCount,
       summary: summaryStored,
+      narratives: narrativesStored,
       // Issue #104：只有真发生跳过时才落库（degraded 也可能仅因 summary 为空），
       // ok 轮留 NULL，避免「空数组」与「无此字段」两种假明细占据审计行。
       skipped: skippedInvalid ? skipped : undefined

package/src/embedding.js

@@ -1,177 +1,177 @@
-// OpenAI-compatible embedding client for vector search. DSH's LLM service is
-// chat-only, so dsh-mneme calls an external `/embeddings` endpoint itself.
-// Works with OpenAI, SiliconFlow, Zhipu, local Ollama (via OpenAI-compatible
-// proxy) and any provider exposing the standard embeddings API.
-const DEFAULT_TIMEOUT_MS = 15000;
-
-/** djb2 — stable, fast fingerprint for a provider/model string. Mirrors the
- *  hash used by the local embedders so all backends share one fingerprint
- *  format (model#hex) for vector_meta consistency checks. */
-function hashString(s) {
-  let h = 5381;
-  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
-  return h.toString(16);
-}
-
-/** Full provider+model fingerprint used for index-consistency checks. */
-function modelHashOf(model) {
-  return `${model}#${hashString(model)}`;
-}
-
-/** Normalize a configured baseUrl into the full embeddings endpoint URL. */
-function embeddingsUrl(baseUrl) {
-  const base = String(baseUrl ?? "").trim().replace(/\/+$/, "");
-  if (!base) return "";
-  // Accept both "https://host/v1" and a full path ending in /embeddings.
-  if (/\/embeddings$/i.test(base)) return base;
-  return `${base}/embeddings`;
-}
-
-/**
- * Call the embeddings API for one text. Resolves to a Float64 array, or null
- * when the provider is not configured, the call fails, or the response is
- * unusable. Never throws: failures degrade to keyword search.
- */
-export async function embedText({ baseUrl, apiKey, model }, text) {
-  const url = embeddingsUrl(baseUrl);
-  if (!url || !apiKey || !model || !text) return null;
-  let res;
-  try {
-    res = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${apiKey}`
-      },
-      body: JSON.stringify({ model, input: String(text).slice(0, 8000) }),
-      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
-    });
-  } catch {
-    return null;
-  }
-  if (!res.ok) return null;
-  let body;
-  try {
-    body = await res.json();
-  } catch {
-    return null;
-  }
-  const vec = body?.data?.[0]?.embedding;
-  return Array.isArray(vec) && vec.length ? Array.from(vec) : null;
-}
-
-/**
- * Embedder bound to the current settings + store: on each write it re-embeds
- * the row's title+content and stores the vector. Failures are swallowed so a
- * flaky embedding endpoint never breaks memory writes.
- *
- * `vectorIndex` (optional) is the vector_meta fingerprint holder: after any
- * successful embed the model that produced the vectors is recorded, so the
- * index can detect drift and the auto-reindex backfill knows what to rebuild.
- */
-export function createEmbedder({ store, settings, logger, vectorIndex }) {
-  // Dimension of the most recent successful embed, exposed for fingerprinting.
-  let _dimension = 0;
-
-  /** Record the producing model fingerprint in vector_meta (best-effort). */
-  function markModel(cfg, dimension) {
-    if (!vectorIndex || typeof vectorIndex.markModel !== "function") return;
-    try {
-      vectorIndex.markModel(modelHashOf(cfg.model), dimension);
-    } catch { /* metadata write is best-effort */ }
-  }
-
-  // issue #135: 「配置是否齐备」的唯一判据 —— embed()/embedFor() 的守卫与下面
-  // ready/configured 两个 getter 共用，避免以后改一处漏一处。
-  const configComplete = (cfg) => !!(cfg?.enabled && cfg.baseUrl && cfg.apiKey && cfg.model);
-
-  async function embedFor(id, title, content) {
-    const cfg = settings.getVectorConfig();
-    if (!configComplete(cfg)) return;
-    const text = [title, content].filter(Boolean).join("\n");
-    const vector = await embedText(cfg, text);
-    if (vector) {
-      store.setEmbedding(id, vector);
-      _dimension = vector.length;
-      // Bug3: record which model produced the current vectors so the index can
-      // detect drift and skip a redundant backfill when nothing changed.
-      markModel(cfg, vector.length);
-      logger?.info?.(`[dsh-mneme] embedded memory ${id} (dim=${vector.length})`);
-    }
-  }
-
-  return {
-    // Display name for /semantic: a literal's constructor.name is "Object",
-    // which the status card would render verbatim.
-    name: "OpenAI",
-    /**
-     * issue #135: 这个 embedder 没有异步初始化，`"ready" in embedder` 的通用
-     * 分支会把它恒判为可用 —— 而 vector-config 四项有缺时它一条都嵌不出来。
-     * 对外报真实可用性，让 /semantic 的 ready 不再是「绿色假阳性」。
-     * 用 getter 而非快照字段：设置面板改完配置无需重启即生效（与 embed() 同源读取）。
-     */
-    get ready() {
-      return configComplete(settings.getVectorConfig());
-    },
-    /**
-     * 与 ready 同源，分开两个名字是给 /semantic 用：local/ollama 的
-     * ready=false 表示「还在初始化」，而这里的 false 表示「根本没配」。
-     */
-    get configured() {
-      return configComplete(settings.getVectorConfig());
-    },
-    /** Fire-and-forget re-embed of a memory after any write. */
-    schedule(memory) {
-      if (!memory?.id) return;
-      embedFor(memory.id, memory.title, memory.content).catch(() => {});
-    },
-
-    /** Embed one text and return its vector (null on failure/disabled). */
-    async embed(query) {
-      const cfg = settings.getVectorConfig();
-      if (!configComplete(cfg)) return null;
-      const vector = await embedText(cfg, query);
-      if (vector) _dimension = vector.length;
-      return vector;
-    },
-
-    // Bug1: single-text adapter. Local/ollama embedders expose embedSingle
-    // natively; the legacy OpenAI-compatible client only has embed. This
-    // adapter unifies the interface so vector-index rebuildIndex (which guards
-    // on `typeof embedder.embedSingle === "function"`) accepts this embedder.
-    async embedSingle(text) {
-      if (typeof this.embed === "function") return this.embed(text);
-      return null;
-    },
-
-    /** Model fingerprint (model#hex), or undefined when not configured. */
-    get modelHash() {
-      const cfg = settings.getVectorConfig();
-      return cfg?.enabled && cfg.model ? modelHashOf(cfg.model) : undefined;
-    },
-
-    /** Dimension of the last successful embed (0 when never embedded). */
-    get dimension() {
-      return _dimension || undefined;
-    },
-
-    /** Batch re-index rows still missing an embedding. */
-    async reindexMissing(limit = 50) {
-      const cfg = settings.getVectorConfig();
-      if (!cfg?.enabled) return { indexed: 0, skipped: 0 };
-      const rows = store.needsEmbedding(limit);
-      let indexed = 0;
-      for (const row of rows) {
-        const text = [row.title, row.content].filter(Boolean).join("\n");
-        const vector = await embedText(cfg, text);
-        if (vector) {
-          store.setEmbedding(row.id, vector);
-          _dimension = vector.length;
-          indexed++;
-        }
-      }
-      if (indexed > 0) markModel(cfg, _dimension || undefined);
-      return { indexed, skipped: rows.length - indexed };
-    }
-  };
-}
+// OpenAI-compatible embedding client for vector search. DSH's LLM service is
+// chat-only, so dsh-mneme calls an external `/embeddings` endpoint itself.
+// Works with OpenAI, SiliconFlow, Zhipu, local Ollama (via OpenAI-compatible
+// proxy) and any provider exposing the standard embeddings API.
+const DEFAULT_TIMEOUT_MS = 15000;
+
+/** djb2 — stable, fast fingerprint for a provider/model string. Mirrors the
+ *  hash used by the local embedders so all backends share one fingerprint
+ *  format (model#hex) for vector_meta consistency checks. */
+function hashString(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h.toString(16);
+}
+
+/** Full provider+model fingerprint used for index-consistency checks. */
+function modelHashOf(model) {
+  return `${model}#${hashString(model)}`;
+}
+
+/** Normalize a configured baseUrl into the full embeddings endpoint URL. */
+function embeddingsUrl(baseUrl) {
+  const base = String(baseUrl ?? "").trim().replace(/\/+$/, "");
+  if (!base) return "";
+  // Accept both "https://host/v1" and a full path ending in /embeddings.
+  if (/\/embeddings$/i.test(base)) return base;
+  return `${base}/embeddings`;
+}
+
+/**
+ * Call the embeddings API for one text. Resolves to a Float64 array, or null
+ * when the provider is not configured, the call fails, or the response is
+ * unusable. Never throws: failures degrade to keyword search.
+ */
+export async function embedText({ baseUrl, apiKey, model }, text) {
+  const url = embeddingsUrl(baseUrl);
+  if (!url || !apiKey || !model || !text) return null;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({ model, input: String(text).slice(0, 8000) }),
+      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return null;
+  }
+  const vec = body?.data?.[0]?.embedding;
+  return Array.isArray(vec) && vec.length ? Array.from(vec) : null;
+}
+
+/**
+ * Embedder bound to the current settings + store: on each write it re-embeds
+ * the row's title+content and stores the vector. Failures are swallowed so a
+ * flaky embedding endpoint never breaks memory writes.
+ *
+ * `vectorIndex` (optional) is the vector_meta fingerprint holder: after any
+ * successful embed the model that produced the vectors is recorded, so the
+ * index can detect drift and the auto-reindex backfill knows what to rebuild.
+ */
+export function createEmbedder({ store, settings, logger, vectorIndex }) {
+  // Dimension of the most recent successful embed, exposed for fingerprinting.
+  let _dimension = 0;
+
+  /** Record the producing model fingerprint in vector_meta (best-effort). */
+  function markModel(cfg, dimension) {
+    if (!vectorIndex || typeof vectorIndex.markModel !== "function") return;
+    try {
+      vectorIndex.markModel(modelHashOf(cfg.model), dimension);
+    } catch { /* metadata write is best-effort */ }
+  }
+
+  // issue #135: 「配置是否齐备」的唯一判据 —— embed()/embedFor() 的守卫与下面
+  // ready/configured 两个 getter 共用，避免以后改一处漏一处。
+  const configComplete = (cfg) => !!(cfg?.enabled && cfg.baseUrl && cfg.apiKey && cfg.model);
+
+  async function embedFor(id, title, content) {
+    const cfg = settings.getVectorConfig();
+    if (!configComplete(cfg)) return;
+    const text = [title, content].filter(Boolean).join("\n");
+    const vector = await embedText(cfg, text);
+    if (vector) {
+      store.setEmbedding(id, vector);
+      _dimension = vector.length;
+      // Bug3: record which model produced the current vectors so the index can
+      // detect drift and skip a redundant backfill when nothing changed.
+      markModel(cfg, vector.length);
+      logger?.info?.(`[dsh-mneme] embedded memory ${id} (dim=${vector.length})`);
+    }
+  }
+
+  return {
+    // Display name for /semantic: a literal's constructor.name is "Object",
+    // which the status card would render verbatim.
+    name: "OpenAI",
+    /**
+     * issue #135: 这个 embedder 没有异步初始化，`"ready" in embedder` 的通用
+     * 分支会把它恒判为可用 —— 而 vector-config 四项有缺时它一条都嵌不出来。
+     * 对外报真实可用性，让 /semantic 的 ready 不再是「绿色假阳性」。
+     * 用 getter 而非快照字段：设置面板改完配置无需重启即生效（与 embed() 同源读取）。
+     */
+    get ready() {
+      return configComplete(settings.getVectorConfig());
+    },
+    /**
+     * 与 ready 同源，分开两个名字是给 /semantic 用：local/ollama 的
+     * ready=false 表示「还在初始化」，而这里的 false 表示「根本没配」。
+     */
+    get configured() {
+      return configComplete(settings.getVectorConfig());
+    },
+    /** Fire-and-forget re-embed of a memory after any write. */
+    schedule(memory) {
+      if (!memory?.id) return;
+      embedFor(memory.id, memory.title, memory.content).catch(() => {});
+    },
+
+    /** Embed one text and return its vector (null on failure/disabled). */
+    async embed(query) {
+      const cfg = settings.getVectorConfig();
+      if (!configComplete(cfg)) return null;
+      const vector = await embedText(cfg, query);
+      if (vector) _dimension = vector.length;
+      return vector;
+    },
+
+    // Bug1: single-text adapter. Local/ollama embedders expose embedSingle
+    // natively; the legacy OpenAI-compatible client only has embed. This
+    // adapter unifies the interface so vector-index rebuildIndex (which guards
+    // on `typeof embedder.embedSingle === "function"`) accepts this embedder.
+    async embedSingle(text) {
+      if (typeof this.embed === "function") return this.embed(text);
+      return null;
+    },
+
+    /** Model fingerprint (model#hex), or undefined when not configured. */
+    get modelHash() {
+      const cfg = settings.getVectorConfig();
+      return cfg?.enabled && cfg.model ? modelHashOf(cfg.model) : undefined;
+    },
+
+    /** Dimension of the last successful embed (0 when never embedded). */
+    get dimension() {
+      return _dimension || undefined;
+    },
+
+    /** Batch re-index rows still missing an embedding. */
+    async reindexMissing(limit = 50) {
+      const cfg = settings.getVectorConfig();
+      if (!cfg?.enabled) return { indexed: 0, skipped: 0 };
+      const rows = store.needsEmbedding(limit);
+      let indexed = 0;
+      for (const row of rows) {
+        const text = [row.title, row.content].filter(Boolean).join("\n");
+        const vector = await embedText(cfg, text);
+        if (vector) {
+          store.setEmbedding(row.id, vector);
+          _dimension = vector.length;
+          indexed++;
+        }
+      }
+      if (indexed > 0) markModel(cfg, _dimension || undefined);
+      return { indexed, skipped: rows.length - indexed };
+    }
+  };
+}