if-split 0.1.0__py3-none-any.whl

ifsplit/ligands.py

@@ -0,0 +1,267 @@
+"""Stage 4 - Tier and classify non-protein components (metadata only).
+
+Curation comes *before* classification, and quality is **annotated, never
+destroyed**: no structure is dropped for ligand-quality reasons (a protein with a
+junk ion is still a good training backbone). Each non-protein component is tiered
+
+  - ``functional``  : real, biologically meaningful ligand/site
+  - ``ambiguous``   : present and contacting, but unconfirmed
+  - ``artifact``    : buffer / cryoprotectant / counterion / purification tag
+
+with a machine-readable reason. Ligand-*class* labels (metal / small_molecule /
+nucleotide) derive from the tier via a config threshold (default: only
+``functional`` sets a class label; ``ambiguous`` is reported but not labelled;
+``artifact`` is excluded). A downstream featurizer reads the same per-component
+tier to decide what counts as real ligand context — this is the lever that
+improves *training* quality, not just test reporting.
+
+Signals used (all from the Data API, no coordinates):
+  - ``bound_components``  : the comp actually contacts the protein (buffer gate)
+  - ``affinity_comp_ids`` : a measured binding affinity exists (strong positive)
+  - chem-comp ``formula`` : metal-only vs organic
+  - His-tag + Ni/Co       : the IMAC purification-artifact pattern (existing rule)
+  - protein_na_interface_count: a protein<->nucleic-acid assembly interface (>0)
+                            verifies a real contact (holo gate for nucleotide)
+"""
+
+from __future__ import annotations
+
+import re
+
+from .config import Config
+from .schema import CandidateRecord, NonpolymerComp
+
+# Ligand classes IF-Split tracks.
+CLASS_METAL = "metal"
+CLASS_NUCLEOTIDE = "nucleotide"
+CLASS_SMALL_MOLECULE = "small_molecule"
+
+# Confidence tiers.
+TIER_FUNCTIONAL = "functional"
+TIER_AMBIGUOUS = "ambiguous"
+TIER_ARTIFACT = "artifact"
+
+# Elements that count as a "metal ion" when a component's formula is made up
+# only of these. A comp like HEM (C34 H32 Fe N4 O4) is NOT a metal ion — its
+# formula contains C/H/N/O — so it falls through to small-molecule.
+METAL_ELEMENTS: frozenset[str] = frozenset(
+    {
+        "LI", "BE", "NA", "MG", "AL", "K", "CA", "SC", "TI", "V", "CR", "MN",
+        "FE", "CO", "NI", "CU", "ZN", "GA", "RB", "SR", "Y", "ZR", "NB", "MO",
+        "TC", "RU", "RH", "PD", "AG", "CD", "IN", "SN", "CS", "BA", "LA", "CE",
+        "PR", "ND", "PM", "SM", "EU", "GD", "TB", "DY", "HO", "ER", "TM", "YB",
+        "LU", "HF", "TA", "W", "RE", "OS", "IR", "PT", "AU", "HG", "TL", "PB",
+        "BI",
+    }
+)  # fmt: skip
+
+# Monatomic counterions / phasing atoms: even though some are technically metals,
+# as lone ions they are crystallization/phasing additives, not biological sites.
+COUNTERION_COMPS: frozenset[str] = frozenset(
+    {"NA", "CL", "K", "BR", "I", "IOD", "CS", "RB", "F", "LI"}
+)
+
+# Common crystallization additives / buffer junk. Config-extensible via
+# excluded_het; this is the always-on baseline.
+DEFAULT_ADDITIVE_BLACKLIST: frozenset[str] = frozenset(
+    {
+        "HOH", "DOD",  # water
+        "GOL", "EDO", "PEG", "PG4", "PGE", "1PE", "2PE", "P6G", "PE4", "MPD",
+        "SO4", "PO4", "ACT", "ACY", "FMT", "EPE", "MES", "TRS", "BME", "DTT",
+        "IMD", "DMS", "BOG", "OLC", "LDA", "SCN", "AZI", "NO3", "CO3", "FLC",
+        "TLA", "CIT", "MLI", "IOD", "GLC", "BCN", "MRD", "BU3", "P33",
+    }
+)  # fmt: skip
+
+_ELEMENT_RE = re.compile(r"[A-Z][a-z]?")
+
+
+def elements_in_formula(formula: str | None) -> set[str]:
+    """Element symbols present in a chem-comp formula, upper-cased.
+
+    ``"C34 H32 Fe N4 O4"`` -> ``{"C", "H", "FE", "N", "O"}``; ``"Zn"`` -> ``{"ZN"}``.
+    Charge tokens and counts are ignored.
+    """
+    if not formula:
+        return set()
+    cleaned = re.sub(r"[0-9]+[+-]?", " ", formula)
+    return {m.group(0).upper() for m in _ELEMENT_RE.finditer(cleaned)}
+
+
+def is_metal_ion(comp: NonpolymerComp) -> bool:
+    """True if the component's formula is composed only of metal element(s)."""
+    elems = elements_in_formula(comp.formula)
+    if not elems:
+        elems = {comp.comp_id} if comp.comp_id in METAL_ELEMENTS else set()
+    return bool(elems) and elems <= METAL_ELEMENTS
+
+
+def longest_residue_run(seq: str, residue: str = "H") -> int:
+    """Length of the longest consecutive run of ``residue`` in ``seq``."""
+    if not seq:
+        return 0
+    best = run = 0
+    up = seq.upper()
+    res = residue.upper()
+    for ch in up:
+        if ch == res:
+            run += 1
+            best = max(best, run)
+        else:
+            run = 0
+    return best
+
+
+def has_histag(seq: str, min_run: int) -> bool:
+    """True if ``seq`` contains a poly-histidine run of at least ``min_run``."""
+    return longest_residue_run(seq, "H") >= min_run
+
+
+def has_protein_na_interface(record: CandidateRecord) -> bool:
+    """True if the assembly has a protein<->nucleic-acid interface.
+
+    Reads RCSB's precomputed ``num_prot_na_interface_entities`` — a metadata signal
+    that the protein actually *contacts* the DNA/RNA, not just that both were
+    co-deposited. No coordinates.
+    """
+    return record.protein_na_interface_count > 0
+
+
+def metal_comps(record: CandidateRecord) -> list[NonpolymerComp]:
+    return [c for c in record.nonpolymer_comps if is_metal_ion(c)]
+
+
+def is_purification_artifact(
+    record: CandidateRecord,
+    *,
+    purification_metals: set[str],
+    histag_min_run: int,
+) -> bool:
+    """Flag the His-tag-binds-Ni/Co purification-artifact pattern.
+
+    True only when (a) the entry has at least one metal, (b) *every* metal it has
+    is a purification metal, and (c) some protein chain carries a His-tag. A real
+    metal site (e.g. a catalytic Zn) present alongside a tag is NOT flagged.
+    """
+    if not purification_metals:
+        return False
+    metals = {c.comp_id for c in metal_comps(record)}
+    if not metals or not metals <= purification_metals:
+        return False
+    return any(has_histag(e.seq, histag_min_run) for e in record.polymer_entities if e.is_protein)
+
+
+def tier_component(
+    comp: NonpolymerComp,
+    record: CandidateRecord,
+    cfg: Config,
+    *,
+    blacklist: set[str],
+    purification: set[str],
+    is_artifact_entry: bool,
+) -> tuple[str, str, str | None]:
+    """Tier a single non-protein component.
+
+    Returns ``(tier, reason, class_label_or_None)``. The class label is set only
+    for the ``functional`` tier (the default threshold); ``ambiguous`` components
+    return their would-be class as None so they are reported but not labelled.
+    """
+    cid = comp.comp_id
+    bound = cid in set(record.bound_components)
+    has_affinity = cid in set(record.affinity_comp_ids)
+
+    if is_metal_ion(comp):
+        # Lone counterion / phasing atom -> artifact regardless of binding.
+        if cid in COUNTERION_COMPS:
+            return TIER_ARTIFACT, "counterion", None
+        # His-tag/Ni(Co) IMAC purification artifact.
+        if is_artifact_entry and cfg.exclude_purification_artifacts and cid in purification:
+            return TIER_ARTIFACT, "histag_metal", None
+        if has_affinity:
+            return TIER_FUNCTIONAL, "metal_affinity", CLASS_METAL
+        if bound:
+            return TIER_FUNCTIONAL, "metal_bound", CLASS_METAL
+        # "Trust biological metals" but require contact: an unbound metal far from
+        # the protein is adventitious -> ambiguous, not functional.
+        return TIER_AMBIGUOUS, "metal_unbound", None
+
+    # Non-metal small molecule.
+    if cid in blacklist:
+        return TIER_ARTIFACT, "additive", None
+    if has_affinity:
+        return TIER_FUNCTIONAL, "ligand_affinity", CLASS_SMALL_MOLECULE
+    if bound:
+        return TIER_FUNCTIONAL, "ligand_bound", CLASS_SMALL_MOLECULE
+    return TIER_AMBIGUOUS, "ligand_unbound", None
+
+
+def classify_components(record: CandidateRecord, cfg: Config) -> dict:
+    """Tier + classify one entry's components into ligand classes (metadata only).
+
+    The structure is always kept; only labels and tiers are assigned. Returns
+    per-component tiers, the functional class tags, the ambiguous class tags, and
+    curation flags.
+    """
+    blacklist = DEFAULT_ADDITIVE_BLACKLIST | set(cfg.excluded_het)
+    purification = set(cfg.purification_metals)
+    is_artifact_entry = is_purification_artifact(
+        record,
+        purification_metals=purification,
+        histag_min_run=cfg.histag_min_run,
+    )
+
+    tiers: dict[str, dict[str, str]] = {}
+    functional_metals: list[str] = []
+    functional_sms: list[str] = []
+    ambiguous_classes: set[str] = set()
+
+    for comp in record.nonpolymer_comps:
+        tier, reason, label = tier_component(
+            comp,
+            record,
+            cfg,
+            blacklist=blacklist,
+            purification=purification,
+            is_artifact_entry=is_artifact_entry,
+        )
+        tiers[comp.comp_id] = {"tier": tier, "reason": reason}
+        if tier == TIER_FUNCTIONAL and label == CLASS_METAL:
+            functional_metals.append(comp.comp_id)
+        elif tier == TIER_FUNCTIONAL and label == CLASS_SMALL_MOLECULE:
+            functional_sms.append(comp.comp_id)
+        elif tier == TIER_AMBIGUOUS:
+            # Record the would-be class for reporting (metal vs small molecule).
+            ambiguous_classes.add(CLASS_METAL if is_metal_ion(comp) else CLASS_SMALL_MOLECULE)
+
+    # Nucleotide class = DNA/RNA polymer chains. Functional only if the protein
+    # actually *interfaces* the nucleic acid (RCSB assembly-interface metadata);
+    # an NA chain with no protein/NA interface is co-deposited, not holo, so the
+    # class is reported as ambiguous, not labelled. Non-polymer nucleotides
+    # (ATP/GTP/NAD) are handled above as small molecules.
+    has_nucleotide = any(e.is_nucleic for e in record.polymer_entities)
+    nucleotide_functional = has_nucleotide and has_protein_na_interface(record)
+    if has_nucleotide:
+        if nucleotide_functional:
+            tiers["nucleic_acid"] = {"tier": TIER_FUNCTIONAL, "reason": "protein_na_interface"}
+        else:
+            ambiguous_classes.add(CLASS_NUCLEOTIDE)
+            tiers["nucleic_acid"] = {"tier": TIER_AMBIGUOUS, "reason": "no_protein_na_interface"}
+
+    classes: set[str] = set()
+    if functional_metals:
+        classes.add(CLASS_METAL)
+    if functional_sms:
+        classes.add(CLASS_SMALL_MOLECULE)
+    if nucleotide_functional:
+        classes.add(CLASS_NUCLEOTIDE)
+
+    return {
+        "entry_id": record.entry_id,
+        "classes": sorted(classes),  # functional-tier class labels
+        "ambiguous_classes": sorted(ambiguous_classes - classes),
+        "metals": sorted(functional_metals),
+        "small_molecules": sorted(functional_sms),
+        "has_nucleotide": has_nucleotide,
+        "tiers": dict(sorted(tiers.items())),
+        "purification_artifact": is_artifact_entry,
+    }

