velm 0.1.2__py3-none-any.whl

velm/core/state/ledger.py

@@ -0,0 +1,46 @@
+# Path: scaffold/core/state/ledger.py
+# -----------------------------------
+
+import threading
+from typing import List
+from ...core.state.contracts import LedgerEntry
+
+
+class _GnosticLedger:
+    """The append-only, thread-safe Write-Ahead Log of all mutations."""
+    _instance = None
+    _lock = threading.RLock()
+
+    def __init__(self):
+        self._entries: List[LedgerEntry] = []
+        self._is_active = False
+
+    def begin_rite(self):
+        """Opens the sacred scroll for a new symphony of actions."""
+        with self._lock:
+            self._entries = []
+            self._is_active = True
+
+    def record(self, entry: LedgerEntry):
+        """Inscribes a new Gnostic vow of intent upon the scroll."""
+        with self._lock:
+            if not self._is_active: return
+            self._entries.append(entry)
+
+    def commit_rite(self) -> List[LedgerEntry]:
+        """Seals the scroll, returning its contents and preparing for the next."""
+        with self._lock:
+            committed_entries = self._entries
+            self._entries = []
+            self._is_active = False
+            return committed_entries
+
+    def rollback(self):
+        """Annihilates the current, unsealed scroll in case of heresy."""
+        with self._lock:
+            self._entries = []
+            self._is_active = False
+
+
+# The one true, sacred, and now unambiguously named instance.
+ActiveLedger = _GnosticLedger()

velm/core/state/machine.py

@@ -0,0 +1,25 @@
+# Path: scaffold/core/state/machine.py
+from contextlib import contextmanager
+from .store import Store
+from .ledger import ActiveLedger
+from .contracts import LedgerOperation
+from ...core.state.contracts import LedgerEntry
+
+@contextmanager
+def GnosticRite(rite_name: str, initial_vars: dict):
+    """
+    The one true, sacred context manager for ALL Scaffold operations.
+    It wraps a rite in a transactional, reversible, and state-aware boundary.
+    """
+    try:
+        Store.load_snapshot(initial_vars)
+        ActiveLedger.begin_rite()
+        # The rite is now conducted in the mortal realm.
+        yield
+        # The rite was pure. The Gnosis is committed.
+        ActiveLedger.commit_rite()
+    except Exception:
+        # A heresy was perceived. The Gnosis is reverted.
+        ActiveLedger.rollback()
+        # The heresy is re-proclaimed to the higher realms.
+        raise

velm/core/state/snapshot.py

