dsh-config-manager 0.1.72 → 0.1.73

package/lib/core/plugin-data-registry.js

@@ -0,0 +1,198 @@
+/**
+ * 内置来源 —— 只放已取证的。
+ *
+ * 收录口径（2026-10-14 调研：按 GitHub star + npm 周下载量排序后逐一核对）：
+ *  - 有自有数据目录（不在 DSH 三个核心存储里，也不在 profile 树里）；
+ *  - 目录里不含凭据（~/.commandcode/auth.json、~/.dsh/agy-accounts 这类命中即整来源不收录 ——
+ *    文件类分区的内容不进 SecretScanner 的剥离路径，带出去就是明文）；
+ *  - 位置由插件自己的 README 明示，或本机实测。
+ *
+ * 未收录但确实有数据目录的插件（如实登记，避免「没列出来 = 不存在」的误读）：
+ *  - dsh-better-sidebar（4175 star）：状态全在 DSH settings/storages，已被既有分区覆盖；
+ *  - @mars-sea/dsh-commandcode-provider（389 star）：~/.commandcode/ 含 auth.json（凭据）；
+ *  - dsh-agy-link（111 star）：~/.dsh/agy-accounts 为账号池（凭据）。
+ */
+export const BUILTIN_PLUGIN_DATA_SOURCES = [
+    {
+        // README「配置与数据」表逐项明示：数据目录 + 缓存/上传/官方资源的覆盖变量
+        id: 'wallpaper-engine',
+        packages: ['dsh-plugin-wallpaper-engine'],
+        evidence: 'documented',
+        areas: [
+            {
+                relPath: '.dsh-wallpaper-engine',
+                role: 'config',
+                envOverrides: ['DSH_WE_DATA_DIR'],
+                // cache = 抽帧/转码/缩略图（可再生产物）；uploads 进 assets；bin 由插件管理（按需下载的运行时）
+                excludeRel: ['cache', 'uploads', 'bin'],
+            },
+            {
+                relPath: '.dsh-wallpaper-engine/uploads',
+                role: 'assets',
+                envOverrides: ['DSH_WE_DATA_DIR', 'DSH_WE_UPLOAD_DIR'],
+            },
+            {
+                relPath: '.dsh-wallpaper-engine/cache',
+                role: 'cache',
+                envOverrides: ['DSH_WE_DATA_DIR', 'DSH_WE_CACHE_DIR'],
+            },
+        ],
+    },
+    {
+        // 本机实测（~/.mnemon 下 runtime / data / documents 三个子目录）；MNEMON_DATA_DIR 覆盖整个根
+        id: 'mnemon',
+        packages: ['dsh-mnemon'],
+        evidence: 'measured',
+        areas: [
+            { relPath: '.mnemon/runtime', role: 'config', envOverrides: ['MNEMON_DATA_DIR'] },
+            { relPath: '.mnemon/data', role: 'assets', envOverrides: ['MNEMON_DATA_DIR'] },
+            { relPath: '.mnemon/documents', role: 'assets', envOverrides: ['MNEMON_DATA_DIR'] },
+        ],
+    },
+    {
+        // README 明示 ~/.fastctx/ 为持久状态（只有 --purge-fastctx 才删）
+        id: 'dsh-ops',
+        packages: ['dsh-ops'],
+        evidence: 'documented',
+        areas: [{ relPath: '.fastctx', role: 'assets' }],
+    },
+    {
+        // README 明示：所有设置落 ~/.dsh/.dsh-any-background-data/（不是 localStorage）
+        id: 'any-background',
+        packages: ['dsh-any-background'],
+        evidence: 'documented',
+        areas: [{ relPath: '.dsh/.dsh-any-background-data', role: 'config' }],
+    },
+    {
+        // README 明示 ~/.opencode2dsh/adapter-status.json
+        id: 'opencode2dsh',
+        packages: ['@opencode2dsh/dsh-plugin'],
+        evidence: 'documented',
+        areas: [{ relPath: '.opencode2dsh', role: 'config' }],
+    },
+];
+/** 角色 → 分区（cache 不属于任何分区） */
+export function sectionOfRole(role) {
+    if (role === 'config')
+        return 'pluginData';
+    if (role === 'assets')
+        return 'pluginAssets';
+    return null;
+}
+/** 该分区要收集的区域清单（保序：来源顺序 → 区域内顺序） */
+export function areasForSection(sources, section) {
+    const out = [];
+    for (const source of sources) {
+        for (const area of source.areas) {
+            if (sectionOfRole(area.role) === section)
+                out.push({ source, area });
+        }
+    }
+    return out;
+}
+/**
+ * home 相对路径归一化 + 安全判定。
+ *
+ * 只接受 POSIX 相对路径：拒绝绝对路径（含 Windows 盘符写法 C:/x）、..、反斜杠、空段、
+ * 以 / 结尾、含 NUL 的值。
+ * 返回 null = 调用方必须报错/跳过，绝不「尽力而为」地拼一个路径出来。
+ */
+export function normalizeHomeRel(value) {
+    if (typeof value !== 'string')
+        return null;
+    const v = value.trim().replace(/\\/g, '/');
+    if (v === '' || v.startsWith('/') || /^[A-Za-z]:/.test(v) || v.includes('\u0000'))
+        return null;
+    if (v.endsWith('/'))
+        return null;
+    for (const part of v.split('/')) {
+        if (part === '' || part === '.' || part === '..')
+            return null;
+    }
+    return v;
+}
+/**
+ * 目录区域的排除判定（issue：**excludeRel 是区域相对路径，rel 是 home 相对路径**）。
+ *
+ * 必须先把 rel 折成区域相对再比：`excludeRel: ['uploads']` 配 `.dsh-wallpaper-engine` 区域时，
+ * 真正的判别对象是 `uploads/a.mp4`（区域相对），不是 `.dsh-wallpaper-engine/uploads/a.mp4`（home 相对）——
+ * 直接拿 home 相对路径去 startsWith，排除项永远不命中，缓存与大资产会悄悄跟着配置分区一起进包。
+ */
+export function isExcludedRel(area, rel) {
+    const inner = rel === area.relPath
+        ? ''
+        : rel.startsWith(area.relPath + '/') ? rel.slice(area.relPath.length + 1) : null;
+    if (inner === null || inner === '')
+        return false;
+    for (const ex of area.excludeRel ?? []) {
+        if (inner === ex || inner.startsWith(ex + '/'))
+            return true;
+    }
+    return false;
+}
+/** rel 是否属于该区域（文件区域 = 精确相等；目录区域 = 精确相等或前缀） */
+export function relInArea(area, rel) {
+    if (rel === area.relPath)
+        return true;
+    return rel.startsWith(area.relPath + '/');
+}
+/**
+ * 路径 → 区域（最长前缀优先）。
+ *
+ * 为什么必须最长优先：.dsh-wallpaper-engine 与 .dsh-wallpaper-engine/uploads 同时是区域，
+ * 短前缀先匹配会把上传的壁纸算进「配置」分区（用户取消勾选大资产也照样带走几百 MB）。
+ */
+export function areaOfPath(entries, rel) {
+    let best = null;
+    for (const entry of entries) {
+        if (!relInArea(entry.area, rel))
+            continue;
+        if (isExcludedRel(entry.area, rel))
+            continue;
+        if (best === null || entry.area.relPath.length > best.area.relPath.length)
+            best = entry;
+    }
+    return best;
+}
+/**
+ * 解析一个已安装插件 package.json 里的自述声明（dsh.dataDirs）—— 「让别的插件自己适配」的钩子。
+ *
+ * 契约（对外文档见 docs/spec/plugin-data-declaration.md）：
+ *   { "dsh": { "dataDirs": [ { "path": ".my-plugin", "role": "config", "env": ["MY_PLUGIN_DIR"] } ] } }
+ *
+ * 形状不认识就整条丢弃（返回 null），绝不猜；path 非法（绝对路径 / .. / 空段）同样丢弃。
+ */
+export function parseDeclaredDataDirs(packageName, manifest) {
+    if (manifest === null || typeof manifest !== 'object')
+        return null;
+    const dsh = manifest.dsh;
+    if (dsh === null || typeof dsh !== 'object')
+        return null;
+    const raw = dsh.dataDirs;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const areas = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object')
+            return null;
+        const rec = item;
+        const relPath = normalizeHomeRel(rec.path);
+        if (relPath === null)
+            return null;
+        const role = rec.role === 'assets' ? 'assets' : rec.role === 'cache' ? 'cache' : 'config';
+        const envOverrides = Array.isArray(rec.env)
+            ? rec.env.filter((e) => typeof e === 'string' && e !== '')
+            : [];
+        const excludes = Array.isArray(rec.exclude)
+            ? rec.exclude.map((e) => normalizeHomeRel(e)).filter((e) => e !== null)
+            : [];
+        areas.push({
+            relPath,
+            role,
+            ...(envOverrides.length > 0 ? { envOverrides } : {}),
+            ...(excludes.length > 0 ? { excludeRel: excludes } : {}),
+        });
+    }
+    return { id: 'declared:' + packageName, packages: [packageName], evidence: 'documented', areas };
+}
+//# sourceMappingURL=plugin-data-registry.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * 回合自动留点（回滚点）的**进程内开关**。
+ *
+ * 为什么需要它（issue #88 / #89）：
+ *  · #88：回滚点与插件主旨（配置备份 / 同步）无关，却随 bundle 默认启用、没有任何关闭入口；
+ *  · #89：默认启用时，每个 `turn/start` 都要留点，而台账写入是「整份读改写」——
+ *    真机 `index.json` 涨到 451 MiB 后宿主反复 V8 heap OOM（exit 134）。
+ *
+ * 设计（三条，别简化）：
+ *  1. **缺省关闭**：`readRollbackEnabledSync()` 读不到 / 形状不符一律 false —— fail-closed，
+ *     绝不因为「文件没写成功」就把功能打开。
+ *  2. **不订阅 = 真的不订阅**：宿主订阅 `session/event` 的那条链由这里驱动 attach / detach。
+ *     关闭时**必须解绑**，而不是「订阅了但回调里 return」（后者仍然吃事件分发路径）。
+ *  3. **活切换**：开关可以在不重载插件的前提下改变 —— 写偏好的一方调 `setRollbackEnabled`，
+ *     订阅方通过 `onRollbackEnabledChange` 收到通知。事件回调**不读文件**（每回合读一次磁盘
+ *     正是本 issue 要消灭的开销形态）。
+ */
+type RollbackEnabledListener = (enabled: boolean) => void;
+/** 当前是否启用（同步、零 I/O —— 事件回调用它做第一道门）。 */
+export declare function isRollbackEnabled(): boolean;
+/**
+ * 设置开关并通知订阅方。值未变化时**不通知**（避免每次保存偏好都触发一次 attach/detach 抖动）。
+ * 监听器里的异常一律吞掉：一个监听器写坏了不能影响开关本身，更不能影响宿主启动。
+ */
+export declare function setRollbackEnabled(value: boolean): void;
+/** 注册开关变化监听；返回解绑函数（解绑幂等）。 */
+export declare function onRollbackEnabledChange(listener: RollbackEnabledListener): () => void;
+/**
+ * 测试专用：把开关与监听器一并复位。
+ * 生产路径**绝不**调用它 —— 重置监听器会让宿主那条订阅链永远收不到后续切换。
+ */
+export declare function resetRollbackGateForTest(): void;
+export {};