ifsplit/manifest.py

@@ -0,0 +1,417 @@
+"""Stage 7 - Snapshot lock, manifest, split registry, and verify/stats commands.
+
+Artifacts written to the output dir:
+
+- ``dataset.lock``   - reproduction anchor: embedded config + canonical
+  ``candidates.jsonl`` hash + entry-id list. ``verify`` re-enumerates from it and
+  reports drift (added/removed entries, hash match), warning not failing.
+- ``manifest.json``  - small (~KB) provenance record: config, drop log, per-split
+  + per-class counts, cluster/component stats, and a ``files`` index pointing at
+  the data files below. No per-entry arrays, so it stays tiny at any scale. Built
+  as a pure function of its inputs (no wall-clock fields) -> byte-identical across
+  runs of the same config.
+
+The split itself is plain lists of PDB ids, each its own file:
+- ``train.json`` / ``val.json`` / ``test.json`` - the entry ids in each split
+  (one id per line; grepable and trivially loadable).
+- ``test/<class>_test.json`` - the test ids carrying each functional ligand class
+  (``metal`` / ``small_molecule`` / ``nucleotide``), for per-class evaluation.
+
+Supporting maps (only needed for sampling / curation, not to read the split):
+- ``clusters.json`` - entry_id -> component key (for cluster-balanced sampling).
+- ``ligands.classes.json`` - entry_id -> functional class labels.
+- ``ligands.tiers.json`` - per-component curation *audit trail* (tier + reason);
+  bulky (~24 MB at full-PDB scale), read only by ``fetch`` and curation audits.
+- ``splits.registry.json`` - canonical_key -> split, so a later, larger snapshot
+  reuses prior assignments instead of re-hashing (growth stability).
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .config import Config
+
+LOCK_SCHEMA = "if-split/lock@1"
+MANIFEST_SCHEMA = "if-split/manifest@2"
+REGISTRY_SCHEMA = "if-split/registry@1"
+TIERS_SCHEMA = "if-split/tiers@1"
+
+# Data files written next to manifest.json (referenced by manifest["files"]).
+TIERS_FILENAME = "ligands.tiers.json"
+CLASSES_FILENAME = "ligands.classes.json"
+CLUSTERS_FILENAME = "clusters.json"
+SPLIT_FILES = {"train": "train.json", "val": "val.json", "test": "test.json"}
+TEST_SUBDIR = "test"  # per-class test-id lists live here: test/<class>_test.json
+
+
+# --------------------------------------------------------------------------- #
+# Lock (Stage 1 reproduction anchor)
+# --------------------------------------------------------------------------- #
+def build_lock(
+    cfg: Config,
+    *,
+    entry_ids: list[str],
+    candidates_sha256: str,
+    limit: int | None,
+) -> dict[str, Any]:
+    """Assemble the lock document (pure; does not touch disk)."""
+    return {
+        "lock_schema": LOCK_SCHEMA,
+        "dataset_version": cfg.dataset_version,
+        "if_split_version": __version__,
+        "config_hash": cfg.config_hash(),
+        "config": cfg.canonical_dict(),
+        "selection": {"limit": limit},
+        "candidates": {
+            "count": len(entry_ids),
+            "sha256": candidates_sha256,
+            "entry_ids": sorted(entry_ids),
+        },
+    }
+
+
+def _write_json(obj: dict[str, Any], path: Path, *, compact: bool = False) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if compact:
+        text = json.dumps(obj, sort_keys=True, separators=(",", ":"))
+    else:
+        text = json.dumps(obj, indent=2, sort_keys=True)
+    path.write_text(text + "\n", encoding="utf-8")
+    return path
+
+
+def write_lock(lock: dict[str, Any], out_dir: str | Path) -> Path:
+    return _write_json(lock, Path(out_dir) / "dataset.lock")
+
+
+def read_lock(path: str | Path) -> dict[str, Any]:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Lock file not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+# --------------------------------------------------------------------------- #
+# Split registry (growth stability)
+# --------------------------------------------------------------------------- #
+def read_registry(path: str | Path) -> dict[str, str]:
+    """Load a canonical_key -> split registry, or {} if absent."""
+    path = Path(path)
+    if not path.exists():
+        return {}
+    doc = json.loads(path.read_text(encoding="utf-8"))
+    return dict(doc.get("assignments", {}))
+
+
+def write_registry(cluster_split: dict[str, str], out_dir: str | Path) -> Path:
+    doc = {
+        "registry_schema": REGISTRY_SCHEMA,
+        "assignments": dict(sorted(cluster_split.items())),
+    }
+    return _write_json(doc, Path(out_dir) / "splits.registry.json")
+
+
+# --------------------------------------------------------------------------- #
+# Manifest (human-facing, deterministic)
+# --------------------------------------------------------------------------- #
+def build_manifest(
+    cfg: Config,
+    *,
+    candidates_sha256: str,
+    n_candidates: int,
+    drops: list[dict],
+    drop_counts: dict[str, int],
+    clusters,
+    splits,
+    class_map: dict[str, dict],
+) -> dict[str, Any]:
+    """Assemble manifest.json as a pure function of the build outputs."""
+    from .split import SPLITS
+
+    # Per-split entry lists.
+    per_split: dict[str, list[str]] = {s: [] for s in SPLITS}
+    for entry, s in splits.entry_split.items():
+        per_split[s].append(entry)
+    for s in per_split:
+        per_split[s].sort()
+
+    # Per-split, per-class counts at the functional tier (the test-quality view),
+    # plus the ambiguous counts so under-/over-confidence is visible.
+    def _class_counts(entries, key):
+        counts: dict[str, int] = {}
+        for entry in entries:
+            for cls in class_map.get(entry, {}).get(key, []):
+                counts[cls] = counts.get(cls, 0) + 1
+        return dict(sorted(counts.items()))
+
+    per_split_class_counts = {s: _class_counts(per_split[s], "classes") for s in SPLITS}
+    per_split_ambiguous_counts = {
+        s: _class_counts(per_split[s], "ambiguous_classes") for s in SPLITS
+    }
+    n_artifacts = sum(1 for info in class_map.values() if info.get("purification_artifact"))
+
+    # Per-class test-id files that will be written (only classes that occur).
+    test_class_files = {
+        cls: f"{TEST_SUBDIR}/{cls}_test.json" for cls in per_split_class_counts["test"]
+    }
+
+    # The manifest is small provenance only: NO per-entry arrays live here. The
+    # split membership and supporting maps are separate files (see "files").
+    return {
+        "manifest_schema": MANIFEST_SCHEMA,
+        "dataset_version": cfg.dataset_version,
+        "if_split_version": __version__,
+        "config_hash": cfg.config_hash(),
+        "config": cfg.canonical_dict(),
+        "candidates": {"count": n_candidates, "sha256": candidates_sha256},
+        "filter": {
+            "kept": len(splits.entry_split),
+            "dropped": len(drops),
+            "drop_counts": dict(sorted(drop_counts.items())),
+        },
+        "clustering": {
+            "backend": cfg.clustering_backend,
+            "identity": clusters.identity,
+            "n_clusters": clusters.n_clusters,
+            "n_raw_clusters": clusters.n_raw_clusters,
+            "multichain_entries": len(clusters.multichain_entries),
+            "unclustered_entries": len(clusters.unclustered_entries),
+        },
+        "splits": {
+            "entry_counts": dict(sorted(splits.counts.items())),
+            "cluster_counts": dict(sorted(splits.cluster_counts.items())),
+            "per_split_class_counts": per_split_class_counts,
+            "per_split_ambiguous_counts": per_split_ambiguous_counts,
+            "test_minimum_shortfalls": dict(sorted(splits.minimum_shortfalls.items())),
+        },
+        "ligands": {"n_purification_artifacts": n_artifacts},
+        # Pointers to the data files written alongside this manifest.
+        "files": {
+            "splits": dict(SPLIT_FILES),
+            "test_by_class": dict(sorted(test_class_files.items())),
+            "clusters": CLUSTERS_FILENAME,
+            "ligand_classes": CLASSES_FILENAME,
+            "ligand_tiers": TIERS_FILENAME,
+        },
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Split data files (the actual lists of PDB ids + supporting maps)
+# --------------------------------------------------------------------------- #
+def _write_id_list(ids: list[str], path: Path) -> Path:
+    """Write a JSON array of ids, one per line (compact yet grepable)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = ",\n".join(json.dumps(i) for i in ids)
+    path.write_text(f"[\n{body}\n]\n" if ids else "[]\n", encoding="utf-8")
+    return path
+
+
+def write_split_files(splits, class_map: dict[str, dict], out_dir: str | Path) -> dict[str, Path]:
+    """Write train/val/test id lists + per-class test lists + supporting maps.
+
+    Returns a name->path map of everything written. Pure function of the inputs:
+    ids are sorted, so output is byte-stable.
+    """
+    out = Path(out_dir)
+    per_split: dict[str, list[str]] = {s: [] for s in SPLIT_FILES}
+    for entry, s in splits.entry_split.items():
+        per_split[s].append(entry)
+    for s in per_split:
+        per_split[s].sort()
+
+    written: dict[str, Path] = {}
+    for s, fname in SPLIT_FILES.items():
+        written[s] = _write_id_list(per_split[s], out / fname)
+
+    # Per-class test-id lists: test entries carrying each functional class.
+    test_ids = per_split["test"]
+    class_to_ids: dict[str, list[str]] = {}
+    for eid in test_ids:
+        for cls in class_map.get(eid, {}).get("classes", []):
+            class_to_ids.setdefault(cls, []).append(eid)
+    for cls, ids in class_to_ids.items():
+        written[f"test:{cls}"] = _write_id_list(sorted(ids), out / TEST_SUBDIR / f"{cls}_test.json")
+
+    return written
+
+
+def write_clusters(entry_to_cluster: dict[str, str], out_dir: str | Path) -> Path:
+    """entry_id -> component key, for cluster-balanced sampling."""
+    doc = {
+        "clusters_schema": "if-split/clusters@1",
+        "entry_clusters": dict(sorted(entry_to_cluster.items())),
+    }
+    return _write_json(doc, Path(out_dir) / CLUSTERS_FILENAME, compact=True)
+
+
+def read_clusters(path: str | Path) -> dict[str, str]:
+    path = Path(path)
+    if not path.exists():
+        return {}
+    return dict(json.loads(path.read_text(encoding="utf-8")).get("entry_clusters", {}))
+
+
+def write_classes(class_map: dict[str, dict], out_dir: str | Path) -> Path:
+    """entry_id -> functional class labels."""
+    classes = {eid: info["classes"] for eid, info in sorted(class_map.items())}
+    doc = {"classes_schema": "if-split/classes@1", "classes": classes}
+    return _write_json(doc, Path(out_dir) / CLASSES_FILENAME, compact=True)
+
+
+def read_classes(path: str | Path) -> dict[str, list[str]]:
+    path = Path(path)
+    if not path.exists():
+        return {}
+    return dict(json.loads(path.read_text(encoding="utf-8")).get("classes", {}))
+
+
+def read_id_list(path: str | Path) -> list[str]:
+    """Read a split id-list file (train.json etc.) into a list of ids."""
+    path = Path(path)
+    if not path.exists():
+        return []
+    return list(json.loads(path.read_text(encoding="utf-8")))
+
+
+def write_manifest(manifest: dict[str, Any], out_dir: str | Path) -> Path:
+    # Pretty-print: the manifest is now small (KB) provenance, meant to be read.
+    return _write_json(manifest, Path(out_dir) / "manifest.json")
+
+
+def read_manifest(path: str | Path) -> dict[str, Any]:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Manifest not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+# --------------------------------------------------------------------------- #
+# Ligand-tier audit sidecar (bulky; off the load path)
+# --------------------------------------------------------------------------- #
+def build_tiers_doc(class_map: dict[str, dict]) -> dict[str, Any]:
+    """Per-entry, per-component tier + reason — the curation audit trail.
+
+    Pure function of ``class_map`` (the same input as the manifest), so it stays
+    deterministic and byte-stable. Lives in its own file because it is large and
+    read by nobody on the load path.
+    """
+    tiers = {eid: info.get("tiers", {}) for eid, info in sorted(class_map.items())}
+    return {"tiers_schema": TIERS_SCHEMA, "tiers": tiers}
+
+
+def write_tiers(doc: dict[str, Any], out_dir: str | Path) -> Path:
+    return _write_json(doc, Path(out_dir) / TIERS_FILENAME, compact=True)
+
+
+def read_tiers(path: str | Path) -> dict[str, dict]:
+    """Load the tier map from a sidecar file, or {} if absent."""
+    path = Path(path)
+    if not path.exists():
+        return {}
+    doc = json.loads(path.read_text(encoding="utf-8"))
+    return dict(doc.get("tiers", {}))
+
+
+# --------------------------------------------------------------------------- #
+# verify / stats commands
+# --------------------------------------------------------------------------- #
+def verify_lock(lock_path: str | Path, *, client=None) -> int:
+    """Re-enumerate from a lock's embedded config and report drift.
+
+    Returns a process exit code: 0 = reproduced exactly, 1 = drift detected.
+    ``client`` is injectable for offline testing; production passes None.
+    """
+    from .enumerate import enumerate_candidates
+
+    lock = read_lock(lock_path)
+    if lock.get("lock_schema") != LOCK_SCHEMA:
+        print(f"warning: unexpected lock_schema {lock.get('lock_schema')!r}")
+
+    cfg = Config.model_validate(lock["config"])
+    limit = (lock.get("selection") or {}).get("limit")
+    locked = lock["candidates"]
+    locked_ids = set(locked["entry_ids"])
+    locked_sha = locked["sha256"]
+
+    print(f"verifying {lock['dataset_version']} (config {cfg.config_hash()})")
+    print(f"  locked: {locked['count']} entries, candidates sha256={locked_sha[:12]}...")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        records, _, sha = enumerate_candidates(
+            cfg, tmp, limit=limit, client=client, progress=lambda m: print(f"  {m}")
+        )
+
+    now_ids = {r.entry_id for r in records}
+    added = sorted(now_ids - locked_ids)
+    removed = sorted(locked_ids - now_ids)  # obsoleted / withdrawn
+
+    if sha == locked_sha and not added and not removed:
+        print(f"OK: reproduced exactly ({len(records)} entries, hashes match).")
+        return 0
+
+    print("DRIFT detected:")
+    if sha != locked_sha:
+        print(f"  candidates sha256 differs: now {sha[:12]}... vs locked {locked_sha[:12]}...")
+    if removed:
+        print(f"  {len(removed)} entries no longer present (obsoleted/withdrawn):")
+        print(f"    {', '.join(removed[:20])}{' ...' if len(removed) > 20 else ''}")
+    if added:
+        print(f"  {len(added)} new entries match the snapshot filters:")
+        print(f"    {', '.join(added[:20])}{' ...' if len(added) > 20 else ''}")
+    if not added and not removed:
+        print("  entry set unchanged, but per-entry metadata changed (see hash).")
+    return 1
+
+
+def summarize_manifest(manifest_path: str | Path) -> int:
+    """`stats` command: print split sizes and per-class (functional) test counts."""
+    m = read_manifest(manifest_path)
+    print(f"{m['dataset_version']}  (config {m['config_hash']})")
+    flt = m["filter"]
+    print(
+        f"  candidates: {m['candidates']['count']}  kept: {flt['kept']}  dropped: {flt['dropped']}"
+    )
+    for reason, n in flt["drop_counts"].items():
+        print(f"    - {reason}: {n}")
+    cl = m["clustering"]
+    print(
+        f"  clustering: {cl['backend']} @ {cl['identity']}%  "
+        f"components={cl['n_clusters']} (from {cl.get('n_raw_clusters', '?')} raw)  "
+        f"multichain={cl['multichain_entries']}"
+    )
+    sp = m["splits"]
+    print("  splits (entries / components):")
+    for s in ("train", "val", "test"):
+        ec = sp["entry_counts"].get(s, 0)
+        cc = sp["cluster_counts"].get(s, 0)
+        print(f"    {s:5s}: {ec:>7} entries  {cc:>7} components")
+    print("  test set by ligand class (functional tier):")
+    for cls, n in sp["per_split_class_counts"].get("test", {}).items():
+        print(f"    {cls}: {n}")
+    amb = sp.get("per_split_ambiguous_counts", {}).get("test", {})
+    if amb:
+        print("  test set ambiguous (reported, not labelled):")
+        for cls, n in amb.items():
+            print(f"    {cls}: {n}")
+    shortfalls = sp.get("test_minimum_shortfalls", {})
+    if shortfalls:
+        print("  test minimum shortfalls (floor exceeded available supply):")
+        for cls, n in shortfalls.items():
+            print(f"    {cls}: short by {n}")
+    lig = m["ligands"]
+    n_arts = lig.get("n_purification_artifacts", len(lig.get("purification_artifacts", [])))
+    print(f"  His-tag/Ni purification artifacts flagged: {n_arts}")
+    files = m.get("files", {})
+    if files:
+        sf = files.get("splits", {})
+        tbc = files.get("test_by_class", {})
+        print(f"  split files: {', '.join(sf.values())}")
+        if tbc:
+            print(f"  per-class test files: {', '.join(tbc.values())}")
+    return 0