@@ -0,0 +1,30 @@
+# Path: scaffold/core/state/snapshot.py
+from pathlib import Path
+import json
+from .contracts import GnosticState
+from .store import Store
+
+class GnosticSnapshot:
+    """The Chronomancer. It freezes and thaws reality."""
+
+    @staticmethod
+    def freeze(session_id: str) -> GnosticState:
+        """Perceives the current state and forges an immutable GnosticState vessel."""
+        return GnosticState(
+            session_id=session_id,
+            variables=Store.get_all()
+        )
+
+    @staticmethod
+    def persist(state: GnosticState, path: Path):
+        """Inscribes a frozen reality to a scripture on disk."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(state.model_dump_json(indent=2), encoding='utf-8')
+
+    @staticmethod
+    def thaw(path: Path) -> GnosticState:
+        """Resurrects a reality from a scripture."""
+        if not path.exists():
+            raise FileNotFoundError("Cannot thaw a void.")
+        state_data = json.loads(path.read_text(encoding='utf-8'))
+        return GnosticState(**state_data)

velm/core/state/store.py

@@ -0,0 +1,205 @@
+# Path: scaffold/core/state/store.py
+# ----------------------------------
+# LIF: INFINITY | ROLE: AKASHIC_MEMORY_CONTROLLER | RANK: SOVEREIGN
+# auth_code: Ω_STORE_TOTALITY_V12_SINGULARITY
+
+import threading
+import time
+import logging
+from typing import Any, Dict, List, Optional, Set, Callable, Union, Iterable
+from difflib import get_close_matches
+
+# --- GNOSTIC LOGGING ---
+Logger = logging.getLogger("GnosticStore")
+
+
+class _GnosticStore:
+    """
+    =================================================================================
+    == THE GNOSTIC STORE (V-Ω-TOTALITY-V12-ASCENDED)                               ==
+    =================================================================================
+    The Sovereign God-Engine for memory management. It serves as the single source
+    of truth for all variables, states, and alchemical constants in the Cosmos.
+    """
+
+    def __init__(self):
+        # The variables container
+        self._variables: Dict[str, Any] = {}
+        # Metadata storage for forensic audit
+        self._meta: Dict[str, Dict[str, Any]] = {}
+        # Subscribers for the Observer pattern
+        self._subscribers: List[Callable[[str, Any], None]] = []
+
+        # [ASCENSION 12]: Re-entrant lock for high-concurrency safety
+        self._lock = threading.RLock()
+
+        # Start the clock
+        self._birth_ts = time.time()
+
+    # =============================================================================
+    # == I. INSCRIPTION RITES (WRITING)                                          ==
+    # =============================================================================
+
+    def set(self, key: str, value: Any, cast_as: Optional[type] = None):
+        """
+        [THE RITE OF INSCRIPTION]
+        Inscribes a unit of data into the memory.
+        """
+        with self._lock:
+            # [ASCENSION 5]: Type-Strict Inscription
+            if cast_as:
+                try:
+                    value = cast_as(value)
+                except (ValueError, TypeError) as e:
+                    Logger.error(f"Type Heresy: Cannot cast {key} to {cast_as}. {e}")
+
+            # [ASCENSION 6]: Metadata Scribing
+            is_new = key not in self._variables
+            self._variables[key] = value
+
+            self._meta[key] = {
+                "last_modified": time.time(),
+                "mutation_count": self._meta.get(key, {}).get("mutation_count", 0) + 1,
+                "is_system": key.startswith("scaffold_")
+            }
+
+            # [ASCENSION 4]: Notify the faithful
+            self._notify(key, value)
+
+    def update(self, data: Dict[str, Any]):
+        """[RITE]: BULK_REALITY_MERGE"""
+        with self._lock:
+            for k, v in data.items():
+                self.set(k, v)
+
+    def remove(self, key: str):
+        """[RITE]: ANNIHILATION"""
+        with self._lock:
+            if key in self._variables:
+                del self._variables[key]
+                del self._meta[key]
+                self._notify(key, None)
+
+    def clear(self):
+        """[RITE]: TABULA_RASA"""
+        with self._lock:
+            self._variables.clear()
+            self._meta.clear()
+            Logger.warning("Gnostic Memory has returned to the Void.")
+
+    # =============================================================================
+    # == II. PERCEPTION RITES (READING)                                          ==
+    # =============================================================================
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        [THE RITE OF PERCEPTION]
+        Retrieves a variable. Handles recursive pointers natively.
+        """
+        with self._lock:
+            val = self._variables.get(key, default)
+
+            # [ASCENSION 10]: Pointer Unwinding
+            # If the value is another key reference (e.g. "$$ other_var")
+            if isinstance(val, str) and val.startswith("$$"):
+                ptr = val.replace("$$", "").strip()
+                return self.get(ptr, default)
+
+            return val
+
+    def get_all(self, include_hidden: bool = False) -> Dict[str, Any]:
+        """[RITE]: TOTAL_RECALL"""
+        with self._lock:
+            if include_hidden:
+                return self._variables.copy()
+            # [ASCENSION 7]: Namespace Partitioning
+            return {k: v for k, v in self._variables.items() if not k.startswith("_")}
+
+    def has(self, key: str) -> bool:
+        """[THE GAZE OF EXISTENCE]"""
+        with self._lock:
+            return key in self._variables
+
+    def __contains__(self, key: str) -> bool:
+        return self.has(key)
+
+    def all_keys(self) -> Set[str]:
+        """
+        =========================================================================
+        == [ASCENSION 1]: THE KEY ORACLE (FIX)                                 ==
+        =========================================================================
+        Returns the absolute set of all manifest identifiers.
+        """
+        with self._lock:
+            return set(self._variables.keys())
+
+    # =============================================================================
+    # == III. DIVINATION RITES (DISCOVERY)                                       ==
+    # =============================================================================
+
+    def search(self, query: str, limit: int = 5, cutoff: float = 0.6) -> List[str]:
+        """
+        [THE FUZZY ORACLE]
+        Finds keys similar to the query string using Levenshtein physics.
+        """
+        with self._lock:
+            return get_close_matches(query, self._variables.keys(), n=limit, cutoff=cutoff)
+
+    def get_metadata(self, key: str) -> Optional[Dict[str, Any]]:
+        """[THE FORENSIC RECORD]"""
+        with self._lock:
+            return self._meta.get(key)
+
+    # =============================================================================
+    # == IV. LATTICE RITES (INTEGRATION)                                         ==
+    # =============================================================================
+
+    def subscribe(self, callback: Callable[[str, Any], None]):
+        """[THE COVENANT OF THE OBSERVER]"""
+        with self._lock:
+            self._subscribers.append(callback)
+
+    def _notify(self, key: str, value: Any):
+        """[INTERNAL BROADCAST]"""
+        for callback in self._subscribers:
+            try:
+                callback(key, value)
+            except Exception as e:
+                pass  # Prevent fractured listeners from killing the store
+
+    def load_snapshot(self, state: Dict[str, Any]):
+        """[RITE]: RESURRECTION"""
+        with self._lock:
+            self.clear()
+            self.update(state)
+
+    def capture_snapshot(self) -> Dict[str, Any]:
+        """[RITE]: IMMUTABLE_FREEZE"""
+        return self.get_all(include_hidden=True)
+
+    def __iter__(self) -> Iterable[str]:
+        """[ASCENSION 10]: Safe Iteration"""
+        with self._lock:
+            keys = list(self._variables.keys())
+        for key in keys:
+            yield key
+
+    @property
+    def vitals(self) -> Dict[str, Any]:
+        """[THE PULSE]"""
+        with self._lock:
+            return {
+                "uptime": time.time() - self._birth_ts,
+                "variable_count": len(self._variables),
+                "subscriber_count": len(self._subscribers),
+                "total_mutations": sum(m["mutation_count"] for m in self._meta.values())
+            }
+
+
+# =============================================================================
+# == THE SOVEREIGN INSTANCE                                                  ==
+# =============================================================================
+# The one true, sacred instance of the Gnostic Memory.
+Store = _GnosticStore()
+
+# === SCRIPTURE SEALED: THE MEMORY IS TITANIUM ===

