Phase 3: Structural Validation, Health Assessment, Telemetry & Performance Guardrails

[fermga]

Summary

Implements Phase 3 structural instrumentation:

Added

• Enhanced validation aggregator (run_structural_validation) combining grammar (U1-U3) + canonical field thresholds (Φ_s, |∇φ|, K_φ, ξ_C) with optional ΔΦ_s drift.
• Health assessment (compute_structural_health) generating risk levels (low/elevated/critical) and actionable recommendations.
• Telemetry integration example (examples/structural_health_demo.py) and CLI (scripts/structural_health_report.py).
• Performance guardrails: PerformanceRegistry, perf_guard, compare_overhead + instrumentation of validation aggregator (<~5.8% overhead moderate workload).
• Glyph-aware grammar error factory improvements (operator glyph → canonical name mapping).
• Documentation updates: README Phase 3 section, CONTRIBUTING instrumentation guidelines, docs/STRUCTURAL_HEALTH.md.
• Changelog entry for v9.1.0.

Tests

• Added unit tests for aggregator, health, telemetry emitter, grammar error factory, performance guardrails (all passing).

Deferred

• U4 bifurcation validation intentionally excluded pending handler reintroduction.

Integrity

• All changes preserve TNFR canonical invariants (read-only; no EPI mutation; phase verification intact).

Performance

• Validation instrumentation overhead measured (~5.8%) below 8% guardrail threshold.

Request

Merge Phase 3 enhancements into main to publish version 9.1.0.

Next Steps (Post-Merge)

• Optional: Reintroduce U4 bifurcation handler.
• Expand examples for drift scenarios & critical ξ_C transitions.
• Address datetime.utcnow() deprecation warning in telemetry for future-proof UTC handling.

Reality is not made of things—it's made of resonance.

[netlify]

❌ Deploy Preview for stunning-zabaione-f1f1ef failed. Why did it fail? →

Name	Link
🔨 Latest commit	7ee5e1d
🔍 Latest deploy log	https://app.netlify.com/projects/stunning-zabaione-f1f1ef/deploys/6917663340aa56000826f393

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Guard human log formatting when metrics missing

The human mirror path in TelemetryEmitter.flush always formats coherence_total and sense_index as floats (C={coh:.3f}, Si={si:.3f}), but record() intentionally allows these entries to be absent when metric computation fails and safe=True. When either key is missing or None, the f-string raises TypeError: unsupported format string passed to NoneType, causing flush to crash despite “safe” mode. Consider defaulting to 0 or skipping formatting when the metrics are unavailable so that telemetry logging cannot fail.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Seed random graphs without nonexistent nx.random

The CLI seeding logic calls nx.random.seed(args.seed) before constructing an Erdos–Renyi graph. NetworkX exposes no random attribute, so this line raises AttributeError: module 'networkx' has no attribute 'random' whenever --random is used, preventing the script from running at all. Use Python’s random.seed or NetworkX’s numpy.random.default_rng instead to seed randomness.

Useful? React with 👍 / 👎.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[Copilot]

Pull Request Overview

This PR implements Phase 3 structural instrumentation for TNFR, adding comprehensive validation, health assessment, telemetry, and performance guardrails. The changes introduce read-only observability layers that preserve canonical TNFR invariants while providing actionable insights into structural health and grammar compliance.

Key Changes:

