pivot 0.2.0__tar.gz → 0.2.1__tar.gz

{pivot-0.2.0 → pivot-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pivot
-Version: 0.2.0
+Version: 0.2.1
 Summary: High-performance Python pipeline tool with automatic code change detection
 Author: Sami Jawhar
 Author-email: Sami Jawhar <sami@metr.org>

{pivot-0.2.0 → pivot-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pivot"
-version = "0.2.0"
+version = "0.2.1"
 description = "High-performance Python pipeline tool with automatic code change detection"
 requires-python = ">=3.13,<3.14"
 readme = "README.md"

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/cli/checkout.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import enum
 import pathlib
 from typing import TYPE_CHECKING, Literal
@@ -12,7 +13,7 @@ from pivot.cli import completion
 from pivot.cli import decorators as cli_decorators
 from pivot.cli import helpers as cli_helpers
 from pivot.cli import targets as cli_targets
-from pivot.storage import cache, lock, track
+from pivot.storage import cache, lock, state, track
 from pivot.types import HashInfo, is_dir_hash
 
 if TYPE_CHECKING:
@@ -96,6 +97,7 @@ def _restore_path_sync(
             "already exists" without --force). Cache misses return ("missing", name)
             instead of raising.
     """
+    keep_ignored = False
     if path.exists():
         match behavior:
             case CheckoutBehavior.ERROR:
@@ -106,12 +108,33 @@ def _restore_path_sync(
                     + "Use --force to overwrite or --only-missing to skip existing files."
                 )
             case CheckoutBehavior.SKIP_EXISTING:
-                # For directories with manifests, don't skip - files inside may be missing.
-                # Let restore_from_cache() handle it (does full directory restoration).
-                # DirHash has "manifest" key, FileHash does not.
-                is_directory = is_dir_hash(output_hash)
-                if not is_directory:
+                # Existing file: skip. Existing real directory: fill in its missing files, or
+                # swap in the target when every differing file is pivot's own cached output,
+                # keeping the entries the directory hash skips. Never overwrite content the
+                # cache lacks (a local change).
+                if not is_dir_hash(output_hash) or path.is_symlink() or not path.is_dir():
                     return ("skipped", path.name)
+                # Reuse hashes `pivot status` and `pivot track` recorded; never create the DB.
+                with (
+                    state.StateDB(state_dir, readonly=True)
+                    if state_dir is not None and (state_dir / "state.lmdb").exists()
+                    else contextlib.nullcontext(None)
+                ) as state_db:
+                    outcome = cache.restore_missing_in_directory(
+                        path, output_hash, cache_dir, checkout_modes, state_db
+                    )
+                if outcome["local_changes"]:
+                    raise click.ClickException(
+                        f"'{path.name}' has local changes that are not in the cache: "
+                        + f"{', '.join(outcome['local_changes'])}. Use --force to overwrite."
+                    )
+                # An interrupted restore may have staged kept entries beside the directory;
+                # the restore below puts them back, so take it even when nothing else differs.
+                if not outcome["replace"] and cache.staged_kept_entries(path) is None:
+                    if outcome["unavailable"]:
+                        return ("missing", path.name)
+                    return ("restored" if outcome["restored"] else "skipped", path.name)
+                keep_ignored = True
             case CheckoutBehavior.FORCE:
                 cache.remove_output(path)
             case _:  # pyright: ignore[reportUnnecessaryComparison] - defensive for future enum values
@@ -123,6 +146,7 @@ def _restore_path_sync(
         cache_dir,
         checkout_modes=checkout_modes,
         state_dir=state_dir,
+        keep_ignored=keep_ignored,
     )
     if not success:
         return ("missing", path.name)

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/cli/verify.py

@@ -190,6 +190,29 @@ def _create_remote_if_needed(allow_missing: bool) -> remote_mod.S3Remote | None:
     return remote
 
 
+def _status_from_explanations(
+    explanations: list[types.StageExplanation],
+) -> list[PipelineStatusInfo]:
+    """Convert rich explanations to verification status, retaining changed dep identities."""
+    statuses = list[PipelineStatusInfo]()
+    for explanation in explanations:
+        reason = explanation["reason"]
+        if reason == "Input dependencies changed" and explanation["dep_changes"]:
+            changed = ", ".join(
+                types.identity_key(change["identity"]) for change in explanation["dep_changes"]
+            )
+            reason = f"{reason}: {changed}"
+        statuses.append(
+            PipelineStatusInfo(
+                name=explanation["stage_name"],
+                status=(PipelineStatus.STALE if explanation["will_run"] else PipelineStatus.CACHED),
+                reason=reason,
+                upstream_stale=explanation["upstream_stale"],
+            )
+        )
+    return statuses
+
+
 def _verify_stages(
     pipeline_status: list[PipelineStatusInfo],
     cache_dir: pathlib.Path,
@@ -345,14 +368,16 @@ def verify(
 
     cache_dir = config.get_cache_dir()
 
-    # Get pipeline status (uses default state directory internally)
-    pipeline_status, _ = status_mod.get_pipeline_status(
+    # Get rich explanations so lock-only dependency mismatches identify the
+    # producer artifact in verification output.
+    explanations = status_mod.get_pipeline_explanations(
         stages_list,
         single_stage=False,
         all_stages=all_stages,
         pipeline=cli_helpers.get_pipeline(),
         allow_missing=allow_missing,
     )
+    pipeline_status = _status_from_explanations(explanations)
 
     if not pipeline_status:
         raise click.ClickException("No stages to verify.")

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/executor/worker.py

@@ -6,6 +6,7 @@ Must be module-level and picklable.
 
 from __future__ import annotations
 
+import codecs
 import collections
 import collections.abc as collections_abc
 import contextlib
@@ -1095,14 +1096,19 @@ class _QueueWriter:
 
     def _pipe_reader(self) -> None:
         assert self._read_fd is not None  # Guaranteed by _ensure_pipe() before thread starts
+        # One incremental decoder per pipe: a multi-byte character split across two reads
+        # is held until its remaining bytes arrive instead of becoming U+FFFD.
+        decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
         try:
             while True:
                 data = os.read(self._read_fd, 8192)
                 if not data:
                     break
-                self.write(data.decode("utf-8", errors="replace"))
+                self.write(decoder.decode(data))
         except OSError:
             pass
+        # Flush a truncated trailing character so it is reported rather than dropped.
+        self.write(decoder.decode(b"", final=True))
 
     def _ensure_pipe(self) -> None:
         if self._read_fd is not None:

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/import_artifact.py

@@ -1,8 +1,12 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import functools
 import logging
+import os
+import pathlib
+import tempfile
 from typing import TYPE_CHECKING, TypedDict, cast
 
 import aiohttp
@@ -16,7 +20,6 @@ from pivot.storage import cache, track
 from pivot.storage import lock as storage_lock
 
 if TYPE_CHECKING:
-    import pathlib
     from collections.abc import Callable
 
     from pivot.types import DirManifestEntry, OutEntry, StorageLockData
@@ -39,6 +42,31 @@ class ImportResult(TypedDict):
     downloaded: bool
 
 
+async def _download_verified(remote_url: str, file_hash: str, data_path: pathlib.Path) -> int:
+    """Download ``file_hash`` to ``data_path`` only if its content matches; return its size.
+
+    The file is downloaded to a temp file in the destination directory and moved over
+    ``data_path`` after its hash is checked, so a corrupt remote copy leaves any existing
+    file (the last good import) untouched.
+    """
+    fd, tmp_name = tempfile.mkstemp(
+        dir=data_path.parent, prefix=f".{data_path.name}.", suffix=".tmp"
+    )
+    os.close(fd)
+    tmp_path = pathlib.Path(tmp_name)
+    try:
+        await remote_storage.S3Remote(remote_url).download_file(file_hash, tmp_path)
+        actual_hash, _ = cache.hash_file(tmp_path)
+        if actual_hash != file_hash:
+            raise exceptions.RemoteError(f"Hash mismatch: expected {file_hash}, got {actual_hash}")
+        size = tmp_path.stat().st_size
+        os.replace(tmp_path, data_path)
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            tmp_path.unlink()
+    return size
+
+
 def _maybe_token(repo_url: str, token: str | None) -> str | None:
     if token is not None:
         return token
@@ -111,7 +139,13 @@ async def read_remote_config(
     remotes = {str(k): str(v) for k, v in remotes_data.items()}
 
     default_remote = config_data.get("default_remote")
-    if not isinstance(default_remote, str):
+    if default_remote is not None and not isinstance(default_remote, str):
+        # Warn-first: the source config is a saved input outside this repo.
+        logger.warning(
+            "Remote config default_remote in %s must be a remote name, got %r; ignoring it",
+            repo_url,
+            default_remote,
+        )
         default_remote = None
     if default_remote is None:
         if len(remotes) == 1:
@@ -370,16 +404,8 @@ async def import_artifact(
     downloaded = False
     file_size = resolved["size"]
     if not no_download:
-        remote = remote_storage.S3Remote(resolved["remote_url"])
-        await remote.download_file(resolved["hash"], data_path)
+        file_size = await _download_verified(resolved["remote_url"], resolved["hash"], data_path)
         downloaded = True
-        actual_hash, _ = cache.hash_file(data_path)
-        if actual_hash != resolved["hash"]:
-            data_path.unlink(missing_ok=True)
-            raise exceptions.RemoteError(
-                f"Downloaded file hash mismatch: expected {resolved['hash']}, got {actual_hash}"
-            )
-        file_size = data_path.stat().st_size
 
     source = track.ImportSource(
         repo=repo_url,
@@ -456,16 +482,8 @@ async def update_import(pvt_path: pathlib.Path, *, new_rev: str | None = None) -
 
     file_size = resolved["size"]
     if need_download:
-        remote = remote_storage.S3Remote(resolved["remote_url"])
-        await remote.download_file(resolved["hash"], data_path)
-        actual_hash, _ = cache.hash_file(data_path)
-        if actual_hash != resolved["hash"]:
-            data_path.unlink(missing_ok=True)
-            raise exceptions.RemoteError(
-                f"Hash mismatch: expected {resolved['hash']}, got {actual_hash}"
-            )
+        file_size = await _download_verified(resolved["remote_url"], resolved["hash"], data_path)
         downloaded = True
-        file_size = data_path.stat().st_size
     elif data_path.exists():
         file_size = data_path.stat().st_size
 

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/remote/sync.py

@@ -180,6 +180,30 @@ def _get_file_hash_from_pvt(rel_path: str, proj_root: pathlib.Path) -> HashInfo
     return FileHash(hash=track_data["hash"])
 
 
+def _get_tracked_hashes(proj_root: pathlib.Path) -> set[str]:
+    """Blob hashes of every `pivot track`-ed file or directory in the project.
+
+    Imports are left out: `pivot import` writes the file straight to the workspace, so its
+    blob never enters the local cache and push never sends it to this project's remote.
+    """
+    hashes = set[str]()
+    for pvt_data in track.discover_pvt_files(proj_root).values():
+        if track.is_import(pvt_data):
+            continue
+        hashes |= _extract_file_hashes_from_hash_info(track.pvt_to_hash_info(pvt_data))
+    return hashes
+
+
+def _is_cached_stage_output(
+    identity: types.ArtifactIdentity, producer_info: RegistryStageInfo
+) -> bool:
+    """Whether a stage output is stored in the cache (Metrics are git-tracked, not cached)."""
+    return not any(
+        out.identity == identity and out.tag is types.ArtifactTag.METRIC
+        for out in producer_info["outs"]
+    )
+
+
 def get_target_hashes(
     targets: list[str],
     state_dir: pathlib.Path,
@@ -192,6 +216,7 @@ def get_target_hashes(
     hashes = set[str]()
     output_identities: dict[str, types.ArtifactIdentity] | None = None
     unresolved = list[str]()
+    tracked_hashes: set[str] | None = None
 
     for target in targets:
         original_target = target
@@ -224,8 +249,19 @@ def get_target_hashes(
                             if types.identity_key(out_path) not in non_cached_paths:
                                 hashes |= _extract_file_hashes_from_hash_info(out_hash)
                         if include_deps:
-                            for dep_hash in lock_data["dep_hashes"].values():
-                                hashes |= _extract_file_hashes_from_hash_info(dep_hash)
+                            # Only deps whose blobs pivot caches (and so pushes) can be fetched:
+                            # upstream stage outputs and `pivot track` inputs. Raw inputs
+                            # committed to git and `pivot import` inputs are never in the remote.
+                            for dep_identity, dep_hash in lock_data["dep_hashes"].items():
+                                dep_blobs = _extract_file_hashes_from_hash_info(dep_hash)
+                                producer_info = all_stages.get(dep_identity.producer)
+                                if producer_info is not None:
+                                    if _is_cached_stage_output(dep_identity, producer_info):
+                                        hashes |= dep_blobs
+                                    continue
+                                if tracked_hashes is None:
+                                    tracked_hashes = _get_tracked_hashes(proj_root)
+                                hashes |= dep_blobs & tracked_hashes
                         continue
             else:
                 resolved_identity = types.ArtifactIdentity(stage_name, target_identity.key)

{pivot-0.2.0 → pivot-0.2.1}/src/pivot/storage/cache.py

@@ -14,7 +14,7 @@ import shutil
 import stat
 import tempfile
 import time
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypedDict
 
 import xxhash
 
@@ -36,9 +36,54 @@ XXHASH64_HEX_LENGTH = 16  # xxhash64 produces 64-bit hash = 16 hex characters
 _RESTORE_TEMP_PREFIX = ".pivot_restore_"
 _BACKUP_TEMP_PREFIX = ".pivot_backup_"
 _RESTORE_LOCK_PREFIX = ".pivot_restore_lock_"
+_KEEP_STAGING_PREFIX = ".pivot_keep_"
 _RESTORE_TEMP_MAX_AGE = 3600  # 1 hour
 
 
+def _keep_staging_path(path: pathlib.Path) -> pathlib.Path:
+    """Sibling that holds a directory's kept entries (see keep_ignored) while it is replaced.
+
+    It is named after the target and no cleanup removes it, so entries an interrupted
+    restore leaves there wait for the next restore of the same target to put them back.
+    """
+    logical_path = path.parent.resolve() / path.name
+    token = hashlib.sha256(str(logical_path).encode()).hexdigest()[:32]
+    return path.parent / f"{_KEEP_STAGING_PREFIX}{token}"
+
+
+def _move_kept_entries(source: pathlib.Path, destination: pathlib.Path) -> None:
+    """Move every entry under source into destination, merging directories, then drop source.
+
+    Raises CacheRestoreError, leaving that entry and the rest in source, when a file or
+    link already exists at its destination.
+    """
+    with os.scandir(source) as entries:
+        for entry in entries:
+            target = destination / entry.name
+            if not os.path.lexists(target):
+                destination.mkdir(parents=True, exist_ok=True)
+                pathlib.Path(entry.path).rename(target)
+            elif (
+                entry.is_dir(follow_symlinks=False) and target.is_dir() and not target.is_symlink()
+            ):
+                _move_kept_entries(pathlib.Path(entry.path), target)
+            else:
+                raise exceptions.CacheRestoreError(
+                    f"Cannot put back {entry.path}: {target} already exists. "
+                    + "Move the entry by hand, then retry."
+                )
+    source.rmdir()
+
+
+def staged_kept_entries(path: pathlib.Path) -> pathlib.Path | None:
+    """The directory where an interrupted restore of path left kept entries, if any.
+
+    Any later restore of path (restore_from_cache) puts them back.
+    """
+    keep_dir = _keep_staging_path(path)
+    return keep_dir if keep_dir.exists() else None
+
+
 def _get_lock_path(target_path: pathlib.Path, state_dir: pathlib.Path) -> pathlib.Path:
     """Get lock file path under state_dir/locks/ for a restore target.
 
@@ -605,6 +650,8 @@ def restore_from_cache(
     checkout_mode: CheckoutMode | None = None,
     checkout_modes: list[CheckoutMode] | None = None,
     state_dir: pathlib.Path | None = None,
+    *,
+    keep_ignored: bool = False,
 ) -> bool:
     """Restore file or directory from cache. Returns True if successful.
 
@@ -616,12 +663,16 @@ def restore_from_cache(
         checkout_modes: Ordered list of link modes to try with fallback on failure.
         state_dir: State directory for lock files (e.g. per-stage .pivot/ dir).
             Required for directory restores to prevent concurrent restore races.
+        keep_ignored: When replacing an existing directory, move the entries the directory
+            hash skips (build/, *.swp, ...) into the restored tree instead of deleting them.
+            They wait in a sibling staging directory during the swap. Entries an interrupted
+            restore left there are put into the restored tree by any later restore of path.
     """
     effective_modes = _resolve_checkout_modes(checkout_mode, checkout_modes)
 
     if is_dir_hash(output_hash):
         return _restore_directory_from_cache(
-            path, output_hash, cache_dir, effective_modes, state_dir
+            path, output_hash, cache_dir, effective_modes, state_dir, keep_ignored=keep_ignored
         )
     return _restore_file_from_cache(path, output_hash, cache_dir, effective_modes)
 
@@ -648,6 +699,8 @@ def _restore_directory_from_cache(
     cache_dir: pathlib.Path,
     checkout_modes: list[CheckoutMode],
     state_dir: pathlib.Path | None = None,
+    *,
+    keep_ignored: bool = False,
 ) -> bool:
     """Restore directory from cache atomically with file locking."""
     cache_dir_path = get_cache_path(cache_dir, output_hash["hash"])
@@ -678,6 +731,23 @@ def _restore_directory_from_cache(
             lock_fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o644)
             fcntl.flock(lock_fd, fcntl.LOCK_EX)
 
+        # Entries of the existing directory that are not part of the output, to carry over.
+        # A restore that carries them first puts back what an interrupted one left staged in
+        # keep_dir, so they are carried like the rest. Any other restore leaves keep_dir alone
+        # and moves its contents into the new tree after the swap.
+        keep_dir = _keep_staging_path(path)
+        keep = list[str]()
+        if keep_ignored and path.is_dir() and not path.is_symlink():
+            if keep_dir.exists():
+                _move_kept_entries(keep_dir, path)
+            _, keep = _scan_entries(path, {entry["relpath"] for entry in output_hash["manifest"]})
+        if symlink_fast_path and (keep or keep_dir.exists()):
+            # A directory that keeps local entries cannot be a link to the cache tree.
+            symlink_fast_path = False
+            for entry in output_hash["manifest"]:
+                if not get_cache_path(cache_dir, entry["hash"]).exists():
+                    return False
+
         # SYMLINK fast path: create symlink at temp location, then atomic rename
         if symlink_fast_path:
             temp_symlink = path.parent / f"{_RESTORE_TEMP_PREFIX}symlink_{secrets.token_hex(4)}"
@@ -748,6 +818,17 @@ def _restore_directory_from_cache(
                 except OSError as e:
                     logger.debug(f"chmod failed (may be NFS with root_squash): {e}")
 
+            # Entries the directory hash skips are not part of the output. Stage them in
+            # keep_dir, which no cleanup removes, and put them into the new tree after the
+            # swap. A crash at any point leaves each one in path, keep_dir or the new tree.
+            for relpath in keep:
+                source = path / relpath
+                if not os.path.lexists(source):
+                    continue
+                staged = keep_dir / relpath
+                staged.parent.mkdir(parents=True, exist_ok=True)
+                source.rename(staged)
+
             # Atomic swap with rollback capability:
             # - Backup original first so we can restore on failure
             # - Replace atomically so path always has valid content
@@ -761,6 +842,9 @@ def _restore_directory_from_cache(
             temp_path.replace(path)
             swap_completed = True
 
+            if keep_dir.exists():
+                _move_kept_entries(keep_dir, path)
+
             try:
                 _clear_path(backup_path)
             except OSError as e:
@@ -776,6 +860,15 @@ def _restore_directory_from_cache(
                 except OSError as e:
                     logger.debug(f"Failed to restore backup: {e}")
                     backup_restore_failed = True
+            # Return staged entries to the original directory if the swap did not happen
+            if not swap_completed and keep_dir.exists() and path.is_dir() and not path.is_symlink():
+                try:
+                    _move_kept_entries(keep_dir, path)
+                except (OSError, exceptions.CacheRestoreError) as e:
+                    logger.warning(
+                        f"Entries kept from {path} remain in {keep_dir} ({e}); "
+                        + "the next restore of it puts them back"
+                    )
             raise
         finally:
             # Clean up temp directory on any exit
@@ -807,6 +900,168 @@ def remove_output(path: pathlib.Path) -> None:
     _clear_path(path)
 
 
+class MissingRestore(TypedDict):
+    """Outcome of restore_missing_in_directory."""
+
+    restored: int  # missing files restored in place
+    unavailable: int  # missing files whose blob is not in the cache
+    local_changes: list[str]  # changed or extra files whose content the cache lacks
+    replace: bool  # directory holds only cached content but not the target: replace it whole
+
+
+def _is_cached(cache_dir: pathlib.Path, content_hash: str | None) -> bool:
+    return (
+        content_hash is not None
+        and is_valid_hash(content_hash)
+        and get_cache_path(cache_dir, content_hash).exists()
+    )
+
+
+def _scan_entries(path: pathlib.Path, expected_paths: set[str]) -> tuple[list[str], list[str]]:
+    """Return (files and symlinks, entries the directory hash skips) under path, as relpaths.
+
+    Symlinked directories are not followed. A skipped name that is, or holds, a manifest
+    path is part of the output and is scanned like any other entry.
+    """
+    expected_dirs = {
+        str(parent)
+        for relpath in expected_paths
+        for parent in pathlib.PurePosixPath(relpath).parents
+        if str(parent) != "."
+    }
+    files = list[str]()
+    ignored = list[str]()
+
+    def _walk(directory: pathlib.Path) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                entry_path = pathlib.Path(entry.path)
+                relpath = str(entry_path.relative_to(path))
+                if (
+                    _should_skip_entry(entry)
+                    and relpath not in expected_paths
+                    and relpath not in expected_dirs
+                ):
+                    ignored.append(relpath)
+                elif entry.is_symlink() or entry.is_file():
+                    files.append(relpath)
+                elif entry.is_dir():
+                    _walk(entry_path)
+
+    _walk(path)
+    return files, ignored
+
+
+def _is_same_file(file_stat: os.stat_result, cache_path: pathlib.Path) -> bool:
+    """Whether file_stat is the cache blob itself (a hardlink checkout). Cache blobs are
+    read-only and never rewritten, so sharing the inode proves the content without a read."""
+    try:
+        blob_stat = cache_path.stat()
+    except FileNotFoundError:
+        return False
+    return (file_stat.st_dev, file_stat.st_ino) == (blob_stat.st_dev, blob_stat.st_ino)
+
+
+def restore_missing_in_directory(
+    path: pathlib.Path,
+    output_hash: DirHash,
+    cache_dir: pathlib.Path,
+    checkout_modes: list[CheckoutMode],
+    state_db: state_mod.StateDB | None = None,
+) -> MissingRestore:
+    """Restore a directory's missing target files without overwriting local changes.
+
+    When every existing file matches the target, the missing files are restored in place
+    and nothing else is touched. When some file differs from the target or is not in it,
+    only a whole-directory swap brings the target. It is safe only if every file it
+    removes is in the cache (pivot's own earlier output): then nothing is written and
+    ``replace`` asks the caller to swap with ``restore_from_cache(..., keep_ignored=True)``,
+    which carries over the entries the directory hash skips (build/, *.swp, ...). Otherwise
+    nothing is written, and the files the cache lacks (local edits, extra files) are returned.
+
+    A retained file is read only when nothing else proves its content: a symlink to the
+    target's cache path, a hardlink to the target's cache blob, or a matching ``state_db``
+    entry each settle it without a read.
+    """
+    lexical_base = pathlib.Path(os.path.abspath(path))
+    resolved_base = path.resolve()
+    expected_paths = set[str]()
+    missing = list[tuple[DirManifestEntry, pathlib.Path, pathlib.Path]]()
+    # relpath -> hash of the content on disk (None when it cannot be in the cache)
+    changed = dict[str, str | None]()
+
+    for entry in output_hash["manifest"]:
+        relpath = entry["relpath"]
+        expected_paths.add(relpath)
+        file_path = path / relpath
+        lexical_path = pathlib.Path(os.path.abspath(file_path))
+        if not lexical_path.is_relative_to(lexical_base):
+            raise exceptions.SecurityValidationError(
+                f"Manifest contains path traversal: {relpath!r}"
+            )
+
+        file_cache_path = get_cache_path(cache_dir, entry["hash"])
+        if file_path.is_symlink():
+            if not file_path.parent.resolve().is_relative_to(resolved_base):
+                raise exceptions.SecurityValidationError(
+                    f"Manifest contains path traversal: {relpath!r}"
+                )
+            if file_path.resolve() == file_cache_path.resolve():
+                if not file_cache_path.exists():
+                    missing.append((entry, file_path, file_cache_path))
+            else:
+                changed[relpath] = _get_symlink_cache_hash(file_path, cache_dir)
+            continue
+        if file_path.exists():
+            if not file_path.is_file():
+                changed[relpath] = None
+                continue
+            if _is_same_file(file_path.stat(), file_cache_path):
+                continue
+            file_hash, _ = hash_file(file_path, state_db)
+            if file_hash != entry["hash"]:
+                changed[relpath] = file_hash
+            continue
+        if not file_path.parent.resolve().is_relative_to(resolved_base):
+            raise exceptions.SecurityValidationError(
+                f"Manifest contains path traversal: {relpath!r}"
+            )
+        missing.append((entry, file_path, file_cache_path))
+
+    files, _ = _scan_entries(path, expected_paths)
+    for relpath in files:
+        if relpath in expected_paths:
+            continue
+        extra_path = path / relpath
+        if extra_path.is_symlink():
+            changed[relpath] = _get_symlink_cache_hash(extra_path, cache_dir)
+        else:
+            changed[relpath], _ = hash_file(extra_path, state_db)
+
+    if changed:
+        # Replacing the directory deletes every file it holds; refuse if any is not cached.
+        local_changes = sorted(
+            rel for rel, content_hash in changed.items() if not _is_cached(cache_dir, content_hash)
+        )
+        if local_changes:
+            return MissingRestore(
+                restored=0, unavailable=0, local_changes=local_changes, replace=False
+            )
+        return MissingRestore(restored=0, unavailable=0, local_changes=[], replace=True)
+
+    unavailable = sum(1 for _, _, file_cache_path in missing if not file_cache_path.exists())
+    if unavailable:
+        return MissingRestore(restored=0, unavailable=unavailable, local_changes=[], replace=False)
+
+    for entry, file_path, file_cache_path in missing:
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        _checkout_with_fallback(
+            file_path, file_cache_path, checkout_modes, executable=entry["isexec"]
+        )
+
+    return MissingRestore(restored=len(missing), unavailable=0, local_changes=[], replace=False)
+
+
 def protect(path: pathlib.Path) -> None:
     """Make file read-only (mode 0o444)."""
     os.chmod(path, 0o444)