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

tnfr/flatten.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from typing import Any
+
+from .tokens import THOL, Token
+
+__all__: list[str]
+
+def __getattr__(name: str) -> Any: ...
+
+class THOLEvaluator(Iterator[Token | object]):
+    def __init__(self, item: THOL, *, max_materialize: int | None = ...) -> None: ...
+    def __iter__(self) -> THOLEvaluator: ...
+    def __next__(self) -> Token | object: ...
+
+def parse_program_tokens(
+    obj: Iterable[Any] | Sequence[Any] | Any,
+    *,
+    max_materialize: int | None = ...,
+) -> list[Token]: ...

tnfr/gamma.py

@@ -1,24 +1,26 @@
 """Gamma registry."""
 
 from __future__ import annotations
-from typing import Any, Callable, NamedTuple
-import math
-import logging
+
 import hashlib
+import logging
+import math
 from collections.abc import Mapping
 from functools import lru_cache
 from types import MappingProxyType
+from typing import Any, Callable, NamedTuple
 
-from .constants import DEFAULTS, get_aliases
-from .alias import get_attr
-from .graph_utils import get_graph_mapping
-from .cache import edge_version_cache, node_set_checksum
-from .json_utils import json_dumps
-from .logging_utils import get_logger
+from .alias import get_theta_attr
+from .constants import DEFAULTS
+from .utils import json_dumps
 from .metrics.trig_cache import get_trig_cache
-
-ALIAS_THETA = get_aliases("THETA")
-
+from .types import GammaSpec, NodeId, TNFRGraph
+from .utils import (
+    edge_version_cache,
+    get_graph_mapping,
+    get_logger,
+    node_set_checksum,
+)
 
 logger = get_logger(__name__)
 
@@ -44,9 +46,8 @@ def _default_gamma_spec() -> tuple[bytes, str]:
     return dumped, hash_
 
 
-def _ensure_kuramoto_cache(G, t) -> None:
-    """Cache ``(R, ψ)`` for the current step ``t`` using
-    ``edge_version_cache``."""
+def _ensure_kuramoto_cache(G: TNFRGraph, t: float | int) -> None:
+    """Cache ``(R, ψ)`` for the current step ``t`` using ``edge_version_cache``."""
     checksum = G.graph.get("_dnfr_nodes_checksum")
     if checksum is None:
         # reuse checksum from cached_nodes_and_A when available
@@ -63,7 +64,7 @@ def _ensure_kuramoto_cache(G, t) -> None:
     G.graph["_kuramoto_cache"] = entry
 
 
-def kuramoto_R_psi(G) -> tuple[float, float]:
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]:
     """Return ``(R, ψ)`` for Kuramoto order using θ from all nodes."""
     max_steps = int(G.graph.get("KURAMOTO_CACHE_STEPS", 1))
     trig = get_trig_cache(G, cache_size=max_steps)
@@ -78,7 +79,9 @@ def kuramoto_R_psi(G) -> tuple[float, float]:
     return R, psi
 
 
-def _kuramoto_common(G, node, _cfg):
+def _kuramoto_common(
+    G: TNFRGraph, node: NodeId, _cfg: GammaSpec
+) -> tuple[float, float, float]:
     """Return ``(θ_i, R, ψ)`` for Kuramoto-based Γ functions.
 
     Reads cached global order ``R`` and mean phase ``ψ`` and obtains node
@@ -88,11 +91,12 @@ def _kuramoto_common(G, node, _cfg):
     cache = G.graph.get("_kuramoto_cache", {})
     R = float(cache.get("R", 0.0))
     psi = float(cache.get("psi", 0.0))
-    th_i = get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    th_val = get_theta_attr(G.nodes[node], 0.0)
+    th_i = float(th_val if th_val is not None else 0.0)
     return th_i, R, psi
 
 
-def _read_gamma_raw(G) -> Mapping[str, Any] | None:
+def _read_gamma_raw(G: TNFRGraph) -> GammaSpec | None:
     """Return raw Γ specification from ``G.graph['GAMMA']``.
 
     The returned value is the direct contents of ``G.graph['GAMMA']`` when
