small_molecule_binding: fix guided-RFD3 crashes, deadlock, and stuck seeds

[drawadiagram]

Splits the guided-RFD3 fix series out of #59. Fourth of four, and the smallest.

Based on #62 — review only the commit on this branch. GitHub retargets this to main once #62 merges.

The guided (partial-diffusion) RFD3 path added in #62 crashed every pipeline on first use. Job 21916521 lost all 4 pipelines to the same ComponentValidationError about 3h in. This is the fix series.

Root cause: ligand atom names

Boltz-2 assigns its own atom names to the ligand when co-folding, unrelated to the canonical names in the Rosetta .params file. select_exposed/select_buried are copied verbatim from the base RFD3 spec and keyed by those canonical names, so they never resolved against a Boltz-derived PDB and RFD3 rejected every guided run.

_infer_ligand_atom_mapping() now establishes the correspondence by element + heavy-atom-connectivity graph isomorphism (RDKit DetermineConnectivity, since Boltz emits no CONECT records), breaking ties by Kabsch RMSD against the reference structure's real coordinates. Local symmetry — a sulfonate's three interchangeable oxygens — can yield several valid isomorphisms, so the best-vs-next-best RMSD gap is logged: a near-tie means the tie-break wasn't decisive and the mapping deserves a look. Every helper fails closed, returning None/False so the caller falls back to unguided diffusion rather than emitting a spec RFD3 will reject.

Three more failure modes

• partial.length is dropped when partial.input/partial_t are set. RFD3's DesignInputSpecification validator rejects length outright in partial-diffusion mode, where length is inferred from the input structure.
• Guided-backbone QC deadlock. Only a successful fold ever cleared rfd3_input_pdb, so a guided backbone that kept failing backbone QC looped on the same seed forever. After 3 consecutive guided failures the pipeline now abandons guided mode and regenerates unguided.
• Stuck guided seed. rfd3_input_pdb is now cleared on every escalation to STEP_RFD3, not just backbone-QC failures. The sequence-similarity gate and packmin could previously escalate while leaving the seed pinned, so RFD3 regenerated near-duplicate doomed backbones — job 21945304 shows 17 consecutive p2 generations producing byte-identical guided_scaffold.pdb output from one stuck seed.

Also adds an mpnn_ensemble_size knob, fixes per-pipeline input_dir, pins rdkit==2024.9.6, and adds validate_run.py check 8 (check_guided_ligand_atom_names).

⚠️ One correction beyond the original change

scripts/check_ligand_atom_mapping.py reads crash artifacts under logs/, which is gitignored — so they aren't committed and are absent on any fresh checkout. As originally written the script printed RESULT: PASS and exited 0 when both of its checks had skipped, i.e. it green-lit precisely the case it couldn't test. It now reports INCONCLUSIVE and exits 2 unless given real fixtures via --base-path <completed run's output tree>. CLAUDE.md's claim that the fixtures are "already in the repo" is corrected to say where they actually come from.

So: this tool is not a merge gate as it stands. The real regression check is validate_run.py's check 8 against a completed run.

Scope note

validation-plan-postfix-atomname.md from #59 is not carried over — it's a post-run checklist for whoever runs the next HPC job rather than repo documentation, and its one durable part (the new-ligand onboarding check) was already in CLAUDE.md.

Replaces part of #59.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lo8DwSbyvdWZRkkkka6gA2