chore: drop dead SSBOND cross-check + trim CysteineHit fields

`cross_check_ssbonds` was called for its return value but the caller
discarded it and the function had no side effects (no stderr, no
raise). That made the call a pure no-op, and the supporting code
(`Ssbond` dataclass, `parsed.ssbonds` list, SSBOND parsing block,
helper key functions) was a 180-line dead chain. The audit also
showed nine `CysteineHit` fields that were only read inside
`cross_check_ssbonds`:
  - resName, chainRole, bondingState
  - sasa, sidechainSasa, rsasa
  - partnerChainId, partnerResSeq, partnerIcode
plus chainId / resSeq / iCode which had a single read inside the
same dead function.

With the per-cys PFrame out of scope per the refreshed spec, all
downstream consumers (`scoring._cys_class_bump`,
`scoring._has_integrity_issue`, the four count loops in main.py)
only ever read `cysClass` and `sidechainRsasa`. Trimming the
dataclass to those two fields drops construction boilerplate from
14 args to 2 and pulls `cysteines.py` from 212 to 154 lines.

Net change: -181 lines across cysteines / structure / main /
test_scoring, no behavior delta (65 pytest tests still pass).

Author: xnacly

README.md

@@ -101,7 +101,7 @@ domain on every output.
    clonotype filter (R1 subset).
 3. **Python** (`software/liabilities-script/`):
    - Parses PDB (`structure.py`): v3.30 fixed-column parser; pulls
-     ATOM / HETATM / SSBOND / `REMARK 99 PLATFORMA CDR*` records.
+     ATOM / HETATM / `REMARK 99 PLATFORMA CDR*` records.
    - Runs FreeSASA against in-block Ala-X-Ala heavy-atom references
      (`data/heavy_atom_max_sasa.tsv`, spec R11).
    - Detects motifs (`motifs.py`): 11 patterns from

software/liabilities-script/cysteines.py

@@ -11,10 +11,15 @@
 #   - disulfide          : both canonical Cys present + bonded
 #   - disulfide_broken   : both canonical Cys present + unbonded
 #   - disulfide_missing  : a canonical position has no Cys (a phantom hit
-#                          is emitted at the expected position with cysClass
-#                          set to disulfide_missing)
+#                          is emitted at that role with cysClass set to
+#                          disulfide_missing)
 #   - cys_extra          : a Cys at any non-canonical position, regardless
 #                          of bonding state
+#
+# Per-cys drill-down is out of scope per the refreshed spec, so each hit
+# only carries the two fields actually consumed downstream: the class label
+# (for counts + the developability bump) and the side-chain rSASA (for the
+# "exposed extra" count + the buried-vs-exposed gate in the scoring bump).
 
 import math
 from dataclasses import dataclass
@@ -29,20 +34,8 @@
 
 @dataclass
 class CysteineHit:
-    chainId: str
-    resSeq: int
-    iCode: str
-    resName: str  # always "CYS" for real hits; "-" for phantom missing entries
-    chainRole: str  # "H" / "L" / "-" when chain isn't mapped to either
     cysClass: str  # "disulfide" | "disulfide_broken" | "disulfide_missing" | "cys_extra" | "bonded" | "unbonded"
-    bondingState: str  # "bonded" | "unbonded" | "missing"
-    sasa: Optional[float]
-    rsasa: Optional[float]
-    sidechainSasa: Optional[float]
     sidechainRsasa: Optional[float]
-    partnerChainId: str
-    partnerResSeq: Optional[int]
-    partnerIcode: str
 
 
 def _dist(a, b) -> float:
