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

package/memory-db-tools/memory-schema-migrate.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// tools/memory-db-tools/memory-schema-migrate.mjs
+//
+// ⑤ 包 §3.3 / P2 §3.8「两列」迁移 CLI（施工卡 ⑤-3 交付）。
+//
+// 做什么：给 `memories` 表补 `owner_user` + `visibility` 两列（+ visibility 索引）。
+// 怎么保证安全：
+//   · 默认 **dry-run**（只读规划，零写入）；
+//   · `--apply` 打到**生产库**必须显式 `--allow-production`，否则拒绝（exit 2）；
+//   · 打生产还必须过**停机窗口判据**（3080 无监听 + 无非空 -wal 残留），否则拒绝（fail-closed）；
+//   · 打生产必须显式给 `--snapshot <dir>`（先 VACUUM INTO 快照 + 落 snapshot.json），否则拒绝；
+//   · 幂等：列已存在就跳过（靠 `PRAGMA table_info`，不用 `CREATE TABLE IF NOT EXISTS` —— §3.8 明文）。
+//
+// 用法：
+//   node memory-schema-migrate.mjs                                   # dry-run（默认生产路径，只读）
+//   node memory-schema-migrate.mjs --db <path>                        # dry-run 指定库（沙箱）
+//   node memory-schema-migrate.mjs --db <path> --apply                # 真改（非生产路径无需额外开关）
+//   node memory-schema-migrate.mjs --allow-production --apply --snapshot <dir>   # 生产（需停机窗口）
+//   node memory-schema-migrate.mjs --db <path> --json                 # 机器可读（stdout 只有 JSON）
+//
+// `--home <dir>` = DSH home（即 `.dsh` 目录），默认 `~/.dsh`；库 = `<home>/memory/memory.db`。
+// `--users <file>` 显式指定身份表（缺省 `<home>/secretary-users.json`）。
+// 退出码：0 = 就绪 / 已迁移（幂等）；1 = 有异常（被拒或复核未过）；2 = 用法错；3 = 环境不可用。
+
+import fs from "node:fs";
+import path from "node:path";
+import net from "node:net";
+import { DatabaseSync } from "node:sqlite";
+import {
+  MEMORIES_TABLE,
+  NEW_COLUMNS,
+  applyMigration,
+  describeDb,
+  isProductionDb,
+  migrationPlan,
+  productionDbPath,
+  readIdentityTable,
+  resolveDefaultOwner,
+  sha256File,
+} from "./lib/memory-scope.mjs";
+
+const argv = process.argv.slice(2);
+function argRaw(name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) {
+    const v = argv[i + 1];
+    return v && !v.startsWith("--") ? v : true;
+  }
+  const kv = argv.find((a) => a.startsWith(`${name}=`));
+  return kv ? kv.slice(name.length + 1) : null;
+}
+const argOf = (name, def = null) => {
+  const v = argRaw(name);
+  return v === null ? def : v;
+};
+const flag = (name) => argv.includes(name);
+const JSON_OUT = flag("--json");
+const log = (...a) => {
+  if (!JSON_OUT) console.log(...a);
+};
+
+if (flag("--help") || flag("-h")) {
+  console.log("用法见本文件头部注释；关键开关：--db --home --users --apply --allow-production --snapshot <dir> --json");
+  process.exitCode = 0;
+} else {
+  main().catch((e) => {
+    if (JSON_OUT) console.log(JSON.stringify({ ok: false, exitCode: 1, message: `未捕获异常：${e && e.stack ? e.stack : e}` }, null, 2));
+    else console.error(`未捕获异常：${e && e.stack ? e.stack : e}`);
+    process.exitCode = 1;
+  });
+}
+
+async function main() {
+  const homeOpt = argOf("--home", null); // = .dsh 目录
+  const dbOpt = argRaw("--db");
+  const usersOpt = argRaw("--users");
+  const apply = flag("--apply");
+  const allowProd = flag("--allow-production");
+  const snapshotDir = argRaw("--snapshot");
+
+  const result = {
+    at: new Date().toISOString(),
+    mode: apply ? "apply" : "dry-run",
+    ok: false,
+    exitCode: 0,
+    steps: [],
+    warnings: [],
+  };
+  if (homeOpt === true || dbOpt === true || usersOpt === true || snapshotDir === true) {
+    return finish(result, 2, "参数错：--home / --db / --users / --snapshot 都需要一个值");
+  }
+
+  const dshDir = homeOpt ? path.resolve(String(homeOpt)) : path.dirname(path.dirname(productionDbPath()));
+  const dbPath = dbOpt ? path.resolve(String(dbOpt)) : path.join(dshDir, "memory", "memory.db");
+  const usersFile = usersOpt ? path.resolve(String(usersOpt)) : path.join(dshDir, "secretary-users.json");
+  const isProd = isProductionDb(dbPath);
+  result.db = dbPath;
+  result.isProduction = isProd;
+
+  if (!fs.existsSync(dbPath)) return finish(result, 3, `环境不可用：库不存在 ${dbPath}`);
+
+  // ---- 身份表（§3.3-3：默认值取自身份表；取不到回落常量并在自检里报一行）
+  const identity = readIdentityTable(usersFile);
+  const resolved = resolveDefaultOwner(identity);
+  result.identity = { path: identity.path, exists: identity.exists, ok: identity.ok, owner: identity.owner, userids: identity.userids, error: identity.error };
+  result.ownerDefault = { user: resolved.ownerUser, source: resolved.source };
+  for (const n of resolved.notes) result.warnings.push(n);
+  if (identity.ok) log(`✓ 身份表：${identity.userids.length} 个 userid · owner = ${resolved.ownerUser}（${identity.path}）`);
+  else log(`⚠️ 身份表不可用（${identity.exists ? identity.error : "不存在"}：${identity.path}）→ owner_user 默认值回落 '${resolved.ownerUser}'`);
+
+  // ---- 只读规划
+  const ro = new DatabaseSync(dbPath, { readOnly: true });
+  let plan;
+  let before;
+  try {
+    before = describeDb(ro);
+    plan = migrationPlan(ro, { identity });
+  } finally {
+    ro.close();
+  }
+  result.before = { columns: before.columns, count: before.count, visibilityIndex: before.visibilityIndex };
+  result.plan = { missing: plan.missing, present: plan.present, statements: plan.statements };
+
+  log(`库：${dbPath}${isProd ? "（**生产库**）" : "（沙箱/副本）"}`);
+  log(`现状：${before.columns.length} 列 · ${before.count} 条 · visibility 索引 ${before.visibilityIndex ? "在" : "缺"}`);
+  log(`待办：缺列 [${plan.missing.join(", ") || "无"}] · 已有 [${plan.present.join(", ") || "无"}] · 语句 ${plan.statements.length} 条`);
+  for (const s of plan.statements) log(`  · ${s}`);
+
+  if (plan.statements.length === 0) {
+    result.ok = true;
+    result.steps.push("幂等：两列与索引均已在位，无需任何写入");
+    return finish(result, 0, "已是目标结构（幂等）");
+  }
+  if (!apply) {
+    result.ok = true;
+    result.steps.push("dry-run：未写入任何内容（源库只读打开）");
+    return finish(result, 0, "计划已列出（dry-run）");
+  }
+
+  // ---- 真改前的闸门
+  if (isProd && !allowProd) {
+    return finish(result, 2, "拒绝：目标是生产库，必须显式 --allow-production（未获停机窗口时不许跑）");
+  }
+  if (isProd) {
+    if (typeof snapshotDir !== "string") {
+      return finish(result, 2, "拒绝：打生产必须先给 --snapshot <dir>（VACUUM INTO 快照落回滚点）");
+    }
+    const win = await checkStopWindow([3080]);
+    result.stopWindow = win;
+    if (!win.ok) return finish(result, 1, `拒绝：停机窗口判据未过（${win.reasons.join("；")}）—— 请先停 DSH 再跑`);
+    log(`✓ 停机窗口：3080 未监听 · -wal ${win.walBytes} 字节`);
+  }
+
+  // ---- 快照（先 VACUUM INTO，再动手）
+  if (typeof snapshotDir === "string") {
+    const snapDir = path.resolve(snapshotDir);
+    const snapPath = path.join(snapDir, "memory.db");
+    fs.mkdirSync(snapDir, { recursive: true });
+    if (fs.existsSync(snapPath)) fs.rmSync(snapPath);
+    const src = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+      src.exec(`VACUUM INTO '${snapPath.replace(/\\/g, "/")}'`);
+    } finally {
+      src.close();
+    }
+    const snapDb = new DatabaseSync(snapPath, { readOnly: true });
+    let snapInfo;
+    try {
+      snapInfo = describeDb(snapDb);
+    } finally {
+      snapDb.close();
+    }
+    const meta = {
+      at: new Date().toISOString(),
+      source: dbPath,
+      sourceSha256: sha256File(dbPath),
+      sourceCount: before.count,
+      snapshot: snapPath,
+      snapshotSha256: sha256File(snapPath),
+      snapshotCount: snapInfo.count,
+      snapshotColumns: snapInfo.columns,
+      restoresTo: `${before.columns.length} 列（改前结构）`,
+    };
+    fs.writeFileSync(path.join(snapDir, "snapshot.json"), JSON.stringify(meta, null, 2), "utf8");
+    result.snapshot = meta;
+    if (snapInfo.count !== before.count) return finish(result, 1, `拒绝：快照条数 ${snapInfo.count} ≠ 源库 ${before.count}（快照不可信）`);
+    log(`✓ 快照：${snapPath} · ${snapInfo.count} 条 · sha ${String(meta.snapshotSha256).slice(0, 16)}`);
+    result.steps.push("VACUUM INTO 快照已落（含 snapshot.json）");
+  } else {
+    result.warnings.push("未给 --snapshot：本次未留 VACUUM INTO 快照（沙箱演练可接受，生产不允许）");
+  }
+
+  // ---- 执行迁移
+  const rw = new DatabaseSync(dbPath);
+  try {
+    const ran = applyMigration(rw, plan);
+    result.statementsRan = ran;
+    result.steps.push(`已执行 ${ran.length} 条 DDL（事务内）`);
+  } catch (e) {
+    try {
+      rw.close();
+    } catch {
+      /* ignore */
+    }
+    return finish(result, 1, `迁移失败：${e.message}`);
+  }
+  try {
+    rw.close();
+  } catch {
+    /* ignore */
+  }
+
+  // ---- 复核
+  const chk = new DatabaseSync(dbPath, { readOnly: true });
+  let after;
+  let dist;
+  try {
+    after = describeDb(chk);
+    dist = chk
+      .prepare(`SELECT owner_user AS owner, visibility AS vis, COUNT(*) AS c FROM ${MEMORIES_TABLE} GROUP BY 1, 2 ORDER BY 1, 2`)
+      .all();
+  } finally {
+    chk.close();
+  }
+  result.after = { columns: after.columns, count: after.count, visibilityIndex: after.visibilityIndex, distribution: dist };
+  const missingAfter = NEW_COLUMNS.filter((c) => !after.columns.includes(c.name)).map((c) => c.name);
+  const countOk = after.count === before.count;
+  log(`复核：${after.columns.length} 列 · ${after.count} 条 · 索引 ${after.visibilityIndex ? "在" : "缺"}`);
+  for (const d of dist) log(`  · ${d.owner} / ${d.vis} = ${d.c} 条`);
+  if (missingAfter.length || !countOk || !after.visibilityIndex) {
+    return finish(result, 1, `复核未过：缺列 [${missingAfter.join(",")}] · 条数一致 ${countOk} · 索引 ${after.visibilityIndex}`);
+  }
+  result.ok = true;
+  result.steps.push("复核通过：两列 + 索引在位、条数未变");
+  return finish(result, 0, "迁移完成");
+}
+
+/** 停机窗口判据：3080（及调用方给的端口）无监听 **且** `memory.db-wal` 无非空残留。 */
+export async function checkStopWindow(ports = [3080]) {
+  const reasons = [];
+  const walPath = `${productionDbPath()}-wal`;
+  let walBytes = 0;
+  if (fs.existsSync(walPath)) {
+    try {
+      walBytes = fs.statSync(walPath).size;
+    } catch {
+      walBytes = -1;
+    }
+  }
+  if (walBytes > 0) reasons.push(`memory.db-wal 非空（${walBytes} 字节，疑似有未落盘事务）`);
+  const live = [];
+  for (const p of ports) if (await probePort(p)) live.push(p);
+  if (live.length) reasons.push(`端口 ${live.join(",")} 在监听（DSH 在跑）`);
+  return { ok: reasons.length === 0, reasons, walBytes, listening: live, checkedPorts: ports };
+}
+
+/** TCP 探活（loopback）。 */
+export function probePort(port, host = "127.0.0.1", timeout = 800) {
+  return new Promise((resolve) => {
+    const sock = net.createConnection({ port, host });
+    let done = false;
+    const end = (v) => {
+      if (done) return;
+      done = true;
+      try {
+        sock.destroy();
+      } catch {
+        /* ignore */
+      }
+      resolve(v);
+    };
+    sock.setTimeout(timeout);
+    sock.on("connect", () => end(true));
+    sock.on("timeout", () => end(false));
+    sock.on("error", () => end(false));
+  });
+}
+
+function finish(result, code, message) {
+  result.exitCode = code;
+  result.message = message;
+  if (JSON_OUT) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`\n[${code === 0 ? "OK" : "STOP"}] ${message}`);
+    for (const s of result.steps) console.log(`  ✓ ${s}`);
+    for (const w of result.warnings) console.log(`  ⚠️ ${w}`);
+  }
+  process.exitCode = code;
+}

