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

tnfr/dynamics/runtime.py

@@ -3,34 +3,47 @@
 from __future__ import annotations
 
 import inspect
-import math
 import sys
+from copy import deepcopy
 from collections import deque
-from collections.abc import Mapping, MutableMapping, MutableSequence
+from collections.abc import Iterable, Mapping, MutableMapping
+from numbers import Real
 from typing import Any, cast
 
-from ..alias import (
-    get_attr,
-    get_theta_attr,
-    set_attr,
-    set_theta,
-    set_theta_attr,
-    set_vf,
-    multi_recompute_abs_max,
-)
+from ..alias import get_attr
 from ..callback_utils import CallbackEvent, callback_manager
-from ..constants import DEFAULTS, get_graph_param, get_param
+from ..constants import get_graph_param, get_param
 from ..glyph_history import ensure_history
-from ..helpers.numeric import clamp
 from ..metrics.sense_index import compute_Si
+from ..operators import apply_remesh_if_globally_stable
+from ..telemetry import publish_graph_cache_metrics
 from ..types import HistoryState, NodeId, TNFRGraph
-from .aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_VF
+from ..utils import normalize_optional_int
+from ..validation import apply_canonical_clamps, validate_canon
 from . import adaptation, coordination, integrators, selectors
+from .aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_THETA, ALIAS_VF
+
+try:  # pragma: no cover - optional NumPy dependency
+    import numpy as np
+except ImportError:  # pragma: no cover - optional dependency missing
+    np = None  # type: ignore[assignment]
+
+try:  # pragma: no cover - optional math extras
+    from ..mathematics.dynamics import MathematicalDynamicsEngine
+    from ..mathematics.projection import BasicStateProjector
+    from ..mathematics.runtime import (
+        coherence as runtime_coherence,
+        frequency_positive as runtime_frequency_positive,
+        normalized as runtime_normalized,
+    )
+except Exception:  # pragma: no cover - fallback when extras not available
+    MathematicalDynamicsEngine = None  # type: ignore[assignment]
+    BasicStateProjector = None  # type: ignore[assignment]
+    runtime_coherence = None  # type: ignore[assignment]
+    runtime_frequency_positive = None  # type: ignore[assignment]
+    runtime_normalized = None  # type: ignore[assignment]
 from .dnfr import default_compute_delta_nfr
 from .sampling import update_node_sample as _update_node_sample
