@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/lib/session-file-name.mjs

@@ -1,160 +1,176 @@
-// DSH / tools/lib/session-file-name.mjs —— 会话日志文件名判据 · **单一真源**（零依赖）
+// 会话日志文件名：认得哪几个世代、以及从名字里读出代际（零依赖的单一真源）。
 //
-// 背景（2026-09-24 · 卡「三机同步步A-V3代际适配」）：
-//   主包 0.1.5 起把会话日志改名 `session.jsonl.zstd` → `session.v3.jsonl.zstd`；
-//   主包 0.2.x 起**再换代** `session.v3.jsonl.zstd` → `session.v4.jsonl.zstd`（**现行世代**）。
-//   （2026-10-16 · 卡「harness · 成本与路由 · 债 D-1/D-3 收口」把**写入侧常量与文案**一并推到 v4；
-//     读取侧判据本已认任意 vN，未动。真源 = 本文件。）
-//   凡是「按精确文件名比较」的**读取侧**判据都会整条失明（实测 pitfall-scan 的
-//   discoverSessionFiles() 活跃树覆盖 0 / 212），而归档里仍有 1040 个旧名文件、
-//   活跃树 212 个全是 v3 名 ⇒ 读取侧必须**认全世代**。
+// 文件名换过好几代：旧的是 `session.jsonl.zstd`，后来加了版本号 `session.vN.jsonl.zstd`，
+// 当前写入侧写的是 v4。归档树里旧名的文件还成堆躺着，活跃树里又都是新名 ——
+// 只要有一处判据写成"精确比较当前文件名"，那一处就对着另一半文件整条失明。
 //
-// 三条口径（写死，别自由发挥）：
-//   ① 读取侧一律用 isSessionFileName() / sessionFileGeneration()（前缀 + 代际），**禁精确字符串比较**；
-//   ② 需要"代际"时从文件名提取（旧名 = 0，`session.vN....` = N），**禁硬编码**；
-//   ③ 写入侧（真要写文件名时）用 SESSION_FILE_NAME_CURRENT（当前世代 = v4，0.2.x 起）。
+// 三条规则（写死，别临场发挥）：
+//   ① 读取侧一律走 isSessionFileName() / sessionFileGeneration()：前缀 + 代际，认出任意 vN，
+//      以后换代也不用回来改判据；
+//   ② 需要"第几代"就从文件名里提取（旧名 = 0，`session.vN...` = N），不要在调用处硬编码；
+//   ③ 写入侧真要落文件名时用 SESSION_FILE_NAME_CURRENT。
 //
