Merge pull request #2816 from fermga/copilot/refactor-sub-epis-into-nodes

Refactor sub-EPIs as independent nodes for operational fractality

Author: fermga

src/tnfr/operators/definitions.py

@@ -2561,6 +2561,10 @@ def _spawn_sub_epi(
         This implements canonical THOL: "reorganizes external experience into
         internal structure without external instruction".
 
+        ARCHITECTURAL: Sub-EPIs are created as independent NFR nodes to enable
+        operational fractality - recursive operator application, hierarchical metrics,
+        and multi-level bifurcation.
+
         Parameters
         ----------
         G : TNFRGraph
@@ -2573,12 +2577,13 @@ def _spawn_sub_epi(
             Bifurcation threshold that was exceeded
         """
         from ..alias import get_attr, set_attr
-        from ..constants.aliases import ALIAS_EPI, ALIAS_VF
+        from ..constants.aliases import ALIAS_EPI, ALIAS_VF, ALIAS_THETA
         from .metabolism import capture_network_signals, metabolize_signals_into_subepi
 
         # Get current node state
         parent_epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
         parent_vf = float(get_attr(G.nodes[node], ALIAS_VF, 1.0))
+        parent_theta = float(get_attr(G.nodes[node], ALIAS_THETA, 0.0))
 
         # Check if vibrational metabolism is enabled
         metabolic_enabled = G.graph.get("THOL_METABOLIC_ENABLED", True)
@@ -2606,24 +2611,33 @@ def _spawn_sub_epi(
             complexity_weight=complexity_weight,
         )
 
-        # Store sub-EPI in node's sub_epis list
-        sub_epis = G.nodes[node].get("sub_epis", [])
-
         # Get current timestamp from glyph history length
         timestamp = len(G.nodes[node].get("glyph_history", []))
 
-        # Store sub-EPI with metabolic metadata
+        # ARCHITECTURAL: Create sub-EPI as independent NFR node
+        # This enables operational fractality - recursive operators, hierarchical metrics
+        sub_node_id = self._create_sub_node(
+            G,
+            parent_node=node,
+            sub_epi=sub_epi_value,
+            parent_vf=parent_vf,
+            parent_theta=parent_theta,
+        )
+
+        # Store sub-EPI metadata for telemetry and backward compatibility
         sub_epi_record = {
             "epi": sub_epi_value,
             "vf": parent_vf,
             "timestamp": timestamp,
             "d2_epi": d2_epi,
             "tau": tau,
-            # NEW: Metabolic metadata
+            "node_id": sub_node_id,  # Reference to independent node
             "metabolized": network_signals is not None and metabolic_enabled,
             "network_signals": network_signals,
         }
 
+        # Keep metadata list for telemetry/metrics backward compatibility
+        sub_epis = G.nodes[node].get("sub_epis", [])
         sub_epis.append(sub_epi_record)
         G.nodes[node]["sub_epis"] = sub_epis
 
@@ -2649,6 +2663,82 @@ def _spawn_sub_epi(
                     }
                 )
 
+    def _create_sub_node(
+        self,
+        G: TNFRGraph,
+        parent_node: Any,
+        sub_epi: float,
+        parent_vf: float,
+        parent_theta: float,
+    ) -> str:
+        """Create sub-EPI as independent NFR node for operational fractality.
+
+        Sub-nodes are full TNFR nodes that can have operators applied, bifurcate
+        recursively, and contribute to hierarchical metrics.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the parent node
+        parent_node : Any
+            Parent node identifier
+        sub_epi : float
+            EPI value for the sub-node
+        parent_vf : float
+            Parent's structural frequency (inherited with damping)
+        parent_theta : float
+            Parent's phase (inherited)
+
+        Returns
+        -------
+        str
+            Identifier of the newly created sub-node
+        """
+        from ..constants import EPI_PRIMARY, VF_PRIMARY, THETA_PRIMARY, DNFR_PRIMARY
+        from ..dynamics import set_delta_nfr_hook
+
+        # Generate unique sub-node ID
+        sub_nodes_list = G.nodes[parent_node].get("sub_nodes", [])
+        sub_index = len(sub_nodes_list)
+        sub_node_id = f"{parent_node}_sub_{sub_index}"
+
+        # Get parent hierarchy level
+        parent_hierarchy_level = G.nodes[parent_node].get("hierarchy_level", 0)
+
+        # Inherit parent's vf with slight damping (canonical: 95%)
+        sub_vf = parent_vf * 0.95
+
+        # Create the sub-node with full TNFR state
+        G.add_node(
+            sub_node_id,
+            **{
+                EPI_PRIMARY: float(sub_epi),
+                VF_PRIMARY: float(sub_vf),
+                THETA_PRIMARY: float(parent_theta),
+                DNFR_PRIMARY: 0.0,
+                "parent_node": parent_node,
+                "hierarchy_level": parent_hierarchy_level + 1,
+                "epi_history": [float(sub_epi)],  # Initialize history for future bifurcation
+                "glyph_history": [],
+            },
+        )
+
+        # Ensure ΔNFR hook is set for the sub-node
+        # (inherits from graph-level hook, but ensure it's activated)
+        if hasattr(G, "graph") and "_delta_nfr_hook" in G.graph:
+            # Hook already set at graph level, will apply to sub-node automatically
+            pass
+
+        # Track sub-node in parent
+        sub_nodes_list.append(sub_node_id)
+        G.nodes[parent_node]["sub_nodes"] = sub_nodes_list
+
+        # Track hierarchy in graph metadata
+        hierarchy = G.graph.setdefault("hierarchy", {})
+        hierarchy.setdefault(parent_node, []).append(sub_node_id)
+
+        return sub_node_id
+
     def _validate_preconditions(self, G: TNFRGraph, node: Any) -> None:
         """Validate THOL-specific preconditions."""
         from .preconditions import validate_self_organization

src/tnfr/operators/metabolism.py

@@ -341,6 +341,9 @@ def compute_cascade_depth(G: TNFRGraph, node: NodeId) -> int:
     Recursively measures how many levels of nested sub-EPIs exist,
     where each sub-EPI can itself bifurcate into deeper levels.
 
+    With architectural refactor: sub-EPIs are now independent NFR nodes,
+    enabling true recursive depth computation.
+
     Parameters
     ----------
     G : TNFRGraph
@@ -368,19 +371,42 @@ def compute_cascade_depth(G: TNFRGraph, node: NodeId) -> int:
     TNFR Principle: Cascade depth measures the hierarchical complexity
     of emergent self-organization. Depth = 1 indicates direct bifurcation;
     depth > 1 indicates recursive, multi-scale emergence.
+
+    ARCHITECTURAL: Now supports true recursive bifurcation with independent
+    sub-nodes. If a node has no independent sub-nodes, falls back to
+    metadata-based depth for backward compatibility.
     """
+    # Primary path: Check for independent sub-nodes (new architecture)
+    sub_nodes = G.nodes[node].get("sub_nodes", [])
+    if sub_nodes:
+        # Recursive computation with actual nodes
+        max_depth = 0
+        for sub_node_id in sub_nodes:
+            if sub_node_id in G.nodes:
+                # Recurse into child's depth
+                child_depth = compute_cascade_depth(G, sub_node_id)
+                max_depth = max(max_depth, 1 + child_depth)
+            else:
+                # Child node exists in list but not in graph (shouldn't happen)
+                max_depth = max(max_depth, 1)
+        return max_depth
+
+    # Fallback path: Legacy metadata-based depth
     sub_epis = G.nodes[node].get("sub_epis", [])
     if not sub_epis:
         return 0
 
-    # For now: depth = 1 (direct children)
-    # TODO: If sub-EPIs become independent nodes, recurse
     max_depth = 1
-
     for sub in sub_epis:
-        # If sub-EPI spawned its own children (future enhancement)
-        nested_depth = sub.get("cascade_depth", 0)
-        max_depth = max(max_depth, 1 + nested_depth)
+        # Check if sub-EPI has node_id (new architecture with metadata)
+        if "node_id" in sub and sub["node_id"] in G.nodes:
+            # Recurse into independent node
+            child_depth = compute_cascade_depth(G, sub["node_id"])
+            max_depth = max(max_depth, 1 + child_depth)
+        else:
+            # Legacy metadata-only mode
+            nested_depth = sub.get("cascade_depth", 0)
+            max_depth = max(max_depth, 1 + nested_depth)
 
     return max_depth