clm-kernel 0.0.0__py3-none-any.whl

clm/layer2/engine/sqlite_engine.py

@@ -0,0 +1,518 @@
+import logging
+import sqlite3
+
+from clm.cross_cutting.config.settings import settings
+from clm.layer0.model.card import MCard
+from clm.layer0.model.pagination import Page
+from clm.layer2.engine.abstract_sql_engine import AbstractSqlEngine
+from clm.layer2.engine.base import DatabaseConnection, resolve_db_path
+
+# DEFAULT_PAGE_SIZE is used in function signatures, so we fetch it once or define a local constant
+# However, usually we can access settings.pagination.default_page_size if it's constant.
+# For function signatures, we can't use dynamic properties easily if they change.
+# But settings are generally static after init.
+# To avoid "argument default is mutable" or weirdness, we can grab the value.
+DEFAULT_PAGE_SIZE = settings.pagination.default_page_size
+
+logger = logging.getLogger(__name__)
+
+
+class SQLiteConnection(DatabaseConnection):
+    """Database connection for SQLite.
+
+    The schema is loaded exclusively from the canonical SQL files via the
+    ``MCardSchema`` singleton.  No hardcoded CREATE TABLE statements should
+    appear in this file.
+    """
+
+    # =====================================================================
+    # Single Source of Truth: Schema files
+    # =====================================================================
+    # The SQLite engine does NOT define its own schema.  It loads all
+    # table / index definitions from the canonical SQL files via the
+    # MCardSchema singleton.
+    #
+    # Canonical source files:
+    #   schema/mcard_schema.sql         (REQUIRED -- core tables)
+    #   schema/mcard_vector_schema.sql  (optional -- vector/graph tables)
+    #
+    # If a new table is added to either file, this engine picks it up
+    # automatically.  No hardcoded CREATE TABLE statements should ever
+    # appear in this file.
+    # =====================================================================
+
+    SCHEMA_SOURCE_FILES = (
+        "schema/mcard_schema.sql",  # Required -- core tables
+        "schema/mcard_vector_schema.sql",  # Optional -- vector/graph tables
+    )
+
+    def __init__(self, db_path: str):
+        self.db_path = resolve_db_path(db_path)
+        self.conn: sqlite3.Connection | None = None
+
+    def connect(self):
+        """Open the SQLite connection and initialise schema if the DB is empty.
+
+        All schema definitions are loaded from the canonical SQL files via
+        ``MCardSchema.init_all_tables(conn)``.  No CREATE TABLE statements
+        are hardcoded in this method.
+
+        Raises:
+            FileNotFoundError: if the required core schema SQL file is missing.
+        """
+        logger.debug(f"Connecting to database at {self.db_path}")
+        try:
+            self.conn = sqlite3.connect(self.db_path, check_same_thread=False)
+            # Set busy_timeout to match TypeScript SqliteNodeEngine parity
+            from clm.cross_cutting.config.config_constants import SQLITE_BUSY_TIMEOUT_MS
+
+            self.conn.execute(f"PRAGMA busy_timeout = {SQLITE_BUSY_TIMEOUT_MS}")
+            if self.db_path != ":memory:" and not self.db_path.startswith(
+                "file::memory:"
+            ):
+                self.conn.execute("PRAGMA journal_mode = WAL")
+                self.conn.execute("PRAGMA synchronous = NORMAL")
+            else:
+                self.conn.execute("PRAGMA journal_mode = DELETE")
+            logger.debug(f"Connection established to {self.db_path}")
+
+            # Check if the database is empty and initialize schema if necessary
+            cursor = self.conn.cursor()
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='card'"
+            )
+
+            if not cursor.fetchone():
+                logger.debug(f"Creating new database schema at {self.db_path}")
+
+                from clm.schemas import MCardSchema
+
+                logger.debug("SQLite schema loading from canonical source")
+
+                schema = MCardSchema.get_instance()
+
+                # Initialize ALL tables from canonical SQL files
+                count = schema.init_all_tables(self.conn)
+                logger.debug(
+                    f"Database schema created successfully "
+                    f"({count} statements executed from canonical SQL files)"
+                )
+
+            else:
+                logger.debug(f"Using existing database at {self.db_path}")
+
+        except sqlite3.Error as e:
+            logger.error(
+                f"Database error connecting to {self.db_path}: {e}", exc_info=True
+            )
+            raise
+
+    def disconnect(self):
+        if self.conn:
+            self.conn.close()
+            self.conn = None
+
+    def commit(self):
+        if self.conn:
+            self.conn.commit()
+
+    def rollback(self):
+        if self.conn:
+            self.conn.rollback()
+
+
+class SQLiteEngine(AbstractSqlEngine):
+    def __init__(self, connection: SQLiteConnection):
+        self.connection = connection
+        self.connection.connect()
+
+    def __del__(self):
+        self.connection.disconnect()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, _exc_tb):
+        self.connection.disconnect()
+        return False
+
+    # =====================================================================
+    # AbstractSqlEngine primitives
+    # =====================================================================
+
+    def _query_rows(self, sql: str, params: tuple = ()) -> list[dict]:
+        cursor = self.connection.conn.cursor()
+        cursor.execute(sql, params)
+        columns = [desc[0] for desc in cursor.description] if cursor.description else []
+        return [dict(zip(columns, row, strict=False)) for row in cursor.fetchall()]
+
+    def _exec_sql(self, sql: str, params: tuple = ()) -> int:
+        import time
+
+        max_retries = 5
+        base_delay = 0.01
+        for attempt in range(max_retries):
+            try:
+                cursor = self.connection.conn.cursor()
+                cursor.execute(sql, params)
+                self.connection.commit()
+                return cursor.rowcount
+            except sqlite3.OperationalError as e:
+                if (
+                    "locked" in str(e).lower() or "busy" in str(e).lower()
+                ) and attempt < max_retries - 1:
+                    time.sleep(base_delay * (2**attempt))
+                    continue
+                raise
+
+    def _ensure_handle_tables(self) -> None:
+        """Ensure the handle_registry and handle_history tables exist.
+
+        Uses the MCardSchema singleton to load table definitions from
+        the canonical SQL files.
+        """
+        from clm.schemas import MCardSchema
+
+        schema = MCardSchema.get_instance()
+        cursor = self.connection.conn.cursor()
+        cursor.execute(schema.get_table("handle_registry"))
+        cursor.execute(schema.get_table("handle_history"))
+        cursor.execute(schema.get_index("idx_handle_current_hash"))
+        self.connection.commit()
+        logger.debug("Handle tables ensured.")
+
+    def _ensure_tombstone_table(self) -> None:
+        """Ensure the card_tombstone table exists."""
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS card_tombstone (
+                hash TEXT PRIMARY KEY,
+                tombstoned_at TEXT NOT NULL,
+                reason TEXT DEFAULT 'DELETED',
+                FOREIGN KEY (hash) REFERENCES card(hash)
+            )
+            """
+        )
+        self.connection.commit()
+
+    # =====================================================================
+    # Card Operations (engine-specific)
+    # =====================================================================
+
+    def add(self, card: MCard) -> str:
+        import time
+
+        hash_value = str(card.hash)
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+
+        # If previously tombstoned, untombstone to restore availability
+        cursor.execute("SELECT 1 FROM card_tombstone WHERE hash = ?", (hash_value,))
+        if cursor.fetchone():
+            cursor.execute("DELETE FROM card_tombstone WHERE hash = ?", (hash_value,))
+            self.connection.commit()
+            logger.debug(f"Re-activated previously tombstoned card {hash_value}")
+            return hash_value
+
+        max_retries = 5
+        base_delay = 0.01
+        for attempt in range(max_retries):
+            try:
+                # Ensure content is bytes
+                content_bytes = (
+                    card.content
+                    if isinstance(card.content, bytes)
+                    else card.content.encode("utf-8")
+                )
+                cursor.execute(
+                    "INSERT INTO card (hash, content, g_time) VALUES (?, ?, ?)",
+                    (hash_value, content_bytes, str(card.g_time)),
+                )
+                self.connection.commit()
+                logger.debug(f"Added card with hash {hash_value}")
+                return hash_value
+            except sqlite3.OperationalError as e:
+                if (
+                    "locked" in str(e).lower() or "busy" in str(e).lower()
+                ) and attempt < max_retries - 1:
+                    time.sleep(base_delay * (2**attempt))
+                    continue
+                raise
+            except sqlite3.IntegrityError as e:
+                raise ValueError(
+                    f"Card with hash {hash_value} and {str(card.g_time)} already exists, \n Content: {card.content[:20]}"
+                ) from e
+
+    def get(self, hash_value: str) -> MCard | None:
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            SELECT c.content, c.g_time, c.hash
+            FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE c.hash = ? AND t.hash IS NULL
+            """,
+            (str(hash_value),),
+        )
+        row = cursor.fetchone()
+
+        if not row:
+            return None
+
+        content, g_time, hash_val = row
+        return self._row_to_card(content, hash_val, g_time)
+
+    def delete(self, hash_value: str) -> bool:
+        """Tombstones a card to preserve G-Set CRDT immortality (INV-REF-03).
+
+        No row is deleted from the `card` CAS table. Instead, a tombstone is recorded
+        in `card_tombstone`, and associated handles are dereferenced with a TOMBSTONE
+        audit entry written to `handle_history`.
+        """
+        from datetime import datetime, timezone
+
+        cursor = self.connection.conn.cursor()
+        cursor.execute("SELECT 1 FROM card WHERE hash = ?", (str(hash_value),))
+        if not cursor.fetchone():
+            return False
+
+        self._ensure_tombstone_table()
+        cursor.execute(
+            "SELECT 1 FROM card_tombstone WHERE hash = ?", (str(hash_value),)
+        )
+        if cursor.fetchone():
+            return False
+
+        now = datetime.now(timezone.utc).isoformat()
+        cursor.execute(
+            "INSERT OR IGNORE INTO card_tombstone (hash, tombstoned_at, reason) VALUES (?, ?, 'DELETED')",
+            (str(hash_value), now),
+        )
+
+        self._ensure_handle_tables()
+        cursor.execute(
+            "SELECT handle FROM handle_registry WHERE current_hash = ?",
+            (str(hash_value),),
+        )
+        handles = [row[0] for row in cursor.fetchall()]
+        for handle in handles:
+            cursor.execute(
+                "INSERT INTO handle_history (handle, previous_hash, changed_at, change_type) VALUES (?, ?, ?, 'TOMBSTONE')",
+                (handle, str(hash_value), now),
+            )
+            cursor.execute("DELETE FROM handle_registry WHERE handle = ?", (handle,))
+
+        self.connection.commit()
+        return True
+
+    def search_by_string(
+        self,
+        search_string: str,
+        page_number: int = 1,
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> Page:
+        """Search for cards by string in content, hash, or g_time"""
+        if page_number < 1:
+            raise ValueError("Page number must be >= 1")
+        if page_size < 1:
+            raise ValueError("Page size must be >= 1")
+
+        offset = (page_number - 1) * page_size
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+
+        # Get total count of matching items
+        cursor.execute(
+            """
+            SELECT COUNT(*) FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL AND (c.hash LIKE ? OR c.g_time LIKE ? OR CAST(c.content AS TEXT) LIKE ?)
+        """,
+            (f"%{search_string}%", f"%{search_string}%", f"%{search_string}%"),
+        )
+        total_items = cursor.fetchone()[0]
+
+        # Get the actual items for the current page
+        cursor.execute(
+            """
+            SELECT c.content, c.g_time, c.hash FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL AND (c.hash LIKE ? OR c.g_time LIKE ? OR CAST(c.content AS TEXT) LIKE ?)
+            ORDER BY c.g_time DESC LIMIT ? OFFSET ?
+        """,
+            (
+                f"%{search_string}%",
+                f"%{search_string}%",
+                f"%{search_string}%",
+                page_size,
+                offset,
+            ),
+        )
+
+        items = [
+            self._row_to_card(content, hash_val, g_time)
+            for content, g_time, hash_val in cursor.fetchall()
+        ]
+
+        return Page.create(items, total_items, page_number, page_size)
+
+    def search_by_content(
+        self,
+        search_string: str | bytes,
+        page_number: int = 1,
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> Page:
+        """Search for cards by string or binary pattern in content.
+
+        Args:
+            search_string: The string or binary pattern to search for
+            page_number: The page number (1-based)
+            page_size: Number of items per page
+
+        Returns:
+            A Page object containing the matching cards
+        """
+        if page_number < 1:
+            raise ValueError("Page number must be >= 1")
+        if page_size < 1:
+            raise ValueError("Page size must be >= 1")
+
+        if not search_string:
+            raise ValueError("Search string cannot be empty")
+
+        offset = (page_number - 1) * page_size
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+
+        # Convert search string to bytes if it's a string
+        if isinstance(search_string, str):
+            search_bytes = search_string.encode("utf-8")
+        else:
+            search_bytes = search_string
+
+        # For binary search, we need to use the INSTR function to find the pattern
+        cursor.execute(
+            """
+            SELECT COUNT(*) FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL AND INSTR(c.content, ?) > 0
+        """,
+            (search_bytes,),
+        )
+        total_items = cursor.fetchone()[0]
+
+        # Get the actual items for the current page
+        cursor.execute(
+            """
+            SELECT c.content, c.g_time, c.hash FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL AND INSTR(c.content, ?) > 0
+            ORDER BY c.g_time DESC
+            LIMIT ? OFFSET ?
+        """,
+            (search_bytes, page_size, offset),
+        )
+
+        items = [
+            self._row_to_card(content, hash_val, g_time)
+            for content, g_time, hash_val in cursor.fetchall()
+        ]
+
+        return Page.create(items, total_items, page_number, page_size)
+
+    def count(self) -> int:
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            SELECT COUNT(*) FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL
+            """
+        )
+        return cursor.fetchone()[0]
+
+    def get_cards_by_page(
+        self, page_number: int = 1, page_size: int = DEFAULT_PAGE_SIZE
+    ) -> Page:
+        """Get a page of cards from the database.
+
+        Args:
+            page_number: The page number (1-based).
+            page_size: Number of items per page.
+
+        Returns:
+            A Page object containing the requested cards.
+
+        Raises:
+            ValueError: If page_number < 1 or page_size < 1
+        """
+        if page_number < 1:
+            raise ValueError("Page number must be >= 1")
+        if page_size < 1:
+            raise ValueError("Page size must be >= 1")
+
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            SELECT COUNT(*) FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL
+            """
+        )
+        total_items = cursor.fetchone()[0]
+
+        offset = (page_number - 1) * page_size
+        cursor.execute(
+            """
+            SELECT c.content, c.g_time, c.hash FROM card c
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL
+            ORDER BY c.g_time DESC LIMIT ? OFFSET ?
+            """,
+            (page_size, offset),
+        )
+
+        items = [
+            self._row_to_card(content, hash_val, g_time)
+            for content, g_time, hash_val in cursor.fetchall()
+        ]
+
+        return Page.create(items, total_items, page_number, page_size)
+
+    # =====================================================================
+    # Handle Space Mapping Operations (bi-directional mapping parity)
+    # =====================================================================
+
+    def set_handle(self, handle: str, target_hash: str, timestamp: str) -> None:
+        """Physically map a namespace Handle strictly against the immutable Content Hash."""
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            INSERT INTO handle_registry (handle, current_hash, created_at, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(handle) DO UPDATE SET
+                current_hash=excluded.current_hash,
+                updated_at=excluded.updated_at
+            """,
+            (handle, target_hash, timestamp, timestamp),
+        )
+        self.connection.commit()
+
+    def get_handle_dump(self) -> list[tuple[str, bytes]]:
+        """Recursively returns ALL valid mappings between Handles and physical Target MCards."""
+        self._ensure_tombstone_table()
+        cursor = self.connection.conn.cursor()
+        cursor.execute(
+            """
+            SELECT h.handle, c.content
+            FROM handle_registry h
+            INNER JOIN card c ON h.current_hash = c.hash
+            LEFT JOIN card_tombstone t ON c.hash = t.hash
+            WHERE t.hash IS NULL
+            """
+        )
+        return [(row[0], row[1]) for row in cursor.fetchall()]

clm/layer2/fiber/__init__.py

@@ -0,0 +1,31 @@
+"""Layer 2 Cordis Fiber Substrate (Sprint 389, INV-389-01..04).
+
+Normative Reference:
+    docs/spec/20-architecture/card-triad-architecture.md § Cordis Fiber Spatiotemporal Execution Substrate
+    docs/spec/40-behavior/hoare_triple_composition_protocol.md § 1 (Hoare Invariant Gating)
+
+Invariants:
+    INV-389-01: 5-State Fiber Lifecycle (Pending ➔ Loading ➔ Active ➔ Unloading ➔ Disposed).
+    INV-389-02: Reversible LIFO Effect Teardown Stack (DisposableList).
+    INV-389-03: Sub-millisecond (<1.0ms) Transactional Rollback (SavepointGuard, TriDbSavepointGuard).
+    INV-389-04: Lexical Context Hierarchy & Service Injection (Context, @Inject, ctx.isolate).
+"""
+from __future__ import annotations
+
+from .context import Context
+from .disposable import DisposableList, SavepointGuard, TriDbSavepointGuard
+from .fiber import Fiber, FiberLifecycleError, FiberState
+from .hoare import HoareExecutionReport, HoareFiberExecutor, HoareTriple
+
+__all__ = [
+    "Context",
+    "DisposableList",
+    "SavepointGuard",
+    "TriDbSavepointGuard",
+    "Fiber",
+    "FiberState",
+    "FiberLifecycleError",
+    "HoareTriple",
+    "HoareExecutionReport",
+    "HoareFiberExecutor",
+]

clm/layer2/fiber/context.py

@@ -0,0 +1,89 @@
+"""Cordis Hierarchical Context Tree (DEL-389-01, INV-389-04).
+
+Implements lexical scoping, dependency injection (@Inject), and spatiotemporal
+isolation (ctx.isolate) composed over the existing clm.layer0.context.CLMContext.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from clm.layer0.context import CLMContext
+
+
+class Context:
+    """Hierarchical Cordis Service Context.
+
+    Enforces INV-389-04 (Spatiotemporal Lexical Isolation):
+    Mutations and service registrations performed in child contexts (created via
+    `ctx.isolate()`) never leak into sibling or parent contexts.
+    """
+
+    def __init__(
+        self,
+        parent: Context | None = None,
+        services: dict[str, Any] | None = None,
+        clm_ctx: CLMContext | None = None,
+    ) -> None:
+        self.parent = parent
+        self._services: dict[str, Any] = dict(services or {})
+        self.clm_ctx = clm_ctx or (parent.clm_ctx.isolate() if parent and parent.clm_ctx else CLMContext.create_default())
+
+    def provide(self, name: str, service: Any) -> None:
+        """Register a service in this lexical context."""
+        self._services[name] = service
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """Resolve a service by name, walking up the ancestor hierarchy if needed."""
+        if name in self._services:
+            return self._services[name]
+        if self.parent is not None:
+            return self.parent.get(name, default)
+        return default
+
+    def has(self, name: str) -> bool:
+        """Check if a service is available in this context or any ancestor."""
+        if name in self._services:
+            return True
+        if self.parent is not None:
+            return self.parent.has(name)
+        return False
+
+    def inject(self, *service_names: str) -> dict[str, Any]:
+        """Resolve multiple declared @Inject services, raising KeyError if missing."""
+        resolved = {}
+        for s in service_names:
+            if not self.has(s):
+                raise KeyError(f"Context injection failed: service '{s}' not available in context")
+            resolved[s] = self.get(s)
+        return resolved
+
+    def isolate(
+        self,
+        services: dict[str, Any] | None = None,
+        **clm_overrides: Any,
+    ) -> Context:
+        """Create an isolated child context.
+
+        Mutations in the child context NEVER affect the parent (INV-389-04).
+        """
+        child_clm = self.clm_ctx.isolate(**clm_overrides) if self.clm_ctx else None
+        return Context(
+            parent=self,
+            services=services or {},
+            clm_ctx=child_clm,
+        )
+
+    def __getitem__(self, key: str) -> Any:
+        val = self.get(key)
+        if val is None and not self.has(key):
+            raise KeyError(f"Service '{key}' not found in context")
+        return val
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.provide(key, value)
+
+    def __contains__(self, key: str) -> bool:
+        return self.has(key)
+
+
+__all__ = ["Context"]