Gate retained fused parents on ambiguity, not on a substituent allow-list

A retained fused parent was abandoned whenever the molecule carried any
substituent outside a curated list of 26 names.  `pentyl` was on it and
`hexyl` was not, so 2-pentyl-7H-purine named itself and its hexyl homologue
fell back to 3-hexyl-2,4,7,9-tetraazabicyclo[4.3.0]nona-1,3,5,8-tetraene.
The list gated the wrong thing: a substituent is named by its own recursive
call, so what it is cannot affect whether the parent's locants are right.
It was a rollout throttle standing in for a hazard nobody had named.

The hazard is real but different.  A lactam like 4-oxoquinoline-3-carboxamide
saturates two ring positions beyond what quinoline supports, and which two
cannot be recovered from the name -- OPSIN puts the hydrogen on C3 and reads
a different molecule.  Those positions have to be cited as
4-oxo-1,4-dihydroquinoline-3-carboxamide, and only parents wired into the
indicated-hydrogen machinery can do it.

So gate on that instead: count the parent's saturated positions, and keep the
retained name only when they fit its indicated hydrogen or it can spell the
rest out.  Anything else keeps the von Baeyer name, which states its
saturation positionally and stays unambiguous.

Measured on 200k molecules, every name this changes was checked against OPSIN
independently of the self-audit: 519 changed, 518 resolve back to their input,
and the one that does not is a garbled spiro name whose previous form was
equally unparseable -- the known spiro renderer gap, untouched here.
Refutations stay at 27; without the ambiguity guard this same change
introduced 29 wrong names.

zinc22 is unchanged at 97.63%.  pubchem drops 96.33% -> 96.21%: 119 names
stop being confirmed, every one because the audit models neither added
hydrogen (70) nor more than one indicated hydrogen (42), not because any
name got worse.  Teaching the audit those two constructs is the next step,
and would also recover the ~200 lactams the new guard still holds back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: AdrianM0

src/openclatura/retained_fused_production.py

@@ -14,14 +14,14 @@
 from .assembly_parts import RetainedParentMetadata, SubstituentItem
 from .grammar_snapshot_data import retained_fused_derivative_gate
 from .molecule import Molecule
+from .namer_config import INDICATED_H_RETAINED_NAMES
 from .perception import PerceivedGroup
 from .retained_fused_templates import RetainedFusedTemplateMatch, match_retained_fused_templates
 
 _DERIVATIVE_GATE = retained_fused_derivative_gate()
 PRODUCTION_RETAINED_FUSED_PARENTS = _DERIVATIVE_GATE.production_parent_names
 ALLOWED_PRINCIPAL_KEYS = _DERIVATIVE_GATE.allowed_principal_keys
 ALLOWED_GROUP_KEYS = _DERIVATIVE_GATE.allowed_group_keys
-ALLOWED_SUBSTITUENT_NAMES = _DERIVATIVE_GATE.allowed_substituent_names
 
 
 @dataclass(frozen=True)
