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

tnfr/cli/execution.pyi

@@ -6,75 +6,65 @@ from typing import Any, Optional
 
 import networkx as nx
 
+from ..config import apply_config
+from ..config.presets import get_preset
 from ..constants import METRIC_DEFAULTS
 from ..dynamics import (
-    run,
     default_glyph_selector,
     parametric_glyph_selector,
+    run,
     validate_canon,
 )
 from ..execution import CANONICAL_PRESET_NAME, play, seq
 from ..flatten import parse_program_tokens
 from ..glyph_history import ensure_history
-from ..io import read_structured_file, safe_write, StructuredFileError
 from ..metrics import (
-    register_metrics_callbacks,
-    glyph_top,
-    export_metrics,
     build_metrics_summary,
+    export_metrics,
+    glyph_top,
+    register_metrics_callbacks,
 )
 from ..metrics.core import _metrics_step
 from ..ontosim import prepare_network
 from ..sense import register_sigma_callback
 from ..trace import register_trace
 from ..types import Glyph, ProgramTokens
-from ..utils import get_logger, json_dumps
-from ..config import apply_config
-from ..config.presets import get_preset
-
+from ..utils import (
+    StructuredFileError,
+    get_logger,
+    json_dumps,
+    read_structured_file,
+    safe_write,
+)
 from .arguments import _args_to_dict
 
 DEFAULT_SUMMARY_SERIES_LIMIT: int
 logger: Any
 
-
 def _save_json(path: str, data: Any) -> None: ...
-
 def _attach_callbacks(G: nx.Graph) -> None: ...
-
 def _persist_history(G: nx.Graph, args: argparse.Namespace) -> None: ...
-
 def build_basic_graph(args: argparse.Namespace) -> nx.Graph: ...
-
 def apply_cli_config(G: nx.Graph, args: argparse.Namespace) -> None: ...
-
 def register_callbacks_and_observer(G: nx.Graph) -> None: ...
-
 def _build_graph_from_args(args: argparse.Namespace) -> nx.Graph: ...
-
 def _load_sequence(path: Path) -> ProgramTokens: ...
-
 def resolve_program(
     args: argparse.Namespace, default: Optional[ProgramTokens] = ...
 ) -> Optional[ProgramTokens]: ...
-
 def run_program(
     G: Optional[nx.Graph],
     program: Optional[ProgramTokens],
     args: argparse.Namespace,
 ) -> nx.Graph: ...
-
 def _run_cli_program(
     args: argparse.Namespace,
     *,
     default_program: Optional[ProgramTokens] = ...,
     graph: Optional[nx.Graph] = ...,
 ) -> tuple[int, Optional[nx.Graph]]: ...
-
 def _log_run_summaries(G: nx.Graph, args: argparse.Namespace) -> None: ...
-
 def cmd_run(args: argparse.Namespace) -> int: ...
-
 def cmd_sequence(args: argparse.Namespace) -> int: ...
-
 def cmd_metrics(args: argparse.Namespace) -> int: ...
+def cmd_profile_si(args: argparse.Namespace) -> int: ...

tnfr/cli/utils.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from typing import Any
 
+from ..utils import normalize_optional_int
+
 
 def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
     """Create an argument specification pair.
@@ -27,8 +30,22 @@ def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
     """
 
     kwargs = dict(kwargs)
-    kwargs.setdefault(
-        "dest", opt.lstrip("-").replace("-", "_").replace(".", "_")
-    )
+    kwargs.setdefault("dest", opt.lstrip("-").replace("-", "_").replace(".", "_"))
     kwargs.setdefault("default", None)
     return opt, kwargs
+
+
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]:
+    """Return a stable list of integer/``None`` variants for the CLI options."""
+
+    if values is None:
+        return [None]
+    parsed: list[int | None] = []
+    seen: set[int | None] = set()
+    for raw in values:
+        coerced = normalize_optional_int(raw, strict=True)
+        if coerced in seen:
+            continue
+        seen.add(coerced)
+        parsed.append(coerced)
+    return parsed or [None]

