@logictan/dsh-config-manager 0.1.60

package/lib/core/recovery-orchestrator.js

@@ -0,0 +1,327 @@
+/**
+ * Phase 5 Recovery Orchestration（§9.2「新增 recovery 编排层」）。
+ *
+ * 职责：把 recovery 路由的编排逻辑（decision / confirmation / authority / snapshot 校验 /
+ * journal 状态机 / 原子 verification+terminal / dismiss）提取为可测纯编排层。
+ * 路由（index.ts）只负责：loopback fence + withMutationLock + 把结果映射为 HTTP 响应。
+ *
+ * 安全不变量（§9.4 / §11）：
+ *  - **权威 snapshotId 只来自 j.snapshotId**（不接受请求体覆盖）。
+ *  - 只消费 `TRUSTED_OPERATION_SNAPSHOT`（requireOperationBound=true）；LEGACY/MANUAL/CORRUPT/
+ *    INVALID/UNSAFE_PATH/WRONG_ENVIRONMENT/WRONG_OPERATION 一律拒绝。
+ *  - destructive 动作必须 `userConfirmed=true`（双重校验：请求体 + journal 状态机）。
+ *  - verify 的 verification 写入 + terminal state 为**单次原子 store.update**（§6.5）。
+ *  - 不新建 journal / lock / transaction / snapshot-trust（复用现有 machinery）。
+ *
+ * 本模块不 import index.ts（避免循环依赖）；restore/rollback 执行器由路由注入
+ * （`RecoveryExecutorFns`），测试注入 mock。
+ */
+import { join } from 'node:path';
+import { FileSnapshotStore } from './backup.js';
+import { validateSnapshotForRestore } from './restore.js';
+import { recomputeRecoveryDecision, executeRecovery } from './reconcile.js';
+import { verifyRecovery, recoveryTerminalState } from './verify-recovery.js';
+import { redactJournalText, isTerminalState, transitionJournalState, isValidOperationId, } from './journal.js';
+import { RunRegistry } from './run-registry.js';
+export function createRecoveryOrchestrator(deps) {
+    const { store, runs, snapshotsDir, host, msg, snapshotExists, getEnvironmentFingerprint, clearSafeMode, inspectLockState, recoverStaleLock } = deps;
+    /**
+     * 只读 recovery decision（不修改 journal）。**不用 reconcileActive**：其 §6.5 硬门控会把
+     * RECOVERING journal 迁移到 NEEDS_ATTENTION，若 status 轮询时触发会破坏 execute→verify 流程。
+     */
+    const decision = async (j) => {
+        if (j.state === 'NEEDS_ATTENTION') {
+            return recomputeRecoveryDecision(j, { snapshotExists });
+        }
+        if (j.state === 'RECOVERING') {
+            if (Object.keys(j.rollback.entryDone ?? {}).length > 0)
+                return 'rollback-continue';
+            return 'needs-attention';
+        }
+        return 'needs-attention'; // CREATED/SNAPSHOT_CREATED/APPLYING/VALIDATING → 保守
+    };
+    /** 校验 trusted snapshot（requireOperationBound=true）；返回 verdict。 */
+    const validateSnapshotVerdict = async (snapshotId) => {
+        const v = await validateSnapshotForRestore(join(snapshotsDir, snapshotId), snapshotsDir, { environmentFingerprint: getEnvironmentFingerprint() });
+        return v.verdict;
+    };
+    /**
+     * recovery 成功后清除 SAFE MODE（§5.3 / §10.2「SAFE MODE 退出」）。
+     * 仅当 **不存在其他未解决 active journal**（active 全部为已解决 terminal：
+     * COMMITTED/ROLLED_BACK/RECOVERED，**NEEDS_ATTENTION 视为未解决**——它代表仍需
+     * 人工处理的 incident，必须保持 SAFE MODE 阻断）时，才清除 durable 标记与内存标志。
+     * fail-closed：扫描失败不强行清除（保守保留 SAFE MODE）。
+     */
+    const maybeClearSafeMode = async () => {
+        try {
+            const activeIds = await store.scanActive();
+            let allResolved = true;
+            for (const opId of activeIds) {
+                const j = await store.loadActive(opId);
+                if (j === null)
+                    continue;
+                // NEEDS_ATTENTION 是 terminal 但代表未解决 incident → 不视为 resolved
+                if (j.state === 'NEEDS_ATTENTION') {
+                    allResolved = false;
+                    break;
+                }
+                if (!isTerminalState(j.state)) {
+                    allResolved = false;
+                    break;
+                }
+            }
+            if (allResolved) {
+                await clearSafeMode();
+            }
+        }
+        catch {
+            // 扫描失败保守：不清除 SAFE MODE（fail-closed）
+        }
+    };
+    /** 执行 recovery（execute/retry 共用）：登记 run → 注入执行器工厂 → executeRecovery。 */
+    const runExecution = async (operationId, j, decisionKind, makeExecutors) => {
+        let run;
+        try {
+            run = runs.register('recovery');
+        }
+        catch (error) {
+            return { status: 409, body: { error: error instanceof Error ? error.message : String(error) } };
+        }
+        const runId = run.runId;
+        try {
+            const executors = makeExecutors(runId);
+            const result = await executeRecovery(store, {
+                operationId, action: 'rollback', snapshotId: j.snapshotId, decision: decisionKind,
+                performRestore: executors.performRestore, performRollback: executors.performRollback,
+            }, true);
+            if (result === 'failed') {
+                runs.fail(runId, 'recovery 执行失败');
+                return { status: 400, body: { error: 'recovery 执行失败', runId } };
+            }
+            runs.finish(runId, { decision: decisionKind, state: 'RECOVERING' });
+            return { status: 200, body: { ok: true, operationId, decision: decisionKind, state: 'RECOVERING', runId } };
+        }
+        catch (error) {
+            runs.fail(runId, error instanceof Error ? error.message : String(error));
+            return { status: 500, body: { error: error instanceof Error ? error.message : String(error), runId } };
+        }
+    };
+    return {
+        async status() {
+            const activeIds = await store.scanActive();
+            const incidents = [];
+            for (const opId of activeIds) {
+                const j = await store.loadActive(opId);
+                if (j === null)
+                    continue;
+                if (isTerminalState(j.state) && j.state !== 'NEEDS_ATTENTION')
+                    continue; // COMMITTED/ROLLED_BACK/RECOVERED → 非 incident
+                const d = await decision(j);
+                incidents.push({
+                    operationId: opId,
+                    operationType: j.operationType,
+                    state: j.state,
+                    decision: d,
+                    snapshotId: j.snapshotId,
+                    reason: redactJournalText(j.error || j.recovery.reason || ''),
+                    createdAt: j.createdAt,
+                });
+            }
+            const running = runs.listActive().filter((r) => r.kind === 'recovery').map((r) => ({ runId: r.runId, status: r.status }));
+            // issue #31：附带环境锁分类。**只暴露分类，不暴露 owner pid/op/hostname**（内部诊断）。
+            // attention 只对「需用户显式处理」的状态为 true：STALE_LOCK_DETECTED（残留锁，重试不会自愈）
+            // 与 UNKNOWN_STATE（无法判定）→ 引导用户回收；LOCKED（另一任务活跃持有）会自行释放，
+            // 不该催用户去「回收」，否则又是一个误导。探测失败 → 保守 UNKNOWN_STATE + attention。
+            let lock;
+            try {
+                const insp = await inspectLockState();
+                lock = {
+                    state: insp.state,
+                    attention: insp.state === 'STALE_LOCK_DETECTED' || insp.state === 'UNKNOWN_STATE',
+                };
+            }
+            catch {
+                lock = { state: 'UNKNOWN_STATE', attention: true };
+            }
+            return { status: 200, body: { incidents, running, lock } };
+        },
+        async preview(operationId) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            const d = await decision(j);
+            let snapshotVerdict = null;
+            let snapshotMeta = null;
+            if (j.snapshotId !== null && j.snapshotId !== '') {
+                snapshotVerdict = await validateSnapshotVerdict(j.snapshotId);
+                try {
+                    const snap = await new FileSnapshotStore({ dir: snapshotsDir }).load(j.snapshotId);
+                    snapshotMeta = { id: snap.id, createdAt: snap.createdAt, operationType: snap.operationType };
+                }
+                catch { /* 快照缺失 */ }
+            }
+            return {
+                status: 200,
+                body: {
+                    operationId,
+                    operationType: j.operationType,
+                    state: j.state,
+                    decision: d,
+                    snapshotId: j.snapshotId,
+                    snapshotVerdict,
+                    snapshotMeta,
+                    environmentFingerprint: j.environmentFingerprint,
+                    environmentCompatible: j.environmentFingerprint === getEnvironmentFingerprint(),
+                    reason: redactJournalText(j.error || j.recovery.reason || ''),
+                    createdAt: j.createdAt,
+                },
+            };
+        },
+        async confirm(operationId, userConfirmed) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            if (userConfirmed !== true)
+                return { status: 400, body: { error: 'userConfirmed required' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            if (j.state !== 'NEEDS_ATTENTION')
+                return { status: 409, body: { error: `journal state ${j.state} 不允许 confirm` } };
+            if (j.snapshotId === null || j.snapshotId === '')
+                return { status: 400, body: { error: 'journal 无 trusted snapshot，无法恢复' } };
+            const verdict = await validateSnapshotVerdict(j.snapshotId);
+            if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT')
+                return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+            // journal 保持 NEEDS_ATTENTION（confirm 不转 RECOVERING）
+            return { status: 200, body: { ok: true, operationId, snapshotId: j.snapshotId, verdict } };
+        },
+        async execute(operationId, userConfirmed, makeExecutors) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            if (userConfirmed !== true)
+                return { status: 400, body: { error: 'userConfirmed required' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            if (j.state !== 'NEEDS_ATTENTION' && j.state !== 'RECOVERING')
+                return { status: 409, body: { error: `journal state ${j.state} 不允许 execute` } };
+            if (j.snapshotId === null || j.snapshotId === '')
+                return { status: 400, body: { error: 'journal 无 trusted snapshot，无法恢复' } };
+            const d = await decision(j);
+            if (d === 'needs-attention')
+                return { status: 400, body: { error: 'recovery decision 为 needs-attention，无法自动执行' } };
+            const verdict = await validateSnapshotVerdict(j.snapshotId);
+            if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT')
+                return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+            return runExecution(operationId, j, d, makeExecutors);
+        },
+        async verify(operationId) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            if (j.state !== 'RECOVERING')
+                return { status: 409, body: { error: `journal state ${j.state} 不允许 verify` } };
+            if (j.snapshotId === null || j.snapshotId === '')
+                return { status: 400, body: { error: 'journal 无 trusted snapshot' } };
+            let snap;
+            try {
+                snap = await new FileSnapshotStore({ dir: snapshotsDir }).load(j.snapshotId);
+            }
+            catch {
+                return { status: 400, body: { error: 'snapshot 无法加载' } };
+            }
+            const verification = await verifyRecovery(snap, host, { snapshotsRoot: snapshotsDir, environmentFingerprint: getEnvironmentFingerprint(), expectedOperationId: j.operationId });
+            const terminal = recoveryTerminalState(verification.verdict);
+            // 单次原子 journal update：recoveryVerification + terminal state（§6.5）
+            await store.update(operationId, (cur) => {
+                let next = cur;
+                if (!isTerminalState(cur.state))
+                    next = transitionJournalState(cur, terminal);
+                next = { ...next, recoveryVerification: { verdict: verification.verdict, details: verification.details.map(redactJournalText), manualHints: verification.manualHints.map(redactJournalText), at: verification.at } };
+                return next;
+            });
+            if (terminal === 'ROLLED_BACK')
+                await store.moveToCompleted(operationId).catch(() => undefined);
+            // §5.3 / §10.2：recovery 成功后若无其他未解决 incident → 清除 SAFE MODE（解除阻断）
+            if (terminal === 'ROLLED_BACK')
+                await maybeClearSafeMode();
+            return {
+                status: 200,
+                body: {
+                    ok: true, operationId, verdict: verification.verdict, terminal,
+                    details: verification.details.map(redactJournalText),
+                    manualHints: verification.manualHints.map(redactJournalText),
+                },
+            };
+        },
+        async retry(operationId, userConfirmed, makeExecutors) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            if (userConfirmed !== true)
+                return { status: 400, body: { error: 'userConfirmed required' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            if (j.state !== 'NEEDS_ATTENTION')
+                return { status: 409, body: { error: `journal state ${j.state} 不允许 retry` } };
+            if (j.snapshotId === null || j.snapshotId === '')
+                return { status: 400, body: { error: 'journal 无 trusted snapshot' } };
+            const d = await decision(j);
+            if (d === 'needs-attention')
+                return { status: 400, body: { error: 'recovery decision 为 needs-attention，无法 retry' } };
+            const verdict = await validateSnapshotVerdict(j.snapshotId);
+            if (verdict !== 'TRUSTED_OPERATION_SNAPSHOT')
+                return { status: 400, body: { error: `snapshot 不可信: ${verdict}` } };
+            return runExecution(operationId, j, d, makeExecutors);
+        },
+        async dismiss(operationId, userConfirmed) {
+            if (!isValidOperationId(operationId))
+                return { status: 400, body: { error: 'invalid operationId' } };
+            if (userConfirmed !== true)
+                return { status: 400, body: { error: 'userConfirmed required' } };
+            const j = await store.loadActive(operationId);
+            if (j === null)
+                return { status: 404, body: { error: 'operation not found' } };
+            // dismiss → quarantine（用户放弃；不删除 snapshot/journal evidence，不强行 RECOVERED）
+            const result = await executeRecovery(store, { operationId, action: 'dismiss', snapshotId: j.snapshotId }, true);
+            if (result === 'failed')
+                return { status: 400, body: { error: 'dismiss 失败' } };
+            return { status: 200, body: { ok: true, operationId, dismissed: true } };
+        },
+        /**
+         * issue #31：显式回收 stale 残留锁。**无 operationId**——残留锁没有 journal（这正是
+         * 「事故恢复」面板过去恒空的原因），因此不复用 confirm/execute 那套 journal 状态机。
+         *
+         * 正确性边界（不放松「绝不自动摘锁」）：
+         *  - **不 acquire 锁**：要回收的正是挡住 acquire 的那把锁，先取锁必然失败；
+         *  - 是否真的 stale 由 recoverStaleLock 内部重做判定（inspect + 二次验证），
+         *    本层拿到的 state/detail 只用于日志，绝不作为删除依据；
+         *  - 活锁/判定不确定 → 内部拒绝，ok=false，不做任何改动（不误删别人的锁）。
+         */
+        async recoverStaleLock(userConfirmed) {
+            if (userConfirmed !== true)
+                return { status: 400, body: { error: 'userConfirmed required' } };
+            try {
+                const res = await recoverStaleLock();
+                if (res.detail !== undefined) {
+                    // 内部诊断（op/pid/路径）只进日志
+                    host.log[res.ok ? 'info' : 'warn'](`stale lock recovery: ok=${res.ok} state=${res.state} detail=${res.detail}`);
+                }
+                if (!res.ok) {
+                    // 拒绝是正常结果（活锁/无法证明 stale/二次验证失败），不是 500
+                    return { status: 200, body: { ok: false, removed: false, state: res.state, reason: res.detail ?? '未判定为 stale，已拒绝回收' } };
+                }
+                // 回收成功后 stale 分类已消失；锁态交由客户端重新拉取 status 刷新
+                return { status: 200, body: { ok: true, removed: res.removed, state: res.state } };
+            }
+            catch (error) {
+                return { status: 500, body: { error: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    };
+}
+//# sourceMappingURL=recovery-orchestrator.js.map

package/lib/core/restore.d.ts

@@ -0,0 +1,162 @@
+import type { MsgFunc } from './messages.ts';
+import type { SnapshotStatus } from './types.ts';
+export type RestoreActionKind = 'hostFileRestore' | 'hostFileRemove' | 'pluginRemove' | 'fileRestore' | 'fileRemove' | 'credentialHint' | 'skip';
+export interface RestoreAction {
+    kind: RestoreActionKind;
+    /** 人类可读描述 */
+    description: string;
+    /** 目标：相对 $DSH_HOME 的 relPath（hostFile/file 类）或插件名（pluginRemove） */
+    target?: string;
+    /** hostFileRestore/fileRestore：快照内 blob 相对路径（相对 snapshotDir） */
+    blobPath?: string;
+    /** pluginRemove：插件包名 */
+    pluginName?: string;
+    /** credentialHint：人工提示文本 */
+    manualHint?: string;
+    /** 附加说明（旧快照缺基线 / 离线无法恢复等） */
+    detail?: string;
+    /** 该动作是否对应 settings 主文件（settingsPath 解析出的文件） */
+    isSettings?: boolean;
+}
+export interface RestorePlan {
+    snapshotId: string;
+    createdAt: string;
+    sourceZip: string;
+    actions: RestoreAction[];
+    summary: {
+        hostFileRestores: number;
+        hostFileRemoves: number;
+        pluginRemoves: number;
+        fileRestores: number;
+        fileRemoves: number;
+        credentialHints: number;
+        skips: number;
+    };
+    /** beforePlugins 基线是否可用（undefined=旧快照无基线 → 不计划任何插件卸载） */
+    pluginBaselineConfirmed: boolean;
+}
+export interface RestoreOptions {
+    /** 快照目录 <snapshotsDir>/<id>/（含 snapshot.json 与 blobs/） */
+    snapshotDir: string;
+    /** $DSH_HOME（默认 ~/.dsh） */
+    homeDir: string;
+    /** 管理的 DSH profile 名（插件卸载走 profiles/<profile>） */
+    profile: string;
+    /** 覆盖 settings 文件路径（默认探测 $DSH_HOME/settings.yaml → settings.json） */
+    settingsPath?: string;
+    /** 注入式插件卸载器（测试用；缺省走 runDshPlugin 官方通道） */
+    pluginUninstaller?: (name: string, profileDir: string, profile: string) => Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    /** 每项动作执行回调（宿主路由埋点：更新 RunRegistry 进度；index/1-based、total=计划动作数、
+     * detail=动作描述。dry-run/planRestore 不触发） */
+    onAction?: (info: {
+        index: number;
+        total: number;
+        detail: string;
+    }) => void;
+    /** 消息翻译器（缺省 zh；宿主按 DSH 应用语言注入） */
+    msg?: MsgFunc;
+    /**
+     * Phase 4 统一恢复校验：快照根目录（<snapshotsDir>，<snapshotDir> 的直接父级）。
+     * 提供时，planRestore 顶端强制调用 validateSnapshotForRestore；CORRUPT/INVALID/UNSAFE_PATH/
+     * WRONG_ENVIRONMENT 拒绝计划。缺省 = 不强制（兼容旧调用；新入口都应传）。
+     */
+    snapshotsRoot?: string;
+    /** Phase 4 恢复校验时校验环境指纹（不匹配 → WRONG_ENVIRONMENT；缺省不校验）。 */
+    environmentFingerprint?: string;
+    /**
+     * Phase 4 恢复确认策略：缺省允许 LEGACY 显式恢复。若调用方要求「非 operation-bound 一律拒绝」，
+     * 可传 'requireOperationBound'。
+     */
+    requireOperationBound?: boolean;
+}
+export interface RestoreReport {
+    snapshotId: string;
+    /** 已还原/已删除的目标（相对 $DSH_HOME） */
+    restored: string[];
+    /** 已卸载的插件名 */
+    removedPlugins: string[];
+    /** 需人工处理的提示（凭据补录等） */
+    manualHints: string[];
+    /** 失败清单 */
+    failed: {
+        item: string;
+        reason: string;
+    }[];
+    /** 跳过项（无动作 / 离线无法处理） */
+    skipped: string[];
+    /**
+     * 幽灵会话（F5 失效归档清理）：快照记录的 sessions 分区会话在磁盘 sessions 目录
+     * 已无任何文件（备份有记录、磁盘无文件）。DSH 官方无归档会话 API，降级本地校验，
+     * 仅供报告、需人工在 DSH 确认清理；无会话分区/无幽灵时为缺省或空数组。
+     */
+    ghostSessions?: string[];
+}
+export interface SnapshotMeta {
+    id: string;
+    createdAt: string;
+    sourceZip: string;
+    status?: SnapshotStatus;
+    entryCount: number;
+    hostFileBackupCount: number;
+    beforePluginCount: number;
+    /** 置顶标记（P1-⑧）：置顶快照不参与自动保留清理（最多保留 N 个时的淘汰豁免） */
+    pinned?: boolean;
+}
+/**
+ * 快照恢复前可信校验的 verdict（统一供 Host API / ModelTools / CLI / sync rollback 消费）。
+ *
+ * - TRUSTED_OPERATION_SNAPSHOT：READY + manifest 完整 + blob hash 匹配 + 有 op/env/owner binding。
+ *   可授权自动/推荐回滚。
+ * - TRUSTED_MANUAL_LOCAL：READY + 完整校验通过，但无 Phase4 binding（如用户手动/pinned 快照）。
+ *   可显式手动恢复，不可作 Phase3 自动 recovery 证据。
+ * - LEGACY_REQUIRES_CONFIRMATION：旧快照（无 manifest / 无 readiness）。结构/路径校验通过即可显式确认恢复，
+ *   绝不可自动恢复。
+ * - INVALID / CORRUPT / UNSAFE_PATH / WRONG_ENVIRONMENT：拒绝。
+ */
+export type RestoreSnapshotVerdict = 'TRUSTED_OPERATION_SNAPSHOT' | 'TRUSTED_MANUAL_LOCAL' | 'LEGACY_REQUIRES_CONFIRMATION' | 'WRONG_ENVIRONMENT' | 'CORRUPT' | 'INVALID' | 'UNSAFE_PATH';
+export interface RestoreSnapshotValidation {
+    verdict: RestoreSnapshotVerdict;
+    reason?: string;
+}
+/**
+ * 统一恢复前校验（供 planRestore 顶端对所有 restore 类型强制调用）：
+ * 1. isValidSnapshotId（语法）
+ * 2. snapshot.json + manifest 存在、id 匹配（结构）
+ * 3. verifySnapshot（磁盘重读：metadataHash + blob hashes + 路径安全）→ CORRUPT
+ * 4. symlink 检查（snapshot.json / manifest / blobs）→ UNSAFE_PATH
+ * 5. readiness + provenance：
+ *    - 无 binding 字段（旧快照）→ LEGACY_REQUIRES_CONFIRMATION
+ *    - 有 manifest/READY 但无 op binding → TRUSTED_MANUAL_LOCAL
+ *    - 有 READY + manifest + op/env/owner binding → TRUSTED_OPERATION_SNAPSHOT
+ * 绝不把「不可证明」当成 trusted。
+ */
+export declare function validateSnapshotForRestore(snapshotDir: string, snapshotsRoot: string, env?: {
+    environmentFingerprint?: string;
+}): Promise<RestoreSnapshotValidation>;
+/**
+ * 生成恢复动作计划（dry-run 预览的唯一入口；零写入）：
+ * 读快照 + 探测当前文件/已装插件状态，输出按执行顺序排列的动作清单。
+ */
+export declare function planRestore(opts: RestoreOptions): Promise<RestorePlan>;
+/**
+ * 执行恢复：按计划顺序 整文件还原 → 插件卸载 → file 补偿，
+ * 覆盖/删除前全部先复制到 <snapshotDir>/pre-restore/（双保险），
+ * 逐项 try/catch（单项失败不拖垮其余），输出诚实报告。
+ */
+export declare function restore(opts: RestoreOptions): Promise<RestoreReport>;
+/**
+ * 扫描快照根目录下每个子目录的 snapshot.json，返回按 createdAt 倒序的元信息。
+ * 目录缺失/条目损坏自动跳过（不阻断其他快照）。
+ */
+export declare function listSnapshots(dir: string): Promise<SnapshotMeta[]>;
+/** 快照 id 安全校验（防路径穿越）：字母数字 + - _ .，长度 1-80。 */
+export declare function isValidSnapshotId(id: unknown): id is string;
+/** 删除单个快照（手动删除；P1-⑧）。只接受合法 id（防穿越），目标是快照根下的 <id>/ 目录。
+ *  不存在视为成功（幂等）。返回是否实际删除。 */
+export declare function deleteSnapshot(snapshotsDir: string, id: string): Promise<boolean>;
+/** 切换置顶状态（P1-⑧）：置顶快照豁免自动保留清理。重写 <dir>/<id>/snapshot.json 的 pinned 字段。
+ *  只接受合法 id；快照不存在抛错。 */
+export declare function setSnapshotPinned(snapshotsDir: string, id: string, pinned: boolean): Promise<boolean>;