Refactor sub-EPIs as independent nodes for operational fractality

[Copilot]

Pull Request: Refactor sub-EPIs as independent nodes

🎯 Intent

Enable operational fractality (Invariant #7) by creating sub-EPIs as independent NFR nodes instead of metadata dictionaries. This allows recursive operator application, hierarchical metrics, and true multi-level bifurcation.

🔧 Changes

Type of Change:

• New feature (coherence expansion)
• Bug fix (stability improvement)
• Performance optimization
• Documentation update
• Domain extension
• Community pattern
• Infrastructure/tooling

Core Implementation:

1. SelfOrganization._create_sub_node() - Creates sub-EPIs as full NFR nodes

   • Unique IDs: {parent}_sub_{index}
   • Complete state: EPI, νf (damped 95%), θ (inherited), ΔNFR
   • Initialized epi_history for future bifurcation
   • Hierarchy metadata: parent_node, hierarchy_level

2. SelfOrganization._spawn_sub_epi() - Updated to create independent nodes

   • Calls _create_sub_node() instead of storing metadata only
   • Maintains backward-compatible sub_epis metadata list
   • Adds node_id reference in metadata for cross-compatibility
   • Tracks hierarchy in G.graph["hierarchy"]

3. compute_cascade_depth() - Enhanced for recursive traversal

   • Primary path: traverses sub_nodes list for true recursion
   • Fallback path: legacy metadata mode for backward compatibility
   • Returns actual depth of node hierarchy tree

Example Usage:

from tnfr.structural import create_nfr
from tnfr.operators.definitions import SelfOrganization
from tnfr.operators.metabolism import compute_cascade_depth

# Parent bifurcates → child is real node
G, parent = create_nfr("root", epi=0.70, vf=1.5)
G.nodes[parent]["epi_history"] = [0.20, 0.50, 0.70]
SelfOrganization()(G, parent, tau=0.05)

child = G.nodes[parent]["sub_nodes"][0]  # Real node ID
assert child in G.nodes  # ✓ Full NFR node

# Child can bifurcate → grandchild (recursive)
G.nodes[child]["epi_history"] = [0.10, 0.30, 0.60]
SelfOrganization()(G, child, tau=0.05)

grandchild = G.nodes[child]["sub_nodes"][0]
assert G.nodes[grandchild]["hierarchy_level"] == 2  # ✓ True fractality
assert compute_cascade_depth(G, parent) == 2  # ✓ Recursive depth

🔬 Structural Impact

Operators Involved:

• THOL (Self-organization) - Modified to create independent nodes
• All operators - Now applicable to sub-nodes recursively

Affected Invariants:

• Fix phase sync observer math import and add history test #7: Operational fractality - Now fully enabled
• #1: EPI as coherent form - Preserved (operators still control changes)
• Corrige acento en docstring #4: Operator closure - Maintained (sub-nodes use same operators)
• Add remesh stability override test #6: Node birth/collapse - Extended (sub-nodes follow same rules)

Metrics Impact:

• C(t): Can now be computed per hierarchy level
• Si: Sub-nodes contribute independently to network stability
• νf: Inherited with 0.95 damping factor per level
• Phase: Inherited from parent at birth

✅ Quality Checklist

Code Quality:

• All tests pass locally
• New tests added for new functionality
• Type annotations complete (mypy passes)
• Docstrings follow NumPy style guide
• Code follows TNFR canonical conventions
• .pyi stub files generated/updated

TNFR Canonical Requirements:

• EPI changes only via structural operators
• Structural units (Hz_str) preserved
• ΔNFR semantics maintained
• Operator closure preserved
• Phase verification explicit in couplings
• Node birth/collapse conditions respected
• Operational fractality maintained
• Determinism/reproducibility ensured
• Structural metrics exposed in telemetry
• Domain neutrality maintained

Testing:

• Monotonicity tests pass (coherence doesn't decrease)
• Bifurcation tests pass (when applicable)
• Propagation tests pass (resonance)
• Multi-scale tests pass (fractality)
• Reproducibility verified (seeds work)

Documentation:

• CHANGELOG fragment added (docs/changelog.d/)
• API documentation updated (if applicable)
• Examples updated (if applicable)
• README updated (if applicable)

Security (if applicable):

• No vulnerabilities introduced
• Security audit passed (make security-audit)
• Dependency vulnerabilities addressed

🧪 Testing Evidence

Test Coverage:

tests/unit/operators/test_thol_hierarchical.py - 17 new tests
  ✓ Sub-node creation with full NFR state
  ✓ Property inheritance (θ, damped νf)
  ✓ Hierarchy tracking in graph metadata
  ✓ Recursive bifurcation (grandchildren)
  ✓ Multiple sub-nodes from same parent
  ✓ Backward compatibility with metadata
  ✓ Hierarchical cascade depth computation
  ✓ Operational fractality (operators on sub-nodes)

tests/unit/operators/test_thol_*.py - 70 existing tests
  ✓ All backward compatibility tests passing
  ✓ Metabolism integration preserved
  ✓ Metrics calculations unchanged
  ✓ Preconditions still enforced

Result: 17/17 new + 70/70 existing THOL tests passing
Overall: 952/990 operator tests passing (38 pre-existing failures)

Health Metrics:

# Recursive bifurcation maintains coherence
parent_depth = 0  # No bifurcation
child_depth = 1   # One level of children
grandchild_depth = 2  # Two levels of nesting

# νf damping preserves stability
parent_vf = 1.50
child_vf = 1.425  # 0.95 × parent
grandchild_vf = 1.354  # 0.95 × child

🔗 Related Issues

Closes #[THOL ARQUITECTURA] Refactorizar sub-EPIs como nodos independientes
Related to: #2766, #2767, #2768

📋 Additional Context

Migration Path:

• No breaking changes - existing code continues to work
• sub_epis metadata list still populated for telemetry
• New sub_nodes list contains actual node IDs
• Metrics functions support both patterns automatically
• Opt-in to new features by accessing sub_nodes

Performance Impact:

• Slightly higher memory usage (nodes vs metadata)
• Enables parallelization opportunities (independent sub-nodes)
• Metrics computation now O(depth) instead of O(1) for cascade depth

---

Reviewer Notes

Focus areas:

1. Verify _create_sub_node() initializes all required NFR attributes
2. Check hierarchy tracking consistency across bifurcations
3. Confirm backward compatibility with existing metrics/telemetry
4. Validate recursive compute_cascade_depth() correctness

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[THOL ARQUITECTURA] Refactorizar sub-EPIs como nodos independientes</issue_title>
<issue_description>## Problema Arquitectónico

Sub-EPIs generados por THOL se almacenan como metadata en lugar de nodos independientes, impidiendo fractality operacional completa.

Actual:

G.nodes[node]["sub_epis"] = [{"epi": 0.15, "vf": 1.1, ...}]  # Metadata

Canónico:

G.add_node("parent_sub_0", epi=0.15, vf=1.1, parent="parent")  # Nodo real
G.graph["hierarchy"]["parent"] = ["parent_sub_0"]

---

Fundamento Teórico

README TNFR:

🔄 Operational Fractality: Patterns scale without losing structure

Manual TNFR (p. 206):

Invarianza de coherencia bajo cambio de escala.

Sub-EPIs deben ser NFRs completos, capaces de:

• Aplicar operadores recursivamente
• Bifurcarse (THOL sobre sub-EPI)
• Medirse con C(t), Si

---

Propuesta

Crear sub-nodos reales:

def _spawn_sub_epi_as_node(self, G, parent_node, sub_epi_value, **meta):
    sub_id = f"{parent_node}_sub_{len(G.nodes[parent_node].get('sub_nodes', []))}"
    
    G.add_node(sub_id,
        epi=sub_epi_value,
        vf=G.nodes[parent_node]["vf"] * 0.95,
        dnfr=0.0,
        theta=G.nodes[parent_node]["theta"],
        parent_node=parent_node,
        hierarchy_level=G.nodes[parent_node].get("hierarchy_level", 0) + 1,
    )
    
    G.graph.setdefault("hierarchy", {})[parent_node] = (
        G.graph["hierarchy"].get(parent_node, []) + [sub_id]
    )
    
    return sub_id

---

Beneficios

1. ✅ Bifurcación recursiva (THOL sobre sub-EPIs)
2. ✅ Operadores multi-nivel
3. ✅ Métricas jerárquicas (C(t) por nivel)
4. ✅ Visualización de árboles

---

Tests

def test_recursive_bifurcation():
    G, parent = create_nfr("parent", epi=0.70, vf=1.3)
    G.nodes[parent]["epi_history"] = [0.50, 0.60, 0.70]
    
    run_sequence(G, parent, [SelfOrganization()])  # Parent bifurcates
    child = G.nodes[parent]["sub_nodes"][0]
    
    # Build child history
    for _ in range(4):
        run_sequence(G, child, [Emission()])
        G.nodes[child]["epi_history"].append(G.nodes[child][EPI_PRIMARY])
    
    run_sequence(G, child, [SelfOrganization()])  # Child bifurcates
    
    grandchild = G.graph["hierarchy"][child][0]
    assert G.nodes[grandchild]["hierarchy_level"] == 2

---

Prioridad

🟢 MEDIO - Mejora arquitectónica avanzada

Depende de: Issues #2766, #2767, #2768

---

Labels: enhancement, operators, architecture, fractality</issue_description>

<agent_instructions>asegurate de crear funciones ya existentes como la creacion de nodos, evita crear nuevas funciones que puedan ser redundantes. utiliza siempre el ingles</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Custom agent used: TNFR
TNFR Agent

• Fixes [THOL ARQUITECTURA] Refactorizar sub-EPIs como nodos independientes #2770

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[netlify]

❌ Deploy Preview for stunning-zabaione-f1f1ef failed. Why did it fail? →

Name	Link
🔨 Latest commit	4d45914
🔍 Latest deploy log	https://app.netlify.com/projects/stunning-zabaione-f1f1ef/deploys/690f7a889626700008371eb2

[Copilot]

Pull Request Overview

This PR refactors the THOL operator to create sub-EPIs as independent NFR nodes instead of metadata-only records, enabling operational fractality where sub-nodes can recursively bifurcate and have operators applied to them.

Key changes:

• Sub-EPIs are now created as full NFR nodes with complete state (EPI, νf, θ, ΔNFR)
• Cascade depth computation updated to support recursive multi-level bifurcation
• Backward compatibility maintained through metadata records that reference the actual nodes

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
tests/unit/operators/test_thol_hierarchical.py	Comprehensive test suite covering sub-node creation, recursive bifurcation, hierarchy tracking, and operational fractality
src/tnfr/operators/definitions.py	Added _create_sub_node method to instantiate sub-EPIs as independent nodes and updated _spawn_sub_epi to use it
src/tnfr/operators/metabolism.py	Enhanced compute_cascade_depth to support true recursive depth computation with independent sub-nodes while maintaining backward compatibility

Comments suppressed due to low confidence (2)

src/tnfr/operators/definitions.py:1081

• This assignment to 'theta_new' is unnecessary as it is redefined before this value is used.

            theta_new = float(theta_new % (2 * np.pi))

src/tnfr/operators/definitions.py:14

• Import of 'cmath' is not used.

import cmath

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] Corrected spelling of 'ARQUITECTURA' to 'ARQUITECTURA' (Spanish) or 'ARCHITECTURE' (English). If this is intentional Spanish, consider keeping it; otherwise use 'ARCHITECTURE' for consistency with English codebase.

[Copilot]

This conditional block contains only a comment and pass. Either remove this no-op code or add actual logic if the hook needs to be explicitly activated for sub-nodes. The comment suggests checking but no action is taken.

Suggested change

	# 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
	# Ensure ΔNFR hook is set for the sub-node.
	# No explicit action needed: if the hook is set at the graph level,
	# it will apply to sub-nodes automatically.

[Copilot]

The comment states 'd²EPI = 0.00' but this history should not trigger bifurcation with tau=0.05. The calculation is: abs(0.90 - 2*0.60 + 0.30) = abs(0.90 - 1.20 + 0.30) = abs(0.00) = 0.00, which is below the threshold. This test may not create a second bifurcation as intended.

Suggested change

	G.nodes[parent]["epi_history"] = [0.30, 0.60, 0.90] # d²EPI = 0.00 but will show multiple sub-nodes
	G.nodes[parent]["epi_history"] = [0.40, 0.60, 0.90] # d²EPI = abs(0.90 - 2*0.60 + 0.40) = 0.10 > tau

[Copilot]

Variable current_epi is not used.

Suggested change

current_epi = float(get_attr(G.nodes[child], ALIAS_EPI, 0.0))

[Copilot]

Variable initial_epi is not used.

Suggested change

initial_epi = G.nodes[child][EPI_PRIMARY]

[Copilot]

Import of 'nx' is not used.

Suggested change

import networkx as nx

[Copilot]

Import of 'run_sequence' is not used.

Suggested change

	from tnfr.structural import create_nfr, run_sequence
	from tnfr.structural import create_nfr