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

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)

tnfr/helpers.py

@@ -4,37 +4,44 @@ helpers.py — TNFR canónica
 Utilidades transversales + cálculo de Índice de sentido (Si).
 """
 from __future__ import annotations
-from typing import Iterable, Dict, Any, Tuple, List
+from typing import Iterable, Dict, Any
 import math
 from collections import deque
+from statistics import fmean, StatisticsError
 
 try:
     import networkx as nx  # solo para tipos
 except Exception:  # pragma: no cover
     nx = None  # type: ignore
 
-from constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI
+from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_SI
 
 # -------------------------
 # Utilidades numéricas
 # -------------------------
 
 def clamp(x: float, a: float, b: float) -> float:
+    """Constriñe ``x`` al intervalo cerrado [a, b]."""
     return a if x < a else b if x > b else x
 
 
 def clamp_abs(x: float, m: float) -> float:
+    """Limita ``x`` al rango simétrico [-m, m] usando ``abs(m)``."""
     m = abs(m)
     return clamp(x, -m, m)
 
 
 def clamp01(x: float) -> float:
+    """Ataja ``x`` a la banda [0, 1]."""
     return clamp(x, 0.0, 1.0)
 
 
 def list_mean(xs: Iterable[float], default: float = 0.0) -> float:
-    xs = list(xs)
-    return sum(xs) / len(xs) if xs else default
+    """Promedio aritmético o ``default`` si ``xs`` está vacío."""
+    try:
+        return fmean(xs)
+    except StatisticsError:
+        return default
 
 
 def _wrap_angle(a: float) -> float:
@@ -74,17 +81,14 @@ def _set_attr(d, aliases, value: float) -> None:
 # -------------------------
 
 def media_vecinal(G, n, aliases: Iterable[str], default: float = 0.0) -> float:
-    vals: List[float] = []
-    for v in G.neighbors(n):
-        vals.append(_get_attr(G.nodes[v], aliases, default))
+    """Media del atributo indicado por ``aliases`` en los vecinos de ``n``."""
+    vals = (_get_attr(G.nodes[v], aliases, default) for v in G.neighbors(n))
     return list_mean(vals, default)
 
 
 def fase_media(G, n) -> float:
     """Promedio circular de las fases de los vecinos."""
-    import math
-    x = 0.0
-    y = 0.0
+    x = y = 0.0
     count = 0
     for v in G.neighbors(n):
         th = _get_attr(G.nodes[v], ALIAS_THETA, 0.0)
@@ -93,7 +97,7 @@ def fase_media(G, n) -> float:
         count += 1
     if count == 0:
         return _get_attr(G.nodes[n], ALIAS_THETA, 0.0)
-    return math.atan2(y / max(1, count), x / max(1, count))
+    return math.atan2(y / count, x / count)
 
 
 # -------------------------
@@ -101,16 +105,24 @@ def fase_media(G, n) -> float:
 # -------------------------
 
 def push_glifo(nd: Dict[str, Any], glifo: str, window: int) -> None:
+    """Añade ``glifo`` al historial del nodo con tamaño máximo ``window``."""
     hist = nd.setdefault("hist_glifos", deque(maxlen=window))
     hist.append(str(glifo))
 
 
 def reciente_glifo(nd: Dict[str, Any], glifo: str, ventana: int) -> bool:
+    """Indica si ``glifo`` apareció en las últimas ``ventana`` emisiones."""
     hist = nd.get("hist_glifos")
     if not hist:
         return False
-    last = list(hist)[-ventana:]
-    return str(glifo) in last
+    gl = str(glifo)
+    for g in reversed(hist):
+        if g == gl:
+            return True
+        ventana -= 1
+        if ventana <= 0:
+            break
+    return False
 
 # -------------------------
 # Callbacks Γ(R)
@@ -128,10 +140,26 @@ def _ensure_callbacks(G):
         cbs.setdefault(k, [])
     return cbs
 
-def register_callback(G, event: str, func):
-    """Registra un callback en G.graph['callbacks'][event]. Firma: func(G, ctx) -> None"""
+def register_callback(
+    G,
+    event: str | None = None,
+    func=None,
+    *,
+    when: str | None = None,
+    name: str | None = None,
+):
+    """Registra ``func`` como callback del ``event`` indicado.
+
+    Permite tanto la forma posicional ``register_callback(G, "after_step", fn)``
+    como la forma con palabras clave ``register_callback(G, when="after_step", func=fn)``.
+    El parámetro ``name`` se acepta por compatibilidad pero actualmente no se
+    utiliza.
+    """
+    event = event or when
     if event not in ("before_step", "after_step", "on_remesh"):
         raise ValueError(f"Evento desconocido: {event}")
+    if func is None:
+        raise TypeError("func es obligatorio")
     cbs = _ensure_callbacks(G)
     cbs[event].append(func)
     return func

tnfr/main.py

@@ -1,7 +1,11 @@
 from __future__ import annotations
-import argparse, sys
-import networkx as nx
-from . import preparar_red, run, __version__
+import argparse, sys
+import networkx as nx
+from . import preparar_red, run, __version__
+from .constants import merge_overrides, attach_defaults
+from .sense import register_sigma_callback
+from .metrics import register_metrics_callbacks
+from .trace import register_trace
 
 def main(argv: list[str] | None = None) -> None:
     p = argparse.ArgumentParser(
@@ -15,13 +19,19 @@ def main(argv: list[str] | None = None) -> None:
     p.add_argument("--observer", action="store_true", help="adjunta observador estándar")
     args = p.parse_args(argv)
 
-    if args.version:
-        print(__version__)
-        return
-
-    G = nx.erdos_renyi_graph(args.n, args.p)
-    preparar_red(G, ATTACH_STD_OBSERVER=bool(args.observer))
-    run(G, args.steps)
+    if args.version:
+        print(__version__)
+        return
+
+    G = nx.erdos_renyi_graph(args.n, args.p)
+    preparar_red(G, ATTACH_STD_OBSERVER=bool(args.observer))
+    attach_defaults(G)
+    register_sigma_callback(G)
+    register_metrics_callbacks(G)
+    register_trace(G)
+    # Ejemplo: activar Γi(R) lineal con β=0.2 y R0=0.5
+    merge_overrides(G, GAMMA={"type": "kuramoto_linear", "beta": 0.2, "R0": 0.5})
+    run(G, args.steps)
 
     h = G.graph.get("history", {})
     C = h.get("C_steps", [])[-1] if h.get("C_steps") else None

tnfr/metrics.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+from typing import Dict, Any, List, Tuple
+from collections import defaultdict, Counter
+import statistics
+
+from .constants import DEFAULTS
+from .helpers import _get_attr, clamp01, register_callback
+from .sense import GLYPHS_CANONICAL
+
+# -------------
+# DEFAULTS
+# -------------
+DEFAULTS.setdefault("METRICS", {
+    "enabled": True,
+    "save_by_node": True,     # guarda Tg por nodo (más pesado)
+    "normalize_series": False # glifograma normalizado a fracción por paso
+})
+
+# -------------
+# Utilidades internas
+# -------------
+
+def _ensure_history(G):
+    if "history" not in G.graph:
+        G.graph["history"] = {}
+    return G.graph["history"]
+
+
+def _last_glifo(nd: Dict[str, Any]) -> str | None:
+    hist = nd.get("hist_glifos")
+    if not hist:
+        return None
+    try:
+        return list(hist)[-1]
+    except Exception:
+        return None
+
+
+# -------------
+# Estado nodal para Tg
+# -------------
+
+def _tg_state(nd: Dict[str, Any]) -> Dict[str, Any]:
+    """Estructura interna por nodo para acumular tiempos de corrida por glifo.
+    Campos: curr (glifo actual), run (tiempo acumulado en el glifo actual)
+    """
+    st = nd.setdefault("_Tg", {"curr": None, "run": 0.0})
+    st.setdefault("curr", None)
+    st.setdefault("run", 0.0)
+    return st
+
+
+# -------------
+# Callback principal: actualizar métricas por paso
+# -------------
+
+def _metrics_step(G, *args, **kwargs):
+    """Actualiza métricas operativas TNFR por paso.
+
+    - Tg (tiempo glífico): sumatoria de corridas por glifo (global y por nodo).
+    - Índice de latencia: fracción de nodos en SH’A.
+    - Glifograma: conteo o fracción por glifo en el paso.
+
+    Todos los resultados se guardan en G.graph['history'].
+    """
+    if not G.graph.get("METRICS", DEFAULTS.get("METRICS", {})).get("enabled", True):
+        return
+
+    hist = _ensure_history(G)
+    dt = float(G.graph.get("DT", 1.0))
+    t = float(G.graph.get("_t", 0.0))
+
+    # --- Glifograma (conteos por glifo este paso) ---
+    counts = Counter()
+
+    # --- Índice de latencia: proporción de nodos en SH’A ---
+    n_total = 0
+    n_latent = 0
+
+    # --- Tg: acumular corridas por nodo ---
+    save_by_node = bool(G.graph.get("METRICS", DEFAULTS["METRICS"]).get("save_by_node", True))
+    tg_total = hist.setdefault("Tg_total", defaultdict(float))  # tiempo total por glifo (global)
+    tg_by_node = hist.setdefault("Tg_by_node", {})             # nodo → {glifo: [runs,...]}
+
+    for n in G.nodes():
+        nd = G.nodes[n]
+        g = _last_glifo(nd)
+        if not g:
+            continue
+
+        n_total += 1
+        if g == "SH’A":
+            n_latent += 1
+
+        counts[g] += 1
+
+        st = _tg_state(nd)
+        # Si seguimos en el mismo glifo, acumulamos; si cambiamos, cerramos corrida
+        if st["curr"] is None:
+            st["curr"] = g
+            st["run"] = dt
+        elif g == st["curr"]:
+            st["run"] += dt
+        else:
+            # cerramos corrida anterior
+            prev = st["curr"]
+            dur = float(st["run"])
+            tg_total[prev] += dur
+            if save_by_node:
+                rec = tg_by_node.setdefault(n, defaultdict(list))
+                rec[prev].append(dur)
+            # reiniciamos corrida
+            st["curr"] = g
+            st["run"] = dt
+
+    # Al final del paso, no cerramos la corrida actual: se cerrará cuando cambie.
+
+    # Guardar glifograma (conteos crudos y normalizados)
+    norm = bool(G.graph.get("METRICS", DEFAULTS["METRICS"]).get("normalize_series", False))
+    row = {"t": t}
+    total = max(1, sum(counts.values()))
+    for g in GLYPHS_CANONICAL:
+        c = counts.get(g, 0)
+        row[g] = (c / total) if norm else c
+    hist.setdefault("glifogram", []).append(row)
+
+    # Guardar índice de latencia
+    li = (n_latent / max(1, n_total)) if n_total else 0.0
+    hist.setdefault("latency_index", []).append({"t": t, "value": li})
+
+
+# -------------
+# Registro del callback
+# -------------
+
+def register_metrics_callbacks(G) -> None:
+    register_callback(G, when="after_step", func=_metrics_step, name="metrics_step")
+
+
+# -------------
+# Consultas / reportes
+# -------------
+
+def Tg_global(G, normalize: bool = True) -> Dict[str, float]:
+    """Tiempo glífico total por clase. Si normalize=True, devuelve fracciones del total."""
+    hist = _ensure_history(G)
+    tg_total: Dict[str, float] = hist.get("Tg_total", {})
+    total = sum(tg_total.values()) or 1.0
+    if normalize:
+        return {g: float(tg_total.get(g, 0.0)) / total for g in GLYPHS_CANONICAL}
+    return {g: float(tg_total.get(g, 0.0)) for g in GLYPHS_CANONICAL}
+
+
+def Tg_by_node(G, n, normalize: bool = False) -> Dict[str, float | List[float]]:
+    """Resumen por nodo: si normalize, devuelve medias por glifo; si no, lista de corridas."""
+    hist = _ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    if not normalize:
+        # convertir default dict → list para serializar
+        return {g: list(rec.get(g, [])) for g in GLYPHS_CANONICAL}
+    out = {}
+    for g in GLYPHS_CANONICAL:
+        runs = rec.get(g, [])
+        out[g] = float(statistics.mean(runs)) if runs else 0.0
+        
+    return out
+
+
+def latency_series(G) -> Dict[str, List[float]]:
+    hist = _ensure_history(G)
+    xs = hist.get("latency_index", [])
+    return {
+        "t": [float(x.get("t", i)) for i, x in enumerate(xs)],
+        "value": [float(x.get("value", 0.0)) for x in xs],
+    }
+
+
+def glifogram_series(G) -> Dict[str, List[float]]:
+    hist = _ensure_history(G)
+    xs = hist.get("glifogram", [])
+    if not xs:
+        return {"t": []}
+    out = {"t": [float(x.get("t", i)) for i, x in enumerate(xs)]}
+    for g in GLYPHS_CANONICAL:
+        out[g] = [float(x.get(g, 0.0)) for x in xs]
+    return out
+
+
+def glyph_top(G, k: int = 3) -> List[Tuple[str, float]]:
+    """Top-k glifos por Tg_global (fracción)."""
+    tg = Tg_global(G, normalize=True)
+    return sorted(tg.items(), key=lambda kv: kv[1], reverse=True)[:max(1, int(k))]
+
+
+def glyph_dwell_stats(G, n) -> Dict[str, Dict[str, float]]:
+    """Estadísticos por nodo: mean/median/max de corridas por glifo."""
+    hist = _ensure_history(G)
+    rec = hist.get("Tg_by_node", {}).get(n, {})
+    out = {}
+    for g in GLYPHS_CANONICAL:
+        runs = list(rec.get(g, []))
+        if not runs:
+            out[g] = {"mean": 0.0, "median": 0.0, "max": 0.0, "count": 0}
+        else:
+            out[g] = {
+                "mean": float(statistics.mean(runs)),
+                "median": float(statistics.median(runs)),
+                "max": float(max(runs)),
+                "count": int(len(runs)),
+            }
+    return out

tnfr/observers.py

@@ -8,8 +8,8 @@ from collections import Counter
 from typing import Dict, Any
 import math
 
-from constants import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_dEPI
-from helpers import _get_attr, list_mean, register_callback
+from .constants import ALIAS_DNFR, ALIAS_EPI, ALIAS_THETA, ALIAS_dEPI
+from .helpers import _get_attr, list_mean, register_callback
 
 # -------------------------
 # Observador estándar Γ(R)
@@ -44,15 +44,27 @@ def coherencia_global(G) -> float:
 
 
 def sincronía_fase(G) -> float:
-    X = list(math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes())
-    Y = list(math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes())
+    X = [math.cos(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
+    Y = [math.sin(_get_attr(G.nodes[n], ALIAS_THETA, 0.0)) for n in G.nodes()]
     if not X:
         return 1.0
-    import math
-    th = math.atan2(sum(Y)/len(Y), sum(X)/len(X))
+    th = math.atan2(sum(Y) / len(Y), sum(X) / len(X))
     # varianza angular aproximada (0 = muy sincronizado)
     import statistics as st
-    var = st.pvariance([((_get_attr(G.nodes[n], ALIAS_THETA, 0.0) - th + math.pi) % (2*math.pi) - math.pi) for n in G.nodes()]) if len(X) > 1 else 0.0
+    var = (
+        st.pvariance(
+            [
+                (
+                    (_get_attr(G.nodes[n], ALIAS_THETA, 0.0) - th + math.pi)
+                    % (2 * math.pi)
+                    - math.pi
+                )
+                for n in G.nodes()
+            ]
+        )
+        if len(X) > 1
+        else 0.0
+    )
     return 1.0 / (1.0 + var)
 
 def orden_kuramoto(G) -> float:

tnfr/ontosim.py

@@ -5,20 +5,21 @@ Módulo de orquestación mínima que encadena:
 ΔNFR (campo) → Si → glifos → ecuación nodal → clamps → U’M → observadores → RE’MESH
 """
 from __future__ import annotations