@@ -93,41 +86,20 @@ def _scan_disulfides(cys_records) -> dict[int, int]:
 def _classify_cys(
     res_seq: int,
     role: Optional[str],
-    bonding_state: str,
+    bonded: bool,
     canonical_keys: set[tuple[str, int]],
     canonical_positions: dict,
 ) -> str:
     """R23 four-state classification. Falls back to raw bonding state
     when numbering isn't wired (no role / no canonical positions for the
-    scheme), so the table is still useful in the auto-detect-only case."""
+    scheme), so the hit is still classified usefully in the auto-detect-only
+    case (though the resulting "bonded"/"unbonded" values are inert
+    downstream)."""
     if role is not None and (role, res_seq) in canonical_keys:
-        return "disulfide" if bonding_state == "bonded" else "disulfide_broken"
+        return "disulfide" if bonded else "disulfide_broken"
     if role is not None and canonical_positions:
         return "cys_extra"
-    return bonding_state
-
-
-def _phantom_missing_cys(role: str, pos: int, chain_id_for_role: str) -> CysteineHit:
-    """Emit a placeholder row for a canonical Cys position the structure
-    doesn't actually contain (resName "-" sentinel). Spec R23: missing
-    canonical Cys is a developability red flag and needs to appear in
-    the cys table even without a real residue to attach to."""
-    return CysteineHit(
-        chainId=chain_id_for_role,
-        resSeq=pos,
-        iCode="-",
-        resName="-",
-        chainRole=role,
-        cysClass="disulfide_missing",
-        bondingState="missing",
-        sasa=None,
-        rsasa=None,
-        sidechainSasa=None,
-        sidechainRsasa=None,
-        partnerChainId="-",
-        partnerResSeq=None,
-        partnerIcode="-",
-    )
+    return "bonded" if bonded else "unbonded"
 
 
 def detect_cysteines(
@@ -144,69 +116,42 @@ def detect_cysteines(
     cys_records = _collect_cys_records(parsed)
     partner_of = _scan_disulfides(cys_records)
 
-    # Per-scheme canonical positions + the set we test each real Cys against.
     canonical_positions: dict[str, tuple[int, int]] = (
         CANONICAL_CYS_POSITIONS.get(numbering_scheme, {}) if numbering_scheme else {}
     )
     canonical_keys: set[tuple[str, int]] = {
         (role, pos) for role, positions in canonical_positions.items() for pos in positions
     }
-    # Used below to skip phantom rows for canonical positions that ARE
-    # filled , keyed by (role, res_seq).
-    cys_by_role_pos: dict[tuple[str, int], int] = {}
-    for idx, (chain_id, r, _ca, _sg) in enumerate(cys_records):
+    # Tracks which canonical (role, res_seq) slots are actually filled, so
+    # missing-Cys phantom rows below don't duplicate a real hit.
+    filled_canonical: set[tuple[str, int]] = set()
+    for chain_id, r, _ca, _sg in cys_records:
         role = role_of_chain(chain_id, heavy_chain_id, light_chain_id)
         if role is not None:
-            cys_by_role_pos[(role, r.res_seq)] = idx
+            filled_canonical.add((role, r.res_seq))
 
     hits: list[CysteineHit] = []
     for idx, (chain_id, r, _ca, _sg) in enumerate(cys_records):
         key = (chain_id, f"{r.res_seq}{r.i_code}".strip())
         sasa_info = sasa_lookup.get(key, {})
         role = role_of_chain(chain_id, heavy_chain_id, light_chain_id)
-
-        partner_idx = partner_of.get(idx)
-        if partner_idx is not None:
-            p_chain, p_res, _, _ = cys_records[partner_idx]
-            bonding_state = "bonded"
-            partner_chain = p_chain
-            partner_res_seq: Optional[int] = p_res.res_seq
-            partner_icode = p_res.i_code or "-"
-        else:
-            bonding_state = "unbonded"
-            partner_chain = "-"
-            partner_res_seq = None
-            partner_icode = "-"
-
+        bonded = partner_of.get(idx) is not None
         hits.append(
             CysteineHit(
-                chainId=chain_id,
-                resSeq=r.res_seq,
-                iCode=r.i_code or "-",
-                resName="CYS",
-                chainRole=role or "-",
                 cysClass=_classify_cys(
-                    r.res_seq, role, bonding_state, canonical_keys, canonical_positions
+                    r.res_seq, role, bonded, canonical_keys, canonical_positions
                 ),
-                bondingState=bonding_state,
-                sasa=sasa_info.get("sasa"),
-                rsasa=sasa_info.get("rsasa"),
-                sidechainSasa=sasa_info.get("sideChainSasa"),
                 sidechainRsasa=sasa_info.get("sideChainRsasa"),
-                partnerChainId=partner_chain,
-                partnerResSeq=partner_res_seq,
-                partnerIcode=partner_icode,
             )
         )
 
     # Phantom rows for missing canonical Cys (R23).
     for role, (p1, p2) in canonical_positions.items():
-        chain_id_for_role = heavy_chain_id if role == "H" else light_chain_id
-        if not chain_id_for_role:
+        if not (heavy_chain_id if role == "H" else light_chain_id):
             continue
         for pos in (p1, p2):
-            if (role, pos) in cys_by_role_pos:
+            if (role, pos) in filled_canonical:
                 continue
-            hits.append(_phantom_missing_cys(role, pos, chain_id_for_role))
+            hits.append(CysteineHit(cysClass="disulfide_missing", sidechainRsasa=None))
 
     return hits

software/liabilities-script/main.py

@@ -23,7 +23,7 @@
 from metrics import compute_metrics
 from motifs import detect_motifs
 from scoring import compute_developability
-from structure import check_hallmark_tetrad, cross_check_ssbonds, parse_pdb
+from structure import check_hallmark_tetrad, parse_pdb
 
 
 # Heavy-atom Ala-X-Ala SASA references (R11), loaded from
@@ -253,9 +253,7 @@ def analyze_pdb(
     )
     mode = "TAP" if n_chains == 2 else "TNP"
 
-    # R21 SSBOND cross-check + R33 hallmark tetrad. Hallmark mismatch
-    # surfaces in the TSV; SSBOND mismatches stay stderr-only.
-    cross_check_ssbonds(parsed.ssbonds, cys_hits)
+    # R33 hallmark tetrad re-check; mismatch surfaces as a TSV warning column.
     hallmark = check_hallmark_tetrad(
         parsed, numbering_scheme, heavy_chain_id, chain_count_mode=mode
     )

software/liabilities-script/structure.py

@@ -4,8 +4,8 @@
 PLATFORMA CDR record extraction, FreeSASA wrapper output normalization
 at the caller, B-factor read-through, the numbering-scheme constants
 (R14: canonical Cys positions, CDR ranges, hallmark tetrad, CDRH3
-compactness anchors), `region_for` resolution, plus the spec defensive
-checks (R21 SSBOND cross-check, R33 hallmark tetrad re-check).
+compactness anchors), `region_for` resolution, plus the R33 hallmark
+tetrad defensive check.
 """
 
 import re
