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

tnfr/structural.py

@@ -1,20 +1,75 @@
-"""Structural analysis."""
+"""Maintain TNFR structural coherence for nodes and operator sequences.
+
+This module exposes the canonical entry points used by the engine to
+instantiate coherent TNFR nodes and to orchestrate structural operator
+pipelines while keeping the nodal equation
+``∂EPI/∂t = νf · ΔNFR(t)`` balanced.
+
+Public API
+----------
+create_nfr
+    Initialise a node with canonical EPI, νf and phase attributes plus a
+    ΔNFR hook that propagates reorganisations through the graph.
+run_sequence
+    Validate and execute operator trajectories so that ΔNFR hooks can
+    update EPI, νf and phase coherently after each step.
+OPERATORS
+    Registry of canonical structural operators ready to be composed into
+    validated sequences.
+validate_sequence
+    Grammar guard that ensures operator trajectories stay within TNFR
+    closure rules before execution.
+"""
 
 from __future__ import annotations
-from typing import Iterable
-import networkx as nx  # type: ignore[import-untyped]
 
+from copy import deepcopy
+from typing import Iterable, Mapping, Sequence
+
+import networkx as nx
+
+from .constants import EPI_PRIMARY, THETA_PRIMARY, VF_PRIMARY
 from .dynamics import (
-    set_delta_nfr_hook,
     dnfr_epi_vf_mixed,
+    set_delta_nfr_hook,
+)
+from .mathematics import (
+    BasicStateProjector,
+    CoherenceOperator,
+    FrequencyOperator,
+    HilbertSpace,
+    MathematicalDynamicsEngine,
+    NFRValidator,
+    make_coherence_operator,
+    make_frequency_operator,
+)
+from .validation import validate_sequence
+from .operators.definitions import (
+    Coherence,
+    Contraction,
+    Coupling,
+    Dissonance,
+    Emission,
+    Expansion,
+    Mutation,
+    Operator,
+    Reception,
+    Recursivity,
+    Resonance,
+    SelfOrganization,
+    Silence,
+    Transition,
 )
-from .grammar import apply_glyph_with_grammar
-from .types import Glyph
-from .constants import EPI_PRIMARY, VF_PRIMARY, THETA_PRIMARY
+from .operators.registry import OPERATORS
+from .types import DeltaNFRHook, NodeId, TNFRGraph
 
+try:  # pragma: no cover - optional dependency path exercised in CI extras
+    import numpy as np
+except ImportError:  # pragma: no cover - optional dependency path exercised in CI extras
+    np = None  # type: ignore[assignment]
 
 # ---------------------------------------------------------------------------
-# 1) Factoría NFR
+# 1) NFR factory
 # ---------------------------------------------------------------------------
 
 
