Merge pull request #2798 from fermga/copilot/update-default-functional-links

feat: Make UM functional links default behavior

Author: fermga

docs/API_CONTRACTS.md

@@ -133,11 +133,12 @@ This document formalizes the **structural invariants** and **API contracts** for
 - **Postconditions**:
   - `θ_new = θ_old + UM_theta_push * angle_diff(θ_neighbor_mean, θ_old)`
   - `0 ≤ UM_theta_push ≤ 1` (default: 0.25)
-  - **Optional**: If `UM_FUNCTIONAL_LINKS=True`, may add edges based on:
+  - By default (`UM_FUNCTIONAL_LINKS=True`), may add edges based on:
     - Phase similarity: `1 - |Δθ|/π`
     - EPI similarity: `1 - |EPI_i - EPI_j| / (|EPI_i| + |EPI_j| + ε)`
     - Sense index similarity: `1 - |Si_i - Si_j|`
     - Edge added if `compatibility ≥ UM_COMPAT_THRESHOLD` (default: 0.75)
+  - Set `UM_FUNCTIONAL_LINKS=False` to disable link creation (edge case: phase-only sync)
   - `EPI`, `νf`, `ΔNFR` remain unchanged
 - **Structural Effect**: Aligns node phase with neighbor mean, enables structural coupling
 - **TNFR Invariants**:

docs/source/user-guide/OPERATORS_GUIDE.md

@@ -224,7 +224,7 @@ print(f"ΔNFR after coupling: {dnfr1:.3f} (reduced by mutual stabilization)")
 - `UM_BIDIRECTIONAL`: Enable bidirectional phase sync (default: True)
 - `UM_SYNC_VF`: Enable frequency synchronization (default: True)
 - `UM_STABILIZE_DNFR`: Enable ΔNFR stabilization (default: True)
-- `UM_FUNCTIONAL_LINKS`: Create edges based on compatibility (default: False)
+- `UM_FUNCTIONAL_LINKS`: Create edges based on compatibility (default: True)
 
 **Contracts**:
 - Must verify phase compatibility before coupling

src/tnfr/operators/__init__.py

@@ -739,7 +739,7 @@ def _op_UM(node: NodeProtocol, gf: GlyphFactors) -> None:  # UM — Coupling
                 reduction_factor = 1.0 - (k_dnfr * mean_alignment)
                 node.dnfr = node.dnfr * reduction_factor
 
-    if bool(node.graph.get("UM_FUNCTIONAL_LINKS", False)):
+    if bool(node.graph.get("UM_FUNCTIONAL_LINKS", True)):
         thr = float(
             node.graph.get(
                 "UM_COMPAT_THRESHOLD",

tests/unit/dynamics/test_operators.py

@@ -280,6 +280,45 @@ def test_um_candidate_subset_proximity(graph_canon):
     assert not G.has_edge(0, 3)
 
 
+def test_um_functional_links_enabled_by_default(graph_canon):
+    """UM operator creates functional links by default (canonical behavior)."""
+    G = graph_canon()
+    inject_defaults(G)
+    # Create nodes with similar phase, EPI, and Si for high compatibility
+    for i, th in enumerate([0.0, 0.05, 0.1]):
+        G.add_node(i, **{"theta": th, "EPI": 1.0, "Si": 0.8})
+
+    # Lower threshold to ensure links are created for testing
+    G.graph["UM_COMPAT_THRESHOLD"] = 0.5
+
+    # Apply UM without explicitly setting UM_FUNCTIONAL_LINKS
+    # Links should be created by default
+    apply_glyph(G, 0, "UM")
+
+    # Verify that at least one link was created
+    # (exact number depends on compatibility calculation)
+    assert G.number_of_edges() > 0, "UM should create functional links by default"
+
+
+def test_um_functional_links_can_be_disabled(graph_canon):
+    """UM operator respects explicit UM_FUNCTIONAL_LINKS=False (edge case)."""
+    G = graph_canon()
+    inject_defaults(G)
+    # Create nodes with similar phase, EPI, and Si for high compatibility
+    for i, th in enumerate([0.0, 0.05, 0.1]):
+        G.add_node(i, **{"theta": th, "EPI": 1.0, "Si": 0.8})
+
+    # Explicitly disable functional links (edge case for phase-only sync)
+    G.graph["UM_FUNCTIONAL_LINKS"] = False
+    G.graph["UM_COMPAT_THRESHOLD"] = 0.5
+
+    # Apply UM with links explicitly disabled
+    apply_glyph(G, 0, "UM")
+
+    # Verify that no links were created
+    assert G.number_of_edges() == 0, "UM should respect UM_FUNCTIONAL_LINKS=False"
+
+
 def test_um_candidate_iter_missing_nodenx(monkeypatch):
     class DummyNode:
         def __init__(self) -> None: