gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/conflict.py

@@ -0,0 +1,506 @@
+"""Keep unresolved paths tied to complete working-tree observations."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import uuid
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, BinaryIO
+
+from gitpane.history.repository_value import FileStatus
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE
+from gitpane.worktree.worktree_snapshot import CONFLICT_ROLE_BY_STAGE, ConflictSide, LocalEntry, WorktreeKey, validate_conflict_index
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.operation.repository_operation import OperationIntent
+    from gitpane.sequencer.mergetool import MergetoolRequest, TemporaryMergeStore
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_file import FileImage
+    from gitpane.worktree.worktree_snapshot import WorktreeSnapshot
+
+# The same refusals are given by every route that accepts a conflict result, so their wording lives in one place.
+SUBMODULE_RESOLUTION_REFUSAL = "Resolve the submodule commit externally; this entry is not a file to merge."
+UNSUPPORTED_RESULT_REFUSAL = "The working result is not a regular file or symbolic link"
+# Said when a conflict action (merge tool, choosing a side, marking solved) is asked with no conflict selected; the merge
+# tool service gives it too, for a caller that skipped this check.
+NO_CONFLICT_SELECTED_TEXT = "Select a conflict before choosing its resolution."
+# Git writes its conflict markers seven characters long unless the conflict-marker-size attribute says otherwise. That
+# attribute is not read here, so a path configured with longer markers is not recognised as still conflicted.
+CONFLICT_MARKER_LENGTH = 7
+CONFLICT_MARKER_CHARACTERS = (b"<", b"|", b"=", b">")
+# A marker is followed by its label after a space, or ends its line; any other character makes it ordinary text.
+CONFLICT_MARKER_FOLLOWER_SET = frozenset((b" ", b"\t"))
+# Git treats content holding a NUL byte as binary and never writes text markers into it.
+BINARY_CONTENT_BYTE = b"\0"
+FIRST_LINE_NUMBER = 1
+
+
+def conflict_count_text(count: int) -> str:
+    """Describe the same unresolved count in the repository banner and conflict list."""
+    return f"{count} unresolved merge conflict" + ("s" if count != 1 else "")
+
+
+def conflict_path_label(path: bytes) -> str:
+    """Expose control characters without changing the original path identity."""
+    parts = []
+    quoted_content_start, quoted_content_end = 1, -1
+    for character in path.decode("utf-8", "surrogateescape"):
+        if character == "\\":
+            parts.append("\\\\")
+        elif not character.isprintable():
+            parts.append(ascii(character)[quoted_content_start:quoted_content_end])
+        else:
+            parts.append(character)
+    return "".join(parts)
+
+
+@dataclass(frozen=True)
+class ConflictMarkerLine:
+    """Name one line of a working result that is still a conflict marker, numbered from 1 as an editor shows it."""
+
+    line_number: int
+    marker: str
+
+
+def conflict_marker_of_line(line: bytes) -> str:
+    """Return the marker that opens a line, or an empty text when the line is ordinary text.
+
+    Seven `<`, `|`, `=` or `>` count only when followed by a space, a tab or the end of the line: a longer run such as
+    a Markdown underline of eight `=` is text, like a marker glued to its label.
+    """
+    for character in CONFLICT_MARKER_CHARACTERS:
+        marker = character * CONFLICT_MARKER_LENGTH
+        if not line.startswith(marker):
+            continue
+        follower = line[CONFLICT_MARKER_LENGTH:CONFLICT_MARKER_LENGTH + 1]
+        if not follower or follower in CONFLICT_MARKER_FOLLOWER_SET:
+            return marker.decode("ascii")
+    return ""
+
+
+def conflict_marker_lines(content: bytes) -> tuple[ConflictMarkerLine, ...]:
+    """Find the conflict markers Git left in a working result, so a file still holding them is not staged as resolved without a warning.
+
+    Staging those lines by mistake commits broken code. Lines end with LF or CRLF. Binary content, recognised as Git
+    does by a NUL byte, is never scanned and gives no marker.
+    """
+    if BINARY_CONTENT_BYTE in content:
+        return ()
+    marker_lines = []
+    for line_number, line in enumerate(content.split(b"\n"), start=FIRST_LINE_NUMBER):
+        marker = conflict_marker_of_line(line.removesuffix(b"\r"))
+        if marker:
+            marker_lines.append(ConflictMarkerLine(line_number, marker))
+    return tuple(marker_lines)
+
+
+def has_deleted_side(sides: tuple[ConflictSide, ...]) -> bool:
+    """Identify a file with a base and an absent merge side, excluding submodule entries."""
+    role_set = set()
+    for side in sides:
+        if side.mode == "160000":
+            return False
+        role_set.add(CONFLICT_ROLE_BY_STAGE[side.stage])
+    return "BASE" in role_set and not {"LOCAL", "REMOTE"}.issubset(role_set)
+
+
+@dataclass(frozen=True)
+class ConflictEntry:
+    """Describe an unresolved path and its immutable Git object versions."""
+
+    path: bytes
+    sides: tuple[ConflictSide, ...]
+    kind: str = "Text conflict"
+    explanation: str = ""
+
+
+@dataclass(frozen=True)
+class ConflictSelection:
+    """Bind exact selected paths to a worktree and capture generation."""
+
+    key: WorktreeKey
+    generation: int
+    paths: tuple[bytes, ...]
+
+
+@dataclass(frozen=True)
+class ConflictResolutionIntent:
+    """Bind a confirmed working result to its exact unresolved index and operation owner."""
+
+    snapshot: WorktreeSnapshot
+    path: bytes
+    sides: tuple[ConflictSide, ...]
+    image: FileImage
+    operation: OperationIntent
+    delete: bool = False
+    # Conflict markers found in the accepted bytes; the confirmation warns about them before anything is staged.
+    marker_lines: tuple[ConflictMarkerLine, ...] = ()
+
+    @classmethod
+    def capture(cls, snapshot: WorktreeSnapshot, path: bytes, operation: OperationIntent, *, delete: bool = False) -> ConflictResolutionIntent:
+        """Capture the working result before confirmation without changing its bytes or index."""
+        from gitpane.worktree.worktree_file import capture_image
+        from gitpane.worktree.worktree_snapshot import verify_local_state
+
+        image = capture_image(snapshot.context, path, allow_missing_parents=True)
+        intent = cls.accept(snapshot, path, image, operation, delete=delete)
+        verify_local_state(snapshot, (path,))
+        return intent
+
+    @classmethod
+    def accept(cls, snapshot: WorktreeSnapshot, path: bytes, image: FileImage, operation: OperationIntent, *, delete: bool = False) -> ConflictResolutionIntent:
+        """Bind an already captured working result to its unresolved index stages, reading the file again only to prove it unchanged.
+
+        A caller that accepted exact bytes earlier builds its intent here, so a second capture can never silently adopt
+        bytes written in between.
+        """
+        from gitpane.worktree.worktree_file import validate_image
+
+        entries = conflicts_from_snapshot(snapshot)
+        entry = next((entry for entry in entries if entry.path == path), None)
+        if entry is None:
+            raise ValueError("The selected path is no longer unresolved; rescan merge conflicts")
+        if any(side.mode == "160000" for side in entry.sides):
+            raise ValueError(SUBMODULE_RESOLUTION_REFUSAL)
+        if delete and image.exists and not has_deleted_side(entry.sides):
+            raise ValueError("Delete file requires a conflict with a deleted side")
+        if image.exists and not (stat.S_ISREG(image.mode) or stat.S_ISLNK(image.mode)):
+            raise ValueError(UNSUPPORTED_RESULT_REFUSAL)
+        if not delete and (not image.exists or not (stat.S_ISREG(image.mode) or stat.S_ISLNK(image.mode))):
+            raise ValueError("The working result is missing or unsupported; a deletion requires explicit confirmation")
+        validate_image(snapshot.context, path, image)
+        return cls(snapshot, path, entry.sides, image, operation, delete)
+
+    def with_marker_lines(self) -> ConflictResolutionIntent:
+        """Attach the conflict markers still present in the accepted bytes, read from the captured image and never from the file again.
+
+        A deletion and a symbolic link have no file content to scan. Runs on a file worker, since the image may have to
+        be read from its private copy.
+        """
+        if self.delete or not self.image.exists or not stat.S_ISREG(self.image.mode):
+            return self
+        return replace(self, marker_lines=conflict_marker_lines(self.image.read()))
+
+
+def capture_conflict_result(snapshot: WorktreeSnapshot, paths: tuple[bytes, ...], *,
+                            expected_image_by_path: dict[bytes, FileImage] | None = None) -> tuple[WorktreeSnapshot, dict[bytes, FileImage]]:
+    """Accept the working bytes of selected unresolved paths as they are now, and answer the snapshot that expects them.
+
+    Only the fingerprints of the accepted paths change. HEAD, index bytes and entries, conflict sides, conversion
+    settings, generation and every other field stay the ones the snapshot was read with, so a later Git verification
+    still compares the repository against that earlier read: this is a local acceptance of chosen bytes, never a new
+    read by Git. With expected images, each path must still be exactly the published file, type, parents and bytes
+    included. Runs on a file worker.
+    """
+    from gitpane.worktree.worktree_file import capture_image, validate_image
+    from gitpane.worktree.worktree_snapshot import file_fingerprint, read_index
+
+    if not snapshot.fresh or snapshot.context.is_bare or snapshot.key != WorktreeKey.from_context(snapshot.context):
+        raise ValueError("A complete current conflict read is required; rescan merge conflicts")
+    if read_index(snapshot.index_filename) != snapshot.index_content:
+        raise ValueError("The index changed since selection; rescan merge conflicts")
+    entry_by_path: dict[bytes, ConflictEntry] = {}
+    for entry in conflicts_from_snapshot(snapshot):
+        entry_by_path[entry.path] = entry
+    fingerprint_by_path = dict(snapshot.fingerprint_by_path)
+    image_by_path: dict[bytes, FileImage] = {}
+    for path in paths:
+        entry = entry_by_path.get(path)
+        if entry is None:
+            raise ValueError("The selected path is no longer unresolved; rescan merge conflicts")
+        if any(side.mode == "160000" for side in entry.sides):
+            raise ValueError(SUBMODULE_RESOLUTION_REFUSAL)
+        image = capture_image(snapshot.context, path, allow_missing_parents=True)
+        if image.exists and not (stat.S_ISREG(image.mode) or stat.S_ISLNK(image.mode)):
+            raise ValueError(UNSUPPORTED_RESULT_REFUSAL)
+        if expected_image_by_path is not None:
+            expected = expected_image_by_path.get(path)
+            if expected is None or (image.exists, image.identity, image.parents, image.digest()) != (expected.exists, expected.identity, expected.parents, expected.digest()):
+                raise ValueError("The published working result changed; rescan merge conflicts")
+        accepted_fingerprint = file_fingerprint(snapshot.context, path)
+        # The fingerprint is read after the image; proving the image unchanged afterwards binds both to the same file.
+        validate_image(snapshot.context, path, image)
+        fingerprint_by_path[path] = accepted_fingerprint
+        image_by_path[path] = image
+    if read_index(snapshot.index_filename) != snapshot.index_content:
+        raise ValueError("The index changed since selection; rescan merge conflicts")
+    return replace(snapshot, fingerprint_by_path=fingerprint_by_path), image_by_path
+
+
+# Version bodies are written straight into their private files as Git streams them; the parser keeps none of them.
+RETAINED_VERSION_BODY_LIMIT_BYTES = 0
+
+
+def open_version_files(filenames_by_oid: dict[str, list[str]]) -> dict[str, list[BinaryIO]]:
+    """Create every private version file exclusively; if one cannot be created, close and remove the ones already made."""
+    streams_by_oid: dict[str, list[BinaryIO]] = {}
+    try:
+        for oid, filenames in filenames_by_oid.items():
+            for filename in filenames:
+                # The writer spans asynchronous Git delivery; close_version_files owns its closing.
+                streams_by_oid.setdefault(oid, []).append(open(filename, "xb"))  # noqa: SIM115
+    except OSError:
+        close_version_files(streams_by_oid)
+        remove_version_files(filenames_by_oid)
+        raise
+    return streams_by_oid
+
+
+def close_version_files(streams_by_oid: dict[str, list[BinaryIO]]) -> None:
+    """Close every version file, even when one of them fails to close, then report the first failure."""
+    first_error: OSError | None = None
+    for streams in streams_by_oid.values():
+        for stream in streams:
+            try:
+                stream.close()
+            except OSError as error:
+                if first_error is None:
+                    first_error = error
+    if first_error is not None:
+        raise first_error
+
+
+def remove_version_files(filenames_by_oid: dict[str, list[str]]) -> None:
+    """Remove the private version files this preparation created, so a failed read leaves no partial tool input."""
+    for filenames in filenames_by_oid.values():
+        for filename in filenames:
+            if os.path.isfile(filename) and not os.path.islink(filename):
+                os.unlink(filename)
+
+
+def prepare_conflict_deletion(intent: ConflictResolutionIntent, operation_dir: str) -> Generator:
+    """Remove only the selected index stages in a private copy before publishing a file deletion."""
+    from gitpane.config import GIT_MUTATION_TIMEOUT_MS, MUTATION_IDLE_TIMEOUT_MS
+    from gitpane.worktree.command_sequence import GitCommand
+    from gitpane.worktree.staged_reset import FileChange, may_carry_split_index
+    from gitpane.worktree.worktree_file import PRIVATE_FILE_MODE, FileImage
+    from gitpane.worktree.worktree_snapshot import read_index
+
+    snapshot = intent.snapshot
+    candidate_filename = os.path.join(operation_dir, "candidate-index")
+    shutil.copy2(snapshot.index_filename, candidate_filename)
+    os.chmod(candidate_filename, PRIVATE_FILE_MODE)
+    if read_index(candidate_filename) != snapshot.index_content:
+        raise ValueError("The index changed while preparing the deletion")
+    environment_by_name = {"GIT_INDEX_FILE": candidate_filename}
+    # Only an index that may be split is flattened, in the private copy: an ordinary index saves a supervised write.
+    if may_carry_split_index(snapshot.index_content):
+        yield GitCommand(["update-index", "--no-split-index"], environment_by_name=environment_by_name, profile=LOCAL_WRITE_PROFILE)
+    yield GitCommand(["update-index", "--force-remove", "-z", "--stdin"], stdin=intent.path + b"\0", environment_by_name=environment_by_name,
+                     timeout_ms=GIT_MUTATION_TIMEOUT_MS, idle_timeout_ms=MUTATION_IDLE_TIMEOUT_MS, profile=LOCAL_WRITE_PROFILE)
+    after_entries = yield GitCommand(["ls-files", "--stage", "-z"], environment_by_name=environment_by_name)
+    expected_records = []
+    for record in snapshot.index_entries.split(b"\0"):
+        _metadata, _separator, path = record.partition(b"\t")
+        if path != intent.path:
+            expected_records.append(record)
+    if sorted(after_entries.split(b"\0")) != sorted(expected_records):
+        raise ValueError("The deletion candidate changed other index entries")
+    candidate = read_index(candidate_filename)
+    if candidate is None:
+        raise ValueError("Git did not produce the deletion candidate index")
+    change = FileChange(intent.path, intent.image, FileImage(False, 0, parents=intent.image.parents))
+    return (change,), snapshot.index_entries, after_entries, candidate
+
+
+@dataclass(frozen=True)
+class ConflictState:
+    """Retain last known conflicts while distinguishing failed or stale reads."""
+
+    key: WorktreeKey
+    generation: int = 0
+    entries: tuple[ConflictEntry, ...] = ()
+    fresh: bool = False
+    diagnostic: str = "Conflict state is unknown; refresh the repository"
+
+
+def conflicts_from_snapshot(snapshot: WorktreeSnapshot) -> tuple[ConflictEntry, ...]:
+    """Build conflicts from the status and index captured together, without new reads."""
+    if not snapshot.fresh or snapshot.index_entries is None:
+        raise ValueError("A complete current index read is required")
+    validate_conflict_index(snapshot.entries, snapshot.index_entries)
+    entries = []
+    for entry in snapshot.entries:
+        if entry.status == FileStatus.UNMERGED:
+            kind, explanation = classify_conflict(entry)
+            entries.append(ConflictEntry(entry.path, entry.conflict_sides, kind, explanation))
+    return tuple(sorted(entries, key=lambda entry: entry.path))
+
+
+def snapshot_has_conflicts(snapshot: WorktreeSnapshot) -> bool:
+    """Tell whether a fresh worktree read still lists a conflict; a read that cannot say counts as still conflicted."""
+    try:
+        return bool(conflicts_from_snapshot(snapshot))
+    except ValueError:
+        return True
+
+
+def classify_conflict(entry: LocalEntry) -> tuple[str, str]:
+    """Describe actual modes and absent roles without guessing associations between paths."""
+    role_set = set()
+    mode_set = set()
+    for side in entry.conflict_sides:
+        role_set.add(CONFLICT_ROLE_BY_STAGE[side.stage])
+        mode_set.add(side.mode)
+    if "160000" in mode_set:
+        return "Submodule conflict", SUBMODULE_RESOLUTION_REFUSAL
+    if "120000" in mode_set:
+        return "Symbolic link", "The side objects contain link targets. Resolve the link explicitly without following it as a text file."
+    if role_set == {"BASE"}:
+        return "Both sides absent", "A rename conflict can leave this original path unresolved. Resolve each listed path independently; no destination is inferred."
+    if role_set == {"LOCAL"}:
+        return "Added locally (no base)", "Only LOCAL is present. This may be a rename destination; resolve this exact path independently."
+    if role_set == {"REMOTE"}:
+        return "Added remotely (no base)", "Only REMOTE is present. This may be a rename destination; resolve this exact path independently."
+    if "LOCAL" not in role_set:
+        return "Deleted locally", "LOCAL is absent; no empty file stands in for the deleted side."
+    if "REMOTE" not in role_set:
+        return "Deleted remotely", "REMOTE is absent; no empty file stands in for the deleted side."
+    if entry.conflict_binary:
+        return "Binary conflict", "An available version contains binary data or Git attributes require binary handling. Choose the result explicitly."
+    if "BASE" not in role_set:
+        return "Add/add (no base)", "Both added versions exist, but BASE is absent."
+    if entry.conflict_binary is None:
+        return "Unmerged file", "The index versions are known, but their contents have not been inspected."
+    return "Text conflict", "BASE, LOCAL and REMOTE refer to the exact versions stored in the index."
+
+
+class ConflictService:
+    """Reconcile conflict observations without treating read failures as resolution."""
+
+    def __init__(self) -> None:
+        """Keep last accepted observations separate for each linked worktree."""
+        self.state_by_key: dict[WorktreeKey, ConflictState] = {}
+
+    def observe(self, key: WorktreeKey, snapshot: WorktreeSnapshot | None, diagnostic: str = "") -> ConflictState:
+        """Publish coherent sides or preserve the previous list with an unknown state."""
+        previous = self.state_by_key.get(key, ConflictState(key))
+        try:
+            if snapshot is None or snapshot.key != key:
+                raise ValueError(diagnostic or "Conflict state is unknown; refresh the repository")
+            entries = conflicts_from_snapshot(snapshot)
+            state = ConflictState(key, snapshot.generation, entries, True, "")
+        except ValueError as error:
+            state = ConflictState(key, previous.generation, previous.entries, False, diagnostic or str(error))
+        self.state_by_key[key] = state
+        return state
+
+    def prepare_merge(self, request: MergetoolRequest, store: TemporaryMergeStore, mutation: MutationService) -> Generator:
+        """Extract only captured index objects into immutable private input files, all versions in one Git read.
+
+        Each object Git streams is routed by its own identity to every role that names it, so the order of the
+        answers never matters and a version shared by two roles is read once. The strict framing must account for
+        every requested object before any file becomes a tool input; on any failure every role file is closed and
+        removed.
+        """
+        from gitpane.history.history_parse import CatFileParser
+        from gitpane.worktree.command_sequence import FileTask, GitCommand
+        from gitpane.worktree.worktree_file import capture_image
+
+        snapshot = request.snapshot
+        yield from mutation.worktree_service.verify(snapshot, (request.path,))
+        image = yield FileTask(lambda: capture_image(snapshot.context, request.path))
+        if not image.exists or not stat.S_ISREG(image.mode):
+            raise ValueError("Use manual conflict resolution for an absent or non-regular working file.")
+        yield FileTask(lambda: store.create(request))
+        filenames_by_oid: dict[str, list[str]] = {}
+        for side in request.sides:
+            filenames_by_oid.setdefault(side.oid, []).append(store.filename(request, CONFLICT_ROLE_BY_STAGE[side.stage]))
+        streams_by_oid = yield FileTask(lambda: open_version_files(filenames_by_oid))
+        oids = sorted(filenames_by_oid)
+        parser = CatFileParser(oids, object_limit_bytes=RETAINED_VERSION_BODY_LIMIT_BYTES, expected_object_type="blob")
+
+        def route(body: bytes) -> None:
+            """Copy the bytes of the object being framed into every role file that names it."""
+            for stream in streams_by_oid[parser.oid]:
+                stream.write(body)
+
+        def consume(chunk: bytes) -> None:
+            """Feed Git's stream to the strict framing, which hands each body fragment to the router."""
+            parser.feed(chunk)
+
+        parser.body_callback = route
+        extracted = False
+        try:
+            yield GitCommand(["cat-file", "--batch"], stdin="".join(oid + "\n" for oid in oids).encode("ascii"), consume=consume, stdout_limit_bytes=None)
+            parser.finish()
+            extracted = True
+        finally:
+            yield FileTask(lambda: close_version_files(streams_by_oid))
+            if not extracted:
+                yield FileTask(lambda: remove_version_files(filenames_by_oid))
+
+        def freeze() -> None:
+            """Make every complete version read-only and remember its identity for later checks."""
+            for filenames in filenames_by_oid.values():
+                for filename in filenames:
+                    store.freeze_input(request, filename)
+
+        yield FileTask(freeze)
+        yield from mutation.worktree_service.verify(snapshot, (request.path,))
+        return image
+
+    def publish_merge_result(self, request: MergetoolRequest, before: FileImage, output: FileImage, store: TemporaryMergeStore,
+                             mutation: MutationService, is_current: Callable[[], bool]) -> Generator:
+        """Revalidate a saved result, publish its bytes, then stage under its existing owner.
+
+        The working file replacement keeps its own Git verification. The image it produced is then accepted locally,
+        its exact identity and bytes, and the staging verifies the index, HEAD and conversion afresh under its lock:
+        a complete capture between the two writes would prove nothing either of them does not prove already.
+        """
+        from gitpane.worktree.command_sequence import FileTask
+        from gitpane.worktree.worktree_file import FileImage, capture_image, prepare_publication_image, private_file_dir, publish_image_mode, validate_destination, validate_image
+        from gitpane.worktree.worktree_snapshot import verify_local_state
+
+        snapshot, path = request.snapshot, request.path
+        yield from mutation.worktree_service.verify(snapshot, (path,))
+
+        def publish() -> FileImage:
+            """Keep the private saved output intact even when publication or later staging fails."""
+            if not is_current():
+                raise ValueError("The original repository session is no longer current.")
+            store.validate_output(request, output)
+            validate_image(snapshot.context, path, before)
+            verify_local_state(snapshot, (path,))
+            if os.path.lexists(snapshot.index_filename + ".lock"):
+                raise ValueError("The Git index is locked by another operation; the saved result has been retained.")
+            output_dir, _identity = store.directory_by_request[request.operation.operation_id]
+            directory = private_file_dir(snapshot.context, path, output_dir)
+            filename = os.path.join(directory, "publish-" + uuid.uuid4().hex)
+            try:
+                after = prepare_publication_image(filename, FileImage(True, before.mode, output.read()), before)
+                store.validate_output(request, output)
+                validate_image(snapshot.context, path, before)
+                verify_local_state(snapshot, (path,))
+                if os.path.lexists(snapshot.index_filename + ".lock"):
+                    raise ValueError("The Git index is locked by another operation; the saved result has been retained.")
+                if not is_current():
+                    raise ValueError("The original repository session is no longer current.")
+                destination_filename, _parents = validate_destination(snapshot.context, path)
+                publish_image_mode(filename, after)
+                os.replace(filename, destination_filename)
+                published = capture_image(snapshot.context, path)
+                if published.digest() != after.digest():
+                    raise ValueError("Working result changed after publication; the saved result has been retained.")
+                return published
+            finally:
+                if os.path.isfile(filename) and not os.path.islink(filename):
+                    os.unlink(filename)
+                if directory != output_dir:
+                    os.rmdir(directory)
+
+        published = yield FileTask(publish)
+
+        def accept() -> ConflictResolutionIntent:
+            """Bind the staging to the exact published image, without adopting any HEAD, index or conversion read now."""
+            accepted_snapshot, image_by_path = capture_conflict_result(snapshot, (path,), expected_image_by_path={path: published})
+            return ConflictResolutionIntent.accept(accepted_snapshot, path, image_by_path[path], request.operation)
+
+        intent = yield FileTask(accept)
+        if intent.image.read() != output.read() or not is_current():
+            raise ValueError("Working result or session changed after publication; rescan merge conflicts.")
+        return (yield from mutation.resolve_conflict_sequence(intent))

