Skip to content

Commit 51d5741

Browse files
author
TNFR AI Agent
committed
Consolidate numerical foundations and conditional formation research
Unify mathematical admission and reuse scoped algebra across mathematics, physics and SDK consumers. Preserve native backend paths and public adapters, replace eager physics exports with a checked lazy facade, and retire redundant helpers with immutable recovery manifests. Consolidate pair-state response and prepared positive-loss acquisition under their declared complete laws. Share preparation and independent test kernels, retain frozen protocols and counterexamples, and reduce the execution plan to one queue with explicit resumption boundaries. Physical identification, autonomous preparation and unique law selection remain open. Fix overflow-based false verdicts in regularity, contractivity and dissipative diagnostics. Reject unrepresentable arithmetic before comparisons and keep tracker histories unchanged on rejected observations. Correct unsupported universal-scale and threshold claims in the arithmetic documentation. Validation: - Routine engine/API gate: 9761 passed, 13 skipped. - Full mathematics and dissipative consumer: 2005 passed. - Broad physics integration: 1399 passed; final affected rerun: 168 passed. - Final facade and module compatibility: 45 passed. - CI-pinned Black/isort, flake8, physics stub, documentation integrity, 6678 internal references, strict MkDocs, and isolated wheel build passed. - Contributor mirror and frozen pair/formation proof owners preserved. Validation is scoped to the selected contracts and local Python 3.13; not every retained research campaign or CI platform was replayed.
1 parent 5967dc3 commit 51d5741

142 files changed

Lines changed: 23446 additions & 4697 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.

‎ARCHITECTURE.md‎

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ boundary, not a measured speedup. Other state/configuration dependencies remain
1818
part of each consumer's key or explicit invalidation contract. Graph views use
1919
fresh computations; concurrent mutation during a read is unsupported.
2020

21+
The structural random-walk verifier reuses one resistance geometry within a
22+
call for resistance and commute-time projections. The comparison still uses
23+
the separate component-volume multiplication of materialized resistance.
24+
There is no persistent geometry cache; a later call re-admits the graph.
25+
2126
LRU storage and callback handling have one implementation in
2227
[`utils/unified_cache.py`](src/tnfr/utils/unified_cache.py). The compatibility
2328
`InstrumentedLRUCache` and `ManagedLRUCache` names remain aliases in `utils.cache`;
@@ -61,6 +66,23 @@ graph invalidation and persistence retain their separate responsibilities.
6166
These are implementation responsibilities. The [documentation ownership map](docs/README.md)
6267
identifies the single maintained guide for each responsibility.
6368

