Consolidate engine contracts and repository maintenance

Unify represented-real admission across standard and optimized execution,
operators and Mutation histories. Preserve raw REMESH callback evidence,
centralize finite reduction arithmetic and correct spectral diagnostics.

Consolidate cache and arithmetic CLI owners, align public SDK exports and
strict atomic report I/O, and repair standalone primality packaging. Retire
unused benchmark/grammar helpers and redundant automation. Correct example
claims, preserve code during documentation staging and guard generated paths.

Validation: 7468 routine engine/API tests passed, 38 skipped, plus 2 passing
subtests. Affected mathematical, packaging, CLI and maintenance checks pass;
2969 internal references and strict MkDocs build pass. Final pinned Black and
isort hooks, flake8 and whitespace checks pass. The final formatting changes
preserve the validated Python AST.

Research queue, model-law scope and frozen evidence remain unchanged. Routine
validation does not replay the complete historical research inventory.

Author: TNFR AI Agent

.github/WORKFLOWS.md

@@ -15,7 +15,6 @@ not establish current GitHub run health, branch protection or enabled secrets.
 | [pip-audit.yml](workflows/pip-audit.yml) | Push/PR to main/master, Monday 05:00 UTC and manual invocation. Audits the installed core, test-all and serialization environment; captures available reports and fails when the JSON audit fails. |
 | [pypi-zenodo.yml](workflows/pypi-zenodo.yml) | Published GitHub release or manual invocation. Builds and checks distributions; publishes on release or when the existing manual force-publish input is true. |
 | [lint-workflows.yml](workflows/lint-workflows.yml) | Filtered workflow/script changes on PRs and pushes to main. Searches for unsupported Bandit SARIF invocation; this is not a general Actions schema linter. |
-| [code-review.yml](workflows/code-review.yml) | PR opened, synchronized or reopened on main. Advisory Black/mypy checks and an automated PR comment; no external code-review service is implemented. |
 | [copilot-setup-steps.yml](workflows/copilot-setup-steps.yml) | Manual invocation or edits to its own workflow. Installs a Python 3.11 development/test environment and verifies importability. |
 
 The default pytest selection is the routine engine/API gate and excludes slow
@@ -78,6 +77,11 @@ verify a DOI. No GitHub/PyPI/Zenodo settings are inferred from this file.
 
 ## Retired automation
 
+The former `code-review.yml` job and reminder-only pre-commit hook are retired.
+Black and advisory mypy already have maintained owners in `ci.yml`; repeating
+them in another environment and posting an automatic PR comment added no
+independent review coverage. The main CI gates retain their existing scope.
+
 The test consolidation removed `tests.yml`, which repeated the complete SDK
 suite on Python 3.11 already included in `ci.yml`. The main matrix retains the
 SDK assertions, environment checks and JUnit/coverage reporting.

.github/workflows/code-review.yml

@@ -17,6 +17,7 @@ on:
       - 'src/tnfr/_version.py'
       - 'scripts/check_documentation.py'
       - 'scripts/prepare_docs.py'
+      - 'scripts/clean_repository.py'
       - 'scripts/verify_internal_references.py'
       - '.github/workflows/docs.yml'
   pull_request:
@@ -35,6 +36,7 @@ on:
       - 'src/tnfr/_version.py'
       - 'scripts/check_documentation.py'
       - 'scripts/prepare_docs.py'
+      - 'scripts/clean_repository.py'
       - 'scripts/verify_internal_references.py'
       - '.github/workflows/docs.yml'
   workflow_dispatch: {}

.github/workflows/docs.yml

@@ -17,12 +17,6 @@ repos:
         files: ^src/tnfr/
   - repo: local
     hooks:
-      - id: code-review-check
-        name: Code review quality check
-        entry: bash -c 'echo "Remember to run code review before committing significant changes (make lint test)" && exit 0'
-        language: system
-        pass_filenames: false
-        stages: [pre-commit]
       - id: check-bandit-format
         name: Check for invalid bandit -f sarif usage
         entry: bash -c 'if grep -r "bandit.*-f sarif" .github/workflows/ scripts/ --exclude=lint-workflows.yml 2>/dev/null; then echo "ERROR - bandit does not support SARIF format. Use -f json instead."; exit 1; fi'

.pre-commit-config.yaml

@@ -18,6 +18,11 @@ boundary, not a measured speedup. Other state/configuration dependencies remain
 part of each consumer's key or explicit invalidation contract. Graph views use
 fresh computations; concurrent mutation during a read is unsupported.
 
+LRU storage and callback handling have one implementation in
+[`utils/unified_cache.py`](src/tnfr/utils/unified_cache.py). The historical
+`InstrumentedLRUCache` and `ManagedLRUCache` names remain aliases in `utils.cache`;
+graph invalidation and persistence retain their separate responsibilities.
+
 ## Implementation owners
 
 | Concern | Source of truth |
@@ -35,6 +40,8 @@ fresh computations; concurrent mutation during a read is unsupported.
 | Nodal integration | [`integrators.py`](src/tnfr/dynamics/integrators.py) |
 | Runtime invocation ordinals | [`_runtime_steps.py`](src/tnfr/_runtime_steps.py); separate from physical time, operator counts and retained metric samples |
 | Represented-real scalar admission | [`_exact_time.py`](src/tnfr/_exact_time.py), reused by clocks, phases, rates and operator gates |
+| Signed scalar EPI admission | [`types.py`](src/tnfr/types.py), validating raw scalars and serialized components before BEPI coercion; shared by standard and optimized execution |
+| Finite matrix products, differences and norms for reductions | [`physics/_finite_linear_algebra.py`](src/tnfr/physics/_finite_linear_algebra.py); quotient and morphism checks preserve finite-range failures |
 | Active acceleration history and detached evidence | [`nodal_equation.py`](src/tnfr/operators/nodal_equation.py), `observe_structural_acceleration` |
 | Optional THOL preconditions and threshold resolution | [`preconditions/self_organization.py`](src/tnfr/operators/preconditions/self_organization.py), [`_thol_config.py`](src/tnfr/operators/_thol_config.py) |
 | Public THOL birth proposals | [`self_organization.py`](src/tnfr/operators/self_organization.py) |
@@ -49,6 +56,7 @@ fresh computations; concurrent mutation during a read is unsupported.
 | Validated relational transit | [`physics/relational_transit.py`](src/tnfr/physics/relational_transit.py); exact reflected ODE enclosure using shared rational intervals, Taylor derivatives and signed-diagonal comparison; read-only proof computation, not live engine evolution |
 | Coherence and equilibrium kernel | [`common.py`](src/tnfr/metrics/common.py) |
 | Public high-level API | [`sdk/simple.py`](src/tnfr/sdk/simple.py) |
+| JSON report I/O | [`sdk/utils.py`](src/tnfr/sdk/utils.py); strict decoding and atomic export, also used by the CLI and fluent `save()` |
 
 These are implementation responsibilities. The [documentation ownership map](docs/README.md)
 identifies the single maintained guide for each responsibility.

ARCHITECTURE.md