gitpane/sequencer/merge_recovery.py

@@ -0,0 +1,163 @@
+"""Keep refused merge outputs discoverable without granting them publication rights."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import sys
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QStandardPaths
+
+from gitpane.config import MUTATION_RECORD_LIMIT_BYTES
+from gitpane.system.qt_folder import writable_folder
+from gitpane.worktree.worktree_file import FILE_OBJECT_IDENTITY_FIELDS, FILE_STABLE_IDENTITY_FIELDS, PRIVATE_DIRECTORY_MODE, PRIVATE_FILE_MODE, stat_identity
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import RepositoryContext
+
+RECOVERY_DIRECTORY_BASENAME = "gitpane-merge-recovery"
+RECOVERY_RECORD_BASENAME = "record.json"
+RECOVERY_OUTPUT_BASENAME = "MERGED"
+
+
+@dataclass(frozen=True)
+class MergeRecovery:
+    """Describe a retained file for manual recovery, never for automatic publication."""
+
+    path: bytes
+    filename: str
+    saved_at: str
+    sha256: str
+
+
+def validate_recovery_directory(directory: str) -> None:
+    """Reject redirected ancestors before accessing private retained files."""
+    while True:
+        metadata = os.lstat(directory)
+        if not stat.S_ISDIR(metadata.st_mode) or os.path.islink(directory) or os.path.isjunction(directory):
+            raise ValueError("The merge recovery directory was redirected.")
+        parent_dir = os.path.dirname(directory)
+        if parent_dir == directory:
+            return
+        directory = parent_dir
+
+
+def read_recovery_file(filename: str, limit: int | None = None) -> bytes:
+    """Read one regular private file only while its open handle and path remain identical."""
+    validate_recovery_directory(os.path.dirname(filename))
+    return read_checked_leaf(filename, limit)
+
+
+def read_checked_leaf(filename: str, limit: int | None = None) -> bytes:
+    """Read one regular private file whose containing folder a caller has already checked.
+
+    Callers that read many files of the same folder walk its ancestors once and then use this function, instead of
+    paying that walk again for every file. A caller with no such check must use the function above.
+    """
+    metadata = os.lstat(filename)
+    if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1 or os.path.islink(filename) or os.path.isjunction(filename):
+        raise ValueError("The merge recovery file is not a regular private file.")
+    if limit is not None and metadata.st_size > limit:
+        raise ValueError("The merge recovery record is too large.")
+    with open(filename, "rb") as stream:
+        # Windows handle and path ctime have different meanings; retain the full path check after reading.
+        if stat_identity(os.fstat(stream.fileno()))[:FILE_STABLE_IDENTITY_FIELDS] != stat_identity(metadata)[:FILE_STABLE_IDENTITY_FIELDS]:
+            raise ValueError("The merge recovery file changed while reading.")
+        # A read sized to the safety limit makes Python allocate that whole limit (up to 256 MiB for a replay backup) even for a
+        # file of a few bytes. One byte more than the checked size costs the real size only and still shows a file that grew.
+        content = stream.read(metadata.st_size + 1)
+    if stat_identity(os.lstat(filename)) != stat_identity(metadata) or len(content) != metadata.st_size:
+        raise ValueError("The merge recovery file changed while reading.")
+    return content
+
+
+class MergeRecoveryStore:
+    """Store private results independently of repository moves and discover them after restart."""
+
+    def __init__(self, storage_dir: str | None = None) -> None:
+        """Normalize injected and Qt storage paths so ownership checks match tempfile directories."""
+        if storage_dir is None:
+            storage_dir = os.path.join(writable_folder(QStandardPaths.StandardLocation.AppLocalDataLocation, sys.platform), RECOVERY_DIRECTORY_BASENAME)
+        self.storage_dir = os.path.abspath(storage_dir)
+
+    def root_dir(self, context: RepositoryContext) -> str:
+        """Keep linked worktrees separate using their own Git administrative directory."""
+        # Git already resolved this absolute location; re-resolving a replaced ancestor would retarget recovery.
+        repository_key = os.path.normcase(os.path.abspath(context.git_dir))
+        return os.path.join(self.storage_dir, hashlib.sha256(os.fsencode(repository_key)).hexdigest())
+
+    def create_directory(self, context: RepositoryContext) -> str:
+        """Allocate durable private storage before launching an editor."""
+        root_dir = self.root_dir(context)
+        missing_dirs = []
+        existing_dir = root_dir
+        while not os.path.lexists(existing_dir):
+            missing_dirs.append(existing_dir)
+            existing_dir = os.path.dirname(existing_dir)
+        validate_recovery_directory(existing_dir)
+        for directory in reversed(missing_dirs):
+            try:
+                os.mkdir(directory, PRIVATE_DIRECTORY_MODE)
+            except FileExistsError:
+                pass
+            validate_recovery_directory(directory)
+        validate_recovery_directory(root_dir)
+        directory = tempfile.mkdtemp(prefix="merge-", dir=root_dir)
+        os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        return directory
+
+    def retain(self, context: RepositoryContext, directory: str, path: bytes) -> None:
+        """Flush minimal recovery metadata only after a saved result has been retained."""
+        if os.path.dirname(directory) != self.root_dir(context):
+            raise ValueError("The merge result is outside its repository recovery directory.")
+        content = read_recovery_file(os.path.join(directory, RECOVERY_OUTPUT_BASENAME))
+        record_by_name = {"path_hex": path.hex(), "saved_at": datetime.now(UTC).isoformat(timespec="seconds"),
+                          "sha256": hashlib.sha256(content).hexdigest(),
+                          "directory_identity": stat_identity(os.lstat(directory))[:FILE_OBJECT_IDENTITY_FIELDS]}
+        filename = os.path.join(directory, RECOVERY_RECORD_BASENAME)
+        descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            json.dump(record_by_name, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+
+    def discover(self, context: RepositoryContext) -> tuple[MergeRecovery, ...]:
+        """Read retained paths and verify bytes without modifying files or authorizing a replay."""
+        root_dir = self.root_dir(context)
+        if not os.path.lexists(root_dir):
+            return ()
+        validate_recovery_directory(root_dir)
+        results = []
+        directories = []
+        with os.scandir(root_dir) as entries:
+            for entry in entries:
+                if entry.is_dir(follow_symlinks=False):
+                    directories.append(entry.path)
+        for directory in sorted(directories):
+            validate_recovery_directory(directory)
+            record_filename = os.path.join(directory, RECOVERY_RECORD_BASENAME)
+            if not os.path.lexists(record_filename):
+                continue
+            try:
+                record_by_name = json.loads(read_recovery_file(record_filename, MUTATION_RECORD_LIMIT_BYTES))
+                identity = stat_identity(os.lstat(directory))[:FILE_OBJECT_IDENTITY_FIELDS]
+                if list(identity) != record_by_name["directory_identity"]:
+                    raise ValueError("A retained merge directory was replaced.")
+                filename = os.path.join(directory, RECOVERY_OUTPUT_BASENAME)
+                content = read_recovery_file(filename)
+                if hashlib.sha256(content).hexdigest() != record_by_name["sha256"]:
+                    raise ValueError("A retained merge result changed. Inspect the recovery directory manually: " + root_dir)
+                path = bytes.fromhex(record_by_name["path_hex"])
+                saved_at = record_by_name["saved_at"]
+                if not path or not isinstance(saved_at, str):
+                    raise ValueError("A retained merge record is incomplete.")
+                results.append(MergeRecovery(path, filename, saved_at, record_by_name["sha256"]))
+            except (KeyError, TypeError, AttributeError) as error:
+                raise ValueError("A retained merge record is unreadable.") from error
+        return tuple(results)