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

package/memory-engine/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "dsh-memory-engine",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "记忆引擎 v2 · 离线层（独立向量库 / 增量同步 / 兜底 hash 轮转 / 召回 / 启动自检）· 方案 docs/P2-记忆引擎升级-方案-20260916.md §3.1 §3.3 §8.3",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node test/run.mjs",
+    "selfcheck": "node cli/selfcheck.mjs",
+    "sync": "node cli/sync.mjs",
+    "sweep": "node cli/sweep.mjs",
+    "recall": "node cli/recall.mjs",
+    "serve": "node serve.mjs",
+    "bench": "node bench/bench.mjs"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.5.2"
+  }
+}

package/memory-engine/serve.mjs

@@ -0,0 +1,171 @@
+// 记忆引擎 v2 · 离线层 —— 编码桥（方案 §3.1 编码通道契约）
+//
+// 契约：
+//   · 仅绑 127.0.0.1（禁任何非回环绑定）；端口 8201，被占则 +1 顺延并落日志
+//   · POST /encode {"texts":[…]} → {"vectors":[[…]],"model":…,"dim":512}
+//   · GET  /health → {ready, modelLoading, model, dim, port}
+//   · 模型懒加载；桥不在 / 加载中 / 异常 ⇒ 调用方 fail-open（本进程不崩对话）
+import http from 'node:http';
+import { resolveConfig } from './lib/config.mjs';
+import { createLocalEmbedder } from './lib/embedder.mjs';
+import { parseArgs, num, isMainEntry } from './lib/cli-util.mjs';
+
+const MAX_PORT_TRIES = 10;
+const MAX_BODY = 4 * 1024 * 1024;
+
+export async function startBridge({ flags = {}, log = (m) => process.stdout.write(m + '\n') } = {}) {
+  const config = resolveConfig({
+    modelDir: flags['model-dir'] || undefined,
+    modelId: flags.model || undefined,
+    dim: flags.dim ? Number(flags.dim) : undefined,
+    bridgeHost: flags.host || undefined,
+    bridgePort: flags.port ? Number(flags.port) : undefined,
+  });
+  const host = flags.bind || config.bridgeHost;
+  if (!/^(127\.0\.0\.1|localhost|::1)$/.test(String(host))) {
+    throw new Error(`只允许回环绑定（方案 §3.1：禁止任何非回环绑定），收到 ${host}`);
+  }
+
+  const state = {
+    modelLoading: false,
+    modelReady: false,
+    embedder: null,
+    error: null,
+    encodeCalls: 0,
+    encodedTexts: 0,
+    lastErrorAt: null,
+    port: null,
+    startedAt: Date.now(),
+  };
+
+  const ensureModel = async () => {
+    if (state.modelReady || state.modelLoading) return;
+    state.modelLoading = true;
+    const t0 = Date.now();
+    try {
+      state.embedder = await createLocalEmbedder({
+        modelDir: config.modelDir,
+        modelId: config.modelId,
+        dim: config.dim,
+        quantized: Boolean(flags.quantized),
+        dtype: flags.dtype || null,
+      });
+      state.modelReady = true;
+      log(`[bridge] 模型就绪 ${config.modelId} dim=${state.embedder.dim} 加载 ${Date.now() - t0}ms dir=${config.modelDir}`);
+    } catch (e) {
+      state.error = String(e && e.message ? e.message : e);
+      state.lastErrorAt = Date.now();
+      log(`[bridge] 模型加载失败：${state.error}`);
+    } finally {
+      state.modelLoading = false;
+    }
+  };
+
+  const readBody = (req) =>
+    new Promise((resolve, reject) => {
+      let n = 0;
+      const chunks = [];
+      req.on('data', (c) => {
+        n += c.length;
+        if (n > MAX_BODY) {
+          reject(new Error('body too large'));
+          req.destroy();
+          return;
+        }
+        chunks.push(c);
+      });
+      req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+      req.on('error', reject);
+    });
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${host}`);
+    const send = (code, obj) => {
+      const body = JSON.stringify(obj);
+      res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) });
+      res.end(body);
+    };
+    try {
+      if (req.method === 'GET' && url.pathname === '/health') {
+        send(200, {
+          ready: state.modelReady,
+          modelLoading: state.modelLoading,
+          model: config.modelId,
+          dim: state.embedder ? state.embedder.dim : config.dim,
+          port: state.port,
+          host,
+          pid: process.pid,
+          uptimeMs: Date.now() - state.startedAt,
+          encodeCalls: state.encodeCalls,
+          encodedTexts: state.encodedTexts,
+          modelDir: config.modelDir,
+          lastError: state.error && state.lastErrorAt && Date.now() - state.lastErrorAt < 60000 ? state.error : null,
+        });
+        return;
+      }
+      if (req.method === 'POST' && url.pathname === '/encode') {
+        const body = JSON.parse((await readBody(req)) || '{}');
+        const texts = Array.isArray(body.texts) ? body.texts.map((t) => String(t ?? '')) : null;
+        if (!texts) return send(400, { error: 'body.texts 必须是字符串数组' });
+        if (!state.modelReady) {
+          if (!state.modelLoading) void ensureModel();
+          return send(503, { error: state.error || 'model loading', modelLoading: true, model: config.modelId });
+        }
+        state.encodeCalls += 1;
+        state.encodedTexts += texts.length;
+        const vectors = await state.embedder.encodeBatch(texts);
+        return send(200, { vectors: vectors.map((v) => Array.from(v)), model: config.modelId, dim: vectors[0] ? vectors[0].length : config.dim });
+      }
+      if (req.method === 'POST' && url.pathname === '/shutdown') {
+        send(200, { ok: true });
+        // 铁律：不发 process.exit() 强退（undici 句柄未收尾会概率性 0xC0000409）⇒ 关服务自然退出
+        setTimeout(() => {
+          server.close();
+          process.exitCode = 0;
+        }, 50);
+        return;
+      }
+      send(404, { error: 'not found', routes: ['GET /health', 'POST /encode'] });
+    } catch (e) {
+      state.error = String(e && e.message ? e.message : e);
+      state.lastErrorAt = Date.now();
+      send(500, { error: state.error });
+    }
+  });
+
+  // 端口占用 → +1 顺延（最多 10 次）
+  const listen = (port, tries = 0) =>
+    new Promise((resolve, reject) => {
+      const onError = (e) => {
+        if (e.code === 'EADDRINUSE' && tries < MAX_PORT_TRIES) {
+          log(`[bridge] 端口 ${port} 被占，顺延到 ${port + 1}`);
+          server.removeListener('error', onError);
+          resolve(listen(port + 1, tries + 1));
+        } else {
+          reject(e);
+        }
+      };
+      server.once('error', onError);
+      server.listen(port, host, () => {
+        server.removeListener('error', onError);
+        state.port = port;
+        resolve(port);
+      });
+    });
+
+  const port = await listen(config.bridgePort);
+  log(`[bridge] 监听 http://${host}:${port}（仅回环）model=${config.modelId} dir=${config.modelDir}`);
+  if (flags.warm !== false) void ensureModel();
+  return { server, port, state, config, close: () => new Promise((r) => server.close(r)) };
+}
+
+if (isMainEntry(import.meta.url)) {
+  const { flags } = parseArgs();
+  const bridge = await startBridge({ flags });
+  const shutdown = async () => {
+    await bridge.close();
+    process.exitCode = 0;
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/memory-engine/test/01-store.test.mjs

@@ -0,0 +1,127 @@
+// 01 · 向量库（独立库 / schema / meta / Float32 往返）
+import fs from 'node:fs';
+import { test, assert, assertEq } from './harness.mjs';
+import { makeTempRoot } from './fixtures.mjs';
+import {
+  openVectorsStore,
+  META_KEYS,
+  getMeta,
+  setMeta,
+  getMetaAll,
+  upsertVectors,
+  loadMatrix,
+  getHashes,
+  countVectors,
+  deleteSource,
+  vecToBlob,
+  blobToVec,
+} from '../lib/vectors-store.mjs';
+
+export const __section = '01 · 向量库（独立库 / schema / meta / Float32 往返）';
+
+test('建库：vectors + meta 表按需创建，schemaVersion 自动落 meta', () => {
+  const t = makeTempRoot();
+  try {
+    const store = openVectorsStore(t.paths.vectorsDb);
+    assertEq(store.schema.tables.vectors, true, 'vectors 表');
+    assertEq(store.schema.tables.meta, true, 'meta 表');
+    assert(store.schema.created.includes('vectors'), '首次应报告新建 vectors');
+    // 【2026-10-10 · 补坑库联动A】**有意**由 '1' 改为 '2'：meta 键位加 `<key>:<source>` 命名空间（表结构未变）。
+    //   本断言改写属口径变更登记，不是"为过测而改用例"（未改断言语义，只跟版本号）。
+    assertEq(getMeta(store.db, META_KEYS.schemaVersion), '2', 'schemaVersion');
+    const again = openVectorsStore(t.paths.vectorsDb);
+    assertEq(again.schema.created.length, 0, '重开不应再创建表（幂等）');
+    store.db.close();
+    again.db.close();
+    assert(fs.existsSync(t.paths.vectorsDb), '库文件存在');
+  } finally {
+    t.cleanup();
+  }
+});
+
+test('Float32 往返：BLOB 读回数值逐位相等（含非零 byteOffset 场景）', () => {
+  const t = makeTempRoot();
+  try {
+    const store = openVectorsStore(t.paths.vectorsDb);
+    const vec = Float32Array.from({ length: 512 }, (_, i) => Math.sin(i) * 1.5);
+    upsertVectors(store.db, [
+      { source: 'memory', refId: '1', model: 'm', dim: 512, vec, textHash: 'h1', updatedAt: 1 },
+    ]);
+    const m = loadMatrix(store.db, 'memory');
+    assertEq(m.count, 1, '条数');
+    assertEq(m.dim, 512, '维度');
+    let maxDiff = 0;
+    for (let i = 0; i < 512; i += 1) maxDiff = Math.max(maxDiff, Math.abs(m.data[i] - vec[i]));
+    assertEq(maxDiff, 0, '往返误差');
+    store.db.close();
+  } finally {
+    t.cleanup();
+  }
+});
+
+test('upsert 幂等：同 ref_id 覆盖不新增行，hash/向量同步更新', () => {
+  const t = makeTempRoot();
+  try {
+    const store = openVectorsStore(t.paths.vectorsDb);
+    const v1 = Float32Array.from([1, 0, 0]);
+    const v2 = Float32Array.from([0, 1, 0]);
+    upsertVectors(store.db, [{ source: 'memory', refId: '7', model: 'm', dim: 3, vec: v1, textHash: 'a', updatedAt: 1 }]);
+    upsertVectors(store.db, [{ source: 'memory', refId: '7', model: 'm', dim: 3, vec: v2, textHash: 'b', updatedAt: 2 }]);
+    assertEq(countVectors(store.db, 'memory'), 1, '仍只有 1 行');
+    assertEq(getHashes(store.db, 'memory', ['7']).get('7'), 'b', 'hash 已更新');
+    const m = loadMatrix(store.db, 'memory');
+    assertEq(Array.from(m.data), [0, 1, 0], '向量已更新');
+    store.db.close();
+  } finally {
+    t.cleanup();
+  }
+});
+
+test('meta 读写与 deleteSource：按 source 清理（可重建载体）', () => {
+  const t = makeTempRoot();
+  try {
+    const store = openVectorsStore(t.paths.vectorsDb);
+    setMeta(store.db, 'k1', 'v1');
+    setMeta(store.db, 'k1', 'v2');
+    assertEq(getMeta(store.db, 'k1'), 'v2', 'meta 覆盖写');
+    upsertVectors(store.db, [
+      { source: 'memory', refId: '1', model: 'm', dim: 2, vec: Float32Array.from([1, 0]), textHash: 'x', updatedAt: 1 },
+      { source: 'doc', refId: 'p#1', model: 'm', dim: 2, vec: Float32Array.from([0, 1]), textHash: 'y', updatedAt: 1 },
+    ]);
+    assertEq(countVectors(store.db), 2, '全库 2 条');
+    assertEq(deleteSource(store.db, 'memory'), 1, '删 memory 源');
+    assertEq(countVectors(store.db, 'doc'), 1, 'doc 源留存');
+    assert(getMetaAll(store.db).k1 === 'v2', 'getMetaAll 可读');
+    store.db.close();
+  } finally {
+    t.cleanup();
+  }
+});
+
+test('维度混入：loadMatrix 遇到不一致维度必须大声报错（不静默复用）', () => {
+  const t = makeTempRoot();
+  try {
+    const store = openVectorsStore(t.paths.vectorsDb);
+    upsertVectors(store.db, [
+      { source: 'memory', refId: '1', model: 'm', dim: 4, vec: Float32Array.from([1, 0, 0, 0]), textHash: 'x', updatedAt: 1 },
+      { source: 'memory', refId: '2', model: 'm', dim: 8, vec: Float32Array.from([1, 0, 0, 0, 0, 0, 0, 0]), textHash: 'y', updatedAt: 2 },
+    ]);
+    let err = null;
+    try {
+      loadMatrix(store.db, 'memory');
+    } catch (e) {
+      err = e;
+    }
+    assert(err && /维度不一致/.test(err.message), `应报维度不一致，实际 ${err && err.message}`);
+    store.db.close();
+  } finally {
+    t.cleanup();
+  }
+});
+
+test('vecToBlob/blobToVec：往返一致，blob 长度 = dim*4', () => {
+  const v = Float32Array.from([0.5, -0.25, 1, 0]);
+  const b = vecToBlob(v);
+  assertEq(b.byteLength, 16, 'blob 长度');
+  assertEq(Array.from(blobToVec(b)), Array.from(v), '往返');
+});

package/memory-engine/test/02-sync.test.mjs

@@ -0,0 +1,196 @@
+// 02 · 增量同步（幂等 / 换维度全量重建 / 失败保留进度可续跑 / 只读不写主库）
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { test, assert, assertEq } from './harness.mjs';
+import { makeTempRoot, makeMemoryDb, sampleRows, makeFlakyEmbedder } from './fixtures.mjs';
+import { openVectorsStore, META_KEYS, getMeta, countVectors } from '../lib/vectors-store.mjs';
+import { openMemorySource } from '../lib/memory-source.mjs';
+import { runIncrementalSync } from '../lib/sync.mjs';
+import { createStubEmbedder } from '../lib/embedder.mjs';
+
+export const __section = '02 · 增量同步（主路径）';
+
+const sha = (p) => crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+
+function setup(n = 5) {
+  const t = makeTempRoot();
+  makeMemoryDb(t.paths.memoryDb, sampleRows(n));
+  const store = openVectorsStore(t.paths.vectorsDb);
+  const source = openMemorySource(t.paths.memoryDb);
+  return { t, store, source, embedder: createStubEmbedder({ dim: 512 }) };
+}
+
+test('首轮增量：全量编码并落 vectors.db，水位前移到 max(updated_at)', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    const stats = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    assertEq(stats.mode, 'incremental', '模式');
+    assertEq(stats.scanned, 5, '扫描 5 条');
+    assertEq(stats.encoded, 5, '编码 5 条');
+    assertEq(stats.vectorsAfter, 5, '向量 5 条');
+    assertEq(stats.batches, 3, '批次数（batch=2）');
+    assertEq(Number(getMeta(store.db, META_KEYS.lastIncrementalSyncAt)), source.maxUpdatedAt(), '水位 = max(updated_at)');
+    assertEq(getMeta(store.db, META_KEYS.modelId), 'stub-ngram', 'meta.modelId');
+    assertEq(getMeta(store.db, META_KEYS.dim), '512', 'meta.dim');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('幂等：同日重跑不重复编码、向量条数不变', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    const first = countVectors(store.db, 'memory');
+    const stats2 = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    assertEq(stats2.mode, 'incremental', '仍是增量');
+    assertEq(stats2.encoded, 0, '第二轮零编码（全部同哈希跳过）');
+    assertEq(stats2.skippedSameHash, stats2.scanned, '扫描到的全部跳过');
+    assertEq(countVectors(store.db, 'memory'), first, '向量条数不变');
+    // 第三轮同样不重复
+    const stats3 = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    assertEq(stats3.encoded, 0, '第三轮仍零编码');
+    assertEq(countVectors(store.db, 'memory'), first, '条数仍不变');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('新增记忆：只编码新增条（增量窗口按 updated_at）', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    source.close();
+    // 追加两条更新的记忆
+    const rows = sampleRows(5);
+    const { makeMemoryDb: mk } = await import('./fixtures.mjs');
+    mk(t.paths.memoryDb, [
+      ...rows,
+      { id: 6, text: '新增记忆 A：向量层增量同步', tags: '技术', pinned: 0, updated_at: rows[4].updated_at + 1000 },
+      { id: 7, text: '新增记忆 B：召回 RRF 融合', tags: '技术', pinned: 0, updated_at: rows[4].updated_at + 2000 },
+    ]);
+    const source2 = openMemorySource(t.paths.memoryDb);
+    const stats = await runIncrementalSync({ source: source2, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    assertEq(stats.encoded, 2, '只编码新增 2 条');
+    assertEq(countVectors(store.db, 'memory'), 7, '向量 7 条');
+    source2.close();
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('换维度 → 自动全量重建（清空旧向量 + 重置水位）', async () => {
+  const { t, store, source, embedder } = setup(4);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    assertEq(countVectors(store.db, 'memory'), 4, '首轮 4 条');
+    const small = createStubEmbedder({ dim: 64 });
+    const stats = await runIncrementalSync({ source, store, embedder: small, modelId: 'stub-ngram', dim: 64 });
+    assertEq(stats.mode, 'rebuild', '判定为全量重建');
+    assert(stats.reasons.some((r) => /维度变更/.test(r)), `重建原因含维度变更：${stats.reasons.join('/')}`);
+    assertEq(stats.vectorsBefore, 0, '旧向量已清空（before 计在清空后）');
+    assertEq(stats.vectorsAfter, 4, '重建后 4 条');
+    assertEq(getMeta(store.db, META_KEYS.dim), '64', 'meta.dim 已更新');
+    const m = await import('../lib/vectors-store.mjs').then((x) => x.loadMatrix(store.db, 'memory'));
+    assertEq(m.dim, 64, '矩阵维度 64');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('换模型 → 自动全量重建', async () => {
+  const { t, store, source, embedder } = setup(3);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'model-A', dim: 512 });
+    const stats = await runIncrementalSync({ source, store, embedder, modelId: 'model-B', dim: 512 });
+    assertEq(stats.mode, 'rebuild', '换模型重建');
+    assert(stats.reasons.some((r) => /模型变更/.test(r)), '原因含模型变更');
+    assertEq(stats.vectorsAfter, 3, '重建后条数');
+    assertEq(getMeta(store.db, META_KEYS.modelId), 'model-B', 'meta.modelId 更新');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('失败保留进度可续跑：第 2 批崩 → 进度停在第 1 批，恢复后补齐', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    const flaky = makeFlakyEmbedder(embedder, { failOnBatchCall: 2 });
+    const s1 = await runIncrementalSync({ source, store, embedder: flaky, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    assert(s1.error, '应记录失败');
+    assertEq(s1.upserted, 2, '第 1 批 2 条已落盘');
+    assertEq(s1.batches, 2, '跑到第 2 批失败');
+    assertEq(s1.vectorsAfter, 2, '库里 2 条');
+    const wm = Number(getMeta(store.db, META_KEYS.lastIncrementalSyncAt));
+    assertEq(wm, source.incrementalPage(0, 0, 2)[1].updated_at, '水位 = 已成功批次的最大 updated_at');
+
+    // 恢复后续跑
+    const s2 = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, batchSize: 2 });
+    assert(!s2.error, '续跑无错');
+    assertEq(countVectors(store.db, 'memory'), 5, '最终 5 条齐全');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('--full 重建：清空后重编码，条数与记忆数一致', async () => {
+  const { t, store, source, embedder } = setup(6);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const stats = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, full: true });
+    assertEq(stats.mode, 'rebuild', '模式 = rebuild');
+    assertEq(stats.cleared, 6, '清空 6 条');
+    assertEq(stats.encoded, 6, '重编码 6 条');
+    assertEq(stats.vectorsAfter, source.count(), '向量数 = 记忆数');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('dry-run：不写库（向量条数 0 / 水位不动）', async () => {
+  const { t, store, source, embedder } = setup(4);
+  try {
+    const before = sha(t.paths.vectorsDb);
+    const stats = await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512, dryRun: true });
+    assertEq(stats.encoded, 4, '计划里要编码 4 条');
+    assertEq(countVectors(store.db, 'memory'), 0, '库里仍是 0 条');
+    assertEq(getMeta(store.db, META_KEYS.lastIncrementalSyncAt) ?? '0', '0', '水位未动（dry-run 不写 meta）');
+    const after = sha(t.paths.vectorsDb);
+    assert(before !== after || true, 'SHA 比对（WAL 下可能变，仅作观察）');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('只读主库：同步前后 memory.db 的 sha256 完全不变', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    const before = sha(t.paths.memoryDb);
+    const mtimeBefore = fs.statSync(t.paths.memoryDb).mtimeMs;
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const after = sha(t.paths.memoryDb);
+    assertEq(after, before, 'memory.db sha256 未变');
+    assertEq(fs.statSync(t.paths.memoryDb).mtimeMs, mtimeBefore, 'memory.db mtime 未变');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});

package/memory-engine/test/03-sweep.test.mjs

@@ -0,0 +1,145 @@
+// 03 · 兜底：全表 text_hash 段轮转（专治"改 text 不动 updated_at"的外部写口）
+import { test, assert, assertEq } from './harness.mjs';
+import { makeTempRoot, makeMemoryDb, sampleRows, silentTextUpdate, readVectorHash } from './fixtures.mjs';
+import { openVectorsStore, META_KEYS, getMeta, countVectors } from '../lib/vectors-store.mjs';
+import { openMemorySource } from '../lib/memory-source.mjs';
+import { runIncrementalSync } from '../lib/sync.mjs';
+import { runHashSweep } from '../lib/sweep.mjs';
+import { createStubEmbedder } from '../lib/embedder.mjs';
+import { textHash } from '../lib/hashes.mjs';
+import { listDirty } from '../lib/dirty-ledger.mjs';
+
+export const __section = '03 · 兜底 hash 轮转（A7 盲区）';
+
+function setup(n = 10) {
+  const t = makeTempRoot();
+  makeMemoryDb(t.paths.memoryDb, sampleRows(n));
+  const store = openVectorsStore(t.paths.vectorsDb);
+  const source = openMemorySource(t.paths.memoryDb);
+  return { t, store, source, embedder: createStubEmbedder({ dim: 512 }) };
+}
+
+test('命中人为改动：改 text 不动 updated_at ⇒ 增量扫不到、兜底能捞到并重编码', async () => {
+  const { t, store, source, embedder } = setup(10);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const oldHash = readVectorHash(store.db, 'memory', 3);
+
+    // 模拟 apply-pinned-refine.mjs:110 的行为：直接改 text，updated_at 纹丝不动
+    source.close();
+    silentTextUpdate(t.paths.memoryDb, 3, '【勘误后】跨机同步的挡推裁决口径（版本 B，人工修订）');
+    const source2 = openMemorySource(t.paths.memoryDb);
+
+    // 主路径：增量窗口看不到它
+    const inc = await runIncrementalSync({ source: source2, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    assertEq(inc.encoded, 0, '增量主路径扫不到（零编码）⇒ 盲区成立');
+    assertEq(readVectorHash(store.db, 'memory', 3), oldHash, '向量里的 hash 仍是旧的');
+
+    // 兜底：段轮转全表校验
+    const sweep = await runHashSweep({
+      source: source2,
+      store,
+      embedder,
+      modelId: 'stub-ngram',
+      dim: 512,
+      segments: 5,
+      rounds: 5,
+    });
+    assertEq(sweep.mismatched, 1, '恰好 1 条哈希不符（就是被手改的那条）');
+    assertEq(sweep.fixed, 1, '重编码 1 条');
+    assertEq(sweep.completedFullSweep, true, '一轮完整覆盖完成');
+    assertEq(
+      readVectorHash(store.db, 'memory', 3),
+      textHash('【勘误后】跨机同步的挡推裁决口径（版本 B，人工修订）'),
+      '兜底后 hash 与新文本一致',
+    );
+    assert(readVectorHash(store.db, 'memory', 3) !== oldHash, 'hash 确已变化');
+    // 【S3c 挂钩】兜底轮转的差异必须落 `memories_dirty` 台账（否则重编码后差异信号就永久消失了）
+    assertEq(sweep.dirtyRecorded, 1, '差异已入台账');
+    const led = listDirty(store.db, { openOnly: true });
+    assertEq(led.map((x) => Number(x.refId)), [3], '台账里正是被手改的那条（提炼 job 的补充输入源）');
+    assertEq(led[0].oldHash, oldHash, '台账留着改动前的 hash（可追）');
+    assertEq(led[0].newHash, textHash('【勘误后】跨机同步的挡推裁决口径（版本 B，人工修订）'), '台账记着改动后的 hash');
+    source2.close();
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('段轮转游标：每次推进一段，跑满 segments 轮才写 lastFullHashSweepAt', async () => {
+  const { t, store, source, embedder } = setup(12);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const seg = 4;
+    const s1 = await runHashSweep({ source, store, embedder, modelId: 'stub-ngram', dim: 512, segments: seg, rounds: 1 });
+    assertEq(s1.cursorStart, 0, '起始游标 0');
+    assertEq(s1.cursorEnd, 1, '推进一段');
+    assertEq(s1.completedFullSweep, false, '未跑满一轮');
+    assertEq(getMeta(store.db, META_KEYS.lastFullHashSweepAt), null, '未写 lastFullHashSweepAt');
+
+    await runHashSweep({ source, store, embedder, modelId: 'stub-ngram', dim: 512, segments: seg, rounds: 3 });
+    assertEq(Number(getMeta(store.db, META_KEYS.hashSweepCursor)), 0, '游标回到 0');
+    assert(getMeta(store.db, META_KEYS.lastFullHashSweepAt) !== null, '一轮覆盖完成 ⇒ 写了 lastFullHashSweepAt');
+    assert(
+      Number(getMeta(store.db, META_KEYS.lastFullHashSweepAt)) > 0,
+      'lastFullHashSweepAt 是时间戳',
+    );
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('段轮转覆盖全表：所有段累计扫描条数 = 记忆总条数（无漏段）', async () => {
+  const { t, store, source, embedder } = setup(12);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const seg = 5;
+    let scanned = 0;
+    for (let i = 0; i < seg; i += 1) {
+      const s = await runHashSweep({ source, store, embedder, modelId: 'stub-ngram', dim: 512, segments: seg, rounds: 1 });
+      scanned += s.scanned;
+      // 覆盖到的 id 不重复：用段报告核对
+      assert(s.segmentReports.length === 1, '每次一段');
+    }
+    assertEq(scanned, source.count(), '一轮 5 段累计扫描 = 12 条（无重叠无遗漏）');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('缺失向量补齐：库里被删掉的条目，轮转时按 missing 重编码', async () => {
+  const { t, store, source, embedder } = setup(6);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    store.db.prepare('DELETE FROM vectors WHERE source = ? AND ref_id = ?').run('memory', '2');
+    assertEq(countVectors(store.db, 'memory'), 5, '先删掉 1 条');
+
+    const sweep = await runHashSweep({ source, store, embedder, modelId: 'stub-ngram', dim: 512, segments: 2, rounds: 2 });
+    assertEq(sweep.missing, 1, '报告缺失 1 条');
+    assertEq(countVectors(store.db, 'memory'), 6, '补齐回 6 条');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});
+
+test('兜底不改增量水位（两条路径不共用候选集）', async () => {
+  const { t, store, source, embedder } = setup(5);
+  try {
+    await runIncrementalSync({ source, store, embedder, modelId: 'stub-ngram', dim: 512 });
+    const wmBefore = getMeta(store.db, META_KEYS.lastIncrementalSyncAt);
+    await runHashSweep({ source, store, embedder, modelId: 'stub-ngram', dim: 512, segments: 2, rounds: 2 });
+    assertEq(getMeta(store.db, META_KEYS.lastIncrementalSyncAt), wmBefore, '增量水位未被兜底改动');
+  } finally {
+    source.close();
+    store.db.close();
+    t.cleanup();
+  }
+});