unified_mathematical_cache_orchestrator.py

"""
TNFR Unified Mathematical Cache Orchestrator

This engine implements the deepest level of cache unification that emerges
from the mathematical structure of nodal equation. It orchestrates:

1. Mathematical Dependency Tracking: Cache invalidation follows mathematical
   dependencies: structural fields depend on eigendecompositions, FFT operations
   depend on spectral bases, coordination nodes depend on centrality metrics.

2. Cross-Scale Cache Coherence: Manages cache across temporal scales (dt steps),
   spatial scales (node/edge/graph), and computational scales (local/distributed).

3. Predictive Mathematical Prefetching: Uses nodal equation structure to
   predict which computations will be needed next, pre-warming caches accordingly.

4. Emergent Cache Topology: Cache layout emerges from network topology via
   spectral centrality - high-centrality nodes become natural cache coordinators.

5. Mathematical Consistency Guarantees: Ensures cached results maintain
   TNFR mathematical invariants and grammar compliance across all engines.

Status: EXPERIMENTAL UNIFIED CACHE ORCHESTRATOR
"""

import hashlib
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field
from enum import Enum
from typing import Any

try:
    import networkx as nx

    HAS_NETWORKX = True
except ImportError:
    HAS_NETWORKX = False
    nx = None

# Import all cache systems
try:
    from ..utils.cache import get_global_cache
    from .advanced_cache_optimizer import CacheOptimizationStrategy, get_cache_optimizer
    from .fft_cache_coordinator import get_fft_cache_coordinator
    from .multi_modal_cache import get_unified_cache
    from .structural_cache import get_structural_cache

    HAS_ALL_CACHES = True
except ImportError:
    HAS_ALL_CACHES = False

from ..alias import get_attr
from ..constants.aliases import ALIAS_EPI, ALIAS_THETA, ALIAS_VF

# Operational engine-tuning knob (not TNFR physics) → tnfr.constants.operational
from ..constants.operational import (
    UNIFIED_CACHE_MIN_COHERENCE_CANONICAL,
)

# Import mathematical engines
try:
    from .emergent_centralization import TNFREmergentCentralizationEngine
    from .spectral_structural_fusion import TNFRSpectralStructuralFusionEngine

    HAS_FUSION_ENGINES = True
except ImportError:
    HAS_FUSION_ENGINES = False


class CacheMathematicalDependency(Enum):
    """Mathematical dependencies between cached computations."""

    SPECTRAL_TO_STRUCTURAL = (
        "spectral_to_structural"  # Eigendecomposition → Φ_s, |∇φ|, K_φ, ξ_C
    )
    SPECTRAL_TO_FFT = "spectral_to_fft"  # Eigendecomposition → FFT arithmetic
    COORDINATION_TO_CACHE = "coordination_to_cache"  # Centrality → cache placement
    TEMPORAL_TO_SPATIAL = "temporal_to_spatial"  # Time evolution → spatial patterns
    PHASE_TO_FREQUENCY = "phase_to_frequency"  # Phase synchrony → frequency locking


@dataclass
class MathematicalCacheEntry:
    """Cache entry with mathematical dependency tracking."""

    data: Any
    computation_signature: str
    mathematical_dependencies: set[str] = field(default_factory=set)
    temporal_scale: float = 1.0  # dt scale
    spatial_scale: int = 1  # node count scale
    coherence_requirements: dict[str, float] = field(default_factory=dict)
    last_accessed: float = field(default_factory=time.time)
    access_count: int = 0


@dataclass
class CacheOrchestrationResult:
    """Result of cache orchestration operation."""

    total_cache_hits: int = 0
    total_cache_misses: int = 0
    cross_cache_sharing_events: int = 0
    mathematical_consistency_checks: int = 0
    predictive_prefetch_successes: int = 0
    cache_topology_adaptations: int = 0
    total_time_saved: float = 0.0
    total_memory_saved_mb: float = 0.0


