grammar: derive error-factory invariants + operator-metadata roles from canon

Intent: continue centralising the grammar by removing two remaining parallel
tables that could drift from grammar_canon (the single source of truth).

grammar_canon.py — two new derivations:
- related_invariants(rule_id): the rule->canonical-invariant annotation (primary
  physics invariant + Grammar Compliance #4), reconciled to the 6-invariant canon.
- u_rules_for_operator(op) + ROLE_TO_URULE: the per-operator active U1-U5 rule
  ids, derived from the operator's canonical role set (accepts function name or
  glyph mnemonic).

grammar_error_factory.py: _RULE_INVARIANTS is now DERIVED from
grammar_canon.GRAMMAR_RULES via related_invariants (was a hardcoded dict that
referenced invariants 7 and 9 — stale numbering from the pre-optimization
10-invariant model that no longer exists). Behaviour is now canonical: e.g.
U4b -> (4,) not (3,4,7). No test asserted the old values.

introspection.py: OPERATOR_METADATA.grammar_roles fixed to match the canonical
derivation, correcting three stale divergences (same class of bug the prior
audit fixed in the classification sets): OZ gains U1b (it IS a closure ∈
CLOSURES), ZHIR gains U2 (it IS a destabilizer — the recurrent ZHIR-omission
bug), REMESH gains U5 (it IS the recursive generator). Now sourced-by-contract
from grammar_canon.u_rules_for_operator.

Tests: test_grammar_canon.py +8 (TestRelatedInvariants, TestOperatorMetadata
RolesAreCanonical) pinning both derivations against the canon. Full suite
2021 passed, 2 skipped, 0 failed. Operators: none modified. Affected invariants:
#4 Grammar Compliance (annotation accuracy; behaviour preserved).

Author: TNFR AI Agent

src/tnfr/operators/grammar_canon.py

@@ -112,6 +112,10 @@
     "GrammarRule",
     "GRAMMAR_RULES",
     "rule",
+    "GRAMMAR_COMPLIANCE_INVARIANT",
+    "related_invariants",
+    "ROLE_TO_URULE",
+    "u_rules_for_operator",
     "StructuralType",
     "StructuralTypeSpec",
     "STRUCTURAL_TYPOLOGY",
@@ -330,6 +334,63 @@ def rule(rule_id: str) -> GrammarRule:
     raise KeyError(f"Unknown grammar rule id: {rule_id!r}")
 
 
