tnfr 4.5.2__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/operators/postconditions/__init__.py

@@ -0,0 +1,38 @@
+"""Postcondition validators for TNFR structural operators.
+
+Each operator has specific guarantees that must be verified after execution
+to ensure TNFR structural invariants are maintained. This package provides
+postcondition validators for operators that need strict verification.
+
+Postconditions ensure that operators fulfill their contracts and maintain
+canonical TNFR physics.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...types import NodeId, TNFRGraph
+
+__all__ = [
+    "OperatorContractViolation",
+]
+
+
+class OperatorContractViolation(Exception):
+    """Raised when an operator's postconditions are violated."""
+
+    def __init__(self, operator: str, reason: str) -> None:
+        """Initialize contract violation error.
+
+        Parameters
+        ----------
+        operator : str
+            Name of the operator that violated its contract
+        reason : str
+            Description of why the contract was violated
+        """
+        self.operator = operator
+        self.reason = reason
+        super().__init__(f"{operator} contract violation: {reason}")

tnfr/operators/postconditions/mutation.py

@@ -0,0 +1,236 @@
+"""Postcondition validators for ZHIR (Mutation) operator.
+
+Implements verification of mutation postconditions including phase transformation,
+identity preservation, and bifurcation handling.
+
+These postconditions ensure that ZHIR fulfills its contract and maintains TNFR
+structural invariants.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...types import NodeId, TNFRGraph
+
+from ...alias import get_attr
+from ...constants.aliases import ALIAS_THETA
+from . import OperatorContractViolation
+
+__all__ = [
+    "verify_phase_transformed",
+    "verify_identity_preserved",
+    "verify_bifurcation_handled",
+]
+
+
+def verify_phase_transformed(
+    G: TNFRGraph, node: NodeId, theta_before: float
+) -> None:
+    """Verify that phase was actually transformed by ZHIR.
+    
+    ZHIR's primary contract is phase transformation (θ → θ'). This verifies
+    that the phase actually changed, fulfilling the operator's purpose.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to verify
+    theta_before : float
+        Phase value before ZHIR application
+    
+    Raises
+    ------
+    OperatorContractViolation
+        If phase was not transformed (theta unchanged)
+    
+    Notes
+    -----
+    A small tolerance (1e-6) is used to account for floating-point precision.
+    If theta changes by less than this tolerance, it's considered unchanged.
+    
+    This check ensures that ZHIR actually performs its structural transformation
+    rather than being a no-op.
+    
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.operators import Mutation
+    >>> G, node = create_nfr("test", epi=0.5, vf=1.0, theta=0.0)
+    >>> theta_before = G.nodes[node]["theta"]
+    >>> Mutation()(G, node)
+    >>> verify_phase_transformed(G, node, theta_before)  # Should pass
+    """
+    theta_after = float(get_attr(G.nodes[node], ALIAS_THETA, 0.0))
+    
+    # Check if phase actually changed (with small tolerance for floating-point)
+    if abs(theta_after - theta_before) < 1e-6:
+        raise OperatorContractViolation(
+            "Mutation",
+            f"Phase was not transformed (θ before={theta_before:.6f}, "
+            f"θ after={theta_after:.6f}, diff={abs(theta_after - theta_before):.9f}). "
+            f"ZHIR must transform phase to fulfill its contract."
+        )
+
+
+def verify_identity_preserved(
+    G: TNFRGraph, node: NodeId, epi_kind_before: str | None
+) -> None:
+    """Verify that structural identity (epi_kind) was preserved through mutation.
+    
+    ZHIR transforms phase/regime while preserving structural identity. A cell
+    remains a cell, a concept remains a concept - only the operational mode changes.
+    This is a fundamental TNFR invariant: transformations preserve coherence.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to verify
+    epi_kind_before : str or None
+        Identity (epi_kind) before ZHIR application
+    
+    Raises
+    ------
+    OperatorContractViolation
+        If identity changed during mutation
+    
+    Notes
+    -----
+    If epi_kind_before is None (identity not tracked), this check is skipped.
+    This allows flexibility for simple nodes while enforcing identity preservation
+    when it's explicitly tracked.
+    
+    **Special Case**: If epi_kind is used to track operator glyphs (common pattern),
+    the check is skipped since this is operational metadata, not structural identity.
+    To enable strict identity checking, use a separate attribute (e.g., "structural_type"
+    or "node_type") for identity tracking.
+    
+    Identity preservation is distinct from EPI preservation - EPI may change
+    slightly during mutation (structural adjustments), but the fundamental type
+    (epi_kind) must remain constant.
+    
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.operators import Mutation
+    >>> G, node = create_nfr("test", epi=0.5, vf=1.0)
+    >>> G.nodes[node]["structural_type"] = "stem_cell"  # Use separate attribute
+    >>> epi_kind_before = G.nodes[node]["structural_type"]
+    >>> Mutation()(G, node)
+    >>> # After mutation, structural_type should still be "stem_cell"
+    >>> # verify_identity_preserved(G, node, epi_kind_before)  # Would check structural_type
+    """
+    # Skip check if identity was not tracked
+    if epi_kind_before is None:
+        return
+    
+    epi_kind_after = G.nodes[node].get("epi_kind")
+    
+    # Skip if epi_kind appears to be tracking operator glyphs (common pattern)
+    # Operator glyphs are short codes like "IL", "OZ", "ZHIR"
+    if epi_kind_after in ["IL", "EN", "AL", "OZ", "RA", "UM", "SHA", "VAL", "NUL", "THOL", "ZHIR", "NAV", "REMESH"]:
+        # epi_kind is being used for operator tracking, not identity
+        # This is acceptable operational metadata, skip identity check
+        return
+    
+    if epi_kind_after != epi_kind_before:
+        raise OperatorContractViolation(
+            "Mutation",
+            f"Structural identity changed during mutation: "
+            f"{epi_kind_before} → {epi_kind_after}. "
+            f"ZHIR must preserve epi_kind while transforming phase."
+        )
+
+
+def verify_bifurcation_handled(G: TNFRGraph, node: NodeId) -> None:
+    """Verify that bifurcation was handled if triggered during mutation.
+    
+    When ZHIR detects bifurcation potential (∂²EPI/∂t² > τ), it must either:
+    1. Create a variant node (if bifurcation mode = "variant_creation")
+    2. Set detection flag (if bifurcation mode = "detection")
+    
+    This ensures that bifurcation events are properly tracked and controlled,
+    preventing uncontrolled structural fragmentation.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to verify
+    
+    Raises
+    ------
+    OperatorContractViolation
+        If bifurcation was triggered but not handled according to configured mode
+    
+    Notes
+    -----
+    **Bifurcation Modes**:
+    
+    - "detection" (default): Only flag bifurcation potential, no variant creation
+    - "variant_creation": Create new node as bifurcation variant
+    
+    In "variant_creation" mode, the function verifies that a bifurcation event
+    was recorded in G.graph["zhir_bifurcation_events"].
+    
+    Grammar rule U4a requires bifurcation handlers (THOL or IL) after ZHIR
+    when bifurcation is detected.
+    
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.operators import Mutation
+    >>> G, node = create_nfr("test", epi=0.5, vf=1.0)
+    >>> G.graph["ZHIR_BIFURCATION_MODE"] = "detection"
+    >>> Mutation()(G, node)
+    >>> # If bifurcation detected, flag should be set
+    >>> verify_bifurcation_handled(G, node)  # Should pass
+    """
+    # Check if bifurcation was detected
+    bifurcation_potential = G.nodes[node].get("_zhir_bifurcation_potential", False)
+    
+    if not bifurcation_potential:
+        # No bifurcation detected, nothing to verify
+        return
+    
+    # Bifurcation was detected - verify it was handled
+    mode = G.graph.get("ZHIR_BIFURCATION_MODE", "detection")
+    
+    if mode == "variant_creation":
+        # In variant creation mode, verify variant was actually created
+        events = G.graph.get("zhir_bifurcation_events", [])
+        
+        # Check if this node has a recorded bifurcation event
+        node_has_event = any(
+            event.get("parent_node") == node
+            for event in events
+        )
+        
+        if not node_has_event:
+            raise OperatorContractViolation(
+                "Mutation",
+                f"Bifurcation potential detected (∂²EPI/∂t² > τ) but variant "
+                f"was not created. Mode={mode} requires variant creation. "
+                f"Check _spawn_mutation_variant() implementation."
+            )
+    
+    elif mode == "detection":
+        # In detection mode, just verify the flag is set (already checked above)
+        # No variant creation required, flag is sufficient
+        pass
+    
+    else:
+        # Unknown mode - log warning but don't raise error
+        import warnings
+        warnings.warn(
+            f"Unknown ZHIR_BIFURCATION_MODE: {mode}. "
+            f"Expected 'detection' or 'variant_creation'. "
+            f"Bifurcation handling could not be fully verified.",
+            stacklevel=2,
+        )