velm/core/structure_sentinel/__init__.py

@@ -0,0 +1,15 @@
+# scaffold/artisans/translocate_core/conductor/structure_sentinel/__init__.py
+
+"""
+=================================================================================
+== THE SACRED GATEWAY TO THE SENTINEL'S SANCTUM (V-Ω-ETERNAL-FACADE)           ==
+=================================================================================
+This scripture is the one true, public gateway to the God-Engine of Structural
+Consecration. It proclaims the existence of the sovereign `StructureSentinel` to the
+cosmos, while shielding the divine pantheon of specialist guardians within from
+profane access. It is the Gnostic Firewall of Architectural Integrity.
+=================================================================================
+"""
+from .facade import StructureSentinel
+
+__all__ = ["StructureSentinel"]

velm/core/structure_sentinel/contracts.py

@@ -0,0 +1,24 @@
+# scaffold/artisans/translocate_core/conductor/structure_sentinel/contracts.py
+
+from pathlib import Path
+from typing import Protocol, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..kernel.transaction import GnosticTransaction
+
+class StructureStrategy(Protocol):
+    """
+    =============================================================================
+    == THE SACRED CONTRACT OF STRUCTURAL LAW (V-Ω-INTERFACE)                   ==
+    =============================================================================
+    This is the divine, unbreakable contract for a language-specific Guardian.
+    It defines the one true rite all Guardians must be able to perform: the Rite
+    of Consecration.
+    """
+    def consecrate(self, file_path: Path, project_root: Path, transaction: Optional["GnosticTransaction"]) -> None:
+        """
+        Performs the Rite of Consecration. The Guardian gazes upon the sanctums
+        housing the `file_path` and ensures they are structurally pure according
+        to the laws of its language.
+        """
+        ...