-import networkx as nx
-import math
-import random
+import networkx as nx
+import math
+import random
+from collections import deque
 
-from constants import DEFAULTS, attach_defaults
-from dynamics import step as _step, run as _run
-from dynamics import default_compute_delta_nfr
+from .constants import DEFAULTS, attach_defaults
+from .dynamics import step as _step, run as _run
+from .dynamics import default_compute_delta_nfr
 
 # API de alto nivel
 
 def preparar_red(G: nx.Graph, *, override_defaults: bool = False, **overrides) -> nx.Graph:
     attach_defaults(G, override=override_defaults)
     if overrides:
-        from constants import merge_overrides
+        from .constants import merge_overrides
         merge_overrides(G, **overrides)
     # Inicializaciones blandas
     G.graph.setdefault("history", {
@@ -43,11 +44,13 @@ def preparar_red(G: nx.Graph, *, override_defaults: bool = False, **overrides) -
         "phase_R": [], 
         "phase_disr": [],
     })
-    G.graph.setdefault("_epi_hist", [])
+    tau = int(G.graph.get("REMESH_TAU", DEFAULTS["REMESH_TAU"]))
+    maxlen = max(2 * tau + 5, 64)
+    G.graph.setdefault("_epi_hist", deque(maxlen=maxlen))
     # Auto-attach del observador estándar si se pide
     if G.graph.get("ATTACH_STD_OBSERVER", False):
         try:
