Update Coupling docstring and metrics for EPI invariance

Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>

Author: Copilot

src/tnfr/operators/definitions.py

@@ -1366,6 +1366,30 @@ class Coupling(Operator):
     Set ``VALIDATE_OPERATOR_PRECONDITIONS=True`` in graph metadata to enable validation.
     Validation is backward-compatible and disabled by default to preserve existing behavior.
 
+    Structural Invariants
+    ---------------------
+    **CRITICAL**: UM preserves EPI identity. The coupling process synchronizes
+    phases (θ), may align structural frequencies (νf), and can reduce ΔNFR, but
+    it NEVER directly modifies EPI. This ensures that coupled nodes maintain
+    their structural identities while achieving phase coherence.
+    
+    Any change to EPI during a sequence containing UM must come from other
+    operators (e.g., Emission, Reception) or from the natural evolution via
+    the nodal equation ∂EPI/∂t = νf · ΔNFR(t), never from UM itself.
+    
+    **Theoretical Basis**: In TNFR theory, coupling (UM) creates structural links 
+    through phase synchronization φᵢ(t) ≈ φⱼ(t), not through information transfer 
+    or EPI modification. The structural identity (EPI) of each node remains intact 
+    while the nodes achieve synchronized phases that enable resonant interaction.
+    
+    **Implementation Guarantee**: The `_op_UM` function modifies only:
+    
+    - Phase (θ): Adjusted towards consensus phase
+    - Structural frequency (νf): Optionally synchronized with neighbors
+    - Reorganization gradient (ΔNFR): Reduced through stabilization
+    
+    EPI is never touched by the coupling logic, preserving this fundamental invariant.
+
     Structural Effects
     ------------------
     - **θ**: Phases of coupled nodes converge (primary effect)
@@ -1476,6 +1500,7 @@ def _collect_metrics(
             dnfr_before=state_before["dnfr"],
             vf_before=state_before["vf"],
             edges_before=state_before.get("edges", None),
+            epi_before=state_before["epi"],
         )
 
 

src/tnfr/operators/metrics.py

@@ -559,6 +559,7 @@ def coupling_metrics(
     dnfr_before: float = None,
     vf_before: float = None,
     edges_before: int = None,
+    epi_before: float = None,
 ) -> dict[str, Any]:
     """UM - Coupling metrics: phase alignment, link formation, synchrony, ΔNFR reduction.
 
@@ -579,6 +580,8 @@ def coupling_metrics(
         Structural frequency (νf) before operator application
     edges_before : int, optional
         Number of edges before operator application
+    epi_before : float, optional
+        EPI value before operator application (for invariance verification)
 
     Returns
     -------
@@ -607,6 +610,13 @@ def coupling_metrics(
         - dnfr_reduction: Absolute reduction (before - after)
         - dnfr_reduction_pct: Percentage reduction
         
+        **EPI Invariance metrics:**
+        
+        - epi_before: EPI value before coupling
+        - epi_after: EPI value after coupling
+        - epi_drift: Absolute difference between before and after
+        - epi_preserved: Boolean indicating EPI invariance (drift < 1e-9)
+        
         **Network metrics:**
         
         - neighbor_count: Number of neighbors after coupling
@@ -622,6 +632,10 @@ def coupling_metrics(
     capture both the synchronization quality and the network structural changes
     resulting from coupling.
     
+    **EPI Invariance**: UM MUST preserve EPI identity. The epi_preserved metric
+    validates this fundamental invariant. If epi_preserved is False, it indicates
+    a violation of TNFR canonical requirements.
+    
     See Also
     --------
     operators.definitions.Coupling : UM operator implementation
@@ -679,6 +693,18 @@ def coupling_metrics(
             "dnfr_final": dnfr_after,
         })
 
+    # EPI invariance verification (if epi_before provided)
+    # CRITICAL: UM MUST preserve EPI identity per TNFR canonical theory
+    if epi_before is not None:
+        epi_after = _get_node_attr(G, node, ALIAS_EPI)
+        epi_drift = abs(epi_after - epi_before)
+        metrics.update({
+            "epi_before": epi_before,
+            "epi_after": epi_after,
+            "epi_drift": epi_drift,
+            "epi_preserved": epi_drift < 1e-9,  # Should ALWAYS be True
+        })
+
     # Edge/network formation metrics (if edges_before provided)
     edges_after = G.degree(node)
     if edges_before is not None: