dsh-config-manager 0.1.72 → 0.1.76

package/lib/core/rollback-point.d.ts

@@ -1,9 +1,19 @@
 import { type DiffHunk } from '../utils/line-diff.ts';
+import { ROLLBACK_DEFAULT_LEDGER_BYTES } from './rollback-ledger.ts';
 export declare const ROLLBACK_SCHEMA_VERSION = 2;
 /** 回滚点库目录名（dataDir/rollback-points）——路由族 /recovery/rollback-points/* 同源 */
 export declare const ROLLBACK_POINTS_DIR_NAME = "rollback-points";
+/**
+ * 台账**清单**文件名（v3，issue #89）：它只是一份小清单（元数据 + 段摘要），
+ * 完整记录在 records/<id>.json、工作区载荷在 payloads/<sha256>.json —— 清单里绝不含大数组。
+ */
 export declare const ROLLBACK_LEDGER_NAME = "index.json";
 export declare const ROLLBACK_OBJECTS_DIR_NAME = "objects";
+/**
+ * 台账字节预算（records/ + payloads/）的缺省值，可由 RollbackEngineOptions.ledgerBytesBudget 覆盖。
+ * 为什么需要它：ROLLBACK_MAX_RECORDS（50）只限**条数**；本机实测 50 条 = 473 MB 直接把宿主撑爆。
+ */
+export { ROLLBACK_DEFAULT_LEDGER_BYTES };
 /** 全局自动点上限（S6）；protected / guard 点不占预算、只进不出 */
 export declare const ROLLBACK_MAX_RECORDS = 50;
 /** 每会话自动点上限（S6） */
@@ -81,6 +91,53 @@ export declare const ROLLBACK_DEFAULT_SESSION_QUIESCENT_MS = 30000;
 /** 轮询回退的间隔上界（S1：会话日志 mtime ≤5 s 轮询） */
 export declare const ROLLBACK_DEFAULT_POLL_INTERVAL_MS = 5000;
 export declare const ROLLBACK_LEFTOVER_LIST_LIMIT = 20;
+/**
+ * 工作区捕获的**挂钟时间预算**（缺省 30 s）。
+ *
+ * 为什么需要（对标 dsh-turn-rewind 的 `deadline.ts`、dsh-checkpoint-rewind 至今未合并的 PR #25）：
+ * 捕获路径此前只有「文件数 / 总字节 / 单文件字节」三个**规模**上限，没有**时间**上限 ——
+ * 一个「文件数很多但总量不大」的工作区能让 walk + stat + sha256 跑很久。
+ * 超预算**不是失败**：已收条目照常成点（ok=true），未走查的部分按 `budget-time` 逐条留痕、
+ * `truncated` 置真 ⇒ 删除集自动 fail-closed（证明名单不完整就一条都不删）。
+ */
+export declare const ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS = 30000;
+/**
+ * 自适应预算区间（见 RollbackEngineOptions.captureBudgetMs）：上一次留点被截断 ⇒ 下次 ×2，
+ * 上一次只用掉不到 1/4 ⇒ 下次 ÷2。区间外不再调整（避免无限拉长 / 缩到不可用）。
+ */
+export declare const ROLLBACK_MIN_CAPTURE_BUDGET_MS = 10000;
+export declare const ROLLBACK_MAX_CAPTURE_BUDGET_MS = 120000;
+/**
+ * 捕获期「读内容 + 写对象仓」的并发上限。
+ *
+ * 为什么必须并发：真机实测（34k 文件 / 512 MiB）一次全量捕获 175 s，其中 **148 s 花在
+ * 31,702 次对象写**（一次 4.7 ms：temp + fsync + rename），而走查本身只要 0.66 s。
+ * 对象写入是纯 I/O，串行做等于把预算全花在等待上 ⇒ 覆盖永远只有一小半。
+ * 并发上限与**在飞字节闸门**共同限流（在飞内容上界 = `captureInFlightBytes`）。
+ */
+export declare const ROLLBACK_DEFAULT_CAPTURE_CONCURRENCY = 16;
+/**
+ * 捕获期**读入内存、尚未落对象仓**的内容字节上限（真正的内存闸门）。
+ *
+ * 为什么必须独立于 `maxFileBytes`（0.1.74 真机闪退事故，2026-10-16）：
+ *  `maxFileBytes` 的缺省是**总量预算** `maxBytes`（512 MiB）。并发捕获把闸门接到它上面，
+ *  于是「同时在飞的内容」可以到 ~512 MiB —— 串行实现的上界是「一份文件」，并发实现的
+ *  上界是「闸门限额」，两者差着两三个数量级。真机表现：发出消息后 1–2 s（= `turn/start`
+ *  开始留点）DSH Desktop 宿主被系统终止 ⇒ 桌面闪退（无 JS 栈、插件零错误、
+ *  退出码是「被外部终止」形状）。这里取一个小常量当闸门；要放宽只能显式传
+ *  `captureInFlightBytes`，且被 `maxBytes` 夹住。
+ */
+export declare const ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES: number;
+/** 捕获阶段①的 stat 批大小：判定仍严格按顺序，只是 stat 并发取（真机 34k 次 stat 从 5 s → <1 s） */
+export declare const ROLLBACK_CAPTURE_STAT_BATCH = 128;
+/**
+ * 捕获期**候选名单**上限（不是入点上限）：必须显著大于 maxFiles，否则「缺口优先」排序作用不到
+ * 那些排在遍历顺序尾部、上一回合没覆盖到的文件（它们连候选都进不了 ⇒ 覆盖率永远不收敛）。
+ * 走查本来就会把每条路径记进 walked（路径索引的来源），这里多留的只是候选数组本身。
+ */
+export declare const ROLLBACK_CAPTURE_LIST_LIMIT = 200000;
+/** 走查中断时逐条记下的「没进去的子树」上限；超出即放弃精确范围，退回全局 fail-closed */
+export declare const ROLLBACK_UNWALKED_DIRS_LIMIT = 200;
 /**
  * 「删除回退点之后新建的路径」的**整套上限**（用户 2026-10-11 定案 A）。
  * 超过就整套拒绝（fail-closed），绝不删一半 —— 半套删除既没有可解释的状态，也无法整体回滚。
@@ -112,6 +169,14 @@ export declare const ROLLBACK_PREVIEW_DIFF_TOTAL_WORK = 32000000;
 export declare const ROLLBACK_FILE_DIFF_LIMITS: {
     readonly maxFileBytes: number;
     readonly context: 3;
+    /**
+     * Myers 编辑距离上限（2026-10-15 用户：不该动辄出现「已按整块替换展示」）。
+     * 实测（本仓 rollback-point.ts 的 4983 行 × 2492 行版本对）：D 在 3000~4000 就能拿到
+     * 最小编辑脚本 —— 耗时 ≤70 ms；代价是回溯的 V 快照 O(D²)，RSS 峰值 +~100 MB。
+     * 缺省那档 400 会让几千行里的普通改动一律退化成「整块替换」，那正是用户看到的那条提示；
+     * 单文件是**按需点开**的一屏，这点内存换「真差异」划算。再大就换算法，不加预算。
+     */
+    readonly maxD: 4000;
 };
 /** 恢复顺序（工作区在前；工作区失败即中止后面的会话段） */
 export declare const ROLLBACK_REWIND_ORDER: readonly ['workspace', 'session'];