tnfr/cli/utils.pyi

@@ -1,8 +1,8 @@
-from typing import Any
+from __future__ import annotations
 
-__all__: Any
+from collections.abc import Iterable
+from typing import Any
 
-def __getattr__(name: str) -> Any: ...
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]: ...
 
-annotations: Any
-spec: Any
+def _parse_cli_variants(values: Iterable[Any] | None) -> list[int | None]: ...

tnfr/config/__init__.py

@@ -7,6 +7,7 @@ previous module level functions so downstream importers remain stable.
 
 from __future__ import annotations
 
+from .feature_flags import context_flags, get_flags
 from .init import apply_config, load_config
 
-__all__ = ("load_config", "apply_config")
+__all__ = ("load_config", "apply_config", "get_flags", "context_flags")

tnfr/config/__init__.pyi

@@ -6,3 +6,5 @@ def __getattr__(name: str) -> Any: ...
 
 apply_config: Any
 load_config: Any
+get_flags: Any
+context_flags: Any

tnfr/config/feature_flags.py

@@ -0,0 +1,83 @@
+"""Math feature flag configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Iterator
+
+__all__ = ("MathFeatureFlags", "get_flags", "context_flags")
+
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    """Toggle optional mathematical behaviours in the engine."""
+
+    enable_math_validation: bool = False
+    enable_math_dynamics: bool = False
+    log_performance: bool = False
+    math_backend: str = "numpy"
+
+
+_TRUE_VALUES = {"1", "true", "on", "yes", "y", "t"}
+_FALSE_VALUES = {"0", "false", "off", "no", "n", "f"}
+
+_BASE_FLAGS: MathFeatureFlags | None = None
+_FLAGS_STACK: list[MathFeatureFlags] = []
+
+
+def _parse_env_flag(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    lowered = value.strip().lower()
+    if lowered in _TRUE_VALUES:
+        return True
+    if lowered in _FALSE_VALUES:
+        return False
+    return default
+
+
+def _load_base_flags() -> MathFeatureFlags:
+    global _BASE_FLAGS
+    if _BASE_FLAGS is None:
+        backend = os.getenv("TNFR_MATH_BACKEND")
+        backend_choice = backend.strip() if backend else "numpy"
+        _BASE_FLAGS = MathFeatureFlags(
+            enable_math_validation=_parse_env_flag(
+                "TNFR_ENABLE_MATH_VALIDATION", False
+            ),
+            enable_math_dynamics=_parse_env_flag(
+                "TNFR_ENABLE_MATH_DYNAMICS", False
+            ),
+            log_performance=_parse_env_flag("TNFR_LOG_PERF", False),
+            math_backend=backend_choice or "numpy",
+        )
+    return _BASE_FLAGS
+
+
+def get_flags() -> MathFeatureFlags:
+    """Return the currently active feature flags."""
+
+    if _FLAGS_STACK:
+        return _FLAGS_STACK[-1]
+    return _load_base_flags()
+
+
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]:
+    """Temporarily override math feature flags."""
+
+    invalid = set(overrides) - set(MathFeatureFlags.__annotations__)
+    if invalid:
+        invalid_names = ", ".join(sorted(invalid))
+        raise TypeError(f"Unknown flag overrides: {invalid_names}")
+
+    previous = get_flags()
+    next_flags = replace(previous, **overrides)
+    _FLAGS_STACK.append(next_flags)
+    try:
+        yield next_flags
+    finally:
+        _FLAGS_STACK.pop()

tnfr/config/init.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from ..constants import inject_defaults
-from ..io import read_structured_file
+from ..utils import read_structured_file
 
 if TYPE_CHECKING:  # pragma: no cover - only for type checkers
     import networkx as nx

tnfr/config/operator_names.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 from typing import Any
 
-
 # Canonical operator identifiers (English tokens)
 EMISSION = "emission"
 RECEPTION = "reception"
@@ -50,13 +49,6 @@ VALID_END_OPERATORS = frozenset({SILENCE, TRANSITION, RECURSIVITY})
 SELF_ORGANIZATION_CLOSURES = frozenset({SILENCE, CONTRACTION})
 
 
-_LEGACY_COLLECTION_ALIASES: dict[str, str] = {
-    "INICIO_VALIDOS": "VALID_START_OPERATORS",
-    "TRAMO_INTERMEDIO": "INTERMEDIATE_OPERATORS",
-    "CIERRE_VALIDO": "VALID_END_OPERATORS",
-    "AUTOORGANIZACION_CIERRES": "SELF_ORGANIZATION_CLOSURES",
-}
-
 def canonical_operator_name(name: str) -> str:
     """Return the canonical operator token for ``name``."""
 
@@ -96,11 +88,6 @@ __all__ = [
 
 
 def __getattr__(name: str) -> Any:
-    """Provide guidance for legacy operator collection aliases."""
+    """Provide a consistent ``AttributeError`` when names are missing."""
 
-    canonical = _LEGACY_COLLECTION_ALIASES.get(name)
-    if canonical is not None:
-        raise AttributeError(
-            f"module '{__name__}' has no attribute '{name}'; use '{canonical}' instead."
-        )
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

tnfr/config/presets.py

@@ -65,39 +65,19 @@ PREFERRED_PRESET_NAMES: tuple[str, ...] = tuple(_PRIMARY_PRESETS.keys())
 _PRESETS: dict[str, PresetTokens] = {**_PRIMARY_PRESETS}
 
 
-_LEGACY_PRESET_ALIASES: dict[str, str] = {
-    "arranque_resonante": "resonant_bootstrap",
-    "mutacion_contenida": "contained_mutation",
-    "exploracion_acople": "coupling_exploration",
-    "ejemplo_canonico": CANONICAL_PRESET_NAME,
-}
-
-
 def legacy_preset_guidance(name: str) -> str | None:
-    """Return CLI guidance for historical preset aliases.
+    """Return CLI guidance for preset lookups.
 
-    Parameters
-    ----------
-    name:
-        Identifier received from the CLI.
-
-    Returns
-    -------
-    str | None
-        A human readable guidance string when ``name`` matches a removed
-        alias. ``None`` when no dedicated guidance is available.
+    Legacy aliases were removed; the function now always returns ``None``.
+    ``name`` is accepted to preserve the public helper signature.
     """
 
