@logictan/dsh-config-manager 0.1.60

package/lib/core/undo.js

@@ -0,0 +1,87 @@
+/**
+ * 撤销 / 重做语义（Phase 1 P0-2）。
+ *
+ * 与竞品 dsh-undo-savepoint 的语义对齐（其「撤销不会撤销掉自己」的等价物在本仓库
+ * 由两处保证：`pre-restore` 快照自身不参与候选，以及恢复后按内容指纹做回声抑制）：
+ *
+ *  自动快照在变更**之后**采集，因此「最新快照」通常等于当前状态。
+ *  真实撤销 = 回退到与当前状态**内容不同**的最新快照（跳过等于当前状态的那些）。
+ *  全部相同 → 明确返回「没有可撤销的变化」，而不是做一次空操作。
+ *
+ * 重做的护栏：撤销时先落一个 `pre-restore` 快照记录「撤销前状态」；
+ * 一旦其后产生任何更新的快照（= 用户又改了），重做即失效——避免把用户的
+ * 新改动覆盖回旧状态。
+ *
+ * 本模块是**纯规划**：不读盘、不写盘、不碰 adapter。执行侧见 config-snapshot.ts。
+ */
+import { statesEqual } from './config-state.js';
+/** 按 createdAt 倒序（新→旧）；同刻按 id 稳定排序保证确定性。 */
+export function sortNewestFirst(items) {
+    return [...items].sort((a, b) => {
+        if (a.createdAt !== b.createdAt)
+            return a.createdAt < b.createdAt ? 1 : -1;
+        return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+}
+/** 可作为撤销目标/状态基准的快照（剔除 pre-restore 与无 state 的旧格式） */
+function comparableCandidates(snapshots) {
+    return sortNewestFirst(snapshots).filter((s) => s.kind !== 'pre-restore' && s.state !== undefined);
+}
+/**
+ * 规划一次撤销：返回第一个内容与 current 不同的快照。
+ * `skippedNewer` = 跳过的「与当前状态相同」的更新快照数（通常 ≥1，因为自动快照
+ * 落在变更之后）。
+ */
+export function planUndo(current, snapshots) {
+    const candidates = comparableCandidates(snapshots);
+    if (candidates.length === 0)
+        return { kind: 'none', reason: 'no-snapshots' };
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        if (!statesEqual(current, candidate.state)) {
+            return { kind: 'undo', targetId: candidate.id, skippedNewer: i, reason: 'content-differs' };
+        }
+    }
+    return { kind: 'none', reason: 'already-at-state' };
+}
+/** 是否存在可撤销的变化（供 UI 按钮可用性；等价于 planUndo 是否命中）。 */
+export function canUndo(current, snapshots) {
+    return planUndo(current, snapshots).kind === 'undo';
+}
+/**
+ * 规划一次重做：取最新的未消费 pre-restore。
+ * 若其后存在任何更新的快照（含未消费的 pre-restore）→ superseded-by-newer-change。
+ */
+export function planRedo(snapshots) {
+    const ordered = sortNewestFirst(snapshots);
+    const pre = ordered.find((s) => s.kind === 'pre-restore' && s.consumed !== true);
+    if (pre === undefined)
+        return { kind: 'none', reason: 'no-pre-restore' };
+    const superseded = ordered.some((s) => s.createdAt > pre.createdAt && (s.kind !== 'pre-restore' || s.consumed !== true));
+    if (superseded)
+        return { kind: 'none', reason: 'superseded-by-newer-change' };
+    return { kind: 'redo', targetId: pre.id, reason: 'unconsumed-pre-restore' };
+}
+/** 是否存在可重做的撤销（供 UI 按钮可用性）。 */
+export function canRedo(snapshots) {
+    return planRedo(snapshots).kind === 'redo';
+}
+/**
+ * 撤销后需要标记为「已被跨过」的快照 id 列表。
+ * 语义：撤销回退到 targetId 之后，比 targetId 更新、且内容等于**撤销前状态**的那些
+ * 快照，代表的是被撤销掉的那一步；重做回到撤销前状态后应清除该标记。
+ * 返回 targetId 之后（更旧侧不涉及）需要标记的 id。
+ */
+export function steppedIds(snapshots, targetId, beforeState) {
+    const target = snapshots.find((s) => s.id === targetId);
+    if (target === undefined)
+        return [];
+    return snapshots
+        .filter((s) => s.kind !== 'pre-restore'
+        && s.id !== targetId
+        && s.createdAt > target.createdAt
+        && s.state !== undefined
+        && statesEqual(s.state, beforeState))
+        .map((s) => s.id);
+}
+//# sourceMappingURL=undo.js.map

package/lib/core/validator.d.ts

@@ -0,0 +1,18 @@
+import type { SectionId } from '../schema/types.ts';
+import type { CompatibilityInput, CompatibilityScore, ValidationResult } from './types.ts';
+export { validateManifest } from '../schema/manifest.ts';
+export { validateSectionData } from '../schema/config.ts';
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export declare function validateSections(sections: ReadonlyMap<SectionId, unknown>): ValidationResult;
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export declare function computeCompatibility(input: CompatibilityInput): CompatibilityScore;
+/** 兼容性得分的可读描述（UI 报告用） */
+export declare function describeCompatibility(score: CompatibilityScore): string;
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export declare function describeSchemaStatus(schemaVersion: number): string;

package/lib/core/validator.js

@@ -0,0 +1,77 @@
+/**
+ * 整体校验与兼容性评分（规范 §18 完整性 / §30 兼容性评分 / 导入后校验）。
+ */
+import { validateManifest } from '../schema/manifest.js';
+import { validateSectionData } from '../schema/config.js';
+import { canImport, describeVersion } from '../schema/versions.js';
+export { validateManifest } from '../schema/manifest.js';
+export { validateSectionData } from '../schema/config.js';
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export function validateSections(sections) {
+    const issues = [];
+    for (const [sectionId, data] of sections) {
+        const sectionIssues = validateSectionData(sectionId, data);
+        for (const issue of sectionIssues) {
+            issues.push({ ...issue, path: `${sectionId}:${issue.path}` });
+        }
+    }
+    return { valid: issues.every((i) => i.severity !== 'error'), issues };
+}
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)(?:\.(\d+))?(?:-(?:rc\.?)?(\d+))?/i.exec(v);
+    if (!m)
+        return { major: 0, minor: 0, patch: 0, pre: 0 };
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0), pre: Number(m[4] ?? Infinity) };
+}
+/** 版本比较：-1=a<b，0=相等，1=a>b（预发布 < 正式版） */
+function compareVersions(a, b) {
+    for (const k of ['major', 'minor', 'patch']) {
+        if (a[k] !== b[k])
+            return a[k] < b[k] ? -1 : 1;
+    }
+    if (a.pre !== b.pre)
+        return a.pre < b.pre ? -1 : 1;
+    return 0;
+}
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export function computeCompatibility(input) {
+    if (!canImport(input.schemaVersion))
+        return 'unsupported';
+    let score = 'excellent';
+    if (input.sourcePlatform !== input.targetPlatform)
+        score = 'partial';
+    if (input.missingSections.length > 0)
+        score = 'partial';
+    const src = parseVersion(input.sourceDsh);
+    const tgt = parseVersion(input.targetDsh);
+    const cmp = compareVersions(src, tgt);
+    if (cmp > 0) {
+        // 备份来自更新的 DSH → 可能有目标版本不认识的配置
+        score = 'partial';
+    }
+    else if (cmp < 0) {
+        // 备份来自更旧的 DSH → 目标向后兼容
+        score = 'good';
+    }
+    return score;
+}
+/** 兼容性得分的可读描述（UI 报告用） */
+export function describeCompatibility(score) {
+    switch (score) {
+        case 'excellent': return 'Excellent — 完美兼容（同平台、无缺失、schema 支持）';
+        case 'good': return 'Good — 兼容（旧版备份导入新版 DSH）';
+        case 'partial': return 'Partial — 部分兼容（跨平台/分区缺失/版本超前，需人工确认）';
+        case 'unsupported': return 'Unsupported — 不受支持（schema 超出范围）';
+    }
+}
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export function describeSchemaStatus(schemaVersion) {
+    return describeVersion(schemaVersion);
+}
+//# sourceMappingURL=validator.js.map