velm/core/structure_sentinel/facade.py

@@ -0,0 +1,84 @@
+# Path: scaffold/artisans/translocate_core/conductor/structure_sentinel/facade.py
+# -------------------------------------------------------------------------------
+
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING, List
+from ...logger import Scribe
+from .strategies import STRATEGY_REGISTRY
+from .contracts import StructureStrategy
+
+if TYPE_CHECKING:
+    from ..kernel.transaction import GnosticTransaction
+
+Logger = Scribe("StructureSentinel")
+
+
+class StructureSentinel:
+    """
+    =================================================================================
+    == THE SENTINEL OF STRUCTURE (V-Ω-CONTEXT-AWARE-LOGGING)                       ==
+    =================================================================================
+    The divine Guardian of Architectural Integrity.
+    Now capable of perceiving the soul of a directory to choose the correct law.
+    """
+
+    def __init__(self, project_root: Path, transaction: Optional["GnosticTransaction"] = None):
+        self.project_root = project_root
+        self.transaction = transaction
+        self.strategies = STRATEGY_REGISTRY
+        Logger.verbose(f"Structure Sentinel initialized. Strategies: {list(self.strategies.keys())}")
+
+    def ensure_structure(self, path: Path):
+        """
+        The Rite of Consecration.
+        """
+        Logger.info(f"Sentinel gazing upon: [cyan]{path.name}[/cyan]")
+
+        strategies_to_invoke = []
+
+        if path.is_dir():
+            # [THE FIX] Directory Inference
+            # We peek inside to see what language this sanctum speaks.
+            strategies_to_invoke = self._divine_strategies_from_dir(path)
+            if not strategies_to_invoke:
+                Logger.verbose(f"   -> No known language signatures found in directory '{path.name}'.")
+        else:
+            # File Inference (Extension)
+            ext = path.suffix.lower()
+            if ext in self.strategies:
+                strategies_to_invoke.append(self.strategies[ext])
+            else:
+                Logger.verbose(f"   -> No strategy found for extension '{ext}'.")
+
+        if not strategies_to_invoke:
+            return
+
+        for strategy in strategies_to_invoke:
+            try:
+                Logger.info(f"   -> Invoking {strategy.__class__.__name__}...")
+                strategy.consecrate(path, self.project_root, self.transaction)
+            except Exception as e:
+                Logger.warn(f"Structural Consecration failed for '{path}': {e}")
+
+    def _divine_strategies_from_dir(self, directory: Path) -> List[StructureStrategy]:
+        """Scans a directory to determine which strategies apply."""
+        found_strategies = []
+        # Heuristic: Check files inside to guess language
+        try:
+            # We look for common markers
+            has_py = any(f.suffix == '.py' for f in directory.iterdir())
+            has_rs = any(f.suffix == '.rs' for f in directory.iterdir())
+            has_js = any(f.suffix in ('.js', '.ts', '.tsx', '.jsx') for f in directory.iterdir())
+
+            if has_py and '.py' in self.strategies:
+                found_strategies.append(self.strategies['.py'])
+            if has_rs and '.rs' in self.strategies:
+                found_strategies.append(self.strategies['.rs'])
+            if has_js:
+                # Add JS strategy if needed (currently mapped to boundary checks)
+                pass
+
+        except Exception as e:
+            Logger.warn(f"Could not gaze into directory '{directory.name}': {e}")
+
+        return found_strategies

velm/core/structure_sentinel/strategies/__init__.py

