dsh-config-manager 0.1.72 → 0.1.73

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,16 @@ 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;
 /**
  * 「删除回退点之后新建的路径」的**整套上限**（用户 2026-10-11 定案 A）。
  * 超过就整套拒绝（fail-closed），绝不删一半 —— 半套删除既没有可解释的状态，也无法整体回滚。
@@ -157,7 +177,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 / 计数）。 */
@@ -232,6 +259,16 @@ export interface RollbackWorkspacePayload {
      * 文件级忽略**不**置它：被忽略的文件既进 skipped、也进 walked（路径索引来源）⇒ 名单照样完整。
      */
     ignoreIncomplete?: boolean;
+    /**
+     * true = 走查被**时间预算 / 取消信号**中断 ⇒ 剩余子树**一条都没进任何名单**
+     * （不在 files / skipped / walked 里）⇒ 证明名单**不完整** ⇒ 删除集整体拒绝（fail-closed）。
+     *
+     * 与 `truncated` 的**关键区别**：`truncated` 的三种成因（文件数 / 总字节 / 单文件超限）都是
+     * 「继续遍历 + 逐条留痕」，名单依然完整，所以**不**拒删；只有「整棵子树根本没被走查」才必须拒删
+     * —— 否则那些文件会被判成「留点后才新建」而被删掉（数据丢失）。
+     * 老台账（本字段诞生前写下的点）一律没有它：按「名单完整」处理（与旧行为一致）。
+     */
+    walkIncomplete?: boolean;
     /** 命中文件数 / 字节上限（内容未全部进来，已如实留痕） */
     truncated: boolean;
     bytes: number;
@@ -347,12 +384,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 +430,11 @@ export interface RollbackPointInput {
     chunks?: readonly string[];
     note?: string | null;
     protect?: boolean;
+    /**
+     * 调用方的取消信号（插件卸载 / 会话销毁）：已中止时捕获在**下一个文件边界**停下，
+     * 已收条目照常成点（部分点 + truncated）。缺省不传 = 只受时间预算约束。
+     */
+    signal?: AbortSignal;
 }
 export interface RollbackCaptureResult {
     ok: boolean;
@@ -710,6 +773,16 @@ 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）。
+     * 超时留**部分点**，不拒绝留点；见该常量的说明。
+     */
+    captureBudgetMs?: number;
     guardPolicy?: RollbackGuardPolicy;
     /** 存储栈探针（缺省 = 真实磁盘探测）；注入失败探针可测「缺失时仍可挂载」 */
     storage?: RollbackStorageProbe;
@@ -722,6 +795,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;
@@ -821,8 +900,21 @@ export declare class RollbackPointEngine {
     private forkLinksComplete;
     /** 会话日志头缓存（mtime + size 失效；只服务 fork 链扫描） */
     private readonly forkHeaderCache;
-    /** 继承判据用的台账快照（TTL 缓存；避免每个 turn/start 都读整份台账） */
+    /** 继承判据用的台账快照（TTL 缓存；只缓存**清单条目**，绝不缓存完整记录） */
     private ledgerSnapshotCache;
+    /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
+    private readonly ledger;
+    private readonly ledgerBytesBudget;
+    /** 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS） */
+    private readonly captureBudgetMs;
+    /**
+     * 启动期一次性初始化（流式迁移 v2 -> v3 + 孤儿 tmp 清理）的惰性单飞。
+     * 为什么惰取而不是构造时同步跑：构造发生在每个请求路径上，同步扫盘/迁移会把请求卡死；
+     * 而「每回合都扫一遍」正是要避免的浪费 —— 所以只跑一次并记住结果。
+     */
+    private initPromise;
+    /** 启动期初始化失败的如实记录（读路径必须报出来，绝不假装台账是空的） */
+    private initError;
     constructor(options: RollbackEngineOptions);
     /** 回滚点库根目录（只读侦察用；写路径全部经本类的门） */
     get storeDir(): string;
@@ -835,8 +927,24 @@ 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;
     private writeObjectWithHash;
     /** 对象仓里是否真有这个 blob（缓存命中时校验；任何异常一律按「没有」处理） */
     private objectExists;
@@ -889,7 +997,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 +1019,50 @@ 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**，
+     * 绝不拿自己的快照覆盖别人的清单（宁可少一条点，也不丢别人的点）。
+     * 诚实的边界：检测与写入之间仍有极小窗口，无跨进程锁时无法彻底消除 —— 这里保证的是
+     * 「不静默覆盖 + 尽量合并」，不是原子性。
+     */
     private appendRecord;
+    /** `appendRecord` 的单次尝试；`conflict: true` = 这期间清单被别的实例改过，调用方应当重试。 */
+    private appendRecordOnce;
     /**
      * 留一个回滚点（宿主自动留点 / 恢复前救援点 / 测试构造都走这一条）。
      * 没有 HTTP capture 端点 —— 手动「拍点」已随规格 S1 下线。
@@ -1047,6 +1204,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 +1348,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';