dsh-config-manager 0.1.78 → 0.1.80

package/lib/sync/s3/messages.d.ts

@@ -36,6 +36,12 @@ export declare const s3Zh: {
     readonly 'sync.s3.providerNoteKodo': '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）';
     readonly 'sync.s3.unknownSignatureDialect': '未知签名方言: {id}';
     readonly 'sync.s3.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}';
+    readonly 'sync.s3.concurrentWrite': '远端索引已被其它设备更新（HTTP {status}）：本次写入已中止，请重新同步后再试';
+    readonly 'sync.s3.probeOk': '连接正常（远端 {count} 份快照）';
+    readonly 'sync.s3.probeRegionRedirect': '端点把请求重定向到区域 {region}：请把 region 改成该值后重试';
+    readonly 'sync.s3.probeRedirectNoRegion': '端点返回了重定向（HTTP {status}）但没有给出区域：请核对 endpoint 与 region';
+    readonly 'sync.s3.probeBucketMissing': '桶不存在或无权访问（HTTP 404）：请核对 bucket 名与 endpoint';
+    readonly 'sync.s3.probeAccessDenied': '访问被拒绝（HTTP 403）：请核对 AccessKey、密钥与桶权限';
 };
 export declare const s3En: Record<keyof typeof s3Zh, string>;
 /**

package/lib/sync/s3/messages.js

@@ -26,6 +26,13 @@ export const s3Zh = {
     'sync.s3.providerNoteKodo': '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）',
     'sync.s3.unknownSignatureDialect': '未知签名方言: {id}',
     'sync.s3.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}',
+    // ---- cloud-sync 借鉴项 ①②：条件写并发保护 + 连通性探针 ----
+    'sync.s3.concurrentWrite': '远端索引已被其它设备更新（HTTP {status}）：本次写入已中止，请重新同步后再试',
+    'sync.s3.probeOk': '连接正常（远端 {count} 份快照）',
+    'sync.s3.probeRegionRedirect': '端点把请求重定向到区域 {region}：请把 region 改成该值后重试',
+    'sync.s3.probeRedirectNoRegion': '端点返回了重定向（HTTP {status}）但没有给出区域：请核对 endpoint 与 region',
+    'sync.s3.probeBucketMissing': '桶不存在或无权访问（HTTP 404）：请核对 bucket 名与 endpoint',
+    'sync.s3.probeAccessDenied': '访问被拒绝（HTTP 403）：请核对 AccessKey、密钥与桶权限',
 };
 export const s3En = {
     'sync.s3.providerUnknown': 'Unknown S3-compatible channel: {provider}',
@@ -53,6 +60,12 @@ export const s3En = {
     'sync.s3.providerNoteKodo': 'Qiniu Kodo S3-compatible (region required, e.g. cn-east-1; endpoint can be overridden)',
     'sync.s3.unknownSignatureDialect': 'Unknown signature dialect: {id}',
     'sync.s3.blobHashInvalid': 'Malformed content hash; refusing to write to the blob store: {hash}',
+    'sync.s3.concurrentWrite': 'The remote index was updated by another device (HTTP {status}): this write was aborted, please sync again',
+    'sync.s3.probeOk': 'Connection OK ({count} remote snapshots)',
+    'sync.s3.probeRegionRedirect': 'The endpoint redirects to region {region}: set region to that value and retry',
+    'sync.s3.probeRedirectNoRegion': 'The endpoint returned a redirect (HTTP {status}) without a region: check endpoint and region',
+    'sync.s3.probeBucketMissing': 'Bucket not found or not accessible (HTTP 404): check the bucket name and endpoint',
+    'sync.s3.probeAccessDenied': 'Access denied (HTTP 403): check the AccessKey, secret, and bucket permissions',
 };
 /** 插值：{param} → 形参值；缺参原样保留（与 core/messages.ts 同口径）。 */
 function interpolate(template, params) {

package/lib/sync/s3/s3-transport.d.ts

@@ -1,6 +1,6 @@
 import type { MsgFunc } from '../../core/msg-types.ts';
 import { SyncTransportError } from '../transport.ts';
-import type { SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
+import type { SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
 import type { SigV4DialectId } from './sigv4.ts';
 import type { S3Target } from './s3-providers.ts';
 import type { S3CompatProvider } from '../sync-config.ts';
@@ -77,6 +77,14 @@ export declare class S3Transport implements SyncTransport {
     download(id: string): Promise<SyncSnapshot>;
     /** 删除远端快照（不存在视为成功）；一并摘除索引条目并回收无人引用的 blob。 */
     delete(id: string): Promise<void>;
+    /** 条件写失败：远端索引在本次读取之后被别人改过 —— 中止写入让用户重跑（cloud-sync 借鉴项 ①）。 */
+    private concurrentWrite;
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②）：HEAD 桶证明端点/凭据/桶可达，再读一次索引回报快照数。
+     * 重定向（301/307/308）时读 x-amz-bucket-region 直接把「region 该填什么」告诉用户 ——
+     * 这是 S3 兼容端点最常见的失败原因（AWS/OSS/COS/Kodo 各自的 region 值不同）。
+     */
+    probe(): Promise<SyncProbeResult>;
     private assertSafeId;
     /** 读取一次 AccessKey Secret（失败 → 空串，让请求按「无凭据」失败并把原因如实带回） */
     private secretOnce;

package/lib/sync/s3/s3-transport.js

@@ -39,6 +39,21 @@ const ERR_BODY_MAX = 500;
 /** 内容哈希形状（sha256 hex）：blob 对象键只接受它，杜绝路径穿越 */
 const BLOB_HASH_RE = /^[a-f0-9]{64}$/;
 const REDACTED = '[REDACTED]';
+/**
+ * 条件写头（cloud-sync 借鉴项 ①）：有 ETag → If-Match（远端必须仍是我读到的那一版）；
+ * 索引本来就不存在 → If-None-Match: *（防两设备同时首推）；服务端不给 ETag → 空（无条件写，不改既有行为）。
+ */
+function conditionalHeaders(etag, indexMissing) {
+    if (etag !== undefined)
+        return { 'if-match': etag };
+    return indexMissing ? { 'if-none-match': '*' } : {};
+}
+/** 条件写失败判定：412 恒是；409 仅在**确实带了条件头**时才算（无条件的 409 另有含义，不吞）。 */
+function isConcurrentWrite(status, headers) {
+    if (status === 412)
+        return true;
+    return status === 409 && Object.keys(headers).length > 0;
+}
 /** S3 通道错误：继承统一错误基类（kind / retryable / status 对上层可见）。 */
 export class S3TransportError extends SyncTransportError {
     constructor(message, opts = {}) {
@@ -168,7 +183,7 @@ export class S3Transport {
         const secret = await this.secretOnce();
         const meta = computeSnapshotMeta(snapshot);
         // audit-sync sync-N1 覆盖面补全（t66，来自 t22 的 C7）：upload 也是写路径，**不接受 404 = 空集合**。
-        const { entries: idxBefore, missing: indexMissing } = await this.readIndexDetailed(secret);
+        const { entries: idxBefore, missing: indexMissing, etag: idxEtag } = await this.readIndexDetailed(secret);
         if (indexMissing && await this.remoteHasPriorContent(secret)) {
             // 索引 404 只是**缺信息**：远端已有历史内容时按空索引读改写，会把权威索引 PUT 成只有本条目
             // → 其余快照从列表整体消失，随后 delete + GC 会回收仍被现存快照文件引用的 blob（不可恢复）。
@@ -188,7 +203,14 @@ export class S3Transport {
         const merged = idxBefore.filter((m) => m.id !== snapshot.id);
         merged.push(meta);
         merged.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
-        const putIdx = await this.send('PUT', indexKey(this.target.prefix), { body: JSON.stringify(merged), secret });
+        const condHeaders = conditionalHeaders(idxEtag, indexMissing);
+        const putIdx = await this.send('PUT', indexKey(this.target.prefix), {
+            body: JSON.stringify(merged),
+            secret,
+            headers: condHeaders,
+        });
+        if (isConcurrentWrite(putIdx.res.status, condHeaders))
+            throw this.concurrentWrite(putIdx.url, putIdx.res.status);
         if (!putIdx.res.ok) {
             throw new S3TransportError(await this.failText('PUT', putIdx.url, putIdx.res, secret), classifyHttpStatus(putIdx.res.status));
         }
@@ -221,7 +243,7 @@ export class S3Transport {
         // index.json 覆盖成 []（其余快照从列表消失）并让 blob GC 删掉仍被引用的会话 blob —— 一律中止。
         // audit-sync sync-N1（P0）：与 WebDAV 同型 —— 写路径**不接受 404 = 空集合**。索引真缺失时
         // 「远端一条快照都没有」是缺信息而非事实，沿用空索引会覆盖 index.json 并用空引用集回收 blob。
-        const { entries: idx, missing: indexMissing } = await this.readIndexDetailed(secret);
+        const { entries: idx, missing: indexMissing, etag: idxEtag } = await this.readIndexDetailed(secret);
         const del = await this.send('DELETE', snapshotKey(this.target.prefix, id), { secret });
         if (!del.res.ok && del.res.status !== 404) {
             throw new S3TransportError(await this.failText('DELETE', del.url, del.res, secret), classifyHttpStatus(del.res.status));
@@ -233,13 +255,52 @@ export class S3Transport {
         const remaining = idx.filter((m) => m.id !== id);
         if (remaining.length === idx.length && del.res.status === 404)
             return; // 对象与索引都没有 → 静默成功
-        const putIdx = await this.send('PUT', indexKey(this.target.prefix), { body: JSON.stringify(remaining), secret });
+        const condHeaders = conditionalHeaders(idxEtag, false);
+        const putIdx = await this.send('PUT', indexKey(this.target.prefix), {
+            body: JSON.stringify(remaining),
+            secret,
+            headers: condHeaders,
+        });
+        if (isConcurrentWrite(putIdx.res.status, condHeaders))
+            throw this.concurrentWrite(putIdx.url, putIdx.res.status);
         if (!putIdx.res.ok) {
             throw new S3TransportError(await this.failText('PUT', putIdx.url, putIdx.res, secret), classifyHttpStatus(putIdx.res.status));
         }
         await this.gcBlobStore(secret, remaining).catch(() => undefined);
     }
     /* ---------------- 内部实现 ---------------- */
+    /** 条件写失败：远端索引在本次读取之后被别人改过 —— 中止写入让用户重跑（cloud-sync 借鉴项 ①）。 */
+    concurrentWrite(url, status) {
+        return new S3TransportError(this.o.msg('sync.s3.concurrentWrite', { status: String(status), url }), { kind: 'conflict', retryable: false, status });
+    }
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②）：HEAD 桶证明端点/凭据/桶可达，再读一次索引回报快照数。
+     * 重定向（301/307/308）时读 x-amz-bucket-region 直接把「region 该填什么」告诉用户 ——
+     * 这是 S3 兼容端点最常见的失败原因（AWS/OSS/COS/Kodo 各自的 region 值不同）。
+     */
+    async probe() {
+        const secret = await this.secretOnce();
+        const bucket = await this.send('HEAD', '', { secret });
+        const status = bucket.res.status;
+        if (status === 301 || status === 307 || status === 308) {
+            const region = bucket.res.headers?.['x-amz-bucket-region'] ?? bucket.res.headers?.['X-Amz-Bucket-Region'];
+            throw new S3TransportError(region !== undefined && region !== ''
+                ? this.o.msg('sync.s3.probeRegionRedirect', { region })
+                : this.o.msg('sync.s3.probeRedirectNoRegion', { status: String(status) }), { kind: 'client', retryable: false, status });
+        }
+        if (status === 404) {
+            throw new S3TransportError(this.o.msg('sync.s3.probeBucketMissing'), { kind: 'notfound', retryable: false, status });
+        }
+        if (status === 403) {
+            throw new S3TransportError(this.o.msg('sync.s3.probeAccessDenied'), { kind: 'auth', retryable: false, status });
+        }
+        if (!bucket.res.ok) {
+            throw new S3TransportError(await this.failText('HEAD', bucket.url, bucket.res, secret), classifyHttpStatus(status));
+        }
+        const { entries, missing } = await this.readIndexDetailed(secret);
+        const count = missing ? 0 : entries.length;
+        return { message: this.o.msg('sync.s3.probeOk', { count: String(count) }), snapshotCount: count };
+    }
     assertSafeId(id) {
         if (typeof id !== 'string' || !SAFE_ID_RE.test(id) || RESERVED_IDS.has(id)) {
             throw new S3TransportError(this.o.msg('sync.s3.invalidSnapshotId', { id: JSON.stringify(id) }));
@@ -257,7 +318,12 @@ export class S3Transport {
     /** 发送一次已签名请求；网络错误/超时归一为带分类的通道错误 */
     async send(method, key, opts) {
         const url = objectUrl(this.target, key);
-        const headers = { 'content-type': 'application/json' };
+        const headers = {
+            'content-type': 'application/json',
+            // 条件写头（if-match / if-none-match）从这里注入（cloud-sync 借鉴项 ①）；
+            // 签名在注入之后计算，因此条件头也进 SignedHeaders。
+            ...(opts.headers ?? {}),
+        };
         if (opts.body !== undefined)
             headers['content-length'] = String(Buffer.byteLength(opts.body, 'utf8'));
         const signed = signRequest({
@@ -342,7 +408,13 @@ export class S3Transport {
         if (!sent.res.ok) {
             throw new S3TransportError(await this.failText('GET', sent.url, sent.res, secret), classifyHttpStatus(sent.res.status));
         }
-        return { entries: this.parseIndex(await sent.res.text(), sent.url, secret), missing: false };
+        // ETag 是条件写的前置条件（cloud-sync 借鉴项 ①）；服务端没给就退化为无条件写，绝不判成失败。
+        const etag = sent.res.headers?.['etag'];
+        return {
+            entries: this.parseIndex(await sent.res.text(), sent.url, secret),
+            missing: false,
+            ...(typeof etag === 'string' && etag !== '' ? { etag } : {}),
+        };
     }
     parseIndex(raw, url, secret) {
         let parsed;

package/lib/sync/s3/sigv4.js

@@ -181,8 +181,17 @@ export function signRequest(input) {
         dialect,
     });
     const signature = createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
-    const authorization = dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
-        + ', ' + dialect.headerListLabel + '=' + headerList + ', Signature=' + signature;
+    // 授权头序列化按方言分两套（issue #109 实证）：
+    //  - AWS：AWS4-HMAC-SHA256 Credential=<ak>/<scope>, SignedHeaders=<list>, Signature=<sig>
+    //  - OSS4：官方 Go/PHP SDK 的格式是**逗号后不带空格**，且 AdditionalHeaders 为空时**整段省略**；
+    //    写成 ", AdditionalHeaders=, Signature=" 会被 OSS 判成 Authorization header value is empty.
+    //    （HTTP 400 InvalidArgument，错误码 EC 0002-00000209，真机逐一比对过两种格式）。
+    const authorization = dialect.headerListLabel === 'AdditionalHeaders'
+        ? dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
+            + (headerList === '' ? '' : ',' + dialect.headerListLabel + '=' + headerList)
+            + ',Signature=' + signature
+        : dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
+            + ', ' + dialect.headerListLabel + '=' + headerList + ', Signature=' + signature;
     return {
         headers: { ...all, authorization },
         authorization,

package/lib/sync/sync-engine.d.ts

@@ -1,11 +1,12 @@
 import { Importer } from '../core/importer.ts';
 import type { ConfigAdapter, GlobalConflictStrategy, HostContext, ImportAnalysis, ImportPlan, ImportResult, PathMapping, PlanItem, PlanItemKind, SecretScanner } from '../core/types.ts';
-import type { SectionId } from '../schema/types.ts';
+import type { SectionData, SectionId } from '../schema/types.ts';
 import type { SnapshotFs } from './fs.ts';
 import type { RetentionPolicy } from './retention-policy.ts';
-import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from './transport.ts';
+import type { PendingMerge } from './sync-state.ts';
+import type { SyncProbeResult, SyncSnapshotMeta, SyncTransport } from './transport.ts';
 import type { MsgFunc } from '../core/messages.ts';
-import type { MergePlan } from './merge.ts';
+import type { MergeConflictReason, MergePlan, MergeSectionResult } from './merge.ts';
 import type { SyncApplyPlan } from './risk.ts';
 import type { TransactionSnapshotContext } from '../core/types.ts';
 import type { PlanItemProgress } from '../core/analyzer.ts';
@@ -100,6 +101,14 @@ export interface SyncPushOptions {
      *  includeSecrets=true 必须同时 encrypt=true，否则拒绝（密钥绝不明文进入同步通道）；
      *  自动同步恒 includeSecrets=false（推普通快照）。 */
     includeSecrets?: boolean;
+    /**
+     * 强制推送（缺省 false）：跳过「远端已被其它设备推进」的前置检测。
+     *
+     * 为什么默认要拦：本机基线 X、别的设备推了 Y、本机再推 Z（不含 Y 的改动）时，
+     * 远端保留策略随后会淘汰 Y ⇒ **Y 的改动在远端与本机都消失**（静默丢数据）。
+     * 只有用户明确知道「要用本机覆盖远端」时才传 true。
+     */
+    force?: boolean;
 }
 export interface SyncPullOptions {
     /** 指定远端快照 id（缺省 = 最新） */
@@ -123,6 +132,12 @@ export interface SyncPushReport {
     /** 分区级告警（单项失败不拖垮整体，§34.17 语义） */
     warnings: string[];
     message?: string;
+    /**
+     * 本次推送**被前置检测拒绝**（远端已被其它设备推进）：未写远端、未记基线、未改 sync-state。
+     * 这是「需要先合并远端」的冲突态，不是通道/凭据故障 —— 调用方（自动同步 / 路由）应按冲突处理，
+     * 而不是记成「同步失败」。
+     */
+    conflict?: boolean;
 }
 /** 差异报告中的单个变更项（PlanItem 摘要，不含敏感细节） */
 export interface PullChange {
@@ -248,6 +263,63 @@ export interface ApplyItemsReport {
  * 保留导出是为了让既有调用方/测试仍能引用「缺省保留份数」这一事实，不再作为唯一判据。
  */
 export declare const MAX_REMOTE_SNAPSHOTS: number;
+/** previewMerge 的单条冲突视图（三侧文本都已截断 + redact；绝不回传原始值对象）。 */
+export interface MergePreviewConflictView {
+    /** 冲突位置：JSON 分区是 top-level key；文件类分区是 relativePath；'$' = 整分区冲突。 */
+    path: string;
+    kind: 'key' | 'file';
+    /** 冲突成因（可选：旧数据/旧 merge 结果没有该字段，界面缺省按 'both-modified' 措辞）。 */
+    reason?: MergeConflictReason;
+    /** 本机侧的可读预览（≤ 2 KiB，超出截断加省略号；已过 redact()）。 */
+    localPreview: string;
+    /** 远端侧的可读预览（同上）。 */
+    remotePreview: string;
+    /** 共同祖先侧的可读预览（同上；无祖先时为空串）。 */
+    ancestorPreview: string;
+}
+/** previewMerge 的单个分区视图。 */
+export interface MergePreviewSectionView {
+    id: SectionId;
+    decision: MergeSectionResult['decision'];
+    /** 自动合并并入的变更点数量（仅 decision === 'merge' 时有意义；缺省 = 未统计）。 */
+    autoMerged?: number;
+    conflictCount: number;
+    conflicts: MergePreviewConflictView[];
+}
+/** previewMerge 结果（只读、零写入）。 */
+export interface MergePreview {
+    /** 预览是否成功产出（远端无快照 → false + message，分区清单为空）。 */
+    ok: boolean;
+    /** 本次预览针对的**远端**快照 id；'' = 远端无快照。 */
+    snapshotId: string;
+    /** 是否拿到了本地祖先副本（false = 退化为两方合并 → 所有双侧差异都会呈现为 conflict）。 */
+    hasAncestor: boolean;
+    sections: MergePreviewSectionView[];
+    /** 与 risk.ts 的 classifyMergePlan 同口径计数：
+     *  auto = 可自动应用的非冲突项，review = 需人工，conflicts = decision === 'conflict'，skipped = 'skip'。 */
+    summary: {
+        auto: number;
+        review: number;
+        conflicts: number;
+        skipped: number;
+    };
+    message?: string;
+}
+/**
+ * 用户对**单个分区**的裁决（分区粒度：没有冲突项粒度 / 复合 id）。
+ *  - useRemote：用远端整分区原值（对键级冲突而言 = 放弃本机该分区里除冲突键以外的改动）；远端没有该分区 → 无法表达删除，计入 pendingConflicts；
+ *  - keepLocal ：保持本机整分区原值（本机没有该分区 = 无写入，直接跳过）；
+ *  - useMerged ：取 merge() 的 merged 结果 —— 仅 decision === 'merge' 的分区有效；'conflict' 分区没有 merged，按冲突处理并计入 pendingConflicts；
+ *  - skip     ：本轮不裁决该分区 → 计入 pendingConflicts，基线不推进（冲突下一轮重新出现）。
+ */
+export type MergeResolution = {
+    id: SectionId;
+    action: 'keepLocal' | 'useRemote' | 'useMerged' | 'skip';
+};
+/** applyMergeResolutions 报告：ApplyReport + 仍未裁决的冲突分区（非空 = 基线未推进）。 */
+export type ApplyMergeResolutionsReport = ApplyReport & {
+    pendingConflicts: SectionId[];
+};
 export declare class SyncEngine {
     private readonly ctx;
     private readonly transport;
@@ -281,8 +353,25 @@ export declare class SyncEngine {
      * 「源机 home → 本机 home」的重定基规则；'' = 旧快照/未知（不猜，行为不变）。
      */
     private lastMergedRemoteSourceHome;
+    /**
+     * 最近一次 merge() 命中的远端快照是否加密（issue #107）：
+     * applyMergeResolutions → applyMergePlan 写基线时据此决定祖先副本是否也落**密文**。
+     * false = 明文通道/未知（保持既有明文副本，行为逐字不变）。
+     */
+    private lastMergedRemoteEncrypted;
     /** 最近一次 merge() 收到的用户路径映射（applyMergePlan 复用；缺省 []） */
     private lastMergedPathMappings;
+    /**
+     * 最近一次 merge() 是否拿到了本地祖先副本（false = 两方合并）。
+     * previewMerge 用它如实告诉界面「为什么全都是冲突」，绝不让两方差异看起来像三方结论。
+     */
+    private lastMergeHadAncestor;
+    /**
+     * 最近一次 merge() 的三方输入（仅内存）。
+     * applyMergeResolutions 需要它还原「整分区」语义：merge() 的 MergePlan 只携带冲突处的
+     * 原始值（键级冲突只给键值），而 'useRemote' / 'keepLocal' 必须落**整分区**数据才能进导入计划。
+     */
+    private lastMergeInputs;
     constructor(opts: SyncEngineOptions);
     /** 同步只做 portable 分区（deviceSpecific/platformSpecific 永不参与）。
      *  构造注入 sections（同步范围）时再按注入范围过滤 —— 自动同步等后台流程
@@ -373,6 +462,9 @@ export declare class SyncEngine {
      * opts.sections：指定仅同步这些分区（高级/自定义模式）；缺省 = 全部 portable 推荐分区。
      * opts.encrypt/password/includeSecrets：加密快照（含可选密钥导出）。
      * 安全不变量：includeSecrets ⇒ encrypt（密钥绝不明文进入同步通道）；密码仅内存。
+     *
+     * 前置：**远端已被其它设备推进时默认拒绝写入**（见 assertRemoteNotAdvanced）—— 这一条在导出
+     * 之前执行，因为「本机这一版要不要推」是被远端状态决定的，先别做无谓的导出（plugins 还会 npm pack）。
      */
     push(opts?: SyncPushOptions): Promise<SyncPushReport>;
     /**
@@ -416,6 +508,17 @@ export declare class SyncEngine {
     private pruneRemoteSnapshots;
     /** 读取远端保留策略；提供者缺失/抛错 → 缺省策略（保守多留，绝不因读取失败误删）。 */
     private resolveRetentionPolicy;
+    /**
+     * push 前置：远端是否已被别的设备推进（防「推上去把别人的改动架空」）。
+     *
+     * 判据与 hasNewRemoteSnapshot() 同源但方向相反：
+     *  - 首次同步（lastSnapshotId === ''）→ **不拦**（本机没有基线可丢，第一次推送就是建立基线）；
+     *  - 远端为空 → 不拦（没有可比对的快照）；
+     *  - 其余：远端最新快照 id !== lastSnapshotId ⇒ 远端被推进（或本机基线已被裁剪）→ 拦。
+     *    两种情况都**无法安全断言「远端没变」**，保守拒绝并给出 force 出口。
+     *  - list() 抛错 → 返回 reason（调用方按原样继续并告警），绝不把「读不到」当成「没变」。
+     */
+    private remoteAdvancedCheck;
     /**
      * pull：拉取远端最新（或指定）快照 → 过滤 portable 分区 → 转临时标准 ZIP →
      * 复用 Importer 预览流程（analyzeImport/createImportPlan）产出差异报告。
@@ -476,8 +579,19 @@ export declare class SyncEngine {
      *
      * 前提：lastSnapshotId 必须是**远端**快照 id（P0-7）。旧实现把本地生成的快照 id 也写进去，
      * 于是合并/应用之后这里恒为 true → 每轮白跑 list + download + merge。
+     *
+     * `listed` 可选：调用方本轮已经 list 过（如自动同步先查加密快照）时直接传进来，
+     * 避免同一个回合对远端做两次 list —— 每条通道的 list 都是一次真实网络往返
+     * （git 通道 = `pull --ff-only`，webdav 通道 = PROPFIND/GET）。
      */
-    hasNewRemoteSnapshot(): Promise<boolean>;
+    hasNewRemoteSnapshot(listed?: readonly SyncSnapshotMeta[]): Promise<boolean>;
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②）：把当前通道的**只读**自检透出给宿主路由。
+     *
+     * 通道没实现 probe（如 git 通道按 fast-forward 语义自证）时**如实报不支持**，
+     * 绝不返回「连接正常」—— 谎报成功比不支持更糟。
+     */
+    probe(): Promise<SyncProbeResult>;
     /**
      * 本地 portable 配置当前内容与上次基线（sync-state.sections hash）相比是否有变化（§3.1 上传「看变化」）。
      * - 从未同步（sync-state.sections 为空）→ true；
@@ -496,13 +610,76 @@ export declare class SyncEngine {
     /**
      * 三方合并（不写本地配置、不执行导入）：local = 现场 export，remote = 下载的远端快照，
      * ancestor = 本地祖先副本；副本缺失 → 退化为两方合并（整分区 conflict 交用户裁决）。
-     * 唯一副作用是一个进程内备忘：记录本次命中的**远端**快照 id，供紧随其后的 applyMergePlan 写基线。
+     * 副作用只有进程内备忘（远端快照 id / sourceHome / 用户映射 / 祖先可用性 / plan / 三方输入），
+     * 供紧随其后的 previewMerge / applyMergePlan / applyMergeResolutions 复用：同一次调用只下载一次远端。
      */
     merge(opts?: {
         snapshotId?: string;
         password?: string;
         pathMappings?: PathMapping[];
     }): Promise<MergePlan>;
+    /**
+     * 合并预览（只读、零写入）：把 merge() 的三方结果翻成界面可渲染的结构化视图。
+     *
+     * 与 merge() 的关系：**复用**同一次调用（同一实例上只下载一次远端快照、只 export 一次本地），
+     * 不改远端、不写 sync-state、不落祖先副本、不动本机配置。
+     *
+     * 安全：每侧预览文本都先过 redact() 再截断到 2 KiB（敏感值绝不回传浏览器）；原始值对象
+     * （对象 / 数组 / 字节数组）**绝不**上抛给调用方。
+     */
+    previewMerge(opts?: {
+        snapshotId?: string;
+        password?: string;
+        pathMappings?: PathMapping[];
+    }): Promise<MergePreview>;
+    /**
+     * 按用户裁决应用合并结果（**分区粒度**），并严守基线纪律。
+     *
+     * 与 applyMergePlan 的关系：把 resolutions 映射成 SyncApplyPlan 后走**同一条执行路径**
+     * （applyMergePlan：兜底快照 + 失败整体回滚 + 成功才记基线）。本方法只额外负责两件事：
+     *  1. 把 merge() 的分区级结论翻成「远端整分区 / 本机整分区 / 自动合并结果」的实际数据
+     *     （键级冲突的 conflicts 只带键值，进不了导入计划，必须回到整分区语义）；
+     *  2. 基线纪律 —— 只要还有未裁决分区，就**不推进远端基线指针**并记 pendingMerge
+     *     （冲突下一轮重新出现）；全部裁决完才清空 pendingMerge 并推进基线。
+     *
+     * 裁决语义（与 MergeResolution 的文档一致）：
+     *  - 未点名的分区按 merge() 的既有结论处理：可决断（useRemote / keepLocal / merge）→ 应用；
+     *    'skip' → 跳过；'conflict' → 计入 pendingConflicts；
+     *  - action='skip'（点名了但不裁决）：该分区若有内容可裁决 → 计入 pendingConflicts（**不算解决**，
+     *    否则基线推进会让它下一轮不再被提出 = 静默丢改动）；本来就无变化的 'skip' 分区 → 跳过；
+     *  - useMerged 而 merge() 没给 merged（典型：'conflict' 分区）→ 计入 pendingConflicts；
+     *  - useRemote 而远端没有该分区（= 远端删了它）→ 导入计划表达不了删除 → 计入 pendingConflicts；
+     *  - keepLocal 而本机没有该分区 → 保持现状（无写入）→ 跳过。
+     */
+    applyMergeResolutions(resolutions: MergeResolution[], opts?: {
+        snapshotId?: string;
+        password?: string;
+        pathMappings?: PathMapping[];
+        snapshotBinding?: TransactionSnapshotContext;
+    }): Promise<ApplyMergeResolutionsReport>;
+    /** 组装 pendingMerge 记录：同一远端快照上的连续待裁决**保留首次时间**（界面据此讲「挂了多久」）。 */
+    private pendingMergeFor;
+    /**
+     * 基线纪律的**纯状态**写入（不写祖先副本、不碰远端）：仅在本机没有任何配置写入时使用。
+     *
+     * - pending 提供 → 写 pendingMerge；undefined → 清除该字段（「全部裁决完」）；
+     * - advanceRemoteId 提供 → 把远端指针推进到该快照 id（缺省 = 保持不变）。
+     *
+     * 为什么不走 recordBaseline：那条路径会重建祖先副本并只带本次应用的分区 —— 在「没有应用任何分区」
+     * 或「仍有未裁决冲突」时都会把共同基线改坏（下一轮所有分区都退化成「无祖先 → 冲突」）。
+     */
+    private writeMergeBaseline;
+    /**
+     * 重新导出**已应用**的分区（F-2，2026-10）：基线的唯一正确来源是「实际落地的本机内容」。
+     *
+     * 为什么不能用计划/远端的 merged 载荷：写回时 adapter 会自增本机侧字段（如
+     * settings.namespaces[*].revision），而 merged 记录的是**远端快照里的值**；据此记基线会让
+     * 下一轮 merge 同时判「本地改了」与「远端改了」→ both-modified 冲突 → 每轮重复冲突。
+     *
+     * 口径与 merge() 的本地侧导出一致：文件类分区直接取 data，其余过 SecretScanner 剥离。
+     * 任一分区导出失败 → 返回 null（调用方**不推进基线**并明确告警）：绝不写半个基线。
+     */
+    private exportAppliedSections;
     /**
      * 记录祖先基线：写本地祖先副本 + 更新 sync-state（每分区 hash/updatedAt、lastSyncAt、transport、
      * 远端指针 lastSnapshotId、本地祖先目录名 ancestorId）+ 裁剪到 keep。
@@ -513,12 +690,24 @@ export declare class SyncEngine {
      *   （push 路径两者天然相同）；合并/应用路径**必须显式传**，否则 lastSnapshotId 会退化成「一个远端
      *   并不存在的本地 id」→ hasNewRemoteSnapshot() 恒判「远端有新生」，每轮白跑 list + download + merge。
      *   传入 `''` 表示「远端 id 未知」——宁可留空，也不要把本地 id 冒充成远端 id。
-     * - `opts.writeAncestor === false`（加密快照 push）：不落本地祖先副本，`ancestorId` 一并置 '' ——
+     * - `opts.writeAncestor === false`：不落本地祖先副本，`ancestorId` 一并置 '' ——
      *   绝不把一个本地并不存在的目录名写进状态（旧实现正是这样让下一轮 merge 直接抛错）。
-     */
-    recordBaseline(snapshotId: string, sections: SyncSnapshot['sections'], nowIso?: string, opts?: {
+     * - `opts.ancestorPassword`（issue #107）：祖先副本落**密文**（manifest.encrypted + 单密文载荷）；
+     *   加密快照 push 必须传，否则下轮三方合并缺共同祖先、整分区冲突。
+     * - `opts.preserveAncestor === true`（合并仍有未裁决冲突）：祖先副本与 ancestorId **保持不动** ——
+     *   共同基线必须仍是「本机与远端都认可的上一版」；拿只带本次应用分区的副本去覆盖它，会让
+     *   下一轮所有分区都退化成「无祖先 → 冲突」。
+     * - `opts.pendingMerge`（基线纪律）：提供即写入；`null` = 清除该字段；缺省 = 不动（既有行为不变）。
+     */
+    recordBaseline(snapshotId: string, sections: Partial<Record<SectionId, SectionData>>, nowIso?: string, opts?: {
         writeAncestor?: boolean;
+        /** 提供即把祖先副本写成**密文**（密码仅本次内存使用；issue #107） */
+        ancestorPassword?: string;
         remoteSnapshotId?: string;
+        /** 保留当前祖先副本与 ancestorId（缺省 false = 既有行为逐字不变） */
+        preserveAncestor?: boolean;
+        /** 待裁决冲突记录：null = 清除；缺省 = 不动该字段 */
+        pendingMerge?: PendingMerge | null;
         /** P1-5：本轮**实际带走**的会话单元（提供即覆盖；缺省 = 保留原记录） */
         sessionUnits?: string[];
         /** P1-5：本轮累积的删除墓碑（提供即覆盖；缺省 = 保留原记录） */
@@ -548,6 +737,21 @@ export declare class SyncEngine {
         pathMappings?: PathMapping[];
         /** 覆盖自动重定基的源 home（缺省 = merge() 记下的远端 sourceHome） */
         sourceHome?: string;
+        /**
+         * 保留祖先副本与 ancestorId（缺省 false = 既有行为逐字不变）。
+         * applyMergeResolutions 在**仍有未裁决冲突**时必须传 true：共同基线仍是「本机与远端都认可的上一版」。
+         */
+        preserveAncestor?: boolean;
+        /**
+         * 待裁决冲突记录（基线纪律）：null = 清除（全部裁决完）；缺省 = 不动该字段。
+         * 与 recordBaseline 同语义，随本次成功的基线写入**同一次落盘**（原子，不留中间态）。
+         */
+        pendingMerge?: PendingMerge | null;
+        /**
+         * issue #107：本次基线对应的远端快照是加密快照时传解密密码 → 祖先副本也落**密文**。
+         * 缺省 = 明文祖先副本（既有行为逐字不变）。密码仅本进程内存使用。
+         */
+        ancestorPassword?: string;
     }): Promise<ApplyReport>;
     /**
      * applyItems：按用户对差异项的逐项决策执行导入（§3.4/§5.3）。