synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Morphism/stereo_morphism_types.py

@@ -0,0 +1,117 @@
+"""Public value types used by stereo-aware graph morphisms."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Mapping
+
+from synkit.Graph.Stereo.orbits import (
+    PermutationWitness,
+    StereoConfiguration,
+    StereoRelation,
+)
+
+
+class StereoInformationPolicy(str, Enum):
+    """How declared orientation information constrains a target descriptor."""
+
+    EXACT = "exact"
+    WILDCARD = "wildcard"
+    EITHER = "either"
+
+
+class StereoPresenceMode(str, Enum):
+    """How source, target, and absent descriptors participate in a match."""
+
+    REQUIRE = "require"
+    STRICT = "strict"
+    IGNORE = "ignore"
+    PROPAGATE = "propagate"
+
+
+class StereoCertificateStatus(str, Enum):
+    MATCHED = "matched"
+    IGNORED = "ignored"
+    PROPAGATE = "propagate"
+
+
+class StereoMorphismIssueCode(str, Enum):
+    GRAPH_NODE_MISMATCH = "STEREO_MORPHISM_GRAPH_NODE_MISMATCH"
+    INVALID_REFERENCE = "STEREO_MORPHISM_INVALID_REFERENCE"
+    MISSING_DESCRIPTOR = "STEREO_MORPHISM_MISSING_DESCRIPTOR"
+    EXTRA_DESCRIPTOR = "STEREO_MORPHISM_EXTRA_DESCRIPTOR"
+    INVALID_CERTIFICATE = "STEREO_MORPHISM_INVALID_CERTIFICATE"
+    POLICY_MISMATCH = "STEREO_MORPHISM_POLICY_MISMATCH"
+    INTERMEDIATE_MISMATCH = "STEREO_MORPHISM_INTERMEDIATE_MISMATCH"
+    WITNESS_MISMATCH = "STEREO_MORPHISM_WITNESS_MISMATCH"
+    PORT_ROLE_MISMATCH = "STEREO_MORPHISM_PORT_ROLE_MISMATCH"
+    PORT_SOURCE_NOT_WILDCARD = "STEREO_MORPHISM_PORT_SOURCE_NOT_WILDCARD"
+    PORT_BINDING_MISSING = "STEREO_MORPHISM_PORT_BINDING_MISSING"
+    PORT_BINDING_AMBIGUOUS = "STEREO_MORPHISM_PORT_BINDING_AMBIGUOUS"
+    PORT_OWNER_MISMATCH = "STEREO_MORPHISM_PORT_OWNER_MISMATCH"
+    PORT_INCIDENCE_MISMATCH = "STEREO_MORPHISM_PORT_INCIDENCE_MISMATCH"
+    PORT_SLOT_MISMATCH = "STEREO_MORPHISM_PORT_SLOT_MISMATCH"
+    PORT_DOMAIN_MISMATCH = "STEREO_MORPHISM_PORT_DOMAIN_MISMATCH"
+    PORT_VIRTUAL_KIND_MISMATCH = "STEREO_MORPHISM_PORT_VIRTUAL_KIND_MISMATCH"
+    PORT_CAPACITY_MISMATCH = "STEREO_MORPHISM_PORT_CAPACITY_MISMATCH"
+
+
+@dataclass(frozen=True)
+class StereoMorphismIssue:
+    code: StereoMorphismIssueCode
+    message: str
+    context: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "code": self.code.value,
+            "message": self.message,
+            "context": dict(self.context),
+        }
+
+
+class StereoMorphismError(ValueError):
+    """Raised when stereo evidence cannot refine a graph morphism."""
+
+    def __init__(self, *issues: StereoMorphismIssue):
+        self.issues = tuple(issues)
+        super().__init__("; ".join(issue.message for issue in issues))
+
+
+@dataclass(frozen=True)
+class LocalStereoCertificate:
+    """One endpoint-local descriptor proof within a stereo morphism."""
+
+    layer: str
+    source_configuration: StereoConfiguration
+    target_configuration: StereoConfiguration | None
+    relation: StereoRelation | None
+    witness: PermutationWitness | None
+    status: StereoCertificateStatus
+    information_policy: StereoInformationPolicy
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.status, StereoCertificateStatus):
+            object.__setattr__(self, "status", StereoCertificateStatus(self.status))
+        if not isinstance(self.information_policy, StereoInformationPolicy):
+            object.__setattr__(
+                self,
+                "information_policy",
+                StereoInformationPolicy(self.information_policy),
+            )
+        matched = self.status is StereoCertificateStatus.MATCHED
+        evidence = (self.target_configuration, self.relation, self.witness)
+        invalid = (
+            any(value is None for value in evidence)
+            if matched
+            else any(value is not None for value in evidence)
+        )
+        if invalid:
+            raise StereoMorphismError(
+                StereoMorphismIssue(
+                    StereoMorphismIssueCode.INVALID_CERTIFICATE,
+                    "Matched certificates require target, relation, and witness; "
+                    "non-matched certificates forbid them.",
+                )
+            )

synkit/Graph/Stereo/__init__.py

@@ -0,0 +1,376 @@
+from .changes import (
+    NonInvertibleStereoEffectError,
+    StereoAlignmentError,
+    StereoChange,
+    StereoReferenceAlignment,
+    align_stereo_references,
+    annotate_its_stereo,
+    classify_stereo_change,
+    compare_stereo_registries,
+    stereo_complete_reaction_center_nodes,
+    stereo_registry,
+)
+from .descriptors import (
+    AtropAxisStereo,
+    AtropBondStereo,
+    CONFIGURED_STEREO_DESCRIPTOR_CLASSES,
+    CumuleneAxisStereo,
+    DEFERRED_STEREO_DESCRIPTOR_CLASSES,
+    ExtendedCisTransStereo,
+    OctahedralStereo,
+    PlanarBondStereo,
+    RDKIT_STEREO_DESCRIPTOR_CLASSES,
+    SquarePlanarStereo,
+    SUPPORTED_STEREO_DESCRIPTOR_CLASSES,
+    StereoValue,
+    TetrahedralStereo,
+    TrigonalBipyramidalStereo,
+    VirtualReferenceKind,
+    VirtualStereoReference,
+    descriptor_id,
+    parse_virtual_reference,
+    stereo_from_dict,
+    virtual_reference,
+)
+from .interchange import (
+    StereoInterchangeError,
+    StereoInterchangeIssue,
+    StereoInterchangeReport,
+    VirtualReferenceSidecar,
+    stereomolgraph_descriptor_to_synkit,
+    stereomolgraph_registry_to_synkit,
+    synkit_descriptor_to_stereomolgraph,
+)
+from .reaction_interchange import (
+    REACTION_STEREO_DIGEST_KEY,
+    REACTION_STEREO_INTERCHANGE_SCHEMA,
+    REACTION_STEREO_SIDECAR_KEY,
+    SUPPORTED_REACTION_STEREO_FORMATS,
+    ReactionStereoInterchangeError,
+    ReactionStereoInterchangeIssue,
+    ReactionStereoInterchangeReport,
+    project_reaction_stereo,
+    reaction_stereo_from_gml,
+    reaction_stereo_from_graph,
+    reaction_stereo_interchange_schema,
+)
+from .identity import (
+    StereoIdentityError,
+    descriptor_relative_form,
+    mapped_reference_resolver,
+    mapped_stereo_registries_match,
+    mapped_stereo_subgraph_registries_match,
+    stereo_identity_form,
+    stereo_identity_signature,
+    stereo_registry_layers,
+    structural_node_colours,
+)
+from .extended_descriptors import (
+    HelicalStereo,
+    HelicalStereoSidecar,
+    PlanarChiralityStereo,
+)
+from .global_stereo import (
+    FrameworkFrame,
+    FrameworkStereo,
+    GlobalStereoCertificate,
+    GlobalStereoInformationState,
+)
+from .rdkit_adapter import apply_stereo_to_rdkit, descriptors_from_rdkit
+from .matching import (
+    candidate_mapping_stereo_matches,
+    candidate_mapping_stereo_morphism,
+    descriptor_graph_support_errors,
+    descriptor_query_matches,
+    normalize_hydrogen_references,
+    propagate_unaffected_stereo,
+    stereo_isomorphic,
+    stereo_isomorphism_mapping,
+    stereo_isomorphism_mappings,
+    stereo_isomorphism_morphisms,
+)
+from .outcomes import StereoOutcome
+from .couplings import StereoCoupling
+from .semantics import (
+    StereoDeterminacy,
+    StereoEvidenceKind,
+    StereoLifecycle,
+    StereoPopulation,
+    StereoReactionDecision,
+    StereoReactionSemantics,
+    StereoRefusal,
+    StereoRefusalCode,
+)
+from .wire import (
+    LEGACY_REACTION_STEREO_SCHEMA,
+    REACTION_STEREO_SCHEMA,
+    SUPPORTED_REACTION_STEREO_SCHEMAS,
+    ReactionStereoSchemaError,
+    StereoReactionValue,
+    reaction_stereo_schema,
+)
+from .composition import (
+    StereoBranchContribution,
+    StereoComposedBranch,
+    StereoCompositionError,
+    StereoCompositionIssueCode,
+    StereoReactionComposition,
+    compose_reaction_stereo,
+    reverse_reaction_stereo,
+)
+from .legacy import (
+    StereoSemanticComparison,
+    StereoSemanticsMode,
+    summarize_stereo_comparisons,
+)
+from .orbits import (
+    Permutation,
+    PermutationGroup,
+    PermutationWitness,
+    SHAPE_DEFINITIONS,
+    ShapeDefinition,
+    StereoConfiguration,
+    StereoRelation,
+    StereoRelationKind,
+    StereoSpecification,
+)
+from .supports import (
+    AtomCenteredStereo,
+    AtomStereoSupport,
+    AxisStereo,
+    AxisStereoSupport,
+    BondCenteredStereo,
+    BondStereoSupport,
+    GlobalStereo,
+    GlobalStereoSupport,
+    PathStereo,
+    PathStereoSupport,
+    PlaneStereo,
+    PlaneStereoSupport,
+    StereoDescriptor,
+    StereoSupport,
+)
+from .canonical import (
+    CanonicalStereographResult,
+    STEREOGRAPH_SCHEMA,
+    StereographMirrorResult,
+    StereographMirrorStatus,
+    classify_rdkit_stereograph_mirror,
+    classify_stereograph_mirror,
+    canonicalize_rdkit_stereograph,
+    canonicalize_rdkit_tetrahedral_stereograph,
+    canonicalize_stereo_registry,
+    canonicalize_stereograph,
+    canonicalize_tetrahedral_registry,
+    canonicalize_tetrahedral_stereograph,
+    expand_stereograph,
+    expand_tetrahedral_stereograph,
+    mirror_stereo_descriptor,
+    mirror_stereo_registry,
+)
+from .configured import (
+    CONFIGURED_STEREOGRAPH_SCHEMA,
+    MirrorIdentityProfile,
+    canonicalize_configured_registry,
+    canonicalize_configured_stereograph,
+    canonicalize_rdkit_configured_stereograph,
+    classify_configured_stereograph_mirror,
+    classify_rdkit_configured_stereograph_mirror,
+    expand_configured_stereograph,
+    mirror_configured_descriptor,
+)
+from .pairwise import (
+    STEREOISOMER_RELATION_SCHEMA,
+    StereoisomerRelation,
+    StereoisomerRelationResult,
+    classify_rdkit_stereoisomer_relation,
+    classify_stereoisomer_relation,
+)
+from .rdkit_identity import (
+    RDKIT_IDENTITY_SCHEMA,
+    RESONANCE_FAMILY_SCHEMA,
+    ResonanceFamilyCanonicalResult,
+)
+from .enumeration import (
+    FOCAL_STEREOGRAPH_SCHEMA,
+    STEREO_ENUMERATION_SCHEMA,
+    FocalStereoEvidence,
+    StereoAssignment,
+    StereoEnumerationLimitError,
+    StereoEnumerationResult,
+    enumerate_rdkit_stereographs,
+    enumerate_stereograph_assignments,
+    focal_stereo_evidence,
+    local_configuration_classes,
+)
+
+__all__ = [
+    "TetrahedralStereo",
+    "SquarePlanarStereo",
+    "TrigonalBipyramidalStereo",
+    "OctahedralStereo",
+    "PlanarBondStereo",
+    "AtropBondStereo",
+    "AtropAxisStereo",
+    "CumuleneAxisStereo",
+    "ExtendedCisTransStereo",
+    "HelicalStereo",
+    "HelicalStereoSidecar",
+    "PlanarChiralityStereo",
+    "FrameworkFrame",
+    "FrameworkStereo",
+    "GlobalStereoCertificate",
+    "GlobalStereoInformationState",
+    "StereoValue",
+    "VirtualReferenceKind",
+    "VirtualStereoReference",
+    "SUPPORTED_STEREO_DESCRIPTOR_CLASSES",
+    "CONFIGURED_STEREO_DESCRIPTOR_CLASSES",
+    "RDKIT_STEREO_DESCRIPTOR_CLASSES",
+    "DEFERRED_STEREO_DESCRIPTOR_CLASSES",
+    "descriptor_id",
+    "virtual_reference",
+    "parse_virtual_reference",
+    "stereo_from_dict",
+    "StereoInterchangeError",
+    "StereoInterchangeIssue",
+    "StereoInterchangeReport",
+    "VirtualReferenceSidecar",
+    "synkit_descriptor_to_stereomolgraph",
+    "stereomolgraph_descriptor_to_synkit",
+    "stereomolgraph_registry_to_synkit",
+    "REACTION_STEREO_DIGEST_KEY",
+    "REACTION_STEREO_INTERCHANGE_SCHEMA",
+    "REACTION_STEREO_SIDECAR_KEY",
+    "SUPPORTED_REACTION_STEREO_FORMATS",
+    "ReactionStereoInterchangeError",
+    "ReactionStereoInterchangeIssue",
+    "ReactionStereoInterchangeReport",
+    "project_reaction_stereo",
+    "reaction_stereo_from_gml",
+    "reaction_stereo_from_graph",
+    "reaction_stereo_interchange_schema",
+    "StereoIdentityError",
+    "descriptor_relative_form",
+    "mapped_reference_resolver",
+    "mapped_stereo_registries_match",
+    "mapped_stereo_subgraph_registries_match",
+    "stereo_identity_form",
+    "stereo_identity_signature",
+    "stereo_registry_layers",
+    "structural_node_colours",
+    "descriptors_from_rdkit",
+    "apply_stereo_to_rdkit",
+    "StereoChange",
+    "StereoReferenceAlignment",
+    "StereoAlignmentError",
+    "NonInvertibleStereoEffectError",
+    "align_stereo_references",
+    "classify_stereo_change",
+    "stereo_registry",
+    "compare_stereo_registries",
+    "annotate_its_stereo",
+    "stereo_complete_reaction_center_nodes",
+    "candidate_mapping_stereo_matches",
+    "candidate_mapping_stereo_morphism",
+    "descriptor_graph_support_errors",
+    "descriptor_query_matches",
+    "normalize_hydrogen_references",
+    "propagate_unaffected_stereo",
+    "stereo_isomorphic",
+    "stereo_isomorphism_mapping",
+    "stereo_isomorphism_mappings",
+    "stereo_isomorphism_morphisms",
+    "StereoOutcome",
+    "StereoCoupling",
+    "StereoDeterminacy",
+    "StereoEvidenceKind",
+    "StereoLifecycle",
+    "StereoPopulation",
+    "StereoReactionDecision",
+    "StereoReactionSemantics",
+    "StereoRefusal",
+    "StereoRefusalCode",
+    "LEGACY_REACTION_STEREO_SCHEMA",
+    "REACTION_STEREO_SCHEMA",
+    "SUPPORTED_REACTION_STEREO_SCHEMAS",
+    "ReactionStereoSchemaError",
+    "StereoReactionValue",
+    "reaction_stereo_schema",
+    "StereoBranchContribution",
+    "StereoComposedBranch",
+    "StereoCompositionError",
+    "StereoCompositionIssueCode",
+    "StereoReactionComposition",
+    "compose_reaction_stereo",
+    "reverse_reaction_stereo",
+    "Permutation",
+    "PermutationGroup",
+    "PermutationWitness",
+    "SHAPE_DEFINITIONS",
+    "ShapeDefinition",
+    "StereoConfiguration",
+    "StereoRelation",
+    "StereoRelationKind",
+    "StereoSpecification",
+    "StereoDescriptor",
+    "AtomCenteredStereo",
+    "BondCenteredStereo",
+    "AxisStereo",
+    "PlaneStereo",
+    "PathStereo",
+    "GlobalStereo",
+    "StereoSupport",
+    "AtomStereoSupport",
+    "BondStereoSupport",
+    "AxisStereoSupport",
+    "PlaneStereoSupport",
+    "PathStereoSupport",
+    "GlobalStereoSupport",
+    "StereoSemanticComparison",
+    "StereoSemanticsMode",
+    "summarize_stereo_comparisons",
+    "CanonicalStereographResult",
+    "STEREOGRAPH_SCHEMA",
+    "StereographMirrorResult",
+    "StereographMirrorStatus",
+    "classify_rdkit_stereograph_mirror",
+    "classify_stereograph_mirror",
+    "canonicalize_rdkit_stereograph",
+    "canonicalize_rdkit_tetrahedral_stereograph",
+    "canonicalize_stereo_registry",
+    "canonicalize_stereograph",
+    "canonicalize_tetrahedral_registry",
+    "canonicalize_tetrahedral_stereograph",
+    "expand_stereograph",
+    "expand_tetrahedral_stereograph",
+    "mirror_stereo_descriptor",
+    "mirror_stereo_registry",
+    "CONFIGURED_STEREOGRAPH_SCHEMA",
+    "MirrorIdentityProfile",
+    "canonicalize_configured_registry",
+    "canonicalize_configured_stereograph",
+    "canonicalize_rdkit_configured_stereograph",
+    "classify_configured_stereograph_mirror",
+    "classify_rdkit_configured_stereograph_mirror",
+    "expand_configured_stereograph",
+    "mirror_configured_descriptor",
+    "STEREOISOMER_RELATION_SCHEMA",
+    "StereoisomerRelation",
+    "StereoisomerRelationResult",
+    "RDKIT_IDENTITY_SCHEMA",
+    "RESONANCE_FAMILY_SCHEMA",
+    "ResonanceFamilyCanonicalResult",
+    "classify_rdkit_stereoisomer_relation",
+    "classify_stereoisomer_relation",
+    "FOCAL_STEREOGRAPH_SCHEMA",
+    "STEREO_ENUMERATION_SCHEMA",
+    "FocalStereoEvidence",
+    "StereoAssignment",
+    "StereoEnumerationLimitError",
+    "StereoEnumerationResult",
+    "enumerate_rdkit_stereographs",
+    "enumerate_stereograph_assignments",
+    "focal_stereo_evidence",
+    "local_configuration_classes",
+]

synkit/Graph/Stereo/_descriptor_core.py

@@ -0,0 +1,207 @@
+"""Shared permutation-orbit mechanics for relative stereodescriptors."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any, Mapping, Sequence
+
+from .orbits import (
+    Permutation,
+    StereoConfiguration,
+    StereoRelation,
+    StereoSpecification,
+)
+from .supports import Reference
+
+
+def reference_sort_key(value: Reference) -> tuple[str, str]:
+    """Return a total ordering key across material and virtual references."""
+    return type(value).__name__, repr(value)
+
+
+def _tuple_sort_key(
+    values: Sequence[Reference],
+) -> tuple[tuple[str, str], ...]:
+    return tuple(reference_sort_key(value) for value in values)
+
+
+def permuted_canonical_form(
+    descriptor_class: str,
+    atoms: Sequence[Reference],
+    parity: int,
+    permutations: Sequence[Sequence[int]],
+    inversion: Sequence[int] | None = None,
+) -> tuple[Any, ...]:
+    """Return a canonical relative form under a descriptor symmetry group."""
+    working = tuple(atoms)
+    canonical_parity = parity
+    if parity == -1:
+        if inversion is None:
+            raise ValueError(f"{descriptor_class} does not define an inverse.")
+        working = tuple(working[index] for index in inversion)
+        canonical_parity = 1
+    forms = tuple(
+        tuple(working[index] for index in permutation) for permutation in permutations
+    )
+    return (
+        descriptor_class,
+        canonical_parity,
+        min(forms, key=_tuple_sort_key),
+    )
+
+
+def unknown_atom_form(
+    descriptor_class: str,
+    atoms: Sequence[Reference],
+) -> tuple[Any, ...]:
+    """Keep an unknown orientation attached to its atom locus and ligands."""
+    return (
+        descriptor_class,
+        atoms[0],
+        tuple(sorted(atoms[1:], key=reference_sort_key)),
+        None,
+    )
+
+
+def unknown_bond_form(
+    descriptor_class: str,
+    atoms: Sequence[Reference],
+) -> tuple[Any, ...]:
+    """Keep an unknown orientation attached to its bond and endpoint groups."""
+    left = (atoms[2], tuple(sorted(atoms[:2], key=reference_sort_key)))
+    right = (atoms[3], tuple(sorted(atoms[4:], key=reference_sort_key)))
+    return (
+        descriptor_class,
+        None,
+        tuple(sorted((left, right), key=repr)),
+    )
+
+
+def descriptor_dict(descriptor: Any) -> dict[str, Any]:
+    """Serialize the common descriptor wire fields."""
+    return {
+        "descriptor_class": descriptor.descriptor_class,
+        "atoms": list(descriptor.atoms),
+        "parity": descriptor.parity,
+        "provenance": descriptor.provenance,
+    }
+
+
+def permutation_sign(
+    values: Sequence[Reference],
+    ordered: Sequence[Reference],
+) -> int:
+    """Return the parity of ``values`` relative to ``ordered``."""
+    positions = {value: index for index, value in enumerate(ordered)}
+    permutation = [positions[value] for value in values]
+    inversions = sum(
+        permutation[i] > permutation[j]
+        for i in range(len(permutation))
+        for j in range(i + 1, len(permutation))
+    )
+    return -1 if inversions % 2 else 1
+
+
+_NEGATIVE_ORBIT_IMAGES = {
+    "tetrahedral": (0, 2, 1, 3, 4),
+    "trigonal_bipyramidal": (0, 1, 2, 3, 5, 4),
+    "octahedral": (0, 2, 1, 3, 4, 5, 6),
+    "atrop_bond": (1, 0, 2, 3, 4, 5),
+    "cumulene_axis": (1, 0, 2, 3, 4, 5),
+}
+
+
+class OrbitDescriptorMixin:
+    """Adapt the stable descriptor wire model to finite-orbit semantics."""
+
+    descriptor_class: str
+    atoms: tuple[Reference, ...]
+    parity: int | None
+    provenance: str | None
+
+    @property
+    def specification(self) -> StereoSpecification:
+        """Return whether orientation is fixed or intentionally unspecified."""
+        return (
+            StereoSpecification.UNSPECIFIED
+            if self.parity is None
+            else StereoSpecification.FIXED
+        )
+
+    @cached_property
+    def configuration(self) -> StereoConfiguration:
+        """Return the authoritative permutation-orbit configuration."""
+        frame = tuple(self.atoms)
+        if self.parity == -1:
+            image = _NEGATIVE_ORBIT_IMAGES[self.descriptor_class]
+            frame = Permutation(image).apply(frame)
+        return StereoConfiguration(
+            self.descriptor_class,
+            frame,
+            self.specification,
+        )
+
+    def same_configuration(
+        self,
+        other: object,
+        *,
+        semantics: str = "orbit",
+        diagnostics: list[Any] | None = None,
+    ) -> bool:
+        """Test relative stereo identity, optionally auditing Beta-2."""
+        from .legacy import (  # Independent oracle; kept lazy at this boundary.
+            StereoSemanticComparison,
+            StereoSemanticsMode,
+            legacy_same_configuration,
+        )
+
+        mode = StereoSemanticsMode(semantics)
+        if mode is StereoSemanticsMode.LEGACY:
+            return legacy_same_configuration(self, other)
+        orbit_result = (
+            type(self) is type(other)
+            and isinstance(other, OrbitDescriptorMixin)
+            and self.configuration.same_configuration(other.configuration)
+        )
+        if mode is StereoSemanticsMode.ORBIT:
+            return orbit_result
+        legacy_result = legacy_same_configuration(self, other)
+        if diagnostics is not None:
+            diagnostics.append(
+                StereoSemanticComparison.create(
+                    "descriptor_identity",
+                    orbit_result,
+                    legacy_result,
+                )
+            )
+        return orbit_result
+
+    def relation_to(self, other: object) -> StereoRelation:
+        """Classify and witness the geometric relation to another descriptor."""
+        configuration = (
+            other.configuration
+            if type(self) is type(other) and isinstance(other, OrbitDescriptorMixin)
+            else other
+        )
+        return self.configuration.relation_to(configuration)
+
+    def replace_reference(self, old: Reference, new: Reference) -> Any:
+        """Replace one peripheral reference without changing orientation."""
+        return self.replace_references({old: new})
+
+    def replace_references(
+        self,
+        replacements: Mapping[Reference, Reference],
+    ) -> Any:
+        """Replace peripheral references after formal locus validation."""
+        self.configuration.replace_references(replacements)
+        atoms = tuple(replacements.get(value, value) for value in self.atoms)
+        return type(self)(atoms, self.parity, self.provenance)
+
+    def opposite(self) -> Any:
+        """Return the binary opposite when the geometry defines one."""
+        opposite = self.configuration.opposite()
+        if self.specification is StereoSpecification.UNSPECIFIED:
+            return self
+        parity = 0 if self.descriptor_class == "planar_bond" else 1
+        return type(self)(opposite.frame, parity, self.provenance)