@modusensus/dsh-mneme 0.8.13 → 0.8.14

package/src/semantic.js

@@ -0,0 +1,229 @@
+// src/semantic.js —— embedder/reranker 装配与 boot 自动回填。
+// 纯搬移自 src/index.js(2026-10,PR2):backfillMissingEmbeddings(原 :150-186)与
+// 装配段(原 :311-477),行为逐字节对齐,仅两处已注记的机械差异(ctx.logger → 注入
+// logger;boot 回填的首查计时器纳入 dispose)。搬移原因:daemon(dsh-mneme-serve,
+// #363)与宿主要共用同一套语义装配——「向量检索开箱即用」的承诺落在两侧同一份
+// 代码上,而不是 daemon 复刻一份会漂移的副本。拆法遵循 AGENTS.md 尺寸约定:
+// 纯搬移独立 PR、原文件调用方零改动(backfill 经 index.js barrel 再出口,测试照旧)。
+//
+// 时序契约(搬移前即如此,由 index.js 全量测试与 reindex-backfill.test.js 锁):
+//   lightMode / openai / 同步构造失败 → applyHumanEdits 立即;
+//   local|ollama → init 成功后 applyHumanEdits;#118 重试(1 + 4×15s)耗尽 →
+//   setEmbedder(null) 检索降级关键词,随后仍 applyHumanEdits;
+//   reranker 异步 init 失败只降级 rerank 自身,绝不影响 search。
+import { createEmbedder } from "./embedding.js";
+import { createEmbedderByProvider } from "./local-embedder.js";
+import { LocalReranker } from "./reranker.js";
+
+/**
+ * Issue #128: bounded backfill of rows still missing an embedding (active rows
+ * only — needsEmbedding filters archived/forgotten). Exported for tests.
+ *
+ * Runs regardless of the model fingerprint: the old call-site gate returned
+ * early when vector_meta already held the embedder's hash, permanently
+ * orphaning rows whose embed failed at write time (embedder not ready /
+ * provider rate limit) — one successful embed was enough to never backfill
+ * again. markModel is idempotent when the fingerprint already matches, so
+ * re-running costs nothing beyond the actually-missing rows.
+ */
+export async function backfillMissingEmbeddings({
+  store, embedder, vectorIndex, logger,
+  maxTotal = 500, batchSize = 10, rateLimitMs = 200
+}) {
+  let indexed = 0;
+  for (let done = 0; done < maxTotal;) {
+    const rows = store.needsEmbedding(batchSize);
+    if (!rows.length) break;
+    for (const row of rows) {
+      try {
+        const text = [row.title, row.content].filter(Boolean).join("\n");
+        const vector = await embedder.embedSingle(text);
+        if (vector?.length) {
+          store.setEmbedding(row.id, vector);
+          indexed++;
+        }
+      } catch { /* skip the bad row */ }
+    }
+    done += rows.length;
+    // Rate limit: space out batches so the provider is not hammered.
+    if (store.needsEmbedding(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
+  }
+  if (indexed > 0 && embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
+  logger?.info?.(`[dsh-mneme] auto-reindex backfilled ${indexed} embeddings on boot`);
+  return indexed;
+}
+
+/**
+ * 组装语义管线(embedder + reranker)并挂到 service 上,随后调度 boot 自动回填。
+ * @param {object} opts
+ *   store/service/settings/vectorIndex — 宿主与 daemon 同形传入;
+ *   cfg            — 宿主传合并后的完整配置;daemon 传语义子集(默认值锚定 config.js);
+ *   logger         — console 形状(原代码读 ctx.logger,搬移后注入);
+ *   applyHumanEdits— 人改镜像合并回调(index.js 闭包,读 mirror.readHumanEdits);
+ *                    在哪个分支何时被调是时序契约的一部分,见文件头;
+ *   lightMode      — 轻量档:整条向量管线关闭,无 embedder/reranker、不回填。
+ * @returns {{embedder, reranker, dispose}} embedder 构造失败(同步抛)时为 null;
+ *   init 异步失败经 #118 重试后 service 侧降级,此处引用仍在(dream/sleep 语义面
+ *   与搬移前一致)。dispose 清两个引导期计时器。
+ */
+export function createSemantic({ store, service, settings, cfg, logger, vectorIndex, applyHumanEdits, lightMode = false }) {
+  let embedder = null;
+  let reranker = null;
+  // #118: pending embedder-init retry timer, cleared on unload.
+  let embedRetryTimer = null;
+  // boot 回填首查计时器。搬移前在 index.js 是裸 setTimeout(不参与卸载清理);
+  // 纳入 dispose 是修悬挂,不改变启动行为。
+  let reindexTimer = null;
+
+  if (lightMode) {
+    // Light mode: the whole vector pipeline stays off — no embedder (nothing
+    // pulls in ONNX/transformers), no reranker, no boot backfill (the preset
+    // also cleared autoReindexOnBoot). Recall degrades to keyword search and
+    // human mirror edits still merge on boot.
+    applyHumanEdits();
+  } else if (cfg.embedProvider === "openai") {
+    // vectorIndex is passed so the legacy OpenAI embedder records the producing
+    // model fingerprint after each successful embed (Bug3).
+    embedder = createEmbedder({ store, settings, logger, vectorIndex });
+    service.setEmbedder(embedder);
+    // issue #135: 未配置时明确告警一次。此前 legacy OpenAI embedder 恒报
+    // ready=true，向量层「绿的但全哑」可以静默存在很久（本机持续了数周）。
+    // 只记日志、不阻断启动：轻量模式与「先跑起来再补配置」都是正当用法。
+    if (embedder.configured === false) {
+      logger?.warn?.(
+        "[dsh-mneme] 向量层未配置（vector-config 的 enabled/baseUrl/apiKey/model 有缺）："
+        + "语义召回、语义去重、rerank、sleep 冲突检测将静默失效，"
+        + "dream 的语义聚类会退化为全量窗口兜底。"
+        + "请在设置面板补全 embedding 端点与模型，或把 embedProvider 改为 local/ollama。"
+      );
+    }
+    // legacy OpenAI embedder needs no async init → human edits apply right away
+    applyHumanEdits();
+  } else {
+    try {
+      embedder = createEmbedderByProvider(cfg.embedProvider, {
+        model: cfg.embedProvider === "ollama" ? cfg.ollamaModel : cfg.localEmbedModel,
+        dimension: cfg.localEmbedDimension,
+        device: cfg.localEmbedDevice,
+        batchSize: cfg.localEmbedBatchSize,
+        // 池化方式必须与模型的训练口径一致（BGE 系 = CLS）。它既进 embed() 的调用，
+        // 也进 modelHash —— 池化改了就是换向量空间，既有索引会被判失配并重建。
+        pooling: cfg.localEmbedPooling,
+        cacheDir: cfg.embedModelCacheDir,
+        runtimeDir: cfg.runtimeDir,
+        // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
+        remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
+        baseUrl: cfg.ollamaBaseUrl,
+        logger
+      });
+      service.setEmbedder(embedder);
+      // issue #6: wait for extractor init before applying human edits, so
+      // scheduled embeddings see a ready embedder.
+      const bootEmbedder = () => embedder.init()
+        .then(() => { applyHumanEdits(); return true; })
+        .catch(() => false);
+      // #118: the old one-shot probe permanently degraded search to keyword
+      // when Ollama was briefly unreachable at boot (recoverable only by
+      // restart). Retry briefly (5 attempts total: 1 initial + 4 × 15s);
+      // search degrades to keyword meanwhile because per-query embed failures
+      // are swallowed.
+      bootEmbedder().then((ok) => {
+        if (ok) return;
+        let tries = 4;
+        const retry = () => {
+          if (tries-- <= 0) {
+            logger?.warn?.("[dsh-mneme] embedder init retries exhausted, search degrades to keyword");
+            service.setEmbedder(null);
+            applyHumanEdits();
+            return;
+          }
+          embedRetryTimer = setTimeout(async () => {
+            if (await bootEmbedder()) return;
+            retry();
+          }, 15_000);
+        };
+        logger?.warn?.("[dsh-mneme] embedder init failed, retrying");
+        retry();
+      });
+    } catch (error) {
+      logger?.warn?.(`[dsh-mneme] embedder unavailable, search degrades to keyword: ${String(error)}`);
+      applyHumanEdits();
+    }
+  }
+
+  // Cross-encoder rerank over recall candidates. Best-effort: a failed model
+  // load only disables reranking, never search itself. Explicit opt-in only
+  // (rerankEnabled defaults to false): constructing LocalReranker is what pulls
+  // in onnxruntime, so the default config never loads it (item ⑥).
+  if (cfg.rerankEnabled && cfg.rerankProvider === "local") {
+    try {
+      reranker = new LocalReranker({
+        model: cfg.rerankModel,
+        batchSize: cfg.rerankBatchSize,
+        maxCandidates: cfg.rerankMaxCandidates,
+        scoreThreshold: cfg.rerankScoreThreshold,
+        device: cfg.localEmbedDevice,
+        cacheDir: cfg.embedModelCacheDir,
+        runtimeDir: cfg.runtimeDir,
+        // #188：量化档默认 q8（此前不传 dtype 会去要 1GB 级 fp32 模型）；
+        // embedModelMirror 此前是死配置，现接成 transformers 的下载镜像。
+        useDtype: cfg.rerankDtype,
+        remoteHost: cfg.embedModelMirror,
+        resilientModelDownload: cfg.resilientModelDownload,
+        logger
+      });
+      service.setReranker(reranker);
+      reranker.init().catch((error) => {
+        logger?.warn?.(`[dsh-mneme] reranker init failed, rerank disabled: ${String(error)}`);
+        service.setReranker(null);
+      });
+    } catch (error) {
+      logger?.warn?.(`[dsh-mneme] reranker unavailable, rerank disabled: ${String(error)}`);
+    }
+  }
+
+  // Bug2: lazy auto-backfill of missing embeddings on boot. When the vector API
+  // is configured and rows still lack an embedding (e.g. written before vector
+  // search was enabled), the backfill runs in the background after a short
+  // delay. Gated on cfg.autoReindexOnBoot; rate-limited in small batches so a
+  // large backlog never floods the provider. Failures degrade silently —
+  // search stays keyword.
+  function scheduleAutoReindex() {
+    if (cfg.autoReindexOnBoot === false) return;
+    const attempt = (tries) => {
+      try {
+        if (!embedder || typeof embedder.embedSingle !== "function") return;
+        if ("ready" in embedder && embedder.ready !== true) {
+          // Local/ollama embedders init asynchronously; give them a moment
+          // before giving up on this boot (next boot retries).
+          // CodeRabbit on #365:嵌套重试计时器同样入册,否则 dispose 后仍可能
+          // 对已关库跑 needsEmbedding(有 try/catch 兜底只是日志噪声,但状态要收干净)。
+          if (tries > 0) reindexTimer = setTimeout(() => attempt(tries - 1), 2000);
+          return;
+        }
+        if (!store.needsEmbedding(1).length) return; // nothing to backfill
+        // Issue #128: no fingerprint gate here anymore — a matching fingerprint
+        // used to return early and permanently orphan rows whose embed failed
+        // at write time. See backfillMissingEmbeddings().
+        backfillMissingEmbeddings({ store, embedder, vectorIndex, logger })
+          .catch((error) => {
+            logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
+          });
+      } catch (error) {
+        logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
+      }
+    };
+    reindexTimer = setTimeout(() => attempt(5), 5000);
+  }
+  scheduleAutoReindex();
+
+  return {
+    embedder,
+    reranker,
+    dispose() {
+      if (embedRetryTimer !== null) { clearTimeout(embedRetryTimer); embedRetryTimer = null; }
+      if (reindexTimer !== null) { clearTimeout(reindexTimer); reindexTimer = null; }
+    }
+  };
+}

package/src/serve.js

@@ -0,0 +1,215 @@
+// src/serve.js —— 独立服务(daemon)运行时:mneme 在 DSH 宿主之外常驻的最小装配面
+// (#363 承诺的「官方推荐第三方挂载姿势」)。bin/dsh-mneme-serve.mjs 是它的 CLI 壳,
+// Mneme Bridge 这类第三方也可直接 import 本模块自行托管生命周期。
+//
+// 与宿主装配(src/index.js apply)的关系:只搬数据面 + 语义管线两块,每步注释锚定
+// index.js 来源行号。刻意不抽公共装配函数——apply 的其余环节(注入/工具/dream)与
+// 宿主 ctx 纠缠,防御段纪律是「最后动或不动」;本文件的漂移风险由 serve-bin 测试的
+// 多进程共存用例兜底(两侧真开同一个库互写互读)。
+//
+// 无 LLM:巩固(autoDream)与蒸馏(autoSummarize)结构上不在这里——巩固只属于 DSH
+// 宿主进程,这就是 daemon 与宿主「单写者」的机械保证(AGENTS.md 的 externalApi/
+// autoDream 单侧纪律),不依赖用户自觉。语义检索(PR2 起)与宿主共用 src/semantic.js
+// 的同一份装配;daemon 不参与做梦,但向量检索/语义去重与宿主同质。
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "./store.js";
+import { createSettings } from "./settings.js";
+import { createMirror, TYPE_FILE } from "./mirror.js";
+import { langOf } from "./lang.js";
+import { createService } from "./service.js";
+import { createMaintenance } from "./maintenance.js";
+import { createStandaloneApi } from "./api-standalone.js";
+import { createSemantic } from "./semantic.js";
+import { createVectorIndex } from "./vector-index.js";
+import { provisionRuntime } from "./runtime/provision.js";
+import { defaultRuntimeDir, listPayloadDirs } from "./runtime/layout.js";
+
+const EMBED_PROVIDERS = new Set(["off", "local", "ollama", "openai"]);
+
+/**
+ * 组装并启动一个独立数据面(含语义管线)。
+ * @param {object} opts
+ *   memoryDir  — 数据目录;缺省与宿主同默认 ~/.dsh/memory(config.js:9),支持前导 ~。
+ *   port/host  — 透传 createStandaloneApi;缺省走 kv external_api 持久值 > 8790/127.0.0.1。
+ *   logger     — console 形状(info/warn/error,收单字符串);缺省 null(全链路容缺)。
+ *   strictPort — 默认 true:配置端口被占即失败(第三方把 URL 写死,顺延=静默打到
+ *                错误端口)。显式 port=0(测试/OS 分配)不受影响。
+ *   embed      — "local"(默认,自管 runtime 取件 + ONNX 嵌入)|"ollama"|"openai"
+ *                (读宿主面板配的 vector-config)|"off"(纯关键词 + BM25)。
+ *   embedder/reranker — 注入式覆盖(测试/宿主方自管):给了就跳过 createSemantic,
+ *                直接 setEmbedder/setReranker;仅 embed="off" 之外有意为之。
+ * @returns {api, store, service, settings, maintenance, semantic, tokenExisted, dispose}
+ *   tokenExisted — 启动前 kv 里是否已有 token;false 时本次为首次生成,入口层可提示。
+ */
+export async function createServeRuntime({
+  memoryDir, port, host, logger = null, strictPort = true, embed = "local", embedder = null, reranker = null
+} = {}) {
+  if (!EMBED_PROVIDERS.has(embed)) {
+    throw new Error(`invalid embed provider: ${String(embed)}(允许 off/local/ollama/openai)`);
+  }
+  // index.js:192-195:~ 展开只认前导;目录不存在时 node:sqlite 直接抛,先 mkdir。
+  const dir = String(memoryDir || join(homedir(), ".dsh", "memory")).replace(/^~(?=$|[\\/])/, homedir());
+  mkdirSync(dir, { recursive: true });
+
+  // 装配顺序照 index.js:197-292:store → settings → mirror → service → recoverMirror。
+  const store = createStore(join(dir, "memory.db"));
+  const settings = createSettings(store.db);
+  // 第一期不吃宿主 config schema(schemastery 是宿主 peer 依赖,独立进程装不装随缘),
+  // 配最小集,与第三方 embedded 挂载实测同形:language 参与镜像渲染与去重标题;
+  // documentMemoryEnabled 关掉 document 子系统(daemon 不建 documentIndex,service
+  // 内部 if-guard 安全,index.js:261 的 documentIndex 仅宿主装配)。
+  const cfg = { language: "zh", documentMemoryEnabled: false };
+  const mirror = createMirror(dir, langOf(cfg));
+  const service = createService({ store, mirror, config: cfg, logger });
+
+  // index.js:292:上次镜像同步失败留下的 dirty 状态,启动时安全重渲一次(内部自吞)。
+  service.recoverMirror();
+
+  // index.js:319-332:人改镜像先合并——镜像文件里的手工编辑每次启动都赢。
+  // readHumanEdits 全类型一次读齐:mergeHumanEdits 成功会重渲全部镜像,逐类型读改
+  // 循环会拿没读到的类型覆盖掉未合并的编辑(index.js:324-327 注释同款坑)。
+  // 何时 apply 由 semantic 的分支时序契约决定(见 semantic.js 文件头),本文件只造闭包。
+  const humanEdits = new Map();
+  for (const type of Object.keys(TYPE_FILE)) humanEdits.set(type, mirror.readHumanEdits(type));
+  const applyHumanEdits = () => {
+    for (const [type, edits] of humanEdits) {
+      if (edits.length) service.mergeHumanEdits(type, edits);
+    }
+  };
+
+  // index.js:316-317:向量索引包住 store 的 embedding 列并跟踪活跃模型指纹。
+  const vectorIndex = createVectorIndex({ store, logger });
+  service.setVectorIndex(vectorIndex);
+
+  // ---- 语义管线(PR2):三路二选一 ------------------------------------------
+  let semantic = null;
+  if (embedder !== null) {
+    // 注入式覆盖(测试 / 宿主方自管 embedder):绕过装配,人改合并立刻做
+    //(对齐宿主 openai 分支的同步语义)。
+    service.setEmbedder(embedder);
+    if (reranker !== null) service.setReranker(reranker);
+    applyHumanEdits();
+  } else if (embed === "off") {
+    // 纯关键词 + BM25:对齐宿主 lightMode 分支——不建 embedder,人改合并立即。
+    applyHumanEdits();
+  } else {
+    let semanticReady = true;
+    if (embed === "local") {
+      // 自管 runtime 缺失时取件:只走 download 档(宿主 adopt 推导对独立进程无意义
+      // ——没有宿主 node_modules 可推)。失败不阻断 daemon:降级关键词 + 可操作提示。
+      semanticReady = await ensureRuntimePayload(logger);
+    }
+    if (semanticReady) {
+      semantic = createSemantic({
+        store, service, settings,
+        cfg: daemonSemanticCfg(embed),
+        logger, vectorIndex, applyHumanEdits, lightMode: false
+      });
+    } else {
+      applyHumanEdits();
+    }
+  }
+
+  // index.js:294-309:检索回执落 recall_runs(searchMemories 的 recordRecall 默认开,
+  // 第三方检索统计因此不缺数)。best-effort:回执写失败绝不影响检索本身。
+  service.setRecallRecorder((recall) => {
+    try {
+      store.saveRecallRun({
+        query: recall.query,
+        mode: recall.mode,
+        topK: recall.topK,
+        threshold: recall.threshold ?? null,
+        candidates: recall.candidates ?? [],
+        created_at: recall.createdAt
+      });
+    } catch { /* non-fatal: recall recording is bookkeeping */ }
+  });
+
+  // index.js:636:#275 无损回收。daemon 带上它,POST /maintenance/reclaim 才有后端
+  // (api-standalone 缺 maintenance 时该路由 503);同样不挂启动路径、不接定时器。
+  const maintenance = createMaintenance({ store, config: cfg, logger });
+
+  // index.js:643-649 同一工厂;差别只有 strictPort 默认开(daemon 语义,见上)。
+  // token 与宿主共用同一 kv 键 external_api:首次启动自动生成并持久化
+  // (api-standalone.js:203-212),DSH 面板 / CLI / daemon 三方零配置共享凭证。
+  const tokenExisted = Boolean(settings.getExternalApi?.()?.token);
+  // embedder 注入 /context 的查询嵌入（issue #370）：三路取当前生效的同一句柄——
+  // 注入覆盖用注入值，semantic 路用它的产物，off/lightMode 为 null（路由侧降级
+  // 规则档）。与 service.setEmbedder 的是同一个实例，不存在第二真相源。
+  const api = createStandaloneApi({ service, store, config: cfg, logger, settings, port, host, maintenance, strictPort, embedder: embedder ?? semantic?.embedder ?? null });
+
+  return {
+    api,
+    store,
+    service,
+    settings,
+    maintenance,
+    semantic,
+    tokenExisted,
+    /**
+     * 收尾：先停收新请求、等在途请求跑完，再关库——直接同步关库会让在途的
+     * PUT/POST 撞上已关的 store（500 或丢写）。closeIdleConnections 排干
+     * keep-alive 空闲连接（node ≥18.2，旧版无此 API 则跳过），否则 server.close
+     * 的回调要等 keep-alive 超时才触发。node:sqlite 对未 finalize 语句可能抛，
+     * 吞掉——WAL 会在下次打开时回放，已提交事务不丢。
+     */
+    async dispose() {
+      await new Promise((resolve) => {
+        try {
+          api.server.close(() => resolve());
+          api.server.closeIdleConnections?.();
+        } catch { resolve(); }
+      });
+      try { semantic?.dispose(); } catch { /* 同上 */ }
+      try { store.close(); } catch { /* 同上 */ }
+    }
+  };
+}
+
+/**
+ * daemon 侧语义配置:默认值逐键锚定 src/config.js(309-420),daemon 不装 schemastery
+ * (宿主 peer 依赖),同值硬编码;config.js 改默认值时此处与 docs/DAEMON.md 同步。
+ * 只放开 embedProvider(CLI --embed);rerank 暂不提供 CLI(默认关,与宿主同默认)。
+ */
+function daemonSemanticCfg(embed) {
+  return {
+    embedProvider: embed,                          // config.js:309(宿主默认 openai;daemon 默认 local——独立部署唯一自洽路径)
+    localEmbedModel: "Xenova/bge-small-zh-v1.5",   // :312
+    localEmbedDimension: 512,                      // :313
+    localEmbedDevice: "cpu",                       // :314
+    localEmbedBatchSize: 8,                        // :315
+    localEmbedPooling: "auto",                     // :323(BGE 系 CLS 口径,改它=换向量空间)
+    ollamaBaseUrl: "http://localhost:11434",       // :326
+    ollamaModel: "nomic-embed-text",               // :331
+    embedModelCacheDir: "",                        // :336(空=local-embedder 内部解析 ~/.dsh/mneme/models)
+    embedModelMirror: "https://hf-mirror.com",     // :337
+    resilientModelDownload: true,                  // :342
+    runtimeDir: process.env.DSH_MNEME_RUNTIME_DIR || "",  // :348(空=defaultRuntimeDir;取件/加载同源)
+    rerankEnabled: false,                          // :419
+    rerankProvider: "none",                        // :420
+    autoReindexOnBoot: true                        // :367
+  };
+}
+
+/**
+ * 本地推理 runtime 取件(download 档)。返回 payload 是否可用:
+ * 已存在(含收编/早前下载)→ true 不重复取;缺失 → 取件成功 true / 失败 false(内部
+ * 已打降级日志)。并发安全由 provisionRuntime 的 IN_FLIGHT 锁保证(按归一化 runtimeDir 串行)。
+ */
+async function ensureRuntimePayload(logger) {
+  const runtimeDir = process.env.DSH_MNEME_RUNTIME_DIR || "";
+  const dir = runtimeDir || defaultRuntimeDir();
+  if (listPayloadDirs(dir).length > 0) return true;
+  logger?.info?.("[dsh-mneme] 本地推理运行时缺失,开始取件(download 档,约 200MB;离线可用 DSH_MNEME_RUNTIME_TARBALL_DIR / DSH_MNEME_RUNTIME_MIRROR)…");
+  try {
+    const result = await provisionRuntime({ runtimeDir, localTarballDir: process.env.DSH_MNEME_RUNTIME_TARBALL_DIR || "", mirror: process.env.DSH_MNEME_RUNTIME_MIRROR || "" });
+    if (!result.ok) throw new Error(result.reason);
+    logger?.info?.(`[dsh-mneme] 运行时就绪(${result.strategy}):${result.packages} 包 / ${result.files} 文件`);
+    return true;
+  } catch (error) {
+    logger?.warn?.(`[dsh-mneme] runtime provisioning failed, search degrades to keyword: ${String(error)}`);
+    return false;
+  }
+}

package/src/service.js

@@ -1530,7 +1530,11 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 合序都不动）。heat 关闭时不建表、不算 heat，权重恒 1，排序与改动前一致。
     // selectiveInject 相似度重排（下方）开启且向量可用时相似度优先——heat 只
     // 生效于规则路排序与语义路回填序。
-    const heatMap = config?.heatEnabled === true
+    // issue #218 / E5 效用考卷：heat 乘进注入排序在真实年龄混合下饿死老约束
+    // （现行量级 ≡ 拟合参数，importance-only 遵从 +12.7pp），故注入侧 heat 拆出
+    // 独立开关 injectHeatEnabled（默认关）：不开时权重恒 1，排序与 heat 关闭
+    // 逐字节一致；召回侧时钟（touchLastAccess）与 sleep 降级联判不受影响。
+    const heatMap = config?.heatEnabled === true && config?.injectHeatEnabled === true
       ? new Map(filtered.map((m) => [m.id, computeHeat(m, Date.now(), config)]))
       : null;
     const heatOf = (m) => (heatMap ? heatMap.get(m.id) ?? 1 : 1);
@@ -1658,11 +1662,6 @@ export function createService({ store, mirror, config, onWrite, logger, document
         }
       } catch { /* topic re-rank unavailable: keep rule-based order */ }
     }
-    // v0.8.0 A3（issue #17）：strictScope 硬过滤同样作用于自动注入——scoped 记忆
-    // 泄进无关注入上下文是最典型的越权通道，检索侧过滤挡不住这里。
-    if (config?.strictScope === true && scope) {
-      candidates = candidates.filter((m) => isVisibleInScope(m, scope));
-    }
     // #24 块3：图召回候选打标。entityRecall 只在 entityRecallEnabled 开启时
     // 有产出，这里为命中者贴 graphHint 标签——注入侧据此（a）graphInjectHint
     // 开=标成 [检索线索] 前缀的线索行（独立预算），（b）关=线索行只参与排序
@@ -1683,6 +1682,16 @@ export function createService({ store, mirror, config, onWrite, logger, document
         }
       } catch { /* graph hint is best-effort */ }
     }
+    // v0.8.0 A3（issue #17）：strictScope 硬过滤同样作用于自动注入——scoped 记忆
+    // 泄进无关注入上下文是最典型的越权通道，检索侧过滤挡不住这里。
+    // 位置纪律：必须在**图召回合并之后**、pin 池之前——entityRecall 不做 scope
+    // 门控，过滤放在它前面时，出局行会被图召回重新打上 graphHint 带回候选池
+    // （graphInjectHint 开时作为线索行进注入块；CodeRabbit on #371 的可达性分析，
+    // /context 与宿主注入同受影响）。pin 池 eligible 取自本过滤之后的候选，
+    // 顺带保证越权行进不了 pin。
+    if (config?.strictScope === true && scope) {
+      candidates = candidates.filter((m) => isVisibleInScope(m, scope));
+    }
     // #249 第一批：B1 pin 池。取在相关性排序之后、轮换之前——取谁按此刻的候选
     // 次序（即相关性次序），取到后从候选中摘除，于是下面的轮换重排碰不到它们
     // （验收：pin 不参与跨轮轮换）。独立预算的两层意义：pin 既不占 maxItems

package/src/settings.js

@@ -83,6 +83,8 @@ const FEATURE_FLAG_BOOLEANS = [
   "autoDreamFailureBackoff",
   "sleepModeEnabled",
   "heatEnabled",
+  // issue #218 / E5：注入侧 heat 独立开关（默认关，老用户 injectHeatEnabled=true 回滚）。
+  "injectHeatEnabled",
   "hybridInject",
   "selectiveInjectEnabled",
   "searchSemanticDedup",

package/test/api.test.js

@@ -674,11 +674,13 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // 块2 新增 graphWeightEnabled/graphWeightDelta、块3 新增 graphInjectHint/graphInjectBudget、
   // 块4 新增 graphPassiveConfirm、
   // issue #339 新增 dreamMergeGuard、
+  // issue #218/E5 新增 injectHeatEnabled、
   // issue #164 A2 新增 sensitiveScanEnabled（顶层扁平键，走 configFlagValue 默认分支））
-  assert.equal(Object.keys(data.effective).length, 59 + 3 + 2 + 1 + 2 + 2 + 2 + 1 + 1 + 1 + 2 + 1 + 2 + 1 + 3 + 2 + 2 + 1 + 1 + 1);
+  assert.equal(Object.keys(data.effective).length, 59 + 3 + 2 + 1 + 2 + 2 + 2 + 1 + 1 + 1 + 2 + 1 + 2 + 1 + 3 + 2 + 2 + 1 + 1 + 1 + 1);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMergeGuard, false);
+  assert.equal(data.effective.injectHeatEnabled, false);
   assert.equal(data.effective.dreamMinIntervalMinutes, 0);
   assert.equal(data.effective.autoDreamFailureBackoff, false);
   assert.equal(data.effective.dreamMaxTokens, 131072);

package/test/changelog-prep.test.js

@@ -0,0 +1,60 @@
+// scripts/changelog-prep.mjs 的回归测试。
+//
+// 这一步的价值全在「别假成功」上：发布准备原先在 CRLF 检出上匹配不到 CHANGELOG 文件头，
+// replace 退化成 no-op 却照样打印 ✓，git status 里看不出任何异常——CI 跑在 ubuntu（LF），
+// 所以只有本机发版会中招（v0.8.13 那次就是这么踩到的，最后靠人工补的占位节）。
+// 下面用 LF / CRLF / BOM 三种输入各钉一遍，并锁住「匹配不上要如实回报」这条契约：
+// 调用方靠 reason 决定 exit 1，退回「返回原文」就等于退回假成功。
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { detectEol, insertReleaseSection } from "../scripts/changelog-prep.mjs";
+
+const LF_HEAD = "# Changelog\n\n## [0.8.12] - 2026-10-01\n\n## 🐛 修复\n\n- 旧条目\n";
+const CRLF_HEAD = LF_HEAD.replace(/\n/g, "\r\n");
+/** 有没有「裸 LF」（前面不是 CR 的 \n）——混排行尾的判据。 */
+const hasBareLf = (text) => /(^|[^\r])\n/.test(text);
+
+test("LF 输入：插入占位节，行尾保持 LF，旧内容原样保留", () => {
+  const r = insertReleaseSection(LF_HEAD, "0.8.13", "2026-10-03");
+  assert.equal(r.ok, true);
+  assert.ok(r.text.startsWith("# Changelog\n\n## [0.8.13] - 2026-10-03"), "插在标题之后");
+  assert.ok(r.text.includes("- （待填）"), "带 release.yml verify 要的占位节");
+  assert.ok(r.text.includes("## [0.8.12] - 2026-10-01"), "旧内容不动");
+  assert.equal(r.text.includes("\r\n"), false, "不该往 LF 文件里混 CRLF");
+});
+
+test("CRLF 输入：同样能插（原先这里静默 no-op —— 本模块存在的首要理由）", () => {
+  const r = insertReleaseSection(CRLF_HEAD, "0.8.13", "2026-10-03");
+  assert.equal(r.ok, true, "CRLF 检出上必须也能插入");
+  assert.notEqual(r.text, CRLF_HEAD, "绝不返回原文——那正是当初的假成功");
+  assert.ok(r.text.includes("## [0.8.13] - 2026-10-03"));
+  assert.equal(hasBareLf(r.text), false, "插入的内容也要用 CRLF，不混行尾");
+});
+
+test("带 BOM 的输入也能插（`^#` 匹配不到属同一类形状漂移）", () => {
+  const r = insertReleaseSection("\uFEFF" + LF_HEAD, "0.8.13", "2026-10-03");
+  assert.equal(r.ok, true);
+  assert.ok(r.text.includes("## [0.8.13] - 2026-10-03"));
+});
+
+test("已含该版本：幂等跳过，并如实回报 already-present", () => {
+  const once = insertReleaseSection(LF_HEAD, "0.8.13", "2026-10-03");
+  assert.equal(once.ok, true);
+  assert.deepEqual(insertReleaseSection(once.text, "0.8.13", "2026-10-03"), { ok: false, reason: "already-present" });
+});
+
+test("文件头不匹配：回报 header-not-found，而不是静默返回原文", () => {
+  // 这条锁的是契约本身。若有人把实现改回「返回原文 + 入口照旧打印 ✓」，它会红。
+  assert.deepEqual(insertReleaseSection("# ChangelogX\n\n## [0.8.12]\n", "0.8.13", "2026-10-03"), {
+    ok: false,
+    reason: "header-not-found"
+  });
+  assert.deepEqual(insertReleaseSection("", "0.8.13", "2026-10-03"), { ok: false, reason: "header-not-found" });
+});
+
+test("detectEol：认两种行尾，无换行时按 LF 处理", () => {
+  assert.equal(detectEol("a\nb"), "\n");
+  assert.equal(detectEol("a\r\nb"), "\r\n");
+  assert.equal(detectEol("a"), "\n");
+});

package/test/inject-heat.test.js

@@ -6,8 +6,13 @@ import { createService } from "../src/service.js";
 // #218 v1：heat 作为注入排序的**同级内乘数**（issue #218 拍板口径）。
 // 规则路 comparator 的层内权重 importance×quality 乘 heat；priority 分层
 // （summary=0 / preference=1 / coding 同级 / 其余 2）与 store 的 order=chrono
-// 分页序不动。heatEnabled=false（默认）时权重恒 1，排序与改动前一致——
-// 本文件的关闭用例与 heat.test.js 的曲线断言共同锁住验收第 1 条。
+// 分页序不动。
+//
+// issue #218 / E5 效用考卷：heat 乘进注入排序在真实年龄混合下饿死老约束
+// （现行量级 ≡ 拟合参数，importance-only 遵从 +12.7pp），注入侧 heat 拆出
+// 独立开关 injectHeatEnabled（默认关）——默认关档下 heatEnabled=true 的库
+// 注入排序与 heat 关闭逐字节一致（平价锁）；显式开启才恢复旧序。
+// 召回侧时钟（touchLastAccess）与 sleep 降级联判不受本键影响。
 
 const HOUR = 3600000;
 
@@ -19,40 +24,51 @@ function setup(config = {}) {
 
 const titles = (candidates) => candidates.map((c) => c.title);
 
-test("heat off（默认）：层内维持 importance 序，与改动前一致", () => {
-  const { store, service } = setup();
+// 三个用例共用的「冷高重要性 + 新低重要性」库。
+function seedColdAndFresh(service) {
   const cold = service.saveWithDedupe({ type: "decision", title: "冷的高重要性决策", content: "旧", importance: 4 }).memory;
   service.saveWithDedupe({ type: "decision", title: "新的低重要性决策", content: "新", importance: 3 });
   service.touchLastAccess(cold.id, new Date(Date.now() - 3000 * HOUR).toISOString());
   // 新记忆不触达：ref 退 created_at（≈现在），heat≈1，不影响本用例
+}
+
+test("heat off（默认）：层内维持 importance 序，与改动前一致", () => {
+  const { store, service } = setup();
+  seedColdAndFresh(service);
   const picked = service.injectCandidates({ maxItems: 5, threshold: 3 });
   assert.deepEqual(titles(picked), ["冷的高重要性决策", "新的低重要性决策"]);
   store.close();
 });
 
-test("heat on：同层内新鲜低重要性记忆越过冷的高重要性记忆", () => {
+test("heat on 且 injectHeatEnabled 关（新默认）：注入序与 heat 关闭逐字节一致（E5 平价锁）", () => {
   const { store, service } = setup({ heatEnabled: true });
-  const cold = service.saveWithDedupe({ type: "decision", title: "冷的高重要性决策", content: "旧", importance: 4 }).memory;
-  service.saveWithDedupe({ type: "decision", title: "新的低重要性决策", content: "新", importance: 3 });
-  service.touchLastAccess(cold.id, new Date(Date.now() - 3000 * HOUR).toISOString());
+  seedColdAndFresh(service);
+  const picked = service.injectCandidates({ maxItems: 5, threshold: 3 });
+  // E5 效用考卷：heat 乘进注入排序饿死老约束——默认不再乘，冷的高重要性决策
+  // 回到它 importance 应在的位置（与 heat off 用例逐条相同）。
+  assert.deepEqual(titles(picked), ["冷的高重要性决策", "新的低重要性决策"]);
+  store.close();
+});
+
+test("heat on 且 injectHeatEnabled 开：恢复旧序（老用户回滚口）", () => {
+  const { store, service } = setup({ heatEnabled: true, injectHeatEnabled: true });
+  seedColdAndFresh(service);
   const picked = service.injectCandidates({ maxItems: 5, threshold: 3 });
   // λ=0.002、3000h → 冷记忆权重 4×e^-6≈0.01，新鲜记忆 3×≈1 → 反超
   assert.deepEqual(titles(picked), ["新的低重要性决策", "冷的高重要性决策"]);
   store.close();
 });
 
-test("heat on 且 λ=0（免疫类型）：乘数恒 1，importance 序不受影响", () => {
-  const { store, service } = setup({ heatEnabled: true, heatTypeDecay: { decision: 0 } });
-  const cold = service.saveWithDedupe({ type: "decision", title: "冷的高重要性决策", content: "旧", importance: 4 }).memory;
-  service.saveWithDedupe({ type: "decision", title: "新的低重要性决策", content: "新", importance: 3 });
-  service.touchLastAccess(cold.id, new Date(Date.now() - 3000 * HOUR).toISOString());
+test("heat on 且 injectHeatEnabled 开 且 λ=0（免疫类型）：乘数恒 1，importance 序不受影响", () => {
+  const { store, service } = setup({ heatEnabled: true, injectHeatEnabled: true, heatTypeDecay: { decision: 0 } });
+  seedColdAndFresh(service);
   const picked = service.injectCandidates({ maxItems: 5, threshold: 3 });
   assert.deepEqual(titles(picked), ["冷的高重要性决策", "新的低重要性决策"]);
   store.close();
 });
 
-test("heat 不跨层：再热的 decision 也不越过 summary 层", () => {
-  const { store, service } = setup({ heatEnabled: true });
+test("heat 不跨层：再热的 decision 也不越过 summary 层（injectHeatEnabled 开）", () => {
+  const { store, service } = setup({ heatEnabled: true, injectHeatEnabled: true });
   service.saveWithDedupe({ type: "summary", title: "会话总览", content: "总览", importance: 2 });
   service.saveWithDedupe({ type: "decision", title: "滚烫决策", content: "新", importance: 3 });
   const picked = service.injectCandidates({ maxItems: 5, threshold: 3 });