gitpane 1.0.0__py3-none-any.whl

gitpane/history_rewrite/publish.py

@@ -0,0 +1,444 @@
+"""Publish an authorized private history proposal without writing working files."""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.config import EXACT_PATH_CASE_ARGUMENTS, GIT_MUTATION_TIMEOUT_MS, LOCAL_PREFIX, MUTATION_IDLE_TIMEOUT_MS, SUBMODULE_RECURSION_OFF_ARGUMENTS
+from gitpane.history.file_history import WindowCapability
+from gitpane.history.repository_value import validate_oid
+from gitpane.history_rewrite.guard import capture_rewrite_state, publication_authority, validate_publication_authority, validate_rewrite_capture
+from gitpane.history_rewrite.index import index_digest
+from gitpane.history_rewrite.prepare import OWNER_BASENAME, OWNER_CONTENT, PRIVATE_REF
+from gitpane.history_rewrite.protocol import copy_bytes, read_line
+from gitpane.history_rewrite.recovery import (
+    EMPTY_LOCK_DIGEST,
+    PRIVATE_REF_PREFIX,
+    RECOVERY_SCHEMA_VERSION,
+    RewritePublicationState,
+    RewriteRecoveryRecord,
+    context_identity,
+    create_recovery_directory,
+    digest_text,
+    finish_coherent_recovery,
+    lock_identity,
+    observe_recovery,
+    recover_rewrite,
+    release_recovery_lock,
+    retain_recovery_failure,
+    sync_directory,
+    transition_record,
+    validate_recovery_authority,
+    write_recovery_record,
+)
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction, OperationIntent, OperationOutcome, WriteScope
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE
+from gitpane.reference.reference_edit import reference_signature
+from gitpane.reference.reference_snapshot import REFERENCE_FORMAT, parse_reference_read
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.file_menu_action import FileAction
+from gitpane.worktree.mutation import fill_owned_lock, release_owned_index_lock
+from gitpane.worktree.worktree_file import FILE_OBJECT_IDENTITY_FIELDS, PRIVATE_FILE_MODE
+from gitpane.worktree.worktree_snapshot import read_index
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history_rewrite.recovery import RecoveryObservation
+    from gitpane.history_rewrite.value import RewritePreparation
+    from gitpane.operation.repository_operation import RepositoryOperationService
+
+
+@dataclass(frozen=True)
+class RewritePublicationOutcome(OperationOutcome):
+    """Expose the reconciled journal location alongside the common operation status."""
+
+    record: RewriteRecoveryRecord | None = None
+
+
+class RewriteProgress(Enum):
+    """Name actual publication steps shared by the service and its presentation."""
+
+    CHECKING = "Checking repository…"
+    IMPORTING = "Importing rewritten commits…"
+    REFERENCES = "Updating local branches…"
+    INDEX = "Updating index…"
+    REFRESHING = "Refreshing repository…"
+    FINISHING = "Finishing repository update…"
+
+
+def rewrite_operation(preparation: RewritePreparation, operation_id: str, *, session_id: str | None = None) -> OperationIntent:
+    """Capture all local branch authority under the common repository reservation."""
+    capture = preparation.capture
+    return OperationIntent.capture(operation_id, capture.context, capture.git_filename, generation=capture.generation, session_id=session_id,
+                                   action=OperationAction.REF_WRITE, capability=WindowCapability.MANAGE, operation=FileAction.REMOVE_FROM_HISTORY.label, from_form=True,
+                                   targets=(preparation.operation_dir, preparation.operation_identity), scope=WriteScope.capture(capture.context, (LOCAL_PREFIX + "*",)))
+
+
+def _validate_preparation(preparation: RewritePreparation, operation: OperationIntent) -> None:
+    """Refuse incomplete, replaced or differently authorized proposals before writing source storage."""
+    if not preparation.complete or preparation.index is None or not preparation.branches:
+        raise ValueError("No complete history changes to publish; build a new preview")
+    capture = preparation.capture
+    if (operation.context != capture.context or operation.git_filename != capture.git_filename or operation.generation != capture.generation
+            or operation.action != OperationAction.REF_WRITE or operation.capability != WindowCapability.MANAGE
+            or operation.targets != (preparation.operation_dir, preparation.operation_identity)
+            or operation.scope != WriteScope.capture(capture.context, (LOCAL_PREFIX + "*",))):
+        raise ValueError("Publication authority differs from the preview; build a new preview")
+    information = os.lstat(preparation.operation_dir)
+    if not stat.S_ISDIR(information.st_mode) or (information.st_dev, information.st_ino) != preparation.operation_identity:
+        raise ValueError("Private preparation was replaced; build a new preview")
+    with open(os.path.join(preparation.operation_dir, OWNER_BASENAME), "rb") as stream:
+        if stream.read(len(OWNER_CONTENT) + 1) != OWNER_CONTENT:
+            raise ValueError("Private preparation ownership changed; build a new preview")
+    if index_digest(preparation.index.candidate_filename) != preparation.index.candidate_identity:
+        raise ValueError("Private candidate index changed; build a new preview")
+
+
+def _new_record(preparation: RewritePreparation, operation: OperationIntent, storage_root_dir: str) -> RewriteRecoveryRecord:
+    """Consume the preparation token before creating the durable publication evidence."""
+    _validate_preparation(preparation, operation)
+    # A claim inside the owned preparation also rejects reuse under a different operation ID.
+    try:
+        with open(os.path.join(preparation.operation_dir, "publication.claim"), "xb") as stream:
+            stream.write(operation.operation_id.encode("ascii"))
+            stream.flush()
+            os.fsync(stream.fileno())
+    except FileExistsError as error:
+        raise ValueError("This preview has already been submitted; build a new preview") from error
+    sync_directory(preparation.operation_dir)
+    operation_dir = create_recovery_directory(storage_root_dir, operation.operation_id, operation.context)
+    old_oid_by_ref = dict(preparation.capture.local_ref_by_name)
+    new_oid_by_ref = dict(old_oid_by_ref)
+    private_ref_by_name = {}
+    for number, branch in enumerate(preparation.branches):
+        if branch.name not in old_oid_by_ref or branch.old_oid != old_oid_by_ref[branch.name] or not branch.name.startswith(LOCAL_PREFIX):
+            raise ValueError("A prepared branch no longer matches its capture; build a new preview")
+        new_oid_by_ref[branch.name] = validate_oid(branch.new_oid)
+        prefix = PRIVATE_REF_PREFIX + operation.operation_id + "/"
+        private_ref_by_name[prefix + "old-" + str(number)] = branch.old_oid
+        private_ref_by_name[prefix + "new-" + str(number)] = branch.new_oid
+    record = RewriteRecoveryRecord(RECOVERY_SCHEMA_VERSION, operation.operation_id, operation_dir, context_identity(operation.context), operation.git_filename,
+                                   preparation.capture.head_ref, old_oid_by_ref, new_oid_by_ref, digest_text(preparation.index.original_identity),
+                                   digest_text(preparation.index.candidate_identity), None, RewritePublicationState.PREPARED, private_ref_by_name)
+    _make_source_stream(preparation, record)
+    write_recovery_record(record)
+    return record
+
+
+def _make_source_stream(preparation: RewritePreparation, record: RewriteRecoveryRecord) -> None:
+    """Copy the closed generated grammar, rebinding only reference directives outside length-delimited messages."""
+    import_ref = PRIVATE_REF_PREFIX + record.operation_id + "/import"
+    mark_by_oid = {}
+    for private_mark, oid in _read_marks(os.path.join(preparation.operation_dir, "marks.out")).items():
+        mark_by_oid[oid] = private_mark
+    mark = None
+    with open(preparation.stream_filename, "rb") as source, open(os.path.join(record.operation_dir, "import.in"), "xb") as destination:
+        while line := read_line(source):
+            if line == b"done\n":
+                if source.read(1):
+                    raise ValueError("Unexpected data after the prepared import; build a new preview")
+                for reference, oid in record.private_ref_by_name.items():
+                    # New objects in the open pack are addressed by marks until fast-import closes it.
+                    target = mark_by_oid.get(oid, oid)
+                    destination.write(b"reset " + reference.encode("ascii") + b"\nfrom " + target.encode("ascii") + b"\n\n")
+                destination.write(b"done\n")
+                break
+            if line.startswith((b"reset ", b"commit ")):
+                verb, reference = line.removesuffix(b"\n").split(b" ", 1)
+                if reference != PRIVATE_REF:
+                    raise ValueError("Unexpected reference in prepared import; build a new preview")
+                line = verb + b" " + import_ref.encode("ascii") + b"\n"
+            elif line.startswith(b"mark "):
+                mark = line.removeprefix(b"mark ").strip().decode("ascii")
+            elif line not in (b"feature done\n", b"\n") and not line.startswith((b"author ", b"committer ", b"encoding ", b"data ", b"from ", b"merge ", b"M ", b"D ")):
+                raise ValueError("Unexpected command in prepared import; build a new preview")
+            destination.write(line)
+            if line.startswith(b"data "):
+                copy_bytes(source, int(line.removeprefix(b"data ").strip()), destination)
+        else:
+            raise ValueError("Incomplete prepared import; build a new preview")
+        destination.flush()
+        os.fsync(destination.fileno())
+    if mark is not None:
+        record.private_ref_by_name[import_ref] = _read_marks(os.path.join(preparation.operation_dir, "marks.out"))[mark]
+
+
+def _read_marks(filename: str) -> dict[str, str]:
+    """Read the import's exact mark mapping without depending on Git's output ordering."""
+    oid_by_mark = {}
+    with open(filename, "rb") as stream:
+        while line := read_line(stream):
+            mark, oid = line.strip().split(b" ")
+            mark = mark.decode("ascii")
+            if mark in oid_by_mark:
+                raise ValueError("Duplicate history import mark; inspect the recovery files")
+            oid_by_mark[mark] = validate_oid(oid.decode("ascii"))
+    return oid_by_mark
+
+
+def _verify_marks(preparation: RewritePreparation, record: RewriteRecoveryRecord) -> None:
+    """Require source import object identities to match the verified private import."""
+    if _read_marks(os.path.join(preparation.operation_dir, "marks.out")) != _read_marks(os.path.join(record.operation_dir, "marks.out")):
+        raise ValueError("Source import differs from the verified preview; inspect the recovery files")
+
+
+def rewrite_command(record: RewriteRecoveryRecord, arguments: list[str], *, stdin: bytes | None = None, stdin_filename: str | None = None,
+                    before_start: Callable[[], None] | None = None) -> GitCommand:
+    """Supervise every native write with empty private hooks, submodule recursion disabled and exact path case.
+
+    The source import must fold no path case, or it would build other commits than the verified private import.
+    """
+    return GitCommand([*SUBMODULE_RECURSION_OFF_ARGUMENTS, *EXACT_PATH_CASE_ARGUMENTS, "-c", "core.hooksPath=" + os.path.join(record.operation_dir, "hooks"), *arguments],
+                      stdin=stdin, stdin_filename=stdin_filename, profile=LOCAL_WRITE_PROFILE, timeout_ms=GIT_MUTATION_TIMEOUT_MS,
+                      idle_timeout_ms=MUTATION_IDLE_TIMEOUT_MS, before_start=before_start)
+
+
+def reference_transaction(old_oid_by_ref: dict[str, str], new_oid_by_ref: dict[str, str]) -> bytes:
+    """Compare every captured reference in one native transaction before moving any affected branch."""
+    commands = [b"start\n"]
+    for name, old_oid in sorted(old_oid_by_ref.items()):
+        new_oid = new_oid_by_ref[name]
+        if old_oid == new_oid:
+            commands.append(b"verify " + os.fsencode(name) + b" " + old_oid.encode("ascii") + b"\n")
+        else:
+            commands.append(b"update " + os.fsencode(name) + b" " + new_oid.encode("ascii") + b" " + old_oid.encode("ascii") + b"\n")
+    commands.extend((b"prepare\n", b"commit\n"))
+    return b"".join(commands)
+
+
+def _acquire_index(record: RewriteRecoveryRecord, preparation: RewritePreparation) -> RewriteRecoveryRecord:
+    """Acquire and fill only an exclusive index lock, recording ownership before content work."""
+    index_filename = os.path.join(preparation.capture.context.git_dir, "index")
+    lock_filename = index_filename + ".lock"
+    try:
+        descriptor = os.open(lock_filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+    except FileExistsError as error:
+        raise ValueError("Another writer owns index.lock; wait for it to finish, then build a new preview") from error
+    information = os.fstat(descriptor)
+    identity = information.st_dev, information.st_ino, stat.S_IFMT(information.st_mode)
+    try:
+        record = transition_record(record, record.state, owned_lock_identity=identity, owned_lock_digest=record.candidate_index_identity or EMPTY_LOCK_DIGEST)
+        if digest_text(index_digest(index_filename)) != record.original_index_identity:
+            raise ValueError("Index changed before locking; build a new preview")
+        content = read_index(preparation.index.candidate_filename)
+        if digest_text(index_digest(preparation.index.candidate_filename)) != record.candidate_index_identity:
+            raise ValueError("Candidate index changed; build a new preview")
+        owned_descriptor, descriptor = descriptor, None
+        fill_owned_lock(owned_descriptor, content if content is not None else b"")
+        return record
+    except (OSError, ValueError, RuntimeError):
+        if descriptor is not None:
+            os.close(descriptor)
+        if lock_identity(lock_filename) == identity and digest_text(index_digest(lock_filename)) in (EMPTY_LOCK_DIGEST, record.owned_lock_digest):
+            release_owned_index_lock(lock_filename, None, identity[:FILE_OBJECT_IDENTITY_FIELDS])
+        raise
+
+
+def _validate_locked_index(record: RewriteRecoveryRecord, operation: OperationIntent) -> None:
+    """Check the exact source bytes and lock identity immediately before publication."""
+    index_filename = os.path.join(operation.context.git_dir, "index")
+    if lock_identity(index_filename + ".lock") != record.owned_lock_identity:
+        raise ValueError("Index lock was replaced by another writer; inspect it before retrying")
+    if digest_text(index_digest(index_filename)) != record.original_index_identity:
+        raise ValueError("Index changed outside the owned lock; inspect it before retrying")
+    if digest_text(index_digest(index_filename + ".lock")) != record.owned_lock_digest:
+        raise ValueError("Index lock content changed; inspect it before retrying")
+
+
+def _read_named_head(record: RewriteRecoveryRecord, operation: OperationIntent) -> Generator[GitCommand | FileTask, object, tuple]:
+    """Bind the expected published references to fresh native HEAD evidence before index installation."""
+    authority = yield FileTask(lambda: reference_signature(operation.context))
+    output = yield GitCommand(["for-each-ref", "--format=" + REFERENCE_FORMAT, LOCAL_PREFIX])
+    reference = parse_reference_read(output)
+    if reference.object_oid_by_name != record.new_oid_by_ref:
+        raise ValueError("Local branches changed after publication; the index was not published. Inspect references and refresh recovery before continuing.")
+    if any(entry.symbolic_target is not None for entry in reference.references):
+        raise ValueError("A local branch became symbolic; the index was not published. Inspect references and refresh recovery before continuing.")
+    head = (yield GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))).removesuffix(b"\n")
+    if not head:
+        raise ValueError("HEAD is detached. The index was not published; inspect recovery and check out the original branch before continuing.")
+    if os.fsdecode(head) != record.head_ref:
+        raise ValueError("HEAD changed before index publication; inspect the active branch and refresh recovery before continuing")
+    if (yield FileTask(lambda: reference_signature(operation.context))) != authority:
+        raise ValueError("References or HEAD changed during reading; the index was not published. Refresh recovery before continuing.")
+    return authority
+
+
+def _publish_index(record: RewriteRecoveryRecord, operation: OperationIntent) -> None:
+    """Replace only the verified owned index lock, leaving absent indexes absent."""
+    _validate_locked_index(record, operation)
+    index_filename = os.path.join(operation.context.git_dir, "index")
+    if record.candidate_index_identity is None:
+        release_recovery_lock(record, operation.context)
+    else:
+        os.replace(index_filename + ".lock", index_filename)
+    sync_directory(operation.context.git_dir)
+
+
+def cleanup_private_refs(record: RewriteRecoveryRecord, observation: RecoveryObservation, *, before_start: Callable[[], None] | None = None) -> Generator[GitCommand, object]:
+    """Delete only operation-owned references whose actual values still match their journal."""
+    commands = [b"start\n"]
+    for name, oid in observation.private_ref_by_name.items():
+        if record.private_ref_by_name.get(name) != oid:
+            raise ValueError("A private recovery reference changed; retain recovery data for inspection")
+        commands.append(b"delete " + name.encode("ascii") + b" " + oid.encode("ascii") + b"\n")
+    if len(commands) == 1:
+        return
+    commands.extend((b"prepare\n", b"commit\n"))
+    yield rewrite_command(record, ["update-ref", "--no-deref", "--stdin"], stdin=b"".join(commands), before_start=before_start)
+
+
+def _lock_compensation(record: RewriteRecoveryRecord, operation: OperationIntent) -> RewriteRecoveryRecord:
+    """Hold the original index stable during the collective inverse reference transaction."""
+    index_filename = os.path.join(operation.context.git_dir, "index")
+    filename = index_filename + ".lock"
+    actual_identity = lock_identity(filename)
+    if actual_identity is None:
+        descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_FILE_MODE)
+        information = os.fstat(descriptor)
+        identity = information.st_dev, information.st_ino, stat.S_IFMT(information.st_mode)
+        os.close(descriptor)
+        record = transition_record(record, record.state, owned_lock_identity=identity, owned_lock_digest=EMPTY_LOCK_DIGEST)
+    elif actual_identity != record.owned_lock_identity:
+        raise ValueError("Another writer owns the index lock; recovery cannot restore references")
+    if digest_text(index_digest(filename)) != record.owned_lock_digest:
+        raise ValueError("Index lock content changed; inspect recovery without restoring branches")
+    if digest_text(index_digest(index_filename)) != record.original_index_identity:
+        raise ValueError("Index changed before compensation; inspect recovery without restoring branches")
+    return record
+
+
+def compensate_rewrite(record: RewriteRecoveryRecord, observation: RecoveryObservation, operation: OperationIntent,
+                       repository_operation: RepositoryOperationService) -> Generator[GitCommand | FileTask, object, RewritePublicationOutcome]:
+    """Restore all previous branches together only while a freshly observed incomplete result still matches."""
+    if record.state in (RewritePublicationState.COMPLETE, RewritePublicationState.RESTORED):
+        raise ValueError("A completed operation cannot be undone by recovery")
+    validate_recovery_authority(record, operation, repository_operation)
+    current = yield from observe_recovery(record, operation.context)
+    if current != observation or not current.restorable:
+        raise ValueError("Recovery state changed since confirmation; refresh recovery before restoring branches")
+    record = yield FileTask(lambda: _lock_compensation(record, operation))
+    record = yield FileTask(lambda: transition_record(record, RewritePublicationState.COMPENSATING))
+
+    def validate_compensation() -> None:
+        """Bind the inverse CAS to the observed worktrees, references, HEAD and original index."""
+        validate_recovery_authority(record, operation, repository_operation)
+        if reference_signature(operation.context) != current.authority:
+            raise ValueError("References or worktrees changed before restoration; refresh recovery before restoring branches")
+        # The observation already read symbolic HEAD through Git; its signature covers files and reftable.
+        index_filename = os.path.join(operation.context.git_dir, "index")
+        if (lock_identity(index_filename + ".lock") != record.owned_lock_identity or digest_text(index_digest(index_filename)) != record.original_index_identity
+                or digest_text(index_digest(index_filename + ".lock")) != record.owned_lock_digest):
+            raise ValueError("Index or lock changed before compensation; refresh recovery")
+
+    try:
+        yield rewrite_command(record, ["update-ref", "--no-deref", "--stdin"], stdin=reference_transaction(record.new_oid_by_ref, record.old_oid_by_ref),
+                              before_start=validate_compensation)
+        after = yield from observe_recovery(record, operation.context)
+        if after.detail or after.ref_oid_by_name != record.old_oid_by_ref or after.index_identity != record.original_index_identity:
+            raise ValueError(after.detail or "Compensation could not be verified; retain recovery data")
+        record = yield from finish_coherent_recovery(record, after, RewritePublicationState.RESTORED, operation, repository_operation,
+                                                    detail="Previous branches restored; the original index was retained")
+    except (OSError, ValueError, RuntimeError) as error:
+        return (yield from retain_recovery_failure(record, operation, error))
+    return RewritePublicationOutcome(operation.operation_id, OperationStatus.FAILED, record=record)
+
+
+def publish_rewrite(preparation: RewritePreparation, operation: OperationIntent, repository_operation: RepositoryOperationService,
+                    storage_root_dir: str, *, progress: Callable[[RewriteProgress], None] | None = None) -> Generator[GitCommand | FileTask, object, RewritePublicationOutcome]:
+    """Publish once under the caller's reservation, reporting only observed refs and index effects."""
+    record = None
+    try:
+        if progress is not None:
+            progress(RewriteProgress.CHECKING)
+        repository_operation.validate(operation)
+        yield FileTask(lambda: _validate_preparation(preparation, operation))
+        import_authority = yield FileTask(lambda: publication_authority(preparation.capture))
+        observed = yield from capture_rewrite_state(preparation.capture)
+        validate_rewrite_capture(preparation.capture, observed)
+        namespace = PRIVATE_REF_PREFIX + operation.operation_id + "/"
+        if (yield GitCommand(["for-each-ref", "--format=%(refname)", namespace])):
+            raise ValueError("Publication reference namespace already exists; build a new preview")
+        record = yield FileTask(lambda: _new_record(preparation, operation, storage_root_dir))
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.IMPORTING))
+        if progress is not None:
+            progress(RewriteProgress.IMPORTING)
+
+        def validate_import() -> None:
+            """Reject authority changes between the final preview read and source object import."""
+            repository_operation.validate(operation)
+            validate_publication_authority(preparation.capture, import_authority)
+
+        yield rewrite_command(record, ["fast-import", "--quiet", "--export-marks=" + os.path.join(record.operation_dir, "marks.out")],
+                              stdin_filename=os.path.join(record.operation_dir, "import.in"), before_start=validate_import)
+        yield FileTask(lambda: _verify_marks(preparation, record))
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.IMPORTED))
+        record = yield FileTask(lambda: _acquire_index(record, preparation))
+        authority = yield FileTask(lambda: publication_authority(preparation.capture))
+        observed = yield from capture_rewrite_state(preparation.capture)
+        validate_rewrite_capture(preparation.capture, observed)
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.REFS_PENDING))
+        if progress is not None:
+            progress(RewriteProgress.REFERENCES)
+
+        def validate_publication() -> None:
+            """Keep authorization, named HEAD and index checks adjacent to the collective CAS."""
+            repository_operation.validate(operation)
+            validate_publication_authority(preparation.capture, authority)
+            # The checked capture includes Git's symbolic HEAD, bound to this unchanged authority.
+            _validate_locked_index(record, operation)
+
+        yield rewrite_command(record, ["update-ref", "--no-deref", "--stdin"], stdin=reference_transaction(record.old_oid_by_ref, record.new_oid_by_ref),
+                              before_start=validate_publication)
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.REFS_COMMITTED))
+        index_authority = yield from _read_named_head(record, operation)
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.INDEX_PENDING))
+        if progress is not None:
+            progress(RewriteProgress.INDEX)
+
+        def publish_index() -> None:
+            """Reject changes while the checked index installation waits for its file worker."""
+            repository_operation.validate(operation)
+            if reference_signature(operation.context) != index_authority:
+                raise ValueError("References or HEAD changed before index publication; refresh recovery before continuing")
+            _publish_index(record, operation)
+
+        yield FileTask(publish_index)
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.INDEX_PUBLISHED))
+        observation = yield from observe_recovery(record, operation.context)
+        if observation.detail or observation.ref_oid_by_name != record.new_oid_by_ref or observation.index_identity != record.candidate_index_identity:
+            raise ValueError(observation.detail or "Published state changed before verification; inspect the recovery files")
+        yield from cleanup_private_refs(record, observation)
+        # Readers and external Git programs are not isolated by our reservation. Reobserve after cleanup too.
+        observation = yield from observe_recovery(record, operation.context)
+        if observation.detail or observation.ref_oid_by_name != record.new_oid_by_ref or observation.index_identity != record.candidate_index_identity:
+            raise ValueError(observation.detail or "Published state changed during cleanup; inspect the recovery files")
+        record = yield FileTask(lambda: transition_record(record, RewritePublicationState.COMPLETE))
+        return RewritePublicationOutcome(operation.operation_id, OperationStatus.SUCCESS, record=record)
+    except (OSError, ValueError, RuntimeError) as error:
+        detail = str(error)
+        status = OperationStatus.REFUSED if record is None else OperationStatus.UNKNOWN
+        if record is not None:
+            try:
+                reconciled = yield from recover_rewrite(record, operation, repository_operation, restore=True)
+                record = reconciled.record
+                status = reconciled.status
+                if reconciled.diagnostic is not None:
+                    detail += "; " + reconciled.diagnostic.cause
+            except (OSError, ValueError, RuntimeError) as recovery_error:
+                detail += "; recovery inspection failed: " + str(recovery_error)
+        diagnostic = Diagnostic(operation.operation, operation.context.repository_dir, operation.git_filename, [], detail).prepare()
+        return RewritePublicationOutcome(operation.operation_id, status, diagnostic=diagnostic, record=record, stale_capture=status == OperationStatus.REFUSED)
+    finally:
+        if record is not None and record.owned_lock_identity is not None:
+            lock_filename = os.path.join(operation.context.git_dir, "index.lock")
+            # A replaced lock belongs to another writer; even failure cleanup must leave it alone.
+            if lock_identity(lock_filename) == record.owned_lock_identity and digest_text(index_digest(lock_filename)) == record.owned_lock_digest:
+                release_recovery_lock(record, operation.context)