@a9i5k4/dsh-auto-memory 3.1.0 → 3.1.3

package/lib/jsonl-tail-cursor.js

@@ -0,0 +1,75 @@
+/**
+ * 环形 JSONL 的增量游标（issue #103）。
+ *
+ * **为什么存在**：`judgement-shadow.jsonl` 这类文件由 Python 侧按**保尾丢弃**维护
+ * （`python/worker_semantic_v1.py` SHADOW_LOG_MAX=256，每次重写为 `lines[-256:]`）。
+ * 用「行数」当游标在文件写满后必然失效：`lines.length` 恒等于上次的 `count` ⇒ 增量区间
+ * 恒为空 ⇒ 消费端永久停摆，且因为"没有新行"是合法状态而不会留下任何痕迹。
+ *
+ * 本模块把游标改成**行内容指纹**：环内每一行只被交付一次，与文件是否被截断无关。
+ * 纯函数、零依赖、不碰文件系统 —— 便于用假环直接单测。
+ *
+ * 语义约定（与调用点 `hubFeedTick` 一致）：
+ * - 首次 `take()` 只登记现状、不交付任何行（`seeded: false`）。追喂历史行会让重启后
+ *   把环里旧判据再吃一遍（`procedures.observe` 会重复计数），故刻意不喂。
+ * - 之后每次 `take()` 只交付指纹未出现过的行，并按插入序把登记表封顶在 `maxSeen`。
+ * - 逐字节相同的重复行视为同一事实（`fresh` 里不出现第二次）。
+ *
+ * ★归属说明（2026-09-22）：本模块内容取自被 3.1.0 强推冲掉的孤儿快照
+ *   `475abfe:lib/jsonl-tail-cursor.js`（原为 PR #119 的产物）；因 pre 线只认 `-pre` 命名，
+ *   此处改名为 `jsonl-tail-cursor.js` **并已登记进 `tools/release.mjs` 的 libModuleRenames**。
+ */
+import { createHash } from 'node:crypto'
+
+const defaultFp = (line) => createHash('sha256').update(String(line)).digest('hex').slice(0, 16)
+
+/**
+ * @param {{maxSeen?: number, fp?: (line: string) => string}} [opts]
+ *   maxSeen 应 ≥ 目标环形文件的上限（默认 1024 = 256 的 4 倍），否则会出现
+ *   「指纹被淘汰 ⇒ 环内旧行被重复交付」。
+ */
+export function createJsonlTailCursorPre(opts = {}) {
+  const maxSeen = Number(opts.maxSeen) > 0 ? Number(opts.maxSeen) : 1024
+  const fpOf = typeof opts.fp === 'function' ? opts.fp : defaultFp
+  const seen = new Set()
+  const order = [] // 插入序旧→新；Set 本身不保证可淘汰顺序，故另记
+  let seeded = false
+
+  const remember = (fp) => {
+    if (seen.has(fp)) return
+    seen.add(fp)
+    order.push(fp)
+    while (order.length > maxSeen) seen.delete(order.shift())
+  }
+
+  /**
+   * @param {string[]} lines 当前文件内容（调用方负责切行与去空行）
+   * @returns {{seeded: boolean, fresh: string[], seenSize: number}}
+   *   `seeded: false` 表示本次为冷启动登记，`fresh` 必为空。
+   */
+  function take(lines) {
+    const arr = Array.isArray(lines) ? lines : []
+    if (!seeded) {
+      seeded = true
+      for (const l of arr) remember(fpOf(l))
+      return { seeded: false, fresh: [], seenSize: seen.size }
+    }
+    const fresh = []
+    for (const l of arr) {
+      const fp = fpOf(l)
+      if (seen.has(fp)) continue
+      remember(fp)
+      fresh.push(l)
+    }
+    return { seeded: true, fresh, seenSize: seen.size }
+  }
+
+  /** 复位（测试与「换文件」场景用）：下次 take() 重新按冷启动登记。 */
+  function reset() {
+    seeded = false
+    seen.clear()
+    order.length = 0
+  }
+
+  return { take, reset, stats: () => ({ seeded, seenSize: seen.size, maxSeen }) }
+}

package/lib/m7-index-sync-host.js

