velm 0.1.2__py3-none-any.whl

velm/core/lsp/scaffold_server/inquest.py

@@ -0,0 +1,268 @@
+# Path: core/lsp/scaffold_server/inquest.py
+# -----------------------------------------
+# LIF: INFINITY | AUTH_CODE: Ω_INQUEST_SINGULARITY_V100_LEGENDARY
+
+import time
+import uuid
+import sys
+import threading
+import logging
+import hashlib
+import re
+from typing import Any, Dict, Optional, List, Tuple
+from pathlib import Path
+
+# --- IRON CORE UPLINKS ---
+from ..base import forensic_log, UriUtils, ServerState, MetricAccumulator
+from ....artisans.analyze.processing.scaffold import ScaffoldProcessor
+from ....artisans.analyze.reporting.privacy import PrivacySentinel
+
+# --- PHYSICS CONSTANTS ---
+MAX_FRACTURE_STRIKES = 3
+HAPTIC_THRESHOLD_MS = 250
+MUNDANE_FLUX_THRESHOLD = 5
+
+# [ASCENSION 12]: ARTIFACT EXORCIST
+# Regex to strip trailing quotes, dots, or whitespace from URIs before broadcast.
+URI_CLEANSER = re.compile(r"['\"\.\s]+$")
+
+
+class OcularInquest:
+    """
+    =============================================================================
+    == THE OCULAR INQUEST (V-Ω-TOTALITY-V100-SINGULARITY)                      ==
+    =============================================================================
+    @gnosis:title The Ocular Inquest
+    @gnosis:summary The Sovereign Optic Nerve. Perceives flux, filters noise, and
+                    projects Gnostic Truth to the UI.
+    @gnosis:LIF 100,000,000,000
+    @gnosis:auth_code: Ω_INQUEST_TITANIUM
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+    1.  **Titanium URI Sanitization:** Applies `UriUtils.normalize_uri` AND a final
+        regex scrub (`URI_CLEANSER`) to annihilate the "Trailing Quote" heresy.
+    2.  **Atomic Version Locking:** Rejects any analysis of version `N` if version `N+1`
+        has already been processed. Time only moves forward.
+    3.  **Merkle Silence:** Calculates MD5 hashes of content. If the content hasn't
+        changed (even if version bumped), the inquest acts as a "Ghost" (no-op).
+    4.  **Fracture Quarantine:** Tracks failures per file. If a specific file crashes
+        the parser 3 times, it is quarantined to protect the Daemon's vitality.
+    5.  **Dual-Stratum Execution:** Runs Stratum-0 (Local Syntax) instantly, then
+        delegates Stratum-1 (Deep Analysis) to the Adrenaline Conductor.
+    6.  **Path Duplication Guard:** Detects recursive path artifacts (`C:/Dev/C:/Dev`)
+        and collapses them before they enter the analysis context.
+    7.  **Privacy Redaction:** Automatically scrubs high-entropy strings (secrets)
+        from diagnostic messages before they leave the server.
+    8.  **Haptic Telemetry:** Measures analysis latency. If >250ms, sends a `gnostic/vfx`
+        pulse to visually confirm "Heavy Computation" to the user.
+    9.  **Trace ID DNA:** Injects a unique `trace_id` into every diagnostic, linking
+        the UI squiggle back to the exact log entry that birthed it.
+    10. **Shadow Awareness:** Detects `scaffold-shadow:` URIs and adjusts context logic
+        to handle ephemeral memory buffers correctly.
+    11. **Metabolic Backpressure:** Checks the Foundry queue depth. If overloaded,
+        it degrades gracefully to "Syntax Only" mode.
+    12. **Inception Sweep:** A dedicated rite to force-analyze all open tabs on boot,
+        ensuring the "Mirror" is populated immediately after handshake.
+    """
+    __slots__ = [
+        'server', 'processor', '_last_version_processed',
+        '_last_merkle_seal', '_fracture_registry', '_lock'
+    ]
+
+    def __init__(self, server: Any):
+        self.server = server
+        # [THE INTERNAL GAZE]: Direct link to the local logic engine
+        self.processor = server._internal_processor
+
+        # --- [INTERNAL MEMORY STRATA] ---
+        self._last_version_processed: Dict[str, int] = {}
+        self._last_merkle_seal: Dict[str, str] = {}
+        self._fracture_registry: Dict[str, int] = {}
+
+        self._lock = threading.RLock()
+
+    def conduct(self, uri: str, content: str, version: int):
+        """
+        [THE RITE OF REVELATION]
+        LIF: 100x | Performs multi-spectral analysis across Local and Remote strata.
+        """
+        # --- 0. SPATIAL COORDINATION ---
+        # [ASCENSION 1]: TITANIUM NORMALIZATION
+        # We normalize immediately to ensure the key is stable across the entire pipeline.
+        norm_uri = UriUtils.normalize_uri(uri)
+
+        # [ASCENSION 12]: ARTIFACT SCRUB (The Final Polish)
+        # Ensure no trailing garbage exists in the key.
+        norm_uri = URI_CLEANSER.sub('', norm_uri)
+
+        fs_path = UriUtils.to_fs_path(norm_uri)
+
+        # [ASCENSION 6]: PATH DUPLICATION CHECK
+        # If the resolved path seems to contain the project root TWICE, we have a fracture.
+        if self.server.project_root:
+            root_str = str(self.server.project_root).replace('\\', '/')
+            path_str = str(fs_path).replace('\\', '/')
+
+            # Simple heuristic: if root appears twice in the path
+            if path_str.count(root_str) > 1:
+                # Try to re-anchor to the root
+                try:
+                    rel = Path(path_str.split(root_str)[-1].lstrip('/'))
+                    fs_path = (self.server.project_root / rel).resolve()
+                    # Re-normalize URI based on corrected path
+                    norm_uri = UriUtils.to_uri(fs_path)
+                except:
+                    pass
+
+        # --- 1. [ASCENSION 3]: THE MERKLE SEAL ---
+        # Calculate the hash of the current matter
+        content_bytes = content.encode('utf-8', errors='ignore')
+        seal = hashlib.md5(content_bytes).hexdigest()
+
+        with self._lock:
+            # 1.1. Monotonic Version Check (Causal Guard)
+            # If the client sent a newer version while we were waiting, vaporize this thread.
+            if version < self._last_version_processed.get(norm_uri, -1) and version != 0:
+                return
+
+            # 1.2. Mundane Flux Check (Merkle Guard)
+            # If the content hasn't shifted, do not waste energy on re-analysis.
+            if self._last_merkle_seal.get(norm_uri) == seal and version != 0:
+                self._last_version_processed[norm_uri] = version
+                return
+
+            self._last_version_processed[norm_uri] = version
+            self._last_merkle_seal[norm_uri] = seal
+
+        # [ASCENSION 4]: QUARANTINE CHECK
+        if self._fracture_registry.get(norm_uri, 0) >= MAX_FRACTURE_STRIKES:
+            return  # Silent rejection of cursed files
+
+        trace_id = f"inq-{uuid.uuid4().hex[:6].upper()}"
+        start_time = time.perf_counter()
+
+        # =====================================================================
+        # == MOVEMENT I: THE INTERNAL GAZE (STRATUM-0)                       ==
+        # =====================================================================
+        # [ASCENSION 5]: Immediate Feedback Channel.
+        try:
+            # [ASCENSION 11]: METABOLIC BACKPRESSURE CHECK
+            # If the local CPU is melting, we might downgrade logic (future impl).
+            pressure = self.server.foundry.active_count
+
+            ctx = {
+                "content": content,
+                "file_path": fs_path,
+                "project_root": self.server.project_root,
+                "grammar": "scaffold",
+                "cursor_offset": -1,
+                "telemetry": {"trace_id": trace_id, "start_time": start_time},
+                "engine": self.server.engine,
+                "session_id": self.server._session_id,
+                "is_shadow": norm_uri.startswith("scaffold-shadow:")
+            }
+
+            # [RITE]: LOCAL_PROCESSOR_INVOCATION
+            local_result = self.processor.process(ctx)
+
+            # 2. CAUSAL VERIFICATION (Post-Compute)
+            # Ensure the Architect hasn't willed new matter during the compute cycle.
+            if self.server.documents.get_version(uri) > version and version != 0:
+                return
+
+            # 3. [ASCENSION 7 & 9]: PRIVACY & TRACE SPLICING
+            raw_diags = local_result.get("diagnostics", [])
+            for diag in raw_diags:
+                # Banish plaintext secrets from the UI
+                diag['message'] = PrivacySentinel.redact(diag.get('message', ''))
+                # Suture the trace_id for the Redemption Artisans
+                if 'data' not in diag: diag['data'] = {}
+                diag['data'].update({
+                    "trace_id": trace_id,
+                    "version": version,
+                    "source_stratum": 0
+                })
+
+            # 4. ATOMIC MULTICAST (LOCAL)
+            # Project the findings to the Ocular Eye immediately.
+            self._emit_holographic_data(norm_uri, version, raw_diags, local_result, trace_id)
+
+            # Reset strikes on successful perception
+            self._fracture_registry[norm_uri] = 0
+
+        except Exception as fracture:
+            # [ASCENSION 4]: FRACTURE REGISTRATION
+            self._fracture_registry[norm_uri] = self._fracture_registry.get(norm_uri, 0) + 1
+            forensic_log(f"Optic Fracture ({self._fracture_registry[norm_uri]}): {fs_path.name}", "ERROR", "INQUEST",
+                         trace_id=trace_id)
+
+            if self._fracture_registry[norm_uri] >= MAX_FRACTURE_STRIKES:
+                self.server.log_message(
+                    f"Scripture Quarantine: {fs_path.name} is causing logic-drift. Local analysis suspended.", type=2)
+
+        # =====================================================================
+        # == MOVEMENT II: THE REMOTE GAZE (DELEGATION)                       ==
+        # =====================================================================
+        # [ASCENSION 5]: RELAY-AGNOSTIC TRIGGER
+        # We project the intent into the Adrenaline Conductor.
+        # It handles the "Cold Start" backlog or immediate Silver Cord dispatch.
+        if hasattr(self.server, 'adrenaline') and self.server.adrenaline:
+            # We hand over the versioned intent with the CLEAN URI.
+            self.server.adrenaline.trigger(norm_uri, content, version)
+
+    def _emit_holographic_data(self, uri: str, version: int, diags: List, data: Dict, trace_id: str):
+        """
+        [THE RITE OF PROJECTION]
+        Transmits multi-spectral findings to the Ocular UI.
+        """
+        # [ASCENSION 12]: FINAL PURIFICATION
+        # Ensure the URI sent to the client is absolutely clean.
+        clean_uri = URI_CLEANSER.sub('', uri)
+
+        # A. Beam 1: Heresies (Diagnostics)
+        self.server.endpoint.send_notification("textDocument/publishDiagnostics", {
+            "uri": clean_uri,
+            "version": version,
+            "diagnostics": diags,
+            "_source": "LOCAL_INQUEST"
+        })
+
+        # B. Beam 2: The Mirror (Structural Tree)
+        if "structure" in data:
+            self.server.mirror.project(clean_uri, data["structure"], data.get("ascii_tree", ""), version)
+
+        # C. [ASCENSION 8]: HAPTIC PULSE
+        # If analysis took significant mass, trigger a bloom in the UI
+        latency = (time.perf_counter() - getattr(self.server._ctx, 'start_time', time.perf_counter())) * 1000
+        if latency > HAPTIC_THRESHOLD_MS:
+            self.server.endpoint.send_notification("gnostic/vfx", {
+                "type": "pulse", "uri": clean_uri, "intensity": 0.3
+            })
+
+    def inception_sweep(self):
+        """
+        [ASCENSION 12]: THE RITE OF FIRST SIGHT
+        Synchronizes all open scriptures to warm the Cortex.
+        """
+        open_uris = self.server.documents.open_uris
+        if not open_uris: return
+
+        forensic_log(f"Inception Sweep: Perceiving {len(open_uris)} scriptures.", "RITE", "INQUEST")
+
+        for uri in open_uris:
+            doc = self.server.documents.get(uri)
+            if doc:
+                # Project into the Foundry for non-blocking mass-perception
+                self.server.foundry.submit(
+                    f"sweep-{uuid.uuid4().hex[:4]}",
+                    self.conduct, uri, doc.text, doc.version
+                )
+
+    def quarantine_purge(self, uri: str):
+        """[RITE]: ABSOLUTION - Clears the fracture strikes for a URI."""
+        norm_uri = UriUtils.normalize_uri(uri)
+        with self._lock:
+            self._fracture_registry.pop(norm_uri, None)
+            self._last_merkle_seal.pop(norm_uri, None)
+            self._last_version_processed.pop(norm_uri, None)

