@modusensus/dsh-mneme 0.9.3 → 0.9.5

package/lib/share-import.js

@@ -0,0 +1,234 @@
+// dsh-mneme/src/share-import.js
+// 车道 C 收侧的入库与退出：一份校验过的分享包 → 本库的外来行（整批一个事务），以及按
+// pack_id 把那一批整包收回（spec §5）。
+//
+// 独立成模块（AGENTS.md 尺寸约定，同 organize.js / document.js 先例）：service.js 只做
+// 依赖注入 + barrel 出口，调用方零改动。依赖由 createService 的闭包注入（store /
+// transaction / scheduleEmbed），形状照 src/organize.js 的 createOrganizer——本模块不
+// 认识 service 的内部接线，也不自带事务助手。
+//
+// C3b 是纯搬移：`ShareImportError` 与 `importSharePack` 的定义连同注释、错误码、答复
+// 形状从 src/service.js 逐字移来，一行行为都没改。搬完那三把变异锁照样咬（见
+// test/share-import.test.js 的「最外层 COMMIT 才排空嵌入队列」那组）。C4 是搬移之后
+// 第一刀真的碰这块的改动，所以那两个「本文件」之类的口吻也一并改对了。
+//
+// ESM 环的位置随之挪了一格：原先是 service → share → write-admission → service，现在
+// 那条 service → share 的直接边换成了 service → share-import → share，环还是那个环、
+// 求值期仍然没有任何一侧调用另一侧。下面 share.js 那条 import 上的注释讲的就是它。
+
+import { scopeKeyOf } from "./scope.js";
+import { isImportedRow, IMPORTED_SOURCE } from "./memory-source.js";
+// 车道 C 收侧的两个纯件：整包闸门与来源标签。import 它们而不是重抄一份——判据有两份
+// 的话，出包侧改了收侧不会红，最坏情况是「对面按旧口径铸的键被我们整包拒掉」。
+// 代价是一条**已知并被接受**的 ESM 环：service → share → write-admission → service
+// （share.js 只借 write-admission 的空白/噪声判据，见它模块头）。环上三处都是函数
+// （`PINNED_MEMORY_TYPES` 是 service 顶层的 const，但 write-admission 只在函数体里读它；
+// share.js 用的 informationlessReason 是函数声明，提升后即刻可用），没有任何一侧在
+// 模块求值期调用另一侧——所以求值顺序炸不出 TDZ。这条不是「应该没事」：C3 的报告里
+// 有一道全新进程的 `import("./src/service.js")` 探针，本文件的测试也全走真实链路。
+import { validateSharePack, importedTagFor } from "./share.js";
+
+// 退出答复里给人核对的清单封顶 20 条。这个数管的是**答复的字节数**不是删除的完整性：
+// deleted 恒是全集，sample 只是前缀。两张皮（面板路由 / Bearer 数据面）都把答复
+// JSON.stringify 出去，一个几千条的包如果整包塞进答复，响应体会比请求还大，而人只需要
+// 认出最前面那几条是不是他要收的那批。同 SHARE_SKIP_LIST_MAX（车道 A，50）的口径：
+// 截的是清单不是账。
+const DELETE_SAMPLE_MAX = 20;
+
+/**
+ * 导入的错误：带 code，让两张皮（面板路由与 standalone 数据面）映射成同一个 400 码
+ * 而不是各写一份文案。类放在模块顶层而不是 createService 的闭包里——闭包每实例造一
+ * 个新类，`instanceof` 就退化成「只在同一个 service 实例内部成立」的关系，而消费方
+ * 判的是 `err.code`（spec §5：码集由 share.js 的 validateSharePack 定，这里只转发）。
+ */
+export class ShareImportError extends Error {
+  constructor(code, detail) {
+    super(`share import: ${code}`);
+    this.name = "ShareImportError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/**
+ * 构造收侧的入库与退出。注入的三个依赖都是 service 闭包成员：`store` 是存储层，
+ * `transaction` 必须是 service 那一个而不是 `store.runAtomically`——嵌入队列只在最外层
+ * COMMIT 排空、回滚时按层截断，这套队列语义存储层的助手不认识（退出那侧用它是为了同一
+ * 件事：镜像重渲染与写通知都在它的 finally 里）。
+ *
+ * @returns {{ importSharePack: (pack: object, opts?: { dryRun?: boolean }) => object,
+ *   deleteSharePack: (packId: string, opts?: { dryRun?: boolean }) => object }}
+ */
+export function createShareImport({ store, transaction, scheduleEmbed }) {
+  /**
+   * 车道 C 的入库（spec §5）。与 service.js 里的 mergeHumanEdits 同属「外部文本进库」
+   * 那一族（C3b 之后它在隔壁文件，别再按同文件口吻读这句），但方向相反：那一族改的是
+   * 本机的行，这一族**已有的行一条都不许碰**。
+   *
+   * 真导入整包裹在注入的 `transaction()` 里而不是 `store.runAtomically()`：scheduleEmbed
+   * 在 txDepth>0 时只入队，队列由那个 transaction()（住在 service.js，不是本文件）的
+   * 最外层 COMMIT 排空（入队在 scheduleEmbed 首行，排空在 transaction 的 finally），
+   * 存储层那个助手不认识这套队列——用它等于静默不嵌入，而这批行对收件人的向量检索就
+   * 永远隐形（车道 C 预检点名的那条）。回滚一侧由 transaction() 截断 pendingEmbed，
+   * 绝不给已回滚的行做向量。
+   *
+   * 幂等的主路径是事务内先查 `share_external_id`，命中即跳过。那把部分 UNIQUE 索引只是
+   * 双保险，管两个宿主共用同一 memoryDir 时的竞态；它从这里穿出时是**整笔回滚**——不
+   * catch、不续跑。「约束报错就跳过这一条」看着宽容，实际是把「这个包还没吃过」报成
+   * 「吃过了」，而整包回滚后重跑一次本来就成了 created=0 的正常答复。
+   *
+   * 走 `store.save` 而不是 `saveWithDedupe`：后者命中即 appendContent 并入既有行，而
+   * 「把别人的正文并进我的条目」正是决策 2 要禁的动作；汇流口那侧也已把外来行剔出候选集
+   * （saveWithDedupe 里的 isImportedRow），两条路合起来才是「谁也不改谁」。
+   *
+   * @param {object} pack 一份分享包（kind `mneme.share/v1`）
+   * @param {{dryRun?: boolean}} [opts] dryRun 只算账不写库，答复同形状
+   * @returns {{pack_id: string, alias: string, created: number, skipped_existing: number,
+   *   unchanged: number, title_conflicts: Array<{type: string, title: string, existing_id: string}>,
+   *   conflicts_checked: number}}
+   * @throws {ShareImportError} 校验不过时 err.code 属于 validateSharePack 的码集，且一行未写
+   */
+  function importSharePack(pack, { dryRun = false } = {}) {
+    const v = validateSharePack(pack);
+    if (!v.ok) throw new ShareImportError(v.error, v.detail);
+    const tag = importedTagFor(pack.alias);
+    // 撞名清单的判据按「收件人会不会真的看不见这条」来定，三个条件各挡一类假报告：
+    //  · 已归档 / 已遗忘（store.list 的默认档已经排掉，这里再写一遍是把契约留在调用处，
+    //    哪天有人给这个调用加上 includeArchived，报出来的就是他自己收起来的行）；
+    //  · 带 scope 标注：外来行落的是 NULL scope，两条在他的视图里根本不在同一格——
+    //    scope 这一半与 saveWithDedupe 的去重键同口径（scopeKeyOf 把 NULL 归一成「未标注」），
+    //    但这里**不比 sensitivity**：去重键是五格（type / title / 两个 scope / sensitivity），
+    //    这里只有四格，少了 sensitivity 那一格，见下面「刻意更宽」那条；
+    //  · 外来行（isImportedRow）：这一格最容易被「顺手简化」掉。少了它，第二次导入别的
+    //    包时会把上一包别人的原文报成「你库里已经有一条」，existing_id 指向一行他既不能
+    //    改写、在 C4 之前也删不掉的行——撞名读数从「要不要处理我这条」变成「去处理别人
+    //    那条」。
+    // 同键取 list() 默认序（importance DESC, updated_at DESC, id）的第一条：那一行落在去重
+    // 窗口里时，就是 saveWithDedupe 会挑中的并入目标，报出来的 id 因此是「假如允许并入会被
+    // 吃掉的那一条」，不是随便一条同名行。但**这不是与去重等价的集合**，是刻意更宽的报法，
+    // 两处差别都要写明免得日后被读成等价：去重只扫 `store.list({type, limit: 100})` 那个窗口
+    // （第 101 条以后的同名行它根本看不见，我们扫全库），并且多比一格 sensitivity（同名同
+    // scope 而敏感度不同的两条，去重会各建一行、我们照样报撞名）。方向是安全的：宽的一侧只
+    // 会多报，漏报才是「收件人看不见这条」那种要命的形状。读的时候按「这里报的都是真同名
+    // 行」，别按「dedupe 会吃的就是这些行」。
+    // 标题两侧 trim，与去重那侧的 title.trim() 同一把尺。最后还有一处对照根本不成立，记下
+    // 免得日后又被拼回等价：dream summary 那一支的键是 source、narrative 那一支（src/service.js:1405-1410）
+    // 的键是 tags[0]，两种行的「假如允许并入」目标跟这里的「同名第一条」不是同一格东西。
+    const ownByKey = new Map();
+    for (const m of store.list({ limit: null })) {
+      if (m.archived || isImportedRow(m)) continue;
+      if (scopeKeyOf(m.agent_scope) || scopeKeyOf(m.workspace_scope)) continue;
+      const key = `${m.type}\u0000${String(m.title).trim()}`;
+      if (!ownByKey.has(key)) ownByKey.set(key, m.id);
+    }
+    const importBatch = () => {
+      let created = 0;
+      let skippedExisting = 0;
+      let unchanged = 0;
+      const conflicts = [];
+      for (const entry of pack.memories) {
+        const existing = store.getByShareExternalId(entry.external_id);
+        if (existing) {
+          skippedExisting++;
+          // unchanged 比的是「同一把尺的两端」，而这两端本来就可能合法地不同：包里的锚是
+          // 发送方**遮之前**的归一化哈希（决策 4），库里这一格是收件人按自己收到的字节
+          // 重算的 store 哈希，两侧各自遮自己那台机器的 home 前缀。所以这个数**只是给人
+          // 看的读数，绝不许当动作依据**——拿它决定「这条不用导入」就是个 bug；要不要建
+          // 这条行，只看上面那格 share_external_id。
+          if (typeof existing.content_hash === "string" && existing.content_hash === entry.content_hash) unchanged++;
+          continue;
+        }
+        const key = `${entry.type}\u0000${String(entry.title).trim()}`;
+        if (ownByKey.has(key)) conflicts.push({ type: entry.type, title: entry.title, existing_id: ownByKey.get(key) });
+        if (dryRun) { created++; continue; }
+        // created_at / content_hash 不在传参里：这两格由 store 铸造（spec §5 记的三个事实
+        // 前两条），包里那两个值只作给人看的时间感与发件侧自证的锚。
+        const row = store.save({
+          type: entry.type,
+          title: entry.title,
+          content: entry.content,
+          // 只追加一个来源标签，包里的标签原样带过来；Set 去重是防发件人本来就带了一个
+          // 一模一样的标签（那样面板上会出现两条同名标签，读起来像系统写了两次）。
+          tags: [...new Set([...(Array.isArray(entry.tags) ? entry.tags.map(String) : []), tag])],
+          importance: Number.isInteger(entry.importance) ? entry.importance : 3,
+          epistemic_status: entry.epistemic_status,
+          source: IMPORTED_SOURCE,
+          agent_scope: null,
+          workspace_scope: null,
+          share_pack_id: pack.pack_id,
+          share_external_id: entry.external_id
+        });
+        // 排队而不是当场嵌：这里在事务里，txDepth>0，scheduleEmbed 入队、由 transaction()
+        // 提交后 drain。别改成「事务外再补一遍」——那是 #372 与 distill-tx-embed-gap 修过
+        // 两次的形状。
+        scheduleEmbed(row);
+        created++;
+      }
+      return { created, skippedExisting, unchanged, conflicts };
+    };
+    // 干跑不裹 transaction()：那一层的 finally 会 syncMirror() + notifyWrite()。一次没写
+    // 任何东西的预览，不该把整面镜像重渲染一遍，更不该告诉睡眠调度器「库刚变过」——那
+    // 一下会把空闲计时器重置，压掉她本来该做的一轮巩固。剩下的全是只读查询，不需要 BEGIN。
+    const result = dryRun ? importBatch() : transaction(importBatch);
+    return {
+      pack_id: pack.pack_id,
+      // alias 对面自报，可以是空串；缺格（手改包）时补空串而不是 undefined——这两张皮的
+      // 答复会被 JSON.stringify，undefined 的键直接消失，面板就分不清「匿名」与「没读到」。
+      alias: typeof pack.alias === "string" ? pack.alias : "",
+      created: result.created,
+      skipped_existing: result.skippedExisting,
+      unchanged: result.unchanged,
+      // title_conflicts 是 advisory 读数，**不是「没有撞名」的证明**：撞名只对本轮真正会新建
+      // 的那些条目判（skipped_existing 那一支直接 continue，不再比），所以空数组只说明「这一批
+      // 里没有新的撞名要报」。conflicts_checked 同样是包里的条数而不是比过的条数——第二次导入
+      // 同一个包时这一格恒空，而撞名在库里物理存在。对面文案别写成「现在没有冲突」。
+      title_conflicts: result.conflicts,
+      conflicts_checked: pack.memories.length
+    };
+  }
+
+  /**
+   * 整包退出（spec §5）。**物删不归档**（裁定与理由都记在这儿，免得日后被读成手滑）：
+   * 归档行仍占着 share_external_id 的 UNIQUE 位，会造成「撤了却导不回来」的死角——那个
+   * 形态比多删更坏，而原始包还在分享者手里，随时能重导。
+   * 本方法与 reclaim 的「一条记忆都不删」哲学相反：那是自动回收面（没人点头，删了就找不
+   * 回来），这是人显式按下的一次撤销——他刚说过「这批不是我的」，留着才是替他做决定。
+   *
+   * 寻址键只有 `share_pack_id` 一个：外来行由本模块铸造（source='imported' + 两列），
+   * 全仓别处都不写这两列，所以「按包删」与「只删外来行」今天等价。哪天有人给本地行也
+   * 盖上 share_pack_id，这条等价就破了——那时要收窄的是 store 那一侧的 WHERE，不是这里
+   * 补一层 filter（补了会让清点与实删分家，见下面 deleted 为什么取 store 的数）。
+   *
+   * 裹 `transaction()` 而不是裸调 `store.deleteBySharePackId`：后者内部有 runAtomically，
+   * 而它在 db.isTransaction 为真时直接跑回调（src/store.js 的 runAtomically 首行），所以
+   * 嵌套安全；换来的是 transaction 的 finally 把 syncMirror + notifyWrite 各做一次——
+   * 退出必须让面板、镜像与做梦调度器同时知道这批行没了。什么都没删时**不进**事务：
+   * 一笔空删除既不该重渲染镜像也不该把空闲计时器顶回去（与 importSharePack 的干跑同一条
+   * 理由）。
+   *
+   * @param {string} packId 要收起的包；非字符串 / 空白 / 没导入过都答 0，不抛
+   * @param {{dryRun?: boolean}} [opts] dryRun 只清点不删，答复同形状
+   * @returns {{pack_id: string, deleted: number, sample: Array<{type: string, title: string}>}}
+   */
+  function deleteSharePack(packId, { dryRun = false } = {}) {
+    const id = typeof packId === "string" ? packId.trim() : "";
+    if (!id) return { pack_id: "", deleted: 0, sample: [] };
+    // 清点与实删读的是同一个 store 方法（listBySharePackId 不过滤 archived/forgotten：
+    // 那两个面也要一起收走，否则库里留下「来自一个已经收起的包」的行）。sample 取前
+    // DELETE_SAMPLE_MAX 条给人核对「我要收起的到底是哪一批」——listBySharePackId 的序是
+    // updated_at DESC, id DESC，所以报出去的是他最近看过的那几条。
+    const rows = store.listBySharePackId(id);
+    const sample = rows.slice(0, DELETE_SAMPLE_MAX).map((m) => ({ type: m.type, title: m.title }));
+    if (dryRun || !rows.length) return { pack_id: id, deleted: rows.length, sample };
+    // deleted 取 store 的 changes 而不是 rows.length：上面那次清点是只读快照，而
+    // deleteBySharePackId 在**它自己的事务里重新读一遍 id**——两个宿主共用同一 memoryDir
+    // 时（AGENTS.md 的那台机器两条腿），别人在我们清点之后往同一个包里补写的行会一起被删
+    // （它不在 sample 里），我们清点到的行也可能已被别人删掉（它数不进 changes）。报实删的
+    // 数才是诚实的那一个：sample 是清点时的预览，deleted 是这一笔真的带走了几行，并发下
+    // 两者可以差一条，谁也不许拿对方的数当「漏删/多删」的依据。
+    const deleted = transaction(() => store.deleteBySharePackId(id));
+    return { pack_id: id, deleted, sample };
+  }
+
+  return { importSharePack, deleteSharePack };
+}

package/lib/share.js

@@ -0,0 +1,335 @@
+// 记忆分享包的纯核心：取行口径、脱敏、序列化。
+// 本模块不认识 store、不认识 http，也不读 config —— 两侧出口（宿主内面板路由与
+// standalone Bearer 数据面）共用的解析与答复在 share-http.js，#411 的教训是这两张皮
+// 只许剩鉴权与路径不同。
+// 唯一进来的外部判据是两个纯函数（write-admission 的空白/噪声、sensitive-scan 的
+// 密钥/PII）：判据只许有一份，所以这里 import 而不是重抄，代价是模块图会连带把
+// store 模块**加载**进来（write-admission → service → store）—— 加载不等于使用，
+// 本模块不调它任何一个方法，也不碰 config。
+import { createHash, randomBytes } from "node:crypto";
+import { informationlessReason } from "./write-admission.js";
+import { scanSensitive } from "./sensitive-scan.js";
+
+export const SHARE_KIND = "mneme.share/v1";
+
+// 跳过清单的条数上限：面板与 CLI 都要把「为什么这条没进包」摊给人看，但一个
+// 几千条的库不该因此产出一份比包还长的报告。超限就截断，计数仍给全量。
+export const SHARE_SKIP_LIST_MAX = 50;
+
+// 体积水位留在 3 MiB，上限是两侧 readBody 各自写死的 4 MiB（api.js:57、
+// api-standalone.js:31）。留 1 MiB 是给 JSON 包装与接收侧再序列化的余量——
+// 包本身要作为 body 原样 POST 回去，水位贴上限等于给自己埋 413。
+export const MAX_PACK_BYTES = 3 * 1024 * 1024;
+
+// document 是指针行（#296），正文文件不随包走，导出去对面就是「看着有、点开是空」；
+// 与 mirror.js 的 MIRROR_READONLY_TYPES 同口径，但这里刻意写死字面量而不是 import
+// 那个 Set —— 分享格式的兼容面比镜像宽，镜像哪天放开只读 type 不该自动改掉包的口径。
+export const SHARE_READONLY_TYPES = new Set(["document"]);
+export const SHARE_EXCLUDED_TYPES = new Set(["summary"]);
+
+const withoutNul = (value) => String(value ?? "").replace(/\u0000/g, "");
+
+/**
+ * 幂等键：`pack_id \0 type \0 title \0 content_hash`，防 ("ab","c") 与 ("a","bc") 撞同一键。
+ *
+ * 分隔符只保证「字段之间」的切法唯一，所以入参自己的 U+0000 必须先剥掉：不剥的话
+ * ("t","a\0b") 与 ("t\0a","b") 拼出同一串字节，对面重算时把这条当成「已经吃过」，
+ * 于是该建的行静默不建（串号是幂等表上最难查的那类 bug，没有报错）。剥完 `"a\0b"` 与
+ * `"ab"` 同键——这与既有的 trim 是同一类归一（丢字节换切法唯一），不是新开的口子。
+ * 归一写在这里而不是各调用方：铸造侧（本模块）与重算侧（车道 C）必须共用一份口径，
+ * 两份实现各自归一迟早漂。除 U+0000 外不动别的字节，trim 口径照旧 —— 归一规则一变，
+ * 已发出去的包里每个 external_id 都对不上。
+ *
+ * 第四格是内容锚，不是装饰：库里的去重键含 `content_hash`（store.js:1233），所以同 type
+ * 同 title、正文不同的两条是两条合法记忆。键里没它时两条铸出同一个 external_id，收侧
+ * 「先查后跳过」把第二条当成已吃过而静默不建，而包里的 `report.included` 已经说了 2 ——
+ * 说谎的是这份账。缺锚的行（store 没算过）与 `null` 都归一成 `""`：JSON 里没有 undefined，
+ * 重算侧只会看到 null，两者不许铸出两个键。
+ */
+export function deriveExternalId(packId, type, title, contentHash) {
+  const parts = [withoutNul(packId), withoutNul(type), withoutNul(title).trim(), withoutNul(contentHash)];
+  return createHash("sha256").update(parts.join("\u0000"), "utf8").digest("hex").slice(0, 16);
+}
+
+const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * 把正文里的本机 home 前缀换成 `~`。
+ *
+ * 判据是**分隔符游程**，不是几种固定拼法：把 base 按 `[/\\]+` 切成段，再用 `[/\\]+`
+ * 拼回一条正则（段间至少一个分隔符、个数不限）。于是同一目录的所有写法——单反斜杠、
+ * 正斜杠、JSON 里转义过的双反斜杠、混合、二次编码——都走同一条判据。上一版按
+ * base / 单反斜杠 / 双反斜杠三个固定形态匹配，混合与二次编码照样漏，而「按拼法打补丁」
+ * 的失败方式是永远漏下没列到的那一种，漏出来的正是用户名。
+ * 大小写不敏感：盘符与用户目录在真实路径里的大小写常常和 homedir() 不一致。
+ * 已知代价：游程要求段间**至少一个**分隔符，所以段间没有分隔符的写法（`C:Users`）不
+ * 命中——上一版按三个固定形态匹配时同样不命中，游程在这一格既没放宽也没收窄。那已经不是
+ * 同一目录的拼法（Node 与 JSON 都不产它），要命中只能把前缀约束整个拆掉，而那侧错的方向
+ * 是泄露。
+ */
+export function createHomeRedactor(homeDir) {
+  // 尾分隔符先剥：留着它就成了末段空串，拼出的游程把「正文必须带尾分隔符」写进判据，
+  // 没带的那个反而漏。全由分隔符组成的 home（`//`）剥完即空，走 identity 出口——
+  // 否则正则会把正文里的斜杠吃成 `~/`，把内容改花。
+  const base = (typeof homeDir === "string" ? homeDir.trim() : "").replace(/[/\\]+$/, "");
+  if (base.length < 2) return (text) => String(text ?? "");
+  const re = new RegExp(`${base.split(/[/\\]+/).map(reEsc).join("[/\\\\]+")}[\\\\/]?`, "gi");
+  // 折掉的只有「前缀 + 紧跟着的那一个分隔符」，输出统一成读者与对面 agent 都认的 `~/`；
+  // 后面的路径按原样留着——改写用户写下的字节是另一类事故。前缀落在句尾时不补分隔符。
+  return (text) => String(text ?? "").replace(re, (m) => (m.endsWith("\\") || m.endsWith("/") ? "~/" : "~"));
+}
+
+/**
+ * 一条记忆进不进包。顺序是刻意的：先状态位（archived/forgotten），再类型，
+ * 再判据 —— 空白与噪声先于敏感判定，因为一条内容为空的记忆没有可泄露的东西，
+ * 把它记成 sensitive 会让跳过清单的读数说错原因。
+ *
+ * 「空白/噪声」这一级不自建判据：复用 informationlessReason（write-admission.js:117），
+ * 它的口径是 title+content 的**组合**判定 —— 两侧归一后都不剩字才命中（"blank" 全空、
+ * "noise" 只剩标点/空白）。组合口径管的是「这条写入有没有信息」，分享边界要问的是另一个
+ * 问题：对面能不能吃下这一条。所以这里另外补一刀「正文 trim 后为空」（见函数内注释）。
+ *
+ * 跳过的分支也返回脱敏后的 title：跳过清单不只在本机看 —— 打包侧把它原样写进
+ * pack.report.skip_list，CLI 再整份打到终端（车道 A3/A7 的口径），而 413 那次拒发
+ * 仍带着同一份 report 出去（src/share-http.js）。未遮的 title 等于把用户名装进这份
+ * 「设计上不含它」的文件，而泄露面最大的恰恰是不进包的那几条。所以在源头遮，每个
+ * 消费方拿到的都是安全字符串；下游不需要、也不该再各补一刀。遮的仍是同一个 redact，
+ * 本模块只有这一条脱敏路径。
+ *
+ * 但「遮过 home」不等于「可以外发」：一条被密钥判据认中的行，它的**标题**常常就是
+ * 那条凭据的回声（最终评审的复现：标题「生产库密码 P@ssw0rd-for-prod-db 别丢」+ 正文
+ * `password: …`，被跳过原因是 archived）。规则表只认「关键词 + 赋值号 + 值的形状」，
+ * 单看这一串标题它并不命中 —— 所以这里判的是**整行**含不含凭据，命中就连带标题一起
+ * 不给：正文不发的那条，它的标题也不该跟着包走。留空而不是给摘要/哈希：skip_list 随包
+ * 外发，一个哈希是递给收侧的离线爆破 oracle，而低熵口令正是这类行最常见的内容。
+ * 方向上的代价只有「少看得见一条标题」，计数仍给全量。
+ *
+ * 因此扫描面在判序**之前**算一次（原因归属仍按下面的判序，空白照旧先于敏感）：代价是
+ * 归档行也进扫描，不再是「进包候选 + 敏感命中」那一小撮。量级没变 —— 整库逐条扫描实测
+ * 98 ms（docs/SHARE.md），而这条路径本来就要付一次全表读（同处约 1.1 s）。
+ */
+export function classifyRowForShare(row, { redact = (t) => t } = {}) {
+  const title = redact(row?.title ?? "");
+  // 扫描面用 `scanSensitive` 这个「任意文本」口径的导出，不用带开关的那个工厂面：
+  // 工厂在 sensitiveScanEnabled 关时返回 null（sensitive-scan.js:199），而那个键管的是
+  // **写入侧**可观测性。分享边界本身就是安全边界（spec §4）——用户没开写入闸门时
+  // 恰恰最需要这里照常在扫，跟着开关走等于裸发整库。
+  const scanned = scanSensitive([row?.title, row?.content, ...(Array.isArray(row?.tags) ? row.tags : [])]
+    .filter((s) => typeof s === "string").join("\n"));
+  const skipTitle = scanned ? "" : title;
+  if (row?.archived) return { include: false, reason: "archived", title: skipTitle };
+  if (row?.forgotten) return { include: false, reason: "forgotten", title: skipTitle };
+  if (SHARE_READONLY_TYPES.has(row?.type)) return { include: false, reason: "readonly_type", title: skipTitle };
+  if (SHARE_EXCLUDED_TYPES.has(row?.type)) return { include: false, reason: "excluded_type", title: skipTitle };
+  // 正文 trim 后为空即算空白，这一格 `informationlessReason` 够不着：它判的是 title+content
+  // 的**组合**（两侧归一后都不剩字才命中），所以「标题有字、正文一片空白」在它眼里是有信息
+  // 的。上一版据此让那条进包，判据本身没错，错在出口：收侧的 `content` 列 NOT NULL，车道 C
+  // 还按 spec §5 逐条校验非空，一条空正文不是少发一条而是**把整包毒掉**（校验不过 → 什么都不
+  // 导入，对面拿着一个报错的包不知道差在哪一条）。这里不开第七个原因键：六个键被 docs/SHARE.md
+  // 的表、CLI 的档位名与本文件的计数三方钉死，多一个就是第四份要跟着改的口径；而「这条不该进包」
+  // 的原因确实就是「它没有正文」，同一格读数不撒谎。
+  if (!String(row?.content ?? "").trim() || informationlessReason(row)) {
+    return { include: false, reason: "blank_or_noise", title: skipTitle };
+  }
+  // 命中判据时标题恒为空串，与「这条压根没标题」同一个出口形状（下游只看到字符串）。
+  if (scanned) return { include: false, reason: "sensitive", title: "" };
+  const content = redact(row?.content ?? "");
+  return {
+    include: true,
+    row: {
+      type: row.type,
+      title,
+      content,
+      tags: (Array.isArray(row.tags) ? row.tags : []).map((t) => String(redact(t))),
+      importance: Number.isInteger(row.importance) ? row.importance : 3,
+      epistemic_status: row.epistemic_status ?? "subjective",
+      created_at: row.created_at ?? null,
+      updated_at: row.updated_at ?? null,
+      // 这一条是**发送方库里的内容锚**，原样带过去只作引用，不是完整性凭证，别拿它
+      // 校验「正文没在路上被改」（车道 C 注意）。两处对不上：① 它由 store 从**未脱敏**
+      // 的 title/content 派生（store.js:1160 → contentHashOf，content-hash.js:49-53），
+      // 而包里的 content/title 是遮过的——所以只要 home 遮过一次，两者就必然不一致，
+      // 恰恰是遮过的那几条对不上；② 它算的是归一化后的文本（NFKC → 小写 → 去标点 →
+      // 空白折叠），对面按收到的字节重算 sha256 本来就得不到同一个值。真要做传输完整性
+      // 校验，得对遮后的字节另派一把新字段，不是复用这一把。
+      content_hash: row.content_hash ?? null
+    }
+  };
+}
+
+/**
+ * filters 一个键的形状归一：→「任一命中」的集合，或 null（= 没填，不收窄）。
+ * type 与 tag 共用这一份判据（裁定：两者同形）。三条理由，方向各不同：
+ * - 裸字符串与数组都算收窄。出口把 `--type` / `--tag` 给成串还是数组不由这里决定
+ *   （单旗标给串、重复旗标与面板多选给数组都说得通），只认一种就是把另一种读成「没筛」
+ *   = **放行整库**，而她以为只发了一类。多值取「任一」，与 type 原本用的集合口径一致。
+ * - 空数组与只剩空白的条目算「没填」：清空勾选不等于要一个空包，读成「筛成 0 条」是替
+ *   她说谎。同一次调用不该因为出口给串还是给数组而读出两种结果。
+ * - 认不出的条目（非字符串）留在集合里 → 谁都不匹配 → 收窄到 0 条。这一侧错的方向是
+ *   **少发**，report 与 stdout 当场看得见；「认不出就当没填」才是把整库发出去。
+ */
+function shareFilterSet(value) {
+  if (value === undefined || value === null) return null;
+  const kept = [];
+  for (const item of Array.isArray(value) ? value : [value]) {
+    if (typeof item !== "string") { kept.push(item); continue; }
+    const trimmed = item.trim();
+    if (trimmed) kept.push(trimmed);
+  }
+  return kept.length ? new Set(kept) : null;
+}
+
+/**
+ * 打包。顺序是刻意的：过滤 → 逐条定性 → 用**进包的那对值**铸 external_id → 序列化 → 量字节。
+ *
+ * 水位量的是**最终序列化字节**，不是条数也不是字符数：这份包要原样当 body POST 回
+ * 对面（车道 C），而中文字符数与 UTF-8 字节数差三倍，按字符数判等于把 413 留给对面；
+ * 按条数判则对「条少但每条很长」的库说谎，那种包照样过大。字节只能在 JSON 写完之后再量，
+ * 所以这里没有「先算大小再决定装几条」的分支。
+ *
+ * 超限**不裁条目**：裁到哪一条是替分享者做「哪条可以不发」的判断，而这份判断该由她自己
+ * 用 filters 分批来做（spec §4 决策 5）。所以只拒绝，并把量到的 bytes 与 limitBytes 一起
+ * 交回，让出口能说出「大了多少、怎么分批」。
+ *
+ * filters 是分享者的显式收窄，**不进跳过计数也不进清单**：那份账要说的是「本可以发、
+ * 因为口径没发」，把她自己筛掉的记进去，读数就把她指向错的那一类。所以两个判据都排在
+ * classifyRowForShare **之前**——这一条顺序是测试锁住的（把过滤挪到定性之后就多说几条
+ * 她没跳过的行），别当成可读性优化来「合并条件」。
+ *
+ * skip_list 截到 SHARE_SKIP_LIST_MAX，skipped 的六个计数仍走全量——截的是清单不是账。
+ * 清单里的 title 用 classifyRowForShare 返回值原样写入：它已在源头遮过 home，命中密钥
+ * 判据的那几条也已在源头留空（标题是凭据的回声，而这份清单随包外发）。这里补第二刀
+ * 是「两个口径」的开始，不是更安全。
+ *
+ * `report.deduped`：同一份包里铸出同一把 `external_id` 的行只发一条。键是
+ * `(pack_id, type, title, content_hash)`，**没有 scope**，而库里同 type 同标题同内容锚、
+ * scope 不同的两条是合法的两行（store.js:1233 的去重键带 agent/workspace/sensitivity
+ * 三维）——所以「两条不同记忆铸出同一个键」是常态，不是畸形数据。为什么在出包侧折叠：
+ * ①对面那台库没有 scope 这一维（包里就不带它），这两条到对面就是同一条记忆，正文与
+ * 标题逐字节相同，发两份只是让她多两行一样的东西；②不折叠的后果不是重复而是**整包失败**
+ * ——车道 C 的 `share_external_id` 是 UNIQUE 索引，第二条 INSERT 抛错会穿出 runAtomically
+ * 的 ROLLBACK 把整包带走（spec §5 明写「先查管常规重复导入、UNIQUE 管并发」，可同一个包
+ * 内部的两条先查谁都查不到，因为那时一行都没落）。「重跑就 created=0」救不了它：重跑吃的
+ * 是同一个死键。方向上的代价只有少发一条重复正文，`included` 因此是**实际发出的条数**，
+ * 折叠掉的数在 `deduped` 里，两份账相加才是「够格进包的行数」。
+ */
+export function buildSharePack({
+  rows, alias = "", homeDir, packageVersion, filters = {},
+  packId = randomBytes(8).toString("hex"), generatedAt = new Date().toISOString()
+} = {}) {
+  const redact = createHomeRedactor(homeDir);
+  const wantedTypes = shareFilterSet(filters.type);
+  const wantedTags = shareFilterSet(filters.tag);
+  const skipped = { archived: 0, forgotten: 0, readonly_type: 0, excluded_type: 0, blank_or_noise: 0, sensitive: 0 };
+  const skipList = [];
+  const memories = [];
+  // 折叠过的键（见模块头那段 `report.deduped` 的理由）。用 Set 而不是再查一次 memories：
+  // 一个包几千条，`some` 会变成平方。
+  const shipped = new Set();
+  let deduped = 0;
+  for (const source of Array.isArray(rows) ? rows : []) {
+    // 两条判据都在定性之前（见上文：筛掉的不是跳过的，一次都不许进那份账）。
+    if (wantedTypes && !wantedTypes.has(source?.type)) continue;
+    if (wantedTags && !(Array.isArray(source?.tags) ? source.tags : []).some((t) => wantedTags.has(t))) continue;
+    const verdict = classifyRowForShare(source, { redact });
+    if (!verdict.include) {
+      skipped[verdict.reason] = (skipped[verdict.reason] ?? 0) + 1;
+      if (skipList.length < SHARE_SKIP_LIST_MAX) skipList.push({ title: verdict.title ?? "", reason: verdict.reason });
+      continue;
+    }
+    // 键的四个入参一律取自 verdict.row，不是 source：收侧是按包内字节重算的（spec §5），
+    // 铸造侧多吃一个遮之前的字节，对面就判成手改包而整包拒绝。内容锚同理——它是发送方
+    // 遮之前的归一化锚（决策 4），但**包里的 content_hash 就是这一个值**，重算吃得准。
+    const externalId = deriveExternalId(packId, verdict.row.type, verdict.row.title, verdict.row.content_hash);
+    // 同键的第二条不发（见模块头）：留第一条，字节层面两条本就同文同题同锚。
+    if (shipped.has(externalId)) { deduped += 1; continue; }
+    shipped.add(externalId);
+    memories.push({ external_id: externalId, ...verdict.row });
+  }
+  const pack = {
+    kind: SHARE_KIND,
+    pack_id: packId,
+    alias: typeof alias === "string" ? alias.trim() : "",
+    generated_at: generatedAt,
+    source_version: String(packageVersion ?? ""),
+    report: { included: memories.length, deduped, skipped, skip_list: skipList },
+    memories
+  };
+  const bytes = Buffer.byteLength(JSON.stringify(pack), "utf8");
+  if (bytes > MAX_PACK_BYTES) {
+    return { ok: false, error: "too-large", pack, bytes, limitBytes: MAX_PACK_BYTES };
+  }
+  return { ok: true, pack, bytes };
+}
+
+// 车道 A 铸 pack_id 用的是 randomBytes(8) 的 hex，16 位；接收侧按这个形状判。
+// 本行不是抄文档：spec §3 初稿写过 12 位，按它校验会把每一个真包拒掉。
+export const PACK_ID_RE = /^[0-9a-f]{16}$/;
+
+// 能入库的类型 = TYPE_FILE 的键集减去两个不随包走的排除项。这里重述一份而不是
+// import mirror 的表，与 SHARE_READONLY_TYPES 同一理由：包的兼容面比镜像宽，
+// 镜像哪天放开某个类型不该自动扩大接收侧的入库范围。形状由测试静态锁比对防漂。
+// 耦合是双向的：出包口径不看 MIRROR_EXCLUDED_TYPES——某类若进了那个集合却没人对本表
+// 做过决定，它照样随包发出、却在收侧把**整包**毒掉（invalid-type 是整包拒绝）；
+// test/share-validate.test.js 的静态锁（直接 Object.keys(TYPE_FILE)）正是让这类
+// 不匹配当场转红、而不是静默发生的仪器。
+export const SHARE_ALLOWED_TYPES = new Set([
+  "preference", "project", "decision", "history", "pitfall", "constraint", "rejected_solution", "pattern"
+]);
+
+// 上限管的是**成品标签**而不是别名片段：这个串要落进 tags 列并在面板上原样显示，
+// 别名是对面自报的任意字符串，不封顶等于让她决定我们这里的字段长度。前缀 `from-`
+// 也算在内，所以别名实际吃到的是 32-5=27 个字符。
+const IMPORTED_TAG_MAX = 32;
+
+/** 外来行的来源标签。别名是分享者自报的自由字符串，在这里被压成一条安全标签；
+ *  空别名走中性值，绝不拿对面的机器身份（用户名、路径）兜底。 */
+export function importedTagFor(alias) {
+  // 整类空白（含换行与制表符）**一条规则**：游程折成一个 "-"。上一版删 \r\n\t、折其余
+  // 空白——同一字符类开两条规则，而删除那侧恰恰制造 "a\nb" 与 "ab" 的同标签碰撞，
+  // 还从收件人实际看得见的来源读数里擦掉词缝。「标签必须单行」两个行为都满足，不构成
+  // 区分理由；仓库先例是 mirror.js 的 oneLine()：只折不删。
+  // trim 排在折叠**之前**：全空白的别名折叠后会剩一个 "-"，于是拿到 `from--` 而不是
+  // 中性值——「空别名走 from-shared」这条契约就漏在半空白那种写法上。
+  const flat = String(alias ?? "").trim().replace(/\s+/g, "-");
+  if (!flat) return "from-shared";
+  return `from-${flat}`.slice(0, IMPORTED_TAG_MAX);
+}
+
+/**
+ * 整包校验。返回第一个不合格项就停：半途入库是最难复盘的失败，而「哪一条不合格」
+ * 对发送方已经足够（index + 一个码）。
+ *
+ * 判序也是契约的一部分（出口按码映射 400，不看码之外的次序）：包级三格先判，因为
+ * 它们决定逐条判据有没有意义；条目内「类型 → 标题 → 正文」排在重算之前，因为一条
+ * 空白正文无论键对不对都不该入库——把它记成 external-id-mismatch 会把人指向「包被改
+ * 过」，而真正的问题是那条本身没内容。
+ */
+export function validateSharePack(pack) {
+  if (!pack || typeof pack !== "object" || Array.isArray(pack)) return { ok: false, error: "invalid-kind" };
+  if (pack.kind !== SHARE_KIND) return { ok: false, error: "invalid-kind" };
+  if (typeof pack.pack_id !== "string" || !PACK_ID_RE.test(pack.pack_id)) return { ok: false, error: "invalid-pack-id" };
+  if (!Array.isArray(pack.memories)) return { ok: false, error: "invalid-memories" };
+  if (!pack.memories.length) return { ok: false, error: "empty-pack" };
+  const seen = new Set();
+  for (let index = 0; index < pack.memories.length; index++) {
+    const m = pack.memories[index];
+    if (!m || typeof m !== "object") return { ok: false, error: "invalid-entry", index };
+    if (!SHARE_ALLOWED_TYPES.has(m.type)) return { ok: false, error: "invalid-type", index, detail: String(m.type ?? "") };
+    if (typeof m.title !== "string" || !m.title.trim()) return { ok: false, error: "invalid-entry", index, detail: "title" };
+    if (typeof m.content !== "string" || !m.content.trim()) return { ok: false, error: "invalid-entry", index, detail: "content" };
+    if (m.tags !== undefined && !Array.isArray(m.tags)) return { ok: false, error: "invalid-entry", index, detail: "tags" };
+    if (m.importance !== undefined && !Number.isInteger(m.importance)) return { ok: false, error: "invalid-entry", index, detail: "importance" };
+    // 16 位这个长度与 PACK_ID_RE 相同是巧合，不是同一份契约：pack_id 是 randomBytes(8)
+    // 的 hex，这一把是 sha256 的前 16 位（deriveExternalId）。写成两个正则是为了让
+    // 「哪天只把包 id 加长」不会顺手改掉这里的判据。
+    if (typeof m.external_id !== "string" || !/^[0-9a-f]{16}$/.test(m.external_id)) return { ok: false, error: "invalid-entry", index, detail: "external_id" };
+    // 四个入参与铸造侧逐字对齐，缺锚归一成 null 而不是跳过这一格：少了第四格时，同标题
+    // 不同正文的两条会重算出同一个键，第二条被判成「包被人改过」——而它恰恰没被改。
+    const expect = deriveExternalId(pack.pack_id, m.type, m.title, typeof m.content_hash === "string" ? m.content_hash : null);
+    if (expect !== m.external_id) return { ok: false, error: "external-id-mismatch", index };
+    if (seen.has(m.external_id)) return { ok: false, error: "duplicate-external-id", index };
+    seen.add(m.external_id);
+  }
+  return { ok: true, pack, count: pack.memories.length };
+}