velm 0.1.2__py3-none-any.whl

velm/core/ignition/conductor.py

@@ -0,0 +1,169 @@
+# Path: scaffold/core/ignition/conductor.py
+# ------------------------------------------
+# LIF: 10,000,000,000,000 // AUTH_CODE: Ω_IGNITION_CONDUCTOR_V1
+# SYSTEM: IDEABOX QUANTUM // ROLE: KINETIC EXECUTION
+
+import os
+import sys
+import subprocess
+import threading
+import time
+import signal
+import psutil
+from pathlib import Path
+from typing import Dict, Optional, List, Callable, Any
+
+from .contracts import ExecutionPlan, VitalityState
+from .sentinel.priest import ToolchainSentinel
+from ...logger import Scribe
+
+Logger = Scribe("IgnitionConductor")
+
+
+class IgnitionConductor:
+    """
+    =================================================================================
+    == THE IGNITION CONDUCTOR (V-Ω-TOTALITY)                                       ==
+    =================================================================================
+    The Sovereign Hand of Action.
+
+    Orchestrates the transition from static code to a living, breathing process.
+    Responsible for Process Lifecycle, Telemetry, and Graceful Banishment.
+    """
+
+    def __init__(self):
+        self._active_processes: Dict[str, subprocess.Popen] = {}
+        self._lock = threading.Lock()
+
+    def ignite(self,
+               plan: ExecutionPlan,
+               on_log: Optional[Callable[[str, str], None]] = None,
+               on_fracture: Optional[Callable[[int, str], None]] = None) -> int:
+        """
+        [ASCENSION 1]: The Rite of Ignition.
+        Manifests the ExecutionPlan in the Operating System.
+        """
+        plan_id = plan.merkle_seal
+
+        with self._lock:
+            if plan_id in self._active_processes:
+                Logger.warn(f"Singularity Conflict: Process {plan_id} already manifest. Banish old soul first.")
+                self.banish(plan_id)
+
+        # 1. BIOLOGICAL READINESS CHECK (The Shield)
+        if plan.support and not plan.support.is_installed:
+            raise RuntimeError(f"Biological Fracture: {plan.support.manifest_type} dependencies missing.")
+
+        # 2. PREPARE KINETIC ENVIRONMENT
+        # [ASCENSION 8]: DNA Grafting
+        env = os.environ.copy()
+        env.update(plan.env)
+
+        # Inject Sentinel-verified paths
+        if plan.support:
+            # Add venv/bin or node_modules/.bin to PATH
+            pass
+
+            # 3. KINETIC SPAWN
+        # [ASCENSION 2]: Group Isolation
+        creation_flags = 0
+        if os.name == 'nt':
+            creation_flags = subprocess.CREATE_NEW_PROCESS_GROUP
+
+        Logger.info(f"Igniting Reality: [bold cyan]{plan.aura.value}[/bold cyan] via {' '.join(plan.command)}")
+
+        try:
+            proc = subprocess.Popen(
+                plan.command,
+                cwd=plan.cwd,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,  # Line buffered
+                creationflags=creation_flags,
+                start_new_session=True if os.name != 'nt' else False
+            )
+
+            self._active_processes[plan_id] = proc
+
+            # 4. AWAKEN TELEMETRIC SCRIBES
+            # [ASCENSION 4]: Splicer Threads
+            threading.Thread(target=self._scribe_stream, args=(proc.stdout, "STDOUT", on_log), daemon=True).start()
+            threading.Thread(target=self._scribe_stream, args=(proc.stderr, "STDERR", on_log), daemon=True).start()
+
+            # 5. ENGAGE VITALITY VIGIL
+            threading.Thread(target=self._vigil_loop, args=(plan_id, proc, on_fracture), daemon=True).start()
+
+            return proc.pid
+
+        except Exception as e:
+            Logger.critical(f"Ignition Fracture: {str(e)}")
+            raise
+
+    def banish(self, plan_id: str):
+        """
+        [ASCENSION 6]: Graceful Banishment.
+        Returns the process and all its children to the void.
+        """
+        with self._lock:
+            proc = self._active_processes.get(plan_id)
+            if not proc: return
+
+            Logger.info(f"Banishing Process Soul: {plan_id} (PID: {proc.pid})")
+
+            try:
+                parent = psutil.Process(proc.pid)
+                children = parent.children(recursive=True)
+
+                # 1. Soft Banish (Terminate)
+                for child in children: child.terminate()
+                parent.terminate()
+
+                # 2. Wait for dissolution
+                _, alive = psutil.wait_procs(children + [parent], timeout=3)
+
+                # 3. Hard Banish (Kill)
+                for survivor in alive:
+                    survivor.kill()
+
+            except psutil.NoSuchProcess:
+                pass
+            finally:
+                self._active_processes.pop(plan_id, None)
+
+    def _scribe_stream(self, stream, name: str, callback: Optional[Callable]):
+        """[ASCENSION 4]: Telemetric Stream Splicer."""
+        for line in iter(stream.readline, ''):
+            clean_line = line.strip()
+            if clean_line:
+                if callback: callback(name, clean_line)
+                # Also log to global scribe
+                Logger.verbose(f"[{name}] {clean_line}")
+        stream.close()
+
+    def _vigil_loop(self, plan_id: str, proc: subprocess.Popen, on_fracture: Optional[Callable]):
+        """[ASCENSION 3]: Vitality Heartbeat Monitoring."""
+        exit_code = proc.wait()
+
+        with self._lock:
+            if plan_id in self._active_processes:
+                self._active_processes.pop(plan_id)
+                Logger.error(f"Reality Fractured: Process {plan_id} exited with code {exit_code}")
+                if on_fracture:
+                    on_fracture(exit_code, "Unexpected Departure")
+
+    def get_status(self, plan_id: str) -> VitalityState:
+        """[ASCENSION 8]: Lifecycle Oracle Query."""
+        with self._lock:
+            proc = self._active_processes.get(plan_id)
+            if not proc: return VitalityState.DORMANT
+
+            if proc.poll() is not None:
+                return VitalityState.FRACTURED
+
+            return VitalityState.ONLINE
+
+
+# [ASCENSION 12]: SOVEREIGN INSTANCE
+Conductor = IgnitionConductor()

