@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.0

package/memory-engine/lib/recall.mjs

@@ -0,0 +1,331 @@
+// 记忆引擎 v2 · 离线层 —— 召回（方案 §3.3）
+//
+// 向量为主（余弦 top-20）+ FTS5 仅补标签/英文/数字 + RRF(k=60) 融合 + 排除 pinned
+// 触发：非空即触发（不用 ≥10 字阈值——短暗号「退下吧」「整夜干活」恰恰最需要记忆）；
+//       纯符号 / 单字跳过。
+import { loadMatrix } from './vectors-store.mjs';
+
+/** 触发判定（方案 §3.3 Z16 已吸收） */
+export function shouldTrigger(rawQuery) {
+  const q = String(rawQuery ?? '').trim();
+  if (!q) return { trigger: false, reason: 'empty' };
+  const semantic = q.match(/[\p{L}\p{N}]/gu) || [];
+  if (semantic.length === 0) return { trigger: false, reason: 'symbols-only' };
+  if (semantic.length < 2) return { trigger: false, reason: 'single-char' };
+  return { trigger: true, reason: 'non-empty' };
+}
+
+/** 抽 FTS 补位 token：只取英文/数字（A4：中文连续串在 unicode61 下几近不可用） */
+export function extractFtsTokens(rawQuery, max = 8) {
+  const m = String(rawQuery ?? '').match(/[A-Za-z0-9][A-Za-z0-9_.-]*/g) || [];
+  const out = [];
+  for (const t of m) {
+    if (t.length < 2) continue; // 单字母/单数字噪声大
+    if (!out.includes(t)) out.push(t);
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+/** 构造 FTS5 MATCH 表达式：每个 token 加双引号（防语法注入），OR 连接 */
+export function buildFtsMatch(tokens) {
+  if (!tokens || !tokens.length) return null;
+  return tokens.map((t) => `"${String(t).replace(/"/g, '')}"`).join(' OR ');
+}
+
+/** 载入向量矩阵 + 行范数（余弦召回用；一次构建，多次召回） */
+export function buildVectorIndex(db, { source = 'memory', model = null } = {}) {
+  const matrix = loadMatrix(db, source, model);
+  const norms = new Float32Array(matrix.count);
+  for (let r = 0; r < matrix.count; r += 1) {
+    let n = 0;
+    const off = r * matrix.dim;
+    for (let i = 0; i < matrix.dim; i += 1) n += matrix.data[off + i] * matrix.data[off + i];
+    norms[r] = Math.sqrt(n) || 1;
+  }
+  return { ...matrix, norms, builtAt: Date.now() };
+}
+
+/** 余弦 top-K（纯内存暴力；万级候选毫秒级，方案 §3.3） */
+export function cosineTopK(index, qvec, topK) {
+  const { data, dim, count, norms } = index;
+  if (!dim || !count) return [];
+  let qn = 0;
+  for (let i = 0; i < dim; i += 1) qn += qvec[i] * qvec[i];
+  qn = Math.sqrt(qn) || 1;
+  const scores = new Float32Array(count);
+  for (let r = 0; r < count; r += 1) {
+    let s = 0;
+    const off = r * dim;
+    for (let i = 0; i < dim; i += 1) s += data[off + i] * qvec[i];
+    scores[r] = s / (qn * norms[r]);
+  }
+  const order = Array.from({ length: count }, (_, i) => i);
+  order.sort((a, b) => scores[b] - scores[a] || a - b);
+  const k = Math.min(Number(topK) || 0, count);
+  const out = [];
+  for (let i = 0; i < k; i += 1) {
+    const idx = order[i];
+    out.push({ index: idx, refId: index.refIds[idx], id: index.refIdsNum[idx], score: scores[idx] });
+  }
+  return out;
+}
+
+/**
+ * refId → 数字 id。
+ * ⚠️ 语义定稿（方案 C1 + 2026-10-10 落地）：**数字 `id` 只是 memory 源的兼容字段**
+ *   （`memories.id` 是整数主键）；其它来源（坑库 16 位 hex、未来 policy）的 `ref_id` 是**不透明键**
+ *   ⇒ 一律给 `null`，绝不写 `NaN`（也避免 hex 全数字时与记忆 id 撞号）。
+ */
+export function refIdToNum(refId) {
+  const s = String(refId);
+  // 前导零视为不透明键（记忆 id 是自增整数，不会带前导零）
+  if (!/^(0|[1-9]\d*)$/.test(s)) return null;
+  const n = Number(s);
+  return Number.isSafeInteger(n) ? n : null;
+}
+
+/**
+ * refId 平局裁决比较器（方案 C1）：
+ * 两侧都是纯数字串 ⇒ **按数值**比（与旧行为逐字节一致，memory 源不受影响）；
+ * 任一不是数字（如坑库 hex）⇒ 按**字符串字典序**比（稳定、可复现，不再出现 `NaN - NaN` 的乱序）。
+ */
+export function cmpRefId(a, b) {
+  const sa = String(a);
+  const sb = String(b);
+  const na = /^-?\d+$/.test(sa);
+  const nb = /^-?\d+$/.test(sb);
+  if (na && nb) return Number(sa) - Number(sb);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+
+/**
+ * RRF 融合（k=60）：score(d) = Σ_r 1/(k + rank_r(d))
+ * @param {Array<{source:string, ids:string[]}>} rankLists 各路排名（已按优劣降序，rank 从 1 起）
+ */
+export function rrfFuse(rankLists, k = 60) {
+  const acc = new Map();
+  for (const list of rankLists) {
+    if (!list || !list.ids) continue;
+    list.ids.forEach((id, i) => {
+      const rank = i + 1;
+      const cur = acc.get(String(id)) || { id: String(id), score: 0, sources: [], ranks: {} };
+      cur.score += 1 / (k + rank);
+      if (!cur.sources.includes(list.source)) cur.sources.push(list.source);
+      cur.ranks[list.source] = rank;
+      acc.set(String(id), cur);
+    });
+  }
+  return [...acc.values()].sort((a, b) => b.score - a.score || cmpRefId(a.id, b.id));
+}
+
+/**
+ * 召回主入口。
+ * fail-open：任何异常都由调用方兜住（本函数内部对 FTS 异常降级为空路）。
+ * @returns {Promise<object>}
+ */
+export async function recall({
+  query,
+  store,
+  source,
+  embedder,
+  index = null,
+  sourceName = 'memory',
+  vectorTopK = 20,
+  ftsTopK = 20,
+  rrfK = 60,
+  resultTopK = 8,
+  log = () => {},
+}) {
+  const t0 = performance.now();
+  const gate = shouldTrigger(query);
+  if (!gate.trigger) {
+    return { triggered: false, reason: gate.reason, query: String(query ?? ''), hits: [], timings: { totalMs: 0 } };
+  }
+
+  const db = store.db;
+  const pinned = new Set((source ? source.pinnedIds() : []).map(String));
+
+  // ① 查询编码
+  const tEnc = performance.now();
+  const qvec = await embedder.encode(query);
+  const encodeMs = performance.now() - tEnc;
+
+  // ② 向量路
+  const tVec = performance.now();
+  const idx = index || buildVectorIndex(db, { source: sourceName });
+  const rawVec = cosineTopK(idx, qvec, vectorTopK + pinned.size + 5);
+  const vecHits = rawVec.filter((h) => !pinned.has(String(h.refId))).slice(0, vectorTopK);
+  const vectorMs = performance.now() - tVec;
+
+  // ③ FTS 补位路（仅英文/数字；缺失时不参与，不做零分占位）
+  const tFts = performance.now();
+  let ftsHits = [];
+  let ftsMatched = 0;
+  const tokens = extractFtsTokens(query);
+  const matchExpr = buildFtsMatch(tokens);
+  if (matchExpr && source) {
+    const r = source.ftsSearch(matchExpr, ftsTopK + pinned.size + 5);
+    if (Array.isArray(r)) {
+      ftsMatched = r.length;
+      ftsHits = r.filter((h) => !pinned.has(String(h.id))).slice(0, ftsTopK);
+    } else if (r && r.error) {
+      log(`[recall] FTS 补位降级：${r.error}`);
+    }
+  }
+  const ftsMs = performance.now() - tFts;
+
+  // ④ RRF 融合
+  const tFuse = performance.now();
+  const fused = rrfFuse(
+    [
+      { source: 'vector', ids: vecHits.map((h) => String(h.refId)) },
+      { source: 'fts', ids: ftsHits.map((h) => String(h.id)) },
+    ],
+    rrfK,
+  );
+  const hits = fused.slice(0, Number(resultTopK) || 8).map((h) => ({
+    refId: h.id,
+    // 数字 id 只对 memory 源有意义（见 refIdToNum 注释）；其它来源恒为 null
+    id: sourceName === 'memory' ? refIdToNum(h.id) : null,
+    source: sourceName,
+    score: h.score,
+    sources: h.sources,
+    vectorRank: h.ranks.vector ?? null,
+    ftsRank: h.ranks.fts ?? null,
+  }));
+  const fuseMs = performance.now() - tFuse;
+
+  const totalMs = performance.now() - t0;
+  return {
+    triggered: true,
+    reason: gate.reason,
+    query: String(query ?? ''),
+    hits,
+    timings: { encodeMs, vectorMs, ftsMs, fuseMs, totalMs },
+    stats: {
+      sourceName,
+      indexSize: idx.count,
+      pinnedExcluded: pinned.size,
+      vectorCandidates: rawVec.length,
+      vectorHits: vecHits.length,
+      ftsTokens: tokens,
+      ftsMatchExpr: matchExpr,
+      ftsMatched,
+      ftsHits: ftsHits.length,
+      fused: fused.length,
+    },
+  };
+}
+
+/**
+ * **多来源召回**（方案 §3 A.2 第 5 行新增入口）：query 只编码一次，逐来源各做「向量 top-K + FTS 补位」，
+ * 跨来源用 RRF 融合；每个命中带 `source` 归属，融合键 = `<source名>:<refId>`（**否则两源同 id 会互相吃掉**）。
+ *
+ * 逐来源 fail-open：某来源无库/无向量/报错 ⇒ 记一行、跳过该来源，**不影响其他来源**。
+ * @param {object} p
+ * @param {Array<{name:string, source?:object, index?:object}>} p.entries 来源列表（name 即 `vectors.source`）
+ */
+export async function recallMulti({
+  query,
+  store,
+  entries,
+  embedder,
+  perSourceTopK = 5,
+  rrfK = 60,
+  resultTopK = 8,
+  log = () => {},
+}) {
+  const t0 = performance.now();
+  const gate = shouldTrigger(query);
+  if (!gate.trigger) {
+    return {
+      triggered: false,
+      reason: gate.reason,
+      query: String(query ?? ''),
+      hits: [],
+      perSource: {},
+      timings: { totalMs: 0 },
+    };
+  }
+
+  const db = store.db;
+  const tEnc = performance.now();
+  const qvec = await embedder.encode(query);
+  const encodeMs = performance.now() - tEnc;
+
+  const tokens = extractFtsTokens(query);
+  const matchExpr = buildFtsMatch(tokens);
+  const rankLists = [];
+  const meta = new Map();
+  const perSource = {};
+  const keyOf = (name, refId) => `${name}:${String(refId)}`;
+
+  const tVec = performance.now();
+  for (const e of entries || []) {
+    const name = String(e.name);
+    const src = e.source || null;
+    const rec = { indexSize: 0, pinnedExcluded: 0, vectorHits: 0, ftsHits: 0, error: null };
+    try {
+      const idx = e.index || buildVectorIndex(db, { source: name });
+      rec.indexSize = idx.count;
+      const pinned = new Set((src ? src.pinnedIds() : []).map(String));
+      rec.pinnedExcluded = pinned.size;
+      const rawVec = cosineTopK(idx, qvec, perSourceTopK + pinned.size + 5);
+      const vecHits = rawVec.filter((h) => !pinned.has(String(h.refId))).slice(0, perSourceTopK);
+      rec.vectorHits = vecHits.length;
+      rankLists.push({ source: `vector:${name}`, ids: vecHits.map((h) => keyOf(name, h.refId)) });
+      for (const h of vecHits) meta.set(keyOf(name, h.refId), { name, refId: String(h.refId) });
+
+      if (matchExpr && src) {
+        const r = src.ftsSearch(matchExpr, perSourceTopK + pinned.size + 5);
+        if (Array.isArray(r)) {
+          const ftsHits = r.filter((h) => !pinned.has(String(h.id))).slice(0, perSourceTopK);
+          rec.ftsHits = ftsHits.length;
+          rankLists.push({ source: `fts:${name}`, ids: ftsHits.map((h) => keyOf(name, h.id)) });
+          for (const h of ftsHits) meta.set(keyOf(name, h.id), { name, refId: String(h.id) });
+        } else if (r && r.error) {
+          log(`[recallMulti] ${name} FTS 补位降级：${r.error}`);
+        }
+      }
+    } catch (err) {
+      rec.error = String(err && err.message ? err.message : err);
+      log(`[recallMulti] 来源 ${name} 跳过：${rec.error}`);
+    }
+    perSource[name] = rec;
+  }
+  const vectorMs = performance.now() - tVec;
+
+  const tFuse = performance.now();
+  const fused = rrfFuse(rankLists, rrfK);
+  const hits = fused.slice(0, Number(resultTopK) || 8).map((h) => {
+    const m = meta.get(h.id) || { name: null, refId: h.id };
+    return {
+      key: h.id,
+      source: m.name,
+      refId: m.refId,
+      id: m.name === 'memory' ? refIdToNum(m.refId) : null,
+      score: h.score,
+      sources: h.sources,
+      vectorRank: m.name ? h.ranks[`vector:${m.name}`] ?? null : null,
+      ftsRank: m.name ? h.ranks[`fts:${m.name}`] ?? null : null,
+    };
+  });
+  const fuseMs = performance.now() - tFuse;
+
+  return {
+    triggered: true,
+    reason: gate.reason,
+    query: String(query ?? ''),
+    hits,
+    perSource,
+    timings: { encodeMs, vectorMs, fuseMs, totalMs: performance.now() - t0 },
+    stats: {
+      sources: (entries || []).map((e) => String(e.name)),
+      ftsTokens: tokens,
+      ftsMatchExpr: matchExpr,
+      rankLists: rankLists.length,
+      fused: fused.length,
+    },
+  };
+}

package/memory-engine/lib/selfcheck.mjs

@@ -0,0 +1,131 @@
+// 记忆引擎 v2 · 离线层 —— 启动自检（方案 §8.3 交付物 #9）
+//
+// 四判据：模型可用性 / 维度一致 / 表存在性（缺则重建）/ hostId 校验。
+// 自检失败绝不阻断启动：返回结构化结果，由调用方决定是否降级。
+import { SCHEMA_VERSION } from './config.mjs';
+import { META_KEYS, getMeta, getMetaFor, setMeta, countVectors } from './vectors-store.mjs';
+
+export async function runSelfcheck({
+  store,
+  source = null,
+  sources = null,
+  sourceName = 'memory',
+  embedder,
+  config,
+  allowHostMismatch = true,
+}) {
+  const db = store.db;
+  const checks = [];
+  const add = (name, status, detail, extra = {}) => {
+    checks.push({ name, status, detail, ...extra });
+    return status;
+  };
+
+  // ① 表存在性（缺则重建）
+  const t = store.schema.tables;
+  if (t.vectors && t.meta) {
+    add(
+      '表存在性',
+      'ok',
+      store.schema.created.length
+        ? `缺表已重建：${store.schema.created.join(', ')}`
+        : 'vectors / meta 均在位',
+      { created: store.schema.created },
+    );
+  } else {
+    add('表存在性', 'fail', 'vectors 或 meta 表缺失且重建失败');
+  }
+
+  // ② schemaVersion
+  const sv = getMeta(db, META_KEYS.schemaVersion);
+  add(
+    'schemaVersion',
+    sv === SCHEMA_VERSION ? 'ok' : 'warn',
+    sv === SCHEMA_VERSION ? `=${sv}` : `库内为 ${sv ?? '(空)'}，代码期望 ${SCHEMA_VERSION}`,
+    { schemaVersion: sv },
+  );
+
+  // ③ 模型可用性
+  let health = { ready: false, error: 'not probed' };
+  try {
+    health = await embedder.health();
+  } catch (e) {
+    health = { ready: false, error: String(e && e.message ? e.message : e) };
+  }
+  add(
+    '模型可用性',
+    health.ready ? 'ok' : 'fail',
+    health.ready
+      ? `${health.model ?? embedder.modelId} @ ${health.modelDir ?? health.bridge ?? embedder.kind}`
+      : `不可用：${health.error || 'unknown'}`,
+    { health },
+  );
+
+  // ④ 维度一致（编码探测 + 与库内 meta / 配置三方比对）
+  let probeDim = null;
+  let probeError = null;
+  try {
+    const v = await embedder.encode('维度自检');
+    probeDim = v.length;
+  } catch (e) {
+    probeError = String(e && e.message ? e.message : e);
+  }
+  const metaDim = getMetaFor(db, META_KEYS.dim, sourceName);
+  if (probeError) {
+    add('维度一致', 'fail', `编码探测失败：${probeError}`);
+  } else {
+    const configOk = Number(probeDim) === Number(config.dim);
+    const metaOk = metaDim == null || Number(metaDim) === Number(probeDim);
+    const status = configOk && metaOk ? 'ok' : 'fail';
+    add(
+      '维度一致',
+      status,
+      `实测 ${probeDim} 维 / 配置 ${config.dim} / 库内 ${metaDim ?? '(空)'}` +
+        (status === 'ok' ? '' : ' ⇒ 需全量重建（--full）'),
+      { probeDim, configDim: config.dim, metaDim },
+    );
+  }
+
+  // ⑤ hostId 校验（向量库明确不同步；hostId 不符说明库来自别的机器）
+  const metaHost = getMeta(db, META_KEYS.hostId);
+  if (!metaHost) {
+    setMeta(db, META_KEYS.hostId, String(config.hostId));
+    add('hostId 校验', 'ok', `首次初始化，已写入 ${config.hostId}`);
+  } else if (metaHost === String(config.hostId)) {
+    add('hostId 校验', 'ok', `=${metaHost}`);
+  } else {
+    add(
+      'hostId 校验',
+      allowHostMismatch ? 'warn' : 'fail',
+      `库内 hostId=${metaHost}，当前=${config.hostId} ⇒ 该库非本机产物，建议全量重建（--full）`,
+      { metaHost, current: config.hostId },
+    );
+  }
+
+  // ⑥ 覆盖度（信息项；非判据）——【2026-10-10 · 补坑库联动A】改成**逐 source** 报告
+  //    ⚠️ 判据不是"向量数 vs 记忆数"这一种：坑源的对照物是**坑库条数**（`butler-pitfalls.json` 的条目数）。
+  const srcList = sources && sources.length
+    ? sources.map((s) => ({ name: String(s.name), source: s.source }))
+    : source
+      ? [{ name: String(sourceName), source }]
+      : [];
+  for (const s of srcList) {
+    const label = srcList.length > 1 ? `向量覆盖度(${s.name})` : '向量覆盖度';
+    try {
+      const memCount = s.source.count();
+      const vecCount = countVectors(db, s.name);
+      const ratio = memCount ? (vecCount / memCount) * 100 : 0;
+      add(label, 'info', `${s.name} 源：向量 ${vecCount} 条 / 源条数 ${memCount} 条（${ratio.toFixed(1)}%）`, {
+        sourceName: s.name,
+        vecCount,
+        memCount,
+      });
+    } catch (e) {
+      add(label, 'warn', `统计失败：${String(e && e.message ? e.message : e)}`);
+    }
+  }
+
+  const failed = checks.filter((c) => c.status === 'fail');
+  const warned = checks.filter((c) => c.status === 'warn');
+  return { ok: failed.length === 0, checks, failed: failed.length, warned: warned.length };
+}

package/memory-engine/lib/sweep.mjs

@@ -0,0 +1,159 @@
+// 记忆引擎 v2 · 离线层 —— 兜底：全表 text_hash 段轮转校验（方案 §3.1 兜底 / §6.2 ②）
+//
+// 为什么必须有（A7 实测）：41 处外部 `UPDATE memories SET text=?` 中，
+// apply-pinned-refine.mjs:110 改 text **不动 updated_at** ⇒ 这类勘误永远进不了增量窗口。
+// 兜底外置、不与增量主路径共用候选集；按 id 段轮转，累计若干轮覆盖全表。
+import { textHash } from './hashes.mjs';
+import { META_KEYS, getMetaFor, setMetaFor, getHashes, upsertVectors } from './vectors-store.mjs';
+// 【S3c 挂钩（2026-09-21）】轮转发现的"正文变了"差异**必须落 `memories_dirty` 台账**：
+//   本函数发现差异后会**立刻重编码并更新 `vectors.text_hash`** ⇒ 差异信号当场消失。
+//   若此刻只用于重编码而不留痕，被外部改过 text 的条（A7 的 41 处写口）就再也没人知道要提炼它们。
+//   台账是**只加不改**的旁路；`recordDirty` 幂等（同一条重复扫到只 hits+1，不复活已消费项）。
+import { recordDirty } from './dirty-ledger.mjs';
+
+/**
+ * @param {object} p
+ * @param {object} p.source
+ * @param {object} p.store
+ * @param {object} p.embedder
+ * @param {number} p.segments  全表分几段（默认 20）
+ * @param {number} p.rounds    本次跑几段（默认 1；--all 传 segments = 一轮完整覆盖）
+ * @param {string} [p.sourceName='memory'] 向量来源名
+ *   ⚠️ 轮转语义按来源不同：memory = **id 段**；pitfall = `segment()` 内部按 `lastSeen` 排序后切片
+ *      （`idRange()` 给的是排序下标区间 ⇒ 同一段轮转代码对两个来源都成立，不必分支）。
+ */
+export async function runHashSweep({
+  source,
+  store,
+  embedder,
+  modelId,
+  dim,
+  sourceName = 'memory',
+  segments = 20,
+  rounds = 1,
+  dryRun = false,
+  log = () => {},
+  now = () => Date.now(),
+}) {
+  const db = store.db;
+  const src = String(sourceName || 'memory');
+  // ⚠️ `memories_dirty` 台账的语义是「哪条**记忆**的正文被外部改过、待提炼」——
+  //    坑源跑兜底时**不得**把 16 位 hex 的坑 id 记进去（会污染提炼侧输入）。故只对 memory 源落台账。
+  const useDirtyLedger = src === 'memory';
+  const startedAt = now();
+  const range = source.idRange();
+  const stats = {
+    source: src,
+    mode: 'hash-sweep',
+    segments,
+    rounds,
+    range,
+    cursorStart: Number(getMetaFor(db, META_KEYS.hashSweepCursor, src) || 0) % Math.max(1, segments),
+    cursorEnd: 0,
+    scanned: 0,
+    mismatched: 0,
+    missing: 0,
+    fixed: 0,
+    dirtyRecorded: 0,
+    segmentReports: [],
+    completedFullSweep: false,
+    elapsedMs: 0,
+    failures: [],
+  };
+  if (range.lo == null) {
+    stats.cursorEnd = stats.cursorStart;
+    stats.finishedAt = now();
+    stats.elapsedMs = stats.finishedAt - startedAt;
+    log(`[sweep] ${src} 源为空，跳过`);
+    return stats;
+  }
+
+  const width = Math.max(1, Math.ceil((range.hi - range.lo + 1) / Math.max(1, segments)));
+  let cursor = stats.cursorStart;
+
+  try {
+    for (let i = 0; i < rounds; i += 1) {
+      const lo = range.lo + cursor * width;
+      const hi = Math.min(range.hi, lo + width - 1);
+      const rows = source.segment(lo, hi);
+      const hashes = getHashes(db, src, rows.map((r) => r.id));
+      const need = [];
+      // 【S3c】差异明细（只收 "mismatch"：正文哈希与向量库不符 = 被外部改过 text）
+      const dirtyItems = [];
+      let missing = 0;
+      let mismatched = 0;
+      for (const r of rows) {
+        const h = textHash(r.text);
+        const prev = hashes.get(String(r.id));
+        if (prev === undefined) {
+          missing += 1;
+          need.push({ row: r, hash: h });
+        } else if (prev !== h) {
+          mismatched += 1;
+          need.push({ row: r, hash: h });
+          dirtyItems.push({ refId: r.id, kind: 'mismatch', oldHash: prev, newHash: h });
+        }
+      }
+      // 先落台账、再重编码（顺序不能反：重编码会把 old_hash 覆盖掉，差异就再也说不清了）
+      if (!dryRun && useDirtyLedger && dirtyItems.length) {
+        try {
+          recordDirty(db, dirtyItems, { now: now() });
+          stats.dirtyRecorded = (stats.dirtyRecorded ?? 0) + dirtyItems.length;
+        } catch (e) {
+          // 台账写失败**不得**影响主路径（它只是提炼侧的补充输入源）
+          stats.failures.push({ stage: 'dirty-ledger', message: String(e && e.message ? e.message : e) });
+        }
+      }
+      if (need.length) {
+        const vecs = await embedder.encodeBatch(need.map((n) => n.row.text));
+        if (!dryRun) {
+          upsertVectors(
+            db,
+            need.map((n, k) => ({
+              source: src,
+              refId: n.row.id,
+              model: modelId,
+              dim: vecs[k].length,
+              vec: vecs[k],
+              textHash: n.hash,
+              updatedAt: n.row.updated_at,
+            })),
+          );
+        }
+      }
+      stats.scanned += rows.length;
+      stats.missing += missing;
+      stats.mismatched += mismatched;
+      stats.fixed += need.length;
+      stats.segmentReports.push({
+        segment: cursor,
+        lo,
+        hi,
+        rows: rows.length,
+        missing,
+        mismatched,
+        fixed: need.length,
+      });
+      log(
+        `[sweep] 段 ${cursor}（id ${lo}-${hi}）：${rows.length} 条，缺失 ${missing}，哈希不符 ${mismatched} ⇒ 重编码 ${need.length}`,
+      );
+      cursor = (cursor + 1) % Math.max(1, segments);
+      if (cursor === 0) stats.completedFullSweep = true;
+    }
+  } catch (e) {
+    stats.failures.push({ stage: 'sweep', message: String(e && e.message ? e.message : e) });
+    stats.error = stats.failures[0].message;
+  }
+
+  stats.cursorEnd = cursor;
+  if (!dryRun) {
+    setMetaFor(db, META_KEYS.hashSweepCursor, src, String(cursor));
+    if (stats.completedFullSweep) {
+      stats.lastFullHashSweepAt = now();
+      setMetaFor(db, META_KEYS.lastFullHashSweepAt, src, String(stats.lastFullHashSweepAt));
+    }
+  }
+  stats.finishedAt = now();
+  stats.elapsedMs = stats.finishedAt - startedAt;
+  return stats;
+}