@@ -16,8 +16,10 @@
  *   - 禁止在每个 Segment 重复全量 sync(成功后缓存 ready identity);
  *   - dispose 清理 in-flight/ready cache/abort controller,不删除 derived cache。
  *
- * 可观察性(最小投影,不泄内容):capturedPathKeys(≤8)、lastSegmentRuntimeKey、
- * lastSegmentSessionRef、lastDrop{reason,contextVersion,runtimeKey}、readyState。
+ * 可观察性(最小投影,不泄内容):ready(按 (wsRef,scope) 的 miv/epoch/generation)、inFlightCount、
+ * generation、recentDrops{reason,contextVersion}、epoch、engineSwitch、stats。
+ * ★2026-09-22:删掉了一条恒空的死投影字段 —— 它取自某个全文件无 .add 的 Set,恒为 []。
+ * 真正的「已捕获路径键」属 context-host.js(那边的集合是活的)。
  * UTF-8 无 BOM。
  */
 import { buildIndexSyncPlansPre, sendIndexSyncPlanPre } from './index-sync.js'
@@ -25,7 +27,6 @@ import { workspaceRefOf } from './evidence-store.js'
 import { createEngineSwitchPre } from './engine-switch.js'
 
 export const M7_INDEX_SYNC_HOST_POLICY_VERSION = 'm7_index_sync_host_v1'
