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

tnfr/validation/compatibility.py

@@ -0,0 +1,460 @@
+"""Canonical TNFR compatibility tables expressed via structural operators."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from ..config.operator_names import (
+    COHERENCE,
+    CONTRACTION,
+    COUPLING,
+    DISSONANCE,
+    EMISSION,
+    EXPANSION,
+    MUTATION,
+    RECEPTION,
+    RECURSIVITY,
+    RESONANCE,
+    SELF_ORGANIZATION,
+    SILENCE,
+    TRANSITION,
+)
+from ..operators import grammar as _grammar
+from ..types import Glyph
+
+__all__ = [
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "CompatibilityLevel",
+    "GRADUATED_COMPATIBILITY",
+    "get_compatibility_level",
+]
+
+
+class CompatibilityLevel(Enum):
+    """Graduated compatibility levels for structural operator transitions.
+
+    Reflects the theoretical richness of TNFR by distinguishing between
+    optimal, acceptable, contextual, and incompatible transitions.
+
+    Attributes
+    ----------
+    EXCELLENT : str
+        Optimal transition that directly supports structural coherence.
+        Example: EMISSION → COHERENCE (initiation → stabilization)
+    GOOD : str
+        Acceptable transition that maintains structural integrity.
+        Example: EMISSION → RESONANCE (initiation → amplification)
+    CAUTION : str
+        Contextually dependent transition requiring careful validation.
+        Example: EMISSION → DISSONANCE (initiation → tension)
+        Generates warnings to alert users of potential incoherence.
+    AVOID : str
+        Incompatible transition that violates structural coherence.
+        Example: SILENCE → DISSONANCE (pause → tension is contradictory)
+        Raises SequenceSyntaxError when encountered.
+    """
+
+    EXCELLENT = "excellent"
+    GOOD = "good"
+    CAUTION = "caution"
+    AVOID = "avoid"
+
+
+# Graduated compatibility matrix expressing structural operator transition quality
+# Maps each operator to its allowed next operators categorized by compatibility level
+GRADUATED_COMPATIBILITY: dict[str, dict[str, list[str]]] = {
+    # EMISSION (AL) - Initiates resonant patterns, seeds coherence outward
+    EMISSION: {
+        "excellent": [
+            COHERENCE,
+            TRANSITION,
+            RECEPTION,
+        ],  # Initiation → stabilization/handoff/anchoring
+        "good": [RESONANCE, EXPANSION, COUPLING],  # Amplification, exploration, linking
+        "caution": [DISSONANCE],  # Direct tension after initiation requires context
+        "avoid": [
+            SILENCE,
+            EMISSION,
+            MUTATION,
+            CONTRACTION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+        ],
+    },
+    # RECEPTION (EN) - Anchors inbound energy into the EPI
+    RECEPTION: {
+        "excellent": [
+            COHERENCE,
+            COUPLING,
+            SELF_ORGANIZATION,
+        ],  # Anchoring → stabilization/linking/autonomous cascades
+        "good": [RESONANCE],  # Amplification after receiving
+        "caution": [],
+        "avoid": [
+            SILENCE,
+            EMISSION,
+            DISSONANCE,
+            EXPANSION,
+            CONTRACTION,
+            MUTATION,
+            TRANSITION,
+            RECURSIVITY,
+            RECEPTION,
+        ],
+    },
+    # COHERENCE (IL) - Compresses ΔNFR drift to stabilize C(t)
+    COHERENCE: {
+        "excellent": [
+            RESONANCE,
+            EXPANSION,
+            COUPLING,
+        ],  # Stability → amplification/exploration/linking
+        "good": [
+            SILENCE,
+            TRANSITION,
+            CONTRACTION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+        ],  # Valid progressions
+        "caution": [
+            MUTATION,
+            DISSONANCE,
+        ],  # Post-stabilization tension/mutation needs context
+        "avoid": [
+            EMISSION,
+            RECEPTION,
+            COHERENCE,
+        ],  # Cannot re-initiate, re-anchor, or re-stabilize
+    },
+    # DISSONANCE (OZ) - Injects controlled tension for probes
+    DISSONANCE: {
+        "excellent": [
+            MUTATION,
+            TRANSITION,
+            SELF_ORGANIZATION,
+        ],  # Tension → transformation/handoff/reorganization
+        "good": [
+            CONTRACTION,
+            RESONANCE,
+            RECURSIVITY,
+            COHERENCE,
+        ],  # Concentration, amplification, fractal echo, stabilization
+        "caution": [DISSONANCE],  # Repeated dissonance needs careful management
+        "avoid": [SILENCE, EMISSION, RECEPTION, COUPLING, EXPANSION],
+    },
+    # COUPLING (UM) - Synchronizes bidirectional coherence links
+    COUPLING: {
+        "excellent": [
+            RESONANCE,
+            COHERENCE,
+            EXPANSION,
+        ],  # Linking → amplification/stabilization/exploration
+        "good": [TRANSITION, SILENCE],  # Handoff or pause after coupling
+        "caution": [],
+        "avoid": [
+            EMISSION,
+            RECEPTION,
+            DISSONANCE,
+            CONTRACTION,
+            MUTATION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+            COUPLING,
+        ],
+    },
+    # RESONANCE (RA) - Amplifies aligned structural frequency
+    RESONANCE: {
+        "excellent": [
+            COHERENCE,
+            EXPANSION,
+            COUPLING,
+        ],  # Amplification → stabilization/exploration/linking
+        "good": [
+            TRANSITION,
+            SILENCE,
+            EMISSION,
+            RECURSIVITY,
+        ],  # Handoff, pause, re-initiation, fractal echo
+        "caution": [],
+        "avoid": [
+            RECEPTION,
+            DISSONANCE,
+            CONTRACTION,
+            MUTATION,
+            SELF_ORGANIZATION,
+            RESONANCE,
+        ],
+    },
+    # SILENCE (SHA) - Suspends reorganization while preserving form
+    SILENCE: {
+        "excellent": [
+            EMISSION,
+            RECEPTION,
+        ],  # Resume from pause → initiation or anchoring
+        "good": [],
+        "caution": [],
+        "avoid": [
+            COHERENCE,
+            DISSONANCE,
+            COUPLING,
+            RESONANCE,
+            EXPANSION,
+            CONTRACTION,
+            MUTATION,
+            TRANSITION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+            SILENCE,
+        ],
+    },
+    # EXPANSION (VAL) - Dilates structure to explore volume
+    EXPANSION: {
+        "excellent": [
+            COUPLING,
+            RESONANCE,
+            COHERENCE,
+        ],  # Exploration → linking/amplification/stabilization
+        "good": [TRANSITION],  # Handoff after expansion
+        "caution": [],
+        "avoid": [
+            EMISSION,
+            RECEPTION,
+            DISSONANCE,
+            SILENCE,
+            CONTRACTION,
+            MUTATION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+            EXPANSION,
+        ],
+    },
+    # CONTRACTION (NUL) - Concentrates trajectories into core
+    CONTRACTION: {
+        "excellent": [
+            EMISSION,
+            COHERENCE,
+        ],  # Concentration → re-initiation or stabilization
+        "good": [],
+        "caution": [],
+        "avoid": [
+            RECEPTION,
+            DISSONANCE,
+            COUPLING,
+            RESONANCE,
+            SILENCE,
+            EXPANSION,
+            MUTATION,
+            TRANSITION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+            CONTRACTION,
+        ],
+    },
+    # SELF_ORGANIZATION (THOL) - Spawns autonomous cascades
+    SELF_ORGANIZATION: {
+        "excellent": [
+            COHERENCE,
+            COUPLING,
+            RESONANCE,
+        ],  # Autonomous cascades → stabilization/linking/amplification
+        "good": [
+            DISSONANCE,
+            MUTATION,
+            TRANSITION,
+            SILENCE,
+            CONTRACTION,
+            EMISSION,
+            SELF_ORGANIZATION,
+        ],  # Nested/sequential self-organization
+        "caution": [],
+        "avoid": [RECEPTION, EXPANSION, RECURSIVITY],
+    },
+    # MUTATION (ZHIR) - Pivots node across structural thresholds
+    MUTATION: {
+        "excellent": [
+            COHERENCE,
+            TRANSITION,
+            SILENCE,
+        ],  # Transformation → stabilization/handoff/pause
+        "good": [],
+        "caution": [],
+        "avoid": [
+            EMISSION,
+            RECEPTION,
+            DISSONANCE,
+            COUPLING,
+            RESONANCE,
+            EXPANSION,
+            CONTRACTION,
+            MUTATION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+        ],
+    },
+    # TRANSITION (NAV) - Guides controlled regime hand-offs
+    TRANSITION: {
+        "excellent": [
+            RESONANCE,
+            COHERENCE,
+            COUPLING,
+        ],  # Handoff → amplification/stabilization/linking
+        "good": [
+            DISSONANCE,
+            MUTATION,
+            SILENCE,
+            TRANSITION,
+        ],  # Tension, transformation, pause, continued handoff
+        "caution": [],
+        "avoid": [
+            EMISSION,
+            RECEPTION,
+            EXPANSION,
+            CONTRACTION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+        ],
+    },
+    # RECURSIVITY (REMESH) - Echoes patterns across nested EPIs
+    RECURSIVITY: {
+        "excellent": [
+            COHERENCE,
+            RESONANCE,
+        ],  # Fractal echo → stabilization/amplification
+        "good": [
+            DISSONANCE,
+            RECEPTION,
+            COUPLING,
+            TRANSITION,
+        ],  # Tension, anchoring, linking, handoff after recursive pattern
+        "caution": [],
+        "avoid": [
+            EMISSION,
+            SILENCE,
+            EXPANSION,
+            CONTRACTION,
+            MUTATION,
+            SELF_ORGANIZATION,
+            RECURSIVITY,
+        ],
+    },
+}
+
+
+def get_compatibility_level(prev: str, next_op: str) -> CompatibilityLevel:
+    """Return the compatibility level between two structural operators.
+
+    Parameters
+    ----------
+    prev : str
+        Previous operator in canonical form (e.g., "emission", "coherence").
+    next_op : str
+        Next operator in canonical form (e.g., "dissonance", "resonance").
+
+    Returns
+    -------
+    CompatibilityLevel
+        The graduated compatibility level: EXCELLENT, GOOD, CAUTION, or AVOID.
+
+    Examples
+    --------
+    >>> get_compatibility_level("emission", "coherence")
+    CompatibilityLevel.EXCELLENT
+
+    >>> get_compatibility_level("emission", "dissonance")
+    CompatibilityLevel.CAUTION
+
+    >>> get_compatibility_level("silence", "dissonance")
+    CompatibilityLevel.AVOID
+
+    Notes
+    -----
+    This function implements the graduated compatibility matrix following TNFR
+    canonical theory. Transitions are categorized as:
+
+    - EXCELLENT: Optimal structural progression
+    - GOOD: Acceptable structural progression
+    - CAUTION: Contextually dependent, requires validation
+    - AVOID: Incompatible, violates structural coherence
+    """
+    if prev not in GRADUATED_COMPATIBILITY:
+        # Unknown operator defaults to AVOID
+        return CompatibilityLevel.AVOID
+
+    levels = GRADUATED_COMPATIBILITY[prev]
+
+    # Check each level in order of preference
+    if next_op in levels.get("excellent", []):
+        return CompatibilityLevel.EXCELLENT
+    elif next_op in levels.get("good", []):
+        return CompatibilityLevel.GOOD
+    elif next_op in levels.get("caution", []):
+        return CompatibilityLevel.CAUTION
+    else:
+        return CompatibilityLevel.AVOID
+
+
+# Generate backward-compatible binary compatibility table from graduated matrix
+# This combines excellent, good, and caution levels as "allowed" transitions
+def _generate_binary_compat() -> dict[str, set[str]]:
+    """Generate binary compatibility table from graduated matrix.
+
+    Combines EXCELLENT, GOOD, and CAUTION levels into a single "allowed" set
+    for backward compatibility with existing code that expects binary validation.
+    """
+    compat: dict[str, set[str]] = {}
+    for operator, levels in GRADUATED_COMPATIBILITY.items():
+        allowed = set()
+        allowed.update(levels.get("excellent", []))
+        allowed.update(levels.get("good", []))
+        allowed.update(levels.get("caution", []))
+        compat[operator] = allowed
+    return compat
+
+
+# Canonical compatibilities (allowed next operators) expressed via structural names
+# Derived from GRADUATED_COMPATIBILITY for backward compatibility
+_STRUCTURAL_COMPAT: dict[str, set[str]] = _generate_binary_compat()
+
+
+def _name_to_glyph(name: str) -> Glyph:
+    glyph = _grammar.function_name_to_glyph(name)
+    if glyph is None:
+        raise KeyError(f"No glyph mapped to structural operator '{name}'")
+    return glyph
+
+
+def _translate_structural() -> tuple[dict[Glyph, set[Glyph]], dict[Glyph, Glyph]]:
+    compat: dict[Glyph, set[Glyph]] = {}
+    for src, targets in _STRUCTURAL_COMPAT.items():
+        src_glyph = _name_to_glyph(src)
+        compat[src_glyph] = {_name_to_glyph(target) for target in targets}
+    fallback: dict[Glyph, Glyph] = {}
+    for src, target in _STRUCTURAL_FALLBACK.items():
+        fallback[_name_to_glyph(src)] = _name_to_glyph(target)
+    return compat, fallback
+
+
+# Canonical fallbacks when a transition is not allowed (structural names)
+_STRUCTURAL_FALLBACK: dict[str, str] = {
+    EMISSION: RECEPTION,
+    RECEPTION: COHERENCE,
+    COHERENCE: RESONANCE,
+    TRANSITION: RESONANCE,
+    CONTRACTION: EMISSION,
+    DISSONANCE: MUTATION,
+    RESONANCE: COHERENCE,
+    SILENCE: EMISSION,
+    SELF_ORGANIZATION: TRANSITION,
+    COUPLING: RESONANCE,
+    EXPANSION: RESONANCE,
+    MUTATION: COHERENCE,
+    RECURSIVITY: COHERENCE,  # Fractal echo → stabilization
+}
+
+CANON_COMPAT, CANON_FALLBACK = _translate_structural()
+
+# Re-export structural tables for internal consumers that operate on functional
+# identifiers without exposing them as part of the public API.
+_STRUCTURAL_COMPAT_TABLE = _STRUCTURAL_COMPAT
+_STRUCTURAL_FALLBACK_TABLE = _STRUCTURAL_FALLBACK

tnfr/validation/compatibility.pyi

@@ -0,0 +1,6 @@
+from ..types import Glyph
+
+__all__ = ("CANON_COMPAT", "CANON_FALLBACK")
+
+CANON_COMPAT: dict[Glyph, set[Glyph]]
+CANON_FALLBACK: dict[Glyph, Glyph]

tnfr/validation/config.py

@@ -0,0 +1,73 @@
+"""Configuration for TNFR validation system.
+
+This module provides configuration options for controlling validation behavior,
+including thresholds, performance settings, and validation levels.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from .invariants import InvariantSeverity
+
+__all__ = [
+    "ValidationConfig",
+    "validation_config",
+    "configure_validation",
+]
+
+
+@dataclass
+class ValidationConfig:
+    """TNFR validation system configuration."""
+
+    # Validation levels
+    validate_invariants: bool = True
+    validate_each_step: bool = False  # Expensive, only for debugging
+    min_severity: InvariantSeverity = InvariantSeverity.ERROR
+
+    # Numerical thresholds (can be overridden from graph.graph config)
+    epi_range: tuple[float, float] = (0.0, 1.0)
+    vf_range: tuple[float, float] = (0.001, 1000.0)  # Hz_str
+    phase_coupling_threshold: float = math.pi / 2
+
+    # Semantic validation
+    enable_semantic_validation: bool = True
+    allow_semantic_warnings: bool = True
+
+    # Performance
+    cache_validation_results: bool = False  # Future optimization
+    max_validation_time_ms: float = 1000.0  # Timeout (not implemented yet)
+
+
+# Global configuration
+validation_config = ValidationConfig()
+
+
+def configure_validation(**kwargs: object) -> None:
+    """Updates global validation configuration.
+
+    Parameters
+    ----------
+    **kwargs
+        Configuration parameters to update. Valid keys match
+        ValidationConfig attributes.
+
+    Raises
+    ------
+    ValueError
+        If an unknown configuration key is provided.
+
+    Examples
+    --------
+    >>> from tnfr.validation.config import configure_validation
+    >>> configure_validation(validate_each_step=True)
+    >>> configure_validation(phase_coupling_threshold=3.14159/3)
+    """
+    global validation_config
+    for key, value in kwargs.items():
+        if hasattr(validation_config, key):
+            setattr(validation_config, key, value)
+        else:
+            raise ValueError(f"Unknown validation config key: {key}")

