claude-code-session-sync 0.1.0__py3-none-any.whl

claude_session_sync/session_merge.py

@@ -0,0 +1,214 @@
+"""session_merge：fork/superset 兩枝的**決定性、無損** union（H2/H3 + DESIGN A1/§6.6）。
+
+語意（PLAN v0.8 §2.4，N1：行級 union 非語意合併）：
+  1. 共同前綴 = 兩枝**依檔序逐行比 line-identity 到第一個 divergence**（uuid 行比 (uuid,hash)、
+     內容 no-uuid 比 content-hash）；揮發 meta（last-prompt/mode/title…）先濾掉、不參與也不保留。
+  2. 共同前綴輸出「一次」。
+  3. 各 branch 分歧段接在共同前綴後、依原序整段輸出：
+     - uuid 行：(uuid,hash) **去重**（跨整檔；同 uuid 異 hash 應已被 classify 擋成 damaged）；
+     - no-uuid 內容行（summary 等）：**不去重**——同段保留 multiplicity、跨段（A vs B）即使同 hash 也各留
+       （屬不同枝的摘要）。
+  4. chosen tip：使用者選或預設「**唯一**最新 timestamp 的 genuine leaf」；結尾 **append 一條新
+     `last-prompt{leafUuid=chosen}`**，不沿用任一輸入尾端（防裸 rewind 落後的 stale tip 被寫死，B2）。
+     chosen 必須是合併後存在的 genuine leaf；自動選只在「唯一最新」時成立，缺 ts / 並列最新 → needs-decision
+     （A11：不以裸/並列 timestamp 自動拍板），交人帶 chosen_tip 重呼。
+  5. 安全條件不成立（damaged / 零共同 uuid=collision / 多個非-system 根 / parent 環 / 無 leaf）
+     → **退回挑選**（FALLBACK；上層改走 keep-local/keep-hub/keep-both）。
+
+決定性 / commutative：兩枝分歧段以「分歧段 line-identity 序列」做 stable sort，故輸出**與 local/hub 標籤無關**；
+每行用 `canonical.canon_dumps` 序列化，故同一 line-identity 在任何機器都產生相同 bytes（跨機 union 收斂）。
+keep-both = 複製/落地時改檔名（檔名即身分，B6），不重寫內文 sessionId——由上層 atomicio 負責。
+
+純標準庫、無 IO。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .canonical import Line, canon_dumps
+from .lineset import VOLATILE_META_TYPES, SessionShape
+
+
+class MergeOutcome(str, Enum):
+    MERGED = "merged"                  # union 成功，objs 為合併後 JSONL 物件序列
+    FALLBACK = "fallback"              # 安全條件不成立 → 退回挑選（keep-local/keep-hub/keep-both）
+    NEEDS_DECISION = "needs-decision"  # chosen tip 非合併後 genuine leaf → 交人
+
+
+@dataclass
+class LeafCandidate:
+    """合併後可當 tip 的 genuine leaf（供互動呈現：時間/身分）。"""
+    uuid: str
+    ts: str | None
+
+
+@dataclass
+class MergeResult:
+    outcome: MergeOutcome
+    reason: str
+    objs: list[dict] | None = None          # MERGED 才有；含結尾新 last-prompt
+    chosen_tip: str | None = None
+    leaves: list[LeafCandidate] = field(default_factory=list)  # 可當 tip 的 genuine leaf（NEEDS_DECISION 時供互動挑選）
+
+
+def _is_content_line(ln: Line) -> bool:
+    """納入 union 的內容行：uuid 行一律算；no-uuid 只算**非揮發** meta（summary 等內容行）。
+
+    與 lineset._counts_for_compare 同準則——揮發 meta（last-prompt/mode/title…）不進 union，
+    結尾另 append 一條新 last-prompt。"""
+    return bool(ln.uuid) or (ln.type not in VOLATILE_META_TYPES)
+
+
+def _idkey(ln: Line) -> tuple[str, str]:
+    """可比較的 line-identity 鍵（避免 None 與 str 比較）。uuid 行=(uuid,hash)；no-uuid=("",hash)。"""
+    return (ln.uuid or "", ln.canon_hash or "")
+
+
+def _common_prefix_len(a: list[Line], b: list[Line]) -> int:
+    k = 0
+    while k < len(a) and k < len(b) and a[k].identity == b[k].identity:
+        k += 1
+    return k
+
+
+def _has_cycle(parent_map: dict[str, str | None]) -> bool:
+    """parent 鏈是否含環（沿 parentUuid 往上走重複造訪即環）。"""
+    for start in parent_map:
+        seen: set[str] = set()
+        cur: str | None = start
+        while cur is not None and cur in parent_map:
+            if cur in seen:
+                return True
+            seen.add(cur)
+            cur = parent_map[cur]
+    return False
+
+
+def merge_sessions(
+    local: SessionShape, hub: SessionShape, *, chosen_tip: str | None = None
+) -> MergeResult:
+    """union 兩個 SessionShape。回 MergeResult；不寫檔。"""
+    # ── (5) 安全前置：damaged / 零共同 uuid → 退回挑選 ──────────────────────────
+    if local.is_damaged or hub.is_damaged:
+        return MergeResult(MergeOutcome.FALLBACK, "至少一側 damaged，不可 union（退回挑選）")
+    if not local.uuids or not hub.uuids:
+        return MergeResult(MergeOutcome.FALLBACK, "至少一側無對話 uuid，無法 union（退回挑選）")
+    if not (local.uuids & hub.uuids):
+        return MergeResult(MergeOutcome.FALLBACK, "零共同 uuid（無共同祖先 / collision），不可 union（退回挑選）")
+
+    a = [ln for ln in local.lines if _is_content_line(ln)]
+    b = [ln for ln in hub.lines if _is_content_line(ln)]
+    k = _common_prefix_len(a, b)
+
+    # 兩枝分歧段以「分歧段 line-identity 序列」做 stable sort → 輸出與 local/hub 標籤無關（commutative）。
+    seg_a, seg_b = a[k:], b[k:]
+    first, first_seg, second_seg = (
+        (a, seg_a, seg_b)
+        if [_idkey(x) for x in seg_a] <= [_idkey(x) for x in seg_b]
+        else (b, seg_b, seg_a)
+    )
+
+    # ── (1)(2)(3) 共同前綴一次 + 兩分歧段保序；uuid 去重、no-uuid 不去重 ──────────
+    out: list[Line] = []
+    emitted_uuid_hash: dict[str, str | None] = {}  # uuid -> 已輸出的 hash（偵測衝突）
+
+    def _emit(ln: Line) -> bool:
+        if ln.uuid:
+            prev = emitted_uuid_hash.get(ln.uuid)
+            if prev is not None:
+                # 同 uuid 重複：同 hash → 安全去重（略過）；異 hash → 歷史行被改寫（damaged，本不該到這）
+                return prev == ln.canon_hash
+            emitted_uuid_hash[ln.uuid] = ln.canon_hash
+        out.append(ln)
+        return True
+
+    for ln in first[:k]:           # 共同前綴（取 canonically-first 那側，bytes 一致）
+        _emit(ln)
+    for ln in first_seg:           # 先輸出的分歧段
+        if not _emit(ln):
+            return MergeResult(MergeOutcome.FALLBACK, f"同 uuid 異 hash（{ln.uuid[:8]} 歷史行被改寫），不可 union")
+    for ln in second_seg:          # 後輸出的分歧段
+        if not _emit(ln):
+            return MergeResult(MergeOutcome.FALLBACK, f"同 uuid 異 hash（{ln.uuid[:8]} 歷史行被改寫），不可 union")
+
+    # ── (5) 合併後結構檢查：多非-system 根 / parent 環 → 退回挑選 ───────────────
+    merged_uuids = {ln.uuid for ln in out if ln.uuid}
+    parent_map = {ln.uuid: ln.parent for ln in out if ln.uuid}
+    if _has_cycle(parent_map):
+        return MergeResult(MergeOutcome.FALLBACK, "合併後 parent 鏈成環（不可解），退回挑選")
+    nonsystem_roots = [
+        ln for ln in out
+        if ln.uuid and (ln.parent is None or ln.parent not in merged_uuids) and ln.type != "system"
+    ]
+    if len(nonsystem_roots) > 1:
+        return MergeResult(
+            MergeOutcome.FALLBACK,
+            "合併後出現多個非-system 對話根（疑似併入不相關對話），退回挑選",
+        )
+
+    # genuine leaves = 未被任何行當 parent、非 sidechain、非工具 fan-out 的 uuid 行。
+    used_as_parent = {ln.parent for ln in out if ln.parent}
+    leaf_lines = [
+        ln for ln in out
+        if ln.uuid and ln.uuid not in used_as_parent and not ln.is_sidechain and not ln.is_tool_fanout
+    ]
+    if not leaf_lines:
+        return MergeResult(MergeOutcome.FALLBACK, "合併後無 genuine leaf，退回挑選")
+    leaves = [LeafCandidate(ln.uuid, ln.ts) for ln in leaf_lines]
+    leaf_uuids = {ln.uuid for ln in leaf_lines}
+
+    # ── (4) chosen tip：使用者選或預設最新；append 新 last-prompt ─────────────────
+    # 自動只在「唯一最新」時拍板；缺 ts / 並列最新 → needs-decision（A11：不以裸/並列 timestamp 自動選；
+    # 防裸 rewind 落後或無法比較時被寫死錯 tip，B2）。上層互動再帶 chosen_tip 重呼。
+    if chosen_tip is not None:
+        if chosen_tip not in leaf_uuids:
+            return MergeResult(
+                MergeOutcome.NEEDS_DECISION,
+                f"指定 tip {chosen_tip[:8]} 非合併後 genuine leaf（交人決策）",
+                leaves=leaves,
+            )
+        chosen = chosen_tip
+    else:
+        if any(ln.ts is None for ln in leaf_lines):
+            return MergeResult(
+                MergeOutcome.NEEDS_DECISION,
+                "部分 genuine leaf 缺 timestamp，無法自動選 tip（交人挑選）",
+                leaves=leaves,
+            )
+        newest_ts = max(ln.ts for ln in leaf_lines)
+        newest = [ln for ln in leaf_lines if ln.ts == newest_ts]
+        if len(newest) != 1:
+            return MergeResult(
+                MergeOutcome.NEEDS_DECISION,
+                "多個 genuine leaf 並列最新 timestamp，無法自動選 tip（交人挑選）",
+                leaves=leaves,
+            )
+        chosen = newest[0].uuid
+
+    objs = [ln.obj for ln in out if ln.obj is not None]
+    sid = None
+    for ln in leaf_lines:
+        if ln.uuid == chosen and isinstance(ln.obj, dict):
+            sid = ln.obj.get("sessionId")
+            break
+    tip_obj: dict = {"type": "last-prompt", "leafUuid": chosen}
+    if sid is not None:
+        tip_obj["sessionId"] = sid
+    objs.append(tip_obj)
+
+    return MergeResult(
+        MergeOutcome.MERGED,
+        "union 成功（共同前綴去重一次 + 兩分歧段保序 + 新 last-prompt 標 tip）",
+        objs=objs,
+        chosen_tip=chosen,
+        leaves=leaves,
+    )
+
+
+def render_jsonl(objs: list[dict]) -> bytes:
+    """把 union 後物件序列序列化成 canonical JSONL bytes（每行 canon_dumps + LF）。
+
+    canonical 序列化 → 同一 line-identity 跨機 bytes 一致；落地用 atomicio.atomic_create_bytes
+    寫到 keep_both_path（不覆蓋既有 local JSONL，C3）。"""
+    return ("".join(canon_dumps(o) + "\n" for o in objs)).encode("utf-8")

claude_session_sync/sidecar.py

@@ -0,0 +1,238 @@
+"""Sidecar：專案同一性（git 指紋優先）與 session meta（A4 hashes）。
+
+依據 DESIGN §8.2/§8.3 + 附錄 A4 + PLAN v0.4 §2.5：
+  - 跨機同一性**優先 git remote / repo fingerprint**；cwd 字串永不單獨自動落地（決定 #7）。
+  - 「無法判斷」與「同一 repo」嚴格分開：判不出一律 NEEDS_MAP，不猜。
+  - 降級：no-git → NEEDS_MAP；同 first-commit 不同 remote（fork/rename）→ AMBIGUOUS（要人確認）。
+
+P1a 只做**讀 + 比對 + 計算**（不寫 sidecar；寫入是 P1b）。純標準庫（git 走 subprocess）。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+import urllib.parse
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from .lineset import analyze
+
+SCHEMA_VERSION = 1
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+_DEFAULT_PORTS = {"ssh": 22, "git": 9418, "http": 80, "https": 443}
+
+
+# ── git remote 正規化 ────────────────────────────────────────────────────
+
+def normalize_remote(url: str | None) -> str | None:
+    """把各種 remote URL 形式正規化成 `host[:port]/path`（小寫、去 .git、去認證/scheme）。
+    **保留非預設 port**（同 host/path 不同 port = 不同伺服器，不可當同專案）。IPv6/query 走 urllib。"""
+    u = (url or "").strip()
+    if not u:
+        return None
+    u = re.sub(r"\.git/?$", "", u)
+    if "://" not in u:
+        # scp-like: user@host:owner/repo（無 scheme）
+        m = re.match(r"^[\w.+-]+@([^:/]+):(.+)$", u)
+        if m:
+            return f"{m.group(1).lower()}/{m.group(2).strip('/').lower()}"
+        return u.lower()  # 本地路徑/未知形式
+    try:
+        parsed = urllib.parse.urlparse(u)
+        host = (parsed.hostname or "").lower()
+        port = parsed.port
+    except ValueError:
+        return u.lower()
+    if not host:
+        return u.lower()
+    if port is not None and port != _DEFAULT_PORTS.get(parsed.scheme):
+        host = f"{host}:{port}"
+    path = parsed.path.strip("/").lower()
+    return f"{host}/{path}" if path else host
+
+
+def _git(cwd: str | Path, *args: str) -> str | None:
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True, text=True, timeout=10,
+        )
+    except Exception:  # noqa: BLE001 - git 不存在/逾時都當無 git
+        return None
+    if r.returncode != 0:
+        return None
+    return r.stdout.strip()
+
+
+# ── 專案指紋 ─────────────────────────────────────────────────────────────
+
+@dataclass
+class ProjectFingerprint:
+    cwd: str
+    repo_root: str | None
+    remotes: dict[str, str]          # name -> normalized remote
+    first_commit: str | None
+    has_git: bool
+
+    @property
+    def remote_set(self) -> set[str]:
+        return set(self.remotes.values())
+
+
+def local_fingerprint(cwd: str | Path) -> ProjectFingerprint:
+    root = _git(cwd, "rev-parse", "--show-toplevel")
+    remotes: dict[str, str] = {}
+    first: str | None = None
+    if root:
+        for name in (_git(cwd, "remote") or "").split():
+            norm = normalize_remote(_git(cwd, "remote", "get-url", name))
+            if norm:
+                remotes[name] = norm
+        roots = _git(cwd, "rev-list", "--max-parents=0", "--all") or ""
+        first = sorted(roots.split())[0] if roots.split() else None
+    return ProjectFingerprint(str(cwd), root, remotes, first, has_git=bool(root))
+
+
+# ── _project.json（hub 端專案 sidecar）────────────────────────────────────
+
+@dataclass
+class ProjectSidecar:
+    git_remote: str | None = None        # 正規化（primary）
+    first_commit: str | None = None
+    repo_root: str | None = None
+    observed_cwds: list[str] = field(default_factory=list)
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "git_remote": self.git_remote,
+            "first_commit": self.first_commit,
+            "repo_root": self.repo_root,
+            "observed_cwds": self.observed_cwds,
+        }
+
+
+def read_project_sidecar(project_dir: str | Path) -> ProjectSidecar | None:
+    p = Path(project_dir) / "_project.json"
+    if not p.exists() or p.is_symlink():   # leaf 防線：symlink _project.json → 不跟隨讀界外身分（treat as absent，e2e）
+        return None
+    try:
+        d = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+    if not isinstance(d, dict):
+        return None
+    gr, fc, rr = d.get("git_remote"), d.get("first_commit"), d.get("repo_root")
+    if not all(x is None or isinstance(x, str) for x in (gr, fc, rr)):
+        return None  # 壞 sidecar → blocked，不可扭曲身分
+    cwds = d.get("observed_cwds", [])
+    if not isinstance(cwds, list) or not all(isinstance(x, str) for x in cwds):
+        return None
+    sv = d.get("schema_version", SCHEMA_VERSION)
+    if not isinstance(sv, int) or isinstance(sv, bool):
+        return None
+    return ProjectSidecar(git_remote=gr, first_commit=fc, repo_root=rr,
+                          observed_cwds=list(cwds), schema_version=sv)
+
+
+# ── 同一性比對 ───────────────────────────────────────────────────────────
+
+class MatchStatus(str, Enum):
+    MATCH = "match"
+    NO_MATCH = "no-match"
+    AMBIGUOUS = "ambiguous"       # 同 lineage 不同 remote（fork/rename）→ 要人確認
+    NEEDS_MAP = "needs-map"       # 缺 git 身分 → 不可自動，要 --map
+
+
+@dataclass
+class MatchResult:
+    status: MatchStatus
+    reason: str
+
+
+def match(local: ProjectFingerprint, sc: ProjectSidecar) -> MatchResult:
+    """本機專案指紋 vs hub _project.json。git 指紋優先；判不出一律 NEEDS_MAP，不靠 cwd 猜。"""
+    if not local.has_git or not sc.git_remote:
+        return MatchResult(MatchStatus.NEEDS_MAP, "缺 git remote 身分，需 --map 人工對應")
+    if sc.git_remote in local.remote_set:
+        return MatchResult(MatchStatus.MATCH, f"git remote 相符：{sc.git_remote}")
+    if sc.first_commit and local.first_commit and sc.first_commit == local.first_commit:
+        return MatchResult(MatchStatus.AMBIGUOUS, "first-commit 相同但 remote 不同（fork/rename）→ 要確認")
+    return MatchResult(MatchStatus.NO_MATCH, "remote 與 first-commit 皆不符")
+
+
+# ── session meta（A4 hashes；P1a 計算 + 讀）──────────────────────────────
+
+@dataclass
+class SessionMeta:
+    content_hash: str            # 全檔 ordered canonical content digest
+    tail_hash: str               # 末段 digest（快速偵測截斷/延伸）
+    line_count: int
+    uuid_count: int
+    non_uuid_count: int
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "content_hash": self.content_hash,
+            "tail_hash": self.tail_hash,
+            "line_count": self.line_count,
+            "uuid_count": self.uuid_count,
+            "non_uuid_count": self.non_uuid_count,
+        }
+
+
+def _sha(parts: list[str]) -> str:
+    h = hashlib.sha256()
+    for p in parts:
+        h.update(p.encode("utf-8"))
+        h.update(b"\n")
+    return h.hexdigest()
+
+
+def compute_session_meta(path: str | Path, tail: int = 20) -> SessionMeta | None:
+    """從一個 jsonl 算 A4 meta。**任何 damaged 都回 None**：檔級(zero/blank/decode)、壞 JSON 行、
+    或同檔同 uuid 異 hash —— meta 不得替 damaged 檔背書（codex r5 critical）。"""
+    shape = analyze(str(path))
+    if shape.is_damaged:
+        return None
+    ok = shape.lines
+    hashes = [ln.canon_hash or "" for ln in ok]
+    uuid_count = sum(1 for ln in ok if ln.uuid)
+    return SessionMeta(
+        content_hash=_sha(hashes),
+        tail_hash=_sha(hashes[-tail:]),
+        line_count=len(ok),
+        uuid_count=uuid_count,
+        non_uuid_count=len(ok) - uuid_count,
+    )
+
+
+def read_session_meta(meta_path: str | Path) -> SessionMeta | None:
+    p = Path(meta_path)
+    if not p.exists():
+        return None
+    try:
+        d = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+    if not isinstance(d, dict):
+        return None
+    ch, th = d.get("content_hash"), d.get("tail_hash")
+    if not (isinstance(ch, str) and _HEX64.match(ch) and isinstance(th, str) and _HEX64.match(th)):
+        return None
+    counts: dict[str, int] = {}
+    for key in ("line_count", "uuid_count", "non_uuid_count"):
+        v = d.get(key)
+        if not isinstance(v, int) or isinstance(v, bool) or v < 0:  # bool 是 int 子類，須排除
+            return None
+        counts[key] = v
+    sv = d.get("schema_version", SCHEMA_VERSION)
+    if not isinstance(sv, int) or isinstance(sv, bool):
+        return None
+    return SessionMeta(content_hash=ch, tail_hash=th, schema_version=sv, **counts)

