tnfr 3.5.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

tnfr/__init__.py

@@ -1,23 +1,57 @@
 
-from __future__ import annotations
-"""
-TNFR — Teoría de la Naturaleza Fractal Resonante
-API pública del paquete.
-
-Ecuación nodal:
-    ∂EPI/∂t = νf · ΔNFR(t)
-"""
-
-__version__ = "3.0.3"
+from __future__ import annotations
+"""
+TNFR — Teoría de la Naturaleza Fractal Resonante
+API pública del paquete.
+
+Ecuación nodal:
+    ∂EPI/∂t = νf · ΔNFR(t)
+"""
+
+__version__ = "4.0.0"
 
 # Re-exports de la API pública
 from .dynamics import step, run, set_delta_nfr_hook
 from .ontosim import preparar_red
 from .observers import attach_standard_observer, coherencia_global, orden_kuramoto
-
-__all__ = [
-    "preparar_red",
-    "step", "run", "set_delta_nfr_hook",
-    "attach_standard_observer", "coherencia_global", "orden_kuramoto",
-    "__version__",
-]
+from .gamma import GAMMA_REGISTRY, eval_gamma, kuramoto_R_psi
+from .grammar import enforce_canonical_grammar, on_applied_glifo
+from .sense import (
+    GLYPHS_CANONICAL, glyph_angle, glyph_unit,
+    sigma_vector_node, sigma_vector_global,
+    push_sigma_snapshot, sigma_series, sigma_rose,
+    register_sigma_callback,
+)
+from .metrics import (
+    register_metrics_callbacks,
+    Tg_global, Tg_by_node,
+    latency_series, glifogram_series,
+    glyph_top, glyph_dwell_stats,
+)
+from .trace import register_trace
+from .program import play, seq, block, target, wait, THOL, TARGET, WAIT
+from .cli import main as cli_main
+from .scenarios import build_graph
+from .presets import get_preset
+from .types import NodeState
+
+__all__ = [
+    "preparar_red",
+    "step", "run", "set_delta_nfr_hook",
+    "attach_standard_observer", "coherencia_global", "orden_kuramoto",
+    "GAMMA_REGISTRY", "eval_gamma", "kuramoto_R_psi",
+    "enforce_canonical_grammar", "on_applied_glifo",
+    "GLYPHS_CANONICAL", "glyph_angle", "glyph_unit",
+    "sigma_vector_node", "sigma_vector_global",
+    "push_sigma_snapshot", "sigma_series", "sigma_rose",
+    "register_sigma_callback",
+    "register_metrics_callbacks",
+    "register_trace",
+    "Tg_global", "Tg_by_node",
+    "latency_series", "glifogram_series",
+    "glyph_top", "glyph_dwell_stats",
+    "play", "seq", "block", "target", "wait", "THOL", "TARGET", "WAIT",
+    "__version__",
+]
+
+__all__ += ["cli_main", "build_graph", "get_preset", "NodeState"]