@@ -85,6 +85,8 @@ def production_retained_fused_parent(
     if not maps:
         return None
     template = matches[0].template
+    if not _added_hydrogen_is_citable(mol, parent_atoms, template):
+        return None
     return ProductionRetainedFusedParent(
         name=parent_name,
         locant_maps=maps,
@@ -97,6 +99,32 @@ def production_retained_fused_parent(
     )
 
 
+def _added_hydrogen_is_citable(mol: Molecule, parent_atoms: set[int], template) -> bool:
+    """Whether every saturated position of the parent can be spelt out.
+
+    A lactam such as 4-oxoquinoline-3-carboxamide saturates two ring positions
+    beyond what quinoline supports, and which two cannot be recovered from the
+    name -- OPSIN puts the hydrogen on C3 and reads a different molecule.  They
+    have to be cited, ``4-oxo-1,4-dihydroquinoline-3-carboxamide``, and only
+    parents wired into the indicated-hydrogen machinery can do that.  A parent
+    needing an uncitable added hydrogen falls back to von Baeyer, which states
+    its saturation positionally and so stays unambiguous.
+    """
+
+    saturated = 0
+    for atom in parent_atoms:
+        ring_bonds = [
+            bond
+            for neighbor in mol.get_neighbors(atom)
+            if neighbor in parent_atoms and (bond := mol.get_bond(atom, neighbor)) is not None
+        ]
+        if ring_bonds and sum(bond.order for bond in ring_bonds) == len(ring_bonds):
+            saturated += 1
+    if saturated <= _indicated_hydrogen_count(template):
+        return True
+    return template.name in INDICATED_H_RETAINED_NAMES
+
+
 def _indicated_hydrogen_count(template) -> int:
     """How many indicated hydrogens this mancude parent hydride supports.
 
@@ -167,30 +195,15 @@ def _allowed_groups(parent_atoms: set[int], perceived_groups: list[PerceivedGrou
     return True
 
 
-def _base_substituent_name(name: str) -> str:
-    """Strip enclosing marks so the gate can list bare substituent names.
+def _allowed_substituents(substituent_mapping: dict[int, list[SubstituentItem]]) -> bool:
+    """Whether the substituents on a retained parent are ones we can render.
 
-    A complex substituent carries context-dependent enclosing marks in its
-    rendered ``name`` (e.g. ``(propan-2-yl)`` on one parent, ``propan-2-yl``
-    on another).  Comparing the bare base name keeps the allow-list stable
-    across attachment contexts.
+    A substituent is named by its own recursive call, so what it *is* cannot
+    affect whether the parent's locants are right; only a spiro junction, which
+    the retained renderer cannot compose, disqualifies the parent here.
     """
 
-    name = name.strip()
-    closing = {"(": ")", "[": "]", "{": "}"}
-    while len(name) >= 2 and name[0] in closing and name[-1] == closing[name[0]]:
-        name = name[1:-1].strip()
-    return name
-
-
-def _allowed_substituents(substituent_mapping: dict[int, list[SubstituentItem]]) -> bool:
-    for items in substituent_mapping.values():
-        for item in items:
-            if item.spiro is not None:
-                return False
-            if _base_substituent_name(item.name) not in ALLOWED_SUBSTITUENT_NAMES:
-                return False
-    return True
+    return all(item.spiro is None for items in substituent_mapping.values() for item in items)
 
 
 def _feature_locants_are_substitutable(atom_to_locant: dict[int, str], feature_atoms: set[int]) -> bool:

src/openclatura/tests/test_rules_tables.py

@@ -116,3 +116,27 @@ def test_retained_fused_audit_templates_match_their_graph_templates():
             frozenset((labels[bond.GetBeginAtomIdx()], labels[bond.GetEndAtomIdx()])) for bond in frag.GetBonds()
         }
         assert actual_bonds == expected_bonds, f"{name}: bonds differ"
+
+
+def test_retained_parent_survives_an_arbitrary_substituent():
+    """A substituent is named by its own recursive call, so what it is cannot
+    affect whether the parent's locants are right.  A curated allow-list used to
+    decide this, and anything off it dropped the retained parent entirely."""
+
+    from openclatura import name_smiles
+
+    for substituent in ("C" * 5, "C" * 6, "C" * 12, "CC(C)CC"):
+        name = name_smiles(substituent + "c1ncc2[nH]cnc2n1")
+        assert name.endswith("-7H-purine"), name
+    assert name_smiles("c1ccc(-c2ncc3[nH]cnc3n2)cc1") == "2-phenyl-7H-purine"
+
+
+def test_uncitable_added_hydrogen_keeps_the_von_baeyer_parent():
+    """4-oxoquinoline-3-carboxamide reads as a different molecule -- the two
+    saturated positions have to be cited, and quinoline cannot cite them yet."""
+
+    from openclatura import name_smiles
+
+    name = name_smiles("N#CC[C@H](O)CNC(=O)c1c[nH]c2ccccc2c1=O")
+    assert "quinoline" not in name
+    assert "bicyclo[4.4.0]" in name