claude_session_sync/snapshot.py

@@ -0,0 +1,136 @@
+"""決策快照子集（C4）：plan 時擷取、apply 取鎖後重算比對；不一致即「決策已過期」→ 中止。
+
+依據 PLAN v0.8 §2.8（codex r3/r4 C4）+ §3 資料流第 6/7 步。一個 per-session 子集，涵蓋這個分類決策
+**所依賴的全部輸入**：兩側資料檔 + 各自 meta sidecar + 該 hub 專案 `_project.json` + config（own_hub/
+remotes/force_unsafe_lock）+ 該 hub 專案 **tombstone 目錄 digest（含 `_coverage.json`）** + **該 session
+在 state 的單一條目 hash**（不是整個 state，避免 per-session commit 自我失效）。
+
+「hub/project fingerprint + known-session set + coverage」屬 **anomaly 重跑**（見 anomaly.py），與本
+per-session 子集分開：本子集放整個 known-set 會被自己的逐 session commit 連動而誤判過期。
+
+codex r8 兩個 critical 防護：
+  ① 接 **專案夾 + sid**（非可為 None 的具體路徑）自行推導 `<sid>.jsonl`/`<sid>.meta.json`——否則 plan
+     時 None 代表「這側沒檔」，apply 時還是 None，即使期間檔被建出來也偵測不到 → 覆蓋掉新檔。
+  ② `_file_digest` **永不回 None**：以 absent/sha/err/nonreg 區分「不存在」與「存在但讀不到/非一般檔」，
+     否則兩者都 None 會被當「沒變」而覆蓋未檢視過的資料。
+
+純標準庫；不寫檔。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat as statmod
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import tombstone
+from .config import Config
+from .state import State
+
+META_SUFFIX = ".meta.json"
+
+
+def _file_digest(path: Path | None) -> str:
+    """檔狀態指紋，永不回 None。先 stat（不開 FIFO 以免阻塞），只對一般檔讀內容算 sha256：
+      - absent          ：不存在
+      - sha:<hex>       ：一般檔內容
+      - nonreg:<ifmt>   ：存在但非一般檔（目錄/FIFO/symlink-to-dir…）
+      - err:<errno>     ：存在但讀不到（權限/IO）
+    四類彼此可辨，確保「plan 時沒檔、apply 時冒出檔（或變不可讀）」一定改變快照。
+    """
+    if path is None:
+        return "absent"
+    try:
+        st = os.lstat(path)  # **no-follow**（e2e gate4 #2）：symlink leaf → S_ISLNK → 下方 nonreg（不 open 讀界外目標）；
+        #                       一般檔 lstat==stat、行為不變。變動偵測仍有效（symlink swap → nonreg vs sha 改變 → 快照失效）。
+    except FileNotFoundError:
+        return "absent"
+    except OSError as e:
+        return f"err:{e.errno}"
+    if not statmod.S_ISREG(st.st_mode):
+        return f"nonreg:{statmod.S_IFMT(st.st_mode)}"   # symlink → S_ISLNK → 非 S_ISREG → 不 open 讀界外（e2e gate4 #2）
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+    except OSError as e:
+        return f"err:{e.errno}"
+    return "sha:" + hashlib.sha256(data).hexdigest()
+
+
+def config_hash(config: Config) -> str:
+    """只納入會左右落地決策的欄位：own_hub / remotes / force_unsafe_lock（map=bindings 在 state 條目）。"""
+    payload = {
+        "own_hub": config.own_hub,
+        "remotes": dict(sorted(config.remotes.items())),
+        "force_unsafe_lock": config.force_unsafe_lock,
+    }
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def state_entry_hash(state: State | None, project_key: str | None, sid: str, cwd: str | None,
+                     local_dir_name: str | None = None) -> str:
+    """**單一 session** 在 state 的條目指紋：是否已知（hub / local 基線）+ 該 cwd 的跨路徑綁定。
+
+    刻意只取**本 sid 的成員性**、不納入整個集合——否則 apply 迴圈中對**其他** session 的 per-session
+    commit 會改動集合、使本 session 的快照誤判過期（PLAN §2.8 明列的自我失效陷阱）。新增其他 sid 不改變
+    「本 sid 是否在集合內」，故此 hash 在我方 additive commit 下穩定。`local_known` 與 `known` 對稱納入
+    （供 local-deleted/copy-to-local 決策；local_sessions[pk] 的 baseline 取代只在專案末發生、不影響本 sid
+    成員性於迴圈內的穩定性，P1c）。"""
+    known = bool(state and project_key is not None and sid in state.known_sessions.get(project_key, set()))
+    local_known = bool(state and project_key is not None and sid in state.local_sessions.get(project_key, set()))
+    binding = state.bindings.get(cwd) if (state and cwd is not None) else None
+    # 夾名綁定也納入：空夾（cwd=None）的身分解析改靠 local_dir_bindings，故其變動（並發 remap）須能令快照失效，
+    # 與 cwd-binding 對稱（codex r26-2）。
+    dir_binding = state.local_dir_bindings.get(local_dir_name) if (state and local_dir_name is not None) else None
+    payload = {"pk": project_key, "sid": sid, "known": known, "local_known": local_known,
+               "binding": binding, "dir_binding": dir_binding}
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class DecisionSnapshot:
+    session_id: str
+    local_data: str
+    hub_data: str
+    local_meta: str
+    hub_meta: str
+    project_sidecar: str
+    config_hash: str
+    tomb_dir_digest: str
+    state_entry: str
+
+
+def compute_decision_snapshot(
+    *,
+    session_id: str,
+    local_project_dir: Path | None,
+    hub_project_dir: Path | None,
+    config: Config,
+    state: State | None,
+    project_key: str | None,
+    cwd: str | None,
+) -> DecisionSnapshot:
+    """擷取/重算一個 session 的決策快照子集。plan 與 apply 各呼叫一次（傳同樣的專案夾），相等才可落地。
+
+    傳**專案夾**而非具體檔路徑：本函式自行推導 `<sid>.jsonl`/`<sid>.meta.json`，使「期間冒出/消失/變不可讀」
+    都能在 apply 重算時被偵測（codex r8 critical①）。某側無對應專案夾（未綁定）→ 該側恆 absent。
+    """
+    def in_dir(d: Path | None, name: str) -> Path | None:
+        return (d / name) if d is not None else None
+
+    sidecar_path = in_dir(hub_project_dir, "_project.json")
+    tomb_digest = tombstone.tombstone_dir_digest(hub_project_dir) if hub_project_dir else ""
+    return DecisionSnapshot(
+        session_id=session_id,
+        local_data=_file_digest(in_dir(local_project_dir, f"{session_id}.jsonl")),
+        hub_data=_file_digest(in_dir(hub_project_dir, f"{session_id}.jsonl")),
+        local_meta=_file_digest(in_dir(local_project_dir, f"{session_id}{META_SUFFIX}")),
+        hub_meta=_file_digest(in_dir(hub_project_dir, f"{session_id}{META_SUFFIX}")),
+        project_sidecar=_file_digest(sidecar_path),
+        config_hash=config_hash(config),
+        tomb_dir_digest=tomb_digest,
+        state_entry=state_entry_hash(state, project_key, session_id, cwd,
+                                     local_project_dir.name if local_project_dir is not None else None),
+    )