69+
The `tnfr.physics` public namespace resolves its exports on first access.
70+
One ordered owner map supplies `__all__`, discovery through `dir()` and lazy
71+
dispatch; resolved names are the actual owner objects, not proxies. Importing
72+
one field or observer therefore does not eagerly load unrelated research and
73+
runtime certificates. Direct module imports retain their own dependencies.
74+
The [facade controls](tests/physics/test_physics_facade_imports.py) check cold
75+
imports, public object identity and discovery independently of timing.
76+
The generated [typing facade](src/tnfr/physics/__init__.pyi) re-exports those
77+
same owners for static analyzers. Its
78+
[generator](scripts/generate_physics_stub.py) reads the runtime map without
79+
importing the package; the [testing guide](TESTING.md#code-quality-and-documentation-checks)
80+
owns regeneration and drift checks.
81+
82+
Physics imports NumPy and NetworkX as core dependencies declared in
83+
`pyproject.toml`. Optional SciPy and acceleration paths retain their own
84+
availability checks and fallback behavior.
85+
6486
## Nodal execution flow
6587

6688
The ordinary runtime composes the following configured operations. The diagram
@@ -203,7 +225,8 @@ lost in that conversion.
203225
| [`physics/source_relative_form.py`](src/tnfr/physics/source_relative_form.py) | Composes the form observer with an independently supplied held rate source; `Network.source_relative_form` is the adapter. |
204226
| [`physics/relational_observations.py`](src/tnfr/physics/relational_observations.py) | Native field, region and hypothetical support-change reports; separately, graph-independent coefficient/rate/sample-jet bounds. Sample adapters share stencils and outward error propagation. |
205227
| [`mathematics/linear_observation.py`](src/tnfr/mathematics/linear_observation.py) | Exact row-space realization and visible/hidden memory for a supplied rational generator; scoped lower bounds distinguish conservative observation from a supplied form-loss model. `physics/epi_memory.py` retains its own diffusion admission. |
206-
| [`mathematics/_exact_linear_algebra.py`](src/tnfr/mathematics/_exact_linear_algebra.py) | Shared exact products, inverses and rank algebra; compatibility physics imports delegate here. |
228+
| [`mathematics/_exact_linear_algebra.py`](src/tnfr/mathematics/_exact_linear_algebra.py) | Shared exact products, powers, inverses and semidefinite tests; compatibility physics imports, fixed-map network-stage powers and p-adic tower products delegate here. The tower adapter retains its mutable list rows. Products skip exact zero factors while retaining full rational output shapes and the consumers' product-call accounting. |
229+
| [`mathematics/krylov.py`](src/tnfr/mathematics/krylov.py) | Exact rational rank, Krylov reachability and Hankel moment calculations under their declared input/output premises. |
207230
| [`mathematics/_phase_resultant_chamber.py`](src/tnfr/mathematics/_phase_resultant_chamber.py) | Rational trigonometric/resultant bounds, principal-argument charts and supplied-rate kinematics. Reused geometry does not transfer a law. |
208231
| [`mathematics/_validated_taylor.py`](src/tnfr/mathematics/_validated_taylor.py) | Strict Picard tubes, Taylor remainders and initial-box propagation; the comparison kernel owns the shared 1–24-coordinate work limit. Each flow adapter retains its layout and other admission budgets. |
209232
| [`mathematics/_validated_metric.py`](src/tnfr/mathematics/_validated_metric.py) | Reuses Picard/Taylor machinery while retaining an SPD-metric radius between steps. The caller proves its whole-tube logarithmic bound; local truncation/rounding errors enter the same norm. Coordinate projections do not replace the retained uncertainty. |
@@ -239,11 +262,34 @@ The sine layer shares four boundaries:
239262
work and resultant kinematics. Mobility and regional/mediated readers reuse
240263
these primitives while retaining their own complete-law identifiers.
241264
3. `_sine_preparation.py` supplies weighted preparation and uncertainty bounds.
265+
Its report reader re-admits original source primitives before the shared
266+
row calculation. Fixed-source consumers can use that calculation after
267+
admitting their law, support, capacities and exact rows, without constructing
268+
an observation report whose derived rates they do not consume.
242269
Forecasts share validated Taylor/metric kernels and retain environmental
243270
coordinates, hidden initialization and original error associations.
244271
4. `sdk/relational_reports.py` delegates reports and projects exact JSON values;
245272
it neither installs a solver nor authenticates an evaluated response.
246273

274+
`relational_sine_pair.py` owns exact global pair state, cancellation
275+
observations and finite exchange/receiver certificates. It depends directly on
276+
shared scalar, phasor and rational-interval admission. The larger
277+
`relational_sine_scale.py` retains replica geometry, grouping and emission.
278+
`relational_sine_replica_pulse.py` owns prepared internal pulses, their
279+
variations, splitting and work-response assessments, including the validated
280+
Taylor solver dependency. The scale module re-exports the established pair
281+
and pulse APIs for compatibility. Their defining classes/functions live in
282+
the corresponding owners; old imports resolve to those same objects,
283+
including SDK dispatch and older pickle class lookups. These boundaries
284+
change neither the complete laws nor the report schemas.
285+
286+
`relational_sine_formation_response.py` combines the shared preparation kernel
287+
with exact Poisson and interval bounds for its fixed positive-loss sources.
288+
One fresh domain admission serves both source rows in a call; all public
289+
budgets are admitted anew. It keeps its own complete-law and clock premises,
290+
independent of the conservative pair certificates. No prepared-state or
291+
verdict cache substitutes for source admission.
292+
247293
Downstream calculations re-admit the producer's primitive source and rebuild
248294
consumed gradients, rates, work and bounds. Forecast readers also check the
249295
source association at the actual validated time. The
@@ -321,7 +367,14 @@ or second transport law is introduced.
321367
classifications.
322368
- `tnfr.errors` provides contextual public exceptions.
323369
- `tnfr.mathematics` owns numerical backends and domain-neutral mathematical
324-
structures.
370+
structures. Its private `_complex_arrays` reader shares original-component
371+
admission and range-safe normalization across spectral consumers.
372+
`_integer_admission` owns exact integer/index admission for arithmetic
373+
modules; primality dispatch and optional SymPy selection remain with
374+
`number_theory`.
375+
- `tnfr.math.symbolic` owns supplied-law symbolic calculus when SymPy is
376+
installed. Its public helpers are re-exported by `tnfr.mathematics` and
377+
`tnfr`; those import paths share the same implementations.
325378

326379
### Structural dynamics
327380

‎TESTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -274,6 +274,16 @@ For examples with `run_protocol` and `build_report`, reuse the real report throu
274274
a module fixture for numerical and scope checks. The shared
275275
[example helper](tests/example_protocol_helpers.py) checks `main` separately with
276276
a sentinel protocol and synthetic report, without rerunning a scientific producer.
277+
278+
Reusable independent oracles belong in test support modules rather than in
279+
another collected test suite. The [pair oracle helper](tests/physics/_sine_pair_oracles.py)
280+
shares fine support, exact jets and high-precision reductions without importing
281+
production certificates or pytest fixtures. Each consuming suite retains its
282+
own complete-law assumptions, preparation budgets and module-scoped reports.
283+
When optimizing a shared certificate kernel, compare complete exact projections
284+
on representative available and unavailable cases as well as these independent
285+
controls; timing differences alone cannot establish unchanged evidence.
286+
277287
[Runtime facade tests](tests/physics/test_runtime_facade_imports.py) own the two
278288
cold import orders for the P2/REMESH example families; those checks still use
279289
fresh processes and resolve the actual public APIs.
@@ -354,6 +364,14 @@ Pass affected files for a focused edit where supported. Black and isort use
354364
in [the workflow guide](.github/WORKFLOWS.md). `make format` modifies files;
355365
it is not a read-only validation step.
356366

367+
The lazy `physics` namespace has one maintained export map and a generated
368+
typing facade. After changing that map, run
369+
`python scripts/generate_physics_stub.py --write`; validate it with
370+
`python scripts/generate_physics_stub.py --check`. The generator reads the
371+
source AST without importing TNFR, and the
372+
[facade tests](tests/physics/test_physics_facade_imports.py) check typed exports,
373+
runtime object identity and cold import boundaries.
374+
357375
Optional pre-commit setup requires installing `pre-commit` separately before
358376
`pre-commit install`. [.pre-commit-config.yaml](.pre-commit-config.yaml)
359377
configures Black, isort, pydocstyle and a local Bandit-command guard. That guard

0 commit comments

Comments
 (0)