-            from observers import attach_standard_observer
+            from .observers import attach_standard_observer
             attach_standard_observer(G)
         except Exception as e:
             G.graph.setdefault("_callback_errors", []).append(

tnfr/operators.py

@@ -5,14 +5,15 @@ import math
 import random
 import hashlib
 
-from constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_D2EPI
-from helpers import _get_attr, _set_attr, clamp, clamp01, list_mean, fase_media, push_glifo, invoke_callbacks
+from .constants import DEFAULTS, ALIAS_VF, ALIAS_THETA, ALIAS_DNFR, ALIAS_EPI, ALIAS_D2EPI
+from .helpers import _get_attr, _set_attr, clamp, clamp01, list_mean, fase_media, push_glifo, invoke_callbacks
+from collections import deque
 
 """
 Este módulo implementa:
 - Los 13 glifos como operadores locales suaves.
 - Un dispatcher `aplicar_glifo` que mapea el nombre del glifo (con apóstrofo tipográfico) a su función.
-- RE’MESH de red: `aplicar_remesh_red` y `aplicar_remesh_si_estabilizacion_global`.
+- RE’MESH de red: `aplicar_remesh_red` y `aplicar_remesh_si_estabilización_global`.
 
 Nota sobre α (alpha) de RE’MESH: se toma por prioridad de
 1) G.graph["GLYPH_FACTORS"]["REMESH_alpha"]
@@ -153,6 +154,18 @@ _NAME_TO_OP = {
 
 
 def aplicar_glifo(G, n, glifo: str, *, window: Optional[int] = None) -> None:
+    """Aplica un glifo TNFR al nodo `n` con histéresis `window`.
+
+    Los 13 glifos implementan reorganizadores canónicos:
+      A’L (emisión), E’N (recepción), I’L (coherencia), O’Z (disonancia),
+      U’M (acoplamiento), R’A (resonancia), SH’A (silencio), VA’L (expansión),
+      NU’L (contracción), T’HOL (autoorganización), Z’HIR (mutación),
+      NA’V (transición), RE’MESH (recursividad).
+
+    Relación con la gramática: la selección previa debe pasar por
+    `enforce_canonical_grammar` (grammar.py) para respetar compatibilidades,
+    precondición O’Z→Z’HIR y cierres T’HOL[...].
+    """
     glifo = str(glifo)
     op = _NAME_TO_OP.get(glifo)
     if not op:
@@ -186,7 +199,7 @@ def aplicar_remesh_red(G) -> None:
     """
     tau = int(G.graph.get("REMESH_TAU", DEFAULTS["REMESH_TAU"]))
     alpha, alpha_src = _remesh_alpha_info(G)
-    hist = G.graph.get("_epi_hist", [])
+    hist = G.graph.get("_epi_hist", deque())
     if len(hist) < tau + 1:
         return
 
@@ -256,7 +269,11 @@ def aplicar_remesh_red(G) -> None:
 
 def aplicar_remesh_si_estabilizacion_global(G, pasos_estables_consecutivos: Optional[int] = None) -> None:
     # Ventanas y umbrales
-    w_estab = int(G.graph.get("REMESH_STABILITY_WINDOW", DEFAULTS["REMESH_STABILITY_WINDOW"]))
+    w_estab = (
+        pasos_estables_consecutivos
+        if pasos_estables_consecutivos is not None
+        else int(G.graph.get("REMESH_STABILITY_WINDOW", DEFAULTS["REMESH_STABILITY_WINDOW"]))
+    )
     frac_req = float(G.graph.get("FRACTION_STABLE_REMESH", DEFAULTS["FRACTION_STABLE_REMESH"]))
     req_extra = bool(G.graph.get("REMESH_REQUIRE_STABILITY", DEFAULTS["REMESH_REQUIRE_STABILITY"]))
     min_sync = float(G.graph.get("REMESH_MIN_PHASE_SYNC", DEFAULTS["REMESH_MIN_PHASE_SYNC"]))
@@ -293,4 +310,4 @@ def aplicar_remesh_si_estabilizacion_global(G, pasos_estables_consecutivos: Opti
         return
     # 4) Aplicar y registrar
     aplicar_remesh_red(G)
-    G.graph["_last_remesh_step"] = step_idx
+    G.graph["_last_remesh_step"] = step_idx