perf(fields): Add automatic caching to canonical tetrad functions

- Import cache system (cache_tnfr_computation, CacheLevel) with fallback
- Add @cache_tnfr_computation decorator to 4 canonical functions:
  * compute_structural_potential (deps: topology, node_dnfr)
  * compute_phase_gradient (deps: topology, node_phase)
  * compute_phase_curvature (deps: topology, node_phase)
  * estimate_coherence_length (deps: topology, node_dnfr, node_coherence)
- Cache level: DERIVED_METRICS (invalidated on property changes)
- ~75% overhead reduction for repeated calls on unchanged graphs
- Update STRUCTURAL_HEALTH.md with cache usage examples
- All tests passing (tests/test_physics_fields.py: 3/3 ✓)

Uses repository's centralized TNFRHierarchicalCache instead of manual
cached_fields parameter. Automatic dependency tracking and invalidation.

Physics: Read-only telemetry; preserves invariants (§3.8, §3.4)

Author: fer

.gitignore

@@ -46,9 +46,17 @@ outputs/
 benchmarks/results/
 dist-test/
 test-env/
+examples/output/
 
 # Large benchmark result files
 benchmarks/results/*_telemetry.jsonl
 benchmarks/results/phase_gradient_full_study.jsonl
 benchmarks/results/u6_aggressive_results.jsonl
 benchmarks/results/*_5000_*.jsonl
+
+debug_scratch/
+*.tmp
+*.temp
+
+# Type checking cache
+.mypy_cache/

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "git.ignoreLimitWarning": true
+}

.vscode/tasks.json

@@ -1,6 +1,12 @@
 # MIT License
 
-Copyright (c) 2025 TNFR – Resonant Fractal Nature Theory
+## Copyright
+
+Copyright (c) 2025 F. F. Martinez Gamo
+
+ORCID: [0009-0007-6116-0613](https://orcid.org/0009-0007-6116-0613)
+
+---
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +18,80 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.**
+
+---
+
+## Additional Information
+
+### TNFR Python Engine
+
+This software implements **Resonant Fractal Nature Theory (TNFR)**, a computational framework
+for modeling coherent patterns through resonance dynamics.
+
+**Project**: TNFR-Python-Engine  
+**Repository**: <https://github.com/fermga/TNFR-Python-Engine>  
+**PyPI**: <https://pypi.org/project/tnfr/>  
+**DOI**: [10.5281/zenodo.17602861](https://doi.org/10.5281/zenodo.17602861)
+
+### Citation
+
+If you use this software in your research, please cite:
+
+```bibtex
+@software{tnfr_python_engine,
+  author = {Martinez Gamo, F. F.},
+  title = {TNFR-Python-Engine: Resonant Fractal Nature Theory Implementation},
+  year = {2025},
+  version = {9.0.2},
+  doi = {10.5281/zenodo.17602861},
+  url = {https://github.com/fermga/TNFR-Python-Engine}
+}
+```
+
+See [CITATION.cff](CITATION.cff) for machine-readable citation metadata.
+
+### Third-Party Dependencies
+
+This software relies on the following open-source libraries:
+
+- **NetworkX** - BSD-3-Clause License
+- **NumPy** - BSD-3-Clause License
+- **SciPy** - BSD-3-Clause License
+- **Matplotlib** (optional) - PSF License
+- **PyYAML** (optional) - MIT License
+
+See `pyproject.toml` for the complete list of dependencies.
+
+### Contributing
+
+Contributions to TNFR Python Engine are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md)
+for guidelines.
+
+By contributing to this project, you agree that your contributions will be licensed under
+the same MIT License that covers this project.
+
+### Trademark Notice
+
+"TNFR" and "Resonant Fractal Nature Theory" are terms associated with this theoretical
+framework. While the software implementation is provided under the MIT License, the
+theoretical framework itself is a scholarly work subject to academic attribution norms.
+
+### Disclaimer
+
+This software is provided for research and educational purposes. The theoretical framework
+of TNFR represents an alternative modeling paradigm and should be evaluated critically
+within appropriate academic and scientific contexts.
+
+---
+
+**For questions about licensing or usage, please contact the maintainers via**:
+
+- GitHub Issues: <https://github.com/fermga/TNFR-Python-Engine/issues>
+- GitHub Discussions: <https://github.com/fermga/TNFR-Python-Engine/discussions>

LICENSE.md

@@ -1,7 +1,7 @@
 # Molecular Chemistry Documentation - Complete Integration Summary
 
-**Date**: 2025-11-12  
-**Status**: ✅ COMPLETE - Comprehensive centralized documentation implemented  
+**Date**: 2025-11-12
+**Status**: ✅ COMPLETE - Comprehensive centralized documentation implemented
 **Achievement**: Revolutionary chemistry paradigm fully documented and integrated
 
 ---
@@ -17,38 +17,50 @@ Successfully implemented comprehensive, centralized documentation for the **revo
 ## 📚 Documentation Architecture Implemented
 
 ### 🏛️ Central Hub System
+
 **[docs/MOLECULAR_CHEMISTRY_HUB.md](docs/MOLECULAR_CHEMISTRY_HUB.md)**
+
 - **Single navigation point** for entire molecular chemistry breakthrough
 - **Complete learning paths** (Beginner → Intermediate → Advanced)
 - **Theory consolidation** with cross-reference matrix
 - **Research opportunities** and contribution guidelines
 
 ### 📊 Canonical Source Integration
+
 **[CANONICAL_SOURCES.md](CANONICAL_SOURCES.md)** - Updated Tier 2b
+
 - Added molecular chemistry module to canonical hierarchy
 - Established authoritative source chain: Hub → Theory → Implementation
 - Clear reference requirements and cross-linking rules
 
-### 🗂️ Navigation Integration  
+### 🗂️ Navigation Integration
+
 **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)**
+
 - New molecular chemistry section with hub prominence
 - Learning Path 5: "Molecular Chemistry Revolution" (90 minutes)
 - Updated "I want to..." section for chemistry discovery
 
 ### 📖 Terminology Integration
+
 **[GLOSSARY.md](GLOSSARY.md)**
+
 - Complete "Molecular Chemistry from TNFR" section
 - TNFR redefinitions: bonds → phase sync, reactions → operator sequences
 - Cross-references to theory and implementation
 
 ### 🔗 Traceability Integration
+
 **[docs/CROSS_REFERENCE_MATRIX.md](docs/CROSS_REFERENCE_MATRIX.md)**
-- Added "Molecular Chemistry Chain" (§5) 
+
+- Added "Molecular Chemistry Chain" (§5)
 - Complete physics → theory → implementation → validation traceability
 - Updated concept coverage matrix (14/14 concepts ✅)
 
 ### 🚀 Public Discovery Integration
+
 **[README.md](README.md)**
+
 - Prominent breakthrough section with key discoveries
 - Clear pathway: hub → implementation → validation
 - Emphasizes revolutionary nature without overpromising
@@ -58,6 +70,7 @@ Successfully implemented comprehensive, centralized documentation for the **revo
 ## 🧪 Technical Implementation Status
 
 ### ✅ Complete Integration
+
 | Component | Status | Tests | Cross-References |
 |-----------|--------|--------|------------------|
 | **Element Signatures** | ✅ Functional | 9/9 ✅ | Hub → Physics README |
@@ -66,8 +79,9 @@ Successfully implemented comprehensive, centralized documentation for the **revo
 | **Pattern Builders** | ✅ Centralized | Integrated | Hub → Physics Module |
 
 ### 📊 Validation Metrics
+
 - **Total Tests**: 19/19 passing ✅
-- **Documentation Coverage**: 14/14 key concepts ✅  
+- **Documentation Coverage**: 14/14 key concepts ✅
 - **Cross-References**: Complete bidirectional linking ✅
 - **Single Source of Truth**: Established and maintained ✅
 
@@ -76,11 +90,12 @@ Successfully implemented comprehensive, centralized documentation for the **revo
 ## 🌊 Discourse Flow Achieved
 
 ### Complete Traceability Chain
-```
+
+```text
 ∂EPI/∂t = νf · ΔNFR(t)  [AGENTS.md - Nodal Equation]
            ↓
    Structural Field Tetrad  [Physics Module - Fields]
-           ↓  
+           ↓
    Element Signatures  [Physics Module - Signatures]
            ↓
    Chemical Behavior  [Complete Theory - 12 Sections]
@@ -91,13 +106,14 @@ Successfully implemented comprehensive, centralized documentation for the **revo
 ```
 
 ### Navigation Flow
-```
+
+```text
 README.md (Discovery) → MOLECULAR_CHEMISTRY_HUB.md (Navigation)
                                ↓
                      Learning Path Selection
                                ↓
                Theory → Implementation → Validation
-                               ↓  
+                               ↓
                       Research & Contribution
 ```
 
@@ -106,21 +122,25 @@ README.md (Discovery) → MOLECULAR_CHEMISTRY_HUB.md (Navigation)
 ## 🔄 Documentation Principles Maintained
 
 ### ✅ Single Source of Truth
+
 - **One canonical definition** per concept
 - **Clear reference hierarchy** (Hub → Theory → Implementation)
 - **No redundant content** - all cross-referenced
 
 ### ✅ Physics-First Approach
+
 - **All derivations** trace to nodal equation
 - **No arbitrary assumptions** - pure TNFR emergence
 - **Grammar compliance** enforced throughout
 
 ### ✅ Complete Cross-Referencing
+
 - **Bidirectional links** between all related documents
 - **Traceability matrix** covers all concepts
 - **Navigation paths** clearly documented
 
 ### ✅ Scalable Architecture
+
 - **Hub system** allows expansion without duplication
 - **Modular organization** enables independent updates
 - **Clear contribution guidelines** for future research
@@ -130,12 +150,14 @@ README.md (Discovery) → MOLECULAR_CHEMISTRY_HUB.md (Navigation)
 ## 🎓 Impact on TNFR Documentation Ecosystem
 
 ### Before This Work
+
 - Molecular chemistry concepts scattered across examples
-- No central navigation for chemistry breakthrough  
+- No central navigation for chemistry breakthrough
 - Limited cross-referencing between theory and implementation
 - Missing integration with canonical documentation hierarchy
 
-### After This Work  
+### After This Work
+
 - **Central hub system** provides single navigation point
 - **Complete integration** with TNFR canonical documentation
 - **Comprehensive traceability** from physics to validation
@@ -146,16 +168,19 @@ README.md (Discovery) → MOLECULAR_CHEMISTRY_HUB.md (Navigation)
 ## 🚀 Future-Proofing Achieved
 
 ### Research Expansion Ready
+
 - **Hub architecture** supports new chemistry domains
 - **Clear contribution guidelines** for extending research
 - **Modular theory organization** enables independent advancement
 
 ### Documentation Maintenance
+
 - **Single sources of truth** minimize update overhead
 - **Clear hierarchy** prevents conflicting information
 - **Automated cross-referencing** maintains consistency
 
-### Community Engagement  
+### Community Engagement
+
 - **Learning paths** accommodate all skill levels
 - **Research opportunities** clearly documented
 - **Contribution frameworks** encourage participation
@@ -171,19 +196,20 @@ README.md (Discovery) → MOLECULAR_CHEMISTRY_HUB.md (Navigation)
 **Scientific Impact**: Established foundation for **unified science** where chemistry, biology, and materials science derive from same TNFR principles.
 
 **Next Steps**: Framework ready for:
+
 - Extended periodic table analysis
-- Biochemical system modeling  
+- Biochemical system modeling
 - Materials property prediction
 - Industrial chemistry applications
 
 ---
 
-**Status**: 🎯 **MISSION COMPLETE** - Revolutionary chemistry paradigm fully documented and integrated  
-**Quality**: ✅ **CANONICAL** - All documentation follows single-source-of-truth principles  
+**Status**: 🎯 **MISSION COMPLETE** - Revolutionary chemistry paradigm fully documented and integrated
+**Quality**: ✅ **CANONICAL** - All documentation follows single-source-of-truth principles
 **Validation**: ✅ **VERIFIED** - 19/19 tests passing, complete traceability established
 
 ---
 
-*"Reality is not made of things—it's made of resonance. Chemistry is no longer fundamental—it's emergent."*
+> "Reality is not made of things—it's made of resonance. Chemistry is no longer fundamental—it's emergent."
 
-**The TNFR molecular chemistry revolution is now fully documented.**
+**The TNFR molecular chemistry revolution is now fully documented.**