package/memory-db-tools/memory-scope-fixture.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// tools/memory-db-tools/memory-scope-fixture.mjs
+//
+// ⑤ 包 §5 判据 5「检索隔离可证伪」夹具（施工卡 ⑤-3 交付）。
+//
+// 判据（§5-5 / §3.3-4）：造「主人私有条 + 家人条」→ 家人侧真跑过滤 SQL ⇒
+//   · 家人侧**不得**命中主人私有条；· 主人注入层**不得**注入家人条。
+// 本卡补充（卡面：「造超域条 ⇒ 必须被过滤掉」）：再验一条 **owner 未登记**的 `visibility='family'` 条
+// ⇒ 严格模式（带 `registeredOwners` 护栏）必须把它挡掉。
+//
+// ⚠️ 本夹具**会写库**（造条）⇒ **硬拒绝生产路径**（不给 `--allow-production` 逃生舱：对生产做这事无意义）。
+//    默认在沙箱副本（`VACUUM INTO` 出来的那份，或 `_archive/.../sandbox/` 工作副本）上跑。
+//
+// 用法：
+//   node memory-scope-fixture.mjs --db <沙箱库> [--json] [--cleanup]
+// 退出码：0 = 全部断言通过；1 = 有断言失败；2 = 用法错或路径被拒；3 = 环境不可用
+
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+  MEMORIES_TABLE,
+  familyScopeSql,
+  isProductionDb,
+  ownerScopeSql,
+  productionDbPath,
+  selectMemories,
+} from "./lib/memory-scope.mjs";
+
+const MARK = "card053-fixture";
+const argv = process.argv.slice(2);
+function argRaw(name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) {
+    const v = argv[i + 1];
+    return v && !v.startsWith("--") ? v : true;
+  }
+  const kv = argv.find((a) => a.startsWith(`${name}=`));
+  return kv ? kv.slice(name.length + 1) : null;
+}
+const JSON_OUT = argv.includes("--json");
+const log = (...a) => {
+  if (!JSON_OUT) console.log(...a);
+};
+
+/** 夹具身份表（wife_test / husband_test 已登记；stranger_unregistered **故意不登记**）。 */
+const FIXTURE_IDENTITY = Object.freeze({
+  LiJianXiao: { name: "主人", role: "owner", caps: ["*"] },
+  wife_test: { name: "家人A（夹具）", role: "member", caps: [] },
+  husband_test: { name: "家人B（夹具）", role: "member", caps: [] },
+});
+
+/** 夹具里"来自身份表"的已登记集合（= 严格模式护栏的输入）。 */
+const REGISTERED = Object.freeze(Object.keys(FIXTURE_IDENTITY));
+
+const CASES = Object.freeze([
+  { key: "owner_private", owner: "LiJianXiao", visibility: "private_owner", expectFamily: false, expectOwner: true, why: "主人私有条（对家人侧超域）" },
+  { key: "owner_family", owner: "LiJianXiao", visibility: "family", expectFamily: true, expectOwner: true, why: "主人显式共享条" },
+  { key: "owner_public", owner: "LiJianXiao", visibility: "public", expectFamily: true, expectOwner: true, why: "公开条" },
+  { key: "wife_private", owner: "wife_test", visibility: "private_owner", expectFamily: true, expectOwner: false, why: "家人A自己的私有条（本人可见）" },
+  { key: "husband_private", owner: "husband_test", visibility: "private_owner", expectFamily: false, expectOwner: false, why: "家人B私有条（对家人A超域）" },
+  { key: "stranger_family", owner: "stranger_unregistered", visibility: "family", expectFamily: false, expectOwner: false, why: "**超域条**：owner 未登记却标了 family" },
+]);
+
+function main() {
+  const dbOpt = argRaw("--db");
+  const cleanup = argv.includes("--cleanup");
+  const out = { at: new Date().toISOString(), check: "判据5-检索隔离", ok: false, exitCode: 0, assertions: [], knownBoundaries: [] };
+  if (!dbOpt || dbOpt === true) return finish(out, 2, "参数错：必须给 --db <沙箱库路径>（本夹具会写库，不接受默认生产路径）");
+  const dbPath = path.resolve(String(dbOpt));
+  out.db = dbPath;
+
+  if (isProductionDb(dbPath)) {
+    return finish(out, 2, `拒绝：${dbPath} 是生产库 —— 本夹具会造条写库，只允许打沙箱副本（生产库路径 = ${productionDbPath()}）`);
+  }
+  if (!fs.existsSync(dbPath)) return finish(out, 3, `环境不可用：库不存在 ${dbPath}`);
+
+  const db = new DatabaseSync(dbPath);
+  const now = Date.now();
+  const insert = db.prepare(`INSERT INTO ${MEMORIES_TABLE} (text, tags, pinned, created_at, updated_at, owner_user, visibility) VALUES (?, ?, 0, ?, ?, ?, ?)`);
+  const ids = {};
+
+  try {
+    // ---- 前置：两列必须在位（迁移跑过）
+    const cols = db.prepare(`PRAGMA table_info(${MEMORIES_TABLE})`).all().map((r) => r.name);
+    const missing = ["owner_user", "visibility"].filter((c) => !cols.includes(c));
+    if (missing.length) return finish(out, 2, `不可用：缺列 [${missing.join(", ")}] —— 先跑 memory-schema-migrate.mjs`);
+
+    // ---- 清掉上一轮夹具条（幂等重跑）
+    const pre = db.prepare(`DELETE FROM ${MEMORIES_TABLE} WHERE tags LIKE ?`).run(`%${MARK}%`);
+    if (pre.changes) log(`（清掉上一轮夹具条 ${pre.changes} 条）`);
+
+    // ---- 造条
+    for (const c of CASES) {
+      const r = insert.run(
+        `[夹具 ${MARK}] ${c.key} —— ${c.why}`,
+        `${MARK} ${c.key}`,
+        now,
+        now,
+        c.owner,
+        c.visibility,
+      );
+      ids[c.key] = Number(r.lastInsertRowid);
+    }
+    out.fixtureIds = ids;
+    log(`造条：${CASES.length} 条（tags 含 ${MARK}）`);
+    for (const c of CASES) log(`  · #${ids[c.key]} ${c.owner} / ${c.visibility} —— ${c.why}`);
+
+    // ---- 家人侧（self = wife_test）· 基础模式（§3.3-4 原文）
+    // ⚠️ 所有断言都只针对**本次造的夹具条**（`tags LIKE '<MARK>%'`）：真实库有近 600 条数据，
+    //    不限定就会被 LIMIT 截断 ⇒ 断言假绿/假红（2026-09-20 本卡实测踩过，见 lib.selectMemories 注释）。
+    const fx = (scope) => selectMemories(db, scope, { limit: 10000, tagLike: `%${MARK}%` });
+    const base = familyScopeSql("wife_test");
+    const famBaseKeys = keysOf(fx(base), ids);
+
+    // ---- 家人侧 · 严格模式（带已登记护栏）
+    const strict = familyScopeSql("wife_test", { registeredOwners: REGISTERED });
+    const famStrictKeys = keysOf(fx(strict), ids);
+
+    // ---- 主人侧注入层
+    const ownerScope = ownerScopeSql("LiJianXiao");
+    const ownerKeys = keysOf(fx(ownerScope), ids);
+
+    // ---- 身份表不可用 ⇒ fail-closed（只留本人条）
+    const failClosed = familyScopeSql("wife_test", { registeredOwners: [] });
+    const fcKeys = keysOf(fx(failClosed), ids);
+
+    out.scopes = {
+      familyBase: { mode: base.mode, where: base.where, hit: famBaseKeys },
+      familyStrict: { mode: strict.mode, where: strict.where, hit: famStrictKeys },
+      ownerInject: { mode: ownerScope.mode, where: ownerScope.where, hit: ownerKeys },
+      familyFailClosed: { mode: failClosed.mode, where: failClosed.where, hit: fcKeys },
+    };
+
+    // ---- 断言
+    const A = (key, pass, detail) => out.assertions.push({ key, pass: Boolean(pass), detail });
+
+    A("家人侧基础模式不命中主人私有条", !famBaseKeys.includes("owner_private"), `命中=[${famBaseKeys.join(", ")}]`);
+    A("家人侧基础模式不命中另一家人私有条", !famBaseKeys.includes("husband_private"), `命中=[${famBaseKeys.join(", ")}]`);
+    A("家人侧基础模式命中 family/public 条", famBaseKeys.includes("owner_family") && famBaseKeys.includes("owner_public"), `命中=[${famBaseKeys.join(", ")}]`);
+    A("家人侧基础模式命中自己的私有条", famBaseKeys.includes("wife_private"), `命中=[${famBaseKeys.join(", ")}]`);
+    A("家人侧严格模式不命中超域条", !famStrictKeys.includes("stranger_family"), `命中=[${famStrictKeys.join(", ")}]`);
+    A("家人侧严格模式不命中主人私有条", !famStrictKeys.includes("owner_private"), `命中=[${famStrictKeys.join(", ")}]`);
+    A("主人注入层不注入家人条", !ownerKeys.includes("wife_private") && !ownerKeys.includes("husband_private"), `命中=[${ownerKeys.join(", ")}]`);
+    A("主人注入层命中主人自己的条", ownerKeys.includes("owner_private") && ownerKeys.includes("owner_family"), `命中=[${ownerKeys.join(", ")}]`);
+    A("主人注入层不注入超域条", !ownerKeys.includes("stranger_family"), `命中=[${ownerKeys.join(", ")}]`);
+    A("身份表不可用 ⇒ fail-closed 只返回本人条", fcKeys.length === 1 && fcKeys[0] === "wife_private", `命中=[${fcKeys.join(", ")}]`);
+
+    // ---- 已知边界（如实记录，不计失败）
+    out.knownBoundaries.push({
+      key: "基础模式会命中超域条",
+      detail: famBaseKeys.includes("stranger_family")
+        ? "基础句（§3.3-4 原文：visibility IN ('family','public') OR owner_user=:self）**会**命中 owner 未登记却标 family 的条 ⇒ 实现层应使用严格模式（带 registeredOwners 护栏），且判据 4 会同时判红"
+        : "基础句本轮未命中超域条（身份/数据组合变了，需复核）",
+    });
+
+    const failed = out.assertions.filter((a) => !a.pass);
+    for (const a of out.assertions) log(`  ${a.pass ? "✓" : "✗"} ${a.key} —— ${a.detail}`);
+    log(`已知边界：${out.knownBoundaries[0].detail}`);
+
+    if (cleanup) {
+      const del = db.prepare(`DELETE FROM ${MEMORIES_TABLE} WHERE tags LIKE ?`).run(`%${MARK}%`);
+      out.cleanedUp = del.changes;
+      log(`清理：删除夹具条 ${del.changes} 条`);
+    }
+    return finish(out, failed.length ? 1 : 0, failed.length ? `${failed.length} 条断言失败` : "判据 5 全部断言通过（家人侧不越域 · 主人侧不注入他人条 · 超域条被严格模式挡掉）");
+  } finally {
+    try {
+      db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function keysOf(rows, ids) {
+  const byId = new Map(Object.entries(ids).map(([k, v]) => [Number(v), k]));
+  return rows.map((r) => byId.get(Number(r.id))).filter(Boolean).sort();
+}
+
+function finish(out, code, message) {
+  out.exitCode = code;
+  out.ok = code === 0;
+  out.message = message;
+  out.failed = out.assertions.filter((a) => !a.pass).map((a) => a.key);
+  if (JSON_OUT) console.log(JSON.stringify(out, null, 2));
+  else console.log(`\n[${code === 0 ? "PASS" : code === 2 || code === 3 ? "UNAVAILABLE" : "FAIL"}] ${message}`);
+  process.exitCode = code;
+}
+
+// ---- 入口（放文件末尾：main 依赖的 const 表都在上方声明，避免 TDZ）
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log("用法见本文件头部注释；开关：--db <沙箱库> [--json] [--cleanup]");
+  process.exitCode = 0;
+} else {
+  main();
+}

package/memory-db-tools/read-memories.mjs

@@ -0,0 +1,26 @@
+import { DatabaseSync } from "node:sqlite";
+
+// 只读读指定记忆全文（替代 PowerShell 内联 node -e 读库，避免引号/转义地狱，见记忆 #46 第 2 条）。
+// 用法：
+//   node read-memories.mjs 9 27       读 #9、#27 全文
+//   node read-memories.mjs --all      输出全部记忆全文
+// （dsh 运行中也可安全执行，WAL 模式只读无冲突）
+const db = new DatabaseSync(`${process.env.USERPROFILE.replaceAll("\\", "/")}/.dsh/memory/memory.db`, { readOnly: true });
+const args = process.argv.slice(2);
+let rows;
+if (args.length === 0 || args.includes("--all")) {
+  rows = db.prepare("SELECT id, text, pinned FROM memories ORDER BY id").all();
+} else {
+  const ids = args.map(Number).filter(Number.isInteger);
+  if (!ids.length) {
+    console.error("用法：node read-memories.mjs <id> [id ...]  或  --all");
+    process.exit(1);
+  }
+  const placeholders = ids.map(() => "?").join(",");
+  rows = db.prepare(`SELECT id, text, pinned FROM memories WHERE id IN (${placeholders}) ORDER BY id`).all(...ids);
+}
+for (const r of rows) {
+  console.log(`=== #${r.id} [pinned=${r.pinned === 1 ? "Y" : "-"}] ===`);
+  console.log(r.text + "\n");
+}
+db.close();

package/memory-db-tools/read-memory-db.mjs

@@ -0,0 +1,20 @@
+import { DatabaseSync } from "node:sqlite";
+
+const db = new DatabaseSync(`${process.env.USERPROFILE.replaceAll("\\", "/")}/.dsh/memory/memory.db`, { readOnly: true });
+
+const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all();
+console.log("=== TABLES ===");
+console.log(JSON.stringify(tables, null, 2));
+
+for (const t of tables) {
+  const name = t.name;
+  try {
+    const cols = db.prepare(`PRAGMA table_info(${name})`).all();
+    console.log(`\n=== TABLE ${name} columns ===`);
+    console.log(JSON.stringify(cols, null, 2));
+  } catch (e) {
+    console.log(`\n=== TABLE ${name} === error: ${e.message}`);
+  }
+}
+
+db.close();