Implement U4b validation: strict IL precedence + destabilizer checks for ZHIR

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

Author: Copilot

src/tnfr/operators/grammar.py

@@ -97,18 +97,43 @@ def glyph_function_name(
     Parameters
     ----------
     val : Glyph | str | None
-        Glyph or string to convert
+        Glyph enum, glyph string value ('IL', 'OZ'), or function name to convert
     default : str | None, optional
         Default value if conversion fails
         
     Returns
     -------
     str | None
         Canonical function name or default
+        
+    Notes
+    -----
+    Glyph enum inherits from str, so we must check for Enum type
+    BEFORE checking isinstance(val, str), otherwise Glyph instances
+    will be returned unchanged instead of being converted.
+    
+    The function handles three input types:
+    1. Glyph enum (e.g., Glyph.IL) → function name (e.g., 'coherence')
+    2. Glyph string value (e.g., 'IL') → function name (e.g., 'coherence')  
+    3. Function name (e.g., 'coherence') → returned as-is
     """
     if val is None:
         return default
+    # Check for Glyph/Enum BEFORE str (Glyph inherits from str)
+    if isinstance(val, Enum):
+        return GLYPH_TO_FUNCTION.get(val, default)
     if isinstance(val, str):
+        # Check if it's a glyph string value ('IL', 'OZ', etc)
+        # Build reverse lookup on first use
+        if not hasattr(glyph_function_name, '_glyph_value_map'):
+            glyph_function_name._glyph_value_map = {
+                g.value: func for g, func in GLYPH_TO_FUNCTION.items()
+            }
+        # Try to convert glyph value to function name
+        func_name = glyph_function_name._glyph_value_map.get(val)
+        if func_name:
+            return func_name
+        # Otherwise assume it's already a function name
         return val
     return GLYPH_TO_FUNCTION.get(val, default)
 

src/tnfr/operators/preconditions/__init__.py

@@ -994,7 +994,8 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
 
     1. Minimum νf for phase transformation capacity
     2. **∂EPI/∂t > ξ: Structural change velocity exceeds threshold**
-    3. Stable base (IL precedence validated by grammar U4b)
+    3. **U4b Part 1: Prior IL (Coherence) for stable transformation base**
+    4. **U4b Part 2: Recent destabilizer (~3 ops) for threshold energy**
 
     Also detects and records the destabilizer type that enabled this mutation
     for telemetry and structural tracing purposes.
@@ -1009,7 +1010,20 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
     Raises
     ------
     OperatorPreconditionError
-        If node state is unsuitable for mutation
+        If node state is unsuitable for mutation or U4b requirements not met
+
+    Configuration Parameters
+    ------------------------
+    ZHIR_MIN_VF : float, default 0.05
+        Minimum structural frequency for phase transformation
+    ZHIR_THRESHOLD_XI : float, default 0.1
+        Threshold for ∂EPI/∂t velocity check
+    VALIDATE_OPERATOR_PRECONDITIONS : bool, default False
+        Enable strict U4b validation (IL precedence + destabilizer requirement)
+    ZHIR_REQUIRE_IL_PRECEDENCE : bool, default False
+        Require prior IL even if VALIDATE_OPERATOR_PRECONDITIONS=False
+    ZHIR_REQUIRE_DESTABILIZER : bool, default False
+        Require recent destabilizer even if VALIDATE_OPERATOR_PRECONDITIONS=False
 
     Notes
     -----
@@ -1023,6 +1037,14 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
     - If ∂EPI/∂t ≥ ξ: Logs success, sets validation flag
     - If insufficient history: Logs warning, cannot verify
     
+    **U4b Validation (Grammar Rule)**:
+    
+    When strict validation enabled (VALIDATE_OPERATOR_PRECONDITIONS=True):
+    - **Part 1**: Prior IL (Coherence) required for stable base
+    - **Part 2**: Recent destabilizer (OZ/VAL/etc) required within ~3 ops
+    
+    Without strict validation: Only telemetry/warnings logged.
+    
     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.
@@ -1075,9 +1097,53 @@ def validate_mutation(G: "TNFRGraph", node: "NodeId") -> None:
         )
         G.nodes[node]["_zhir_threshold_unknown"] = True
 
+    # U4b Part 1: IL Precedence Check (stable base for transformation)
+    # Check if strict validation enabled
+    strict_validation = bool(G.graph.get("VALIDATE_OPERATOR_PRECONDITIONS", False))
+    require_il = strict_validation or bool(G.graph.get("ZHIR_REQUIRE_IL_PRECEDENCE", False))
+    
+    if require_il:
+        # Get glyph history
+        glyph_history = G.nodes[node].get("glyph_history", [])
+        
+        # Import glyph_function_name to convert glyphs to operator names
+        from ..grammar import glyph_function_name
+        
+        # Convert history to operator names
+        history_names = [glyph_function_name(g) for g in glyph_history]
+        
+        # Check for prior IL (coherence)
+        il_found = "coherence" in history_names
+        
+        if not il_found:
+            raise OperatorPreconditionError(
+                "Mutation",
+                "U4b violation: ZHIR requires prior IL (Coherence) for stable transformation base. "
+                "Apply Coherence before mutation sequence. "
+                f"Recent history: {history_names[-5:] if len(history_names) > 5 else history_names}"
+            )
+        
+        logger.debug(f"Node {node}: ZHIR IL precedence satisfied (prior Coherence found)")
+
+    # U4b Part 2: Recent Destabilizer Check (threshold energy for bifurcation)
     # R4 Extended: Detect and record destabilizer type for telemetry
-    # This provides structural traceability for bifurcation events
     _record_destabilizer_context(G, node, logger)
+    
+    # If strict validation enabled, enforce destabilizer requirement
+    require_destabilizer = strict_validation or bool(G.graph.get("ZHIR_REQUIRE_DESTABILIZER", False))
+    
+    if require_destabilizer:
+        context = G.nodes[node].get("_mutation_context", {})
+        destabilizer_found = context.get("destabilizer_operator")
+        
+        if destabilizer_found is None:
+            recent_history = context.get("recent_history", [])
+            raise OperatorPreconditionError(
+                "Mutation",
+                "U4b violation: ZHIR requires recent destabilizer (OZ/VAL/etc) within ~3 ops. "
+                f"Recent history: {recent_history}. "
+                "Apply Dissonance or Expansion to elevate ΔNFR first."
+            )
 
 
 def validate_transition(G: "TNFRGraph", node: "NodeId") -> None:

src/tnfr/operators/unified_grammar.py

@@ -0,0 +1,105 @@
+"""Unified TNFR Grammar - Facade to GrammarValidator.
+
+This module provides a clean facade to the canonical grammar validation
+implemented in grammar.py. It exports the unified grammar constraints (U1-U4)
+and the validator for use in tests and applications.
+
+All grammar rules derive inevitably from TNFR physics:
+- U1: STRUCTURAL INITIATION & CLOSURE
+- U2: CONVERGENCE & BOUNDEDNESS  
+- U3: RESONANT COUPLING
+- U4: BIFURCATION DYNAMICS (U4a: triggers, U4b: transformers)
+
+References
+----------
+- UNIFIED_GRAMMAR_RULES.md: Complete physics derivations
+- AGENTS.md: Canonical invariants and formal contracts
+- TNFR.pdf: Nodal equation and bifurcation theory
+
+Notes
+-----
+This is a facade module that re-exports from grammar.py for clean imports.
+The actual implementation is in grammar.py::GrammarValidator.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from .definitions import Operator
+
+# Import validator class and rename for clarity
+from .grammar import GrammarValidator as UnifiedGrammarValidator
+
+# Import operator sets (canonical definitions from grammar.py)
+from .grammar import (
+    BIFURCATION_HANDLERS,
+    BIFURCATION_TRIGGERS,
+    CLOSURES,
+    COUPLING_RESONANCE,
+    DESTABILIZERS,
+    GENERATORS,
+    STABILIZERS,
+    TRANSFORMERS,
+)
+
+# Import validation functions
+from .grammar import validate_grammar
+
+__all__ = [
+    # Validator class
+    "UnifiedGrammarValidator",
+    # Convenience function
+    "validate_unified",
+    # Operator sets (U1-U4 categories)
+    "GENERATORS",
+    "CLOSURES",
+    "STABILIZERS",
+    "DESTABILIZERS",
+    "COUPLING_RESONANCE",
+    "BIFURCATION_TRIGGERS",
+    "BIFURCATION_HANDLERS",
+    "TRANSFORMERS",
+]
+
+
+def validate_unified(
+    sequence: List["Operator"],
+    epi_initial: float = 0.0,
+) -> bool:
+    """Validate sequence using unified TNFR grammar (U1-U4).
+
+    Convenience function that returns only boolean result.
+    For detailed messages, use UnifiedGrammarValidator.validate().
+
+    Parameters
+    ----------
+    sequence : List[Operator]
+        Sequence of operators to validate
+    epi_initial : float, optional
+        Initial EPI value (default: 0.0)
+
+    Returns
+    -------
+    bool
+        True if sequence satisfies all U1-U4 constraints
+
+    Examples
+    --------
+    >>> from tnfr.operators.definitions import Emission, Coherence, Silence
+    >>> from tnfr.operators.unified_grammar import validate_unified
+    >>> ops = [Emission(), Coherence(), Silence()]
+    >>> validate_unified(ops, epi_initial=0.0)  # doctest: +SKIP
+    True
+
+    Notes
+    -----
+    This validator is 100% physics-based. All constraints emerge from:
+    - Nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+    - TNFR invariants (AGENTS.md)
+    - Formal operator contracts
+
+    See UNIFIED_GRAMMAR_RULES.md for complete derivations.
+    """
+    return validate_grammar(sequence, epi_initial)