tnfr 6.0.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

tnfr/validation/compatibility.py

@@ -1,59 +1,95 @@
-"""Canonical TNFR compatibility tables.
-
-This module centralises the canonical transitions that keep TNFR
-coherence consistent across refactors.  It is intentionally lightweight
-so :mod:`tnfr.validation.grammar` can depend on it without introducing
-cycles.
-"""
+"""Canonical TNFR compatibility tables expressed via structural operators."""
 
 from __future__ import annotations
 
+from ..config.operator_names import (
+    COHERENCE,
+    CONTRACTION,
+    COUPLING,
+    DISSONANCE,
+    EMISSION,
+    EXPANSION,
+    MUTATION,
+    RECEPTION,
+    RESONANCE,
+    SELF_ORGANIZATION,
+    SILENCE,
+    TRANSITION,
+)
+from ..operators import grammar as _grammar
 from ..types import Glyph
 
 __all__ = ["CANON_COMPAT", "CANON_FALLBACK"]
 
-# Canonical compatibilities (allowed next glyphs)
-CANON_COMPAT: dict[Glyph, set[Glyph]] = {
+# Canonical compatibilities (allowed next operators) expressed via structural names
+_STRUCTURAL_COMPAT: dict[str, set[str]] = {
     # Opening / initiation
-    Glyph.AL: {Glyph.EN, Glyph.RA, Glyph.NAV, Glyph.VAL, Glyph.UM},
-    Glyph.EN: {Glyph.IL, Glyph.UM, Glyph.RA, Glyph.NAV},
+    EMISSION: {RECEPTION, RESONANCE, TRANSITION, EXPANSION, COUPLING},
+    RECEPTION: {COHERENCE, COUPLING, RESONANCE, TRANSITION},
     # Stabilisation / diffusion / coupling
-    Glyph.IL: {Glyph.RA, Glyph.VAL, Glyph.UM, Glyph.SHA},
-    Glyph.UM: {Glyph.RA, Glyph.IL, Glyph.VAL, Glyph.NAV},
-    Glyph.RA: {Glyph.IL, Glyph.VAL, Glyph.UM, Glyph.NAV},
-    Glyph.VAL: {Glyph.UM, Glyph.RA, Glyph.IL, Glyph.NAV},
+    COHERENCE: {RESONANCE, EXPANSION, COUPLING, SILENCE},
+    COUPLING: {RESONANCE, COHERENCE, EXPANSION, TRANSITION},
+    RESONANCE: {COHERENCE, EXPANSION, COUPLING, TRANSITION},
+    EXPANSION: {COUPLING, RESONANCE, COHERENCE, TRANSITION},
     # Dissonance → transition → mutation
-    Glyph.OZ: {Glyph.ZHIR, Glyph.NAV},
-    Glyph.ZHIR: {Glyph.IL, Glyph.NAV},
-    Glyph.NAV: {Glyph.OZ, Glyph.ZHIR, Glyph.RA, Glyph.IL, Glyph.UM},
+    DISSONANCE: {MUTATION, TRANSITION},
+    MUTATION: {COHERENCE, TRANSITION},
+    TRANSITION: {DISSONANCE, MUTATION, RESONANCE, COHERENCE, COUPLING},
     # Closures / latent states
-    Glyph.SHA: {Glyph.AL, Glyph.EN},
-    Glyph.NUL: {Glyph.AL, Glyph.IL},
+    SILENCE: {EMISSION, RECEPTION},
+    CONTRACTION: {EMISSION, COHERENCE},
     # Self-organising blocks
-    Glyph.THOL: {
-        Glyph.OZ,
-        Glyph.ZHIR,
-        Glyph.NAV,
-        Glyph.RA,
-        Glyph.IL,
-        Glyph.UM,
-        Glyph.SHA,
-        Glyph.NUL,
+    SELF_ORGANIZATION: {
+        DISSONANCE,
+        MUTATION,
+        TRANSITION,
+        RESONANCE,
+        COHERENCE,
+        COUPLING,
+        SILENCE,
+        CONTRACTION,
     },
 }
 
-# Canonical fallbacks when a transition is not allowed
-CANON_FALLBACK: dict[Glyph, Glyph] = {
-    Glyph.AL: Glyph.EN,
-    Glyph.EN: Glyph.IL,
-    Glyph.IL: Glyph.RA,
-    Glyph.NAV: Glyph.RA,
-    Glyph.NUL: Glyph.AL,
-    Glyph.OZ: Glyph.ZHIR,
-    Glyph.RA: Glyph.IL,
-    Glyph.SHA: Glyph.AL,
-    Glyph.THOL: Glyph.NAV,
-    Glyph.UM: Glyph.RA,
-    Glyph.VAL: Glyph.RA,
-    Glyph.ZHIR: Glyph.IL,
+
+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,
 }
+
+
+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

@@ -1,8 +1,6 @@
-from typing import Any
+from ..types import Glyph
 
-__all__: Any
+__all__ = ("CANON_COMPAT", "CANON_FALLBACK")
 
-def __getattr__(name: str) -> Any: ...
-
-CANON_COMPAT: Any
-CANON_FALLBACK: Any
+CANON_COMPAT: dict[Glyph, set[Glyph]]
+CANON_FALLBACK: dict[Glyph, Glyph]

tnfr/validation/grammar.py

@@ -1,149 +1,71 @@
-"""Canonical grammar enforcement utilities."""
+"""Deprecated compatibility wrapper for :mod:`tnfr.operators.grammar`.
 
-from __future__ import annotations
+Import :mod:`tnfr.operators.grammar` directly to access the canonical grammar
+interfaces. This module remains as a thin shim for historical callers and will
+be removed once downstream packages adopt the canonical entry point.
+"""
 
-from collections.abc import Iterable
-from dataclasses import dataclass
-from typing import Any, Optional, TYPE_CHECKING, cast
+from __future__ import annotations
 
-from ..constants import DEFAULTS, get_param
-from ..operators import apply_glyph
-from ..types import Glyph, NodeId, TNFRGraph
-from .compatibility import CANON_COMPAT
-from . import rules as _rules
+import warnings
+from typing import TYPE_CHECKING
+
+from ..operators.grammar import (
+    GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    record_grammar_violation as _canonical_record_violation,
+    SequenceSyntaxError,
+    SequenceValidationResult,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    _gram_state,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    parse_sequence,
+    validate_sequence,
+)
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from ..node import NodeProtocol
+    from ..types import NodeId, TNFRGraph
 
 __all__ = [
     "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceSyntaxError",
+    "SequenceValidationResult",
+    "record_grammar_violation",
     "_gram_state",
+    "apply_glyph_with_grammar",
     "enforce_canonical_grammar",
     "on_applied_glyph",
-    "apply_glyph_with_grammar",
+    "parse_sequence",
+    "validate_sequence",
 ]
 
+warnings.warn(
+    "'tnfr.validation.grammar' is deprecated; import from 'tnfr.operators.grammar' "
+    "for the canonical grammar interface.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
-@dataclass
-class GrammarContext:
-    """Shared context for grammar helpers.
-
-    Collects graph-level settings to reduce positional parameters across
-    helper functions.
-    """
-
-    G: TNFRGraph
-    cfg_soft: dict[str, Any]
-    cfg_canon: dict[str, Any]
-    norms: dict[str, Any]
-
-    @classmethod
-    def from_graph(cls, G: TNFRGraph) -> "GrammarContext":
-        """Create a :class:`GrammarContext` for ``G``."""
-
-        return cls(
-            G=G,
-            cfg_soft=G.graph.get("GRAMMAR", DEFAULTS.get("GRAMMAR", {})),
-            cfg_canon=G.graph.get(
-                "GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {})
-            ),
-            norms=G.graph.get("_sel_norms") or {},
-        )
-
-
-# -------------------------
-# Per-node grammar state
-# -------------------------
-
-def _gram_state(nd: dict[str, Any]) -> dict[str, Any]:
-    """Create or return the node grammar state."""
-
-    return nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
-
-
-# -------------------------
-# Core: enforce grammar on a candidate
-# -------------------------
-
-def enforce_canonical_grammar(
-    G: TNFRGraph,
-    n: NodeId,
-    cand: Glyph | str,
-    ctx: Optional[GrammarContext] = None,
-) -> Glyph | str:
-    """Validate and adjust a candidate glyph according to canonical grammar."""
 
-    if ctx is None:
-        ctx = GrammarContext.from_graph(G)
-
-    nd = ctx.G.nodes[n]
-    st = _gram_state(nd)
-
-    raw_cand = cand
-    cand = _rules.coerce_glyph(cand)
-    input_was_str = isinstance(raw_cand, str)
-
-    # 0) If glyphs outside the alphabet arrive, leave untouched
-    if not isinstance(cand, Glyph) or cand not in CANON_COMPAT:
-        return raw_cand if input_was_str else cand
-
-    original = cand
-    cand = _rules._check_repeats(ctx, n, cand)
-
-    cand = _rules._maybe_force(ctx, n, cand, original, _rules.normalized_dnfr, "force_dnfr")
-    cand = _rules._maybe_force(ctx, n, cand, original, _rules._accel_norm, "force_accel")
-    cand = _rules._check_oz_to_zhir(ctx, n, cand)
-    cand = _rules._check_thol_closure(ctx, n, cand, st)
-    cand = _rules._check_compatibility(ctx, n, cand)
-
-    coerced_final = _rules.coerce_glyph(cand)
-    if input_was_str:
-        if isinstance(coerced_final, Glyph):
-            return coerced_final.value
-        return str(cand)
-    return coerced_final if isinstance(coerced_final, Glyph) else cand
-
-
-# -------------------------
-# Post-selection: update grammar state
-# -------------------------
-
-def on_applied_glyph(G: TNFRGraph, n: NodeId, applied: Glyph | str) -> None:
-    nd = G.nodes[n]
-    st = _gram_state(nd)
-    try:
-        glyph = applied if isinstance(applied, Glyph) else Glyph(str(applied))
-    except ValueError:
-        glyph = None
-
-    if glyph is Glyph.THOL:
-        st["thol_open"] = True
-        st["thol_len"] = 0
-    elif glyph in (Glyph.SHA, Glyph.NUL):
-        st["thol_open"] = False
-        st["thol_len"] = 0
-
-
-# -------------------------
-# Direct application with canonical grammar
-# -------------------------
-
-def apply_glyph_with_grammar(
-    G: TNFRGraph,
-    nodes: Optional[Iterable[NodeId | "NodeProtocol"]],
-    glyph: Glyph | str,
-    window: Optional[int] = None,
+def record_grammar_violation(
+    G: "TNFRGraph", node: "NodeId", error: StructuralGrammarError, *, stage: str
 ) -> None:
-    """Apply ``glyph`` to ``nodes`` enforcing the canonical grammar."""
-
-    if window is None:
-        window = get_param(G, "GLYPH_HYSTERESIS_WINDOW")
-
-    g_str = glyph.value if isinstance(glyph, Glyph) else str(glyph)
-    iter_nodes = G.nodes() if nodes is None else nodes
-    ctx = GrammarContext.from_graph(G)
-    for node_ref in iter_nodes:
-        node_id = cast(NodeId, getattr(node_ref, "n", node_ref))
-        g_eff = enforce_canonical_grammar(G, node_id, g_str, ctx)
-        apply_glyph(G, node_id, g_eff, window=window)
-        on_applied_glyph(G, node_id, g_eff)
+    """Bridge to :func:`tnfr.operators.grammar.record_grammar_violation`."""
+
+    warnings.warn(
+        "'tnfr.validation.grammar.record_grammar_violation' is deprecated; "
+        "use 'tnfr.operators.grammar.record_grammar_violation' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    _canonical_record_violation(G, node, error, stage=stage)

tnfr/validation/grammar.pyi

@@ -1,11 +1,40 @@
-from typing import Any
+from ..operators.grammar import (
+    GrammarContext,
+    StructuralGrammarError,
+    RepeatWindowError,
+    MutationPreconditionError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    SequenceSyntaxError,
+    SequenceValidationResult,
+    _gram_state,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    parse_sequence,
+    validate_sequence,
+)
+from ..types import NodeId, TNFRGraph
 
-__all__: Any
+__all__ = (
+    "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceSyntaxError",
+    "SequenceValidationResult",
+    "record_grammar_violation",
+    "_gram_state",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "parse_sequence",
+    "validate_sequence",
+)
 
-def __getattr__(name: str) -> Any: ...
 
-GrammarContext: Any
-_gram_state: Any
-apply_glyph_with_grammar: Any
-enforce_canonical_grammar: Any
-on_applied_glyph: Any
+def record_grammar_violation(
+    G: TNFRGraph, node: NodeId, error: StructuralGrammarError, *, stage: str
+) -> None: ...

tnfr/validation/graph.py

@@ -0,0 +1,138 @@
+"""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,17 @@
+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: ...