gitpane 1.0.0__py3-none-any.whl

gitpane/history/avatar.py

@@ -0,0 +1,241 @@
+"""Fetch optional author photos without exposing identities or trusting image input."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+from zlib import crc32
+
+from PySide6.QtCore import QBuffer, QByteArray, QIODevice, QObject, Qt, QTimer, QUrl, Signal
+from PySide6.QtGui import QImage, QImageReader
+from PySide6.QtNetwork import QNetworkAccessManager, QNetworkReply, QNetworkRequest
+
+from gitpane.config import (
+    AVATAR_ACTIVE_LIMIT,
+    AVATAR_CACHE_ENTRY_LIMIT,
+    AVATAR_CACHE_LIMIT_BYTES,
+    AVATAR_CACHE_TTL_SECONDS,
+    AVATAR_DECODED_SIDE_LIMIT,
+    AVATAR_PENDING_LIMIT,
+    AVATAR_REQUEST_SIDE_LIMIT,
+    AVATAR_RESPONSE_LIMIT_BYTES,
+    AVATAR_TIMEOUT_MS,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+GRAVATAR_HOST = "www.gravatar.com"
+HTTP_OK = 200
+RASTER_FORMAT_SET = {b"png", b"jpeg", b"jpg", b"gif", b"webp"}
+IMAGE_CONTENT_TYPE_SET = {"image/png", "image/jpeg", "image/gif", "image/webp"}
+AUTHOR_COLORS = ("#778d13", "#990099", "#267777", "#944913", "#6754a3", "#19699b")
+
+
+def normalize_author_email(author_email: str) -> str:
+    """Use one author identity for Gravatar requests, cache lookups and fallback colors."""
+    return author_email.strip().lower()
+
+
+def author_color(author_name: str, author_email: str) -> str:
+    """Keep the same colored initials in history rows and the selected commit's detail."""
+    identity = normalize_author_email(author_email) or author_name
+    return AUTHOR_COLORS[crc32(identity.encode("utf-8")) % len(AUTHOR_COLORS)]
+
+
+def author_initials(author_name: str) -> str:
+    """Return the first two word initials, retaining a visible unknown-author fallback."""
+    initial_word_count = 2
+    first_character_index = 0
+    initials = ""
+    for word in author_name.split()[:initial_word_count]:
+        initials += word[first_character_index].upper()
+    return initials or "?"
+
+
+@dataclass
+class PhotoRequest:
+    """Retain coalesced consumers while limiting a single network response."""
+
+    author_hash: str
+    side: int
+    ratio_by_identity: dict[object, float] = field(default_factory=dict)
+    reply: QNetworkReply | None = None
+    timer: QTimer | None = None
+    data: bytearray = field(default_factory=bytearray)
+
+
+class AvatarService(QObject):
+    """Share bounded HTTPS downloads and decoded image caching across windows."""
+
+    image_ready = Signal(object, QImage)
+
+    def __init__(self, manager: QNetworkAccessManager | None = None, clock: Callable[[], float] = time.monotonic, parent: QObject | None = None) -> None:
+        """Inject the network and clock so timeout, cache and race tests stay offline."""
+        super().__init__(parent)
+        self.manager = manager if manager is not None else QNetworkAccessManager(self)
+        self.clock = clock
+        self.request_by_key: dict[tuple[str, int], PhotoRequest] = {}
+        self.cache_by_key: OrderedDict[tuple[str, int], tuple[float, QImage]] = OrderedDict()
+        self.cache_bytes = 0
+        self.closed = False
+
+    def request(self, author_email: str, logical_size: int, device_pixel_ratio: float, identity: object) -> None:
+        """Coalesce equal images and publish only to consumers still interested in them."""
+        if self.closed or not author_email.strip() or logical_size <= 0 or not math.isfinite(device_pixel_ratio) or device_pixel_ratio <= 0:
+            return
+        side = min(AVATAR_REQUEST_SIDE_LIMIT, math.ceil(logical_size * device_pixel_ratio))
+        author_hash = hashlib.sha256(normalize_author_email(author_email).encode("utf-8")).hexdigest()
+        key = (author_hash, side)
+        cached = self.cache_by_key.get(key)
+        if cached is not None:
+            expiry, image = cached
+            if expiry > self.clock():
+                self.cache_by_key.move_to_end(key)
+                self._publish(identity, image, device_pixel_ratio)
+                return
+            self._evict(key)
+        pending = self.request_by_key.get(key)
+        if pending is None:
+            if len(self.request_by_key) >= AVATAR_PENDING_LIMIT:
+                return
+            pending = PhotoRequest(author_hash, side)
+            self.request_by_key[key] = pending
+        pending.ratio_by_identity[identity] = device_pixel_ratio
+        self._pump()
+
+    def cancel(self, identity: object) -> None:
+        """Remove a consumer and abort a download once nobody needs its response."""
+        for key, pending in tuple(self.request_by_key.items()):
+            pending.ratio_by_identity.pop(identity, None)
+            if not pending.ratio_by_identity:
+                self._release(key, abort=True)
+        self._pump()
+
+    def close(self) -> None:
+        """Abort outstanding requests before the application's network objects disappear."""
+        self.closed = True
+        for key in tuple(self.request_by_key):
+            self._release(key, abort=True)
+        self.cache_by_key.clear()
+        self.cache_bytes = 0
+
+    def _pump(self) -> None:
+        """Start queued downloads only while global capacity remains available."""
+        active_count = 0
+        for pending in self.request_by_key.values():
+            active_count += pending.reply is not None
+        for key, pending in tuple(self.request_by_key.items()):
+            if active_count >= AVATAR_ACTIVE_LIMIT:
+                return
+            if pending.reply is not None:
+                continue
+            request = QNetworkRequest(QUrl(f"https://{GRAVATAR_HOST}/avatar/{pending.author_hash}?d=404&s={pending.side}"))
+            # Refuse every redirect: optional photos never justify forwarding an identity to another endpoint.
+            request.setAttribute(QNetworkRequest.Attribute.RedirectPolicyAttribute, QNetworkRequest.RedirectPolicy.ManualRedirectPolicy)
+            request.setAttribute(QNetworkRequest.Attribute.CookieLoadControlAttribute, QNetworkRequest.LoadControl.Manual)
+            request.setAttribute(QNetworkRequest.Attribute.CookieSaveControlAttribute, QNetworkRequest.LoadControl.Manual)
+            request.setTransferTimeout(AVATAR_TIMEOUT_MS)
+            reply = self.manager.get(request)
+            pending.reply = reply
+            reply.setReadBufferSize(AVATAR_RESPONSE_LIMIT_BYTES + 1)
+            reply.readyRead.connect(lambda key=key: self._receive(key))
+            reply.metaDataChanged.connect(lambda key=key: self._check_header(key))
+            reply.sslErrors.connect(lambda _errors, key=key: self._finish(key, failed=True))
+            reply.finished.connect(lambda key=key: self._finish(key))
+            timer = QTimer(self)
+            timer.setSingleShot(True)
+            timer.timeout.connect(lambda key=key: self._finish(key, failed=True))
+            pending.timer = timer
+            timer.start(AVATAR_TIMEOUT_MS)
+            active_count += 1
+
+    def _check_header(self, key: tuple[str, int]) -> bool:
+        """Reject oversized or redirected content before reading its body."""
+        pending = self.request_by_key.get(key)
+        if pending is None or pending.reply is None:
+            return False
+        reply = pending.reply
+        content_length = reply.header(QNetworkRequest.KnownHeaders.ContentLengthHeader)
+        redirect = reply.attribute(QNetworkRequest.Attribute.RedirectionTargetAttribute)
+        if redirect is not None or (content_length is not None and int(content_length) > AVATAR_RESPONSE_LIMIT_BYTES):
+            self._finish(key, failed=True)
+            return False
+        return True
+
+    def _receive(self, key: tuple[str, int]) -> None:
+        """Read at most one byte beyond the budget to detect streamed overflow."""
+        if not self._check_header(key):
+            return
+        pending = self.request_by_key[key]
+        pending.data.extend(bytes(pending.reply.read(AVATAR_RESPONSE_LIMIT_BYTES + 1 - len(pending.data))))
+        if len(pending.data) > AVATAR_RESPONSE_LIMIT_BYTES:
+            self._finish(key, failed=True)
+
+    def _finish(self, key: tuple[str, int], failed: bool = False) -> None:
+        """Validate trusted origin and bounded raster data, then release before notifying UI."""
+        pending = self.request_by_key.get(key)
+        if pending is None:
+            return
+        image = QImage()
+        reply = pending.reply
+        if not failed and reply is not None:
+            self._receive(key)
+            if key not in self.request_by_key:
+                return
+            url = reply.url()
+            content_type = str(reply.header(QNetworkRequest.KnownHeaders.ContentTypeHeader) or "").split(";", maxsplit=1)[0].lower()
+            if (reply.error() == QNetworkReply.NetworkError.NoError and reply.attribute(QNetworkRequest.Attribute.HttpStatusCodeAttribute) == HTTP_OK
+                    and url.scheme() == "https" and url.host() == GRAVATAR_HOST and content_type in IMAGE_CONTENT_TYPE_SET):
+                image = self._decode(pending)
+        self._release(key, abort=failed)
+        self.cache_by_key[key] = (self.clock() + AVATAR_CACHE_TTL_SECONDS, image)
+        self.cache_bytes += image.sizeInBytes()
+        while len(self.cache_by_key) > AVATAR_CACHE_ENTRY_LIMIT or self.cache_bytes > AVATAR_CACHE_LIMIT_BYTES:
+            self._evict(next(iter(self.cache_by_key)))
+        for identity, ratio in pending.ratio_by_identity.items():
+            self._publish(identity, image, ratio)
+        self._pump()
+
+    def _decode(self, pending: PhotoRequest) -> QImage:
+        """Inspect raster dimensions before allocation and scale to the requested density."""
+        buffer = QBuffer()
+        buffer.setData(QByteArray(pending.data))
+        buffer.open(QIODevice.OpenModeFlag.ReadOnly)
+        reader = QImageReader(buffer)
+        size = reader.size()
+        if bytes(reader.format()).lower() not in RASTER_FORMAT_SET or not size.isValid() or size.isEmpty() or max(size.width(), size.height()) > AVATAR_DECODED_SIDE_LIMIT:
+            return QImage()
+        image = reader.read()
+        if image.isNull() or max(image.width(), image.height()) > AVATAR_DECODED_SIDE_LIMIT:
+            return QImage()
+        return image.scaled(pending.side, pending.side, Qt.AspectRatioMode.KeepAspectRatio, Qt.TransformationMode.SmoothTransformation)
+
+    def _publish(self, identity: object, image: QImage, ratio: float) -> None:
+        if image.isNull():
+            return
+        rendered = QImage(image)
+        rendered.setDevicePixelRatio(ratio)
+        self.image_ready.emit(identity, rendered)
+
+    def _evict(self, key: tuple[str, int]) -> None:
+        _expiry, image = self.cache_by_key.pop(key)
+        self.cache_bytes -= image.sizeInBytes()
+
+    def _release(self, key: tuple[str, int], abort: bool) -> None:
+        """Disconnect callbacks before abort/deleteLater so late signals cannot touch released work."""
+        pending = self.request_by_key.pop(key)
+        if pending.timer is not None:
+            pending.timer.stop()
+            pending.timer.timeout.disconnect()
+            pending.timer.deleteLater()
+        if pending.reply is not None:
+            for signal in (pending.reply.readyRead, pending.reply.metaDataChanged, pending.reply.sslErrors, pending.reply.finished):
+                signal.disconnect()
+            if abort:
+                pending.reply.abort()
+            pending.reply.deleteLater()

