Merge optimization/phase-3: 3.7× validation speedup + TNFR-aligned caching

PERFORMANCE ACHIEVEMENTS (73% reduction, 6.138s → 1.670s):
- Fast diameter approximation: 46-111× speedup (O(N+M) vs O(N³))
- Cached eccentricity: 10× first call + ∞× cached (topological invariant)
- Vectorized phase operations: NumPy broadcasting (2-3× faster)
- Field caching: Perfect cache coherence (0.000s repeated calls)
- Grammar early exit: 10-30% speedup on invalid sequences (optional)

PARADIGM ALIGNMENT (All optimizations respect TNFR physics):
- Eccentricity = structural invariant → automatic cache invalidation
- Cache dependencies = structural coupling (graph_topology tracking)
- Vectorization = coherent batch operations (circular topology preserved)
- Read-only telemetry = no state mutation (all invariants preserved)

IMPLEMENTATION (8 major optimizations):
1. UTC timestamp migration (future-proof)
2. Centralized field caching (TNFRHierarchicalCache integration)
3. Performance guardrails (5.8% overhead, < 8% target)
4. Validation aggregator (unified grammar + fields)
5. Fast diameter (2-sweep BFS heuristic)
6. Cached eccentricity (dependencies={'graph_topology'})
7. Vectorized phases (NumPy broadcasting)
8. Grammar early exit (stop_on_first_error parameter)

TESTING: 23/23 tests passing (fields, validation, grammar)
DOCUMENTATION: Complete (OPTIMIZATION_PROGRESS.md, PROFILING_RESULTS.md)
COMMITS: 8 commits (2cf122b...7ee5e1d)

Physics: All optimizations preserve nodal equation semantics and
canonical invariants. Cache respects ∂EPI/∂t = 0 when topology frozen.

Refs: #phase-3, docs/OPTIMIZATION_PROGRESS.md

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

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [9.1.0] - 2025-11-14
+
+### Added
+
+- Phase 3 structural instrumentation:
+  - `run_structural_validation` aggregator (grammar U1-U3 + field thresholds Φ_s, |∇φ|, K_φ, ξ_C, optional ΔΦ_s drift).
+  - `compute_structural_health` with risk levels and recommendations.
+  - `TelemetryEmitter` integration example (`examples/structural_health_demo.py`).
+  - Performance guardrails: `PerformanceRegistry`, `perf_guard`, `compare_overhead`.
+  - CLI: `scripts/structural_health_report.py` (on-demand health summaries).
+  - Docs: README Phase 3 section, CONTRIBUTING instrumentation notes, `docs/STRUCTURAL_HEALTH.md`.
+- Glyph-aware grammar error factory (operator glyph → canonical name mapping).
+
+### Tests
+
+- Added unit tests for validation, health, grammar error factory, telemetry emitter, performance guardrails.
+
+### Performance
+
+- Validation instrumentation overhead ~5.8% (moderate workload) below 8% guardrail.
+
+### Internal
+
+- Optional `perf_registry` parameter in `run_structural_validation` (read-only timing).
+
+### Deferred
+
+- U4 bifurcation validation excluded pending dedicated handler reintroduction.
+
+### Integrity
+
+- All changes preserve TNFR canonical invariants (no EPI mutation; phase verification intact; read-only telemetry/validation).
+
+## [9.0.2]
+
+Previous release (see repository history) with foundational operators, unified grammar, metrics, and canonical field tetrad.
+
+---
+**Reality is not made of things—it's made of resonance.**

CHANGELOG.md

@@ -126,6 +126,29 @@ ruff check src/
 mypy src/tnfr/
 ```
 
+### 3a. Phase 3 Structural Instrumentation
+
+If adding validation, health, or telemetry logic:
+
+- Use `run_structural_validation` to produce a `ValidationReport`.
+- Derive `compute_structural_health(report)` for recommendations.
+- Include performance timing (pass `perf_registry=PerformanceRegistry()`).
+- Ensure added overhead ratio < 0.10 baseline (see perf tests).
+- Never mutate graph state inside validation / health functions.
+- Document physics traceability (why each threshold is used).
+
+Telemetry additions must:
+
+- Remain read-only (no operator side effects).
+- Export coherence (`coherence_total`), sense index, Φ_s, |∇φ|, K_φ, ξ_C.
+- Provide deterministic timestamps when seeds fixed.
+
+Performance guardrails:
+
+- Wrap optional expensive helpers with `perf_guard(label, registry)`.
+- Add/adjust tests under `tests/unit/performance/` for new instrumentation.
+- Avoid micro-optimizing at expense of clarity unless overhead > target.
+
 ### 4. Update Documentation
 
 - Add docstrings to new functions/classes
@@ -241,25 +264,30 @@ from tnfr.utils import get_logger
 The TNFR codebase is organized into focused modules for maintainability and cognitive load reduction:
 
 **Operators** (`tnfr.operators.*`):
+
 - **Individual operator modules**: `emission.py`, `coherence.py`, etc. (13 operators)
 - **Base class**: `definitions_base.py` - Shared operator infrastructure
 - **Facade**: `definitions.py` - Backward-compatible imports
 
 **Grammar** (`tnfr.operators.grammar.*`):
+
 - **Constraint modules**: `u1_initiation_closure.py`, `u2_convergence_boundedness.py`, etc. (8 rules)
 - **Facade**: `grammar.py` - Unified validation interface
 
 **Metrics** (`tnfr.metrics.*`):
+
 - **Focused metrics**: `coherence.py`, `sense_index.py`, `phase_sync.py`, `telemetry.py`
 - **Facade**: `metrics.py` - Backward-compatible exports
 
 **Adding New Code**:
+
 - **New operator**: Add to appropriate operator file (e.g., `coupling.py` for coupling modifications)
 - **New metric**: Create new file in `tnfr.metrics/` or extend existing metric module
 - **New grammar rule**: Add to relevant constraint module or create new `uN_*.py` file
 - **Always update facades**: If adding new exports, add to facade files for backward compatibility
 
 **Module Guidelines**:
+
 - Keep files under 600 lines (ideally 200-400)
 - One primary concept per module
 - Use facade pattern for public APIs

CONTRIBUTING.md

@@ -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>