• Enhanced validation aggregator combining grammar rules (U1-U3) with canonical field thresholds (Φ_s, |∇φ|, K_φ, ξ_C)
• Health assessment system with risk levels and actionable recommendations
• Unified telemetry emitter for metrics streaming with JSON Lines output
• Performance guardrails ensuring instrumentation overhead remains below 8%

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/tnfr/validation/aggregator.py	Core validation aggregator combining grammar and field threshold checks
src/tnfr/validation/health.py	Health assessment with risk levels and recommendations
src/tnfr/performance/guardrails.py	Performance measurement utilities with registry and decorators
src/tnfr/operators/introspection.py	Operator metadata registry for tooling integration
src/tnfr/operators/grammar_error_factory.py	Structured grammar error generation with enriched metadata
src/tnfr/metrics/telemetry.py	Unified telemetry emitter for structural metrics streaming
src/tnfr/operators/definitions.py	Integration of new introspection and grammar error exports
src/tnfr/metrics/__init__.py	Export of new telemetry components
tests/unit/validation/test_health.py	Unit tests for health assessment
tests/unit/validation/test_aggregator.py	Unit tests for validation aggregator
tests/unit/performance/test_guardrails.py	Unit tests for performance guardrails
tests/unit/operators/test_grammar_error_factory.py	Unit tests for grammar error factory
tests/unit/metrics/test_telemetry_emitter.py	Unit tests for telemetry emitter
examples/structural_health_demo.py	Demo integrating telemetry and health assessment
scripts/structural_health_report.py	CLI tool for generating health reports
docs/STRUCTURAL_HEALTH.md	Comprehensive documentation for Phase 3 features
README.md	Updated with Phase 3 usage examples and overview
CONTRIBUTING.md	Added guidelines for structural instrumentation contributions
CHANGELOG.md	Version 9.1.0 release notes

Comments suppressed due to low confidence (1)

examples/structural_health_demo.py:97

• File is opened but is not closed.

        for ln in open(
            telemetry_path, "r", encoding="utf-8"
        ).read().splitlines()[-3:]:

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] Trailing whitespace after the closing brace. Remove the extra spaces at the end of the line for consistency with project style.

Suggested change

[Copilot]

Resource leak: file handle not closed. The open() call should use a context manager to ensure proper resource cleanup.

Replace:

for ln in open(
    telemetry_path, "r", encoding="utf-8"
).read().splitlines()[-3:]:
    print("  ", ln)

With:

with open(telemetry_path, "r", encoding="utf-8") as f:
    lines = f.read().splitlines()[-3:]
    for ln in lines:
        print("  ", ln)

Suggested change

	for ln in open(
	telemetry_path, "r", encoding="utf-8"
	).read().splitlines()[-3:]:
	print(" ", ln)
	with open(telemetry_path, "r", encoding="utf-8") as f:
	lines = f.read().splitlines()[-3:]
	for ln in lines:
	print(" ", ln)

[Copilot]

Duplicate documentation line: "where available." appears on both lines 145 and 146. Remove one occurrence.

Suggested change

where available.

[Copilot]

datetime.utcnow() is deprecated as of Python 3.12. Use datetime.now(timezone.utc) instead to avoid deprecation warnings.

Replace:

t_iso=datetime.utcnow().isoformat(timespec="seconds") + "Z",

With:

from datetime import timezone
# ...
t_iso=datetime.now(timezone.utc).isoformat(timespec="seconds"),

Note: datetime.now(timezone.utc) already includes timezone info, so the "+Z" suffix is not needed.

[Copilot]

Potential None attribute error if any field value is None. When formatting strings with .3f, you need to handle None values to avoid AttributeError.

For example, if coh, si, or phi are None, the string formatting will fail. Add None checks before formatting:

coh_str = f"{coh:.3f}" if coh is not None else "NA"
si_str = f"{si:.3f}" if si is not None else "NA"
# Use these in the write call

