@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/memory-engine/lib/layer-migrate.mjs

@@ -0,0 +1,330 @@
+// 加层字段的迁移引擎：探查 → 出计划 → 备份 → 事务内改 → 改完复核。
+//
+// 五条硬约束（每条都在代码里）：
+//   ① **默认 dry-run**：只有显式 apply 才写；调用方没给 backup 就不许写（先备份再动 schema）；
+//   ② **零删行**：本文件的 SQL 里没有 DELETE / DROP；行数在事务内与事务后各核一次；
+//   ③ **幂等**：列已在、空值已清零 ⇒ 一个字节都不写（第二次 apply 的 sha 与前一次相同）；
+//   ④ **跨盘不 rename**：备份一律「写新文件 + sha 校验」；还原走「同目录临时文件 + rename」，
+//      临时文件与目标同盘，因此不会踩 EXDEV；
+//   ⑤ **改完必复核**：行数、id 上界、sqlite_sequence、PRAGMA integrity_check 四项与改前对拍。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { GuardError } from './cli-strict.mjs';
+
+export const MEMORY_TABLE = 'memories';
+const BUSY_TIMEOUT_MS = 8000;
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+/** SQLite 字符串字面量转义：单引号翻倍（路径里可能出现）。 */
+const quoteSql = (text) => `'${String(text).replace(/'/g, "''")}'`;
+
+function openRead(dbPath) {
+  if (!fs.existsSync(dbPath)) throw new Error(`库文件不存在：${dbPath}`);
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+  return db;
+}
+
+/** 只读取数：表清单 / 列清单 / 行数 / 序列 / 完整性。 */
+export function inspectDatabase(dbPath) {
+  const abs = path.resolve(dbPath);
+  const out = {
+    dbPath: abs,
+    exists: fs.existsSync(abs),
+    bytes: 0,
+    sha256: null,
+    tables: [],
+    hasMemoryTable: false,
+    columns: [],
+    rowCount: null,
+    seq: null,
+    integrity: null,
+    error: null,
+  };
+  if (!out.exists) {
+    out.error = `库文件不存在：${abs}`;
+    return out;
+  }
+  out.bytes = fs.statSync(abs).size;
+  out.sha256 = sha256(fs.readFileSync(abs));
+
+  let db = null;
+  try {
+    db = openRead(abs);
+    out.tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type IN ('table','view') ORDER BY name")
+      .all()
+      .map((r) => String(r.name));
+    out.hasMemoryTable = out.tables.includes(MEMORY_TABLE);
+    if (out.hasMemoryTable) {
+      out.columns = db.prepare(`PRAGMA table_info(${MEMORY_TABLE})`).all().map((r) => ({
+        name: String(r.name),
+        type: String(r.type ?? ''),
+        notnull: Number(r.notnull ?? 0),
+        dflt: r.dflt_value === null ? null : String(r.dflt_value),
+      }));
+      out.rowCount = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${MEMORY_TABLE}`).get().n);
+      try {
+        const s = db.prepare("SELECT seq FROM sqlite_sequence WHERE name = ?").get(MEMORY_TABLE);
+        out.seq = s ? Number(s.seq) : null;
+      } catch {
+        out.seq = null; // 没有 AUTOINCREMENT 就不会有 sqlite_sequence，不算错
+      }
+    }
+    try {
+      const r = db.prepare('PRAGMA integrity_check').get();
+      out.integrity = r ? String(r.integrity_check ?? Object.values(r)[0]) : null;
+    } catch (e) {
+      out.integrity = `读不动：${e && e.message}`;
+    }
+  } catch (e) {
+    out.error = `打不开（只读）：${e && e.message}`;
+  } finally {
+    try {
+      if (db) db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  return out;
+}
+
+function countEmptyLayer(db, cfg) {
+  const col = cfg.column;
+  try {
+    const r = db.prepare(`SELECT COUNT(*) AS n FROM ${MEMORY_TABLE} WHERE ${col} IS NULL OR TRIM(${col}) = ''`).get();
+    return Number(r.n);
+  } catch {
+    return null;
+  }
+}
+
+function layerHistogram(db, cfg) {
+  const col = cfg.column;
+  const rows = db.prepare(`SELECT ${col} AS v, COUNT(*) AS n FROM ${MEMORY_TABLE} GROUP BY ${col} ORDER BY n DESC`).all();
+  const known = new Set(cfg.layers.map((n) => n.toLowerCase()));
+  const hist = {};
+  const outOfSet = {};
+  for (const row of rows) {
+    const key = row.v === null || String(row.v).trim() === '' ? '(空)' : String(row.v);
+    hist[key] = Number(row.n);
+    if (key !== '(空)' && !known.has(key.toLowerCase())) outOfSet[key] = Number(row.n);
+  }
+  return { hist, outOfSet };
+}
+
+/** 出计划：只读，绝不写。 */
+export function buildPlan(dbPath, cfg) {
+  const info = inspectDatabase(dbPath);
+  const plan = {
+    dbPath: info.dbPath,
+    column: cfg.column,
+    defaultLayer: cfg.defaultLayer,
+    layerNames: cfg.layers,
+    info,
+    blockers: [],
+    hasColumn: false,
+    needsAlter: false,
+    needsBackfill: false,
+    rowCount: info.rowCount,
+    emptyLayerRows: null,
+    histogram: {},
+    outOfSet: {},
+    seq: info.seq,
+    integrity: info.integrity,
+  };
+  if (!info.exists) plan.blockers.push(info.error);
+  else if (info.error) plan.blockers.push(info.error);
+  else if (!info.hasMemoryTable) plan.blockers.push(`库里没有 ${MEMORY_TABLE} 表 —— 这不是一本记忆库`);
+  if (info.integrity && info.integrity !== 'ok') plan.blockers.push(`PRAGMA integrity_check 不是 ok：${info.integrity}`);
+
+  if (plan.blockers.length) return plan;
+
+  plan.hasColumn = info.columns.some((c) => c.name.toLowerCase() === cfg.column.toLowerCase());
+  let db = null;
+  try {
+    db = openRead(info.dbPath);
+    if (plan.hasColumn) {
+      plan.emptyLayerRows = countEmptyLayer(db, cfg);
+      const { hist, outOfSet } = layerHistogram(db, cfg);
+      plan.histogram = hist;
+      plan.outOfSet = outOfSet;
+      plan.needsBackfill = Number(plan.emptyLayerRows) > 0;
+    } else {
+      plan.needsAlter = true;
+      // 列还没有 ⇒ 加列即回填，条数就是全表
+      plan.emptyLayerRows = plan.rowCount;
+      plan.needsBackfill = plan.rowCount > 0;
+    }
+  } catch (e) {
+    plan.blockers.push(`取数失败：${e && e.message}`);
+  } finally {
+    try {
+      if (db) db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  return plan;
+}
+
+/**
+ * 做备份：默认**逐字节复制**（无 WAL 时最直白，还原后与原件逐字节相同）；
+ * 库旁有非空 `-wal` 时改用 `VACUUM INTO`（单文件、含 WAL 内容，避免半截复制）。
+ * 两种办法都在写完之后**打开副本核对**：行数 / 序列 / 完整性。
+ */
+export function createBackup({ dbPath, backupPath }) {
+  const src = path.resolve(dbPath);
+  const dst = path.resolve(backupPath);
+  if (src.toLowerCase() === dst.toLowerCase()) throw new Error('备份路径不能是库本身');
+  if (fs.existsSync(dst)) throw new GuardError(`备份文件已存在，不覆盖：${dst}（换个带时间戳的名字，或先挪走）`);
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+
+  const before = inspectDatabase(src);
+  if (!before.exists || before.error) throw new Error(`源库读不了，拒绝备份：${before.error ?? src}`);
+
+  const wal = `${src}-wal`;
+  const hasLiveWal = fs.existsSync(wal) && fs.statSync(wal).size > 0;
+  let method = hasLiveWal ? 'vacuum-into' : 'file-copy';
+
+  if (hasLiveWal) {
+    let db = null;
+    try {
+      db = openRead(src);
+      db.exec(`VACUUM INTO ${quoteSql(dst)}`);
+    } catch (e) {
+      throw new Error(`备份失败（VACUUM INTO 不行，而源库带活的 WAL 又不能直接复制）：${e && e.message}`);
+    } finally {
+      try {
+        if (db) db.close();
+      } catch {
+        /* ignore */
+      }
+    }
+  } else {
+    method = 'file-copy';
+    fs.copyFileSync(src, dst);
+  }
+
+  const after = inspectDatabase(dst);
+  if (!after.exists || after.error) throw new Error(`备份文件打不开：${after.error}`);
+  if (after.rowCount !== before.rowCount) {
+    throw new Error(`备份行数不符（源 ${before.rowCount} / 备份 ${after.rowCount}）—— 库可能正在被写，重跑一次`);
+  }
+  if (after.integrity !== 'ok') throw new Error(`备份完整性检查不是 ok：${after.integrity}`);
+  return {
+    method,
+    path: dst,
+    bytes: after.bytes,
+    sha256: after.sha256,
+    rows: after.rowCount,
+    seq: after.seq,
+    integrity: after.integrity,
+    byteIdentical: after.sha256 === before.sha256,
+    source: { path: src, bytes: before.bytes, sha256: before.sha256, rows: before.rowCount, seq: before.seq },
+  };
+}
+
+/** 事务内把计划做完，然后复核四项。 */
+export function applyMigration({ dbPath, cfg, backupPath }) {
+  const plan = buildPlan(dbPath, cfg);
+  if (plan.blockers.length) throw new Error(`计划有阻断项，不动库：${plan.blockers.join('；')}`);
+  if (!plan.needsAlter && !plan.needsBackfill) {
+    return { changed: false, plan, backup: null, verify: { rowCountSame: true, seqSame: true, integrity: plan.integrity } };
+  }
+  if (!backupPath) throw new Error('动 schema 前必须先备份：用 --backup <path> 指定一份（拒绝无备份写入）');
+
+  const backup = createBackup({ dbPath, backupPath });
+  const abs = path.resolve(dbPath);
+  const db = new DatabaseSync(abs);
+  db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+  let touched = 0;
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    if (plan.needsAlter) {
+      db.exec(`ALTER TABLE ${MEMORY_TABLE} ADD COLUMN ${cfg.column} TEXT NOT NULL DEFAULT ${quoteSql(cfg.defaultLayer)}`);
+    }
+    if (plan.needsBackfill) {
+      const stmt = db.prepare(
+        `UPDATE ${MEMORY_TABLE} SET ${cfg.column} = ? WHERE ${cfg.column} IS NULL OR TRIM(${cfg.column}) = ''`,
+      );
+      const res = stmt.run(cfg.defaultLayer);
+      touched = Number(res.changes ?? 0);
+    }
+    // 加列时既有行由列默认值直接填好（0 次 UPDATE）—— 记账按"被填了多少行"算，别报 0
+    if (plan.needsAlter) touched += Number(plan.rowCount ?? 0);
+    db.exec('COMMIT');
+  } catch (e) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      /* ignore */
+    }
+    db.close();
+    throw new Error(`迁移事务回滚（库未改）：${e && e.message}；备份仍在 ${backup.path}`);
+  }
+  db.close();
+
+  const after = buildPlan(dbPath, cfg);
+  const verify = {
+    rowCountSame: after.rowCount === plan.rowCount,
+    seqSame: after.seq === plan.seq,
+    integrity: after.integrity,
+    emptyAfter: after.emptyLayerRows,
+    histogram: after.histogram,
+  };
+  if (!verify.rowCountSame) throw new Error(`行数变了（${plan.rowCount} → ${after.rowCount}）—— 立刻用备份还原：${backup.path}`);
+  if (!verify.seqSame) throw new Error(`sqlite_sequence 变了（${plan.seq} → ${after.seq}）—— 立刻用备份还原：${backup.path}`);
+  if (Number(verify.emptyAfter) !== 0) throw new Error(`回填后仍有 ${verify.emptyAfter} 行空层 —— 立刻用备份还原：${backup.path}`);
+  if (verify.integrity !== 'ok') throw new Error(`迁移后完整性不是 ok：${verify.integrity} —— 用备份还原：${backup.path}`);
+
+  return { changed: true, plan, backup, touched, verify, after };
+}
+
+/** 还原：从备份写回库文件。默认 dry-run；真写走「同目录临时文件 + sha 校验 + rename」。 */
+export function restoreDatabase({ backupPath, dbPath, apply = false }) {
+  const backup = inspectDatabase(backupPath);
+  if (!backup.exists) throw new Error(`备份不存在：${path.resolve(backupPath)}`);
+  if (backup.error) throw new Error(`备份打不开：${backup.error}`);
+  if (!backup.hasMemoryTable) throw new Error(`备份里没有 ${MEMORY_TABLE} 表 —— 不是一本记忆库的备份`);
+  if (backup.integrity !== 'ok') throw new Error(`备份完整性不是 ok：${backup.integrity}`);
+
+  const target = inspectDatabase(dbPath);
+  const plan = {
+    backup: { path: backup.dbPath, bytes: backup.bytes, sha256: backup.sha256, rows: backup.rowCount, seq: backup.seq },
+    target: target.exists
+      ? { path: target.dbPath, bytes: target.bytes, sha256: target.sha256, rows: target.rowCount, seq: target.seq }
+      : { path: path.resolve(dbPath), bytes: null, sha256: null, rows: null, seq: null, missing: true },
+    sidecars: ['-wal', '-shm'].filter((s) => fs.existsSync(path.resolve(dbPath) + s)),
+    applied: false,
+    verify: null,
+  };
+  if (!apply) return plan;
+
+  const abs = path.resolve(dbPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  // 陈旧 WAL 与新库文件配在一起 = 直接损坏库，必须先摘掉（这是备份还原的一部分，不是删数据）
+  for (const suffix of ['-wal', '-shm']) {
+    const side = abs + suffix;
+    if (fs.existsSync(side)) fs.rmSync(side, { force: true });
+  }
+  const tmp = `${abs}.restore-${process.pid}-${Date.now()}.tmp`;
+  fs.copyFileSync(backup.dbPath, tmp);
+  const tmpSha = sha256(fs.readFileSync(tmp));
+  if (tmpSha !== backup.sha256) {
+    fs.rmSync(tmp, { force: true });
+    throw new Error(`临时副本 sha 与备份不符（${tmpSha.slice(0, 12)} ≠ ${backup.sha256.slice(0, 12)}）—— 未替换`);
+  }
+  fs.renameSync(tmp, abs); // 同目录 rename：不跨盘，不会 EXDEV
+
+  const after = inspectDatabase(abs);
+  if (!after.exists || after.error || after.sha256 !== backup.sha256) {
+    throw new Error(`还原后核对失败（${after.error ?? `sha ${String(after.sha256).slice(0, 12)}`}）—— 库文件已替换，请人工确认`);
+  }
+  plan.applied = true;
+  plan.verify = { sha256: after.sha256, rows: after.rowCount, seq: after.seq, integrity: after.integrity };
+  return plan;
+}

package/memory-engine/lib/layer-move.mjs

@@ -0,0 +1,307 @@
+// 软淘汰执行器：把一整层「搬走」而不是删掉 —— 搬到本库内的一张边表（memories_evicted），一条命令出去、一条命令回来。
+//
+// 为什么选「另一张表」而不是「另一个库文件」（代价写在这里，README 同款）：
+//   · 好处：同一个事务里搬进搬出，守恒可以当场断言；不会留下一个可能被误删的旁路库文件；
+//     FTS5 触发器仍然在 主表 上，搬出即从索引删除、搬回即重建，索引不会漂。
+//   · 代价：搬走的行**仍然占这个库文件的体积**（软淘汰省的是上下文与召回面，不是磁盘）；
+//     边表没有 FTS 索引 ⇒ 搬走的行在引擎召回里不可见，只能用 SQL 或 `--back` 取回。
+//
+// 四条硬判据：
+//   ① 守恒：搬出层行数 + 剩下行数 == 搬前总行数（事务内断言，不成立就整批回滚）；
+//   ② 逐行可比：每行落边表时记 content_sha（与 lib/layers.mjs 的行指纹同算法），搬回时先核后写；
+//   ③ 默认 dry-run：不带 apply 一个字节都不写；
+//   ④ 不许把主表搬空：会搬走全部行时要显式 `--force`（防"层名写错"把库清空）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { rowDigest, canonicalLayerName } from './layers.mjs';
+import { GuardError } from './cli-strict.mjs';
+
+export const MEMORY_TABLE = 'memories';
+export const EVICTED_TABLE = 'memories_evicted';
+const BUSY_TIMEOUT_MS = 8000;
+
+const sha256 = (text) => crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+
+/** 边表：列与主表一一对应 + 三个记账列（层 / 指纹 / 批次）。 */
+export const EVICTED_DDL = `
+CREATE TABLE IF NOT EXISTS ${EVICTED_TABLE} (
+  id INTEGER PRIMARY KEY,
+  text TEXT NOT NULL,
+  tags TEXT NOT NULL DEFAULT '',
+  pinned INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  layer TEXT NOT NULL,
+  content_sha TEXT NOT NULL,
+  batch TEXT NOT NULL,
+  moved_at INTEGER NOT NULL
+)`;
+
+const MEMORY_COLUMNS = 'id, text, tags, pinned, created_at, updated_at';
+
+function open(dbPath, { readOnly = false } = {}) {
+  const abs = path.resolve(dbPath);
+  if (!fs.existsSync(abs)) throw new Error(`库文件不存在：${abs}`);
+  const db = new DatabaseSync(abs, readOnly ? { readOnly: true } : {});
+  db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+  return db;
+}
+
+function tableExists(db, name) {
+  return Boolean(db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?").get(name));
+}
+
+function columnExists(db, table, column) {
+  return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => String(c.name).toLowerCase() === column.toLowerCase());
+}
+
+const countAll = (db) => Number(db.prepare(`SELECT COUNT(*) AS n FROM ${MEMORY_TABLE}`).get().n);
+const countLayerInMain = (db, cfg, layer) =>
+  Number(
+    db.prepare(`SELECT COUNT(*) AS n FROM ${MEMORY_TABLE} WHERE LOWER(${cfg.column}) = LOWER(?)`).get(String(layer)).n,
+  );
+
+function countEvicted(db, layer) {
+  if (!tableExists(db, EVICTED_TABLE)) return 0;
+  return Number(db.prepare(`SELECT COUNT(*) AS n FROM ${EVICTED_TABLE} WHERE LOWER(layer) = LOWER(?)`).get(String(layer)).n);
+}
+
+function seqOf(db) {
+  try {
+    const r = db.prepare('SELECT seq FROM sqlite_sequence WHERE name = ?').get(MEMORY_TABLE);
+    return r ? Number(r.seq) : null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureEvictedTable(db) {
+  db.exec(EVICTED_DDL);
+}
+
+/** 只说出计划：会不会搬、搬几行、有没有阻断项。 */
+export function planMove({ dbPath, cfg, layer }) {
+  const db = open(dbPath, { readOnly: true });
+  try {
+    const plan = {
+      dbPath: path.resolve(dbPath),
+      layer,
+      totalRows: countAll(db),
+      hasColumn: columnExists(db, MEMORY_TABLE, cfg.column),
+      hasEvictedTable: tableExists(db, EVICTED_TABLE),
+      layerRows: 0,
+      evictedRows: 0,
+      seq: seqOf(db),
+      blockers: [],
+    };
+    if (!plan.hasColumn) {
+      plan.blockers.push(`主表没有 ${cfg.column} 列 —— 先跑 layer-migrate --apply 把列加上`);
+      return plan;
+    }
+    plan.layerRows = countLayerInMain(db, cfg, layer);
+    plan.evictedRows = countEvicted(db, layer);
+    plan.leavesEmpty = plan.layerRows > 0 && plan.layerRows === plan.totalRows;
+    return plan;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * 搬出：主表 → 边表。事务内断言守恒；任何一步不符就整批回滚。
+ * @returns {{moved:number,totalBefore:number,remaining:number,evicted:number,batch:string,digests:number}}
+ */
+export function moveOut({ dbPath, cfg, layer, batch, force = false }) {
+  const name = canonicalLayerName(cfg, layer);
+  if (!name) throw new Error(`「${layer}」不在层名集合 [${cfg.layers.join(', ')}] 里`);
+  const plan = planMove({ dbPath, cfg, layer: name });
+  if (plan.blockers.length) throw new Error(plan.blockers.join('；'));
+  if (plan.layerRows === 0) {
+    return { moved: 0, totalBefore: plan.totalRows, remaining: plan.totalRows, evicted: plan.evictedRows, batch, digests: 0 };
+  }
+  if (plan.leavesEmpty && !force) {
+    throw new GuardError(
+      `搬走「${name}」会把主表搬空（${plan.layerRows}/${plan.totalRows} 行）—— 这通常是层名填错。确实要搬请加 --force`,
+    );
+  }
+
+  const db = open(dbPath);
+  const before = { rows: countAll(db), seq: seqOf(db) };
+  let movedRows = 0;
+  try {
+    ensureEvictedTable(db);
+    const rows = db
+      .prepare(`SELECT ${MEMORY_COLUMNS}, ${cfg.column} AS layer_value FROM ${MEMORY_TABLE} WHERE LOWER(${cfg.column}) = LOWER(?) ORDER BY id`)
+      .all(name);
+    db.exec('BEGIN IMMEDIATE');
+    const insert = db.prepare(
+      `INSERT INTO ${EVICTED_TABLE} (id, text, tags, pinned, created_at, updated_at, layer, content_sha, batch, moved_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const remove = db.prepare(`DELETE FROM ${MEMORY_TABLE} WHERE id = ? AND LOWER(${cfg.column}) = LOWER(?)`);
+    const clash = db.prepare(`SELECT id FROM ${EVICTED_TABLE} WHERE id = ?`);
+    const now = Date.now();
+    for (const row of rows) {
+      const layerValue = String(row.layer_value ?? name);
+      const digest = rowDigest({ ...row, [cfg.column]: layerValue }, cfg);
+      if (clash.get(Number(row.id))) {
+        throw new GuardError(`id ${row.id} 已经在边表里（上次搬出没搬回）—— 先 layer-move --back，别覆盖`);
+      }
+      insert.run(
+        Number(row.id), String(row.text ?? ''), String(row.tags ?? ''), Number(row.pinned ?? 0),
+        Number(row.created_at ?? 0), Number(row.updated_at ?? 0), layerValue, digest, batch, now,
+      );
+      const res = remove.run(Number(row.id), name);
+      if (Number(res.changes ?? 0) !== 1) throw new Error(`删除主表 id ${row.id} 失败（影响 ${res.changes} 行）`);
+      movedRows += 1;
+    }
+    const remaining = countAll(db);
+    const evicted = countEvicted(db, name);
+    if (evicted + remaining !== before.rows) {
+      throw new Error(`守恒不成立：搬出 ${evicted} + 剩下 ${remaining} ≠ 搬前 ${before.rows}`);
+    }
+    db.exec('COMMIT');
+    return { moved: movedRows, totalBefore: before.rows, remaining, evicted, batch, digests: movedRows, seqBefore: before.seq, seqAfter: seqOf(db) };
+  } catch (e) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      /* ignore */
+    }
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * 搬回：边表 → 主表。先逐行核指纹（不符整批拒动），再插回并删边表。
+ */
+export function moveBack({ dbPath, cfg, layer }) {
+  const name = canonicalLayerName(cfg, layer);
+  if (!name) throw new Error(`「${layer}」不在层名集合 [${cfg.layers.join(', ')}] 里`);
+  const db = open(dbPath);
+  const before = { rows: countAll(db), seq: seqOf(db) };
+  try {
+    if (!tableExists(db, EVICTED_TABLE)) {
+      return { restored: 0, totalBefore: before.rows, totalAfter: before.rows, mismatched: [], reason: '边表不存在（没搬出过）' };
+    }
+    ensureEvictedTable(db);
+    const rows = db.prepare(`SELECT * FROM ${EVICTED_TABLE} WHERE LOWER(layer) = LOWER(?) ORDER BY id`).all(name);
+    if (rows.length === 0) {
+      return { restored: 0, totalBefore: before.rows, totalAfter: before.rows, mismatched: [], reason: `边表里没有「${name}」的行` };
+    }
+
+    // 先验后写：任一指纹不符 / 主表已存在同 id ⇒ 整批不动
+    const mismatched = [];
+    const collisions = [];
+    for (const row of rows) {
+      const digest = rowDigest({ ...row, [cfg.column]: String(row.layer ?? name) }, cfg);
+      if (digest !== String(row.content_sha)) mismatched.push({ id: Number(row.id), stored: String(row.content_sha), now: digest });
+      const hit = db.prepare(`SELECT id FROM ${MEMORY_TABLE} WHERE id = ?`).get(Number(row.id));
+      if (hit) collisions.push(Number(row.id));
+    }
+    if (mismatched.length) {
+      const ids = mismatched.slice(0, 5).map((m) => m.id).join(', ');
+      throw new GuardError(`边表里有 ${mismatched.length} 行内容被改过（指纹不符，例：${ids}）—— 整批拒动`);
+    }
+    if (collisions.length) {
+      throw new GuardError(`主表里已存在同 id 的行（例：${collisions.slice(0, 5).join(', ')}）—— 整批拒动，先查清哪一份该留`);
+    }
+
+    db.exec('BEGIN IMMEDIATE');
+    const insert = db.prepare(
+      `INSERT INTO ${MEMORY_TABLE} (id, text, tags, pinned, created_at, updated_at, ${cfg.column})
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const remove = db.prepare(`DELETE FROM ${EVICTED_TABLE} WHERE id = ? AND LOWER(layer) = LOWER(?)`);
+    let restored = 0;
+    for (const row of rows) {
+      insert.run(
+        Number(row.id), String(row.text ?? ''), String(row.tags ?? ''), Number(row.pinned ?? 0),
+        Number(row.created_at ?? 0), Number(row.updated_at ?? 0), String(row.layer ?? name),
+      );
+      const res = remove.run(Number(row.id), name);
+      if (Number(res.changes ?? 0) !== 1) throw new Error(`从边表删 id ${row.id} 失败（影响 ${res.changes} 行）`);
+      restored += 1;
+    }
+    const after = countAll(db);
+    if (after !== before.rows + restored) {
+      throw new Error(`守恒不成立：搬前 ${before.rows} + 搬回 ${restored} ≠ 搬后 ${after}`);
+    }
+    db.exec('COMMIT');
+    return { restored, totalBefore: before.rows, totalAfter: after, mismatched: [], seqBefore: before.seq, seqAfter: seqOf(db) };
+  } catch (e) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      /* ignore */
+    }
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+/** 导出主表（或某一层）的逐行指纹，当作「搬前长什么样」的凭据。 */
+export function dumpDigests({ dbPath, cfg, layer = null }) {
+  const db = open(dbPath, { readOnly: true });
+  try {
+    if (!columnExists(db, MEMORY_TABLE, cfg.column)) throw new Error(`主表没有 ${cfg.column} 列 —— 先跑 layer-migrate`);
+    const rows = layer
+      ? db
+          .prepare(`SELECT ${MEMORY_COLUMNS}, ${cfg.column} AS layer_value FROM ${MEMORY_TABLE} WHERE LOWER(${cfg.column}) = LOWER(?) ORDER BY id`)
+          .all(String(layer))
+      : db.prepare(`SELECT ${MEMORY_COLUMNS}, ${cfg.column} AS layer_value FROM ${MEMORY_TABLE} ORDER BY id`).all();
+    const items = rows.map((row) => ({
+      id: Number(row.id),
+      digest: rowDigest({ ...row, [cfg.column]: String(row.layer_value ?? '') }, cfg),
+    }));
+    return { at: new Date().toISOString(), dbPath: path.resolve(dbPath), layer, count: items.length, rows: items };
+  } finally {
+    db.close();
+  }
+}
+
+/** 拿导出件对拍当前主表：缺行 / 多行 / 内容变了 三类分开报。 */
+export function verifyAgainstDump({ dbPath, cfg, dump }) {
+  const now = dumpDigests({ dbPath, cfg, layer: dump.layer ?? null });
+  const before = new Map((dump.rows ?? []).map((r) => [Number(r.id), String(r.digest)]));
+  const after = new Map(now.rows.map((r) => [Number(r.id), String(r.digest)]));
+  const missing = [];
+  const extra = [];
+  const changed = [];
+  for (const [id, digest] of before) {
+    if (!after.has(id)) missing.push(id);
+    else if (after.get(id) !== digest) changed.push(id);
+  }
+  for (const id of after.keys()) if (!before.has(id)) extra.push(id);
+  const byId = (a, b) => a - b;
+  return {
+    ok: missing.length === 0 && extra.length === 0 && changed.length === 0,
+    checked: before.size,
+    currentCount: after.size,
+    missing: missing.sort(byId),
+    extra: extra.sort(byId),
+    changed: changed.sort(byId),
+  };
+}
+
+/** 写导出件（JSON 只落文件）。 */
+export function writeDump(file, dump) {
+  const abs = path.resolve(file);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(dump, null, 2)}\n`, 'utf8');
+  return abs;
+}
+
+export function readDump(file) {
+  const abs = path.resolve(file);
+  if (!fs.existsSync(abs)) throw new Error(`指纹导出件不在：${abs}`);
+  return JSON.parse(fs.readFileSync(abs, 'utf8'));
+}
+
+export { sha256 as sha256OfText };