-// ⚠️ PowerShell 侧无法 import 本模块：`tools\dsh-backup-sessions.ps1` 内写等价 PS 判据
-//   （$SessionFileFilter / Test-SessionFileName / $SessionFileNameCurrent）。**改一处必须同步另一处。**
-//   已知同类读取侧判据（**★2026-09-24 收尾清账批逐处核实后重写**，原清单两处已修、又漏了一族）：
-//   ✅ 已消费本模块：tools\lib\attach-refs.mjs · tools\board-ops\session-tail.mjs · tools\dsh-sessions-land.mjs ·
-//      tools\dsh-butler\{session-ledger.mjs, lib\pitfall-scan.mjs, lib\session-header.mjs, lib\restart.mjs} ·
-//      tools\archive-card-sessions.mjs · tools\archive-inactive-sessions.mjs · tools\dsh-archive-sessions\lib\index.js ·
-//      tools\dsh-butler-panel\lib\state.js（★A2：判据 +「取哪份」取法一并统一；checks.mjs 经它复用，无第二份实现）。
-//      ⚠️ restart-coordinator.mjs **无自有判据**（经 lib\restart.mjs#scanSessionLogFiles 间接同源）——原清单点名它属误记。
-//   ⏳ 仍**只认旧名**的读取侧（低频/一次性工具，待各自 owner 认领；行号 = 2026-09-24 快照）：
-//      tools\dsh-archive-sessions\{clean-empty-shells.mjs:78, scan-empty.mjs:48, scan-small.mjs:57} ·
-//      tools\projcache-restore-archived.mjs:107 · tools\restore-shell-sessions.mjs:76 · tools\test-single-archive.mjs:21 ·
-//      tools\{session-tail-for-llm.mjs:81, session-tail-audit.mjs:96, session-impact.mjs:78, session-cot.mjs:77,
-//      dsh-session-tail-dump.mjs:23}。**要长期用再改**，改法照本文件（认全世代 + 需要代际时提取）。
-//   ⚠️ 已知风险登记（A6 · 2026-09-24 **先登记不修**）：「两代并存」目录里新世代文件可能只是**补写壳**
-//      （实测 v3 仅 2 事件 / 244 B，旧名才是完整对话 2621 事件 / 2.7 MB）⇒ **需要读内容的消费者必须走候选链**
-//      （rankSessionFilesInDir / collectSessionFilesByDir 的 files），只做扫描/移动的取 current 即可。
-//      当前无消费方受影响（面板只扫活跃树：231/231 全 v3、0 并存）；若将来把归档并存目录纳入扫描，先接候选链再开。
-//      （插件包内为**派生副本** `lib/session-file-name.mjs`，由 tools\sync-session-file-name.mjs 生成，
-//        deploy 时 fail-closed 校验副本与真源 sha 一致 —— 改真源必须同批重跑该同步器。）
+// 跨语言提醒：脚本侧（PowerShell 之类）没法 import 本模块，那边有一份等价判据。
+// 改这里必须同批改那边，否则两边会各认一半世代。
+//
+// 另一个已知坑：换代后新世代文件可能只是个"补写壳"（只有会话头一小段），完整对话还在
+// 旧名文件里。所以"当前那份"不等于"内容最全的那份" —— 要读内容的调用方必须把
+// rankSessionFilesInDir / collectSessionFilesByDir 给出的整条候选链走完；只做扫描或
+// 搬迁的调用方取第一个就够。
 import fs from 'node:fs';
 import path from 'node:path';
 
-/** 旧世代文件名（≤ 0.1.1；归档树里仍有大量此名）。 */
+/** 旧世代文件名（更早的版本；归档树里大量存在） */
 export const SESSION_FILE_NAME_LEGACY = 'session.jsonl.zstd';
 
-/** v3 世代文件名（0.1.5 起；**已被 0.2.x 换代**，仍须认得）。 */
+/** 带 v3 的世代名（更早的一次换代；仍必须认得） */
 export const SESSION_FILE_NAME_V3 = 'session.v3.jsonl.zstd';
 
-/** 当前世代文件名（0.2.x 起）。 */
+/** 当前世代文件名 */
 export const SESSION_FILE_NAME_V4 = 'session.v4.jsonl.zstd';
 
-/** 写入侧应使用的当前世代文件名。 */
+/** 写入侧该用的名字（当前世代） */
 export const SESSION_FILE_NAME_CURRENT = SESSION_FILE_NAME_V4;
 
-/** 认得的三个世代名（读取侧清单；顺序 = 旧 → 新）。 */
+/** 全部认得的世代名（顺序 = 旧 → 新） */
 export const SESSION_FILE_NAMES = [SESSION_FILE_NAME_LEGACY, SESSION_FILE_NAME_V3, SESSION_FILE_NAME_V4];
 
-/** 宽匹配模式（shell / robocopy / Get-ChildItem -Filter 用；**读取侧**）。 */
+/** 宽匹配模式：给 shell / 复制工具 / 目录枚举当过滤器用（读取侧） */
 export const SESSION_FILE_GLOB = 'session*.jsonl.zstd';
 
 /**
- * 读取侧判据（前缀 + 代际）。命中的形态：
- *   `session.jsonl.zstd`（旧世代）· `session.v3.jsonl.zstd`（0.1.5 世代）· `session.v4.jsonl.zstd`（当前世代）
- *   · 更高的 `session.vN.jsonl.zstd`（未来世代）—— **本判据认任意 vN，换代时无需改**。
- * 不命中：`session.jsonl`（明文形态，另有判据）· `session.jsonl.zstd.bak` · 其它任意文件。
+ * 读取侧判据：前缀 `session` + 可选的 `.vN` + `.jsonl.zstd`。
+ * 命中：`session.jsonl.zstd` / `session.v3.jsonl.zstd` / `session.v4.jsonl.zstd` / 未来的 `session.v5...`。
+ * 不命中：明文 `session.jsonl`、备份 `session.jsonl.zstd.bak`、以及其它任何文件。
  */
 export const SESSION_FILE_RE = /^session(?:\.v(\d+))?\.jsonl\.zstd$/;
 
