Skip to content

Commit c80c99e

Browse files
author
TNFR AI Agent
committed
feat: unify canonical TNFR research and runtime semantics
Centralize nodal contracts, atomic network stages, scalar and phase semantics, and evidence-backed diagnostics across CPU, SDK, GPU, and integration paths. Integrate the research programme with executable certificates, tests, examples, and canonical documentation while removing simulated performance claims and redundant implementations.
1 parent 47cd760 commit c80c99e

426 files changed

Lines changed: 74894 additions & 28001 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/agents/my-agent.md‎

Lines changed: 121 additions & 44 deletions
Large diffs are not rendered by default.

‎AGENTS.md‎

Lines changed: 121 additions & 44 deletions
Large diffs are not rendered by default.

‎CHANGELOG.md‎

Lines changed: 451 additions & 76 deletions
Large diffs are not rendered by default.

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ cd TNFR-Python-Engine
7777
pip install -e .[dev]
7878

7979
# Verify installation
80-
python -c "from tnfr.constants.canonical import PI, U6_STRUCTURAL_POTENTIAL_LIMIT; print(f'π={PI:.6f}, U6 Φ_s bound={U6_STRUCTURAL_POTENTIAL_LIMIT:.6f}')"
80+
python -c "from tnfr.constants.canonical import PI, U6_STRUCTURAL_POTENTIAL_LIMIT; print(f'π={PI:.6f}, selected U6 ΔΦ_s policy={U6_STRUCTURAL_POTENTIAL_LIMIT:.6f}')"
8181
```
8282

8383
### Canonical Constants Framework

‎README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ those primitives. [AGENTS.md](AGENTS.md) is the canonical synthesized reference.
1919
Mathematical scope and counterexamples are stated explicitly in the linked
2020
theory documents.
2121

22+
The graph engine's scalar EPI chart accepts a raw real value or the equivalent
23+
uniform-real `BEPIElement` representation. Its scalar projection retains the
24+
sign; `abs(EPI)` remains the nonnegative Banach-envelope magnitude. Genuinely
25+
nonuniform or complex BEPI payloads keep that magnitude projection for generic
26+
read-outs and are rejected by certificates that require one real EPI coordinate.
27+
2228
```bash
2329
pip install tnfr
2430
```
@@ -71,6 +77,11 @@ The public structural-field tetrad is `(Phi_s, |grad phi|, K_phi, xi_C)`.
7177
| `K_phi` | Local wrapped phase curvature | Exact wrapped magnitude bound `pi`; `0.9*pi` is a warning margin |
7278
| `xi_C` | Non-local correlation range | Spectral estimate scales as `1/sqrt(lambda_2)` under its documented hypotheses |
7379

80+
`Phi_s` uses explicit edge `length` for path geometry when available; otherwise
81+
it retains `weight` as a compatibility fallback. EPI diffusion always reads
82+
`weight` as conductance, so models with distinct geometry and transport should
83+
declare both attributes.
84+
7485
For small phase spread on a consistent branch and matching weight conventions,
7586
`K_phi` agrees with the random-walk Laplacian applied to phase. The EPI channel
7687
of `Delta NFR` is exact graph diffusion. These statements do not make every
@@ -93,6 +104,60 @@ classifications are derived in
93104
[`grammar_canon.py`](src/tnfr/operators/grammar_canon.py), and exposed through
94105
[`grammar.py`](src/tnfr/operators/grammar.py).
95106

107+
The operator registry is the canonical semantic interface for named
108+
transformations. Declared numerical solvers may advance EPI only through the
109+
shared nodal-equation integrator from explicit `nu_f` and `DeltaNFR`, with
110+
provenance or a residual; ad hoc state assignment is outside the engine
111+
contract.
112+
113+
SDK words preserve operator order. Each SDK Reception or Resonance stage
114+
reads one immutable all-target snapshot and commits its validated proposals
115+
atomically; the GPU Resonance strategy reuses that same stage. These positions
116+
have two-phase Jacobi semantics. Other operator stages retain operator-major
117+
Gauss-Seidel semantics, so the guarantee does not make an entire mixed word
118+
simultaneous. No GPU Reception strategy is currently registered.
119+
120+
THOL's `subepi_amplitude_alignment` is a variance-based EPI-amplitude
121+
diagnostic, not canonical `C(t)` and not U5. A concrete U5 target is evaluated
122+
by `assess_u5_parent_child_coherence(..., alpha=...)`; the hierarchy and
123+
nonnegative `alpha` must be supplied explicitly.
124+
125+
### Mutation temporal evidence
126+
127+
Mutation keeps three related quantities separate:
128+
129+
| Read-out | Definition | Scope |
130+
| --- | --- | --- |
131+
| `predicted_depi_dt` | instantaneous `nu_f * DeltaNFR` | Nodal-equation prediction; its crossing is exposed by the legacy SDK alias `near_bifurcation` |
132+
| `observed_depi_dt` | signed two-sample EPI secant | Evidence used by the strict, non-disableable ZHIR threshold gate |
133+
| `d2epi_dt2` | three-sample change between adjacent secant rates | Structural-acceleration diagnostic; timestamped or legacy unit-step, and not the ZHIR gate |
134+
135+
Physical evidence uses timestamped `(time, EPI)` records with finite increasing
136+
time and a fresh final EPI endpoint. If supplied, it is authoritative and does
137+
not fall back when invalid or stale. Legacy `epi_history` and `_epi_history`
138+
instead retain a unit-operator-step interpretation and are explicitly not
139+
resolved in physical time. Direct Mutation requires a valid observed rate
140+
strictly above `ZHIR_THRESHOLD_XI`, together with active capacity and any
141+
configured minimum capacity.
142+
143+
When dynamic selection cannot support a proposed ZHIR from that evidence, it
144+
substitutes Coherence (IL) before ordinary grammar enforcement and records the
145+
requested and applied glyphs with the reason. The SDK whole-word runner
146+
checks all target nodes before executing a word that contains Mutation and
147+
rejects timestamped evidence that an earlier EPI-channel operator in the word
148+
would make stale. `ZHIR_BIFURCATION_VF_THRESHOLD = 0.5` only controls branch
149+
proposal; it is not the Mutation gate. `MutationTriggerCertificate` is an
150+
immutable diagnostic, and `nodal_state()` reads the same evidence without
151+
modifying the graph. Neither evaluates the prior-IL and recent-destabilizer
152+
context required by U4b, and neither certifies execution readiness.
153+
`TNFRNetwork.apply_evidence_gated_mutation()` is the high-level experiment
154+
policy: it runs the requested ZHIR word only after the same preflight;
155+
otherwise it executes a declared Mutation-free exploration word and records
156+
the decision in `NetworkResults.mutation_workflows`. It never synthesizes EPI
157+
history, and malformed evidence remains an error. Direct `apply_sequence()`
158+
calls remain strict. See
159+
[Mutation (ZHIR)](theory/STRUCTURAL_OPERATORS.md#91-mutation-zhir).
160+
96161
## Mathematical scope
97162

98163
TNFR provides executable structural models, diagnostics, and reproducible
@@ -104,6 +169,59 @@ The current scope is centralized in:
104169
- [Diagnostic and Grammar Scope](theory/DIAGNOSTIC_AND_GRAMMAR_SCOPE.md)
105170
- [Minimal Structural Degrees](theory/MINIMAL_STRUCTURAL_DEGREES.md)
106171
- [Structural Conservation Theorem](theory/STRUCTURAL_CONSERVATION_THEOREM.md)
172+
- [Core Dynamics Research Program](theory/CORE_RESEARCH_PROGRAM.md), with its
173+
[diffusion stability theorem](theory/TNFR_DIFFUSION_STABILITY_THEOREM.md) and
174+
[scale, geometry and bridge results](theory/TNFR_SCALE_GEOMETRY_AND_BRIDGE.md)
175+
176+
The restricted S16 executable boundary now covers both frozen endpoints and
177+
sampled pure-EPI trajectories. The path certificate checks every nodal update
178+
on persistent node identifiers, the explicit-Euler modal limit and a common
179+
switching Lyapunov metric. It separates spectral and residual tolerances and
180+
limits cumulative positive energy variation. Its mesh comparison requires an
181+
explicit same-dynamics declaration and keeps numerical agreement separate from
182+
a proof of convergence.
183+
184+
Within that common metric, a declared affine EPI reset has a finite global
185+
disagreement gain exactly when it preserves the consensus subspace. The engine
186+
combines a rational Frobenius upper bound computed exactly on the represented
187+
binary64 coefficients for each passing reset with a rationally certified lower
188+
bound for the represented diffusion decay. The flow proof separately checks
189+
that its materialized generator preserves the consensus subspace and requires
190+
the stronger exact identity `A 1 = 0` so every uniform EPI field is a fixed
191+
point. Preservation of the displayed weighted mean, `h^T A = 0`, is reported
192+
separately. Spectral rates remain estimates. A rational log/exp enclosure
193+
decides and bounds finite and repeated hybrid words without using caller
194+
tolerance as a theorem gate.
195+
196+
For bounded time-varying capacities, the certificate constructs `W`, `D`,
197+
`B=D-W`, its quotient gap and the Lyapunov rate rationally from the effective
198+
binary64 conductances and declared capacity bounds. It reports the conditional
199+
exact-real theorem, availability of a positive operational float rate, ordinary
200+
spectral diagnostics and numerical-integration verification separately; the
201+
last remains open because no future schedule or solver path is observed.
202+
203+
Local Reception (EN) and Resonance (RA) are the first two catalog operators
204+
connected to this framework. They share one centralized unweighted-neighbour
205+
EPI blend even when transport conductance is weighted. The RA audit keeps four
206+
layers separate: the ideal-real convex blend, the represented binary64 affine
207+
map, the actual two-stage binary64 proposal, and the accepted identity-gated
208+
runtime snapshot. Only neighbours that individually pass U3 participate in
209+
RA's EPI mean, phase mean, and frequency trigger; its configured phase limit
210+
may tighten, but cannot exceed, the canonical `pi/2` gate.
211+
212+
RA permits the scalar EPI to move through convex mixing while preserving its
213+
identity: a strict negative/positive crossing is rejected, exact zero is a
214+
neutral boundary, and an established nonempty `epi_kind` cannot change (an
215+
absent kind may be initialized). These sign and kind conditions are independent.
216+
The runtime also requires `0 <= RA_epi_diff <= 1`, nonnegative
217+
`RA_vf_amplification`, and `0 <= RA_phase_coupling <= 1` before mutation. A
218+
local frequency boost generally changes the post-RA diffusion metric
219+
`h_i=d_i/nu_i`; the fixed post-RA flow can still be certified, while a pre/post
220+
switching claim abstains unless the represented metrics are exactly
221+
proportional. Any accepted nontrivial EPI change requires pure-EPI pressure
222+
refresh before diffusion resumes. Separate rounding, clipping, identity gates,
223+
and multichannel effects preclude a global binary64 affinity claim. Canonical
224+
labels do not supply gains for the remaining runtime operators.
107225

108226
The Riemann, Navier-Stokes, Yang-Mills, P-vs-NP, BSD, and Hodge programs remain
109227
open research programs. They do not claim solutions to the corresponding

0 commit comments

Comments
 (0)