clm-kernel 0.0.0__py3-none-any.whl

clm/layer2/fiber/disposable.py

@@ -0,0 +1,163 @@
+"""Cordis DisposableList & Savepoint Guard (DEL-389-01, INV-389-02, INV-389-03).
+
+Provides:
+1. DisposableList: Strict LIFO stack of reversible side-effects for zero-residual state.
+2. SavepointGuard: RAII SQLite savepoint manager with <1ms transactional rollback.
+3. TriDbSavepointGuard: Multi-database atomic savepoint coordinator across the Triad.
+"""
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+import uuid
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class DisposableList:
+    """Strict LIFO stack of cleanup/rollback closures for Cordis fibers.
+
+    Enforces INV-389-02: Disposers execute in exact reverse registration order.
+    Aggregates exceptions so that all disposers run even if one raises.
+    """
+
+    def __init__(self) -> None:
+        self._disposables: list[Callable[[], None]] = []
+
+    def push(self, disposable: Callable[[], None]) -> None:
+        """Register a cleanup closure to be executed on disposal."""
+        if callable(disposable):
+            self._disposables.append(disposable)
+
+    def dispose(self) -> list[Exception]:
+        """Execute all registered closures in reverse-LIFO order.
+
+        Returns:
+            List of any exceptions raised during disposal.
+        """
+        errors: list[Exception] = []
+        while self._disposables:
+            fn = self._disposables.pop()
+            try:
+                fn()
+            except Exception as e:
+                logger.error(f"[DisposableList] Disposer failed: {e}", exc_info=True)
+                errors.append(e)
+        return errors
+
+    def clear(self) -> None:
+        """Clear all registered disposers without executing them."""
+        self._disposables.clear()
+
+    def __len__(self) -> int:
+        return len(self._disposables)
+
+    def __bool__(self) -> bool:
+        return len(self._disposables) > 0
+
+
+class SavepointGuard:
+    """RAII SQLite savepoint manager with sub-millisecond rollback (INV-389-03)."""
+
+    def __init__(
+        self,
+        conn: sqlite3.Connection,
+        name: str | None = None,
+        disposables: DisposableList | None = None,
+    ) -> None:
+        self.conn = conn
+        self.name = name or f"sp_{uuid.uuid4().hex[:8]}"
+        self.disposables = disposables or DisposableList()
+        self._rolled_back = False
+        self._released = False
+        self.rollback_duration_ms: float = 0.0
+
+    def begin(self) -> None:
+        """Issue SAVEPOINT statement."""
+        self.conn.execute(f"SAVEPOINT {self.name};")
+
+    def rollback(self) -> None:
+        """Roll back to savepoint and unwind disposables in LIFO order."""
+        if self._rolled_back or self._released:
+            return
+        t0 = time.perf_counter()
+        try:
+            self.disposables.dispose()
+            self.conn.execute(f"ROLLBACK TO SAVEPOINT {self.name};")
+            self.conn.execute(f"RELEASE SAVEPOINT {self.name};")
+        finally:
+            self._rolled_back = True
+            self.rollback_duration_ms = (time.perf_counter() - t0) * 1000.0
+            logger.debug(f"[SavepointGuard] Rollback '{self.name}' completed in {self.rollback_duration_ms:.3f}ms")
+
+    def commit(self) -> None:
+        """Release the savepoint cleanly."""
+        if self._rolled_back or self._released:
+            return
+        self.conn.execute(f"RELEASE SAVEPOINT {self.name};")
+        self._released = True
+
+    def __enter__(self) -> SavepointGuard:
+        self.begin()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if exc_type is not None:
+            self.rollback()
+            return False
+        else:
+            self.commit()
+            return True
+
+
+class TriDbSavepointGuard:
+    """Coordinated savepoint guard across multiple SQLite database connections."""
+
+    def __init__(
+        self,
+        connections: dict[str, sqlite3.Connection] | list[sqlite3.Connection],
+        name: str | None = None,
+        disposables: DisposableList | None = None,
+    ) -> None:
+        if isinstance(connections, dict):
+            self.conns = list(connections.values())
+        else:
+            self.conns = list(connections)
+        self.name = name or f"tridb_sp_{uuid.uuid4().hex[:8]}"
+        self.disposables = disposables or DisposableList()
+        self._guards = [SavepointGuard(c, self.name, None) for c in self.conns]
+        self.rollback_duration_ms: float = 0.0
+
+    def begin(self) -> None:
+        for g in self._guards:
+            g.begin()
+
+    def rollback(self) -> None:
+        t0 = time.perf_counter()
+        try:
+            self.disposables.dispose()
+            for g in self._guards:
+                g.rollback()
+        finally:
+            self.rollback_duration_ms = (time.perf_counter() - t0) * 1000.0
+
+    def commit(self) -> None:
+        for g in self._guards:
+            g.commit()
+
+    def __enter__(self) -> TriDbSavepointGuard:
+        self.begin()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if exc_type is not None:
+            self.rollback()
+            return False
+        else:
+            self.commit()
+            return True
+
+
+__all__ = ["DisposableList", "SavepointGuard", "TriDbSavepointGuard"]

