Implement ZHIR threshold verification (∂EPI/∂t > ξ) - core implementation

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

Author: Copilot

src/tnfr/operators/definitions.py

@@ -3121,14 +3121,34 @@ class Mutation(Operator):
     random variation, ZHIR is controlled transformation that preserves structural identity
     while shifting operational regime. Critical for adaptation and evolution.
 
+    **Canonical Threshold Requirement (∂EPI/∂t > ξ)**:
+    
+    According to TNFR physics (AGENTS.md §11, TNFR.pdf §2.2.11), ZHIR requires sufficient
+    structural change velocity to justify phase transformation. The threshold ξ (default 0.1)
+    represents the minimum rate of reorganization needed for meaningful mutation.
+    
+    - **∂EPI/∂t ≥ ξ**: Mutation validated, phase transformation proceeds
+    - **∂EPI/∂t < ξ**: Warning logged, mutation may lack structural justification
+    - **Insufficient history**: Warning logged, threshold cannot be verified
+    
+    Configuration: Set ``G.graph["ZHIR_THRESHOLD_XI"]`` to customize threshold (default: 0.1).
+    
+    Metrics: Threshold verification included in mutation_metrics() telemetry:
+    - ``depi_dt``: Computed structural change velocity
+    - ``threshold_met``: Boolean flag indicating threshold status
+    - ``threshold_ratio``: Ratio of velocity to threshold
+
     Use Cases: Paradigm shifts, strategic pivots, adaptive responses, regime transitions,
     identity transformation while maintaining continuity.
 
     Typical Sequences: IL → ZHIR → IL (stabilize-mutate-stabilize), OZ → ZHIR (dissonance
     enables mutation), ZHIR → NAV → IL (mutate-transition-stabilize).
 
-    Preconditions: Requires stable base (often IL), sufficient ΔNFR for phase change,
-    network support for new phase.
+    Preconditions: 
+    - Minimum νf for phase transformation capacity (ZHIR_MIN_VF, default: 0.05)
+    - **Structural velocity threshold (∂EPI/∂t > ξ)** - validated with EPI history
+    - Stable base (often IL) validated by grammar U4b
+    - Network support for new phase
 
     Examples
     --------

src/tnfr/operators/metrics.py

@@ -1546,6 +1546,9 @@ def mutation_metrics(
 ) -> dict[str, Any]:
     """ZHIR - Mutation metrics: phase transition, structural regime change.
 
+    Collects mutation-specific metrics including canonical threshold verification
+    (∂EPI/∂t > ξ) as per TNFR physics (AGENTS.md §11, TNFR.pdf §2.2.11).
+
     Parameters
     ----------
     G : TNFRGraph
@@ -1560,19 +1563,46 @@ def mutation_metrics(
     Returns
     -------
     dict
-        Mutation-specific metrics including phase change indicators
+        Mutation-specific metrics including:
+        - Phase change indicators (theta_shift, phase_change)
+        - EPI change (delta_epi)
+        - **Threshold verification**: depi_dt, threshold_met, threshold_ratio
+        - Structural justification flags
     """
     theta_after = _get_node_attr(G, node, ALIAS_THETA)
     epi_after = _get_node_attr(G, node, ALIAS_EPI)
 
+    # Compute ∂EPI/∂t from history
+    epi_history = G.nodes[node].get("epi_history") or G.nodes[node].get("_epi_history", [])
+    if len(epi_history) >= 2:
+        depi_dt = abs(epi_history[-1] - epi_history[-2])
+    else:
+        depi_dt = 0.0
+
+    # Check threshold
+    xi = float(G.graph.get("ZHIR_THRESHOLD_XI", 0.1))
+    threshold_met = depi_dt >= xi
+    threshold_ratio = depi_dt / xi if xi > 0 else 0.0
+
     return {
         "operator": "Mutation",
         "glyph": "ZHIR",
+        # Existing metrics
         "theta_shift": abs(theta_after - theta_before),
         "theta_final": theta_after,
         "delta_epi": epi_after - epi_before,
         "epi_final": epi_after,
         "phase_change": abs(theta_after - theta_before) > 0.5,  # Configurable threshold
+        # NEW: Threshold verification metrics
+        "depi_dt": depi_dt,
+        "threshold_xi": xi,
+        "threshold_met": threshold_met,
+        "threshold_ratio": threshold_ratio,
+        "threshold_exceeded_by": max(0.0, depi_dt - xi),
+        # Structural justification flags from preconditions
+        "threshold_warning": G.nodes[node].get("_zhir_threshold_warning", False),
+        "threshold_validated": G.nodes[node].get("_zhir_threshold_met", False),
+        "threshold_unknown": G.nodes[node].get("_zhir_threshold_unknown", False),
     }
 
 

src/tnfr/operators/preconditions/__init__.py

@@ -990,6 +990,12 @@ def _record_destabilizer_context(
 def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
     """ZHIR - Mutation requires node to be in valid structural state.
 
+    Implements canonical TNFR requirements for mutation (AGENTS.md §11, TNFR.pdf §2.2.11):
+
+    1. Minimum νf for phase transformation capacity
+    2. **∂EPI/∂t > ξ: Structural change velocity exceeds threshold**
+    3. Stable base (IL precedence validated by grammar U4b)
+
     Also detects and records the destabilizer type that enabled this mutation
     for telemetry and structural tracing purposes.
 
@@ -1007,6 +1013,16 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
 
     Notes
     -----
+    **Canonical threshold verification (∂EPI/∂t > ξ)**:
+    
+    ZHIR is a phase transformation that requires sufficient structural reorganization
+    velocity to justify the transition. The threshold ξ represents the minimum rate
+    of structural change needed for a phase shift to be physically meaningful.
+    
+    - If ∂EPI/∂t < ξ: Logs warning (soft check for backward compatibility)
+    - If ∂EPI/∂t ≥ ξ: Logs success, sets validation flag
+    - If insufficient history: Logs warning, cannot verify
+    
     This function implements R4 Extended telemetry by analyzing the glyph_history
     to determine which destabilizer (strong/moderate/weak) enabled the mutation.
     The destabilizer context is stored in node metadata for structural tracing.
@@ -1024,6 +1040,41 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
             f"Structural frequency too low for mutation (νf={vf:.3f} < {min_vf:.3f})",
         )
 
+    # NEW: Threshold crossing validation (∂EPI/∂t > ξ)
+    # Get EPI history - check both keys for compatibility
+    epi_history = G.nodes[node].get("epi_history") or G.nodes[node].get("_epi_history", [])
+    
+    if len(epi_history) >= 2:
+        # Compute ∂EPI/∂t (discrete approximation using last two points)
+        # For discrete operator applications with Δt=1: ∂EPI/∂t ≈ EPI_t - EPI_{t-1}
+        depi_dt = abs(epi_history[-1] - epi_history[-2])
+        
+        # Get threshold from configuration
+        xi_threshold = float(G.graph.get("ZHIR_THRESHOLD_XI", 0.1))
+        
+        # Verify threshold crossed
+        if depi_dt < xi_threshold:
+            # Allow mutation but log warning (soft check for backward compatibility)
+            logger.warning(
+                f"Node {node}: ZHIR applied with ∂EPI/∂t={depi_dt:.3f} < ξ={xi_threshold}. "
+                f"Mutation may lack structural justification. "
+                f"Consider increasing dissonance (OZ) first."
+            )
+            G.nodes[node]["_zhir_threshold_warning"] = True
+        else:
+            # Threshold met - log success
+            logger.info(
+                f"Node {node}: ZHIR threshold crossed (∂EPI/∂t={depi_dt:.3f} > ξ={xi_threshold})"
+            )
+            G.nodes[node]["_zhir_threshold_met"] = True
+    else:
+        # Insufficient history - cannot verify threshold
+        logger.warning(
+            f"Node {node}: ZHIR applied without sufficient EPI history "
+            f"(need ≥2 points, have {len(epi_history)}). Cannot verify threshold."
+        )
+        G.nodes[node]["_zhir_threshold_unknown"] = True
+
     # R4 Extended: Detect and record destabilizer type for telemetry
     # This provides structural traceability for bifurcation events
     _record_destabilizer_context(G, node, logger)