velm/core/lsp/scaffold_server/lifecycle.py

@@ -0,0 +1,214 @@
+# Path: core/lsp/scaffold_server/lifecycle.py
+# -------------------------------------------
+# LIF: INFINITY | ROLE: REALITY_CONSECRATOR | RANK: SOVEREIGN
+# auth_code: Ω_LIFECYCLE_TOTALITY_V306_UNSTOPPABLE
+
+import os
+import gc
+import sys
+import uuid
+import time
+import re
+import threading
+import traceback
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# --- IRON CORE UPLINKS ---
+from ..base import forensic_log, ServerState
+from ..base.utils.uri import UriUtils
+from ..base.types import (
+    InitializeParams,
+    InitializeResult,
+    ServerCapabilities,
+    ServerInfo,
+    MessageType,
+    TextDocumentSyncKind
+)
+
+# [ASCENSION 7]: TOKEN PURIFIER
+TOKEN_CLEANSE_RE = re.compile(r'[\s\x00-\x1f\x7f-\xff]')
+
+
+class OracleLifecycle:
+    """
+    =============================================================================
+    == THE ORACLE LIFECYCLE (V-Ω-TOTALITY-V306-UNSTOPPABLE)                    ==
+    =============================================================================
+    The High Priest of Inception. Responsible for the materialization of the
+    Oracle, the negotiation of immutable laws, and the confirmation of Life.
+    =============================================================================
+    """
+
+    def __init__(self, server: Any):
+        self.server = server
+        self.logger = server.logger
+        self._boot_time_ns = time.perf_counter_ns()
+        self._initialized_flag = False
+
+    # =========================================================================
+    # == RITE 1: THE MATERIALIZATION (REQUEST)                               ==
+    # =========================================================================
+
+    def initialize(self, params: Any) -> Dict[str, Any]:
+        """
+        Negotiates the laws of reality with the Ocular UI.
+        """
+        # [ASCENSION 1]: THERMAL RE-ENTRY GUARD
+        with self.server._state_lock:
+            if self.server.state != ServerState.DORMANT:
+                self.logger.warn("Initialization Plea ignored: Essence already manifest.")
+                return self._generate_consecrated_response()
+
+            self.server.state = ServerState.AWAKENING
+
+        # [ASCENSION 2]: AURA TRACE GENESIS
+        trace_id = f"init-{uuid.uuid4().hex[:8].upper()}"
+        forensic_log(f"Oracle Awakening Initiated. Trace: {trace_id}", "RITE", "LIFE", trace_id=trace_id)
+
+        try:
+            # 1. PARSE HANDSHAKE DNA
+            # Transmute raw JSON-RPC dict into a validated Pydantic model
+            # [ASCENSION 3]: MODEL SOVEREIGNTY
+            p = InitializeParams.model_validate(params) if isinstance(params, dict) else params
+
+            # 2. [ASCENSION 4]: ISOMORPHIC ANCHOR PURIFICATION
+            root_uri = getattr(p, 'root_uri', None) or getattr(p, 'rootUri', None)
+            opts = getattr(p, 'initialization_options', {}) or getattr(p, 'initializationOptions', {}) or {}
+
+            # Triage: Prefer rootUri, fallback to projectRoot from options, final fallback CWD
+            uri_to_resolve = root_uri.root if hasattr(root_uri, 'root') else (root_uri or opts.get('projectRoot'))
+
+            if uri_to_resolve:
+                # [THE CURE]: ABSOLUTE PATH RESOLUTION
+                self.server.project_root = UriUtils.to_fs_path(uri_to_resolve)
+
+                # [ASCENSION 6]: ENVIRONMENTAL GRAFTING
+                os.environ["SCAFFOLD_PROJECT_ROOT"] = str(self.server.project_root)
+                if self.server.engine:
+                    self.server.engine.project_root = str(self.server.project_root)
+
+                forensic_log(f"Reality Anchored to Sanctum: {self.server.project_root}", "SUCCESS", "LIFE",
+                             trace_id=trace_id)
+            else:
+                self.server.project_root = Path.cwd().resolve()
+                self.logger.warn("Handshake missing Root URI. Defaulting anchor to CWD.")
+
+            # 3. [ASCENSION 5]: SILVER CORD PRE-WARMING
+            if isinstance(opts, dict):
+                self.server._daemon_port = int(opts.get('daemonPort', 5555))
+
+                # [ASCENSION 7]: AGGRESSIVE TOKEN EXORCISM
+                raw_token = str(opts.get('token', 'VOID'))
+                clean_token = TOKEN_CLEANSE_RE.sub('', raw_token)
+                self.server._daemon_token = clean_token
+
+                if self.server._daemon_token != 'VOID' and self.server._daemon_token != '':
+                    # [ASCENSION 8]: LAZY SKILL AWAKENING
+                    # Fire-and-forget relay ignition
+                    threading.Thread(
+                        target=self.server.relay.ignite,
+                        args=(self.server._daemon_port, self.server._daemon_token),
+                        name="RelayIgniter",
+                        daemon=True
+                    ).start()
+                else:
+                    forensic_log("No Daemon token found. Operating in Standalone (Local) Mode.", "INFO", "LIFE",
+                                 trace_id=trace_id)
+
+            # 4. STORE CLIENT SOUL
+            self.server.client_capabilities = getattr(p, 'capabilities', None)
+
+            # [ASCENSION 9]: FORENSIC PID INSCRIPTION
+            if self.server.project_root and self.server.project_root.exists():
+                # [THE GUARD]: Don't pollute the App Root if something went wrong
+                if self.server.project_root == Path.cwd():
+                    # Unless the project is ACTUALLY the app root (rare)
+                    pass
+
+                try:
+                    debug_dir = self.server.project_root / ".scaffold" / "debug"
+                    # [SAFETY]: Only create if parent exists to avoid deep nesting of errors
+                    if not debug_dir.exists():
+                        debug_dir.mkdir(parents=True, exist_ok=True)
+
+                    (debug_dir / "lsp.pid").write_text(str(os.getpid()))
+                except Exception as e:
+                    self.logger.warn(f"PID Inscription failed: {e}")
+
+            # 5. [ASCENSION 10]: METABOLIC PURGE
+            gc.collect()
+
+            # 6. [ASCENSION 11]: CONSTITUTIONAL PROCLAMATION
+            return self._generate_consecrated_response()
+
+        except Exception as e:
+            # [ASCENSION 12]: CATASTROPHIC AUTOPSY
+            self.logger.critical(f"Inception Fracture: {str(e)}")
+            forensic_log("Catastrophic Inception failure.", "CRIT", "LIFE", exc=e, trace_id=trace_id)
+            return self._generate_fallback_response()
+
+    # =========================================================================
+    # == RITE 2: THE ACTIVATION (NOTIFICATION)                               ==
+    # =========================================================================
+
+    def initialized(self, params: Any = None):
+        """
+        [THE MISSING LINK: RESTORED]
+        Confirming the connection and opening the eyes of the Oracle.
+        """
+        with self.server._state_lock:
+            if self._initialized_flag: return
+            self.server.state = ServerState.ACTIVE
+            self._initialized_flag = True
+
+        # [ASCENSION 3]: CHRONOMETRY
+        total_boot_ms = (time.perf_counter_ns() - self._boot_time_ns) / 1_000_000
+
+        # [ASCENSION 9]: VITALITY BROADCAST
+        self.server.endpoint.send_notification("gnostic/vitality", {
+            "status": "ONLINE",
+            "mode": "FULL_DUPLEX" if self.server._relay_active else "STANDALONE",
+            "boot_ms": round(total_boot_ms, 2),
+            "timestamp": time.time(),
+            "session_id": self.server._session_id
+        })
+
+        # [ASCENSION 10]: INCEPTION SWEEP
+        # Now that we are initialized, force the Inquisitor to gaze at all open files.
+        #if self.server.project_root:
+            #self.server.inquest.inception_sweep()
+
+        forensic_log(f"Singularity active in {total_boot_ms:.2f}ms. Initiating Inception Sweep.", "SUCCESS", "LIFE")
+
+    # =========================================================================
+    # == INTERNAL GNOSIS                                                     ==
+    # =========================================================================
+
+    def _generate_consecrated_response(self) -> Dict[str, Any]:
+        """Forges the high-fidelity constitutional response."""
+        caps = self.server.get_capabilities()
+        result = InitializeResult(
+            capabilities=caps,
+            serverInfo=ServerInfo(
+                name="Scaffold Gnostic Oracle",
+                version="3.2.0-SINGULARITY"
+            )
+        )
+        return result.model_dump(mode='json', by_alias=True, exclude_none=True)
+
+    def _generate_fallback_response(self) -> Dict[str, Any]:
+        """Provides a safe-mode manifest when reality collapses."""
+        return {
+            "capabilities": {
+                "textDocumentSync": 1,
+                "hoverProvider": False,
+                "completionProvider": {"triggerCharacters": ["$"]}
+            },
+            "serverInfo": {
+                "name": "Scaffold Oracle [RECOVERY_MODE]",
+                "version": "3.2.0-FRACTURED"
+            }
+        }
+
+# === SCRIPTURE SEALED: THE LIFECYCLE IS COMPLETE ===

