feat: add Pocket Atlas development gate

AUDIT.md

@@ -115,6 +115,12 @@ GtoPdb release 2026.2 was pinned by embedded release metadata and source hashes.
 
 All 161 target accessions were pinned to reviewed Swiss-Prot sequences from UniProt 2026_02. Joint 50/80 clustering against the complete 2,061-protein Source Atlas and scaffold filtering against all 40,477 Atlas ligands froze a cold-both external holdout with 103 observations, 96 pairs, 78 proteins, 78 scaffolds, and 77 publications. Affinity labels are isolated from the identifier manifest. No predictions have been generated. The holdout is sealed until one frozen candidate passes all internal development gates. See `recovery/GTOPDB_EXTERNAL_HOLDOUT.md` and `recovery/reports/gtopdb-2026.2-external-holdout.json`.
 
+### Pocket Atlas development gate (2026-07-21)
+
+Pocket Atlas mapped 148 homology-safe development proteins to exact or at least 80%-coverage reviewed UniProt sequences and downloaded 145 canonical, versioned AlphaFold monomer structures. Pocketeer extracted 64 confidence, shape, contact-density, and top-pocket descriptors without failure. The checked acquisition workflow reproduced the complete mapping and structure manifest byte-for-byte.
+
+On 1,765 development observations outside every reserved test homology cluster, ligand LightGBM achieved RMSE `1.6682`, the ESM residual achieved `1.6435`, and the best structure-containing residual achieved `1.6643`. Structure therefore worsened RMSE by `0.0208` relative to ESM; the incremental cluster-bootstrap interval was `[-0.0481, 0.0083]`, improvement probability was `0.0905`, and one fold regressed by `0.3835`. The predeclared structure gate rejected further training. No benchmark-test or external-holdout evaluation, GPU run, checkpoint, or weight publication occurred. See `recovery/POCKET_ATLAS_GATE.md` and `recovery/reports/bindingdb-v2-pocket-atlas-development-gate.json`.
+
 ### Mixed-pAffinity forensic track
 
 The deterministic 10,000-pair diagnostic sample is backed by `jglaser/binding_affinity` revision `11e49b7ece33d62afd7f65bc05ce60ad37f9ba7b` and Parquet SHA-256 `d50f4cae794298f32c39f75a9e8603528d20e50e4fa757025def412f5b2a78d8`.

recovery/MODEL_EVALUATION_V2.md

@@ -117,13 +117,21 @@ manifest and no model predictions have been generated. See
 `GTOPDB_EXTERNAL_HOLDOUT.md` and
 `reports/gtopdb-2026.2-external-holdout.json`.
 
-The next development candidate is Pocket Atlas: versioned AlphaFold confidence
-and alpha-sphere pocket geometry fused with the existing ligand control. It has
-usable reviewed-UniProt placement for 1,272 of 1,765 homology-safe development
-observations. It must first demonstrate benefit on repeated homology-grouped
-development folds. Only a frozen candidate passing the RMSE, bootstrap,
-catastrophic-fold, and protein-macro gates may receive the one permitted
-external-holdout evaluation.
+Pocket Atlas tested versioned AlphaFold confidence and deterministic
+alpha-sphere pocket geometry on the 1,765 homology-safe development rows. The
+best structure-containing residual achieved RMSE `1.6643`, barely improving the
+ligand control's `1.6682` and worsening the ESM-only residual's `1.6435` by
+`0.0208`. Its incremental cluster-bootstrap interval was `[-0.0481, 0.0083]`
+and one fold regressed by `0.3835`, so the predeclared gate rejected further
+structure training without touching either holdout. See `POCKET_ATLAS_GATE.md`
+and `reports/bindingdb-v2-pocket-atlas-development-gate.json`.
+
+The next candidate must provide ligand-conditioned interaction information or
+new exact-Kd training observations that survive the reserved homology and
+scaffold manifests. More capacity over global or ligand-independent protein
+features is not justified. Only a frozen candidate passing the RMSE, bootstrap,
+catastrophic-fold, incremental-signal, and protein-macro gates may receive the
+one permitted external-holdout evaluation.
 
 ## Reproduce
 

recovery/POCKET_ATLAS_GATE.md

@@ -0,0 +1,189 @@
+# Pocket Atlas Development Gate
+
+## Decision
+
+**Reject the structure candidate. Do not train or publish weights from this
+hypothesis.**
+
+Pocket Atlas added versioned AlphaFold confidence and alpha-sphere pocket
+geometry to the strongest ligand-only control. The best structure-containing
+residual did not beat the ESM-only residual, its grouped confidence interval
+crossed zero, and one fold regressed catastrophically.
+
+No benchmark-test or sealed GtoPdb external-holdout prediction was generated.
+The experiment cost $0 in cloud compute.
+
+## Development population
+
+The original cold-protein test was already observed by earlier work and remains
+spent. This gate used development data only:
+
+1. Start with the original train and validation observations.
+2. Jointly use the Source Atlas MMseqs2 50% identity / 80% bidirectional
+   coverage clusters.
+3. Reserve all 34 clusters containing any benchmark test protein.
+4. Remove 292 homologous train/validation observations.
+5. Evaluate exactly 1,765 observations, 1,717 pairs, 278 proteins, and 187
+   clusters with five outer grouped folds.
+
+Each fold contained 353 observations. The prediction-sidecar audit found zero
+test pairs and zero reserved test clusters.
+
+## Structure source contract
+
+BindingDB source provenance linked benchmark proteins to UniProt accessions.
+A structure was eligible only when:
+
+- exactly one accession was available;
+- the UniProt entry was reviewed;
+- the benchmark sequence was exact or a contiguous UniProt
+  subsequence/supersequence;
+- contiguous sequence coverage was at least 80%; and
+- AlphaFold returned the canonical DeepMind monomer whose model identity was
+  exactly `AF-{accession}-F1`.
+
+This explicitly rejects AlphaFold isoforms, alternate models, and complex
+predictions returned by the same API endpoint.
+
+Source results:
+
+| Item | Count |
+|---|---:|
+| Homology-safe proteins | 278 |
+| Sequence-eligible proteins | 148 |
+| Eligible accessions | 146 |
+| Canonical AlphaFold models | 145 |
+| Unavailable canonical models | 1 (`P0DTD1`) |
+| Downloaded PDB bytes | 56,834,558 |
+
+All coordinates are versioned AlphaFold URLs and locally hashed. The checked
+source-preparation script reproduced both the protein mapping and complete
+structure manifest byte-for-byte.
+
+## Structure features
+
+`pocketeer==0.3.1` generated 64 fixed protein-only features:
+
+- AlphaFold global confidence and pLDDT distributions;
+- sequence, atom, and C-alpha counts;
+- radius of gyration and principal-axis dimensions;
+- shape eigenvalues and C-alpha contact density;
+- pocket count and aggregate scores/volumes; and
+- top-three pocket score, volume, sphere count, residue count, radius, solvent
+  accessibility, pLDDT, and residue chemistry fractions.
+
+Two mapping-quality indicators captured UniProt coverage and exact-sequence
+placement. Missing structures received zero descriptors plus an unavailable
+indicator.
+
+Extraction results:
+
+| Item | Count |
+|---|---:|
+| Requested structures | 145 |
+| Successful structures | 145 |
+| Failed structures | 0 |
+| Minimum detected pockets | 1 |
+| Maximum detected pockets | 47 |
+| Zero-pocket structures | 0 |
+| Development observations with structure | 1,189 / 1,765 |
+| Development proteins with structure | 147 / 278 |
+
+A repeated P00338 extraction was exactly equal with maximum absolute feature
+difference `0.0`.
+
+## Predeclared gate
+
+A structure candidate had to satisfy all of the following:
+
+1. improve RMSE over ligand LightGBM by at least `0.05`;
+2. have a positive lower bound in a 2,000-replicate protein-cluster bootstrap;
+3. maintain positive protein-macro Pearson correlation;
+4. avoid a fold regression worse than `0.10` RMSE;
+5. improve at least `0.02` RMSE over the ESM-only residual; and
+6. have a positive incremental bootstrap lower bound versus ESM.
+
+The ligand LightGBM was cross-fitted within every outer-training fold before
+residual fitting. Ridge regularization was selected only inside grouped inner
+folds.
+
+## Results
+
+| Model | RMSE | Change vs ligand control | Gate |
+|---|---:|---:|---|
+| Ligand Morgan + descriptors LightGBM | 1.66824 | reference | control |
+| ESM protein residual | 1.64349 | +0.02475 | fail |
+| Structure residual | 1.70274 | -0.03450 | fail |
+| ESM + structure residual | 1.66427 | +0.00397 | **fail** |
+
+For the best structure-containing model:
+
+- incremental change versus ESM: `-0.02078` RMSE;
+- incremental 95% cluster-bootstrap interval: `[-0.04808, 0.00835]`;
+- probability of any incremental improvement: `0.0905`;
+- worst fold change versus ligand control: `-0.38354`; and
+- protein-macro Pearson remained positive but was insufficient to pass.
+
+Structure-only behavior was also negative:
+
+- RMSE change versus control: `-0.03450`;
+- bootstrap interval: `[-0.09739, 0.03359]`; and
+- probability of improvement: `0.1635`.
+
+## Interpretation
+
+Global fold and ligand-independent top-pocket descriptors do not supply useful
+incremental affinity information here. AlphaFold structure availability alone
+is not the missing model ingredient. A future structure hypothesis would need
+a ligand-conditioned mechanism, such as a defensibly selected binding site,
+co-complex geometry, or docking/interaction features. Repeating this experiment
+with a larger neural head is not justified by the grouped CPU evidence.
+
+The independent GtoPdb cold-both holdout remains sealed. It must not be used to
+choose the next model family.
+
+## Reproduce
+
+Prepare the pinned structure snapshot:
+
+```bash
+cd recovery
+PYTHONPATH=src uv run python scripts/prepare_pocket_atlas_sources.py \
+  --sample artifacts/bindingdb-202607-benchmark-v2/sample.jsonl \
+  --manifest artifacts/bindingdb-202607-benchmark-v2/split-cold_protein_exact.jsonl \
+  --source-records artifacts/bindingdb-202607-source-aware-final/source_records.jsonl \
+  --clusters /path/to/source-atlas/mmseqs-identity-50-coverage-80/clusters_cluster.tsv \
+  --uniprot /path/to/pinned-uniprot-2026_02.tsv \
+  --output-dir /path/to/pocket-atlas-sources
+```
+
+Create an isolated pocket-tool environment and extract features:
+
+```bash
+uv venv --python 3.11 /path/to/pocket-tools
+uv pip install --python /path/to/pocket-tools/bin/python pocketeer==0.3.1
+
+PYTHONPATH=src /path/to/pocket-tools/bin/python \
+  scripts/extract_pocket_atlas_features.py \
+  --structure-manifest /path/to/pocket-atlas-sources/structure_manifest.json \
+  --structures-dir /path/to/pocket-atlas-sources/structures \
+  --output-dir /path/to/pocket-atlas-features \
+  --workers 4
+```
+
+Run the development-only gate:
+
+```bash
+PYTHONPATH=src uv run python scripts/run_pocket_atlas_gate.py \
+  --sample artifacts/bindingdb-202607-benchmark-v2/sample.jsonl \
+  --manifest artifacts/bindingdb-202607-benchmark-v2/split-cold_protein_exact.jsonl \
+  --embeddings artifacts/bindingdb-202607-benchmark-v2/frozen-embeddings.npz \
+  --clusters /path/to/source-atlas/mmseqs-identity-50-coverage-80/clusters_cluster.tsv \
+  --protein-mapping /path/to/pocket-atlas-sources/protein_mapping.jsonl \
+  --pocket-features /path/to/pocket-atlas-features/features.json \
+  --output-dir /path/to/pocket-atlas-gate
+```
+
+Aggregate evidence is checked in at
+`reports/bindingdb-v2-pocket-atlas-development-gate.json`. Generated PDB files,
+features, predictions, and labels remain outside Git.