velm/core/ignition/contracts.py

@@ -0,0 +1,248 @@
+# Path: scaffold/core/ignition/diviner/contracts.py
+# --------------------------------------------------
+# LIF: 10,000,000,000,000 // AUTH_CODE: Ω_SINGULARITY_CONTRACTS_V12_FINAL
+# SYSTEM: IDEABOX QUANTUM // MODULE: IGNITION.DIVINER
+# -------------------------------------------------------------------------------------
+
+import time
+import uuid
+import hashlib
+from enum import Enum
+from pathlib import Path
+from typing import List, Dict, Optional, Any, Union, Set
+from pydantic import BaseModel, Field, ConfigDict, computed_field, field_validator
+
+
+# =================================================================================
+# == SECTION I: THE GNOSTIC ENUMS (THE NATURE OF REALITY)                        ==
+# =================================================================================
+
+class IgnitionAura(str, Enum):
+    """
+    [ASCENSION 1]: The Expanded Aura Spectrum.
+    Defines the perceived framework 'soul' of the project.
+    """
+    # --- Frontend Realities ---
+    VITE = "vite"
+    NEXT = "next"
+    NUXT = "nuxt"
+    ASTRO = "astro"
+    REMIX = "remix"
+    SVELTE = "svelte"
+    STATIC = "static"
+
+    # --- Python Realities ---
+    FASTAPI = "fastapi"
+    FLASK = "flask"
+    DJANGO = "django"
+    STREAMLIT = "streamlit"
+    GRADIO = "gradio"
+    PYTHON_SCRIPT = "python_script"
+
+    # --- Intelligence Realities (AI) ---
+    LANGCHAIN = "langchain"
+    LLM_AGENT = "llm_agent"
+    JUPYTER = "jupyter"
+
+    # --- Systems Realities ---
+    CARGO = "cargo"
+    GO_MOD = "go_mod"
+    CMAKE = "cmake"
+    MAKEFILE = "makefile"
+
+    # --- Fallbacks ---
+    GENERIC = "generic"
+    SHELL = "shell"
+
+
+class VitalityState(str, Enum):
+    """
+    [ASCENSION 8]: The Lifecycle Oracle.
+    Defines the perceived state of a manifested process.
+    """
+    DORMANT = "dormant"  # Matter exists but is not breathing
+    IGNITING = "igniting"  # Process starting, port not yet bound
+    ONLINE = "online"  # Stable resonance achieved (Port Bound)
+    FRACTURED = "fractured"  # Process crashed or returned error code
+    ZOMBIE = "zombie"  # PID manifest but non-responsive to heartbeat
+    STALE = "stale"  # Running code differs from physical disk matter
+
+
+class Protocol(str, Enum):
+    """[ASCENSION 5]: The sacred tongues of network communication."""
+    HTTP = "http"
+    HTTPS = "https"
+    WSS = "wss"
+    GRPC = "grpc"
+    TCP = "tcp"
+
+
+# =================================================================================
+# == SECTION II: COMPONENTS OF MATTER (SUB-VESSELS)                              ==
+# =================================================================================
+
+class SemanticVersion(BaseModel):
+    """[ASCENSION 7]: Structured temporal identification for toolchains."""
+    major: int = 0
+    minor: int = 0
+    patch: int = 0
+    raw: str = "0.0.0"
+
+    @classmethod
+    def from_str(cls, v_str: str) -> "SemanticVersion":
+        import re
+        match = re.search(r'(\d+)\.(\d+)\.(\d+)', v_str)
+        if match:
+            return cls(major=int(match.group(1)), minor=int(match.group(2)),
+                       patch=int(match.group(3)), raw=v_str)
+        return cls(raw=v_str)
+
+
+class HardwareConstraint(BaseModel):
+    """
+    [ASCENSION 2]: The Physical Cage.
+    Defines the limits of the process's consumption.
+    """
+    model_config = ConfigDict(frozen=True)
+
+    cpu_limit_percent: float = Field(default=50.0, ge=1.0, le=100.0)
+    memory_limit_mb: int = Field(default=1024, ge=128)
+    priority: int = Field(default=10, ge=0, le=20)  # OS Niceness
+
+
+class BiologicalSupport(BaseModel):
+    """
+    [ASCENSION 4]: The dependency tomography vessel.
+    Distinguishes between "Manifest Intent" and "Physical Matter".
+    """
+    model_config = ConfigDict(frozen=True)
+
+    manifest_type: str = Field(..., description="e.g. 'package.json' or 'poetry.lock'")
+    is_installed: bool = False
+    runtime_version: Optional[SemanticVersion] = None
+    missing_elements: List[str] = Field(default_factory=list)
+    suggested_install_cmd: Optional[str] = None
+    lockfile_hash: Optional[str] = None
+
+
+class NetworkPhysics(BaseModel):
+    """[ASCENSION 5]: Frequency and Protocol Resonance."""
+    model_config = ConfigDict(frozen=True)
+
+    port: int = Field(..., ge=0, le=65535)
+    host: str = "127.0.0.1"
+    protocol: Protocol = Protocol.HTTP
+    is_public: bool = False
+
+
+# =================================================================================
+# == SECTION III: THE DIVINE RESULT (THE PROPHECY)                               ==
+# =================================================================================
+
+class HeuristicResonance(BaseModel):
+    """[ASCENSION 1]: A single potential reality discovered by the Bayesian brain."""
+    aura: IgnitionAura
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    reasoning: List[str] = Field(default_factory=list)
+
+
+class ExecutionPlan(BaseModel):
+    """
+    =================================================================================
+    == THE SOVEREIGN EXECUTION PLAN (V-Ω-TOTALITY)                                 ==
+    =================================================================================
+    The definitive contract for bringing code to life.
+    """
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    # --- 1. CORE IDENTITY ---
+    trace_id: str = Field(default_factory=lambda: f"tr-{uuid.uuid4().hex[:8]}")
+    command: List[str] = Field(..., description="Tokenized shell command sequence.")
+    cwd: Path = Field(..., description="The physical anchor root for the process.")
+    aura: IgnitionAura = Field(default=IgnitionAura.GENERIC)
+
+    # --- 2. ENVIRONMENT & PHYSICS ---
+    env: Dict[str, str] = Field(default_factory=dict, description="Redacted environment DNA.")
+    network: NetworkPhysics
+    constraints: HardwareConstraint = Field(default_factory=HardwareConstraint)
+
+    # --- 3. BIOLOGY & TRUST ---
+    support: Optional[BiologicalSupport] = None
+    confidence: float = Field(default=1.0)
+
+    # --- 4. FORENSIC REASONING (ASCENSION 12) ---
+    # The step-by-step chronicle of the Diviner's logic.
+    reasoning_trace: List[str] = Field(default_factory=list)
+
+    # --- 5. TEMPORAL ANCHORS ---
+    divination_timestamp: float = Field(default_factory=time.time)
+
+    @computed_field
+    @property
+    def merkle_seal(self) -> str:
+        """
+        [ASCENSION 3]: The Deterministic Fingerprint.
+        Hashes the entire intent to detect environmental drift.
+        """
+        fingerprint = f"{self.command}{self.cwd}{self.aura}{sorted(self.env.items())}"
+        return hashlib.sha256(fingerprint.encode()).hexdigest()[:16]
+
+    @computed_field
+    @property
+    def ui_hint_color(self) -> str:
+        """[ASCENSION 11]: Chromatic resonance for the React layer."""
+        colors = {
+            IgnitionAura.VITE: "#06b6d4",  # Cyan
+            IgnitionAura.FASTAPI: "#10b981",  # Emerald
+            IgnitionAura.CARGO: "#f97316",  # Orange
+            IgnitionAura.NEXT: "#ffffff",  # White
+            IgnitionAura.STATIC: "#f472b6",  # Pink
+        }
+        return colors.get(self.aura, "#94a3b8")
+
+    @field_validator('cwd', mode='before')
+    @classmethod
+    def _normalize_cwd(cls, v: Any) -> Path:
+        """[ASCENSION 10]: Isomorphic Path Purification."""
+        return Path(v).resolve()
+
+
+class DivinationResult(BaseModel):
+    """
+    =================================================================================
+    == THE BAYESIAN DIVINATION DOSSIER                                             ==
+    =================================================================================
+    The final output of the Diviner Engine.
+    Carries the winning prophecy and the probability cloud.
+    """
+    # The winner of the Bayesian competition
+    winning_plan: ExecutionPlan
+
+    # [ASCENSION 1]: The Probability Distribution
+    alternative_realities: List[HeuristicResonance] = Field(default_factory=list)
+
+    # [ASCENSION 12]: Socratic Feedback Loop
+    requires_architect_intervention: bool = False
+    inquiry_hooks: List[str] = Field(default_factory=list)
+
+    # Telemetry
+    total_divination_ms: float = 0.0
+    logic_heart_path: Path
+
+    @computed_field
+    @property
+    def is_highly_certain(self) -> bool:
+        return self.winning_plan.confidence > 0.85
+
+
+# =================================================================================
+# == SECTION IV: FUSION CORE (POLYGLOT BINDINGS)                                 ==
+# =================================================================================
+
+class FusionBinding(BaseModel):
+    """[ASCENSION 11]: Definitions for cross-runtime logic fusion (e.g., Rust in Py)."""
+    source_lang: str  # rust, go, c
+    binary_path: Path
+    bridge_type: str  # pyo3, maturin, cffi, node-gyp
+    exported_symbols: List[str] = Field(default_factory=list)
+    compilation_flags: Dict[str, Any] = Field(default_factory=dict)

