dsh-config-manager 0.1.76 → 0.1.77

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;
     /**