gitpane 1.0.0__py3-none-any.whl

gitpane/history_rewrite/recovery.py

@@ -0,0 +1,481 @@
+"""Reconcile durable evidence of an interrupted history publication."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from dataclasses import asdict, dataclass, fields, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.config import LOCAL_PREFIX, MUTATION_RECORD_LIMIT_BYTES
+from gitpane.history.file_history import WindowCapability
+from gitpane.history.repository_value import validate_oid
+from gitpane.history_rewrite.guard import GIT_STORAGE_ARGUMENTS, git_storage_matches, other_worktree_dir_by_branch, parse_worktree_listing
+from gitpane.history_rewrite.index import index_digest
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction, WriteScope
+from gitpane.process.process_runner import READ_PROFILE
+from gitpane.reference.reference_edit import reference_signature
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.mutation import write_record
+from gitpane.worktree.worktree_file import FILE_MODE_IDENTITY_FIELD, FILE_OBJECT_IDENTITY_FIELDS, PRIVATE_DIRECTORY_MODE
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.history_rewrite.publish import RewritePublicationOutcome
+    from gitpane.operation.repository_operation import OperationIntent, RepositoryOperationService
+
+HISTORY_REWRITE_STORAGE_BASENAME = "history-rewrite"
+RECOVERY_SCHEMA_VERSION = 1
+PRIVATE_REF_PREFIX = "refs/gitpane/history-rewrite/"
+RECOVERY_REF_FORMAT = "%(refname)%00%(objectname)%00%(symref)"
+EMPTY_LOCK_DIGEST = hashlib.sha256(b"").hexdigest()
+LOCK_IDENTITY_FIELD_COUNT = 3
+
+
+class RewritePublicationState(Enum):
+    """Name durable transitions without claiming a transaction across refs and index."""
+
+    PREPARED = "prepared"
+    IMPORTING = "importing"
+    IMPORTED = "imported"
+    REFS_PENDING = "refs_pending"
+    REFS_COMMITTED = "refs_committed"
+    INDEX_PENDING = "index_pending"
+    INDEX_PUBLISHED = "index_published"
+    COMPENSATING = "compensating"
+    RESTORED = "restored"
+    COMPLETE = "complete"
+    NEEDS_RECOVERY = "needs_recovery"
+
+
+@dataclass(frozen=True)
+class RewriteRecoveryRecord:
+    """Keep exact before/after identities outside Git for a single publication token."""
+
+    schema_version: int
+    operation_id: str
+    operation_dir: str
+    context_identity: tuple[str, str, str]
+    git_filename: str
+    head_ref: str
+    old_oid_by_ref: dict[str, str]
+    new_oid_by_ref: dict[str, str]
+    original_index_identity: str | None
+    candidate_index_identity: str | None
+    owned_lock_identity: tuple[int, int, int] | None
+    state: RewritePublicationState
+    private_ref_by_name: dict[str, str]
+    detail: str = ""
+    owned_lock_digest: str | None = None
+
+
+@dataclass(frozen=True)
+class RecoveryObservation:
+    """Report observed public state independently of the last journal transition."""
+
+    ref_oid_by_name: dict[str, str]
+    index_identity: str | None
+    restorable: bool
+    detail: str
+    head_ref: str | None
+    lock_identity: tuple[int, int, int] | None
+    private_ref_by_name: dict[str, str]
+    authority: tuple = ()
+    worktrees: tuple[bytes, ...] = ()
+
+
+@dataclass(frozen=True)
+class RecoveryDiscovery:
+    """Retain unreadable operation folders as visible diagnostics during discovery."""
+
+    operation_dir: str
+    record: RewriteRecoveryRecord | None
+    detail: str = ""
+
+
+class RecoveryContextMismatch(ValueError):
+    """Distinguish another repository's valid record from corrupt recovery data."""
+
+
+def context_identity(context: RepositoryContext) -> tuple[str, str, str]:
+    """Bind a record to the exact active repository and its two storage directories."""
+    return canonical_path(context.repository_dir), canonical_path(context.git_dir), canonical_path(context.common_git_dir)
+
+
+def digest_text(identity: bytes | None) -> str | None:
+    """Serialize an absent index distinctly from every byte digest."""
+    return identity.hex() if identity is not None else None
+
+
+def lock_identity(filename: str) -> tuple[int, int, int] | None:
+    """Identify a lock entry without following a replacement symlink."""
+    try:
+        information = os.lstat(filename)
+    except FileNotFoundError:
+        return None
+    return information.st_dev, information.st_ino, stat.S_IFMT(information.st_mode)
+
+
+def sync_directory(directory: str) -> None:
+    """Persist renamed entries on systems that support opening directory descriptors."""
+    if not hasattr(os, "O_DIRECTORY"):
+        return
+    descriptor = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def validate_storage_root(storage_root_dir: str, context: RepositoryContext) -> str:
+    """Require recovery storage outside the worktree and all of its Git storage."""
+    storage_root_dir = canonical_path(storage_root_dir)
+    for source_dir in context_identity(context):
+        try:
+            inside = os.path.commonpath((source_dir, storage_root_dir)) == source_dir
+        except ValueError:
+            inside = False
+        if inside:
+            raise ValueError("History recovery storage must be outside the repository and its Git storage")
+    return storage_root_dir
+
+
+def create_recovery_directory(storage_root_dir: str, operation_id: str, context: RepositoryContext) -> str:
+    """Claim a private durable operation folder without reusing an earlier publication."""
+    if re.fullmatch(r"[0-9a-f]{32}", operation_id) is None:
+        raise ValueError("Invalid history publication identifier; build a new preview")
+    storage_root_dir = validate_storage_root(storage_root_dir, context)
+    os.makedirs(storage_root_dir, mode=PRIVATE_DIRECTORY_MODE, exist_ok=True)
+    operation_dir = os.path.join(storage_root_dir, operation_id)
+    os.mkdir(operation_dir, PRIVATE_DIRECTORY_MODE)
+    os.mkdir(os.path.join(operation_dir, "hooks"), PRIVATE_DIRECTORY_MODE)
+    sync_directory(storage_root_dir)
+    return operation_dir
+
+
+def write_recovery_record(record: RewriteRecoveryRecord) -> None:
+    """Flush a bounded private JSON record before performing its announced action."""
+    if os.path.islink(record.operation_dir) or not os.path.isdir(record.operation_dir):
+        raise ValueError("Recovery directory changed; retain the recovery files for inspection")
+    record_by_name = asdict(record)
+    record_by_name["state"] = record.state.value
+    if len(json.dumps(record_by_name, sort_keys=True).encode("utf-8")) > MUTATION_RECORD_LIMIT_BYTES:
+        raise ValueError("History recovery record exceeds its size limit; retain the recovery files")
+    for basename in ("record.json", "record.next"):
+        filename = os.path.join(record.operation_dir, basename)
+        if os.path.lexists(filename):
+            information = os.lstat(filename)
+            if not stat.S_ISREG(information.st_mode) or information.st_nlink != 1:
+                raise ValueError("Linked or nonregular recovery record; inspect the recovery files")
+    write_record(record.operation_dir, record_by_name)
+    sync_directory(record.operation_dir)
+
+
+def transition_record(record: RewriteRecoveryRecord, state: RewritePublicationState, **changes: object) -> RewriteRecoveryRecord:
+    """Persist a transition before returning it to the caller."""
+    record = replace(record, state=state, **changes)
+    write_recovery_record(record)
+    return record
+
+
+def _unique_record_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    """Refuse duplicate JSON fields instead of silently trusting the last occurrence."""
+    value_by_name = {}
+    for name, value in pairs:
+        if name in value_by_name:
+            raise ValueError("Duplicate recovery record field; inspect it before continuing")
+        value_by_name[name] = value
+    return value_by_name
+
+
+def _validate_record_reference(reference: str, prefix: str) -> None:
+    """Check the native reference namespace using Git's ASCII restrictions, preserving non-ASCII bytes."""
+    forbidden_byte_set = set(b" ~^:?*[\\")
+    encoded = os.fsencode(reference)
+    if (not reference.startswith(prefix) or any(value <= 32 or value == 127 or value in forbidden_byte_set for value in encoded)
+            or ".." in reference or "@{" in reference or reference.endswith(".")):
+        raise ValueError("Recovery reference is outside its allowed namespace")
+    for part in reference.split("/"):
+        if not part or part.startswith(".") or part.endswith(".lock"):
+            raise ValueError("Invalid recovery reference name")
+
+
+def read_recovery_record(operation_dir: str, context: RepositoryContext) -> RewriteRecoveryRecord:
+    """Read only a supported journal bound to this repository and operation folder."""
+    validate_storage_root(os.path.dirname(operation_dir), context)
+    filename = os.path.join(operation_dir, "record.json")
+    if os.path.islink(operation_dir):
+        raise ValueError("Linked recovery directory; inspect it before continuing")
+    information = os.lstat(filename)
+    if not stat.S_ISREG(information.st_mode) or information.st_nlink != 1 or information.st_size > MUTATION_RECORD_LIMIT_BYTES:
+        raise ValueError("Linked, oversized or nonregular recovery record; inspect it before continuing")
+    with open(filename, "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        current = os.lstat(filename)
+        if (opened.st_dev, opened.st_ino) != (information.st_dev, information.st_ino) or not stat.S_ISREG(current.st_mode):
+            raise ValueError("Recovery record was replaced while opening it; inspect it before continuing")
+        content = stream.read(MUTATION_RECORD_LIMIT_BYTES + 1)
+    if len(content) > MUTATION_RECORD_LIMIT_BYTES:
+        raise ValueError("Oversized recovery record; inspect it before continuing")
+    record_by_name = json.loads(content, object_pairs_hook=_unique_record_pairs)
+    if not isinstance(record_by_name, dict) or set(record_by_name) != {field.name for field in fields(RewriteRecoveryRecord)}:
+        raise ValueError("Unrecognized recovery record fields; inspect it before continuing")
+    if type(record_by_name["schema_version"]) is not int or record_by_name["schema_version"] != RECOVERY_SCHEMA_VERSION:
+        raise ValueError("Unsupported recovery record version; inspect it before continuing")
+    if record_by_name["operation_id"] != os.path.basename(operation_dir) or re.fullmatch(r"[0-9a-f]{32}", record_by_name["operation_id"]) is None:
+        raise ValueError("Recovery operation identifier does not match its folder")
+    # The folder is recorded with its canonical spelling, lower case under Windows: compare folders, not spellings.
+    if not isinstance(record_by_name["operation_dir"], str) or canonical_path(record_by_name["operation_dir"]) != canonical_path(operation_dir):
+        raise ValueError("Recovery record does not belong to this repository")
+    if record_by_name["context_identity"] != list(context_identity(context)):
+        raise RecoveryContextMismatch("Recovery record belongs to another repository")
+    record_by_name["context_identity"] = tuple(record_by_name["context_identity"])
+    record_by_name["state"] = RewritePublicationState(record_by_name["state"])
+    identity = record_by_name["owned_lock_identity"]
+    if identity is not None:
+        if (not isinstance(identity, list) or len(identity) != LOCK_IDENTITY_FIELD_COUNT or any(type(value) is not int or value < 0 for value in identity)
+                or identity[FILE_MODE_IDENTITY_FIELD] != stat.S_IFREG):
+            raise ValueError("Invalid recorded index lock identity")
+        record_by_name["owned_lock_identity"] = tuple(identity)
+    for name in ("original_index_identity", "candidate_index_identity", "owned_lock_digest"):
+        identity = record_by_name[name]
+        if identity is not None and (not isinstance(identity, str) or re.fullmatch(r"[0-9a-f]{64}", identity) is None):
+            raise ValueError("Invalid recorded index digest")
+    for name in ("old_oid_by_ref", "new_oid_by_ref", "private_ref_by_name"):
+        oid_by_ref = record_by_name[name]
+        if not isinstance(oid_by_ref, dict):
+            raise ValueError("Invalid recovery reference map")  # noqa: TRY004 — malformed persisted JSON is a recoverable data error.
+        prefix = PRIVATE_REF_PREFIX + record_by_name["operation_id"] + "/" if name == "private_ref_by_name" else LOCAL_PREFIX
+        for reference, oid in oid_by_ref.items():
+            _validate_record_reference(reference, prefix)
+            validate_oid(oid)
+    if set(record_by_name["old_oid_by_ref"]) != set(record_by_name["new_oid_by_ref"]) or record_by_name["head_ref"] not in record_by_name["old_oid_by_ref"]:
+        raise ValueError("Recovery reference sets do not describe one captured repository")
+    return RewriteRecoveryRecord(**record_by_name)
+
+
+def observe_recovery(record: RewriteRecoveryRecord, context: RepositoryContext) -> Generator[GitCommand | FileTask, object, RecoveryObservation]:
+    """Inspect actual refs, HEAD and index instead of trusting a pending journal state."""
+    if record.context_identity != context_identity(context):
+        raise ValueError("Recovery record belongs to another repository")
+    authority = yield FileTask(lambda: reference_signature(context))
+    locations = yield GitCommand(list(GIT_STORAGE_ARGUMENTS), profile=READ_PROFILE)
+    if not git_storage_matches(context, locations):
+        raise ValueError("Repository storage changed; reopen the repository before recovery")
+    output = yield GitCommand(["for-each-ref", "--format=" + RECOVERY_REF_FORMAT, LOCAL_PREFIX, PRIVATE_REF_PREFIX + record.operation_id + "/"])
+    ref_oid_by_name = {}
+    private_ref_by_name = {}
+    detail = ""
+    for line in output.splitlines():
+        name, oid, symbolic = line.split(b"\0")
+        name = os.fsdecode(name)
+        if symbolic:
+            detail = "A reference became symbolic; inspect references before recovery"
+        if name.startswith(LOCAL_PREFIX):
+            ref_oid_by_name[name] = validate_oid(oid.decode("ascii"))
+        else:
+            private_ref_by_name[name] = validate_oid(oid.decode("ascii"))
+    head = (yield GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))).removesuffix(b"\n")
+    head_ref = os.fsdecode(head) if head else None
+    worktrees = parse_worktree_listing((yield GitCommand(["worktree", "list", "--porcelain", "-z"])))
+    index_filename = os.path.join(context.git_dir, "index")
+    identity = yield FileTask(lambda: digest_text(index_digest(index_filename)))
+    actual_lock_identity = yield FileTask(lambda: lock_identity(index_filename + ".lock"))
+    if head_ref != record.head_ref:
+        detail = "HEAD changed outside the operation; inspect the active branch before recovery"
+    if actual_lock_identity is not None and actual_lock_identity != record.owned_lock_identity:
+        detail = "An index lock belongs to another writer; wait for that writer before recovery"
+    elif actual_lock_identity is not None:
+        lock_digest = yield FileTask(lambda: digest_text(index_digest(index_filename + ".lock")))
+        if lock_digest != record.owned_lock_digest:
+            detail = "Index lock content changed outside the operation; inspect it before recovery"
+    restorable = (not detail and record.state not in (RewritePublicationState.COMPLETE, RewritePublicationState.RESTORED)
+                  and ref_oid_by_name == record.new_oid_by_ref and identity == record.original_index_identity and identity != record.candidate_index_identity)
+    if restorable:
+        worktree_dir_by_branch = other_worktree_dir_by_branch(context, worktrees)
+        for name in sorted(record.old_oid_by_ref):
+            if record.old_oid_by_ref[name] != record.new_oid_by_ref[name] and name in worktree_dir_by_branch:
+                detail = (f"{name} is checked out in another worktree: {worktree_dir_by_branch[name]}. Restoring it would change that checkout's branch without its index. "
+                          "Release that branch in the other worktree, then refresh recovery. No branches were restored.")
+                restorable = False
+                break
+    if (yield FileTask(lambda: reference_signature(context))) != authority:
+        raise ValueError("References, HEAD or worktrees changed during recovery inspection; refresh recovery")
+    return RecoveryObservation(ref_oid_by_name, identity, restorable, detail, head_ref, actual_lock_identity, private_ref_by_name, authority, worktrees)
+
+
+def coherent_recovery_state(record: RewriteRecoveryRecord, observation: RecoveryObservation) -> RewritePublicationState | None:
+    """Identify already consistent public data that needs no branch restoration."""
+    if observation.detail:
+        return None
+    if observation.ref_oid_by_name == record.old_oid_by_ref and observation.index_identity == record.original_index_identity:
+        return RewritePublicationState.RESTORED
+    if observation.ref_oid_by_name == record.new_oid_by_ref and observation.index_identity == record.candidate_index_identity:
+        return RewritePublicationState.COMPLETE
+    return None
+
+
+def validate_recovery_observation(record: RewriteRecoveryRecord, observation: RecoveryObservation, operation: OperationIntent,
+                                  repository_operation: RepositoryOperationService) -> None:
+    """Reject changed evidence immediately before cleanup or a terminal journal write."""
+    validate_recovery_authority(record, operation, repository_operation)
+    if read_recovery_record(record.operation_dir, operation.context) != record or reference_signature(operation.context) != observation.authority:
+        raise ValueError("Recovery evidence changed; refresh recovery before continuing")
+    index_filename = os.path.join(operation.context.git_dir, "index")
+    actual_lock = lock_identity(index_filename + ".lock")
+    if digest_text(index_digest(index_filename)) != observation.index_identity or actual_lock != observation.lock_identity:
+        raise ValueError("Index or lock changed during recovery; retain recovery data")
+    if actual_lock is not None and (actual_lock != record.owned_lock_identity or digest_text(index_digest(index_filename + ".lock")) != record.owned_lock_digest):
+        raise ValueError("Index lock content changed; retain it for inspection")
+
+
+def discover_recovery(storage_root_dir: str, context: RepositoryContext) -> tuple[RecoveryDiscovery, ...]:
+    """List unfinished operations without deleting malformed or unknown recovery evidence."""
+    storage_root_dir = validate_storage_root(storage_root_dir, context)
+    if not os.path.exists(storage_root_dir):
+        return ()
+    discoveries = []
+    with os.scandir(storage_root_dir) as entries:
+        for entry in entries:
+            try:
+                if not entry.is_dir(follow_symlinks=False):
+                    raise ValueError("Unexpected entry in recovery storage; inspect it before continuing")
+                record = read_recovery_record(entry.path, context)
+                if record.state not in (RewritePublicationState.COMPLETE, RewritePublicationState.RESTORED):
+                    discoveries.append(RecoveryDiscovery(entry.path, record))
+            except RecoveryContextMismatch:
+                continue
+            except (OSError, ValueError, TypeError, KeyError, AttributeError) as error:
+                discoveries.append(RecoveryDiscovery(entry.path, None, "Cannot inspect history recovery: " + str(error)))
+    return tuple(sorted(discoveries, key=lambda discovery: discovery.operation_dir))
+
+
+def validate_recovery_authority(record: RewriteRecoveryRecord, operation: OperationIntent, repository_operation: RepositoryOperationService) -> None:
+    """Require the same executable, context and full reference scope for every recovery write."""
+    repository_operation.validate(operation)
+    if (record.context_identity != context_identity(operation.context) or record.git_filename != operation.git_filename
+            or operation.action != OperationAction.REF_WRITE or operation.capability != WindowCapability.MANAGE
+            or operation.scope != WriteScope.capture(operation.context, (LOCAL_PREFIX + "*",))):
+        raise ValueError("History recovery authority changed; reopen the repository before continuing")
+
+
+def release_recovery_lock(record: RewriteRecoveryRecord, context: RepositoryContext) -> None:
+    """Release an interrupted writer's exact regular lock, never a replacement entry."""
+    from gitpane.worktree.mutation import release_owned_index_lock
+
+    filename = os.path.join(context.git_dir, "index.lock")
+    actual_identity = lock_identity(filename)
+    if actual_identity is None:
+        return
+    if actual_identity != record.owned_lock_identity:
+        raise ValueError("Index lock belongs to another writer; wait before retrying recovery")
+    if digest_text(index_digest(filename)) != record.owned_lock_digest:
+        raise ValueError("Index lock content changed; retain it for inspection")
+    release_owned_index_lock(filename, None, record.owned_lock_identity[:FILE_OBJECT_IDENTITY_FIELDS])
+    sync_directory(context.git_dir)
+
+
+def finish_coherent_recovery(record: RewriteRecoveryRecord, observation: RecoveryObservation, state: RewritePublicationState,
+                             operation: OperationIntent, repository_operation: RepositoryOperationService, *, detail: str = "") -> Generator[GitCommand | FileTask, object, RewriteRecoveryRecord]:
+    """Close recovery only while fresh public state, journal and owned resources remain coherent."""
+    from gitpane.history_rewrite.publish import cleanup_private_refs
+
+    if coherent_recovery_state(record, observation) != state:
+        raise ValueError("Repository is not coherent; retain recovery data")
+
+    def validate() -> None:
+        """Use the latest complete observation at each write boundary."""
+        validate_recovery_observation(record, observation, operation, repository_operation)
+
+    yield from cleanup_private_refs(record, observation, before_start=validate)
+    observation = yield from observe_recovery(record, operation.context)
+    if coherent_recovery_state(record, observation) != state or observation.private_ref_by_name:
+        raise ValueError("Repository changed during recovery cleanup; retain recovery data")
+
+    def release_lock() -> None:
+        """Revalidate before releasing only the interrupted operation's lock."""
+        validate()
+        release_recovery_lock(record, operation.context)
+
+    yield FileTask(release_lock)
+    observation = yield from observe_recovery(record, operation.context)
+    if coherent_recovery_state(record, observation) != state or observation.private_ref_by_name or observation.lock_identity is not None:
+        raise ValueError("Repository changed before recovery finished; retain recovery data")
+
+    def finish() -> RewriteRecoveryRecord:
+        """Record completion only while the final public state still matches."""
+        validate()
+        return transition_record(record, state, detail=detail)
+
+    return (yield FileTask(finish))
+
+
+def recover_rewrite(record: RewriteRecoveryRecord, operation: OperationIntent, repository_operation: RepositoryOperationService,
+                    *, restore: bool = False, expected_observation: RecoveryObservation | None = None) -> Generator[GitCommand | FileTask, object, RewritePublicationOutcome]:
+    """Reobserve pending work, restoring incomplete publication only when its caller authorizes it."""
+    from gitpane.history_rewrite.publish import RewritePublicationOutcome, compensate_rewrite
+
+    trusted = False
+    try:
+        fresh_record = yield FileTask(lambda: read_recovery_record(record.operation_dir, operation.context))
+        if fresh_record != record:
+            raise ValueError("Recovery record changed; refresh recovery before continuing")
+        trusted = True
+        validate_recovery_authority(record, operation, repository_operation)
+        observation = yield from observe_recovery(record, operation.context)
+        if expected_observation is not None and observation != expected_observation:
+            raise ValueError("Recovery state changed since observation; refresh recovery")
+        if observation.detail:
+            raise ValueError(observation.detail)
+        state = coherent_recovery_state(record, observation)
+        if state is None and observation.restorable and restore:
+            return (yield from compensate_rewrite(record, observation, operation, repository_operation))
+        if state is None:
+            detail = "Branches were published but the index is original. Review recovery and confirm Restore previous branches."
+            if not observation.restorable:
+                changed_refs = []
+                for name in sorted(set(observation.ref_oid_by_name) | set(record.old_oid_by_ref)):
+                    observed_oid = observation.ref_oid_by_name.get(name, "absent")
+                    if observed_oid not in (record.old_oid_by_ref.get(name), record.new_oid_by_ref.get(name)):
+                        changed_refs.append(f"{name}={observed_oid}")
+                detail = "References or index differ from a complete before/after state; inspect recovery without overwriting external changes."
+                if changed_refs:
+                    detail += " Changed references: " + ", ".join(changed_refs)
+            raise ValueError(detail)
+        record = yield from finish_coherent_recovery(record, observation, state, operation, repository_operation)
+        status = OperationStatus.SUCCESS if state == RewritePublicationState.COMPLETE else OperationStatus.FAILED
+        return RewritePublicationOutcome(operation.operation_id, status, record=record)
+    except (OSError, ValueError, RuntimeError, TypeError, KeyError) as error:
+        if trusted:
+            return (yield from retain_recovery_failure(record, operation, error))
+        diagnostic = Diagnostic(operation.operation, operation.context.repository_dir, operation.git_filename, [], str(error)).prepare()
+        return RewritePublicationOutcome(operation.operation_id, OperationStatus.UNKNOWN, diagnostic=diagnostic, record=record)
+
+
+def retain_recovery_failure(record: RewriteRecoveryRecord, operation: OperationIntent, error: Exception) -> Generator[FileTask, object, RewritePublicationOutcome]:
+    """Persist failure against the caller's latest journal without replacing an external edit."""
+    from gitpane.history_rewrite.publish import RewritePublicationOutcome
+
+    detail = str(error)
+    try:
+        def retain_failure() -> RewriteRecoveryRecord:
+            """Change only the exact journal last written or inspected by this operation."""
+            current = read_recovery_record(record.operation_dir, operation.context)
+            if current != record:
+                return current
+            return transition_record(record, RewritePublicationState.NEEDS_RECOVERY, detail=detail)
+
+        record = yield FileTask(retain_failure)
+    except (OSError, ValueError, RuntimeError, TypeError, KeyError):
+        detail += "; cannot persist recovery status, retain the existing record for inspection"
+    diagnostic = Diagnostic(operation.operation, operation.context.repository_dir, operation.git_filename, [], detail).prepare()
+    return RewritePublicationOutcome(operation.operation_id, OperationStatus.UNKNOWN, diagnostic=diagnostic, record=record)