-/** 是否会话日志文件（读取侧唯一判据）。 */
+/** 是不是会话日志文件（读取侧唯一判据，别在调用处另写一套） */
 export function isSessionFileName(name) {
   return SESSION_FILE_RE.test(String(name));
 }
 
 /**
- * 从文件名提取代际：旧世代 = 0；`session.vN.jsonl.zstd` = N；非会话文件 = null。
+ * 从文件名读代际：旧名 = 0；`session.vN.jsonl.zstd` = N；不是会话文件 = null。
+ * @param {string} name
  * @returns {number|null}
  */
 export function sessionFileGeneration(name) {
-  const m = SESSION_FILE_RE.exec(String(name));
-  if (!m) return null;
-  return m[1] ? Number(m[1]) : 0;
+  const matched = SESSION_FILE_RE.exec(String(name));
+  if (!matched) return null;
+  return matched[1] ? Number(matched[1]) : 0;
+}
+
+// 目录枚举统一走"可注入的 fs"：测试塞夹具时不必碰真盘
+function ioOf(opts) {
+  return opts?.fs ?? fs;
 }
 
 /**
- * 目录形态的会话文件清单（不递归）。
+ * 列出一个目录里的会话文件（不递归）。
+ * @param {string} dir
+ * @param {{fs?:object}} [opts]
  * @returns {{file:string,name:string,generation:number,bytes:number,mtimeMs:number}[]}
  */
 export function listSessionFilesInDir(dir, opts = {}) {
-  const fsImpl = opts.fs ?? fs;
-  let ents;
-  try { ents = fsImpl.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
-  const out = [];
-  for (const e of ents) {
-    if (!e.isFile()) continue;
-    if (!isSessionFileName(e.name)) continue;
-    const full = path.join(dir, e.name);
-    let st;
-    try { st = fsImpl.statSync(full); } catch { continue; }
-    out.push({
-      file: full, name: e.name, generation: sessionFileGeneration(e.name),
-      bytes: st.size, mtimeMs: Math.round(st.mtimeMs),
+  const io = ioOf(opts);
+  let entries;
+  try {
+    entries = io.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const rows = [];
+  for (const dent of entries) {
+    if (!dent.isFile()) continue;
+    if (!isSessionFileName(dent.name)) continue;
+    const file = path.join(dir, dent.name);
+    let info;
+    try {
+      info = io.statSync(file);
+    } catch {
+      continue; // 枚举与 stat 之间被删掉：跳过，不当异常
+    }
+    rows.push({
+      file,
+      name: dent.name,
+      generation: sessionFileGeneration(dent.name),
+      bytes: info.size,
+      mtimeMs: Math.round(info.mtimeMs),
     });
   }
-  return out;
+  return rows;
 }
 
 /**
- * 同一会话目录内的候选文件，按优先级排序（第一个 = 「当前那份」）：
- *   mtime 最新优先 → 平局取代际大者 → 再平局取名字典序小者（确定性）。
- *
- * ⚠️ **「当前那份」≠「内容最全的那份」**（2026-09-24 实测，卡「修·V3判据④」）：
- *    换代后新世代文件可能只是"补写壳"——归档树 28 个两代并存目录里，`session.v3.jsonl.zstd`
- *    只有 2 个事件（`session` 头 + `session/end-seed`、有效内容 244 B），而旧名文件才是完整对话
- *    （2621 个事件 / 2.7 MB 解压文本）。**需要读内容的消费者必须走完候选链**（见下），
- *    只做"扫描/移动"的消费者取第一个即可。
+ * 同一会话目录里的候选文件，按"先取哪一份"排好序（第一个就是当前那份）：
+ *   mtime 最新 → 平局取代际大的 → 再平局取名字典序小的（最后的平局也要确定，不能靠运气）。
+ * 要读内容时别只看第一个：两代并存时新世代可能只是补写壳，得顺着整条链继续往下看。
  * @returns {{file:string,name:string,generation:number,bytes:number,mtimeMs:number}[]}
  */
 export function rankSessionFilesInDir(dir, opts = {}) {
-  const hits = listSessionFilesInDir(dir, opts);
-  hits.sort((a, b) => (b.mtimeMs - a.mtimeMs) || (b.generation - a.generation) || (a.name < b.name ? -1 : 1));
-  return hits;
+  return listSessionFilesInDir(dir, opts).sort((left, right) => (
+    right.mtimeMs - left.mtimeMs
+    || right.generation - left.generation
+    || (left.name < right.name ? -1 : 1)
+  ));
 }
 
 /**
- * 在一个会话目录里挑出"当前那份"会话文件（两代并存时的取法）：
- *   mtime 最新优先 → 平局取代际大者 → 再平局取名字典序小者（确定性）。
- * @returns {string|null} 绝对路径；目录不存在 / 无会话文件 = null
+ * 挑出"当前那份"会话文件的绝对路径。
+ * @param {string} dir
+ * @param {{fs?:object}} [opts]
+ * @returns {string|null} 目录不存在 / 目录里没有会话文件 → null
  */
 export function pickSessionFileInDir(dir, opts = {}) {
-  const hits = rankSessionFilesInDir(dir, opts);
-  return hits.length ? hits[0].file : null;
+  const [best] = rankSessionFilesInDir(dir, opts);
+  return best ? best.file : null;
 }
 
 /**
- * 递归收集会话目录（**每个目录聚合一次**，不做逐文件扁平化）。
- * 用途：归档器的扫描面 —— 一个会话目录 = 一个会话，两代并存时 `current` 是"当前那份"、
- * `files` 是该目录全部世代（移动校验/尾部判据/内容回落都要用到全量）。
- * @returns {{dir:string, current:string, files:object[]}[]} 按 dir 字典序（确定性）
+ * 递归收集"每个会话目录一条"（不逐文件摊平）。
+ * 用途：归档这类按目录当单位处理的场景 —— current 是当前那份，files 是该目录全部世代
+ * （搬运校验、尾部判据、内容回落都要用到全量）。
+ * @param {string} root
+ * @param {{fs?:object}} [opts]
+ * @returns {{dir:string, current:string, files:object[]}[]} 按目录名字典序（确定性）
  */
 export function collectSessionFilesByDir(root, opts = {}) {
-  const fsImpl = opts.fs ?? fs;
-  const out = [];
-  const stack = [root];
-  while (stack.length) {
-    const d = stack.pop();
-    let ents;
-    try { ents = fsImpl.readdirSync(d, { withFileTypes: true }); } catch { continue; }
-    let hasSessionFile = false;
-    for (const e of ents) {
-      if (e.isDirectory()) { stack.push(path.join(d, e.name)); continue; }
-      if (e.isFile() && isSessionFileName(e.name)) hasSessionFile = true;
+  const io = ioOf(opts);
+  const buckets = [];
+  const pending = [root];
+
+  while (pending.length > 0) {
+    const dir = pending.pop();
+    let entries;
+    try {
+      entries = io.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // 读不动的目录直接跳过（权限/竞态删除），不影响其余
+    }
+
+    const subdirs = [];
+    let holdsLog = false;
+    for (const dent of entries) {
+      if (dent.isDirectory()) {
+        subdirs.push(path.join(dir, dent.name));
+        continue;
+      }
+      if (dent.isFile() && isSessionFileName(dent.name)) holdsLog = true;
     }
-    if (!hasSessionFile) continue;
-    const files = rankSessionFilesInDir(d, opts);
-    if (files.length) out.push({ dir: d, current: files[0].file, files });
+    pending.push(...subdirs);
+    if (!holdsLog) continue;
+
+    const files = rankSessionFilesInDir(dir, opts);
+    if (files.length > 0) buckets.push({ dir, current: files[0].file, files });
   }
-  out.sort((a, b) => (a.dir < b.dir ? -1 : 1));
-  return out;
+
+  buckets.sort((left, right) => (left.dir < right.dir ? -1 : 1));
+  return buckets;
 }
 
-/** 递归收集「每目录当前那份」的绝对路径（collectSessionFilesByDir 的扁平形态）。 */
+/** 递归收集「每个目录当前那份」的绝对路径（collectSessionFilesByDir 的扁平形态） */
 export function collectSessionFilesInTree(root, opts = {}) {
-  return collectSessionFilesByDir(root, opts).map((x) => x.current);
+  return collectSessionFilesByDir(root, opts).map((bucket) => bucket.current);
 }

package/lib/zstd-frames.mjs

@@ -1,78 +1,99 @@
-// zstd-frames.mjs —— zstd 多帧日志「拆帧」的 **CLI 侧唯一源**（严格结构解析）。
+// 多帧 zstd 日志的拆帧器（按帧结构解析，不靠搜魔数）。
 //
-// 用途：会话日志（`session.jsonl.zstd` / `session.v3.jsonl.zstd`）是**多帧**追加写的
-//   —— 一帧 ≈ 一次 flush 的一批事件。要取「尾部 N 帧」或「全部帧」，就得先把多帧缓冲切成逐帧。
+// 会话日志是一个帧接一个帧追加出来的：一帧大约对应一次 flush 的那批事件。
+// 想只取尾部若干帧、或者要逐帧解压，第一步就得把这一整块缓冲切成帧边界。
 //
-// 算法（严格结构解析，**不吃"魔数搜索"那套启发式**）：
-//   ZSTD magic（0xFD2FB528 LE）→ frame header descriptor（含 dictionary / content-size 字段宽度）
-//   → block 循环（block type 3 = reserved ⇒ 断）→ optional 4 字节 checksum；
-//   遇**不完整帧**返回 `tornStart`（该帧起点），**不猜长度、也不把残字节当完整帧**。
-//   对比"魔数搜索 + 游标推进"启发式的两个弱点：
-//     ① 压缩数据里**恰好出现 zstd magic 字节序列**时会把一帧切成两半（本件靠帧结构解析不会）；
-//     ② 多份实现各自演化 ⇒ 一处修另一处不跟（2026-09-29 的「隔帧取样」缺陷族就是这么来的）。
+// 做法：读到 magic → 读帧头描述符（里面塞着字典 id、内容长度的宽度）→ 一帧一帧读 block
+// （block type 3 是保留值，见着就停）→ 有校验位就再跳 4 字节。任何一步拿不够字节就
+// 判定"撕裂"，把该帧起点交回去；**不猜长度，也不把半截字节凑成完整帧**。
 //
-// 三条必读：
-//   ① **本件是 CLI 侧唯一源**（2026-09-29 卡「归档帧扫描同源化」建立）：`tools\archive-card-sessions.mjs`
-//      与 `tools\archive-inactive-sessions.mjs` 的 **6 处**拆帧点（tailTypes / readSessionMeta / framesOf、
-//      tailState / allTypes / framesOf）全部消费本件。原魔数搜索实现已删除。
-//   ② 与插件侧 `tools\dsh-archive-sessions\lib\zstd-frame-rewrite.mjs#scanZstdFrames` **同源但不是同一
-//      文件**：插件部署时只同步插件目录 ⇒ 插件**不能 import 插件目录外的文件**（CLI 侧也不该反向依赖
-//      插件目录 = 跨包部署边界）。两份实现靠 `tools\_test\test-archive-framescan.mjs` 的**一致性单测**
-//      守住：两文件并排跑同一批样本（含魔数字节样本 / 撕裂帧样本 / 生产形态样本），帧边界必须逐帧相同。
-//      ⇒ **禁再抄第三份**：要改算法，先改这两份并让一致性单测过。
-//   ③ 与本件同算法的另两份**历史副本**（`tools\archive-meta-backfill.mjs` 约 L169 /
-//      `tools\projcache-restore-archived.mjs` 约 L64 各自的内联版：无 tornStart、撕裂即 break）
-//      **登记为待收口** —— 它们属其它卡的产物，本件建立时**未动**，留给后续卡（避免与在途改动互相踩）。
+// 为什么不用"搜魔数 + 游标推进"：压缩后的字节流里可能正好出现 magic 的字节序列，
+// 那种做法会把一帧劈成两半；而且每份实现各写一套，改了一处另一处不跟，缺陷就会
+// 隔一段时间冒一次。宁可多写几十行结构解析。
+//
+// 边界说明：这里只负责切，不负责解压（解压由调用方用平台自带的 zstd 解）。
+// 另一份同样的算法存在于归档插件内部 —— 部署时插件只能带走自己目录里的文件，
+// 所以两边各留一份实现，靠一致性单测对齐帧边界；要改算法就两边一起改、让单测过。
+
+/** zstd 帧魔数（小端读出来的 32 位值） */
+export const ZSTD_MAGIC = 4247762216;
+
+const MAGIC_BYTES = 4;
+const DESCRIPTOR_BYTES = 1;
+const BLOCK_HEADER_BYTES = 3;
+const CHECKSUM_BYTES = 4;
+const BLOCK_TYPE_RESERVED = 3;
+const BLOCK_TYPE_RLE = 1;
+
+/**
+ * 解析单帧，返回它的结束偏移。
+ * @param {Buffer} buffer
+ * @param {number} from 帧起点
+ * @returns {{end:number}|null} null = 这帧不完整（或魔数对不上），由调用方记为撕裂点
+ */
+function parseFrameAt(buffer, from) {
+  if (buffer.length - from < MAGIC_BYTES) return null;
+  if (buffer.readUInt32LE(from) !== ZSTD_MAGIC) return null;
+
+  let at = from + MAGIC_BYTES;
+  if (at === buffer.length) return null;
+
+  const descriptor = buffer.readUInt8(at);
+  at += DESCRIPTOR_BYTES;
+  // 描述符里第 3、4 位保留，非零说明不是我们认识的帧头
+  if ((descriptor & 0b1_1000) !== 0) return null;
 
-export const ZSTD_MAGIC = 4247762216 // 0xFD2FB528 LE
+  const contentSizeFlag = descriptor >>> 6;
+  const singleSegment = (descriptor & 0b10_0000) !== 0;
+  const hasChecksum = (descriptor & 0b100) !== 0;
+  const dictionaryFlag = descriptor & 0b11;
+  const dictionaryBytes = dictionaryFlag === 0b11 ? 4 : dictionaryFlag;
+  // 单段帧不写 window descriptor；内容长度字段按 flag 给出的宽度（flag 0 时单段帧占 1 字节）
+  const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+  const windowBytes = singleSegment ? 0 : 1;
+
+  at += windowBytes + dictionaryBytes + contentSizeBytes;
+  if (at > buffer.length) return null;
+
+  for (;;) {
+    if (buffer.length - at < BLOCK_HEADER_BYTES) return null;
+    const blockHeader = buffer.readUIntLE(at, BLOCK_HEADER_BYTES);
+    at += BLOCK_HEADER_BYTES;
+
+    const isLastBlock = (blockHeader & 0b1) !== 0;
+    const blockType = (blockHeader >>> 1) & 0b11;
+    const blockSize = blockHeader >>> 3;
+    if (blockType === BLOCK_TYPE_RESERVED) return null;
+
+    // RLE 块整块只有 1 个字节在流里，长度由 blockSize 说；其余类型的长度就是 blockSize
+    at += blockType === BLOCK_TYPE_RLE ? 1 : blockSize;
+    if (at > buffer.length) return null;
+    if (isLastBlock) break;
+  }
+
+  if (hasChecksum) {
+    at += CHECKSUM_BYTES;
+    if (at > buffer.length) return null;
+  }
+  return { end: at };
+}
 
 /**
- * 扫描 zstd 多帧边界（严格帧结构解析；与插件侧 scanZstdFrames 逐行同源）。
- * @param {Buffer} buffer 整个多帧缓冲（调用方负责截断/切片）
+ * 扫出一整块缓冲里的完整帧。
+ * @param {Buffer} buffer
  * @returns {{frames: {start:number,end:number}[], tornStart: number|undefined}}
- *   frames    —— **完整帧**的 [start, end) 区间，顺序即文件内顺序；
- *   tornStart —— 第一个**不完整**帧的起点（没有 = undefined）。调用方须"遇撕裂不猜"：
- *                撕裂帧一律丢弃，绝不把残字节当完整帧去解。
+ *   frames    —— 完整帧的 [start, end) 区间，顺序同文件内顺序；
+ *   tornStart —— 第一处不完整帧的起点（没有则 undefined）。调用方遇到它就停：
+ *                撕裂的那帧整体丢弃，绝不能把残字节当完整帧去解压。
  */
 export function scanZstdFrames(buffer) {
-  const frames = []
-  let offset = 0
-  while (offset < buffer.length) {
-    const start = offset
-    if (buffer.length - offset < 4) return { frames, tornStart: start }
-    if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return { frames, tornStart: start }
-    offset += 4
-    if (offset === buffer.length) return { frames, tornStart: start }
-    const descriptor = buffer.readUInt8(offset)
-    offset += 1
-    if ((descriptor & 24) !== 0) return { frames, tornStart: start }
-    const contentSizeFlag = descriptor >>> 6
-    const singleSegment = (descriptor & 32) !== 0
-    const checksum = (descriptor & 4) !== 0
-    const dictionaryFlag = descriptor & 3
-    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag
-    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag
-    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes
-    if (buffer.length - offset < remainingHeaderBytes) return { frames, tornStart: start }
-    offset += remainingHeaderBytes
-    for (;;) {
-      if (buffer.length - offset < 3) return { frames, tornStart: start }
-      const blockHeader = buffer.readUIntLE(offset, 3)
-      offset += 3
-      const lastBlock = (blockHeader & 1) !== 0
-      const blockType = (blockHeader >>> 1) & 3
-      const blockSize = blockHeader >>> 3
-      if (blockType === 3) return { frames, tornStart: start }
-      const payloadBytes = blockType === 1 ? 1 : blockSize
-      if (buffer.length - offset < payloadBytes) return { frames, tornStart: start }
-      offset += payloadBytes
-      if (lastBlock) break
-    }
-    if (checksum) {
-      if (buffer.length - offset < 4) return { frames, tornStart: start }
-      offset += 4
-    }
-    frames.push({ start, end: offset })
+  const frames = [];
+  let cursor = 0;
+  while (cursor < buffer.length) {
+    const parsed = parseFrameAt(buffer, cursor);
+    if (!parsed) return { frames, tornStart: cursor };
+    frames.push({ start: cursor, end: parsed.end });
+    cursor = parsed.end;
   }
-  return { frames, tornStart: undefined }
+  return { frames, tornStart: undefined };
 }

package/memory-db-tools/README.md

@@ -19,7 +19,7 @@
 |---|---|---|---|---|---|
 | `audit-export.mjs` | 第 1 站：把记忆库全量导成 `memories.json`，给下面所有探针当数据源 | `node audit-export.mjs` | `--db` `<库路径>`、`--out` `<文件>`、`--force`（覆盖已存在）、`--json`、`--quiet` | **只读库**（可写 `--out`） | `memories.json` + 统计（TOTAL/PINNED/CHARS/设备分布） |
 | `audit-analyze.mjs` | 第 2 站：六项分析——首行清单 / 漏标设备候选 / 重复对 / 过期关键词 / pinned 全文 / 统计 | `node audit-analyze.mjs` | `--in` `<memories.json>`、`--out` `<目录>`、`--json`、`--quiet` | 只读输入（可写 6 个产物） | `list-lines.txt`、`list-nodev.txt`、`dup-pairs.txt`、`keyword-hits.txt`、`pinned-full.txt`、`stats.json` |
-| `audit-struct-probe.mjs` | 结构异常：设备标不在已知清单（OTHER）
+| `audit-struct-probe.mjs` | 结构异常：设备标不在「已知设备名」清单（OTHER）+ 一条里两个设备标（DOUBLE）+ 长度分布 | `node audit-struct-probe.mjs` | `--in` `<memories.json>`、`--top` `<n>`、`--json` | **只读，不写文件** | 标准输出（OTHER / DOUBLE / PINNED_CHARS / TOP_LONG_NONPINNED） |
 | `audit-hit-probe.mjs` | 给 id 列表，报每条命中了哪些机器特征词（自证「漏标设备」判据站得住） | `node audit-hit-probe.mjs --ids 40,46,67` | `--ids`（必填）、`--in`、`--json` | **只读，不写文件** | 标准输出（每行 `#id [命中词] 首行`） |
 | `audit-dump-ids.mjs` | 按 id 取记忆全文（分批精读，规避 stdout 编码/截断坑） | `node audit-dump-ids.mjs --ids 40,46,67` | `--ids`（必填）、`--out`、`--stdout`、`--db`、`--json` | **只读库**（可写 `--out`） | `dump-ids-<本地时间>.txt`（默认临时目录）或 stdout |
 | `audit-persona-overlap.mjs` | 量化每条记忆有多少比例已出现在 persona 里（找「焊接残留」条目） | `node audit-persona-overlap.mjs` | `--db`、`--persona`、`--out`、`--top` `<n>`、`--json` | **只读库与 persona**（可写 `--out`） | `persona-overlap.json` + 覆盖比 Top N / pinned 覆盖比 |
@@ -49,6 +49,34 @@ node $T\audit-verify-unchanged.mjs --baseline "$W\memories.json" --expect-unchan
 - **过期关键词表**：`audit-analyze.mjs` 的 `STALE_KEYWORDS`（19 组；过期项增减改这一处）。
 - **重复对阈值**：`audit-analyze.mjs` 的 `analyze(mems, { shingle, minShared, jacThreshold })`（默认 6-gram / 共享 shingle ≥ 6 / Jaccard ≥ 0.15）。
 
+### 已知设备名（改这里，不是改代码）
+
+`audit-export.mjs` 的设备分布统计与 `audit-struct-probe.mjs` 的 OTHER 判据，都要知道「哪些设备名算已知」。
+**代码里不写死任何机器名**（不带任何真实机器名，换机器不用改代码）。优先级从高到低：
+
+1. **环境变量** `MEMORY_DB_AUDIT_DEVICES` —— 逗号或空格分隔，例如
+   `$env:MEMORY_DB_AUDIT_DEVICES = 'laptop,desktop'`（临时起效，适合偶尔跑一次）；
+2. **配置文件** `memory-engine/config/audit-devices.json` 里的 `devices` 数组 —— 随包发布，改它长期生效：
+
+   ```json
+   { "devices": ["alpha", "beta"] }
+   ```
+
+3. 两者都没给时退回**内置中性示例名** `alpha` / `beta`（只是让工具装完能跑，不代表任何真实机器）。
+
+匹配规则：只看 `【设备：X】` 里的 X 那段，拿名单里每个名字做**大小写敏感**的子串匹配；
+名单不认识的一律归 **OTHER**（结构探针会列出来让人复核）；名单里出现 `NONE` / `OTHER` / `DOUBLE`
+（统计结果里的固定键）或形态不合法的名字会被剔掉，并在 stderr 打一行警告。
+名单为空或全不合法 ⇒ 退回内置缺省（不是「全都算 OTHER」）。
+
+> ⚠️ **别把本机真实设备名写进仓里那份 `audit-devices.json`** —— 它会随包发布到公开仓。
+> 本机跑体检要认真名，用环境变量（或写进自己的 PowerShell profile / 启动脚本），
+> 让仓里的那份始终是**中性洁本**。反过来说：缺省配置不认识你的机器名时，
+> 全部设备标都会落进 OTHER —— 这是**故意**的（宁可让你看见一堆"不认识"，也不把机器名刻进代码）。
+>
+> 统计输出（`DEV={...}`）的形状固定 = 名单里每个名字一个计数 + `NONE` / `OTHER` / `DOUBLE` 三个固定键；
+> 名单换了，键名跟着换，**键的数量与顺序规则不变**。改名单不会改动任何 CLI 参数 / 缺省值 / 退出码。
+
 ### 自检
 
 每个工具都有 `--help`（用法/参数/退出码）与 `--self-test`（合成夹具跑一遍 + 自证只读：合成库 sha 前后一致、主体逻辑段每次开库都带 `readOnly: true`）：

package/memory-db-tools/audit-analyze.mjs

@@ -298,7 +298,7 @@ export function selfTest() {
   const inFile = path.join(tmp, "memories.json");
   const outDir = path.join(tmp, "out");
   try {
-    const base = "【设备：ROG】重复内容判定用长文本片段甲乙丙丁戊己庚辛壬癸子丑寅卯辰巳午未申酉戌亥";
+    const base = "【设备：alpha】重复内容判定用长文本片段甲乙丙丁戊己庚辛壬癸子丑寅卯辰巳午未申酉戌亥";
     const DRV = path.parse(process.cwd()).root;
     const mems = [
       { id: 1, text: base, pinned: true, tags: "", created_at: 1, updated_at: 1 },