@@ -24,13 +79,85 @@ def create_nfr(
     epi: float = 0.0,
     vf: float = 1.0,
     theta: float = 0.0,
-    graph: nx.Graph | None = None,
-    dnfr_hook=dnfr_epi_vf_mixed,
-) -> tuple[nx.Graph, str]:
-    """Create a graph with an initialised NFR node.
-
-    Returns the tuple ``(G, name)`` for convenience.
+    graph: TNFRGraph | None = None,
+    dnfr_hook: DeltaNFRHook = dnfr_epi_vf_mixed,
+) -> tuple[TNFRGraph, str]:
+    """Anchor a TNFR node by seeding EPI, νf, phase and ΔNFR coupling.
+
+    The factory secures the structural state of a node: it stores canonical
+    values for the Primary Information Structure (EPI), structural frequency
+    (νf) and phase, then installs a ΔNFR hook so that later operator
+    sequences can reorganise the node without breaking the nodal equation.
+
+    Parameters
+    ----------
+    name : str
+        Identifier for the new node. The identifier is stored as the node key
+        and must remain hashable by :mod:`networkx`.
+    epi : float, optional
+        Initial Primary Information Structure (EPI) assigned to the node. The
+        value provides the baseline form that subsequent ΔNFR hooks reorganise
+        through the nodal equation.
+    vf : float, optional
+        Structural frequency (νf, expressed in Hz_str) used as the starting
+        reorganisation rate for the node.
+    theta : float, optional
+        Initial phase of the node in radians, used to keep phase alignment with
+        neighbouring coherence structures.
+    graph : TNFRGraph, optional
+        Existing graph where the node will be registered. When omitted a new
+        :class:`networkx.Graph` instance is created.
+    dnfr_hook : DeltaNFRHook, optional
+        Callable responsible for computing ΔNFR and updating EPI/νf after each
+        operator application. By default the canonical ``dnfr_epi_vf_mixed``
+        hook is installed, which keeps the nodal equation coherent with TNFR
+        invariants.
+
+    Returns
+    -------
+    tuple[TNFRGraph, str]
+        The graph that stores the node together with the node identifier. The
+        tuple form allows immediate reuse with :func:`run_sequence`.
+
+    Notes
+    -----
+    The factory does not introduce additional TNFR-specific errors. Any
+    exceptions raised by :mod:`networkx` when adding nodes propagate unchanged.
+
+    Examples
+    --------
+    Create a node, connect a ΔNFR hook and launch a coherent operator
+    trajectory while tracking the evolving metrics.
+
+    >>> from tnfr.constants import DNFR_PRIMARY, EPI_PRIMARY, THETA_PRIMARY, VF_PRIMARY
+    >>> from tnfr.dynamics import set_delta_nfr_hook
+    >>> from tnfr.structural import (
+    ...     Coherence,
+    ...     Emission,
+    ...     Reception,
+    ...     Resonance,
+    ...     Silence,
+    ...     create_nfr,
+    ...     run_sequence,
+    ... )
+    >>> G, node = create_nfr("seed", epi=1.0, vf=2.0, theta=0.1)
+    >>> def synchronise_delta(graph):
+    ...     delta = graph.nodes[node][VF_PRIMARY] * 0.2
+    ...     graph.nodes[node][DNFR_PRIMARY] = delta
+    ...     graph.nodes[node][EPI_PRIMARY] += delta
+    ...     graph.nodes[node][VF_PRIMARY] += delta * 0.05
+    ...     graph.nodes[node][THETA_PRIMARY] += 0.01
+    >>> set_delta_nfr_hook(G, synchronise_delta)
+    >>> run_sequence(G, node, [Emission(), Reception(), Coherence(), Resonance(), Silence()])  # doctest: +SKIP
+    >>> (
+    ...     G.nodes[node][EPI_PRIMARY],
+    ...     G.nodes[node][VF_PRIMARY],
+    ...     G.nodes[node][THETA_PRIMARY],
+    ...     G.nodes[node][DNFR_PRIMARY],
+    ... )  # doctest: +SKIP
+    (..., ..., ..., ...)
     """
+
     G = graph if graph is not None else nx.Graph()
     G.add_node(
         name,
@@ -44,280 +171,413 @@ def create_nfr(
     return G, name
 
 
-# ---------------------------------------------------------------------------
-# 2) Operadores estructurales como API de primer orden
-# ---------------------------------------------------------------------------
-
-
-class Operador:
-    """Base class for TNFR operators.
-
-    Each operator defines ``name`` (ASCII identifier) and ``glyph``
-    (símbolo TNFR canónico). Calling an instance applies the corresponding
-    symbol to the node.
+def _resolve_dimension(
+    G: TNFRGraph,
+    *,
+    dimension: int | None,
+    hilbert_space: HilbertSpace | None,
+    existing_cfg: Mapping[str, object] | None,
+) -> int:
+    if hilbert_space is not None:
+        resolved = int(getattr(hilbert_space, "dimension", 0) or 0)
+        if resolved <= 0:
+            raise ValueError("Hilbert space dimension must be positive.")
+        return resolved
+
+    if dimension is None and existing_cfg:
+        candidate = existing_cfg.get("dimension")
+        if isinstance(candidate, int) and candidate > 0:
+            dimension = candidate
+
+    if dimension is None:
+        if hasattr(G, "number_of_nodes"):
+            count = int(G.number_of_nodes())
+        else:
+            count = len(tuple(G.nodes))
+        dimension = max(1, count)
+
+    resolved = int(dimension)
+    if resolved <= 0:
+        raise ValueError("Hilbert space dimension must be positive.")
+    return resolved
+
+
+def _ensure_coherence_operator(
+    *,
+    operator: CoherenceOperator | None,
+    dimension: int,
+    spectrum: Sequence[float] | None,
+    c_min: float | None,
+) -> CoherenceOperator:
+    if operator is not None:
+        return operator
+
+    kwargs: dict[str, object] = {}
+    if spectrum is not None:
+        spectrum_array = np.asarray(spectrum, dtype=np.complex128)
+        if spectrum_array.ndim != 1:
+            raise ValueError("Coherence spectrum must be one-dimensional.")
+        kwargs["spectrum"] = spectrum_array
+    if c_min is not None:
+        kwargs["c_min"] = float(c_min)
+    return make_coherence_operator(dimension, **kwargs)
+
+
+def _ensure_frequency_operator(
+    *,
+    operator: FrequencyOperator | None,
+    dimension: int,
+    diagonal: Sequence[float] | None,
+) -> FrequencyOperator:
+    if operator is not None:
+        return operator
+
+    if diagonal is None:
+        matrix = np.eye(dimension, dtype=float)
+    else:
+        diag_array = np.asarray(diagonal, dtype=float)
+        if diag_array.ndim != 1:
+            raise ValueError("Frequency diagonal must be one-dimensional.")
+        if diag_array.shape[0] != int(dimension):
+            raise ValueError("Frequency diagonal size must match Hilbert dimension.")
+        matrix = np.diag(diag_array)
+    return make_frequency_operator(np.asarray(matrix, dtype=np.complex128))
+
+
+def _ensure_generator_matrix(
+    *,
+    dimension: int,
+    diagonal: Sequence[float] | None,
+) -> "np.ndarray":
+    if diagonal is None:
+        return np.zeros((dimension, dimension), dtype=np.complex128)
+    diag_array = np.asarray(diagonal, dtype=np.complex128)
+    if diag_array.ndim != 1:
+        raise ValueError("Generator diagonal must be one-dimensional.")
+    if diag_array.shape[0] != int(dimension):
+        raise ValueError("Generator diagonal size must match Hilbert dimension.")
+    return np.diag(diag_array)
+
+
+def create_math_nfr(
+    name: str,
+    *,
+    epi: float = 0.0,
+    vf: float = 1.0,
+    theta: float = 0.0,
+    graph: TNFRGraph | None = None,
+    dnfr_hook: DeltaNFRHook = dnfr_epi_vf_mixed,
+    dimension: int | None = None,
+    hilbert_space: HilbertSpace | None = None,
+    coherence_operator: CoherenceOperator | None = None,
+    coherence_spectrum: Sequence[float] | None = None,
+    coherence_c_min: float | None = None,
+    coherence_threshold: float | None = None,
+    frequency_operator: FrequencyOperator | None = None,
+    frequency_diagonal: Sequence[float] | None = None,
+    generator_diagonal: Sequence[float] | None = None,
+    state_projector: BasicStateProjector | None = None,
+    dynamics_engine: MathematicalDynamicsEngine | None = None,
+    validator: NFRValidator | None = None,
+) -> tuple[TNFRGraph, str]:
+    """Create a TNFR node with canonical mathematical validation attached.
+
+    The helper wraps :func:`create_nfr` while projecting the structural state
+    into a Hilbert space so coherence, νf and norm invariants can be tracked via
+    the mathematical runtime.  It installs operators and validation metadata on
+    both the node and the hosting graph so that the
+    :class:`~tnfr.mathematics.MathematicalDynamicsEngine` can consume them
+    directly.
+
+    Parameters
+    ----------
+    name : str
+        Identifier for the new node.
+    epi, vf, theta : float, optional
+        Canonical TNFR scalars forwarded to :func:`create_nfr`.
+    dimension : int, optional
+        Hilbert space dimension. When omitted it is inferred from the graph size
+        (at least one).
+    hilbert_space : HilbertSpace, optional
+        Pre-built Hilbert space to reuse. Its dimension supersedes ``dimension``.
+    coherence_operator, frequency_operator : optional
+        Custom operators to install. When omitted they are derived from
+        ``coherence_spectrum``/``coherence_c_min`` and
+        ``frequency_diagonal`` respectively.
+    coherence_threshold : float, optional
+        Validation floor. Defaults to ``coherence_operator.c_min``.
+    generator_diagonal : sequence of float, optional
+        Diagonal entries for the unitary generator used by the mathematical
+        dynamics engine. Defaults to a null generator.
+    state_projector : BasicStateProjector, optional
+        Projector used to build the canonical spectral state for validation.
+
+    Returns
+    -------
+    tuple[TNFRGraph, str]
+        The graph and node identifier, mirroring :func:`create_nfr`.
+
+    Examples
+    --------
+    >>> G, node = create_math_nfr("math-seed", epi=0.4, vf=1.2, theta=0.05, dimension=3)
+    >>> metrics = G.nodes[node]["math_metrics"]
+    >>> round(metrics["norm"], 6)
+    1.0
+    >>> metrics["coherence_passed"], metrics["frequency_passed"]
+    (True, True)
+    >>> metrics["coherence_value"] >= metrics["coherence_threshold"]
+    True
+
+    Notes
+    -----
+    The helper mutates/extends ``G.graph['MATH_ENGINE']`` so subsequent calls to
+    :mod:`tnfr.dynamics.runtime` can advance the mathematical engine without
+    further configuration.
     """
 