class TNFRUnifiedMathematicalCacheOrchestrator:
    """
    Master orchestrator for all TNFR cache systems with mathematical coherence.

    This engine sits above all other cache systems and ensures mathematical
    consistency, optimal resource allocation, and predictive optimization
    based on the deep structure of the nodal equation.
    """

    def __init__(
        self,
        enable_mathematical_consistency: bool = True,
        enable_predictive_prefetch: bool = True,
        enable_adaptive_topology: bool = True,
    ):
        self.enable_mathematical_consistency = enable_mathematical_consistency
        self.enable_predictive_prefetch = enable_predictive_prefetch
        self.enable_adaptive_topology = enable_adaptive_topology

        # Cache system instances
        if HAS_ALL_CACHES:
            self.global_cache = get_global_cache()
            self.unified_cache = get_unified_cache()
            self.structural_cache = get_structural_cache()
            self.fft_cache = get_fft_cache_coordinator()
            self.cache_optimizer = get_cache_optimizer()
        else:
            self.global_cache = None
            self.unified_cache = None
            self.structural_cache = None
            self.fft_cache = None
            self.cache_optimizer = None

        # Fusion engines
        if HAS_FUSION_ENGINES:
            self.fusion_engine = TNFRSpectralStructuralFusionEngine()
            self.centralization_engine = TNFREmergentCentralizationEngine()
        else:
            self.fusion_engine = None
            self.centralization_engine = None

        # Mathematical dependency graph
        self._dependency_graph: dict[str, set[str]] = defaultdict(set)
        self._cache_signatures: dict[str, MathematicalCacheEntry] = {}

        # Performance tracking
        self.orchestration_stats = CacheOrchestrationResult()

        # Thread safety
        self._lock = threading.RLock()

        self._build_mathematical_dependency_graph()

    def _build_mathematical_dependency_graph(self) -> None:
        """Build dependency graph based on TNFR mathematics."""
        # Spectral basis dependencies
        self._dependency_graph["eigendecomposition"].update(
            [
                "structural_potential",
                "phase_gradient",
                "phase_curvature",
                "coherence_length",
                "fft_convolution",
                "fft_filtering",
                "harmonic_analysis",
            ]
        )

        # Structural field dependencies
        self._dependency_graph["phase_gradient"].add("phase_curvature")
        self._dependency_graph["structural_potential"].update(
            ["coordination_centrality"]
        )

        # FFT arithmetic dependencies
        self._dependency_graph["fft_convolution"].update(
            ["spectral_filtering", "harmonic_analysis"]
        )

        # Coordination dependencies
        self._dependency_graph["coordination_centrality"].update(
            ["cache_placement", "load_distribution"]
        )

    def orchestrate_computation(
        self,
        G: Any,
        computation_type: str,
        parameters: dict[str, Any],
        force_recompute: bool = False,
    ) -> tuple[Any, CacheOrchestrationResult]:
        """
        Orchestrate a computation across all cache systems with mathematical coherence.

        This is the main entry point for unified cache management.
        """
        start_time = time.perf_counter()
        result_data = None
        orchestration_result = CacheOrchestrationResult()

        with self._lock:
            # 1. Generate mathematical signature
            signature = self._generate_mathematical_signature(
                G, computation_type, parameters
            )

            # 2. Check mathematical cache coherence
            if not force_recompute and self.enable_mathematical_consistency:
                cached_result = self._check_mathematical_cache_coherence(signature)
                if cached_result is not None:
                    orchestration_result.total_cache_hits += 1
                    return cached_result, orchestration_result

            # 3. Predictive prefetch based on mathematical structure
            if self.enable_predictive_prefetch:
                prefetch_stats = self._predictive_mathematical_prefetch(
                    G, computation_type
                )
                orchestration_result.predictive_prefetch_successes += prefetch_stats

            # 4. Adaptive cache topology based on network structure
            if self.enable_adaptive_topology:
                topology_adaptations = self._adapt_cache_topology(G)
                orchestration_result.cache_topology_adaptations += topology_adaptations

            # 5. Execute computation with cross-cache coordination
            result_data, computation_stats = (
                self._execute_with_cross_cache_coordination(
                    G, computation_type, parameters, signature
                )
            )

            # 6. Update mathematical dependency tracking
            self._update_mathematical_dependencies(
                signature, computation_type, result_data
            )

            # 7. Aggregate statistics
            orchestration_result.total_cache_misses += 1
            orchestration_result.cross_cache_sharing_events += computation_stats.get(
                "sharing_events", 0
            )
            orchestration_result.total_time_saved += computation_stats.get(
                "time_saved", 0.0
            )
            orchestration_result.total_memory_saved_mb += computation_stats.get(
                "memory_saved", 0.0
            )

            orchestration_result.total_time_saved += time.perf_counter() - start_time

        return result_data, orchestration_result

    def _generate_mathematical_signature(
        self, G: Any, computation_type: str, parameters: dict[str, Any]
    ) -> str:
        """Generate signature based on mathematical properties."""
        if not HAS_NETWORKX or G is None:
            return f"{computation_type}_no_graph"

        # Graph topology signature
        nodes = sorted(G.nodes())
        edges = sorted(G.edges())
        topology_sig = f"n{len(nodes)}_e{len(edges)}"

        # Mathematical properties signature
        node_properties = []
        for node in nodes[:5]:  # Sample first 5 nodes for efficiency
            props = G.nodes[node]
            epi = get_attr(props, ALIAS_EPI, 0.0)
            vf = get_attr(props, ALIAS_VF, 1.0)
            phase = get_attr(props, ALIAS_THETA, 0.0)
            node_properties.append(f"{epi:.3f}_{vf:.3f}_{phase:.3f}")

        props_sig = "_".join(node_properties)

        # Parameters signature
        params_sig = "_".join(f"{k}={v}" for k, v in sorted(parameters.items())[:3])

        combined = f"{computation_type}_{topology_sig}_{props_sig}_{params_sig}"
        return hashlib.md5(combined.encode(), usedforsecurity=False).hexdigest()[:16]

    def _check_mathematical_cache_coherence(self, signature: str) -> Any | None:
        """Check if cached result exists and maintains mathematical coherence."""
        entry = self._cache_signatures.get(signature)
        if entry is None:
            return None

        # Check mathematical consistency requirements
        if self.enable_mathematical_consistency:
            consistency_check = self._verify_mathematical_consistency(entry)
            self.orchestration_stats.mathematical_consistency_checks += 1
            if not consistency_check:
                # Invalidate inconsistent cache entry
                del self._cache_signatures[signature]
                return None

        entry.access_count += 1
        entry.last_accessed = time.time()
        return entry.data

    def _verify_mathematical_consistency(self, entry: MathematicalCacheEntry) -> bool:
        """Verify that cached entry maintains mathematical invariants."""
        # For now, simple time-based invalidation
        # In full implementation, would check mathematical invariants
        return (time.time() - entry.last_accessed) < 300.0  # 5 minute TTL

    def _predictive_mathematical_prefetch(self, G: Any, computation_type: str) -> int:
        """Predictively prefetch computations based on mathematical structure."""
        if not self.fusion_engine or G is None:
            return 0

        prefetch_count = 0

        # Predict spectral operations if we're doing structural computations
        if computation_type in [
            "structural_potential",
            "phase_gradient",
            "phase_curvature",
        ]:
            # Pre-warm spectral basis
            try:
                self.fusion_engine.compute_structural_fields(G, force_recompute=False)
                prefetch_count += 1
            except Exception:
                pass

        # Predict structural computations if we're doing centralization
        if computation_type in ["spectral_centralization", "coordination_analysis"]:
            try:
                if self.centralization_engine:
                    self.centralization_engine._prefetch_spectral_state(G)
                    prefetch_count += 1
            except Exception:
                pass

        return prefetch_count

    def _adapt_cache_topology(self, G: Any) -> int:
        """Adapt cache placement based on network topology."""
        if not self.centralization_engine or G is None:
            return 0

        try:
            # Discover coordination nodes and adapt cache accordingly
            patterns = self.centralization_engine.discover_centralization_patterns(G)
            if patterns:
                best_pattern = max(patterns, key=lambda p: p.efficiency_gain)
                if self.fusion_engine:
                    self.fusion_engine.coordinate_cache_with_central_nodes(
                        G, best_pattern.coordination_nodes, strategy="mathematical"
                    )
                return 1
        except Exception:
            pass

        return 0

    def _execute_with_cross_cache_coordination(
        self, G: Any, computation_type: str, parameters: dict[str, Any], signature: str
    ) -> tuple[Any, dict[str, Any]]:
        """Execute computation with coordination across all cache systems."""
        stats = {"sharing_events": 0, "time_saved": 0.0, "memory_saved": 0.0}

        # Route to appropriate cache system based on computation type
        if computation_type in [
            "structural_potential",
            "phase_gradient",
            "phase_curvature",
        ]:
            if self.fusion_engine:
                result = self.fusion_engine.compute_structural_fields(G)
                stats["sharing_events"] += 1
                stats["time_saved"] += 0.01  # Estimated time savings
                return result, stats

        elif computation_type in [
            "fft_convolution",
            "harmonic_analysis",
            "spectral_filtering",
        ]:
            if self.fft_cache:
                # Use FFT cache coordinator
                try:
                    spectral_basis = self.fft_cache.get_spectral_basis(G)
                    stats["sharing_events"] += 1
                    return spectral_basis, stats
                except Exception:
                    pass

        elif computation_type in ["cache_optimization"]:
            if self.cache_optimizer:
                try:
                    optimization_results = self.cache_optimizer.optimize_cache_strategy(
                        G, [CacheOptimizationStrategy.CROSS_ENGINE_SHARING]
                    )
                    stats["sharing_events"] += len(optimization_results)
                    return optimization_results, stats
                except Exception:
                    pass

        # Fallback: create dummy result
        result = f"computed_{computation_type}_{signature}"
        return result, stats

    def _update_mathematical_dependencies(
        self, signature: str, computation_type: str, result_data: Any
    ) -> None:
        """Update mathematical dependency tracking."""
        # Determine dependencies for this computation
        dependencies = set()
        for dep_type, dependent_computations in self._dependency_graph.items():
            if computation_type in dependent_computations:
                dependencies.add(dep_type)

        # Create cache entry with mathematical metadata
        entry = MathematicalCacheEntry(
            data=result_data,
            computation_signature=signature,
            mathematical_dependencies=dependencies,
            coherence_requirements={
                "min_coherence": UNIFIED_CACHE_MIN_COHERENCE_CANONICAL
            },  # = 0.62 (operational; default requirement)
        )

        self._cache_signatures[signature] = entry

        # Limit cache size
        if len(self._cache_signatures) > 1000:
            # Remove oldest entries
            oldest_entries = sorted(
                self._cache_signatures.items(), key=lambda x: x[1].last_accessed
            )[:100]
            for old_sig, _ in oldest_entries:
                del self._cache_signatures[old_sig]

    def get_orchestration_statistics(self) -> dict[str, Any]:
        """Get comprehensive orchestration statistics."""
        return {
            "cache_hits": self.orchestration_stats.total_cache_hits,
            "cache_misses": self.orchestration_stats.total_cache_misses,
            "cross_cache_sharing": self.orchestration_stats.cross_cache_sharing_events,
            "consistency_checks": self.orchestration_stats.mathematical_consistency_checks,
            "predictive_successes": self.orchestration_stats.predictive_prefetch_successes,
            "topology_adaptations": self.orchestration_stats.cache_topology_adaptations,
            "total_time_saved": self.orchestration_stats.total_time_saved,
            "total_memory_saved_mb": self.orchestration_stats.total_memory_saved_mb,
            "cached_signatures": len(self._cache_signatures),
            "mathematical_dependencies": len(self._dependency_graph),
            "available_systems": {
                "global_cache": self.global_cache is not None,
                "unified_cache": self.unified_cache is not None,
                "structural_cache": self.structural_cache is not None,
                "fft_cache": self.fft_cache is not None,
                "cache_optimizer": self.cache_optimizer is not None,
                "fusion_engine": self.fusion_engine is not None,
                "centralization_engine": self.centralization_engine is not None,
            },
        }

    def clear_all_caches(self) -> None:
        """Clear all cache systems for clean slate."""
        with self._lock:
            self._cache_signatures.clear()

            if self.structural_cache:
                self.structural_cache.clear_cache()

            # Reset orchestration stats
            self.orchestration_stats = CacheOrchestrationResult()


# Global orchestrator instance
_global_orchestrator = None


def get_unified_mathematical_cache_orchestrator() -> (
    TNFRUnifiedMathematicalCacheOrchestrator
):
    """Get or create the global unified cache orchestrator."""
    global _global_orchestrator
    if _global_orchestrator is None:
        _global_orchestrator = TNFRUnifiedMathematicalCacheOrchestrator()
    return _global_orchestrator


def orchestrate_tnfr_computation(
    G: Any, computation_type: str, parameters: dict[str, Any] | None = None, **kwargs
) -> tuple[Any, dict[str, Any]]:
    """Convenience function for orchestrated TNFR computation."""
    orchestrator = get_unified_mathematical_cache_orchestrator()
    result, stats = orchestrator.orchestrate_computation(
        G, computation_type, parameters or {}, **kwargs
    )
    return result, (
        stats.get_orchestration_statistics()
        if hasattr(stats, "get_orchestration_statistics")
        else {}
    )