Add comprehensive U4b audit report documentation

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

Author: Copilot

U4B_AUDIT_REPORT.md

@@ -0,0 +1,377 @@
+# U4b Grammar Validation Audit - Final Report
+
+**Date**: 2025-11-09  
+**Issue**: [ZHIR][Testing] Auditoría completa de validación de grammar U4b para mutaciones  
+**Status**: ✅ COMPLETE - All requirements met
+
+---
+
+## Executive Summary
+
+Complete audit and implementation of U4b grammar validation for ZHIR (Mutation) operator. All critical gaps identified and fixed, comprehensive test coverage added (22/22 tests passing).
+
+**U4b Requirements** (AGENTS.md, UNIFIED_GRAMMAR_RULES.md):
+1. **Prior IL (Coherence)**: Stable base for transformation
+2. **Recent destabilizer**: Threshold energy within ~3 operators
+
+---
+
+## Audit Findings
+
+### Gap #1: Missing `unified_grammar.py` Module ⚠️ **HIGH PRIORITY**
+**Status**: ✅ FIXED
+
+**Problem**:
+- Tests import from `tnfr.operators.unified_grammar` but module didn't exist
+- `ModuleNotFoundError` prevented test execution
+
+**Solution**:
+- Created `src/tnfr/operators/unified_grammar.py` as facade to `grammar.py`
+- Exports `GrammarValidator` as `UnifiedGrammarValidator`
+- Exports operator sets: GENERATORS, CLOSURES, STABILIZERS, etc.
+- Provides `validate_unified()` convenience function
+
+**Evidence**:
+```python
+# Before: ImportError
+from tnfr.operators.unified_grammar import UnifiedGrammarValidator
+
+# After: Works correctly
+validator = UnifiedGrammarValidator()
+valid, messages = validator.validate(sequence)
+```
+
+---
+
+### Gap #2: `validate_mutation()` Does NOT Validate IL Precedence ⚠️ **HIGH PRIORITY**
+**Status**: ✅ FIXED
+
+**Problem**:
+- Function only recorded context, never enforced IL requirement
+- ZHIR could execute without stable base, violating U4b
+- Soft warning only, no validation error
+
+**Solution**:
+Enhanced `validate_mutation()` with strict IL precedence check:
+
+```python
+# Added to validate_mutation() (lines 1101-1126)
+if require_il:  # When strict validation enabled
+    glyph_history = G.nodes[node].get("glyph_history", [])
+    history_names = [glyph_function_name(g) for g in glyph_history]
+    il_found = "coherence" in history_names
+    
+    if not il_found:
+        raise OperatorPreconditionError(
+            "Mutation",
+            "U4b violation: ZHIR requires prior IL (Coherence) for stable transformation base..."
+        )
+```
+
+**Configuration**:
+- `VALIDATE_OPERATOR_PRECONDITIONS=True`: Enable all strict checks
+- `ZHIR_REQUIRE_IL_PRECEDENCE=True`: Enable IL check independently
+
+**Test Coverage**:
+- ✅ `test_zhir_without_il_fails_with_strict_validation`
+- ✅ `test_zhir_with_il_passes_strict_validation`
+- ✅ `test_zhir_il_anywhere_in_history_satisfies`
+
+---
+
+### Gap #3: `_record_destabilizer_context()` Only Logs, Doesn't Validate ⚠️ **MEDIUM PRIORITY**
+**Status**: ✅ FIXED
+
+**Problem**:
+- Function searches for destabilizers and stores context
+- Only logs warning if none found, never raises error
+- Invalid sequences pass validation
+
+**Solution**:
+Added destabilizer requirement check to `validate_mutation()`:
+
+```python
+# Added after _record_destabilizer_context() call (lines 1133-1145)
+if require_destabilizer:  # When strict validation enabled
+    context = G.nodes[node].get("_mutation_context", {})
+    destabilizer_found = context.get("destabilizer_operator")
+    
+    if destabilizer_found is None:
+        raise OperatorPreconditionError(
+            "Mutation",
+            "U4b violation: ZHIR requires recent destabilizer (OZ/VAL/etc) within ~3 ops..."
+        )
+```
+
+**Configuration**:
+- `VALIDATE_OPERATOR_PRECONDITIONS=True`: Enable all strict checks
+- `ZHIR_REQUIRE_DESTABILIZER=True`: Enable destabilizer check independently
+
+**Test Coverage**:
+- ✅ `test_zhir_without_destabilizer_fails_with_strict_validation`
+- ✅ `test_zhir_with_recent_dissonance_passes`
+- ✅ `test_zhir_with_recent_expansion_passes`
+
+---
+
+### Gap #4: Grammar Validator Not Integrated with Preconditions ℹ️ **INFORMATIONAL**
+**Status**: ✅ DOCUMENTED
+
+**Finding**:
+- `grammar.py::validate_transformer_context()` exists and correctly validates U4b
+- Located at lines 703-780, properly checks:
+  - Recent destabilizer within ~3 ops
+  - Prior IL for ZHIR specifically
+- Separate from runtime precondition validation (different use case)
+
+**Use Cases**:
+- Grammar validation: Sequence validation before execution
+- Precondition validation: Runtime checks during execution
+- Both now aligned on U4b requirements
+
+**No action required**: Design is correct, both systems serve different purposes
+
+---
+
+## Critical Bug Fix: `glyph_function_name()`
+
+### Problem
+`Glyph` enum inherits from both `str` and `Enum`:
+```python
+class Glyph(str, Enum):
+    AL = "AL"
+    IL = "IL"
+    ...
+```
+
+Original function checked `isinstance(val, str)` first, which matched Glyph instances, returning them unchanged instead of converting to function names ('IL' instead of 'coherence').
+
+### Solution
+Check for `Enum` type BEFORE checking for `str`:
+
+```python
+def glyph_function_name(val, *, default=None):
+    if val is None:
+        return default
+    # Check Enum FIRST (before str, since Glyph inherits from str)
+    if isinstance(val, Enum):
+        return GLYPH_TO_FUNCTION.get(val, default)
+    if isinstance(val, str):
+        # Convert glyph string values ('IL' → 'coherence')
+        # Or pass through function names ('coherence' → 'coherence')
+        ...
+    return GLYPH_TO_FUNCTION.get(val, default)
+```
+
+### Supported Formats
+Now handles three input types correctly:
+1. Glyph enum: `Glyph.IL` → `'coherence'`
+2. Glyph string value: `'IL'` → `'coherence'`
+3. Function name: `'coherence'` → `'coherence'`
+
+---
+
+## Test Coverage
+
+### New Test Suite: `test_zhir_u4b_validation.py`
+**Total**: 22 tests, all passing
+
+#### IL Precedence Tests (6 tests)
+- ✅ Strict validation enforces IL requirement
+- ✅ Soft validation allows without IL (warnings only)
+- ✅ Flag-based control (`ZHIR_REQUIRE_IL_PRECEDENCE`)
+- ✅ IL anywhere in history satisfies requirement
+
+#### Destabilizer Requirement Tests (5 tests)
+- ✅ Strict validation enforces destabilizer requirement
+- ✅ Accepts OZ (Dissonance) destabilizer
+- ✅ Accepts VAL (Expansion) destabilizer
+- ✅ Flag-based control (`ZHIR_REQUIRE_DESTABILIZER`)
+
+#### Graduated Destabilizer Windows (3 tests)
+- ✅ Strong (OZ): window = 4 operators
+- ✅ Moderate (VAL): window = 2 operators
+- ✅ Expired destabilizers correctly rejected
+
+#### Integration Tests (4 tests)
+- ✅ Full sequences with IL + destabilizer requirements
+- ✅ Sequence without IL fails when strict
+- ✅ Sequence without destabilizer fails when strict
+- ✅ Both requirements enforced together
+
+#### Error Messages (2 tests)
+- ✅ IL error shows recent history
+- ✅ Destabilizer error shows recent history
+
+#### Backward Compatibility (2 tests)
+- ✅ Default behavior is soft validation (warnings only)
+- ✅ Independent flag control works
+
+### Existing Tests
+- ✅ `test_unified_grammar.py::TestU4bTransformerContext`: 7/7 passing
+- ✅ `test_mutation_threshold.py`: 12/12 passing
+- ✅ No regressions introduced
+
+---
+
+## Configuration
+
+### Strict Validation (Opt-In)
+```python
+# Enable all strict precondition checks
+G.graph["VALIDATE_OPERATOR_PRECONDITIONS"] = True
+```
+
+### Fine-Grained Control
+```python
+# Enable only IL precedence check
+G.graph["ZHIR_REQUIRE_IL_PRECEDENCE"] = True
+
+# Enable only destabilizer requirement check
+G.graph["ZHIR_REQUIRE_DESTABILIZER"] = True
+```
+
+### Default Behavior
+- **Strict validation OFF by default** (backward compatible)
+- Warnings logged, but no errors raised
+- Telemetry still recorded for analysis
+
+---
+
+## Validation Examples
+
+### Valid Sequence (Strict Mode)
+```python
+G.graph["VALIDATE_OPERATOR_PRECONDITIONS"] = True
+
+# Canonical U4b-compliant sequence
+run_sequence(G, node, [
+    Coherence(),    # ✅ Provides IL precedence (stable base)
+    Dissonance(),   # ✅ Provides destabilizer (threshold energy)
+    Mutation(),     # ✅ Passes all U4b checks
+])
+```
+
+### Invalid: Missing IL
+```python
+G.graph["VALIDATE_OPERATOR_PRECONDITIONS"] = True
+
+# Fails: No prior Coherence
+run_sequence(G, node, [
+    Dissonance(),   # Destabilizer present
+    Mutation(),     # ❌ Raises OperatorPreconditionError - no IL
+])
+# Error: "U4b violation: ZHIR requires prior IL (Coherence) for stable transformation base"
+```
+
+### Invalid: Missing Destabilizer
+```python
+G.graph["VALIDATE_OPERATOR_PRECONDITIONS"] = True
+
+# Fails: No recent destabilizer
+run_sequence(G, node, [
+    Coherence(),    # IL present
+    Silence(),      # Not a destabilizer
+    Mutation(),     # ❌ Raises OperatorPreconditionError - no destabilizer
+])
+# Error: "U4b violation: ZHIR requires recent destabilizer (OZ/VAL/etc) within ~3 ops"
+```
+
+---
+
+## Files Modified
+
+### Created
+1. **src/tnfr/operators/unified_grammar.py**
+   - Facade module for GrammarValidator
+   - Exports UnifiedGrammarValidator, operator sets, validate_unified()
+   - Lines: 107
+
+2. **tests/unit/operators/test_zhir_u4b_validation.py**
+   - Comprehensive U4b test suite
+   - 22 tests covering all requirements
+   - Lines: 450+
+
+### Modified
+3. **src/tnfr/operators/preconditions/__init__.py**
+   - Enhanced `validate_mutation()` with U4b checks (lines 1045-1145)
+   - Added IL precedence validation (lines 1101-1126)
+   - Added destabilizer requirement validation (lines 1133-1145)
+   - 100 lines modified
+
+4. **src/tnfr/operators/grammar.py**
+   - Fixed `glyph_function_name()` for str-based Glyph enum (lines 90-140)
+   - Added Glyph string value support ('IL' → 'coherence')
+   - 50 lines modified
+
+---
+
+## Physics Compliance
+
+### U4b: Transformers Need Context (UNIFIED_GRAMMAR_RULES.md)
+
+**Physical Basis**:
+Bifurcations are phase transitions requiring threshold energy. Like water→ice:
+- **Temperature threshold**: Destabilizer provides energy (ΔNFR elevation)
+- **Nucleation site**: IL provides stable base for transformation
+- **Proper conditions**: Handlers manage transition
+
+**Implementation**:
+- ✅ IL precedence check enforces stable base requirement
+- ✅ Destabilizer window check enforces threshold energy requirement
+- ✅ Graduated windows (strong/moderate/weak) match ΔNFR decay physics
+- ✅ Soft validation default preserves backward compatibility
+
+---
+
+## Recommendations
+
+### For Production Use
+1. **Enable strict validation** for new code:
+   ```python
+   G.graph["VALIDATE_OPERATOR_PRECONDITIONS"] = True
+   ```
+
+2. **Gradual migration** for existing code:
+   - Start with warnings (default)
+   - Enable specific flags per operator
+   - Full strict validation when ready
+
+3. **Monitor telemetry**:
+   - Check `_mutation_context` for destabilizer info
+   - Review warnings before enabling strict mode
+
+### For Testing
+1. Use `test_zhir_u4b_validation.py` as reference
+2. Test both strict and soft validation modes
+3. Verify error messages are helpful
+
+---
+
+## Conclusion
+
+**All U4b requirements successfully implemented and tested**:
+- ✅ IL precedence validation
+- ✅ Destabilizer requirement validation
+- ✅ Graduated destabilizer windows
+- ✅ Comprehensive test coverage (22/22 passing)
+- ✅ Backward compatible (strict mode opt-in)
+- ✅ Physics-compliant implementation
+
+**No breaking changes**: Default behavior unchanged, strict validation is opt-in.
+
+**Ready for production**: All canonical requirements met, fully tested.
+
+---
+
+## References
+
+- **AGENTS.md**: §U4b (Transformers Need Context)
+- **UNIFIED_GRAMMAR_RULES.md**: U4b physics derivation
+- **Source Code**:
+  - `src/tnfr/operators/preconditions/__init__.py:1045-1145`
+  - `src/tnfr/operators/grammar.py:90-140`
+  - `src/tnfr/operators/unified_grammar.py`
+- **Tests**:
+  - `tests/unit/operators/test_zhir_u4b_validation.py`
+  - `tests/unit/operators/test_unified_grammar.py::TestU4bTransformerContext`