-const MAX_PATH_KEYS = 8
 const MAX_DROPS = 16
 
 export function createIndexSyncHostPre(opts = {}) {
@@ -33,7 +34,6 @@ export function createIndexSyncHostPre(opts = {}) {
   if (!engine) throw new Error('index-sync-host: engine required')
   const readyCache = new Map()   // key=(wsRef,scope) -> { miv, epoch, at, generation }
   const inFlight = new Map()     // key=(wsRef,scope) -> { controller, promise, miv }
-  const enabledKeys = new Set()  // 显式 disable 的 key(同一 miv 内不再重试;miv 变化自动解除)
   const volatileDrops = []       // ≤16 条最小投影(无文本)
   const stats = { syncsStarted: 0, syncsOk: 0, syncsFailed: 0, skippedCached: 0,
     epochReset: 0, mivReplaced: 0, aborted: 0, drops: 0, readyHits: 0, generationResets: 0 }
@@ -197,7 +197,6 @@ export function createIndexSyncHostPre(opts = {}) {
       engineSwitch: switchMachine.getEngineSwitchStatusPre(),
       ready: [...readyCache.entries()].map(([k, v]) => ({ key: k, miv: v.miv, epoch: v.epoch ? v.epoch.slice(0, 12) : null, generation: v.generation })),
       inFlightCount: inFlight.size,
-      capturedPathKeys: [...enabledKeys].slice(0, MAX_PATH_KEYS),
       stats: { ...stats },
       recentDrops: volatileDrops.slice(-4),
       epoch: c && typeof c.currentEpoch === 'function' ? (c.currentEpoch() || '').slice(0, 12) : null,
@@ -235,7 +234,6 @@ export function createIndexSyncHostPre(opts = {}) {
     for (const [, infl] of inFlight) { try { infl.controller.abort() } catch (_) {} }
     inFlight.clear()
     readyCache.clear()
-    enabledKeys.clear()
     volatileDrops.length = 0
     stats.drops = 0
   }

package/lib/memory-hub.js

@@ -149,9 +149,32 @@ export function createMemoryHubPre(opts = {}) {
   }
 
   function ingestJudgementRows(rows) {
+    // issue #110 的剩余缺口：批内合并落盘此前**只挂在宿主的喂数定时循环上**（index.js 里
+    // 手动 beginBatch/endBatch）。于是走 `ingestJudgementRows` 的其它批量入口——HTTP
+    // `/memory-hub` 的 `action=feed`（面板/外部重放器喂一整批判据）——仍是 N 行 = N 次整份快照写盘，
+    // 正是写放大。把批语义收到"拥有这批行"的这一层，任何批量入口都自动只落一次。
+    // 外层若已自己开批（喂数循环），beginBatch 的 depth 计数保证内层 end 不会提前落盘。
+    const batch = opts.batch
+    const canBatch = batch && typeof batch.beginBatch === 'function' && typeof batch.endBatch === 'function'
+    if (!canBatch) {
+      const out = []
+      for (const r of rows) out.push(ingestJudgement(r))
+      return { results: out }
+    }
+    batch.beginBatch()
     const out = []
-    for (const r of rows) out.push(ingestJudgement(r))
-    return { results: out }
+    let batchResult = null
+    try {
+      for (const r of rows) out.push(ingestJudgement(r))
+    } finally {
+      // 批末必落：中途抛错也不能把已接受的改动留在内存里等下次。
+      // ★不在 finally 里 return —— 那会吞掉正在传播的异常（静默失败的同一种形状）。
+      batchResult = batch.endBatch() || null
+    }
+    if (batchResult && batchResult.ok === false) {
+      log('memory-hub batch persist failed: ' + JSON.stringify((batchResult.errors || []).slice(-1)))
+    }
+    return { results: out, batch: batchResult }
   }
 
   // ---- 2) episodic 巩固钩子(会话结束/空闲期调) ----

package/lib/migrate-pack.js

@@ -0,0 +1,431 @@
+/**
+ * 迁移包引擎（migrate pack）—— 把一个工作区的记忆打包/搬包/导入。
+ *
+ * ★设计要点（依据 docs/internal/MIGRATION-ARCH-20260922.md 的实测取证）：
+ *   1. **零依赖**：只用 node 内置。不用 zip（`node:zlib` 只有 gzip/deflate、没有 zip 容器；
+ *      引第三方库违反本仓零依赖铁律）⇒ 单 JSON 文件，可选再 gzip 一层。
+ *   2. **纯逻辑与 IO 分离**：本模块**不碰真实磁盘**（只做纯函数），IO 由宿主负责。
+ *      这样导出/重写/计划三步都能在守卫里用真数据直接单测，不必起宿主。
+ *   3. **路径重写是必需的**：实测 slug 规则为
+ *        `'--' + path.replace(/[\\/:*?"<>|]/g, '-') + '--'`
+ *      —— 它**不可逆**（原路径里的 `-` 与替换产物 `-` 无法区分）⇒ 新路径的 slug 只能由
+ *      新路径**重新计算**，且文件内出现的旧路径必须逐处重写，否则 B 机全是死链。
+ *   4. **checksum 必校验**：半损坏的包会污染现场且极难排查 ⇒ inspect 阶段即拒绝。
+ *
+ * 包格式 `dam-pack-v1`（单个 JSON）：
+ *   {
+ *     format, createdAt, source:{ws,slug,host}, runtime:{pluginVersion},
+ *     summaryRecord,            // workspaces-summary.json 里属于该工作区的那一条
+ *     files: { '<相对 slug 目录的路径>': '<原样文本>' },
+ *     stats: { fileCount, bytes },
+ *     checksum: { algo:'sha256', value }
+ *   }
+ */
+
+import { createHash } from 'node:crypto'
+
+export const MIGRATE_PACK_FORMAT_PRE = 'dam-pack-v1'
+export const MIGRATE_PACK_CHECKSUM_ALGO_PRE = 'sha256'
+/** 单包上限：文件数与总字节（防手滑把整个 memory 目录塞进来）。 */
+export const MIGRATE_PACK_MAX_FILES_PRE = 20000
+export const MIGRATE_PACK_MAX_BYTES_PRE = 256 * 1024 * 1024
+
+/**
+ * workspaceKey（slug）—— **与宿主 `lib/index.js` 的同名逻辑逐字一致**。
+ * ★不要改成「更聪明」的写法：两处一旦不一致，导入会把数据放进错误的目录。
+ */
+export function workspaceSlugPre(ws) {
+  if (typeof ws !== 'string' || !ws) return ''
+  return '--' + String(ws).replace(/[\\/:*?"<>|]/g, '-') + '--'
+}
+
+/**
+ * 一个真实路径在文件里可能出现的 **4 种形态**。
+ * 实测：日志/笔记正文写的是 `D:\a\b`；JSON 里是转义形态 `D:\\a\\b`；
+ * file URL 出现在语义索引与部分摘要里。
+ */
+export function pathVariantsPre(p) {
+  const s = String(p || '')
+  if (!s) return []
+  const posix = s.replace(/\\/g, '/')
+  const out = [s, posix, 'file:///' + posix]
+  // JSON 转义形态：反斜杠翻倍（Windows 路径在 JSON 文本里长这样）
+  if (s.includes('\\')) out.push(s.replace(/\\/g, '\\\\'))
+  // 去重并按长度降序（先替换长的，避免短形态抢先命中留下残渣）
+  return Array.from(new Set(out)).filter(Boolean).sort((a, b) => b.length - a.length)
+}
+
+/**
+ * 文本级路径重写（纯函数）。**这是导入时唯一会改动用户正文的地方**，故：
+ *   - 逐形态替换，长形态优先
+ *   - 返回 `hits`（改了多少处）供预览逐文件展示，用户能看见改在哪
+ *   - 不做正则/模糊匹配（避免误伤），只做**字面量**替换
+ *
+ * @param {string} text
+ * @param {{fromPath:string, toPath:string, fromSlug?:string, toSlug?:string}} opt
+ * @returns {{text:string, hits:number}}
+ */
+export function rewritePathsInTextPre(text, opt = {}) {
+  let s = String(text == null ? '' : text)
+  let hits = 0
+  const fromPath = String(opt.fromPath || '')
+  const toPath = String(opt.toPath || '')
+  if (fromPath && toPath && fromPath !== toPath) {
+    const toVariants = pathVariantsPre(toPath)
+    const fromVariants = pathVariantsPre(fromPath)
+    // 建立「同形态 → 同形态」映射：Windows 原形对 Windows 原形、posix 对 posix …
+    // 简化为按索引对齐（pathVariantsPre 的排序对两者一致，因为只是斜杠方向不同）
+    for (let i = 0; i < fromVariants.length; i++) {
+      const fv = fromVariants[i]
+      const tv = toVariants[i] !== undefined ? toVariants[i] : toPath
+      if (!fv || fv === tv) continue
+      const before = s
+      s = s.split(fv).join(tv)
+      if (s !== before) hits += countOccurrencesPre(before, fv)
+    }
+  }
+  const fromSlug = String(opt.fromSlug || '')
+  const toSlug = String(opt.toSlug || '')
+  if (fromSlug && toSlug && fromSlug !== toSlug) {
+    const before = s
+    s = s.split(fromSlug).join(toSlug)
+    if (s !== before) hits += countOccurrencesPre(before, fromSlug)
+  }
+  return { text: s, hits }
+}
+
+/** 字面量子串出现次数（不用正则，避免特殊字符）。 */
+export function countOccurrencesPre(hay, needle) {
+  if (!needle) return 0
+  let n = 0, i = 0
+  for (;;) {
+    const p = String(hay).indexOf(needle, i)
+    if (p < 0) return n
+    n++
+    i = p + needle.length
+  }
+}
+
+// ───────────────────────── 校验和 ─────────────────────────
+
+/**
+ * 包内容摘要（纯函数）。**规范化**：按路径排序后逐条喂入，保证同一内容在任何机器上
+ * 得到同一个值（否则跨机校验永远失败）。
+ * 用 `\u0000` 作字段分隔（路径/内容里不会出现的字符），避免拼接歧义（如 a|b 与 a、b）。
+ */
+export function packChecksumPre(files) {
+  const names = Object.keys(files || {}).sort()
+  const h = createHash(MIGRATE_PACK_CHECKSUM_ALGO_PRE)
+  for (const n of names) {
+    h.update(n)
+    h.update('\u0000')
+    h.update(String(files[n]))
+    h.update('\u0000')
+  }
+  return h.digest('hex')
+}
+
+// ───────────────────────── 打包（纯函数）─────────────────────────
+
+/**
+ * 构造一个迁移包对象（**不写盘**）。
+ * @param {{ws:string, files:Object<string,string>, summaryRecord?:object,
+ *          pluginVersion?:string, now?:number, sourceHost?:string}} opt
+ * @returns {{ok:boolean, error?:string, pack?:object, warnings:string[]}}
+ */
+export function buildPackPre(opt = {}) {
+  const warnings = []
+  const ws = String(opt.ws || '')
+  const files = opt.files && typeof opt.files === 'object' ? opt.files : {}
+  if (!ws) return { ok: false, error: 'missing-source-ws', warnings }
+  const names = Object.keys(files)
+  if (!names.length) return { ok: false, error: 'no-files', warnings }
+  if (names.length > MIGRATE_PACK_MAX_FILES_PRE) return { ok: false, error: 'too-many-files:' + names.length, warnings }
+  let bytes = 0
+  for (const n of names) {
+    if (n.includes('..') || n.startsWith('/') || n.startsWith('\\')) {
+      return { ok: false, error: 'unsafe-relative-path:' + n, warnings }
+    }
+    bytes += Buffer.byteLength(String(files[n]), 'utf8')
+  }
+  if (bytes > MIGRATE_PACK_MAX_BYTES_PRE) return { ok: false, error: 'too-large:' + bytes, warnings }
+  // 体积提示（不阻断）：超过 16 MB 时提醒用户包会很大
+  if (bytes > 16 * 1024 * 1024) warnings.push('pack-large:' + Math.round(bytes / 1048576) + 'MB')
+  // ★v3.1.3：用户级文件（如 `CALENDAR.md`）—— 与 `files` 的语义区别：
+  //   files 相对「工作区 slug 目录」，userFiles 相对「用户级 memory 目录」，且**跨工作区共享**。
+  //   老包无此字段 ⇒ 视为 {}，行为逐字节不变（向后兼容）。
+  const userFiles = (opt.userFiles && typeof opt.userFiles === 'object') ? opt.userFiles : {}
+  let userBytes = 0
+  for (const n of Object.keys(userFiles)) {
+    if (n.includes('..') || n.startsWith('/') || n.startsWith('\\')) {
+      return { ok: false, error: 'unsafe-user-relative-path:' + n, warnings }
+    }
+    userBytes += Buffer.byteLength(String(userFiles[n]), 'utf8')
+  }
+  const pack = {
+    format: MIGRATE_PACK_FORMAT_PRE,
+    createdAt: typeof opt.now === 'number' ? opt.now : Date.now(),
+    source: { ws, slug: workspaceSlugPre(ws), host: String(opt.sourceHost || '') },
+    runtime: { pluginVersion: String(opt.pluginVersion || '') },
+    summaryRecord: opt.summaryRecord && typeof opt.summaryRecord === 'object' ? opt.summaryRecord : null,
+    files,
+    userFiles,
+    stats: { fileCount: names.length, bytes, userFileCount: Object.keys(userFiles).length, userBytes },
+    checksum: { algo: MIGRATE_PACK_CHECKSUM_ALGO_PRE, value: packChecksumPre(files) },
+  }
+  return { ok: true, pack, warnings }
+}
+
+/**
+ * 校验一个已解析的包对象（纯函数，不抛）。
+ * @returns {{ok:boolean, errors:string[], warnings:string[]}}
+ */
+export function validatePackPre(pack) {
+  const errors = []
+  const warnings = []
+  if (!pack || typeof pack !== 'object') return { ok: false, errors: ['not-an-object'], warnings }
+  if (pack.format !== MIGRATE_PACK_FORMAT_PRE) errors.push('unknown-format:' + String(pack.format))
+  if (!pack.source || typeof pack.source.ws !== 'string' || !pack.source.ws) errors.push('missing-source-ws')
+  if (!pack.files || typeof pack.files !== 'object') errors.push('missing-files')
+  else {
+    const n = Object.keys(pack.files).length
+    if (!n) errors.push('empty-files')
+    if (n > MIGRATE_PACK_MAX_FILES_PRE) errors.push('too-many-files:' + n)
+    for (const k of Object.keys(pack.files)) {
+      if (k.includes('..') || k.startsWith('/') || k.startsWith('\\')) { errors.push('unsafe-relative-path:' + k); break }
+    }
+  }
+  // ★v3.1.3：userFiles 与 files 受**同等**安全检查（路径穿越）；老包无该字段直接通过。
+  if (!errors.length && pack.userFiles && typeof pack.userFiles === 'object') {
+    for (const k of Object.keys(pack.userFiles)) {
+      if (k.includes('..') || k.startsWith('/') || k.startsWith('\\')) { errors.push('unsafe-user-relative-path:' + k); break }
+      if (typeof pack.userFiles[k] !== 'string') { errors.push('non-text-user-file:' + k); break }
+    }
+  }
+  if (!errors.length) {
+    const want = pack.checksum && pack.checksum.value
+    const got = packChecksumPre(pack.files)
+    if (!want) errors.push('missing-checksum')
+    else if (String(want) !== got) errors.push('checksum-mismatch')
+  }
+  if (!errors.length && pack.stats) {
+    const real = Object.keys(pack.files).length
+    if (pack.stats.fileCount !== undefined && pack.stats.fileCount !== real) warnings.push('stats-filecount-drift')
+  }
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// ───────────────────────── 目标重写（纯函数）─────────────────────────
+
+/**
+ * 把包内容重写到目标工作区（纯函数，不写盘）。
+ *
+ * 路径相同时**不做任何替换**（避免误改用户正文）——这是架构里的「情形 A」；
+ * 路径不同时才逐文件重写并回报 hits（供预览逐条展示）。
+ *
+ * @param {object} pack
+ * @param {{targetWs:string, rewriteBody?:boolean}} opt
+ *        `rewriteBody !== false` ⇒ 连正文一起改（用户拍板：需要重写，避免 B 机死链）
+ * @returns {{files:Object, plan:{pathChanged:boolean, rewriteFiles:Array, totalHits:number}}}
+ */
+export function rewritePackForTargetPre(pack, opt = {}) {
+  const files = pack && pack.files ? pack.files : {}
+  const fromPath = String((pack && pack.source && pack.source.ws) || '')
+  const toPath = String(opt.targetWs || '')
+  const fromSlug = workspaceSlugPre(fromPath)
+  const toSlug = workspaceSlugPre(toPath)
+  const pathChanged = !!toPath && (fromPath !== toPath || fromSlug !== toSlug)
+  const rewriteBody = opt.rewriteBody !== false
+  const out = {}
+  const rewriteFiles = []
+  let totalHits = 0
+  for (const name of Object.keys(files)) {
+    const raw = String(files[name])
+    if (!pathChanged || !rewriteBody) { out[name] = raw; continue }
+    const r = rewritePathsInTextPre(raw, { fromPath, toPath, fromSlug, toSlug })
+    out[name] = r.text
+    if (r.hits > 0) { rewriteFiles.push({ path: name, hits: r.hits }); totalHits += r.hits }
+  }
+  rewriteFiles.sort((a, b) => b.hits - a.hits)
+  return { files: out, plan: { pathChanged, fromPath, toPath, fromSlug, toSlug, rewriteFiles, totalHits } }
+}
+
+// ───────────────────────── 预览计划（纯函数）─────────────────────────
+
+/**
+ * 计算「导入将要发生什么」（纯函数）—— **这是唯一能算出差异的地方**，
+ * import 只接受这里产出的 plan（防 TOCTOU），且预览必须能逐条列出覆盖项。
+ *
+ * @param {object} pack           已校验通过的包
+ * @param {{targetWs:string, existingFiles?:Object<string,string>, rewriteBody?:boolean,
+ *          onConflict?:'keep'|'overwrite'|'rename'}} opt
+ *        `existingFiles` = 目标目录现有文件（宿主负责读），用于算新增/覆盖
+ */
+export function planImportPre(pack, opt = {}) {
+  const { files, plan: rw } = rewritePackForTargetPre(pack, opt)
+  const targetWs = String(opt.targetWs || '')
+  const targetSlug = workspaceSlugPre(targetWs)
+  const onConflict = ['keep', 'overwrite', 'rename'].includes(opt.onConflict) ? opt.onConflict : 'keep'
+  const existing = opt.existingFiles && typeof opt.existingFiles === 'object' ? opt.existingFiles : {}
+  const additions = []
+  const overwrites = []
+  const replaced = {}   // 实际会写入的文件（含改名后的键）
+  for (const name of Object.keys(files)) {
+    const next = String(files[name])
+    const has = Object.prototype.hasOwnProperty.call(existing, name)
+    if (!has) { additions.push({ path: name, bytes: Buffer.byteLength(next, 'utf8') }); replaced[name] = next; continue }
+    const old = String(existing[name])
+    if (old === next) { replaced[name] = next; continue }           // 内容相同 ⇒ 无需改动，不算覆盖
+    if (onConflict === 'keep') { continue }                          // 默认保留 B 机 ⇒ 不写
+    if (onConflict === 'overwrite') {
+      overwrites.push({ path: name, oldBytes: Buffer.byteLength(old, 'utf8'), newBytes: Buffer.byteLength(next, 'utf8') })
+      replaced[name] = next
+      continue
+    }
+    // rename：A 机的版本改名为 <名字>.from-pack，B 机原文件保持不动
+    const alt = renameForConflictPre(name)
+    additions.push({ path: alt, bytes: Buffer.byteLength(next, 'utf8'), renamedFrom: name })
+    replaced[alt] = next
+  }
+  const warnings = []
+  if (rw.pathChanged) warnings.push('path-changed')
+  else warnings.push('same-path')
+  if (!Object.keys(replaced).length) warnings.push('nothing-to-write')
+  return {
+    ok: true,
+    format: pack.format,
+    source: { ws: pack.source.ws, slug: pack.source.slug },
+    target: { ws: targetWs, slug: targetSlug },
+    pathChanged: rw.pathChanged,
+    fromPath: rw.fromPath,
+    toPath: rw.toPath,
+    onConflict,
+    additions: additions.sort((a, b) => a.path.localeCompare(b.path)),
+    overwrites: overwrites.sort((a, b) => a.path.localeCompare(b.path)),
+    rewrite: { totalHits: rw.totalHits, files: rw.rewriteFiles.slice(0, 50), fileCount: rw.rewriteFiles.length },
+    writeFiles: replaced,
+    stats: { willWrite: Object.keys(replaced).length, total: Object.keys(files).length, bytes: pack.stats ? pack.stats.bytes : 0 },
+    warnings,
+  }
+}
+
+/** 冲突改名：`handoff/PLAN.md` → `handoff/PLAN.from-pack.md`（保留扩展名）。 */
+export function renameForConflictPre(relPath) {
+  const s = String(relPath)
+  const i = s.lastIndexOf('.')
+  const j = s.lastIndexOf('/')
+  if (i > j && i > 0) return s.slice(0, i) + '.from-pack' + s.slice(i)
+  return s + '.from-pack'
+}
+
+// ───────────────────────── 全局记录合并（纯函数）─────────────────────────
+
+/**
+ * 把包内的 summaryRecord 合并进目标机的 workspaces-summary.json（**merge 不 replace**）。
+ * ★实测该文件有 7 条记录（含其它工作区）⇒ 整体覆盖会丢别人的。
+ *
+ * @param {object} summary  目标机现有 summary（可能为 null）
+ * @param {object} record   包内记录（可能为 null）
+ * @param {string} targetWs 目标真实路径
+ * @returns {{summary:object, changed:boolean, action:'appended'|'updated'|'noop'}}
+ */
+export function mergeSummaryRecordPre(summary, record, targetWs) {
+  const base = summary && typeof summary === 'object' ? summary : {}
+  const list = Array.isArray(base.workspaces) ? base.workspaces.slice() : []
+  const now = Date.now()
+  if (!record || typeof record !== 'object') {
+    return { summary: Object.assign({}, base, { workspaces: list, generatedAt: base.generatedAt || now }), changed: false, action: 'noop' }
+  }
+  const next = Object.assign({}, record, { path: targetWs, name: basenamePre(targetWs) })
+  const i = list.findIndex((x) => x && x.path === targetWs)
+  if (i >= 0) {
+    // 同路径：保留目标机已有的 items（更可能是较新的），但把 A 机的补进来（去重）
+    const old = list[i] || {}
+    const items = dedupeStringsPre([].concat(old.items || [], next.items || []))
+    list[i] = Object.assign({}, old, next, { items, dateRange: old.dateRange || next.dateRange })
+    return { summary: Object.assign({}, base, { workspaces: list, generatedAt: now }), changed: true, action: 'updated' }
+  }
+  list.push(next)
+  return { summary: Object.assign({}, base, { workspaces: list, generatedAt: now }), changed: true, action: 'appended' }
+}
+
+/** 去重（保持顺序，字面量比对）。 */
+/**
+ * ★v3.1.3：日历条目**合并**（纯函数，不覆盖）。
+ *
+ * 为什么不是整篇覆盖：CALENDAR.md 在 `~/.dsh/memory/CALENDAR.md` —— **用户级、跨工作区共享**，
+ *   且两台机器都可能往里写过。整篇覆盖会丢掉本机独有的条目
+ *   （与 `workspaces-summary.json` 必须 merge 是同一条纪律）。
+ *
+ * 判据：以 `date | time | title` 三元组为身份。
+ *   - 身份冲突 ⇒ **保留本机已有的**（与导入冲突默认 keep 一致；不覆盖用户已改过的状态）。
+ *   - 本机没有的 ⇒ 追加进来。
+ *   - 输出按 日期 → 时间 排序，保证确定性（同输入必得同输出，便于断言）。
+ *
+ * @param {string} localText 本机 CALENDAR.md 原文（空 ⇒ 视为空日历）
+ * @param {string} incomingText 包内 CALENDAR.md 原文
+ * @returns {{ok:boolean, text:string, added:number, kept:number}}
+ */
+export function calendarMergePre(localText, incomingText) {
+  const parse = (t) => {
+    const out = []
+    let curDate = ''
+    for (const raw of String(t || '').split(/\r?\n/)) {
+      const line = raw.trim()
+      if (!line) continue
+      const dm = line.match(/^## (\d{4}-\d{2}-\d{2})/)
+      if (dm) { curDate = dm[1]; continue }
+      const m = line.match(/^- \[([ xX])\] (\d{1,2}:\d{2}) \| ([^|]+?) \| (.+?)(?: \| (.*))?$/)
+      if (m) out.push({ date: curDate, done: m[1] !== ' ', time: m[2], quadrant: m[3].trim(), title: m[4].trim(), note: (m[5] || '').trim() })
+    }
+    return out
+  }
+  const keyOf = (en) => en.date + '|' + en.time + '|' + en.title
+  const local = parse(localText).filter((en) => en.date)
+  const incoming = parse(incomingText).filter((en) => en.date)
+  const seen = new Set(local.map(keyOf))
+  const merged = local.slice()
+  let added = 0
+  for (const en of incoming) {
+    const k = keyOf(en)
+    if (seen.has(k)) continue
+    seen.add(k)
+    merged.push(en)
+    added++
+  }
+  const byDate = new Map()
+  for (const en of merged) {
+    if (!byDate.has(en.date)) byDate.set(en.date, [])
+    byDate.get(en.date).push(en)
+  }
+  const lines = ['# 日历与日程 (CALENDAR)', '', '> 由 dsh-auto-memory 维护;AI 可从对话中提取 deadline/约定写入,用户也可在 GUI 操作。', '']
+  for (const date of Array.from(byDate.keys()).sort()) {
+    lines.push('## ' + date)
+    for (const en of byDate.get(date).sort((a, b) => String(a.time || '').localeCompare(String(b.time || '')))) {
+      const mark = en.done ? 'x' : ' '
+      const note = en.note ? ' | ' + en.note : ''
+      lines.push('- [' + mark + '] ' + (en.time || '--:--') + ' | ' + (en.quadrant || '未分类') + ' | ' + en.title + note)
+    }
+    lines.push('')
+  }
+  return { ok: true, text: lines.join('\n'), added, kept: local.length }
+}
+
+export function dedupeStringsPre(arr) {
+  const seen = new Set()
+  const out = []
+  for (const x of arr || []) {
+    const s = String(x == null ? '' : x)
+    if (!s || seen.has(s)) continue
+    seen.add(s)
+    out.push(s)
+  }
+  return out
+}
+
+/** 取路径最后一段（不引 node:path，保持本模块可被纯逻辑测试）。 */
+export function basenamePre(p) {
+  const s = String(p || '').replace(/[\\/]+$/, '')
+  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'))
+  return i >= 0 ? s.slice(i + 1) : s
+}