Skip to content

Commit a6217ab

Browse files
author
TNFR AI Agent
committed
Merge audited numerical foundations and conditional formation research
2 parents 5967dc3 + 51d5741 commit a6217ab

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)