-    name = "operador"
-    glyph = None  # tipo: str
-
-    def __call__(self, G: nx.Graph, node, **kw) -> None:
-        if self.glyph is None:
-            raise NotImplementedError("Operador sin glyph asignado")
-        apply_glyph_with_grammar(G, [node], self.glyph, kw.get("window"))
-
-
-class Emision(Operador):
-    """Aplicación del operador de emisión (símbolo ``AL``)."""
-
-    __slots__ = ()
-    name = "emision"
-    glyph = Glyph.AL.value
-
-
-class Recepcion(Operador):
-    """Operador de recepción (símbolo ``EN``)."""
-
-    __slots__ = ()
-    name = "recepcion"
-    glyph = Glyph.EN.value
-
-
-class Coherencia(Operador):
-    """Operador de coherencia (símbolo ``IL``)."""
-
-    __slots__ = ()
-    name = "coherencia"
-    glyph = Glyph.IL.value
-
-
-class Disonancia(Operador):
-    """Operador de disonancia (símbolo ``OZ``)."""
-
-    __slots__ = ()
-    name = "disonancia"
-    glyph = Glyph.OZ.value
-
-
-class Acoplamiento(Operador):
-    """Operador de acoplamiento (símbolo ``UM``)."""
-
-    __slots__ = ()
-    name = "acoplamiento"
-    glyph = Glyph.UM.value
-
-
-class Resonancia(Operador):
-    """Operador de resonancia (símbolo ``RA``)."""
-
-    __slots__ = ()
-    name = "resonancia"
-    glyph = Glyph.RA.value
-
-
-class Silencio(Operador):
-    """Operador de silencio (símbolo ``SHA``)."""
-
-    __slots__ = ()
-    name = "silencio"
-    glyph = Glyph.SHA.value
-
-
-class Expansion(Operador):
-    """Operador de expansión (símbolo ``VAL``)."""
-
-    __slots__ = ()
-    name = "expansion"
-    glyph = Glyph.VAL.value
+    if np is None:
+        raise ImportError("create_math_nfr requires NumPy; install the 'tnfr[math]' extras.")
 
