clm-kernel 0.0.0__py3-none-any.whl

clm/layer2/storage/db_hyperlinks.py

@@ -0,0 +1,214 @@
+"""Hyperlink and graph-traversal SQL mixin relocated to Layer 2 Storage (Sprint 387).
+
+Part of the CLMRepository MRO.
+Extracted from Layer 0. Provides graph traversal and hyperlink resolution
+over content-addressed MCards and semantic handles.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.exceptions import DatabaseError
+
+_logger = get_logger("clm.db")
+
+
+class HyperlinkMixin:
+    """Graph traversal and hyperlink resolution methods for CLMRepository.
+
+    Implements:
+      - ``extract_links(content)``: parses [[wikilinks]] and mcard:// URIs.
+      - ``get_outgoing_links(hash_val, pillar)``: outgoing references from a card.
+      - ``get_backlinks(target_hash_or_handle, pillar)``: cards pointing to a target.
+      - ``traverse_graph(start_hash, max_depth, pillar)``: BFS graph traversal.
+      - ``find_citing_stages(doc_handle, pillar)``: stage cards citing an arch doc.
+    """
+
+    @staticmethod
+    def extract_links(content: str) -> list[tuple[str, str]]:
+        """Extract typed hyperlinks from MCard content.
+
+        Supports:
+          - Wikilinks: ``[[target]]`` or ``[[target|label]]``
+          - URIs: ``mcard://handle/name``, ``mcard://hash/hex``,
+            ``mcard://eval/expr``
+
+        Returns:
+            list of ``(link_type, target)`` tuples where link_type is one of
+            ``'wikilink'``, ``'handle'``, ``'hash'``, or ``'eval'``.
+        """
+        if not content:
+            return []
+
+        links: list[tuple[str, str]] = []
+
+        # 1. Wikilinks: [[target]] or [[target|label]]
+        for match in re.finditer(r"\[\[([^\|\]]+)(?:\|[^\]]+)?\]\]", content):
+            target = match.group(1).strip()
+            if target:
+                links.append(("wikilink", target))
+
+        # 2. MCard URIs
+        for match in re.finditer(r"mcard://(handle|hash|eval)/([^\s\'\"\)\>]+)", content):
+            scheme_type = match.group(1)
+            target = match.group(2).strip()
+            if target:
+                links.append((scheme_type, target))
+
+        return links
+
+    def get_outgoing_links(self, hash_val: str, pillar: str = "content_memory") -> list[tuple[str, str]]:
+        """Return all outgoing hyperlinks extracted from a card's content.
+
+        Returns:
+            list of ``(link_type, target)`` tuples.
+        """
+        content = self.get_card_content(hash_val, pillar)
+        if not content:
+            return []
+        return self.extract_links(content)
+
+    def get_backlinks(self, target: str, pillar: str = "content_memory") -> list[str]:
+        """Find all card hashes that link to the given target (hash or handle).
+
+        Scans the card table using SQLite LIKE for candidates, then confirms
+        via ``extract_links`` to prevent substring false positives.
+        """
+        sql = "SELECT hash, content FROM card WHERE content LIKE ?;"
+        like_pattern = f"%{target}%"
+        try:
+            res = self.db.execute(pillar, sql, [like_pattern])
+        except Exception as e:
+            raise DatabaseError(f"Failed to query backlinks for {target}: {e}") from e
+
+        if not res or not res.strip():
+            return []
+
+        referring_hashes: list[str] = []
+        for line in res.strip().split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            pipe_idx = line.find("|")
+            if pipe_idx == -1:
+                continue
+            h = line[:pipe_idx].strip()
+            content = self.get_card_content(h, pillar) or ""
+            links = self.extract_links(content)
+            if any(t == target for _, t in links):
+                referring_hashes.append(h)
+
+        return referring_hashes
+
+    def traverse_graph(
+        self,
+        start_hash: str,
+        max_depth: int = 3,
+        pillar: str = "content_memory",
+    ) -> dict[str, Any]:
+        """Breadth-first traversal of the hyperlink graph starting from a card.
+
+        Returns a dictionary representing the traversed subgraph:
+          - ``nodes``: set of visited card hashes
+          - ``edges``: list of ``(source_hash, link_type, target)``
+        """
+        visited: set[str] = set()
+        edges: list[tuple[str, str, str]] = []
+        queue: list[tuple[str, int]] = [(start_hash, 0)]
+
+        while queue:
+            current_hash, depth = queue.pop(0)
+            if current_hash in visited or depth > max_depth:
+                continue
+
+            visited.add(current_hash)
+            links = self.get_outgoing_links(current_hash, pillar)
+
+            for link_type, target in links:
+                edges.append((current_hash, link_type, target))
+                if depth + 1 <= max_depth:
+                    next_hash: str | None = None
+                    if link_type == "hash":
+                        next_hash = target
+                    elif link_type in ("handle", "wikilink"):
+                        resolved = self.resolve_handle_hash(target, pillar)
+                        if resolved:
+                            next_hash = resolved
+
+                    if next_hash and next_hash not in visited:
+                        queue.append((next_hash, depth + 1))
+
+        return {"nodes": list(visited), "edges": edges}
+
+    def find_citing_stages(self, doc_handle: str, pillar: str = "content_memory") -> list[str]:
+        """Return Abstract-face card hashes whose ``external_references`` cite ``doc_handle``.
+
+        Implements the contravariant Yoneda functor Hom(-, A) specialised to
+        the Sprint 134 provenance graph: given an architecture doc handle A,
+        return the hashes of every Abstract-face card whose
+        ``context.external_references`` block cites it.
+
+        Args:
+            doc_handle: Architecture document handle name, e.g.
+                ``"doc:arch:134-provenance-hyperlinks"``.
+            pillar: Database pillar to scan (default ``"content_memory"``).
+
+        Returns:
+            A deduplicated list of card hashes that cite ``doc_handle``.
+            Empty list if no card cites it or the handle is unknown.
+
+        Raises:
+            DatabaseError: if the underlying scan query fails.
+        """
+        if not doc_handle:
+            return []
+        # Reuse the existing LIKE-pattern backlink scan: any card whose
+        # serialized content mentions the handle (as an mcard:// URI or a
+        # [[wikilink]]) is a candidate. The filter below confirms the
+        # citation via extract_links so partial-string false positives
+        # (e.g. a hash that happens to contain the handle as a substring)
+        # are rejected.
+        sql = "SELECT hash, content FROM card WHERE content LIKE ?;"
+        like_pattern = f"%{doc_handle}%"
+        try:
+            res = self.db.execute(pillar, sql, [like_pattern])
+        except Exception as e:
+            raise DatabaseError(
+                f"Failed to find citing stages for handle {doc_handle}: {e}"
+            ) from e
+        if not res or not res.strip():
+            return []
+
+        citing: list[str] = []
+        seen: set[str] = set()
+        # ``db.execute`` returns pipe-separated rows "hash|content" — but the
+        # content column itself may contain newlines, so we re-fetch per
+        # card via get_card_content to be safe. First pass extracts the
+        # candidate hashes only.
+        candidate_hashes: list[str] = []
+        for line in res.strip().split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            # The first pipe-delimited field is the hash; the rest is the
+            # content (which may contain additional pipes).
+            pipe_idx = line.find("|")
+            if pipe_idx == -1:
+                continue
+            h = line[:pipe_idx].strip()
+            if h and h not in seen:
+                seen.add(h)
+                candidate_hashes.append(h)
+
+        # Second pass: confirm via extract_links that the candidate actually
+        # cites the handle as a hyperlink (not as incidental prose).
+        for h in candidate_hashes:
+            content = self.get_card_content(h, pillar) or ""
+            links = self.extract_links(content)
+            for link_type, target in links:
+                if link_type == "handle" and target == doc_handle:
+                    citing.append(h)
+                    break
+        return citing

clm/layer2/storage/db_pool.py

@@ -0,0 +1,139 @@
+"""High-Concurrency SQLite WAL Connection Pool (Sprint 177 / Sprint 387).
+
+Thread-safe SQLite connection pool separating Read and Write channels:
+- Single Writer: Serialized writes using BEGIN IMMEDIATE to avoid busy locks.
+- Multi-Reader Pool: Fixed-size queue of read-only WAL connections.
+- In-Memory Support: Detects ':memory:' and uses shared-cache URI mode.
+- Directory Assurance: Automatically creates parent directories for disk DBs.
+
+Canonical Path: clm.layer2.storage.db_pool
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from contextlib import contextmanager
+from queue import Empty, Queue
+from typing import Generator
+
+
+class ClmDbPool:
+    """Thread-safe SQLite connection pool with dedicated writer and reader pool."""
+
+    def __init__(self, db_path: str, max_readers: int = 8, timeout: float = 5.0) -> None:
+        self.raw_path = db_path
+        self.is_memory = db_path == ":memory:" or "mode=memory" in db_path
+        self.db_path = (
+            "file:clm_memdb?mode=memory&cache=shared"
+            if db_path == ":memory:"
+            else db_path
+        )
+        self.uri = self.is_memory or db_path.startswith("file:")
+        self.max_readers = max_readers
+        self.timeout = timeout
+        self._write_lock = threading.Lock()
+        self._writer_conn: sqlite3.Connection | None = None
+        self._reader_queue: Queue[sqlite3.Connection] = Queue(maxsize=max_readers)
+        self._closed = False
+        self._ensure_dir()
+        self._init_db()
+
+    def _ensure_dir(self) -> None:
+        """Create parent directory if database is a disk file."""
+        if not self.is_memory and not self.db_path.startswith("file:"):
+            dir_path = os.path.dirname(os.path.abspath(self.db_path))
+            if dir_path:
+                os.makedirs(dir_path, exist_ok=True)
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a raw connection with timeout and URI configuration."""
+        return sqlite3.connect(
+            self.db_path,
+            timeout=self.timeout,
+            uri=self.uri,
+            check_same_thread=False,
+        )
+
+    def _init_db(self) -> None:
+        """Initialize WAL mode and pragmatic performance settings."""
+        conn = self._connect()
+        try:
+            if not self.is_memory:
+                conn.execute("PRAGMA journal_mode=WAL;")
+                conn.execute("PRAGMA synchronous=NORMAL;")
+            conn.execute("PRAGMA busy_timeout=5000;")
+            conn.execute("PRAGMA cache_size=-64000;")  # 64MB cache
+            conn.commit()
+        finally:
+            conn.close()
+
+    @contextmanager
+    def read_connection(self) -> Generator[sqlite3.Connection, None, None]:
+        """Borrow a read connection from the pool, recycling cleanly on return."""
+        conn = None
+        try:
+            conn = self._reader_queue.get_nowait()
+        except Empty:
+            conn = self._connect()
+            if not self.is_memory:
+                conn.execute("PRAGMA query_only=ON;")
+            conn.execute("PRAGMA busy_timeout=5000;")
+
+        try:
+            yield conn
+        except Exception:
+            if conn:
+                try:
+                    conn.rollback()
+                except Exception:
+                    pass
+                conn.close()
+                conn = None
+            raise
+        finally:
+            if conn is not None and not self._closed and self._reader_queue.qsize() < self.max_readers:
+                self._reader_queue.put_nowait(conn)
+            elif conn is not None:
+                conn.close()
+
+    @contextmanager
+    def write_transaction(self) -> Generator[sqlite3.Connection, None, None]:
+        """Acquire exclusive writer connection with automatic rollback and reconnect on error."""
+        with self._write_lock:
+            if self._writer_conn is None:
+                self._writer_conn = self._connect()
+                self._writer_conn.execute("PRAGMA busy_timeout=5000;")
+            try:
+                self._writer_conn.execute("BEGIN IMMEDIATE;")
+                yield self._writer_conn
+                self._writer_conn.commit()
+            except Exception:
+                try:
+                    self._writer_conn.rollback()
+                except sqlite3.OperationalError:
+                    try:
+                        self._writer_conn.close()
+                    except Exception:
+                        pass
+                    self._writer_conn = None
+                raise
+
+    def close(self) -> None:
+        """Close all pooled connections."""
+        self._closed = True
+        with self._write_lock:
+            if self._writer_conn:
+                try:
+                    self._writer_conn.close()
+                except Exception:
+                    pass
+                self._writer_conn = None
+
+        while not self._reader_queue.empty():
+            try:
+                conn = self._reader_queue.get_nowait()
+                conn.close()
+            except Empty:
+                break

clm/layer2/storage/db_repository.py

@@ -0,0 +1,229 @@
+"""RepositoryBase core CRUD relocated to Layer 2 Storage (Sprint 387).
+
+Extracted from Layer 0. The foundational Create/Retrieve/Delete operations
+on content-addressed MCards, semantic handles, and handle history.
+"""
+import os
+import time
+from pathlib import Path
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.exceptions import DatabaseError
+from clm.layer0.utils import clm_hash_string
+
+_logger = get_logger("clm.db")
+
+
+class RepositoryBase:
+    """Core CRUD operations for the MCard three-table schema.
+
+    Implements CRD-only operations (Create, Retrieve, Delete — no Update) on
+    content-addressed MCards, semantic handles, and the append-only handle
+    history. Handles are the α-conversion layer (mutable pointers over
+    immutable content); every handle reassignment is logged immutably in
+    handle_history (the η-conversion witness), preserving full temporal
+    provenance.
+
+    The repository enforces the Empty Schema Principle (Kenosis): zero
+    domain-specific columns. Domain semantics enter only through the content
+    stored in MCards, never through schema structure.
+    """
+
+    def __init__(self, db, clm_root: str):
+        self.db = db
+        self.clm_root = clm_root
+
+    def has_card(self, hash_val: str, pillar: str) -> bool:
+        """Checks if a card exists in the CAS by hash."""
+        sql = "SELECT 1 FROM card WHERE hash = ? LIMIT 1;"
+        try:
+            res = self.db.execute(pillar, sql, [hash_val])
+            return res.strip() == "1"
+        except Exception as e:
+            raise DatabaseError(f"Failed to check card existence in {pillar}: {e}") from e
+
+    def get_card_content(self, hash_val: str, pillar: str) -> str | None:
+        """Gets the content of a card from the CAS by hash."""
+        sql = "SELECT content FROM card WHERE hash = ?;"
+        try:
+            res = self.db.execute(pillar, sql, [hash_val])
+            return res.strip() if res else None
+        except Exception as e:
+            raise DatabaseError(f"Failed to get card content from {pillar}: {e}") from e
+
+    def save_card(self, hash_val: str, content: str, pillar: str, timestamp: str | None = None, replace: bool = False) -> None:
+        """Saves a card to the CAS."""
+        g_time = timestamp or time.strftime("%Y-%m-%dT%H:%M:%S%z")
+        verb = "REPLACE" if replace else "IGNORE"
+        sql = f"INSERT OR {verb} INTO card (hash, content, g_time) VALUES (?, ?, ?);"
+        try:
+            self.db.execute(pillar, sql, [hash_val, content, g_time])
+        except Exception as e:
+            raise DatabaseError(f"Failed to save card to {pillar}: {e}") from e
+
+    def save_card_and_handle(self, handle_name: str, hash_val: str, content: str, pillar: str, timestamp: str | None = None, replace: bool = True) -> None:
+        """Saves a card to the CAS and updates/registers its handle."""
+        g_time = timestamp or time.strftime("%Y-%m-%dT%H:%M:%S%z")
+        self.save_card(hash_val, content, pillar, timestamp=g_time, replace=replace)
+
+        existing_hash = self.resolve_handle_hash(handle_name, pillar)
+
+        try:
+            if not existing_hash:
+                verb = "REPLACE" if replace else "IGNORE"
+                sql = f"INSERT OR {verb} INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?);"
+                self.db.execute(pillar, sql, [handle_name, hash_val, g_time, g_time])
+            elif existing_hash != hash_val:
+                self.db.execute(pillar, "INSERT OR IGNORE INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?);", [handle_name, existing_hash, g_time])
+                self.db.execute(pillar, "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?;", [hash_val, g_time, handle_name])
+        except Exception as e:
+            raise DatabaseError(f"Failed to save handle {handle_name} in {pillar}: {e}") from e
+
+    def get_handle_by_hash(self, hash_val: str, pillar: str) -> str | None:
+        """Gets the handle name associated with a given hash value."""
+        sql = "SELECT handle FROM handle_registry WHERE current_hash = ? LIMIT 1;"
+        try:
+            res = self.db.execute(pillar, sql, [hash_val])
+            return res.strip() if res else None
+        except Exception as e:
+            raise DatabaseError(f"Failed to get handle by hash from {pillar}: {e}") from e
+
+    def get_all_handles(self, pillar: str) -> list[tuple[str, str]]:
+        """Gets all handle-to-hash mappings from the handle registry."""
+        sql = "SELECT handle, current_hash FROM handle_registry;"
+        try:
+            res = self.db.execute(pillar, sql)
+            lines = [line.strip() for line in res.strip().split("\n") if line.strip()]
+            results = []
+            for line in lines:
+                parts = line.split("|")
+                if len(parts) >= 2:
+                    results.append((parts[0], parts[1]))
+            return results
+        except Exception as e:
+            raise DatabaseError(f"Failed to get all handles from {pillar}: {e}") from e
+
+    def get_latest_handle_history(self, handle_name: str, pillar: str) -> str | None:
+        """Gets the latest previous hash from the handle history."""
+        sql = "SELECT previous_hash FROM handle_history WHERE handle = ? ORDER BY changed_at DESC LIMIT 1;"
+        try:
+            res = self.db.execute(pillar, sql, [handle_name])
+            return res.strip() if res else None
+        except Exception as e:
+            raise DatabaseError(f"Failed to get latest handle history for {handle_name} from {pillar}: {e}") from e
+
+    def resolve_handle_hash(self, handle_name: str, pillar: str = "content_memory") -> str:
+        sql = "SELECT current_hash FROM handle_registry WHERE handle = ?;"
+        res = self.db.execute(pillar, sql, [handle_name])
+        return res.strip() if res else ""
+
+    def _find_script_on_disk(self, handle_name: str) -> str | None:
+        if not handle_name.startswith("script:"):
+            return None
+        script_name = handle_name.split("script:")[1].split("#")[0]
+        for ext in (".py", ".sh"):
+            for dir_name in ("tests/runners", "scripts", "tests", "computable_knowledge"):
+                dir_path = Path(self.clm_root) / dir_name
+                if dir_path.exists():
+                    if dir_name == "tests/runners":
+                        for sub in ("layers", "sprints", "petri", "benchmarks"):
+                            cand = dir_path / sub / f"{script_name}{ext}"
+                            if cand.exists():
+                                return str(cand)
+                    for p in dir_path.rglob(f"{script_name}{ext}"):
+                        return str(p)
+        return None
+
+    def resolve_handle_content(self, handle_name: str, pillar: str = "content_memory") -> str:
+        hash_val = self.resolve_handle_hash(handle_name, pillar)
+
+        if not hash_val and handle_name.startswith("script:"):
+            script_path = self._find_script_on_disk(handle_name)
+            if script_path:
+                self.register_handle(handle_name, script_path)
+                hash_val = self.resolve_handle_hash(handle_name, pillar)
+
+        if hash_val and handle_name.startswith("script:"):
+            script_path = self._find_script_on_disk(handle_name)
+            if script_path:
+                with open(script_path, encoding="utf-8") as f:
+                    disk_content = f.read()
+                norm_content = disk_content.replace("\r\n", "\n").replace("\r", "\n")
+                disk_hash = clm_hash_string(norm_content)
+                if disk_hash != hash_val:
+                    _logger.info(f"[PAL:python] Stale handle detected: '{handle_name}' (DB={hash_val}, disk={disk_hash}). Re-reading from file.")
+                    self.register_handle(handle_name, script_path)
+                    hash_val = disk_hash
+
+        if not hash_val:
+            return ""
+
+        sql = "SELECT content FROM card WHERE hash = ?;"
+        res = self.db.execute(pillar, sql, [hash_val])
+        content_val = res.strip() if res else ""
+        if handle_name.startswith("script:") and not content_val:
+            script_path = self._find_script_on_disk(handle_name)
+            if script_path:
+                with open(script_path, encoding="utf-8") as f:
+                    disk_content = f.read()
+                content_val = disk_content.replace("\r\n", "\n").replace("\r", "\n")
+
+        return content_val
+
+    def register_handle(self, handle_name: str, content_source: str) -> int:
+        import sys
+        if content_source == "-":
+            content = sys.stdin.read()
+        elif os.path.exists(content_source):
+            with open(content_source, encoding="utf-8") as f:
+                content = f.read()
+        else:
+            content = content_source
+
+        if not content:
+            _logger.error(f"[REGISTER_HANDLE] Empty content for handle: {handle_name}")
+            return 1
+
+        norm_content = content.replace("\r\n", "\n").replace("\r", "\n")
+        content_hash = clm_hash_string(norm_content)
+
+        existing_hash = self.resolve_handle_hash(handle_name, "content_memory")
+        g_time = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+        self.db.execute("content_memory", "INSERT OR IGNORE INTO card (hash, content, g_time) VALUES (?, ?, ?);", [content_hash, content, g_time])
+
+        now = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+        if not existing_hash:
+            self.db.execute("content_memory", "INSERT OR REPLACE INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?);", [handle_name, content_hash, now, now])
+            _logger.info(f"[REGISTER_HANDLE] Created handle: {handle_name}")
+            _logger.info(f"[REGISTER_HANDLE]   hash: {content_hash}")
+        elif existing_hash == content_hash:
+            _logger.info(f"[REGISTER_HANDLE] No change for handle: {handle_name}")
+            _logger.info(f"[REGISTER_HANDLE]   hash: {content_hash}")
+        else:
+            self.db.execute("content_memory", "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?);", [handle_name, existing_hash, now])
+            self.db.execute("content_memory", "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?;", [content_hash, now, handle_name])
+            _logger.info(f"[REGISTER_HANDLE] Updated handle: {handle_name}")
+            _logger.info(f"[REGISTER_HANDLE]   old_hash: {existing_hash}")
+            _logger.info(f"[REGISTER_HANDLE]   new_hash: {content_hash}")
+
+        return 0
+
+    def tombstone_handle(self, handle_name: str, pillar: str = "content_memory") -> bool:
+        """Tombstones a handle by dereferencing it and appending a tombstone record to handle_history.
+
+        Preserves G-Set CRDT monotonicity: the referenced CAS card remains untouched,
+        while the mutable handle pointer is removed and an audit tombstone event is logged.
+        """
+        existing_hash = self.resolve_handle_hash(handle_name, pillar)
+        if not existing_hash:
+            return False
+        now = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+        self.db.execute(
+            pillar,
+            "INSERT INTO handle_history (handle, previous_hash, changed_at, change_type) VALUES (?, ?, ?, 'TOMBSTONE');",
+            [handle_name, existing_hash, now],
+        )
+        self.db.execute(pillar, "DELETE FROM handle_registry WHERE handle = ?;", [handle_name])
+        _logger.info(f"[TOMBSTONE_HANDLE] Tombstoned handle '{handle_name}' (was {existing_hash})")
+        return True

clm/layer2/storage/savepoint.py

@@ -0,0 +1,78 @@
+"""SQLite Savepoint Transaction Guard & Cordis Disposable List (Sprint 177 / Sprint 387).
+
+Implements nested transaction savepoints mirroring Rust Sprint 165 SavepointGuard,
+and DisposableList for strict LIFO rollback and zero-residual-state guarantees.
+
+Canonical Path: clm.layer2.storage.savepoint
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import uuid
+from contextlib import contextmanager
+from typing import Callable, Generator
+
+
+@contextmanager
+def savepoint(conn: sqlite3.Connection, name: str | None = None) -> Generator[DisposableList, None, None]:
+    """Execute within a named SQLite savepoint with automatic LIFO rollback on exception."""
+    sp_name = name or f"sp_{uuid.uuid4().hex[:8]}"
+    disposables = DisposableList()
+    disposables.name = sp_name
+    conn.execute(f"SAVEPOINT {sp_name};")
+    try:
+        yield disposables
+        conn.execute(f"RELEASE SAVEPOINT {sp_name};")
+    except Exception:
+        disposables.dispose()
+        conn.execute(f"ROLLBACK TO SAVEPOINT {sp_name};")
+        conn.execute(f"RELEASE SAVEPOINT {sp_name};")
+        raise
+
+
+class DisposableList:
+    """LIFO stack of reversible effects and cleanup callbacks (Cordis parity)."""
+
+    def __init__(self) -> None:
+        self._disposers: list[Callable[[], None]] = []
+
+    def push(self, disposer: Callable[[], None]) -> None:
+        """Pushes a cleanup function to the top of the LIFO stack."""
+        self._disposers.append(disposer)
+
+    def register(self, disposer: Callable[[], None]) -> None:
+        """Alias for push."""
+        self.push(disposer)
+
+    def __len__(self) -> int:
+        return len(self._disposers)
+
+    def is_empty(self) -> bool:
+        return len(self._disposers) == 0
+
+    def dispose(self) -> list[Exception]:
+        """Unwinds all registered disposers in strict LIFO order.
+
+        Executes all disposers even if some raise exceptions, accumulating errors.
+        """
+        errors: list[Exception] = []
+        while self._disposers:
+            disposer = self._disposers.pop()
+            try:
+                disposer()
+            except Exception as e:
+                errors.append(e)
+        return errors
+
+    def unwind_lifo(self) -> list[Exception]:
+        """Alias for dispose() matching Cordis LIFO unwind convention."""
+        return self.dispose()
+
+    def __enter__(self) -> DisposableList:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        errors = self.dispose()
+        if errors and exc_type is None:
+            raise errors[0]