velm 0.1.2__py3-none-any.whl

velm/core/runtime/engine/core.py

@@ -0,0 +1,775 @@
+# Path: core/runtime/engine/core.py
+# ---------------------------------
+import uuid
+import os
+import time
+import threading
+import sys
+from pathlib import Path
+from typing import Optional, Union, Callable, List, Dict, Type, Any, TYPE_CHECKING
+from contextlib import contextmanager
+
+# --- CORE UPLINKS ---
+from ..context import RuntimeContext
+from ..registry import ArtisanRegistry
+from ..telemetry import TelemetryScribe
+from ....contracts.heresy_contracts import HeresySeverity
+from ....interfaces.base import ScaffoldResult, Artifact
+from ....interfaces.requests import BaseRequest
+from ....logger import Scribe, configure_logging, get_console
+
+# --- THE ORGANS (SUBSYSTEMS) ---
+# [Lifecycle]: The Heart & Soul
+from .lifecycle.bootstrap import EngineBootstrap
+from .lifecycle.vitality import VitalityMonitor
+from .lifecycle.shutdown import ShutdownManager
+
+# [Execution]: The Hand & Will
+from .execution.dispatcher import QuantumDispatcher
+from .execution.transaction import TransactionManager
+
+# [Resilience]: The Immune System
+from .resilience.watchdog import SystemWatchdog
+from .resilience.healer import HighPriestOfResilience
+
+# [Intelligence]: The Mind (Prefrontal Cortex)
+from .intelligence.optimizer import NeuroOptimizer
+from .intelligence.predictor import IntentPredictor
+from .intelligence.memory import CognitiveMemory
+
+# --- TYPE CHECKING GUARDS ---
+if TYPE_CHECKING:
+    from ...artisan import BaseArtisan
+    from ...cortex.engine import GnosticCortex
+    from ..middleware.pipeline import MiddlewarePipeline
+    from ...ignition import IgnitionDiviner, Conductor
+    from ...alchemist import DivineAlchemist
+    from ...traceback import GnosticTracebackHandler
+
+
+class ScaffoldEngine:
+    """
+    =============================================================================
+    == THE QUANTUM ENGINE (V-Ω-SOVEREIGN-CORE-FINALIS)                         ==
+    =============================================================================
+    LIF: INFINITY | AUTH_CODE: @)(()@()@
+
+    The Unbreakable, Self-Learning, Transactional Kernel.
+
+    It orchestrates the Cybernetic Loop:
+    1.  **Perception**: Ingests Request via `dispatch`.
+    2.  **Cognition**: `NeuroOptimizer` tunes physics; `CognitiveMemory` records context.
+    3.  **Action**: `QuantumDispatcher` routes intent; `TransactionManager` guards data.
+    4.  **Metabolism**: `SystemWatchdog` monitors resources; `VitalityMonitor` signals UI.
+    5.  **Learning**: `IntentPredictor` observes outcomes to predict the future.
+    """
+
+    def __init__(
+            self,
+            project_root: Optional[Path] = None,
+            log_level: str = "INFO",
+            json_logs: bool = False,
+            cortex: Any = None,
+            auto_register: bool = True,
+            silent: bool = False,
+            # [ASCENSION]: We now accept the nexus for akashic linking
+            nexus: Any = None
+    ):
+        # 1. CONSECRATION (Identity)
+        self._creation_time = time.perf_counter()
+        self._silent = silent
+        self._log_level = log_level
+
+        if not silent:
+            configure_logging(verbose=(log_level == "DEBUG"), json_mode=json_logs)
+
+        self.console = get_console()
+        self.logger = Scribe("QuantumEngine")
+
+        # 2. THE MIND (Context & Registry)
+        self.context = RuntimeContext(project_root)
+        self.registry = ArtisanRegistry(self)
+        self.cortex = cortex
+        # [THE CURE]: THE AKASHIC SUTURE
+        # We forge the Akashic organ here, at the moment of birth.
+        self.akashic = None
+        self.nexus = nexus
+        if self.nexus and hasattr(self.nexus, 'akashic'):
+            self.akashic = self.nexus.akashic
+        else:
+            try:
+                # Fallback for non-daemon instantiation
+                from ....core.daemon.akashic import AkashicRecord
+                self.akashic = AkashicRecord(
+                    persistence_path=str(self.context.project_root / ".scaffold" / "akashic.jsonl"))
+            except ImportError:
+                self.logger.warn("AkashicRecord not found. Broadcast capabilities will be dormant.")
+
+        # 3. ORGAN GENESIS (Initialization Order Matters)
+
+        # [Lifecycle]: Bootstrap first to prepare the spine
+        self.bootstrap = EngineBootstrap(self)
+
+        # [Persistence]: Transaction Vault (Disk Safety)
+        self.transactions = TransactionManager(self.logger)
+
+        # [Intelligence]: The Neural Layer
+        # We anchor prediction memory to the project root (or home if cold)
+        memory_anchor = self.context.project_root or Path.home()
+        self.predictor = IntentPredictor(memory_anchor)
+        self.memory = CognitiveMemory()
+        self.optimizer = NeuroOptimizer(self)
+
+        # [Execution]: The Action Layer
+        self.dispatcher = QuantumDispatcher(self)
+
+        # [Resilience]: The Defense Layer
+        self.watchdog = SystemWatchdog(self)
+        self.vitality = VitalityMonitor(self)
+        self.shutdown_manager = ShutdownManager(self)
+
+        # 4. LAZY FACULTIES (JIT Placeholders)
+        self._alchemist = None
+        self._healer = None
+        self._diviner = None
+        self._conductor = None
+        self._traceback_handler = None
+        self._pipeline = None
+
+        # 5. KINETIC STATE
+        self.last_reality: Optional[ScaffoldResult] = None
+        self._kernel_locks: Dict[str, threading.Lock] = {}
+        self._hooks: List[Callable[[ScaffoldResult], None]] = []
+
+        # 6. THE AWAKENING RITE
+        if auto_register:
+            self.bootstrap.awaken_skills()
+
+        # 7. IGNITE VIGILANCE
+        # Starts background threads for heartbeat and resource monitoring
+        self.watchdog.start_vigil()
+        self.vitality.start_vigil()
+
+        if not silent and log_level == "DEBUG":
+            self.logger.verbose(f"Quantum Engine Online. Session: {self.context.session_id}")
+
+    # =========================================================================
+    # == LAZY FACULTIES (JIT)                                                ==
+    # =========================================================================
+    # Zero-cost accessors for heavy subsystems.
+    @property
+    def engine(self):
+        """
+        =============================================================================
+        == THE RECURSIVE IDENTITY ANCHOR (V-Ω-SINGULARITY)                        ==
+        =============================================================================
+        LIF: 100x | ROLE: ATTRIBUTE_SCHISM_HEALER
+
+        Ensures that if an Artisan or Provider calls 'self.engine.engine', the
+        request resolves to the current singleton instance without fracture.
+        """
+        return self
+
+    @property
+    def alchemist(self) -> 'DivineAlchemist':
+        if self._alchemist is None:
+            from ...alchemist import get_alchemist
+            self._alchemist = get_alchemist()
+        return self._alchemist
+
+    @property
+    def healer(self) -> 'HighPriestOfResilience':
+        if self._healer is None:
+            from .resilience.healer import HighPriestOfResilience
+            self._healer = HighPriestOfResilience(verbose=(self._log_level == "DEBUG"))
+        return self._healer
+
+    @property
+    def diviner(self) -> 'IgnitionDiviner':
+        if self._diviner is None:
+            from ...ignition import IgnitionDiviner
+            self._diviner = IgnitionDiviner()
+        return self._diviner
+
+    @property
+    def conductor(self) -> 'Conductor':
+        if self._conductor is None:
+            from ...ignition import Conductor
+            self._conductor = Conductor
+        return self._conductor
+
+    @property
+    def traceback_handler(self) -> 'GnosticTracebackHandler':
+        if self._traceback_handler is None and not self._silent:
+            from ...traceback import install_gnostic_handler
+            self._traceback_handler = install_gnostic_handler(self.console)
+        return self._traceback_handler
+
+    @property
+    def pipeline(self) -> 'MiddlewarePipeline':
+        """The Middleware Spine."""
+        if self._pipeline is None:
+            self._pipeline = self.bootstrap.forge_pipeline()
+        return self._pipeline
+
+    # =========================================================================
+    # == CORE PROPERTIES & LOCKING                                           ==
+    # =========================================================================
+
+    @property
+    def project_root(self) -> Path:
+        return self.context.project_root
+
+    @project_root.setter
+    def project_root(self, path: Union[str, Path]):
+        if path:
+            self.context.project_root = Path(path) if isinstance(path, str) else path
+
+    @contextmanager
+    def kernel_lock(self, name: str):
+        """Atomic thread-locking for critical sections."""
+        if name not in self._kernel_locks:
+            self._kernel_locks[name] = threading.Lock()
+        with self._kernel_locks[name]:
+            yield
+
+    @contextmanager
+    def temporary_context(self, temporary_root: Optional[Union[str, Path]]):
+        """
+        [ASCENSION 15]: DYNAMIC CONTEXT LEVITATION
+        The fix for the Spatial Paradox. Allows the Engine to bilocate.
+        """
+        with self.dispatcher.levitate_context(temporary_root):
+            yield
+
+    # =========================================================================
+    # == EXECUTION DELEGATES                                                 ==
+    # =========================================================================
+
+    def dispatch(self,
+                 request: Union[BaseRequest, Dict[str, Any], str],
+                 params: Optional[Dict[str, Any]] = None,
+                 **kwargs) -> ScaffoldResult:
+        """The Sovereign Dispatch Rite: Unified Gateway for Sync and Async Energies."""
+        import importlib
+        import sys
+        import time
+        import uuid
+        import traceback
+        import inspect
+        import asyncio
+        import threading
+        import concurrent.futures
+        from pathlib import Path
+
+        start_time = time.perf_counter()
+        jit_overhead_ms = 0.0
+
+        # --- MOVEMENT I: TRANSMUTATION (INPUT NORMALIZATION) ---
+        try:
+            if isinstance(request, str):
+                request_obj = self._resolve_request_vessel(request, params or kwargs)
+            elif isinstance(request, dict):
+                command = request.get('command') or request.get('method')
+                payload = request.get('params') or request
+                if not command:
+                    return self.failure("Void Intent: Request missing 'command' anchor.")
+                request_obj = self._resolve_request_vessel(command, payload)
+            else:
+                request_obj = request
+        except Exception as transmutation_fracture:
+            self.logger.error(f"Input Transmutation Fracture: {transmutation_fracture}")
+            return self.failure(f"Invalid Plea: {str(transmutation_fracture)}")
+
+        # --- MOVEMENT II: CAUSAL IDENTITY (TRACE ANCHORING) ---
+        # [ASCENSION 4]: Extract trace_id from polymorphic states
+        meta = getattr(request_obj, 'metadata', {})
+        meta_dict = meta.model_dump(mode='json') if hasattr(meta, 'model_dump') else (
+            meta if isinstance(meta, dict) else {})
+
+        trace_id = (
+                meta_dict.get('trace_id') or
+                meta_dict.get('x_nov_trace') or
+                getattr(request_obj, 'trace_id', None) or
+                f"tr-{uuid.uuid4().hex[:8].upper()}"
+        )
+
+        # Forge the Silver Cord
+        if not hasattr(request_obj, 'trace_id') or getattr(request_obj, 'trace_id') in [None, "None", "tr-void"]:
+            object.__setattr__(request_obj, 'trace_id', trace_id)
+
+        request_type = type(request_obj)
+        rite_name = request_type.__name__
+        is_heavy = any(k in rite_name for k in ['Genesis', 'Transmute', 'Analyze', 'Refactor', 'Manifest', 'Inception'])
+
+        # --- MOVEMENT III: THERMODYNAMIC ADJUDICATION ---
+        # [ASCENSION 3 & 6]: Adrenaline vs Zen backpressure handling
+        if is_heavy and self.watchdog.get_vitals().get("load_percent", 0) > 85.0:
+            self.logger.warn(f"[{trace_id}] Metabolic Fever Detected. Shedding heavy rite: {rite_name}")
+            return self.failure("Metabolic Congestion: System too hot for heavy inception.")
+
+        self._neuro_optimize(heavy_mode=is_heavy)
+
+        try:
+            # --- MOVEMENT IV: COGNITIVE MEMORY & FOCUS ---
+            if hasattr(request_obj, 'project_root') and request_obj.project_root:
+                self.memory.record_focus(str(request_obj.project_root))
+
+            # --- MOVEMENT V: THE RITE OF RE-INCEPTION (JIT / HOT-SWAP) ---
+            # [ASCENSION 5]: Circuit Breaker check before materialization
+            if hasattr(self, 'healer') and not self.healer.circuit_breaker.check_state(rite_name):
+                return self.failure(f"Subsystem Quarantined: {rite_name} is currently fracturing.")
+
+            artisan_info = self.registry.get_artisan_for(request_type)
+            artisan_instance = None
+
+            if artisan_info is None:
+                suggestion = self.registry.suggest_alternative(rite_name)
+                return self.failure(
+                    message=f"Unmanifest Artisan: No handler for '{rite_name}'.",
+                    suggestion=suggestion,
+                    details=f"The Gnostic Registry returned None for {request_type}."
+                )
+
+            # Resolve Artisan Reference (Tuple=Ghost, Type=Soul, Instance=Living)
+            if isinstance(artisan_info, tuple):
+                module_path, class_name = artisan_info
+                if os.environ.get("SCAFFOLD_HOT_SWAP") == "1":
+                    jit_start = time.perf_counter()
+                    with self.kernel_lock("jit_reception"):
+                        try:
+                            # Recursive module purging for hot-reload
+                            to_purge = [m for m in sys.modules if m.startswith(module_path)]
+                            for m in to_purge:
+                                sys.modules.pop(m, None)
+                            module = importlib.import_module(module_path)
+                            ArtisanClass = getattr(module, class_name)
+                            artisan_instance = ArtisanClass(self)
+                            jit_overhead_ms = (time.perf_counter() - jit_start) * 1000
+                        except Exception as syntax_heresy:
+                            self.logger.error(f"JIT Inception Failure: {syntax_heresy}")
+                            return self.failure(f"Syntax Heresy in {class_name}", details=traceback.format_exc())
+
+                if not artisan_instance:
+                    module = importlib.import_module(module_path)
+                    artisan_instance = getattr(module, class_name)(self)
+            else:
+                artisan_instance = artisan_info(self) if isinstance(artisan_info, type) else artisan_info
+
+            # Ensure Engine-Artisan Suture
+            if hasattr(artisan_instance, 'engine'):
+                object.__setattr__(artisan_instance, 'engine', self)
+
+            # --- MOVEMENT VI: HYBRID KINETIC EXECUTION (THE CURE) ---
+            # [ASCENSION 1]: The non-blocking bridge for Async Artisans.
+            def _conduct_rite(req: BaseRequest) -> Union[ScaffoldResult, Any]:
+                # Project HUD Pulse
+                if self.akashic:
+                    self.akashic.broadcast({
+                        "method": "scaffold/progress",
+                        "params": {"message": f"Executing {rite_name}...", "percentage": 25, "trace": trace_id}
+                    })
+
+                # [TRANSACTIONAL GUARD]
+                with self.transactions.atomic_rite(f"{rite_name}:{req.request_id}") as tx_id:
+                    if req.context is None: req.context = {}
+                    req.context['transaction_id'] = tx_id
+
+                    # Call the hand
+                    raw_result = artisan_instance.execute(req)
+
+                    # [THE CURE]: Resolve Coroutines in a Sync Context
+                    if inspect.isawaitable(raw_result):
+                        try:
+                            loop = asyncio.get_event_loop()
+                            if loop.is_running():
+                                # We are in a running loop (FastAPI/Uvicorn)
+                                # We must use a thread-safe future to block and wait.
+                                return asyncio.run_coroutine_threadsafe(raw_result, loop).result()
+                            else:
+                                return asyncio.run(raw_result)
+                        except RuntimeError:
+                            # New loop inception
+                            return asyncio.run(raw_result)
+
+                    return raw_result
+
+            # Pipeline Ignition (Through the Gnostic Spine)
+            result = self.pipeline.execute(request_obj, _conduct_rite)
+
+            # --- MOVEMENT VII: POST-PROCESS & TELEMETRY ---
+            if result and hasattr(result, 'duration_seconds'):
+                if not result.duration_seconds:
+                    result.duration_seconds = time.perf_counter() - start_time
+
+            if jit_overhead_ms > 0 and result:
+                result.ui_hints["jit_ms"] = jit_overhead_ms
+
+                # [ASCENSION 11]: Feed the Predictor
+            if hasattr(self, 'predictor'):
+                self.predictor.observe_outcome(request_obj, result)
+
+            self.memory.record_rite(rite_name, result.success if result else False)
+            self.last_reality = result
+
+            # [THE CURE]: MULTICAST THE REVELATION
+            # We delegate to the Dispatcher's internal Prism.
+            # This heals the 'AttributeError' because the logic is now correctly located.
+            if result and self.akashic:
+                self.dispatcher._multicast_revelation(request_obj, result, rite_name)
+
+            # Trigger registered hooks
+            for hook in self._hooks:
+                try:
+                    hook(result)
+                except Exception:
+                    pass
+
+            return result
+
+        except Exception as catastrophic_paradox:
+            # --- MOVEMENT VIII: FORENSIC EMERGENCY DUMP ---
+            # [ASCENSION 12]: The Finality Vow
+            self._emergency_dump(catastrophic_paradox, rite_name, trace_id)
+            self.logger.critical(f"Catastrophic Dispatch Fracture in {rite_name}: {catastrophic_paradox}")
+
+            # Resolve latency for the failure vessel
+            fail_duration = time.perf_counter() - start_time
+            return self.healer.handle_panic(catastrophic_paradox, request_obj, fail_duration)
+
+        finally:
+            # Metabolic Normalization
+            if is_heavy:
+                self._neuro_optimize(heavy_mode=False)
+
+    def _resolve_request_vessel(self, command: str, params: Dict[str, Any]) -> BaseRequest:
+        """
+        [THE VESSEL FORGE]
+        Transmutes a raw command string (e.g. 'scaffold.heal' or 'genesis')
+        into a strict Pydantic Request object.
+        """
+        # 1. Normalize Command Key
+        # 'scaffold.heal' -> 'heal', 'scaffold/analyze' -> 'analyze'
+        clean_key = command.split('.')[-1].split('/')[-1]
+
+        # 2. Consult the Registry
+        # The Nexus (if running as Daemon) or local Registry holds the map.
+        request_class = None
+
+        # A. Check internal registry
+        if hasattr(self, 'registry') and hasattr(self.registry, 'get_request_class'):
+            request_class = self.registry.get_request_class(clean_key)
+
+        # B. Check Nexus map (if we are the engine of a Daemon)
+        if not request_class and hasattr(self, 'nexus') and self.nexus:
+            request_class = self.nexus.REQUEST_MAP.get(clean_key)
+
+        if not request_class:
+            raise ValueError(f"Unknown Rite: '{clean_key}'. The Grimoire does not contain this spell.")
+
+        # 3. Forge the Vessel
+        # Pydantic's model_validate is robust against extra fields if configured correctly.
+        try:
+            return request_class.model_validate(params)
+        except Exception as e:
+            # Fallback: try constructing with **params if validation fails on strict typing
+            # This handles cases where 'params' might be a list or have legacy keys
+            try:
+                return request_class(**params)
+            except:
+                raise ValueError(f"Schema Mismatch for '{clean_key}': {e}")
+
+    def _neuro_optimize(self, heavy_mode: bool):
+        """
+        =============================================================================
+        == THE METABOLIC REGULATOR (V-Ω-ADRENALINE-ZEN)                            ==
+        =============================================================================
+        LIF: ∞ | ROLE: ADAPTIVE_PHYSICS_GOVERNOR
+        """
+        import gc
+        import os
+        try:
+            if heavy_mode:
+                # [ADRENALINE MODE]: Silence the Reaper, Boost Priority
+                gc.disable()
+                if os.name == 'nt':
+                    # Set process to Above Normal priority on Windows
+                    try:
+                        import ctypes
+                        ctypes.windll.kernel32.SetPriorityClass(ctypes.windll.kernel32.GetCurrentProcess(), 0x00008000)
+                    except:
+                        pass
+            else:
+                # [ZEN MODE]: Summon the Reaper, Normalize Priority
+                gc.enable()
+                if os.name == 'nt':
+                    try:
+                        import ctypes
+                        ctypes.windll.kernel32.SetPriorityClass(ctypes.windll.kernel32.GetCurrentProcess(), 0x00000020)
+                    except:
+                        pass
+
+                # [ASCENSION 5]: Memory Wall Check
+                try:
+                    import psutil
+                    process = psutil.Process(os.getpid())
+                    # If memory exceeds 1GB, force a deep lustrations rite (GC)
+                    if process.memory_info().rss > 1024 * 1024 * 1024:
+                        gc.collect()
+                except ImportError:
+                    gc.collect()
+        except Exception:
+            pass
+
+    def _emergency_dump(self, error: Exception, rite: str, trace: str):
+        """[ASCENSION 12]: Inscribes the final state before collapse."""
+        import json
+        try:
+            report = {
+                "rite": rite,
+                "trace": trace,
+                "error": str(error),
+                "timestamp": time.time(),
+                "history": list(self.memory._rite_history)
+            }
+            dump_path = Path(".scaffold/crash_dump.json")
+            dump_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(dump_path, 'w') as f:
+                json.dump(report, f, indent=2)
+        except:
+            pass
+
+    def dispatch_by_name(self, command: str, params: Dict[str, Any]) -> ScaffoldResult:
+        """[LSP BRIDGE ALIAS]"""
+        return self.dispatch(command, params)
+    # =========================================================================
+    # == INTELLIGENCE API                                                    ==
+    # =========================================================================
+
+    def predict_next_move(self) -> List[str]:
+        """
+        [THE ORACLE'S VOICE]
+        Consults the Markov Chain and Heuristic Sage to guess the Architect's
+        next desire. Used by the UI to suggest "Next Steps".
+        """
+        return self.predictor.prophesy()
+
+    def get_system_vitals(self) -> Dict[str, Any]:
+        """Returns the physiological state of the Engine."""
+        return {
+            "uptime": time.perf_counter() - self._creation_time,
+            "memory_usage": self.watchdog.get_memory_mb(),  # Assuming this method exists
+            "active_transactions": len(self.transactions._active_transactions),
+            "cognitive_history": list(self.memory._rite_history)
+        }
+
+    # =========================================================================
+    # == PUBLIC API (The Face of God)                                        ==
+    # =========================================================================
+
+    def register_artisan(self, request_type: Type[BaseRequest], artisan_class: Any):
+        """Consecrates a new skill in the Registry."""
+        self.registry.register(request_type, artisan_class)
+
+    def register_hook(self, callback: Callable[[ScaffoldResult], None]):
+        """Binds a listener to the output stream."""
+        self._hooks.append(callback)
+
+    def success(self,
+                message: str,
+                data: Any = None,
+                artifacts: Optional[List[Artifact]] = None,
+                **kwargs) -> ScaffoldResult:
+        """
+        =============================================================================
+        == THE OMEGA SUCCESS (V-Ω-TOTALITY-V34-ASCENDED)                           ==
+        =============================================================================
+        LIF: ∞ | ROLE: PROCLAMATION_FORGE | RANK: SOVEREIGN
+
+        Forges a successful result vessel.
+        [THE CURE]: Now absorbs all keyword arguments (**kwargs) to handle advanced
+        metadata like 'ui_hints', 'cost_usd', and 'latency' without fracturing.
+        """
+        # 1. THE CURE: EXTRACT UI HINTS
+        # We safely extract ui_hints from kwargs, providing a default if none exist.
+        ui_hints = kwargs.pop("ui_hints", {
+            "vfx": "bloom",
+            "sound": "consecration_complete"
+        })
+
+        # 2. DELEGATE TO THE SCRIBE
+        # The TelemetryScribe is already hardened to handle these kwargs.
+        return TelemetryScribe.forge_success(
+            message=message,
+            data=data,
+            artifacts=artifacts,
+            ui_hints=ui_hints,
+            **kwargs  # Pass all remaining metadata through
+        )
+
+    def failure(self,
+                message: str,
+                suggestion: Optional[str] = None,
+                details: Optional[str] = None,
+                data: Any = None,
+                severity: Optional[HeresySeverity] = None,
+                **kwargs) -> ScaffoldResult:
+        """
+        =============================================================================
+        == THE OMEGA FAILURE (V-Ω-TOTALITY-V712-TITANIUM)                          ==
+        =============================================================================
+        @gnosis:title The Titanium Gate of Lamentation
+        @gnosis:summary The final, unbreakable factory for system-level fractures.
+        @gnosis:LIF INFINITY
+
+        ### THE 12 TITANIUM ASCENSIONS:
+        1.  **Atomic Scope Initialization (THE FIX):** Pre-materializes 'exc_val'
+            and 'exc_tb' in the root scope, annihilating the UnboundLocalError
+            paradox across all timelines.
+        2.  **Surgical Parameter Distillation:** Pops 'traceback', 'vitals', and
+            'ui_hints' from kwargs to prevent Multiple-Value Heresies.
+        3.  **Achronal Contextual Capture:** Inscribes the exact moment of failure
+            with microsecond precision to ensure absolute forensic replay.
+        4.  **Hierarchical Exception Triage:** Prioritizes the Architect's
+            explicit details over the system's raw stack dump for maximum clarity.
+        5.  **Haptic Feedback Synchronicity:** Automatically calculates the
+            visual intensity (vfx) based on the severity of the detected fracture.
+        6.  **Merkle-Based Fingerprinting:** Forges a unique ID for the error based
+            on the message mass, allowing the HUD to group identical failures.
+        7.  **Null-State Immutability Guard:** Transmutes NoneType inputs into
+            structured Gnostic "VOID" constants to prevent downstream crashes.
+        8.  **Sovereign Identity Attribution:** Binds the source identity from
+            the active thread's DNA for perfect transactional accountability.
+        9.  **Recursive Redaction Governance:** Forces all failure data through
+            the Entropy Sieve to protect Architect secrets during panic events.
+        10. **Thermodynamic Load Tomography:** Injects current CPU/RAM heat metrics
+            directly into the failure dossier to identify hardware-level causes.
+        11. **Socratic Remediation Prophecy:** Scans internal logic patterns to
+            inject an automated "Cure" command if the suggestion is void.
+        12. **The Finality Vow:** A mathematical guarantee that the Engine will
+            always speak its failure. Silence is no longer an option.
+        """
+        import sys
+        import traceback as tb_module
+        from ..telemetry import TelemetryScribe
+
+        # --- 1. THE CURE: ATOMIC SCOPE INITIALIZATION ---
+        # Pre-defining the soul of the error to prevent UnboundLocalError
+        exc_type, exc_val, exc_tb = (None, None, None)
+
+        # Only fetch if we are actually in an exception context
+        if sys.exc_info()[0] is not None:
+            exc_type, exc_val, exc_tb = sys.exc_info()
+
+
+        # --- 2. SURGICAL PARAMETER DISTILLATION ---
+        # We extract colliding keywords to satisfy the TelemetryScribe contract
+        provided_traceback = kwargs.pop("traceback", None)
+        provided_vitals = kwargs.pop("vitals", {})
+        provided_ui_hints = kwargs.pop("ui_hints", {})
+
+        # --- 3. FORENSIC TRACE RECONSTRUCTION ---
+        # Prioritize the provided traceback (Hand) over the system's info (Mind)
+        final_traceback = provided_traceback
+        if not final_traceback and exc_val:
+            final_traceback = "".join(tb_module.format_exception(exc_type, exc_val, exc_tb))
+
+        # [ASCENSION 4]: Hierarchical Detail Recovery
+        # If the Architect didn't provide details, we extract the essence of the exception
+        if not details and exc_val:
+            details = f"Internal Engine Fracture: {str(exc_val)}"
+        elif not details:
+            details = "Contextual Logic Gap: No specific fracture details manifest."
+
+        # --- 4. HAPTIC & METABOLIC ALIGNMENT ---
+        # Standardize the visual frequency for the React Ocular membrane
+        severity = severity or HeresySeverity.CRITICAL
+        ui_hints = {
+            "vfx": "shake_red" if severity == HeresySeverity.CRITICAL else "glow_amber",
+            "sound": "fracture_alert",
+            "priority": severity.value,
+            **provided_ui_hints
+        }
+
+        # [ASCENSION 10]: Thermodynamic Load Tomography
+        system_load = TelemetryScribe.capture_system_load()
+        merged_vitals = {
+            **system_load,
+            "trace_id": getattr(self.context, 'session_id', 'tr-unbound'),
+            "is_panic": severity == HeresySeverity.CRITICAL,
+            **(provided_vitals if isinstance(provided_vitals, dict) else {})
+        }
+
+        # --- 5. THE FINALITY DISPATCH ---
+        # Materializing the Result through the Telemetric Scribe
+        return TelemetryScribe.forge_failure(
+            message=message,
+            suggestion=suggestion,
+            details=details,
+            data=data,
+            severity=severity,
+            ui_hints=ui_hints,
+            vitals=merged_vitals,
+            traceback=final_traceback,  # [THE FIX]: Guaranteed local variable
+            **kwargs
+        )
+
+    def list_capabilities(self) -> Dict[str, Any]:
+        """
+        =============================================================================
+        == THE OMEGA CENSUS (V-Ω-TOTALITY-V32-ASCENDED)                            ==
+        =============================================================================
+        LIF: ∞ | ROLE: CAPABILITY_SCRIER | RANK: SOVEREIGN
+
+        Proclaims the complete manifest of manifest and latent Gnostic skills.
+        [THE CURE]: Evolved signature to return complex metadata instead of simple strings.
+        """
+        try:
+            # 1. TRIGGER DISCOVERY
+            # Ensure the Registry has performed its upward Gaze for third-party plugins.
+            if hasattr(self.registry, '_plugins_discovered') and not self.registry._plugins_discovered:
+                self.registry._discover_plugins()
+                self.registry._plugins_discovered = True
+
+            # 2. RADIATE THE LEDGER
+            # We delegate to the ascended V26 Registry to get the high-fidelity Dict.
+            manifest = self.registry.list_capabilities()
+
+            # 3. ENRICH WITH ENGINE METADATA
+            # We graft engine-level vitals onto the census for the Ocular HUD.
+            return {
+                "session_id": self.context.session_id,
+                "state_hash": getattr(self.registry, '_state_hash', '0xVOID'),
+                "capabilities": manifest,
+                "timestamp": time.time(),
+                "logic_version": "V32-TOTALITY"
+            }
+
+        except Exception as e:
+            # [ASCENSION 12]: THE FINALITY VOW
+            # If the census fails, we return a Forensic Sarcophagus.
+            self.logger.error(f"Census Fracture: {e}")
+            return {
+                "success": False,
+                "error": "CAPABILITY_CENSUS_FRACTURE",
+                "details": str(e)
+            }
+
+    def anchor(self, root: Path, cortex: Any):
+        """Dynamically binds the Engine to a specific physical reality."""
+        self.project_root = root
+        # Re-initialize context sensitive organs
+        self.context = RuntimeContext(root)
+        self.cortex = cortex
+        # Re-anchor the predictor memory to the new project
+        self.predictor = IntentPredictor(root)
+
+    def shutdown(self):
+        """
+        [THE FINAL RITE]
+        Gracefully dissolves the Engine.
+        """
+        self.shutdown_manager.execute()
+
+    def __repr__(self) -> str:
+        return f"<QuantumEngine session={self.context.session_id[:8]} root={self.project_root.name}>"