clm/layer2/fiber/fiber.py

@@ -0,0 +1,125 @@
+"""Cordis 5-State Fiber Lifecycle Machine (DEL-389-01, INV-389-01).
+
+Implements the formal state machine:
+    Pending ➔ Loading ➔ Active ➔ Unloading ➔ Disposed
+
+Enforces INV-389-01: Every execution fiber must strictly follow valid transitions;
+direct jumps or resurrections raise FiberLifecycleError.
+"""
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Callable
+
+from clm.layer0.exceptions import CLMError
+from clm.layer2.fiber.context import Context
+from clm.layer2.fiber.disposable import DisposableList
+
+logger = logging.getLogger(__name__)
+
+
+class FiberState(str, Enum):
+    """The five canonical lifecycle states of a Cordis Fiber."""
+    PENDING = "pending"
+    LOADING = "loading"
+    ACTIVE = "active"
+    UNLOADING = "unloading"
+    DISPOSED = "disposed"
+
+
+class FiberLifecycleError(CLMError):
+    """Raised when an illegal transition is attempted across fiber states."""
+    pass
+
+
+# Strict transition matrix enforcing INV-389-01
+VALID_TRANSITIONS: dict[FiberState, set[FiberState]] = {
+    FiberState.PENDING: {FiberState.LOADING},
+    FiberState.LOADING: {FiberState.ACTIVE, FiberState.DISPOSED},
+    FiberState.ACTIVE: {FiberState.UNLOADING},
+    FiberState.UNLOADING: {FiberState.DISPOSED},
+    FiberState.DISPOSED: set(),  # Terminal state: cannot transition out
+}
+
+
+class Fiber:
+    """Cordis Execution Fiber.
+
+    Represents an isolated unit of execution with a 5-state lifecycle and LIFO disposer stack.
+    """
+
+    def __init__(
+        self,
+        fiber_id: str,
+        context: Context | None = None,
+        disposables: DisposableList | None = None,
+    ) -> None:
+        self.id = fiber_id
+        self.state: FiberState = FiberState.PENDING
+        self.context = context or Context()
+        self.disposables = disposables or DisposableList()
+        self._history: list[FiberState] = [FiberState.PENDING]
+
+    def register_disposable(self, callback: Callable[[], None]) -> None:
+        """Register a LIFO cleanup closure on this fiber."""
+        self.disposables.push(callback)
+
+    def transition(self, target: FiberState | str) -> None:
+        """Transition the fiber to a new lifecycle state.
+
+        Raises:
+            FiberLifecycleError: If the transition violates INV-389-01.
+        """
+        if isinstance(target, str):
+            try:
+                target_state = FiberState(target.lower())
+            except ValueError:
+                raise FiberLifecycleError(f"Unknown FiberState '{target}' for fiber '{self.id}'")
+        else:
+            target_state = target
+
+        allowed = VALID_TRANSITIONS.get(self.state, set())
+        if target_state not in allowed:
+            raise FiberLifecycleError(
+                f"Illegal fiber lifecycle transition for '{self.id}': "
+                f"cannot jump from {self.state.value.upper()} to {target_state.value.upper()}. "
+                f"Valid target states: {[s.value.upper() for s in allowed]}"
+            )
+
+        logger.debug(f"[Fiber:{self.id}] {self.state.value} -> {target_state.value}")
+        self.state = target_state
+        self._history.append(target_state)
+
+        # When entering DISPOSED, automatically unwind disposables
+        if target_state == FiberState.DISPOSED:
+            self.disposables.dispose()
+
+    def dispose(self) -> None:
+        """Gracefully transition this fiber to DISPOSED via valid intermediate steps."""
+        if self.state == FiberState.DISPOSED:
+            return
+        if self.state == FiberState.PENDING:
+            self.transition(FiberState.LOADING)
+            self.transition(FiberState.DISPOSED)
+        elif self.state == FiberState.LOADING:
+            self.transition(FiberState.DISPOSED)
+        elif self.state == FiberState.ACTIVE:
+            self.transition(FiberState.UNLOADING)
+            self.transition(FiberState.DISPOSED)
+        elif self.state == FiberState.UNLOADING:
+            self.transition(FiberState.DISPOSED)
+
+    @property
+    def is_active(self) -> bool:
+        return self.state == FiberState.ACTIVE
+
+    @property
+    def is_disposed(self) -> bool:
+        return self.state == FiberState.DISPOSED
+
+    def __repr__(self) -> str:
+        return f"<Fiber id={self.id!r} state={self.state.value!r} disposables={len(self.disposables)}>"
+
+
+__all__ = ["FiberState", "FiberLifecycleError", "Fiber"]

