dsh-config-manager 0.1.73 → 0.1.76

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

@@ -1,4 +1,4 @@
-import type { RollbackPointKind, RollbackPointRecord, RollbackPointSummary, RollbackSegmentSummary, RollbackStateKind } from './rollback-point.ts';
+import type { RollbackPointKind, RollbackPointRecord, RollbackPointSummary, RollbackSegmentSummary, RollbackStateKind, RollbackWorkspacePayload } from './rollback-point.ts';
 /** 清单格式版本（与**记录**的 schemaVersion 无关：后者是记录内容的版本，恒为 2） */
 export declare const ROLLBACK_LEDGER_SCHEMA_VERSION = 3;
 /** 单条记录目录名 */
@@ -54,6 +54,12 @@ export interface RollbackLedgerManifestEntry {
         payload: string | null;
         /** 载荷文件字节数（**同一哈希只算一次**，预算与统计用） */
         payloadBytes: number;
+        /**
+         * 这份点**解析所需的全部载荷哈希**（自身在前、基准依次在后）。
+         * 增量载荷依赖基准 ⇒ 回收（prunePayloads）必须按链保活，否则链一断这个点就读不出来了。
+         * 老清单没有该字段 ⇒ 视为 `[payload]`（老载荷都是全量、无依赖）。
+         */
+        payloadChain?: string[];
     };
     session: RollbackLedgerTrackHeader & {
         /** 会话字节副本的对象仓键；null = 没有副本（回收对象时用，不必读记录文件） */
@@ -176,14 +182,34 @@ export declare class RollbackLedger {
     /** 原子写清单（小文件；条目由调用方决定） */
     writeManifest(entries: readonly RollbackLedgerManifestEntry[]): Promise<void>;
     /** 把完整记录拆成「清单条目 + 记录文件内容 + 载荷文件内容」（**不做 IO**，纯函数） */
-    prepareRecord(record: RollbackPointRecord): RollbackLedgerPrepared;
+    prepareRecord(record: RollbackPointRecord, reuse?: {
+        hash: string;
+        bytes: number;
+        chain?: string[];
+    }): RollbackLedgerPrepared;
     /**
      * 落盘：载荷（内容寻址；同一哈希已存在则**零写入**）+ 记录文件。
      * 先载荷后记录：中途失败只留一份没人引用的载荷（垃圾，不是坏数据），下次 prune 回收。
      */
     writePrepared(prepared: RollbackLedgerPrepared): Promise<void>;
     /** 读校验过的载荷（哈希不符 / 形状不符 -> error，绝不返回半个） */
-    private readVerifiedPayload;
+    /**
+     * **原始**读取一份载荷（形状校验 + 内容寻址自证）。
+     * `files` 可能只是「相对基准的增量子集」（`payload.delta` 非空）—— **只给解析器用**，
+     * 消费者一律走 {@link resolvePayload} 拿物化后的完整清单。
+     */
+    private readStoredPayload;
+    /**
+     * 解析一份载荷：增量视图**物化**成完整 `files`（含 `object` 字段补回），全量视图原样返回。
+     *
+     * 任何一环不成立（基准缺失 / 哈希不符 / 形状不符 / 链成环）⇒ **如实失败**：绝不返回半个清单 ——
+     * 半份清单会让「留点后新建」的判据把绝大多数文件当成新建的，回退就会删掉它们。
+     */
+    resolvePayload(hash: string): Promise<{
+        payload?: RollbackWorkspacePayload;
+        error?: string;
+    }>;
+    private materializePayload;
     /** 读一条**完整**记录（引用解析对调用方透明）；任何一步不成立就如实失败 */
     readRecord(id: string): Promise<{
         record?: RollbackPointRecord;

package/lib/core/rollback-ledger.js

@@ -490,6 +490,7 @@ export function normalizeManifestEntry(value) {
         return null;
     const rawRecordBytes = value['recordBytes'];
     const rawPayloadBytes = isRecord(workspaceRaw) ? workspaceRaw['payloadBytes'] : 0;
+    const rawPayloadChain = isRecord(workspaceRaw) ? workspaceRaw['payloadChain'] : null;
     return {
         id,
         kind,
@@ -507,6 +508,10 @@ export function normalizeManifestEntry(value) {
             ...workspace,
             payload: typeof wsPayload === 'string' ? wsPayload : null,
             payloadBytes: typeof rawPayloadBytes === 'number' && Number.isFinite(rawPayloadBytes) && rawPayloadBytes >= 0 ? rawPayloadBytes : 0,
+            // 只保留形状合法的哈希；读不回来的链由解析器如实失败（绝不猜）
+            ...(Array.isArray(rawPayloadChain)
+                ? { payloadChain: rawPayloadChain.filter((h) => typeof h === 'string' && OBJECT_KEY_RE.test(h)) }
+                : {}),
         },
         session: { ...session, object: typeof sessionObject === 'string' ? sessionObject : null },
         segments: [first, second],
@@ -532,6 +537,26 @@ function normalizeWorkspacePayload(value) {
         return null;
     return value;
 }
+/**
+ * **存盘**形状校验：完整清单（`files` 是数组）或增量视图（`delta` 是对象、`files` 故意留 null）。
+ * 与 {@link normalizeWorkspacePayload}（消费侧，要求物化后的完整形状）分开：增量载荷**绝不会**被当成完整清单读出去。
+ */
+function normalizeStoredPayload(value) {
+    const base = normalizeWorkspacePayload(value);
+    if (base !== null)
+        return base;
+    if (!isRecord(value))
+        return null;
+    const delta = value['delta'];
+    if (!isRecord(delta))
+        return null;
+    if (typeof delta['base'] !== 'string')
+        return null;
+    if (!Array.isArray(delta['added']) || !Array.isArray(delta['removed']))
+        return null;
+    const clone = { ...value, files: [] };
+    return normalizeWorkspacePayload(clone);
+}
 function normalizeSessionPayload(value) {
     if (!isRecord(value))
         return null;
@@ -743,7 +768,7 @@ export class RollbackLedger {
     }
     /* -------------------------------------------------------- 单条记录 */
     /** 把完整记录拆成「清单条目 + 记录文件内容 + 载荷文件内容」（**不做 IO**，纯函数） */
-    prepareRecord(record) {
+    prepareRecord(record, reuse) {
         const summary = this.summarize(record);
         const workspaceTrack = record.workspace;
         const sessionTrack = record.session;
@@ -751,7 +776,12 @@ export class RollbackLedger {
         let payloadJson = null;
         let payloadHash = null;
         let payloadBytes = 0;
-        if (payload !== null) {
+        if (payload !== null && reuse !== undefined) {
+            // **复用**：这份工作区态与基准点逐条相同 ⇒ 直接引用它已经落盘的载荷（零额外字节，链不增长）
+            payloadHash = reuse.hash;
+            payloadBytes = reuse.bytes;
+        }
+        else if (payload !== null) {
             payloadJson = JSON.stringify(payload);
             payloadHash = sha256Hex(payloadJson);
             payloadBytes = byteLength(payloadJson);
@@ -773,6 +803,14 @@ export class RollbackLedger {
             workspace: { ...trackHeader(workspaceTrack), payload: payloadHash },
             session: { ...trackHeader(sessionTrack), payload: sessionTrack.payload },
         });
+        // 增量视图 ⇒ 清单条目带上「解析所需的全部载荷哈希」（自身 + 基准链），回收按链保活
+        const payloadChain = payloadHash === null
+            ? undefined
+            : reuse !== undefined
+                ? (reuse.chain !== undefined && reuse.chain.length > 0 ? [...reuse.chain] : [payloadHash])
+                : payload?.delta === undefined
+                    ? [payloadHash]
+                    : [payloadHash, ...payload.delta.baseChain];
         const entry = {
             id: record.id,
             kind: record.kind,
@@ -786,7 +824,7 @@ export class RollbackLedger {
             turnSeq: record.turnSeq,
             boundarySeq: record.boundarySeq,
             recordBytes: byteLength(recordJson),
-            workspace: { ...trackHeader(workspaceTrack), payload: payloadHash, payloadBytes },
+            workspace: { ...trackHeader(workspaceTrack), payload: payloadHash, payloadBytes, ...(payloadChain === undefined ? {} : { payloadChain }) },
             session: { ...trackHeader(sessionTrack), object: sessionTrack.payload?.object ?? null },
             segments: summary.segments,
         };
@@ -813,7 +851,12 @@ export class RollbackLedger {
         await this.write(recordFile, Buffer.from(prepared.recordJson, 'utf8'));
     }
     /** 读校验过的载荷（哈希不符 / 形状不符 -> error，绝不返回半个） */
-    async readVerifiedPayload(hash) {
+    /**
+     * **原始**读取一份载荷（形状校验 + 内容寻址自证）。
+     * `files` 可能只是「相对基准的增量子集」（`payload.delta` 非空）—— **只给解析器用**，
+     * 消费者一律走 {@link resolvePayload} 拿物化后的完整清单。
+     */
+    async readStoredPayload(hash) {
         const target = this.payloadPath(hash);
         if (target === null)
             return { error: 'record-incomplete: payload ref invalid' };
@@ -834,11 +877,64 @@ export class RollbackLedger {
         catch (error) {
             return { error: 'record-incomplete: payload unreadable (' + errorDetail(error) + ')' };
         }
-        const payload = normalizeWorkspacePayload(parsed);
+        const payload = normalizeStoredPayload(parsed);
         if (payload === null)
             return { error: 'record-incomplete: payload shape invalid' };
         return { payload };
     }
+    /**
+     * 解析一份载荷：增量视图**物化**成完整 `files`（含 `object` 字段补回），全量视图原样返回。
+     *
+     * 任何一环不成立（基准缺失 / 哈希不符 / 形状不符 / 链成环）⇒ **如实失败**：绝不返回半个清单 ——
+     * 半份清单会让「留点后新建」的判据把绝大多数文件当成新建的，回退就会删掉它们。
+     */
+    async resolvePayload(hash) {
+        // **不缓存**：载荷被删/被改必须立刻看得见（缓存会把「存储已经坏了」蒙过去），
+        // 也守住「一次只驻留一份载荷」的内存护栏（issue #89 的 OOM 现场）。
+        return this.materializePayload(hash, new Set([hash]));
+    }
+    async materializePayload(hash, seen) {
+        const stored = await this.readStoredPayload(hash);
+        if (stored.payload === undefined)
+            return { error: stored.error ?? 'record-incomplete: payload unreadable' };
+        const payload = stored.payload;
+        const delta = payload.delta;
+        if (delta === undefined)
+            return { payload: withObjectRefs(payload) };
+        if (typeof delta.base !== 'string' || !OBJECT_KEY_RE.test(delta.base)) {
+            return { error: 'record-incomplete: delta base ref invalid' };
+        }
+        if (seen.has(delta.base))
+            return { error: 'record-incomplete: delta chain cycle' };
+        const next = new Set(seen);
+        next.add(delta.base);
+        const base = await this.materializePayload(delta.base, next);
+        if (base.payload === undefined) {
+            return { error: 'record-incomplete: delta base unresolved (' + String(base.error ?? '') + ')' };
+        }
+        const removed = new Set();
+        for (const p of Array.isArray(delta.removed) ? delta.removed : [])
+            if (typeof p === 'string')
+                removed.add(p);
+        const added = withObjectRefs({ ...payload, files: delta.added ?? [], delta: undefined }).files;
+        const addedPaths = new Set();
+        for (const file of added)
+            if (typeof file?.path === 'string')
+                addedPaths.add(file.path);
+        const files = [];
+        for (const file of base.payload.files) {
+            if (typeof file?.path !== 'string')
+                continue;
+            if (removed.has(file.path) || addedPaths.has(file.path))
+                continue;
+            files.push(file);
+        }
+        for (const file of added)
+            files.push(file);
+        // 与全量捕获同序（`payload.files.sort` 用的就是这个比较器）
+        files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        return { payload: { ...payload, files, delta: undefined } };
+    }
     /** 读一条**完整**记录（引用解析对调用方透明）；任何一步不成立就如实失败 */
     async readRecord(id) {
         const target = this.recordPath(id);
@@ -870,7 +966,7 @@ export class RollbackLedger {
             if (typeof payloadRef !== 'string' || !OBJECT_KEY_RE.test(payloadRef)) {
                 return { error: 'record-incomplete: payload ref invalid' };
             }
-            const resolved = await this.readVerifiedPayload(payloadRef);
+            const resolved = await this.resolvePayload(payloadRef);
             if (resolved.payload === undefined)
                 return { error: resolved.error ?? 'record-incomplete: payload unreadable' };
             payload = resolved.payload;
@@ -935,6 +1031,13 @@ export class RollbackLedger {
     async prunePayloads(entries) {
         const referenced = new Set();
         for (const entry of entries) {
+            // 增量载荷依赖基准 ⇒ **按链保活**（否则淘汰/删点会把基准删掉，那个点就永远读不回来了）
+            const chain = entry.workspace.payloadChain;
+            if (Array.isArray(chain) && chain.length > 0) {
+                for (const hash of chain)
+                    referenced.add(hash);
+                continue;
+            }
             if (entry.workspace.payload !== null)
                 referenced.add(entry.workspace.payload);
         }
@@ -986,7 +1089,7 @@ export class RollbackLedger {
         for (const entry of entries) {
             const hash = entry.workspace.payload;
             if (hash !== null) {
-                const resolved = await this.readVerifiedPayload(hash);
+                const resolved = await this.resolvePayload(hash);
                 if (resolved.payload === undefined) {
                     return { removed: 0, bytes: 0, referencedPaths, aborted: resolved.error ?? 'payload unreadable' };
                 }
@@ -1272,6 +1375,21 @@ function trackHeader(track) {
         reasonDetail: track.reasonDetail,
     };
 }
+/**
+ * 补回**落盘时省掉的** `object` 字段：内容寻址的名字就是内容哈希 ⇒ `object ≡ sha256`。
+ * 缺 `sha256` 的畸形条目保持原样（消费侧的防御判据照旧生效）。
+ */
+function withObjectRefs(payload) {
+    for (const file of payload.files) {
+        if (file === null || typeof file !== 'object')
+            continue;
+        if (typeof file.object === 'string')
+            continue;
+        if (typeof file.sha256 === 'string')
+            file.object = file.sha256;
+    }
+    return payload;
+}
 function errorDetail(error) {
     if (error instanceof Error) {
         const code = error.code;

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

@@ -101,6 +101,43 @@ export declare const ROLLBACK_LEFTOVER_LIST_LIMIT = 20;
  * `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），绝不删一半 —— 半套删除既没有可解释的状态，也无法整体回滚。
@@ -132,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'];
@@ -208,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;
 }
@@ -230,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）。
@@ -269,6 +336,12 @@ export interface RollbackWorkspacePayload {
      * 老台账（本字段诞生前写下的点）一律没有它：按「名单完整」处理（与旧行为一致）。
      */
     walkIncomplete?: boolean;
+    /**
+     * 走查被中断时**栈里还没进去的子树**（精确到目录）。有它 ⇒ 拒删只覆盖这些子树
+     * （分子树 fail-closed），而不是把整个工作区的删除全关掉；缺它（老台账 / 栈太深被截断）
+     * ⇒ 退回全局拒删。与 walkIncomplete 一起看：后者是「安全判据」，本字段是「精确范围」。
+     */
+    unwalkedDirs?: string[];
     /** 命中文件数 / 字节上限（内容未全部进来，已如实留痕） */
     truncated: boolean;
     bytes: number;
@@ -781,8 +854,25 @@ export interface RollbackEngineOptions {
     /**
      * 工作区捕获的挂钟时间预算（毫秒，缺省 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;
@@ -809,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;
 /**
@@ -854,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;
@@ -870,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;
@@ -899,14 +1007,41 @@ 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 缓存；只缓存**清单条目**，绝不缓存完整记录） */
     private ledgerSnapshotCache;
     /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
     private readonly ledger;
     private readonly ledgerBytesBudget;
-    /** 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS） */
-    private readonly captureBudgetMs;
+    /**
+     * 工作区捕获的挂钟时间预算（毫秒；见 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 清理）的惰性单飞。
      * 为什么惰取而不是构造时同步跑：构造发生在每个请求路径上，同步扫盘/迁移会把请求卡死；
@@ -945,6 +1080,19 @@ export declare class RollbackPointEngine {
     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;
@@ -963,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;
@@ -978,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;
     /**
@@ -986,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：写失败只意味着下次全量读，绝不影响留点成败） */
@@ -1060,6 +1259,20 @@ export declare class RollbackPointEngine {
      * 诚实的边界：检测与写入之间仍有极小窗口，无跨进程锁时无法彻底消除 —— 这里保证的是
      * 「不静默覆盖 + 尽量合并」，不是原子性。
      */
+    /**
+     * 把工作区载荷改写成**增量视图**（相对最近一个同分块的点）——清单增量化，省的是磁盘，不是语义。
+     *
+     * 判据与安全边界（逐条）：
+     *  · 基准 = 清单里最近一个 `workspace.payload` 非空、**分块完全相同**的点（只试最近几个，代价有界）；
+     *  · 增量 = 「相对基准新增 / 改写的条目」+「基准里不再存在的路径」，条目**逐字比较**（同形绝对路径）；
+     *  · 只有增量明显更小（< 全量的 60%）才用；否则原样全量落盘；
+     *  · 读路径由 ledger 物化（`resolvePayload`）⇒ 预览 / 回退 / 回收看到的永远是完整清单；
+     *  · 基准读不出来 / 分块对不上 / 任何异常 ⇒ 原样全量（绝不因为省字节而让点不可用）；
+     *  · 基准载荷的保活由 ledger 的 `payloadChain` 负责（淘汰时不会把基准删掉）。
+     */
+    private storagePlanFor;
+    /** 记下这份点作为下一次留点的增量基准（内存摘要，见 {@link deltaBase}） */
+    private rememberDeltaBase;
     private appendRecord;
     /** `appendRecord` 的单次尝试；`conflict: true` = 这期间清单被别的实例改过，调用方应当重试。 */
     private appendRecordOnce;
@@ -1116,6 +1329,11 @@ export declare class RollbackPointEngine {
         error?: string;
         storage: RollbackStorageStatus;
     }>;
+    /**
+     * 预览的**单条只读判定**（阶段 A，可并发跑）：一次 bigint lstat + 身份快路径。
+     * `unchanged = true` 表示「已证明与记录一致」（身份命中身份缓存且 sha/bytes 相同）⇒ 调用方直接跳过。
+     */
+    private previewScan;
     private trackWarnings;
     /**
      * 「证明为留点之后新建」的完整规划 —— 预览（`preview`）与执行（`restoreWorkspace`）**共用这一份**。