Document SHA operator νf reduction in code and add canonical test

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

Author: Copilot

src/tnfr/operators/__init__.py

@@ -965,12 +965,20 @@ def _op_SHA(node: NodeProtocol, gf: GlyphFactors) -> None:  # SHA — Silence
     stillness. EPI, ΔNFR, and phase remain unchanged, signalling a temporary
     suspension of structural evolution.
 
+    **TNFR Canonical Behavior:**
+    
+    According to the nodal equation ∂EPI/∂t = νf · ΔNFR(t), reducing νf → νf_min ≈ 0
+    causes structural evolution to freeze (∂EPI/∂t → 0) regardless of ΔNFR magnitude.
+    This implements **structural silence** - a state where the node's form (EPI) is
+    preserved intact despite external pressures, enabling memory consolidation and
+    protective latency.
+
     Parameters
     ----------
     node : NodeProtocol
         Node whose νf is being attenuated.
     gf : GlyphFactors
-        Provides ``SHA_vf_factor`` to scale νf.
+        Provides ``SHA_vf_factor`` to scale νf (default 0.85 for gradual reduction).
 
     Examples
     --------
@@ -983,6 +991,8 @@ def _op_SHA(node: NodeProtocol, gf: GlyphFactors) -> None:  # SHA — Silence
     0.5
     """
     factor = get_factor(gf, "SHA_vf_factor", 0.85)
+    # Canonical SHA effect: reduce structural frequency toward zero
+    # This implements: νf → νf_min ≈ 0 ⇒ ∂EPI/∂t → 0 (structural preservation)
     node.vf = factor * node.vf
 
 

src/tnfr/operators/grammar.py

@@ -1727,6 +1727,10 @@ def apply_glyph_with_grammar(
 ) -> None:
     """Apply glyph with grammar-based validation and coherence sequence recognition.
     
+    This function is the canonical entry point for applying structural operators through
+    the grammar layer. It enforces TNFR grammar rules, validates operator preconditions,
+    and tracks operator sequences for telemetry.
+    
     Enhanced to recognize and log canonical coherence sequences when they
     occur in the glyph history. This enables pattern detection, telemetry, and
     future optimization of common structural patterns.
@@ -1738,13 +1742,31 @@ def apply_glyph_with_grammar(
     nodes : Optional[Iterable[NodeId | NodeProtocol]]
         Target nodes (all nodes if None)
     glyph : Glyph | str
-        Glyph to apply
+        Glyph to apply (e.g., Glyph.SHA for Silence operator)
     window : Optional[int]
         Hysteresis window (uses graph default if None)
     
     Notes
     -----
-    **Coherence Sequence Recognition** (New):
+    **Structural Operator Effects:**
+    
+    This function delegates to operator-specific implementations that enforce
+    TNFR canonical behavior. Key operator effects include:
+    
+    - **SHA (Silence)**: Reduces νf → νf_min ≈ 0, causing ∂EPI/∂t → 0
+      (structural evolution freezes). EPI preserved intact regardless of ΔNFR.
+      Implements structural silence for memory consolidation and protective latency.
+    
+    - **AL (Emission)**: Increases νf and initiates positive ΔNFR for pattern activation
+    
+    - **IL (Coherence)**: Reduces |ΔNFR| and stabilizes EPI form
+    
+    - **OZ (Dissonance)**: Increases |ΔNFR| for exploration and bifurcation
+    
+    See operator definitions in ``tnfr.operators.definitions`` for complete
+    canonical behavior specifications.
+    
+    **Coherence Sequence Recognition:**
     
     When a glyph is applied, the function checks if it forms a canonical coherence
     sequence with the previous glyph in the node's history. Recognized patterns

tests/unit/operators/test_operator_enhancements.py

@@ -97,6 +97,56 @@ def test_silence_precondition_minimal_vf(self):
         with pytest.raises(OperatorPreconditionError, match="already minimal"):
             Silence()(G, "n1")
 
+    def test_silence_canonical_vf_reduction(self):
+        """SHA - Canonical behavior: νf reduction below threshold with EPI preservation.
+        
+        Validates TNFR canonical invariant for SHA operator:
+        - νf → νf_min ≈ 0 (structural frequency reduction)
+        - EPI(t + Δt) ≈ EPI(t) (form preservation)
+        - ∂EPI/∂t → 0 (structural evolution freezes)
+        
+        This test ensures apply_glyph_with_grammar correctly reduces νf
+        through the operator chain when SHA is applied.
+        """
+        # Create node with active νf and established EPI
+        G = nx.DiGraph()
+        G.add_node("n1", **{EPI_PRIMARY: 0.51, VF_PRIMARY: 1.00})
+        G.graph["SHA_MIN_VF"] = 0.01  # Configure threshold
+        G.graph["SHA_vf_factor"] = 0.85  # Explicit reduction factor
+        
+        # Record state before SHA
+        epi_before = G.nodes["n1"][EPI_PRIMARY]
+        vf_before = G.nodes["n1"][VF_PRIMARY]
+        
+        # Apply SHA through operator (canonical path via grammar layer)
+        Silence()(G, "n1")
+        
+        # Get state after SHA
+        epi_after = G.nodes["n1"][EPI_PRIMARY]
+        vf_after = G.nodes["n1"][VF_PRIMARY]
+        
+        # Validate canonical SHA effects:
+        # 1. νf explicitly reduced (primary effect)
+        assert vf_after < vf_before, "SHA must reduce νf"
+        assert vf_after == pytest.approx(vf_before * 0.85, abs=0.01), \
+            "SHA should reduce νf by configured factor"
+        
+        # 2. νf approaches minimum (structural silence)
+        # After one application: 1.0 * 0.85 = 0.85
+        # We verify it's moving toward zero
+        assert vf_after < 1.0, "νf should decrease toward structural silence"
+        
+        # 3. EPI preserved (form invariance during silence)
+        assert abs(epi_after - epi_before) < 1e-6, \
+            "SHA must preserve EPI (structural form)"
+        
+        # 4. Verify metrics track the reduction (using centralized function)
+        from tnfr.operators.metrics import silence_metrics
+        metrics = silence_metrics(G, "n1", vf_before, epi_before)
+        assert metrics["vf_reduction"] == pytest.approx(vf_before - vf_after, abs=0.01)
+        assert metrics["epi_preservation"] < 1e-6, \
+            "Metrics should confirm EPI preservation"
+
     def test_expansion_precondition_max_vf(self):
         """VAL - Expansion should fail if νf at maximum."""
         G = nx.DiGraph()