clm/layer2/fiber/hoare.py

@@ -0,0 +1,191 @@
+"""Hoare Fiber State Machine & Deterministic Rollback (DEL-389-01, INV-389-03).
+
+Executes formal Hoare Triples {P} C {Q} across Fiber lifecycles with guaranteed
+sub-millisecond (<1ms) transactional rollback via SavepointGuard and DisposableList.
+"""
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from clm.layer2.fiber.context import Context
+from clm.layer2.fiber.disposable import SavepointGuard
+from clm.layer2.fiber.fiber import Fiber, FiberState
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HoareTriple:
+    """Formal specification of a state transition as a Hoare Triple {P} C {Q}."""
+    name: str
+    transition: Callable[[Context, Fiber], Any]
+    precondition: Callable[[Context], bool | tuple[bool, str]] | None = None
+    postcondition: Callable[[Context, Any], bool | tuple[bool, str]] | None = None
+
+
+@dataclass
+class HoareExecutionReport:
+    """Execution telemetry report measuring rollback timing and determinism."""
+    fiber_id: str
+    success: bool
+    rollback_triggered: bool
+    rollback_duration_ms: float
+    final_state: FiberState
+    value: Any = None
+    error: str | None = None
+
+
+class HoareFiberExecutor:
+    """Executes transitions under formal Hoare contract verification with deterministic rollback."""
+
+    @staticmethod
+    def execute(
+        context: Context,
+        fiber: Fiber,
+        triple: HoareTriple,
+        conn: sqlite3.Connection | None = None,
+    ) -> HoareExecutionReport:
+        """Execute a HoareTriple {P} C {Q} over a Fiber.
+
+        Guarantees:
+        - {P} evaluated in LOADING state.
+        - Computation C evaluated in ACTIVE state.
+        - {Q} evaluated on concrete output value before state commitment.
+        - On {P} or {Q} failure or exception: triggers LIFO unwinding and savepoint rollback in <1ms.
+        """
+        # Step 1: Ensure fiber is in LOADING state
+        if fiber.state == FiberState.PENDING:
+            fiber.transition(FiberState.LOADING)
+
+        # Step 2: Evaluate Precondition {P} in LOADING state
+        if triple.precondition is not None:
+            try:
+                pre_res = triple.precondition(context)
+                if isinstance(pre_res, tuple):
+                    passed, msg = pre_res
+                    if not passed:
+                        fiber.transition(FiberState.DISPOSED)
+                        return HoareExecutionReport(
+                            fiber_id=fiber.id,
+                            success=False,
+                            rollback_triggered=False,
+                            rollback_duration_ms=0.0,
+                            final_state=fiber.state,
+                            error=f"Precondition {{P}} failed: {msg}",
+                        )
+                elif not pre_res:
+                    fiber.transition(FiberState.DISPOSED)
+                    return HoareExecutionReport(
+                        fiber_id=fiber.id,
+                        success=False,
+                        rollback_triggered=False,
+                        rollback_duration_ms=0.0,
+                        final_state=fiber.state,
+                        error="Precondition {P} check returned False",
+                    )
+            except Exception as e:
+                fiber.transition(FiberState.DISPOSED)
+                return HoareExecutionReport(
+                    fiber_id=fiber.id,
+                    success=False,
+                    rollback_triggered=False,
+                    rollback_duration_ms=0.0,
+                    final_state=fiber.state,
+                    error=f"Precondition {{P}} exception: {e}",
+                )
+
+        # Step 3: Transition to ACTIVE state
+        fiber.transition(FiberState.ACTIVE)
+
+        # Step 4: Setup SavepointGuard for computation C
+        sp_guard: SavepointGuard | None = None
+        if conn is not None:
+            sp_guard = SavepointGuard(conn, name=f"sp_{triple.name[:12]}", disposables=fiber.disposables)
+            sp_guard.begin()
+
+        # Step 5: Execute computation C
+        try:
+            val = triple.transition(context, fiber)
+        except Exception as e:
+            logger.warning(f"[HoareFiberExecutor] Computation error in '{triple.name}': {e}", exc_info=True)
+            rollback_duration = 0.0
+            if sp_guard is not None:
+                sp_guard.rollback()
+                rollback_duration = sp_guard.rollback_duration_ms
+            else:
+                t0 = time.perf_counter()
+                fiber.disposables.dispose()
+                rollback_duration = (time.perf_counter() - t0) * 1000.0
+
+            fiber.transition(FiberState.UNLOADING)
+            fiber.transition(FiberState.DISPOSED)
+
+            return HoareExecutionReport(
+                fiber_id=fiber.id,
+                success=False,
+                rollback_triggered=True,
+                rollback_duration_ms=rollback_duration,
+                final_state=fiber.state,
+                error=f"Execution error in {triple.name}: {e}",
+            )
+
+        # Step 6: Evaluate Postcondition {Q} in ACTIVE state on output value
+        if triple.postcondition is not None:
+            post_passed = True
+            post_error = ""
+            try:
+                post_res = triple.postcondition(context, val)
+                if isinstance(post_res, tuple):
+                    post_passed, post_error = post_res
+                elif not post_res:
+                    post_passed = False
+                    post_error = "Postcondition {Q} returned False"
+            except Exception as e:
+                post_passed = False
+                post_error = f"Postcondition {{Q}} exception: {e}"
+
+            if not post_passed:
+                logger.warning(f"[HoareFiberExecutor] Postcondition {{Q}} failed in '{triple.name}': {post_error}")
+                rollback_duration = 0.0
+                if sp_guard is not None:
+                    sp_guard.rollback()
+                    rollback_duration = sp_guard.rollback_duration_ms
+                else:
+                    t0 = time.perf_counter()
+                    fiber.disposables.dispose()
+                    rollback_duration = (time.perf_counter() - t0) * 1000.0
+
+                fiber.transition(FiberState.UNLOADING)
+                fiber.transition(FiberState.DISPOSED)
+
+                return HoareExecutionReport(
+                    fiber_id=fiber.id,
+                    success=False,
+                    rollback_triggered=True,
+                    rollback_duration_ms=rollback_duration,
+                    final_state=fiber.state,
+                    error=f"Postcondition {{Q}} failed: {post_error}",
+                )
+
+        # Step 7: Postconditions satisfied, commit transaction
+        if sp_guard is not None:
+            sp_guard.commit()
+
+        fiber.transition(FiberState.UNLOADING)
+        fiber.transition(FiberState.DISPOSED)
+
+        return HoareExecutionReport(
+            fiber_id=fiber.id,
+            success=True,
+            rollback_triggered=False,
+            rollback_duration_ms=0.0,
+            final_state=fiber.state,
+            value=val,
+        )
+
+
+__all__ = ["HoareTriple", "HoareExecutionReport", "HoareFiberExecutor"]