@@ -104,11 +108,13 @@ def _read_gamma_raw(G) -> Mapping[str, Any] | None:
     if raw is None or isinstance(raw, Mapping):
         return raw
     return get_graph_mapping(
-        G, "GAMMA", "G.graph['GAMMA'] no es un mapeo; se usa {'type': 'none'}"
+        G,
+        "GAMMA",
+        "G.graph['GAMMA'] is not a mapping; using {'type': 'none'}",
     )
 
 
-def _get_gamma_spec(G) -> Mapping[str, Any]:
+def _get_gamma_spec(G: TNFRGraph) -> GammaSpec:
     """Return validated Γ specification caching results.
 
     The raw value from ``G.graph['GAMMA']`` is cached together with the
@@ -122,7 +128,7 @@ def _get_gamma_spec(G) -> Mapping[str, Any]:
     cached_spec = G.graph.get("_gamma_spec")
     cached_hash = G.graph.get("_gamma_spec_hash")
 
-    def _hash_mapping(mapping: Mapping[str, Any]) -> str:
+    def _hash_mapping(mapping: GammaSpec) -> str:
         dumped = json_dumps(mapping, sort_keys=True, to_bytes=True)
         return hashlib.blake2b(dumped, digest_size=16).hexdigest()
 
@@ -165,9 +171,7 @@ def _get_gamma_spec(G) -> Mapping[str, Any]:
 # -----------------
 
 
-def _gamma_params(
-    cfg: Mapping[str, Any], **defaults: float
-) -> tuple[float, ...]:
+def _gamma_params(cfg: GammaSpec, **defaults: float) -> tuple[float, ...]:
     """Return normalized Γ parameters from ``cfg``.
 
     Parameters are retrieved from ``cfg`` using the keys in ``defaults`` and
