@modusensus/dsh-mneme 0.9.4 → 0.10.0

package/test/share-routes.test.js

@@ -0,0 +1,337 @@
+// 分享包的**两张皮**路由锁。盯四件事：
+//   a) policy 归对（token —— 它是全库级读取，与 /export 同门，见 2026-10 审计 P0）；
+//   b) token 配上时**不带 token 必须 401**，不是静默放行；
+//   c) readBody 返回 null（超 4 MiB，它自己已答 413）时 handler 必须直接 return，
+//      不能再答一次 —— 双写响应是 #410 那一类故障；
+//   d) 500 必须留下日志：shareReply 把抛错兜成 500，不接 warn 回调时那条 500 是静默的
+//      （现场只剩「内部错误」，查不出是哪一次打包炸的）。同款契约见 reclaim 的 500 用例。
+// 装配台照 test/api-routes-gaps.test.js 的 reclaimSetup，**必须落文件库**：`:memory:`
+// 与文件库在 store.all() 的读侧口径上没差别，但分享包吃的正是「全库含归档/已遗忘」，
+// 用内存库时归档位的字节口径与体积水位都摸不到真实数字（同 reclaim 报告的理由）。
+//
+// 后半截是 Bearer 数据面（src/api-standalone.js）的真 HTTP 装配，起服务与读 token 的
+// 形状照 test/standalone-api.test.js。放同一份文件里是有意的：#411 说两张皮只许差在
+// 鉴权与路径，那么「同一份答复」就是两侧共同的不变量——分开两个文件时，改一侧的人
+// 看不见另一侧锁着什么。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSettings } from "../src/settings.js";
+import { createApi } from "../src/api.js";
+import { createStandaloneApi } from "../src/api-standalone.js";
+
+const SHARE_PATH = "/api/dsh-mneme/share";
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+class FakeRes extends EventEmitter {
+  constructor({ failFirstHead = false } = {}) {
+    super();
+    this.statusCode = 0;
+    this.body = "";
+    this.headers = null;
+    // writeHead 计数：双写响应的故障形态是「第二次 writeHead 覆盖掉第一次的状态码」，
+    // 只看最终 statusCode 抓不住（413 之后又被 200 盖掉时 body 也换了），要数次数。
+    this.heads = 0;
+    // 一次性坏掉的 sink：真 socket 上「一个响应两写」的现场形态就是第二次 writeHead 抛
+    // ERR_HTTP_HEADERS_SENT（Node 的 writeHead 当场把头发出去）。这里让第一次抛、第二次
+    // 正常，好把「promise 链上的错误到底有没有人接」单独问出来；抛掉的那一次不计数，
+    // 因为它一个字节都没写出去。
+    this.failFirstHead = failFirstHead;
+    // 数据面的 handler 不返回 promise（那条链是 `void readBody(...)`），所以等答复只能靠
+    // 这一声 end：配超时竞速，缺 .catch 时用例红得干脆，而不是把文件挂死在无限超时上。
+    this.settled = new Promise((resolve) => { this.settle = resolve; });
+  }
+  writeHead(code, headers) {
+    if (this.failFirstHead) {
+      this.failFirstHead = false;
+      throw new Error("sink on fire");
+    }
+    this.statusCode = code;
+    this.headers = headers;
+    this.heads += 1;
+    return this;
+  }
+  end(text) {
+    this.body = text ?? "";
+    this.emit("end");
+    this.settle?.("ended");
+    return this;
+  }
+}
+
+function shareSetup(apiToken = "secret-token", { logger = null } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-share-api-"));
+  const store = createStore(join(dir, "memory.db"));
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const commands = { add: () => {}, remove: () => {}, list: () => [] };
+  const routes = [];
+  const ctx = { logger, webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, commands, null, undefined, apiToken, null, null);
+  return {
+    store, service, routes,
+    // 闭包拿 store，不用 this：裸函数调用下 this 是 undefined，异常被吞掉就会变成
+    // 「库没关就删目录」的 EPERM（清理失败还说不清原因）。
+    close() {
+      try { store.close(); } catch { /* already closed */ }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+/**
+ * 字节必须在 listener 挂上之后再 emit：EventEmitter 不排队，在 `route.handler` 里
+ * readBody 注册 data/end 之前 emit 出去等于什么都没发，readBody 的 promise 永不
+ * resolve，整个用例会挂到超时——失败原因还完全看不出跟分享有关。
+ */
+function shareReq({ method = "POST", url = SHARE_PATH, body = "", authorized = true } = {}) {
+  const req = new EventEmitter();
+  req.method = method;
+  req.url = url;
+  req.headers = authorized ? { authorization: "Bearer secret-token" } : {};
+  process.nextTick(() => {
+    req.emit("data", Buffer.from(body));
+    req.emit("end");
+  });
+  return req;
+}
+
+async function callShare(route, opts = {}) {
+  const res = new FakeRes({ failFirstHead: opts.failFirstHead === true });
+  let rejection = null;
+  try {
+    await route.handler(shareReq(opts), res);
+  } catch (error) {
+    // 把 rejection 收成读数而不是让它冒出去：少了 .catch 时这里就是 #410 的形状——
+    // 断言「rejection 必须为 null」比让用例以一个看不懂的异常挂掉说得清得多。
+    rejection = String(error);
+  }
+  return {
+    status: res.statusCode,
+    body: res.body ? JSON.parse(res.body) : null,
+    headers: res.headers,
+    heads: res.heads,
+    rejection
+  };
+}
+
+function shareRoute(setup) {
+  const route = setup.routes.find((r) => r.path === SHARE_PATH);
+  assert.ok(route, "route must exist");
+  return route;
+}
+
+test("share route is registered with policy token", () => {
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    assert.equal(route.policy, "token");
+    assert.equal(route.kind, "exact");
+  } finally { s.close(); }
+});
+
+test("a configured token gates the share route", async () => {
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    s.store.save({ type: "decision", title: "选 SQLite", content: "正文", tags: [] });
+    const denied = await callShare(route, { authorized: false, body: "" });
+    assert.equal(denied.status, 401);
+    const allowed = await callShare(route, { authorized: true, body: "" });
+    assert.equal(allowed.status, 200);
+    const pack = allowed.body;
+    assert.equal(pack.kind, "mneme.share/v1");
+    assert.equal(pack.report.included, 1);
+    assert.ok(!("id" in pack.memories[0]));
+    // 本侧 sendJson 有 headers 第四参（数据面没有）：Content-Disposition 是面板这张脸
+    // 独有的那半，共用层只回 {status, body}，文件名由这里拼——锁它，防止哪天把
+    // shareFilename 的连接也一起「统一」掉。
+    assert.match(allowed.headers["Content-Disposition"], /^attachment; filename="dsh-mneme-share-\d{8}-[0-9a-f]{8}\.json"$/);
+    // 空 body 与「一个字节都不发」同口径：分享的主用法就是按整库口径打。
+    const alias = await callShare(route, { body: JSON.stringify({ alias: "桉桉的库" }) });
+    assert.equal(alias.status, 200);
+    assert.equal(alias.body.alias, "桉桉的库");
+    assert.match(alias.body.source_version, /\d/, "包要记下发送方版本，对面按它判兼容");
+    assert.ok(Number.isFinite(Date.parse(alias.body.generated_at)));
+  } finally { s.close(); }
+});
+
+test("GET on the share route is not an open read", async () => {
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    s.store.save({ type: "decision", title: "选 SQLite", content: "正文", tags: [] });
+    const out = await callShare(route, { method: "GET", body: "" });
+    // 状态码锁死 405，不留 404 这个后门：#411 说两张皮只许差在鉴权与路径，
+    // 而数据面那半（本文件末尾）已经只认 405。这里容忍 404 就等于让「面板哪天
+    // 掉回末尾 404」也算通过——两张皮悄悄多出一处差别，没人报警。
+    assert.equal(out.status, 405, `GET 必须回 405，got ${out.status}`);
+    assert.ok(!out.body || !("memories" in out.body), "GET 不许把包交出去");
+  } finally { s.close(); }
+});
+
+test("a body this layer cannot read is a 400 with one code, not a pack", async () => {
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    s.store.save({ type: "decision", title: "选 SQLite", content: "正文", tags: [] });
+    for (const raw of ["{oops", "[1,2]", "null"]) {
+      const out = await callShare(route, { body: raw });
+      assert.equal(out.status, 400, `${raw} 必须被拒`);
+      assert.equal(out.headers?.["Content-Type"], "application/json; charset=utf-8");
+      assert.ok(!("memories" in out.body), "拒答里绝不带包体");
+    }
+  } finally { s.close(); }
+});
+
+test("an oversize body answers 413 exactly once", async () => {
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    s.store.save({ type: "decision", title: "选 SQLite", content: "正文", tags: [] });
+    // readBody 超限时会自己答 413 并把 text 解析成 null。handler 若没有
+    // `if (text === null) return`，它会拿 null 继续往下走：parseShareBody(null) 是
+    // 合法的「空 body」，于是整库进包、再答一次 200 —— 一个响应两写，客户端按
+    // 状态码分支时看到的是最后那一次（#410 修过的同一类故障）。
+    const out = await callShare(route, { body: "x".repeat(MAX_BODY_BYTES + 1) });
+    assert.equal(out.heads, 1, "超限时只许有一次响应写");
+    assert.equal(out.status, 413);
+    assert.equal(out.body.error, "payload-too-large");
+  } finally { s.close(); }
+});
+
+test("a throwing pack build answers 500 and leaves a log line", async () => {
+  // 不带 logger 也照答 500（shareReply 的 warn 是可选的），但带时必须真的写日志：
+  // 否则「500 且无迹可查」这条现场就无从下手。
+  const warnings = [];
+  const s = shareSetup("secret-token", { logger: { warn: (m) => warnings.push(String(m)) } });
+  try {
+    const route = shareRoute(s);
+    s.service.all = () => { throw new Error("database is locked"); };
+    const out = await callShare(route, { body: "" });
+    assert.equal(out.status, 500);
+    assert.deepEqual(out.body, { error: "internal" }, "对外只有一个码，不带原始错误文本");
+    assert.match(warnings.join(" "), /share pack failed/);
+    assert.match(warnings.join(" "), /database is locked/, "原始错误文本要留在日志里");
+  } finally { s.close(); }
+});
+
+test("the panel /share chain answers once when the sink fails mid-write", async () => {
+  // 车道 A 的这条路由只有外层 try，而外层 try 在 .then 的回调里早已退栈：回调里抛出的错
+  // （这里是 sendJson 的 writeHead 抛——真 socket 上「一个响应两写」的第二次就是这个形状）
+  // 没人接，就是一个 unhandled rejection 加「一个字节都没回」（#410）。数据面的同名路由
+  // （本文件末尾）一直带着那一声 .catch，两条皮在这里本该只差鉴权与路径（#411），
+  // 所以补的是面板这一侧。C6 之后 warn 已被共用层守卫包住，日志坏掉那条路走不到这里，
+  // 这个 sink 形状是 .catch 唯一还能被独立问到的入口。
+  const s = shareSetup();
+  try {
+    const route = shareRoute(s);
+    s.store.save({ type: "decision", title: "选 SQLite", content: "正文 here", tags: [] });
+    const out = await callShare(route, { body: "", failFirstHead: true });
+    assert.equal(out.rejection, null, "回调里抛出的错必须由链上的 .catch 接住");
+    assert.equal(out.status, 500, "sink 坏了也要把答复交出去");
+    assert.deepEqual(out.body, { error: "internal" });
+    assert.equal(out.heads, 1, "抛掉的那一次没写出去，成功的只许有一次");
+  } finally { s.close(); }
+});
+
+// --- Bearer 数据面（src/api-standalone.js）-----------------------------------
+
+function standaloneSetup() {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-share-std-"));
+  const store = createStore(join(dir, "memory.db"));
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  // 起法照 test/standalone-api.test.js：这个模块没有 start()/stop()，监听在构造里
+  // 发起、由 ready 兑现，端口是 OS 给的（port: 0），token 挂在 api 上。
+  const api = createStandaloneApi({ service, store, config: {}, settings, logger: null, port: 0 });
+  return api.ready.then(() => {
+    const base = `http://127.0.0.1:${api.port}`;
+    return {
+      api, store, service, base, auth: { authorization: `Bearer ${api.token}` },
+      close() {
+        // 拆掉 keep-alive 连接，否则 node --test 的循环排不干净（同那份文件）。
+        api.server.closeIdleConnections?.();
+        api.server.close();
+        try { store.close(); } catch { /* already closed */ }
+        rmSync(dir, { recursive: true, force: true });
+      }
+    };
+  });
+}
+
+test("standalone /share answers the pack for a Bearer caller and 401 otherwise", async () => {
+  const h = await standaloneSetup();
+  try {
+    h.store.save({ type: "decision", title: "选 SQLite", content: "正文 here", tags: [] });
+    const anon = await fetch(`${h.base}/share`, { method: "POST", body: "{}" });
+    assert.equal(anon.status, 401, "这一面除 GET /health 外一律要 token，没有 policy 名可绕");
+    assert.deepEqual(await anon.json(), { error: "unauthorized" });
+
+    const ok = await fetch(`${h.base}/share`, {
+      method: "POST", headers: h.auth, body: JSON.stringify({ alias: "桉" })
+    });
+    assert.equal(ok.status, 200);
+    const pack = await ok.json();
+    assert.equal(pack.kind, "mneme.share/v1", "两张皮交出去的是同一个包形状");
+    assert.equal(pack.alias, "桉");
+    assert.equal(pack.report.included, 1);
+    // 本面**没有** Content-Disposition：它的 sendJson 连 headers 参数都没有，CLI 拿
+    // JSON 自己落盘。锁「不许冒出来」，防止哪天有人为了对齐面板而改那个签名。
+    assert.equal(ok.headers.get("content-disposition"), null);
+
+    // 读不懂的 body 在这侧同样是 400 一个码，而不是掉回末尾的 404。
+    for (const raw of ["{oops", "[1,2]", "null"]) {
+      const bad = await fetch(`${h.base}/share`, { method: "POST", headers: h.auth, body: raw });
+      assert.equal(bad.status, 400, `${raw} 必须被拒`);
+      assert.ok(!("memories" in await bad.json()), "拒答里绝不带包体");
+    }
+  } finally { await h.close(); }
+});
+
+test("standalone GET /share answers 405, matching the panel", async () => {
+  // 这一条**故意**与 /maintenance/reclaim 不同（那边 GET 掉到末尾 404）。#411 的口径
+  // 是「两张皮只许差在鉴权与路径」，状态码差一次就是第三处差别，所以这里跟着面板回
+  // 405 —— 一致性优先于照抄这份文件里的邻居。
+  const h = await standaloneSetup();
+  try {
+    h.store.save({ type: "decision", title: "选 SQLite", content: "正文 here", tags: [] });
+    const out = await fetch(`${h.base}/share`, { headers: h.auth });
+    assert.equal(out.status, 405);
+    const body = await out.json();
+    assert.ok(!("memories" in body), "GET 不许把包交出去");
+  } finally { await h.close(); }
+});
+
+test("the standalone /share chain answers once when the sink fails mid-write", async () => {
+  // 本面这条链一直带着 .catch，但**从来没有任何用例走到得过它**：共用层从不抛、日志也
+  // 被守卫吞掉之后，剩下的入口只有面自己写答复这一步（真 socket 上「一个响应两写」的
+  // 第二次 writeHead 就是这里的形状）。与上面面板那条同名用例是一对——两张皮的 .catch
+  // 各锁各的，少一边就只有一边会红（#411）。假 sink 第一次抛、第二次正常；等得到答复
+  // 就说明链上有主，等不到（输给超时）就是 #410 的「一个字节都没回」。
+  const h = await standaloneSetup();
+  try {
+    h.store.save({ type: "decision", title: "选 SQLite", content: "正文 here", tags: [] });
+    const handlers = h.api.server.listeners("request");
+    assert.equal(handlers.length, 1, "这台面上只许挂着一个 request handler，否则不知道在驱动谁");
+    const req = new EventEmitter();
+    req.method = "POST";
+    req.url = "/share";
+    req.headers = { authorization: `Bearer ${h.api.token}` };
+    const res = new FakeRes({ failFirstHead: true });
+    handlers[0](req, res);
+    process.nextTick(() => {
+      req.emit("data", Buffer.from("{}"));
+      req.emit("end");
+    });
+    const settled = await Promise.race([res.settled, new Promise((r) => setTimeout(() => r("timeout"), 3000))]);
+    assert.equal(settled, "ended", "缺了 .catch 就永远等不到答复");
+    assert.equal(res.statusCode, 500);
+    assert.equal(res.heads, 1, "抛掉的那一次没写出去，成功的只许有一次");
+  } finally { await h.close(); }
+});