@@ -0,0 +1,38 @@
+# Path: scaffold/artisans/translocate_core/conductor/structure_sentinel/strategies/__init__.py
+# --------------------------------------------------------------------------------------------
+
+"""
+=================================================================================
+== THE LIVING PANTHEON OF GUARDIANS (V-Ω-AUTO-REGISTERING)                     ==
+=================================================================================
+"""
+from typing import Dict
+from ..contracts import StructureStrategy
+from .python_strategy import PythonStructureStrategy
+from .rust_strategy import RustStructureStrategy
+from .boundary_strategy import BoundaryCheckStrategy
+from .typescript_strategy import TypeScriptStructureStrategy
+from .javascript_strategy import JavaScriptStructureStrategy
+from .go_strategy import GoStructureStrategy
+from .java_strategy import JavaStructureStrategy
+from .cpp_strategy import CppStructureStrategy
+from .ruby_strategy import RubyStructureStrategy  # <--- THE FINAL GEM
+
+# The one true, unified registry of all known structural laws.
+STRATEGY_REGISTRY: Dict[str, StructureStrategy] = {
+    # Active Guardians (Creators & Weavers)
+    ".py": PythonStructureStrategy(),
+    ".rs": RustStructureStrategy(),
+    ".go": GoStructureStrategy(),
+    ".java": JavaStructureStrategy(),
+    ".cpp": CppStructureStrategy(),
+    ".hpp": CppStructureStrategy(),
+    ".h": CppStructureStrategy(),
+    ".rb": RubyStructureStrategy(), # <--- ACTIVATED
+
+    # Node Guardians (Barrel Weavers)
+    ".ts": TypeScriptStructureStrategy(),
+    ".tsx": TypeScriptStructureStrategy(),
+    ".js": JavaScriptStructureStrategy(),
+    ".jsx": JavaScriptStructureStrategy(),
+}

velm/core/structure_sentinel/strategies/base_strategy.py

@@ -0,0 +1,17 @@
+# scaffold/artisans/translocate_core/conductor/structure_sentinel/strategies/base_strategy.py
+
+from abc import ABC
+from ..contracts import StructureStrategy
+from ....logger import Scribe
+
+class BaseStrategy(ABC, StructureStrategy):
+    """
+    =============================================================================
+    == THE ANCESTRAL SOUL OF THE GUARDIANS                                     ==
+    =============================================================================
+    The abstract ancestor for all specialist structural guardians. It provides a
+    common Gnostic root and a luminous voice (Logger).
+    """
+    def __init__(self, language_name: str):
+        self.language_name = language_name
+        self.logger = Scribe(f"{language_name.title()}StructureGuardian")

velm/core/structure_sentinel/strategies/boundary_strategy.py

@@ -0,0 +1,59 @@
+# Path: scaffold/artisans/translocate_core/conductor/structure_sentinel/strategies/boundary_strategy.py
+# -----------------------------------------------------------------------------------------------------
+
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+from .base_strategy import BaseStrategy
+
+if TYPE_CHECKING:
+    from ....core.kernel.transaction import GnosticTransaction
+
+
+class BoundaryCheckStrategy(BaseStrategy):
+    """
+    =============================================================================
+    == THE BOUNDARY GUARDIAN (V-Ω-GENERIC-SENTINEL)                            ==
+    =============================================================================
+    For languages that define their cosmos via a root-level manifest, this
+    Guardian does not write files. Instead, it gazes upwards from a new scripture,
+    ensuring it can perceive the project's sacred manifest. If not, it proclaims
+    a heresy of orphanage.
+    """
+
+    def __init__(self, language_name: str, manifest_file: str):
+        super().__init__(language_name)
+        self.manifest_file = manifest_file
+
+    def consecrate(self, file_path: Path, project_root: Path, transaction: Optional["GnosticTransaction"]) -> None:
+        # [THE FIX] Handle directory targets correctly
+        if file_path.is_dir():
+            current = file_path
+        else:
+            current = file_path.parent
+
+        found_manifest = False
+
+        # Search upwards
+        while current.is_relative_to(project_root) or current == project_root:
+            manifest = current / self.manifest_file
+
+            physical_exists = manifest.exists()
+            virtual_exists = False
+            if transaction:
+                try:
+                    staged = transaction.get_staging_path(manifest.relative_to(project_root))
+                    virtual_exists = staged.exists()
+                except ValueError:
+                    pass
+
+            if physical_exists or virtual_exists:
+                found_manifest = True
+                break
+
+            if current == current.parent: break
+            current = current.parent
+
+        if not found_manifest:
+            # We warn, but do not halt. The Architect may be forging a new world.
+            self.logger.warn(
+                f"Structural Heresy: {self.language_name} file '{file_path.name}' is orphaned outside a '{self.manifest_file}' sanctum.")

velm/core/structure_sentinel/strategies/cpp_strategy.py