velm/core/ignition/diviner/__init__.py

@@ -0,0 +1,21 @@
+# Path: scaffold/core/ignition/diviner/__init__.py
+# ------------------------------------------------
+# LIF: INFINITY // AUTH_CODE: DIVINER_SINGULARITY_SEAL
+
+"""
+The Diviner Singularity.
+Deterministic reality perception for the Gnostic Forge.
+"""
+
+from .engine import IgnitionDiviner
+from ..contracts import ExecutionPlan, IgnitionAura, BiologicalSupport
+from .exceptions import DivinationHeresy, VoidSanctumError
+
+__all__ = [
+    "IgnitionDiviner",
+    "ExecutionPlan",
+    "IgnitionAura",
+    "BiologicalSupport",
+    "DivinationHeresy",
+    "VoidSanctumError"
+]

velm/core/ignition/diviner/engine.py

@@ -0,0 +1,175 @@
+# Path: scaffold/core/ignition/diviner/engine.py
+# ----------------------------------------------
+# LIF: INFINITY // AUTH_CODE: @)(!@(!()@ // Ω_DIVINER_ENGINE_SINGULARITY
+# SYSTEM: IDEABOX QUANTUM // MODULE: IGNITION.DIVINER
+# -------------------------------------------------------------------------------------
+
+import time
+from pathlib import Path
+from typing import Optional, Union, List, Tuple
+
+# --- THE DIVINE SUMMONS: INTERNAL GNOSTIC CLUSTER ---
+from ..contracts import (
+    ExecutionPlan,
+    IgnitionAura,
+    NetworkPhysics,
+    BiologicalSupport,
+    DivinationResult,
+    HeuristicResonance
+)
+from .seekers import SeekerConductor
+from .heuristics.engine import BayesianBrain
+from .strategies import StrategyArchitect
+from ..sentinel.priest import ToolchainSentinel
+from .persistence import PersistenceMatrix
+from .telemetry import ForensicScribe
+from .exceptions import VoidSanctumError, DivinationHeresy
+
+from ....logger import Scribe
+
+Logger = Scribe("IgnitionEngine")
+
+
+class IgnitionDiviner:
+    """
+    =================================================================================
+    == THE IGNITION DIVINER (ZENITH_APOTHEOSIS_FINAL)                              ==
+    =================================================================================
+    LIF: INFINITY | The 100% Mathematical Certainty Engine.
+
+    The Sovereign Conductor of Inception. This engine unifies the Perception Array,
+    The Bayesian Mind, and the Strategic Hand to materialize code as a living process.
+    =================================================================================
+    """
+
+    def __init__(self):
+        """
+        [ASCENSION 17]: Initialize the internal faculty conduits.
+        The Brain and Scribe are instantiated once to hold state during a rite.
+        """
+        self.brain = BayesianBrain()
+        self.scribe = ForensicScribe()
+
+    def divine(self,
+               path: Union[str, Path],
+               port: int,
+               force_aura: Optional[str] = None,
+               no_cache: bool = False) -> ExecutionPlan:
+        """
+        =============================================================================
+        == THE GRAND RITE OF DIVINATION (V-Ω-TOTALITY)                           ==
+        =============================================================================
+        Performs a full-spectrum tomography of a directory to derive the
+        optimal ExecutionPlan.
+        """
+        self.scribe = ForensicScribe()  # [ASCENSION 9]: Reset the chronicle for a new take
+        root = Path(path).resolve()
+
+        # [ASCENSION 61]: Forensic Capture - Guard the Gateway
+        if not root.exists():
+            raise VoidSanctumError(str(root))
+
+        self.scribe.record(f"Inception initiated at: {root}")
+
+        # --- MOVEMENT I: TEMPORAL RECALL (PERSISTENCE) ---
+        # [ASCENSION 65]: Persistence Matrix Resonance
+        # We attempt to resurrect the previous reality if the Merkle Seal is unbroken.
+        matrix = PersistenceMatrix(root)
+        if not no_cache and not force_aura:
+            cached_data = matrix.recall(root)
+            if cached_data:
+                self.scribe.record("Temporal Resonance achieved: Recalling past Gnosis.")
+                # We validate the cached data against the current contracts
+                return ExecutionPlan.model_validate(cached_data)
+
+        Logger.info(f"Conducting High-Fidelity Tomography: [cyan]{root.name}[/cyan]")
+
+        # --- MOVEMENT II: SPATIAL TOMOGRAPHY (SEEKERS) ---
+        # [ASCENSION 35]: We find the 'Logic Heart' and the 'Visual Seed' using the Seeker pack.
+        conductor = SeekerConductor(root)
+        logic_heart, visual_root = conductor.conduct_tomography()
+
+        # [ASCENSION 7]: Isomorphic Path Resolution
+        # Ensure the heart is expressed relative to the project root for UI clarity
+        self.scribe.record(f"Logic Heart anchored: {logic_heart.relative_to(root) if logic_heart != root else 'ROOT'}")
+
+        # --- MOVEMENT III: CEREBRAL INFERENCE (HEURISTICS) ---
+        # [ASCENSION 52]: The Bayesian brain weighs all indicators from the tomographic heart.
+        aura, confidence = self.brain.judge(logic_heart)
+        self.scribe.record(f"Bayesian Adjudication: {aura.value} ({confidence * 100:.1f}%)")
+
+        # --- MOVEMENT IV: SOCRATIC OVERRIDE & RECONCILIATION ---
+        # [ASCENSION 54]: Respect the Architect's direct will if spoken.
+        if force_aura:
+            try:
+                aura = IgnitionAura(force_aura)
+                confidence = 1.0
+                self.scribe.record(f"Socratic Override: Wavefunction collapsed to {aura}")
+            except ValueError:
+                Logger.warn(f"Heresy: Profane Aura override ignored: {force_aura}")
+
+        # [ASCENSION 18]: VISUAL FALLBACK CASCADE
+        # If logic is silent but matter is dense with HTML, pivot to Ocular Reality.
+        if (aura == IgnitionAura.GENERIC or aura == IgnitionAura.STATIC) and confidence < 0.4:
+            if (visual_root / "index.html").exists():
+                aura = IgnitionAura.STATIC
+                logic_heart = visual_root
+                confidence = 0.7
+                self.scribe.record("Logic Heart silent. Pivoting to Ocular Reality (Static).")
+
+        # --- MOVEMENT V: STRATEGIC FORGING (STRATEGIES) ---
+        # [ASCENSION 58]: Build the immutable execution sequence.
+        # This handles binary resolution (npm.cmd vs npm) and port injection.
+        plan = StrategyArchitect.forge(aura, logic_heart, port)
+        self.scribe.record("Strategic Command Sequence forged.")
+
+        # --- MOVEMENT VI: BIOLOGICAL AUDIT (SENTINEL) ---
+        # [ASCENSION 32]: Verifying that the Lungs (node_modules/venv) are physically manifest.
+        support = ToolchainSentinel.verify_biological_support(logic_heart, aura)
+        self.scribe.record(f"Biological Audit: {'PURE' if support.is_installed else 'FRACTURED'}")
+
+        # --- MOVEMENT VII: FINAL APOTHEOSIS (COMPOSITION) ---
+        # [ASCENSION 96]: Assemble the final result with full decision telemetry.
+        final_plan = plan.model_copy(update={
+            "support": support,
+            "confidence": confidence,
+            "reasoning_trace": self.scribe.finalize() + self.brain.trace
+        })
+
+        # [ASCENSION 72]: Enshrine in the Temporal Vault for zero-latency recall.
+        if not no_cache:
+            matrix.enshrine(root, final_plan)
+
+        # Final Proclamation
+        latency = (time.perf_counter() - self.scribe.start_time) * 1000
+        Logger.success(f"Apotheosis Complete: [bold]{aura.value}[/bold] manifested in {latency:.2f}ms")
+
+        return final_plan
+
+    # =============================================================================
+    # == AUXILIARY RITES                                                         ==
+    # =============================================================================
+
+    def check_infrastructure(self, plan: ExecutionPlan) -> tuple[bool, str]:
+        """
+        [ASCENSION 31]: Performs a live health check on the plan's components.
+        Verifies if the specific toolchain binary is functional.
+        """
+        tool = plan.command[0]
+        exists, path, remedy = ToolchainSentinel.scry_artisan(tool)
+        return exists, remedy
+
+    def generate_dossier(self, plan: ExecutionPlan) -> DivinationResult:
+        """
+        [ASCENSION 1]: Transmutes a plan into a comprehensive Bayesian Dossier.
+        Used by the UI to show alternative realities and confidence intervals.
+        """
+        return DivinationResult(
+            winning_plan=plan,
+            total_divination_ms=(time.time() - plan.divination_timestamp) * 1000,
+            logic_heart_path=plan.cwd
+        )
+
+# [ASCENSION 12]: SOVEREIGN MODULE SEAL
+# The engine is now finalized and immutable.
+