tnfr/validation/graph.py

@@ -0,0 +1,139 @@
+"""Graph-level validation helpers enforcing TNFR invariants."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+import numpy as np
+
+from ..alias import get_attr
+from ..glyph_runtime import last_glyph
+from ..config.constants import GLYPHS_CANONICAL_SET
+from ..constants import get_param
+from ..constants.aliases import ALIAS_EPI, ALIAS_VF
+from ..utils import within_range
+from ..types import (
+    EPIValue,
+    NodeAttrMap,
+    NodeId,
+    StructuralFrequency,
+    TNFRGraph,
+    ValidatorFunc,
+    ensure_bepi,
+)
+
+NodeData = NodeAttrMap
+"""Read-only node attribute mapping used by validators."""
+
+AliasSequence = Sequence[str]
+"""Sequence of accepted attribute aliases."""
+
+__all__ = ("run_validators", "GRAPH_VALIDATORS")
+
+
+def _materialize_node_mapping(data: NodeData) -> dict[str, object]:
+    if isinstance(data, dict):
+        return data
+    return dict(data)
+
+
+def _require_attr(
+    data: NodeData, alias: AliasSequence, node: NodeId, name: str
+) -> float:
+    """Return scalar attribute value or raise if missing."""
+
+    mapping = _materialize_node_mapping(data)
+    val = get_attr(mapping, alias, None)
+    if val is None:
+        raise ValueError(f"Missing {name} attribute in node {node}")
+    return float(val)
+
+
+def _require_epi(data: NodeData, node: NodeId) -> EPIValue:
+    """Return a validated BEPI element stored in ``data``."""
+
+    mapping = _materialize_node_mapping(data)
+    value = get_attr(mapping, ALIAS_EPI, None, conv=lambda obj: obj)
+    if value is None:
+        raise ValueError(f"Missing EPI attribute in node {node}")
+    try:
+        return ensure_bepi(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Invalid EPI payload in node {node}: {exc}") from exc
+
+
+def _validate_sigma(graph: TNFRGraph) -> None:
+    from ..sense import sigma_vector_from_graph
+
+    sv = sigma_vector_from_graph(graph)
+    if sv.get("mag", 0.0) > 1.0 + sys.float_info.epsilon:
+        raise ValueError("σ norm exceeds 1")
+
+
+GRAPH_VALIDATORS: tuple[ValidatorFunc, ...] = (_validate_sigma,)
+"""Ordered collection of graph-level validators."""
+
+
+def _max_abs(values: np.ndarray) -> float:
+    if values.size == 0:
+        return 0.0
+    return float(np.max(np.abs(values)))
+
+
+def _check_epi(
+    epi: EPIValue,
+    epi_min: float,
+    epi_max: float,
+    node: NodeId,
+) -> None:
+    continuous_max = _max_abs(epi.f_continuous)
+    discrete_max = _max_abs(epi.a_discrete)
+    _check_range(continuous_max, epi_min, epi_max, "EPI continuous", node)
+    _check_range(discrete_max, epi_min, epi_max, "EPI discrete", node)
+
+    spacings = np.diff(epi.x_grid)
+    if np.any(spacings <= 0.0):
+        raise ValueError(f"EPI grid must be strictly increasing for node {node}")
+    if not np.allclose(spacings, spacings[0], rtol=1e-9, atol=1e-12):
+        raise ValueError(f"EPI grid must be uniform for node {node}")
+
+
+def _out_of_range_msg(name: str, node: NodeId, val: float) -> str:
+    return f"{name} out of range in node {node}: {val}"
+
+
+def _check_range(
+    val: float,
+    lower: float,
+    upper: float,
+    name: str,
+    node: NodeId,
+    tol: float = 1e-9,
+) -> None:
+    if not within_range(val, lower, upper, tol):
+        raise ValueError(_out_of_range_msg(name, node, val))
+
+
+def _check_glyph(glyph: str | None, node: NodeId) -> None:
+    if glyph and glyph not in GLYPHS_CANONICAL_SET:
+        raise KeyError(f"Invalid glyph {glyph} in node {node}")
+
+
+def run_validators(graph: TNFRGraph) -> None:
+    """Run all invariant validators on ``graph`` with a single node pass."""
+
+    epi_min = float(get_param(graph, "EPI_MIN"))
+    epi_max = float(get_param(graph, "EPI_MAX"))
+    vf_min = float(get_param(graph, "VF_MIN"))
+    vf_max = float(get_param(graph, "VF_MAX"))
+
+    for node, data in graph.nodes(data=True):
+        epi = _require_epi(data, node)
+        vf = StructuralFrequency(_require_attr(data, ALIAS_VF, node, "VF"))
+        _check_epi(epi, epi_min, epi_max, node)
+        _check_range(vf, vf_min, vf_max, "VF", node)
+        _check_glyph(last_glyph(data), node)
+
+    for validator in GRAPH_VALIDATORS:
+        validator(graph)

tnfr/validation/graph.pyi

@@ -0,0 +1,18 @@
+from collections.abc import Sequence
+from typing import Tuple
+
+from ..types import (
+    EPIValue,
+    NodeAttrMap,
+    NodeId,
+    StructuralFrequency,
+    TNFRGraph,
+    ValidatorFunc,
+)
+
+NodeData = NodeAttrMap
+AliasSequence = Sequence[str]
+
+GRAPH_VALIDATORS: Tuple[ValidatorFunc, ...]
+
+def run_validators(graph: TNFRGraph) -> None: ...