@modusensus/dsh-mneme 0.8.12 → 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/sensitive-scan.js

@@ -0,0 +1,209 @@
+// #164 A2：写入边界的密钥 / PII 判据。判据来源是 #164 A2（维护者 09-28 把认领转给
+// 本侧），消费方是 #254 的写入准入——`write-admission.js` 从 #332 起就留了
+// `sensitiveScan` 注入点，本模块是那个占位的实现。
+//
+// 为什么判据独立成文件、不写进 write-admission.js：判据的归属是 #164 A2，闸门的归属
+// 是 #254。闸门只消费 `{kind, label}`（deny 面已在 #332 定死），判据自己既不认识
+// 「会话预算」也不认识 `llm_audit_logs`——换一个判据（比如将来接更重的 PII 分类器）
+// 只换注入的那一行。写入边界的另外两个出口（autoSummarize / dream 输出）要复用同一份
+// 判据时也直接 import 本模块的 `scanSensitive`，不必各写一套形状。
+//
+// 三条判据口径（前两条是 #254 已定的硬约束，第三条是本模块自己的）：
+//
+// 1. 零 LLM、纯确定性。写入路径在最上游，这里多花的时间会乘上每一次写入；EdgeMem
+//    （2609.05553）那句「能不用模型判定就不用」说的就是这一层。
+//
+// 2. 假阳率由负样本定。`test/helpers/write-admission-samples.js` 的 12 条负样本是
+//    #332 就配好的验收面，维护者把话说死了：「同一套负样本原样跑，抓错任何一条就不
+//    算落地」。所以本模块的形状是**先认形状再认关键词**——纯关键词匹配在那组负样本
+//    上全军覆没（「把 API key 放进环境变量」这类讨论句里一个凭据值都没有）。
+//
+// 3. 报最严重的那一类（`kind` 落审计）。同一个字符串可能同时像两类（`sk_live_` 前缀
+//    既是 Stripe 的形状、也能被通用的 `sk-` 规则吃下），所以规则表按「越具体越靠前」
+//    排，命中即返回。密钥在前、PII 在后：两者误杀面差一个量级（密钥串出现在正常项目
+//    记忆里就是事故，邮箱 / 手机号完全可能是正当内容），同时命中时报更严重的那一类。
+//    `kind` 是稳定判据键（不是展示文案），enforce 打开前先按它看分布，将来要按类放行
+//    也只改策略、不动判据。
+//
+// 已知边界（都是「宁漏不误杀」的取舍，不是遗漏）：
+//   - 只扫文本（title / content / tags）。不扫路径、id、时间戳这类元数据字段——它们
+//     由系统生成，不是用户写进来的内容，扫它们只会引入假阳。
+//   - 中文关键词（密码 / 令牌）不认。补进去会让「密码必须脱敏后再入库」这类讨论句
+//     命中，而那正是负样本 group 的形状。要覆盖中文赋值得先设计「关键词语种 × 值形状」
+//     的两维判据，不在本批。
+//   - 手机号只认大陆移动号段（1[3-9] + 9 位），固定电话与带国家码的写法不认。宽一位
+//     就会把长度相近的订单号 / 内部编号吃进来，而 PII 这一档的误杀面已经比密钥大一档。
+//   - 银行卡号加 Luhn 校验：`0000000000000000`、`4111111111111112` 这类形状对但校验
+//     不过的串不报。少了这道校验，任何 16 位数字串（订单号、时间戳拼接）都会命中。
+//   - 身份证同样加校验位（GB 11643 / ISO 7064 MOD 11-2）：位数对但校验不过的 18 位
+//     数字串不报。原先只有银行卡有校验、身份证没有，结果是 18 位纯数字先被身份证规则
+//     命中，反倒绕过银行卡那条的 Luhn。
+//
+// 归一化：这里**不**用 content-hash.js 的 normalizeForHash。那套口径（NFKC → 小写 →
+// 去标点）是为「只差格式的两条写入是否同一件事」定的，判据要的是原串的形状——大小写
+// 是密钥 alphabet 的一部分（`AKIA` 与 `akia` 不是同一个值），去掉 `-` / `_` 会把 JWT
+// 与 Slack token 的分段结构一起折没。两个口径别互换。
+
+/** 判据命中的返回形状（与 `createWriteAdmission` 的 sensitiveScan 契约一致）。 */
+// kind 是稳定键、label 是给人看的一行说明；两者都落 llm_audit_logs 的
+// metadata.deny，所以别在其中塞运行时的值（命中的凭据本身绝不落盘 / 不回显）。
+const SECRET_RULES = [
+  { kind: "aws_access_key", label: "AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  // AWS 的 secret access key 没有前缀，只能靠赋值键认：`AWS_SECRET_ACCESS_KEY` /
+  // `aws_secret_access_key` 这个键名是它的形状。最早的一批 `secret` 关键词规则被
+  // 「必须在赋值号前」的位置要求挡在外面（多词键里 `secret` 后面跟的是 `_`，不是
+  // `:`/`=`），所以它得单独一条。40 位下限取 AWS 官方密钥的固定长度。
+  {
+    kind: "aws_secret_key",
+    label: "AWS secret access key",
+    // 键名不分大小写，所以挂 `/i` 而不是行内修饰符组 `(?i:...)`：后者是 ES2025 语法，
+    // CI 矩阵里的 Node 22 直接抛 SyntaxError（本文件其余规则也没有用它的）。
+    // 值那一半本来就是 `[A-Za-z0-9/+=]`，带上 `/i` 不改变大小写敏感度。
+    re: /(?:aws[_-]?secret[_-]?access[_-]?key)\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])/i
+  },
+  { kind: "github_token", label: "GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/ },
+  { kind: "slack_token", label: "Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+  // PEM 头是明文私钥的确定标志，带不带正文都一样判——`BEGIN` 与 `PRIVATE KEY` 之间
+  // 可能有 `RSA` / `EC` / `OPENSSH`，所以中间那段是 [A-Z ]*。
+  { kind: "private_key", label: "PEM private key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  { kind: "jwt", label: "JSON Web Token", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+  // scheme 与 userinfo 两段都加上界。scheme 那段的 `*` 作用在含 `.` 的字符类上，
+  // 一条长点分串（包名 / 路径 / 版本链）里每个起点都要一路回溯到结尾才发现没有
+  // `://` → 与 email 同源的 O(n²)（实测 120KB 对抗串里这条占 4.1 秒）。
+  // URL scheme 名本就短、`user:password` 也不会长到 64，上界只钉住回溯面，
+  // 真实连接串一条不少。
+  { kind: "connection_string", label: "credentials in URL", re: /\b[a-z][a-z0-9+.-]{0,31}:\/\/[^\s/:@]{1,64}:[^\s/:@]{6,}@/ },
+  // Stripe 排在通用 `sk-` 之前：`sk_live_…` 两条规则都吃，先到的那条决定 kind。
+  // 只认 sk_live_（生产密钥）：sk_test_ 是公开测试密钥，报它是纯误杀。
+  { kind: "stripe_key", label: "Stripe secret key", re: /\bsk_live_[A-Za-z0-9]{16,}\b/ },
+  { kind: "npm_token", label: "npm auth token", re: /_authToken\s*=\s*[A-Za-z0-9_-]{20,}/ },
+  // 下限 24 而不是 20：这是一条纯收紧、不动语料读数的加固——OpenAI 的 key 没有校验
+  // 位，前缀 + 长度是唯一形状，20 位会把更长的假阳性面留在表里。`sk-` 后面跟短串的
+  // 赋值句仍会被赋值型那条认下（那是**对的**：值长了 8 位以上就该报）。
+  { kind: "openai_key", label: "OpenAI API key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}\b/ },
+  {
+    // 赋值型：最常见的一类，也是负样本组（占位符 / 环境变量 / 模板变量 / 只提关键词）
+    // 的主要靶子。判据是「关键词 + 赋值号 + 右边真的是个值的形状」，值本身不校验
+    // alphabet——凭据值没有通用形状，能通用的只有「它不像占位符」。
+    kind: "assigned_secret",
+    label: "assigned credential literal",
+    // 左边界不能把 `_` 排除在外：环境变量名正是拿 `_` 当分隔符，排除它会让
+    // `DB_PASSWORD=` / `MY_API_KEY=` / `MYSQL_PASSWORD=` 整类漏放（只有恰好落在
+    // 行首的 `API_KEY=` 能中）。放宽后 #332 那套 26 条语料（含 12 条负样本）全绿，
+    // 说明原写法不是语料换来的取舍。挡误杀的是下面那道占位符守卫，不是这个边界。
+    re: /(?:^|[^A-Za-z0-9])(?:password|passwd|pwd|secret|api[_-]?key|token)\b\s*[:=]\s*["']?([^\s"']{8,})/i,
+    // 占位符守卫：右边是尖括号占位、shell / 模板变量、环境变量读取、或一串 x / * / …
+    // 时不算命中。少这道守卫，`password: <redacted>` 与 `token: ${TOKEN}` 都会被报，
+    // 而它们正是「配置里该怎么写」的示例文本。
+    guard: (value) => !/^(?:<[^>]*>|\$\{|\$[A-Z_]+$|process\.env|redacted|xx+|\*+|\u2026)/i.test(value)
+  }
+];
+
+const PII_RULES = [
+  {
+    kind: "email",
+    label: "email address",
+    // 先看 TLD 再看 `@`：反过来的 `(?:[A-Za-z]{2,}\.)+[A-Za-z]{2,}` 对
+    // `a@b.c.d.e` 这类可以回溯出指数条路径。
+    // local part 的 `+` 必须加上界。该字符类含 `.`，所以一条长点分串（包名 / 路径 /
+    // 版本链）后跟一个 `@` 时，每个起点都要重扫到那个 `@` 才失败 → 整体 O(n²)。
+    // 实测 120KB 对抗串 23.5 秒里这条占 18.6 秒，34KB 点分链要 0.6 秒；本判据在写入
+    // 路径上同步跑，等于把写入阻塞住。64 是 RFC 5321 给 local part 的上限，加上界
+    // 不缩检测面——放弃的只是长于 64 的非法形状。
+    re: /\b[A-Za-z0-9._%+-]{1,64}@(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}\b/
+  },
+  { kind: "cn_mobile", label: "mainland mobile number", re: /(?<!\d)1[3-9]\d{9}(?!\d)/ },
+  { kind: "cn_id_card", label: "mainland ID number", re: /(?<![0-9A-Za-z])\d{17}[\dXx](?![0-9A-Za-z])/, cnId: true },
+  { kind: "bank_card", label: "payment card number", re: /(?<!\d)(?:\d{13,19})(?!\d)/, luhn: true }
+];
+
+/**
+ * Luhn（模 10）校验。银行卡号这一档只靠位数与首字符形状会把所有 13–19 位数字串
+ * 都吃进来，而项目记忆里长度差不多的数字串（订单号、拼接的时间戳）很常见；校验位
+ * 是卡号自带的、零成本的第二道形状。负样本里没有卡号形状的串，这道校验是防未列举
+ * 的那一类（同时它也不影响正样本：4111111111111111 是 Luhn 通过的公开测试卡号）。
+ * @param {string} value 归一后的数字串（可能含分隔符）
+ */
+function passesLuhn(value) {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length < 13 || digits.length > 19) return false;
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+// 大陆身份证校验位（GB 11643 / ISO 7064 MOD 11-2）。与银行卡的 Luhn 同理：18 位
+// 数字串在项目记忆里很常见（订单号、内部编号、拼接时间戳），位数这个形状拦不住它们，
+// 而校验位是身份证自带的、零成本的第二道形状。权重序列与余数映射都是标准值，别改。
+const CN_ID_WEIGHTS = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+const CN_ID_CODES = "10X98765432";
+/** @param {string} value 命中串（17 位数字 + 校验位，校验位可为 X） */
+function passesCnId(value) {
+  if (!/^\d{17}[\dXx]$/.test(value)) return false;
+  let sum = 0;
+  for (let i = 0; i < 17; i++) sum += Number(value[i]) * CN_ID_WEIGHTS[i];
+  return CN_ID_CODES[sum % 11] === value[17].toUpperCase();
+}
+
+/**
+ * 扫一段文本里的密钥 / PII。命中返回 `{kind, label}`、未命中返回 null，不抛。
+ *
+ * 只认第一处命中（按规则表顺序 = 严重度顺序）。一次写入里出现第二条凭据时不再报——
+ * deny 面只记判据类别，报多条只是把同一件事写几遍。
+ * @param {unknown} value
+ * @returns {{kind: string, label: string}|null}
+ */
+export function scanSensitive(value) {
+  const text = typeof value === "string" ? value : String(value ?? "");
+  if (!text) return null;
+  for (const rule of [...SECRET_RULES, ...PII_RULES]) {
+    const match = text.match(rule.re);
+    if (!match) continue;
+    // 守卫只看捕获组：没有捕获组的规则天然没有守卫。
+    if (rule.guard && !rule.guard(match[1] ?? "")) continue;
+    if (rule.luhn && !passesLuhn(match[0])) continue;
+    if (rule.cnId && !passesCnId(match[0])) continue;
+    return { kind: rule.kind, label: rule.label };
+  }
+  return null;
+}
+
+/**
+ * 判据的两种调用面，共用同一份规则表：
+ *   `scanSensitive(text)`           — 任意文本，给写入边界之外的消费方（autoSummarize /
+ *                                     dream 输出）直接调；它们手里是文本，不是记忆行。
+ *   `createSensitiveScan({config})` — `write-admission.js` 的 `sensitiveScan` 契约，
+ *                                     入参是记忆对象、返回 `{kind, label}` 或 null。
+ *
+ * 开关在工厂里判一次：`sensitiveScanEnabled` 关时返回 null，闸门侧连函数都拿不到，
+ * 于是「第 1 级只跑空白 / 噪声」这条路与 #332 合并时**逐字段一致**（那一版根本没有
+ * 这个函数）。反过来，本键开着也不会自己去扫：唯一的调用点是闸门的 firstLevelHit，
+ * 而闸门要 `writeAdmission.enabled` 打开才走第 1 级判据。所以两个键是「闸门」与
+ * 「闸门内这一批判据」的关系，不是互为子开关——任一个关着，A2 都不产生任何判定。
+ * 分成两个键是为了能单独观察 A2 的命中分布（空白 / 噪声与密钥 / PII 的误杀面差一个
+ * 量级），不是为了让它能脱离闸门独立生效。
+ *
+ * @param {{config?: object}} [deps]
+ * @returns {((memory: object) => ({kind: string, label: string}|null))|null}
+ */
+export function createSensitiveScan({ config } = {}) {
+  if (config?.sensitiveScanEnabled !== true) return null;
+  const scan = (memory) => {
+    const text = [memory?.title, memory?.content, ...(Array.isArray(memory?.tags) ? memory.tags : [])]
+      .filter((s) => typeof s === "string")
+      .join("\n");
+    return scanSensitive(text);
+  };
+  // 工厂只认「开 / 关」；enforce 由 write-admission 决定（命中即 deny 还是仅告警），
+  // 判据自己不碰决策——那一步在闸门里。两层分开就能先开检测看分布、再开拦截。
+  return scan;
+}

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;
+  }
+}