clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/runtimes/__init__.py

@@ -0,0 +1,71 @@
+"""
+Runtimes Module for PTR
+========================
+
+This module provides modular runtime executor implementations.
+
+Organization:
+- base.py: Core abstractions (RuntimeExecutor, SubprocessRuntime, enums)
+- python.py: PythonRuntime (in-process Python execution)
+- javascript.py: JavaScriptRuntime (Node.js/Deno execution)
+- binary.py: BinaryRuntime, RustRuntime, CRuntime
+- script.py: ScriptRuntime, LeanRuntime, RRuntime, JuliaRuntime
+- lambda_calc.py: LambdaRuntimeExecutor
+- factory.py: RuntimeFactory
+
+For backward compatibility, the main runtime.py re-exports all classes.
+"""
+
+from .base import (
+    DEFAULT_TIMEOUT,
+    JULIA_TIMEOUT,
+    LEAN_TIMEOUT,
+    R_TIMEOUT,
+    RUNTIME_CONFIG,
+    BoundaryType,
+    RuntimeExecutor,
+    RuntimeType,
+    SubprocessRuntime,
+)
+from .binary import BinaryRuntime, CRuntime, RustRuntime
+from .factory import RuntimeFactory
+from .javascript import JavaScriptRuntime
+from .lambda_calc import LambdaRuntimeExecutor
+from .python import PythonRuntime
+from .script import JuliaRuntime, LeanRuntime, RRuntime, ScriptRuntime
+
+__all__ = [
+    # Enums
+    "RuntimeType",
+    "BoundaryType",
+    # Base classes
+    "RuntimeExecutor",
+    "SubprocessRuntime",
+    # Configuration
+    "DEFAULT_TIMEOUT",
+    "LEAN_TIMEOUT",
+    "JULIA_TIMEOUT",
+    "R_TIMEOUT",
+    "RUNTIME_CONFIG",
+    # Runtime implementations
+    "PythonRuntime",
+    "JavaScriptRuntime",
+    "BinaryRuntime",
+    "RustRuntime",
+    "CRuntime",
+    "ScriptRuntime",
+    "LeanRuntime",
+    "RRuntime",
+    "JuliaRuntime",
+    "LambdaRuntimeExecutor",
+    # Factory
+    "RuntimeFactory",
+]
+
+# Register RuntimeFactory with Layer 0 loader (Dependency Inversion for INV-383-02)
+try:
+    from clm.layer0.loader import register_runtime_factory
+
+    register_runtime_factory(RuntimeFactory)
+except ImportError:
+    pass

clm/layer1/runtimes/_generated_assertions.py

