dsh-config-manager 0.1.73 → 0.1.76

package/src/core/rollback-point.test.ts

@@ -30,6 +30,7 @@ import path from 'node:path'
 
 import {
   ROLLBACK_ANCESTOR_MAX_DEPTH,
+  ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES,
   ROLLBACK_DEFAULT_MAX_BYTES,
   ROLLBACK_DEFAULT_MAX_FILES,
   ROLLBACK_LEFTOVER_LIST_LIMIT,
@@ -1050,6 +1051,8 @@ test('R-11 记录被篡改不能变成写原语：路径越界 / 指纹不符一
   assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2', '一条不合格 → 零写入')
 
   // 篡改 2：路径合法但声明的内容指纹不符
+  // 注：载荷**不再存** `object`（object ≡ sha256，落盘时省掉、读取时按 sha256 补回）⇒ 改 sha256
+  // 等于同时改掉对象名 ⇒ 那个对象根本不存在 ⇒ 如实报 `object-missing`（仍是 fail-closed、零写入）。
   const tampered2 = await readFullRecord(engine, record.id)
   const hit2 = (tampered2.workspace.payload?.files ?? []).find((f) => f.sha256 === sha256Hex('A1'))
   assert.ok(hit2 !== undefined)
@@ -1058,7 +1061,25 @@ test('R-11 记录被篡改不能变成写原语：路径越界 / 指纹不符一
   await writeFullRecord(engine, tampered2)
   const rewound2 = await engine.rewind({ id: record.id, userConfirmed: true, guardPolicy: 'off' })
   assert.equal(rewound2.outcome, 'failed')
-  assert.ok((rewound2.segments[0]?.detail ?? []).some((line) => line.includes('object-hash-mismatch')))
+  assert.ok((rewound2.segments[0]?.detail ?? []).some((line) => line.includes('object-missing')),
+    '改 sha256 ⇒ 对象名随之改 ⇒ 读不到：' + JSON.stringify(rewound2.segments[0]?.detail))
+  assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2')
+
+  // 篡改 2b：指纹合法、但把**对象键**指向另一份真实存在的内容 ⇒ 该走 object-hash-mismatch
+  const tampered3 = await readFullRecord(engine, record.id)
+  const files3 = tampered3.workspace.payload?.files ?? []
+  const aTxt = path.join(fx.workspaceDir, 'a.txt')
+  const hit3 = files3.find((f) => f.path === aTxt)
+  assert.ok(hit3 !== undefined)
+  hit3.sha256 = sha256Hex('A1')   // 指纹还原成**真的**（上一轮篡改改过它）
+  const otherObject = files3.find((f) => f.path !== aTxt && f.sha256 !== hit3.sha256)?.sha256
+  assert.ok(otherObject !== undefined)
+  hit3.object = otherObject   // 对象存在、但它的内容哈希 ≠ 记录里的 sha256
+  await writeFullRecord(engine, tampered3)
+  const rewound3 = await engine.rewind({ id: record.id, userConfirmed: true, guardPolicy: 'off' })
+  assert.equal(rewound3.outcome, 'failed')
+  assert.ok((rewound3.segments[0]?.detail ?? []).some((line) => line.includes('object-hash-mismatch')),
+    '对象键被换 ⇒ 内容哈希对不上：' + JSON.stringify(rewound3.segments[0]?.detail))
   assert.equal(await readText(path.join(fx.workspaceDir, 'a.txt')), 'A2')
 })
 
@@ -1378,7 +1399,10 @@ test('R-19 分块不可用 / 非绝对路径 / 会话越界：该态结构化失
   const linked = await capturePoint(engine, fx)
   const track = linked.point?.workspace
   assert.equal(track?.ok, true)
-  assert.equal(track?.degraded, true)
+  // 链接是**设计内**跳过（不跟随、也不该回退它）⇒ 逐条留痕但不算「留得不完整」（R-50 口径）：
+  // 否则任何含符号链接的仓库每个点都挂「回退可能不完整」，真出问题时被噪声淹没
+  assert.equal(track?.degraded, false)
+  assert.equal(track?.reasonCode, null)
   assert.ok((track?.payload?.skipped ?? []).some((s) => s.reason === 'link' && s.path === junction))
   assert.equal((track?.payload?.files ?? []).some((f) => isInsidePath(f.path, junction)), false)
 })
@@ -2404,7 +2428,7 @@ test('T2-B 缓存命中与未命中两条路径下，删除候选判定（预览
   for (const file of created) await assert.rejects(fs.readFile(file), { code: 'ENOENT' })
 })
 