velm/core/lsp/scaffold_server/mirror.py

@@ -0,0 +1,162 @@
+# Path: core/lsp/scaffold_server/mirror.py
+# ----------------------------------------
+# LIF: INFINITY | ROLE: VISUAL_CORTEX | RANK: SOVEREIGN
+# =================================================================================
+# == THE MIRROR PROJECTOR (V-Ω-TOTALITY-V306-TRANSCENDENT)                       ==
+# =================================================================================
+
+import time
+import uuid
+import logging
+import threading
+from typing import List, Dict, Any, Optional, Union
+from pathlib import Path
+
+# --- IRON CORE UPLINKS ---
+from ..base import (
+    forensic_log,
+    UriUtils,
+    ServerState
+)
+
+Logger = logging.getLogger("MirrorProjector")
+
+
+class MirrorProjector:
+    """
+    [THE VISUAL CORTEX]
+    Orchestrates the projection of structural Gnosis to the Ocular UI.
+    Ensures the Mirror (Tree View) is a liquid-smooth reflection of the Architect's will.
+    """
+
+    def __init__(self, server: Any):
+        self.server = server
+
+        # --- [INTERNAL MEMORY STRATA] ---
+        # Map[URI, Version] - Temporal Guard
+        self._last_projected_version: Dict[str, int] = {}
+        # Map[URI, Hash] - Redundancy Filter
+        self._last_projected_hash: Dict[str, str] = {}
+
+        self._lock = threading.RLock()
+
+    def project(self, uri: str, structure: List[Dict[str, Any]], ascii_tree: str = "", version: int = 0):
+        """
+        [THE RITE OF PROJECTION]
+        Transmits the structural hologram to the Ocular UI across the Silver Cord.
+        """
+        # [ASCENSION 2]: GENERATIONAL FLUX FILTER
+        with self._lock:
+            if version < self._last_projected_version.get(uri, -1) and version != 0:
+                # Discard stale reality
+                return
+            self._last_projected_version[uri] = version
+
+        try:
+            # 1. [ASCENSION 1]: ISOMORPHIC URI SYNCHRONIZATION
+            # Force absolute parity with the client's internal coordinate system.
+            norm_uri = UriUtils.normalize_uri(uri)
+            fs_path = UriUtils.to_fs_path(norm_uri)
+
+            # 2. [ASCENSION 3]: RECURSIVE NODE ALCHEMISTRY
+            # Purify the tree matter and ensure no null-pointer heresies reach the React layer.
+            sanitized_structure = self._sanitize_tree(structure)
+
+            # 3. [ASCENSION 9]: LUMINOUS TRACE CORRELATION
+            # Link this projection to the current request context for forensic auditing.
+            trace_id = getattr(self.server._ctx, 'trace_id', f"mir-{uuid.uuid4().hex[:6].upper()}")
+
+            # 4. [ASCENSION 7]: ATOMIC MULTICAST BURST
+            # Combine all perceived facets of the scripture into a single protocol packet.
+            projection_packet = {
+                "uri": norm_uri,
+                "structure": sanitized_structure,
+                "ascii_tree": ascii_tree,
+                "version": version,
+                "meta": {
+                    "timestamp": time.time(),
+                    "trace_id": trace_id,
+                    "latency_ms": self._calculate_latency(),  # [ASCENSION 10]
+                    "is_shadow": norm_uri.startswith("scaffold-shadow:")  # [ASCENSION 8]
+                }
+            }
+
+            # 5. THE PROCLAMATION
+            # Send the Gnostic notification to the Ocular UI.
+            self.server.endpoint.send_notification("scaffold/previewStructure", projection_packet)
+
+            # self.server.logger.debug(f"Mirror Reflected: {fs_path.name} (v{version})", trace_id=trace_id)
+
+        except Exception as fracture:
+            # [ASCENSION 12]: FAULT TOLERANCE
+            forensic_log(f"Mirror Projection Fracture for {uri}: {fracture}", "ERROR", "MIRROR")
+
+    # =============================================================================
+    # == INTERNAL ALCHEMISTRY                                                    ==
+    # =============================================================================
+
+    def _sanitize_tree(self, nodes: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        [ASCENSION 3]: THE NODE ALCHEMIST
+        Recursively ensures every node is valid, named, and iconographically aligned.
+        """
+        if not nodes:
+            return []
+
+        # [ASCENSION 12]: CAUSAL ANCHORING
+        # Promote important files to the top of the collection.
+        def _sort_key(n):
+            name = n.get('name', '').lower()
+            if 'scaffold.scaffold' in name: return 0
+            if 'index.' in name: return 1
+            if n.get('is_dir'): return 2
+            return 3
+
+        sorted_nodes = sorted(nodes, key=_sort_key)
+
+        for node in sorted_nodes:
+            # 1. DIVINE IDENTITY
+            if 'name' not in node or not node['name']:
+                path = node.get('path', 'unknown_node')
+                node['name'] = str(path).split('/')[-1] if path else "AnonymousNode"
+
+            # 2. [ASCENSION 4]: SEMANTIC ICONOGRAPHY
+            # Assign kind codes (1=File, 13=Var, 12=Func, 19=Folder)
+            if 'kind' not in node:
+                if node.get('is_dir'):
+                    node['kind'] = 19
+                elif node['name'].startswith('$$'):
+                    node['kind'] = 13
+                elif node['name'].startswith('@'):
+                    node['kind'] = 12
+                else:
+                    node['kind'] = 1
+
+            # 3. [ASCENSION 6]: ADAPTIVE DETAIL SPLICING
+            # Extract variable values for immediate visibility
+            if 'value' in node and not node.get('detail'):
+                node['detail'] = f"= {node['value']}"
+
+            # 4. [ASCENSION 8]: VOID GUARD
+            # Ensure children is always a manifest list, never a null heresy.
+            if 'children' in node and node['children']:
+                node['children'] = self._sanitize_tree(node['children'])
+            else:
+                node['children'] = []
+
+        return sorted_nodes
+
+    def _calculate_latency(self) -> float:
+        """[ASCENSION 10]: CHRONOMETRIC TELEMETRY."""
+        # Calculate how long since the current request (keystroke) arrived.
+        start = getattr(self.server._ctx, 'start_time', time.perf_counter())
+        return (time.perf_counter() - start) * 1000
+
+    def clear(self, uri: str):
+        """[THE RITE OF ABSOLUTION] Clears the temporal memory for a specific file."""
+        norm_uri = UriUtils.normalize_uri(uri)
+        with self._lock:
+            self._last_projected_version.pop(norm_uri, None)
+            self._last_projected_hash.pop(norm_uri, None)
+
+# === SCRIPTURE SEALED: THE MIRROR IS PURE ===