gitpane/history/file_history.py

@@ -0,0 +1,359 @@
+"""Follow historical file identities without changing repository navigation."""
+
+from __future__ import annotations
+
+from collections import OrderedDict, deque
+from dataclasses import dataclass
+from enum import Enum
+from time import monotonic
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.config import FILE_HISTORY_ACTIVE_COMPARISON_LIMIT, FILE_HISTORY_BATCH_SIZE, FILE_HISTORY_CACHE_ENTRY_LIMIT, FILE_HISTORY_COMPARISON_LIMIT, FILE_HISTORY_TURN_BUDGET_MS
+from gitpane.history.repository_value import FilePanel, FileReadIdentity
+
+if TYPE_CHECKING:
+    from gitpane.history.repository import GitRepository
+    from gitpane.history.repository_value import Commit, ComparisonGroup, HistorySnapshot, RepositoryFailure, RequestIdentity, RevisionEntry
+
+
+class WindowCapability(Enum):
+    """Name actions whose availability differs between reading and management windows."""
+
+    CONSULT = "consult"
+    MANAGE = "manage"
+    FILE_MENU = "file_menu"
+    RESTORE = "restore"
+
+
+WINDOW_CAPABILITY_BY_MODE = {
+    "repository": frozenset(WindowCapability),
+    "file_history": frozenset({WindowCapability.CONSULT}),
+}
+
+
+@dataclass(frozen=True)
+class FileHistoryAnchor:
+    """Identify an existing side of a historical entry, including its exact object."""
+
+    commit_oid: str
+    path: bytes
+    blob_oid: str
+    side: str = "after"
+
+    @classmethod
+    def from_entry(cls, entry: RevisionEntry) -> FileHistoryAnchor:
+        """Anchor deletions in their parent so the removed identity remains reachable."""
+        if entry.new_path is not None and entry.new_blob_oid is not None:
+            return cls(entry.commit_oid, entry.new_path, entry.new_blob_oid)
+        if entry.parent_oid is not None and entry.old_path is not None and entry.old_blob_oid is not None:
+            return cls(entry.parent_oid, entry.old_path, entry.old_blob_oid, "before")
+        raise ValueError("The selected entry has no historical file")
+
+
+@dataclass(frozen=True)
+class FileHistoryResult:
+    """Keep file membership, historical names and drawing ancestry independent."""
+
+    touching_oid_set: set[str]
+    path_by_oid: dict[str, tuple[bytes, ...]]
+    visible_parent_oids_by_oid: dict[str, list[str]]
+    complete: bool
+    comparison_count: int = 0
+    error: str | None = None
+
+    def select_entry(self, commit: Commit, groups: list[ComparisonGroup]) -> RevisionEntry | None:
+        """Find the tracked revision in true parent order, using the old side for deletions."""
+        paths = self.path_by_oid.get(commit.oid, ())
+        for parent_oid in commit.parent_oids or [None]:
+            for group in groups:
+                if group.parent_oid != parent_oid:
+                    continue
+                for entry in group.entries:
+                    path = entry.new_path if entry.new_path is not None else entry.old_path
+                    if path in paths:
+                        return entry
+        return None
+
+
+def visible_parent_map(snapshot: HistorySnapshot, visible_oid_set: set[str]) -> dict[str, list[str]]:
+    """Connect the first visible ancestors on each real parent branch, preserving order."""
+    nearest_oids_by_oid: dict[str, list[str]] = {}
+    result_by_oid = {}
+    for oid in snapshot.ordered_oids:
+        if oid not in visible_oid_set:
+            continue
+        pending = [(oid, False)]
+        while pending:
+            current_oid, expanded = pending.pop()
+            if current_oid in nearest_oids_by_oid:
+                continue
+            parents = snapshot.parent_oids_by_oid.get(current_oid, [])
+            if not expanded:
+                pending.append((current_oid, True))
+                for parent_oid in reversed(parents):
+                    if parent_oid not in visible_oid_set and parent_oid not in nearest_oids_by_oid:
+                        pending.append((parent_oid, False))
+                continue
+            ancestor_oids = []
+            ancestor_oid_set: set[str] = set()
+            for parent_oid in parents:
+                candidates = [parent_oid] if parent_oid in visible_oid_set else nearest_oids_by_oid.get(parent_oid, [])
+                for candidate in candidates:
+                    if candidate not in ancestor_oid_set:
+                        ancestor_oid_set.add(candidate)
+                        ancestor_oids.append(candidate)
+            nearest_oids_by_oid[current_oid] = ancestor_oids
+        result_by_oid[oid] = nearest_oids_by_oid[oid]
+    return result_by_oid
+
+
+@dataclass(frozen=True)
+class FileHistoryLimits:
+    """Bound comparison concurrency, retained edges and work between event-loop turns."""
+
+    active_comparison_limit: int = FILE_HISTORY_ACTIVE_COMPARISON_LIMIT
+    cache_entry_limit: int = FILE_HISTORY_CACHE_ENTRY_LIMIT
+    comparison_limit: int = FILE_HISTORY_COMPARISON_LIMIT
+    turn_budget_ms: int = FILE_HISTORY_TURN_BUDGET_MS
+
+    def __post_init__(self) -> None:
+        """Reject unusable limits before starting a calculation."""
+        if min(self.active_comparison_limit, self.cache_entry_limit, self.comparison_limit, self.turn_budget_ms) < 1:
+            raise ValueError("File history limits must be positive")
+
+
+class FileHistoryEngine(QObject):
+    """Read immutable comparisons asynchronously and follow identities along both directions."""
+
+    finished = Signal(object)
+    progressed = Signal(int, int)
+
+    def __init__(self, repository: GitRepository, limits: FileHistoryLimits | None = None) -> None:
+        """Use the repository's bounded process runner for all historical reads."""
+        super().__init__()
+        self.repository = repository
+        self.limits = limits or FileHistoryLimits()
+        self.generation = 0
+        self.identity: RequestIdentity | None = None
+        self.snapshot: HistorySnapshot | None = None
+        self.entry_by_cache_key: OrderedDict[tuple[str, int, int, bytes, str | None, str], list[RevisionEntry]] = OrderedDict()
+        self.cache_entry_count = 0
+        self.comparison_count = 0
+        self.active_comparison_count = 0
+        self.round_comparison_count = 0
+        self.batch_size_limit = FILE_HISTORY_BATCH_SIZE
+        self.active_batch_size = 0
+        self.states: deque[tuple[str, bytes, str]] = deque()
+        self.edges: deque[tuple[str, bytes, str, str | None, str, bool]] = deque()
+        self.seen_state_set: set[tuple[str, bytes, str]] = set()
+        self.path_set_by_oid: dict[str, set[bytes]] = {}
+        self.touching_oid_set: set[str] = set()
+        self.child_oids_by_oid: dict[str, list[str]] = {}
+        self.error: str | None = None
+        self.paused = False
+        self.closed = False
+        self.timer = QTimer(self)
+        self.timer.setSingleShot(True)
+        self.timer.timeout.connect(self._advance)
+        self.repository.file_failed.connect(self._failed)
+
+    def cancel(self) -> None:
+        """Invalidate callbacks before cancelling this engine's file comparisons."""
+        self.generation += 1
+        self.timer.stop()
+        self.active_comparison_count = 0
+        self.active_batch_size = 0
+        self.paused = False
+        if self.identity is not None:
+            self.repository.cancel_file(self.identity.session_id, FilePanel.FILE_HISTORY)
+
+    def calculate(self, snapshot: HistorySnapshot, anchor: FileHistoryAnchor, identity: RequestIdentity) -> None:
+        """Walk every captured branch, including descendants newer than the opening commit."""
+        if self.closed:
+            return
+        self.cancel()
+        self.identity = identity
+        self.snapshot = snapshot
+        self.comparison_count = 0
+        self.round_comparison_count = 0
+        self.batch_size_limit = FILE_HISTORY_BATCH_SIZE
+        self.states = deque([(anchor.commit_oid, anchor.path, anchor.blob_oid)])
+        self.edges.clear()
+        self.seen_state_set.clear()
+        self.path_set_by_oid.clear()
+        self.touching_oid_set.clear()
+        self.child_oids_by_oid.clear()
+        for child_oid, parent_oids in snapshot.parent_oids_by_oid.items():
+            for parent_oid in parent_oids:
+                self.child_oids_by_oid.setdefault(parent_oid, []).append(child_oid)
+        self.error = snapshot.error
+        self.paused = False
+        if anchor.commit_oid not in snapshot.parent_oids_by_oid:
+            self.error = "The opening revision is outside the captured history"
+        self.timer.start(0)
+
+    def resume(self) -> None:
+        """Continue the same captured identity after a comparison budget or read failure."""
+        if self.closed or not self.paused or self.snapshot is None or self.snapshot.error:
+            return
+        self.error = None
+        self.paused = False
+        self.round_comparison_count = 0
+        self.timer.start(0)
+
+    def close(self) -> None:
+        """Disconnect the shared service so closing a window releases its calculation safely."""
+        if self.closed:
+            return
+        self.closed = True
+        self.cancel()
+        self.repository.file_failed.disconnect(self._failed)
+        self.timer.timeout.disconnect(self._advance)
+        self.identity = None
+        self.states.clear()
+        self.edges.clear()
+        self.entry_by_cache_key.clear()
+        self.cache_entry_count = 0
+
+    def _advance(self) -> None:
+        """Follow cached identity edges cooperatively and prefetch missing neighborhoods in batches."""
+        if self.identity is None or self.snapshot is None or self.paused or self.active_comparison_count:
+            return
+        deadline = monotonic() + self.limits.turn_budget_ms / 1000
+        while monotonic() < deadline:
+            if self.error:
+                self._publish(False)
+                return
+            if self.edges:
+                edge = next(iter(self.edges))
+                _oid, path, _blob, parent_oid, child_oid, _forward = edge
+                repository_dir = self.repository.context_by_session[self.identity.session_id].repository_dir
+                key = (repository_dir, id(self.snapshot), self.snapshot.generation, path, parent_oid, child_oid)
+                entries = self.entry_by_cache_key.get(key)
+                if entries is None:
+                    if self.round_comparison_count >= self.limits.comparison_limit:
+                        self.error = "File history is incomplete. Continue reading to resume the captured history."
+                        self._publish(False)
+                        return
+                    self._read_edge(key, parent_oid, child_oid)
+                    return
+                self.entry_by_cache_key.move_to_end(key)
+                self.edges.popleft()
+                self._follow_edge(edge, entries)
+                continue
+            if not self.states:
+                self._publish(self.snapshot.complete and not self.snapshot.shallow)
+                return
+            oid, path, blob = self.states.popleft()
+            if (oid, path, blob) in self.seen_state_set:
+                continue
+            self.seen_state_set.add((oid, path, blob))
+            self.path_set_by_oid.setdefault(oid, set()).add(path)
+            for parent_oid in self.snapshot.parent_oids_by_oid.get(oid, []) or [None]:
+                self.edges.append((oid, path, blob, parent_oid, oid, False))
+            for child_oid in self.child_oids_by_oid.get(oid, []):
+                self.edges.append((oid, path, blob, oid, child_oid, True))
+        self.timer.start(0)
+
+    def _read_edge(self, key: tuple[str, int, int, bytes, str | None, str], parent_oid: str | None, child_oid: str) -> None:
+        """Batch neighboring captured edges while bounding read work and retained cache entries."""
+        if self.active_comparison_count >= self.limits.active_comparison_limit:
+            return
+        generation = self.generation
+        repository_dir, snapshot_id, snapshot_generation, path, _parent_oid, _child_oid = key
+        prefix = (repository_dir, snapshot_id, snapshot_generation, path)
+        batch_limit = min(self.batch_size_limit, self.limits.cache_entry_limit, self.limits.comparison_limit - self.round_comparison_count)
+        comparisons = [(parent_oid, child_oid)]
+        comparison_set = {(parent_oid, child_oid)}
+        pending_oids = deque([child_oid])
+        if parent_oid is not None:
+            pending_oids.append(parent_oid)
+        visited_oid_set: set[str] = set()
+        deadline = monotonic() + self.limits.turn_budget_ms / 1000
+        while pending_oids and len(comparisons) < batch_limit and monotonic() < deadline:
+            oid = pending_oids.popleft()
+            if oid in visited_oid_set or oid not in self.snapshot.parent_oids_by_oid:
+                continue
+            visited_oid_set.add(oid)
+            neighbors = []
+            for parent in self.snapshot.parent_oids_by_oid[oid] or [None]:
+                neighbors.append((parent, oid))
+                if parent is not None:
+                    pending_oids.append(parent)
+            for child in self.child_oids_by_oid.get(oid, []):
+                neighbors.append((oid, child))
+                pending_oids.append(child)
+            for comparison in neighbors:
+                if comparison in comparison_set or (*prefix, *comparison) in self.entry_by_cache_key:
+                    continue
+                comparison_set.add(comparison)
+                comparisons.append(comparison)
+                if len(comparisons) == batch_limit:
+                    break
+        self.active_comparison_count += 1
+        self.active_batch_size = len(comparisons)
+        self.comparison_count += len(comparisons)
+        self.round_comparison_count += len(comparisons)
+
+        def receive(entry_by_comparison: dict[tuple[str | None, str], list[RevisionEntry]]) -> None:
+            """Cache only scoped raw metadata, with no parent descriptions or file patches."""
+            if generation != self.generation:
+                return
+            self.active_comparison_count -= 1
+            self.active_batch_size = 0
+            for comparison, entries in entry_by_comparison.items():
+                self.entry_by_cache_key[(*prefix, *comparison)] = entries
+            while len(self.entry_by_cache_key) > self.limits.cache_entry_limit:
+                self.entry_by_cache_key.popitem(last=False)
+            self.cache_entry_count = len(self.entry_by_cache_key)
+            self.progressed.emit(len(self.path_set_by_oid), len(self.snapshot.ordered_oids))
+            if generation == self.generation:
+                self.timer.start(0)
+
+        self.repository.read_history_comparisons(comparisons, path, FileReadIdentity(self.identity, FilePanel.FILE_HISTORY, generation), receive)
+
+    def _follow_edge(self, edge: tuple[str, bytes, str, str | None, str, bool], entries: list[RevisionEntry]) -> None:
+        """Carry the actual blob across renames, stopping on an addition or deletion."""
+        _oid, path, blob, parent_oid, child_oid, forward = edge
+        opposite_oid = child_oid if forward else parent_oid
+        opposite_path, opposite_blob = path, blob
+        for entry in entries:
+            own_path = entry.old_path if forward else entry.new_path
+            if own_path != path:
+                continue
+            own_blob = entry.old_blob_oid if forward else entry.new_blob_oid
+            if own_blob != blob:
+                self.error = "The historical file identity does not match the captured Git object"
+                return
+            self.touching_oid_set.add(child_oid)
+            opposite_path = entry.new_path if forward else entry.old_path
+            opposite_blob = entry.new_blob_oid if forward else entry.old_blob_oid
+            if opposite_path is None:
+                self.path_set_by_oid.setdefault(child_oid, set()).add(path)
+            break
+        if opposite_oid in self.snapshot.parent_oids_by_oid and opposite_path is not None and opposite_blob is not None:
+            self.states.append((opposite_oid, opposite_path, opposite_blob))
+
+    def _publish(self, complete: bool) -> None:
+        """Report completion separately from partial results so callers can offer a retry."""
+        self.paused = not complete
+        if not complete and self.error is None:
+            self.error = "File history is incomplete at the shallow repository boundary"
+        path_by_oid = {}
+        for oid, path_set in self.path_set_by_oid.items():
+            path_by_oid[oid] = tuple(sorted(path_set))
+        result = FileHistoryResult(set(self.touching_oid_set), path_by_oid, visible_parent_map(self.snapshot, self.touching_oid_set), complete, self.comparison_count, self.error)
+        self.finished.emit(result)
+
+    def _failed(self, identity: FileReadIdentity, failure: RepositoryFailure) -> None:
+        """Retain failed work and shrink the next batch so output or timeout limits can recover."""
+        if identity.panel_kind != FilePanel.FILE_HISTORY or identity.request_identity != self.identity or identity.panel_generation != self.generation:
+            return
+        retry_divisor = 2
+        self.batch_size_limit = max(1, self.active_batch_size // retry_divisor)
+        self.active_batch_size = 0
+        self.active_comparison_count = 0
+        self.error = f"File history is incomplete: {failure.cause}"
+        self._publish(False)