package/lib/core/rollback-gate.js

@@ -0,0 +1,57 @@
+/**
+ * 回合自动留点（回滚点）的**进程内开关**。
+ *
+ * 为什么需要它（issue #88 / #89）：
+ *  · #88：回滚点与插件主旨（配置备份 / 同步）无关，却随 bundle 默认启用、没有任何关闭入口；
+ *  · #89：默认启用时，每个 `turn/start` 都要留点，而台账写入是「整份读改写」——
+ *    真机 `index.json` 涨到 451 MiB 后宿主反复 V8 heap OOM（exit 134）。
+ *
+ * 设计（三条，别简化）：
+ *  1. **缺省关闭**：`readRollbackEnabledSync()` 读不到 / 形状不符一律 false —— fail-closed，
+ *     绝不因为「文件没写成功」就把功能打开。
+ *  2. **不订阅 = 真的不订阅**：宿主订阅 `session/event` 的那条链由这里驱动 attach / detach。
+ *     关闭时**必须解绑**，而不是「订阅了但回调里 return」（后者仍然吃事件分发路径）。
+ *  3. **活切换**：开关可以在不重载插件的前提下改变 —— 写偏好的一方调 `setRollbackEnabled`，
+ *     订阅方通过 `onRollbackEnabledChange` 收到通知。事件回调**不读文件**（每回合读一次磁盘
+ *     正是本 issue 要消灭的开销形态）。
+ */
+let enabled = false;
+const listeners = new Set();
+/** 当前是否启用（同步、零 I/O —— 事件回调用它做第一道门）。 */
+export function isRollbackEnabled() {
+    return enabled;
+}
+/**
+ * 设置开关并通知订阅方。值未变化时**不通知**（避免每次保存偏好都触发一次 attach/detach 抖动）。
+ * 监听器里的异常一律吞掉：一个监听器写坏了不能影响开关本身，更不能影响宿主启动。
+ */
+export function setRollbackEnabled(value) {
+    const next = value === true;
+    if (next === enabled)
+        return;
+    enabled = next;
+    for (const listener of [...listeners]) {
+        try {
+            listener(next);
+        }
+        catch {
+            /* 监听器自己的问题；开关状态已生效 */
+        }
+    }
+}
+/** 注册开关变化监听；返回解绑函数（解绑幂等）。 */
+export function onRollbackEnabledChange(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/**
+ * 测试专用：把开关与监听器一并复位。
+ * 生产路径**绝不**调用它 —— 重置监听器会让宿主那条订阅链永远收不到后续切换。
+ */
+export function resetRollbackGateForTest() {
+    enabled = false;
+    listeners.clear();
+}
+//# sourceMappingURL=rollback-gate.js.map

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

@@ -0,0 +1,248 @@
+import type { RollbackPointKind, RollbackPointRecord, RollbackPointSummary, RollbackSegmentSummary, RollbackStateKind } from './rollback-point.ts';
+/** 清单格式版本（与**记录**的 schemaVersion 无关：后者是记录内容的版本，恒为 2） */
+export declare const ROLLBACK_LEDGER_SCHEMA_VERSION = 3;
+/** 单条记录目录名 */
+export declare const ROLLBACK_RECORDS_DIR_NAME = "records";
+/** 内容寻址载荷目录名 */
+export declare const ROLLBACK_PAYLOADS_DIR_NAME = "payloads";
+/**
+ * 回退前像暂存目录名（`<root>/undo/<pid>-<ts36>-<8hex>/`）。
+ * 名字以 pid 开头是**清理判据的一部分**（见 cleanupOrphanTempFiles）；改命名必须同步改 `UNDO_DIR_RE`。
+ */
+export declare const ROLLBACK_UNDO_DIR_NAME = "undo";
+/** v2 单文件迁移成功后的保留名（改名，不是删除） */
+export declare const ROLLBACK_LEDGER_BACKUP_NAME = "index.v2.backup.json";
+/**
+ * 台账（records/ + payloads/）缺省字节预算。
+ *
+ * 为什么需要它：ROLLBACK_MAX_RECORDS（50）只限**条数**，一条记录的工作区载荷可以到几十 MB
+ * （本机实测 50 条 = 473 MB，直接把宿主撑爆）。字节预算与条数预算**互相独立**，两者都生效。
+ */
+export declare const ROLLBACK_DEFAULT_LEDGER_BYTES: number;
+/** 记录文件名 = 记录 id；只允许可自证安全的字符（防篡改清单把路径引出去） */
+export declare const LEDGER_RECORD_ID_RE: RegExp;
+/** 台账里一条记录的**纯标量**头（与 RollbackTrack 的可序列化部分逐字对应） */
+export interface RollbackLedgerTrackHeader {
+    kind: RollbackStateKind;
+    capturedAt: number;
+    ok: boolean;
+    degraded: boolean;
+    fingerprint: string | null;
+    reasonCode: string | null;
+    reasonDetail: string | null;
+}
+/**
+ * 清单条目：**绝不含大数组**。段摘要（segments）在写入时由注入的 summarize 算出，
+ * list() 直接回放 —— 口径只有一份，且清单大小与工作区文件数无关。
+ */
+export interface RollbackLedgerManifestEntry {
+    id: string;
+    kind: RollbackPointKind;
+    createdAt: number;
+    spreadMs: number;
+    protected: boolean;
+    incomplete: boolean;
+    note: string | null;
+    sessionId: string | null;
+    unitId: string | null;
+    turnSeq: number | null;
+    boundarySeq: number | null;
+    /** 该条记录文件的字节数（预算淘汰时用于估算可释放空间） */
+    recordBytes: number;
+    workspace: RollbackLedgerTrackHeader & {
+        /** 内容寻址载荷哈希；null = 该态没有载荷（捕获失败） */
+        payload: string | null;
+        /** 载荷文件字节数（**同一哈希只算一次**，预算与统计用） */
+        payloadBytes: number;
+    };
+    session: RollbackLedgerTrackHeader & {
+        /** 会话字节副本的对象仓键；null = 没有副本（回收对象时用，不必读记录文件） */
+        object: string | null;
+    };
+    /** 冻结口径的段摘要（= summarizeRollbackPoint(record).segments） */
+    segments: RollbackSegmentSummary[];
+}
+/** 清单条目 -> 列表投影（逐字等于旧的 summarizeRollbackPoint(record)，因为它是写入时算好的） */
+export declare function entrySummaryOf(entry: RollbackLedgerManifestEntry): RollbackPointSummary;
+export interface RollbackLedgerMigration {
+    /** 是否真的改了磁盘布局（v2 -> v3，或从 records/ 重建清单） */
+    migrated: boolean;
+    /** 成功落盘的记录条数 */
+    records: number;
+    /** 形状不合格被跳过的条数（如实计数，绝不静默） */
+    skipped: number;
+    /** 非空 = 迁移失败（原文件未动，下次启动重试） */
+    error?: string;
+}
+export interface RollbackLedgerOptions {
+    /** 回滚点库根目录（= dataDir/rollback-points） */
+    root: string;
+    /** 冻结口径的摘要（rollback-point.ts 的 summarizeRollbackPoint） */
+    summarize: (record: RollbackPointRecord) => RollbackPointSummary;
+    /** 冻结口径的记录校验（rollback-point.ts 的 isRollbackPointRecord） */
+    isLedgerRecord: (value: unknown) => value is RollbackPointRecord;
+    /** 字节预算；缺省 ROLLBACK_DEFAULT_LEDGER_BYTES */
+    bytesBudget?: number;
+    now?: () => number;
+    /** best-effort 日志（绝不抛给调用方） */
+    log?: (line: string) => void;
+    /**
+     * 每次「读一条记录文件 / 一份载荷文件」前的观测钩子（生产不传）。
+     * 为什么要有它：内存护栏需要**确定性**证据 —— 「单次 append 绝不读别人的记录文件」
+     * 只能靠数读盘次数来钉，而不是靠不可复现的堆采样。
+     */
+    onFileRead?: (file: string) => void;
+    /** 写 seam（缺省 = atomicWriteFile）；测试用它注入「第 N 次写失败」以验证迁移中断可重试 */
+    writeFile?: (target: string, bytes: Uint8Array) => Promise<void>;
+}
+/** 一次「准备写一条记录」的产物（先把清单条目算出来，预算淘汰才能在写之前决策） */
+export interface RollbackLedgerPrepared {
+    entry: RollbackLedgerManifestEntry;
+    /** 记录文件内容（workspace.payload 已换成哈希引用） */
+    recordJson: string;
+    /** 载荷文件内容；null = 该态没有载荷 */
+    payloadJson: string | null;
+    payloadHash: string | null;
+}
+export interface RollbackLedgerStats {
+    /** records/ 下的文件数 */
+    records: number;
+    /** records/ + payloads/ 的总字节 */
+    bytes: number;
+}
+export interface RollbackTempCleanupResult {
+    removed: number;
+    bytes: number;
+    /** 形似临时文件但**判据不足**（判不准就不删） */
+    skipped: number;
+}
+/**
+ * 删除 rollback-points/ 下**形状可自证**的崩溃残留原子写临时文件。
+ *
+ * 判据（三条全中才删，判不准一律不删）：
+ *  1. 名字逐字符合 atomic-write.ts 的 tmpPath() 形态：.dshcm.<base>.<pid>.<16hex>.tmp；
+ *  2. 该 pid **不是本进程**（本进程的 tmp 可能正在写）；
+ *  3. 该 pid 进程已不存在（崩溃残留）—— 仍然活着的进程可能正在写，绝不抢。
+ * 只扫根目录与它的一级子目录（records/ payloads/ objects/），不递归。
+ */
+export declare function cleanupOrphanTempFiles(root: string): Promise<RollbackTempCleanupResult>;
+/** 清单条目校验：形状不对就**丢掉并计数**（与 v2 的 records.filter(isRollbackPointRecord) 同一条路） */
+export declare function normalizeManifestEntry(value: unknown): RollbackLedgerManifestEntry | null;
+export declare class RollbackLedger {
+    readonly root: string;
+    readonly manifestPath: string;
+    readonly backupPath: string;
+    readonly recordsDir: string;
+    readonly payloadsDir: string;
+    readonly objectsDir: string;
+    readonly bytesBudget: number;
+    private readonly summarize;
+    private readonly isLedgerRecord;
+    private readonly nowFn;
+    private readonly log;
+    private readonly onFileRead;
+    private readonly writeSeam;
+    /**
+     * 被**字节预算**淘汰的自动点累计数（可观测；与「条数上限」淘汰分开计数）。
+     *
+     * 为什么必须**持久化**而不是只记在实例上：宿主每个请求都新建一个引擎（路由侧），
+     * 只记在实例上的话这个数字永远是 0 —— 界面就永远看不到「已经因为预算淘汰过 N 个」。
+     * 值随清单落盘（`evicted` 字段），读清单时取「磁盘值与内存值的大者」，
+     * 这样「先 markEvicted 再读清单」的时序也不会把刚加上的计数抹掉。
+     */
+    private evicted;
+    constructor(options: RollbackLedgerOptions);
+    get evictedCount(): number;
+    markEvicted(count: number): void;
+    private warn;
+    private write;
+    private readText;
+    private exists;
+    private recordPath;
+    private payloadPath;
+    /**
+     * 清单文件的**代际戳**（mtimeMs + 字节数）。跨进程乐观并发用：留点侧在读清单前后各取一次，
+     * 不一致说明另一个实例写过 ⇒ 重读重试，绝不拿自己的快照覆盖别人的清单。
+     * 读不到返回 null = **不参与判定**（可选探针失败绝不阻塞留点）。
+     */
+    manifestStamp(): Promise<string | null>;
+    /** 这份载荷是否已经落过盘（内容寻址 ⇒ 已存在就是同一份，可零写入；也是「本次新增字节」的判据） */
+    hasPayload(hash: string): Promise<boolean>;
+    readManifest(): Promise<{
+        entries: RollbackLedgerManifestEntry[];
+        error?: string;
+    }>;
+    private findMissingRecordFiles;
+    /** 原子写清单（小文件；条目由调用方决定） */
+    writeManifest(entries: readonly RollbackLedgerManifestEntry[]): Promise<void>;
+    /** 把完整记录拆成「清单条目 + 记录文件内容 + 载荷文件内容」（**不做 IO**，纯函数） */
+    prepareRecord(record: RollbackPointRecord): RollbackLedgerPrepared;
+    /**
+     * 落盘：载荷（内容寻址；同一哈希已存在则**零写入**）+ 记录文件。
+     * 先载荷后记录：中途失败只留一份没人引用的载荷（垃圾，不是坏数据），下次 prune 回收。
+     */
+    writePrepared(prepared: RollbackLedgerPrepared): Promise<void>;
+    /** 读校验过的载荷（哈希不符 / 形状不符 -> error，绝不返回半个） */
+    private readVerifiedPayload;
+    /** 读一条**完整**记录（引用解析对调用方透明）；任何一步不成立就如实失败 */
+    readRecord(id: string): Promise<{
+        record?: RollbackPointRecord;
+        error?: string;
+    }>;
+    /** 删记录文件（返回实际释放字节；ENOENT 不计），**不**动载荷与对象 */
+    deleteRecords(ids: readonly string[]): Promise<{
+        removed: number;
+        bytes: number;
+    }>;
+    /** 没人引用的载荷文件一律删（引用计数靠扫清单得到，**不读载荷内容**） */
+    prunePayloads(entries: readonly RollbackLedgerManifestEntry[]): Promise<{
+        removed: number;
+        bytes: number;
+    }>;
+    /**
+     * 内容寻址对象仓回收（**重写版，内存 ∝ 单份载荷 + 对象键集合**）。
+     *
+     * 旧实现要先在内存里拿到「所有记录的全部 files 数组」，于是回收一次就等于把整份台账读进内存
+     * （issue #89 的 OOM 现场之一）。现在：扫清单 -> **逐个读引用到的载荷文件（一次只驻留一份）**
+     * -> 累计 referenced 对象键 -> 扫 objects/ 删无引用项。
+     *
+     * 任何一份被引用的载荷读不出来（缺失 / 哈希不符 / 形状不符）⇒ **整体放弃回收**（aborted 非空）：
+     * 读不到的载荷里有什么对象谁也不知道，此时删对象可能删掉活数据 —— fail-closed。
+     */
+    collectObjects(entries: readonly RollbackLedgerManifestEntry[]): Promise<{
+        removed: number;
+        bytes: number;
+        referencedPaths: Set<string>;
+        aborted: string | null;
+    }>;
+    /** records/ + payloads/ 的**实际**磁盘占用与文件数（诚实：含尚未回收的孤儿文件） */
+    stats(): Promise<RollbackLedgerStats>;
+    private sniffSchemaVersion;
+    private acquireMigrationLock;
+    /**
+     * v2 单文件 -> v3：**流式**切记录、逐条落盘，最后才动原文件。
+     *
+     * 幂等与崩溃安全：
+     *  · 步骤 1（流式落 records/ + payloads/）可重复执行 —— id 稳定，重复写是覆盖，不产生重复条目；
+     *  · 步骤 2 才把 v2 文件改名为 index.v2.backup.json（**成功之前原文件一动不动**）；
+     *  · 若在步骤 2 与 3 之间崩溃（没有 index.json、有 index.v2.backup.json），下次启动走
+     *    rebuildManifest() 从 records/ 重建清单 —— 清单自证：每条 id 必须在 records/ 找得到。
+     */
+    /**
+     * 清单**读不出来**时从 `records/` 重建，并返回重建后重新读到的清单。
+     *
+     * 为什么公开：留点侧（`appendRecord`）在 `readManifest` 报错时**必须**走这里 —— 旧点的最终真相
+     * 在记录文件里，而拿一个空 entries 直接覆盖清单会把旧点整批抹掉、紧接着 `prunePayloads` 还会删掉
+     * 它们的载荷（永久不可恢复）。重建后仍读不出来才由调用方拒写（fail-closed）。
+     */
+    recoverManifest(): Promise<{
+        entries: RollbackLedgerManifestEntry[];
+        error?: string;
+    }>;
+    migrateIfNeeded(): Promise<RollbackLedgerMigration>;
+    private migrateV2;
+    /** 从 records/ 重建清单（崩溃恢复；清单自证：找不到记录文件的 id 一律跳过并计数） */
+    private rebuildManifest;
+    private listRecordIds;
+    private readEntriesFromRecords;
+}