@@ -0,0 +1,125 @@
+# AUTO-GENERATED FILE — DO NOT EDIT
+# Generated by scripts/generate_constants.py
+# Source: schema/assertion_types.json (single source of truth)
+
+"""
+Auto-generated CLM assertion validators.
+
+These functions implement the cross-language assertion contracts
+defined in schema/assertion_types.json, ensuring identical validation
+behavior in both Python and TypeScript.
+"""
+
+import json
+from typing import Any
+
+
+def assert_result(actual: Any, expected: Any) -> bool:
+    """Exact deep-equality match (assertion_types.json: result)."""
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        return all(
+            k in actual and assert_result(actual[k], v) for k, v in expected.items()
+        )
+    if isinstance(expected, list) and isinstance(actual, list):
+        return len(expected) == len(actual) and all(
+            assert_result(a, e) for a, e in zip(actual, expected, strict=False)
+        )
+    if isinstance(expected, int | float) and isinstance(actual, int | float):
+        return abs(expected - actual) < 1e-6
+    return expected == actual
+
+
+def assert_result_contains(actual: Any, substring: str) -> bool:
+    """Substring match, case-insensitive (assertion_types.json: result_contains)."""
+    actual_str = json.dumps(actual) if not isinstance(actual, str) else actual
+    return substring.lower() in actual_str.lower()
+
+
+def assert_result_type(actual: Any, expected_type: str) -> bool:
+    """Type check (assertion_types.json: result_type)."""
+    type_map: dict[str, type | tuple[type, ...]] = {
+        "object": dict,
+        "string": str,
+        "number": (int, float),
+        "array": list,
+        "boolean": bool,
+    }
+    expected_cls = type_map.get(expected_type)
+    if expected_cls is None:
+        return False
+    return isinstance(actual, expected_cls)
+
+
+def assert_schema(actual: Any, schema: dict) -> bool:
+    """Structural validation (assertion_types.json: schema).
+
+    Validates that actual matches the given schema structure:
+    - type: expected type
+    - required: list of required keys
+    - properties: nested schemas for object properties
+    - minLength/maxLength: for strings/arrays
+    - min/max: for numbers
+    - enum: list of allowed values
+    - items: schema for array items
+    """
+    if not isinstance(schema, dict):
+        return True
+
+    # Type check
+    if "type" in schema:
+        if not assert_result_type(actual, schema["type"]):
+            return False
+
+    # Required keys
+    if "required" in schema and isinstance(actual, dict):
+        for key in schema["required"]:
+            if key not in actual:
+                return False
+
+    # Properties
+    if "properties" in schema and isinstance(actual, dict):
+        for key, sub_schema in schema["properties"].items():
+            if key in actual:
+                if not assert_schema(actual[key], sub_schema):
+                    return False
+
+    # Length checks (strings/arrays)
+    if "minLength" in schema and hasattr(actual, "__len__"):
+        if len(actual) < schema["minLength"]:
+            return False
+    if "maxLength" in schema and hasattr(actual, "__len__"):
+        if len(actual) > schema["maxLength"]:
+            return False
+    if "length" in schema and hasattr(actual, "__len__"):
+        if len(actual) != schema["length"]:
+            return False
+
+    # Numeric range
+    if "min" in schema and isinstance(actual, int | float):
+        if actual < schema["min"]:
+            return False
+    if "max" in schema and isinstance(actual, int | float):
+        if actual > schema["max"]:
+            return False
+
+    # Enum
+    if "enum" in schema:
+        if actual not in schema["enum"]:
+            return False
+
+    # Array items
+    if "items" in schema and isinstance(actual, list):
+        for item in actual:
+            if not assert_schema(item, schema["items"]):
+                return False
+
+    return True
+
+
+# Map assertion type names to validator functions
+ASSERTION_VALIDATORS = {
+    "result": assert_result,
+    "result_contains": assert_result_contains,
+    "result_type": assert_result_type,
+    "schema": assert_schema,
+}

clm/layer1/runtimes/_generated_types.py

@@ -0,0 +1,42 @@
+# AUTO-GENERATED FILE — DO NOT EDIT
+# Generated by scripts/generate_constants.py
+# Source: schema/runtime_types.json (single source of truth)
+
+"""Auto-generated runtime type constants from schema/runtime_types.json."""
+
+from enum import Enum
+
+
+class RuntimeType(Enum):
+    """Supported runtime types (auto-generated from schema/runtime_types.json)."""
+
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    RUST = "rust"
+    C = "c"
+    WASM = "wasm"
+    LEAN = "lean"
+    R = "r"
+    JULIA = "julia"
+    LLM = "llm"
+    LAMBDA = "lambda"
+    NETWORK = "network"
+    LOADER = "loader"
+    COLLECTION_LOADER = "collection_loader"
+
+
+RUNTIME_ALIASES: dict[str, str] = {
+    "node": "javascript",
+    "js": "javascript",
+    "py": "python",
+    "ts": "javascript",
+}
+"""Maps shorthand names to canonical runtime IDs."""
+
+
+def resolve_runtime_alias(name: str) -> str:
+    """Resolve a runtime name through shared aliases.
+
+    E.g., 'node' -> 'javascript', 'py' -> 'python'.
+    """
+    return RUNTIME_ALIASES.get(name.lower(), name.lower())

clm/layer1/runtimes/base.py