-test('T2-C 忽略规则：整个目录被忽略 ⇒ 证明名单不完整 ⇒ 删除整体拒绝（fail-closed，预览如实说明）', async (t) => {
+test('T2-C 忽略规则：整个目录被忽略 ⇒ **只拒那棵子树**的删除（分子树 fail-closed），范围外照常删', async (t) => {
   const fx = await makeFixture()
   t.after(fx.cleanup)
   const dir = await makeSizeDir(fx, 'cap-ignore-dir', { 'keep.txt': 3, 'note.md': 3 })
@@ -2430,23 +2454,29 @@ test('T2-C 忽略规则：整个目录被忽略 ⇒ 证明名单不完整 ⇒
   await fs.writeFile(createdRoot, 'NEW')
   await fs.writeFile(createdInBuild, 'NEW-IN-BUILD')
 
-  // 预览如实说明：删除被整体拒绝、原因 = 忽略目录
+  // 分子树 fail-closed：拒删只说 build/ 那棵子树，不再把整个工作区的删除一起关掉
   const preview = await engine.preview(captured.point?.id ?? '')
-  assert.equal(preview.workspace.createdRefusedReason, 'capture-incomplete')
-  assert.deepEqual(preview.workspace.removals, [], '证明名单不完整 ⇒ 预览的删除清单必须是空的')
-  const warn = preview.warnings.find((w) => w.code === 'rollback.warn.createdRefused')
-  assert.equal(warn?.detail, 'ignore-dirs', '成因必须如实回传（忽略目录）')
+  assert.equal(preview.workspace.createdRefusedReason, null, '范围说得清 ⇒ 不是全局拒删')
+  assert.deepEqual(preview.workspace.removals, [createdRoot], '范围外的候选照常删')
+  // 被忽略的子树在**回退期也走查不到**（同一条忽略规则）⇒ 它里面的路径根本不进候选，
+  // 既不在删除集、也不必进拒删清单；它的安全由「两端一致地看不见」保证。
+  assert.deepEqual(preview.workspace.createdSkipped, [], '被忽略子树整棵不进候选')
+  assert.equal(
+    preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'),
+    false,
+    '不再「一条都不删」⇒ 不得给那句全局警告（文案诚实性）',
+  )
 
-  // 执行：一条都不删
+  // 执行：范围内删 1 条、子树里的一条都不删
   const rewound = await engine.rewind({
     id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
   })
   const ws = rewound.segments.find((s) => s.state === 'workspace')
-  assert.equal(ws?.createdRefusedReason, 'capture-incomplete')
-  assert.equal(ws?.removed ?? 0, 0, '证明名单不完整 ⇒ 一条都不删')
-  assert.equal(await readText(createdRoot), 'NEW')
-  assert.equal(await readText(createdInBuild), 'NEW-IN-BUILD')
-  assert.ok((ws?.createdSkippedCount ?? 0) > 0, '候选必须如实进拒删清单')
+  assert.equal(ws?.createdRefusedReason, undefined, '分子树拒绝不是全局拒绝')
+  assert.equal(ws?.removed, 1, '范围外的候选照常删')
+  await assert.rejects(fs.readFile(createdRoot), { code: 'ENOENT' })
+  assert.equal(await readText(createdInBuild), 'NEW-IN-BUILD', '被忽略子树里的新建路径绝不删')
+  assert.equal(ws?.createdSkippedCount ?? 0, 0, '被忽略子树不进候选 ⇒ 拒删清单为空（不是「拒删了几条」）')
 })
 
 test('T2-D 忽略规则：文件级忽略仍保持证明名单完整 ⇒ 删除照常；内置 node_modules 规则不可反向取消', async (t) => {
@@ -2498,7 +2528,7 @@ test('T2-E 内存硬约束：同时驻留的文件内容 ≤ maxFileBytes（绝
   sizes['huge.txt'] = 4096
   const dir = await makeSizeDir(fx, 'cap-mem', sizes)
   const reader = countingReader()
-  const engine = makeEngine(fx, { maxFileBytes: 64, maxBytes: 1024 * 1024, readFile: reader.seam })
+  const engine = makeEngine(fx, { maxFileBytes: 64, captureInFlightBytes: 64, maxBytes: 1024 * 1024, readFile: reader.seam })
   const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-mem' })
   const payload = captured.point?.workspace.payload
   assert.ok(payload !== null && payload !== undefined)
@@ -2506,11 +2536,12 @@ test('T2-E 内存硬约束：同时驻留的文件内容 ≤ maxFileBytes（绝
   assert.equal(reader.reads.includes(path.join(dir, 'huge.txt')), false, '超限文件绝不整份读进内存')
   assert.ok(payload.skipped.some((e) => e.path.endsWith('huge.txt') && e.reason === 'too-large'))
   assert.equal(payload.files.length, 10)
-  // 同时驻留：单份 ≤ maxFileBytes，且从不并发驻留两份（走查是逐条串行的）
+  // 两个上限是两件事：maxFileBytes = 单文件「要不要读」的判据；captureInFlightBytes = 并发内存闸门。
+  // 2026-10-16 之前闸门错接到 maxFileBytes（缺省 = 总量预算 512 MiB）⇒ 桌面闪退。
   assert.ok(reader.peakSingle <= 64, '单份驻留 = ' + String(reader.peakSingle) + ' > maxFileBytes=64')
   assert.ok(
     reader.peakLive <= 64,
-    '同时驻留内容 = ' + String(reader.peakLive) + ' 字节，必须 ≤ maxFileBytes(64) + 常量(0)',
+    '同时驻留内容 = ' + String(reader.peakLive) + ' 字节，必须 ≤ captureInFlightBytes(64)',
   )
 })
 
@@ -2672,6 +2703,550 @@ test('R-31 采集时间预算：超预算留**部分点**并如实标 truncated
   assert.equal(track?.payload?.walkIncomplete, true, '走查中断必须标记 ⇒ 删除集随之 fail-closed')
 })
 
+/**
+ * 测试专用的时序注入：把「预算**何时**越界」钉成确定性的（不靠真机速度）。
+ *
+ * `now` 恒定返回同一个基线时刻，直到 state 被置位才推过 deadline：
+ *  · `walkDone` 由 {@link timeOutAfterWalk} 在 listChunkFiles 返回后置位 ⇒ 越界发生在**读文件阶段**；
+ *  · `armed` 由 {@link timeOutAtStop} 在第 N 次停止判据内置位 ⇒ 越界发生在**走查之中**。
+ */
+function makeArmedClock(budgetMs: number): { now: () => number; state: { armed: boolean } } {
+  const base = 1_000_000
+  const state = { armed: false }
+  // 未 armed ⇒ 恒定基线时刻（永不越界）；armed ⇒ 直接推过 deadline
+  const now = (): number => (state.armed ? base + budgetMs + 60_000 : base)
+  return { now, state }
+}
+
+/** 包一层私有的 listChunkFiles：把第 `at` 次停止判据变成「越界」（栈里还剩没进去的子树）。 */
+function timeOutAtStop(engine: RollbackPointEngine, state: { armed: boolean }, at: number): void {
+  const self = engine as unknown as { listChunkFiles: (...args: unknown[]) => Promise<unknown> }
+  const original = self.listChunkFiles.bind(engine)
+  // 计数跨分块累计（每个分块各调一次 listChunkFiles，停止判据是按次判定的）
+  let calls = 0
+  self.listChunkFiles = async (...args: unknown[]) => {
+    const stop = args[5]
+    if (typeof stop === 'function') {
+      const stopFn = stop as () => boolean
+      args[5] = () => {
+        calls += 1
+        if (calls >= at) state.armed = true
+        return stopFn()
+      }
+    }
+    return await original(...args)
+  }
+}
+
+test('R-43 预算落在**走查之后**：不误报 walk-incomplete，被中断的条目逐条留痕（删除照常）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-after-walk', { 'k1.txt': 3, 'k2.txt': 3, 'k3.txt': 3 })
+  const clock = makeArmedClock(50)
+  const engine = makeEngine(fx, {
+    captureBudgetMs: 50,
+    now: clock.now,
+    captureConcurrency: 1,
+    // 确定性地把「超时」钉在**第一个文件读完之后**（不靠真机速度）：并发为 1 ⇒ 只此一份入点
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      clock.state.armed = true
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-after-walk' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  // 读文件阶段被打断 ⇒ 截断仍如实标注（诚实不降级）
+  assert.equal(payload.truncated, true, '读到一半停下必须如实标截断')
+  assert.equal(captured.point?.workspace.reasonCode, 'capture-truncated')
+  assert.deepEqual(payload.files.map((f) => path.basename(f.path)), ['k1.txt'], JSON.stringify(payload.files))
+  // 被中断的两条**逐条留痕**（不静默）—— 名单因此保持完整，不需要路径索引兜底
+  assert.deepEqual(
+    payload.skipped.filter((s) => s.reason === 'budget-time').map((s) => path.basename(s.path)),
+    ['k2.txt', 'k3.txt'],
+    JSON.stringify(payload.skipped),
+  )
+  // 核心：走查已走完 ⇒ **不得**标记「走查不完整」（旧实现在这里误报，删除集整片失效）
+  assert.equal(payload.walkIncomplete ?? false, false, '走查已完成 ⇒ 不许标记 walkIncomplete（误报回归）')
+  assert.equal(payload.pathIndex ?? null, null, '每条都逐条留痕 ⇒ 覆盖自检认为名单完整，无需索引')
+
+  // 点之后新建一条：证明名单完整 ⇒ 预览与执行都照常删
+  const created = path.join(dir, 'created-after.txt')
+  await fs.writeFile(created, 'NEW')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '证明名单完整 ⇒ 不拒删')
+  assert.deepEqual(preview.workspace.removals, [created])
+  assert.equal(preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'), false, JSON.stringify(preview.warnings))
+
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(ws?.removed, 1, '证明名单完整 ⇒ 新建文件照常删')
+  await assert.rejects(fs.readFile(created), { code: 'ENOENT' })
+  assert.equal(await readText(path.join(dir, 'k3.txt')), 'xxx', '没读到的老文件绝不能被当成「新建」删掉')
+})
+
+test('R-44 走查被打断：只拒「没走查到的那棵子树」（分子树 fail-closed），范围外照常删', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 分块 1 整棵走完（其中的文件照常入点）；分块 2 的走查在弹出 sub/ **之前**被预算打断 ⇒ sub/ 从未进门
+  const dir1 = await makeSizeDir(fx, 'cap-walk-ok', { 'n1.txt': 3 })
+  const dir2 = await makeSizeDir(fx, 'cap-walk-abort', { 'm1.txt': 3 })
+  const sub = path.join(dir2, 'sub')
+  await fs.mkdir(sub, { recursive: true })
+  await fs.writeFile(path.join(sub, 'm2.txt'), 'OLD-IN-SUB')
+  const clock = makeArmedClock(50)
+  const engine = makeEngine(fx, { captureBudgetMs: 50, now: clock.now, captureConcurrency: 1 })
+  // 停止判据调用序：dir1 排空(#1) → dir2 弹出(#2，仍在预算内) → dir2/sub 弹出(#3，越界 ⇒ sub/ 从未进门)
+  timeOutAtStop(engine, clock.state, 3)
+
+  const captured = await engine.capturePoint({ chunks: [dir1, dir2], sessionId: 's-walk-abort' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(payload.truncated, true)
+  assert.equal(payload.walkIncomplete, true, '子树从未进门 ⇒ 安全判据必须生效')
+  assert.deepEqual(payload.unwalkedDirs, [sub], '精确范围必须带出来（分子树 fail-closed 的依据）')
+  assert.deepEqual(payload.files.map((f) => path.basename(f.path)), ['n1.txt'], '打断前读完的分块照常入点')
+  assert.equal(payload.files.some((f) => f.path.startsWith(sub)), false, 'sub/ 从未被走查')
+  assert.ok(
+    payload.skipped.some((s) => s.path.endsWith('m1.txt') && s.reason === 'budget-time'),
+    JSON.stringify(payload.skipped),
+  )
+
+  const createdElsewhere = path.join(dir1, 'created-in-walked-chunk.txt')
+  const createdRoot = path.join(dir2, 'created-root.txt')
+  const createdInSub = path.join(sub, 'created-in-sub.txt')
+  await fs.writeFile(createdElsewhere, 'NEW')
+  await fs.writeFile(createdRoot, 'NEW')
+  await fs.writeFile(createdInSub, 'NEW-IN-SUB')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '范围说得清 ⇒ 不是全局拒删')
+  assert.deepEqual(
+    [...preview.workspace.removals].sort(),
+    [createdElsewhere, createdRoot].sort(),
+    '没走查到的子树之外，候选照常删',
+  )
+  // 没走查到的子树里，**所有**当前存在且无记录的路径都进拒删清单（新建的 + 本来就在的 m2.txt）
+  assert.deepEqual(
+    [...preview.workspace.createdSkipped].sort(),
+    [createdInSub, path.join(sub, 'm2.txt')].sort(),
+    '子树里的候选如实进拒删清单',
+  )
+  assert.equal(
+    preview.warnings.some((w) => w.code === 'rollback.warn.createdRefused'),
+    false,
+    '分子树拒绝不得套用那句「一条都不删」的全局警告',
+  )
+
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(ws?.createdRefusedReason, undefined, '分子树拒绝不是全局拒绝')
+  assert.equal(ws?.removed, 2, '没走查到的子树之外照常删')
+  await assert.rejects(fs.readFile(createdElsewhere), { code: 'ENOENT' })
+  await assert.rejects(fs.readFile(createdRoot), { code: 'ENOENT' })
+  assert.equal(await readText(createdInSub), 'NEW-IN-SUB')
+  assert.equal(await readText(path.join(sub, 'm2.txt')), 'OLD-IN-SUB', '从未走查的文件绝不能被删')
+  assert.equal(await readText(path.join(dir1, 'n1.txt')), 'xxx')
+  assert.ok((ws?.createdSkippedCount ?? 0) > 0, '候选必须如实进拒删清单')
+})
+
+test('R-45 捕获并发：读 + 写并发跑（真机大头），但在飞内容字节 ≤ captureInFlightBytes', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const sizes: Record<string, number> = {}
+  for (let i = 0; i < 24; i += 1) sizes['p-' + String(i).padStart(2, '0') + '.txt'] = 64
+  const dir = await makeSizeDir(fx, 'cap-parallel', sizes)
+  let live = 0
+  let peak = 0
+  let inFlight = 0
+  let maxInFlight = 0
+  const engine = makeEngine(fx, {
+    // 闸门 = captureInFlightBytes（并发内存上界），与 maxFileBytes（单文件判据）分开：
+    // 同时最多 4 份 64 B 的内容在飞。
+    captureInFlightBytes: 256,
+    readFile: async (file: string) => {
+      inFlight += 1
+      maxInFlight = Math.max(maxInFlight, inFlight)
+      const bytes = await fs.readFile(file)
+      live += bytes.byteLength
+      peak = Math.max(peak, live)
+      await new Promise((resolve) => setTimeout(resolve, 2)) // 让并发真的重叠
+      live -= bytes.byteLength
+      inFlight -= 1
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-par' })
+  const payload = captured.point?.workspace.payload
+  assert.equal(payload?.files.length, 24, JSON.stringify(payload?.skipped))
+  assert.ok(maxInFlight > 1, '必须真的并发（否则 34k 文件永远扫不完）：实测 ' + String(maxInFlight))
+  assert.ok(peak <= 256, '在飞内容字节必须 ≤ captureInFlightBytes，实测 ' + String(peak))
+})
+
+test('R-45b 缺省闸门：maxFileBytes 缺省 = 总量预算，绝不能当成在飞内容上限（0.1.74 闪退根因）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const sizes: Record<string, number> = {}
+  for (let i = 0; i < 24; i += 1) sizes['g-' + String(i).padStart(2, '0') + '.txt'] = 64
+  const dir = await makeSizeDir(fx, 'cap-inflight-default', sizes)
+  let live = 0
+  let peak = 0
+  // maxFileBytes 给一个**远大于闸门**的值：旧实现（闸门 = maxFileBytes）会放行 24×64 = 1536 B 在飞。
+  const engine = makeEngine(fx, {
+    maxFileBytes: 4096,
+    captureInFlightBytes: 128,
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      live += bytes.byteLength
+      peak = Math.max(peak, live)
+      await new Promise((resolve) => setTimeout(resolve, 2))
+      live -= bytes.byteLength
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-inflight' })
+  assert.equal(captured.point?.workspace.payload?.files.length, 24)
+  assert.ok(peak <= 128, '在飞内容必须被 captureInFlightBytes 钉死（不是 maxFileBytes），实测 ' + String(peak))
+  // 缺省闸门本身必须远小于总量预算 —— 它才是并发的内存上界
+  assert.equal(ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES, 32 * 1024 * 1024)
+  assert.ok(
+    ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES < ROLLBACK_DEFAULT_MAX_BYTES / 8,
+    '缺省在飞闸门必须比总量预算小一个数量级以上',
+  )
+})
+
+test('T2-H .asar 路径绝不交给 fs：宿主里那是原生容器解析，畸形夹具能带走整个宿主', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-asar', {})
+  await fs.writeFile(path.join(dir, 'normal.txt'), 'N')
+  await fs.writeFile(path.join(dir, 'broken.asar'), Buffer.alloc(64, 0xff))
+  await fs.mkdir(path.join(dir, 'bundle.asar'), { recursive: true })
+  await fs.writeFile(path.join(dir, 'bundle.asar', 'inner.txt'), 'I')
+  const reads: string[] = []
+  const engine = makeEngine(fx, {
+    readFile: async (file: string) => {
+      reads.push(file)
+      return await fs.readFile(file)
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-asar' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(reads.some((f) => f.endsWith('.asar')), false, '任何 .asar 路径都不得被读')
+  assert.equal(reads.some((f) => f.includes('.asar' + path.sep)), false, '含 .asar 段的路径一律不碰')
+  assert.ok(
+    payload.skipped.some((e) => e.path.endsWith('broken.asar') && e.reason === 'asar-container'),
+    '畸形 .asar 必须留痕为 asar-container: ' + JSON.stringify(payload.skipped.map((e) => [e.path, e.reason])),
+  )
+  assert.ok(
+    payload.skipped.some((e) => e.path.endsWith('bundle.asar') && e.reason === 'asar-container'),
+    '名字含 .asar 段的目录同样不碰',
+  )
+  assert.ok(payload.files.some((f) => f.path.endsWith('normal.txt')), '普通文件照常入点')
+})
+
+test('R-46 缺口优先：预算被限死时覆盖率随回合**单调收敛**到 100%', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-converge', {})
+  const names = Array.from({ length: 60 }, (_, i) => 'c-' + String(i).padStart(3, '0') + '.txt')
+  for (const name of names) await fs.writeFile(path.join(dir, name), 'x')
+  // 每回合只放行 3 次读：等价于「预算只够扫一小部分」的确定性版本
+  let allowance = 3
+  const engine = makeEngine(fx, {
+    captureConcurrency: 1,
+    now: () => (allowance <= 0 ? 2_000_000 + 60_000 : 2_000_000),
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      allowance -= 1
+      return bytes
+    },
+  })
+  const seen = new Set<string>()
+  const covered: number[] = []
+  for (let round = 0; round < 25; round += 1) {
+    allowance = 3
+    const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-converge' })
+    for (const file of captured.point?.workspace.payload?.files ?? []) seen.add(file.path)
+    covered.push(seen.size)
+  }
+  for (let i = 1; i < covered.length; i += 1) {
+    assert.ok(covered[i]! >= covered[i - 1]!, '覆盖率不得回退：' + covered.join(','))
+  }
+  assert.equal(covered[covered.length - 1], 60, '足够多回合后必须覆盖 100%：' + covered.join(','))
+})
+
+test('R-47 自适应预算：被截断 ⇒ 下次翻倍；提前收工 ⇒ 下次减半（区间内）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-adapt', { 'a.txt': 3, 'b.txt': 3 })
+  let stepped = true
+  let tick = 0
+  const engine = makeEngine(fx, {
+    captureBudgetMs: 1_000,
+    captureBudgetMinMs: 500,
+    captureBudgetMaxMs: 4_000,
+    now: () => (stepped ? (tick += 1_000) : Date.now()),
+  })
+  const budgetOf = (): number => (engine as unknown as { captureBudgetMs: number }).captureBudgetMs
+  assert.equal(budgetOf(), 1_000, '初值 = 选项值')
+  // ① 步进时钟 ⇒ 一次次判定就撞满预算 ⇒ 截断 ⇒ 下次翻倍
+  const truncated = await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(truncated.point?.workspace.payload?.truncated, true)
+  assert.equal(budgetOf(), 2_000, '被截断 ⇒ 翻倍')
+  // ② 真实时钟 ⇒ 两个小文件毫秒级跑完（用不到 1/4）⇒ 下次减半；继续跑到下界为止
+  stepped = false
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(budgetOf(), 1_000, '提前收工 ⇒ 减半')
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  await engine.capturePoint({ chunks: [dir], sessionId: 's-adapt' })
+  assert.equal(budgetOf(), 500, '减到下界即停（回到 captureBudgetMinMs 下界）')
+})
+
+test('R-48 捕获竞态：读到一半被改写的文件不当前像，但进证明名单（绝不被当成新建删掉）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-race', { 'r1.txt': 3, 'r2.txt': 3 })
+  const target = path.join(dir, 'r1.txt')
+  let mutated = false
+  const engine = makeEngine(fx, {
+    captureConcurrency: 1,
+    readFile: async (file: string) => {
+      const bytes = await fs.readFile(file)
+      if (file === target && !mutated) {
+        mutated = true
+        await fs.writeFile(file, 'XYZ') // 同长度原地改写：身份（mtimeNs/ctimeNs）必变
+      }
+      return bytes
+    },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-race' })
+  const payload = captured.point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  assert.equal(mutated, true)
+  assert.equal(payload.files.some((f) => f.path === target), false, '竞态中的文件不得当作前像')
+  assert.ok(
+    payload.unreadableFiles.some((f) => f.path === target && f.reason === 'changed-during-read'),
+    JSON.stringify(payload.unreadableFiles),
+  )
+  const created = path.join(dir, 'created.txt')
+  await fs.writeFile(created, 'NEW')
+  const preview = await engine.preview(captured.point?.id ?? '')
+  assert.equal(preview.workspace.createdRefusedReason, null, '证明名单仍完整（unreadableFiles 也是证明）')
+  assert.deepEqual(preview.workspace.removals, [created])
+  const rewound = await engine.rewind({
+    id: captured.point?.id ?? '', userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true,
+  })
+  assert.equal(rewound.ok, true)
+  assert.equal(await readText(target), 'XYZ', '竞态文件绝不能被当成新建删掉')
+  assert.equal(await readText(path.join(dir, 'r2.txt')), 'xxx')
+})
+
+test('R-49 记录与读预算解耦：已知内容不占读槽位 ⇒ 大仓库从第二个点起记录全量', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-entries', {})
+  const names = Array.from({ length: 12 }, (_, i) => 'e-' + String(i).padStart(2, '0') + '.txt')
+  for (const name of names) await fs.writeFile(path.join(dir, name), 'x')
+  // 每回合只允许读 5 条**新内容**（maxFiles 约束的是读，不是「记录多少条」）
+  const engine = makeEngine(fx, { maxFiles: 5 })
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p1 = first.point?.workspace.payload
+  assert.equal(p1?.files.length, 5, '第一点：只有 5 条新内容被读进来')
+  assert.equal(p1?.truncated, true, '还有新内容没读 ⇒ 如实标截断')
+  const second = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p2 = second.point?.workspace.payload
+  assert.equal(p2?.files.length, 10, '已知的 5 条不占槽位、一律进记录：' + JSON.stringify(p2?.files.map((f) => path.basename(f.path))))
+  const third = await engine.capturePoint({ chunks: [dir], sessionId: 's-entries' })
+  const p3 = third.point?.workspace.payload
+  assert.equal(p3?.files.length, 12, '全部已知 ⇒ 记录必须是全量（这是「任何大小都收敛」的判据）')
+  assert.equal(p3?.truncated, false, '没有新内容要读 ⇒ 不该再标截断')
+  assert.deepEqual(p3?.files.map((f) => path.basename(f.path)), names, '记录顺序仍按路径有序')
+})
+
+test('R-50 降级口径：设计内跳过（符号链接 / 文件级忽略）不构成「留得不完整」；缺内容才算', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  // 分块根：一个正常文件 + 一个被文件级忽略规则跳过的文件（等价于「符号链接被跳过」那类设计内跳过）
+  const dir = await makeSizeDir(fx, 'cap-degraded', { 'keep.txt': 3 })
+  await fs.writeFile(path.join(dir, 'old.log'), 'OLD')
+  await fs.writeFile(path.join(dir, '.dsh-rollback-ignore'), '*.log' + '\n')
+  const engine = makeEngine(fx)
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-degraded' })
+  const p1 = first.point?.workspace.payload
+  assert.ok(p1 !== null && p1 !== undefined)
+  assert.ok(p1.skippedCount > 0, '文件级忽略必须逐条留痕：' + JSON.stringify(p1.skipped))
+  assert.equal(p1.skipped.some((e) => e.reason === 'ignored'), true)
+  assert.equal(p1.truncated, false)
+  assert.equal(first.point?.workspace.degraded, false, '设计内跳过 ⇒ 不得报「留得不完整」')
+  assert.equal(first.point?.workspace.reasonCode, null)
+  const seg = (await engine.list()).points[0]?.segments.find((s) => s.state === 'workspace')
+  assert.equal(seg?.degraded, false, '列表摘要同样不得降级')
+  assert.equal(seg?.reasonCode, null)
+
+  // 对照：真的缺内容（超单文件上限被跳过）⇒ 必须降级且如实给码
+  const dir2 = await makeSizeDir(fx, 'cap-degraded-real', { 'big.bin': 200 })
+  const engine2 = makeEngine(fx, { maxFileBytes: 64 })
+  const second = await engine2.capturePoint({ chunks: [dir2], sessionId: 's-degraded2' })
+  assert.equal(second.point?.workspace.degraded, true)
+  assert.equal(second.point?.workspace.reasonCode, 'capture-truncated')
+  assert.ok(second.point?.workspace.payload?.skipped.some((e) => e.reason === 'too-large'))
+})
+
+test('R-51 预览快路径：身份命中时不再真读工作区文件（大仓库预览的 13 s 就在这一步）', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-preview', { 'a.txt': 5, 'b.txt': 5, 'c.txt': 5 })
+  const reader = countingReader()
+  const engine = makeEngine(fx, { readFile: reader.seam })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-preview' })
+  const id = captured.point?.id ?? ''
+  reader.reset()
+  const first = await engine.preview(id)
+  assert.equal(first.workspace.different, 0, '三条全都一致')
+  assert.equal(reader.reads.length, 0, '身份命中 ⇒ 预览一次都不读内容：' + JSON.stringify(reader.reads))
+  // 改一条：**只有它**需要被真读（其余仍走快路径）
+  await fs.writeFile(path.join(dir, 'b.txt'), 'ZZZZZ')
+  reader.reset()
+  const second = await engine.preview(id)
+  assert.equal(second.workspace.different, 1)
+  assert.deepEqual(reader.reads, [path.join(dir, 'b.txt')], '只真读被改的那一条：' + JSON.stringify(reader.reads))
+})
+
+test('R-52 回退快路径：已一致的条目不读对象、不写盘；用不到的对象坏掉不再中止整次回退', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = await makeSizeDir(fx, 'cap-rewind-fast', { 'k1.txt': 5, 'k2.txt': 5 })
+  const reader = countingReader()
+  const engine = makeEngine(fx, {
+    readFile: reader.seam,
+    writeFile: async () => { throw new Error('不该写任何文件') },
+  })
+  const captured = await engine.capturePoint({ chunks: [dir], sessionId: 's-rewind-fast' })
+  const id = captured.point?.id ?? ''
+  reader.reset()
+  const rewound = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true })
+  const ws = rewound.segments.find((s) => s.state === 'workspace')
+  assert.equal(rewound.outcome, 'restored', JSON.stringify(ws))
+  assert.equal(ws?.reasonCode, 'nothing-to-restore', '全部已一致 ⇒ 0 变更')
+  assert.equal(reader.reads.length, 0, '身份命中 ⇒ 阶段 2/3 一次都不读：' + JSON.stringify(reader.reads))
+
+  // 新语义：**用不到的对象**坏掉不该中止整次回退（真要用它时仍会 object-missing 硬失败）
+  const payload = (await engine.read(id)).point?.workspace.payload
+  assert.ok(payload !== null && payload !== undefined)
+  await fs.rm(path.join(engine.storeDir, 'objects', payload.files[0]?.object ?? ''))
+  const second = await engine.rewind({ id, userConfirmed: true, guardPolicy: 'off', mode: 'files', removeCreated: true })
+  const ws2 = second.segments.find((s) => s.state === 'workspace')
+  assert.equal(second.outcome, 'restored', '用不到的对象坏掉仍应成功：' + JSON.stringify(ws2?.detail))
+  assert.equal(ws2?.reasonCode, 'nothing-to-restore')
+})
+
+test('R-53 清单增量化：第二点只落「相对第一点的增量」，读回来是同一份完整清单', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = path.join(fx.workspaceDir, 'cap-delta')
+  await fs.mkdir(dir, { recursive: true })
+  for (let i = 0; i < 40; i += 1) {
+    await fs.writeFile(path.join(dir, 'f' + String(i).padStart(2, '0') + '.txt'), 'V' + String(i))
+  }
+  const engine = makeEngine(fx)
+  const first = await engine.capturePoint({ chunks: [dir], sessionId: 's-delta' })
+  const firstFull = first.point?.workspace.payload
+  assert.ok(firstFull !== null && firstFull !== undefined)
+  assert.equal(firstFull.fileCount, 40)
+  const manifest = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+    records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+  }
+  void manifest
+  // 每次现读清单（第二点会再写一次清单）
+  const hashOf = async (id: string): Promise<string> => {
+    const fresh = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+      records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+    }
+    return fresh.records.find((r) => r.id === id)?.workspace.payload ?? ''
+  }
+  const payloadPath = (hash: string): string => path.join(engine.storeDir, 'payloads', hash + '.json')
+  const firstHash = await hashOf(first.point?.id ?? '')
+  const firstBytes = (await fs.stat(payloadPath(firstHash))).size
+  t.diagnostic('首点载荷 ' + String(firstBytes) + ' 字节')
+  // 第二点：改 1 个文件 + 新增 1 个 ⇒ 增量应远小于全量
+  await fs.writeFile(path.join(dir, 'f00.txt'), 'CHANGED')
+  await fs.writeFile(path.join(dir, 'new.txt'), 'NEW')
+  const second = await engine.capturePoint({ chunks: [dir], sessionId: 's-delta' })
+  const secondFull = second.point?.workspace.payload
+  assert.ok(secondFull !== null && secondFull !== undefined)
+  assert.equal(secondFull.fileCount, 41, '摘要里的条数必须是全量条数，不是增量条数')
+  const payloadsDir = path.join(engine.storeDir, 'payloads')
+  const names = await fs.readdir(payloadsDir)
+  assert.equal(names.length, 2, '首点全量 + 第二点增量（内容不同 ⇒ 两份载荷）')
+  const secondHash = await hashOf(second.point?.id ?? '')
+  assert.notEqual(secondHash, firstHash)
+  const secondBytes = (await fs.stat(payloadPath(secondHash))).size
+  const secondStored = JSON.parse(await fs.readFile(payloadPath(secondHash), 'utf8')) as { delta?: { base?: string } }
+  assert.equal(secondStored.delta?.base, firstHash, '第二点必须是相对首点的增量视图（而不是又一份全量）')
+  assert.ok(secondBytes < firstBytes / 2, '增量载荷必须明显更小：' + String(secondBytes) + ' vs ' + String(firstBytes))
+  // 读回来必须与「全量捕获」逐条一致（路径序 / sha / bytes / 对象键）
+  const back = await engine.read(second.point?.id ?? '')
+  const rebuilt = back.point?.workspace.payload
+  assert.ok(rebuilt !== null && rebuilt !== undefined)
+  assert.equal(rebuilt.delta, undefined, '读回来必须是物化后的完整清单')
+  const sorted = [...(secondFull.files ?? [])].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  assert.deepEqual(
+    rebuilt.files.map((f) => [f.path, f.sha256, f.bytes, f.object]),
+    sorted.map((f) => [f.path, f.sha256, f.bytes, f.object]),
+    '增量重建的清单必须与全量逐条一致（含补回的 object）',
+  )
+  assert.equal(rebuilt.pathIndex?.object ?? null, secondFull.pathIndex?.object ?? null)
+  // 预览与全量点同一口径：内容一致 ⇒ 零改动
+  const preview = await engine.preview(second.point?.id ?? '')
+  assert.equal(preview.workspace.different, 0)
+  assert.equal(preview.workspace.overwrite, 41, '全量条数（不是增量条数）')
+})
+
+test('R-54 增量链：基准载荷缺失 ⇒ 该点如实失败（绝不返回半份清单）；prune 不删被链引用的载荷', async (t) => {
+  const fx = await makeFixture()
+  t.after(fx.cleanup)
+  const dir = path.join(fx.workspaceDir, 'cap-delta-chain')
+  await fs.mkdir(dir, { recursive: true })
+  for (let i = 0; i < 20; i += 1) await fs.writeFile(path.join(dir, 'g' + String(i) + '.txt'), 'C' + String(i))
+  const engine = makeEngine(fx)
+  const a = await engine.capturePoint({ chunks: [dir], sessionId: 's-chain' })
+  await fs.writeFile(path.join(dir, 'g0.txt'), 'CHANGED')
+  const b = await engine.capturePoint({ chunks: [dir], sessionId: 's-chain' })
+  assert.ok(a.point !== undefined && b.point !== undefined)
+  // 第二点必须是增量（载荷哈希 ≠ 第一点；且它的载荷里有 delta 标记）
+  const payloadsDir = path.join(engine.storeDir, 'payloads')
+  const names = await fs.readdir(payloadsDir)
+  assert.equal(names.length, 2)
+  const manifest = JSON.parse(await fs.readFile(path.join(engine.storeDir, 'index.json'), 'utf8')) as {
+    records: { id: string; workspace: { payload: string | null; payloadChain?: string[] } }[]
+  }
+  const entryOf = (id: string) => manifest.records.find((r) => r.id === id)
+  const payloadPath = (hash: string): string => path.join(payloadsDir, hash + '.json')
+  const bHash = entryOf(b.point.id)?.workspace.payload ?? ''
+  assert.ok(Array.isArray(entryOf(b.point.id)?.workspace.payloadChain), '清单条目必须带上解析所需的链')
+  const bFile = JSON.parse(await fs.readFile(payloadPath(bHash), 'utf8')) as {
+    files?: unknown
+    delta?: { base?: string; added?: unknown; removed?: unknown }
+  }
+  assert.ok(bFile.delta !== undefined && bFile.delta.base !== undefined, '第二点必须落成增量视图')
+  const delta0 = bFile.delta as { base: string; added?: unknown }
+  // 增量视图**故意**让 files 不是数组：不认识 delta 的旧读取器会因形状不符拒绝这个点（fail-closed），
+  // 而不是把「增量那几条」当完整清单去规划删除
+  assert.equal(bFile.files, null, '增量视图的 files 必须为 null')
+  assert.ok(Array.isArray(delta0.added))
+  // 删掉基准载荷：**读第二点必须如实失败**（半份清单会被拿去规划删除，等于删掉其它全部文件）
+  await fs.rm(payloadPath(delta0.base))
+  const broken = await engine.read(b.point.id)
+  assert.equal(broken.point, undefined)
+  assert.ok((broken.error ?? '').includes('record-incomplete'), '如实失败：' + String(broken.error))
+})
+
 test('R-32 取消信号：已中止 ⇒ 在文件边界停下（部分点 + budget-time 留痕，绝不整份跑完）', async (t) => {
   const fx = await makeFixture()
   t.after(fx.cleanup)