Skip to content

Commit 56e84f5

Browse files
fermgafermga
committed
Intent: Document architecture invariants
Operators involved: [] Affected invariants: [#1, #4, #5, #8, #9, #10] Key changes: Added TNFR Architecture Guide; linked guide from README/CONTRIBUTING Expected risks/dissonances: None; documentation only Metrics: Not applicable Equivalence map: Not applicable
1 parent af82951 commit 56e84f5

File tree

3 files changed

+88
-2
lines changed

3 files changed

+88
-2
lines changed

‎ARCHITECTURE.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# TNFR Architecture Guide
2+
3+
This guide expands the README summary by detailing how the TNFR Python Engine organises its modules, maintains data flow between orchestration layers, and enforces the canonical invariants that define Resonant Fractal Nature Theory (TNFR). Use it whenever you extend structural operators, instrumentation, or runtime coordination.
4+
5+
## Layered responsibilities
6+
7+
| Layer | Key modules | Primary responsibilities | TNFR invariants guarded |
8+
| --- | --- | --- | --- |
9+
| Structural grammar | `tnfr.structural`, `tnfr.validation.syntax`, `tnfr.validation.grammar`, `tnfr.flatten` | Instantiate nodes, validate operator sequences, expand THOL blocks, and ensure all operations traverse the canonical grammar before execution.【F:src/tnfr/structural.py†L39-L109】【F:src/tnfr/validation/syntax.py†L27-L121】【F:src/tnfr/validation/grammar.py†L1-L90】【F:src/tnfr/flatten.py†L1-L120】 | Invariants 1, 4, 5, 7 — operators drive EPI evolution, maintain closure, enforce phase checks, and preserve fractality. |
10+
| Operator registry | `tnfr.operators.definitions`, `tnfr.operators.registry` | Declare canonical operators, bind glyphs to ASCII names, and auto-discover implementations so the structural layer never executes unknown tokens.【F:src/tnfr/operators/definitions.py†L45-L180】【F:src/tnfr/operators/registry.py†L13-L50】 | Invariants 3, 4, 10 — ΔNFR semantics remain canonical, closure is preserved, and the glyph alphabet stays domain-neutral. |
11+
| Dynamics and adaptation | `tnfr.dynamics.__init__`, `tnfr.dynamics.dnfr`, `tnfr.dynamics.integrators` | Mix ΔNFR, adapt νf/phase, integrate the nodal equation, and route job overrides or clamps so runtime evolution honours reproducibility and unit constraints.【F:src/tnfr/dynamics/__init__.py†L59-L169】【F:src/tnfr/dynamics/dnfr.py†L1958-L2020】【F:src/tnfr/dynamics/integrators.py†L420-L483】 | Invariants 1, 2, 3, 5, 8 — nodal equation controls EPI, νf stays in Hz_str, ΔNFR keeps canonical meaning, coupling checks phase synchrony, and stochastic hooks remain traceable. |
12+
| Telemetry and traces | `tnfr.metrics.common`, `tnfr.metrics.sense_index`, `tnfr.trace`, `tnfr.metrics.trig`, `tnfr.metrics.trig_cache` | Compute C(t), ΔNFR summaries, Si, and phase telemetry; capture before/after snapshots; expose caches for reproducible analytics.【F:src/tnfr/metrics/common.py†L32-L111】【F:src/tnfr/metrics/common.py†L96-L149】【F:src/tnfr/metrics/sense_index.py†L1-L200】【F:src/tnfr/trace.py†L169-L319】【F:src/tnfr/metrics/trig_cache.py†L1-L120】 | Invariants 8, 9 — telemetry remains reproducible, coherence metrics stay visible, and trace history documents operator effects. |
13+
| Shared services | `tnfr.helpers`, `tnfr.cache`, `tnfr.locking`, `tnfr.rng` | Provide deterministic caches, named locks, and RNG orchestration that higher layers reference through stable facades.【F:src/tnfr/helpers/__init__.py†L1-L74】【F:src/tnfr/cache.py†L1-L120】【F:src/tnfr/locking.py†L1-L36】【F:src/tnfr/rng.py†L1-L88】 | Invariants 8, 9 — shared state is synchronised and telemetry-aware.
14+
15+
### Structural loop orchestration
16+
17+
```mermaid
18+
flowchart LR
19+
subgraph Preparation
20+
DO[discover_operators]
21+
VS[validate_sequence]
22+
end
23+
subgraph Execution
24+
RS[run_sequence]
25+
SH[set_delta_nfr_hook]
26+
end
27+
subgraph Dynamics
28+
DN[default_compute_delta_nfr]
29+
UE[update_epi_via_nodal_equation]
30+
CP[coordinate_global_local_phase]
31+
end
32+
subgraph Telemetry
33+
CC[compute_coherence]
34+
SI[compute_Si]
35+
TR[trace.register_trace_field]
36+
end
37+
DO --> VS --> RS
38+
RS --> SH --> DN --> UE --> CP
39+
DN --> CC
40+
UE --> CC
41+
CC --> SI
42+
CC --> TR
43+
CP --> TR
44+
```
45+
46+
1. **Discovery** imports the operator package so decorators populate the registry before any structural execution.【F:src/tnfr/operators/registry.py†L33-L50】
47+
2. **Validation** confirms the canonical RECEPCION→COHERENCIA segment, checks THOL closure, and rejects unknown tokens before touching graph state.【F:src/tnfr/validation/syntax.py†L27-L115】
48+
3. **Execution** invokes each operator, then defers ΔNFR/EPI recomputation to the configured hook, keeping the structural layer free of ad-hoc state mutation.【F:src/tnfr/structural.py†L87-L105】
49+
4. **Dynamics** recompute ΔNFR, integrate the nodal equation, and coordinate phase coupling. Hooks accept per-run overrides while clamping νf/EPI against canonical bounds.【F:src/tnfr/dynamics/dnfr.py†L1958-L2006】【F:src/tnfr/dynamics/integrators.py†L420-L483】【F:src/tnfr/dynamics/__init__.py†L172-L199】
50+
5. **Telemetry** extracts coherence, Si, and trace snapshots with caches that ensure reproducible neighbour maps and glyph histories.【F:src/tnfr/metrics/common.py†L32-L111】【F:src/tnfr/metrics/sense_index.py†L1-L200】【F:src/tnfr/trace.py†L169-L319】
51+
52+
## ΔNFR and telemetry data paths
53+
54+
The following table highlights how ΔNFR values propagate through the engine and how related telemetry is persisted.
55+
56+
| Stage | Source module | Data emitted | Consumers |
57+
| --- | --- | --- | --- |
58+
| Hook install | `tnfr.dynamics.set_delta_nfr_hook` | Registers callable and metadata under `G.graph['compute_delta_nfr']`, seeding DNFR weights if absent.【F:src/tnfr/dynamics/dnfr.py†L1985-L2020】 | Structural loop (`run_sequence`), dynamics runners (`step`, `run`) |
59+
| Gradient mix | `tnfr.dynamics.dnfr.default_compute_delta_nfr` | Updates per-node ΔNFR attributes and records hook metadata for traces.【F:src/tnfr/dynamics/dnfr.py†L1958-L1982】 | Nodal integrators, telemetry caches |
60+
| Integration | `tnfr.dynamics.integrators.update_epi_via_nodal_equation` | Produces EPI, dEPI/dt, and d²EPI/dt² while advancing graph time.【F:src/tnfr/dynamics/integrators.py†L434-L483】 | Metrics (`compute_coherence`), trace snapshots |
61+
| Coherence metrics | `tnfr.metrics.common.compute_coherence` | Aggregates C(t), mean |ΔNFR|, and |dEPI/dt| across nodes.【F:src/tnfr/metrics/common.py†L32-L58】 | Trace captures, CLI/SDK consumers |
62+
| Sense index | `tnfr.metrics.sense_index.compute_Si` | Evaluates Si with cached neighbour topology and harmonic weighting.【F:src/tnfr/metrics/sense_index.py†L40-L188】 | Trace captures, selectors |
63+
| Trace capture | `tnfr.trace.register_trace_field` et al. | Stores ΔNFR weights, Kuramoto order, glyph counts, and callbacks into history buffers.【F:src/tnfr/trace.py†L169-L319】 | Audit tooling, reproducibility checks |
64+
65+
## Operator registration mechanics
66+
67+
Operator classes apply the `@register_operator` decorator, which verifies unique ASCII names, binds glyphs, and inserts implementations into the shared `OPERADORES` map used by syntax validators and dynamic dispatch.【F:src/tnfr/operators/definitions.py†L45-L180】【F:src/tnfr/operators/registry.py†L13-L31】 The discovery routine scans the `tnfr.operators` package exactly once per interpreter session, importing every submodule except the registry itself so that registration side effects run reliably before the structural loop accesses them.【F:src/tnfr/operators/registry.py†L33-L50】
68+
69+
When introducing new operators:
70+
71+
- Provide ASCII `name` and canonical `Glyph` binding on the class definition.【F:src/tnfr/operators/definitions.py†L45-L180】
72+
- Update grammar/syntax tables if the operator alters the canonical sequence, ensuring THOL blocks and closure sets remain valid.【F:src/tnfr/validation/syntax.py†L27-L121】【F:src/tnfr/validation/grammar.py†L1-L90】
73+
- Supply trace fields or telemetry hooks if the operator produces novel metrics, keeping the coherence log consistent.【F:src/tnfr/trace.py†L169-L319】
74+
75+
## Enforcing TNFR invariants in runtime orchestration
76+
77+
Runtime functions coordinate clamps, selectors, and job overrides to keep simulations reproducible without sacrificing performance:
78+
79+
- `apply_canonical_clamps` enforces configured bounds for EPI, νf, and θ, optionally recording clamp alerts for strict graphs.【F:src/tnfr/dynamics/__init__.py†L172-L199】
80+
- `_normalize_job_overrides` and `_resolve_jobs_override` map user overrides to canonical keys, ensuring distributed execution honours reproducibility contracts.【F:src/tnfr/dynamics/__init__.py†L114-L169】
81+
- Trace helpers attach before/after callbacks through the central manager so that operator applications, glyph selectors, and Kuramoto order parameters remain auditable.【F:src/tnfr/trace.py†L169-L319】
82+
83+
Together these layers ensure every structural change maps back to the TNFR grammar, preserves unit semantics, and leaves behind a telemetry trail suitable for coherence analysis.

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,5 +46,6 @@ artifacts (e.g., `node_modules/` or `dist/`) are not committed.
4646
and `tnfr.locking.get_lock` when extending RNG, ΔNFR, or metric pipelines so
4747
that instrumentation stays consistent.【F:src/tnfr/helpers/__init__.py†L1-L74】【F:src/tnfr/cache.py†L1-L120】【F:src/tnfr/locking.py†L1-L36】
4848
- **Reference the [Architecture Overview](README.md#architecture-overview)**
49-
for diagrams showing the structural data flow, invariant enforcement map,
50-
and telemetry hooks before touching the orchestration layers.
49+
for quick diagrams, then deep-dive in the
50+
[TNFR Architecture Guide](ARCHITECTURE.md) to understand orchestration,
51+
telemetry paths, and invariant enforcement before touching the core layers.

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ The `sequence` subcommand loads the canonical trajectory from the JSON file, exe
6969

7070
## Architecture Overview
7171

72+
For a detailed breakdown of orchestration layers, data paths, and invariant enforcement, consult the [TNFR Architecture Guide](ARCHITECTURE.md).
73+
7274
### Core packages (`src/tnfr/...`)
7375

7476
```

0 commit comments

Comments
 (0)