@@ -0,0 +1,265 @@
+"""
+Base classes for runtime executors.
+
+This module provides the core abstractions for runtime execution:
+- RuntimeType: Enum of supported runtimes
+- BoundaryType: Enum for intrinsic/extrinsic execution
+- RuntimeExecutor: Abstract base class for all runtimes
+- SubprocessRuntime: Base class for runtimes that execute via subprocess
+"""
+
+import logging
+import subprocess
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Configuration Constants
+# ─────────────────────────────────────────────────────────────────────────────
+from clm.cross_cutting.config.config_constants import (
+    PTR_COMMAND_CHECK_TIMEOUT_SECS,
+    PTR_DEFAULT_TIMEOUT_SECS,
+    PTR_JULIA_TIMEOUT_SECS,
+    PTR_LEAN_TIMEOUT_SECS,
+    PTR_R_TIMEOUT_SECS,
+)
+from clm.layer0.model.card import MCard
+
+try:
+    from clm.cross_cutting.config.settings import settings as _settings
+
+    DEFAULT_TIMEOUT = _settings.ptr.default_timeout
+    LEAN_TIMEOUT = _settings.ptr.lean_timeout
+    JULIA_TIMEOUT = _settings.ptr.julia_timeout
+    R_TIMEOUT = _settings.ptr.r_timeout
+except ImportError:
+    DEFAULT_TIMEOUT = PTR_DEFAULT_TIMEOUT_SECS
+    LEAN_TIMEOUT = PTR_LEAN_TIMEOUT_SECS
+    JULIA_TIMEOUT = PTR_JULIA_TIMEOUT_SECS
+    R_TIMEOUT = PTR_R_TIMEOUT_SECS
+
+# Global Runtime Registry
+RUNTIME_REGISTRY = {}
+
+
+def register_runtime(runtime_id: str):
+    """Decorator to register a runtime executor in the global registry."""
+
+    def wrapper(cls):
+        RUNTIME_REGISTRY[runtime_id] = cls
+        return cls
+
+    return wrapper
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Runtime Types (shared source of truth: schema/runtime_types.json)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _load_shared_runtime_types() -> tuple[list[str], dict[str, str], dict]:
+    """Load runtime type IDs, aliases, and explicit configs from the shared JSON registry.
+
+    Returns (runtime_ids, aliases, runtime_configs) tuple.
+    Falls back to empty collections if file is not found.
+    """
+    import json
+    from pathlib import Path
+
+    module_dir = Path(__file__).resolve().parent
+    # Calculate project root: runtimes -> core -> ptr -> mcard -> project root
+    project_root = module_dir.parents[3]
+    schema_path = project_root / "schema" / "runtime_types.json"
+
+    if schema_path.exists():
+        try:
+            with open(schema_path, encoding="utf-8") as f:
+                data = json.load(f)
+            ids = [r["id"] for r in data.get("runtimes", [])]
+            aliases = data.get("aliases", {})
+
+            # Build runtime config
+            configs = {}
+            for r in data.get("runtimes", []):
+                configs[r["id"]] = {
+                    "command": r.get("command"),
+                    "version_flag": r.get("version_flag", "--version"),
+                    "run_flag": r.get("run_flag"),
+                    "eval_flag": r.get("eval_flag"),
+                }
+            return ids, aliases, configs
+        except Exception as e:
+            logging.warning("Failed to load runtime_types.json: %s", e)
+    return [], {}, {}
+
+
+# Load shared data at import time
+_SHARED_RUNTIME_IDS, SHARED_ALIASES, RUNTIME_CONFIG = _load_shared_runtime_types()
+
+
+class RuntimeType(Enum):
+    """Supported runtime types.
+
+    IDs are aligned with schema/runtime_types.json (single source of truth).
+    """
+
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    RUST = "rust"
+    C = "c"
+    WASM = "wasm"
+    LEAN = "lean"
+    R = "r"
+    JULIA = "julia"
+    LLM = "llm"
+    LAMBDA = "lambda"
+    LOADER = "loader"
+    COLLECTION_LOADER = "collection_loader"
+
+
+def resolve_runtime_alias(name: str) -> str:
+    """Resolve a runtime name through shared aliases.
+
+    E.g., 'node' -> 'javascript', 'py' -> 'python', 'js' -> 'javascript'.
+    Returns the canonical runtime ID.
+    """
+    return SHARED_ALIASES.get(name.lower(), name.lower())
+
+
+class BoundaryType(Enum):
+    """CLM execution boundary type.
+
+    Determines how a CLM is executed relative to the caller:
+
+    INTRINSIC: Process runs within the same execution context (same process).
+               Best for lightweight, trusted operations. No serialization overhead.
+
+    EXTRINSIC: Process runs in a separate process/container/network.
+               Required for untrusted code, language isolation, or distributed execution.
+               Requires serialization/deserialization of inputs and outputs.
+    """
+
+    INTRINSIC = "intrinsic"
+    EXTRINSIC = "extrinsic"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Base Executor Classes
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class RuntimeExecutor(ABC):
+    """Abstract base class for runtime executors.
+
+    Each executor manages a specific runtime environment (Python, JavaScript, etc.)
+    and can operate in either intrinsic or extrinsic boundary mode.
+    """
+
+    # Default boundary type for this runtime
+    boundary_type: BoundaryType = BoundaryType.INTRINSIC
+
+    def __init__(self):
+        self.logger = logging.getLogger(self.__class__.__name__)
+
+    @abstractmethod
+    def execute(
+        self, concrete_impl: dict[str, Any], target: MCard, context: dict[str, Any]
+    ) -> Any:
+        """Execute the operation in the runtime environment."""
+        pass
+
+    @abstractmethod
+    def validate_environment(self) -> bool:
+        """Check if runtime environment is available."""
+        pass
+
+    def get_boundary_type(self) -> BoundaryType:
+        """Get the boundary type for this runtime.
+
+        Override in subclasses to provide dynamic boundary determination.
+        """
+        return self.boundary_type
+
+    def is_intrinsic(self) -> bool:
+        """Check if this runtime operates within the same process."""
+        return self.get_boundary_type() == BoundaryType.INTRINSIC
+
+    def is_extrinsic(self) -> bool:
+        """Check if this runtime operates in a separate process."""
+        return self.get_boundary_type() == BoundaryType.EXTRINSIC
+
+    def get_runtime_status(self) -> dict[str, Any]:
+        """Get detailed status information about this runtime."""
+        return {
+            "available": self.validate_environment(),
+            "version": None,
+            "command": self.__class__.__name__.replace("Runtime", "").lower(),
+            "details": "",
+        }
+
+
+class SubprocessRuntime(RuntimeExecutor):
+    """
+    Base class for runtimes that execute via subprocess.
+    Reduces duplication across Rust/C/Lean/R/Julia.
+
+    Note: Subprocess runtimes are EXTRINSIC - they run in separate processes.
+    """
+
+    # Subprocess runtimes are extrinsic by default
+    boundary_type: BoundaryType = BoundaryType.EXTRINSIC
+
+    runtime_name: str = ""
+    command: str | None = None
+    version_flag: str = "--version"
+    timeout: int = DEFAULT_TIMEOUT
+
+    def _run_subprocess(
+        self,
+        cmd: list[str],
+        target: MCard,
+        context: dict,
+        timeout: int | None = None,
+    ) -> str:
+        """Execute subprocess and return output or error string."""
+        try:
+            result = subprocess.run(
+                cmd,
+                input=target.get_content(),
+                capture_output=True,
+                timeout=timeout or self.timeout,
+            )
+            if result.returncode != 0:
+                return f"Error: {self.runtime_name} execution failed: {result.stderr.decode()}"
+            return result.stdout.decode("utf-8")
+        except subprocess.TimeoutExpired:
+            return f"Error: {self.runtime_name} execution timed out"
+        except (OSError, subprocess.SubprocessError) as e:
+            return f"Error executing {self.runtime_name}: {e}"
+
+    def _check_command(
+        self, cmd: Any, flag: str, timeout: int = PTR_COMMAND_CHECK_TIMEOUT_SECS
+    ) -> bool:
+        """Check if a command is available."""
+        try:
+            if isinstance(cmd, list):
+                args = cmd + [flag]
+            else:
+                args = [cmd, flag]
+
+            result = subprocess.run(args, capture_output=True, timeout=timeout)
+            if result.returncode != 0:
+                self.logger.debug(
+                    f"Command check failed for {args}: {result.stderr.decode()}"
+                )
+                return False
+            return True
+        except (OSError, subprocess.SubprocessError) as e:
+            self.logger.debug(f"Exception checking command {cmd}: {e}")
+            return False
+
+    def validate_environment(self) -> bool:
+        if not self.command:
+            return True  # No command needed (e.g., compiled binaries)
+        return self._check_command(self.command, self.version_flag)

