[fix.fep.ρ.D8+] make eight-ligand design usable and executable

The focused FEP surface was still an expert-only backend projection: ordinary substitution networks disconnected under arbitrary conformer distances, legitimate partial-core chemistry was refused, and the browser could preserve stale or contradictory workflow state. This commit makes the one-click T4L path survive from novice input through eight reviewed poses, a connected OpenFE plan, and exact two-leg system qualification. It also adds adversarial browser and HTTP matrices so malformed inputs, modal/focus failures, responsive overflow, cross-tab state, corrupted receipts, contract bypasses, and job creation regressions remain reproducible.\n\nEvidence: two consecutive clean rounds of 125 FEP tests, 175 RBFE/OpenFE tests plus 10 subtests, hostile browser and HTTP matrices, full eight-ligand campaign qualification, typecheck, both production builds, contract generators, architecture twin, and all 14 repository gates. Physical FEP was not started; the verified no-GPU boundary remained locked.

Author: ivanicu

backend/motif/openfe_network_planner.py

@@ -211,8 +211,15 @@ def plan(document: dict) -> dict:
         row["id"]: Chem.MolFromSmiles(row["smiles"]).GetNumHeavyAtoms()
         for row in compounds
     }
+    # These components are embedded independently only to satisfy GUFE's
+    # explicit-molecule contract.  LoMap still applies ``max3d`` trimming when
+    # ``threed`` is false, so its default 1 A cutoff can erase a chemically
+    # obvious 2-D MCS (for example benzene -> toluene) solely because the two
+    # arbitrary conformers are not superposed.  Disable the coordinate cutoff
+    # for this topology-only planning pass; posed-system preparation performs
+    # the later receptor-frame geometry check.
     lomap = openfe.LomapAtomMapper(time=int(document.get("lomap_timeout", 20)),
-                                  threed=False)
+                                  threed=False, max3d=0)
     kartograf = openfe.KartografAtomMapper(atom_map_hydrogens=False,
                                            allow_bond_breaks=False)
     network = ligand_network_planning.generate_minimal_redundant_network(

backend/motif/rbfe_campaign_builder.py

@@ -570,6 +570,29 @@ def _validate_forcefield_contract(contract: dict) -> dict:
     }
 
 
+def _missing_atom_names(atoms) -> list[str]:
+    return sorted(str(getattr(atom, "name", atom)) for atom in atoms)
+
+
+def _missing_residue_segment_witnesses(missing_residues, chain_lengths) -> list[dict]:
+    witnesses = []
+    for (chain, index), names in sorted(missing_residues.items()):
+        chain_index, insertion_index = int(chain), int(index)
+        modeled_count = int(chain_lengths.get(chain_index, 0))
+        terminal = insertion_index == 0 or insertion_index == modeled_count
+        witnesses.append({
+            "chain_index": chain_index,
+            "insertion_index": insertion_index,
+            "residue_names": list(names),
+            "location": ("n_terminal" if insertion_index == 0 else
+                         "c_terminal" if insertion_index == modeled_count else
+                         "internal"),
+            "modeled_residue_count": modeled_count,
+            "terminal_omission": terminal,
+        })
+    return witnesses
+
+
 def _prepare_receptor(pdb_text: str, *, ph: float, keep_waters: bool,
                       chain_ids: list[str] | None = None,
                       missing_atoms_policy: str = "auto_repair_report",
@@ -636,22 +659,29 @@ def _prepare_receptor(pdb_text: str, *, ph: float, keep_waters: bool,
             f"tautomer/protonation decisions were supplied; witnesses "
             f"{histidine_input_witnesses[:10]}")
     fixer.findMissingResidues()
-    unresolved_residues = [
-        {"chain_index": int(chain), "insertion_index": int(index),
-         "residue_names": list(names)}
-        for (chain, index), names in sorted(fixer.missingResidues.items())
-    ]
+    modeled_chain_lengths = {
+        index: len(list(chain.residues()))
+        for index, chain in enumerate(fixer.topology.chains())
+    }
+    missing_residue_segments = _missing_residue_segment_witnesses(
+        fixer.missingResidues, modeled_chain_lengths)
     if missing_residues_policy not in {"auto_repair_report", "review_each", "block"}:
         raise ValueError(
             f"unsupported receptor_policy.missing_residues={missing_residues_policy!r}")
-    if unresolved_residues:
+    internal_missing_residues = [
+        row for row in missing_residue_segments if not row["terminal_omission"]]
+    if missing_residue_segments and (
+            missing_residues_policy != "auto_repair_report" or
+            internal_missing_residues):
         raise ValueError(
             f"receptor_policy.missing_residues={missing_residues_policy} is UNVERIFIED: "
-            f"the structure has {len(unresolved_residues)} absent residue segments; "
-            "PDBFixer loop coordinates are deliberately not invented; first witnesses "
-            f"{unresolved_residues[:10]}")
+            f"the structure has {len(missing_residue_segments)} absent residue segments "
+            f"({len(internal_missing_residues)} internal); PDBFixer loop coordinates are "
+            "deliberately not invented; first witnesses "
+            f"{missing_residue_segments[:10]}")
     # Building absent loops would invent coordinates. Existing-residue heavy atoms