recovery/reports/bindingdb-v2-pocket-atlas-development-gate.json

@@ -0,0 +1,229 @@
+{
+  "schema_version": "mitointeract-pocket-atlas-checked-report/v1",
+  "experiment": "pocket_atlas_development_gate",
+  "status": "development_only_no_test_or_external_evaluation",
+  "decision": "reject_structure_candidate_no_further_training",
+  "target": "pKd",
+  "seed": 42,
+  "benchmark_test_evaluations": 0,
+  "external_holdout_evaluations": 0,
+  "cost_usd": 0.0,
+  "population": {
+    "sample_rows": 2327,
+    "source_development_rows": 2057,
+    "development_rows_excluded_for_test_cluster_homology": 292,
+    "safe_development_rows": 1765,
+    "safe_development_pairs": 1717,
+    "safe_development_proteins": 278,
+    "safe_development_clusters": 187,
+    "benchmark_test_rows_excluded": 270,
+    "benchmark_test_clusters_reserved": 34
+  },
+  "source_mapping": {
+    "uniprot_release": "2026_02",
+    "uniprot_release_date": "10-June-2026",
+    "uniprot_api_deployment_date": "11-July-2026",
+    "uniprot_entries": 229,
+    "uniprot_tsv_sha256": "68c3b65d90446de0df13960242e30d7d60f9a60649374a959ff34405996a2c75",
+    "eligible_proteins": 148,
+    "eligible_accessions": 146,
+    "ineligible": {
+      "ambiguous_accession": 1,
+      "missing_accession": 29,
+      "sequence_placement_or_coverage": 99,
+      "unreviewed_uniprot_entry": 1
+    },
+    "minimum_contiguous_sequence_coverage": 0.8,
+    "protein_mapping_sha256": "db7b8812dd1face08e590c5a51a19cf6863f9de11bad8ae30f509d9b3e7084b1"
+  },
+  "alphafold_snapshot": {
+    "api": "https://alphafold.ebi.ac.uk/api/prediction/",
+    "metadata_accessions": 146,
+    "gdm_monomer_entries": 280,
+    "canonical_selection": "modelEntityId == AF-{accession}-F1; provider GDM; monomer only",
+    "canonical_models": 145,
+    "unavailable_accessions": [
+      "P0DTD1"
+    ],
+    "downloaded_structures": 145,
+    "structure_bytes": 56834558,
+    "structure_manifest_sha256": "9f985679d4d17aae8c7a11bed849c4d4062c7d682b0b40905435785e1916f9c4"
+  },
+  "structure_features": {
+    "tool": "pocketeer",
+    "version": "0.3.1",
+    "feature_count": 64,
+    "mapping_quality_feature_count": 2,
+    "requested_structures": 145,
+    "successful_structures": 145,
+    "failed_structures": 0,
+    "minimum_pockets": 1,
+    "maximum_pockets": 47,
+    "zero_pocket_structures": 0,
+    "feature_sha256": "200d0d8cd15c0d57cb51096d8f56ef60c84d83493ecac12eed7a0064aa6f930e",
+    "determinism_check": {
+      "accession": "P00338",
+      "exact_equal": true,
+      "maximum_absolute_difference": 0.0
+    }
+  },
+  "structure_coverage": {
+    "safe_rows": 1765,
+    "available_rows": 1189,
+    "missing_rows": 576,
+    "safe_proteins": 278,
+    "available_proteins": 147,
+    "missing_proteins": 131
+  },
+  "control": {
+    "name": "ligand_morgan_descriptors_lightgbm",
+    "metrics": {
+      "rmse": 1.6682415337174723,
+      "mae": 1.3337803693102785,
+      "pearson_r": 0.33782116805873186,
+      "spearman_r": 0.29689795196092983,
+      "r2": 0.08151297017567782
+    },
+    "protein_macro_mean_pearson_r": 0.5207683213714444
+  },
+  "variants": {
+    "protein_embedding_ridge_residual": {
+      "metrics": {
+        "rmse": 1.6434931065733804,
+        "mae": 1.326762151114221,
+        "pearson_r": 0.44720924687855346,
+        "spearman_r": 0.4453109776035747,
+        "r2": 0.10856241169224723
+      },
+      "rmse_improvement_vs_control": 0.024748427144091867,
+      "cluster_bootstrap": {
+        "iterations": 2000,
+        "ci_2_5": -0.1226979699222684,
+        "ci_97_5": 0.14593144177553413,
+        "probability_improvement": 0.6405
+      },
+      "fold_rmse_improvements": [
+        0.19749483894689246,
+        0.03203609759448267,
+        -0.3950203091840785,
+        0.26783291384310304,
+        0.013510866159464952
+      ],
+      "protein_macro_mean_pearson_r": 0.5314499173271257,
+      "passed": false
+    },
+    "structure_ridge_residual": {
+      "metrics": {
+        "rmse": 1.7027422554992393,
+        "mae": 1.3740292703037023,
+        "pearson_r": 0.32258584622423186,
+        "spearman_r": 0.2630759939864411,
+        "r2": 0.04312987314367667
+      },
+      "rmse_improvement_vs_control": -0.034500721781766996,
+      "cluster_bootstrap": {
+        "iterations": 2000,
+        "ci_2_5": -0.09738584672656869,
+        "ci_97_5": 0.03358697436359342,
+        "probability_improvement": 0.1635
+      },
+      "fold_rmse_improvements": [
+        -0.052726149391103094,
+        -0.17034724269050883,
+        0.0566650978161638,
+        0.011227189056832731,
+        -0.019131441509435243
+      ],
+      "protein_macro_mean_pearson_r": 0.4867412848102915,
+      "passed": false
+    },
+    "protein_embedding_plus_structure_ridge_residual": {
+      "metrics": {
+        "rmse": 1.6642723336109313,
+        "mae": 1.3471499523001278,
+        "pearson_r": 0.43435936114789336,
+        "spearman_r": 0.42805907694460715,
+        "r2": 0.08587843133505468
+      },
+      "rmse_improvement_vs_control": 0.003969200106541004,
+      "cluster_bootstrap": {
+        "iterations": 2000,
+        "ci_2_5": -0.1343544421249894,
+        "ci_97_5": 0.11774505669976526,
+        "probability_improvement": 0.525
+      },
+      "fold_rmse_improvements": [
+        0.13279607681808803,
+        0.015698267195580762,
+        -0.3835410243143167,
+        0.249759930531807,
+        -0.004686872948701071
+      ],
+      "protein_macro_mean_pearson_r": 0.5255208296082974,
+      "passed": false
+    }
+  },
+  "predeclared_structure_gate": {
+    "best_structure_variant": "protein_embedding_plus_structure_ridge_residual",
+    "minimum_rmse_improvement_vs_control": 0.05,
+    "actual_rmse_improvement_vs_control": 0.003969200106541004,
+    "minimum_incremental_rmse_improvement_vs_esm": 0.02,
+    "actual_incremental_rmse_improvement_vs_esm": -0.020779227037550863,
+    "incremental_cluster_bootstrap": {
+      "iterations": 2000,
+      "seed": 43,
+      "ci_2_5": -0.048075518247379725,
+      "ci_97_5": 0.008345387666166259,
+      "probability_improvement": 0.0905
+    },
+    "bootstrap_lower_bound_positive_vs_control": false,
+    "incremental_bootstrap_lower_bound_positive_vs_esm": false,
+    "no_catastrophic_fold": false,
+    "protein_macro_pearson_positive": true,
+    "passed": false
+  },
+  "verification": {
+    "prediction_rows": 1765,
+    "unique_observation_ids": 1765,
+    "fold_rows": {
+      "0": 353,
+      "1": 353,
+      "2": 353,
+      "3": 353,
+      "4": 353
+    },
+    "test_pairs_in_predictions": 0,
+    "test_clusters_in_predictions": 0,
+    "all_predictions_finite": true,
+    "all_reconstructed_metric_differences": 0.0,
+    "source_reproduction": {
+      "mapping_exact_match": true,
+      "structure_manifest_exact_match": true
+    }
+  },
+  "inputs": {
+    "sample_sha256": "4b022ee8e3f1a4d00499bcaea218bad730f0181fedd7dda7d6a5a3ea370bb7ea",
+    "manifest_sha256": "fb0a4dc63b8074018a1b7f02b863b8fa0cf6117930c3298b7c80133867cb2798",
+    "source_records_sha256": "1e9963217b9ed65528ca477adcba66beea1fa341a1c1c6d41cd789332ab85bbb",
+    "clusters_sha256": "0162c535ba224b64f328555bb18628d945f5aeb98a4bb7b9f1f832394baddbf6",
+    "frozen_embeddings_sha256": "e4c8c3e510b9f28c0b556aa429b79025a07712362e37a2e99a365a8fca844bff"
+  },
+  "artifacts": {
+    "predictions_sha256": "6d8b251deccf2881d9cc8bdf95e6f8a8ec4ecee065c53b56f5ea2b17907bee7f",
+    "predictions_in_git": false,
+    "structures_in_git": false,
+    "checkpoint_created": false,
+    "weights_published": false
+  },
+  "packages": {
+    "lightgbm": "4.7.0",
+    "numpy_gate": "2.5.1",
+    "numpy_pocket_tool": "2.4.6",
+    "pocketeer": "0.3.1",
+    "biotite": "1.6.0",
+    "scipy_pocket_tool": "1.17.1",
+    "rdkit": "2026.3.4",
+    "scikit_learn": "1.9.0"
+  },
+  "publication_decision": "publish_negative_report_only"
+}

recovery/scripts/extract_pocket_atlas_features.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Extract pinned AlphaFold confidence and pocketeer descriptors."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib.metadata
+import json
+import logging
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from mitointeract_recovery.pocket_features import (
+    FEATURE_NAMES,
+    POCKET_TOOL,
+    POCKET_TOOL_VERSION,
+    extract_structure_features,
+)
+
+SCHEMA_VERSION = "mitointeract-pocket-atlas-features/v1"
+
+
+def sha256_file(path: Path) -> str:
+    with path.open("rb") as handle:
+        return hashlib.file_digest(handle, "sha256").hexdigest()
+
+
+def worker(accession: str, path_text: str, metadata: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    logging.getLogger().setLevel(logging.WARNING)
+    vector, diagnostics = extract_structure_features(Path(path_text), metadata)
+    return accession, {
+        "features": vector.astype(float).tolist(),
+        "diagnostics": diagnostics,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--structure-manifest", type=Path, required=True)
+    parser.add_argument("--structures-dir", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--workers", type=int, default=4)
+    args = parser.parse_args()
+    if args.workers <= 0:
+        raise ValueError("workers must be positive")
+    if args.output_dir.exists() and any(args.output_dir.iterdir()):
+        raise FileExistsError(f"output directory is not empty: {args.output_dir}")
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    manifest = json.loads(args.structure_manifest.read_text())
+    if manifest.get("schema_version") != "mitointeract-pocket-atlas-structures/v1":
+        raise ValueError("unexpected structure manifest schema")
+    files = manifest.get("files")
+    if not isinstance(files, dict) or not files:
+        raise ValueError("structure manifest has no files")
+    version = importlib.metadata.version(POCKET_TOOL)
+    if version != POCKET_TOOL_VERSION:
+        raise ValueError(
+            f"unexpected {POCKET_TOOL} version: {version}; expected {POCKET_TOOL_VERSION}"
+        )
+    jobs: list[tuple[str, Path, dict[str, Any]]] = []
+    for accession, metadata in sorted(files.items()):
+        path = args.structures_dir / f"{accession}.pdb"
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        actual = sha256_file(path)
+        if actual != metadata["sha256"]:
+            raise ValueError(f"structure hash mismatch for {accession}")
+        jobs.append((accession, path, metadata))
+
+    results: dict[str, dict[str, Any]] = {}
+    failures: dict[str, str] = {}
+    with ProcessPoolExecutor(max_workers=args.workers) as executor:
+        futures = {
+            executor.submit(worker, accession, str(path), metadata): accession
+            for accession, path, metadata in jobs
+        }
+        for future in as_completed(futures):
+            accession = futures[future]
+            try:
+                returned_accession, result = future.result()
+                if returned_accession != accession:
+                    raise RuntimeError("worker accession mismatch")
+                if len(result["features"]) != len(FEATURE_NAMES):
+                    raise RuntimeError("worker feature width mismatch")
+                results[accession] = result
+            except Exception as exc:
+                failures[accession] = f"{type(exc).__name__}: {exc}"
+
+    features_path = args.output_dir / "features.json"
+    features_path.write_text(
+        json.dumps(
+            {
+                "schema_version": SCHEMA_VERSION,
+                "feature_names": FEATURE_NAMES,
+                "accessions": {key: results[key] for key in sorted(results)},
+            },
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n"
+    )
+    report = {
+        "schema_version": SCHEMA_VERSION,
+        "tool": {"name": POCKET_TOOL, "version": version},
+        "feature_count": len(FEATURE_NAMES),
+        "requested_structures": len(jobs),
+        "successful_structures": len(results),
+        "failed_structures": len(failures),
+        "failures": failures,
+        "pocket_counts": {
+            "minimum": min(result["diagnostics"]["pockets"] for result in results.values()),
+            "maximum": max(result["diagnostics"]["pockets"] for result in results.values()),
+            "zero": sum(result["diagnostics"]["pockets"] == 0 for result in results.values()),
+        }
+        if results
+        else None,
+        "inputs": {
+            "structure_manifest": {
+                "bytes": args.structure_manifest.stat().st_size,
+                "sha256": sha256_file(args.structure_manifest),
+            },
+            "total_structure_bytes": sum(path.stat().st_size for _, path, _ in jobs),
+        },
+        "output": {
+            "bytes": features_path.stat().st_size,
+            "sha256": sha256_file(features_path),
+        },
+    }
+    (args.output_dir / "audit.json").write_text(json.dumps(report, indent=2, sort_keys=True) + "\n")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

recovery/scripts/prepare_pocket_atlas_sources.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Prepare the pinned development-only Pocket Atlas source snapshot."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import json
+import time
+import urllib.error
+import urllib.request
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from mitointeract_recovery.chimera import read_manifest, read_mmseqs_clusters
+from mitointeract_recovery.pocket_sources import (
+    build_protein_mapping,
+    select_canonical_alphafold_model,
+)
+
+EXPECTED_SHA256 = {
+    "sample": "4b022ee8e3f1a4d00499bcaea218bad730f0181fedd7dda7d6a5a3ea370bb7ea",
+    "manifest": "fb0a4dc63b8074018a1b7f02b863b8fa0cf6117930c3298b7c80133867cb2798",
+    "source_records": "1e9963217b9ed65528ca477adcba66beea1fa341a1c1c6d41cd789332ab85bbb",
+    "clusters": "0162c535ba224b64f328555bb18628d945f5aeb98a4bb7b9f1f832394baddbf6",
+    "uniprot": "68c3b65d90446de0df13960242e30d7d60f9a60649374a959ff34405996a2c75",
+}
+UNIPROT_HEADER = (
+    "Entry",
+    "Entry Name",
+    "Reviewed",
+    "Organism",
+    "Organism (ID)",
+    "Protein names",
+    "Sequence",
+    "Sequence version",
+)
+AFDB_API = "https://alphafold.ebi.ac.uk/api/prediction/"
+
+
+def sha256_file(path: Path) -> str:
+    with path.open("rb") as handle:
+        return hashlib.file_digest(handle, "sha256").hexdigest()
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    with path.open() as handle:
+        return [json.loads(line) for line in handle if line.strip()]
+
+
+def read_source_accessions(path: Path) -> dict[str, str]:
+    output: dict[str, str] = {}
+    with path.open() as handle:
+        for line_number, line in enumerate(handle, start=1):
+            envelope = json.loads(line)
+            row = envelope.get("source_record")
+            if not isinstance(row, dict):
+                raise ValueError(f"source record row {line_number} lacks payload")
+            source_id = str(row.get("source_record_id", "")).strip()
+            if not source_id or source_id in output:
+                raise ValueError(f"invalid or duplicate source record row {line_number}")
+            provenance = row.get("provenance")
+            if not isinstance(provenance, dict):
+                raise ValueError(f"source record row {line_number} lacks provenance")
+            output[source_id] = str(provenance.get("swissprot_primary_id") or "").strip()
+    return output
+
+
+def read_uniprot(path: Path) -> dict[str, dict[str, Any]]:
+    output: dict[str, dict[str, Any]] = {}
+    with path.open(newline="") as handle:
+        reader = csv.DictReader(handle, delimiter="\t")
+        if tuple(reader.fieldnames or ()) != UNIPROT_HEADER:
+            raise ValueError("unexpected UniProt TSV schema")
+        for line_number, row in enumerate(reader, start=2):
+            accession = row["Entry"].strip()
+            if not accession or accession in output:
+                raise ValueError(f"invalid or duplicate UniProt row {line_number}")
+            sequence = row["Sequence"].strip()
+            if not sequence:
+                raise ValueError(f"empty UniProt sequence at row {line_number}")
+            output[accession] = {
+                "reviewed": row["Reviewed"].strip(),
+                "sequence": sequence,
+                "sequence_version": int(row["Sequence version"]),
+            }
+    return output
+
+
+def get_metadata(accession: str) -> tuple[str, int, list[dict[str, Any]]]:
+    last_error: Exception | None = None
+    for attempt in range(4):
+        try:
+            with urllib.request.urlopen(AFDB_API + accession, timeout=60) as response:
+                status = int(response.status)
+                data = json.loads(response.read())
+            if not isinstance(data, list):
+                raise ValueError("AlphaFold API response is not a list")
+            selected = [
+                model
+                for model in data
+                if model.get("providerId") == "GDM"
+                and not model.get("isComplex", False)
+                and model.get("entityType") == "protein"
+            ]
+            return accession, status, selected
+        except urllib.error.HTTPError as exc:
+            if exc.code == 429:
+                time.sleep(2**attempt)
+                continue
+            last_error = exc
+            time.sleep(2**attempt)
+        except Exception as exc:
+            last_error = exc
+            time.sleep(2**attempt)
+    raise RuntimeError(f"AlphaFold metadata request failed for {accession}: {last_error}")
+
+
+def download_structure(
+    accession: str, model: dict[str, Any], structures_dir: Path
+) -> tuple[str, dict[str, Any]]:
+    last_error: Exception | None = None
+    url = str(model["pdbUrl"])
+    for attempt in range(4):
+        try:
+            with urllib.request.urlopen(url, timeout=180) as response:
+                content = response.read()
+            if b"ATOM" not in content[:200_000]:
+                raise ValueError("response is not PDB coordinate content")
+            path = structures_dir / f"{accession}.pdb"
+            path.write_bytes(content)
+            return accession, {
+                "model_entity_id": model["modelEntityId"],
+                "latest_version": model["latestVersion"],
+                "model_created_date": model.get("modelCreatedDate"),
+                "sequence_checksum": model.get("sequenceChecksum"),
+                "sequence_start": model.get("sequenceStart"),
+                "sequence_end": model.get("sequenceEnd"),
+                "global_metric_value": model.get("globalMetricValue"),
+                "fraction_plddt_very_high": model.get("fractionPlddtVeryHigh"),
+                "fraction_plddt_confident": model.get("fractionPlddtConfident"),
+                "fraction_plddt_low": model.get("fractionPlddtLow"),
+                "fraction_plddt_very_low": model.get("fractionPlddtVeryLow"),
+                "pdb_url": url,
+                "bytes": len(content),
+                "sha256": hashlib.sha256(content).hexdigest(),
+            }
+        except Exception as exc:
+            last_error = exc
+            time.sleep(2**attempt)
+    raise RuntimeError(f"AlphaFold coordinate download failed for {accession}: {last_error}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--sample", type=Path, required=True)
+    parser.add_argument("--manifest", type=Path, required=True)
+    parser.add_argument("--source-records", type=Path, required=True)
+    parser.add_argument("--clusters", type=Path, required=True)
+    parser.add_argument("--uniprot", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--workers", type=int, default=8)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    paths = {
+        "sample": args.sample,
+        "manifest": args.manifest,
+        "source_records": args.source_records,
+        "clusters": args.clusters,
+        "uniprot": args.uniprot,
+    }
+    for name, path in paths.items():
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        actual = sha256_file(path)
+        if actual != EXPECTED_SHA256[name]:
+            raise ValueError(f"{name} hash mismatch: {actual}")
+    if args.output_dir.exists():
+        raise FileExistsError(args.output_dir)
+    metadata_dir = args.output_dir / "afdb_metadata"
+    structures_dir = args.output_dir / "structures"
+    metadata_dir.mkdir(parents=True)
+    structures_dir.mkdir()
+    sample_rows = read_jsonl(args.sample)
+    mapping_rows, mapping_audit = build_protein_mapping(
+        sample_rows=sample_rows,
+        manifest=read_manifest(args.manifest),
+        source_accessions=read_source_accessions(args.source_records),
+        clusters=read_mmseqs_clusters(args.clusters),
+        uniprot_entries=read_uniprot(args.uniprot),
+    )
+    mapping_path = args.output_dir / "protein_mapping.jsonl"
+    mapping_path.write_text("".join(json.dumps(row, sort_keys=True) + "\n" for row in mapping_rows))
+    eligible_accessions = sorted({str(row["accession"]) for row in mapping_rows if row["eligible"]})
+    metadata: dict[str, list[dict[str, Any]]] = {}
+    statuses: Counter[int] = Counter()
+    with ThreadPoolExecutor(max_workers=args.workers) as executor:
+        futures = {
+            executor.submit(get_metadata, accession): accession for accession in eligible_accessions
+        }
+        for future in as_completed(futures):
+            accession, status, models = future.result()
+            metadata[accession] = models
+            statuses[status] += 1
+            (metadata_dir / f"{accession}.json").write_text(
+                json.dumps(models, indent=2, sort_keys=True) + "\n"
+            )
+    canonical: dict[str, dict[str, Any]] = {}
+    unavailable: list[str] = []
+    for accession in eligible_accessions:
+        model = select_canonical_alphafold_model(accession, metadata[accession])
+        if model is None:
+            unavailable.append(accession)
+        else:
+            canonical[accession] = model
+    files: dict[str, dict[str, Any]] = {}
+    with ThreadPoolExecutor(max_workers=args.workers) as executor:
+        futures = {
+            executor.submit(download_structure, accession, model, structures_dir): accession
+            for accession, model in canonical.items()
+        }
+        for future in as_completed(futures):
+            accession, file_metadata = future.result()
+            files[accession] = file_metadata
+    structure_manifest = {
+        "schema_version": "mitointeract-pocket-atlas-structures/v1",
+        "canonical_selection": ("modelEntityId == AF-{accession}-F1; provider GDM; monomer only"),
+        "eligible_accessions": len(eligible_accessions),
+        "available_canonical_models": len(canonical),
+        "unavailable_accessions": unavailable,
+        "files": {key: files[key] for key in sorted(files)},
+        "total_bytes": sum(item["bytes"] for item in files.values()),
+    }
+    structure_path = args.output_dir / "structure_manifest.json"
+    structure_path.write_text(json.dumps(structure_manifest, indent=2, sort_keys=True) + "\n")
+    report = {
+        "schema_version": "mitointeract-pocket-atlas-sources/v1",
+        "inputs": {name: sha256_file(path) for name, path in paths.items()},
+        "mapping": {
+            **mapping_audit,
+            "sha256": sha256_file(mapping_path),
+        },
+        "alphafold_api": {
+            "base_url": AFDB_API,
+            "status_counts": {str(key): value for key, value in statuses.items()},
+            "metadata_accessions": len(metadata),
+            "gdm_monomer_entries": sum(len(models) for models in metadata.values()),
+            "canonical_models": len(canonical),
+            "unavailable_accessions": unavailable,
+        },
+        "structures": {
+            "files": len(files),
+            "total_bytes": structure_manifest["total_bytes"],
+            "manifest_sha256": sha256_file(structure_path),
+        },
+    }
+    report_path = args.output_dir / "audit.json"
+    report_path.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n")
+    print(json.dumps(report, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

recovery/scripts/run_pocket_atlas_gate.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Run the development-only Pocket Atlas residual gate."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from mitointeract_recovery.chimera import (
+    LightGBMConfig,
+    ResidualVariant,
+    cluster_bootstrap_rmse_improvement,
+    evaluate_chimera,
+    ligand_feature_matrix,
+    read_manifest,
+    read_mmseqs_clusters,
+    sha256_file,
+    validate_and_align,
+)
+from mitointeract_recovery.pocket_features import FEATURE_NAMES
+from mitointeract_recovery.pocket_gate import (
+    MINIMUM_INCREMENTAL_RMSE_IMPROVEMENT,
+    align_structure_features,
+    read_mapping,
+)
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    with path.open() as handle:
+        return [json.loads(line) for line in handle if line.strip()]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--sample", type=Path, required=True)
+    parser.add_argument("--manifest", type=Path, required=True)
+    parser.add_argument("--embeddings", type=Path, required=True)
+    parser.add_argument("--clusters", type=Path, required=True)
+    parser.add_argument("--protein-mapping", type=Path, required=True)
+    parser.add_argument("--pocket-features", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--target-key", default="pkd")
+    parser.add_argument("--outer-splits", type=int, default=5)
+    parser.add_argument("--control-crossfit-splits", type=int, default=4)
+    parser.add_argument("--residual-selection-splits", type=int, default=3)
+    parser.add_argument("--bootstrap-iterations", type=int, default=2000)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--minimum-rmse-improvement", type=float, default=0.05)
+    parser.add_argument("--catastrophic-fold-tolerance", type=float, default=0.10)
+    parser.add_argument(
+        "--minimum-incremental-rmse-improvement",
+        type=float,
+        default=MINIMUM_INCREMENTAL_RMSE_IMPROVEMENT,
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    inputs = (
+        args.sample,
+        args.manifest,
+        args.embeddings,
+        args.clusters,
+        args.protein_mapping,
+        args.pocket_features,
+    )
+    for path in inputs:
+        if not path.is_file():
+            raise FileNotFoundError(path)
+    if args.output_dir.exists():
+        raise FileExistsError(args.output_dir)
+    args.output_dir.mkdir(parents=True)
+    started = time.monotonic()
+    rows = read_jsonl(args.sample)
+    manifest = read_manifest(args.manifest)
+    clusters = read_mmseqs_clusters(args.clusters)
+    with np.load(args.embeddings) as embedding_arrays:
+        aligned = validate_and_align(
+            rows,
+            embedding_arrays,
+            manifest,
+            clusters,
+            target_key=args.target_key,
+        )
+    test_clusters = set(aligned["cluster_ids"][aligned["test_indices"]].tolist())
+    safe_indices = np.asarray(
+        [
+            index
+            for index in aligned["development_indices"]
+            if aligned["cluster_ids"][index] not in test_clusters
+        ],
+        dtype=np.int64,
+    )
+    excluded_homologous_development = len(aligned["development_indices"]) - len(safe_indices)
+    if set(aligned["cluster_ids"][safe_indices]).intersection(test_clusters):
+        raise RuntimeError("test-homologous protein cluster survived the safety filter")
+    mapping = read_mapping(args.protein_mapping)
+    feature_document = json.loads(args.pocket_features.read_text())
+    structure_features, structure_coverage = align_structure_features(
+        protein_ids=aligned["protein_ids"],
+        safe_indices=safe_indices,
+        mapping=mapping,
+        feature_document=feature_document,
+    )
+    ligand_control = ligand_feature_matrix(rows)
+    variants = [
+        ResidualVariant("protein_embedding_ridge_residual", aligned["protein"]),
+        ResidualVariant("structure_ridge_residual", structure_features),
+        ResidualVariant(
+            "protein_embedding_plus_structure_ridge_residual",
+            np.concatenate([aligned["protein"], structure_features], axis=1),
+        ),
+    ]
+    result = evaluate_chimera(
+        targets=aligned["targets"],
+        ligand_control_features=ligand_control,
+        variants=variants,
+        development_indices=safe_indices,
+        cluster_ids=aligned["cluster_ids"],
+        protein_ids=aligned["protein_ids"],
+        outer_splits=args.outer_splits,
+        control_crossfit_splits=args.control_crossfit_splits,
+        residual_selection_splits=args.residual_selection_splits,
+        bootstrap_iterations=args.bootstrap_iterations,
+        seed=args.seed,
+        minimum_rmse_improvement=args.minimum_rmse_improvement,
+        catastrophic_fold_tolerance=args.catastrophic_fold_tolerance,
+        lightgbm_config=LightGBMConfig(),
+    )
+    variant_reports = result["variants"]
+    esm_name = "protein_embedding_ridge_residual"
+    structure_names = (
+        "structure_ridge_residual",
+        "protein_embedding_plus_structure_ridge_residual",
+    )
+    best_structure = min(structure_names, key=lambda name: variant_reports[name]["metrics"]["rmse"])
+    safe_targets = aligned["targets"][safe_indices]
+    safe_clusters = aligned["cluster_ids"][safe_indices]
+    esm_predictions = result["variant_predictions"][esm_name][safe_indices]
+    structure_predictions = result["variant_predictions"][best_structure][safe_indices]
+    incremental_bootstrap = cluster_bootstrap_rmse_improvement(
+        safe_targets,
+        esm_predictions,
+        structure_predictions,
+        safe_clusters,
+        iterations=args.bootstrap_iterations,
+        seed=args.seed + 1,
+    )
+    incremental_improvement = (
+        variant_reports[esm_name]["metrics"]["rmse"]
+        - variant_reports[best_structure]["metrics"]["rmse"]
+    )
+    structure_gate = {
+        "best_structure_variant": best_structure,
+        "minimum_incremental_rmse_improvement_over_esm": args.minimum_incremental_rmse_improvement,
+        "actual_incremental_rmse_improvement_over_esm": incremental_improvement,
+        "meets_incremental_improvement": incremental_improvement
+        >= args.minimum_incremental_rmse_improvement,
+        "incremental_bootstrap": incremental_bootstrap,
+        "incremental_bootstrap_lower_bound_positive": incremental_bootstrap["ci_2_5"] > 0,
+        "base_gate_passed": variant_reports[best_structure]["gate"]["passed"],
+    }
+    structure_gate["passed"] = all(
+        (
+            structure_gate["base_gate_passed"],
+            structure_gate["meets_incremental_improvement"],
+            structure_gate["incremental_bootstrap_lower_bound_positive"],
+        )
+    )
+
+    prediction_path = args.output_dir / "predictions.jsonl"
+    with prediction_path.open("w") as handle:
+        for index in safe_indices:
+            handle.write(
+                json.dumps(
+                    {
+                        "observation_id": str(aligned["observation_ids"][index]),
+                        "pair_id": str(aligned["pair_ids"][index]),
+                        "protein_id": str(aligned["protein_ids"][index]),
+                        "protein_cluster_id": str(aligned["cluster_ids"][index]),
+                        "original_split": str(aligned["row_splits"][index]),
+                        "development_fold": int(result["fold_assignments"][index]),
+                        "structure_available": bool(structure_features[index, 0]),
+                        "target_pkd": float(aligned["targets"][index]),
+                        "ligand_control_prediction": float(result["control_predictions"][index]),
+                        "variant_predictions": {
+                            name: float(predictions[index])
+                            for name, predictions in result["variant_predictions"].items()
+                        },
+                    },
+                    sort_keys=True,
+                )
+                + "\n"
+            )
+    report = {
+        "schema_version": "mitointeract-pocket-atlas-gate/v1",
+        "experiment": "pocket_atlas_development_gate",
+        "status": "development_only_no_test_or_external_evaluation",
+        "decision": (
+            "advance_structure_candidate"
+            if structure_gate["passed"]
+            else "reject_structure_candidate"
+        ),
+        "target": "pKd",
+        "seed": args.seed,
+        "benchmark_test_evaluations": 0,
+        "external_holdout_evaluations": 0,
+        "population": {
+            "sample_rows": len(rows),
+            "source_development_rows": len(aligned["development_indices"]),
+            "development_rows_excluded_for_test_cluster_homology": excluded_homologous_development,
+            "safe_development_rows": len(safe_indices),
+            "safe_development_pairs": len(set(aligned["pair_ids"][safe_indices].tolist())),
+            "safe_development_proteins": len(set(aligned["protein_ids"][safe_indices].tolist())),
+            "safe_development_clusters": result["development_clusters"],
+            "benchmark_test_rows_excluded": len(aligned["test_indices"]),
+            "benchmark_test_clusters_reserved": len(test_clusters),
+        },
+        "structure_coverage": structure_coverage,
+        "inputs": {path.stem + "_sha256": sha256_file(path) for path in inputs},
+        "features": {
+            "pocket_feature_count": len(FEATURE_NAMES),
+            "mapping_quality_feature_count": 2,
+            "total_structure_feature_count": structure_features.shape[1],
+            "pocket_feature_names": FEATURE_NAMES,
+            "mapping_quality_features": ["uniprot_sequence_coverage", "exact_sequence_mapping"],
+        },
+        "control": {
+            "name": "ligand_morgan_descriptors_lightgbm",
+            **result["control"],
+        },
+        "variants": variant_reports,
+        "structure_gate": structure_gate,
+        "folds": result["folds"],
+        "protocol": {
+            "outer_splits": args.outer_splits,
+            "outer_group": "Source Atlas joint MMseqs2 50/80 protein cluster",
+            "control_crossfit_splits": args.control_crossfit_splits,
+            "residual_selection_splits": args.residual_selection_splits,
+            "bootstrap_iterations": args.bootstrap_iterations,
+            "bootstrap_unit": "Source Atlas MMseqs2 protein cluster",
+            "minimum_control_rmse_improvement": args.minimum_rmse_improvement,
+            "minimum_incremental_rmse_improvement_over_esm": (
+                args.minimum_incremental_rmse_improvement
+            ),
+            "catastrophic_fold_tolerance": args.catastrophic_fold_tolerance,
+            "benchmark_test_policy": (
+                "masked and excluded with every homologous development cluster"
+            ),
+            "external_holdout_policy": "not loaded, not predicted, and not evaluated",
+        },
+        "packages": {
+            package: importlib.metadata.version(package)
+            for package in ("lightgbm", "numpy", "rdkit", "scikit-learn")
+        },
+        "artifacts": {
+            "predictions": prediction_path.name,
+            "predictions_sha256": sha256_file(prediction_path),
+        },
+        "elapsed_seconds": time.monotonic() - started,
+    }
+    report_path = args.output_dir / "report.json"
+    report_path.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n")
+    print(
+        json.dumps(
+            {
+                "decision": report["decision"],
+                "control_rmse": report["control"]["metrics"]["rmse"],
+                "esm_rmse": report["variants"][esm_name]["metrics"]["rmse"],
+                "best_structure_variant": best_structure,
+                "best_structure_rmse": report["variants"][best_structure]["metrics"]["rmse"],
+                "structure_gate": structure_gate,
+                "benchmark_test_evaluations": 0,
+                "external_holdout_evaluations": 0,
+                "report": str(report_path),
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

recovery/src/mitointeract_recovery/pocket_features.py

@@ -0,0 +1,216 @@
+"""Deterministic AlphaFold confidence and alpha-sphere pocket descriptors."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from scipy.spatial.distance import pdist  # type: ignore[import-not-found]
+
+POCKET_TOOL = "pocketeer"
+POCKET_TOOL_VERSION = "0.3.1"
+TOP_POCKETS = 3
+HYDROPHOBIC = frozenset({"ALA", "VAL", "ILE", "LEU", "MET", "PHE", "TRP", "PRO"})
+AROMATIC = frozenset({"PHE", "TYR", "TRP", "HIS"})
+CHARGED = frozenset({"ASP", "GLU", "LYS", "ARG", "HIS"})
+POLAR = frozenset({"SER", "THR", "ASN", "GLN", "CYS", "TYR", "HIS"})
+
+GLOBAL_FEATURES = (
+    "structure_available",
+    "af_global_metric_100",
+    "af_fraction_very_high",
+    "af_fraction_confident",
+    "af_fraction_low",
+    "af_fraction_very_low",
+    "log_sequence_length",
+    "log_atom_count",
+    "log_ca_count",
+    "radius_gyration_100",
+    "bbox_small_100",
+    "bbox_middle_100",
+    "bbox_large_100",
+    "log_bbox_volume",
+    "shape_eigenvalue_1",
+    "shape_eigenvalue_2",
+    "shape_eigenvalue_3",
+    "ca_contact_density_8",
+    "ca_contact_density_12",
+    "plddt_mean_100",
+    "plddt_std_100",
+    "plddt_q10_100",
+    "plddt_q50_100",
+    "plddt_q90_100",
+    "plddt_fraction_ge70",
+    "plddt_fraction_ge90",
+    "log_pocket_count",
+    "pocket_score_max",
+    "pocket_score_mean",
+    "log_pocket_volume_sum",
+    "log_pocket_residue_sum",
+)
+POCKET_FEATURE_SUFFIXES = (
+    "score",
+    "log_volume",
+    "log_spheres",
+    "log_residues",
+    "mean_radius_10",
+    "mean_sasa_100",
+    "plddt_mean_100",
+    "hydrophobic_fraction",
+    "aromatic_fraction",
+    "charged_fraction",
+    "polar_fraction",
+)
+FEATURE_NAMES = GLOBAL_FEATURES + tuple(
+    f"pocket_{rank}_{suffix}"
+    for rank in range(1, TOP_POCKETS + 1)
+    for suffix in POCKET_FEATURE_SUFFIXES
+)
+
+
+def parse_pdb_plddt(path: Path) -> np.ndarray:
+    """Read AlphaFold per-atom pLDDT from PDB B-factor columns."""
+    values: list[float] = []
+    with path.open() as handle:
+        for line_number, line in enumerate(handle, start=1):
+            if not line.startswith(("ATOM  ", "HETATM")):
+                continue
+            if len(line) < 66:
+                raise ValueError(f"PDB line {line_number}: missing B-factor columns")
+            try:
+                value = float(line[60:66])
+            except ValueError as exc:
+                raise ValueError(f"PDB line {line_number}: invalid B-factor") from exc
+            if not math.isfinite(value) or not 0 <= value <= 100:
+                raise ValueError(f"PDB line {line_number}: invalid AlphaFold pLDDT")
+            values.append(value)
+    if not values:
+        raise ValueError("PDB contains no coordinate records")
+    return np.asarray(values, dtype=np.float64)
+
+
+def _fraction(residues: list[tuple[str, int, str]], group: frozenset[str]) -> float:
+    if not residues:
+        return 0.0
+    return sum(residue_name in group for _, _, residue_name in residues) / len(residues)
+
+
+def _pocket_features(pocket: Any, plddt: np.ndarray) -> list[float]:
+    radii = np.asarray([sphere.radius for sphere in pocket.spheres], dtype=np.float64)
+    sasa = np.asarray([sphere.mean_sasa for sphere in pocket.spheres], dtype=np.float64)
+    pocket_confidence = plddt[np.asarray(pocket.mask, dtype=bool)]
+    residues = list(pocket.residues)
+    return [
+        float(pocket.score),
+        math.log1p(max(0.0, float(pocket.volume))),
+        math.log1p(int(pocket.n_spheres)),
+        math.log1p(len(residues)),
+        float(np.mean(radii)) / 10.0,
+        float(np.mean(sasa)) / 100.0,
+        float(np.mean(pocket_confidence)) / 100.0,
+        _fraction(residues, HYDROPHOBIC),
+        _fraction(residues, AROMATIC),
+        _fraction(residues, CHARGED),
+        _fraction(residues, POLAR),
+    ]
+
+
+def structure_feature_vector(
+    atomarray: Any,
+    pockets: list[Any],
+    plddt: np.ndarray,
+    metadata: dict[str, Any],
+) -> np.ndarray:
+    """Build fixed-width, rotation-invariant global and top-pocket features."""
+    coordinates = np.asarray(atomarray.coord, dtype=np.float64)
+    if coordinates.ndim != 2 or coordinates.shape[1] != 3:
+        raise ValueError("atom coordinates must have shape [N, 3]")
+    if plddt.shape != (len(atomarray),):
+        raise ValueError(f"pLDDT/atom count mismatch: {len(plddt)} vs {len(atomarray)}")
+    ca_mask = np.asarray(atomarray.atom_name == "CA", dtype=bool)
+    ca = coordinates[ca_mask]
+    if len(ca) < 2:
+        raise ValueError("structure has fewer than two CA atoms")
+    centered = ca - np.mean(ca, axis=0)
+    radius_gyration = float(np.sqrt(np.mean(np.sum(centered**2, axis=1))))
+    covariance = np.cov(centered, rowvar=False)
+    raw_eigenvalues, eigenvectors = np.linalg.eigh(covariance)
+    eigenvalues = np.maximum(raw_eigenvalues, 0.0)[::-1]
+    principal_coordinates = centered @ eigenvectors[:, ::-1]
+    bounds = np.sort(np.ptp(principal_coordinates, axis=0))
+    eigenvalue_total = float(np.sum(eigenvalues))
+    normalized_eigenvalues = eigenvalues / eigenvalue_total if eigenvalue_total > 0 else np.zeros(3)
+    distances = pdist(ca)
+    contact_8 = float(np.mean(distances <= 8.0))
+    contact_12 = float(np.mean(distances <= 12.0))
+    sorted_pockets = sorted(pockets, key=lambda pocket: pocket.score, reverse=True)
+    scores = np.asarray([pocket.score for pocket in sorted_pockets], dtype=np.float64)
+    volumes = np.asarray([pocket.volume for pocket in sorted_pockets], dtype=np.float64)
+    residue_counts = np.asarray(
+        [len(pocket.residues) for pocket in sorted_pockets], dtype=np.float64
+    )
+    plddt_quantiles = np.quantile(plddt, [0.1, 0.5, 0.9])
+    global_values = [
+        1.0,
+        float(metadata["global_metric_value"]) / 100.0,
+        float(metadata["fraction_plddt_very_high"]),
+        float(metadata["fraction_plddt_confident"]),
+        float(metadata["fraction_plddt_low"]),
+        float(metadata["fraction_plddt_very_low"]),
+        math.log1p(int(metadata["sequence_end"]) - int(metadata["sequence_start"]) + 1),
+        math.log1p(len(atomarray)),
+        math.log1p(len(ca)),
+        radius_gyration / 100.0,
+        *(bounds / 100.0).tolist(),
+        math.log1p(float(np.prod(bounds))),
+        *normalized_eigenvalues.tolist(),
+        contact_8,
+        contact_12,
+        float(np.mean(plddt)) / 100.0,
+        float(np.std(plddt)) / 100.0,
+        *(plddt_quantiles / 100.0).tolist(),
+        float(np.mean(plddt >= 70.0)),
+        float(np.mean(plddt >= 90.0)),
+        math.log1p(len(sorted_pockets)),
+        float(np.max(scores)) if len(scores) else 0.0,
+        float(np.mean(scores)) if len(scores) else 0.0,
+        math.log1p(float(np.sum(volumes))) if len(volumes) else 0.0,
+        math.log1p(float(np.sum(residue_counts))) if len(residue_counts) else 0.0,
+    ]
+    values = global_values
+    for rank in range(TOP_POCKETS):
+        if rank < len(sorted_pockets):
+            values.extend(_pocket_features(sorted_pockets[rank], plddt))
+        else:
+            values.extend([0.0] * len(POCKET_FEATURE_SUFFIXES))
+    vector = np.asarray(values, dtype=np.float32)
+    if vector.shape != (len(FEATURE_NAMES),):
+        raise RuntimeError(f"feature width mismatch: {vector.shape} vs {len(FEATURE_NAMES)}")
+    if not np.isfinite(vector).all():
+        raise ValueError("structure feature vector contains nonfinite values")
+    return vector
+
+
+def extract_structure_features(
+    pdb_path: Path, metadata: dict[str, Any]
+) -> tuple[np.ndarray, dict[str, int]]:
+    """Load one structure and run the pinned optional pocket detector."""
+    import importlib.metadata
+
+    import pocketeer  # type: ignore[import-not-found]
+
+    version = importlib.metadata.version(POCKET_TOOL)
+    if version != POCKET_TOOL_VERSION:
+        raise ValueError(
+            f"unexpected {POCKET_TOOL} version: {version}; expected {POCKET_TOOL_VERSION}"
+        )
+    atomarray = pocketeer.load_structure(str(pdb_path))
+    plddt = parse_pdb_plddt(pdb_path)
+    pockets = pocketeer.find_pockets(atomarray)
+    return structure_feature_vector(atomarray, pockets, plddt, metadata), {
+        "atoms": len(atomarray),
+        "ca_atoms": int(np.sum(atomarray.atom_name == "CA")),
+        "pockets": len(pockets),
+    }

recovery/src/mitointeract_recovery/pocket_gate.py

@@ -0,0 +1,82 @@
+"""Validation and alignment helpers for the Pocket Atlas development gate."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from mitointeract_recovery.pocket_features import FEATURE_NAMES
+
+FEATURE_SCHEMA = "mitointeract-pocket-atlas-features/v1"
+MINIMUM_INCREMENTAL_RMSE_IMPROVEMENT = 0.02
+
+
+def read_mapping(path: Path) -> dict[str, dict[str, Any]]:
+    mapping: dict[str, dict[str, Any]] = {}
+    with path.open() as handle:
+        for row_number, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            row = json.loads(line)
+            protein_id = str(row.get("protein_id", "")).strip()
+            if not protein_id or protein_id in mapping:
+                raise ValueError(f"invalid or duplicate protein mapping row {row_number}")
+            mapping[protein_id] = row
+    if not mapping:
+        raise ValueError("protein mapping is empty")
+    return mapping
+
+
+def align_structure_features(
+    *,
+    protein_ids: np.ndarray,
+    safe_indices: np.ndarray,
+    mapping: dict[str, dict[str, Any]],
+    feature_document: dict[str, Any],
+) -> tuple[np.ndarray, dict[str, int]]:
+    """Align accession-level descriptors to observations with fail-closed coverage."""
+    if feature_document.get("schema_version") != FEATURE_SCHEMA:
+        raise ValueError("unexpected Pocket Atlas feature schema")
+    if tuple(feature_document.get("feature_names", ())) != FEATURE_NAMES:
+        raise ValueError("Pocket Atlas feature names differ from the code contract")
+    accessions = feature_document.get("accessions")
+    if not isinstance(accessions, dict):
+        raise ValueError("Pocket Atlas feature document has no accession map")
+    safe_proteins = set(protein_ids[safe_indices].tolist())
+    if set(mapping) != safe_proteins:
+        raise ValueError("protein mapping must exactly cover homology-safe proteins")
+    matrix = np.zeros((len(protein_ids), len(FEATURE_NAMES) + 2), dtype=np.float32)
+    available_proteins: set[str] = set()
+    for protein_id in safe_proteins:
+        row = mapping[protein_id]
+        accession = str(row.get("accession", ""))
+        if bool(row.get("eligible")) and accession in accessions:
+            vector = np.asarray(accessions[accession].get("features"), dtype=np.float32)
+            if vector.shape != (len(FEATURE_NAMES),) or not np.isfinite(vector).all():
+                raise ValueError(f"invalid Pocket Atlas vector for {accession}")
+            if vector[0] != 1.0:
+                raise ValueError(
+                    f"available Pocket Atlas vector lacks availability flag: {accession}"
+                )
+            coverage = float(row.get("coverage", float("nan")))
+            if not np.isfinite(coverage) or not 0.8 <= coverage <= 1.0:
+                raise ValueError(f"invalid eligible mapping coverage for {protein_id}")
+            protein_rows = np.flatnonzero(protein_ids == protein_id)
+            matrix[protein_rows, : len(FEATURE_NAMES)] = vector
+            matrix[protein_rows, -2] = coverage
+            matrix[protein_rows, -1] = float(row.get("placement") == "exact")
+            available_proteins.add(protein_id)
+    if not np.isfinite(matrix).all():
+        raise ValueError("aligned Pocket Atlas matrix contains nonfinite values")
+    safe_available = matrix[safe_indices, 0] == 1.0
+    return matrix, {
+        "safe_rows": len(safe_indices),
+        "available_rows": int(np.sum(safe_available)),
+        "missing_rows": int(np.sum(~safe_available)),
+        "safe_proteins": len(safe_proteins),
+        "available_proteins": len(available_proteins),
+        "missing_proteins": len(safe_proteins.difference(available_proteins)),
+    }

recovery/src/mitointeract_recovery/pocket_sources.py

@@ -0,0 +1,170 @@
+"""Build the development-only benchmark-to-UniProt structure mapping."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+
+def place_sequence(query: str, reference: str) -> dict[str, Any]:
+    """Place a benchmark sequence in a UniProt sequence without alignment guessing."""
+    if not query or not reference:
+        return {
+            "placement": "unmapped",
+            "coverage": 0.0,
+            "sequence_start": None,
+            "sequence_end": None,
+        }
+    if query == reference:
+        return {
+            "placement": "exact",
+            "coverage": 1.0,
+            "sequence_start": 1,
+            "sequence_end": len(reference),
+        }
+    if query in reference:
+        start = reference.index(query) + 1
+        return {
+            "placement": "subsequence",
+            "coverage": len(query) / len(reference),
+            "sequence_start": start,
+            "sequence_end": start + len(query) - 1,
+        }
+    if reference in query:
+        return {
+            "placement": "supersequence",
+            "coverage": len(reference) / len(query),
+            "sequence_start": 1,
+            "sequence_end": len(reference),
+        }
+    return {
+        "placement": "noncontiguous",
+        "coverage": 0.0,
+        "sequence_start": None,
+        "sequence_end": None,
+    }
+
+
+def select_canonical_alphafold_model(
+    accession: str, models: list[dict[str, Any]]
+) -> dict[str, Any] | None:
+    """Select only the canonical DeepMind monomer, never an isoform or complex."""
+    expected_id = f"AF-{accession}-F1"
+    matches = [
+        model
+        for model in models
+        if model.get("modelEntityId") == expected_id
+        and model.get("providerId") == "GDM"
+        and model.get("entityType") == "protein"
+        and not model.get("isComplex", False)
+    ]
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise ValueError(f"multiple canonical AlphaFold models for {accession}")
+    model = matches[0]
+    if not model.get("pdbUrl") or not model.get("latestVersion"):
+        raise ValueError(f"canonical AlphaFold model lacks versioned coordinates: {accession}")
+    return model
+
+
+def build_protein_mapping(
+    *,
+    sample_rows: list[dict[str, Any]],
+    manifest: dict[str, str],
+    source_accessions: dict[str, str],
+    clusters: dict[str, str],
+    uniprot_entries: dict[str, dict[str, Any]],
+    minimum_coverage: float = 0.8,
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+    """Map homology-safe development proteins to reviewed UniProt sequences."""
+    if not 0 < minimum_coverage <= 1:
+        raise ValueError("minimum coverage must be in (0, 1]")
+    pair_ids = {str(row.get("pair_id", "")) for row in sample_rows}
+    if set(manifest) != pair_ids:
+        raise ValueError("manifest pair set must exactly match the sample")
+    missing_clusters = {str(row.get("protein_id", "")) for row in sample_rows}.difference(clusters)
+    if missing_clusters:
+        raise ValueError(
+            f"sample proteins missing cluster assignments: {sorted(missing_clusters)[:3]}"
+        )
+    test_clusters = {
+        clusters[str(row["protein_id"])]
+        for row in sample_rows
+        if manifest[str(row["pair_id"])] == "test"
+    }
+    safe_rows = [
+        row
+        for row in sample_rows
+        if manifest[str(row["pair_id"])] in {"train", "validation"}
+        and clusters[str(row["protein_id"])] not in test_clusters
+    ]
+    if not safe_rows:
+        raise ValueError("homology-safe development population is empty")
+    accessions_by_protein: dict[str, set[str]] = defaultdict(set)
+    sequence_by_protein: dict[str, str] = {}
+    for row in safe_rows:
+        protein_id = str(row["protein_id"])
+        sequence = str(row["sequence"])
+        previous = sequence_by_protein.setdefault(protein_id, sequence)
+        if previous != sequence:
+            raise ValueError(f"inconsistent sequence for protein {protein_id}")
+        for source_record_id in row.get("source_record_ids", ()):
+            accession = source_accessions.get(str(source_record_id), "").strip()
+            if accession:
+                accessions_by_protein[protein_id].add(accession)
+    output: list[dict[str, Any]] = []
+    reason_counts: dict[str, int] = defaultdict(int)
+    for protein_id in sorted(sequence_by_protein):
+        accessions = sorted(accessions_by_protein[protein_id])
+        record: dict[str, Any] = {
+            "protein_id": protein_id,
+            "sequence": sequence_by_protein[protein_id],
+            "cluster": clusters[protein_id],
+            "accessions": accessions,
+            "eligible": False,
+        }
+        if len(accessions) != 1:
+            reason = "missing_accession" if not accessions else "ambiguous_accession"
+            reason_counts[reason] += 1
+            output.append(record)
+            continue
+        accession = accessions[0]
+        entry = uniprot_entries.get(accession)
+        if entry is None:
+            reason_counts["missing_uniprot_entry"] += 1
+            output.append(record)
+            continue
+        if str(entry.get("reviewed")) != "reviewed":
+            reason_counts["unreviewed_uniprot_entry"] += 1
+            output.append(record)
+            continue
+        reference = str(entry["sequence"])
+        placement = place_sequence(record["sequence"], reference)
+        record.update(
+            {
+                "accession": accession,
+                "uniprot_sequence": reference,
+                "placement": placement["placement"],
+                "coverage": placement["coverage"],
+                "sequence_start": placement["sequence_start"],
+                "sequence_end": placement["sequence_end"],
+                "uniprot_sequence_version": int(entry["sequence_version"]),
+            }
+        )
+        record["eligible"] = (
+            placement["placement"] in {"exact", "subsequence", "supersequence"}
+            and placement["coverage"] >= minimum_coverage
+        )
+        if not record["eligible"]:
+            reason_counts["sequence_placement_or_coverage"] += 1
+        output.append(record)
+    audit = {
+        "safe_rows": len(safe_rows),
+        "safe_proteins": len(output),
+        "test_clusters_reserved": len(test_clusters),
+        "eligible_proteins": sum(bool(row["eligible"]) for row in output),
+        "eligible_accessions": len({str(row["accession"]) for row in output if row["eligible"]}),
+        **{f"ineligible_{key}": value for key, value in sorted(reason_counts.items())},
+    }
+    return output, audit

recovery/tests/test_checked_reports.py

@@ -211,6 +211,49 @@ def test_gtopdb_external_holdout_is_independent_cold_both_and_sealed():
     assert report["evaluation_policy"]["status"] == "sealed"
 
 
+def test_pocket_atlas_gate_rejects_structure_without_touching_holdouts():
+    report = load("bindingdb-v2-pocket-atlas-development-gate.json")
+    assert report["decision"] == "reject_structure_candidate_no_further_training"
+    assert report["benchmark_test_evaluations"] == 0
+    assert report["external_holdout_evaluations"] == 0
+    assert report["population"] == {
+        "sample_rows": 2327,
+        "source_development_rows": 2057,
+        "development_rows_excluded_for_test_cluster_homology": 292,
+        "safe_development_rows": 1765,
+        "safe_development_pairs": 1717,
+        "safe_development_proteins": 278,
+        "safe_development_clusters": 187,
+        "benchmark_test_rows_excluded": 270,
+        "benchmark_test_clusters_reserved": 34,
+    }
+    assert report["alphafold_snapshot"]["canonical_models"] == 145
+    assert report["structure_features"]["successful_structures"] == 145
+    assert report["structure_features"]["failed_structures"] == 0
+    control = report["control"]["metrics"]["rmse"]
+    esm = report["variants"]["protein_embedding_ridge_residual"]["metrics"]["rmse"]
+    structure = report["variants"]["structure_ridge_residual"]["metrics"]["rmse"]
+    combined = report["variants"]["protein_embedding_plus_structure_ridge_residual"]["metrics"][
+        "rmse"
+    ]
+    assert esm < combined < control < structure
+    gate = report["predeclared_structure_gate"]
+    assert gate["actual_incremental_rmse_improvement_vs_esm"] < 0
+    assert gate["incremental_cluster_bootstrap"]["ci_2_5"] < 0
+    assert gate["incremental_cluster_bootstrap"]["ci_97_5"] > 0
+    assert gate["no_catastrophic_fold"] is False
+    assert gate["passed"] is False
+    verification = report["verification"]
+    assert verification["test_pairs_in_predictions"] == 0
+    assert verification["test_clusters_in_predictions"] == 0
+    assert verification["source_reproduction"] == {
+        "mapping_exact_match": True,
+        "structure_manifest_exact_match": True,
+    }
+    assert report["artifacts"]["checkpoint_created"] is False
+    assert report["artifacts"]["weights_published"] is False
+
+
 def test_primary_kd_audit_and_similarity_split():
     audit = load("balm-kd-audit.json")
     clusters = load("balm-kd-protein-clusters.json")

recovery/tests/test_pocket_features.py

@@ -0,0 +1,112 @@
+"""Tests for deterministic Pocket Atlas structural descriptors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pytest
+from mitointeract_recovery.pocket_features import (
+    FEATURE_NAMES,
+    parse_pdb_plddt,
+    structure_feature_vector,
+)
+
+
+class FakeAtoms:
+    def __init__(self, coordinates: np.ndarray, atom_names: list[str]) -> None:
+        self.coord = coordinates
+        self.atom_name = np.asarray(atom_names)
+
+    def __len__(self) -> int:
+        return len(self.coord)
+
+
+@dataclass
+class FakeSphere:
+    radius: float
+    mean_sasa: float
+
+
+@dataclass
+class FakePocket:
+    score: float
+    volume: float
+    spheres: list[FakeSphere]
+    residues: list[tuple[str, int, str]]
+    mask: np.ndarray
+
+    @property
+    def n_spheres(self) -> int:
+        return len(self.spheres)
+
+
+def pdb_atom(serial: int, plddt: float) -> str:
+    return (
+        f"ATOM  {serial:5d}  CA  ALA A{serial:4d}    "
+        f"{serial:8.3f}{0.0:8.3f}{0.0:8.3f}{1.0:6.2f}{plddt:6.2f}          C\n"
+    )
+
+
+def metadata() -> dict:
+    return {
+        "global_metric_value": 85.0,
+        "fraction_plddt_very_high": 0.4,
+        "fraction_plddt_confident": 0.4,
+        "fraction_plddt_low": 0.1,
+        "fraction_plddt_very_low": 0.1,
+        "sequence_start": 1,
+        "sequence_end": 4,
+    }
+
+
+def test_parse_pdb_plddt_reads_coordinate_b_factors(tmp_path: Path) -> None:
+    path = tmp_path / "model.pdb"
+    path.write_text(pdb_atom(1, 91.2) + pdb_atom(2, 67.8) + "END\n")
+    assert parse_pdb_plddt(path).tolist() == [91.2, 67.8]
+
+
+def test_parse_pdb_plddt_rejects_out_of_range_confidence(tmp_path: Path) -> None:
+    path = tmp_path / "model.pdb"
+    path.write_text(pdb_atom(1, 101.0))
+    with pytest.raises(ValueError, match="invalid AlphaFold pLDDT"):
+        parse_pdb_plddt(path)
+
+
+def test_structure_features_have_fixed_finite_width() -> None:
+    coordinates = np.asarray([[0, 0, 0], [2, 1, 0], [4, 1, 2], [7, 3, 1]], dtype=float)
+    atoms = FakeAtoms(coordinates, ["CA"] * 4)
+    pocket = FakePocket(
+        score=0.8,
+        volume=200.0,
+        spheres=[FakeSphere(4.0, 12.0), FakeSphere(5.0, 16.0)],
+        residues=[("A", 1, "LEU"), ("A", 2, "ASP")],
+        mask=np.asarray([True, True, False, False]),
+    )
+    vector = structure_feature_vector(
+        atoms, [pocket], np.asarray([90, 80, 70, 60], dtype=float), metadata()
+    )
+    assert vector.shape == (len(FEATURE_NAMES),)
+    assert len(FEATURE_NAMES) == len(set(FEATURE_NAMES))
+    assert np.isfinite(vector).all()
+    assert vector[FEATURE_NAMES.index("structure_available")] == 1
+    assert vector[FEATURE_NAMES.index("log_pocket_count")] > 0
+    assert vector[FEATURE_NAMES.index("pocket_1_hydrophobic_fraction")] == 0.5
+
+
+def test_structure_features_are_rotation_invariant() -> None:
+    coordinates = np.asarray([[0, 0, 0], [2, 1, 0], [4, 1, 2], [7, 3, 1], [8, 6, 3]], dtype=float)
+    rotation = np.asarray([[0.0, -1.0, 0.0], [1.0, 0.0, 0.0], [0.0, 0.0, 1.0]], dtype=float)
+    plddt = np.asarray([90, 80, 70, 60, 50], dtype=float)
+    first = structure_feature_vector(FakeAtoms(coordinates, ["CA"] * 5), [], plddt, metadata())
+    second = structure_feature_vector(
+        FakeAtoms(coordinates @ rotation.T, ["CA"] * 5), [], plddt, metadata()
+    )
+    np.testing.assert_allclose(first, second, rtol=1e-6, atol=1e-6)
+
+
+def test_structure_features_reject_plddt_atom_mismatch() -> None:
+    atoms = FakeAtoms(np.asarray([[0, 0, 0], [1, 1, 1]], dtype=float), ["CA", "CA"])
+    with pytest.raises(ValueError, match="count mismatch"):
+        structure_feature_vector(atoms, [], np.asarray([90.0]), metadata())

recovery/tests/test_pocket_gate.py

@@ -0,0 +1,110 @@
+"""Tests for Pocket Atlas feature alignment and missingness handling."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pytest
+from mitointeract_recovery.pocket_features import FEATURE_NAMES
+from mitointeract_recovery.pocket_gate import (
+    FEATURE_SCHEMA,
+    align_structure_features,
+    read_mapping,
+)
+
+
+def mapping() -> dict[str, dict]:
+    return {
+        "p1": {
+            "protein_id": "p1",
+            "eligible": True,
+            "accession": "A1",
+            "coverage": 1.0,
+            "placement": "exact",
+        },
+        "p2": {
+            "protein_id": "p2",
+            "eligible": True,
+            "accession": "A2",
+            "coverage": 0.9,
+            "placement": "subsequence",
+        },
+        "p3": {"protein_id": "p3", "eligible": False},
+    }
+
+
+def document() -> dict:
+    vector = [0.0] * len(FEATURE_NAMES)
+    vector[0] = 1.0
+    return {
+        "schema_version": FEATURE_SCHEMA,
+        "feature_names": FEATURE_NAMES,
+        "accessions": {"A1": {"features": vector}},
+    }
+
+
+def test_align_structure_features_tracks_available_and_missing_rows() -> None:
+    protein_ids = np.asarray(["p1", "p1", "p2", "p3"])
+    matrix, coverage = align_structure_features(
+        protein_ids=protein_ids,
+        safe_indices=np.arange(4),
+        mapping=mapping(),
+        feature_document=document(),
+    )
+    assert matrix.shape == (4, len(FEATURE_NAMES) + 2)
+    assert matrix[:, 0].tolist() == [1.0, 1.0, 0.0, 0.0]
+    assert matrix[:2, -2].tolist() == [1.0, 1.0]
+    assert matrix[:2, -1].tolist() == [1.0, 1.0]
+    assert coverage == {
+        "safe_rows": 4,
+        "available_rows": 2,
+        "missing_rows": 2,
+        "safe_proteins": 3,
+        "available_proteins": 1,
+        "missing_proteins": 2,
+    }
+
+
+def test_align_structure_features_requires_exact_safe_protein_manifest() -> None:
+    with pytest.raises(ValueError, match="exactly cover"):
+        align_structure_features(
+            protein_ids=np.asarray(["p1", "p2"]),
+            safe_indices=np.arange(2),
+            mapping={"p1": mapping()["p1"]},
+            feature_document=document(),
+        )
+
+
+def test_align_structure_features_rejects_invalid_availability_flag() -> None:
+    bad = document()
+    bad["accessions"]["A1"]["features"][0] = 0.0
+    with pytest.raises(ValueError, match="availability flag"):
+        align_structure_features(
+            protein_ids=np.asarray(["p1", "p2", "p3"]),
+            safe_indices=np.arange(3),
+            mapping=mapping(),
+            feature_document=bad,
+        )
+
+
+def test_align_structure_features_rejects_contract_drift() -> None:
+    bad = document()
+    bad["feature_names"] = list(FEATURE_NAMES[:-1])
+    with pytest.raises(ValueError, match="feature names"):
+        align_structure_features(
+            protein_ids=np.asarray(["p1", "p2", "p3"]),
+            safe_indices=np.arange(3),
+            mapping=mapping(),
+            feature_document=bad,
+        )
+
+
+def test_read_mapping_rejects_duplicate_proteins(tmp_path: Path) -> None:
+    path = tmp_path / "mapping.jsonl"
+    path.write_text(
+        json.dumps({"protein_id": "p1"}) + "\n" + json.dumps({"protein_id": "p1"}) + "\n"
+    )
+    with pytest.raises(ValueError, match="duplicate"):
+        read_mapping(path)

recovery/tests/test_pocket_sources.py

@@ -0,0 +1,140 @@
+"""Tests for Pocket Atlas source mapping and canonical model selection."""
+
+from __future__ import annotations
+
+import pytest
+from mitointeract_recovery.pocket_sources import (
+    build_protein_mapping,
+    place_sequence,
+    select_canonical_alphafold_model,
+)
+
+
+def test_place_sequence_exact_and_contiguous_constructs() -> None:
+    assert place_sequence("ACDE", "ACDE") == {
+        "placement": "exact",
+        "coverage": 1.0,
+        "sequence_start": 1,
+        "sequence_end": 4,
+    }
+    subsequence = place_sequence("CDE", "ACDEF")
+    assert subsequence == {
+        "placement": "subsequence",
+        "coverage": 0.6,
+        "sequence_start": 2,
+        "sequence_end": 4,
+    }
+    supersequence = place_sequence("XACDEY", "ACDE")
+    assert supersequence["placement"] == "supersequence"
+    assert supersequence["coverage"] == pytest.approx(4 / 6)
+    assert place_sequence("AAAA", "CCCC")["placement"] == "noncontiguous"
+
+
+def test_select_canonical_model_excludes_isoforms_and_complexes() -> None:
+    models = [
+        {
+            "modelEntityId": "AF-P12345-2-F1",
+            "providerId": "GDM",
+            "entityType": "protein",
+            "isComplex": False,
+            "pdbUrl": "isoform",
+            "latestVersion": 6,
+        },
+        {
+            "modelEntityId": "AF-P12345-F1",
+            "providerId": "GDM",
+            "entityType": "protein",
+            "isComplex": False,
+            "pdbUrl": "canonical",
+            "latestVersion": 6,
+        },
+        {
+            "modelEntityId": "AF-P12345-F1",
+            "providerId": "NVIDIA",
+            "entityType": "protein",
+            "isComplex": True,
+            "pdbUrl": "complex",
+            "latestVersion": 1,
+        },
+    ]
+    selected = select_canonical_alphafold_model("P12345", models)
+    assert selected is not None
+    assert selected["pdbUrl"] == "canonical"
+    assert select_canonical_alphafold_model("Q99999", models) is None
+
+
+def test_build_mapping_excludes_test_and_test_homology_clusters() -> None:
+    rows = [
+        {
+            "pair_id": "pair-1",
+            "protein_id": "p1",
+            "sequence": "ACDE",
+            "source_record_ids": ["s1"],
+        },
+        {
+            "pair_id": "pair-2",
+            "protein_id": "p2",
+            "sequence": "FGHI",
+            "source_record_ids": ["s2"],
+        },
+        {
+            "pair_id": "pair-3",
+            "protein_id": "p3",
+            "sequence": "KLMN",
+            "source_record_ids": ["s3"],
+        },
+        {
+            "pair_id": "pair-4",
+            "protein_id": "p4",
+            "sequence": "QRST",
+            "source_record_ids": ["s4"],
+        },
+    ]
+    mapping, audit = build_protein_mapping(
+        sample_rows=rows,
+        manifest={
+            "pair-1": "train",
+            "pair-2": "test",
+            "pair-3": "validation",
+            "pair-4": "validation",
+        },
+        source_accessions={"s1": "U1", "s2": "U2", "s3": "U3", "s4": "U4"},
+        clusters={"p1": "c1", "p2": "ct", "p3": "ct", "p4": "c4"},
+        uniprot_entries={
+            "U1": {"reviewed": "reviewed", "sequence": "ACDE", "sequence_version": 1},
+            "U4": {
+                "reviewed": "reviewed",
+                "sequence": "QRSTX",
+                "sequence_version": 2,
+            },
+        },
+    )
+    assert [row["protein_id"] for row in mapping] == ["p1", "p4"]
+    assert all(row["eligible"] for row in mapping)
+    assert mapping[1]["placement"] == "subsequence"
+    assert mapping[1]["coverage"] == 0.8
+    assert audit == {
+        "safe_rows": 2,
+        "safe_proteins": 2,
+        "test_clusters_reserved": 1,
+        "eligible_proteins": 2,
+        "eligible_accessions": 2,
+    }
+
+
+def test_build_mapping_rejects_incomplete_manifest() -> None:
+    with pytest.raises(ValueError, match="pair set"):
+        build_protein_mapping(
+            sample_rows=[
+                {
+                    "pair_id": "pair-1",
+                    "protein_id": "p1",
+                    "sequence": "ACDE",
+                    "source_record_ids": [],
+                }
+            ],
+            manifest={},
+            source_accessions={},
+            clusters={"p1": "c1"},
+            uniprot_entries={},
+        )