Skip to content

Commit 016bf9f

Browse files
author
fer
committed
feat(introspection): Add operator metadata registry (Phase 3)
Introduces introspection.py providing OperatorMeta dataclass and OPERATOR_METADATA registry. Exports via definitions facade for backward compatibility. Metadata covers categories, grammar roles (U1-U4) and contracts. Read-only, preserves all invariants. To be used by telemetry enrichment and upcoming grammar-aware errors.
1 parent 9948bd0 commit 016bf9f

File tree

2 files changed

+220
-0
lines changed

2 files changed

+220
-0
lines changed

‎src/tnfr/operators/definitions.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@
3838
from .mutation import Mutation
3939
from .transition import Transition
4040
from .recursivity import Recursivity
41+
from .introspection import (
42+
OperatorMeta,
43+
OPERATOR_METADATA,
44+
get_operator_meta,
45+
iter_operator_meta,
46+
)
4147

4248
__all__ = [
4349
"Operator",
@@ -54,4 +60,9 @@
5460
"Mutation",
5561
"Transition",
5662
"Recursivity",
63+
# Introspection exports
64+
"OperatorMeta",
65+
"OPERATOR_METADATA",
66+
"get_operator_meta",
67+
"iter_operator_meta",
5768
]

‎src/tnfr/operators/introspection.py‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
"""Operator introspection metadata (Phase 3).
2+
3+
Provides a lightweight, immutable metadata registry describing each
4+
canonical structural operator's physics category, grammar roles, and
5+
contracts for tooling (telemetry enrichment, validation messaging,
6+
documentation generation).
7+
8+
Design Constraints
9+
------------------
10+
1. Read-only: No mutation of operator classes or graph state.
11+
2. Traceability: Grammar roles reference U1-U4 identifiers verbatim.
12+
3. Fidelity: Contracts reflect AGENTS.md canonical operator summaries.
13+
4. Backward compatibility: Optional; absence of this module should not
14+
break existing imports.
15+
16+
Public API
17+
----------
18+
get_operator_meta(name_or_glyph) -> OperatorMeta
19+
iter_operator_meta() -> iterator[OperatorMeta]
20+
OPERATOR_METADATA: dict[str, OperatorMeta]
21+
22+
Fields
23+
------
24+
OperatorMeta.name English class name (e.g. Emission)
25+
OperatorMeta.mnemonic Glyph code (AL, EN, ...)
26+
OperatorMeta.category High-level functional category
27+
OperatorMeta.grammar_roles List of grammar rule roles (U1a, U1b, U2, ...)
28+
OperatorMeta.contracts Short, stable contract statements
29+
OperatorMeta.doc Concise physics rationale (1-2 sentences)
30+
31+
Note: Grammar rule U6 (confinement) is telemetry-only and not included
32+
as an active role.
33+
"""
34+
35+
from __future__ import annotations
36+
37+
from dataclasses import dataclass
38+
from typing import Iterator, Mapping
39+
40+
__all__ = [
41+
"OperatorMeta",
42+
"OPERATOR_METADATA",
43+
"get_operator_meta",
44+
"iter_operator_meta",
45+
]
46+
47+
48+
@dataclass(frozen=True, slots=True)
49+
class OperatorMeta:
50+
name: str
51+
mnemonic: str
52+
category: str
53+
grammar_roles: tuple[str, ...]
54+
contracts: tuple[str, ...]
55+
doc: str
56+
57+
58+
OPERATOR_METADATA: Mapping[str, OperatorMeta] = {
59+
# Generators ---------------------------------------------------------
60+
"AL": OperatorMeta(
61+
name="Emission",
62+
mnemonic="AL",
63+
category="generator",
64+
grammar_roles=("U1a",),
65+
contracts=(
66+
"Initialises νf",
67+
"Positive ΔNFR",
68+
"Irreversible activation",
69+
),
70+
doc="Starts coherent emission; begins structural reorganization.",
71+
),
72+
"EN": OperatorMeta(
73+
name="Reception",
74+
mnemonic="EN",
75+
category="integrator",
76+
grammar_roles=(),
77+
contracts=("Integrates incoming resonance", "Does not reduce C(t)"),
78+
doc="Integrates external resonance without coherence loss.",
79+
),
80+
"IL": OperatorMeta(
81+
name="Coherence",
82+
mnemonic="IL",
83+
category="stabilizer",
84+
grammar_roles=("U2", "U4a"),
85+
contracts=(
86+
"Reduces |ΔNFR|",
87+
"Monotonic C(t) unless test",
88+
"Bifurcation handler",
89+
),
90+
doc="Negative feedback preserving bounded evolution and coherence.",
91+
),
92+
"OZ": OperatorMeta(
93+
name="Dissonance",
94+
mnemonic="OZ",
95+
category="destabilizer",
96+
grammar_roles=("U2", "U4a"),
97+
contracts=(
98+
"Increases |ΔNFR|",
99+
"May trigger bifurcation",
100+
"Needs IL/THOL handler",
101+
),
102+
doc="Controlled instability elevating structural pressure.",
103+
),
104+
"UM": OperatorMeta(
105+
name="Coupling",
106+
mnemonic="UM",
107+
category="coupling",
108+
grammar_roles=("U3",),
109+
contracts=("Phase compatibility", "Establishes link"),
110+
doc="Phase-sync enabling resonance exchange.",
111+
),
112+
"RA": OperatorMeta(
113+
name="Resonance",
114+
mnemonic="RA",
115+
category="propagation",
116+
grammar_roles=("U3",),
117+
contracts=("Amplifies identity", "Phase compatibility"),
118+
doc="Propagates coherent pattern maintaining identity.",
119+
),
120+
"SHA": OperatorMeta(
121+
name="Silence",
122+
mnemonic="SHA",
123+
category="closure",
124+
grammar_roles=("U1b",),
125+
contracts=("νf→0 temporary", "Preserves EPI"),
126+
doc="Freezes evolution for observation window.",
127+
),
128+
"VAL": OperatorMeta(
129+
name="Expansion",
130+
mnemonic="VAL",
131+
category="destabilizer",
132+
grammar_roles=("U2",),
133+
contracts=("Raises dimensionality", "Needs stabilizer"),
134+
doc="Adds degrees of freedom increasing complexity.",
135+
),
136+
"NUL": OperatorMeta(
137+
name="Contraction",
138+
mnemonic="NUL",
139+
category="simplifier",
140+
grammar_roles=(),
141+
contracts=("Reduces dimensionality", "Aids stabilization"),
142+
doc="Simplifies complexity by removing degrees of freedom.",
143+
),
144+
"THOL": OperatorMeta(
145+
name="SelfOrganization",
146+
mnemonic="THOL",
147+
category="stabilizer",
148+
grammar_roles=("U2", "U4a", "U4b"),
149+
contracts=(
150+
"Creates sub-EPIs",
151+
"Preserves form",
152+
"Bifurcation handler",
153+
),
154+
doc="Autopoietic structuring creating fractal sub-forms.",
155+
),
156+
"ZHIR": OperatorMeta(
157+
name="Mutation",
158+
mnemonic="ZHIR",
159+
category="transformer",
160+
grammar_roles=("U4a", "U4b"),
161+
contracts=(
162+
"Phase transform threshold",
163+
"Requires prior IL",
164+
"Recent destabilizer",
165+
),
166+
doc="Threshold-driven phase change altering regime.",
167+
),
168+
"NAV": OperatorMeta(
169+
name="Transition",
170+
mnemonic="NAV",
171+
category="generator",
172+
grammar_roles=("U1a", "U1b"),
173+
contracts=("Activates latent EPI", "Closes sequences"),
174+
doc="Regime shift navigating attractors.",
175+
),
176+
"REMESH": OperatorMeta(
177+
name="Recursivity",
178+
mnemonic="REMESH",
179+
category="generator",
180+
grammar_roles=("U1a", "U1b"),
181+
contracts=("Cross-scale echoing", "Supports fractality"),
182+
doc="Echoes patterns across scales for memory/nesting.",
183+
),
184+
}
185+
186+
187+
def get_operator_meta(identifier: str) -> OperatorMeta:
188+
"""Return metadata for glyph mnemonic or class name.
189+
190+
Resolution order:
191+
1. Exact mnemonic key (AL, EN, ...)
192+
2. Search by English name (Emission, Coherence, ...)
193+
Raises KeyError if not found.
194+
"""
195+
196+
# Direct mnemonic
197+
meta = OPERATOR_METADATA.get(identifier)
198+
if meta is not None:
199+
return meta
200+
# English name lookup
201+
for m in OPERATOR_METADATA.values():
202+
if m.name == identifier:
203+
return m
204+
raise KeyError(identifier)
205+
206+
207+
def iter_operator_meta() -> Iterator[OperatorMeta]:
208+
"""Iterate all operator metadata objects."""
209+
return iter(OPERATOR_METADATA.values())

0 commit comments

Comments
 (0)