tnfr/cli.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+import argparse
+import json
+from typing import Any, Dict, List, Optional
+
+try:  # pragma: no cover - opcional
+    import yaml  # type: ignore
+except Exception:  # pragma: no cover - yaml es opcional
+    yaml = None
+
+import networkx as nx
+
+from .constants import inject_defaults, DEFAULTS
+from .sense import register_sigma_callback, sigma_series, sigma_rose
+from .metrics import (
+    register_metrics_callbacks,
+    Tg_global,
+    latency_series,
+    glifogram_series,
+    glyph_top,
+)
+from .trace import register_trace
+from .program import play, seq, block, wait, target
+from .dynamics import step, _update_history
+from .scenarios import build_graph
+from .presets import get_preset
+
+
+def _save_json(path: str, data: Any) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def _load_sequence(path: str) -> List[Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    if path.endswith(".yaml") or path.endswith(".yml"):
+        if not yaml:
+            raise RuntimeError("pyyaml no está instalado, usa JSON o instala pyyaml")
+        data = yaml.safe_load(text)
+    else:
+        data = json.loads(text)
+
+    def parse_token(tok: Any):
+        if isinstance(tok, str):
+            return tok
+        if isinstance(tok, dict):
+            if "WAIT" in tok:
+                return wait(int(tok["WAIT"]))
+            if "TARGET" in tok:
+                return target(tok["TARGET"])
+            if "THOL" in tok:
+                spec = tok["THOL"] or {}
+                b = [_parse_inner(x) for x in spec.get("body", [])]
+                return block(*b, repeat=int(spec.get("repeat", 1)), close=spec.get("close"))
+        raise ValueError(f"Token inválido: {tok}")
+
+    def _parse_inner(x: Any):
+        return parse_token(x)
+
+    return [parse_token(t) for t in data]
+
+
+def _attach_callbacks(G: nx.Graph) -> None:
+    inject_defaults(G, DEFAULTS)
+    register_sigma_callback(G)
+    register_metrics_callbacks(G)
+    register_trace(G)
+    _update_history(G)
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+
+    if args.preset:
+        program = get_preset(args.preset)
+        play(G, program)
+    else:
+        steps = int(args.steps or 100)
+        for _ in range(steps):
+            step(G)
+
+    if args.save_history:
+        _save_json(args.save_history, G.graph.get("history", {}))
+
+    if args.summary:
+        tg = Tg_global(G, normalize=True)
+        lat = latency_series(G)
+        print("Top glifos por Tg:", glyph_top(G, k=5))
+        if lat["value"]:
+            print("Latencia media:", sum(lat["value"]) / max(1, len(lat["value"])) )
+    return 0
+
+
+def cmd_sequence(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+
+    if args.preset:
+        program = get_preset(args.preset)
+    elif args.sequence_file:
+        program = _load_sequence(args.sequence_file)
+    else:
+        program = seq("A’L", "E’N", "I’L", block("O’Z", "Z’HIR", "I’L", repeat=1), "R’A", "SH’A")
+
+    play(G, program)
+
+    if args.save_history:
+        _save_json(args.save_history, G.graph.get("history", {}))
+    return 0
+
+
+def cmd_metrics(args: argparse.Namespace) -> int:
+    G = build_graph(n=args.nodes, topology=args.topology, seed=args.seed)
+    _attach_callbacks(G)
+    for _ in range(int(args.steps or 200)):
+        step(G)
+
+    tg = Tg_global(G, normalize=True)
+    lat = latency_series(G)
+    rose = sigma_rose(G)
+    glifo = glifogram_series(G)
+
+    out = {
+        "Tg_global": tg,
+        "latency_mean": (sum(lat["value"]) / max(1, len(lat["value"])) ) if lat["value"] else 0.0,
+        "rose": rose,
+        "glifogram": {k: v[:10] for k, v in glifo.items()},
+    }
+    if args.save:
+        _save_json(args.save, out)
+    else:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="tnfr")
+    sub = p.add_subparsers(dest="cmd")
+
+    p_run = sub.add_parser("run", help="Correr escenario libre o preset y opcionalmente exportar history")
+    p_run.add_argument("--nodes", type=int, default=24)
+    p_run.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_run.add_argument("--steps", type=int, default=200)
+    p_run.add_argument("--seed", type=int, default=1)
+    p_run.add_argument("--preset", type=str, default=None)
+    p_run.add_argument("--save-history", dest="save_history", type=str, default=None)
+    p_run.add_argument("--summary", action="store_true")
+    p_run.set_defaults(func=cmd_run)
+
+    p_seq = sub.add_parser("sequence", help="Ejecutar una secuencia (preset o YAML/JSON)")
+    p_seq.add_argument("--nodes", type=int, default=24)
+    p_seq.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_seq.add_argument("--seed", type=int, default=1)
+    p_seq.add_argument("--preset", type=str, default=None)
+    p_seq.add_argument("--sequence-file", type=str, default=None)
+    p_seq.add_argument("--save-history", dest="save_history", type=str, default=None)
+    p_seq.set_defaults(func=cmd_sequence)
+
+    p_met = sub.add_parser("metrics", help="Correr breve y volcar métricas clave")
+    p_met.add_argument("--nodes", type=int, default=24)
+    p_met.add_argument("--topology", choices=["ring", "complete", "erdos"], default="ring")
+    p_met.add_argument("--steps", type=int, default=300)
+    p_met.add_argument("--seed", type=int, default=1)
+    p_met.add_argument("--save", type=str, default=None)
+    p_met.set_defaults(func=cmd_metrics)
+
+    args = p.parse_args(argv)
+    if not hasattr(args, "func"):
+        p.print_help()
+        return 1
+    return int(args.func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tnfr/constants.py

@@ -10,7 +10,7 @@ from typing import Dict, Any
 # -------------------------
 # Parámetros canónicos
 # -------------------------
-DEFAULTS: Dict[str, Any] = {
+DEFAULTS: Dict[str, Any] = {
     # Discretización
     "DT": 1.0,
 
@@ -147,22 +147,52 @@ DEFAULTS: Dict[str, Any] = {
         "dnfr_hi": 0.50, "dnfr_lo": 0.10,
         "accel_hi": 0.50, "accel_lo": 0.10
     },
-    # Callbacks Γ(R)
-    "CALLBACKS_STRICT": False,  # si True, un error en callback detiene; si False, se loguea y continúa
-}
+    # Callbacks Γ(R)
+    "GAMMA": {
+        "type": "none",  # 'none' | 'kuramoto_linear' | 'kuramoto_bandpass'
+        "beta": 0.0,
+        "R0": 0.0,
+    },
+    "CALLBACKS_STRICT": False,  # si True, un error en callback detiene; si False, se loguea y continúa
+}
+
+# Gramática glífica canónica
+DEFAULTS.setdefault("GRAMMAR_CANON", {
+    "enabled": True,                # activar la gramática canónica
+    "zhir_requires_oz_window": 3,   # cuántos pasos atrás buscamos O’Z
+    "zhir_dnfr_min": 0.05,          # si |ΔNFR|_norm < este valor, no permitimos Z’HIR sin O’Z
+    "thol_min_len": 2,
+    "thol_max_len": 6,
+    "thol_close_dnfr": 0.15,        # si el campo calma, cerramos con SH’A/NU’L
+    "si_high": 0.66,                # umbral para elegir NU’L vs SH’A al cerrar
+})
 
 
 # -------------------------
 # Utilidades
 # -------------------------
 
-def attach_defaults(G, override: bool = False) -> None:
-    """Escribe DEFAULTS en G.graph (sin sobreescribir si override=False)."""
-    G.graph.setdefault("_tnfr_defaults_attached", False)
-    for k, v in DEFAULTS.items():
-        if override or k not in G.graph:
-            G.graph[k] = v
-    G.graph["_tnfr_defaults_attached"] = True
+def attach_defaults(G, override: bool = False) -> None:
+    """Escribe DEFAULTS en G.graph (sin sobreescribir si override=False)."""
+    G.graph.setdefault("_tnfr_defaults_attached", False)
+    for k, v in DEFAULTS.items():
+        if override or k not in G.graph:
+            G.graph[k] = v
+    G.graph["_tnfr_defaults_attached"] = True
+
+
+def inject_defaults(G, defaults: Dict[str, Any] = DEFAULTS, override: bool = False) -> None:
+    """Alias de conveniencia para inyectar ``DEFAULTS`` en ``G.graph``.
+
+    Permite pasar un diccionario de *defaults* alternativo y mantiene la
+    semántica de ``attach_defaults`` existente. Si ``override`` es ``True`` se
+    sobreescriben valores ya presentes.
+    """
+    G.graph.setdefault("_tnfr_defaults_attached", False)
+    for k, v in defaults.items():
+        if override or k not in G.graph:
+            G.graph[k] = v
+    G.graph["_tnfr_defaults_attached"] = True
 
 
 def merge_overrides(G, **overrides) -> None:

tnfr/dynamics.py

@@ -18,7 +18,9 @@ import networkx as nx
 
 from .observers import sincronía_fase, carga_glifica, orden_kuramoto, sigma_vector
 from .operators import aplicar_remesh_si_estabilizacion_global
+from .grammar import select_and_apply_with_grammar
 from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_dEPI, ALIAS_D2EPI
+from .gamma import eval_gamma
 from .helpers import (
      clamp, clamp01, list_mean, phase_distance,
      _get_attr, _set_attr, media_vecinal, fase_media,
@@ -52,6 +54,7 @@ def _write_dnfr_metadata(G, *, weights: dict, hook_name: str, note: str | None =
 
 
 def default_compute_delta_nfr(G) -> None:
+    """Calcula ΔNFR mezclando gradientes de fase, EPI y νf según pesos."""
     w = G.graph.get("DNFR_WEIGHTS", DEFAULTS["DNFR_WEIGHTS"])  # dict
     w_phase = float(w.get("phase", 0.34))
     w_epi = float(w.get("epi", 0.33))
@@ -121,7 +124,23 @@ def dnfr_epi_vf_mixed(G) -> None:
 # Ecuación nodal
 # -------------------------
 
-def update_epi_via_nodal_equation(G, *, dt: float = None) -> None:
+def update_epi_via_nodal_equation(G, *, dt: float = None, t: float | None = None) -> None:
+    """Ecuación nodal TNFR.
+
+    Implementa la forma extendida de la ecuación nodal:
+        ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+
+    Donde:
+      - EPI es la Estructura Primaria de Información del nodo.
+      - νf es la frecuencia estructural del nodo (Hz_str).
+      - ΔNFR(t) es el gradiente nodal (necesidad de reorganización),
+        típicamente una mezcla de componentes (p. ej. fase θ, EPI, νf).
+      - Γi(R) es el acoplamiento de red opcional en función del orden de Kuramoto R
+        (ver gamma.py), usado para modular la integración en red.
+
+    Referencias TNFR: ecuación nodal (manual), glosario νf/ΔNFR/EPI, operador Γ.
+    Efectos secundarios: cachea dEPI y actualiza EPI por integración explícita.
+    """
     if not isinstance(G, (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph)):
         raise TypeError("G must be a networkx graph instance")
     if dt is None:
@@ -132,16 +151,22 @@ def update_epi_via_nodal_equation(G, *, dt: float = None) -> None:
         if dt < 0:
             raise ValueError("dt must be non-negative")
         dt = float(dt)
+    if t is None:
+        t = float(G.graph.get("_t", 0.0))
+    else:
+        t = float(t)
     for n in G.nodes():
         nd = G.nodes[n]
         vf = _get_attr(nd, ALIAS_VF, 0.0)
         dnfr = _get_attr(nd, ALIAS_DNFR, 0.0)
         dEPI_dt_prev = _get_attr(nd, ALIAS_dEPI, 0.0)
         dEPI_dt = vf * dnfr
+        dEPI_dt += eval_gamma(G, n, t)
         epi = _get_attr(nd, ALIAS_EPI, 0.0) + dt * dEPI_dt
         _set_attr(nd, ALIAS_EPI, epi)
         _set_attr(nd, ALIAS_dEPI, dEPI_dt)
         _set_attr(nd, ALIAS_D2EPI, (dEPI_dt - dEPI_dt_prev) / dt if dt != 0 else 0.0)
+    G.graph["_t"] = t + dt
 
 
 # -------------------------
@@ -432,9 +457,13 @@ def step(G, *, dt: float | None = None, use_Si: bool = True, apply_glyphs: bool
         selector = G.graph.get("glyph_selector", default_glyph_selector)
         from .operators import aplicar_glifo
         window = int(G.graph.get("GLYPH_HYSTERESIS_WINDOW", DEFAULTS["GLYPH_HYSTERESIS_WINDOW"]))
+        use_canon = bool(G.graph.get("GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {})).get("enabled", False))
         for n in G.nodes():
-            g = selector(G, n)
-            aplicar_glifo(G, n, g, window=window)
+            if use_canon:
+                select_and_apply_with_grammar(G, n, selector, window)
+            else:
+                g = selector(G, n)
+                aplicar_glifo(G, n, g, window=window)
 
     # 4) Ecuación nodal
     update_epi_via_nodal_equation(G, dt=dt)

tnfr/gamma.py

@@ -0,0 +1,91 @@
+"""gamma.py — TNFR canónica
+
+Γi(R): acoplamientos de red para la ecuación nodal extendida
+    ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+
+Provee:
+- kuramoto_R_psi(G): (R, ψ) orden de Kuramoto en la red
+- GAMMA_REGISTRY: registro de acoplamientos canónicos
+- eval_gamma(G, node, t): evalúa Γ para cada nodo según G.graph['GAMMA']
+"""
+from __future__ import annotations
+from typing import Dict, Any, Tuple
+import math
+import cmath
+
+from .constants import ALIAS_THETA
+
+
+def _get_attr(nd: Dict[str, Any], aliases, default: float = 0.0) -> float:
+    """Obtiene el primer atributo presente en nd según aliases."""
+    for k in aliases:
+        if k in nd:
+            return nd[k]
+    return default
+
+
+def kuramoto_R_psi(G) -> Tuple[float, float]:
+    """Devuelve (R, ψ) del orden de Kuramoto usando θ de todos los nodos."""
+    acc = 0 + 0j
+    n = 0
+    for node in G.nodes():
+        nd = G.nodes[node]
+        th = _get_attr(nd, ALIAS_THETA, 0.0)
+        acc += cmath.exp(1j * th)
+        n += 1
+    if n == 0:
+        return 0.0, 0.0
+    z = acc / n
+    return abs(z), math.atan2(z.imag, z.real)
+
+
+# -----------------
+# Γi(R) canónicos
+# -----------------
+
+
+def gamma_none(G, node, t, cfg: Dict[str, Any]) -> float:
+    return 0.0
+
+
+def gamma_kuramoto_linear(G, node, t, cfg: Dict[str, Any]) -> float:
+    """Acoplamiento lineal de Kuramoto para Γi(R).
+
+    Fórmula: Γ = β · (R - R0) · cos(θ_i - ψ)
+      - R ∈ [0,1] es el orden global de fase.
+      - ψ es la fase media (dirección de coordinación).
+      - β, R0 son parámetros (ganancia/umbral).
+
+    Uso: refuerza integración cuando la red ya exhibe coherencia de fase (R>R0).
+    """
+    beta = float(cfg.get("beta", 0.0))
+    R0 = float(cfg.get("R0", 0.0))
+    R, psi = kuramoto_R_psi(G)
+    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    return beta * (R - R0) * math.cos(th_i - psi)
+
+
+def gamma_kuramoto_bandpass(G, node, t, cfg: Dict[str, Any]) -> float:
+    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
+    beta = float(cfg.get("beta", 0.0))
+    R, psi = kuramoto_R_psi(G)
+    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+    sgn = 1.0 if math.cos(th_i - psi) >= 0.0 else -1.0
+    return beta * R * (1.0 - R) * sgn
+
+
+GAMMA_REGISTRY = {
+    "none": gamma_none,
+    "kuramoto_linear": gamma_kuramoto_linear,
+    "kuramoto_bandpass": gamma_kuramoto_bandpass,
+}
+
+
+def eval_gamma(G, node, t) -> float:
+    """Evalúa Γi para `node` según la especificación en G.graph['GAMMA']."""
+    spec = G.graph.get("GAMMA", {"type": "none"})
+    fn = GAMMA_REGISTRY.get(spec.get("type", "none"), gamma_none)
+    try:
+        return float(fn(G, node, t, spec))
+    except Exception:
+        return 0.0

tnfr/grammar.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+from typing import Dict, Any, Set
+
+from .constants import (
+    DEFAULTS,
+    ALIAS_SI, ALIAS_DNFR, ALIAS_EPI,
+)
+from .helpers import _get_attr, clamp01, reciente_glifo
+from collections import deque
+
+# Glifos nominales (para evitar typos)
+AL = "A’L"; EN = "E’N"; IL = "I’L"; OZ = "O’Z"; UM = "U’M"; RA = "R’A"; SHA = "SH’A"; VAL = "VA’L"; NUL = "NU’L"; THOL = "T’HOL"; ZHIR = "Z’HIR"; NAV = "NA’V"; REMESH = "RE’MESH"
+
+# -------------------------
+# Estado de gramática por nodo
+# -------------------------
+
+def _gram_state(nd: Dict[str, Any]) -> Dict[str, Any]:
+    """Crea/retorna el estado de gramática nodal.
+    Campos:
+      - thol_open (bool)
+      - thol_len (int)
+    """
+    st = nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
+    st.setdefault("thol_open", False)
+    st.setdefault("thol_len", 0)
+    return st
+
+# -------------------------
+# Compatibilidades canónicas (siguiente permitido)
+# -------------------------
+CANON_COMPAT: Dict[str, Set[str]] = {
+    # Inicio / apertura
+    AL:   {EN, RA, NAV, VAL, UM},
+    EN:   {IL, UM, RA, NAV},
+    # Estabilización / difusión / acople
+    IL:   {RA, VAL, UM, SHA},
+    UM:   {RA, IL, VAL, NAV},
+    RA:   {IL, VAL, UM, NAV},
+    VAL:  {UM, RA, IL, NAV},
+    # Disonancia → transición → mutación
+    OZ:   {ZHIR, NAV},
+    ZHIR: {IL, NAV},
+    NAV:  {OZ, ZHIR, RA, IL, UM},
+    # Cierres / latencias
+    SHA:  {AL, EN},
+    NUL:  {AL, IL},
+    # Bloques autoorganizativos
+    THOL: {OZ, ZHIR, NAV, RA, IL, UM, SHA, NUL},
+}
+
+# Fallbacks canónicos si una transición no está permitida
+CANON_FALLBACK: Dict[str, str] = {
+    AL: EN, EN: IL, IL: RA, UM: RA, RA: IL, VAL: RA, OZ: ZHIR, ZHIR: IL, NAV: RA, SHA: AL, NUL: AL, THOL: NAV,
+}
+
+# -------------------------
+# Cierres T’HOL y precondiciones Z’HIR
+# -------------------------
+
+def _dnfr_norm(G, nd) -> float:
+    # Normalizador robusto: usa historial de |ΔNFR| máx guardado por dynamics (si existe)
+    norms = G.graph.get("_sel_norms") or {}
+    dmax = float(norms.get("dnfr_max", 1.0)) or 1.0
+    return clamp01(abs(_get_attr(nd, ALIAS_DNFR, 0.0)) / dmax)
+
+
+def _si(G, nd) -> float:
+    return clamp01(_get_attr(nd, ALIAS_SI, 0.5))
+
+# -------------------------
+# Núcleo: forzar gramática sobre un candidato
+# -------------------------
+
+def enforce_canonical_grammar(G, n, cand: str) -> str:
+    """Valida/ajusta el glifo candidato según la gramática canónica.
+
+    Reglas clave:
+      - Compatibilidades de transición glífica (recorrido TNFR).
+      - O’Z→Z’HIR: la mutación requiere disonancia reciente o |ΔNFR| alto.
+      - T’HOL[...]: obliga cierre con SH’A o NU’L cuando el campo se estabiliza
+        o se alcanza el largo del bloque; mantiene estado por nodo.
+
+    Devuelve el glifo efectivo a aplicar.
+    """
+    nd = G.nodes[n]
+    st = _gram_state(nd)
+    cfg = G.graph.get("GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {}))
+
+    # 0) Si vienen glifos fuera del alfabeto, no tocamos
+    if cand not in CANON_COMPAT:
+        return cand
+
+    # 1) Precondición O’Z→Z’HIR: mutación requiere disonancia reciente o campo fuerte
+    if cand == ZHIR:
+        win = int(cfg.get("zhir_requires_oz_window", 3))
+        dn_min = float(cfg.get("zhir_dnfr_min", 0.05))
+        if not reciente_glifo(nd, OZ, win) and _dnfr_norm(G, nd) < dn_min:
+            cand = OZ  # forzamos paso por O’Z
+
+    # 2) Si estamos dentro de T’HOL, control de cierre obligado
+    if st.get("thol_open", False):
+        st["thol_len"] = int(st.get("thol_len", 0))
+        st["thol_len"] += 1
+        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))
+        if st["thol_len"] >= maxlen or (st["thol_len"] >= minlen and _dnfr_norm(G, nd) <= close_dn):
+            cand = NUL if _si(G, nd) >= float(cfg.get("si_high", 0.66)) else SHA
+
+    # 3) Compatibilidades: si el anterior restringe el siguiente
+    prev = None
+    hist = nd.get("hist_glifos")
+    if hist:
+        try:
+            prev = list(hist)[-1]
+        except Exception:
+            prev = None
+    if prev in CANON_COMPAT and cand not in CANON_COMPAT[prev]:
+        cand = CANON_FALLBACK.get(prev, cand)
+
+    return cand
+
+# -------------------------
+# Post-selección: actualizar estado de gramática
+# -------------------------
+
+def on_applied_glifo(G, n, applied: str) -> None:
+    nd = G.nodes[n]
+    st = _gram_state(nd)
+    if applied == THOL:
+        st["thol_open"] = True
+        st["thol_len"] = 0
+    elif applied in (SHA, NUL):
+        st["thol_open"] = False
+        st["thol_len"] = 0
+    else:
+        pass
+
+# -------------------------
+# Integración con dynamics.step: helper de selección+aplicación
+# -------------------------
+
+def select_and_apply_with_grammar(G, n, selector, window: int) -> None:
+    from .operators import aplicar_glifo
+    cand = selector(G, n)
+    cand = enforce_canonical_grammar(G, n, cand)
+    aplicar_glifo(G, n, cand, window=window)
+    on_applied_glifo(G, n, cand)