Merge pull request #2876 from fermga/copilot/add-collective-coherence-validation

Add collective coherence validation for THOL sub-EPI ensembles

Author: fermga

docs/THOL_CONFIGURATION_REFERENCE.md

@@ -29,6 +29,7 @@ Parameters controlling when and how bifurcation (sub-EPI creation) occurs.
 | `THOL_MIN_EPI` | 0.2 | [0.05, 0.5] | — | Minimum EPI magnitude required for structural bifurcation |
 | `THOL_MIN_VF` | 0.1 | [0.01, 1.0] | Hz_str | Minimum structural frequency for reorganization capacity |
 | `THOL_ACCEL` | 0.10 | [0.01, 0.5] | — | Acceleration factor in glyph: ΔNFR += `THOL_accel` × d²EPI/dt² |
+| `THOL_MIN_COLLECTIVE_COHERENCE` | 0.3 | [0.0, 1.0] | — | Minimum collective coherence for sub-EPI ensemble. When multiple sub-EPIs exist and coherence < threshold, warning is logged |
 
 **Physical Basis:**
 
@@ -38,6 +39,12 @@ From the nodal equation ∂EPI/∂t = νf · ΔNFR(t), bifurcation occurs when *
 - **EPI_min**: Coherence floor. Nodes below this lack sufficient form to bifurcate coherently.
 - **νf_min**: Reorganization capacity floor. Nodes below this are "frozen" and cannot respond.
 - **THOL_accel**: Controls how strongly d²EPI/dt² influences ΔNFR in glyph sequences.
+- **THOL_MIN_COLLECTIVE_COHERENCE**: Monitors ensemble coherence of sub-EPIs. According to TNFR.pdf §2.2.10, sub-EPIs must form a **coherent ensemble** rather than fragmenting chaotically. Collective coherence is computed as `C = 1/(1 + var(sub_epi_magnitudes))`. Interpretation:
+  - **> 0.7**: High coherence (structurally solid bifurcation)
+  - **0.3-0.7**: Moderate (acceptable, monitor)
+  - **< 0.3**: Low (possible fragmentation, warning logged)
+  
+  When multiple sub-EPIs exist and coherence falls below threshold, a warning is logged and the event is recorded in `G.graph["thol_coherence_warnings"]` for analysis. This validation is **non-blocking** (warnings only) to allow research into low-coherence dynamics.
 
 **Configuration Example:**
 ```python
@@ -48,11 +55,21 @@ G = nx.Graph()
 G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.8  # High threshold
 G.graph["THOL_MIN_EPI"] = 0.3              # Require strong coherence
 G.graph["THOL_MIN_VF"] = 0.2               # Require high capacity
+G.graph["THOL_MIN_COLLECTIVE_COHERENCE"] = 0.5  # Require coherent ensemble
 
 # Sensitive bifurcation (easier to trigger)
 G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.2  # Low threshold
 G.graph["THOL_MIN_EPI"] = 0.1              # Lower coherence floor
 G.graph["THOL_MIN_VF"] = 0.05              # Lower capacity floor
+G.graph["THOL_MIN_COLLECTIVE_COHERENCE"] = 0.2  # More tolerant of fragmentation
+
+# Monitor collective coherence
+from tnfr.operators.health_analyzer import SequenceHealthAnalyzer
+analyzer = SequenceHealthAnalyzer()
+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']}")
 ```
 
 ---
@@ -668,6 +685,7 @@ G.graph["BIFURCATION_THRESHOLD_TAU"] = 0.5         # Higher threshold
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2025-11-09 | Initial release: Centralized all THOL parameters with canonical constraints |
+| 1.1.0 | 2025-11-09 | Added `THOL_MIN_COLLECTIVE_COHERENCE` parameter for sub-EPI ensemble validation |
 
 ---
 

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,
+        }