@@ -46,21 +46,10 @@ def atom(self, name: str) -> Optional[Atom]:
         return None
 
 
-@dataclass
-class Ssbond:
-    chain1: str
-    res1: int
-    i_code1: str
-    chain2: str
-    res2: int
-    i_code2: str
-
-
 @dataclass
 class Parsed:
     chain_order: List[str] = field(default_factory=list)
     residues_by_chain: Dict[str, List[Residue]] = field(default_factory=dict)
-    ssbonds: List[Ssbond] = field(default_factory=list)
     # Spec R10 , CDR ranges from `REMARK 99 PLATFORMA CDR*` records emitted
     # by the Structure Prediction block. Shape: {"H": {"CDR1": (start, end),
     # "CDR2": (...), "CDR3": (...)}, "L": {...}}. Empty when not present;
@@ -125,29 +114,6 @@ def parse_pdb(text: str) -> Parsed:
                     out.chain_role_to_pdb_chain[role] = chain_start
                 elif existing.upper() != chain_start.upper():
                     out.chain_role_to_pdb_chain.pop(role, None)
-        elif tag == "SSBOND":
-            # SSBOND record fixed offsets (PDB v3.30):
-            #   col 15 = chainID1, 17-20 = resSeq1, 21 = iCode1
-            #   col 29 = chainID2, 31-34 = resSeq2, 35 = iCode2
-            try:
-                chain1 = line[15:16]
-                res1 = int(line[17:21].strip())
-                i_code1 = line[21:22].strip()
-                chain2 = line[29:30]
-                res2 = int(line[31:35].strip())
-                i_code2 = line[35:36].strip()
-            except ValueError:
-                continue
-            out.ssbonds.append(
-                Ssbond(
-                    chain1=chain1,
-                    res1=res1,
-                    i_code1=i_code1,
-                    chain2=chain2,
-                    res2=res2,
-                    i_code2=i_code2,
-                )
-            )
         elif tag in ("ATOM", "HETATM"):
             if not in_first_model:
                 continue