-from ..operators import apply_remesh_if_globally_stable
-
-HistoryLog = MutableSequence[MutableMapping[str, object]]
 
 __all__ = (
     "ALIAS_VF",
@@ -51,23 +64,36 @@ __all__ = (
     "step",
     "run",
 )
-
-
-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 _normalize_job_overrides(
     job_overrides: Mapping[str, Any] | None,
 ) -> dict[str, Any]:
+    """Canonicalise job override keys for ΔNFR, νf and phase orchestration.
+
+    Parameters
+    ----------
+    job_overrides : Mapping[str, Any] | None
+        User-provided mapping whose keys may use legacy ``*_N_JOBS`` forms or
+        mixed casing. The values tune the parallel workloads that update ΔNFR,
+        νf adaptation and global phase coordination.
+
+    Returns
+    -------
+    dict[str, Any]
+        A dictionary where keys are upper-cased without the ``_N_JOBS`` suffix,
+        ready for downstream lookup in the runtime schedulers.
+
+    Notes
+    -----
+    ``None`` keys are silently skipped to preserve resiliency when
+    orchestrating ΔNFR workers.
+
+    Examples
+    --------
+    >>> _normalize_job_overrides({"dnfr_n_jobs": 2, "vf_adapt": 4})
+    {'DNFR': 2, 'VF_ADAPT': 4}
+    >>> _normalize_job_overrides(None)
+    {}
+    """
     if not job_overrides:
         return {}
 
@@ -82,23 +108,6 @@ def _normalize_job_overrides(
     return normalized
 
 
-def _coerce_jobs_value(raw: Any) -> int | None:
-    if raw is None:
-        return None
-    try:
-        return int(raw)
-    except (TypeError, ValueError):
-        return None
-
-
-def _sanitize_jobs(value: int | None, *, allow_non_positive: bool) -> int | None:
-    if value is None:
-        return None
-    if not allow_non_positive and value <= 0:
-        return None
-    return value
-
-
 def _resolve_jobs_override(
     overrides: Mapping[str, Any],
     key: str,
@@ -106,16 +115,54 @@ def _resolve_jobs_override(
     *,
     allow_non_positive: bool,
 ) -> int | None:
+    """Resolve job overrides prioritising user hints over graph defaults.
+
+    Parameters
+    ----------
+    overrides : Mapping[str, Any]
+        Normalised overrides produced by :func:`_normalize_job_overrides` that
+        steer the ΔNFR computation, νf adaptation or phase coupling workers.
+    key : str
+        Logical subsystem key such as ``"DNFR"`` or ``"VF_ADAPT"``.
+    graph_value : Any
+        Baseline job count stored in the graph configuration.
+    allow_non_positive : bool
+        Propagated policy describing whether zero or negative values are valid
+        for the subsystem.
+
+    Returns
+    -------
+    int | None
+        Final job count that each scheduler will use, or ``None`` when no
+        explicit override or valid fallback exists.
+
+    Notes
+    -----
+    Preference resolution is pure and returns ``None`` instead of raising when
+    overrides cannot be coerced into valid integers.
+
+    Examples
+    --------
+    >>> overrides = _normalize_job_overrides({"phase": 0})
+    >>> _resolve_jobs_override(overrides, "phase", 2, allow_non_positive=True)
+    0
+    >>> _resolve_jobs_override({}, "vf_adapt", 4, allow_non_positive=False)
+    4
+    """
     norm_key = key.upper()
     if overrides and norm_key in overrides:
-        return _sanitize_jobs(
-            _coerce_jobs_value(overrides.get(norm_key)),
+        return normalize_optional_int(
+            overrides.get(norm_key),
             allow_non_positive=allow_non_positive,
+            strict=False,
+            sentinels=None,
         )
 
-    return _sanitize_jobs(
-        _coerce_jobs_value(graph_value),
+    return normalize_optional_int(
+        graph_value,
         allow_non_positive=allow_non_positive,
+        strict=False,
+        sentinels=None,
     )
 
 
@@ -220,64 +267,6 @@ def _resolve_integrator_instance(G: TNFRGraph) -> integrators.AbstractIntegrator
     return instance
 
 
-def apply_canonical_clamps(
-    nd: MutableMapping[str, Any],
-    G: TNFRGraph | None = None,
-    node: NodeId | None = None,
-) -> None:
-    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"]))
-
-    epi = cast(float, get_attr(nd, ALIAS_EPI, 0.0))
-    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", {}))
-        hist = cast(
-            HistoryLog,
-            history.setdefault("clamp_alerts", []),
-        )
-        _log_clamp(hist, node, "EPI", float(epi), eps_min, eps_max)
-        _log_clamp(hist, node, "VF", float(vf), vf_min, vf_max)
-
-    set_attr(nd, ALIAS_EPI, clamp(epi, eps_min, eps_max))
-
-    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)
-
-
-def validate_canon(G: TNFRGraph) -> TNFRGraph:
-    for n, nd in G.nodes(data=True):
-        apply_canonical_clamps(cast(MutableMapping[str, Any], nd), G, cast(NodeId, n))
-    maxes = multi_recompute_abs_max(G, {"_vfmax": ALIAS_VF})
-    G.graph.update(maxes)
-    return G
-
-
 def _run_before_callbacks(
     G: TNFRGraph,
     *,
@@ -286,6 +275,8 @@ def _run_before_callbacks(
     use_Si: bool,
     apply_glyphs: bool,
 ) -> None:
+    """Notify ``BEFORE_STEP`` observers with execution context."""
+
     callback_manager.invoke_callbacks(
         G,
         CallbackEvent.BEFORE_STEP.value,
@@ -304,9 +295,9 @@ def _prepare_dnfr(
     use_Si: bool,
     job_overrides: Mapping[str, Any] | None = None,
 ) -> None:
-    compute_dnfr_cb = G.graph.get(
-        "compute_delta_nfr", default_compute_delta_nfr
-    )
+    """Recompute ΔNFR (and optionally Si) ahead of an integration step."""
+
+    compute_dnfr_cb = G.graph.get("compute_delta_nfr", default_compute_delta_nfr)
     overrides = job_overrides or {}
     n_jobs = _resolve_jobs_override(
         overrides,
@@ -328,9 +319,7 @@ def _prepare_dnfr(
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
                 inspect.Parameter.KEYWORD_ONLY,
             )
-        elif any(
-            p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values()
-        ):
+        elif any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values()):
             supports_n_jobs = True
 
     if supports_n_jobs:
@@ -372,6 +361,8 @@ def _update_nodes(
     hist: HistoryState,
     job_overrides: Mapping[str, Any] | None = None,
 ) -> None:
+    """Apply glyphs, integrate ΔNFR and refresh derived nodal state."""
+
     _update_node_sample(G, step=step_idx)
     overrides = job_overrides or {}
     _prepare_dnfr(G, use_Si=use_Si, job_overrides=overrides)
@@ -395,9 +386,7 @@ def _update_nodes(
         n_jobs=n_jobs,
     )
     for n, nd in G.nodes(data=True):
-        apply_canonical_clamps(
-            cast(MutableMapping[str, Any], nd), G, cast(NodeId, n)
-        )
+        apply_canonical_clamps(cast(MutableMapping[str, Any], nd), G, cast(NodeId, n))
     phase_jobs = _resolve_jobs_override(
         overrides,
         "PHASE",
@@ -415,6 +404,8 @@ def _update_nodes(
 
 
 def _update_epi_hist(G: TNFRGraph) -> None:
+    """Maintain the rolling EPI history used by remeshing heuristics."""
+
     tau_g = int(get_param(G, "REMESH_TAU_GLOBAL"))
     tau_l = int(get_param(G, "REMESH_TAU_LOCAL"))
     tau = max(tau_g, tau_l)
@@ -423,22 +414,26 @@ def _update_epi_hist(G: TNFRGraph) -> None:
     if not isinstance(epi_hist, deque) or epi_hist.maxlen != maxlen:
         epi_hist = deque(list(epi_hist or [])[-maxlen:], maxlen=maxlen)
         G.graph["_epi_hist"] = epi_hist
-    epi_hist.append(
-        {n: get_attr(nd, ALIAS_EPI, 0.0) for n, nd in G.nodes(data=True)}
-    )
+    epi_hist.append({n: get_attr(nd, ALIAS_EPI, 0.0) for n, nd in G.nodes(data=True)})
 
 
 def _maybe_remesh(G: TNFRGraph) -> None:
+    """Trigger remeshing when stability thresholds are satisfied."""
+
     apply_remesh_if_globally_stable(G)
 
 
 def _run_validators(G: TNFRGraph) -> None:
-    from ..utils import run_validators
+    """Execute registered validators ensuring canonical invariants hold."""
+
+    from ..validation import run_validators
 
     run_validators(G)
 
 
 def _run_after_callbacks(G, *, step_idx: int) -> None:
+    """Notify ``AFTER_STEP`` observers with the latest structural metrics."""
+
     h = ensure_history(G)
     ctx = {"step": step_idx}
     metric_pairs = [
@@ -454,6 +449,254 @@ def _run_after_callbacks(G, *, step_idx: int) -> None:
             ctx[dst] = values[-1]
     callback_manager.invoke_callbacks(G, CallbackEvent.AFTER_STEP.value, ctx)
 
+    telemetry = G.graph.get("telemetry")
+    if isinstance(telemetry, MutableMapping):
+        history = telemetry.get("nu_f")
+        history_key = "nu_f_history"
+        if isinstance(history, list) and history_key not in telemetry:
+            telemetry[history_key] = history
+        payload = telemetry.get("nu_f_snapshot")
+        if isinstance(payload, Mapping):
+            bridge_raw = telemetry.get("nu_f_bridge")
+            try:
+                bridge = float(bridge_raw) if bridge_raw is not None else None
+            except (TypeError, ValueError):
+                bridge = None
+            nu_f_summary = {
+                "total_reorganisations": payload.get("total_reorganisations"),
+                "total_duration": payload.get("total_duration"),
+                "rate_hz_str": payload.get("rate_hz_str"),
+                "rate_hz": payload.get("rate_hz"),
+                "variance_hz_str": payload.get("variance_hz_str"),
+                "variance_hz": payload.get("variance_hz"),
+                "confidence_level": payload.get("confidence_level"),
+                "ci_hz_str": {
+                    "lower": payload.get("ci_lower_hz_str"),
+                    "upper": payload.get("ci_upper_hz_str"),
+                },
+                "ci_hz": {
+                    "lower": payload.get("ci_lower_hz"),
+                    "upper": payload.get("ci_upper_hz"),
+                },
+                "bridge": bridge,
+            }
+            telemetry["nu_f"] = nu_f_summary
+            math_summary = telemetry.get("math_engine")
+            if isinstance(math_summary, MutableMapping):
+                math_summary["nu_f"] = dict(nu_f_summary)
+
+
+def _get_math_engine_config(G: TNFRGraph) -> MutableMapping[str, Any] | None:
+    """Return the mutable math-engine configuration stored on ``G``."""
+
+    cfg_raw = G.graph.get("MATH_ENGINE")
+    if not isinstance(cfg_raw, Mapping) or not cfg_raw.get("enabled", False):
+        return None
+    if isinstance(cfg_raw, MutableMapping):
+        return cfg_raw
+    cfg_mutable: MutableMapping[str, Any] = dict(cfg_raw)
+    G.graph["MATH_ENGINE"] = cfg_mutable
+    return cfg_mutable
+
+
+def _initialise_math_state(
+    G: TNFRGraph,
+    cfg: MutableMapping[str, Any],
+    *,
+    hilbert_space: Any,
+    projector: BasicStateProjector,
+) -> np.ndarray | None:
+    """Project graph nodes into the Hilbert space to seed the math engine."""
+
+    dimension = getattr(hilbert_space, "dimension", None)
+    if dimension is None:
+        raise AttributeError("Hilbert space configuration is missing 'dimension'.")
+
+    vectors: list[np.ndarray] = []
+    for _, nd in G.nodes(data=True):
+        epi = float(get_attr(nd, ALIAS_EPI, 0.0) or 0.0)
+        nu_f = float(get_attr(nd, ALIAS_VF, 0.0) or 0.0)
+        theta_val = float(get_attr(nd, ALIAS_THETA, 0.0) or 0.0)
+        try:
+            vector = projector(epi=epi, nu_f=nu_f, theta=theta_val, dim=int(dimension))
+        except ValueError:
+            continue
+        vectors.append(np.asarray(vector, dtype=np.complex128))
+
+    if not vectors:
+        return None
+
+    stacked = np.vstack(vectors)
+    averaged = np.mean(stacked, axis=0)
+    atol = float(getattr(projector, "atol", 1e-9))
+    norm = float(getattr(hilbert_space, "norm")(averaged))
+    if np.isclose(norm, 0.0, atol=atol):
+        averaged = vectors[0]
+        norm = float(getattr(hilbert_space, "norm")(averaged))
+    if np.isclose(norm, 0.0, atol=atol):
+        return None
+    normalised = averaged / norm
+    cfg.setdefault("_state_origin", "projected")
+    return normalised
+
+
+def _advance_math_engine(
+    G: TNFRGraph,
+    *,
+    dt: float,
+    step_idx: int,
+    hist: HistoryState,
+) -> None:
+    """Advance the optional math engine and record spectral telemetry."""
+
+    cfg = _get_math_engine_config(G)
+    if cfg is None:
+        return
+
+    if (
+        np is None
+        or MathematicalDynamicsEngine is None
+        or runtime_normalized is None
+        or runtime_coherence is None
+    ):
+        raise RuntimeError(
+            "Mathematical dynamics require NumPy and tnfr.mathematics extras to be installed."
+        )
+
+    hilbert_space = cfg.get("hilbert_space")
+    coherence_operator = cfg.get("coherence_operator")
+    coherence_threshold = cfg.get("coherence_threshold")
+    if hilbert_space is None or coherence_operator is None or coherence_threshold is None:
+        raise ValueError(
+            "MATH_ENGINE requires 'hilbert_space', 'coherence_operator' and "
+            "'coherence_threshold' entries."
+        )
+
+    if BasicStateProjector is None:  # pragma: no cover - guarded by import above
+        raise RuntimeError("Mathematical dynamics require the BasicStateProjector helper.")
+
+    projector = cfg.get("state_projector")
+    if not isinstance(projector, BasicStateProjector):
+        projector = BasicStateProjector()
+        cfg["state_projector"] = projector
+
+    engine = cfg.get("dynamics_engine")
+    if not isinstance(engine, MathematicalDynamicsEngine):
+        generator = cfg.get("generator_matrix")
+        if generator is None:
+            raise ValueError(
+                "MATH_ENGINE requires either a 'dynamics_engine' instance or a "
+                "'generator_matrix'."
+            )
+        generator_matrix = np.asarray(generator, dtype=np.complex128)
+        engine = MathematicalDynamicsEngine(generator_matrix, hilbert_space=hilbert_space)
+        cfg["dynamics_engine"] = engine
+
+    state_vector = cfg.get("_state_vector")
+    if state_vector is None:
+        state_vector = _initialise_math_state(
+            G,
+            cfg,
+            hilbert_space=hilbert_space,
+            projector=projector,
+        )
+        if state_vector is None:
+            return
+    else:
+        state_vector = np.asarray(state_vector, dtype=np.complex128)
+        dimension = getattr(hilbert_space, "dimension", state_vector.shape[0])
+        if state_vector.shape != (int(dimension),):
+            state_vector = _initialise_math_state(
+                G,
+                cfg,
+                hilbert_space=hilbert_space,
+                projector=projector,
+            )
+            if state_vector is None:
+                return
+
+    advanced = engine.step(state_vector, dt=float(dt), normalize=True)
+    cfg["_state_vector"] = advanced
+
+    atol = float(cfg.get("atol", getattr(engine, "atol", 1e-9)))
+    label = f"step[{step_idx}]"
+
+    normalized_passed, norm_value = runtime_normalized(
+        advanced,
+        hilbert_space,
+        atol=atol,
+        label=label,
+    )
+    coherence_passed, coherence_value = runtime_coherence(
+        advanced,
+        coherence_operator,
+        float(coherence_threshold),
+        normalise=False,
+        atol=atol,
+        label=label,
+    )
+
+    frequency_operator = cfg.get("frequency_operator")
+    frequency_summary: dict[str, Any] | None = None
+    if frequency_operator is not None:
+        if runtime_frequency_positive is None:  # pragma: no cover - guarded above
+            raise RuntimeError(
+                "Frequency positivity checks require tnfr.mathematics extras."
+            )
+        freq_raw = runtime_frequency_positive(
+            advanced,
+            frequency_operator,
+            normalise=False,
+            enforce=True,
+            atol=atol,
+            label=label,
+        )
+        frequency_summary = {
+            "passed": bool(freq_raw.get("passed", False)),
+            "value": float(freq_raw.get("value", 0.0)),
+            "projection_passed": bool(freq_raw.get("projection_passed", False)),
+            "spectrum_psd": bool(freq_raw.get("spectrum_psd", False)),
+            "enforced": bool(freq_raw.get("enforce", True)),
+        }
+        if "spectrum_min" in freq_raw:
+            frequency_summary["spectrum_min"] = float(freq_raw.get("spectrum_min", 0.0))
+
+    summary = {
+        "step": step_idx,
+        "normalized": bool(normalized_passed),
+        "norm": float(norm_value),
+        "coherence": {
+            "passed": bool(coherence_passed),
+            "value": float(coherence_value),
+            "threshold": float(coherence_threshold),
+        },
+        "frequency": frequency_summary,
+    }
+
+    hist.setdefault("math_engine_summary", []).append(summary)
+    hist.setdefault("math_engine_norm", []).append(summary["norm"])
+    hist.setdefault("math_engine_normalized", []).append(summary["normalized"])
+    hist.setdefault("math_engine_coherence", []).append(summary["coherence"]["value"])
+    hist.setdefault("math_engine_coherence_passed", []).append(
+        summary["coherence"]["passed"]
+    )
+
+    if frequency_summary is None:
+        hist.setdefault("math_engine_frequency", []).append(None)
+        hist.setdefault("math_engine_frequency_passed", []).append(None)
+        hist.setdefault("math_engine_frequency_projection_passed", []).append(None)
+    else:
+        hist.setdefault("math_engine_frequency", []).append(frequency_summary["value"])
+        hist.setdefault("math_engine_frequency_passed", []).append(
+            frequency_summary["passed"]
+        )
+        hist.setdefault("math_engine_frequency_projection_passed", []).append(
+            frequency_summary["projection_passed"]
+        )
+
+    cfg["last_summary"] = summary
+    telemetry = G.graph.setdefault("telemetry", {})
+    telemetry["math_engine"] = deepcopy(summary)
 
 def step(
     G: TNFRGraph,
@@ -463,6 +706,59 @@ def step(
     apply_glyphs: bool = True,
     n_jobs: Mapping[str, Any] | None = None,
 ) -> None:
+    """Advance the runtime one ΔNFR step updating νf, phase and glyphs.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph whose nodes store EPI, νf and phase metadata. The graph must
+        expose a ΔNFR hook under ``G.graph['compute_delta_nfr']`` and optional
+        selector or callback registrations.
+    dt : float | None, optional
+        Time increment injected into the integrator. ``None`` falls back to the
+        ``DT`` attribute stored in ``G.graph`` which keeps ΔNFR integration
+        aligned with the nodal equation.
+    use_Si : bool, default True
+        When ``True`` the Sense Index (Si) is recomputed to modulate ΔNFR and
+        νf adaptation heuristics.
+    apply_glyphs : bool, default True
+        Enables canonical glyph selection so that phase and coherence glyphs
+        continue to modulate ΔNFR.
+    n_jobs : Mapping[str, Any] | None, optional
+        Optional overrides that tune the parallel workers used for ΔNFR, phase
+        coordination and νf adaptation. The mapping is processed by
+        :func:`_normalize_job_overrides`.
+
+    Returns
+    -------
+    None
+        Mutates ``G`` in place by recomputing ΔNFR, νf and phase metrics.
+
+    Notes
+    -----
+    Registered callbacks execute within :func:`step` and any exceptions they
+    raise propagate according to the callback manager configuration.
+
+    Examples
+    --------
+    Register a hook that records phase synchrony while using the parametric
+    selector to choose glyphs before advancing one runtime step.
+
+    >>> from tnfr.callback_utils import CallbackEvent, callback_manager
+    >>> from tnfr.dynamics import selectors
+    >>> from tnfr.dynamics.runtime import ALIAS_VF
+    >>> from tnfr.structural import create_nfr
+    >>> G, node = create_nfr("seed", epi=0.2, vf=1.5)
+    >>> callback_manager.register_callback(
+    ...     G,
+    ...     CallbackEvent.AFTER_STEP,
+    ...     lambda graph, ctx: graph.graph.setdefault("phase_log", []).append(ctx.get("phase_sync")),
+    ... )
+    >>> G.graph["glyph_selector"] = selectors.ParametricGlyphSelector()
+    >>> step(G, dt=0.05, n_jobs={"dnfr_n_jobs": 1})
+    >>> ALIAS_VF in G.nodes[node]
+    True
+    """
     job_overrides = _normalize_job_overrides(n_jobs)
     hist = ensure_history(G)
     step_idx = len(hist.setdefault("C_steps", []))
@@ -478,10 +774,18 @@ def step(
         hist=hist,
         job_overrides=job_overrides,
     )
+    resolved_dt = get_graph_param(G, "DT") if dt is None else float(dt)
+    _advance_math_engine(
+        G,
+        dt=resolved_dt,
+        step_idx=step_idx,
+        hist=hist,
+    )
     _update_epi_hist(G)
     _maybe_remesh(G)
     _run_validators(G)
     _run_after_callbacks(G, step_idx=step_idx)
+    publish_graph_cache_metrics(G)
 
 
 def run(
@@ -493,13 +797,63 @@ def run(
     apply_glyphs: bool = True,
     n_jobs: Mapping[str, Any] | None = None,
 ) -> None:
+    """Iterate :func:`step` to evolve ΔNFR, νf and phase trajectories.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph that stores the coherent structures. Callbacks and selectors
+        configured on ``G.graph`` orchestrate glyph application and telemetry.
+    steps : int
+        Number of times :func:`step` is invoked. Each iteration integrates ΔNFR
+        and νf according to ``dt`` and the configured selector.
+    dt : float | None, optional
+        Time increment for each step. ``None`` uses the graph's default ``DT``.
+    use_Si : bool, default True
+        Recompute the Sense Index during each iteration to keep ΔNFR feedback
+        loops tied to νf adjustments.
+    apply_glyphs : bool, default True
+        Enables glyph selection and application per step.
+    n_jobs : Mapping[str, Any] | None, optional
+        Shared overrides forwarded to each :func:`step` call.
+
+    Returns
+    -------
+    None
+        The graph ``G`` is updated in place.
+
+    Raises
+    ------
+    ValueError
+        Raised when ``steps`` is negative because the runtime cannot evolve a
+        negative number of ΔNFR updates.
+
+    Examples
+    --------
+    Install a before-step callback and use the default glyph selector while
+    running two iterations that synchronise phase and νf.
+
+    >>> from tnfr.callback_utils import CallbackEvent, callback_manager
+    >>> from tnfr.dynamics import selectors
+    >>> from tnfr.structural import create_nfr
+    >>> G, node = create_nfr("seed", epi=0.3, vf=1.2)
+    >>> callback_manager.register_callback(
+    ...     G,
+    ...     CallbackEvent.BEFORE_STEP,
+    ...     lambda graph, ctx: graph.graph.setdefault("dt_trace", []).append(ctx["dt"]),
+    ... )
+    >>> G.graph["glyph_selector"] = selectors.default_glyph_selector
+    >>> run(G, 2, dt=0.1)
+    >>> len(G.graph["dt_trace"])
+    2
+    """
     steps_int = int(steps)
     if steps_int < 0:
         raise ValueError("'steps' must be non-negative")
     stop_cfg = get_graph_param(G, "STOP_EARLY", dict)
     stop_enabled = False
     if stop_cfg and stop_cfg.get("enabled", False):
-        w = int(stop_cfg.get("window", 25))
+        w = max(1, int(stop_cfg.get("window", 25)))
         frac = float(stop_cfg.get("fraction", 0.90))
         stop_enabled = True
     job_overrides = _normalize_job_overrides(n_jobs)
@@ -513,9 +867,15 @@ def run(
         )
         if stop_enabled:
             history = ensure_history(G)
-            series = history.get("stable_frac", [])
-            if not isinstance(series, list):
-                series = list(series)
-            if len(series) >= w and all(v >= frac for v in series[-w:]):
+            raw_series = dict.get(history, "stable_frac", [])
+            if not isinstance(raw_series, Iterable):
+                series = []
+            elif isinstance(raw_series, list):
+                series = raw_series
+            else:
+                series = list(raw_series)
+            numeric_series = [v for v in series if isinstance(v, Real)]
+            if len(numeric_series) >= w and all(
+                v >= frac for v in numeric_series[-w:]
+            ):
                 break
-