gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/worktree_snapshot.py

@@ -0,0 +1,630 @@
+"""Hold the coherent state of a worktree, parsed from Git's status, checked against local file fingerprints."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import stat
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from gitpane.config import PROCESS_CHUNK_BYTES, READ_SIZE_SENTINEL_BYTES, WORKTREE_FILE_WORKER_COUNT, WORKTREE_INDEX_LIMIT_BYTES
+from gitpane.history.repository_value import FileStatus, file_status
+from gitpane.system.path_identity import canonical_path
+from gitpane.tool.system_tool import worktree_filename
+from gitpane.worktree.command_sequence import FileTask, ReadBatch
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from typing import BinaryIO
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.sequencer.merge_state import MergeBannerState
+
+
+@dataclass(frozen=True)
+class WorktreeKey:
+    """Keep linked worktrees independent by using their own canonical Git directory."""
+
+    git_dir: str
+
+    @classmethod
+    def from_context(cls, context: RepositoryContext) -> WorktreeKey:
+        """Normalize filesystem aliases without merging the common object directory."""
+        return cls(canonical_path(context.git_dir))
+
+
+CONFLICT_ROLE_BY_STAGE = {1: "BASE", 2: "LOCAL", 3: "REMOTE"}
+CONFLICT_ROLE_SET_BY_STATUS = {
+    b"DD": frozenset(("BASE",)), b"AU": frozenset(("LOCAL",)), b"UA": frozenset(("REMOTE",)),
+    b"UD": frozenset(("BASE", "LOCAL")), b"DU": frozenset(("BASE", "REMOTE")),
+    b"AA": frozenset(("LOCAL", "REMOTE")), b"UU": frozenset(CONFLICT_ROLE_BY_STAGE.values()),
+}
+INDEX_MODE_SET = frozenset(("100644", "100755", "120000", "160000", "040000"))
+
+
+STATUS_HEADER_PREFIX = b"# "
+STATUS_BRANCH_OID_PREFIX = b"# branch.oid "
+STATUS_BRANCH_HEAD_PREFIX = b"# branch.head "
+STATUS_UNMERGED_PREFIX = b"u "
+# An unmerged status record holds ten spaces before its path, which may itself contain spaces.
+STATUS_UNMERGED_SEPARATOR_COUNT = 10
+STATUS_RENAMED_PREFIX = b"2 "
+STATUS_ORDINARY_PREFIX = b"1 "
+STATUS_UNTRACKED_PREFIX = b"? "
+# Letter of the XY column of a porcelain v2 record for the side (index or work tree) that did not change.
+STATUS_UNCHANGED_LETTER = "."
+STATUS_INITIAL_OID = b"(initial)"
+STATUS_DETACHED_HEAD = b"(detached)"
+STATUS_UNKNOWN_HEAD = b"(NULL)"
+SUBMODULE_DIRTY_DESCRIPTION = "These changes are inside the submodule and are not included in the parent commit."
+SUBMODULE_NO_COMMIT_CHANGE = "There is no commit change to stage. Commit internal changes inside the submodule first."
+
+
+@dataclass(frozen=True)
+class SubmoduleState:
+    """Distinguish gitlink movement from tracked and untracked child changes."""
+
+    commit_changed: bool | None = None
+    tracked_changed: bool | None = None
+    untracked_changed: bool | None = None
+
+    @property
+    def dirty(self) -> bool | None:
+        """Keep incomplete status unknown without hiding a known internal change."""
+        if self.tracked_changed or self.untracked_changed:
+            return True
+        if self.tracked_changed is None or self.untracked_changed is None:
+            return None
+        return False
+
+    @classmethod
+    def parse(cls, value: bytes) -> SubmoduleState:
+        """Decode native porcelain flags while preserving unsupported values as unknown."""
+        if value == b"N...":
+            return cls(False, False, False)
+        if len(value) != len(b"S...") or not value.startswith(b"S"):
+            return cls()
+        flags = []
+        for actual, changed in zip(value.removeprefix(b"S"), b"CMU", strict=True):
+            flags.append(True if actual == changed else False if actual == ord(".") else None)
+        return cls(*flags)
+
+
+@dataclass(frozen=True)
+class ConflictSide:
+    """Identify one version actually present in the unmerged index."""
+
+    stage: int
+    mode: str
+    oid: str
+
+    def __post_init__(self) -> None:
+        """Reject invalid object identities before any consumer can use a side."""
+        if (self.stage not in CONFLICT_ROLE_BY_STAGE or self.mode not in INDEX_MODE_SET or self.mode == "040000"
+                or not re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", self.oid) or not self.oid.strip("0")):
+            raise ValueError("Malformed unmerged index side")
+
+
+class StagingSide(Enum):
+    """The side of the staging window a changed file is listed on: staged in the index, or unstaged in the working tree.
+
+    The value is the word written under "side" in a reset's recovery record; ``label`` is the word inside a sentence
+    and ``title`` the word that starts a title.
+    """
+
+    STAGED = ("staged", "staged", "Staged")
+    UNSTAGED = ("unstaged", "unstaged", "Unstaged")
+
+    def __new__(cls, value: str, label: str, title: str) -> Self:
+        """Keep the recorded word as the value, with the sentence and title words beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        member.title = title
+        return member
+
+
+@dataclass(frozen=True)
+class LocalEntry:
+    """Retain original Git paths and object identities independently of labels."""
+
+    side: StagingSide
+    old_path: bytes | None
+    new_path: bytes | None
+    status: FileStatus
+    old_mode: str = "000000"
+    new_mode: str = "000000"
+    old_blob_oid: str | None = None
+    new_blob_oid: str | None = None
+    conflict_stages: tuple[int, ...] = ()
+    skip_worktree: bool = False
+    conflict_sides: tuple[ConflictSide, ...] = ()
+    conflict_binary: bool | None = None
+    submodule: SubmoduleState = SubmoduleState()
+
+    @property
+    def is_gitlink(self) -> bool:
+        """Recognize child repositories on either side of additions and deletions."""
+        return "160000" in (self.old_mode, self.new_mode)
+
+    @property
+    def stageable(self) -> bool:
+        """Allow real reference changes without staging internal-only child edits."""
+        return not self.is_gitlink or self.status in (FileStatus.ADDED, FileStatus.DELETED) or self.old_mode != self.new_mode or self.submodule.commit_changed is True
+
+    @property
+    def path(self) -> bytes:
+        """Choose the current identity, retaining a deleted path when necessary."""
+        return self.new_path if self.new_path is not None else self.old_path or b""
+
+    @property
+    def paths(self) -> tuple[bytes, ...]:
+        """Include both ends of a rename for a complete index operation."""
+        return tuple(dict.fromkeys(path for path in (self.old_path, self.new_path) if path is not None))
+
+    @property
+    def label(self) -> str:
+        """Decode paths for display and distinguish parent gitlinks from internal child files."""
+        label = self.path.decode("utf-8", "replace")
+        if self.status == FileStatus.RENAMED and self.old_path is not None:
+            label += " (" + self.old_path.decode("utf-8", "replace") + ")"
+        if self.is_gitlink:
+            if self.side == StagingSide.STAGED or self.stageable:
+                label += " — Submodule commit"
+                if self.side == StagingSide.UNSTAGED and self.submodule.dirty:
+                    label += " + internal changes"
+            elif self.submodule.dirty:
+                label += " — Internal changes only"
+        return label
+
+
+@dataclass(frozen=True)
+class WorktreeProbe:
+    """The facts of a single status that say whether the displayed state still holds.
+
+    A hint for the views, never a proof a write can rely on.
+    """
+
+    head_oid: str | None
+    branch_head: str | None
+    unmerged_records: tuple[bytes, ...]
+    entry_fingerprint: str
+
+
+def unmerged_record_path(record: bytes) -> bytes:
+    """Answer the path of one unmerged status record, exactly as Git wrote it."""
+    if not record.startswith(STATUS_UNMERGED_PREFIX):
+        raise ValueError("Malformed unmerged status record")
+    fields = record.split(b" ", STATUS_UNMERGED_SEPARATOR_COUNT)
+    # Each separator ends one field, and the path is the field after the last one.
+    if len(fields) != STATUS_UNMERGED_SEPARATOR_COUNT + 1:
+        raise ValueError("Malformed unmerged status record")
+    path = fields[STATUS_UNMERGED_SEPARATOR_COUNT]
+    if not path:
+        raise ValueError("Malformed unmerged status record")
+    return path
+
+
+@dataclass(frozen=True)
+class PassiveObservationSource:
+    """What the automatic refresh already has in hand when the banner follows a pause: the status facts and the pause paths.
+
+    It lets that display skip reading them again through Git; it is never a proof a write can rely on.
+    """
+
+    head_oid: str | None
+    branch_head: str | None
+    unmerged_paths: tuple[bytes, ...]
+    filename_by_git_path: dict[str, str]
+
+
+def passive_observation_source(worktree_probe: WorktreeProbe, filename_by_git_path: dict[str, str]) -> PassiveObservationSource:
+    """Gather the facts of one status and the pause paths of its session for the observation that follows the pause."""
+    path_set = set()
+    for record in worktree_probe.unmerged_records:
+        path_set.add(unmerged_record_path(record))
+    return PassiveObservationSource(worktree_probe.head_oid, worktree_probe.branch_head, tuple(sorted(path_set)), dict(filename_by_git_path))
+
+
+class WorktreeColorState(Enum):
+    """What the Commit icon says about the worktree: which sides hold changes, or unknown before any fresh read."""
+
+    UNKNOWN = "unknown"
+    MIXED = "mixed"
+    STAGED = "staged"
+    UNSTAGED = "unstaged"
+    CLEAN = "clean"
+
+
+@dataclass(frozen=True)
+class WorktreeSnapshot:
+    """Capture a complete read, including exact index absence and conversion settings."""
+
+    key: WorktreeKey
+    context: RepositoryContext
+    generation: int
+    git_filename: str
+    head_oid: str | None
+    index_filename: str
+    index_content: bytes | None
+    entries: tuple[LocalEntry, ...]
+    fingerprint_by_path: dict[bytes, str]
+    conversion: bytes
+    fresh: bool = True
+    diagnostic: PreparedDiagnostic | None = None
+    index_entries: bytes | None = None
+    hooks_dir: str | None = None
+    hidden_index_paths: tuple[bytes, ...] = ()
+    skip_worktree_paths: tuple[bytes, ...] = ()
+    probe: WorktreeProbe | None = None
+    # The merge state read from Git's files right after this capture, for the repository window's banner; None when the
+    # capture did not read it, as the captures made for a write do not. It is left out of the comparison of two
+    # snapshots: the session that shows them tracks the merge state on its own, and a changed merge alone does not
+    # change the files shown.
+    merge_banner_state: MergeBannerState | None = field(default=None, compare=False)
+
+    @property
+    def index_fingerprint(self) -> str:
+        """Distinguish an absent index from every existing byte representation."""
+        return fingerprint(self.index_content)
+
+    @property
+    def count(self) -> int:
+        """Count grouped staged renames once and deduplicate a path on both sides."""
+        return len({entry.path for entry in self.entries})
+
+    def color_state(self) -> WorktreeColorState:
+        """Distinguish staged and unstaged changes without letting a message alter repository status."""
+        if not self.fresh:
+            return WorktreeColorState.UNKNOWN
+        side_set = {entry.side for entry in self.entries}
+        if StagingSide.STAGED in side_set and StagingSide.UNSTAGED in side_set:
+            return WorktreeColorState.MIXED
+        if StagingSide.STAGED in side_set:
+            return WorktreeColorState.STAGED
+        return WorktreeColorState.UNSTAGED if side_set else WorktreeColorState.CLEAN
+
+    def requires_file_confirmation(self, paths: tuple[bytes, ...]) -> bool:
+        """Confirm destructive file actions when a target is an addition on either side."""
+        path_set = set(paths)
+        return any(entry.status == FileStatus.ADDED and entry.path in path_set for entry in self.entries)
+
+
+def local_history_path(snapshot: WorktreeSnapshot, entry: LocalEntry) -> bytes | None:
+    """Find a possible HEAD name without pretending an index-only addition has history."""
+    if snapshot.head_oid is None or entry not in snapshot.entries or entry.side != StagingSide.UNSTAGED:
+        return None
+    for staged in snapshot.entries:
+        if staged.side != StagingSide.STAGED or staged.path != entry.path:
+            continue
+        if staged.status == FileStatus.RENAMED:
+            return staged.old_path
+        if staged.status == FileStatus.ADDED:
+            return None
+        if staged.status == FileStatus.DELETED:
+            return staged.old_path
+    return entry.old_path
+
+
+def fingerprint(content: bytes | None) -> str:
+    """Hash exact bytes while keeping absence explicit."""
+    return "absent" if content is None else hashlib.sha256(content).hexdigest()
+
+
+def read_validated_size(stream: BinaryIO, validated_size: int) -> bytes:
+    """Read a small file whose size was just validated on its open descriptor, asking for that size and one byte more.
+
+    A read sized on the largest file accepted makes the interpreter reserve that whole buffer even for a few bytes.
+    The extra byte is how growth shows: the caller refuses every length other than the validated size, so a file that
+    grew or shrank meanwhile never passes for complete content.
+    """
+    return stream.read(validated_size + READ_SIZE_SENTINEL_BYTES)
+
+
+def read_index(index_filename: str) -> bytes | None:
+    """Read a bounded index without confusing a missing file with an empty one."""
+    try:
+        if not stat.S_ISREG(os.lstat(index_filename).st_mode):
+            raise ValueError("The Git index is not a regular file")
+        # A read sized to the safety limit allocates the maximum even for a small index.
+        # Chunked reads retain the same limit without paying that cost on every check.
+        content = bytearray()
+        with open(index_filename, "rb") as stream:
+            while chunk := stream.read(PROCESS_CHUNK_BYTES):
+                content.extend(chunk)
+                if len(content) > WORKTREE_INDEX_LIMIT_BYTES:
+                    raise ValueError("The Git index exceeds the supported read limit")
+        return bytes(content)
+    except FileNotFoundError:
+        return None
+
+
+def _validate_fingerprint_parent(context: RepositoryContext, filename: str, metadata_by_dir: dict[str, os.stat_result | None]) -> None:
+    """Check each ancestor once per batch and retain its identity for the closing check."""
+    parent_dir = os.path.dirname(filename)
+    while os.path.normcase(parent_dir) != os.path.normcase(os.path.abspath(context.worktree_dir)):
+        if parent_dir in metadata_by_dir:
+            return
+        try:
+            metadata = os.lstat(parent_dir)
+        except FileNotFoundError:
+            metadata = None
+        if metadata is not None and (stat.S_ISLNK(metadata.st_mode) or getattr(metadata, "st_reparse_tag", None) == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", -1)):
+            raise ValueError("A selected path traverses a linked directory")
+        metadata_by_dir[parent_dir] = metadata
+        ancestor_dir = os.path.dirname(parent_dir)
+        if ancestor_dir == parent_dir:
+            raise ValueError("A selected path is outside the working tree")
+        parent_dir = ancestor_dir
+
+
+def _fingerprint_filename(filename: str) -> str:
+    """Hash one validated file's bytes and mode without following a final symlink."""
+    try:
+        metadata = os.lstat(filename)
+    except FileNotFoundError:
+        return "absent"
+    mode = str(stat.S_IFMT(metadata.st_mode)) + ":" + str(stat.S_IMODE(metadata.st_mode))
+    if stat.S_ISLNK(metadata.st_mode):
+        return mode + ":" + fingerprint(os.fsencode(os.readlink(filename)))
+    if stat.S_ISDIR(metadata.st_mode):
+        return mode
+    if not stat.S_ISREG(metadata.st_mode):
+        raise ValueError("Unsupported working file type")
+    digest = hashlib.sha256()
+    with open(filename, "rb") as stream:
+        while chunk := stream.read(PROCESS_CHUNK_BYTES):
+            digest.update(chunk)
+    return mode + ":" + digest.hexdigest()
+
+
+def file_fingerprint(context: RepositoryContext, path: bytes) -> str:
+    """Hash working bytes and mode without following symlinks or walking submodules."""
+    filename = worktree_filename(context, path)
+    _validate_fingerprint_parent(context, filename, {})
+    return _fingerprint_filename(filename)
+
+
+def fingerprint_files(context: RepositoryContext, paths: tuple[bytes, ...]) -> dict[bytes, str]:
+    """Hash exact bytes in one worker and validate shared ancestor directories once at each end."""
+    fingerprint_by_path: dict[bytes, str] = {}
+    metadata_by_dir: dict[str, os.stat_result | None] = {}
+    for path in paths:
+        if path and path not in fingerprint_by_path:
+            filename = worktree_filename(context, path)
+            _validate_fingerprint_parent(context, filename, metadata_by_dir)
+            fingerprint_by_path[path] = _fingerprint_filename(filename)
+    for directory, expected in metadata_by_dir.items():
+        try:
+            actual = os.lstat(directory)
+        except FileNotFoundError:
+            actual = None
+        if actual is None and expected is None:
+            continue
+        if actual is None or expected is None or (actual.st_dev, actual.st_ino, actual.st_mode, getattr(actual, "st_reparse_tag", None)) != (
+            expected.st_dev, expected.st_ino, expected.st_mode, getattr(expected, "st_reparse_tag", None)
+        ):
+            raise ValueError("A working directory changed during reading; refresh the changes")
+    return fingerprint_by_path
+
+
+def read_fingerprints(context: RepositoryContext, paths: tuple[bytes, ...]) -> Generator:
+    """Distribute exact byte reads across the existing bounded filesystem workers."""
+    unique_paths = tuple(dict.fromkeys(path for path in paths if path))
+    groups = []
+    for position in range(min(WORKTREE_FILE_WORKER_COUNT, len(unique_paths))):
+        group = unique_paths[position::WORKTREE_FILE_WORKER_COUNT]
+        groups.append(FileTask(lambda group=group: fingerprint_files(context, group)))
+    results = yield ReadBatch(tuple(groups))
+    fingerprint_by_path: dict[bytes, str] = {}
+    for result in results:
+        fingerprint_by_path.update(result)
+    return fingerprint_by_path
+
+
+def verify_local_state(snapshot: WorktreeSnapshot, paths: tuple[bytes, ...]) -> None:
+    """Refuse stale local bytes before private preparation; Git metadata is checked before publication."""
+    if read_index(snapshot.index_filename) != snapshot.index_content:
+        raise ValueError("The index changed since selection; refresh the changes")
+    for path, actual in fingerprint_files(snapshot.context, paths).items():
+        expected = snapshot.fingerprint_by_path.get(path)
+        # Gitlink HEAD is checked by Git before publication; the directory itself is checked here.
+        if actual != expected and (expected is None or not expected.startswith(actual + ":")):
+            raise ValueError("Working file changed since selection; refresh the changes")
+
+
+def parse_status(output: bytes) -> tuple[LocalEntry, ...]:
+    """Parse NUL records without splitting or normalizing the path bytes."""
+    if output and not output.endswith(b"\0"):
+        raise ValueError("Incomplete Git status output")
+    entries: list[LocalEntry] = []
+    renamed_separator_count, ordinary_separator_count = 9, 8
+    records = iter(output.split(b"\0"))
+    for record in records:
+        if not record or record.startswith(STATUS_HEADER_PREFIX):
+            continue
+        if record.startswith(STATUS_UNTRACKED_PREFIX):
+            entries.append(LocalEntry(StagingSide.UNSTAGED, None, record[len(STATUS_UNTRACKED_PREFIX):], FileStatus.ADDED))
+            continue
+        if record.startswith(STATUS_UNMERGED_PREFIX):
+            fields = record.split(b" ", STATUS_UNMERGED_SEPARATOR_COUNT)
+            _kind, _status, _submodule, base_mode, local_mode, remote_mode, work_mode, base_oid, local_oid, remote_oid, path = fields
+            if not path or work_mode.decode("ascii") not in INDEX_MODE_SET | {"000000"}:
+                raise ValueError("Malformed unmerged status path or mode")
+            sides = []
+            stages = []
+            role_set: set[str] = set()
+            for stage, mode, oid in zip(CONFLICT_ROLE_BY_STAGE, (base_mode, local_mode, remote_mode), (base_oid, local_oid, remote_oid), strict=True):
+                if mode == b"000000":
+                    if not re.fullmatch(rb"(?:0{40}|0{64})", oid):
+                        raise ValueError("Absent conflict side has a nonzero object")
+                    continue
+                sides.append(ConflictSide(stage, mode.decode("ascii"), oid.decode("ascii")))
+                stages.append(stage)
+                role_set.add(CONFLICT_ROLE_BY_STAGE[stage])
+            if (not sides or not len(base_oid) == len(local_oid) == len(remote_oid)
+                    or role_set != CONFLICT_ROLE_SET_BY_STATUS.get(_status)):
+                raise ValueError("Malformed unmerged status sides")
+            entries.append(LocalEntry(StagingSide.UNSTAGED, path, path, FileStatus.UNMERGED, base_mode.decode(), work_mode.decode(), base_oid.decode(),
+                                      conflict_stages=tuple(stages), conflict_sides=tuple(sides), submodule=SubmoduleState.parse(_submodule)))
+            continue
+        if not record.startswith((STATUS_ORDINARY_PREFIX, STATUS_RENAMED_PREFIX)):
+            raise ValueError("Unsupported Git status record")
+        old_path = None
+        if record.startswith(STATUS_RENAMED_PREFIX):
+            _kind, status, _submodule, head_mode, index_mode, work_mode, head_oid, index_oid, _score, path = record.split(b" ", renamed_separator_count)
+            old_path = next(records, None)
+            if not old_path:
+                raise ValueError("Missing renamed status path")
+        else:
+            _kind, status, _submodule, head_mode, index_mode, work_mode, head_oid, index_oid, path = record.split(b" ", ordinary_separator_count)
+        staged_letter, unstaged_letter = status.decode("ascii")
+        if staged_letter != STATUS_UNCHANGED_LETTER:
+            staged_status = file_status(staged_letter)
+            entries.append(LocalEntry(StagingSide.STAGED, (old_path or path) if staged_status != FileStatus.ADDED else None, path if staged_status != FileStatus.DELETED else None, staged_status,
+                                      head_mode.decode(), index_mode.decode(), head_oid.decode(), index_oid.decode(), submodule=SubmoduleState.parse(_submodule)))
+        if unstaged_letter != STATUS_UNCHANGED_LETTER:
+            unstaged_status = file_status(unstaged_letter)
+            entries.append(LocalEntry(StagingSide.UNSTAGED, path, path if unstaged_status != FileStatus.DELETED else None, unstaged_status,
+                                      index_mode.decode(), work_mode.decode(), index_oid.decode(), submodule=SubmoduleState.parse(_submodule)))
+    return tuple(entries)
+
+
+@dataclass(frozen=True)
+class IndexListing:
+    """What `ls-files --stage -v -z` says about an index: a pure function of the index bytes it listed."""
+
+    index_entries: bytes
+    hidden_index_paths: tuple[bytes, ...]
+    skip_worktree_paths: tuple[bytes, ...]
+
+
+def parse_index_listing(flag_output: bytes) -> IndexListing:
+    """Split a flagged index listing into sorted entry records and the paths Git hides from the working tree."""
+    if flag_output and not flag_output.endswith(b"\0"):
+        raise ValueError("Incomplete Git index flag output")
+    index_metadata_field_count = 3
+    skip_paths: list[bytes] = []
+    hidden_paths: list[bytes] = []
+    index_records: list[bytes] = []
+    for record in flag_output.split(b"\0"):
+        if not record:
+            continue
+        flag, separator, index_record = record.partition(b" ")
+        metadata, path_separator, path = index_record.partition(b"\t")
+        if not separator or not path_separator or len(metadata.split(b" ")) != index_metadata_field_count or not path:
+            raise ValueError("Malformed Git index entry output")
+        index_records.append(index_record + b"\0")
+        if flag.upper() == b"S":
+            skip_paths.append(path)
+        if flag.upper() == b"S" or flag.islower():
+            hidden_paths.append(path)
+    return IndexListing(b"".join(sorted(index_records)), tuple(hidden_paths), tuple(skip_paths))
+
+
+def reusable_index_listing(previous: WorktreeSnapshot | None, context: RepositoryContext, git_filename: str, index_filename: str,
+                           index_content: bytes | None) -> IndexListing | None:
+    """Return the index listing of a previous read of the same worktree, index file and Git, when its index bytes are the ones just read."""
+    if previous is None or previous.index_entries is None:
+        return None
+    if previous.key != WorktreeKey.from_context(context) or previous.git_filename != git_filename:
+        return None
+    if canonical_path(previous.index_filename) != canonical_path(index_filename):
+        return None
+    if previous.index_content != index_content:
+        return None
+    return IndexListing(previous.index_entries, previous.hidden_index_paths, previous.skip_worktree_paths)
+
+
+def conflict_side_by_path(index_entries: bytes) -> dict[bytes, tuple[ConflictSide, ...]]:
+    """Validate captured index records and group only their nonzero stages."""
+    if index_entries and not index_entries.endswith(b"\0"):
+        raise ValueError("Incomplete Git index entries")
+    side_by_path: dict[bytes, list[ConflictSide]] = {}
+    stage_by_path: dict[bytes, set[int]] = {}
+    for record in index_entries.split(b"\0"):
+        if not record:
+            continue
+        metadata, separator, path = record.partition(b"\t")
+        mode, oid, stage_value = metadata.split(b" ")
+        if (not separator or not path or stage_value not in (b"0", b"1", b"2", b"3") or mode.decode("ascii") not in INDEX_MODE_SET
+                or not re.fullmatch(rb"(?:[0-9a-f]{40}|[0-9a-f]{64})", oid) or not oid.strip(b"0")):
+            raise ValueError("Malformed Git index entry")
+        stage = int(stage_value)
+        stage_set = stage_by_path.setdefault(path, set())
+        if stage in stage_set or (stage_set and (stage == 0 or 0 in stage_set)):
+            raise ValueError("Duplicate or conflicting Git index stage")
+        stage_set.add(stage)
+        if stage:
+            side_by_path.setdefault(path, []).append(ConflictSide(stage, mode.decode("ascii"), oid.decode("ascii")))
+    result_by_path = {}
+    for path, sides in side_by_path.items():
+        result_by_path[path] = tuple(sorted(sides, key=lambda side: side.stage))
+    return result_by_path
+
+
+def validate_conflict_index(entries: tuple[LocalEntry, ...], index_entries: bytes) -> None:
+    """Refuse disagreement between status and index from the same capture."""
+    side_by_path = conflict_side_by_path(index_entries)
+    seen_path_set: set[bytes] = set()
+    for entry in entries:
+        if entry.status != FileStatus.UNMERGED:
+            if entry.path in side_by_path:
+                raise ValueError("A path is both resolved and unmerged in status")
+            continue
+        if (entry.path in seen_path_set or side_by_path.get(entry.path) != entry.conflict_sides
+                or tuple(side.stage for side in entry.conflict_sides) != entry.conflict_stages):
+            raise ValueError("Unmerged status and index disagree; refresh the changes")
+        seen_path_set.add(entry.path)
+    if seen_path_set != set(side_by_path):
+        raise ValueError("Unmerged index paths are missing from status; refresh the changes")
+
+
+def apply_conflict_attributes(entries: tuple[LocalEntry, ...], attributes: bytes) -> tuple[LocalEntry, ...]:
+    """Retain native binary merge/diff attributes even when the blob contains only text."""
+    if attributes and not attributes.endswith(b"\0"):
+        raise ValueError("Incomplete conflict attributes")
+    fields = attributes.removesuffix(b"\0").split(b"\0") if attributes else []
+    attribute_field_count = 3
+    if len(fields) % attribute_field_count:
+        raise ValueError("Malformed conflict attributes")
+    binary_path_set: set[bytes] = set()
+    iterator = iter(fields)
+    for path, attribute, value in zip(iterator, iterator, iterator, strict=True):
+        if ((attribute in (b"diff", b"merge") and value == b"unset") or (attribute == b"merge" and value == b"binary")
+                or (attribute == b"binary" and value == b"set")):
+            binary_path_set.add(path)
+    result_entries = []
+    for entry in entries:
+        result_entries.append(replace(entry, conflict_binary=True) if entry.conflict_sides and entry.path in binary_path_set else entry)
+    return tuple(result_entries)
+
+
+def parse_staged(output: bytes) -> tuple[LocalEntry, ...]:
+    """Read rename-aware raw comparisons using Git's exact object modes and paths."""
+    if output and not output.endswith(b"\0"):
+        raise ValueError("Incomplete staged comparison output")
+    records = iter(output.split(b"\0"))
+    entries: list[LocalEntry] = []
+    for record in records:
+        if not record:
+            continue
+        if not record.startswith(b":"):
+            raise ValueError("Malformed staged comparison")
+        old_mode, new_mode, old_oid, new_oid, raw_status = record[len(b":"):].split(b" ")
+        status = file_status(raw_status.decode("ascii"))
+        path = next(records, None)
+        if not path:
+            raise ValueError("Missing staged path")
+        old_path = None if status == FileStatus.ADDED else path
+        new_path = None if status == FileStatus.DELETED else path
+        if status in (FileStatus.RENAMED, FileStatus.COPIED):
+            new_path = next(records, None)
+            if not new_path:
+                raise ValueError("Missing renamed path")
+        entries.append(LocalEntry(StagingSide.STAGED, old_path, new_path, status, old_mode.decode(), new_mode.decode(), old_oid.decode(), new_oid.decode()))
+    return tuple(entries)