+#: Canonical invariant index for "Grammar Compliance" (AGENTS.md §Canonical
+#: Invariants, the 6-invariant model). Every grammar-rule violation relates to
+#: this invariant by definition, in addition to the rule's primary physics
+#: invariant.
+GRAMMAR_COMPLIANCE_INVARIANT = 4
+
+
+def related_invariants(rule_id: str) -> tuple[int, ...]:
+    """Canonical invariants a violation of ``rule_id`` relates to.
+
+    Returns the rule's primary physics invariant plus Grammar Compliance (#4),
+    sorted and de-duplicated. This is the single source of the rule→invariant
+    annotation, reconciled to the 6-invariant canon (AGENTS.md §Canonical
+    Invariants); it replaces the stale pre-optimization 10-invariant numbering.
+    """
+    try:
+        primary = rule(rule_id).invariant
+    except KeyError:
+        return (GRAMMAR_COMPLIANCE_INVARIANT,)
+    return tuple(sorted({primary, GRAMMAR_COMPLIANCE_INVARIANT}))
+
+
+#: Map each grammatical role to the active U1-U5 rule id it participates in.
+#: (U6 confinement is telemetry-only and is not an active operator role.)
+ROLE_TO_URULE: dict[GrammarRole, str] = {
+    GrammarRole.GENERATOR: "U1a",
+    GrammarRole.CLOSURE: "U1b",
+    GrammarRole.STABILIZER: "U2",
+    GrammarRole.DESTABILIZER: "U2",
+    GrammarRole.COUPLING: "U3",
+    GrammarRole.TRIGGER: "U4a",
+    GrammarRole.HANDLER: "U4a",
+    GrammarRole.TRANSFORMER: "U4b",
+    GrammarRole.RECURSIVE: "U5",
+}
+
+#: Resolve a glyph mnemonic (e.g. "ZHIR") back to its function name.
+_OPERATOR_BY_GLYPH: dict[str, str] = {
+    g.glyph: op for op, g in OPERATOR_ROLES.items()
+}
+
+
+def u_rules_for_operator(op: str) -> tuple[str, ...]:
+    """The active U1-U5 rule ids an operator participates in (sorted, unique).
+
+    Derived from the operator's canonical role set. ``op`` may be a function
+    name (e.g. ``"mutation"``) or a glyph mnemonic (e.g. ``"ZHIR"``). U6
+    (confinement) is telemetry-only and is not an active operator role, so it
+    never appears here. Single source of the per-operator grammar-role table.
+    """
+    name = _OPERATOR_BY_GLYPH.get(op, op)
+    grammar = OPERATOR_ROLES.get(name)
+    if grammar is None:
+        return ()
+    return tuple(sorted({ROLE_TO_URULE[r] for r in grammar.roles}))
+
+
 #: The TNFR.pdf §2.3.3 "Esquema formal de sintaxis" positions (theory anchor).
 #: Quoted Spanish terms are verbatim citations of the source schema headers.
 FORMAL_SYNTAX_SCHEMA: dict[str, tuple[str, ...]] = {

src/tnfr/operators/grammar_error_factory.py

@@ -23,18 +23,22 @@
 make_grammar_error(rule, candidate, message, sequence, index=None)
     -> ExtendedGrammarError
 
-Invariants Mapping (Minimal)
-----------------------------
-U1a -> (1,4)        # EPI initiation & operator closure precondition
-U1b -> (4)          # Closure / bounded sequence end
-U2  -> (3,4)        # ΔNFR semantics & closure (stabilizer presence)
-U3  -> (5)          # Phase verification
-U4a -> (3,4,5)      # Trigger handling (ΔNFR pressure + handlers + phase)
-U4b -> (3,4,7)      # Transformers need stabilised base & fractality preserved
-U6  -> (3,9)        # Potential confinement + metrics integrity
+Invariants Mapping (canonical, derived)
+---------------------------------------
+Each grammar-rule violation relates to its primary physics invariant plus
+Grammar Compliance (#4). The mapping is DERIVED from
+``grammar_canon.GRAMMAR_RULES`` (the single source of truth) via
+``related_invariants``, reconciled to the 6-invariant canon (AGENTS.md
+§Canonical Invariants):
 
-NOTE: Mapping kept intentionally lean; can be extended in future without
-breaking existing consumers.
+U1a/U1b/U2 -> (1, 4)   # Nodal Equation Integrity + Grammar Compliance
+U3         -> (2, 4)   # Phase-Coherent Coupling + Grammar Compliance
+U4a/U4b    -> (4,)     # Grammar Compliance (bifurcation dynamics)
+U5         -> (3, 4)   # Multi-Scale Fractality + Grammar Compliance
+U6         -> (4, 5)   # Grammar Compliance + Structural Metrology
+
+NOTE: Sourced from grammar_canon so the annotation cannot drift from the
+canonical rule registry; a consistency test pins the agreement.
 """
 
 from __future__ import annotations
@@ -43,6 +47,10 @@
 from typing import Any, Sequence
 
 from .definitions import get_operator_meta
+from .grammar_canon import (
+    GRAMMAR_RULES as _GRAMMAR_RULES,
+    related_invariants as _related_invariants,
+)
 from .grammar_core import GrammarValidator
 from .grammar_types import StructuralGrammarError
 
@@ -52,15 +60,16 @@
     "make_grammar_error",
 ]
 
-_RULE_INVARIANTS = {
-    "U1a": (1, 4),
-    "U1b": (4,),
-    "U2": (3, 4),
-    "U3": (5,),
-    "U4a": (3, 4, 5),
-    "U4b": (3, 4, 7),
-    "U6_CONFINEMENT": (3, 9),
+# U-rule violation → canonical invariants it relates to (its primary physics
+# invariant + Grammar Compliance #4). DERIVED from grammar_canon.GRAMMAR_RULES,
+# the single source of truth, reconciled to the 6-invariant canon (AGENTS.md
+# §Canonical Invariants). This replaces the stale pre-optimization 10-invariant
+# numbering (which referenced invariants 7/9 that no longer exist). The
+# "U6_CONFINEMENT" key aliases the canonical "U6" telemetry rule.
+_RULE_INVARIANTS: dict[str, tuple[int, ...]] = {
+    r.rule_id: _related_invariants(r.rule_id) for r in _GRAMMAR_RULES
 }
+_RULE_INVARIANTS["U6_CONFINEMENT"] = _related_invariants("U6")
 
 @dataclass(slots=True)
 class ExtendedGrammarError:

src/tnfr/operators/introspection.py

@@ -29,7 +29,10 @@
 OperatorMeta.doc           Concise physics rationale (1-2 sentences)
 
 Note: Grammar rule U6 (confinement) is telemetry-only and not included
-as an active role.
+as an active role. The ``grammar_roles`` tuples are the canonical per-operator
+U1-U5 roles derived from the operator's role set in
+:mod:`tnfr.operators.grammar_canon` (single source of truth); the agreement is
+pinned by ``test_grammar_canon.py`` (``u_rules_for_operator``).
 """
 
 from __future__ import annotations
@@ -91,7 +94,7 @@ class OperatorMeta:
         name="Dissonance",
         mnemonic="OZ",
         category="destabilizer",
-        grammar_roles=("U2", "U4a"),
+        grammar_roles=("U1b", "U2", "U4a"),
         contracts=(
             "Increases |ΔNFR|",
             "May trigger bifurcation",
@@ -155,7 +158,7 @@ class OperatorMeta:
         name="Mutation",
         mnemonic="ZHIR",
         category="transformer",
-        grammar_roles=("U4a", "U4b"),
+        grammar_roles=("U2", "U4a", "U4b"),
         contracts=(
             "Phase transform threshold",
             "Requires prior IL",
@@ -175,7 +178,7 @@ class OperatorMeta:
         name="Recursivity",
         mnemonic="REMESH",
         category="generator",
-        grammar_roles=("U1a", "U1b"),
+        grammar_roles=("U1a", "U1b", "U5"),
         contracts=("Cross-scale echoing", "Supports fractality"),
         doc="Echoes patterns across scales for memory/nesting.",
     ),

tests/operators/test_grammar_canon.py

@@ -171,3 +171,65 @@ def test_formal_syntax_schema_positions(self) -> None:
         schema = gc.FORMAL_SYNTAX_SCHEMA
         assert "AL" in schema["start"]
         assert "SHA" in schema["closure"]
+
+
+class TestRelatedInvariants:
+    """The rule→invariant annotation is canonical (6-invariant model)."""
+
+    def test_every_rule_relates_to_grammar_compliance(self) -> None:
+        # Grammar Compliance (#4) is in every grammar-rule's related set.
+        for r in gc.GRAMMAR_RULES:
+            assert gc.GRAMMAR_COMPLIANCE_INVARIANT in gc.related_invariants(
+                r.rule_id
+            )
+
+    def test_invariants_are_in_the_six_invariant_canon(self) -> None:
+        # No stale references to the old 10-invariant numbering (7, 9, …).
+        for r in gc.GRAMMAR_RULES:
+            for inv in gc.related_invariants(r.rule_id):
+                assert 1 <= inv <= 6
+
+    def test_primary_invariant_is_included(self) -> None:
+        for r in gc.GRAMMAR_RULES:
+            assert r.invariant in gc.related_invariants(r.rule_id)
+
+    def test_error_factory_mapping_is_derived(self) -> None:
+        # The error factory's _RULE_INVARIANTS must come from grammar_canon.
+        from tnfr.operators import grammar_error_factory as gef
+
+        for r in gc.GRAMMAR_RULES:
+            assert gef._RULE_INVARIANTS[r.rule_id] == gc.related_invariants(
+                r.rule_id
+            )
+        # The U6 confinement alias maps to the canonical U6 rule.
+        assert gef._RULE_INVARIANTS["U6_CONFINEMENT"] == gc.related_invariants(
+            "U6"
+        )
+
+
+class TestOperatorMetadataRolesAreCanonical:
+    """introspection.OPERATOR_METADATA.grammar_roles == the canonical roles."""
+
+    def test_every_operator_metadata_matches_canon(self) -> None:
+        from tnfr.operators.introspection import OPERATOR_METADATA
+
+        for mnemonic, meta in OPERATOR_METADATA.items():
+            expected = gc.u_rules_for_operator(mnemonic)
+            assert tuple(meta.grammar_roles) == expected, (
+                f"{mnemonic}: metadata {meta.grammar_roles} != canon {expected}"
+            )
+
+    def test_u_rules_accepts_function_name_and_glyph(self) -> None:
+        # Same result whether queried by function name or glyph mnemonic.
+        assert gc.u_rules_for_operator("mutation") == gc.u_rules_for_operator(
+            "ZHIR"
+        )
+        assert gc.u_rules_for_operator("ZHIR") == ("U2", "U4a", "U4b")
+
+    def test_remesh_carries_the_recursive_rule(self) -> None:
+        # REMESH is the U5 recursive generator (was historically omitted).
+        assert "U5" in gc.u_rules_for_operator("REMESH")
+
+    def test_dissonance_is_also_a_closure(self) -> None:
+        # OZ is a closure (∈ CLOSURES) → U1b (was historically omitted).
+        assert "U1b" in gc.u_rules_for_operator("OZ")