gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/command_sequence.py

@@ -0,0 +1,110 @@
+"""Describe the steps of a Git command sequence: commands, read batches, file tasks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_READ_TIMEOUT_MS, WORKTREE_OUTPUT_LIMIT_BYTES, ProcessPriority
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.process.process_runner import READ_PROFILE
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.process.process_runner import ProcessResult
+    from gitpane.tool.editor import EditorExecutionContext
+
+
+@dataclass(frozen=True)
+class GitCommand:
+    """Describe a bounded command without exposing asynchronous plumbing to callers."""
+
+    arguments: list[str]
+    stdin: bytes | None = None
+    environment_by_name: dict[str, str] = field(default_factory=dict)
+    accepted_codes: tuple[int, ...] = (0,)
+    stdout_limit_bytes: int | None = WORKTREE_OUTPUT_LIMIT_BYTES
+    timeout_ms: int = GIT_READ_TIMEOUT_MS
+    idle_timeout_ms: int = GIT_READ_TIMEOUT_MS
+    consume: Callable[[bytes], None] | None = None
+    # None means a read: see command_profile.
+    profile: str | None = None
+    before_start: Callable[[], None] | None = None
+    editor_context: EditorExecutionContext | None = None
+    suppress_editor: bool = False
+    stdin_filename: str | None = None
+    # See ProcessRequest.opens_files_deleted_at_end.
+    opens_files_deleted_at_end: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject competing input sources before the sequence reaches its runner."""
+        if self.stdin is not None and self.stdin_filename is not None:
+            raise ValueError("stdin and stdin_filename are mutually exclusive")
+
+
+class GitCommandError(RuntimeError):
+    """Preserve a prepared command failure for both the view and optional logging."""
+
+    def __init__(self, result: ProcessResult) -> None:
+        """Filter command details once at the process boundary, naming the process so a console that showed its end does not repeat it."""
+        request = result.request
+        self.process_status = result.status
+        self.return_code = result.return_code
+        self.diagnostic = Diagnostic("Read or prepare changes", request.working_dir, request.program_filename, request.arguments, result.cause, result.stderr, result.return_code,
+                                     process_id=request.request_id).prepare()
+        super().__init__(self.diagnostic.cause)
+
+
+@dataclass(frozen=True)
+class ReadBatch:
+    """Read independent Git or filesystem facts concurrently, retaining their original result positions."""
+
+    commands: tuple[GitCommand | FileTask, ...]
+
+
+@dataclass(frozen=True)
+class FileTask:
+    """Move potentially large filesystem reads off the Qt event loop."""
+
+    callback: Callable[[], object]
+
+
+# A command that declares nothing is a read and does not need the supervised launcher, which costs an interpreter and
+# a job per process. Every command that writes, or that can run a hook, a filter or the editor, declares LOCAL_WRITE_PROFILE
+# itself, and the tests refuse any undeclared command that is not a read.
+DEFAULT_COMMAND_PROFILE = READ_PROFILE
+
+
+def command_profile(command: GitCommand) -> str:
+    """Decide the launch profile of one command: the one it declares, otherwise the read profile.
+
+    This is the only place where that decision is made, so a change of rule cannot forget one of the paths a command
+    can take to the process runner.
+    """
+    if command.profile is not None:
+        return command.profile
+    return DEFAULT_COMMAND_PROFILE
+
+
+def resumed_priority(priority: ProcessPriority) -> ProcessPriority:
+    """Answer the level a sequence resumes at once one of its steps has ended.
+
+    A user action that has started is from then on the rest of an operation; the rest of an operation and background
+    work keep their own level, so background work never overtakes anything by lasting longer.
+    """
+    if priority == ProcessPriority.USER:
+        return ProcessPriority.CONTINUATION
+    return priority
+
+
+def observation_priority(observers: list[tuple[Callable[[], bool], Callable, ProcessPriority]]) -> ProcessPriority:
+    """Answer the queue level of a read shared by these callers: the most urgent level among those still current.
+
+    A caller whose window was replaced meanwhile will not be answered, so its level does not hurry the read.
+    """
+    priority = ProcessPriority.BACKGROUND
+    for current, _callback, observer_priority in observers:
+        if observer_priority < priority and current():
+            priority = observer_priority
+    return priority

