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

tnfr/validation/__init__.py

@@ -0,0 +1,113 @@
+"""Unified validation interface consolidating grammar, graph and spectral checks.
+
+This package re-exports the canonical grammar helpers implemented in
+``tnfr.operators.grammar`` so downstream code can rely on a single import path for
+structural validation primitives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, Mapping, Protocol, TypeVar, runtime_checkable
+
+SubjectT = TypeVar("SubjectT")
+
+
+@dataclass(slots=True)
+class ValidationOutcome(Generic[SubjectT]):
+    """Result emitted by all canonical TNFR validators."""
+
+    subject: SubjectT
+    """The validated subject in canonical form."""
+
+    passed: bool
+    """Whether the validation succeeded without invariant violations."""
+
+    summary: Mapping[str, Any]
+    """Structured diagnostics describing the performed checks."""
+
+    artifacts: Mapping[str, Any] | None = None
+    """Optional artefacts (e.g. clamped nodes, normalised vectors)."""
+
+
+@runtime_checkable
+class Validator(Protocol[SubjectT]):
+    """Contract implemented by runtime and spectral validators."""
+
+    def validate(self, subject: SubjectT, /, **kwargs: Any) -> ValidationOutcome[SubjectT]:
+        """Validate ``subject`` returning a :class:`ValidationOutcome`."""
+
+    def report(self, outcome: "ValidationOutcome[SubjectT]") -> str:
+        """Produce a concise textual explanation for ``outcome``."""
+
+
+from .compatibility import CANON_COMPAT, CANON_FALLBACK
+from ..operators.grammar import (
+    GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    SequenceValidationResult,
+    SequenceSyntaxError,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    record_grammar_violation,
+)
+from .graph import GRAPH_VALIDATORS, run_validators
+from .window import validate_window
+from .runtime import GraphCanonicalValidator, apply_canonical_clamps, validate_canon
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr
+from .soft_filters import (
+    acceleration_norm,
+    check_repeats,
+    maybe_force,
+    soft_grammar_filters,
+)
+from ..operators.grammar import validate_sequence
+
+__all__ = (
+    "ValidationOutcome",
+    "Validator",
+    "validate_sequence",
+    "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceValidationResult",
+    "SequenceSyntaxError",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "record_grammar_violation",
+    "validate_window",
+    "run_validators",
+    "GRAPH_VALIDATORS",
+    "coerce_glyph",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "get_norm",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "NFRValidator",
+)
+
+
+def __getattr__(name: str) -> Any:
+    if name == "NFRValidator":
+        from .spectral import NFRValidator as _NFRValidator
+
+        return _NFRValidator
+    raise AttributeError(name)
+

tnfr/validation/__init__.pyi

@@ -0,0 +1,77 @@
+from collections.abc import Mapping
+from typing import Any, Generic, Protocol, TypeVar
+
+from ..types import Glyph, TNFRGraph
+from .compatibility import CANON_COMPAT as CANON_COMPAT, CANON_FALLBACK as CANON_FALLBACK
+from ..operators.grammar import (
+    GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    SequenceSyntaxError,
+    SequenceValidationResult,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    record_grammar_violation,
+)
+from .graph import GRAPH_VALIDATORS, run_validators
+from .window import validate_window
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr
+from .soft_filters import (acceleration_norm, check_repeats, maybe_force, soft_grammar_filters)
+from .runtime import GraphCanonicalValidator, apply_canonical_clamps, validate_canon
+from .spectral import NFRValidator
+from ..operators.grammar import validate_sequence
+
+SubjectT = TypeVar("SubjectT")
+
+
+class ValidationOutcome(Generic[SubjectT]):
+    subject: SubjectT
+    passed: bool
+    summary: Mapping[str, Any]
+    artifacts: Mapping[str, Any] | None
+
+
+class Validator(Protocol[SubjectT]):
+    def validate(self, subject: SubjectT, /, **kwargs: Any) -> ValidationOutcome[SubjectT]: ...
+
+    def report(self, outcome: ValidationOutcome[SubjectT]) -> str: ...
+
+
+__all__ = (
+    "ValidationOutcome",
+    "Validator",
+    "validate_sequence",
+    "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceSyntaxError",
+    "SequenceValidationResult",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "record_grammar_violation",
+    "validate_window",
+    "run_validators",
+    "GRAPH_VALIDATORS",
+    "coerce_glyph",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "get_norm",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "NFRValidator",
+)

tnfr/validation/compatibility.py

@@ -0,0 +1,95 @@
+"""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 operators) expressed via structural names
+_STRUCTURAL_COMPAT: dict[str, set[str]] = {
+    # Opening / initiation
+    EMISSION: {RECEPTION, RESONANCE, TRANSITION, EXPANSION, COUPLING},
+    RECEPTION: {COHERENCE, COUPLING, RESONANCE, TRANSITION},
+    # Stabilisation / diffusion / coupling
+    COHERENCE: {RESONANCE, EXPANSION, COUPLING, SILENCE},
+    COUPLING: {RESONANCE, COHERENCE, EXPANSION, TRANSITION},
+    RESONANCE: {COHERENCE, EXPANSION, COUPLING, TRANSITION},
+    EXPANSION: {COUPLING, RESONANCE, COHERENCE, TRANSITION},
+    # Dissonance → transition → mutation
+    DISSONANCE: {MUTATION, TRANSITION},
+    MUTATION: {COHERENCE, TRANSITION},
+    TRANSITION: {DISSONANCE, MUTATION, RESONANCE, COHERENCE, COUPLING},
+    # Closures / latent states
+    SILENCE: {EMISSION, RECEPTION},
+    CONTRACTION: {EMISSION, COHERENCE},
+    # Self-organising blocks
+    SELF_ORGANIZATION: {
+        DISSONANCE,
+        MUTATION,
+        TRANSITION,
+        RESONANCE,
+        COHERENCE,
+        COUPLING,
+        SILENCE,
+        CONTRACTION,
+    },
+}
+
+
+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

@@ -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/grammar.py

@@ -0,0 +1,71 @@
+"""Deprecated compatibility wrapper for :mod:`tnfr.operators.grammar`.
+
+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 __future__ import annotations
+
+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 ..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",
+    "parse_sequence",
+    "validate_sequence",
+]
+
+warnings.warn(
+    "'tnfr.validation.grammar' is deprecated; import from 'tnfr.operators.grammar' "
+    "for the canonical grammar interface.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+def record_grammar_violation(
+    G: "TNFRGraph", node: "NodeId", error: StructuralGrammarError, *, stage: str
+) -> None:
+    """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

@@ -0,0 +1,40 @@
+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__ = (
+    "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 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: ...