package/test/share-store.test.js

@@ -0,0 +1,133 @@
+// 车道 C 的存储层。这里盯的不是「列在不在」，而是三件容易写错的事：
+//   a) 存量库重开即建列，且存量行的新列是 NULL 而不是被填成某个假值；
+//   b) UNIQUE 索引只对外来行生效——普通本地行必须能无限多条共享 NULL；
+//   c) 批删清 side table 且 generation 前移，否则镜像恢复会把删掉的行当「没跟上」。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { createStore } from "../src/store.js";
+import { IMPORTED_SOURCE } from "../src/memory-source.js";
+
+const temp = () => mkdtempSync(join(tmpdir(), "dsh-mneme-share-store-"));
+
+test("an existing library gains both columns on reopen, legacy rows stay NULL", () => {
+  const dir = temp(), path = join(dir, "memory.db");
+  const raw = new DatabaseSync(path);
+  raw.exec(`CREATE TABLE memories (
+    id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '[]', importance INTEGER NOT NULL DEFAULT 3,
+    forgotten INTEGER NOT NULL DEFAULT 0, archived INTEGER NOT NULL DEFAULT 0,
+    archived_at TEXT, source TEXT, content_history TEXT, content_hash TEXT, embedding TEXT,
+    epistemic_status TEXT NOT NULL DEFAULT 'subjective', last_accessed_at TEXT,
+    _full_content TEXT, evidence TEXT, doc_path TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);`);
+  raw.prepare(`INSERT INTO memories (id, type, title, content, created_at, updated_at)
+    VALUES ('legacy-1','decision','旧条目','正文','2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')`).run();
+  raw.close();
+
+  const store = createStore(path);
+  try {
+    const row = store.getById("legacy-1");
+    assert.equal(row.share_pack_id, undefined, "legacy row must not be stamped as imported");
+    assert.equal(row.share_external_id, undefined);
+    // toRow 读不到列时也返回 undefined，所以「列真的建了」「建的是 NULL 而不是 ''」
+    // 这两件事只能在库里看——否则本用例对迁移毫无判别力。
+    const cols = store.db.prepare("PRAGMA table_info(memories)").all().map((c) => c.name);
+    assert.ok(cols.includes("share_pack_id") && cols.includes("share_external_id"),
+      "reopen must add both columns to a legacy library");
+    const stored = store.db.prepare("SELECT share_pack_id, share_external_id AS e FROM memories WHERE id = 'legacy-1'").get();
+    assert.equal(stored.share_pack_id, null, "legacy cells are NULL, not '' (empty string would collide in the UNIQUE index)");
+    assert.equal(stored.e, null);
+  } finally { store.close(); }
+  // 幂等重开：第二个连接开在同一条路径上，列已在，迁移不许再动它一根手指。
+  const again = createStore(path);
+  try {
+    assert.ok(again.getById("legacy-1"));
+    assert.equal(again.getById("legacy-1").share_pack_id, undefined);
+  } finally { again.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("foreign rows are unique per external_id while local rows share NULL freely", () => {
+  const dir = temp(), store = createStore(join(dir, "memory.db"));
+  try {
+    store.save({ type: "decision", title: "a", content: "x", source: IMPORTED_SOURCE, share_external_id: "deadbeef00000001" });
+    assert.throws(() => store.save({ type: "decision", title: "b", content: "y", source: IMPORTED_SOURCE, share_external_id: "deadbeef00000001" }),
+      /UNIQUE constraint failed/);
+    for (const t of ["p1", "p2", "p3"]) store.save({ type: "decision", title: t, content: "x" });
+    assert.equal(store.list({ type: "decision", limit: null }).length, 4, "NULL must not collide");
+  } finally { store.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("share columns round-trip through toRow and are queryable", () => {
+  const dir = temp(), store = createStore(join(dir, "memory.db"));
+  try {
+    const row = store.save({ type: "preference", title: "t", content: "c", source: IMPORTED_SOURCE,
+      share_pack_id: "packA", share_external_id: "deadbeef00000002" });
+    assert.equal(row.share_pack_id, "packA");
+    assert.equal(row.share_external_id, "deadbeef00000002");
+    assert.equal(store.getByShareExternalId("deadbeef00000002").id, row.id);
+    assert.equal(store.getByShareExternalId("nope"), undefined);
+    store.save({ type: "preference", title: "t2", content: "c2", source: IMPORTED_SOURCE, share_pack_id: "packA", share_external_id: "deadbeef00000003" });
+    assert.deepEqual(store.listBySharePackId("packA").map((m) => m.share_external_id).sort(),
+      ["deadbeef00000002", "deadbeef00000003"]);
+  } finally { store.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("deleteBySharePackId removes the whole pack, cleans provenance, and bumps generation", () => {
+  const dir = temp(), store = createStore(join(dir, "memory.db"));
+  try {
+    const a = store.save({ type: "preference", title: "t1", content: "c", source: IMPORTED_SOURCE, share_pack_id: "packA", share_external_id: "deadbeef00000011" });
+    const b = store.save({ type: "preference", title: "t2", content: "c", source: IMPORTED_SOURCE, share_pack_id: "packA", share_external_id: "deadbeef00000012" });
+    store.save({ type: "preference", title: "keep", content: "c", source: IMPORTED_SOURCE, share_pack_id: "packB", share_external_id: "deadbeef00000013" });
+    // 归档面也要一起收走：整包退出之后不许留下「来自一个已经收起的包」的行。
+    // 行数用库级 count 而不是 store.count()——后者按活跃面过滤，归档行不在账上，
+    // 拿它当「删了几行」的锚会把断言变成过滤器口径的探针（那不是本用例要锁的东西）。
+    store.setArchived(b.id, true);
+    const totalRows = () => store.db.prepare("SELECT count(*) AS c FROM memories").get().c;
+    // 真实 schema 的必填列是 (memory_id, session_id, seq_start, seq_end, created_at) 全部
+    // NOT NULL，走 store 自己的写入口 saveMemoryProvenance，不走手搓 INSERT。
+    //
+    // 这里先把 foreign_keys 关掉，不是随手配置：memory_provenance 挂着
+    // ON DELETE CASCADE，而 node:sqlite 的 DatabaseSync 默认就把 PRAGMA foreign_keys 开成
+    // 1（实测：新库上 `PRAGMA foreign_keys` 返回 1）。FK 开着时删记忆由级联代劳，本用例
+    // 断言的「批删自己清链接」就永远测不到那行代码——变异检验证实：摘掉 deleteBySharePackId
+    // 里那条 DELETE FROM memory_provenance，五条用例照绿。关掉之后级联不再代劳，
+    // 断言测的才是显式清理本身。（`src/store.js` 的 `remove()` 注释在 C1 修复轮已经改成
+    // 真口径：node:sqlite 默认就把外键开着、级联是活的，显式清理是为了不把清理押在一份没人
+    // 钉过的驱动默认上——本用例反过来**临时关掉**它，恰恰就是为了让那句「不押注」可测。）
+    store.db.exec("PRAGMA foreign_keys = OFF");
+    store.saveMemoryProvenance({ memoryId: a.id, sessionId: "s-1", seqStart: 1, seqEnd: 3, createdAt: "2026-01-01T00:00:00.000Z" });
+    assert.equal(store.provenanceFor(a.id).length, 1, "the link must exist before the delete or the assertion below is empty");
+    const before = totalRows();
+    const genBefore = store.getMirrorState().generation;
+    assert.equal(store.listBySharePackId("packA").length, 2, "the withdrawal inventory must see archived rows too");
+    const deleted = store.deleteBySharePackId("packA");
+    assert.equal(deleted, 2);
+    assert.ok(store.getMirrorState().generation > genBefore,
+      "batch delete must register mirror debt like remove() does, else recoverMirror reads the pack as 「not yet synced」");
+    assert.equal(totalRows(), before - 2);
+    assert.equal(store.provenanceFor(a.id).length, 0, "provenance links must not dangle after a batch delete");
+    assert.equal(store.getByShareExternalId("deadbeef00000011"), undefined, "UNIQUE slot must be freed for a clean re-import");
+    assert.equal(store.listBySharePackId("packA").length, 0);
+    assert.equal(store.listBySharePackId("packB").length, 1);
+    const genAfterDelete = store.getMirrorState().generation;
+    assert.equal(store.deleteBySharePackId("packA"), 0, "idempotent");
+    assert.equal(store.getMirrorState().generation, genAfterDelete,
+      "a no-op withdrawal deletes nothing, so it must not register mirror debt either");
+  } finally { store.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("a UNIQUE collision aborts the whole transaction — nothing lands partially", () => {
+  const dir = temp(), store = createStore(join(dir, "memory.db"));
+  try {
+    store.save({ type: "decision", title: "seed", content: "x", source: IMPORTED_SOURCE, share_external_id: "cafe000000000001" });
+    assert.throws(() => store.runAtomically(() => {
+      store.save({ type: "decision", title: "dup", content: "y", source: IMPORTED_SOURCE, share_external_id: "cafe000000000001" });
+      store.save({ type: "decision", title: "later", content: "z", source: IMPORTED_SOURCE, share_external_id: "cafe000000000002" });
+    }), /UNIQUE constraint failed/);
+    assert.equal(store.getByShareExternalId("cafe000000000002"), undefined, "the row after the collision must not have landed");
+    assert.equal(store.list({ limit: null }).length, 1, "the batch left nothing behind");
+  } finally { store.close(); rmSync(dir, { recursive: true, force: true }); }
+});

package/test/share-validate.test.js

@@ -0,0 +1,101 @@
+// 接收侧的格式闸门。锁三件事：
+//   a) 一个不合规的包**整包**不合格（车道 C 不许半途入库）；
+//   b) 键必须可重算——包是别人发来的，重算对不上就是被人改过，幂等键失效；
+//   c) 允许的类型集合不许偷偷跟着 mirror 扩：这里刻意重述一遍，并由静态锁比对
+//      TYPE_FILE 的键集减去两个排除项，将来加第 9 类时它会转红提醒人来决定。
+import test from "node:test";
+import assert from "node:assert/strict";
+// 静态锁用真仪器而不是源码正则：test/mirror-types.test.js 已经是 import TYPE_FILE +
+// Object.keys 的先例。在**测试**里 import 它不花钱——src/share.js 的重述字面集照旧，
+// 那是接收侧的兼容契约，不是漂移。
+import { TYPE_FILE } from "../src/mirror.js";
+import {
+  PACK_ID_RE, SHARE_ALLOWED_TYPES, SHARE_READONLY_TYPES, SHARE_EXCLUDED_TYPES,
+  importedTagFor, validateSharePack, deriveExternalId, SHARE_KIND
+} from "../src/share.js";
+
+const entry = (over = {}) => {
+  const base = { type: "decision", title: "选 SQLite", content: "正文正文", tags: ["x"], importance: 4,
+    epistemic_status: "subjective", created_at: "2026-10-01T00:00:00.000Z", updated_at: "2026-10-01T00:00:00.000Z", content_hash: "ab" };
+  return { ...base, external_id: deriveExternalId("f0f0f0f0f0f0f0f0", base.type, base.title, base.content_hash), ...over };
+};
+const packOf = (memories, over = {}) => ({
+  kind: SHARE_KIND, pack_id: "f0f0f0f0f0f0f0f0", alias: "桉", generated_at: "2026-10-22T00:00:00.000Z",
+  source_version: "0.9.4", report: { included: memories.length, skipped: {}, skip_list: [], deduped: 0 },
+  memories, ...over
+});
+
+test("pack_id is exactly 16 lowercase hex", () => {
+  assert.match("f0f0f0f0f0f0f0f0", PACK_ID_RE);
+  assert.doesNotMatch("f0f0f0f0f0f0f0", PACK_ID_RE);       // 车道 A 铸的是 16 位，不是 12
+  assert.doesNotMatch("F0F0F0F0F0F0F0F0", PACK_ID_RE);
+  // 后两条只验 {16} 那个量词，验不到两个锚：锚一掉，「16 位以内」就成了「正文里含 16 位」，
+  // 于是 18 位的串和带空白的串都能过——而这两种恰好是手改包与编码包的形状。
+  assert.doesNotMatch("f0f0f0f0f0f0f0f0ff", PACK_ID_RE);
+  assert.doesNotMatch(" f0f0f0f0f0f0f0f0", PACK_ID_RE);
+});
+
+test("a well-formed pack validates and reports its count", () => {
+  const out = validateSharePack(packOf([entry()]));
+  assert.equal(out.ok, true);
+  assert.equal(out.count, 1);
+});
+
+test("every rejection names a code and never a partial success", () => {
+  assert.equal(validateSharePack({}).error, "invalid-kind");
+  assert.equal(validateSharePack(packOf([entry()], { kind: "other" })).error, "invalid-kind");
+  assert.equal(validateSharePack(packOf([entry()], { pack_id: "nope" })).error, "invalid-pack-id");
+  assert.equal(validateSharePack(packOf([])).error, "empty-pack");
+  assert.equal(validateSharePack({ ...packOf([entry()]), memories: "x" }).error, "invalid-memories");
+  const badType = validateSharePack(packOf([entry({ type: "document" })]));
+  assert.equal(badType.error, "invalid-type");
+  assert.equal(badType.index, 0);
+  assert.equal(validateSharePack(packOf([entry({ title: "  " })])).error, "invalid-entry");
+  assert.equal(validateSharePack(packOf([entry({ content: "" })])).error, "invalid-entry");
+  assert.equal(validateSharePack(packOf([entry({ importance: "high" })])).error, "invalid-entry");
+});
+
+test("a recomputed key that disagrees means the pack was edited by hand", () => {
+  const out = validateSharePack(packOf([entry({ external_id: "0000000000000000" })]));
+  assert.equal(out.ok, false);
+  assert.equal(out.error, "external-id-mismatch");
+  assert.equal(out.index, 0);
+});
+
+test("duplicate external_id inside one pack is rejected, not folded here", () => {
+  // 折叠是出包侧的义务（§3 的 deduped）；收到重复键说明包被人改过，按不合格处置。
+  const dup = packOf([entry(), entry({ content: "另一条" })]);
+  assert.equal(validateSharePack(dup).error, "duplicate-external-id");
+});
+
+test("the tag is derived in one place and never from the sharer's identity", () => {
+  assert.equal(importedTagFor("桉"), "from-桉");
+  assert.equal(importedTagFor(""), "from-shared");
+  assert.equal(importedTagFor(undefined), "from-shared");
+  assert.equal(importedTagFor("   "), "from-shared");         // 全空白别名走中性值，不许剩 `from--`
+  assert.equal(importedTagFor("a\nb  c"), "from-a-b-c");      // 空白游程一律折成一个 -，标签不许带换行
+  assert.equal(importedTagFor("x".repeat(80)).length, 32);    // 上限：别人的字符串不许无限长
+});
+
+test("folding keeps the word boundary: a newline alias is not the squashed spelling", () => {
+  // 上一版对同一类字符开两条规则：换行/制表符**删除**、其余空白折成 -。删除那一侧
+  // 恰恰制造了它自己测试要防的撞名——"a\nb" 与 "ab" 读出同一个标签，而对面看到的
+  // 来源读数还丢了词缝。裁定：整类空白（含 \r\n\t）折成一个 -（mirror.js 的
+  // oneLine() 同是先例：只折不删）。单行的要求折叠同样满足。
+  assert.equal(importedTagFor("a\nb"), "from-a-b");
+  assert.equal(importedTagFor("ab"), "from-ab");
+  assert.notEqual(importedTagFor("a\nb"), importedTagFor("ab"));
+  assert.equal(importedTagFor("a\tb"), "from-a-b");           // 制表符与换行同一条规则
+  assert.equal(importedTagFor("a\r\nb"), "from-a-b");         // \r\n 游程折成**一个** -
+});
+
+test("the allowed type set is the mirror's minus the two exclusions", () => {
+  // 真仪器读真数据：TYPE_FILE import 进来直接 Object.keys()。源码正则有两类静默失明——
+  // 不匹配 `[a-z_]+: "….md"` 形状的键（大写、连字符、带引号的键名）会被无声丢掉，
+  // 而缩进/换行这类纯排版改动同样能让它一条都不解析。断言本体不变：新键进 TYPE_FILE
+  // 而没在这里被决定过，这条必须转红。
+  const keys = Object.keys(TYPE_FILE);
+  assert.ok(keys.length >= 8, `TYPE_FILE should expose its keys to the lock, got ${keys.length}`);
+  const minus = new Set(keys.filter((k) => !SHARE_READONLY_TYPES.has(k) && !SHARE_EXCLUDED_TYPES.has(k)));
+  assert.deepEqual([...SHARE_ALLOWED_TYPES].sort(), [...minus].sort());
+});

package/test/sleep-action-set.test.js

@@ -74,10 +74,12 @@ test("issue#126 supersede: replay is idempotent (archived loser, single note)",
   store.close();
 });
 
-test("issue#126 differentiate: both entries survive and each carries the distinctions note", () => {
+test("issue#533 differentiate: both entries survive, bodies untouched, the pair lands in the ledger", () => {
   const { service, store } = setup();
   const a = makeMemory(service, "内网 SSH 端口", "内网走 22");
   const b = makeMemory(service, "外网 SSH 端口", "外网映射 2222");
+  // 两侧各自追加注记会让共享后缀把向量拉近——先记下原始正文，事后逐字节比对。
+  const before = { [a.id]: service.getById(a.id).content, [b.id]: service.getById(b.id).content };
   const snapshot = snapshotOf(store, a, b);
   const { applied } = applyDecisions(
     [{ action: "differentiate", ids: [a.id, b.id], distinctions: ["内网直连", "外网映射"] }],
@@ -87,10 +89,12 @@ test("issue#126 differentiate: both entries survive and each carries the distinc
   for (const m of [a, b]) {
     const after = service.getById(m.id);
     assert.equal(after.archived, false, "differentiate never archives");
-    assert.ok(after.content.includes("差异注记"), "each side gets the note");
+    assert.equal(after.content, before[m.id], "the body is left byte-identical");
+    assert.ok(!after.content.includes("差异注记"), "no note is written into the body");
   }
-  assert.ok(service.getById(a.id).content.includes("内网直连"), "note carries the distinctions");
-  assert.ok(service.getById(b.id).content.includes("外网映射"));
+  const record = service.findDifferentiatedPair(a.id, b.id);
+  assert.ok(record, "the verdict is recorded as a pair, not as body text");
+  assert.deepEqual(record.distinctions, ["内网直连", "外网映射"], "the model's distinctions survive for audit");
   store.close();
 });
 
@@ -369,20 +373,20 @@ test("issue#126r: buildOutcome records a disposition for the new actions", () =>
   assert.equal(outcome.byId.d2, "differentiated");
 });
 
-test("issue#126r: differentiate refreshes the cached vectors so the note reaches the index", async () => {
+test("issue#533r: differentiate leaves the cached vectors alone (nothing changed to re-embed)", async () => {
   const { service, store, vectorIndex } = setup();
   const { a, b } = seedPair(service, vectorIndex, "向量甲", "向量乙");
-  const before = vectorIndex.getEmbedding(a.id);
-  // 让嵌入器产出与旧向量不同的结果，便于确认"确实重嵌了"。
+  const beforeA = vectorIndex.getEmbedding(a.id);
+  const beforeB = vectorIndex.getEmbedding(b.id);
+  // 让嵌入器产出与旧向量不同的结果：若源码又悄悄重嵌，这里立刻会变。
   const fresh = { ...embedder, embedSingle: async () => [0, 1, 0] };
   service.setEmbedder(fresh);
   const ctx = captureCtx(JSON.stringify([
     { action: "differentiate", ids: [a.id, b.id], distinctions: ["甲面", "乙面"] }
   ]));
   await runSleep(ctx, service, baseConfig({ sleepActionSet: "full" }), ctx.logger, { embedder: fresh, vectorIndex }, null);
-  const after = vectorIndex.getEmbedding(a.id);
-  assert.notDeepEqual(after, before, "the cached vector was recomputed after the content note");
-  assert.deepEqual(after, [0, 1, 0], "it carries the fresh embedding");
+  assert.deepEqual(vectorIndex.getEmbedding(a.id), beforeA, "side A keeps its vector");
+  assert.deepEqual(vectorIndex.getEmbedding(b.id), beforeB, "side B keeps its vector");
   store.close();
 });
 
@@ -397,7 +401,8 @@ test("issue#126r: the full tier discovers cross-type pairs (differentiate would
   ]));
   const result = await runSleep(ctx, service, baseConfig({ sleepActionSet: "full" }), ctx.logger, { embedder, vectorIndex }, null);
   assert.equal(result.phases.conflicts.applied, 1, "the cross-type pair was adjudicated");
-  assert.ok(service.getById(proj.id).content.includes("差异注记"), "differentiate reached the cross-type pair");
+  assert.ok(service.findDifferentiatedPair(proj.id, pref.id), "differentiate reached the cross-type pair");
+  assert.equal(service.getById(proj.id).content, "项目用 8080", "the project body is untouched");
   store.close();
 });