velm/core/ignition/diviner/exceptions.py

@@ -0,0 +1,37 @@
+# Path: scaffold/core/ignition/diviner/exceptions.py
+# --------------------------------------------------
+# LIF: INFINITY // AUTH_CODE: DIVINER_EXCEPTIONS_V2
+
+from ....contracts.heresy_contracts import ArtisanHeresy
+
+class DivinationHeresy(ArtisanHeresy):
+    """Ancestral exception for all reality-perception failures."""
+    def __init__(self, message: str, suggestion: str = None, code: str = "DIV_BASE"):
+        super().__init__(message, suggestion=suggestion, exit_code=1)
+        self.gnostic_code = code
+
+class VoidSanctumError(DivinationHeresy):
+    """Raised when the target path is a non-reality (does not exist)."""
+    def __init__(self, path: str):
+        super().__init__(
+            f"Void Sanctum: Path '{path}' does not exist in the mortal realm.",
+            suggestion="Verify the physical anchor coordinate before initiating divination.",
+            code="DIV_VOID"
+        )
+
+class AmbiguousAuraError(DivinationHeresy):
+    """Raised when the Bayesian score for multiple auras is too close to call."""
+    def __init__(self, auras: list):
+        super().__init__(
+            f"Ambiguous Aura: Multiple realities resonate with equal mass: {auras}",
+            suggestion="Speak a specific 'force_aura' to collapse the wave function.",
+            code="DIV_AMBIGUOUS"
+        )
+
+class LogicHeartFracture(DivinationHeresy):
+    """Raised when a manifest exists but its internal DNA is corrupted."""
+    def __init__(self, manifest: str, detail: str):
+        super().__init__(
+            f"Logic Heart Fracture: {manifest} is profane. {detail}",
+            code="DIV_FRACTURE"
+        )

