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

tnfr/validation/rules.py

@@ -0,0 +1,281 @@
+"""Validation helpers grouped by rule type.
+
+These utilities implement the canonical checks required by
+:mod:`tnfr.operators.grammar`.  They are organised here to make it
+explicit which pieces enforce repetition control, transition
+compatibility or stabilisation thresholds.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, Mapping
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_SI
+from ..config.operator_names import (
+    CONTRACTION,
+    DISSONANCE,
+    MUTATION,
+    SELF_ORGANIZATION,
+    SILENCE,
+    canonical_operator_name,
+    operator_display_name,
+)
+from ..utils import clamp01
+from ..metrics.common import normalize_dnfr
+from ..types import Glyph
+
+if TYPE_CHECKING:  # pragma: no cover - only for typing
+    from ..operators.grammar import GrammarContext
+
+__all__ = [
+    "coerce_glyph",
+    "glyph_fallback",
+    "get_norm",
+    "normalized_dnfr",
+    "_norm_attr",
+    "_si",
+    "_check_oz_to_zhir",
+    "_check_thol_closure",
+    "_check_compatibility",
+]
+
+
+def coerce_glyph(val: Any) -> Glyph | Any:
+    """Return ``val`` coerced to :class:`Glyph` when possible."""
+
+    try:
+        return Glyph(val)
+    except (ValueError, TypeError):
+        if isinstance(val, str) and val.startswith("Glyph."):
+            _, _, candidate = val.partition(".")
+            if candidate:
+                try:
+                    return Glyph(candidate)
+                except ValueError:
+                    pass
+        return val
+
+
+def glyph_fallback(cand_key: str, fallbacks: Mapping[str, Any]) -> Glyph | str:
+    """Determine fallback glyph for ``cand_key`` considering canon tables."""
+
+    glyph_key = coerce_glyph(cand_key)
+    fb_override = fallbacks.get(cand_key)
+    if fb_override is not None:
+        return coerce_glyph(fb_override)
+
+    glyph_to_name, name_to_glyph = _functional_translators()
+    _, fallback_table = _structural_tables()
+    cand_name = glyph_to_name(glyph_key if isinstance(glyph_key, Glyph) else cand_key)
+    if cand_name is None:
+        return coerce_glyph(cand_key)
+    fb_name = fallback_table.get(cand_name)
+    if fb_name is None:
+        return coerce_glyph(cand_key)
+    fb_glyph = name_to_glyph(fb_name)
+    return fb_glyph if fb_glyph is not None else coerce_glyph(cand_key)
+
+
+# -------------------------
+# Normalisation helpers
+# -------------------------
+
+
+def get_norm(ctx: "GrammarContext", key: str) -> float:
+    """Retrieve a global normalisation value from ``ctx.norms``."""
+
+    return float(ctx.norms.get(key, 1.0)) or 1.0
+
+
+def _norm_attr(ctx: "GrammarContext", nd, attr_alias: str, norm_key: str) -> float:
+    """Normalise ``attr_alias`` using the global maximum ``norm_key``."""
+
+    max_val = get_norm(ctx, norm_key)
+    return clamp01(abs(get_attr(nd, attr_alias, 0.0)) / max_val)
+
+
+def _si(nd) -> float:
+    """Return the structural sense index for ``nd`` clamped to ``[0, 1]``."""
+
+    return clamp01(get_attr(nd, ALIAS_SI, 0.5))
+
+
+def normalized_dnfr(ctx: "GrammarContext", nd) -> float:
+    """Normalise |ΔNFR| using the configured global maximum."""
+
+    return normalize_dnfr(nd, get_norm(ctx, "dnfr_max"))
+
+
+# -------------------------
+# Translation helpers
+# -------------------------
+
+
+def _structural_label(value: object) -> str:
+    """Return the canonical structural name for ``value`` when possible."""
+
+    glyph_to_name = _functional_translators()[0]
+    coerced = coerce_glyph(value)
+    if isinstance(coerced, Glyph):
+        name = glyph_to_name(coerced)
+        if name is not None:
+            return name
+    name = glyph_to_name(value if isinstance(value, Glyph) else value)
+    if name is not None:
+        return name
+    if value is None:
+        return "unknown"
+    return canonical_operator_name(str(value))
+
+
+# -------------------------
+# Validation rules
+# -------------------------
+
+def _check_oz_to_zhir(ctx: "GrammarContext", n, cand: Glyph | str) -> Glyph | str:
+    """Enforce OZ precedents before allowing ZHIR mutations."""
+
+    from ..glyph_history import recent_glyph
+    nd = ctx.G.nodes[n]
+    cand_glyph = coerce_glyph(cand)
+    glyph_to_name, name_to_glyph = _functional_translators()
+    cand_name = glyph_to_name(cand_glyph if isinstance(cand_glyph, Glyph) else cand)
+    if cand_name == MUTATION:
+        cfg = ctx.cfg_canon
+        win = int(cfg.get("zhir_requires_oz_window", 3))
+        dn_min = float(cfg.get("zhir_dnfr_min", 0.05))
+        dissonance_glyph = name_to_glyph(DISSONANCE)
+        if dissonance_glyph is None:
+            return cand
+        norm_dn = normalized_dnfr(ctx, nd)
+        recent_glyph(nd, dissonance_glyph.value, win)
+        history = tuple(_structural_label(item) for item in nd.get("glyph_history", ()))
+        has_recent_dissonance = any(
+            entry == DISSONANCE for entry in history[-win:]
+        )
+        if not has_recent_dissonance and norm_dn < dn_min:
+            cand_label = cand_name if cand_name is not None else _structural_label(cand)
+            order = (*history[-win:], cand_label)
+            from ..operators import grammar as _grammar
+
+            raise _grammar.MutationPreconditionError(
+                rule="oz-before-zhir",
+                candidate=cand_label,
+                message=f"mutation {cand_label} requires {DISSONANCE} within window {win}",
+                window=win,
+                threshold=dn_min,
+                order=order,
+                context={"normalized_dnfr": norm_dn},
+            )
+    return cand
+
+
+def _check_thol_closure(
+    ctx: "GrammarContext", n, cand: Glyph | str, st: dict[str, Any]
+) -> Glyph | str:
+    """Close THOL blocks with canonical glyphs once stabilised."""
+
+    nd = ctx.G.nodes[n]
+    if st.get("thol_open", False):
+        st["thol_len"] = int(st.get("thol_len", 0)) + 1
+        cfg = ctx.cfg_canon
+        minlen = int(cfg.get("thol_min_len", 2))
+        maxlen = int(cfg.get("thol_max_len", 6))
+        close_dn = float(cfg.get("thol_close_dnfr", 0.15))
+        requires_close = st["thol_len"] >= maxlen or (
+            st["thol_len"] >= minlen and normalized_dnfr(ctx, nd) <= close_dn
+        )
+        if requires_close:
+            glyph_to_name, name_to_glyph = _functional_translators()
+            cand_glyph = coerce_glyph(cand)
+            cand_name = glyph_to_name(cand_glyph if isinstance(cand_glyph, Glyph) else cand)
+
+            si_high = float(cfg.get("si_high", 0.66))
+            si = _si(nd)
+            target_name = SILENCE if si >= si_high else CONTRACTION
+            target_glyph = name_to_glyph(target_name)
+
+            if cand_name == target_name and isinstance(cand_glyph, Glyph):
+                return cand_glyph
+
+            if target_glyph is not None and cand_name in {CONTRACTION, SILENCE}:
+                return target_glyph
+
+            history = tuple(
+                _structural_label(item) for item in nd.get("glyph_history", ())
+            )
+            cand_label = cand_name if cand_name is not None else _structural_label(cand)
+            order = (*history[-st["thol_len"]:], cand_label)
+            from ..operators import grammar as _grammar
+
+            raise _grammar.TholClosureError(
+                rule="thol-closure",
+                candidate=cand_label,
+                message=(
+                    f"{operator_display_name(SELF_ORGANIZATION)} block requires {operator_display_name(target_name)} closure"
+                ),
+                window=st["thol_len"],
+                threshold=close_dn,
+                order=order,
+                context={
+                    "thol_min_len": minlen,
+                    "thol_max_len": maxlen,
+                    "si": si,
+                    "si_high": si_high,
+                    "required_closure": target_name,
+                },
+            )
+    return cand
+
+
+def _check_compatibility(ctx: "GrammarContext", n, cand: Glyph | str) -> Glyph | str:
+    """Verify canonical transition compatibility for ``cand``."""
+
+    nd = ctx.G.nodes[n]
+    hist = nd.get("glyph_history")
+    prev = hist[-1] if hist else None
+    prev_glyph = coerce_glyph(prev)
+    cand_glyph = coerce_glyph(cand)
+    if isinstance(prev_glyph, Glyph):
+        glyph_to_name, name_to_glyph = _functional_translators()
+        compat, fallback = _structural_tables()
+        prev_name = glyph_to_name(prev_glyph)
+        if prev_name is None:
+            return cand
+        allowed = compat.get(prev_name)
+        if allowed is None:
+            return cand
+        cand_name = glyph_to_name(cand_glyph if isinstance(cand_glyph, Glyph) else cand)
+        if cand_name in allowed:
+            return cand
+        fb_name = fallback.get(prev_name)
+        if fb_name is not None:
+            fb_glyph = name_to_glyph(fb_name)
+            if fb_glyph is not None:
+                return fb_glyph
+        order = (prev_name, cand_name or str(cand))
+        from ..operators import grammar as _grammar
+
+        raise _grammar.TransitionCompatibilityError(
+            rule="transition-compatibility",
+            candidate=cand_name or str(cand),
+            message=f"{cand_name or cand} incompatible after {prev_name}",
+            order=order,
+        )
+    return cand
+
+
+@lru_cache(maxsize=1)
+def _functional_translators():
+    from ..operators import grammar as _grammar
+
+    return _grammar.glyph_function_name, _grammar.function_name_to_glyph
+
+
+@lru_cache(maxsize=1)
+def _structural_tables():
+    from . import compatibility as _compat
+
+    return _compat._STRUCTURAL_COMPAT_TABLE, _compat._STRUCTURAL_FALLBACK_TABLE

tnfr/validation/rules.pyi

@@ -0,0 +1,55 @@
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+from typing import Any, Mapping, TypeVar
+
+from ..types import Glyph, NodeId
+from .grammar import GrammarContext
+
+__all__ = (
+    "coerce_glyph",
+    "glyph_fallback",
+    "get_norm",
+    "normalized_dnfr",
+    "_norm_attr",
+    "_si",
+    "_check_oz_to_zhir",
+    "_check_thol_closure",
+    "_check_compatibility",
+)
+
+_T = TypeVar("_T")
+
+
+def coerce_glyph(val: _T) -> Glyph | _T: ...
+
+
+def glyph_fallback(cand_key: str, fallbacks: Mapping[str, Any]) -> Glyph | str: ...
+
+
+def get_norm(ctx: GrammarContext, key: str) -> float: ...
+
+
+def _norm_attr(
+    ctx: GrammarContext, nd: Mapping[str, Any], attr_alias: str, norm_key: str
+) -> float: ...
+
+
+def _si(nd: Mapping[str, Any]) -> float: ...
+
+
+def normalized_dnfr(ctx: GrammarContext, nd: Mapping[str, Any]) -> float: ...
+
+
+def _check_oz_to_zhir(ctx: GrammarContext, n: NodeId, cand: Glyph | str) -> Glyph | str: ...
+
+
+def _check_thol_closure(
+    ctx: GrammarContext,
+    n: NodeId,
+    cand: Glyph | str,
+    st: dict[str, Any],
+) -> Glyph | str: ...
+
+
+def _check_compatibility(ctx: GrammarContext, n: NodeId, cand: Glyph | str) -> Glyph | str: ...

tnfr/validation/runtime.py

@@ -0,0 +1,263 @@
+"""Runtime validation helpers exposing canonical graph contracts."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, MutableMapping, MutableSequence
+from typing import Any, cast
+
+import numpy as np
+
+from ..alias import (
+    get_attr,
+    get_theta_attr,
+    multi_recompute_abs_max,
+    set_attr,
+    set_attr_generic,
+    set_theta,
+    set_theta_attr,
+    set_vf,
+)
+from ..constants import DEFAULTS
+from ..types import (
+    NodeId,
+    TNFRGraph,
+    ZERO_BEPI_STORAGE,
+    ensure_bepi,
+    serialize_bepi,
+)
+from ..utils import clamp, ensure_collection
+from . import ValidationOutcome, Validator
+from .graph import run_validators
+
+HistoryLog = MutableSequence[MutableMapping[str, object]]
+"""Mutable history buffer storing clamp alerts for strict graphs."""
+
+__all__ = (
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+)
+
+
+def _max_bepi_magnitude(value: Any) -> float:
+    element = ensure_bepi(value)
+    mags = [
+        float(np.max(np.abs(element.f_continuous))) if element.f_continuous.size else 0.0,
+        float(np.max(np.abs(element.a_discrete))) if element.a_discrete.size else 0.0,
+    ]
+    return float(max(mags)) if mags else 0.0
+
+
+def _clamp_component(values: Any, lower: float, upper: float) -> np.ndarray:
+    array = np.asarray(values, dtype=np.complex128)
+    if array.size == 0:
+        return array
+    magnitudes = np.abs(array)
+    result = array.copy()
+    above = magnitudes > upper
+    if np.any(above):
+        result[above] = array[above] * (upper / magnitudes[above])
+    if lower > 0.0:
+        below = (magnitudes < lower) & (magnitudes > 0.0)
+        if np.any(below):
+            result[below] = array[below] * (lower / magnitudes[below])
+    return result
+
+
+def _clamp_bepi(value: Any, lower: float, upper: float) -> Any:
+    element = ensure_bepi(value)
+    clamped_cont = _clamp_component(element.f_continuous, lower, upper)
+    clamped_disc = _clamp_component(element.a_discrete, lower, upper)
+    return ensure_bepi(
+        {"continuous": clamped_cont, "discrete": clamped_disc, "grid": element.x_grid}
+    )
+
+
+def _log_clamp(
+    hist: HistoryLog,
+    node: NodeId | None,
+    attr: str,
+    value: float,
+    lo: float,
+    hi: float,
+) -> None:
+    if value < lo or value > hi:
+        hist.append({"node": node, "attr": attr, "value": float(value)})
+
+
+def apply_canonical_clamps(
+    nd: MutableMapping[str, Any],
+    G: TNFRGraph | None = None,
+    node: NodeId | None = None,
+) -> None:
+    """Clamp nodal EPI, νf and θ according to canonical bounds."""
+
+    from ..dynamics.aliases import ALIAS_EPI, ALIAS_VF
+
+    if G is not None:
+        graph_dict = cast(MutableMapping[str, Any], G.graph)
+        graph_data: Mapping[str, Any] = graph_dict
+    else:
+        graph_dict = None
+        graph_data = DEFAULTS
+    eps_min = float(graph_data.get("EPI_MIN", DEFAULTS["EPI_MIN"]))
+    eps_max = float(graph_data.get("EPI_MAX", DEFAULTS["EPI_MAX"]))
+    vf_min = float(graph_data.get("VF_MIN", DEFAULTS["VF_MIN"]))
+    vf_max = float(graph_data.get("VF_MAX", DEFAULTS["VF_MAX"]))
+    theta_wrap = bool(graph_data.get("THETA_WRAP", DEFAULTS["THETA_WRAP"]))
+
+    raw_epi = get_attr(nd, ALIAS_EPI, ZERO_BEPI_STORAGE, conv=lambda obj: obj)
+    epi = ensure_bepi(raw_epi)
+    vf = get_attr(nd, ALIAS_VF, 0.0)
+    th_val = get_theta_attr(nd, 0.0)
+    th = 0.0 if th_val is None else float(th_val)
+
+    strict = bool(
+        graph_data.get("VALIDATORS_STRICT", DEFAULTS.get("VALIDATORS_STRICT", False))
+    )
+    if strict and graph_dict is not None:
+        history = cast(MutableMapping[str, Any], graph_dict.setdefault("history", {}))
+        alerts = history.get("clamp_alerts")
+        if alerts is None:
+            hist = cast(HistoryLog, history.setdefault("clamp_alerts", []))
+        elif isinstance(alerts, MutableSequence):
+            hist = cast(HistoryLog, alerts)
+        else:
+            materialized = ensure_collection(alerts, max_materialize=None)
+            hist = cast(HistoryLog, list(materialized))
+            history["clamp_alerts"] = hist
+        epi_mag = _max_bepi_magnitude(epi)
+        _log_clamp(hist, node, "EPI", epi_mag, eps_min, eps_max)
+        _log_clamp(hist, node, "VF", float(vf), vf_min, vf_max)
+
+    clamped_epi = _clamp_bepi(epi, eps_min, eps_max)
+    set_attr_generic(nd, ALIAS_EPI, serialize_bepi(clamped_epi), conv=lambda obj: obj)
+
+    vf_val = float(clamp(vf, vf_min, vf_max))
+    if G is not None and node is not None:
+        set_vf(G, node, vf_val, update_max=False)
+    else:
+        set_attr(nd, ALIAS_VF, vf_val)
+
+    if theta_wrap:
+        new_th = (th + math.pi) % (2 * math.pi) - math.pi
+        if G is not None and node is not None:
+            set_theta(G, node, new_th)
+        else:
+            set_theta_attr(nd, new_th)
+
+
+class GraphCanonicalValidator(Validator[TNFRGraph]):
+    """Validator enforcing canonical runtime contracts on TNFR graphs."""
+
+    recompute_frequency_maxima: bool
+    enforce_graph_validators: bool
+
+    def __init__(
+        self,
+        *,
+        recompute_frequency_maxima: bool = True,
+        enforce_graph_validators: bool = True,
+    ) -> None:
+        self.recompute_frequency_maxima = bool(recompute_frequency_maxima)
+        self.enforce_graph_validators = bool(enforce_graph_validators)
+
+    def _diff_after_clamp(
+        self,
+        before: Mapping[str, float],
+        after: Mapping[str, float],
+    ) -> Mapping[str, Mapping[str, float]]:
+        changes: dict[str, Mapping[str, float]] = {}
+        for key, before_val in before.items():
+            after_val = after.get(key)
+            if after_val is None:
+                continue
+            if math.isclose(before_val, after_val, rel_tol=0.0, abs_tol=1e-12):
+                continue
+            changes[key] = {"before": before_val, "after": after_val}
+        return changes
+
+    def validate(self, subject: TNFRGraph, /, **_: Any) -> ValidationOutcome[TNFRGraph]:
+        """Clamp nodal attributes, refresh νf maxima and run graph validators."""
+
+        from ..dynamics.aliases import ALIAS_EPI, ALIAS_VF
+
+        clamped_nodes: list[dict[str, Any]] = []
+        for node, data in subject.nodes(data=True):
+            mapping = cast(MutableMapping[str, Any], data)
+            before = {
+                "EPI": _max_bepi_magnitude(
+                    get_attr(mapping, ALIAS_EPI, ZERO_BEPI_STORAGE, conv=lambda obj: obj)
+                ),
+                "VF": float(get_attr(mapping, ALIAS_VF, 0.0)),
+                "THETA": float(get_theta_attr(mapping, 0.0) or 0.0),
+            }
+            apply_canonical_clamps(mapping, subject, cast(NodeId, node))
+            after = {
+                "EPI": _max_bepi_magnitude(
+                    get_attr(mapping, ALIAS_EPI, ZERO_BEPI_STORAGE, conv=lambda obj: obj)
+                ),
+                "VF": float(get_attr(mapping, ALIAS_VF, 0.0)),
+                "THETA": float(get_theta_attr(mapping, 0.0) or 0.0),
+            }
+            changes = self._diff_after_clamp(before, after)
+            if changes:
+                clamped_nodes.append({"node": node, "attributes": changes})
+
+        maxima: Mapping[str, float] = {}
+        if self.recompute_frequency_maxima:
+            maxima = multi_recompute_abs_max(subject, {"_vfmax": ALIAS_VF})
+            subject.graph.update(maxima)
+
+        errors: list[str] = []
+        if self.enforce_graph_validators:
+            try:
+                run_validators(subject)
+            except Exception as exc:  # pragma: no cover - defensive
+                errors.append(str(exc))
+
+        summary: dict[str, Any] = {
+            "clamped": tuple(clamped_nodes),
+            "maxima": dict(maxima),
+        }
+        if errors:
+            summary["errors"] = tuple(errors)
+
+        passed = not errors
+        artifacts: dict[str, Any] = {}
+        if clamped_nodes:
+            artifacts["clamped_nodes"] = clamped_nodes
+        if maxima:
+            artifacts["maxima"] = dict(maxima)
+
+        return ValidationOutcome(
+            subject=subject,
+            passed=passed,
+            summary=summary,
+            artifacts=artifacts or None,
+        )
+
+    def report(self, outcome: ValidationOutcome[TNFRGraph]) -> str:
+        """Return a concise textual summary of ``outcome``."""
+
+        if outcome.passed:
+            clamped = outcome.summary.get("clamped")
+            if clamped:
+                return "Graph canonical validation applied clamps successfully."
+            return "Graph canonical validation passed without adjustments."
+
+        errors = outcome.summary.get("errors")
+        if not errors:
+            return "Graph canonical validation failed without diagnostic details."
+        if isinstance(errors, (list, tuple)):
+            return "Graph canonical validation errors: " + ", ".join(map(str, errors))
+        return f"Graph canonical validation error: {errors}"
+
+
+def validate_canon(G: TNFRGraph) -> ValidationOutcome[TNFRGraph]:
+    """Validate ``G`` using :class:`GraphCanonicalValidator`."""
+
+    validator = GraphCanonicalValidator()
+    return validator.validate(G)
+

tnfr/validation/runtime.pyi

@@ -0,0 +1,31 @@
+from collections.abc import MutableMapping
+from typing import Any
+
+from ..types import NodeId, TNFRGraph
+from . import ValidationOutcome, Validator
+
+class GraphCanonicalValidator(Validator[TNFRGraph]):
+    def __init__(
+        self,
+        *,
+        recompute_frequency_maxima: bool = ...,
+        enforce_graph_validators: bool = ...,
+    ) -> None: ...
+
+    def validate(self, subject: TNFRGraph, /, **kwargs: Any) -> ValidationOutcome[TNFRGraph]: ...
+
+    def report(self, outcome: ValidationOutcome[TNFRGraph]) -> str: ...
+
+
+def apply_canonical_clamps(
+    nd: MutableMapping[str, Any],
+    G: TNFRGraph | None = ...,
+    node: NodeId | None = ...,
+) -> None: ...
+
+
+def validate_canon(G: TNFRGraph) -> ValidationOutcome[TNFRGraph]: ...
+
+
+__all__: tuple[str, ...]
+