-    # are repairable; absent residues stay explicitly unresolved.
+    # are repairable. Under auto_repair_report, absent terminal tails are retained
+    # as explicit omissions; internal gaps remain fail-closed.
     fixer.missingResidues = {}
     fixer.findNonstandardResidues()
     nonstandard = [{"residue": str(residue), "replacement": replacement}
@@ -668,12 +698,14 @@ def _prepare_receptor(pdb_text: str, *, ph: float, keep_waters: bool,
     missing_atom_witnesses = [{
         "chain_id": str(residue.chain.id), "residue_name": str(residue.name),
         "residue_number": str(residue.id),
-        "atom_names": sorted(str(atom.name) for atom in atoms),
+        "atom_names": _missing_atom_names(atoms),
     } for residue, atoms in fixer.missingAtoms.items()]
     missing_terminal_witnesses = [{
         "chain_id": str(residue.chain.id), "residue_name": str(residue.name),
         "residue_number": str(residue.id),
-        "atom_names": sorted(str(atom.name) for atom in atoms),
+        # PDBFixer 1.12 exposes internal missing atoms as template Atom
+        # objects but terminal atoms as names. Preserve either API shape.
+        "atom_names": _missing_atom_names(atoms),
     } for residue, atoms in fixer.missingTerminals.items()]
     if missing_atoms_policy not in {"auto_repair_report", "review_each", "block"}:
         raise ValueError(
@@ -735,7 +767,8 @@ def _prepare_receptor(pdb_text: str, *, ph: float, keep_waters: bool,
         "missing_residues_policy": missing_residues_policy,
         "missing_existing_residue_atoms_added": missing_atom_count,
         "missing_terminal_atoms_added": missing_terminal_count,
-        "unresolved_missing_residues": unresolved_residues,
+        "unresolved_missing_residues": internal_missing_residues,
+        "omitted_terminal_residue_segments": missing_residue_segments,
         "nonstandard_residue_replacements": nonstandard,
         "policy_execution": {
             "missing_atoms": {
@@ -748,8 +781,13 @@ def _prepare_receptor(pdb_text: str, *, ph: float, keep_waters: bool,
             },
             "missing_residues": {
                 "verdict": "CONFIRMED", "policy": missing_residues_policy,
-                "observed_action": "not_applicable_no_missing_residue_segments",
+                "observed_action": (
+                    "terminal_absent_segments_omitted_and_reported"
+                    if missing_residue_segments else
+                    "not_applicable_no_missing_residue_segments"),
                 "unresolved_segment_count": 0,
+                "omitted_terminal_segment_count": len(missing_residue_segments),
+                "omitted_terminal_witnesses": missing_residue_segments,
             },
             "histidines": {
                 "verdict": "CONFIRMED", "policy": histidines_policy,

backend/motif/rbfe_chemistry_evidence.py

@@ -428,26 +428,30 @@ def mapping_change_evidence(left: Chem.Mol, right: Chem.Mol,
               "full_coverage": full_coverage}]),
         _dimension(
             "ELEMENT", CHANGED if element_changes else (
-                CONFIRMED if full_coverage else UNVERIFIED),
+                CONFIRMED if full_coverage or microstate_contract_attached
+                else UNVERIFIED),
             (f"{len(element_changes)} mapped element changes" if element_changes
              else "no mapped element change"), element_changes),
         _dimension(
             "CONNECTIVITY", CHANGED if connectivity_changes else (
-                CONFIRMED if full_coverage and mapped_left_bonds else UNVERIFIED),
+                CONFIRMED if ((full_coverage or microstate_contract_attached)
+                              and mapped_left_bonds) else UNVERIFIED),
             (f"{len(connectivity_changes)} mapped adjacency changes"
              if connectivity_changes else
              f"no adjacency change across {mapped_left_bonds} mapped bonds"),
             connectivity_changes),
         _dimension(
             "BOND_ORDER", CHANGED if bond_order_changes else (
-                CONFIRMED if full_coverage and mapped_left_bonds else UNVERIFIED),
+                CONFIRMED if ((full_coverage or microstate_contract_attached)
+                              and mapped_left_bonds) else UNVERIFIED),
             (f"{len(bond_order_changes)} mapped bond-order changes"
              if bond_order_changes else
              f"no bond-order change across {mapped_left_bonds} mapped bonds"),
             bond_order_changes),
         _dimension(
             "FORMAL_CHARGE", CHANGED if charge_changes else (
-                CONFIRMED if full_coverage else UNVERIFIED),
+                CONFIRMED if full_coverage or microstate_contract_attached
+                else UNVERIFIED),
             (f"{len(charge_changes)} formal-charge changes" if charge_changes
              else f"total formal charge {left_charge} in both endpoints"), charge_changes),
         _dimension(
@@ -461,7 +465,8 @@ def mapping_change_evidence(left: Chem.Mol, right: Chem.Mol,
             stereo_changes + stereo_unverified),
         _dimension(
             "RING_CYCLE_RANK", CHANGED if left_rank != right_rank else (
-                CONFIRMED if full_coverage else UNVERIFIED),
+                CONFIRMED if full_coverage or microstate_contract_attached
+                else UNVERIFIED),
             f"cycle rank {left_rank} -> {right_rank}",
             [{"parent_cycle_rank": left_rank, "proposal_cycle_rank": right_rank}]),
         _dimension(
@@ -499,6 +504,21 @@ def mapping_change_evidence(left: Chem.Mol, right: Chem.Mol,
             "kind": "TAUTOMER_OR_VALENCE_STATE",
             "bond_order_witnesses": bond_order_changes,
         })
+    elif (not microstate_comparable and microstate_contract_attached
+          and not charge_delta):
+        # A partial common core is the normal RBFE case: adding or removing a
+        # substituent changes total hydrogen count without implying a hidden
+        # protonation transition.  Once both exact endpoint microstates have
+        # been server-attested, record that structural delta explicitly rather
+        # than downgrading the whole transformation to UNVERIFIED.
+        microstate_changes.append({
+            "kind": "ATTESTED_ENDPOINTS_WITH_STRUCTURAL_DELTA",
+            "parent_total_hydrogen_count": left_h,
+            "proposal_total_hydrogen_count": right_h,
+            "formal_charge_delta": charge_delta,
+            "unmapped_parent_heavy_atoms": len(left_unmapped),
+            "unmapped_proposal_heavy_atoms": len(right_unmapped),
+        })
     elif not microstate_comparable and (hydrogen_delta or charge_delta):
         microstate_ambiguity.append({
             "kind": "ENDPOINTS_NOT_MICROSTATE_COMPARABLE",
@@ -507,13 +527,20 @@ def mapping_change_evidence(left: Chem.Mol, right: Chem.Mol,
             "formal_charge_delta": charge_delta,
         })
     microstate_verdict = (
-        CHANGED if microstate_changes else
+        (CONFIRMED if (microstate_changes and
+                       microstate_changes[0].get("kind") ==
+                       "ATTESTED_ENDPOINTS_WITH_STRUCTURAL_DELTA") else CHANGED)
+        if microstate_changes else
         (UNVERIFIED if microstate_ambiguity else
          (CONFIRMED if microstate_contract_attached else UNVERIFIED)))
     ledger.append(_dimension(
         "PROTONATION_TAUTOMER",
         microstate_verdict,
-        (f"{len(microstate_changes)} protonation/microstate changes" if microstate_changes
+        ("endpoint microstates attested; hydrogen delta is explained by the "
+         "explicit structural transformation" if (microstate_changes and
+             microstate_changes[0].get("kind") ==
+             "ATTESTED_ENDPOINTS_WITH_STRUCTURAL_DELTA") else
+         f"{len(microstate_changes)} protonation/microstate changes" if microstate_changes
          else (f"{len(microstate_ambiguity)} non-diagnostic hydrogen/charge changes"
                if microstate_ambiguity else
                ("explicit endpoint microstate contracts attached"

backend/motif/rbfe_references.py

@@ -42,6 +42,11 @@ def _canonical(document: dict) -> bytes:
                       allow_nan=False).encode()
 
 
+def _receipt_snapshot(response: dict) -> dict:
+    """Detach persisted receipt data from the mutable command response."""
+    return json.loads(json.dumps(response, allow_nan=False))
+
+
 def _sha(data: bytes | str) -> str:
     if isinstance(data, str):
         data = data.encode()
@@ -2003,7 +2008,7 @@ def prepare_campaign(self, payload: dict, store,
                 "prepared_scientific_ref": prepared_scientific_ref,
             })
             state.pop("pending_changed_domains", None)
-            receipt_response = dict(response)
+            receipt_response = _receipt_snapshot(response)
             receipt = {
                 "request_digest": request_digest,
                 "input_version": expected_version,
@@ -2254,6 +2259,7 @@ def accept_poses(self, payload: dict, actor: dict[str, str]) -> dict:
                     "Human-reviewed reference-constrained poses. This acceptance does not "
                     "constitute an FEP result or validate the pose-generation method."),
             }
+            receipt_response = _receipt_snapshot(response)
             state = dict(current["state"])
             state.update({
                 "version": output_version, "status": "poses_reviewed",
@@ -2264,7 +2270,7 @@ def accept_poses(self, payload: dict, actor: dict[str, str]) -> dict:
                     "request_digest": request_digest,
                     "input_version": expected_version,
                     "output_version": output_version,
-                    "response": response, "verdict": "CONFIRMED",
+                    "response": receipt_response, "verdict": "CONFIRMED",
                 },
             })
             state = _advance_scientific_state(

backend/tests/test_rbfe_campaign_state.py

@@ -300,6 +300,25 @@ def test_real_1cbs_polymer_a_reference_b_simple_remove_path_stays_usable():
     assert completed.returncode == 0, completed.stdout + completed.stderr
 
 
+def test_pdbfixer_missing_atom_shapes_and_terminal_residue_omissions_are_normalized():
+    script = r'''
+import sys
+from types import SimpleNamespace
+sys.path.insert(0, "backend/motif")
+import rbfe_campaign_builder as builder
+
+assert builder._missing_atom_names(["OXT", SimpleNamespace(name="H")]) == ["H", "OXT"]
+witnesses = builder._missing_residue_segment_witnesses(
+    {(0, 0): ["MET"], (0, 162): ["ASN", "LEU"], (0, 80): ["GLY"]},
+    {0: 162},
+)
+assert [row["location"] for row in witnesses] == ["n_terminal", "internal", "c_terminal"]
+assert [row["terminal_omission"] for row in witnesses] == [True, False, True]
+'''
+    completed = _openfe_probe(script)
+    assert completed.returncode == 0, completed.stdout + completed.stderr
+
+
 def test_server_histidine_and_terminus_assignments_have_exact_atom_witnesses_manual_is_blocked():
     script = r'''
 import sys
@@ -585,6 +604,16 @@ def test_scientific_conflicts_do_not_masquerade_as_revision_conflicts():
     assert "actual_version" not in payload
 
 
+def test_receipt_snapshot_cannot_be_mutated_by_later_response_enrichment():
+    from motif.rbfe_references import _receipt_snapshot
+
+    response = {"poses": [{"id": "pose-1"}]}
+    receipt = _receipt_snapshot(response)
+    response["campaign_ref"] = {"id": "campaign-1"}
+    response["poses"][0]["id"] = "mutated"
+    assert receipt == {"poses": [{"id": "pose-1"}]}
+
+
 def test_import_receipt_survives_metadata_revision_but_not_science_change():
     from motif.rbfe_references import (
         _campaign_scientific_ref, _import_receipt_is_current)

backend/tests/test_rbfe_chemistry_evidence.py

@@ -255,6 +255,22 @@ def test_tautomer_bond_pattern_is_changed_but_analogue_hydrogens_are_not() -> No
     assert analogue_row["witnesses"][0][
         "kind"] == "ENDPOINTS_NOT_MICROSTATE_COMPARABLE"
 
+    attested_analogue = mapping_change_evidence(
+        _mol("c1ccccc1"), _mol("Cc1ccccc1"),
+        [(index, index + 1) for index in range(6)],
+        microstate_contract_attached=True)
+    attested_ledger = _ledger(attested_analogue)
+    assert attested_analogue["verdict"] == CHANGED
+    assert attested_ledger["UNMAPPED"]["verdict"] == CHANGED
+    assert attested_ledger["ELEMENT"]["verdict"] == CONFIRMED
+    assert attested_ledger["CONNECTIVITY"]["verdict"] == CONFIRMED
+    assert attested_ledger["BOND_ORDER"]["verdict"] == CONFIRMED
+    assert attested_ledger["FORMAL_CHARGE"]["verdict"] == CONFIRMED
+    assert attested_ledger["RING_CYCLE_RANK"]["verdict"] == CONFIRMED
+    assert attested_ledger["PROTONATION_TAUTOMER"]["verdict"] == CONFIRMED
+    assert attested_ledger["PROTONATION_TAUTOMER"]["witnesses"][0][
+        "kind"] == "ATTESTED_ENDPOINTS_WITH_STRUCTURAL_DELTA"
+
 
 @pytest.mark.parametrize("parent, proposal, change", [
     ("CC(O)C", "C[C@H](O)F", "ADDED_STEREOCENTER"),
@@ -354,6 +370,26 @@ def test_planner_preserves_campaign_contract_and_all_depictions(
         "schema_version"] == "rbfe-depiction-index.v2"
 
 
+@pytest.mark.skipif(not RUNTIME.is_file(), reason="pinned OpenFE runtime unavailable")
+def test_topology_planning_does_not_trim_a_common_core_by_random_3d_distance(
+        tmp_path: Path) -> None:
+    network = _plan(tmp_path, {
+        "compounds": [
+            {"id": "BEN", "smiles": "c1ccccc1"},
+            {"id": "TOL", "smiles": "Cc1ccccc1"},
+        ],
+        "seed": 1729,
+        "mst_num": 1,
+    })
+    assert network["rejected_edges"] == []
+    assert len(network["edges"]) == 1
+    edge = network["edges"][0]
+    assert {edge["left_id"], edge["right_id"]} == {"BEN", "TOL"}
+    assert edge["mapped_heavy_atom_count"] == 6
+    assert len(edge["selected_heavy_atom_mapping"]) == 6
+    assert edge["mapping_score"] >= 0.8
+
+
 @pytest.mark.skipif(not RUNTIME.is_file(), reason="pinned OpenFE runtime unavailable")
 def test_planner_direct_entry_refuses_duplicate_compound_ids(
         tmp_path: Path) -> None: