Merge pull request #2886 from fermga/copilot/implement-canonical-transition-logic

Implement canonical NAV transition logic - regime detection, structural transformations, telemetry

Author: fermga

src/tnfr/operators/definitions.py

@@ -3735,6 +3735,247 @@ class Transition(Operator):
     name: ClassVar[str] = TRANSITION
     glyph: ClassVar[Glyph] = Glyph.NAV
 
+    def __call__(self, G: TNFRGraph, node: Any, **kw: Any) -> None:
+        """Apply NAV with regime detection and controlled transition.
+
+        Implements TNFR.pdf §2.3.11 canonical transition logic:
+        1. Detect current structural regime (latent/active/resonant)
+        2. Handle latency reactivation if node was in silence (SHA → NAV)
+        3. Apply grammar via parent __call__
+        4. Execute regime-specific structural transformation (θ, νf, ΔNFR)
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph storing TNFR nodes and structural operator history.
+        node : Any
+            Identifier or object representing the target node within ``G``.
+        **kw : Any
+            Additional keyword arguments:
+            - phase_shift (float): Override default phase shift per regime
+            - vf_factor (float): Override νf scaling for active regime (default: 1.0)
+            - Other args forwarded to grammar layer via parent __call__
+
+        Notes
+        -----
+        Regime-specific transformations (TNFR.pdf §2.3.11):
+
+        **Latent → Active** (νf < 0.05 or latent flag):
+        - νf × 1.2 (20% increase for gradual reactivation)
+        - θ + 0.1 rad (small phase shift)
+        - ΔNFR × 0.7 (30% reduction for smooth transition)
+
+        **Active** (baseline state):
+        - νf × vf_factor (default 1.0, configurable)
+        - θ + 0.2 rad (standard phase shift)
+        - ΔNFR × 0.8 (20% reduction)
+
+        **Resonant → Active** (EPI > 0.5 AND νf > 0.8):
+        - νf × 0.95 (5% reduction for stability)
+        - θ + 0.15 rad (careful phase shift)
+        - ΔNFR × 0.9 (10% reduction, gentle)
+
+        Telemetry stored in G.graph["_nav_transitions"] tracks:
+        - regime_origin, vf_before/after, theta_before/after, dnfr_before/after
+        """
+        from ..alias import get_attr, set_attr
+        from ..constants.aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_VF
+
+        # 1. Detect current regime
+        current_regime = self._detect_regime(G, node)
+
+        # 2. Handle latency reactivation if applicable
+        if G.nodes[node].get("latent", False):
+            self._handle_latency_transition(G, node)
+
+        # 3. Apply grammar base (delegates to parent which calls apply_glyph_with_grammar)
+        super().__call__(G, node, **kw)
+
+        # 4. Execute structural transition
+        self._apply_structural_transition(G, node, current_regime, **kw)
+
+    def _detect_regime(self, G: TNFRGraph, node: Any) -> str:
+        """Detect current structural regime: latent/active/resonant.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the node.
+        node : Any
+            Target node.
+
+        Returns
+        -------
+        str
+            Regime classification: "latent", "active", or "resonant"
+
+        Notes
+        -----
+        Classification criteria:
+        - **Latent**: latent flag set OR νf < 0.05 (minimal reorganization capacity)
+        - **Resonant**: EPI > 0.5 AND νf > 0.8 (high form + high frequency)
+        - **Active**: Default (baseline operational state)
+        """
+        from ..alias import get_attr
+        from ..constants.aliases import ALIAS_EPI, ALIAS_VF
+
+        epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+        vf = float(get_attr(G.nodes[node], ALIAS_VF, 0.0))
+        latent = G.nodes[node].get("latent", False)
+
+        if latent or vf < 0.05:
+            return "latent"
+        elif epi > 0.5 and vf > 0.8:
+            return "resonant"
+        else:
+            return "active"
+
+    def _handle_latency_transition(self, G: TNFRGraph, node: Any) -> None:
+        """Handle transition from latent state (SHA → NAV flow).
+
+        Similar to Emission._check_reactivation but for NAV-specific transitions.
+        Validates silence duration and clears latency attributes.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the node.
+        node : Any
+            Target node being reactivated.
+
+        Warnings
+        --------
+        - Warns if node transitioning after extended silence (duration > MAX_SILENCE_DURATION)
+        - Warns if EPI drifted significantly during silence (> 1% tolerance)
+
+        Notes
+        -----
+        Clears latency-related attributes:
+        - latent (flag)
+        - latency_start_time (ISO timestamp)
+        - preserved_epi (EPI snapshot from SHA)
+        - silence_duration (computed duration)
+        """
+        from datetime import datetime, timezone
+
+        # Verify silence duration if timestamp available
+        if "latency_start_time" in G.nodes[node]:
+            start = datetime.fromisoformat(G.nodes[node]["latency_start_time"])
+            duration = (datetime.now(timezone.utc) - start).total_seconds()
+            G.nodes[node]["silence_duration"] = duration
+
+            max_silence = G.graph.get("MAX_SILENCE_DURATION", float("inf"))
+            if duration > max_silence:
+                warnings.warn(
+                    f"Node {node} transitioning after extended silence "
+                    f"(duration: {duration:.2f}s, max: {max_silence:.2f}s)",
+                    stacklevel=4,
+                )
+
+        # Check EPI preservation integrity
+        preserved_epi = G.nodes[node].get("preserved_epi")
+        if preserved_epi is not None:
+            from ..alias import get_attr
+            from ..constants.aliases import ALIAS_EPI
+
+            current_epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+            epi_drift = abs(current_epi - preserved_epi)
+
+            # Allow small numerical drift (1% tolerance)
+            if epi_drift > 0.01 * abs(preserved_epi):
+                warnings.warn(
+                    f"Node {node} EPI drifted during silence "
+                    f"(preserved: {preserved_epi:.3f}, current: {current_epi:.3f}, "
+                    f"drift: {epi_drift:.3f})",
+                    stacklevel=4,
+                )
+
+        # Clear latency state
+        del G.nodes[node]["latent"]
+        if "latency_start_time" in G.nodes[node]:
+            del G.nodes[node]["latency_start_time"]
+        if "preserved_epi" in G.nodes[node]:
+            del G.nodes[node]["preserved_epi"]
+        if "silence_duration" in G.nodes[node]:
+            # Keep silence_duration for telemetry
+            pass
+
+    def _apply_structural_transition(
+        self, G: TNFRGraph, node: Any, regime: str, **kw: Any
+    ) -> None:
+        """Apply structural transformation based on regime origin.
+
+        Parameters
+        ----------
+        G : TNFRGraph
+            Graph containing the node.
+        node : Any
+            Target node.
+        regime : str
+            Origin regime: "latent", "active", or "resonant"
+        **kw : Any
+            Optional overrides:
+            - phase_shift (float): Custom phase shift
+            - vf_factor (float): Custom νf scaling for active regime
+
+        Notes
+        -----
+        Applies regime-specific transformations to θ, νf, and ΔNFR following
+        TNFR.pdf §2.3.11. All changes use canonical alias system (set_attr)
+        to ensure proper attribute resolution.
+
+        Telemetry appended to G.graph["_nav_transitions"] for analysis.
+        """
+        from ..alias import get_attr, set_attr
+        from ..constants.aliases import ALIAS_DNFR, ALIAS_THETA, ALIAS_VF
+
+        # Get current state
+        theta = float(get_attr(G.nodes[node], ALIAS_THETA, 0.0))
+        vf = float(get_attr(G.nodes[node], ALIAS_VF, 1.0))
+        dnfr = float(get_attr(G.nodes[node], ALIAS_DNFR, 0.0))
+
+        # Apply regime-specific adjustments
+        if regime == "latent":
+            # Latent → Active: gradual reactivation
+            vf_new = vf * 1.2  # 20% increase
+            theta_shift = kw.get("phase_shift", 0.1)  # Small phase shift
+            theta_new = (theta + theta_shift) % (2 * math.pi)
+            dnfr_new = dnfr * 0.7  # 30% reduction for smooth transition
+        elif regime == "active":
+            # Active: standard transition
+            vf_new = vf * kw.get("vf_factor", 1.0)  # Configurable
+            theta_shift = kw.get("phase_shift", 0.2)  # Standard shift
+            theta_new = (theta + theta_shift) % (2 * math.pi)
+            dnfr_new = dnfr * 0.8  # 20% reduction
+        else:  # resonant
+            # Resonant → Active: careful transition (high energy state)
+            vf_new = vf * 0.95  # 5% reduction for stability
+            theta_shift = kw.get("phase_shift", 0.15)  # Careful phase shift
+            theta_new = (theta + theta_shift) % (2 * math.pi)
+            dnfr_new = dnfr * 0.9  # 10% reduction, gentle
+
+        # Apply changes via canonical alias system
+        set_attr(G.nodes[node], ALIAS_VF, vf_new)
+        set_attr(G.nodes[node], ALIAS_THETA, theta_new)
+        set_attr(G.nodes[node], ALIAS_DNFR, dnfr_new)
+
+        # Telemetry tracking
+        if "_nav_transitions" not in G.graph:
+            G.graph["_nav_transitions"] = []
+        G.graph["_nav_transitions"].append(
+            {
+                "node": node,
+                "regime_origin": regime,
+                "vf_before": vf,
+                "vf_after": vf_new,
+                "theta_before": theta,
+                "theta_after": theta_new,
+                "dnfr_before": dnfr,
+                "dnfr_after": dnfr_new,
+                "phase_shift": theta_new - theta,
+            }
+        )
+
     def _validate_preconditions(self, G: TNFRGraph, node: Any) -> None:
         """Validate NAV-specific preconditions."""
         from .preconditions import validate_transition

src/tnfr/validation/sequence_validator.py

@@ -35,13 +35,17 @@ def __init__(self) -> None:
             "invalid_transition_sequence": {
                 "pattern": ["transition"],
                 "not_preceded_by": [
+                    "emission",  # AL → NAV (activate-transition)
+                    "silence",  # SHA → NAV (latency-transition)
+                    "coherence",  # IL → NAV (stabilize-transition)
                     "dissonance",
                     "mutation",
                     "resonance",
                     "transition",
+                    "reception",  # EN → NAV (integrate-transition)
                 ],
                 "severity": InvariantSeverity.ERROR,
-                "message": "Transition requires structural perturbation (dissonance, mutation) or coherent propagation (resonance)",
+                "message": "Transition requires prior structural context (emission, coherence, perturbation, or propagation)",
             },
             "resonance_without_coupling": {
                 "pattern": ["resonance"],