pettrace-ml 0.2.5__py3-none-any.whl

pettrace/__init__.py

@@ -0,0 +1,12 @@
+"""Reusable PetTrace ML logic for independently executable experiment notebooks.
+
+Data loading, model inference, training, evaluation and tracking live in this package.
+Experiment configuration, explanations, figures and findings live in notebooks/.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pettrace-ml")
+except PackageNotFoundError:
+    __version__ = "0.2.5.dev3+source"

pettrace/_build.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.2.5",
+  "git_sha": "e1ff5289b6b8f0dd71eb8c418e85305b1dfc987c",
+  "git_dirty": false,
+  "uv_lock_sha256": "30a7a313b7fd2731d4f1d83ed02b6df386f44491709749ba1b6e998b01290dd4",
+  "reference_python": "3.11.15",
+  "uv": "uv 0.11.22 (x86_64-unknown-linux-gnu)"
+}

pettrace/artifact_upload.py

@@ -0,0 +1,61 @@
+"""Lossless transport for JSON evidence exceeding the tracking proxy upload limit."""
+import gzip
+import hashlib
+import json
+from pathlib import Path
+import tempfile
+from contextlib import contextmanager
+
+CHUNK_BYTES = 512 * 1024
+
+
+def log_report_artifacts(local_dir, artifact_path=None, run_id=None):
+    import mlflow
+
+    root = Path(local_dir)
+    for path in sorted(root.rglob('*')):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root)
+        parent = (Path(artifact_path or '') / relative.parent).as_posix()
+        parent = None if parent == '.' else parent
+        if path.suffix != '.json' or path.stat().st_size <= CHUNK_BYTES:
+            mlflow.log_artifact(str(path), artifact_path=parent, run_id=run_id)
+            continue
+        # Keep local evidence untouched; only its remote representation changes.
+        with tempfile.TemporaryDirectory() as tmp:
+            packed = Path(tmp) / 'payload.gz'
+            digest = hashlib.sha256()
+            size = 0
+            with path.open('rb') as source, packed.open('wb') as target:
+                with gzip.GzipFile(filename='', fileobj=target, mode='wb', mtime=0) as output:
+                    while block := source.read(CHUNK_BYTES):
+                        digest.update(block)
+                        size += len(block)
+                        output.write(block)
+            parts = []
+            with packed.open('rb') as source:
+                while block := source.read(CHUNK_BYTES):
+                    part = Path(tmp) / f'{path.name}.gz.part{len(parts):05d}'
+                    part.write_bytes(block)
+                    mlflow.log_artifact(str(part), artifact_path=parent, run_id=run_id)
+                    parts.append({'name': part.name, 'size': len(block),
+                                  'sha256': hashlib.sha256(block).hexdigest()})
+            manifest = Path(tmp) / f'{path.name}.transport.json'
+            manifest.write_text(json.dumps({'schema': 1, 'original': path.name,
+                'size': size, 'sha256': digest.hexdigest(), 'encoding': 'gzip', 'parts': parts,
+                'restore': 'Concatenate parts in listed order, then gzip-decompress; verify original SHA-256.'}, indent=2))
+            mlflow.log_artifact(str(manifest), artifact_path=parent, run_id=run_id)
+
+
+@contextmanager
+def compact_json_uploads():
+    """Allow an already-running v0.2.4 kernel to retry without replacing its package."""
+    import mlflow
+
+    original = mlflow.log_artifacts
+    mlflow.log_artifacts = log_report_artifacts
+    try:
+        yield
+    finally:
+        mlflow.log_artifacts = original

pettrace/cli.py

@@ -0,0 +1,47 @@
+"""Evaluate a `pettrace-embedder` version on a `pettrace-reid` version (thesis protocol).
+
+    make evaluate DATASET=v3 MODEL=models:/pettrace-embedder/1 PROTOCOL=zero-shot [REPORT=reports/e1_v3]
+    python -m pettrace.cli --model /path/to/model/dir --dataset /path/to/dataset/dir
+
+The protocol, model identity and MLflow logging live in pettrace.evaluation.core (shared with the experiment
+notebooks, which are the canonical record of each experiment). --report also writes the figures
+and tables (pettrace.evaluation.figures) and attaches them to the run.
+"""
+
+import argparse
+import os
+import sys
+
+from pettrace.data import benchmark as data
+from pettrace.evaluation.core import evaluate, load_model, log_run, report
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--model", default="models:/pettrace-embedder@production")
+    ap.add_argument("--dataset", required=True, help="version tag (v3) or a local dataset directory")
+    ap.add_argument("--repo", default=data.REPO)
+    ap.add_argument("--protocol", choices=("split", "zero-shot"), default="split",
+                    help="zero-shot: every photo is a query (pretrained models only); EER on the same pairs")
+    ap.add_argument("--report", help="directory for summary.json, scores.json and figures")
+    ap.add_argument("--experiment", default="", help="E1…E5, tagged on the run")
+    args = ap.parse_args()
+
+    ds = data.from_dir(args.dataset) if os.path.isdir(args.dataset) else data.load(args.dataset, args.repo)
+    model = load_model(args.model)
+    if not model.golden_ok:
+        print(f"warning: {args.model} does not reproduce its golden fingerprint", file=sys.stderr)
+    ev = evaluate(ds, model.pipeline, zero_shot=args.protocol == "zero-shot")
+    print(report(ev.result))
+    if args.report:
+        from pettrace.evaluation.figures import save
+
+        save(ev, model, args.report)
+        print(f"report → {args.report}")
+    run_id = log_run(ev, model, experiment=args.experiment, artifacts=args.report)
+    print(f"run {run_id}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pettrace/data/__init__.py

@@ -0,0 +1 @@
+"""Dataset acquisition, preparation and versioned snapshots."""

pettrace/data/acquisition.py

@@ -0,0 +1,117 @@
+"""Acquire public body-ID datasets, retain provenance, then build an audited manifest."""
+
+import hashlib
+import io
+import json
+import os
+import zipfile
+from pathlib import Path
+
+import requests
+
+from pettrace.data.curation import audit_and_split, discover
+
+MPDD_URL = "https://data.mendeley.com/public-files/datasets/v5j6m8dzhv/files/05d1d583-faf6-410d-89a5-a6b1134b6e5e/file_downloaded"
+MPDD_SHA256 = "6c800c1b4aa67629544dec7444dee85bc57781abde1ae1d077ea9ef1804284cd"
+
+
+def download(url, destination, expected_hash=None, auth=None):
+    destination = Path(destination)
+    digest = hashlib.sha256()
+    if not destination.exists():
+        partial = destination.with_suffix(".partial")
+        try:
+            with requests.get(url, stream=True, timeout=(30, 120), auth=auth) as response:
+                response.raise_for_status()
+                total = int(response.headers.get("Content-Length", 0))
+                received, last = 0, 0
+                with partial.open("wb") as f:
+                    for block in response.iter_content(1 << 20):
+                        if block:
+                            f.write(block)
+                            received += len(block)
+                            if received - last >= 128 << 20:
+                                print(f"Downloaded {received / 2**20:.0f} MiB / {total / 2**20:.0f} MiB", flush=True)
+                                last = received
+            if not zipfile.is_zipfile(partial):
+                raise ValueError("Download is not a ZIP; authenticate/download manually from the source")
+            partial.replace(destination)
+        except Exception:
+            # Leave a clearly named partial file for diagnosis, never treat it as a completed dataset.
+            raise
+    with destination.open("rb") as f:
+        for block in iter(lambda: f.read(1 << 20), b""):
+            digest.update(block)
+    result = digest.hexdigest()
+    if expected_hash and result != expected_hash:
+        raise ValueError(f"Archive SHA-256 mismatch: {destination.name}")
+    return result
+
+
+def extract(archive, destination):
+    destination = Path(destination).resolve()
+    destination.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive) as z:
+        nested_archives = [destination / info.filename for info in z.infolist()
+                           if info.filename.lower().endswith(".zip")]
+        for info in z.infolist():
+            target = (destination / info.filename).resolve()
+            if not target.is_relative_to(destination) or (info.external_attr >> 16) & 0o170000 == 0o120000:
+                raise ValueError("Unsafe archive path or symlink")
+        z.extractall(destination)
+    # Some publisher downloads are a wrapper ZIP containing the actual MPDD archive.
+    for nested in nested_archives:
+        with nested.open("rb") as f:
+            payload = io.BytesIO(f.read())
+        extract(payload, nested.parent)
+
+
+def prepare(root, cat_root=None, mpdd_root=None, cat_version=None):
+    root = Path(root)
+    root.mkdir(parents=True, exist_ok=True)
+    sources = []
+    if mpdd_root is None:
+        archive = root / "MPDD-v1.zip"
+        archive_hash = download(MPDD_URL, archive, MPDD_SHA256)
+        mpdd_root = root / "mpdd"
+        if not (mpdd_root / ".extracted").exists():
+            extract(archive, mpdd_root)
+            (mpdd_root / ".extracted").write_text(archive_hash)
+        sources.append({"name": "MPDD", "version": 1, "sha256": archive_hash,
+                        "url": "https://data.mendeley.com/datasets/v5j6m8dzhv/1", "license": "CC BY 4.0"})
+    else:
+        sources.append({"name": "MPDD", "root": str(mpdd_root), "version": "user-provided archive",
+                        "license": "CC BY 4.0; verify supplied source matches publisher"})
+    if cat_root is None:
+        auth = None
+        if os.environ.get("KAGGLE_USERNAME") and os.environ.get("KAGGLE_KEY"):
+            auth = (os.environ["KAGGLE_USERNAME"], os.environ["KAGGLE_KEY"])
+        metadata_url = "https://www.kaggle.com/api/v1/datasets/view/timost1234/cat-individuals"
+        if cat_version is None:
+            metadata = requests.get(metadata_url, timeout=30, auth=auth)
+            metadata.raise_for_status()
+            cat_version = metadata.json().get("currentVersionNumber")
+            if not cat_version:
+                raise ValueError("Cannot resolve CatIndividuals version; supply an extracted cat_root")
+        archive = root / f"CatIndividuals-v{cat_version}.zip"
+        url = f"https://www.kaggle.com/api/v1/datasets/download/timost1234/cat-individuals?datasetVersionNumber={cat_version}"
+        archive_hash = download(url, archive, auth=auth)
+        cat_root = root / f"cats-v{cat_version}"
+        if not (cat_root / ".extracted").exists():
+            extract(archive, cat_root)
+            (cat_root / ".extracted").write_text(archive_hash)
+        sources.append({"name": "CatIndividualImages", "version": cat_version, "sha256": archive_hash,
+                        "url": "https://www.kaggle.com/datasets/timost1234/cat-individuals",
+                        "license": "CC BY 4.0 per WildlifeDatasets 1.0.9; retain publisher terms"})
+    else:
+        sources.append({"name": "CatIndividualImages", "root": str(cat_root), "version": "user-provided archive",
+                        "license": "Retain and verify the downloaded dataset's license"})
+    dogs, skipped_dogs = discover(mpdd_root, "mpdd", "dog")
+    cats, skipped_cats = discover(cat_root, "cat-individuals", "cat")
+    rows, audit = audit_and_split(dogs + cats, root / "curated")
+    (root / "curated/sources.json").write_text(json.dumps({"sources": sources,
+        "skipped_paths": skipped_dogs + skipped_cats}, indent=2))
+    print(json.dumps(audit["counts"], indent=2))
+    print("Conservative duplicate removals:", len(audit["removed_duplicates"]))
+    print("No automatic audit can confirm different photo sessions; inspect the public examples.")
+    return root / "curated/manifest.csv", rows, audit

pettrace/data/benchmark.py

@@ -0,0 +1,71 @@
+"""Load a pinned version of the `pettrace-reid` dataset (private Hugging Face dataset).
+
+Training and evaluation read only published versions — never R2 or the app API — so every result
+traces back to an immutable snapshot. Needs a read token in HF_TOKEN.
+"""
+
+import csv
+import hashlib
+import os
+from dataclasses import dataclass, field
+
+REPO = os.environ.get("HF_DATASET_REPO", "alessandro54/pettrace-reid")
+
+
+@dataclass
+class Photo:
+    path: str  # absolute path of the image
+    animal: str
+    species: str
+    split: str
+    light: float
+
+
+@dataclass
+class Dataset:
+    repo: str
+    version: str
+    commit: str  # Hub commit the tag points to
+    fingerprint: str  # sha256 of metadata.csv (first 16 hex): changes iff labels/photos change
+    root: str
+    animals: dict[str, dict] = field(default_factory=dict)  # animal_id → animals.csv row
+    photos: list[Photo] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return f"{self.repo.split('/')[-1]}@{self.version}"
+
+    @property
+    def url(self) -> str:
+        return f"https://huggingface.co/datasets/{self.repo}/tree/{self.version}"
+
+    def split(self, name: str) -> list[Photo]:
+        return [p for p in self.photos if p.split == name]
+
+
+def load(version: str, repo: str = REPO, cache_dir: str | None = None) -> Dataset:
+    from huggingface_hub import HfApi, snapshot_download
+
+    commit = HfApi().dataset_info(repo, revision=version).sha
+    root = snapshot_download(repo, repo_type="dataset", revision=commit, cache_dir=cache_dir)
+    return from_dir(root, repo=repo, version=version, commit=commit)
+
+
+def from_dir(root: str, repo: str = REPO, version: str = "local", commit: str = "") -> Dataset:
+    meta_path = os.path.join(root, "metadata.csv")
+    with open(meta_path, "rb") as f:
+        fingerprint = hashlib.sha256(f.read()).hexdigest()[:16]
+    with open(os.path.join(root, "animals.csv"), newline="") as f:
+        animals = {row["animal_id"]: row for row in csv.DictReader(f)}
+    with open(meta_path, newline="") as f:
+        photos = [
+            Photo(
+                path=os.path.join(root, row["file_name"]),
+                animal=row["animal_id"],
+                species=row["species"],
+                split=row["split"],
+                light=float(row.get("light") or 0),
+            )
+            for row in csv.DictReader(f)
+        ]
+    return Dataset(repo, version, commit, fingerprint, root, animals, photos)

pettrace/data/checkpoints.py

@@ -0,0 +1,259 @@
+"""Immutable incremental archives on mounted Drive; computation stays on local disk."""
+
+import hashlib
+import json
+import shutil
+import sqlite3
+import tarfile
+import tempfile
+import time
+from pathlib import Path, PurePosixPath
+from uuid import uuid4
+
+from pettrace.data.verification import sha256 as verified_sha256
+
+
+def _sha(path):
+    with Path(path).open('rb') as stream:
+        return hashlib.file_digest(stream, 'sha256').hexdigest()
+
+
+def _safe(name):
+    path = PurePosixPath(name)
+    if path.is_absolute() or '..' in path.parts or '\\' in name or len(path.parts) < 2:
+        raise ValueError('Unsafe checkpoint path')
+    return path
+
+
+class DriveBackup:
+    """One writer per backup directory. Only confirmed archives can be restored.
+
+    Call periodically at completed work units, and use as a context manager to
+    save on normal exit or Python exceptions. Abrupt VM loss retains the last
+    confirmed checkpoint, not the unfinished work since that checkpoint.
+    """
+
+    def __init__(self, roots, destination, *, interval=300, block_bytes=512 * 2**20):
+        self.roots = {name: Path(path).resolve() for name, path in roots.items()}
+        if not self.roots or any('/' in name or name in {'', '.', '..'} for name in self.roots):
+            raise ValueError('Use simple named checkpoint roots')
+        self.destination = Path(destination).resolve()
+        if interval < 0 or block_bytes <= 0:
+            raise ValueError('Invalid checkpoint interval or block size')
+        if any(self.destination.is_relative_to(p) or p.is_relative_to(self.destination)
+               for p in self.roots.values()):
+            raise ValueError('Backups and working directories must be separate')
+        self.interval, self.block_bytes = interval, block_bytes
+        self._saved = {}
+        self._pending_paths = set()
+        self._last = time.monotonic()
+
+    def _target(self, name):
+        relative = _safe(name)
+        root = self.roots.get(relative.parts[0])
+        if root is None:
+            raise ValueError('Unknown checkpoint root')
+        target = root.joinpath(*relative.parts[1:])
+        if not target.resolve().is_relative_to(root):
+            raise ValueError('Checkpoint path escapes working directory')
+        return target
+
+    def restore(self, *, only=None, files=None):
+        """Restore selected roots or exact archive paths, verifying confirmed packs."""
+        if only is not None and not set(only) <= self.roots.keys():
+            raise ValueError("Unknown restore root")
+        if files is not None:
+            files = set(files)
+            for name in files:
+                self._target(name)
+                if only is not None and _safe(name).parts[0] not in only:
+                    raise ValueError("Requested file is outside the selected restore roots")
+        latest, receipts = {}, {}
+        for receipt_path in sorted(self.destination.glob('*.json')):
+            receipt = json.loads(receipt_path.read_text())
+            if receipt.get('schema') != 1 or receipt.get('archive') != receipt_path.with_suffix('.tar').name:
+                raise ValueError('Invalid checkpoint receipt')
+            for name, info in receipt['files'].items():
+                if files is not None and name not in files:
+                    continue
+                label = _safe(name).parts[0]
+                if label not in self.roots:
+                    raise ValueError('Unknown checkpoint root')
+                if only is None or label in only:
+                    self._target(name)
+                    receipts[receipt_path.name] = receipt
+                    latest[name] = (receipt_path.name, info)
+        if files is not None and files - latest.keys():
+            raise FileNotFoundError(f"No confirmed Drive backup for: {', '.join(sorted(files - latest.keys()))}")
+        needed = {}
+        for name, (receipt_name, info) in latest.items():
+            target = self._target(name)
+            if not target.is_file() or target.stat().st_size != info['size'] or verified_sha256(target) != info['sha256']:
+                needed.setdefault(receipt_name, set()).add(name)
+        for receipt_name, names in needed.items():
+            receipt = receipts[receipt_name]
+            with tempfile.TemporaryDirectory(prefix='pettrace-restore-') as folder:
+                local = Path(folder) / 'block.tar'
+                shutil.copyfile(self.destination / receipt['archive'], local)
+                if _sha(local) != receipt['sha256']:
+                    raise ValueError('Checkpoint archive checksum mismatch')
+                with tarfile.open(local) as archive:
+                    members = archive.getmembers()
+                    if len({m.name for m in members}) != len(members) or {m.name for m in members} != set(receipt['files']):
+                        raise ValueError('Checkpoint inventory mismatch')
+                    for member in members:
+                        self._target(member.name)
+                        if not member.isfile() or member.size != receipt['files'][member.name]['size']:
+                            raise ValueError('Unsafe checkpoint member')
+                    for member in members:
+                        if member.name not in names:
+                            continue
+                        target = self._target(member.name)
+                        target.parent.mkdir(parents=True, exist_ok=True)
+                        with tempfile.NamedTemporaryFile(dir=target.parent, delete=False) as stream:
+                            partial = Path(stream.name)
+                            with archive.extractfile(member) as source:
+                                shutil.copyfileobj(source, stream)
+                        try:
+                            if _sha(partial) != receipt['files'][member.name]['sha256']:
+                                raise ValueError('Checkpoint member checksum mismatch')
+                            partial.replace(target)
+                        finally:
+                            partial.unlink(missing_ok=True)
+                print(f'Drive: bloque restaurado ({len(names)} archivos).', flush=True)
+        for name in latest:
+            self._saved[name] = self._signature(self._target(name))
+        print(f'Drive: {len(latest)} archivos verificados; respaldo listo.', flush=True)
+
+    @staticmethod
+    def _signature(path):
+        stat = path.stat()
+        return stat.st_size, stat.st_mtime_ns
+
+    def __call__(self, *, force=False, paths=None):
+        """Back up supplied files/subtrees, or scan all roots when paths is omitted.
+
+        Paths accumulate until the next checkpoint; context exit always scans all
+        roots so exceptions and callers without change tracking remain recoverable.
+        """
+        if paths is not None:
+            for path in paths:
+                path = Path(path).absolute()
+                match = next(((label, root) for label, root in self.roots.items() if path.is_relative_to(root)), None)
+                if match is None:
+                    raise ValueError('Checkpoint path is outside its roots')
+                label, root = match
+                if path != root:
+                    self._target(f'{label}/{path.relative_to(root).as_posix()}')
+                if path.is_symlink():
+                    raise ValueError('Checkpoint roots must contain regular files, not symlinks')
+                self._pending_paths.add(path)
+        if not force and time.monotonic() - self._last < self.interval:
+            return
+        def candidates():
+            for label, root in self.roots.items():
+                if not root.exists():
+                    continue
+                selected = {root} if paths is None else {p for p in self._pending_paths if p.is_relative_to(root)}
+                for path in sorted(selected):
+                    if any(parent in selected for parent in path.parents):
+                        continue
+                    yield from ((label, p) for p in (path.rglob('*') if path.is_dir() else [path]))
+
+        pending, size = [], 0
+        for label, path in candidates():
+            relative = path.relative_to(self.roots[label])
+            # Incomplete outputs, Hub internals and SQLite journals are not snapshots.
+            if any(p.startswith('.') for p in relative.parts) or path.name.endswith(('.partial', '-wal', '-shm', '-journal')):
+                continue
+            name = f'{label}/{relative.as_posix()}'
+            if path.is_symlink():
+                raise ValueError('Checkpoint roots must contain regular files, not symlinks')
+            if not path.is_file():
+                continue
+            signature = self._signature(path)
+            if self._saved.get(name) == signature:
+                continue
+            pending.append((name, path, signature))
+            size += signature[0]
+            if size >= self.block_bytes:
+                self._save_block(pending)
+                pending, size = [], 0
+        if pending:
+            self._save_block(pending)
+        self._pending_paths.clear()
+        self._last = time.monotonic()
+
+    def _save_block(self, files):
+        self.destination.mkdir(parents=True, exist_ok=True)
+        key = f'{time.time_ns():020d}-{uuid4().hex}'
+        with tempfile.TemporaryDirectory(prefix='pettrace-checkpoint-') as folder:
+            folder = Path(folder)
+            pack = folder / f'{key}.tar'
+            inventory = {}
+            with tarfile.open(pack, 'w') as archive:
+                for name, path, signature in files:
+                    source = path
+                    if path.suffix == '.sqlite3':
+                        source = folder / 'snapshot.sqlite3'
+                        source.unlink(missing_ok=True)
+                        with sqlite3.connect(f'{path.as_uri()}?mode=ro', uri=True) as db, sqlite3.connect(source) as copy:
+                            db.backup(copy)
+                    inventory[name] = {'size': source.stat().st_size, 'sha256': _sha(source)}
+                    archive.add(source, arcname=name, recursive=False)
+                    if self._signature(path) != signature:
+                        raise RuntimeError('File changed during backup; retry at a completed work unit')
+            digest = _sha(pack)
+            remote = self.destination / pack.name
+            partial = remote.with_suffix('.tar.partial')
+            shutil.copyfile(pack, partial)
+            if _sha(partial) != digest:
+                raise IOError('Drive backup verification failed')
+            partial.replace(remote)
+            receipt = {'schema': 1, 'archive': remote.name, 'sha256': digest, 'files': inventory}
+            temporary = remote.with_suffix('.json.partial')
+            temporary.write_text(json.dumps(receipt, sort_keys=True))
+            if json.loads(temporary.read_text()) != receipt:
+                raise IOError('Drive receipt verification failed')
+            temporary.replace(remote.with_suffix('.json'))
+        for name, _, signature in files:
+            self._saved[name] = signature
+        print(f'Drive: respaldo confirmado ({len(files)} archivos, {pack.name}).', flush=True)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        self(force=True)
+        return False
+
+
+def stage_archive(source, destination):
+    """Copy a Drive ZIP to local scratch; acquisition verifies its pinned index and CRCs."""
+    source, destination = Path(source).resolve(), Path(destination).resolve()
+    if source == destination:
+        raise ValueError('ZIP staging must use a separate local destination')
+    stat = source.stat()
+    signature = {'size': stat.st_size, 'mtime_ns': stat.st_mtime_ns}
+    receipt = destination.with_suffix(destination.suffix + '.json')
+    if destination.is_file() and receipt.is_file() and json.loads(receipt.read_text()) == signature:
+        if destination.stat().st_size == stat.st_size:
+            return destination
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if shutil.disk_usage(destination.parent).free < stat.st_size + 64 * 2**20:
+        raise OSError("Insufficient local disk space to stage the source ZIP")
+    partial = destination.with_suffix(destination.suffix + '.partial')
+    with source.open('rb') as incoming, partial.open('wb') as outgoing:
+        copied, last = 0, time.monotonic()
+        while block := incoming.read(8 * 2**20):
+            outgoing.write(block)
+            copied += len(block)
+            if time.monotonic() - last >= 5:
+                print(f'\rZIP {source.name}: {copied / 2**30:.1f}/{stat.st_size / 2**30:.1f} GiB', end='', flush=True)
+                last = time.monotonic()
+    if source.stat().st_mtime_ns != stat.st_mtime_ns or copied != stat.st_size:
+        raise IOError('Source ZIP changed during transfer')
+    partial.replace(destination)
+    receipt.write_text(json.dumps(signature))
+    print(f'\rZIP {source.name}: copia local lista; se verificará índice y CRC al extraer.', flush=True)
+    return destination