gitpane/worktree/file_action_target.py

@@ -0,0 +1,61 @@
+"""Describe what a file menu of a repository window points at."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.history.repository_value import FilePanel, RevisionEntry
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import TreeEntry
+
+
+class FileActionTargetKind(Enum):
+    """Distinguish a single historical entry from an entire directory."""
+
+    FILE = "file"
+    FOLDER = "folder"
+
+
+@dataclass(frozen=True)
+class FileActionSelection:
+    """Capture the clicked entry and panel generation before opening a menu."""
+
+    entry: RevisionEntry | TreeEntry | None
+    commit_oid: str
+    panel_kind: FilePanel
+    generation: int
+    kind: FileActionTargetKind = FileActionTargetKind.FILE
+    folder_path: bytes | None = None
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous selections before any caller can treat a directory as a blob."""
+        if self.kind == FileActionTargetKind.FOLDER:
+            if self.entry is not None or not self.folder_path:
+                raise ValueError("A folder selection needs its raw path and no file entry.")
+        elif self.entry is None or self.folder_path is not None:
+            raise ValueError("A file selection needs its entry and no folder path.")
+
+    def basename(self) -> str:
+        """Return the literal selected side's basename without display decorations."""
+        _directory, _separator, basename = self.path().rpartition(b"/")
+        return os.fsdecode(basename)
+
+    def path(self) -> bytes:
+        """Return the raw folder or file path, using the former spelling for a deletion."""
+        if self.kind == FileActionTargetKind.FOLDER:
+            return self.folder_path
+        return self.entry.new_path or self.entry.old_path if isinstance(self.entry, RevisionEntry) else self.entry.path
+
+
+@dataclass(frozen=True)
+class FileRestoreTarget:
+    """Identify a restoration source separately from the commit that owns the visible selection."""
+
+    commit_oid: str
+    label: str
+    message: str
+    unavailable: str = ""

gitpane/worktree/file_menu_action.py

@@ -0,0 +1,52 @@
+"""Name the actions the file menus offer, each with the label it shows."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Self
+
+
+class FileAction(Enum):
+    """An action of the menu on a file of Prepare changes or of the repository window, with the label of its entry.
+
+    The value is the name of the action; it is never written to a file.
+    """
+
+    STAGE = ("stage", "Stage selected")
+    """Prepare changes only: stage the selected files."""
+    RESET = ("reset", "Reset")
+    """Prepare changes only: reset the selected side of the files."""
+    DELETE = ("delete", "Delete file")
+    """Prepare changes only: move the files to the Trash."""
+    COPY_PATHS = ("copy_paths", "Copy path(s)")
+    """Prepare changes only: the title of the submenu that holds the two copies of the path."""
+    COPY_BASENAME = ("copy_basename", "Copy basename")
+    COPY_ABSOLUTE = ("copy_absolute", "Copy full abs filename")
+    FOLDER = ("folder", "Show in folder")
+    TEXT_EDITOR = ("text_editor", "Show in text editor")
+    HISTORY = ("history", "File history")
+    """Prepare changes only: the history of the working copy file."""
+    STOP_TRACKING = ("stop_tracking", "Stop tracking this file")
+    """Prepare changes only: stage the removal of the files from the index, keeping them on disk."""
+    RESET_TO = ("reset_to", "Reset to")
+    """Repository window only: the title of the submenu that restores the file from a parent commit."""
+    DISPLAY_HISTORY = ("display_history", "Display file history")
+    """Repository window only: the history of the file of the selected commit."""
+    COMPARE = ("compare", "Compare with external tool")
+    """Repository window only: the comparison of the file in the external diff tool, in the file menu and the tool menu."""
+    SAVE_AS = ("save_as", "Save selected as")
+    """Repository window only: save the file of the selected commit to a chosen place."""
+    REMOVE_FROM_HISTORY = ("remove_from_history", "Remove from history")
+    """Repository window only: review removing the selected path from local history."""
+
+    def __new__(cls, value: str, label: str) -> Self:
+        """Keep the name of the action as the value, and its menu label beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        return member
+
+
+# The actions that only open the working copy or its folder. Prepare changes offers them in both lists, Staged
+# included, because they never change the index; the menu and the session both read this one definition.
+READ_ONLY_FILE_ACTION_SET = frozenset((FileAction.FOLDER, FileAction.TEXT_EDITOR))

