@logictan/dsh-config-manager 0.1.60

package/lib/core/migration-consult.d.ts

@@ -0,0 +1,117 @@
+import type { Manifest, SectionId } from '../schema/types.ts';
+import type { ManifestIssue } from '../schema/manifest.ts';
+import type { SensitiveHit } from './types.ts';
+export type ConsultSourceType = 'export-zip' | 'local-snapshot' | 'remote-snapshot' | 'profile';
+export type HealthVerdict = 'healthy' | 'needs-attention' | 'critical';
+export type Recommendation = 'proceed' | 'review' | 'block';
+export type ConsultDimensionId = 'compatibility' | 'integrity' | 'sections' | 'consistency' | 'sensitive' | 'migratability';
+export interface ConsultSourceRef {
+    type: ConsultSourceType;
+    /** 源标识：ZIP 路径 / snapshotId / 远端快照 id / profile 名 */
+    id: string;
+    /** 关联 snapshotId（local-snapshot / remote-snapshot） */
+    snapshotId?: string;
+}
+export interface ConsultIssue {
+    severity: 'info' | 'warning' | 'error';
+    /** 稳定问题码（i18n 键后缀；如 'integrity.manifestInvalid'） */
+    code: string;
+    /** 已 redact 的可读消息（宿主/UI 层负责脱敏） */
+    message: string;
+    /** 已 redact 的证据（可选） */
+    evidence?: string;
+}
+export interface HealthDimension {
+    id: ConsultDimensionId;
+    /** 0-100 */
+    score: number;
+    verdict: HealthVerdict;
+    issues: ConsultIssue[];
+}
+/** 可迁移性（宿主经 analyzeImport / createImportPlan / analyzeSwitch 计算；null = 未评估） */
+export interface MigratabilityResult {
+    ok: boolean;
+    itemCount: number;
+    fatalConflicts: number;
+    warnings: number;
+    sections: SectionId[];
+    errors: string[];
+}
+/** 归一化后的源数据（宿主按源类型读取填充；核心只做评分） */
+export interface ConsultSourceData {
+    source: ConsultSourceRef;
+    manifest: Manifest | null;
+    manifestIssues: ManifestIssue[];
+    sections: Map<SectionId, unknown>;
+    sectionFiles: Map<string, Uint8Array>;
+    checksums: Record<string, string> | null;
+    checksumIssues: string[];
+    zipSlipIssues: string[];
+    encrypted: boolean;
+    containsSecrets: boolean;
+    sourceDsh: string;
+    sourcePlatform: string;
+    schemaVersion: number;
+    missingSections: SectionId[];
+    /** 敏感暴露面（宿主经 scanAndRedact 统计；只含路径/字段名，不含值） */
+    sensitiveHits: SensitiveHit[];
+    /** 可迁移性（宿主计算；null = 未评估） */
+    migratability: MigratabilityResult | null;
+}
+export interface ConsultTarget {
+    targetDsh: string;
+    targetPlatform: string;
+}
+export interface ConsultOptions {
+    /** block 是否允许（health=critical 且此 true 时 recommendation=block；缺省 false） */
+    allowBlock?: boolean;
+    /** 各维度权重（缺省内置；总和应为 1） */
+    weights?: Partial<Record<ConsultDimensionId, number>>;
+}
+export interface ConsultWillApply {
+    sections: SectionId[];
+    itemCount: number;
+    conflicts: number;
+    risks: number;
+    overwritten: number;
+    /** 咨询恒为 dry-run（只读分析） */
+    dryRun: boolean;
+}
+export interface ConsultReport {
+    source: ConsultSourceRef;
+    /** 0-100 */
+    healthScore: number;
+    verdict: HealthVerdict;
+    recommendation: Recommendation;
+    /** 触发项（已 redact） */
+    recommendationReasons: string[];
+    dimensions: HealthDimension[];
+    willApply: ConsultWillApply;
+    bound: {
+        manifest?: Manifest;
+        snapshotId?: string;
+        sourceId: string;
+    };
+    generatedAt: string;
+}
+/** 内置维度权重（总和 = 1） */
+export declare const DEFAULT_DIMENSION_WEIGHTS: Record<ConsultDimensionId, number>;
+/** 维度 verdict 阈值：score>=90 → healthy；60<=score<90 → needs-attention；score<60 → critical */
+export declare const HEALTHY_THRESHOLD = 90;
+export declare const CRITICAL_THRESHOLD = 60;
+/** 兼容性维度：复用 computeCompatibility（扩展而非重写） */
+export declare function scoreCompatibility(data: ConsultSourceData, target: ConsultTarget): HealthDimension;
+/** 结构完整性维度：manifest 合法 + checksums 匹配 + 无 Zip Slip */
+export declare function scoreIntegrity(data: ConsultSourceData): HealthDimension;
+/** 分区完整性维度：每个声明分区的数据可解析、无残缺 */
+export declare function scoreSections(data: ConsultSourceData): HealthDimension;
+/** 一致性维度：跨分区引用（凭据引用）是否自洽；孤立/悬空引用 */
+export declare function scoreConsistency(data: ConsultSourceData): HealthDimension;
+/** 敏感暴露维度：快照是否含未加密 secret、高熵 token 泄漏面 */
+export declare function scoreSensitive(data: ConsultSourceData): HealthDimension;
+/** 可迁移性维度：dry-run 应用能否通过（无致命冲突） */
+export declare function scoreMigratability(data: ConsultSourceData): HealthDimension;
+/** 计算全部维度（确定性） */
+export declare function computeDimensions(data: ConsultSourceData, target: ConsultTarget, weights?: Record<ConsultDimensionId, number>): HealthDimension[];
+/** 汇总健康评分 + verdict + recommendation（确定性） */
+export declare function computeConsultReport(data: ConsultSourceData, target: ConsultTarget, opts?: ConsultOptions): ConsultReport;

