Add THOL collective coherence validation

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

Author: Copilot

src/tnfr/config/defaults_core.py

@@ -158,6 +158,7 @@ class CoreDefaults:
     THOL_MIN_DEGREE: int = 1  # Minimum network connectivity
     THOL_MIN_HISTORY_LENGTH: int = 3  # Minimum EPI history for acceleration computation
     THOL_ALLOW_ISOLATED: bool = False  # Require network context by default
+    THOL_MIN_COLLECTIVE_COHERENCE: float = 0.3  # Minimum collective coherence for sub-EPI ensemble
 
     # VAL (Expansion) precondition thresholds
     VAL_MAX_VF: float = 10.0  # Maximum structural frequency threshold

src/tnfr/operators/definitions.py

@@ -2720,6 +2720,13 @@ def __call__(self, G: TNFRGraph, node: Any, **kw: Any) -> None:
         if d2_epi > tau:
             self._spawn_sub_epi(G, node, d2_epi=d2_epi, tau=tau)
 
+        # CANONICAL VALIDATION: Verify collective coherence of sub-EPIs
+        # When THOL creates multiple sub-EPIs, they must form a coherent ensemble
+        # that preserves the structural identity of the parent node (TNFR Manual §2.2.10)
+        # Always validate if node has sub-EPIs (whether created now or previously)
+        if G.nodes[node].get("sub_epis"):
+            self._validate_collective_coherence(G, node)
+
     def _compute_epi_acceleration(self, G: TNFRGraph, node: Any) -> float:
         """Calculate ∂²EPI/∂t² from node's EPI history.
 
@@ -2947,6 +2954,71 @@ def _create_sub_node(
 
         return sub_node_id
 
+    def _validate_collective_coherence(self, G: TNFRGraph, node: Any) -> None:
+        """Validate collective coherence of sub-EPI ensemble after bifurcation.
+
+        When THOL creates multiple sub-EPIs, they must form a coherent ensemble
+        that preserves the structural identity of the parent node. This validation
+        ensures the emergent sub-structures maintain structural alignment.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the node
+        node : Any
+            Node that underwent bifurcation
+
+        Notes
+        -----
+        TNFR Canonical Principle (TNFR Manual §2.2.10):
+        "THOL reorganiza la forma desde dentro, en respuesta a la coherencia
+        vibracional del campo. La autoorganización es resonancia estructurada
+        desde el interior del nodo."
+
+        Implication: Sub-EPIs are not random fragments but coherent structures
+        that emerge from internal resonance.
+
+        This method:
+        1. Computes collective coherence of sub-EPI ensemble
+        2. Stores coherence value for telemetry
+        3. Logs warning if coherence < threshold
+        4. Records event for analysis
+
+        Does NOT fail the operation - allows monitoring and analysis of
+        low-coherence bifurcations for research purposes.
+        """
+        import logging
+        from .metabolism import compute_subepi_collective_coherence
+
+        # Compute collective coherence
+        coherence = compute_subepi_collective_coherence(G, node)
+
+        # Store for telemetry (always store, even if 0.0 for single/no sub-EPIs)
+        G.nodes[node]["_thol_collective_coherence"] = coherence
+
+        # Get threshold from graph config
+        min_coherence = float(G.graph.get("THOL_MIN_COLLECTIVE_COHERENCE", 0.3))
+
+        # Validate against threshold (only warn if we have multiple sub-EPIs)
+        sub_epis = G.nodes[node].get("sub_epis", [])
+        if len(sub_epis) >= 2 and coherence < min_coherence:
+            # Log warning (but don't fail - allow monitoring)
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                f"Node {node}: THOL collective coherence ({coherence:.3f}) < "
+                f"threshold ({min_coherence}). Sub-EPIs may be fragmenting. "
+                f"Sub-EPI count: {len(sub_epis)}."
+            )
+
+            # Record event for analysis
+            events = G.graph.setdefault("thol_coherence_warnings", [])
+            events.append({
+                "node": node,
+                "coherence": coherence,
+                "threshold": min_coherence,
+                "sub_epi_count": len(sub_epis),
+            })
+
     def _validate_preconditions(self, G: TNFRGraph, node: Any) -> None:
         """Validate THOL-specific preconditions."""
         from .preconditions import validate_self_organization

src/tnfr/operators/health_analyzer.py

@@ -7,7 +7,10 @@
 from __future__ import annotations
 
 from functools import lru_cache
-from typing import List, Tuple
+from typing import Any, List, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph
 
 from ..compat.dataclass import dataclass
 from ..config.operator_names import (
@@ -725,3 +728,82 @@ def _detect_pattern(self, sequence: List[str]) -> str:
             return "exploratory"
 
         return "unknown"
+
+    def analyze_thol_coherence(self, G: TNFRGraph) -> dict[str, Any] | None:
+        """Analyze collective coherence of THOL bifurcations across the network.
+
+        Examines all nodes that have undergone THOL bifurcation and provides
+        statistics on their collective coherence metrics.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing nodes with potential THOL bifurcations
+
+        Returns
+        -------
+        dict or None
+            Dictionary containing coherence statistics:
+            - mean_coherence: Average coherence across all THOL nodes
+            - min_coherence: Lowest coherence value observed
+            - max_coherence: Highest coherence value observed
+            - nodes_below_threshold: Count of nodes with coherence < 0.3
+            - total_thol_nodes: Total nodes with sub-EPIs
+            Returns None if no THOL bifurcations exist in the network.
+
+        Notes
+        -----
+        TNFR Principle: Collective coherence measures the structural alignment
+        of emergent sub-EPIs. Low coherence may indicate chaotic fragmentation
+        rather than controlled emergence.
+
+        This metric is particularly useful for:
+        - Detecting pathological bifurcation patterns
+        - Monitoring network-wide self-organization quality
+        - Identifying nodes requiring stabilization
+
+        Examples
+        --------
+        >>> analyzer = SequenceHealthAnalyzer()
+        >>> # After running THOL operations on graph G
+        >>> coherence_stats = analyzer.analyze_thol_coherence(G)
+        >>> if coherence_stats:
+        ...     print(f"Mean coherence: {coherence_stats['mean_coherence']:.3f}")
+        ...     print(f"Nodes below threshold: {coherence_stats['nodes_below_threshold']}")
+        """
+        # Find all nodes with sub-EPIs (THOL bifurcation occurred)
+        thol_nodes = []
+        for node in G.nodes():
+            if G.nodes[node].get("sub_epis"):
+                thol_nodes.append(node)
+
+        if not thol_nodes:
+            return None
+
+        # Collect coherence values
+        coherences = []
+        for node in thol_nodes:
+            coh = G.nodes[node].get("_thol_collective_coherence")
+            if coh is not None:
+                coherences.append(coh)
+
+        if not coherences:
+            return None
+
+        # Compute statistics
+        mean_coherence = sum(coherences) / len(coherences)
+        min_coherence = min(coherences)
+        max_coherence = max(coherences)
+
+        # Get threshold from graph config
+        threshold = float(G.graph.get("THOL_MIN_COLLECTIVE_COHERENCE", 0.3))
+        nodes_below_threshold = sum(1 for c in coherences if c < threshold)
+
+        return {
+            "mean_coherence": mean_coherence,
+            "min_coherence": min_coherence,
+            "max_coherence": max_coherence,
+            "nodes_below_threshold": nodes_below_threshold,
+            "total_thol_nodes": len(thol_nodes),
+            "threshold": threshold,
+        }