@@ -157,7 +222,14 @@ export type RollbackCode = 'ok' | 'deleted' | 'storage-unavailable' | 'ledger-un
  * 界面必须说两句不同的话（「这点没记录文件」vs「工作区已与该点一致」），
  * 而 `detail` 是技术细节、**不能**当用户可见分派依据。只出现在 segments[].reasonCode。
  */
- | 'no-recorded-files' | 'mutation-locked' | 'method-not-allowed' | 'session-missing' | 'session-out-of-root' | 'session-too-large' | 'session-active' | 'session-fork-unavailable' | 'fork-failed' | 'capture-failed' | 'capture-truncated' | 'capture-degraded' | 'no-chunks' | 'chunk-not-absolute' | 'chunk-not-found'
+ | 'no-recorded-files' | 'mutation-locked' | 'method-not-allowed' | 'session-missing' | 'session-out-of-root' | 'session-too-large' | 'session-active'
+/**
+ * 子代理会话（`header.origin === 'subagent'`）：**不自动留点**。
+ * 它的工作区与父会话相同、回合号是自己的，留点既与父会话重复又只挤占预算；
+ * 用户在侧栏看到的是嵌套在父对话下的子代理，不需要单独回退。
+ * 读不到 `origin`（老宿主）时**不加判定** —— 绝不因为读不到就少留点。
+ */
+ | 'subagent-session' | 'session-fork-unavailable' | 'fork-failed' | 'capture-failed' | 'capture-truncated' | 'capture-degraded' | 'no-chunks' | 'chunk-not-absolute' | 'chunk-not-found'
 /** 单文件差异：该路径**不在**这个回滚点的记录里（收窄：绝不把本端点做成任意路径读取器）。 */
  | 'file-not-recorded';
 /** 结构化指引 / 告警：code 供界面映射字典键，detail 是技术标识（路径 / errno / 计数）。 */
@@ -181,7 +253,8 @@ export interface RollbackSkippedEntry {
     /**
      * link（符号链接/junction，不跟随）/ missing / not-a-file / self-store /
      * dep-dir（运行时依赖目录，整棵忽略）/ ignored（用户忽略规则命中）/ too-large（超单文件上限）/
-     * budget-bytes（加它会超总量预算）/ budget-files（文件数预算用尽）
+     * budget-bytes（加它会超总量预算）/ budget-files（文件数预算用尽）/
+     * asar-container（含 `.asar` 段的路径：宿主会把它当容器解析、畸形夹具能带走宿主，因此绝不碰）
      */
     reason: string;
 }