-    canonical = _LEGACY_PRESET_ALIASES.get(name)
-    if canonical is None:
-        return None
-    return (
-        f"Legacy preset identifier '{name}' was removed in TNFR 9.0. "
-        f"Use '{canonical}' instead."
-    )
+    return None
 
 
 def get_preset(name: str) -> PresetTokens:
+    """Return the preset token sequence identified by ``name``."""
+
     try:
         return _PRESETS[name]
     except KeyError:

tnfr/constants/__init__.py

@@ -7,30 +7,28 @@ from collections.abc import Mapping
 from types import MappingProxyType
 from typing import Callable, TypeVar, cast
 
+from ..immutable import _is_immutable
+from ..types import GraphLike, TNFRConfigValue
 from .core import CORE_DEFAULTS, REMESH_DEFAULTS
 from .init import INIT_DEFAULTS
 from .metric import (
+    COHERENCE,
+    DIAGNOSIS,
+    GRAMMAR_CANON,
     METRIC_DEFAULTS,
+    METRICS,
     SIGMA,
     TRACE,
-    METRICS,
-    GRAMMAR_CANON,
-    COHERENCE,
-    DIAGNOSIS,
 )
 
-from ..immutable import _is_immutable
-from ..types import GraphLike, TNFRConfigValue
-
 T = TypeVar("T")
 
 STATE_STABLE = "stable"
 STATE_TRANSITION = "transition"
 STATE_DISSONANT = "dissonant"
 
