clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/sandbox.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+"""
+Sandbox execution environment for PCards with multi-language runtime support.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from clm.layer0.model.card import MCard
+from clm.layer0.narrative import IO, Either, Left, Right
+from clm.layer1.runtimes import RuntimeFactory
+from clm.layer1.store import PTRSharedStore
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Configuration
+# ─────────────────────────────────────────────────────────────────────────────
+
+DEFAULT_RUNTIME = "python"
+
+# Error message patterns for system errors (these should raise exceptions)
+SYSTEM_ERROR_PATTERNS = (
+    "Failed to parse PCard",
+    "Sandbox execution failed",
+)
+
+# Fallback resolution order
+FALLBACK_SOURCES = ("mcard", "file", "url")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Code Resolution Strategies
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class CodeResolver:
+    """Resolves code from multiple sources with fallback chain."""
+
+    def __init__(self, collection=None, logger=None):
+        self.collection = collection
+        self.logger = logger or logging.getLogger(__name__)
+
+    def resolve(
+        self, concrete_impl: dict, context: dict | PTRSharedStore
+    ) -> Either[str, str | None]:
+        """
+        Resolve code from available sources in priority order.
+
+        Returns:
+            Right(code) on success, Left(error) on failure
+        """
+        # Already have code
+        if concrete_impl.get("code"):
+            return Right(concrete_impl["code"])
+
+        # No code hash means no content-addressed lookup needed
+        code_hash = concrete_impl.get("code_hash")
+
+        # If no code source is specified, return None (success, no code needed)
+        if not any(
+            [
+                code_hash,
+                concrete_impl.get("code_file"),
+                concrete_impl.get("fallback_file"),
+                concrete_impl.get("fallback_url"),
+            ]
+        ):
+            return Right(None)
+
+        # Try resolution sources in order
+        resolvers = [
+            ("mcard", lambda: self._from_mcard(code_hash) if code_hash else None),
+            (
+                "file",
+                lambda: self._from_file(
+                    concrete_impl.get("code_file")
+                    or concrete_impl.get("fallback_file"),
+                    context,
+                    code_hash or "unknown",
+                ),
+            ),
+            (
+                "url",
+                lambda: self._from_url(
+                    concrete_impl.get("fallback_url"), code_hash or "unknown"
+                ),
+            ),
+        ]
+
+        for _source_name, resolver in resolvers:
+            result = resolver()
+            if result is not None:
+                return Right(result)
+
+        return Left(
+            f"Error: Code resolution failed. MCard {code_hash} not found, and fallbacks failed."
+        )
+
+    def _from_mcard(self, code_hash: str) -> str | None:
+        """Try to resolve code from MCard collection."""
+        if not self.collection:
+            return None
+
+        code_card = self.collection.get(code_hash)
+        if code_card:
+            self.logger.info(f"Resolved code from MCard: {code_hash}")
+            return code_card.get_content().decode("utf-8")
+        return None
+
+    def _from_file(
+        self, fallback_file: str | None, context: dict | PTRSharedStore, code_hash: str
+    ) -> str | None:
+        """Try to resolve code from fallback file."""
+        if not fallback_file:
+            return None
+
+        try:
+            path = self._resolve_file_path(fallback_file, context)
+            if path and path.exists():
+                self.logger.warning(
+                    f"MCard not found for hash {code_hash}, loaded from fallback file: {fallback_file}"
+                )
+                return path.read_text()
+            self.logger.warning(f"Fallback file not found: {path}")
+        except OSError as e:
+            self.logger.error(
+                f"Failed to load fallback file {fallback_file}: {e}", exc_info=True
+            )
+        return None
+
+    def _from_url(self, fallback_url: str | None, code_hash: str) -> str | None:
+        """Try to resolve code from fallback URL."""
+        if not fallback_url:
+            return None
+
+        try:
+            import urllib.request
+
+            with urllib.request.urlopen(fallback_url) as response:  # nosec B310
+                status = getattr(response, "status", None) or getattr(
+                    response, "code", 200
+                )
+                if status == 200:
+                    self.logger.warning(
+                        f"Loaded code from fallback URL: {fallback_url}"
+                    )
+                    return response.read().decode("utf-8")
+                self.logger.error(
+                    f"Failed to fetch fallback URL {fallback_url}: Status {status}"
+                )
+        except (OSError, ValueError, UnicodeDecodeError) as e:
+            self.logger.error(
+                f"Failed to fetch fallback URL {fallback_url}: {e}", exc_info=True
+            )
+        return None
+
+    @staticmethod
+    def _resolve_file_path(
+        file_path: str, context: dict | PTRSharedStore
+    ) -> Path | None:
+        """Resolve a file path, handling relative paths."""
+        path = Path(file_path)
+        if path.is_absolute():
+            return path
+
+        # Try pcard_dir first, then cwd
+        context_dict = (
+            context.inputs if isinstance(context, PTRSharedStore) else context
+        )
+        pcard_dir = context_dict.get("pcard_dir") if context_dict else None
+        if pcard_dir:
+            candidate = Path(pcard_dir) / path
+            if candidate.exists():
+                return candidate
+
+        return Path.cwd() / path
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Sandbox Executor
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class SandboxExecutor:
+    """
+    Executes PCard logic in a sandboxed environment with multi-language support.
+
+    The sandbox dynamically selects the appropriate runtime (Python, JavaScript,
+    Rust, C, etc.) based on the Concrete Implementation specification in the PCard.
+
+    Production deployments should use:
+    - WebAssembly (WASM) for true sandboxing
+    - Container isolation (Docker/Kubernetes)
+    - Resource limits and timeout enforcement
+    """
+
+    def __init__(self, collection=None):
+        self.logger = logging.getLogger(__name__)
+        self.collection = collection
+        self._code_resolver = CodeResolver(collection, self.logger)
+
+    def execute(
+        self, pcard: MCard, target: MCard, context: dict[str, Any] | PTRSharedStore
+    ) -> Any:
+        """
+        Execute PCard logic using the specified runtime.
+
+        The runtime is determined from the Concrete Implementation's 'runtime' field.
+        Defaults to 'python' if not specified.
+        """
+        result_either = self.execute_monad(pcard, target, context).unsafe_run()
+
+        if result_either.is_left():
+            error_msg = result_either.value
+            if self._is_system_error(error_msg):
+                raise RuntimeError(error_msg)
+            return error_msg
+        return result_either.value
+
+    async def aexecute(
+        self, pcard: MCard, target: MCard, context: dict[str, Any] | PTRSharedStore
+    ) -> Any:
+        """Async wrapper for execute() using a thread pool.
+
+        This provides an awaitable interface for sandbox execution without
+        altering runtime semantics. When true async runtimes are available,
+        this method can be updated to call them directly.
+        """
+        import asyncio
+
+        return await asyncio.to_thread(self.execute, pcard, target, context)
+
+    def execute_monad(
+        self, pcard: MCard, target: MCard, context: dict[str, Any] | PTRSharedStore
+    ) -> IO[Either[str, Any]]:
+        """Monadic execution pipeline returning IO[Either[Error, Result]]."""
+
+        def run() -> Either[str, Any]:
+            try:
+                return self._pipeline(pcard, target, context)
+            except Exception as e:
+                return Left(f"Sandbox execution failed: {e}")
+
+        return IO(run)
+
+    async def execute_monad_async(
+        self, pcard: MCard, target: MCard, context: dict[str, Any] | PTRSharedStore
+    ) -> Either[str, Any]:
+        """Async wrapper that returns Either by running the monadic pipeline in a thread pool."""
+        import asyncio
+
+        return await asyncio.to_thread(
+            lambda: self.execute_monad(pcard, target, context).unsafe_run()
+        )
+
+    def _pipeline(
+        self, pcard: MCard, target: MCard, context: dict | PTRSharedStore
+    ) -> Either[str, Any]:
+        """Execute the main processing pipeline."""
+        # 1. Parse PCard
+        pcard_data = self._parse_pcard(pcard)
+        if pcard_data.is_left():
+            return pcard_data
+
+        clm_base = pcard_data.value.get("clm", pcard_data.value)
+        concrete_impl = clm_base.get("concrete_impl", clm_base.get("concrete", {}))
+
+        # 2. Resolve Code
+        code_result = self._code_resolver.resolve(concrete_impl, context)
+        if code_result.is_left():
+            return code_result
+
+        if code_result.value:
+            concrete_impl["code"] = code_result.value
+
+        # 3. Get Executor
+        runtime_type = concrete_impl.get("runtime", DEFAULT_RUNTIME)
+        self.logger.info(f"Executing PCard with runtime: {runtime_type}")
+
+        executor = RuntimeFactory.get_executor(runtime_type)
+        if not executor:
+            return Left(
+                f"Error: Runtime '{runtime_type}' is not available or not supported"
+            )
+
+        # 4. Execute
+        return self._execute_runtime(executor, concrete_impl, target, context)
+
+    def _parse_pcard(self, pcard: MCard) -> Either[str, dict]:
+        """Parse PCard YAML content."""
+        try:
+            import yaml
+
+            return Right(yaml.safe_load(pcard.get_content().decode("utf-8")))
+        except (yaml.YAMLError, UnicodeDecodeError, ValueError, TypeError) as e:
+            return Left(f"Failed to parse PCard: {e}")
+
+    def _execute_runtime(
+        self,
+        executor: Any,
+        concrete_impl: dict,
+        target: MCard,
+        context: dict | PTRSharedStore,
+    ) -> Either[str, Any]:
+        """Execute using the selected runtime."""
+        try:
+            context_dict = (
+                context.inputs if isinstance(context, PTRSharedStore) else context
+            )
+            result = executor.execute(concrete_impl, target, context_dict)
+            if isinstance(result, str) and result.startswith("Error:"):
+                return Left(result)
+            return Right(result)
+        except (RuntimeError, ValueError, TypeError, OSError) as e:
+            return Left(f"Runtime execution failed: {e}")
+
+    @staticmethod
+    def _is_system_error(error_msg: str) -> bool:
+        """Check if error message indicates a system-level error."""
+        return any(pattern in error_msg for pattern in SYSTEM_ERROR_PATTERNS)
+
+    def list_available_runtimes(self) -> dict[str, bool]:
+        """Get list of available runtimes on this system."""
+        return RuntimeFactory.list_available_runtimes()
+
+
+__all__ = [
+    "DEFAULT_RUNTIME",
+    "SYSTEM_ERROR_PATTERNS",
+    "FALLBACK_SOURCES",
+    "CodeResolver",
+    "SandboxExecutor",
+]

clm/layer1/savepoint_guard.py

@@ -0,0 +1,136 @@
+"""
+Layer 1: ℤ₄ Savepoint Guard & Reversibility Engine (DV-373-03, INV-339-02).
+
+Implements transactional atomicity across the 4-phase cyclic group ℤ₄ = ℤ / 4ℤ:
+    0 (Idle) -> 1 (Pre-Gate) -> 2 (Transform) -> 3 (Post-Gate) -> 0 (Committed)
+
+On any VCard meet failure (T_valid = ⊥) or execution exception:
+- Automatically rolls back to the named SQLite savepoint
+- Executes all Cordis DisposableList callbacks in strict reverse-LIFO order
+- Guarantees zero residual state in the G-Set CAS (card, handle_history, learning_event)
+- Records safety and liveness telemetry metrics
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import sys
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any, Callable, Generator
+
+_target = "clm.layer2.fiber"
+_mod = sys.modules.get(_target)
+if _mod is None:
+    __import__(_target)
+    _mod = sys.modules.get(_target)
+DisposableList = _mod.DisposableList
+
+
+class VCardMeetViolation(Exception):
+    """Raised when pre- or post-condition meet collapses to ⊥."""
+    pass
+
+
+@dataclass
+class CPNExecutionTelemetry:
+    """Telemetry counters for CPN transition safety and liveness."""
+
+    total_transitions: int = 0
+    successful_transitions: int = 0
+    aborted_transitions: int = 0
+    safety_violation_count: int = 0
+    liveness_metric: float = 1.0
+
+    def record_success(self) -> None:
+        self.total_transitions += 1
+        self.successful_transitions += 1
+        self._update_liveness()
+
+    def record_abort(self) -> None:
+        self.total_transitions += 1
+        self.aborted_transitions += 1
+        self.safety_violation_count += 1
+        self._update_liveness()
+
+    def _update_liveness(self) -> None:
+        if self.total_transitions == 0:
+            self.liveness_metric = 1.0
+        else:
+            self.liveness_metric = self.successful_transitions / self.total_transitions
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_transitions": self.total_transitions,
+            "successful_transitions": self.successful_transitions,
+            "aborted_transitions": self.aborted_transitions,
+            "safety_violation_count": self.safety_violation_count,
+            "liveness_metric": round(self.liveness_metric, 4),
+        }
+
+
+# Vault-level singleton telemetry for CPN execution
+GLOBAL_CPN_TELEMETRY = CPNExecutionTelemetry()
+
+
+class Z4TransitionContext:
+    """State manager for a single ℤ₄ transition step."""
+
+    def __init__(self, step_id: str, conn: sqlite3.Connection, disposables: DisposableList) -> None:
+        self.step_id = step_id
+        self.conn = conn
+        self.disposables = disposables
+        self.phase: int = 0  # 0: Idle, 1: Prep, 2: Exec, 3: Post
+        self.vcard_meet_satisfied: bool = True
+
+    def advance_phase(self, new_phase: int) -> None:
+        """Transitions state: 0 -> 1 -> 2 -> 3 -> 0."""
+        self.phase = new_phase % 4
+
+    def register_disposable(self, callback: Callable[[], None]) -> None:
+        """Registers a reverse-LIFO rollback callback."""
+        self.disposables.push(callback)
+
+    def fail_meet(self, reason: str = "State collapsed to ⊥") -> None:
+        """Explicitly collapses transition to ⊥."""
+        self.vcard_meet_satisfied = False
+        raise VCardMeetViolation(f"Step '{self.step_id}' VCard Meet Violation: {reason}")
+
+
+@contextmanager
+def z4_savepoint_guard(
+    conn: sqlite3.Connection,
+    step_id: str | None = None,
+    telemetry: CPNExecutionTelemetry | None = None,
+) -> Generator[Z4TransitionContext, None, None]:
+    """
+    Executes a CPN transition in an isolated SQLite savepoint with ℤ₄ reversibility.
+
+    Guarantees zero partial writes on error.
+    """
+    tel = telemetry or GLOBAL_CPN_TELEMETRY
+    name = step_id or f"ptr_step_{uuid.uuid4().hex[:8]}"
+    sp_name = f"sp_{name}"
+    disposables = DisposableList()
+
+    conn.execute(f"SAVEPOINT {sp_name};")
+    t_ctx = Z4TransitionContext(step_id=name, conn=conn, disposables=disposables)
+
+    try:
+        t_ctx.advance_phase(1)  # Prep
+        yield t_ctx
+
+        if not t_ctx.vcard_meet_satisfied:
+            raise VCardMeetViolation("VCard meet collapsed to ⊥")
+
+        t_ctx.advance_phase(0)  # Sealed
+        conn.execute(f"RELEASE SAVEPOINT {sp_name};")
+        tel.record_success()
+
+    except Exception:
+        disposables.dispose()
+        conn.execute(f"ROLLBACK TO SAVEPOINT {sp_name};")
+        conn.execute(f"RELEASE SAVEPOINT {sp_name};")
+        tel.record_abort()
+        raise

clm/layer1/sparse_net.py

@@ -0,0 +1,122 @@
+"""Layer 1: Compressed Sparse Incidence Matrix & Precomputed P-Invariants (INV-419).
+
+Sprint 419 / DEL-419-02.
+Provides zero-allocation token transitions and O(1) Noetherian conservation verification.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from clm.layer0.math_utils import solve_nullspace
+
+
+@dataclass
+class PrecomputedInvariants:
+    """Pre-computed nullspace basis for Noetherian P-invariants (INV-419).
+
+    Replaces dynamic Gaussian elimination during transitions with O(1) dot-product checks.
+    """
+
+    basis_vectors: list[list[int]]
+    initial_constants: list[int]
+
+    @classmethod
+    def compile(
+        cls,
+        matrix: list[list[int]],
+        rows: int,
+        cols: int,
+        initial_marking: list[int],
+    ) -> PrecomputedInvariants:
+        """Compile nullspace invariants from an incidence matrix D and initial marking."""
+        basis = solve_nullspace(matrix, rows, cols, transpose=True)
+        initial_constants: list[int] = []
+        for b in basis:
+            s = sum(w * initial_marking[p] for p, w in enumerate(b) if p < len(initial_marking))
+            initial_constants.append(s)
+        return cls(basis_vectors=basis, initial_constants=initial_constants)
+
+    def verify_marking(self, marking: list[int]) -> bool:
+        """Fast-path check: returns True if current marking satisfies all basis conservation laws."""
+        for i, b in enumerate(self.basis_vectors):
+            s = sum(w * marking[p] for p, w in enumerate(b) if p < len(marking))
+            if i < len(self.initial_constants) and s != self.initial_constants[i]:
+                return False
+        return True
+
+    def verify_delta(self, delta: list[int]) -> bool:
+        """Fast-path check on marking delta: returns True if delta * v_k == 0 for all basis vectors."""
+        for b in self.basis_vectors:
+            s = sum(w * delta[p] for p, w in enumerate(b) if p < len(delta))
+            if s != 0:
+                return False
+        return True
+
+
+@dataclass
+class SparseIncidenceMatrix:
+    """Compressed Sparse Incidence Matrix for high-performance CPN evaluation."""
+
+    place_count: int
+    trans_count: int
+    consumed: list[list[tuple[int, int]]] = field(default_factory=list)
+    produced: list[list[tuple[int, int]]] = field(default_factory=list)
+    deltas: list[list[tuple[int, int]]] = field(default_factory=list)
+
+    @classmethod
+    def from_dense(
+        cls,
+        d: list[list[int]],
+        place_count: int,
+        trans_count: int,
+    ) -> SparseIncidenceMatrix:
+        """Construct from dense incidence matrix D (rows=places, cols=transitions)."""
+        consumed: list[list[tuple[int, int]]] = [[] for _ in range(trans_count)]
+        produced: list[list[tuple[int, int]]] = [[] for _ in range(trans_count)]
+        deltas: list[list[tuple[int, int]]] = [[] for _ in range(trans_count)]
+
+        for t in range(trans_count):
+            for p in range(place_count):
+                val = d[p][t] if p < len(d) and t < len(d[p]) else 0
+                if val < 0:
+                    consumed[t].append((p, -val))
+                    deltas[t].append((p, val))
+                elif val > 0:
+                    produced[t].append((p, val))
+                    deltas[t].append((p, val))
+
+        return cls(
+            place_count=place_count,
+            trans_count=trans_count,
+            consumed=consumed,
+            produced=produced,
+            deltas=deltas,
+        )
+
+    def is_enabled(self, t: int, marking: list[int]) -> bool:
+        """Check if transition t is enabled under the given marking."""
+        if t >= self.trans_count:
+            return False
+        for p, required in self.consumed[t]:
+            if p >= len(marking) or marking[p] < required:
+                return False
+        return True
+
+    def fire(self, t: int, marking: list[int]) -> bool:
+        """Fire transition t in-place on marking. Returns True on success, False if disabled."""
+        if not self.is_enabled(t, marking):
+            return False
+        for p, delta in self.deltas[t]:
+            if p < len(marking):
+                marking[p] += delta
+        return True
+
+    def get_delta(self, t: int) -> list[int]:
+        """Compute flat delta vector for transition t."""
+        res = [0] * self.place_count
+        if t < self.trans_count:
+            for p, delta in self.deltas[t]:
+                if p < len(res):
+                    res[p] = delta
+        return res