@@ -338,7 +304,7 @@ def role_of_chain(
 
 
 # ---------------------------------------------------------------------------
-# Section 3: defensive checks (R21 SSBOND cross-check, R33 hallmark tetrad)
+# Section 3: R33 hallmark tetrad defensive check
 # ---------------------------------------------------------------------------
 
 
@@ -375,81 +341,6 @@ def _match_score(observed_one_letter: list[Optional[str]], canonical: tuple) ->
     return score
 
 
-def _norm_icode(s: Optional[str]) -> str:
-    """Normalize iCode for comparison. Both the empty-string convention (PDB
-    SSBOND records) and the `"-"` sentinel (cysteines.py emits this so PColumn
-    String axes accept the value) collapse to empty-string here so the two
-    sides of the cross-check actually meet."""
-    if not s:
-        return ""
-    t = s.strip()
-    if t in ("", "-"):
-        return ""
-    return t
-
-
-def _pair_key(chain_a, res_a, icode_a, chain_b, res_b, icode_b):
-    """Order-independent key for a Cys pair (sorted by chain+resSeq)."""
-    a = (chain_a, res_a, _norm_icode(icode_a))
-    b = (chain_b, res_b, _norm_icode(icode_b))
-    return tuple(sorted([a, b]))
-
-
-def cross_check_ssbonds(ssbonds, cys_hits) -> dict:
-    """Compare PDB SSBOND records with geometry-detected disulfide bonds.
-
-    Returns a dict suitable for JSON emission:
-      {
-        "headerBondCount": int,
-        "geometryBondCount": int,
-        "matched": int,
-        "headerOnly": [...],     # SSBOND declared, geometry rejected
-        "geometryOnly": [...],   # geometry found, no SSBOND
-      }
-    """
-    header_pairs: set = set()
-    for s in ssbonds:
-        header_pairs.add(
-            _pair_key(s.chain1, s.res1, s.i_code1, s.chain2, s.res2, s.i_code2)
-        )
-
-    # Each disulfide is represented twice in cys_hits (once per partner). De-dup.
-    geom_pairs: set = set()
-    for h in cys_hits:
-        if h.cysClass not in ("disulfide", "disulfide_broken"):
-            continue
-        if h.partnerChainId is None or h.partnerResSeq is None:
-            continue
-        if h.cysClass == "disulfide_broken":
-            # geometry rejected this; it stays under headerOnly, not geometryOnly.
-            continue
-        geom_pairs.add(
-            _pair_key(
-                h.chainId, h.resSeq, h.iCode,
-                h.partnerChainId, h.partnerResSeq, h.partnerIcode,
-            )
-        )
-
-    matched = header_pairs & geom_pairs
-    header_only = header_pairs - geom_pairs
-    geometry_only = geom_pairs - header_pairs
-
-    def _fmt(pair):
-        a, b = pair
-        return {
-            "chain1": a[0], "resSeq1": a[1], "iCode1": a[2] or "",
-            "chain2": b[0], "resSeq2": b[1], "iCode2": b[2] or "",
-        }
-
-    return {
-        "headerBondCount": len(header_pairs),
-        "geometryBondCount": len(geom_pairs),
-        "matched": len(matched),
-        "headerOnly": [_fmt(p) for p in sorted(header_only)],
-        "geometryOnly": [_fmt(p) for p in sorted(geometry_only)],
-    }
-
-
 def check_hallmark_tetrad(
     parsed,
     numbering_scheme: Optional[str],

software/tests/test_scoring.py

@@ -36,22 +36,7 @@ def _motif(
 
 
 def _cys(cys_class="cys_extra", sidechain_rsasa=0.5) -> CysteineHit:
-    return CysteineHit(
-        chainId="H",
-        resSeq=100,
-        iCode="",
-        resName="CYS",
-        chainRole="H",
-        cysClass=cys_class,
-        bondingState="unbonded",
-        sasa=80.0,
-        rsasa=0.5,
-        sidechainSasa=40.0,
-        sidechainRsasa=sidechain_rsasa,
-        partnerChainId="",
-        partnerResSeq=None,
-        partnerIcode="",
-    )
+    return CysteineHit(cysClass=cys_class, sidechainRsasa=sidechain_rsasa)
 
 
 class TestComputeFlagsFv: