Runtime Violation Registry
Relevant source files
The following files were used as context for generating this wiki page:
The Runtime Violation Registry is a specialized utility within flext-core designed to act as a process-local buffer for architectural and enforcement violations detected during execution. It provides a centralized mechanism for capturing Report objects—which contain one or more Violation instances—allowing them to be buffered and subsequently "drained" or cleared by consuming systems, such as a dispatcher or a test runner.
The registry is primarily used to track violations of FLEXT enforcement rules, such as MRO (Method Resolution Order) issues, code smells, and namespace violations that occur at runtime. By buffering these reports, the system ensures that violations can be collected atomically without immediately interrupting execution unless a strict enforcement mode is active.
Sources: tests/unit/test_utilities_runtime_violation_registry_coverage_100.py:1-12, src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py:108-121
Core Architecture
The registry operates as a singleton-style utility using class methods to manage a private, process-local buffer. This buffer maintains a FIFO (First-In, First-Out) order for all appended reports.
Data Flow
The following diagram illustrates the lifecycle of a violation report within the registry:
The registry acts as an intermediate storage point between the enforcement detection logic and the final reporting or error-handling logic.
Sources: tests/unit/test_utilities_runtime_violation_registry_coverage_100.py:15-25
Key Components and Operations
The registry exposes three primary operations via its public interface. These operations are designed to be atomic and idempotent where applicable.
| Operation | Description |
|---|---|
append_violation_report | Adds a new m.Report to the internal process-local buffer. |
drain_violation_reports | Returns all buffered reports as a tuple and resets the internal buffer to empty. |
clear_violation_reports | Discards all currently buffered reports without returning them. |
Sources: tests/unit/test_utilities_runtime_violation_registry_coverage_100.py:46-77
Buffering Logic
When a report is appended, it is stored in the order it was received. The drain operation is destructive, meaning once reports are retrieved, they are removed from the registry to prevent duplicate processing.
Integration with Enforcement Engine
The FlextUtilitiesEnforcement engine utilizes the registry to handle violations specifically identified with rule IDs such as ENFORCE-022 (Runtime Warning). When the enforcement engine detects issues during class definition or model construction, it generates reports that can be routed through this registry.
Violation Model Structure
The registry handles m.Report objects, which are composed of m.Violation models. A violation includes several critical metadata fields:
| Field | Type | Description |
|---|---|---|
qualname | str | The fully qualified name of the offending class or attribute. |
layer | str | The architectural layer (e.g., "Model", "Runtime", "namespace"). |
severity | str | The severity level (e.g., "warning", "HARD rules", "MEDIUM"). |
message | str | The human-readable description of the violation. |
rule_id | str | The specific FLEXT enforcement rule ID (e.g., "ENFORCE-001"). |
Sources: tests/unit/test_enforcement_reports.py:65-104, src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py:108-121
Usage in Testing
The registry is heavily exercised in unit tests to ensure that the process-local state does not leak between test cases. Pytest fixtures are typically used to clear the buffer before and after tests to maintain isolation.
@pytest.fixture
def _isolated_buffer(self) -> None:
"""Guarantee each test starts and ends with an empty buffer."""
runtime_registry.clear_violation_reports()
Sources: tests/unit/test_utilities_runtime_violation_registry_coverage_100.py:32-35
Conclusion
The Runtime Violation Registry provides a critical, low-overhead mechanism for capturing architectural debt and rule violations during the Python runtime. By decoupling detection from reporting, it allows flext-core to maintain clean execution flows while ensuring that all violations are logged and available for developer review or automated quality gates.