gitpane/worktree/historical_restore.py

@@ -0,0 +1,361 @@
+"""Restore an explicitly chosen historical file without touching the live index or HEAD."""
+
+from __future__ import annotations
+
+import os
+import stat
+import uuid
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer
+
+from gitpane.history.file_history import WINDOW_CAPABILITY_BY_MODE, WindowCapability
+from gitpane.history.history_parse import parse_commit, parse_tree_entries
+from gitpane.history.repository_value import FileStatus, RevisionEntry, validate_oid
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.repository_operation import OperationAction
+from gitpane.worktree.command_sequence import FileTask, GitCommand, GitCommandError
+from gitpane.worktree.mutation import JOURNAL_SCHEMA_VERSION, JournalKind, JournalState, MutationOutcome, recovery_files_cause, write_record
+from gitpane.worktree.worktree_file import (
+    FILE_OBJECT_IDENTITY_FIELDS,
+    PRIVATE_DIRECTORY_MODE,
+    PRIVATE_FILE_MODE,
+    FileImage,
+    capture_image,
+    clean_created_parents,
+    create_missing_parents,
+    materialize_blob,
+    prepare_publication_image,
+    private_file_dir,
+    publish_image_mode,
+    stat_identity,
+    validate_destination,
+    validate_image,
+    write_image,
+)
+from gitpane.worktree.worktree_snapshot import WorktreeKey, read_index, verify_local_state
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.worktree.file_action_target import FileActionSelection
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_snapshot import WorktreeSnapshot
+
+
+# The name of the action, also the title of every window and diagnostic that reports on it.
+RESTORE_SELECTED_VERSION_TITLE = "Restore selected version"
+
+
+@dataclass(frozen=True)
+class HistoricalRestoreRequest:
+    """Own one exact historical source and the local state accepted by its confirmation."""
+
+    operation_id: str
+    key: WorktreeKey
+    commit_oid: str
+    path: bytes
+    blob_oid: str
+    mode: str
+    selection: FileActionSelection
+    before: FileImage
+    after: FileImage
+    snapshot: WorktreeSnapshot
+    attributes: bytes
+    message: str
+    window_mode: str
+    validate: Callable[[], bool]
+    operation_dir: str
+    private_dir: str
+    candidate_filename: str
+    record_by_name: dict[str, object]
+
+
+class HistoricalRestoreService(QObject):
+    """Retain preparations and writes independently of the lifetime of their initiating widgets."""
+
+    def __init__(self, mutation: MutationService, parent: QObject | None = None) -> None:
+        """Share worktree reservations, recovery and rereads with other local operations."""
+        super().__init__(parent)
+        self.mutation = mutation
+        self.prepared_by_id: dict[str, HistoricalRestoreRequest] = {}
+        self.outcome_by_id: dict[str, MutationOutcome] = {}
+
+    def prepare(self, context: RepositoryContext, git_filename: str, selection: FileActionSelection | None, message: str,
+                window_mode: str, validate: Callable[[], bool], callback: Callable[[HistoricalRestoreRequest | None, Exception | None], None], source_oid: str | None = None) -> str:
+        """Capture the viewed commit or a verified direct parent's file before replacing local content.
+
+        A refused reservation gives the real reason, worked out right away so it describes the state that refused it:
+        another operation is named only when a write really holds the repository.
+        """
+        operation_id = uuid.uuid4().hex
+        key = WorktreeKey.from_context(context)
+        try:
+            self._authorize(context, window_mode, validate)
+            if selection is None:
+                raise ValueError("Select a historical file first")
+            if not self.mutation.acquire_context(context, git_filename, operation_id, action=OperationAction.WORKTREE_EDIT):
+                raise ValueError(self.mutation.acquire_context_refusal_cause(context, git_filename, operation_id, action=OperationAction.WORKTREE_EDIT))
+        except ValueError as error:
+            QTimer.singleShot(0, lambda error=error: callback(None, error))
+            return operation_id
+        self.mutation.live_reset_id_set.add(operation_id)
+
+        def complete(request: HistoricalRestoreRequest | None, error: Exception | None) -> None:
+            """Release the worktree while the owned candidate awaits confirmation."""
+            self.mutation.release(key, operation_id)
+            if error is None:
+                self.prepared_by_id[operation_id] = request
+            else:
+                self.mutation.live_reset_id_set.discard(operation_id)
+                self.mutation.reread_requested.emit(key)
+            callback(request, error)
+
+        sequence = self._prepare(operation_id, context, git_filename, selection, message, window_mode, validate, source_oid)
+        self.mutation.worktree_service.run(context, git_filename, sequence, complete, operation_id=operation_id)
+        return operation_id
+
+    def cancel(self, request: HistoricalRestoreRequest) -> None:
+        """Invalidate declined or stale confirmation without touching the working file."""
+        if self.prepared_by_id.pop(request.operation_id, None) is not request:
+            return
+        self.mutation.live_reset_id_set.discard(request.operation_id)
+        request.record_by_name["state"] = JournalState.ABANDONED.value
+        write_record(request.operation_dir, request.record_by_name)
+        self._clean(request)
+
+    def restore(self, request: HistoricalRestoreRequest) -> str:
+        """Reacquire publication ownership and refuse any changed capability or capture.
+
+        A refused reservation writes nothing and gives the real reason, followed by the folder of its recovery files.
+        """
+        if self.prepared_by_id.pop(request.operation_id, None) is not request:
+            raise ValueError("This restoration confirmation is no longer current")
+        snapshot = request.snapshot
+
+        def complete(outcome: MutationOutcome | None, error: Exception | None) -> None:
+            """Publish retained terminal results only after all asynchronous work ends."""
+            self.mutation.release(request.key, request.operation_id)
+            self.mutation.live_reset_id_set.discard(request.operation_id)
+            if error is not None:
+                outcome = self._failure(request, error, bool(request.record_by_name.get("working_file_published")))
+            self.outcome_by_id[request.operation_id] = outcome
+            self.mutation._publish_outcome(outcome)
+
+        if not self.mutation.acquire(snapshot, request.operation_id, action=OperationAction.WORKTREE_EDIT):
+            self.mutation.live_reset_id_set.discard(request.operation_id)
+            cause = self.mutation.acquire_refusal_cause(snapshot, request.operation_id, action=OperationAction.WORKTREE_EDIT)
+            outcome = self._failure(request, ValueError(cause), False)
+            self.outcome_by_id[request.operation_id] = outcome
+            QTimer.singleShot(0, lambda: self.mutation._publish_outcome(outcome))
+            return request.operation_id
+        self.mutation.worktree_service.run(snapshot.context, snapshot.git_filename, self._publish(request), complete, operation_id=request.operation_id)
+        return request.operation_id
+
+    def _authorize(self, context: RepositoryContext, window_mode: str, validate: Callable[[], bool]) -> None:
+        """Enforce management permission again at the write service boundary."""
+        if WindowCapability.RESTORE not in WINDOW_CAPABILITY_BY_MODE.get(window_mode, ()) or context.is_bare or context.worktree_dir is None:
+            raise ValueError("Historical restoration requires a repository window with a working tree")
+        if not validate():
+            raise ValueError("The selected historical file is no longer current")
+
+    def _prepare(self, operation_id: str, context: RepositoryContext, git_filename: str, selection: FileActionSelection,
+                 message: str, window_mode: str, validate: Callable[[], bool], source_oid: str | None = None) -> Generator:
+        """Resolve the explicit source tree while retaining the visible selection as the destination."""
+        selected_oid = validate_oid(selection.commit_oid)
+        commit_oid = validate_oid(source_oid) if source_oid is not None else selected_oid
+        if commit_oid != selected_oid:
+            raw_commit = yield GitCommand(["cat-file", "commit", selected_oid])
+            selected_commit = parse_commit(selected_oid, raw_commit, selected_oid)
+            if commit_oid not in selected_commit.parent_oids:
+                raise ValueError("The restoration source is not this commit or one of its direct parents")
+        path = selection.path()
+        validate_destination(context, path, allow_missing_parents=True)
+        source_path = path
+        if commit_oid != selected_oid and isinstance(selection.entry, RevisionEntry) and selection.entry.parent_oid == commit_oid and selection.entry.status == FileStatus.RENAMED:
+            source_path = selection.entry.old_path or path
+        output = yield GitCommand(["--literal-pathspecs", "ls-tree", "-z", commit_oid, "--", os.fsdecode(source_path)])
+        entries = parse_tree_entries(output)
+        if len(entries) != 1 or next(iter(entries)).path != source_path:
+            raise ValueError("This file is absent from the chosen source commit")
+        entry = next(iter(entries))
+        if entry.mode == "160000":
+            raise ValueError("A submodule points to a commit, not a file blob")
+        snapshot = yield from self.mutation.worktree_service.capture(context, git_filename)
+        recovery = self.mutation.recover(context, snapshot.index_filename, operation_id=operation_id)
+        if recovery:
+            raise ValueError(recovery)
+        attributes = yield GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=path + b"\0")
+        before = yield FileTask(lambda: capture_image(context, path, allow_missing_parents=True))
+        root_dir = os.path.join(context.git_dir, "gitpane-operation")
+        os.makedirs(root_dir, mode=PRIVATE_DIRECTORY_MODE, exist_ok=True)
+        operation_dir = os.path.join(root_dir, operation_id)
+        os.mkdir(operation_dir, PRIVATE_DIRECTORY_MODE)
+        record_by_name: dict[str, object] = {"schema_version": JOURNAL_SCHEMA_VERSION, "kind": JournalKind.FILE.value, "operation_id": operation_id,
+            "index_filename": snapshot.index_filename, "path_hex": path.hex(), "before": before.digest(), "after": None, "state": JournalState.PREPARING.value}
+        write_record(operation_dir, record_by_name)
+        try:
+            private_dir = private_file_dir(context, path, operation_dir, allow_missing_parents=True)
+            content_filename = os.path.join(private_dir, "blob-content")
+            candidate_filename = os.path.join(private_dir, "candidate")
+            backup_filename = os.path.join(private_dir, "before")
+            symlink_output = yield GitCommand(["config", "--bool", "--get", "core.symlinks"], accepted_codes=(0, 1))
+            after = yield from materialize_blob(entry.oid, path, entry.mode, content_filename, symlink_output.strip() != b"false")
+            if stat.S_ISREG(after.mode) and stat.S_ISREG(before.mode):
+                executable_mask = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+                permission_mode = stat.S_IMODE(before.mode) & ~executable_mask
+                if entry.mode == "100755":
+                    permission_mode |= executable_mask
+                after = replace(after, mode=stat.S_IFREG | permission_mode)
+            if before.exists:
+                yield FileTask(lambda: write_image(backup_filename, FileImage(True, stat.S_IFREG | PRIVATE_FILE_MODE, before.read())))
+            after = yield FileTask(lambda: prepare_publication_image(candidate_filename, after, before))
+            owned_identity_by_basename = {}
+            for filename in (content_filename, candidate_filename, backup_filename):
+                if os.path.lexists(filename):
+                    owned_identity_by_basename[os.path.basename(filename)] = stat_identity(os.lstat(filename))
+            record_by_name.update({"after": after.digest(), "state": JournalState.PREPARED.value, "private_dir": private_dir,
+                "private_identity": stat_identity(os.lstat(private_dir))[:FILE_OBJECT_IDENTITY_FIELDS],
+                "owned_identity_by_basename": owned_identity_by_basename})
+            request = HistoricalRestoreRequest(operation_id, snapshot.key, commit_oid, path, entry.oid, entry.mode, selection, before, after,
+                snapshot, attributes, message, window_mode, validate, operation_dir, private_dir, candidate_filename, record_by_name)
+            yield from self._check_preparation(request)
+            write_record(operation_dir, record_by_name)
+            return request
+        except (OSError, ValueError, RuntimeError):
+            record_by_name["state"] = JournalState.ABANDONED.value
+            write_record(operation_dir, record_by_name)
+            raise
+
+    def _check_preparation(self, request: HistoricalRestoreRequest) -> Generator:
+        """Check without a Git process that the confirmation still matches the capture: authority, index bytes, target file and private storage.
+
+        These checks only prepare the confirmation. Publication has Git verify the capture again under the index lock.
+        """
+        snapshot = request.snapshot
+        self._authorize(snapshot.context, request.window_mode, request.validate)
+        yield FileTask(lambda: verify_local_state(snapshot, ()))
+        yield FileTask(lambda: validate_image(snapshot.context, request.path, request.before))
+        yield FileTask(lambda: self._validate_storage(request))
+        self._authorize(snapshot.context, request.window_mode, request.validate)
+
+    def _validate(self, request: HistoricalRestoreRequest) -> Generator:
+        """Have Git verify the capture, then compare the target's own conversion attributes and its exact local file capture.
+
+        Called under the owned index lock just before publication. The capture is verified without paths on purpose: the
+        historical target can be clean or absent from the read, so its content is proved by its own file capture and its
+        attributes by the explicit check below.
+        """
+        snapshot = request.snapshot
+        self._authorize(snapshot.context, request.window_mode, request.validate)
+        yield from self.mutation.worktree_service.verify(snapshot, ())
+        attributes = yield GitCommand(["check-attr", "--all", "-z", "--stdin"], stdin=request.path + b"\0")
+        if attributes != request.attributes:
+            raise ValueError("File conversion attributes changed after selection")
+        yield FileTask(lambda: validate_image(snapshot.context, request.path, request.before))
+        self._authorize(snapshot.context, request.window_mode, request.validate)
+
+    def _publish(self, request: HistoricalRestoreRequest) -> Generator:
+        """Replace only the working file under an owned index lock, then prove index and HEAD stayed unchanged."""
+        snapshot = request.snapshot
+        lock_filename = snapshot.index_filename + ".lock"
+        lock_identity = None
+        published = False
+        created_dirs: list[tuple[str, tuple[int, int]]] = []
+        request.record_by_name["created_dirs"] = created_dirs
+        try:
+            descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+            try:
+                lock_identity = stat_identity(os.fstat(descriptor))[:FILE_OBJECT_IDENTITY_FIELDS]
+            finally:
+                os.close(descriptor)
+            yield from self._validate(request)
+            self._validate_storage(request)
+            if request.before.digest() == request.after.digest():
+                status = "unchanged"
+            else:
+                request.record_by_name["state"] = JournalState.PUBLISHING.value
+                write_record(request.operation_dir, request.record_by_name)
+                validate_image(snapshot.context, request.path, request.before)
+                expected = create_missing_parents(snapshot.context, request.path, request.before, created_dirs, lambda: write_record(request.operation_dir, request.record_by_name))
+                filename, _parents = validate_destination(snapshot.context, request.path)
+                validate_image(snapshot.context, request.path, expected)
+                self._authorize(snapshot.context, request.window_mode, request.validate)
+                if stat_identity(os.lstat(lock_filename))[:FILE_OBJECT_IDENTITY_FIELDS] != lock_identity:
+                    raise ValueError("The restoration index lock changed")
+                publish_image_mode(request.candidate_filename, request.after)
+                request.record_by_name["owned_identity_by_basename"][os.path.basename(request.candidate_filename)] = stat_identity(os.lstat(request.candidate_filename))
+                write_record(request.operation_dir, request.record_by_name)
+                validate_image(snapshot.context, request.path, expected)
+                self.mutation.validate_write(snapshot.key)
+                os.replace(request.candidate_filename, filename)
+                published = True
+                request.record_by_name["working_file_published"] = True
+                request.record_by_name["state"] = JournalState.FILE_PUBLISHED.value
+                write_record(request.operation_dir, request.record_by_name)
+                status = "success"
+            final_head = yield GitCommand(["rev-parse", "--verify", "--quiet", "HEAD"], accepted_codes=(0, 1))
+            if read_index(snapshot.index_filename) != snapshot.index_content or (final_head.strip().decode("ascii") or None) != snapshot.head_oid:
+                raise ValueError("HEAD or index changed during restoration; recovery files retained")
+            actual = yield FileTask(lambda: capture_image(snapshot.context, request.path))
+            if actual.digest() != request.after.digest():
+                raise ValueError("The working file changed during restoration; recovery files retained")
+            outcome = MutationOutcome(request.operation_id, request.key, status, (request.path,), ())
+        except (OSError, ValueError, RuntimeError) as error:
+            outcome = self._failure(request, error, published)
+        finally:
+            if not published:
+                clean_created_parents(created_dirs)
+            try:
+                if lock_identity is not None and os.path.lexists(lock_filename):
+                    if stat_identity(os.lstat(lock_filename))[:FILE_OBJECT_IDENTITY_FIELDS] != lock_identity:
+                        raise ValueError("The restoration index lock changed; cleanup refused")
+                    os.unlink(lock_filename)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._failure(request, error, published)
+        if outcome.diagnostic is None:
+            try:
+                # Recovery content stays owned until the index lock has been released successfully.
+                request.record_by_name["state"] = JournalState.COMPLETE.value
+                write_record(request.operation_dir, request.record_by_name)
+                self._clean(request)
+            except (OSError, ValueError, RuntimeError) as error:
+                outcome = self._failure(request, error, published)
+        return outcome
+
+    def _validate_storage(self, request: HistoricalRestoreRequest) -> None:
+        """Refuse private directory or candidate substitutions before exposing any prepared content."""
+        record = request.record_by_name
+        if os.path.islink(request.private_dir) or os.path.isjunction(request.private_dir) or stat_identity(os.lstat(request.private_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != record["private_identity"]:
+            raise ValueError("Private restoration storage changed")
+        for basename, identity in record["owned_identity_by_basename"].items():
+            if stat_identity(os.lstat(os.path.join(request.private_dir, basename))) != identity:
+                raise ValueError("Private restoration content changed")
+
+    def _clean(self, request: HistoricalRestoreRequest) -> None:
+        """Remove only still-owned private artifacts after success or cancellation."""
+        record = request.record_by_name
+        if os.path.islink(request.private_dir) or os.path.isjunction(request.private_dir) or stat_identity(os.lstat(request.private_dir))[:FILE_OBJECT_IDENTITY_FIELDS] != record["private_identity"]:
+            raise ValueError("Private restoration storage changed; cleanup refused")
+        for basename, identity in request.record_by_name["owned_identity_by_basename"].items():
+            filename = os.path.join(request.private_dir, basename)
+            if os.path.lexists(filename):
+                if stat_identity(os.lstat(filename)) != identity:
+                    raise ValueError("Private restoration content changed; cleanup refused")
+                os.unlink(filename)
+        if request.private_dir != request.operation_dir:
+            os.rmdir(request.private_dir)
+
+    def _failure(self, request: HistoricalRestoreRequest, error: Exception, published: bool) -> MutationOutcome:
+        """Retain backups on any uncertain result without undoing a later external edit."""
+        request.record_by_name["state"] = (JournalState.FILE_PUBLISHED if published else JournalState.ABANDONED).value
+        try:
+            write_record(request.operation_dir, request.record_by_name)
+        except OSError:
+            pass
+        diagnostic = error.diagnostic if isinstance(error, GitCommandError) else Diagnostic(RESTORE_SELECTED_VERSION_TITLE, request.snapshot.context.repository_dir,
+            request.snapshot.git_filename, [], str(error)).prepare()
+        diagnostic = replace(diagnostic, cause=recovery_files_cause(diagnostic.cause, request.operation_dir))
+        return MutationOutcome(request.operation_id, request.key, "unknown" if published else "refused", (request.path,) if published else (), (request.path,), diagnostic, request.operation_dir)