package/lib/core/verify-recovery.d.ts

@@ -0,0 +1,21 @@
+import type { RecoveryVerification, RecoveryVerificationVerdict } from './journal.ts';
+import type { HostContext, Snapshot } from './types.ts';
+export interface VerifyRecoveryOptions {
+    /** 快照根目录（<snapshotsDir>，<snapshotDir> 的直接父级）。 */
+    snapshotsRoot: string;
+    /** 当前环境指纹（必须与 snapshot binding 一致，否则 WRONG_ENVIRONMENT）。 */
+    environmentFingerprint: string;
+    /** 期望的 operationId（journal.operationId）。快照 operationId 必须与之双向一致，否则 WRONG_OPERATION。 */
+    expectedOperationId?: string;
+}
+/**
+ * Post-recovery verification（§6.4）。
+ *
+ * @param snapshot 被恢复 operation 的 journal 引用快照（id + binding 用于定位与交叉校验；
+ *                 实际校验以磁盘重读为准，不信任内存对象）。
+ * @param ctx      HostContext（homeDir / fs / settings / plugins 门面）。
+ * @param opts     snapshotsRoot + environmentFingerprint。
+ */
+export declare function verifyRecovery(snapshot: Snapshot, ctx: HostContext, opts: VerifyRecoveryOptions): Promise<RecoveryVerification>;
+/** 便捷：把 RecoveryVerification 映射为 journal 终态（供 verify 路由单次原子 update 使用）。 */
+export declare function recoveryTerminalState(verdict: RecoveryVerificationVerdict): 'ROLLED_BACK' | 'RECOVERED' | 'NEEDS_ATTENTION';