@@ -179,28 +183,28 @@ def _gamma_params(
     >>> beta, R0 = _gamma_params(cfg, beta=0.0, R0=0.0)
     """
 
-    return tuple(
-        float(cfg.get(name, default)) for name, default in defaults.items()
-    )
+    return tuple(float(cfg.get(name, default)) for name, default in defaults.items())
 
 
 # -----------------
-# Γi(R) canónicos
+# Canonical Γi(R)
 # -----------------
 
 
-def gamma_none(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float:
+    """Return ``0.0`` to disable Γ forcing for the given node."""
+
     return 0.0
 
 
 def _gamma_kuramoto(
-    G,
-    node,
-    cfg: Mapping[str, Any],
+    G: TNFRGraph,
+    node: NodeId,
+    cfg: GammaSpec,
     builder: Callable[..., float],
     **defaults: float,
 ) -> float:
-    """Helper for Kuramoto-based Γ functions.
+    """Construct a Kuramoto-based Γ function.
 
     ``builder`` receives ``(θ_i, R, ψ, *params)`` where ``params`` are
     extracted from ``cfg`` according to ``defaults``.
@@ -220,11 +224,15 @@ def _builder_bandpass(th_i: float, R: float, psi: float, beta: float) -> float:
     return beta * R * (1.0 - R) * sgn
 
 
-def _builder_tanh(th_i: float, R: float, psi: float, beta: float, k: float, R0: float) -> float:
+def _builder_tanh(
+    th_i: float, R: float, psi: float, beta: float, k: float, R0: float
+) -> float:
     return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
 
 
-def gamma_kuramoto_linear(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Linear Kuramoto coupling for Γi(R).
 
     Formula: Γ = β · (R - R0) · cos(θ_i - ψ)
@@ -239,13 +247,17 @@ def gamma_kuramoto_linear(G, node, t, cfg: dict[str, Any]) -> float:
     return _gamma_kuramoto(G, node, cfg, _builder_linear, beta=0.0, R0=0.0)
 
 
-def gamma_kuramoto_bandpass(G, node, t, cfg: dict[str, Any]) -> float:
-    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    """Compute Γ = β · R(1-R) · sign(cos(θ_i - ψ))."""
 
     return _gamma_kuramoto(G, node, cfg, _builder_bandpass, beta=0.0)
 
 
-def gamma_kuramoto_tanh(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
     """Saturating tanh coupling for Γi(R).
 
     Formula: Γ = β · tanh(k·(R - R0)) · cos(θ_i - ψ)
@@ -257,7 +269,7 @@ def gamma_kuramoto_tanh(G, node, t, cfg: dict[str, Any]) -> float:
     return _gamma_kuramoto(G, node, cfg, _builder_tanh, beta=0.0, k=1.0, R0=0.0)
 
 
-def gamma_harmonic(G, node, t, cfg: dict[str, Any]) -> float:
+def gamma_harmonic(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float:
     """Harmonic forcing aligned with the global phase field.
 
     Formula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
@@ -271,13 +283,15 @@ def gamma_harmonic(G, node, t, cfg: dict[str, Any]) -> float:
 
 
 class GammaEntry(NamedTuple):
-    fn: Callable[[Any, Any, Any, dict[str, Any]], float]
+    """Lookup entry linking Γ evaluators with their preconditions."""
+
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
     needs_kuramoto: bool
 
 
-# ``GAMMA_REGISTRY`` asocia el nombre del acoplamiento con un
-# ``GammaEntry`` donde ``fn`` es la función evaluadora y
-# ``needs_kuramoto`` indica si requiere precomputar el orden global de fase.
+# ``GAMMA_REGISTRY`` associates each coupling name with a ``GammaEntry`` where
+# ``fn`` is the evaluation function and ``needs_kuramoto`` indicates whether
+# the global phase order must be precomputed.
 GAMMA_REGISTRY: dict[str, GammaEntry] = {
     "none": GammaEntry(gamma_none, False),
     "kuramoto_linear": GammaEntry(gamma_kuramoto_linear, True),
@@ -288,20 +302,19 @@ GAMMA_REGISTRY: dict[str, GammaEntry] = {
 
 
 def eval_gamma(
-    G,
-    node,
-    t,
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
     *,
     strict: bool = False,
     log_level: int | None = None,
 ) -> float:
-    """Evaluate Γi for ``node`` according to ``G.graph['GAMMA']``
-    specification.
+    """Evaluate Γi for ``node`` using ``G.graph['GAMMA']`` specification.
 
     If ``strict`` is ``True`` exceptions raised during evaluation are
     propagated instead of returning ``0.0``. Likewise, if the specified
-    Γ type is not registered a warning is emitted (o ``ValueError`` en
-    modo estricto) y se usa ``gamma_none``.
+    Γ type is not registered a warning is emitted (or ``ValueError`` in
+    strict mode) and ``gamma_none`` is used.
 
     ``log_level`` controls the logging level for captured errors when
     ``strict`` is ``False``. If omitted, ``logging.ERROR`` is used in
@@ -311,7 +324,7 @@ def eval_gamma(
     spec_type = spec.get("type", "none")
     reg_entry = GAMMA_REGISTRY.get(spec_type)
     if reg_entry is None:
-        msg = f"Tipo GAMMA desconocido: {spec_type}"
+        msg = f"Unknown GAMMA type: {spec_type}"
         if strict:
             raise ValueError(msg)
         logger.warning(msg)
@@ -330,7 +343,7 @@ def eval_gamma(
         )
         logger.log(
             level,
-            "Fallo al evaluar Γi para nodo %s en t=%s: %s: %s",
+            "Failed to evaluate Γi for node %s at t=%s: %s: %s",
             node,
             t,
             exc.__class__.__name__,

tnfr/gamma.pyi

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Callable, NamedTuple
+
+from .types import GammaSpec, NodeId, TNFRGraph
+
+__all__: tuple[str, ...]
+
+class GammaEntry(NamedTuple):
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
+    needs_kuramoto: bool
+
+GAMMA_REGISTRY: dict[str, GammaEntry]
+
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]: ...
+def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float: ...
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+def gamma_harmonic(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+def eval_gamma(
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+) -> float: ...

tnfr/glyph_history.py

@@ -1,16 +1,21 @@
-"""Utilities for tracking glyph emission history and related metrics."""
+"""Utilities for tracking structural operator emission history and related metrics.
+
+This module tracks the history of glyphs (structural symbols like AL, EN, IL, etc.)
+that are emitted when structural operators (Emission, Reception, Coherence, etc.)
+are applied to nodes in the TNFR network.
+"""
 
 from __future__ import annotations
 
-from typing import Any
-from collections import deque, Counter
+from collections import Counter, deque
+from collections.abc import Iterable, Mapping, MutableMapping
 from itertools import islice
-from collections.abc import Iterable, Mapping
-from functools import lru_cache
+from typing import Any, cast
 
-from .constants import get_param
-from .collections_utils import ensure_collection
-from .logging_utils import get_logger
+from .constants import get_param, normalise_state_token
+from .glyph_runtime import last_glyph
+from .types import TNFRGraph
+from .utils import ensure_collection, get_logger
 
 logger = get_logger(__name__)
 
@@ -21,28 +26,27 @@ __all__ = (
     "ensure_history",
     "current_step_idx",
     "append_metric",
-    "last_glyph",
     "count_glyphs",
 )
 
-
-@lru_cache(maxsize=1)
-def _resolve_validate_window():
-    from .validators import validate_window
-
-    return validate_window
-
-
-def _validate_window(window: int, *, positive: bool = False) -> int:
-    return _resolve_validate_window()(window, positive=positive)
+_NU_F_HISTORY_KEYS = (
+    "nu_f_rate_hz_str",
+    "nu_f_rate_hz",
+    "nu_f_ci_lower_hz_str",
+    "nu_f_ci_upper_hz_str",
+    "nu_f_ci_lower_hz",
+    "nu_f_ci_upper_hz",
+)
 
 
 def _ensure_history(
-    nd: dict[str, Any], window: int, *, create_zero: bool = False
-) -> tuple[int, deque | None]:
+    nd: MutableMapping[str, Any], window: int, *, create_zero: bool = False
+) -> tuple[int, deque[str] | None]:
     """Validate ``window`` and ensure ``nd['glyph_history']`` deque."""
 
-    v_window = _validate_window(window)
+    from tnfr.validation.window import validate_window
+
+    v_window = validate_window(window)
     if v_window == 0 and not create_zero:
         return v_window, None
     hist = nd.setdefault("glyph_history", deque(maxlen=v_window))
@@ -54,16 +58,14 @@ def _ensure_history(
             try:
                 items = ensure_collection(hist, max_materialize=None)
             except TypeError:
-                logger.debug(
-                    "Discarding non-iterable glyph history value %r", hist
-                )
+                logger.debug("Discarding non-iterable glyph history value %r", hist)
                 items = ()
-        hist = deque(items, maxlen=v_window)
+        hist = deque((str(item) for item in items), maxlen=v_window)
         nd["glyph_history"] = hist
     return v_window, hist
 
 
-def push_glyph(nd: dict[str, Any], glyph: str, window: int) -> None:
+def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None:
     """Add ``glyph`` to node history with maximum size ``window``.
 
     ``window`` validation and deque creation are handled by
@@ -74,22 +76,47 @@ def push_glyph(nd: dict[str, Any], glyph: str, window: int) -> None:
     hist.append(str(glyph))
 
 
-def recent_glyph(nd: dict[str, Any], glyph: str, window: int) -> bool:
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool:
     """Return ``True`` if ``glyph`` appeared in last ``window`` emissions.
 
-    ``window`` validation and deque creation are handled by
-    :func:`_ensure_history`. A ``window`` of zero returns ``False`` and
-    leaves ``nd`` unchanged. Negative values raise :class:`ValueError`.
+    This is a **read-only** operation that checks the existing history without
+    modifying it. If ``window`` is zero, returns ``False``. Negative values
+    raise :class:`ValueError`.
+
+    Notes
+    -----
+    This function intentionally does NOT call ``_ensure_history`` to avoid
+    accidentally truncating the glyph_history deque when checking with a
+    smaller window than the deque's maxlen. This preserves the canonical
+    principle that reading history should not modify it.
+
+    Reuses ``validate_window`` and ``ensure_collection`` utilities.
     """
+    from tnfr.validation.window import validate_window
 
-    v_window, hist = _ensure_history(nd, window)
+    v_window = validate_window(window)
     if v_window == 0:
         return False
+
+    # Read existing history without modifying it
+    hist = nd.get("glyph_history")
+    if hist is None:
+        return False
+
     gl = str(glyph)
-    return gl in hist
+
+    # Use canonical ensure_collection to materialize history
+    try:
+        items = list(ensure_collection(hist, max_materialize=None))
+    except (TypeError, ValueError):
+        return False
+
+    # Check only the last v_window items
+    recent_items = items[-v_window:] if len(items) > v_window else items
+    return gl in recent_items
 
 
-class HistoryDict(dict):
+class HistoryDict(dict[str, Any]):
     """Dict specialized for bounded history series and usage counts.
 
     Usage counts are tracked explicitly via :meth:`get_increment`. Accessing
@@ -108,7 +135,7 @@ class HistoryDict(dict):
 
     def __init__(
         self,
-        data: dict[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
         *,
         maxlen: int = 0,
     ) -> None:
@@ -129,7 +156,7 @@ class HistoryDict(dict):
         """Increase usage count for ``key``."""
         self._counts[key] += 1
 
-    def _to_deque(self, val: Any) -> deque:
+    def _to_deque(self, val: Any) -> deque[Any]:
         """Coerce ``val`` to a deque respecting ``self._maxlen``.
 
         ``Iterable`` inputs (excluding ``str`` and ``bytes``) are expanded into
@@ -155,26 +182,36 @@ class HistoryDict(dict):
         return val
 
     def get_increment(self, key: str, default: Any = None) -> Any:
+        """Return value for ``key`` and increment its usage counter."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         self._increment(key)
         return val
 
-    def __getitem__(self, key):  # type: ignore[override]
+    def __getitem__(self, key: str) -> Any:  # type: ignore[override]
+        """Return the tracked value for ``key`` ensuring deque normalisation."""
+
         return self._resolve_value(key, None, insert=False)
 
-    def get(self, key, default=None):  # type: ignore[override]
+    def get(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return ``key`` when present; otherwise fall back to ``default``."""
+
         try:
             return self._resolve_value(key, None, insert=False)
         except KeyError:
             return default
 
-    def __setitem__(self, key, value):  # type: ignore[override]
+    def __setitem__(self, key: str, value: Any) -> None:  # type: ignore[override]
+        """Store ``value`` for ``key`` while initialising usage tracking."""
+
         super().__setitem__(key, value)
         if key not in self._counts:
             self._counts[key] = 0
 
-    def setdefault(self, key, default=None):  # type: ignore[override]
+    def setdefault(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return existing value for ``key`` or insert ``default`` when absent."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         if insert:
@@ -191,6 +228,8 @@ class HistoryDict(dict):
         raise KeyError("HistoryDict is empty; cannot pop least used")
 
     def pop_least_used_batch(self, k: int) -> None:
+        """Remove up to ``k`` least-used entries from the history."""
+
         for _ in range(max(0, int(k))):
             try:
                 self.pop_least_used()
@@ -198,7 +237,7 @@ class HistoryDict(dict):
                 break
 
 
-def ensure_history(G) -> dict[str, Any]:
+def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]:
     """Ensure ``G.graph['history']`` exists and return it.
 
     ``HISTORY_MAXLEN`` must be non-negative; otherwise a
@@ -220,11 +259,10 @@ def ensure_history(G) -> dict[str, Any]:
             replaced = True
         if replaced:
             G.graph.pop(sentinel_key, None)
+        if isinstance(hist, MutableMapping):
+            _normalise_state_streams(hist)
         return hist
-    if (
-        not isinstance(hist, HistoryDict)
-        or hist._maxlen != maxlen
-    ):
+    if not isinstance(hist, HistoryDict) or hist._maxlen != maxlen:
         hist = HistoryDict(hist, maxlen=maxlen)
         G.graph["history"] = hist
         replaced = True
@@ -233,31 +271,44 @@ def ensure_history(G) -> dict[str, Any]:
         hist.pop_least_used_batch(excess)
     if replaced:
         G.graph.pop(sentinel_key, None)
+    _normalise_state_streams(cast(MutableMapping[str, Any], hist))
     return hist
 
 
-def current_step_idx(G) -> int:
+def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int:
     """Return the current step index from ``G`` history."""
 
     graph = getattr(G, "graph", G)
     return len(graph.get("history", {}).get("C_steps", []))
 
-    
 
-def append_metric(hist: dict[str, Any], key: str, value: Any) -> None:
+def append_metric(hist: MutableMapping[str, list[Any]], key: str, value: Any) -> None:
     """Append ``value`` to ``hist[key]`` list, creating it if missing."""
-    hist.setdefault(key, []).append(value)
-
+    if key == "phase_state" and isinstance(value, str):
+        value = normalise_state_token(value)
+    elif key == "nodal_diag" and isinstance(value, Mapping):
+        snapshot: dict[Any, Any] = {}
+        for node, payload in value.items():
+            if isinstance(payload, Mapping):
+                state_value = payload.get("state")
+                if isinstance(payload, MutableMapping):
+                    updated = payload
+                else:
+                    updated = dict(payload)
+                if isinstance(state_value, str):
+                    updated["state"] = normalise_state_token(state_value)
+                snapshot[node] = updated
+            else:
+                snapshot[node] = payload
+        hist.setdefault(key, []).append(snapshot)
+        return
 
-def last_glyph(nd: dict[str, Any]) -> str | None:
-    """Return the most recent glyph for node or ``None``."""
-    hist = nd.get("glyph_history")
-    return hist[-1] if hist else None
+    hist.setdefault(key, []).append(value)
 
 
 def count_glyphs(
-    G, window: int | None = None, *, last_only: bool = False
-) -> Counter:
+    G: TNFRGraph, window: int | None = None, *, last_only: bool = False
+) -> Counter[str]:
     """Count recent glyphs in the network.
 
     If ``window`` is ``None``, the full history for each node is used. A
@@ -266,7 +317,9 @@ def count_glyphs(
     """
 
     if window is not None:
-        window = _validate_window(window)
+        from tnfr.validation.window import validate_window
+
+        window = validate_window(window)
         if window == 0:
             return Counter()
 
@@ -288,3 +341,37 @@ def count_glyphs(
         counts.update(seq)
 
     return counts
+
+
+def _normalise_state_streams(hist: MutableMapping[str, Any]) -> None:
+    """Normalise legacy state tokens stored in telemetry history."""
+
+    phase_state = hist.get("phase_state")
+    if isinstance(phase_state, deque):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != list(phase_state):
+            phase_state.clear()
+            phase_state.extend(canonical)
+    elif isinstance(phase_state, list):
+        canonical = [normalise_state_token(str(item)) for item in phase_state]
+        if canonical != phase_state:
+            hist["phase_state"] = canonical
+
+    diag_history = hist.get("nodal_diag")
+    if isinstance(diag_history, list):
+        for snapshot in diag_history:
+            if not isinstance(snapshot, Mapping):
+                continue
+            for node, payload in snapshot.items():
+                if not isinstance(payload, Mapping):
+                    continue
+                state_value = payload.get("state")
+                if not isinstance(state_value, str):
+                    continue
+                canonical = normalise_state_token(state_value)
+                if canonical == state_value:
+                    continue
+                if isinstance(payload, MutableMapping):
+                    payload["state"] = canonical
+                else:
+                    snapshot[node] = {**payload, "state": canonical}