fix: Precomputed carbon substituent bond/charge scopes in _carbon_substituent_tokens.

Added shared stereo_descriptors.py for R/S, E/Z, cis/trans token sets.
Replaced local hardcoded stereo sets with the shared constants.
Narrowed renderer-stereo priority so it only wins for stereo tokens and compact stereo locant tokens.
Removed redundant set copies in _bond_stereo_tokens.
Made test_absolute_stereo_tokens_bind_to_stereocenter_atoms order-independent.

Author: r-fedorov

src/bluenamer/name_assembly.py

@@ -9,6 +9,7 @@
 from .assembly_parts import AssemblyParts, NameAtomBinding, NameTokenBinding
 from .molecule import Molecule
 from .name_bindings import ensure_name_atom_binding_tokens, postprocess_name_atom_bindings
+from .stereo_descriptors import is_searchable_stereo_token
 
 
 @dataclass(frozen=True)
@@ -1051,7 +1052,7 @@ def _native_token_is_searchable(token: str, token_binding: NameTokenBinding | No
     if not token:
         return False
     if token_binding is not None and token_binding.token_kind == "stereo":
-        return token in {"r", "s", "e", "z", "cis", "trans"}
+        return is_searchable_stereo_token(token)
     return len(token) >= 2 or token.isdigit() or "," in token or token in _ELEMENT_LOCANT_TOKENS
 
 
@@ -1720,7 +1721,7 @@ def _token_span_from_native_binding_group(
         for binding_idx, token_binding in matches
         if token_binding.source == "renderer_stereo"
     ]
-    if stereo_matches:
+    if stereo_matches and _should_prioritize_renderer_stereo(text, stereo_matches):
         matches = stereo_matches
     atoms: set[int] = set()
     bonds: set[int] = set()
@@ -1765,6 +1766,18 @@ def _token_span_from_native_binding_group(
     )
 
 
+def _should_prioritize_renderer_stereo(text: str, matches: list[tuple[int, NameTokenBinding]]) -> bool:
+    """Return whether a span is owned by an explicit stereo-renderer token."""
+
+    token_text = text.lower()
+    for _binding_idx, token_binding in matches:
+        if token_binding.token_kind == "stereo" and is_searchable_stereo_token(token_text):
+            return True
+        if token_binding.token_kind == "locant" and token_binding.grammar_role in {"absolute_stereo", "bond_stereo"}:
+            return True
+    return False
+
+
 def _collapse_metadata(values: list[str], *, default: str) -> str:
     values = [value for value in values if value]
     if not values:

src/bluenamer/name_bindings.py

@@ -7,6 +7,7 @@
 from .nomenclature import RULES
 from .principal_suffixes import render_principal_suffix
 from .rules import bonds, stems
+from .stereo_descriptors import ABSOLUTE_STEREO_DESCRIPTORS, BOND_STEREO_DESCRIPTORS
 
 
 def refresh_name_atom_bindings(parts: AssemblyParts) -> list[NameAtomBinding]:
@@ -43,7 +44,7 @@ def refresh_name_atom_bindings(parts: AssemblyParts) -> list[NameAtomBinding]:
             )
         )
     for locant, descriptor in parts.stereo_features:
-        if descriptor not in {"R", "S"} or not locant:
+        if descriptor not in ABSOLUTE_STEREO_DESCRIPTORS or not locant:
             continue
         atom_idx = parts.parent_atom_ids_by_locant.get(str(locant))
         if atom_idx is None:
@@ -59,7 +60,7 @@ def refresh_name_atom_bindings(parts: AssemblyParts) -> list[NameAtomBinding]:
             )
         )
     for locant, descriptor in parts.stereo_features:
-        if descriptor not in {"E", "Z"} or not locant:
+        if descriptor not in BOND_STEREO_DESCRIPTORS or not locant:
             continue
         _bond_locants, atom_ids, bond_ids = _bond_stereo_graph_scope(parts, str(locant))
         if not atom_ids:
@@ -69,10 +70,10 @@ def refresh_name_atom_bindings(parts: AssemblyParts) -> list[NameAtomBinding]:
                 stage="assembly",
                 role="bond_stereo",
                 term=descriptor,
-                atom_ids=set(atom_ids),
-                bond_ids=set(bond_ids),
+                atom_ids=atom_ids,
+                bond_ids=bond_ids,
                 locants=(str(locant),),
-                emitted_tokens=_bond_stereo_tokens(str(locant), descriptor, set(atom_ids), set(bond_ids)),
+                emitted_tokens=_bond_stereo_tokens(str(locant), descriptor, atom_ids, bond_ids),
             )
         )
     bindings.extend(preserved_assembly_stereo)
@@ -540,8 +541,8 @@ def _bond_stereo_tokens(
             source="renderer_stereo",
             grammar_role="bond_stereo",
             binding_key="assembly:bond_stereo",
-            atom_ids=set(atom_ids),
-            bond_ids=set(bond_ids),
+            atom_ids=atom_ids,
+            bond_ids=bond_ids,
             locants=(locant,),
         ),
         NameTokenBinding(
@@ -552,8 +553,8 @@ def _bond_stereo_tokens(
             source="renderer_stereo",
             grammar_role="bond_stereo",
             binding_key="assembly:bond_stereo",
-            atom_ids=set(atom_ids),
-            bond_ids=set(bond_ids),
+            atom_ids=atom_ids,
+            bond_ids=bond_ids,
             locants=(locant,),
         ),
     )

