feat: Add hierarchical depth telemetry for nested THOL bifurcations

- Add bifurcation_level and hierarchy_path fields to sub_epi records
- Implement compute_hierarchical_depth() for recursive depth measurement
- Add depth validation with THOL_MAX_BIFURCATION_DEPTH parameter
- Create hierarchy visualization utility (print_bifurcation_hierarchy)
- Add comprehensive tests for 1, 2, and 3-level nested bifurcations
- Fix missing angle_diff import in metabolism.py

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

Author: Copilot

src/tnfr/operators/definitions.py

@@ -2718,6 +2718,8 @@ def __call__(self, G: TNFRGraph, node: Any, **kw: Any) -> None:
 
         # Bifurcate if acceleration exceeds threshold
         if d2_epi > tau:
+            # Validate depth before bifurcation
+            self._validate_bifurcation_depth(G, node)
             self._spawn_sub_epi(G, node, d2_epi=d2_epi, tau=tau)
 
         # CANONICAL VALIDATION: Verify collective coherence of sub-EPIs
@@ -2827,6 +2829,14 @@ def _spawn_sub_epi(
         # Get current timestamp from glyph history length
         timestamp = len(G.nodes[node].get("glyph_history", []))
 
+        # Determine parent bifurcation level for hierarchical telemetry
+        parent_level = G.nodes[node].get("_bifurcation_level", 0)
+        child_level = parent_level + 1
+        
+        # Construct hierarchy path for full traceability
+        parent_path = G.nodes[node].get("_hierarchy_path", [])
+        child_path = parent_path + [node]
+
         # ARCHITECTURAL: Create sub-EPI as independent NFR node
         # This enables operational fractality - recursive operators, hierarchical metrics
         sub_node_id = self._create_sub_node(
@@ -2835,6 +2845,8 @@ def _spawn_sub_epi(
             sub_epi=sub_epi_value,
             parent_vf=parent_vf,
             parent_theta=parent_theta,
+            child_level=child_level,
+            child_path=child_path,
         )
 
         # Store sub-EPI metadata for telemetry and backward compatibility
@@ -2847,6 +2859,8 @@ def _spawn_sub_epi(
             "node_id": sub_node_id,  # Reference to independent node
             "metabolized": network_signals is not None and metabolic_enabled,
             "network_signals": network_signals,
+            "bifurcation_level": child_level,  # Hierarchical depth tracking
+            "hierarchy_path": child_path,  # Full parent chain for traceability
         }
 
         # Keep metadata list for telemetry/metrics backward compatibility
@@ -2883,6 +2897,8 @@ def _create_sub_node(
         sub_epi: float,
         parent_vf: float,
         parent_theta: float,
+        child_level: int,
+        child_path: list,
     ) -> str:
         """Create sub-EPI as independent NFR node for operational fractality.
 
@@ -2901,6 +2917,10 @@ def _create_sub_node(
             Parent's structural frequency (inherited with damping)
         parent_theta : float
             Parent's phase (inherited)
+        child_level : int
+            Bifurcation level for hierarchical tracking
+        child_path : list
+            Full hierarchy path (ancestor chain)
 
         Returns
         -------
@@ -2931,6 +2951,8 @@ def _create_sub_node(
                 DNFR_PRIMARY: 0.0,
                 "parent_node": parent_node,
                 "hierarchy_level": parent_hierarchy_level + 1,
+                "_bifurcation_level": child_level,  # Hierarchical depth tracking
+                "_hierarchy_path": child_path,  # Full ancestor chain
                 "epi_history": [
                     float(sub_epi)
                 ],  # Initialize history for future bifurcation
@@ -2954,6 +2976,58 @@ def _create_sub_node(
 
         return sub_node_id
 
+    def _validate_bifurcation_depth(self, G: TNFRGraph, node: Any) -> None:
+        """Validate bifurcation depth before creating new sub-EPI.
+        
+        Checks if the current bifurcation level is at or exceeds the configured
+        maximum depth. Issues a warning if depth limit is reached but still
+        allows the bifurcation (for flexibility in research contexts).
+        
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the node
+        node : Any
+            Node about to undergo bifurcation
+            
+        Notes
+        -----
+        TNFR Principle: Deep nesting reflects operational fractality (Invariant #7),
+        but excessive depth may impact performance and interpretability. This
+        validation provides observability without hard constraints.
+        
+        The warning allows tracking when hierarchies become complex, enabling
+        researchers to study bifurcation patterns while maintaining system
+        performance awareness.
+        """
+        import logging
+        
+        # Get current bifurcation level
+        current_level = G.nodes[node].get("_bifurcation_level", 0)
+        
+        # Get max depth from graph config (default: 5 levels)
+        max_depth = int(G.graph.get("THOL_MAX_BIFURCATION_DEPTH", 5))
+        
+        # Warn if at or exceeding maximum
+        if current_level >= max_depth:
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                f"Node {node}: Bifurcation depth ({current_level}) at/exceeds "
+                f"maximum ({max_depth}). Deep nesting may impact performance. "
+                f"Consider adjusting THOL_MAX_BIFURCATION_DEPTH if intended."
+            )
+            
+            # Record warning in node for telemetry
+            G.nodes[node]["_thol_max_depth_warning"] = True
+            
+            # Record event for analysis
+            events = G.graph.setdefault("thol_depth_warnings", [])
+            events.append({
+                "node": node,
+                "depth": current_level,
+                "max_depth": max_depth,
+            })
+
     def _validate_collective_coherence(self, G: TNFRGraph, node: Any) -> None:
         """Validate collective coherence of sub-EPI ensemble after bifurcation.
 

src/tnfr/operators/metabolism.py

@@ -41,12 +41,14 @@
 from ..alias import get_attr
 from ..constants.aliases import ALIAS_EPI, ALIAS_THETA
 from ..utils import get_numpy
+from ..utils.numeric import angle_diff
 
 __all__ = [
     "capture_network_signals",
     "metabolize_signals_into_subepi",
     "propagate_subepi_to_network",
     "compute_cascade_depth",
+    "compute_hierarchical_depth",
     "compute_propagation_radius",
     "compute_subepi_collective_coherence",
     "compute_metabolic_activity_index",
@@ -414,6 +416,76 @@ def compute_cascade_depth(G: TNFRGraph, node: NodeId) -> int:
     return max_depth
 
 
+def compute_hierarchical_depth(G: TNFRGraph, node: NodeId) -> int:
+    """Compute maximum bifurcation depth from node using recursive traversal.
+    
+    Traverses sub-EPI hierarchy recursively to find the maximum bifurcation_level
+    across all nested branches. This provides accurate hierarchical telemetry for
+    nested THOL bifurcations, supporting operational fractality analysis.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Network graph
+    node : NodeId
+        Root node to measure depth from
+        
+    Returns
+    -------
+    int
+        Maximum bifurcation depth (0 = no bifurcations, 1 = single-level, etc.)
+        
+    Notes
+    -----
+    TNFR Principle: Hierarchical depth reflects operational fractality
+    (Invariant #7) - the ability of sub-EPIs to bifurcate recursively,
+    creating multi-scale emergent structures.
+    
+    This function recursively traverses all branches to find the deepest
+    bifurcation_level, providing precise depth tracking for:
+    - Debugging complex nested structures
+    - Validating depth limits
+    - Analyzing bifurcation patterns
+    - Performance monitoring
+    
+    Examples
+    --------
+    >>> # Node with no bifurcations
+    >>> compute_hierarchical_depth(G, node)
+    0
+    
+    >>> # Node with single-level bifurcation
+    >>> compute_hierarchical_depth(G, node_with_subs)
+    1
+    
+    >>> # Node with 2-level nested bifurcation
+    >>> compute_hierarchical_depth(G, node_nested)
+    2
+    """
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    
+    if not sub_epis:
+        return 0
+    
+    # Recursively find the maximum bifurcation_level across all branches
+    max_level = 0
+    for sub_epi in sub_epis:
+        # Get this sub-EPI's bifurcation level
+        level = sub_epi.get("bifurcation_level", 1)
+        max_level = max(max_level, level)
+        
+        # Recurse into sub-node if it exists to find deeper levels
+        sub_node_id = sub_epi.get("node_id")
+        if sub_node_id and sub_node_id in G.nodes:
+            # Recursively check this sub-node's depth
+            sub_depth = compute_hierarchical_depth(G, sub_node_id)
+            # If sub-node has bifurcations, its depth represents deeper levels
+            if sub_depth > 0:
+                max_level = max(max_level, sub_depth)
+    
+    return max_level
+
+
 def compute_propagation_radius(G: TNFRGraph) -> int:
     """Count total unique nodes affected by THOL cascades.
 

src/tnfr/visualization/__init__.py

@@ -5,12 +5,15 @@
 - Health metrics dashboards with radar charts and gauges
 - Pattern analysis with component highlighting
 - Frequency timelines showing structural evolution
-- Cascade propagation and temporal dynamics (NEW)
+- Cascade propagation and temporal dynamics
+- Hierarchical bifurcation structures (NEW)
 
-Requires matplotlib for plotting. Install with::
+Requires matplotlib for plotting (optional). Install with::
 
     pip install tnfr[viz]
 
+Hierarchy visualization (ASCII) has no external dependencies.
+
 Examples
 --------
 >>> from tnfr.visualization import SequenceVisualizer
@@ -23,12 +26,22 @@
 >>> fig, ax = visualizer.plot_sequence_flow(sequence, result.health_metrics)
 >>> fig.savefig("sequence_flow.png")
 
->>> # Cascade visualization (NEW)
+>>> # Cascade visualization
 >>> from tnfr.visualization import plot_cascade_propagation, plot_cascade_timeline
 >>> fig = plot_cascade_propagation(G)
 >>> fig.savefig("cascade_propagation.png")
+
+>>> # Hierarchy visualization (no matplotlib required)
+>>> from tnfr.visualization import print_bifurcation_hierarchy
+>>> print_bifurcation_hierarchy(G, node)
 """
 
+# Always available (no dependencies)
+from .hierarchy import (
+    print_bifurcation_hierarchy,
+    get_hierarchy_info,
+)
+
 _import_error: ImportError | None = None
 
 try:
@@ -44,6 +57,8 @@
         "plot_cascade_propagation",
         "plot_cascade_timeline",
         "plot_cascade_metrics_summary",
+        "print_bifurcation_hierarchy",
+        "get_hierarchy_info",
     ]
 except ImportError as _import_err:
     _import_error = _import_err
@@ -78,4 +93,6 @@ def _missing_viz_dependency(*args: _Any, **kwargs: _Any) -> None:
         "plot_cascade_propagation",
         "plot_cascade_timeline",
         "plot_cascade_metrics_summary",
+        "print_bifurcation_hierarchy",
+        "get_hierarchy_info",
     ]