Suggested change

	hf.write(
	(
	f"[{ev.step}] op={ev.operator} C={coh:.3f} "
	f"Si={si:.3f} Φ_s={phi} t={ev.t_iso}\n"
	coh_str = f"{coh:.3f}" if coh is not None else "NA"
	si_str = f"{si:.3f}" if si is not None else "NA"
	phi_str = phi if phi is not None else "NA"
	hf.write(
	(
	f"[{ev.step}] op={ev.operator} C={coh_str} "
	f"Si={si_str} Φ_s={phi_str} t={ev.t_iso}\n"

[Copilot]

[nitpick] The wrapped function lacks proper type annotations which can affect type checking. Consider adding:

def wrapped(*args: Any, **kwargs: Any) -> Any:

This maintains compatibility with mypy and other type checkers.

Suggested change

	def wrapped(*args, **kwargs): # type: ignore[override]
	def wrapped(*args: Any, **kwargs: Any) -> Any: # type: ignore[override]

[Copilot]

Docstring incorrectly states the return contains "(instrumented - baseline) / baseline" but the actual formula is correct in the code. The ratio represents overhead, which should be clarified.

Update docstring:

"""Compare overhead ratio between baseline and instrumented call sets.

Returns timing dict with baseline, instrumented and ratio representing
overhead: (instrumented - baseline) / baseline.
"""

Suggested change

	Returns timing dict with baseline, instrumented and ratio
	(instrumented - baseline) / baseline.
	Returns a timing dict with the following keys:
	- 'baseline': total elapsed time for baseline runs
	- 'instrumented': total elapsed time for instrumented runs
	- 'ratio': overhead, computed as (instrumented - baseline) / baseline
	- 'runs': number of runs performed
	The 'ratio' represents the relative overhead introduced by instrumentation.

[Copilot]

The documentation example is inconsistent. Line 57 calls compute_structural_health(report) but compute_structural_health expects a graph G as its first parameter, not a ValidationReport.

Based on the function signature in health.py, the correct usage is:

health = compute_structural_health(
    G,
    sequence=["AL","UM","IL","SHA"],
    perf_registry=perf,
)

Additionally, line 59 attempts to access health.recommendations but health is a dict, so it should be health["recommended_actions"].

Suggested change

	health = compute_structural_health(report)
	print(report.risk_level, report.thresholds_exceeded)
	for rec in health.recommendations:
	health = compute_structural_health(
	G,
	sequence=["AL","UM","IL","SHA"],
	perf_registry=perf,
	)
	print(health["risk_level"], health["thresholds_exceeded"])
	for rec in health["recommended_actions"]:

[Copilot]

The example calls compute_structural_health(report) but this function expects a graph G as its first parameter, not a ValidationReport.

Based on the function signature, the correct usage is:

health = compute_structural_health(
    G,
    sequence=["AL","UM","IL","SHA"],
)

This is a separate call from run_structural_validation.

Suggested change

	health = compute_structural_health(report)
	health = compute_structural_health(
	G,
	sequence=["AL","UM","IL","SHA"],
	)

[Copilot]

The variable health is referenced on line 97 but it's a dict, not an object with a .recommendations attribute. This should be health["recommended_actions"] to match the actual structure returned by compute_structural_health.

Replace:

print(report.risk_level, health.recommendations)

With:

print(report.risk_level, health["recommended_actions"])

Suggested change

	print(report.risk_level, health.recommendations)
	print(report.risk_level, health["recommended_actions"])

The best way to fix a module-level cyclic import in Python is to restructure the code so that the import between the two modules is no longer cyclic. There are several ways to do this: (1) move any function or class (e.g., ExtendedGrammarError) that is only needed in one module (and causes the import) to the module where it is actually required, and delete the import from the other module; (2) if both modules require access to shared functionality, move the interdependent parts to a new third module, and have both modules import from the third module instead of each other, thereby breaking the cycle.

In this specific scenario, because the cyclic import is caused by importing ExtendedGrammarError, collect_grammar_errors, and make_grammar_error from grammar_error_factory in definitions.py, and the error message suggests that grammar_error_factory.py itself imports definitions.py (perhaps for Operator or other symbols), the simplest fix is to (a) move the definitions of ExtendedGrammarError, collect_grammar_errors, and make_grammar_error into a new module (e.g., grammar_core.py or grammar_errors_common.py), (b) have both grammar_error_factory.py and definitions.py import these symbols from the new module, and (c) update any imports accordingly. This breaks the cyclic dependency by making both definitions.py and grammar_error_factory.py depend only on the new module, not on each other.

All required changes should be made in src/tnfr/operators/definitions.py: update import statements to point to the new module as needed. If changes are needed in grammar_error_factory.py, those are out of scope for now.

---

To fix module-level cyclic imports, the best-practice is to break the cycle by moving the imports that create dependencies so that they are imported only within functions or methods that truly need them, or to restructure the modules so that they share a third dependency. In this case, since the offending import in definitions.py is merely re-exporting collect_grammar_errors for the public API, and it's very likely only needed when called directly, we should make the import of collect_grammar_errors a function-local import. That is, remove the module-level import/re-export of collect_grammar_errors in definitions.py. If the public API demands that collect_grammar_errors be available at the module level, we can instead provide a proxy function or property which dynamically imports and returns collect_grammar_errors when accessed, thereby breaking the cyclic initialization chain.

Specifically, in src/tnfr/operators/definitions.py (the only file you've shown), remove collect_grammar_errors from the module-level import and from __all__, and instead add a wrapper function collect_grammar_errors in this module that imports and returns the actual collect_grammar_errors at runtime. This maintains backward compatibility at the API level while breaking the cyclic import.

---

The standard way to break a cyclic import is to defer one side of the import to run-time, for example by moving the potentially problematic import into the body of a function or method—instead of performing it at the module level. In this case, since make_grammar_error is imported at the module level in definitions.py, but the module it comes from (grammar_error_factory) imports definitions.py as well, the cycle triggers the risk.

The best fix is to remove make_grammar_error from the module-level import in definitions.py and instead, wherever it is needed in downstream code, import it locally inside the relevant function/method, or recommend users do so. This is safe because you only need make_grammar_error at runtime; deferring the import avoids the cyclic initialization problem.

Specifically:

• Remove make_grammar_error from the imports and from __all__ in src/tnfr/operators/definitions.py.
• If needed, add documentation to indicate to import it directly from grammar_error_factory (but you cannot change documentation here since you only control the shown code).
• No other code changes required unless you are shown code that uses make_grammar_error inside this file.

---

To fix a module-level cyclic import, the standard techniques are:

1. Move the import inside the function or method that actually requires it (delayed import), rather than at module scope.
2. Refactor the code to remove the dependency (possibly moving utility code to a third module).

In this specific case, the import from .grammar_core import GrammarValidator is performed at the top-level, but it is likely only used in one or two functions (possibly just for validation, or for type checking). Moving this import inside the function(s) that require it (a so-called "local import" or "delayed import") will break the import cycle by ensuring that the actual import only occurs if/when the function is invoked, at which time both modules are guaranteed to have completed their initializations.

Therefore, the single best way to fix the cyclical import is:

• Identify every usage of GrammarValidator in src/tnfr/operators/grammar_error_factory.py.
• Remove the top-level import of GrammarValidator.
• Instead, add the same import at the point(s) of use, inside the relevant function(s).

You only need to make changes within the code blocks you have provided; do not introduce any new dependencies or change any signatures or logic.

---

The recommended solution is to remove or defer the import of StructuralGrammarError to break the module-level cycle. The best approach, given the provided code, is to move the import statement from the module level to inside the function(s) that require it—this way, the import will happen only when the function is called, at which point all modules will already have been initialized and definitions will exist. Specifically, search for all usages of StructuralGrammarError in src/tnfr/operators/grammar_error_factory.py and, if its usage is confined to functions, move the import statement for it inside those function(s). If StructuralGrammarError is used at class level, refactor to only use it in methods or in function scope where possible.

Change to make:

• In src/tnfr/operators/grammar_error_factory.py, remove from .grammar_types import StructuralGrammarError from the module top.
• Add from .grammar_types import StructuralGrammarError inside the function(s) where it is required (for example, in make_grammar_error or wherever it is referenced).

---

To fix the problem, ensure the file opened for reading on line 95 is always properly closed, even if an exception occurs. The best way to do this is to replace the direct call to open(...).read() with a with statement context, so the file is closed automatically after reading. Specifically, modify the block beginning at line 95 so that open is used within a with statement, and use the file object directly to read its contents. This only affects the lines within the file-reading logic inside the try block. No external dependencies or complex changes are needed, only this code in examples/structural_health_demo.py.

---

To resolve the cyclic import, we should break the import cycle by refactoring how get_operator_meta is accessed. The canonical solution is to move the logic that requires get_operator_meta (usually a function or method) out of grammar_error_factory.py and into definitions.py (or a new module, if necessary). If only one function or limited functionality depends on get_operator_meta, this function should be relocated to definitions.py. Then, instead of importing get_operator_meta, grammar_error_factory.py would import the (now relocated) function from definitions.py. This removes the dependency direction from grammar_error_factory.py to definitions.py, breaking the cycle.

To implement this:

• Identify every place in grammar_error_factory.py that uses get_operator_meta, typically in functions or methods.
• Move those functions to definitions.py.
• Update imports everywhere to use the relocated function from definitions.py.
• Remove the import of get_operator_meta from grammar_error_factory.py.

All these edits must occur strictly within the provided snippet of grammar_error_factory.py, and any function using get_operator_meta must be replaced with an importable version from definitions.py.

---

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

To fix the issue of an unused import, we simply need to remove the line import os from the imports section (line 17) in scripts/optimize_repository.py. This will have no impact on the current functionality of the script, as none of the code shown relies on the os module. Only remove the exact line for the import, taking care not to change the order or spacing of other imports.

---

To fix this issue, we should remove the unused import statement (import sys) from the script. This will clean up the code, avoid unnecessary dependencies, and align with Python best practices for maintainability and readability. Specifically, in scripts/optimize_repository.py, delete or comment out the line containing import sys (line 19). No further code changes or other modifications are necessary, as the functionality remains unaffected.

The best way to fix this problem is to edit the import statement at line 21 in scripts/optimize_repository.py so that it no longer imports Dict from the typing module. This preserves all other imported types (List, Set, Optional) in case they are used elsewhere in the file. The change should only modify line 21, removing Dict from the list of imported items, and leaving the rest of the code unchanged.

---

To fix the problem, remove the unused import statement for the os module from scripts/repo_health_check.py. Specifically, delete line 14: import os. No other code needs to be changed, since none of the code shown uses the os module directly or indirectly. This will clean up the dependencies and the script's imports without changing existing functionality.

To resolve the issue, we should simply remove the unused import statement from line 18: from typing import List, Dict, Any, Optional. This reduces code clutter and eliminates an unnecessary dependency. No other changes are needed elsewhere in the code, as these types are not referenced. Only one file and one block need to be edited, and only the one line needs to be deleted.

To address the issue, the except Exception: pass block should be replaced with code that logs a warning message, capturing and displaying details about the exception. This approach surfaces errors to the user or developer while maintaining the program's ability to continue execution. The fix involves modifying the except Exception: block (lines 221-222 in scripts/repo_health_check.py) to call logger.warning(), including information about the exception in the message text. No new imports are needed, as the script already has logging configured and available as logger. Optionally, also attach the exception information with exc_info=True for full traceback details, depending on verbosity or reporting standards.

The best way to fix this problem is to remove the expression statement nu_f * DELTA_NFR entirely, as it has no effect. If the intention was to perform some operation with this expression—such as assigning it to a variable or returning it—then the code should be updated to do so. However, the next lines already correctly compute the derivative starting from symbolic functions rather than these "constant" symbols, which is more general and correct for the intended bifurcation analysis. Thus, simply deleting this line is the right (and non-disruptive) fix.

You only need to remove line 230 (nu_f * DELTA_NFR). No imports, definitions, or follow-up actions are required.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

To fix this problem, simply remove the assignment to the unused variable at the module level. Specifically: In src/tnfr/physics/fields.py, remove both the import line (line 250) and its fallback assignment (line 253) so that approximate_diameter_2sweep is not assigned at all. Since its assignment does not have side effects (it is either imported or set to None), we do not need to keep any right-hand side expressions. No additional imports, method definitions, or code structure changes are necessary. Only the region of code assigning or importing the unused variable should be updated.

The best fix for this type of unused import is to delete the import statement entirely. Removing an unused import cleans up dependencies and improves code readability. Specifically, in src/tnfr/physics/fields.py, lines 250-253 cover importing approximate_diameter_2sweep with a fallback assignment in case the import fails. Since this isn't used anywhere else in the code snippet, both the import and the fallback logic should be deleted. This includes the entire try-except block assigning approximate_diameter_2sweep = None. Only these lines (250-253) need to be removed.

The best way to fix the unused global variable warning for xi_c is to indicate that the result is intentionally unused, by renaming the variable to an "unused" naming convention (e.g., _ or unused_xi_c). Given this is module top-level code, using _ is conventional and clear. This demonstrates intent to future readers and silences static analysis tools. Only change line 70, renaming xi_c to _.

No new methods, imports, or definitions are required. Only change the assignment target. No functionality will be altered, as the value is not further used.

---

To fix the problem, remove the assignment to the unused global variable curv while preserving the function call (to ensure side effects and profiling measurements remain unchanged). Only the left-hand side should be removed, keeping the compute_phase_curvature(G) call in the loop. This change is to be applied in profile_validation.py, specifically to line 69:

69:     curv = compute_phase_curvature(G)

This becomes:

69:     compute_phase_curvature(G)

No imports or further changes are required.

The best fix is to remove the assignment to the unused variable grad on line 68. Rather than assigning to grad, simply call compute_phase_gradient(G) without assigning its result to any variable. This retains the function call for profiling (i.e., its runtime impact and any side effects are preserved) but removes the unused variable and the associated false impression that its value may be used elsewhere. This change should be made in profile_validation.py, on line 68. No additional imports, definitions, or code changes are needed.

---

The best way to fix the problem is to remove the unused assignment to the global variable phi_s. Since the right-hand side function compute_structural_potential(G) still needs to be called for its potential side effects (to be consistent with the way the other field computations are handled), the assignment operator and variable name should be removed, leaving just a bare function call. No other part of the code relies on phi_s, so removing the assignment does not impact any code functionality.

Concretely, in file profile_validation.py, line 67 should be changed from phi_s = compute_structural_potential(G) to simply compute_structural_potential(G). No imports, further code edits, or new definitions are needed.

To resolve the unused global variable warning for report, simply remove the assignment to report and replace it with a function call to run_structural_validation(...). This will ensure the function is still executed for its side effects, but it's clear the return value is intentionally unneeded. Update only lines 43 and avoid changing the arguments or logic of the loop. No new imports or definitions are needed.

---

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

[github-actions]

Automated Code Review

⚠️ Issues found

Please review the workflow logs for details.

The best way to fix the problem is to rename the unused variable curv in the assignment on line 47 to _, which is the standard convention to indicate that the value is intentionally unused. This preserves the function call's side effects (if any) and maintains the timing measurement for benchmarking purposes while clarifying to readers and static analysis tools that the return value is not used.

To do so, update the assignment in the inner loop on line 47 from curv = compute_phase_curvature(G) to _ = compute_phase_curvature(G). No other changes, imports, definitions, or method modifications are required.

To fix the unused global variable error for grad, we should remove the assignment and instead simply call compute_phase_gradient(G) for its potential side effects and to properly time the function execution. Only the timing result (difference between t0 and t1) is needed.

Specifically:

• In benchmark_phase_vectorization.py, in the loop at line 34 for phase gradient timing, replace grad = compute_phase_gradient(G) with compute_phase_gradient(G).
• Preserve the function call to ensure any side effects are maintained.
• No other changes are needed, and no additional imports or definitions are required.

---