src/bluenamer/stereo_descriptors.py

@@ -0,0 +1,20 @@
+"""Shared stereochemical descriptor tokens used by renderers and metadata."""
+
+ABSOLUTE_STEREO_DESCRIPTORS = frozenset({"R", "S"})
+BOND_STEREO_DESCRIPTORS = frozenset({"E", "Z"})
+RELATIVE_STEREO_DESCRIPTORS = frozenset({"cis", "trans"})
+
+SEARCHABLE_STEREO_TOKENS = frozenset(
+    descriptor.lower()
+    for descriptor in (
+        *ABSOLUTE_STEREO_DESCRIPTORS,
+        *BOND_STEREO_DESCRIPTORS,
+        *RELATIVE_STEREO_DESCRIPTORS,
+    )
+)
+
+
+def is_searchable_stereo_token(text: str) -> bool:
+    """Return whether a renderer-emitted stereo token may be matched directly."""
+
+    return text.lower() in SEARCHABLE_STEREO_TOKENS

src/bluenamer/substituent_tokens.py

@@ -6,6 +6,7 @@
 from .assembly_parts import NameTokenBinding
 from .formatting import strip_outer_parentheses
 from .molecule import Molecule
+from .stereo_descriptors import ABSOLUTE_STEREO_DESCRIPTORS, RELATIVE_STEREO_DESCRIPTORS
 from .trace_helpers import bond_ids_within
 
 BranchNamer = Callable[..., str]
@@ -36,9 +37,12 @@ def _carbon_substituent_tokens(mol: Molecule, atom_ids: set[int], term: str) ->
     if not term_text:
         return ()
     stereo_atoms = {idx for idx in atom_ids if mol.atoms[idx].raw_stereo and not mol.atoms[idx].stereo}
+    substituent_bond_ids = bond_ids_within(mol, atom_ids)
+    substituent_charge_atom_ids = {idx for idx in atom_ids if mol.atoms[idx].charge != 0}
+    stereo_bond_ids = bond_ids_within(mol, stereo_atoms) if len(stereo_atoms) >= 2 else set()
     tokens = []
     for token_text in _lexical_tokens(term_text):
-        if token_text.lower() in {"cis", "trans"} and len(stereo_atoms) >= 2:
+        if token_text.lower() in RELATIVE_STEREO_DESCRIPTORS and len(stereo_atoms) >= 2:
             tokens.append(
                 NameTokenBinding(
                     text=token_text,
@@ -49,7 +53,7 @@ def _carbon_substituent_tokens(mol: Molecule, atom_ids: set[int], term: str) ->
                     grammar_role="relative_stereo",
                     binding_key="prefix:relative_stereo",
                     atom_ids=set(stereo_atoms),
-                    bond_ids=bond_ids_within(mol, stereo_atoms),
+                    bond_ids=set(stereo_bond_ids),
                 )
             )
             continue
@@ -61,8 +65,8 @@ def _carbon_substituent_tokens(mol: Molecule, atom_ids: set[int], term: str) ->
                 grammar_role="carbon_substituent",
                 binding_key="prefix:carbon_substituent",
                 atom_ids=set(atom_ids),
-                bond_ids=bond_ids_within(mol, atom_ids),
-                charge_atom_ids={idx for idx in atom_ids if mol.atoms[idx].charge != 0},
+                bond_ids=set(substituent_bond_ids),
+                charge_atom_ids=set(substituent_charge_atom_ids),
             )
         )
     return tuple(tokens)
@@ -72,7 +76,7 @@ def _embedded_absolute_stereo_tokens(mol: Molecule, center: int, term_text: str)
     """Return graph-bound tokens for directly rendered non-parent R/S descriptors."""
 
     descriptor = mol.atoms[center].stereo
-    if descriptor not in {"R", "S"}:
+    if descriptor not in ABSOLUTE_STEREO_DESCRIPTORS:
         return ()
     if not re.search(rf"\({re.escape(descriptor)}\)-", term_text):
         return ()

src/bluenamer/tests/test_public_api.py

@@ -114,13 +114,22 @@ def test_absolute_stereo_tokens_bind_to_stereocenter_atoms():
     assembly = [step for step in result.decisions if step.decision == "assembled component name"][-1]
     token_spans = assembly.data["name_token_spans"]
 
-    assert [(token["text"], token["atoms"], token["token_kind"], token["source"]) for token in token_spans[:4]] == [
-        ("3", [4], "locant", "renderer_stereo"),
-        ("R", [4], "stereo", "renderer_stereo"),
-        ("5", [7], "locant", "renderer_stereo"),
-        ("R", [7], "stereo", "renderer_stereo"),
+    expected_tokens = [
+        ("3", 4, "locant", "renderer_stereo"),
+        ("R", 4, "stereo", "renderer_stereo"),
+        ("5", 7, "locant", "renderer_stereo"),
+        ("R", 7, "stereo", "renderer_stereo"),
     ]
-    assert all(token["confidence"] != "fallback" for token in token_spans[:4])
+    for text, atom, token_kind, source in expected_tokens:
+        token = next(
+            token
+            for token in token_spans
+            if token["text"] == text
+            and token["atoms"] == [atom]
+            and token["token_kind"] == token_kind
+            and token["source"] == source
+        )
+        assert token["confidence"] != "fallback"
 
 
 def test_naming_errors_become_result_error_not_exception():