package/lib/core/verify-recovery.js

@@ -0,0 +1,256 @@
+/**
+ * Phase 5 Post-Recovery Verification（§6）。
+ *
+ * 职责：recovery/rollback 完成后，验证目标状态与 trusted snapshot 匹配。
+ * 核心不变量（VERIFIED）：**No recovery/rollback may be considered complete until the
+ * target state is verified to match the trusted snapshot** —— 验证失败不能 COMMITTED。
+ *
+ * 关键规则（§6.2 / §6.3 / §11.1）：
+ *  - **verify 时刻重验**：不信任 execute 时「已校验过」的结论（TOCTOU 窗口，快照可能被替换）。
+ *    本函数在 verify 时刻重跑完整 `validateSnapshotForRestore`（含 symlink + provenance +
+ *    env binding + `requireOperationBound=true`），并从磁盘重读 snapshot.json 作为权威。
+ *  - **只消费 TRUSTED_OPERATION_SNAPSHOT**：非 operation-bound（TRUSTED_MANUAL_LOCAL /
+ *    LEGACY_REQUIRES_CONFIRMATION）一律拒绝，绝不当作 MATCH。
+ *  - **verdict 语义严格区分**：
+ *      MATCH            目标状态与 snapshot 完全匹配
+ *      PARTIAL_MATCH    核心可验证状态匹配，但存在无法可靠验证的部分（如凭据值不可回读）
+ *      MISMATCH         能确定目标状态仍不同于 snapshot（文件 hash 不匹配 / 应删仍存在 /
+ *                       plugin/settings 明确不同）
+ *      VERIFICATION_ERROR 验证过程本身无法可靠完成（快照重验失败 / fs 读错误 / 异常）
+ *    绝不把 VERIFICATION_ERROR 降级成 PARTIAL_MATCH。
+ *  - 输出结构兼容 Step 2 的 `recoveryVerification`（verdict/details[]/manualHints[]/at）；
+ *    details/manualHints 写入 journal 前由调用方过 `redactJournalText`（本函数只产出文本，
+ *    不含 secret 值——凭据值不可回读，settings 只比对不输出值）。
+ *
+ * 本模块为纯函数（fs 经 node:fs + HostContext 门面注入），可独立测试。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveFileTarget } from './backup.js';
+import { validateSnapshotForRestore } from './restore.js';
+/** 越界防御：abs 必须等于 homeDir 或在 homeDir 之内 */
+function isWithinHome(homeDir, abs) {
+    const root = path.resolve(homeDir);
+    return abs === root || abs.startsWith(root + path.sep);
+}
+/** 绝对路径 → 相对 homeDir（跨平台归一为 / 分隔；越界返回空串） */
+function toRelPath(homeDir, abs) {
+    if (!isWithinHome(homeDir, abs))
+        return '';
+    return path.relative(homeDir, abs).split(path.sep).join('/');
+}
+/** 快照目录内 blob 绝对路径（防 snapshot.json 里伪造 ../ 越界读） */
+function blobAbs(snapshotDir, blobPath) {
+    const abs = path.resolve(snapshotDir, blobPath);
+    if (!isWithinHome(snapshotDir, abs))
+        throw new Error(`blob 路径越界: ${blobPath}`);
+    return abs;
+}
+/** Uint8Array 字节级相等 */
+function bufEq(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** file 类条目的目标绝对路径（复用 backup.ts 的基准目录规则；仅读 homeDir） */
+function resolveFileAbs(homeDir, adapter, ref) {
+    return resolveFileTarget({ homeDir }, adapter, ref);
+}
+/**
+ * Post-recovery verification（§6.4）。
+ *
+ * @param snapshot 被恢复 operation 的 journal 引用快照（id + binding 用于定位与交叉校验；
+ *                 实际校验以磁盘重读为准，不信任内存对象）。
+ * @param ctx      HostContext（homeDir / fs / settings / plugins 门面）。
+ * @param opts     snapshotsRoot + environmentFingerprint。
+ */
+export async function verifyRecovery(snapshot, ctx, opts) {
+    const details = [];
+    const manualHints = [];
+    const at = new Date().toISOString();
+    const snapshotDir = path.join(opts.snapshotsRoot, snapshot.id);
+    // 1) verify 时刻重验快照（TOCTOU）：重跑完整 validateSnapshotForRestore，requireOperationBound=true。
+    //    只接受 TRUSTED_OPERATION_SNAPSHOT；任何其它 verdict（含 TRUSTED_MANUAL_LOCAL / LEGACY）→ VERIFICATION_ERROR。
+    const val = await validateSnapshotForRestore(snapshotDir, opts.snapshotsRoot, {
+        environmentFingerprint: opts.environmentFingerprint,
+    });
+    if (val.verdict !== 'TRUSTED_OPERATION_SNAPSHOT') {
+        return {
+            verdict: 'VERIFICATION_ERROR',
+            details: [`快照重验失败: ${val.verdict}${val.reason ? ` — ${val.reason}` : ''}`],
+            manualHints: [],
+            at,
+        };
+    }
+    details.push('快照重验通过（TRUSTED_OPERATION_SNAPSHOT）');
+    // 2) 从磁盘重读 snapshot.json 作为权威（不信任传入的 snapshot 对象，防 execute→verify 间替换）。
+    let diskSnapshot;
+    try {
+        const raw = await fs.readFile(path.join(snapshotDir, 'snapshot.json'), 'utf8');
+        diskSnapshot = JSON.parse(raw);
+    }
+    catch (err) {
+        return { verdict: 'VERIFICATION_ERROR', details: [...details, `snapshot.json 重读失败: ${err instanceof Error ? err.message : String(err)}`], manualHints: [], at };
+    }
+    // 3) environment binding（validateSnapshotForRestore 已查，此处双保险）
+    if (diskSnapshot.environmentFingerprint && diskSnapshot.environmentFingerprint !== opts.environmentFingerprint) {
+        return { verdict: 'VERIFICATION_ERROR', details: [...details, 'environmentFingerprint 不匹配（WRONG_ENVIRONMENT）'], manualHints: [], at };
+    }
+    // 3b) operation binding（journal.operationId ↔ snapshot.operationId 双向一致；WRONG_OPERATION 拒绝）
+    if (opts.expectedOperationId !== undefined && diskSnapshot.operationId !== opts.expectedOperationId) {
+        return { verdict: 'VERIFICATION_ERROR', details: [...details, `operationId 不匹配（WRONG_OPERATION）: snapshot=${diskSnapshot.operationId ?? '(无)'} expected=${opts.expectedOperationId}`], manualHints: [], at };
+    }
+    let mismatch = false;
+    let unverifiable = false;
+    // 4) host files（hostFileBackups）：existed=true 应存在且内容 hash 匹配 blob；existed=false 应不存在。
+    //    经 ctx.fs（HostContext 注入，homeDir 相对）读写，与 rollback.ts 一致。
+    for (const backup of diskSnapshot.hostFileBackups ?? []) {
+        const rel = backup.relPath;
+        if (backup.existed) {
+            if (backup.blobPath === '') {
+                unverifiable = true;
+                details.push(`host file 无 blob 信息: ${rel}`);
+                continue;
+            }
+            if (!(await ctx.fs.exists(rel))) {
+                mismatch = true;
+                details.push(`host file 缺失: ${rel}`);
+                continue;
+            }
+            let blob;
+            try {
+                blob = await fs.readFile(blobAbs(snapshotDir, backup.blobPath));
+            }
+            catch {
+                unverifiable = true;
+                details.push(`host file blob 读取失败: ${rel}`);
+                continue;
+            }
+            const current = await ctx.fs.readFile(rel);
+            if (!bufEq(current, blob)) {
+                mismatch = true;
+                details.push(`host file 内容不匹配: ${rel}`);
+            }
+            else {
+                details.push(`host file 匹配: ${rel}`);
+            }
+        }
+        else {
+            // snapshot expects absent → target 必须不存在（删除动作失败 → 残留被检测）
+            if (await ctx.fs.exists(rel)) {
+                mismatch = true;
+                details.push(`应删除目标仍存在: ${rel}`);
+            }
+            else {
+                details.push(`删除目标已不存在: ${rel}`);
+            }
+        }
+    }
+    // 5) file 类条目（entries kind='file'）：existed=true 应存在且内容匹配 blob；existed=false 应不存在。
+    for (const entry of diskSnapshot.entries ?? []) {
+        if (entry.kind !== 'file')
+            continue;
+        const rel = toRelPath(ctx.homeDir, resolveFileAbs(ctx.homeDir, entry.adapter, entry.ref));
+        if (rel === '') {
+            unverifiable = true;
+            details.push(`file 路径越界: ${entry.adapter}:${entry.ref}`);
+            continue;
+        }
+        if (entry.existed && entry.copiedTo) {
+            if (!(await ctx.fs.exists(rel))) {
+                mismatch = true;
+                details.push(`file 缺失: ${entry.adapter}:${entry.ref}`);
+                continue;
+            }
+            let blob;
+            try {
+                blob = await fs.readFile(blobAbs(snapshotDir, entry.copiedTo));
+            }
+            catch {
+                unverifiable = true;
+                details.push(`file blob 读取失败: ${entry.adapter}:${entry.ref}`);
+                continue;
+            }
+            const current = await ctx.fs.readFile(rel);
+            if (!bufEq(current, blob)) {
+                mismatch = true;
+                details.push(`file 内容不匹配: ${entry.adapter}:${entry.ref}`);
+            }
+            else {
+                details.push(`file 匹配: ${entry.adapter}:${entry.ref}`);
+            }
+        }
+        else if (!entry.existed) {
+            if (await ctx.fs.exists(rel)) {
+                mismatch = true;
+                details.push(`应删除 file 目标仍存在: ${entry.adapter}:${entry.ref}`);
+            }
+            else {
+                details.push(`删除 file 目标已不存在: ${entry.adapter}:${entry.ref}`);
+            }
+        }
+    }
+    // 6) plugin state（best-effort）：导入期间新增插件应被移除。可精确验证 → 纳入 MATCH 判断；
+    //    无法可靠验证（无基线 / listInstalled 失败）→ PARTIAL_MATCH + manualHint。
+    const beforePlugins = diskSnapshot.beforePlugins;
+    if (beforePlugins === undefined) {
+        unverifiable = true;
+        details.push('快照无 beforePlugins 基线，插件状态不可验证');
+        manualHints.push('插件状态无法自动验证（快照无基线），请人工确认已装插件');
+    }
+    else {
+        try {
+            const current = await ctx.plugins.listInstalled();
+            const beforeNames = new Set(beforePlugins.map((p) => p.name));
+            const added = current.filter((p) => !beforeNames.has(p.name));
+            if (added.length > 0) {
+                mismatch = true;
+                details.push(`导入期间新增插件未移除: ${added.map((p) => p.name).join(', ')}`);
+            }
+            else {
+                details.push('插件状态匹配（无新增插件）');
+            }
+        }
+        catch {
+            unverifiable = true;
+            details.push('插件状态无法验证（listInstalled 失败）');
+            manualHints.push('插件状态无法自动验证（listInstalled 失败），请人工确认已装插件');
+        }
+    }
+    // 7) settings（best-effort）：settingsNamespace 条目 before 值应与当前 settings 一致。
+    const settingsEntries = (diskSnapshot.entries ?? []).filter((e) => e.kind === 'settingsNamespace');
+    for (const entry of settingsEntries) {
+        try {
+            const current = await ctx.settings.describe(entry.ref);
+            if (!isDeepStrictEqual(current.value, entry.before)) {
+                mismatch = true;
+                details.push(`settings 不匹配: ${entry.ref}`);
+            }
+            else {
+                details.push(`settings 匹配: ${entry.ref}`);
+            }
+        }
+        catch {
+            unverifiable = true;
+            details.push(`settings 无法验证: ${entry.ref}`);
+            manualHints.push(`settings 无法自动验证（${entry.ref}），请人工确认`);
+        }
+    }
+    // 8) verdict：MISMATCH 优先（能确定目标状态不同）；其次 PARTIAL_MATCH（存在不可验证项）；否则 MATCH。
+    if (mismatch)
+        return { verdict: 'MISMATCH', details, manualHints, at };
+    if (unverifiable)
+        return { verdict: 'PARTIAL_MATCH', details, manualHints, at };
+    return { verdict: 'MATCH', details, manualHints, at };
+}
+/** 便捷：把 RecoveryVerification 映射为 journal 终态（供 verify 路由单次原子 update 使用）。 */
+export function recoveryTerminalState(verdict) {
+    if (verdict === 'MATCH' || verdict === 'PARTIAL_MATCH')
+        return 'ROLLED_BACK';
+    return 'NEEDS_ATTENTION';
+}
+//# sourceMappingURL=verify-recovery.js.map

package/lib/core/watcher.d.ts

@@ -0,0 +1,101 @@
+/** 监听句柄（fs.watch 返回值的结构子集，便于测试伪造） */
+export interface WatchHandle {
+    close(): void;
+}
+/** 监听工厂（真实实现注入 fs.watch） */
+export type WatchFactory = (dir: string, onEvent: (eventType: string, filename: string | null) => void) => WatchHandle;
+/** 定时器注入（测试用假实现驱动时序） */
+export interface TimerApi {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface WatcherEvent {
+    /** 事件发生的目录（绝对路径） */
+    dir: string;
+    /** 文件名（fs.watch 可能给 null） */
+    filename: string;
+}
+export interface DebouncedWatcherOptions {
+    /** 要监听的目录（绝对路径；不存在的目录由 watchFactory 抛错，本类记 onError 后跳过） */
+    dirs: readonly string[];
+    /** 防抖窗口（毫秒） */
+    debounceMs: number;
+    watchFactory: WatchFactory;
+    /** 防抖到期后回调（事件已合并；同一目录同一文件去重） */
+    onFlush: (events: WatcherEvent[]) => void;
+    /** 监听失败 / 运行时 error 回调（不抛；默认静默） */
+    onError?: (dir: string, error: unknown) => void;
+    timers?: TimerApi;
+}
+/** 临时文件 / 编辑器残留：默认忽略，避免「保存一次触发多轮快照」 */
+export declare function isIgnorableFileName(name: string): boolean;
+/**
+ * 防抖监听器：把高频文件事件合并成一次 `onFlush`。
+ *
+ * 生命周期：`start()` 建立监听；`stop()` 关闭全部监听并清掉待发定时器；
+ * `start()` 可在 `stop()` 后重新调用（幂等重建——宿主改配置后需要重建监听集）。
+ */
+export declare class DebouncedWatcher {
+    private readonly options;
+    private readonly timers;
+    private handles;
+    private timer;
+    private pending;
+    private suppressCount;
+    private running;
+    constructor(options: DebouncedWatcherOptions);
+    get isRunning(): boolean;
+    /** 当前抑制深度（>0 表示正在执行会自写文件的操作） */
+    get suppressDepth(): number;
+    /** 待发事件数（测试与诊断用） */
+    get pendingCount(): number;
+    start(): void;
+    stop(): void;
+    /**
+     * 进入抑制窗口：期间产生的文件事件**直接丢弃**。
+     * 调用方必须在 finally 里 `endSuppress()`，否则自动快照会永久停摆。
+     */
+    beginSuppress(): void;
+    /**
+     * 退出抑制窗口：深度归零时**顺带清空待发事件**——那些事件正是被抑制的写操作
+     * 自己产生的，若放行会立刻产生一个回声快照（挡住重做）。
+     */
+    endSuppress(): void;
+    /** 同步便捷包装：抑制窗口内执行 fn，异常也保证退出抑制。 */
+    suppressWhile<T>(fn: () => T): T;
+    /** 异步便捷包装（恢复/回滚等长操作）。 */
+    suppressWhileAsync<T>(fn: () => Promise<T>): Promise<T>;
+    private onEvent;
+    private schedule;
+}
+/**
+ * 回声登记表：记录「我们刚刚写回的内容指纹」，用于识别监听器收到的
+ * 「恢复动作自己的写」这一回声。
+ *
+ * 与 `beginSuppress/endSuppress` 的分工：抑制窗口覆盖**写操作进行中**的事件；
+ * 本表覆盖**窗口之后才被投递**的延迟事件（macOS / 网络盘 / 杀毒软件扫描后
+ * 重写文件都可能造成事件晚到）。两条防线缺一不可——竞品的注释与 v0.4.6
+ * CHANGELOG 都记录了「macOS 延迟投递的回声快照挡住 redo」这一实际事故。
+ */
+export declare class EchoRegistry {
+    private readonly hashes;
+    /** 登记一次写回：key 建议 `${scope}:${relPath}`（如 `config:cordis.patch.yml`） */
+    record(key: string, hash: string): void;
+    /** 是否仍等于我们写回的内容（= 回声，应忽略） */
+    isEcho(key: string, hash: string): boolean;
+    has(key: string): boolean;
+    get size(): number;
+    /**
+     * 清空。
+     * 语义：**真实变更一旦发生就清空整表**——否则后续对同一路径的合法修改
+     * 只要恰好等于某次历史写回内容就会被误判为回声而漏拍。
+     */
+    clear(): void;
+}
+/**
+ * 把事件批按「目录 → 文件名」聚合，便于调用方按关注目录分类。
+ * 返回 Map<dir, Set<filename>>（顺序无关，便于集合判定）。
+ */
+export declare function groupEventsByDir(events: readonly WatcherEvent[]): Map<string, Set<string>>;
+/** 事件批里是否包含关注的文件名（跨目录；用于「配置目录里出现了被关注的 basename」判定） */
+export declare function hasWatchedBasename(events: readonly WatcherEvent[], watched: ReadonlySet<string>): boolean;