+    G, node = create_nfr(
+        name,
+        epi=epi,
+        vf=vf,
+        theta=theta,
+        graph=graph,
+        dnfr_hook=dnfr_hook,
+    )
 
-class Contraccion(Operador):
-    """Operador de contracción (símbolo ``NUL``)."""
-
-    __slots__ = ()
-    name = "contraccion"
-    glyph = Glyph.NUL.value
-
-
-class Autoorganizacion(Operador):
-    """Operador de autoorganización (símbolo ``THOL``)."""
-
-    __slots__ = ()
-    name = "autoorganizacion"
-    glyph = Glyph.THOL.value
-
-
-class Mutacion(Operador):
-    """Operador de mutación (símbolo ``ZHIR``)."""
-
-    __slots__ = ()
-    name = "mutacion"
-    glyph = Glyph.ZHIR.value
+    existing_cfg = G.graph.get("MATH_ENGINE")
+    mapping_cfg: Mapping[str, object] | None
+    if isinstance(existing_cfg, Mapping):
+        mapping_cfg = existing_cfg
+    else:
+        mapping_cfg = None
+
+    resolved_dimension = _resolve_dimension(
+        G,
+        dimension=dimension,
+        hilbert_space=hilbert_space,
+        existing_cfg=mapping_cfg,
+    )
 