@@ -0,0 +1,115 @@
+# Path: scaffold/artisans/translocate_core/conductor/structure_sentinel/strategies/cpp_strategy.py
+# ------------------------------------------------------------------------------------------------
+
+import re
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+from .base_strategy import BaseStrategy
+from ....utils import atomic_write
+
+if TYPE_CHECKING:
+    from ....core.kernel.transaction import GnosticTransaction
+
+
+class CppStructureStrategy(BaseStrategy):
+    """
+    =============================================================================
+    == THE C++ MASON (V-Ω-HEADER-GUARD-WEAVER)                                 ==
+    =============================================================================
+    The Guardian of the C/C++ Cosmos.
+    1. Enforces Include Guards (`#pragma once` or `#ifndef`) in headers.
+    2. Suggests CMake registration for new implementation files.
+    """
+
+    def __init__(self):
+        super().__init__("C++")
+
+    def consecrate(self, file_path: Path, project_root: Path, transaction: Optional["GnosticTransaction"]) -> None:
+        if file_path.is_dir(): return
+
+        ext = file_path.suffix.lower()
+
+        # 1. Header Guard Enforcement
+        if ext in ('.h', '.hpp', '.hh', '.hxx'):
+            self._enforce_header_guard(file_path, project_root, transaction)
+
+        # 2. CMake Awareness (Passive Log)
+        if ext in ('.cpp', '.c', '.cc', '.cxx'):
+            self._check_cmake_registration(file_path, project_root, transaction)
+
+    def _enforce_header_guard(self, file_path: Path, root: Path, tx):
+        content = self._read_content(file_path, root, tx)
+        if not content: return
+
+        # Check for #pragma once
+        if "#pragma once" in content:
+            return
+
+        # Check for standard ifndef guard
+        guard_name = self._forge_guard_name(file_path, root)
+        if f"#ifndef {guard_name}" in content:
+            return
+
+        # Inject #pragma once (Modern Convention)
+        self.logger.info(f"   -> Injecting '#pragma once' into {file_path.name}")
+        new_content = f"#pragma once\n\n{content}"
+        self._write_file(file_path, new_content, root, tx)
+
+    def _forge_guard_name(self, path: Path, root: Path) -> str:
+        """Forges a unique guard name like PROJECT_SRC_UTILS_H"""
+        try:
+            rel = path.relative_to(root)
+            slug = str(rel).upper().replace("/", "_").replace("\\", "_").replace(".", "_")
+            return slug
+        except ValueError:
+            return path.name.upper().replace(".", "_")
+
+    def _check_cmake_registration(self, file_path: Path, root: Path, tx):
+        """
+        Walks up to find CMakeLists.txt and warns if the file might be orphaned.
+        Does not auto-edit CMakeLists as that is a high-entropy operation.
+        """
+        current = file_path.parent
+        found_cmake = False
+        while current.is_relative_to(root) or current == root:
+            cmake = current / "CMakeLists.txt"
+
+            # Check physical or virtual existence
+            if cmake.exists():
+                found_cmake = True
+            elif tx:
+                try:
+                    if tx.get_staging_path(cmake.relative_to(root)).exists(): found_cmake = True
+                except:
+                    pass
+
+            if found_cmake:
+                # We found the build manifest.
+                # In a future ascension, we could grep it for the filename.
+                break
+
+            if current == current.parent: break
+            current = current.parent
+
+        if not found_cmake:
+            self.logger.verbose(f"   -> Note: No CMakeLists.txt found in parent hierarchy for '{file_path.name}'.")
+
+    # ... Helper methods ...
+    def _read_content(self, path: Path, root: Path, tx) -> str:
+        if tx:
+            try:
+                staged = tx.get_staging_path(path.relative_to(root))
+                if staged.exists(): return staged.read_text('utf-8')
+            except:
+                pass
+        if path.exists(): return path.read_text('utf-8')
+        return ""
+
+    def _write_file(self, path: Path, content: str, root: Path, tx):
+        res = atomic_write(path, content, self.logger, root, transaction=tx, verbose=False)
+        if tx and res.success:
+            try:
+                res.path = path.relative_to(root)
+                tx.record(res)
+            except:
+                pass