velm/core/ignition/diviner/heuristics/__init__.py

@@ -0,0 +1,8 @@
+# Path: scaffold/core/ignition/diviner/heuristics/__init__.py
+# ----------------------------------------------------------
+# LIF: INFINITY // AUTH_CODE: Ω_HEURISTIC_GATEWAY_V1
+
+from .engine import BayesianBrain
+from .base import BaseInquisitor
+
+__all__ = ["BayesianBrain", "BaseInquisitor"]

velm/core/ignition/diviner/heuristics/base.py

@@ -0,0 +1,27 @@
+# Path: scaffold/core/ignition/diviner/heuristics/base.py
+# -------------------------------------------------------
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Tuple, List
+from ...contracts import IgnitionAura
+
+
+class BaseInquisitor(ABC):
+    """The Immutable Contract for all Heuristic Perceivers."""
+
+    @abstractmethod
+    def analyze(self, root: Path) -> Tuple[IgnitionAura, float, List[str]]:
+        """
+        Perceives the soul of the directory.
+        Returns: (Aura, Confidence, Reasoning_Trace)
+        """
+        pass
+
+    def read_manifest_safe(self, path: Path, limit: int = 8192) -> str:
+        """Lightweight tomography: Reads only the essential bytes."""
+        try:
+            with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+                return f.read(limit)
+        except:
+            return ""
+