+    hilbert = hilbert_space or HilbertSpace(resolved_dimension)
+    resolved_dimension = int(getattr(hilbert, "dimension", resolved_dimension))
 
-class Transicion(Operador):
-    """Operador de transición (símbolo ``NAV``)."""
+    coherence = _ensure_coherence_operator(
+        operator=coherence_operator,
+        dimension=resolved_dimension,
+        spectrum=coherence_spectrum,
+        c_min=coherence_c_min,
+    )
+    threshold = float(
+        coherence_threshold if coherence_threshold is not None else coherence.c_min
+    )
 
-    __slots__ = ()
-    name = "transicion"
-    glyph = Glyph.NAV.value
+    frequency = _ensure_frequency_operator(
+        operator=frequency_operator,
+        dimension=resolved_dimension,
+        diagonal=frequency_diagonal,
+    )
 
+    projector = state_projector or BasicStateProjector()
 
-class Recursividad(Operador):
-    """Operador de recursividad (símbolo ``REMESH``)."""
+    generator_matrix = _ensure_generator_matrix(
+        dimension=resolved_dimension,
+        diagonal=generator_diagonal,
+    )
+    engine = dynamics_engine or MathematicalDynamicsEngine(
+        generator_matrix,
+        hilbert_space=hilbert,
+    )
 
-    __slots__ = ()
-    name = "recursividad"
-    glyph = Glyph.REMESH.value
+    enforce_frequency = frequency is not None
+    spectral_validator = validator or NFRValidator(
+        hilbert,
+        coherence,
+        threshold,
+        frequency_operator=frequency if enforce_frequency else None,
+    )
 
+    state = projector(
+        epi=float(epi),
+        nu_f=float(vf),
+        theta=float(theta),
+        dim=resolved_dimension,
+    )
+    norm_value = float(hilbert.norm(state))
+    outcome = spectral_validator.validate(
+        state,
+        enforce_frequency_positivity=enforce_frequency,
+    )
+    summary_raw = outcome.summary
+    summary = {key: deepcopy(value) for key, value in summary_raw.items()}
+
+    coherence_summary = summary.get("coherence")
+    frequency_summary = summary.get("frequency")
+
+    math_metrics = {
+        "norm": norm_value,
+        "normalized": bool(summary.get("normalized", False)),
+        "coherence_value": float(coherence_summary.get("value", 0.0))
+        if isinstance(coherence_summary, Mapping)
+        else 0.0,
+        "coherence_threshold": float(
+            coherence_summary.get("threshold", threshold)
+        )
+        if isinstance(coherence_summary, Mapping)
+        else threshold,
+        "coherence_passed": bool(coherence_summary.get("passed", False))
+        if isinstance(coherence_summary, Mapping)
+        else False,
+        "frequency_value": float(frequency_summary.get("value", 0.0))
+        if isinstance(frequency_summary, Mapping)
+        else 0.0,
+        "frequency_passed": bool(frequency_summary.get("passed", False))
+        if isinstance(frequency_summary, Mapping)
+        else True,
+        "frequency_spectrum_min": float(
+            frequency_summary.get("spectrum_min", 0.0)
+        )
+        if isinstance(frequency_summary, Mapping)
+        and "spectrum_min" in frequency_summary
+        else None,
+        "unitary_passed": bool(
+            summary.get("unitary_stability", {}).get("passed", False)
+        ),
+    }
+
+    node_context = {
+        "hilbert_space": hilbert,
+        "coherence_operator": coherence,
+        "frequency_operator": frequency,
+        "coherence_threshold": threshold,
+        "dimension": resolved_dimension,
+    }
+
+    node_data = G.nodes[node]
+    node_data["math_metrics"] = math_metrics
+    node_data["math_summary"] = summary
+    node_data["math_context"] = node_context
+
+    cfg = dict(mapping_cfg) if mapping_cfg is not None else {}
+    cfg.update(
+        {
+            "enabled": True,
+            "dimension": resolved_dimension,
+            "hilbert_space": hilbert,
+            "coherence_operator": coherence,
+            "coherence_threshold": threshold,
+            "frequency_operator": frequency,
+            "state_projector": projector,
+            "validator": spectral_validator,
+            "generator_matrix": generator_matrix,
+            "dynamics_engine": engine,
+        }
+    )
+    G.graph["MATH_ENGINE"] = cfg
 