package/lib/core/migration-consult.js

@@ -0,0 +1,363 @@
+/**
+ * 迁移前咨询（Phase 7）：健康评分 + 咨询报告模型（纯函数，可测）。
+ *
+ * 三段式引擎第一段：迁移前咨询（Manifest + 健康评分）→ 迁移中事务（Phase 3 Journal）
+ * → 迁移后可审计（Phase 6 迁移历史）。本模块是**只读分析层**，不新建任何持久化 framework。
+ *
+ * Core Invariants：
+ *  - READ-ONLY：本模块纯函数，绝不产生 mutation（不写配置/快照/journal）。
+ *  - ACCURATE：评分规则驱动、确定性（同一源任何时候评分一致）；verdict 与评分/证据一致。
+ *  - COMPLETE：覆盖全部 4 种可迁移源类型（export-zip / local-snapshot / remote-snapshot / profile）。
+ *  - REDACTED：报告绝不含 secret/凭据/敏感值（宿主在填充 sensitiveHits 时已脱敏；
+ *    渲染前由 UI 层 redact() 兜底）。
+ *  - ACTIONABLE：产出 proceed / review / block 三态建议并能解释为什么（recommendationReasons）。
+ *  - BOUND：报告关联 manifest / snapshotId / 源标识（可追溯）。
+ *  - NON-BLOCKING 安全：咨询是建议性；默认 review 级不强制阻断，health=critical 且
+ *    allowBlock=true 时可 block（block 逻辑可回退/可覆盖，且记录在案）。
+ *
+ * 复用现有：computeCompatibility（扩展而非重写）、validateManifest、scanAndRedact、
+ * integrity/zip-security、import-wizard 分析管线（宿主填充 migratability）。
+ */
+import { computeCompatibility } from './validator.js';
+import { redact } from '../security/redaction.js';
+/* ---------------- 常量 ---------------- */
+/** 内置维度权重（总和 = 1） */
+export const DEFAULT_DIMENSION_WEIGHTS = {
+    compatibility: 0.20,
+    integrity: 0.25,
+    sections: 0.20,
+    consistency: 0.10,
+    sensitive: 0.15,
+    migratability: 0.10,
+};
+/** 维度 verdict 阈值：score>=90 → healthy；60<=score<90 → needs-attention；score<60 → critical */
+export const HEALTHY_THRESHOLD = 90;
+export const CRITICAL_THRESHOLD = 60;
+/* ---------------- 评分辅助 ---------------- */
+function dimensionVerdict(score) {
+    if (score >= HEALTHY_THRESHOLD)
+        return 'healthy';
+    if (score >= CRITICAL_THRESHOLD)
+        return 'needs-attention';
+    return 'critical';
+}
+function clampScore(score) {
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+function worstVerdict(a, b) {
+    const rank = { healthy: 0, 'needs-attention': 1, critical: 2 };
+    return rank[a] >= rank[b] ? a : b;
+}
+/* ---------------- 各维度评分 ---------------- */
+/** 兼容性维度：复用 computeCompatibility（扩展而非重写） */
+export function scoreCompatibility(data, target) {
+    const issues = [];
+    let score;
+    let compat;
+    if (data.manifest === null) {
+        compat = 'unsupported';
+        score = 0;
+        issues.push({ severity: 'error', code: 'compatibility.noManifest', message: '无法评估兼容性：manifest 缺失' });
+    }
+    else {
+        compat = computeCompatibility({
+            sourceDsh: data.sourceDsh,
+            targetDsh: target.targetDsh,
+            sourcePlatform: data.sourcePlatform,
+            targetPlatform: target.targetPlatform,
+            schemaVersion: data.schemaVersion,
+            missingSections: data.missingSections,
+        });
+        switch (compat) {
+            case 'excellent':
+                score = 100;
+                break;
+            case 'good':
+                score = 90;
+                break;
+            case 'partial':
+                score = 60;
+                issues.push({ severity: 'warning', code: 'compatibility.partial', message: '部分兼容：跨平台 / 分区缺失 / 版本超前，需人工确认' });
+                break;
+            case 'unsupported':
+                score = 0;
+                issues.push({ severity: 'error', code: 'compatibility.unsupported', message: '不受支持：schema 超出本插件支持范围' });
+                break;
+        }
+    }
+    return { id: 'compatibility', score, verdict: dimensionVerdict(score), issues };
+}
+/** 结构完整性维度：manifest 合法 + checksums 匹配 + 无 Zip Slip */
+export function scoreIntegrity(data) {
+    const issues = [];
+    let score = 100;
+    if (data.manifest === null) {
+        score = 0;
+        issues.push({ severity: 'error', code: 'integrity.noManifest', message: 'manifest 缺失，无法校验结构完整性' });
+    }
+    else {
+        for (const issue of data.manifestIssues) {
+            if (issue.severity === 'error') {
+                score -= 30;
+                issues.push({ severity: 'error', code: 'integrity.manifestInvalid', message: `manifest 无效：${issue.message}`, evidence: issue.path });
+            }
+            else {
+                score -= 10;
+                issues.push({ severity: 'warning', code: 'integrity.manifestWarning', message: `manifest 警告：${issue.message}`, evidence: issue.path });
+            }
+        }
+    }
+    for (const c of data.checksumIssues) {
+        score -= 30;
+        issues.push({ severity: 'error', code: 'integrity.checksumMismatch', message: `完整性校验失败：${c}` });
+    }
+    // 源无 checksum 表（manifest 存在但 checksums 缺失）→ warning（轻度完整性顾虑）
+    if (data.manifest !== null && data.checksums === null) {
+        score -= 10;
+        issues.push({ severity: 'warning', code: 'integrity.noChecksums', message: '源缺少 checksum 表，无法校验条目完整性' });
+    }
+    for (const z of data.zipSlipIssues) {
+        score -= 30;
+        issues.push({ severity: 'error', code: 'integrity.zipSlip', message: `ZIP 路径越界：${z}` });
+    }
+    return { id: 'integrity', score: clampScore(score), verdict: dimensionVerdict(clampScore(score)), issues };
+}
+/** 分区完整性维度：每个声明分区的数据可解析、无残缺 */
+export function scoreSections(data) {
+    const issues = [];
+    let score = 100;
+    for (const sid of data.missingSections) {
+        score -= 20;
+        issues.push({ severity: 'warning', code: 'sections.missing', message: `声明包含但数据缺失：${sid}`, evidence: sid });
+    }
+    // 分区数据不可解析（manifest 声明但 sections 中无对应数据且非 missingSections 覆盖）
+    if (data.manifest !== null) {
+        for (const [sid, enabled] of Object.entries(data.manifest.sections)) {
+            if (!enabled)
+                continue;
+            if (data.missingSections.includes(sid))
+                continue;
+            if (!data.sections.has(sid)) {
+                score -= 30;
+                issues.push({ severity: 'error', code: 'sections.unparseable', message: `分区数据不可解析：${sid}`, evidence: sid });
+            }
+        }
+    }
+    return { id: 'sections', score: clampScore(score), verdict: dimensionVerdict(clampScore(score)), issues };
+}
+/* ---------------- 一致性检查（凭据引用） ---------------- */
+/** 从 settings 分区提取凭据引用名（apiKeyEnv / 引用类字段值） */
+function extractSettingsCredentialRefs(data) {
+    const refs = new Set();
+    const settings = data.sections.get('settings');
+    const REFERENCE_REF_FIELDS = new Set([
+        'apikeyenv', 'api_key_env', 'apikeyname', 'tokenenv', 'accesstokenenv',
+        'refreshtokenenv', 'clientsecretenv', 'passwordenv',
+    ]);
+    for (const rec of Object.values(settings?.namespaces ?? {})) {
+        const value = (rec.value ?? {});
+        for (const [k, v] of Object.entries(value)) {
+            const norm = k.toLowerCase().replace(/[^a-z0-9]/g, '');
+            if (REFERENCE_REF_FIELDS.has(norm) && typeof v === 'string' && v !== '')
+                refs.add(v);
+        }
+        if (typeof value['apiKeyEnv'] === 'string' && value['apiKeyEnv'] !== '')
+            refs.add(value['apiKeyEnv']);
+        const providers = value['providers'];
+        if (providers !== null && typeof providers === 'object') {
+            for (const pv of Object.values(providers)) {
+                if (pv !== null && typeof pv === 'object' && typeof pv.apiKeyEnv === 'string' && pv.apiKeyEnv !== '') {
+                    refs.add(pv.apiKeyEnv);
+                }
+            }
+        }
+    }
+    return [...refs];
+}
+/** 从 providers 分区提取凭据引用名（providers[route].apiKeyEnv） */
+function extractProvidersCredentialRefs(data) {
+    const refs = new Set();
+    const providers = data.sections.get('providers');
+    for (const pv of Object.values(providers?.providers ?? {})) {
+        if (pv !== null && typeof pv === 'object' && typeof pv.apiKeyEnv === 'string' && pv.apiKeyEnv !== '') {
+            refs.add(pv.apiKeyEnv);
+        }
+    }
+    return [...refs];
+}
+/** 从 credentialsStatus 分区提取已声明 ref 集 */
+function extractDeclaredCredentialRefs(data) {
+    const refs = new Set();
+    const creds = data.sections.get('credentialsStatus');
+    for (const c of creds?.credentials ?? []) {
+        if (typeof c?.ref === 'string' && c.ref !== '')
+            refs.add(c.ref);
+    }
+    return refs;
+}
+/** 一致性维度：跨分区引用（凭据引用）是否自洽；孤立/悬空引用 */
+export function scoreConsistency(data) {
+    const issues = [];
+    let score = 100;
+    const referenced = new Set([
+        ...extractSettingsCredentialRefs(data),
+        ...extractProvidersCredentialRefs(data),
+    ]);
+    const declared = extractDeclaredCredentialRefs(data);
+    for (const ref of referenced) {
+        if (!declared.has(ref)) {
+            score -= 15;
+            issues.push({
+                severity: 'warning',
+                code: 'consistency.danglingCredentialRef',
+                message: `凭据引用未在 credentials 分区声明：${ref}`,
+                evidence: ref,
+            });
+        }
+    }
+    return { id: 'consistency', score: clampScore(score), verdict: dimensionVerdict(clampScore(score)), issues };
+}
+/** 敏感暴露维度：快照是否含未加密 secret、高熵 token 泄漏面 */
+export function scoreSensitive(data) {
+    const issues = [];
+    let score = 100;
+    if (data.containsSecrets && !data.encrypted) {
+        score -= 40;
+        issues.push({ severity: 'error', code: 'sensitive.unencryptedSecrets', message: '快照含未加密秘密（凭据值明文暴露）' });
+    }
+    const hitCount = data.sensitiveHits.length;
+    if (hitCount > 0) {
+        const penalty = Math.min(hitCount * 5, 40);
+        score -= penalty;
+        issues.push({
+            severity: 'warning',
+            code: 'sensitive.hits',
+            message: `检测到 ${hitCount} 处敏感字段暴露（已脱敏）`,
+        });
+    }
+    return { id: 'sensitive', score: clampScore(score), verdict: dimensionVerdict(clampScore(score)), issues };
+}
+/** 可迁移性维度：dry-run 应用能否通过（无致命冲突） */
+export function scoreMigratability(data) {
+    const issues = [];
+    let score;
+    const m = data.migratability;
+    if (m === null) {
+        // 未评估可迁移性 = warning 级 → needs-attention（60），与 warning 标签一致（不落到 critical）
+        score = 60;
+        issues.push({ severity: 'warning', code: 'migratability.notEvaluated', message: '未评估可迁移性（dry-run 未执行）' });
+    }
+    else if (!m.ok) {
+        score = 0;
+        issues.push({ severity: 'error', code: 'migratability.failed', message: '可迁移性检查失败：dry-run 无法通过' });
+        for (const e of m.errors) {
+            issues.push({ severity: 'error', code: 'migratability.error', message: e });
+        }
+    }
+    else {
+        score = 100;
+        for (let i = 0; i < m.fatalConflicts; i++) {
+            score -= 30;
+            issues.push({ severity: 'error', code: 'migratability.fatalConflict', message: '存在致命冲突，需人工决策' });
+        }
+        for (let i = 0; i < m.warnings; i++) {
+            score -= 10;
+            issues.push({ severity: 'warning', code: 'migratability.warning', message: '存在需注意的迁移项' });
+        }
+    }
+    return { id: 'migratability', score: clampScore(score), verdict: dimensionVerdict(clampScore(score)), issues };
+}
+/* ---------------- 汇总 ---------------- */
+/**
+ * 构造时脱敏（REDACTED 不变量主防线）：对每个 issue 的 message/evidence 应用 redact()。
+ * 渲染前 redact() 仅作辅防线；本函数保证报告对象本身不含敏感值。
+ */
+function redactIssues(dims) {
+    return dims.map((d) => ({
+        ...d,
+        issues: d.issues.map((i) => ({
+            ...i,
+            message: redact(i.message),
+            evidence: i.evidence !== undefined ? redact(i.evidence) : undefined,
+        })),
+    }));
+}
+/** 计算全部维度（确定性） */
+export function computeDimensions(data, target, weights = DEFAULT_DIMENSION_WEIGHTS) {
+    const dims = [
+        scoreCompatibility(data, target),
+        scoreIntegrity(data),
+        scoreSections(data),
+        scoreConsistency(data),
+        scoreSensitive(data),
+        scoreMigratability(data),
+    ];
+    // 权重仅用于加权平均；维度 verdict 与权重无关（确定性）
+    void weights;
+    return redactIssues(dims);
+}
+/** 汇总健康评分 + verdict + recommendation（确定性） */
+export function computeConsultReport(data, target, opts = {}) {
+    const weights = {
+        ...DEFAULT_DIMENSION_WEIGHTS,
+        ...opts.weights,
+    };
+    const dimensions = computeDimensions(data, target, weights);
+    // 加权平均
+    let weighted = 0;
+    for (const dim of dimensions) {
+        weighted += (weights[dim.id] ?? 0) * dim.score;
+    }
+    const healthScore = clampScore(weighted);
+    // verdict = 最差维度 verdict
+    let verdict = 'healthy';
+    for (const dim of dimensions)
+        verdict = worstVerdict(verdict, dim.verdict);
+    // recommendation
+    let recommendation;
+    if (verdict === 'critical') {
+        recommendation = opts.allowBlock === true ? 'block' : 'review';
+    }
+    else if (verdict === 'needs-attention') {
+        recommendation = 'review';
+    }
+    else {
+        recommendation = 'proceed';
+    }
+    // 触发项（全部 error/warning issue 的 message，已 redact）
+    const recommendationReasons = [];
+    for (const dim of dimensions) {
+        for (const issue of dim.issues) {
+            if (issue.severity === 'error' || issue.severity === 'warning') {
+                recommendationReasons.push(issue.message);
+            }
+        }
+    }
+    // willApply（来自 migratability；dryRun 恒 true）
+    const m = data.migratability;
+    const willApply = {
+        sections: m?.sections ?? [],
+        itemCount: m?.itemCount ?? 0,
+        conflicts: m?.fatalConflicts ?? 0,
+        risks: m?.warnings ?? 0,
+        overwritten: m?.fatalConflicts ?? 0,
+        dryRun: true,
+    };
+    const bound = { sourceId: data.source.id };
+    if (data.manifest !== null)
+        bound.manifest = data.manifest;
+    if (data.source.snapshotId !== undefined)
+        bound.snapshotId = data.source.snapshotId;
+    return {
+        source: data.source,
+        healthScore,
+        verdict,
+        recommendation,
+        recommendationReasons,
+        dimensions,
+        willApply,
+        bound,
+        generatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=migration-consult.js.map

package/lib/core/migration-history.d.ts

@@ -0,0 +1,153 @@
+export declare const MIGRATION_HISTORY_SCHEMA_VERSION = 1;
+export declare const MIGRATION_HISTORY_DIR = "migration-history";
+/** 默认保留上限（retention 删最旧）。 */
+export declare const DEFAULT_MIGRATION_RETENTION = 1000;
+/** 合法 kind 集合（§5 COMPLETE 清单 + 评审补 'profile-import'）。 */
+declare const MIGRATION_KINDS: readonly ['import', 'restore', 'rollback', 'profile-switch', 'profile-delete', 'profile-rename', 'profile-save', 'profile-import', 'sync-apply', 'autosync', 'recovery', 'backup', 'snapshot-delete', 'snapshot-prune'];
+/** §5 覆盖的操作 kind（COMPLETE 不变量；常量枚举，天然非敏感）。 */
+export type MigrationKind = (typeof MIGRATION_KINDS)[number];
+/** 操作结果。 */
+export type MigrationResult = 'success' | 'failed' | 'skipped';
+/** 触发来源（常量）。 */
+export type MigrationSource = 'api' | 'autosync' | 'backup-scheduler' | 'recovery' | 'cli' | 'internal';
+/** 一条不可变的迁移历史记录（磁盘形态；schemaVersion 内联）。 */
+export interface MigrationHistoryEntry {
+    schemaVersion: number;
+    at: string;
+    kind: MigrationKind;
+    result: MigrationResult;
+    /** 涉及分区 adapter id（常量集合）。 */
+    sections: string[];
+    /** Journal operation id（UUID，BOUND）。 */
+    operationId?: string;
+    /** 快照 id（UUID，BOUND）。 */
+    snapshotId?: string;
+    /** run-registry runId（UUID，BOUND）。 */
+    runId?: string;
+    source: MigrationSource;
+    /** 非敏感摘要（redact + high-entropy 后）。 */
+    summary: string;
+    /** 失败原因（redact + high-entropy 后）。 */
+    error?: string;
+}
+/**
+ * 磁盘形态：schemaVersion + contentHash（对除 contentHash 外全字段的 SHA-256）。
+ * contentHash 用于 **append-only 篡改检测**：合法 JSON 内改字段值（含 result/summary/at）
+ * → 读回 hash 不符 → 该文件被识别为损坏并跳过（满足「篡改必须被拒绝或检测」）。
+ * 仅是内联字段（非 MAC/签名 / 非第二套 integrity framework；审计史非对抗性安全边界）。
+ */
+export interface StoredMigrationHistoryEntry extends Omit<MigrationHistoryEntry, 'schemaVersion'> {
+    schemaVersion: number;
+    contentHash: string;
+}
+/** 查询条件（纯函数过滤）。 */
+export interface MigrationQuery {
+    kinds?: MigrationKind[];
+    /** 起始时间（epoch ms，含）。 */
+    from?: number;
+    /** 结束时间（epoch ms，含）。 */
+    to?: number;
+    result?: MigrationResult[];
+    /** sections 子集匹配（条目 sections 含任一查询分区即命中）。 */
+    sections?: string[];
+}
+/** 统计（纯函数）。 */
+export interface MigrationHistoryStats {
+    total: number;
+    byKind: Partial<Record<MigrationKind, number>>;
+    byResult: Partial<Record<MigrationResult, number>>;
+}
+export type ExportFormat = 'json' | 'markdown';
+/** 读取历史的结果：合法条目 + 被识别为损坏/跳过的文件名（append-only 篡改检测）。 */
+export interface ReadMigrationResult {
+    entries: StoredMigrationHistoryEntry[];
+    /** 被跳过/损坏的文件名（读取时识别，UI 可选警示；不静默接受）。 */
+    corrupted: string[];
+}
+/** 追加写入结果（best-effort 调用方据此判断降级）。 */
+export interface AppendResult {
+    ok: boolean;
+    entry: StoredMigrationHistoryEntry;
+    file?: string;
+    error?: string;
+}
+/** 可注入 IO 门面（测试注入失败点）；默认包 node:fs/promises。 */
+export interface MigrationIo {
+    mkdir(dir: string, opts: {
+        recursive: boolean;
+    }): Promise<void>;
+    readdirNames(dir: string): Promise<string[]>;
+    readFileText(p: string): Promise<string>;
+    writeAll(target: string, content: string): Promise<void>;
+    rm(p: string, opts: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    lstat(p: string): Promise<{
+        isSymbolicLink(): boolean;
+    } | null>;
+    exists(p: string): Promise<boolean>;
+}
+/**
+ * 历史文本强脱敏：redact（结构化字段 + 已知值形状）+ 高熵长 token 掩码。
+ * 用于 summary / error 等可能嵌入任意值的字段（REDACTED 不变量）。
+ */
+export declare function redactHistoryText(text: string): string;
+/**
+ * 构造安全条目：对 summary / error 做强脱敏（scanAndRedact 高熵档 + redactHistoryText），
+ * 做白名单字段规范化，并计算 contentHash（对除 contentHash 外全字段的 SHA-256）。
+ * **历史写入的唯一出口入口**，禁止绕过。
+ */
+export declare function sanitizeEntry(raw: Omit<MigrationHistoryEntry, 'schemaVersion'> & {
+    schemaVersion?: number;
+}): StoredMigrationHistoryEntry;
+/** 合法 kind 判定（类型守卫 + 运行时校验）。 */
+export declare function isValidMigrationKind(k: unknown): k is MigrationKind;
+/** 判断文件 basename 是否是可追踪历史文件（<sortable>-<hex>.json）。忽略 tmp 及其它。 */
+export declare function isHistoryBasename(name: string): boolean;
+/** 文件名安全：仅 basename（不含目录分隔符/穿越）。 */
+export declare function isSafeHistoryFilename(name: string): boolean;
+/**
+ * 生成排序文件名（Windows-safe 定宽时间戳 + 随机后缀 + kind 标记）。
+ *
+ * 时间戳契约（Windows/排序可靠性）：`toISOString().replace(/[:Z]/g,'')`
+ * → `2026-08-30T120000.123`（UTC 定宽、仅 ASCII、无 Windows 非法字符 `<>:"/\|?*`、
+ * 字典序== 时间序）。**禁止**以原始 `toISOString()`（含 `:`）直接落文件名（Windows rename 失败）。
+ * 与既有 `dateStamp`（`YYYYMMDD-HHmmss`）语义同为「定宽 + 仅 ASCII + 可排序」，本实现用 UTC 含毫秒
+ * 以获得更高时序精度；排序可靠性一致。
+ */
+export declare function makeHistoryFilename(now: Date, kind: MigrationKind): string;
+export interface MigrationStoreOptions {
+    /** history 存放目录（<dataDir>/migration-history）。 */
+    dir: string;
+    io?: MigrationIo;
+    /** 保留上限（retention 用；调用方可覆盖）。 */
+    retention?: number;
+}
+/** MigrationHistory：per-file append-only 历史存储。 */
+export declare class MigrationStore {
+    private readonly dir;
+    private readonly io;
+    constructor(opts: MigrationStoreOptions);
+    /** 追加一条历史（原子写）。best-effort：调用方须经 tryAppendHistory 处理失败降级。 */
+    append(raw: Omit<MigrationHistoryEntry, 'schemaVersion' | 'at' | 'kind'> & {
+        kind: MigrationKind;
+        at?: string;
+    }): Promise<AppendResult>;
+    /** 读取全部合法历史条目（旧→新；损坏/非史文件跳过并计数）。 */
+    read(): Promise<ReadMigrationResult>;
+    /**
+     * 保留清理：按文件名排序删除最旧合法历史文件，幂等。只删合法历史文件（防误删）。
+     * 返回本次删除的文件名。
+     */
+    retention(limit?: number): Promise<string[]>;
+}
+/** 纯函数过滤（无 IO）。 */
+export declare function queryHistory(entries: StoredMigrationHistoryEntry[], q: MigrationQuery): StoredMigrationHistoryEntry[];
+/** 纯函数统计（kind/result 计数）。 */
+export declare function summarizeHistory(entries: StoredMigrationHistoryEntry[]): MigrationHistoryStats;
+/** 导出报告（纯函数）。渲染文本统一过 redact() 兜底（安全不变量）。 */
+export declare function renderExport(entries: StoredMigrationHistoryEntry[], format: ExportFormat, locale?: 'zh' | 'en'): string;
+/** 解析查询参数为 MigrationQuery（宿主路由复用；过滤非法输入）。 */
+export declare function parseHistoryQuery(raw: Record<string, unknown>): MigrationQuery;
+export {};