dsh-config-manager 0.1.76 → 0.1.78

package/lib/core/rollback-merge.js

@@ -0,0 +1,203 @@
+/**
+ * 行级**三方合并**（base / ours / theirs）—— 回退时「撤销本会话的改动、保留别人的改动」的判定内核。
+ *
+ * 为什么需要它（2026-10-17 跨对话安全回退）：
+ *  回滚点的「工作区态」是整棵树的快照，回退若直接整文件覆盖，会把别的对话在留点之后
+ *  产生的修改一起抹掉。正确语义是：把 **base→ours**（本会话那次改动的反向）与
+ *  **base→theirs**（别人后来的改动）同时应用到文件上 —— 即标准三方合并。
+ *
+ * 三方是谁（由调用方给定，本模块只管算）：
+ *  · `base`  = 共同祖先：本会话改动之后、别人的改动之前的那个版本；
+ *  · `ours`  = 回退目标：回滚点里记录的内容（= 本会话改之前的版本）；
+ *  · `theirs` = 当前磁盘上的内容。
+ *  结果为 `ours + (theirs - base)`，即撤销本会话、保留别人。
+ *
+ * 四条硬规矩：
+ *  ① **不确定就不合并**：任一方向的 diff 被规模预算降级（`degraded`）⇒ 直接拒绝（reason=`degraded`），
+ *     绝不拿一个「整块替换」的近似编辑脚本去算合并。
+ *  ② **冲突绝不自动选边**：两侧改到同一处（含同一插入点）就报冲突，返回 theirs 原文 + `ok:false`，
+ *     调用方必须**不写文件**并把冲突交给用户。
+ *  ③ **二进制不合并**（含 NUL 即二进制，与 git 同口径）。
+ *  ④ **依赖风险只提示、不假装证明**：合并要删掉的行里的标识符若仍出现在结果中，
+ *     给出**启发式**风险提示（`risks`）—— 它不构成「删除不安全」的证明，也绝不因此声称合并正确。
+ */
+import { diffLines, looksBinary } from '../utils/line-diff.js';
+/** 标识符取样用的最小长度（太短的词（i、id）同名词满天飞，只会制造噪声） */
+const RISK_TOKEN_MIN = 4;
+/** 不参与依赖提示的通用词（语言关键字 / 极常见标识符） */
+const RISK_STOPWORDS = new Set([
+    'const', 'let', 'var', 'function', 'return', 'import', 'export', 'from', 'class', 'interface', 'type',
+    'public', 'private', 'readonly', 'async', 'await', 'true', 'false', 'null', 'undefined', 'this', 'void',
+    'if', 'else', 'for', 'while', 'switch', 'case', 'break', 'continue', 'new', 'throw', 'try', 'catch',
+    'string', 'number', 'boolean', 'object', 'Array', 'Promise', 'Record', 'Partial', 'default',
+]);
+/**
+ * 一段文本相对 base 的**变更块**（按 base 的行区间表示）。
+ * 返回 null = 该方向的 diff 被降级（规模预算），调用方必须放弃合并。
+ */
+function changeBlocks(base, target) {
+    // context=0：只要变更行，块边界自己算（省得剔上下文）
+    const diff = diffLines(base, target, { context: 0 });
+    if (diff.degraded)
+        return null;
+    const blocks = [];
+    for (const hunk of diff.hunks) {
+        // 当前块与「已消耗到 base 的哪一行」
+        let block = null;
+        let cursor = Math.max(0, hunk.oldStart - 1);
+        const flush = () => {
+            if (block !== null)
+                blocks.push(block);
+            block = null;
+        };
+        for (const line of hunk.lines) {
+            if (line.kind === 'context') {
+                flush();
+                if (line.oldNo !== null)
+                    cursor = line.oldNo;
+                continue;
+            }
+            if (line.kind === 'del') {
+                const at = line.oldNo === null ? cursor : line.oldNo - 1;
+                if (block === null)
+                    block = { start: at, end: at, lines: [] };
+                block.end = at + 1;
+                cursor = at + 1;
+                continue;
+            }
+            // add：没有 del 时是纯插入（位置 = 当前游标）
+            if (block === null)
+                block = { start: cursor, end: cursor, lines: [] };
+            block.lines.push(line.text);
+        }
+        flush();
+    }
+    return blocks;
+}
+/** 两个块在 base 上是否**互相触碰**（保守：含边界与纯插入点） */
+function touches(a, b) {
+    const aPoint = a.start === a.end;
+    const bPoint = b.start === b.end;
+    if (aPoint && bPoint)
+        return a.start === b.start;
+    // **纯插入点落在区间端点不算冲突**：「删掉 `[s,e)`」与「在 e 处插入」可以共存（先删、再在删除后
+    // 的位置插入）。真机 2026-10-17 的「撤销 A 的描述 + 保留 B 的描述」正是这种形状：A 删掉了尾部
+    // 一行，B 又在其后追加了一行 —— 旧判据把它们当冲突，于是回退变成「什么都不做」。
+    // 只有落在区间**内部**（严格介于 s 与 e 之间）的插入才是真正说不清的冲突。
+    if (aPoint)
+        return a.start > b.start && a.start < b.end;
+    if (bPoint)
+        return b.start > a.start && b.start < a.end;
+    return a.start < b.end && b.start < a.end;
+}
+/** 两侧的块是否「改成了同一件事」（内容逐行相同即可取其一，不算冲突） */
+function sameChange(a, b) {
+    if (a.lines.length !== b.lines.length)
+        return false;
+    for (let i = 0; i < a.lines.length; i += 1)
+        if (a.lines[i] !== b.lines[i])
+            return false;
+    return true;
+}
+/** 从被撤销的行里取「可能仍被引用」的标识符（启发式，见模块头 ④） */
+function riskTokens(lines) {
+    const seen = new Set();
+    for (const line of lines) {
+        for (const token of line.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []) {
+            if (token.length < RISK_TOKEN_MIN)
+                continue;
+            if (RISK_STOPWORDS.has(token))
+                continue;
+            seen.add(token);
+        }
+    }
+    return [...seen];
+}
+/**
+ * 三方合并（纯函数、无 I/O）。
+ *
+ * 语义：结果是 `ours` 上再应用 `(theirs - base)` —— 撤销「我们从 base 改到 ours 的那部分」，
+ * 同时保留「别人从 base 改到 theirs 的那部分」。
+ */
+export function mergeThreeWay(ours, base, theirs) {
+    const empty = (reason, conflicts = 0, risks = []) => ({
+        ok: false, text: theirs, reason, conflicts, revertedLines: 0, risks,
+    });
+    // 没有基线就退化成「谁的改动都不认识」—— 调用方负责在无 base 时根本不调用本函数
+    if (looksBinary(base) || looksBinary(ours) || looksBinary(theirs))
+        return empty('binary');
+    if (ours === base) {
+        // 本会话没改过 ⇒ 结论就是「保持别人现在的内容」（不是失败）
+        return { ok: true, text: theirs, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+    }
+    if (theirs === base) {
+        // 别人没改过 ⇒ 直接回到 ours
+        return { ok: true, text: ours, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+    }
+    if (ours === theirs) {
+        // 双方最终内容一致 ⇒ 谁都不用动
+        return { ok: true, text: theirs, reason: 'clean', conflicts: 0, revertedLines: 0, risks: [] };
+    }
+    const oursBlocks = changeBlocks(base, ours);
+    const theirsBlocks = changeBlocks(base, theirs);
+    if (oursBlocks === null || theirsBlocks === null)
+        return empty('degraded');
+    // 冲突扫描：任一 ours 块与任一 theirs 块触碰且内容不同 ⇒ 冲突
+    let conflicts = 0;
+    for (const a of oursBlocks) {
+        for (const b of theirsBlocks) {
+            if (!touches(a, b))
+                continue;
+            if (sameChange(a, b))
+                continue;
+            conflicts += 1;
+        }
+    }
+    if (conflicts > 0)
+        return empty('conflict', conflicts);
+    const baseLines = splitLinesOf(base);
+    const merged = [];
+    const reverted = [];
+    let cursor = 0;
+    // 把两侧的块按 base 位置归并（位置相同的「同一改动」只应用一次）
+    const all = [
+        ...oursBlocks.map((block) => ({ block, owner: 'ours' })),
+        ...theirsBlocks.map((block) => ({ block, owner: 'theirs' })),
+    ].sort((left, right) => left.block.start - right.block.start);
+    for (const item of all) {
+        const { block, owner } = item;
+        if (block.start < cursor) {
+            // 已被同一位置的另一个块消费（只可能是「同一改动」）—— 跳过重复应用
+            continue;
+        }
+        for (let i = cursor; i < block.start && i < baseLines.length; i += 1)
+            merged.push(baseLines[i]);
+        if (owner === 'ours') {
+            // 这一段就是「被撤销的本会话改动」：记下它删掉了哪些行，供依赖提示用
+            for (let i = block.start; i < block.end && i < baseLines.length; i += 1)
+                reverted.push(baseLines[i]);
+        }
+        for (const line of block.lines)
+            merged.push(line);
+        cursor = Math.max(cursor, block.end);
+    }
+    for (let i = cursor; i < baseLines.length; i += 1)
+        merged.push(baseLines[i]);
+    // 尾换行以**当前磁盘**（theirs）为准：我们是在它的基础上撤销本会话的改动，不擅改它原本的收尾形态
+    const text = merged.join('\n') + (merged.length > 0 && theirs.endsWith('\n') ? '\n' : '');
+    // 依赖风险（启发式）：被撤销的行里出现过、且合并结果里仍能读到的标识符
+    const tokens = riskTokens(reverted);
+    const risks = tokens.filter((token) => new RegExp('\\b' + token + '\\b').test(text)).slice(0, 8);
+    return { ok: true, text, reason: 'clean', conflicts: 0, revertedLines: reverted.length, risks };
+}
+/** 与 `splitLines` 同口径的本地折行（避免为了一个函数再引一层依赖） */
+function splitLinesOf(text) {
+    if (text === '')
+        return [];
+    const normalized = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const lines = normalized.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+//# sourceMappingURL=rollback-merge.js.map

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

@@ -1,4 +1,5 @@
 import { type DiffHunk } from '../utils/line-diff.ts';
+import type { RollbackWriteAttributionPort, RollbackWriteRecorder } from './rollback-attribution.ts';
 import { ROLLBACK_DEFAULT_LEDGER_BYTES } from './rollback-ledger.ts';
 export declare const ROLLBACK_SCHEMA_VERSION = 2;
 /** 回滚点库目录名（dataDir/rollback-points）——路由族 /recovery/rollback-points/* 同源 */
@@ -575,6 +576,23 @@ export interface RollbackPreviewFile {
      * **宁可说「不知道」，也绝不谎报行数。**
      */
     truncated: boolean;
+    /**
+     * true = 该文件在留点**之后**是**别的会话**写的（写入归属台账证明；见 core/rollback-attribution.ts）。
+     * 界面据此默认不勾选它（用户仍可勾上）。缺字段 / false = **没有归属证据**，
+     * 而不是「本会话写的」——「未判定」与「确知是本会话」必须分开。
+     */
+    foreign?: boolean;
+    /** 那些「别的会话」的会话 id（仅当 foreign 为 true） */
+    foreignSessionId?: string;
+    /** 那次写入的时间（毫秒；仅当 foreign 为 true） */
+    foreignAt?: number;
+    /**
+     * true = 这次回退**不会改动它**：要么与其它对话的改动冲突、要么无法安全合并（缺共同祖先 / 二进制 /
+     * 差异被降级 / 对方删了它）。行级统计一律为 null —— 「不改动」不是「0 行变化」。
+     */
+    skipped?: boolean;
+    /** 不改动的机器原因（界面映射成字典键，绝不裸渲染） */
+    mergeReason?: string;
 }
 /** 单文件差异里一侧（当前磁盘 / 回退点快照）的展示信息。 */
 export interface RollbackFileDiffSide {
@@ -616,6 +634,15 @@ export interface RollbackFileDiffResult {
     degraded: boolean;
     /** 无法逐行对比的原因（有值时 hunks 为空） */
     reason?: RollbackFileDiffReason;
+    /** true = 「回退后」一侧显示的是**三方合并**的结果，而不是记录里的原文 */
+    merged?: boolean;
+    /**
+     * true = 这次回退**不会改动**它（与其它对话的改动冲突 / 无法安全合并）—— 此时 after 与 before 相同。
+     * 界面必须把「不会改动」与「0 行变化」分开说。
+     */
+    mergeSkipped?: boolean;
+    /** 不改动的机器原因（界面映射成字典键，绝不裸渲染） */
+    mergeReason?: string;
     limits: typeof ROLLBACK_FILE_DIFF_LIMITS;
 }
 export interface RollbackPreviewWorkspace {
@@ -784,6 +811,28 @@ export interface RollbackSegmentResult {
      */
     createdRefusedReason?: 'capture-incomplete';
     writtenBytes?: number;
+    /**
+     * 因路径选择（onlyPaths）而未恢复 / 未删除的条目数。
+     * 与 createdSkipped（安全拒删）**分开**：这里的原因是用户自己没勾它，不是安全判据挡下。
+     */
+    selectionSkipped?: number;
+    /**
+     * 因**归属隔离**（2026-10-17 定案 B）而跳过的记录条目数：该文件在留点之后是**别的会话**写的。
+     * 只在**没有显式点名**（`onlyPaths` 缺省）时生效；显式点名 = 用户明确要它，归属不再拦。
+     */
+    foreignSkipped?: number;
+    /** 三方合并成功、写回「撤销本会话 + 保留对方改动」的条目数（有界清单同给） */
+    mergedCount?: number;
+    mergedPaths?: string[];
+    /** 冲突：两侧改到同一处 ⇒ **未写**，交给用户处理 */
+    conflictCount?: number;
+    conflictPaths?: string[];
+    /** 无法安全撤销（无中间版本 / 二进制 / 差异被降级 / 对方改成了不存在）⇒ **未写** */
+    unavailableCount?: number;
+    unavailablePaths?: string[];
+    /** 写入前发现又被改过（并发）⇒ **未写** */
+    concurrentCount?: number;
+    concurrentPaths?: string[];
     /** 会话段：fork 出来的子会话 id */
     childSessionId?: string;
     guidance?: RollbackGuidance[];
@@ -803,6 +852,16 @@ export interface RollbackRewindInput {
      * （把已写回的文件还原、把已删的文件写回）。拒删判据见 createdRemovalRefusal。
      */
     removeCreated?: boolean;
+    /**
+     * **路径级选择性恢复**（2026-10-17 用户定案 A）：只恢复 / 只删除这些路径。
+     *
+     * 缺省（undefined）= 既有全量口径，行为一字不变。给了值就：
+     *  · 记录在案的文件里**不在**清单中的：不写（计入 selectionSkipped）；
+     *  · 「留点后新建」的候选里**不在**清单中的：不删（同样计入）。
+     * 清单里出现**既未记录、也不在删除候选**里的路径 ⇒ **fail-closed 拒绝、零写入**（invalid-input）：
+     * 绝不把「用户打错一个路径」变成「静默少恢复几个文件」。
+     */
+    onlyPaths?: readonly string[];
 }
 export interface RollbackRewindResult {
     ok: boolean;
@@ -829,6 +888,11 @@ export type RollbackStorageProbe = () => Promise<{
 export interface RollbackEngineOptions {
     /** 插件数据目录（= $DSH_HOME/dsh-config-manager）；回滚点库在 dataDir/rollback-points */
     dataDir: string;
+    /**
+     * 写入归属台账（2026-10-17 用户定案 B）。缺省 = 没有归属信息 ⇒ 预览不标 foreign，
+     * 回退行为与旧版**逐字一致**（未判定绝不当作「别的会话写的」）。
+     */
+    attribution?: RollbackWriteAttributionPort;
     /** DSH home（会话根 = homeDir/sessions） */
     homeDir: string;
     now?: () => number;
@@ -1020,6 +1084,8 @@ export declare class RollbackPointEngine {
     private ledgerSnapshotCache;
     /** 台账存储层（v3：清单 + 单条记录 + 内容寻址载荷；issue #89） */
     private readonly ledger;
+    /** 写入归属（2026-10-17 定案 B）。undefined = 没有归属信息 ⇒ 预览不标 foreign */
+    private readonly attribution;
     private readonly ledgerBytesBudget;
     /**
      * 工作区捕获的挂钟时间预算（毫秒；见 ROLLBACK_DEFAULT_CAPTURE_BUDGET_MS）。**可变**：
@@ -1377,6 +1443,13 @@ export declare class RollbackPointEngine {
      * `budget` 是**单张预览**共享的累计预算（字节 + 步数），跨条目生效。
      */
     private previewFileCounts;
+    /**
+     * **合并结果**的逐文件行级统计（与 `previewFileCounts` 同一套预算与降级判据）。
+     *
+     * 为什么单独一份：合并后要写进去的内容既不是记录里的原文（ours），也不是磁盘现状（theirs）——
+     * 预览若照旧拿 ours 算差异，就会把「其实会被保留的对方改动」显示成「会被删掉」。
+     */
+    private previewMergeCounts;
     /** 只读预览：零写入（不过确认门、不拍 guard、不写任何字节）。 */
     preview(id: string): Promise<RollbackPreviewResult>;
     /**
@@ -1406,6 +1479,41 @@ export declare class RollbackPointEngine {
      * · 不是绝对路径。
      */
     private createdRemovalRefusal;
+    /**
+     * 把一条「留点之后被**别的会话**写过」的记录做成三方合并结果（2026-10-17 跨对话安全回退）。
+     *
+     * 三方：`ours` = 记录里的内容（回退目标）、`base` = 目标点之后**最早**那份中间版本、
+     * `theirs` = 当前磁盘。结果是「撤销本会话那次改动 + 保留对方后来的改动」。
+     *
+     * 返回：`write`（合并干净且确实要写，带目标哈希 + 期望的当前哈希）、
+     * `unchanged`（合并结果就是当前内容 —— 对方没动这一处，本来就不需要写）、
+     * `blocked`（不能安全处理：冲突 / 没有中间版本 / 二进制 / 差异被降级 / 对方改成了不存在 / 读不出）。
+     */
+    private mergeForeignRecord;
+    /**
+     * 三方合并的 **base**：目标点之后**最早**那份仍含该路径的中间版本（共同祖先）。
+     *
+     * 为什么这么取：回滚点的「工作区态」是回合开始前拍的 ⇒ 别的会话那个回合的点，
+     * 正好是「本会话改动之后、对方改动之前」的版本 —— 标准三方合并的共同祖先。
+     * 取**最早**而不是最近是刻意选安全方向：宁可少撤销，也绝不把对方更晚的改动算进 ours 侧。
+     *
+     * 排除四类：目标点自己（`createdAt > afterAt`）、**救援点 guard**（它在执行回退那一刻拍，
+     * 内容 ≈ 当前磁盘，拿它当 base 会让合并结果直接等于 ours = 整文件覆盖，正是本机制要消灭的形态）、
+     * **本会话的点**（见上）、以及内容读不出来的点（继续往后找 —— 找不到 ⇒ 调用方按「无法安全撤销」
+     * 处理，绝不用近似值代替）。
+     */
+    private baseVersionFor;
+    /**
+     * **别的会话的回合点里记录过的路径集合** —— 删除集保护的第二种证据（不依赖归属台账）。
+     *
+     * 为什么需要第二证据：归属可能整条缺失（工具不在白名单 / 另一个 DSH 进程把 attribution.json
+     * 整体覆盖写 / 采集时机错过），而「别人的点里出现过这个路径」是**点台账本身**记录的事实 ——
+     * 它足以证明「这条路径在留点之后被别的会话所在的回合捕获过」，因此删它就是销毁别人的工作。
+     *
+     * 有界：只扫目标点之后**最早**的 `limit` 个别的会话的点（按时间升序），且只读路径不读内容。
+     * 扫不完不影响安全方向（少保护也会被归属那条兜一部分），但绝不因此声称「已扫全」。
+     */
+    private foreignRecordedPaths;
     private restoreWorkspace;
     /**
      * S3：会话回退 = 在目标回合前的稳定边界 **fork 子会话**。
@@ -1493,6 +1601,11 @@ export interface RollbackTrackerOptions {
         size: number;
         mtimeMs: number;
     } | undefined>;
+    /**
+     * 写入归属采集器（2026-10-17 定案 B）。缺省 = 不采集 ⇒ 预览永远没有 foreign 标记，
+     * 回退行为与旧版**逐字一致**。
+     */
+    attribution?: RollbackWriteRecorder;
 }
 export interface RollbackTrackerResult {
     captured: boolean;
@@ -1554,6 +1667,7 @@ export declare class RollbackAutoTracker {
     private readonly pollIntervalMs;
     private readonly log;
     private readonly statSessionLog;
+    private readonly attribution;
     private readonly bindings;
     private readonly open;
     /**