@@ -203,7 +276,28 @@ export interface RollbackPathIndex {
 export interface RollbackWorkspacePayload {
     /** 显式路径分块：恢复只在这些分块内覆盖 */
     chunks: string[];
+    /**
+     * 记录在案的**文件条目数**。**必须自带**（不能再用 `files.length`）：增量视图下 `files` 只是
+     * 「相对基准新增/改写的子集」，而摘要（界面上的条数 / 可恢复判定）要的是全量条数。
+     */
+    fileCount?: number;
     files: RollbackWorkspaceFile[];
+    /**
+     * **存盘专用**：这份载荷是「相对某个基准载荷的增量」（见 rollback-ledger 的 resolvePayload）。
+     * 只在写盘那一刻存在 —— 任何读路径（readRecord / 预览 / 回退 / 对象回收）拿到的都是**物化后**
+     * 的完整 `files`（`delta` 已被抹掉）。**绝不把带 delta 的对象交给消费者**：它看起来像一份
+     * 「只有这几条记录」的完整清单，拿去规划删除会删掉其它全部文件。
+     */
+    delta?: {
+        /** 基准载荷的内容寻址哈希（必须在 prune/回收时一并保活） */
+        base: string;
+        /** 基准自己的依赖链（深→浅，含基准），保活用 */
+        baseChain: string[];
+        /** 相对基准**不再存在**的路径（逐字，与捕获产出的绝对路径同形） */
+        removed: string[];
+        /** 相对基准**新增 / 改写**的条目（`files` 在增量视图下为 null） */
+        added?: RollbackWorkspaceFile[];
+    };
     skipped: RollbackSkippedEntry[];
     /**
      * 整棵跳过的「运行时依赖目录」（忽略规则 = 全仓唯一来源 EXCLUDED_DEP_DIR_NAMES，当前 node_modules）。
@@ -232,6 +326,22 @@ export interface RollbackWorkspacePayload {
      * 文件级忽略**不**置它：被忽略的文件既进 skipped、也进 walked（路径索引来源）⇒ 名单照样完整。
      */
     ignoreIncomplete?: boolean;
+    /**
+     * true = 走查被**时间预算 / 取消信号**中断 ⇒ 剩余子树**一条都没进任何名单**
+     * （不在 files / skipped / walked 里）⇒ 证明名单**不完整** ⇒ 删除集整体拒绝（fail-closed）。
+     *
+     * 与 `truncated` 的**关键区别**：`truncated` 的三种成因（文件数 / 总字节 / 单文件超限）都是
+     * 「继续遍历 + 逐条留痕」，名单依然完整，所以**不**拒删；只有「整棵子树根本没被走查」才必须拒删
+     * —— 否则那些文件会被判成「留点后才新建」而被删掉（数据丢失）。
+     * 老台账（本字段诞生前写下的点）一律没有它：按「名单完整」处理（与旧行为一致）。
+     */
+    walkIncomplete?: boolean;
+    /**
+     * 走查被中断时**栈里还没进去的子树**（精确到目录）。有它 ⇒ 拒删只覆盖这些子树
+     * （分子树 fail-closed），而不是把整个工作区的删除全关掉；缺它（老台账 / 栈太深被截断）
+     * ⇒ 退回全局拒删。与 walkIncomplete 一起看：后者是「安全判据」，本字段是「精确范围」。
+     */
+    unwalkedDirs?: string[];
     /** 命中文件数 / 字节上限（内容未全部进来，已如实留痕） */
     truncated: boolean;
     bytes: number;
@@ -347,12 +457,33 @@ export interface RollbackPointSummary {
     /** 继承视图里「状态真正的归属会话」（= 祖先会话 id；与 `inheritedFrom` 成对出现） */
     inheritedSessionId?: string | null;
 }
+/**
+ * 台账（records/ + payloads/）的可观测快照。
+ * 路由层转发给界面时必须**照抄字段名与形状**（issue #89 的交付契约）。
+ */
+export interface RollbackLedgerStatus {
+    /** 清单里的记录条数 */
+    records: number;
+    /** records/ + payloads/ 当前总字节 */
+    bytes: number;
+    /** 生效的字节预算（缺省 ROLLBACK_DEFAULT_LEDGER_BYTES） */
+    budgetBytes: number;
+    /** 本进程内被**预算**淘汰的自动点累计数（条数淘汰不计入） */
+    evicted: number;
+    /**
+     * 当前磁盘字节**已超**预算、且已无处可淘汰（典型：单条点本身就大于预算）。
+     * 界面据此说「台账已超预算、无法再自动回收」，绝不静默成「一切正常」。
+     */
+    overBudget: boolean;
+}
 export interface RollbackStorageStatus {
     available: boolean;
     root: string;
     detail?: string;
     guidance: RollbackGuidance[];
     requirements: readonly string[];
+    /** 新增，可选（不破坏既有构造点）；存储栈不可用时缺省 */
+    ledger?: RollbackLedgerStatus;
 }
 /** 捕获一个回滚点的输入（宿主/测试构造；无 HTTP capture 端点） */
 export interface RollbackPointInput {
@@ -372,6 +503,11 @@ export interface RollbackPointInput {
     chunks?: readonly string[];
     note?: string | null;
     protect?: boolean;
+    /**
+     * 调用方的取消信号（插件卸载 / 会话销毁）：已中止时捕获在**下一个文件边界**停下，
+     * 已收条目照常成点（部分点 + truncated）。缺省不传 = 只受时间预算约束。
+     */
+    signal?: AbortSignal;
 }
 export interface RollbackCaptureResult {
     ok: boolean;
@@ -710,6 +846,33 @@ export interface RollbackEngineOptions {
     maxGuardsPerSession?: number;
     /** **全局** guard 点上限（缺省 50，见 ROLLBACK_MAX_GUARDS；与自动点的 maxRecords 无关） */
     maxGuards?: number;
+    /**
+     * 台账字节预算（records/ + payloads/ 的总字节，缺省 ROLLBACK_DEFAULT_LEDGER_BYTES）。
+     * 超预算时**只淘汰最旧的 auto 点**（guard / protected 不淘汰，沿用 selectPrune 的类别口径）。
+     */
+    ledgerBytesBudget?: number;
+    /**
+     * 工作区捕获的挂钟时间预算（毫秒，缺省 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS）。
+     * 超时留**部分点**，不拒绝留点；见该常量的说明。
+     *
+     * 运行期**自适应**：被截断 ⇒ 下次翻倍；用得很少 ⇒ 下次减半（区间见
+     * ROLLBACK_MIN/MAX_CAPTURE_BUDGET_MS）。回退期走查的预算见 rewindBudgetMs。
+     */
+    captureBudgetMs?: number;
+    /** 自适应区间下界（缺省 ROLLBACK_MIN_CAPTURE_BUDGET_MS；测试可注入更小值） */
+    captureBudgetMinMs?: number;
+    /** 自适应区间上界（缺省 ROLLBACK_MAX_CAPTURE_BUDGET_MS；测试可注入更小值） */
+    captureBudgetMaxMs?: number;
+    /** 回退期走查的时间预算（缺省 = captureBudgetMs 初值；**不参与自适应**） */
+    rewindBudgetMs?: number;
+    /** 捕获期读 + 写并发上限（缺省 ROLLBACK_DEFAULT_CAPTURE_CONCURRENCY，1..64） */
+    captureConcurrency?: number;
+    /**
+     * 捕获期**在飞内容字节**上限（缺省 ROLLBACK_DEFAULT_CAPTURE_INFLIGHT_BYTES = 32 MiB，
+     * 有效范围 1..maxBytes）。与 `maxFileBytes`（单文件「要不要读」的判据）是两件事：
+     * **这个才是并发的内存闸门**。
+     */
+    captureInFlightBytes?: number;
     guardPolicy?: RollbackGuardPolicy;
     /** 存储栈探针（缺省 = 真实磁盘探测）；注入失败探针可测「缺失时仍可挂载」 */
     storage?: RollbackStorageProbe;
@@ -722,6 +885,12 @@ export interface RollbackEngineOptions {
      * 测试用它计数「真的读了几次」，从而钉住路径身份缓存命中时**零重读**。
      */
     readFile?: (target: string) => Promise<Uint8Array>;
+    /**
+     * 台账读盘观测 seam（缺省不观测）：每次「读一条记录文件 / 一份载荷文件」前回调一次。
+     * 与 readFile seam 同一用途 —— 测试用它**确定性地**计数「一次留点到底读了几份记录」，
+     * 而不是靠无法复现的堆采样（issue #89 的内存护栏）。
+     */
+    ledgerReadFile?: (file: string) => void;
     /** E1：预览行级统计的规模上限（缺省见 ROLLBACK_PREVIEW_DIFF_*）；注入小值即可确定性地覆盖 truncated 分支 */
     previewDiffMaxFileBytes?: number;
     previewDiffMaxTotalBytes?: number;
@@ -730,6 +899,18 @@ export interface RollbackEngineOptions {
     /** best-effort 日志（清理失败等；绝不抛给调用方） */
     log?: (line: string) => void;
 }
+/**
+ * 路径里是否存在以 `.asar` 结尾的段（**捕获 / 走查期一律不碰这类路径**）。
+ *
+ * 为什么（真机事故，0.1.76）：Electron 宿主对任何含 `.asar` 段的路径**启用了 asar 虚拟化** ——
+ * 即使那只是个普通文件，`fs.stat`/`readdir`/`read` 也会被接管去当容器解析。工作区里只要躺着一枚
+ * **畸形** `.asar`（测试夹具、被打断的打包残留），宿主进程就会被原生层带走：crashpad
+ * `not connected`、退出码 4294930435 ⇒ DSH Desktop 闪退（无 JS 栈、插件零错误）。
+ * 实测（本仓真机捕获、同一份输入）：`.tmp` 下 19 枚 `.asar` 夹具在场 → Electron 进程死；
+ * 全部改名后 → 同一趟捕获 9 s 跑完、退出码 0。
+ * `.asar.unpacked` 是**真目录**（段名不以 `.asar` 结尾）⇒ 不拦。
+ */
+export declare function hasAsarSegment(target: string): boolean;
 /** child 是否等于 parent 或位于其下（win32 折叠大小写；段边界判定） */
 export declare function isInsidePath(child: string, parent: string): boolean;
 /**
@@ -775,6 +956,11 @@ export declare function resolveTurnBoundary(events: readonly RollbackEventLike[]
     code: 'no-boundary';
     detail: string;
 };
+/**
+ * 记录在案的文件条目数：优先用载荷自带的 `fileCount`（增量视图下 `files` 可能只是子集），
+ * 老载荷没有该字段才回落到 `files.length`。
+ */
+export declare function workspaceFileCount(payload: RollbackWorkspacePayload | null): number;
 export declare function summarizeRollbackPoint(record: RollbackPointRecord): RollbackPointSummary;
 /** 浅层形状校验：台账被篡改 / 半写时不把它当记录用（宁可当「读不到」）。 */
 export declare function isRollbackPointRecord(value: unknown): value is RollbackPointRecord;
@@ -791,6 +977,7 @@ export declare class RollbackPointEngine {
     private readonly maxFiles;
     private readonly maxBytes;
     private readonly maxFileBytes;
+    private readonly captureInFlightBytes;
     private readonly maxSkippedEntries;
     private readonly sessionMaxBytes;
     private readonly sessionQuiescentMs;
@@ -820,9 +1007,49 @@ export declare class RollbackPointEngine {
     private forkLinksAt;
     private forkLinksComplete;
     /** 会话日志头缓存（mtime + size 失效；只服务 fork 链扫描） */
+    /**
+     * **本进程**最近一次成功留点的工作区摘要（清单增量化的基准）。
+     *
+     * 为什么是内存而不是读盘：一次留点只准读清单（L-08 / issue #89）—— 读上一份 12 MB 载荷去算差异
+     * 正是那条被消灭的路。内存量 ≈ 每文件一个 `sha:bytes:chunk` 串（3.4 万文件约几 MB），
+     * 与已有的身份缓存（`pathCache`）同量级；进程重启后第一次留点落全量锚点，随后继续链。
+     */
+    private deltaBase;
     private readonly forkHeaderCache;
-    /** 继承判据用的台账快照（TTL 缓存；避免每个 turn/start 都读整份台账） */
+    /** 继承判据用的台账快照（TTL 缓存；只缓存**清单条目**，绝不缓存完整记录） */
     private ledgerSnapshotCache;
+    /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
+    private readonly ledger;
+    private readonly ledgerBytesBudget;
+    /**
+     * 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS）。**可变**：
+     * 每次留点后按「是否被截断 / 用掉多少」自适应（见 ROLLBACK_MIN/MAX_CAPTURE_BUDGET_MS）。
+     */
+    private captureBudgetMs;
+    /** 自适应区间下界 / 上界（构造期定死，运行期只调 captureBudgetMs） */
+    private readonly captureBudgetMinMs;
+    private readonly captureBudgetMaxMs;
+    /** 回退期走查的时间预算（与捕获预算分开：自适应不该顺手拉长回退期的走查） */
+    private readonly rewindBudgetMs;
+    /** 捕获期读 + 写并发上限 */
+    private readonly captureConcurrency;
+    /** 对象仓目录已确认存在（省掉每个对象一次 mkdir） */
+    private objectsDirReady;
+    /**
+     * 本回合对象名单快照（一次 readdir 顶掉「每个候选一次 fs.access」；真机 34k 次 access ≈ 3.7 s）。
+     * null = 读不到名单（首次还没建目录/异常）⇒ 回落逐条 objectExists。
+     * 只保证「写进去的立刻可见」：捕获期间被**并发删除**的对象可能仍被判为存在 —— 那一路由
+     * 读取侧（readObject + 哈希校验）响亮失败，不会静默给出错误的 before 内容。
+     */
+    private captureObjectNames;
+    /**
+     * 启动期一次性初始化（流式迁移 v2 -> v3 + 孤儿 tmp 清理）的惰性单飞。
+     * 为什么惰取而不是构造时同步跑：构造发生在每个请求路径上，同步扫盘/迁移会把请求卡死；
+     * 而「每回合都扫一遍」正是要避免的浪费 —— 所以只跑一次并记住结果。
+     */
+    private initPromise;
+    /** 启动期初始化失败的如实记录（读路径必须报出来，绝不假装台账是空的） */
+    private initError;
     constructor(options: RollbackEngineOptions);
     /** 回滚点库根目录（只读侦察用；写路径全部经本类的门） */
     get storeDir(): string;
@@ -835,8 +1062,37 @@ export declare class RollbackPointEngine {
      * node_modules）逐条记录、**不计入 skippedCount**，因此不会把点判成 degraded。
      */
     private recordSkip;
+    /**
+     * 打开一次回退的前像暂存目录（`<root>/undo/<pid>-<ts36>-<8hex>/`）。
+     * 返回 null = 建不出来（权限 / 磁盘满）⇒ 调用方必须**零写入失败**。
+     */
+    private openUndoStager;
     private writeFile;
+    /**
+     * 启动期一次性初始化（惰性单飞）：先**流式**迁移 v2 单文件 -> v3，再清理崩溃残留的原子写 tmp。
+     *
+     * 为什么惰取而不是在构造里同步跑：引擎在每个请求路径上都会被新建（路由层不缓存引擎），
+     * 构造里同步扫盘/迁移会把请求卡死；而「每回合扫一遍」又是纯浪费 —— 所以只跑一次并记住结果。
+     * 迁移失败**不抛**：如实记进 initError，由读路径报出来，并**拒写**（绝不覆盖还没迁完的 v2 文件）。
+     */
+    private ensureReady;
+    private runInit;
     storageStatus(): Promise<RollbackStorageStatus>;
+    /** 台账可观测快照（清单条数 + 磁盘字节 + 预算 + 本进程淘汰计数） */
+    private ledgerStatus;
+    /** 对象仓目录只 mkdir 一次（每个对象各 mkdir 一次是纯白花的 syscall） */
+    private ensureObjectsDir;
+    /**
+     * 写内容寻址对象（对象文件名 = 内容 SHA-256）。
+     *
+     * **为什么这里不用 atomicWriteFile**：那是给「可写配置文件」用的强原子写（同目录 tmp → fsync →
+     * rename），真机实测一次约 4.7 ms —— 34k 文件的工作区一次全量捕获 148 s 全花在它上面（走查本身
+     * 只要 0.66 s）。对象仓的正确性要求不同：文件名即内容哈希 ⇒
+     *   · 用 'wx' **独占创建最终名**本身已是原子的（不覆盖已有对象；并发同写只有一方成功）；
+     *   · 半截 / 被篡改的内容在读取侧必然过不了哈希校验（readObject + sha256Hex）⇒ 按「读不出」
+     *     处理并 fail-closed，绝不会冒充有效前像；
+     *   · 不做 fsync：回滚点是尽力而为的本地快照，不为掉电持久性付出每文件一次 fsync 的代价。
+     */
     private writeObjectWithHash;
     /** 对象仓里是否真有这个 blob（缓存命中时校验；任何异常一律按「没有」处理） */
     private objectExists;
@@ -855,10 +1111,40 @@ export declare class RollbackPointEngine {
     /**
      * 列出一个显式分块内的候选文件（不跟随符号链接 / junction；跳过与读不到都留痕）。
      * 返回 null = 该分块本身不可用（不存在 / 是链接 / 非常规文件），细节已写进 sink。
+     *
+     * `truncated` 与 `walkAborted` 是**两件事**：前者只说「本次列表不完整」（文件数上限 / 提交上限），
+     * 后者说「走查被预算或取消打断，栈里还有没进去的子树」—— 只有后者才意味着那些路径
+     * **一条都没进任何名单**，调用方必须据此让删除集 fail-closed。
      */
     private listChunkFiles;
     private captureWorkspace;
     /** 用户忽略规则是否命中该路径（只认「相对分块根」的斜杠路径） */
+    /**
+     * 处理一个分块的候选文件（**两阶段**）。
+     *
+     *  ① **顺序判定**（与旧的串行实现逐条一致，保证预算 / 计数 / 字节上限完全确定）：
+     *     文件数上限、时间预算、自身数据区、stat、单文件上限、总量上限、身份缓存 + 对象存在性
+     *     → 得出「当场入点（缓存命中）」还是「要真读」，该跳过的**当场**按原有 reason 逐条留痕。
+     *     stat 按**有序批**并发取（判定仍严格按顺序），并用「一次 readdir 的对象名单快照」代替
+     *     每个文件一次 fs.access —— 这两处是稳态成本的大头（真机实测各占 ~5 s / ~3.7 s）。
+     *  ② **并发读 + 哈希 + 落对象仓**：这是捕获耗时的**唯一大头**（真机 148 s / 31,702 个对象，
+     *     96% 的时间），用 captureConcurrency 个 worker 并发跑；并用**在飞字节闸门**保证
+     *     「同时在飞的内容字节 ≤ captureInFlightBytes」。**不是** maxFileBytes —— 它缺省 =
+     *     总量预算（512 MiB），拿它当闸门等于允许把整个点的预算同时驻留（0.1.74 闪退根因）。
+     *
+     * 返回本分块**真正入点**的文件数（调用方据此推进 maxFiles 预算）。
+     * 没判到 / 没读完的条目一律逐条进 skipped(budget-time)，绝不静默丢弃。
+     */
+    private captureChunkCandidates;
+    /**
+     * 缺口优先排序：身份缓存里**没有**的路径排前面。
+     *
+     * 为什么：预算固定时按目录顺序走查，同一个「已覆盖且便宜」的前缀每回合都会吃掉全部预算，
+     * 尾部永远进不来（真机：34k 文件每次只覆盖 1/5，且五次都是同一批 outputs/ 前缀）。
+     * 未覆盖的排前面 ⇒ 每个点都在补上一次的缺口，覆盖率随回合**单调收敛**到 100%。
+     * 组内保持走查顺序（稳定），因此同一输入下的结果仍然确定。
+     */
+    private orderByCoverage;
     private ignoredByRules;
     /** 读文件（可注入 seam；只用于捕获期读内容这一步） */
     private readFileBytes;
@@ -870,6 +1156,13 @@ export declare class RollbackPointEngine {
      * 用毫秒换算同样不行：会把「同一毫秒内的两次写」当成同一个身份。
      * 读不到身份（文件消失 / 权限 / 平台不支持 bigint stat）→ null ⇒ 回落全量真读。
      */
+    /**
+     * 一次 bigint stat 拿到阶段①需要的**全部**东西（是否文件 / 大小 / mtime / 身份）。
+     * 旧实现「fs.stat + pathIdentityOf」每文件 stat 两次，真机 34k 文件白花约 5 s。
+     */
+    private fileStatOf;
+    /** 对象名单快照（每个捕获回合一次 readdir）；读不到则返回 null ⇒ 调用方回落逐条判断 */
+    private objectNamesSnapshot;
     private pathIdentityOf;
     private pathCachePath;
     /**
@@ -878,6 +1171,20 @@ export declare class RollbackPointEngine {
      */
     private loadPathCache;
     /** 缓存命中：身份键存在、且路径逐字相同（身份被复用也绝不认）。 */
+    /**
+     * 「这条记录的当前内容**仍然是它**吗」的身份快路径 —— **预览与执行共用同一条判据**
+     * （否则「预览说会改的 = 实际会改的」这条不变式会被打破）。
+     *
+     * 判据：路径身份（dev:ino:size:mtimeNs:ctimeNs:mode）命中**身份缓存**，且缓存里的 sha/bytes 与记录一致。
+     * 身份未变 ⇒ 内容未变：缓存里的 sha 就是**这份内容**在留点那一次真读出来的哈希（身份含 size/mtimeNs/
+     * ctimeNs/ino/dev/mode，改内容必动 mtime/ctime，Windows 上 user 代码改不了 ctime）。
+     * 任何一环拿不到（读不到身份 / 缓存没有该身份 / sha 或 bytes 不同）⇒ false，调用方回落「真读 + 哈希」。
+     *
+     * 为什么必须有它：大仓库一次预览/回退要判 3 万+ 条目，逐个真读等于把整个工作区读两遍
+     * （真机 34k 文件 / 609 MiB：预览 14.2 s 里 13 s 全在这，回退 60 s+ 同理）。**记录的指纹被篡改**
+     * 时本判据必然不成立（缓存的 sha 是真算出来的）⇒ 仍走真读 + 哈希的旧路径，护栏不退化。
+     */
+    private unchangedByIdentity;
     private lookupCachedFile;
     private rememberCachedFile;
     /** 缓存落盘（best-effort：写失败只意味着下次全量读，绝不影响留点成败） */
@@ -889,7 +1196,19 @@ export declare class RollbackPointEngine {
     private gcPathCache;
     /** 拒删成因的如实说明（没有可解释成因时返回空数组，绝不编理由） */
     private createdRefusalWarnings;
-    private readLedger;
+    /**
+     * 读台账**清单**（只读元数据 + 段摘要；代价与工作区文件数**无关**）。
+     *
+     * 与 v2 的差别只在实现：v2 每回合把整份 index.json 读进内存并 parse（473 MB 那条路），
+     * v3 读的是一份小清单。**外部语义一个字没变**：返回 entries + 同一套 error 文案。
+     * 启动期初始化失败时如实回报（不读 v2 文件、不假装台账为空）。
+     */
+    private readManifest;
+    /**
+     * 读**完整**记录（引用解析对调用方透明）。失败一律如实回报，**绝不返回半个记录**：
+     * 载荷缺失 / 哈希不符 / 形状不符 ⇒ error（调用方走 record-incomplete 路径）。
+     */
+    private readFullRecord;
     /**
      * S6 淘汰（t14 冻结 + 2026-10-12 guard 全局上限）：三类点各按各的预算裁，**只删最旧的**。
      *
@@ -899,13 +1218,64 @@ export declare class RollbackPointEngine {
      * | guard 救援点 | 每会话 `maxGuardsPerSession`（20）→ 全局 `maxGuards`（`ROLLBACK_MAX_GUARDS`，50） | **不占**自动点预算、**不受**自动点的 20/50 影响；用户删不掉 ⇒ 必须有自己的两道预算（单会话挡住不够，跨会话也要收敛） |
      * | protected 点 | 无上限（只进不出） | 生产路径**造不出来**（capture 端点已下线、tracker 从不设 protect），只有测试能造 |
      */
-    private selectPrune;
+    /**
+     * 条数淘汰（口径与 v2 逐字相同，只是从「记录」换成「清单条目」）：三类点各按各的预算裁，**只删最旧的**。
+     *
+     * | 类别 | 预算 | 说明 |
+     * |---|---|---|
+     * | auto 自动点 | 每会话 maxRecordsPerSession（20）→ 全局 maxRecords（50） | 两次裁剪都只删最旧 |
+     * | guard 救援点 | 每会话 maxGuardsPerSession（20）→ 全局 maxGuards（ROLLBACK_MAX_GUARDS，50） | **不占**自动点预算、**不受**自动点的 20/50 影响；用户删不掉 ⇒ 必须有自己的两道预算（单会话挡住不够，跨会话也要收敛） |
+     * | protected 点 | 无上限（只进不出） | 生产路径**造不出来**（capture 端点已下线、tracker 从不设 protect），只有测试能造 |
+     */
+    private selectPruneEntries;
+    /**
+     * 字节预算淘汰（issue #89 的**根因修复**）：条数没超、字节超了照样会 OOM。
+     *
+     * 判据与条数淘汰共用同一类别口径：**只淘汰最旧的 auto 点**（guard / protected 永不淘汰）。
+     * 释放量按「记录文件字节 + 载荷**最后一个引用**消失时的载荷字节」估算（引用计数靠清单，不读载荷）。
+     * 返回淘汰后的清单（调用方负责落盘与删文件）。
+     */
+    private applyByteBudget;
+    /**
+     * 对象仓回收（**重写版**，issue #89）：账本字节数不再进内存。
+     *
+     * 旧实现要从「内存里所有记录的全部 files 数组」累计引用 ⇒ 回收一次 = 把整份台账读进内存。
+     * 现在：扫**清单** -> 逐个读引用到的**载荷文件**（一次只驻留一份）-> 累计 referenced 对象键 -> 扫 objects/。
+     * 峰值内存 ∝ 单份载荷 + 对象键集合，**不 ∝ 台账总字节**。
+     * 任何一份被引用的载荷读不出来 ⇒ 整体放弃回收（fail-closed：读不到的载荷里有什么对象谁也不知道）。
+     */
     private gcObjects;
     /**
      * 把记录写进台账（**留点侧唯一写入口**）：整段「读全文 → 合并 → S6 淘汰 → 原子写 → 回收对象」
      * 都在 {@link withLedgerWriteLock} 的进程内串行队列里 —— 绝不与 tracker / 路由的另一次写交错。
      */
+    /**
+     * 写一条记录（**最多三次尝试**）—— 跨进程乐观并发（①B）。
+     *
+     * dataDir 由 `$DSH_HOME` 决定、**不随 profile 分家**（与本插件自带的实例锁同一套多实例假设），
+     * 所以「另一个 DSH 实例正在写同一份清单」是设计内的场景，而 `withLedgerWriteLock` 只串行本进程。
+     * 策略：读清单前后各取一次**代际戳**，被改过就重读重试；三次都变 ⇒ **放弃本次留点并 warn**，
+     * 绝不拿自己的快照覆盖别人的清单（宁可少一条点，也不丢别人的点）。
+     * 诚实的边界：检测与写入之间仍有极小窗口，无跨进程锁时无法彻底消除 —— 这里保证的是
+     * 「不静默覆盖 + 尽量合并」，不是原子性。
+     */
+    /**
+     * 把工作区载荷改写成**增量视图**（相对最近一个同分块的点）——清单增量化，省的是磁盘，不是语义。
+     *
+     * 判据与安全边界（逐条）：
+     *  · 基准 = 清单里最近一个 `workspace.payload` 非空、**分块完全相同**的点（只试最近几个，代价有界）；
+     *  · 增量 = 「相对基准新增 / 改写的条目」+「基准里不再存在的路径」，条目**逐字比较**（同形绝对路径）；
+     *  · 只有增量明显更小（< 全量的 60%）才用；否则原样全量落盘；
+     *  · 读路径由 ledger 物化（`resolvePayload`）⇒ 预览 / 回退 / 回收看到的永远是完整清单；
+     *  · 基准读不出来 / 分块对不上 / 任何异常 ⇒ 原样全量（绝不因为省字节而让点不可用）；
+     *  · 基准载荷的保活由 ledger 的 `payloadChain` 负责（淘汰时不会把基准删掉）。
+     */
+    private storagePlanFor;
+    /** 记下这份点作为下一次留点的增量基准（内存摘要，见 {@link deltaBase}） */
+    private rememberDeltaBase;
     private appendRecord;
+    /** `appendRecord` 的单次尝试；`conflict: true` = 这期间清单被别的实例改过，调用方应当重试。 */
+    private appendRecordOnce;
     /**
      * 留一个回滚点（宿主自动留点 / 恢复前救援点 / 测试构造都走这一条）。
      * 没有 HTTP capture 端点 —— 手动「拍点」已随规格 S1 下线。
@@ -959,6 +1329,11 @@ export declare class RollbackPointEngine {
         error?: string;
         storage: RollbackStorageStatus;
     }>;
+    /**
+     * 预览的**单条只读判定**（阶段 A，可并发跑）：一次 bigint lstat + 身份快路径。
+     * `unchanged = true` 表示「已证明与记录一致」（身份命中身份缓存且 sha/bytes 相同）⇒ 调用方直接跳过。
+     */
+    private previewScan;
     private trackWarnings;
     /**
      * 「证明为留点之后新建」的完整规划 —— 预览（`preview`）与执行（`restoreWorkspace`）**共用这一份**。
@@ -1047,6 +1422,30 @@ export declare class RollbackPointEngine {
      * 会在本方法的读与写之间插入一次 append，把刚删掉的点**复活**（评审 20 轮实测 12 轮复现）。
      */
     remove(id: string): Promise<RollbackRemoveResult>;
+    /**
+     * 磁盘清理入口（引擎侧）：删**全部**自动点（includeGuards=true 时连 guard 也删），
+     * protected 点**永不删**（生产路径造不出来，只有测试能造）。随后回收无人引用的载荷与对象。
+     *
+     * 零写入拒绝路径照旧：存储不可用 / 清单读不出来（形状不符、迁移失败、迁移中）⇒ **抛带 code 的错误**，
+     * 一个字节都不动、也绝不静默返回全 0（「什么都没删」与「读不出来所以没删」是两件事）。
+     * 返回的 bytes = 本次真正删掉的字节（记录文件 + 载荷文件 + 对象文件）。
+     */
+    purgeLedger(options?: {
+        includeGuards?: boolean;
+    }): Promise<{
+        removedRecords: number;
+        removedPayloads: number;
+        removedObjects: number;
+        bytes: number;
+    }>;
+}
+/**
+ * 台账清理的**显式拒绝**（形状不符 / 存储不可用）：带机器可读 code，绝不静默返回全 0。
+ * 路由层按 code 映射 HTTP（与既有 RollbackCode 冻结集同源）。
+ */
+export declare class RollbackLedgerRefusedError extends Error {
+    readonly code: RollbackCode;
+    constructor(code: RollbackCode, detail: string);
 }
 /** 会话登记（宿主订阅 session/event 时按会话登记一次）。 */
 export interface RollbackSessionBinding {
@@ -1167,6 +1566,8 @@ export declare class RollbackAutoTracker {
     private readonly lastStat;
     private timer;
     private mechanism;
+    /** 在途捕获的取消信号（stop() 时 abort；重新 start() 时换一个新的） */
+    private captureAbort;
     constructor(options: RollbackTrackerOptions);
     /** 实际采用的留点机制（output / 诊断用） */
     get mechanismKind(): 'event' | 'poll';