@@ -33,6 +33,10 @@ The source inventory is discoverable without starting any experiment:
 rg --files benchmarks -g '*.py'
 ```
 
+The retained graph-preparation helper serves the curvature safety illustration.
+Unused generic CLI scaffolding and handwritten grammar validators are removed;
+use each instrument's actual CLI and the shared engine grammar/executor owners.
+
 ## Reuse the mechanism appropriate to the question
 
 - [Local relational composition](relational_local_composition.py) checks exact

benchmarks/README.md

@@ -1,8 +1,8 @@
 """Benchmark Utilities for TNFR Research
 ==========================================
 
-Shared utilities for creating valid TNFR graphs, generating grammar-compliant
-operator sequences, and running experiments.
+Shared supplied-graph preparation for the curvature safety illustration.
+Operator admission and execution belong to the production engine.
 
 Status: RESEARCH - Support infrastructure for validation experiments
 """
@@ -15,7 +15,6 @@
 # Import TNFR core
 import sys
 from pathlib import Path
-from typing import Any, List
 
 import networkx as nx
 
@@ -31,21 +30,6 @@
     VF_PRIMARY,
     inject_defaults,
 )
-from tnfr.operators.definitions import (
-    Coherence,
-    Contraction,
-    Coupling,
-    Dissonance,
-    Emission,
-    Expansion,
-    Mutation,
-    Reception,
-    Recursivity,
-    Resonance,
-    SelfOrganization,
-    Silence,
-    Transition,
-)
 
 
 def create_tnfr_topology(topology: str, n_nodes: int, seed: int) -> nx.Graph:
@@ -65,8 +49,6 @@ def create_tnfr_topology(topology: str, n_nodes: int, seed: int) -> nx.Graph:
     nx.Graph
         Graph with TNFR defaults injected but nodes not yet initialized
     """
-    random.seed(seed)
-
     if topology == "ring":
         G = nx.cycle_graph(n_nodes)
     elif topology == "scale_free":
@@ -102,14 +84,15 @@ def create_tnfr_topology(topology: str, n_nodes: int, seed: int) -> nx.Graph:
 
     # Inject TNFR defaults into graph
     inject_defaults(G)
+    G.graph["RANDOM_SEED"] = seed
 
     return G
 
 
 def initialize_tnfr_nodes(
     G: nx.Graph,
     nu_f: float = 1.0,
-    epi_range: tuple[float, float] = (0.2, 0.8),  # FIXED: Within [-1, 1]
+    epi_range: tuple[float, float] = (0.2, 0.8),
     seed: int = 42,
 ) -> None:
     """Initialize node attributes with proper TNFR primary keys.
@@ -121,143 +104,20 @@ def initialize_tnfr_nodes(
     nu_f : float
         Structural frequency (νf) for all nodes
     epi_range : tuple[float, float]
-        (min, max) for random EPI initialization (must be in [-1, 1])
+        (min, max) for the supplied signed scalar EPI initialization
     seed : int
         Random seed
     """
-    random.seed(seed)
+    rng = random.Random(seed)
 
     for node in G.nodes:
-        G.nodes[node][EPI_PRIMARY] = random.uniform(*epi_range)
+        G.nodes[node][EPI_PRIMARY] = rng.uniform(*epi_range)
         G.nodes[node][VF_PRIMARY] = nu_f
-        G.nodes[node][THETA_PRIMARY] = random.uniform(0.0, 2 * math.pi)
-        G.nodes[node][DNFR_PRIMARY] = random.uniform(0.01, 0.05)
+        G.nodes[node][THETA_PRIMARY] = rng.uniform(0.0, 2 * math.pi)
+        G.nodes[node][DNFR_PRIMARY] = rng.uniform(0.01, 0.05)
         # NOTE: Do NOT add legacy aliases ('phase', 'delta_nfr')
         # The fields.py module will find the correct aliases automatically
         # Adding redundant aliases causes desync issues
 
 
-def generate_grammar_valid_sequence(
-    sequence_type: str,
-    intensity: float = 1.0,
-) -> List[Any]:
-    """Generate operator sequences that comply with TNFR grammar (U1-U4).
-
-    All sequences:
-    - Start with generator (U1a): Emission, Transition, or Recursivity
-    - End with closure (U1b): Silence, Transition, Recursivity, or Dissonance
-    - Include stabilizers after destabilizers (U2)
-    - Respect canonical flow compatibility matrix
-
-    Parameters
-    ----------
-    sequence_type : str
-        'RA_dominated' (resonance-heavy), 'OZ_heavy' (dissonance-heavy),
-        'balanced' (mixed)
-    intensity : float
-        Multiplier for sequence length (1.0 = baseline)
-
-    Returns
-    -------
-    List
-        List of operator instances forming a valid sequence
-    """
-    base_length = max(3, int(intensity * 5))
-
-    if sequence_type == "RA_dominated":
-        # Resonance/coupling focused sequence
-        # Pattern: AL → IL → (RA → IL)* → SHA
-        seq = [Emission(), Coherence()]
-        n_resonance = max(1, int(base_length * 0.5))
-        for _ in range(n_resonance):
-            seq.extend([Resonance(), Coherence()])
-        seq.append(Silence())
-
-    elif sequence_type == "OZ_heavy":
-        # Dissonance-heavy sequence with required stabilizers
-        # Pattern: AL → (OZ → IL)* → (VAL → THOL) → SHA
-        seq = [Emission()]
-        n_dissonance = max(1, int(base_length * 0.4))
-        for _ in range(n_dissonance):
-            seq.extend([Dissonance(), Coherence()])
-        # Add expansion with self-organization (U2: destabilizer needs stabilizer)
-        seq.extend([Dissonance(), Expansion(), SelfOrganization(), Coherence()])
-        seq.append(Silence())
-
-    elif sequence_type == "balanced":
-        # Mix of operators maintaining grammar compliance
-        # Pattern: AL → IL → (OZ → IL → RA → IL)* → SHA
-        seq = [Emission(), Coherence()]
-        n_cycles = max(1, int(base_length * 0.3))
-        for _ in range(n_cycles):
-            seq.extend([Dissonance(), Coherence(), Resonance(), Coherence()])
-        seq.append(Silence())
-
-    else:
-        raise ValueError(f"Unknown sequence type: {sequence_type}")
-
-    return seq
-
-
-# Validation: Ensure sequences comply with grammar
-def validate_sequence_grammar(sequence: List[Any]) -> tuple[bool, str]:
-    """Validate that a sequence complies with TNFR grammar rules.
-
-    Checks:
-    - U1a: Starts with generator (AL, NAV, REMESH)
-    - U1b: Ends with closure (SHA, NAV, REMESH, OZ)
-    - U2: Destabilizers (OZ, VAL, ZHIR) followed by stabilizers (IL, THOL)
-
-    Parameters
-    ----------
-    sequence : List
-        List of operator instances
-
-    Returns
-    -------
-    tuple[bool, str]
-        (is_valid, error_message)
-    """
-    if not sequence:
-        return False, "Empty sequence"
-
-    # Map operators to their names
-    op_names = [op.__class__.__name__ for op in sequence]
-
-    # U1a: Generator check
-    generators = {"Emission", "Transition", "Recursivity"}
-    if op_names[0] not in generators:
-        return False, f"Must start with generator, got {op_names[0]}"
-
-    # U1b: Closure check
-    closures = {"Silence", "Transition", "Recursivity", "Dissonance"}
-    if op_names[-1] not in closures:
-        return False, f"Must end with closure, got {op_names[-1]}"
-
-    # U2: Destabilizer → Stabilizer check
-    destabilizers = {"Dissonance", "Expansion", "Mutation"}
-    stabilizers = {"Coherence", "SelfOrganization"}
-
-    for i, op_name in enumerate(op_names):
-        if op_name in destabilizers:
-            # Look ahead for stabilizer within next 3 operators
-            found_stabilizer = False
-            for j in range(i + 1, min(i + 4, len(op_names))):
-                if op_names[j] in stabilizers:
-                    found_stabilizer = True
-                    break
-            if not found_stabilizer:
-                return (
-                    False,
-                    f"Destabilizer {op_name} at position {i} needs stabilizer within 3 ops",
-                )
-
-    return True, "Valid"
-
-
-__all__ = [
-    "create_tnfr_topology",
-    "initialize_tnfr_nodes",
-    "generate_grammar_valid_sequence",
-    "validate_sequence_grammar",
-]
+__all__ = ["create_tnfr_topology", "initialize_tnfr_nodes"]