-CANONICAL_STATE_TOKENS = frozenset(
-    {STATE_STABLE, STATE_TRANSITION, STATE_DISSONANT}
-)
+CANONICAL_STATE_TOKENS = frozenset({STATE_STABLE, STATE_TRANSITION, STATE_DISSONANT})
+
 
 def normalise_state_token(token: str) -> str:
     """Return the canonical English token for ``token``.
@@ -56,6 +54,7 @@ def normalise_state_token(token: str) -> str:
         "state token must be one of 'stable', 'transition', or 'dissonant'"
     )
 
+
 try:  # pragma: no cover - optional dependency
     from ..utils import ensure_node_offset_map as _ensure_node_offset_map
 except ImportError:  # noqa: BLE001 - allow any import error
@@ -103,9 +102,7 @@ def inject_defaults(
     for k, v in defaults.items():
         if override or k not in G.graph:
             G.graph[k] = (
-                v
-                if _is_immutable(v)
-                else cast(TNFRConfigValue, copy.deepcopy(v))
+                v if _is_immutable(v) else cast(TNFRConfigValue, copy.deepcopy(v))
             )
     G.graph["_tnfr_defaults_attached"] = True
     if ensure_node_offset_map is not None:

tnfr/constants/__init__.pyi

@@ -3,18 +3,17 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Callable, TypeVar
 
-from .core import CORE_DEFAULTS as CORE_DEFAULTS, REMESH_DEFAULTS as REMESH_DEFAULTS
-from .init import INIT_DEFAULTS as INIT_DEFAULTS
-from .metric import (
-    COHERENCE as COHERENCE,
-    DIAGNOSIS as DIAGNOSIS,
-    GRAMMAR_CANON as GRAMMAR_CANON,
-    METRICS as METRICS,
-    METRIC_DEFAULTS as METRIC_DEFAULTS,
-    SIGMA as SIGMA,
-    TRACE as TRACE,
-)
 from ..types import GraphLike, TNFRConfigValue
+from .core import CORE_DEFAULTS as CORE_DEFAULTS
+from .core import REMESH_DEFAULTS as REMESH_DEFAULTS
+from .init import INIT_DEFAULTS as INIT_DEFAULTS
+from .metric import COHERENCE as COHERENCE
+from .metric import DIAGNOSIS as DIAGNOSIS
+from .metric import GRAMMAR_CANON as GRAMMAR_CANON
+from .metric import METRIC_DEFAULTS as METRIC_DEFAULTS
+from .metric import METRICS as METRICS
+from .metric import SIGMA as SIGMA
+from .metric import TRACE as TRACE
 
 T = TypeVar("T")
 
@@ -79,26 +78,15 @@ STATE_TRANSITION: str
 STATE_DISSONANT: str
 CANONICAL_STATE_TOKENS: frozenset[str]
 
-
 def inject_defaults(
     G: GraphLike,
     defaults: Mapping[str, TNFRConfigValue] = ...,
     override: bool = ...,
 ) -> None: ...
-
-
 def merge_overrides(G: GraphLike, **overrides: TNFRConfigValue) -> None: ...
-
-
 def get_param(G: GraphLike, key: str) -> TNFRConfigValue: ...
-
-
 def get_graph_param(
     G: GraphLike, key: str, cast: Callable[[object], T] = ...
 ) -> T | None: ...
-
-
 def get_aliases(key: str) -> tuple[str, ...]: ...
-
-
 def normalise_state_token(token: str) -> str: ...

tnfr/constants/aliases.py

@@ -0,0 +1,31 @@
+"""Shared alias constants for TNFR attributes."""
+
+from __future__ import annotations
+
+from . import get_aliases
+
+ALIAS_VF = get_aliases("VF")
+ALIAS_THETA = get_aliases("THETA")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_EPI_KIND = get_aliases("EPI_KIND")
+ALIAS_SI = get_aliases("SI")
+ALIAS_DEPI = get_aliases("DEPI")
+ALIAS_D2EPI = get_aliases("D2EPI")
+ALIAS_DVF = get_aliases("DVF")
+ALIAS_D2VF = get_aliases("D2VF")
+ALIAS_DSI = get_aliases("DSI")
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+]

tnfr/constants/core.py

@@ -2,10 +2,9 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any, Mapping
+from dataclasses import asdict, dataclass, field
 from types import MappingProxyType
-
+from typing import Any, Mapping
 
 SELECTOR_THRESHOLD_DEFAULTS: Mapping[str, float] = MappingProxyType(
     {
@@ -72,6 +71,7 @@ class CoreDefaults:
     GLYPH_SELECTOR_MARGIN: float = 0.05
     VF_ADAPT_TAU: int = 5
     VF_ADAPT_MU: float = 0.1
+    HZ_STR_BRIDGE: float = 1.0
     GLYPH_FACTORS: dict[str, float] = field(
         default_factory=lambda: {
             "AL_boost": 0.05,
@@ -151,6 +151,7 @@ class RemeshDefaults:
     REMESH_ALPHA: float = 0.5
     REMESH_ALPHA_HARD: bool = False
 
+
 _core_defaults = asdict(CoreDefaults())
 _remesh_defaults = asdict(RemeshDefaults())
 

tnfr/constants/init.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict
 import math
+from dataclasses import asdict, dataclass
 
 
 @dataclass(frozen=True, slots=True)

tnfr/constants/metric.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict, field
-from typing import Any
+from dataclasses import asdict, dataclass, field
 from types import MappingProxyType
+from typing import Any
 
 
 @dataclass(frozen=True, slots=True)
@@ -27,7 +27,7 @@ class MetricDefaults:
         default_factory=lambda: {
             "enabled": True,
             "weight": "Si",  # "Si" | "EPI" | "1"
-            "smooth": 0.0,  # EMA sobre el vector global (0=off)
+            "smooth": 0.0,  # EMA over the global vector (0=off)
             "history_key": "sigma_global",
             "per_node": False,
         }

tnfr/dynamics/__init__.py

@@ -1,9 +1,71 @@
-"""Facade for TNFR dynamics submodules."""
+"""Facade that keeps ΔNFR, νf and phase orchestration coherent across TNFR dynamics.
+
+Attributes
+----------
+run : callable
+    Callable that fully manages the evolution loop, integrating the nodal
+    equation while enforcing ΔNFR hooks, νf adaptation and phase coordination
+    on every step.
+step : callable
+    Callable entry point for a single iteration that reuses the
+    ΔNFR/νf/phase pipeline while letting callers interleave bespoke telemetry
+    or operator injections.
+set_delta_nfr_hook : callable
+    Callable used to install custom ΔNFR supervision under
+    ``G.graph['compute_delta_nfr']`` so each operator reorganization stays
+    coupled to νf drift and phase targets.
+default_glyph_selector, parametric_glyph_selector : AbstractSelector
+    Selector implementations that choose glyphs according to ΔNFR trends,
+    νf ranges and phase synchrony, ensuring operator firing reinforces
+    coherence.
+coordination, dnfr, integrators : module
+    Re-exported modules providing explicit control over phase alignment,
+    ΔNFR caches and integrator lifecycles to centralize orchestration.
+ProcessPoolExecutor, apply_glyph, compute_Si : callable
+    Re-exported utilities for parallel selector evaluation, explicit glyph
+    execution and Si telemetry so ΔNFR, νf and phase traces remain observable.
+
+Notes
+-----
+The facade aggregates runtime helpers that preserve canonical TNFR dynamics:
+``dnfr`` manages ΔNFR preparation and caching, ``integrators`` drives the
+numerical updates of νf and EPI, and ``coordination`` synchronizes global and
+local phase. Complementary exports such as
+:func:`~tnfr.dynamics.adaptation.adapt_vf_by_coherence` and
+:func:`~tnfr.dynamics.coordination.coordinate_global_local_phase` allow custom
+feedback loops without breaking operator closure.
+
+Examples
+--------
+>>> from tnfr.constants import DNFR_PRIMARY, EPI_PRIMARY, VF_PRIMARY
+>>> from tnfr.structural import Coherence, Emission, Resonance, create_nfr, run_sequence
+>>> from tnfr.dynamics import parametric_glyph_selector, run, set_delta_nfr_hook, step
+>>> G, node = create_nfr("seed", epi=0.22, vf=1.0)
+>>> def regulate_delta(graph, *, n_jobs=None):
+...     for _, nd in graph.nodes(data=True):
+...         delta = nd[VF_PRIMARY] * 0.08
+...         nd[DNFR_PRIMARY] = delta
+...         nd[EPI_PRIMARY] += delta
+...         nd[VF_PRIMARY] += delta * 0.05
+...     return None
+>>> set_delta_nfr_hook(G, regulate_delta, note="ΔNFR guided by νf")
+>>> G.graph["glyph_selector"] = parametric_glyph_selector
+>>> run_sequence(G, node, [Emission(), Resonance(), Coherence()])
+>>> run(G, steps=2, dt=0.05)
+>>> # Automatic integration keeps ΔNFR, νf and phase co-modulated.
+>>> step(G, dt=0.05)
+>>> # Manual control reuses the selector state to consolidate coherence traces.
+"""
 
 from __future__ import annotations
 
 from concurrent.futures import ProcessPoolExecutor
 
+from ..metrics.sense_index import compute_Si
+from ..operators import apply_glyph, enforce_canonical_grammar, on_applied_glyph
+from ..types import GlyphCode
+from ..utils import get_numpy
+from ..validation import apply_canonical_clamps, validate_canon
 from . import coordination, dnfr, integrators
 from .adaptation import adapt_vf_by_coherence
 from .aliases import (
@@ -43,18 +105,14 @@ from .runtime import (
     _run_validators,
     _update_epi_hist,
     _update_nodes,
-    apply_canonical_clamps,
     run,
     step,
-    validate_canon,
 )
 from .sampling import update_node_sample as _update_node_sample
 from .selectors import (
     AbstractSelector,
     DefaultGlyphSelector,
-    GlyphCode,
     ParametricGlyphSelector,
-    _SelectorPreselection,
     _apply_glyphs,
     _apply_selector,
     _choose_glyph,
@@ -63,13 +121,10 @@ from .selectors import (
     _prepare_selector_preselection,
     _resolve_preselected_glyph,
     _selector_parallel_jobs,
+    _SelectorPreselection,
     default_glyph_selector,
     parametric_glyph_selector,
 )
-from ..operators import apply_glyph
-from ..metrics.sense_index import compute_Si
-from ..utils import get_numpy
-from ..validation.grammar import enforce_canonical_grammar, on_applied_glyph
 
 __all__ = (
     "coordination",
@@ -133,4 +188,3 @@ __all__ = (
     "update_epi_via_nodal_equation",
     "validate_canon",
 )
-

tnfr/dynamics/__init__.pyi

@@ -1,6 +1,7 @@
 from typing import Any, Literal, Sequence
 
-from tnfr.types import TNFRGraph
+from tnfr.types import GlyphCode, TNFRGraph
+from tnfr.validation import ValidationOutcome
 
 __all__: tuple[str, ...]
 
@@ -16,7 +17,6 @@ ALIAS_VF: Sequence[str]
 
 AbstractSelector: Any
 DefaultGlyphSelector: Any
-GlyphCode: Any
 ParametricGlyphSelector: Any
 _SelectorPreselection: Any
 _apply_glyphs: Any
@@ -79,5 +79,4 @@ def update_epi_via_nodal_equation(
     n_jobs: int | None = ...,
 ) -> None: ...
 
-validate_canon: Any
-
+def validate_canon(G: TNFRGraph) -> ValidationOutcome[TNFRGraph]: ...