-OPERADORES: dict[str, type[Operador]] = {
-    Emision.name: Emision,
-    Recepcion.name: Recepcion,
-    Coherencia.name: Coherencia,
-    Disonancia.name: Disonancia,
-    Acoplamiento.name: Acoplamiento,
-    Resonancia.name: Resonancia,
-    Silencio.name: Silencio,
-    Expansion.name: Expansion,
-    Contraccion.name: Contraccion,
-    Autoorganizacion.name: Autoorganizacion,
-    Mutacion.name: Mutacion,
-    Transicion.name: Transicion,
-    Recursividad.name: Recursividad,
-}
+    return G, node
 
 
 __all__ = (
     "create_nfr",
-    "Operador",
-    "Emision",
-    "Recepcion",
-    "Coherencia",
-    "Disonancia",
-    "Acoplamiento",
-    "Resonancia",
-    "Silencio",
+    "create_math_nfr",
+    "Operator",
+    "Emission",
+    "Reception",
+    "Coherence",
+    "Dissonance",
+    "Coupling",
+    "Resonance",
+    "Silence",
     "Expansion",
-    "Contraccion",
-    "Autoorganizacion",
-    "Mutacion",
-    "Transicion",
-    "Recursividad",
-    "OPERADORES",
+    "Contraction",
+    "SelfOrganization",
+    "Mutation",
+    "Transition",
+    "Recursivity",
+    "OPERATORS",
     "validate_sequence",
     "run_sequence",
 )
-# ---------------------------------------------------------------------------
-# 3) Motor de secuencias + validador sintáctico
-# ---------------------------------------------------------------------------
-
-
-_INICIO_VALIDOS = {"emision", "recursividad"}
-_TRAMO_INTERMEDIO = {"disonancia", "acoplamiento", "resonancia"}
-_CIERRE_VALIDO = {"silencio", "transicion", "recursividad"}
-
 
-def _validate_start(token: str) -> tuple[bool, str]:
-    """Ensure the sequence begins with a valid structural operator."""
 