clm/layer1/runtimes/binary.py

@@ -0,0 +1,101 @@
+"""
+Binary-based runtimes (Rust, C).
+
+These runtimes execute compiled binaries via subprocess.
+"""
+
+import json
+from typing import Any
+
+from clm.layer0.model.card import MCard
+
+from .base import RUNTIME_CONFIG, SubprocessRuntime, register_runtime
+
+
+class BinaryRuntime(SubprocessRuntime):
+    """Base class for runtimes that execute compiled binaries."""
+
+    def execute(self, impl: dict[str, Any], target: MCard, ctx: dict[str, Any]) -> Any:
+        binary_path = impl.get("binary_path")
+        if not binary_path:
+            return f"Error: No {self.runtime_name} binary path provided"
+        return self._run_subprocess([binary_path, json.dumps(ctx)], target, ctx)
+
+
+@register_runtime("rust")
+@register_runtime("wasm")
+class RustRuntime(BinaryRuntime):
+    """Rust runtime executor - executes via compiled binary or WASM."""
+
+    runtime_name = "Rust"
+    command = RUNTIME_CONFIG.get("rust", {}).get("command")
+
+    def execute(self, impl: dict[str, Any], target: MCard, ctx: dict[str, Any]) -> Any:
+        wasm_module = impl.get("wasm_module")
+        if wasm_module:
+            return self._execute_wasm(wasm_module, target, ctx)
+        return super().execute(impl, target, ctx)
+
+    def _execute_wasm(self, wasm_path: str, target: MCard, ctx: dict) -> Any:
+        """Execute WASM module using wasmtime."""
+        try:
+            import os
+            import tempfile
+
+            from wasmtime import Linker, Module, Store, WasiConfig
+
+            store = Store()
+            wasi = WasiConfig()
+            wasi.inherit_stdout()
+            wasi.inherit_stderr()
+            wasi.argv = ["program_name", json.dumps(ctx)]
+
+            # Create temp files for stdin/stdout
+            with tempfile.NamedTemporaryFile(mode="w+", delete=False) as tmp_in:
+                tmp_in.write(target.get_content().decode("utf-8"))
+                in_path = tmp_in.name
+
+            with tempfile.NamedTemporaryFile(mode="w+", delete=False) as tmp_out:
+                out_path = tmp_out.name
+
+            wasi.stdin_file = in_path
+            wasi.stdout_file = out_path
+            store.set_wasi(wasi)
+
+            linker = Linker(store.engine)
+            linker.define_wasi()
+
+            module = Module.from_file(store.engine, wasm_path)
+            instance = linker.instantiate(store, module)
+            instance.exports(store)["_start"](store)
+
+            with open(out_path) as f:
+                output = f.read()
+
+            os.unlink(in_path)
+            os.unlink(out_path)
+            return output
+
+        except ImportError as e:
+            return f"Error: wasmtime python library not installed or load failed: {e}"
+        except (OSError, RuntimeError, ValueError) as e:
+            return f"Error executing WASM: {e}"
+
+    def validate_environment(self) -> bool:
+        rust_ok = self._check_command("rustc", "--version")
+        wasm_ok = False
+        try:
+            import importlib.util
+
+            wasm_ok = importlib.util.find_spec("wasmtime") is not None
+        except ImportError:
+            pass
+        return rust_ok or wasm_ok
+
+
+@register_runtime("c")
+class CRuntime(BinaryRuntime):
+    """C runtime executor - executes via compiled binary."""
+
+    runtime_name = "C"
+    command = None  # No compiler check needed