-    if not isinstance(token, str):
-        return False, "tokens must be str"
-    if token not in _INICIO_VALIDOS:
-        return False, "must start with emission or recursion"
-    return True, ""
-
-
-def _validate_intermediate(
-    found_recepcion: bool, found_coherencia: bool, seen_intermedio: bool
-) -> tuple[bool, str]:
-    """Check that the central TNFR segment is present."""
-
-    if not (found_recepcion and found_coherencia):
-        return False, "missing input→coherence segment"
-    if not seen_intermedio:
-        return False, "missing tension/coupling/resonance segment"
-    return True, ""
-
-
-def _validate_end(last_token: str, open_thol: bool) -> tuple[bool, str]:
-    """Validate closing operator and any pending THOL blocks."""
-
-    if last_token not in _CIERRE_VALIDO:
-        return False, "sequence must end with silence/transition/recursion"
-    if open_thol:
-        return False, "THOL block without closure"
-    return True, ""
-
-
-def _validate_known_tokens(nombres_set: set[str]) -> tuple[bool, str]:
-    """Ensure all tokens map to canonical operators."""
-
-    desconocidos = nombres_set - OPERADORES.keys()
-    if desconocidos:
-        return False, f"unknown tokens: {', '.join(desconocidos)}"
-    return True, ""
-
-
-def _validate_token_sequence(nombres: list[str]) -> tuple[bool, str]:
-    """Validate token format and logical coherence in one pass."""
-
-    if not nombres:
-        return False, "empty sequence"
-
-    ok, msg = _validate_start(nombres[0])
-    if not ok:
-        return False, msg
-
-    nombres_set: set[str] = set()
-    found_recepcion = False
-    found_coherencia = False
-    seen_intermedio = False
-    open_thol = False
-
-    for n in nombres:
-        if not isinstance(n, str):
-            return False, "tokens must be str"
-        nombres_set.add(n)
-
-        if n == "recepcion" and not found_recepcion:
-            found_recepcion = True
-        elif found_recepcion and n == "coherencia" and not found_coherencia:
-            found_coherencia = True
-        elif found_coherencia and not seen_intermedio and n in _TRAMO_INTERMEDIO:
-            seen_intermedio = True
-
-        if n == "autoorganizacion":
-            open_thol = True
-        elif open_thol and n in {"silencio", "contraccion"}:
-            open_thol = False
-
-    ok, msg = _validate_known_tokens(nombres_set)
-    if not ok:
-        return False, msg
-    ok, msg = _validate_intermediate(found_recepcion, found_coherencia, seen_intermedio)
-    if not ok:
-        return False, msg
-    ok, msg = _validate_end(nombres[-1], open_thol)
-    if not ok:
-        return False, msg
-    return True, "ok"
-
-
-def validate_sequence(nombres: list[str]) -> tuple[bool, str]:
-    """Validate minimal TNFR syntax rules."""
-    return _validate_token_sequence(nombres)
-
-
-def run_sequence(G: nx.Graph, node, ops: Iterable[Operador]) -> None:
-    """Execute a sequence of operators on ``node`` after validation."""
+def run_sequence(G: TNFRGraph, node: NodeId, ops: Iterable[Operator]) -> None:
+    """Drive structural sequences that rebalance EPI, νf, phase and ΔNFR.
+
+    The function enforces the canonical operator grammar, then executes each
+    operator so that the configured ΔNFR hook can update the nodal equation in
+    place. Each step is expected to express the structural effect of the
+    operator, while the hook keeps EPI, νf and phase consistent with the
+    resulting ΔNFR variations.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph that stores the node and its ΔNFR orchestration hook. The hook is
+        read from ``G.graph['compute_delta_nfr']`` and is responsible for
+        keeping the nodal equation up to date after each operator.
+    node : NodeId
+        Identifier of the node that will receive the operators. The node must
+        already contain the canonical attributes ``EPI``, ``νf`` and ``θ``.
+    ops : Iterable[Operator]
+        Iterable of canonical structural operators to apply. Their
+        concatenation must respect the validated TNFR grammar.
+
+    Returns
+    -------
+    None
+        The function mutates ``G`` in-place by updating the node attributes.
+
+    Raises
+    ------
+    ValueError
+        Raised when the provided operator names do not satisfy the canonical
+        sequence validation rules.
+
+    Examples
+    --------
+    Run a validated trajectory that highlights the ΔNFR-driven evolution of the
+    node metrics.
+
+    >>> from tnfr.constants import DNFR_PRIMARY, EPI_PRIMARY, THETA_PRIMARY, VF_PRIMARY
+    >>> from tnfr.dynamics import set_delta_nfr_hook
+    >>> from tnfr.structural import (
+    ...     Coherence,
+    ...     Emission,
+    ...     Reception,
+    ...     Resonance,
+    ...     Silence,
+    ...     create_nfr,
+    ...     run_sequence,
+    ... )
+    >>> G, node = create_nfr("seed", epi=0.8, vf=1.5, theta=0.0)
+    >>> def amplify_delta(graph):
+    ...     delta = graph.nodes[node][VF_PRIMARY] * 0.15
+    ...     graph.nodes[node][DNFR_PRIMARY] = delta
+    ...     graph.nodes[node][EPI_PRIMARY] += delta * 0.8
+    ...     graph.nodes[node][VF_PRIMARY] += delta * 0.1
+    ...     graph.nodes[node][THETA_PRIMARY] += 0.02
+    >>> set_delta_nfr_hook(G, amplify_delta)
+    >>> run_sequence(G, node, [Emission(), Reception(), Coherence(), Resonance(), Silence()])  # doctest: +SKIP
+    >>> (
+    ...     G.nodes[node][EPI_PRIMARY],
+    ...     G.nodes[node][VF_PRIMARY],
+    ...     G.nodes[node][THETA_PRIMARY],
+    ...     G.nodes[node][DNFR_PRIMARY],
+    ... )  # doctest: +SKIP
+    (..., ..., ..., ...)
+    """
 
     compute = G.graph.get("compute_delta_nfr")
     ops_list = list(ops)
-    nombres = [op.name for op in ops_list]
+    names = [op.name for op in ops_list]
 
-    ok, msg = validate_sequence(nombres)
-    if not ok:
-        raise ValueError(f"Invalid sequence: {msg}")
+    outcome = validate_sequence(names)
+    if not outcome.passed:
+        summary_message = outcome.summary.get("message", "validation failed")
+        raise ValueError(f"Invalid sequence: {summary_message}")
 
     for op in ops_list:
         op(G, node)