clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/config/settings.py

@@ -0,0 +1,504 @@
+"""
+MCard Unified Settings
+======================
+
+This module provides a single, unified interface for all MCard configuration.
+It organizes settings into logical categories for better discoverability.
+
+Usage:
+    from clm.cross_cutting.config.settings import settings
+
+    # Access database settings
+    db_path = settings.database.path
+
+    # Access API settings
+    port = settings.api.port
+
+    # Access hash settings
+    algorithm = settings.hashing.algorithm
+
+    # Access PTR runtime settings
+    timeout = settings.ptr.default_timeout
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from dotenv import load_dotenv
+
+from .config_constants import (
+    # Hashing
+    ALGORITHM_HIERARCHY,
+    API_KEY_HEADER_NAME,
+    CORS_ORIGINS,
+    DEFAULT_API_KEY,
+    # API
+    DEFAULT_API_PORT,
+    # Knowledge
+    DEFAULT_CONTENT_KNOWLEDGE_DIR,
+    # Database
+    DEFAULT_DB_PATH,
+    # Pool/Timeout
+    DEFAULT_HASH_ALGORITHM,
+    DEFAULT_HASH_CUSTOM_FUNCTION,
+    DEFAULT_HASH_CUSTOM_LENGTH,
+    DEFAULT_HASH_CUSTOM_MODULE,
+    # Identity Configuration
+    DEFAULT_IDENTITY_PROVIDER,
+    DEFAULT_IDENTITY_SPACE_PATH,
+    DEFAULT_LOG_LEVEL,
+    DEFAULT_LOG_PATH,
+    DEFAULT_MAX_FILE_SIZE,
+    DEFAULT_MAX_PROBLEM_TEXT_BYTES,
+    # Pagination
+    DEFAULT_PAGE_SIZE,
+    DEFAULT_POOL_SIZE,
+    DEFAULT_READ_TIMEOUT_SECS,
+    DEFAULT_TIMEOUT,
+    DEFAULT_WRAP_WIDTH_DEFAULT,
+    DEFAULT_WRAP_WIDTH_KNOWN,
+    ENV_API_KEY,
+    ENV_API_PORT,
+    ENV_CONTENT_KNOWLEDGE_DIR,
+    ENV_DB_MAX_CONNECTIONS,
+    # Environment Variable Names
+    ENV_DB_PATH,
+    ENV_DB_TIMEOUT,
+    ENV_DEFAULT_POOL_SIZE,
+    ENV_HASH_ALGORITHM,
+    ENV_HASH_CUSTOM_FUNCTION,
+    ENV_HASH_CUSTOM_LENGTH,
+    ENV_HASH_CUSTOM_MODULE,
+    ENV_IDENTITY_API_ENDPOINT,
+    ENV_IDENTITY_PROVIDER,
+    ENV_IDENTITY_SPACE_PATH,
+    ENV_KNOWLEDGE_VAULT,
+    ENV_MAX_FILE_SIZE,
+    ENV_MAX_PROBLEM_TEXT_BYTES,
+    ENV_READ_TIMEOUT_SECS,
+    ENV_SERVICE_LOG_LEVEL,
+    ENV_TEST_DB_PATH,
+    ENV_WRAP_WIDTH_DEFAULT,
+    ENV_WRAP_WIDTH_KNOWN,
+    HTTP_STATUS_FORBIDDEN,
+    HTTP_STATUS_INTERNAL_SERVER_ERROR,
+    HTTP_STATUS_NOT_FOUND,
+    # HTTP Status
+    HTTP_STATUS_OK,
+    # Logging
+    LOG_DIRECTORY,
+    LOG_FILENAME,
+    MAX_PAGE_SIZE,
+    MIN_PAGE_SIZE,
+    # PTR Timeouts
+    PTR_DEFAULT_TIMEOUT_SECS,
+    PTR_JULIA_TIMEOUT_SECS,
+    PTR_LEAN_TIMEOUT_SECS,
+    PTR_R_TIMEOUT_SECS,
+    SERVER_HOST,
+    TEST_DB_PATH,
+)
+
+
+def _load_default_schema() -> dict:
+    """Load the default database schema lazily to avoid import-time cycles."""
+    from clm.schemas import MCardSchema
+
+    schema = MCardSchema.get_instance()
+    return {
+        "documents": schema.get_table("mcard_fts"),
+        "card": schema.get_table("card"),
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Settings Data Classes
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class DatabaseSettings:
+    """Database-related settings."""
+
+    path: str = DEFAULT_DB_PATH
+    test_path: str = TEST_DB_PATH
+    pool_size: int = DEFAULT_POOL_SIZE
+    timeout: float = DEFAULT_TIMEOUT
+    max_connections: int = DEFAULT_POOL_SIZE
+    schema: dict = field(default_factory=_load_default_schema)
+
+
+@dataclass
+class APISettings:
+    """API server settings."""
+
+    port: int = DEFAULT_API_PORT
+    host: str = SERVER_HOST
+    api_key: str = DEFAULT_API_KEY
+    api_key_header: str = API_KEY_HEADER_NAME
+    cors_origins: list[str] = field(default_factory=lambda: CORS_ORIGINS.copy())
+
+
+@dataclass
+class IdentitySettings:
+    """Identity service and storage settings."""
+
+    provider: str = DEFAULT_IDENTITY_PROVIDER
+    space_path: str = DEFAULT_IDENTITY_SPACE_PATH
+    api_endpoint: str | None = None
+
+
+@dataclass
+class PaginationSettings:
+    """Pagination settings."""
+
+    default_page_size: int = DEFAULT_PAGE_SIZE
+    max_page_size: int = MAX_PAGE_SIZE
+    min_page_size: int = MIN_PAGE_SIZE
+
+
+@dataclass
+class HashingSettings:
+    """Hashing algorithm settings."""
+
+    algorithm: str = DEFAULT_HASH_ALGORITHM
+    custom_module: str = DEFAULT_HASH_CUSTOM_MODULE
+    custom_function: str = DEFAULT_HASH_CUSTOM_FUNCTION
+    custom_length: int = DEFAULT_HASH_CUSTOM_LENGTH
+    hierarchy: dict = field(default_factory=lambda: ALGORITHM_HIERARCHY.copy())
+
+
+@dataclass
+class LoggingSettings:
+    """Logging settings."""
+
+    directory: str = LOG_DIRECTORY
+    filename: str = LOG_FILENAME
+    default_path: str = DEFAULT_LOG_PATH
+    level: str = DEFAULT_LOG_LEVEL
+
+
+@dataclass
+class FileProcessingSettings:
+    """File processing settings."""
+
+    wrap_width_default: int = DEFAULT_WRAP_WIDTH_DEFAULT
+    wrap_width_known: int = DEFAULT_WRAP_WIDTH_KNOWN
+    max_problem_text_bytes: int = DEFAULT_MAX_PROBLEM_TEXT_BYTES
+    read_timeout_secs: float = DEFAULT_READ_TIMEOUT_SECS
+    max_file_size: int = DEFAULT_MAX_FILE_SIZE
+
+
+@dataclass
+class BootstrapSettings:
+    """Bootstrap procedure schema configurations."""
+
+    db_dir: str = "db"
+    manifests_dir: str = "../clm/bootstrap_phases"
+    identity_db_name: str = "agent_identities.db"
+    content_db_name: str = "content_memory.db"
+    log_db_name: str = "execution_log.db"
+    genesis_manifest: str = "00a_phase_a_genesis_identity.yaml"
+    cleanup_manifest: str = "cleanup_procedure.yaml"
+
+
+@dataclass
+class KnowledgeSettings:
+    """Content knowledge source directory configuration."""
+
+    content_knowledge_dir: str = DEFAULT_CONTENT_KNOWLEDGE_DIR
+
+
+@dataclass
+class PTRSettings:
+    """Polynomial Type Runtime settings."""
+
+    # Subprocess timeouts
+    default_timeout: int = PTR_DEFAULT_TIMEOUT_SECS
+    lean_timeout: int = PTR_LEAN_TIMEOUT_SECS
+    julia_timeout: int = PTR_JULIA_TIMEOUT_SECS
+    r_timeout: int = PTR_R_TIMEOUT_SECS
+
+    # Allowed imports for sandboxed Python
+    allowed_imports: dict[str, str] = field(default_factory=dict)
+
+    # Safe builtins for sandbox
+    safe_builtins: set[str] = field(default_factory=set)
+
+    # Runtime command configurations (migrating away from this in Phase 2)
+    runtime_config: dict = field(default_factory=dict)
+
+
+@dataclass
+class HTTPStatus:
+    """HTTP status code constants."""
+
+    OK: int = HTTP_STATUS_OK
+    FORBIDDEN: int = HTTP_STATUS_FORBIDDEN
+    NOT_FOUND: int = HTTP_STATUS_NOT_FOUND
+    INTERNAL_SERVER_ERROR: int = HTTP_STATUS_INTERNAL_SERVER_ERROR
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main Settings Class
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class Settings:
+    """
+    Unified settings container for MCard.
+
+    Provides organized access to all configuration through category-specific
+    properties.
+
+    This is a singleton - use `settings` instance instead of creating new ones.
+    """
+
+    _instance: Optional["Settings"] = None
+    _initialized: bool = False
+
+    def __new__(cls) -> "Settings":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if Settings._initialized:
+            return
+
+        # Load environment variables
+        load_dotenv()
+
+        # Load system configuration yaml
+        self._yaml_config = self._load_system_config_yaml()
+
+        # Initialize category settings
+        self._database = self._init_database_settings()
+        self._identity = self._init_identity_settings()
+        self._api = self._init_api_settings()
+        self._bootstrap = BootstrapSettings()
+        self._knowledge = self._init_knowledge_settings()
+        self._pagination = PaginationSettings()
+        self._hashing = self._init_hashing_settings()
+        self._logging = self._init_logging_settings()
+        self._file_processing = self._init_file_processing_settings()
+        self._ptr = self._init_ptr_settings()
+        self._http_status = HTTPStatus()
+
+        Settings._initialized = True
+
+    def _load_system_config_yaml(self) -> dict:
+        """Load external settings from mcard_system_config.yaml."""
+        candidates = [
+            Path(__file__).parent.parent.parent / "schema" / "mcard_system_config.yaml",
+            Path.cwd() / "schema" / "mcard_system_config.yaml",
+        ]
+        for path in candidates:
+            if path.exists():
+                try:
+                    with open(path, encoding="utf-8") as f:
+                        data = yaml.safe_load(f)
+                        return data.get("settings", {})
+                except Exception:
+                    pass
+        return {}
+
+    def _init_database_settings(self) -> DatabaseSettings:
+        """Initialize database settings from environment and yaml."""
+        return DatabaseSettings(
+            path=os.getenv(ENV_DB_PATH, DEFAULT_DB_PATH),
+            test_path=os.getenv(ENV_TEST_DB_PATH, TEST_DB_PATH),
+            pool_size=int(os.getenv(ENV_DEFAULT_POOL_SIZE, DEFAULT_POOL_SIZE)),
+            timeout=float(os.getenv(ENV_DB_TIMEOUT, DEFAULT_TIMEOUT)),
+            max_connections=int(os.getenv(ENV_DB_MAX_CONNECTIONS, DEFAULT_POOL_SIZE)),
+        )
+
+    def _init_ptr_settings(self) -> PTRSettings:
+        """Initialize PTR settings from loaded schema config."""
+        s_conf = self._yaml_config.get("sandbox", {})
+        t_conf = self._yaml_config.get("timeouts", {})
+
+        # We start migrating away from runtime_config inside python,
+        # but keep an empty dict if someone is holding on to it
+        r_conf = self._yaml_config.get("runtime_config", {})
+
+        return PTRSettings(
+            default_timeout=t_conf.get("default_runtime", PTR_DEFAULT_TIMEOUT_SECS),
+            lean_timeout=t_conf.get("lean_runtime", PTR_LEAN_TIMEOUT_SECS),
+            julia_timeout=t_conf.get("julia_runtime", PTR_JULIA_TIMEOUT_SECS),
+            r_timeout=t_conf.get("r_runtime", PTR_R_TIMEOUT_SECS),
+            allowed_imports=s_conf.get("allowed_imports", {}),
+            safe_builtins=set(s_conf.get("safe_builtins", [])),
+            runtime_config=r_conf,
+        )
+
+    def _init_identity_settings(self) -> IdentitySettings:
+        """Initialize identity settings from environment."""
+        return IdentitySettings(
+            provider=os.getenv(ENV_IDENTITY_PROVIDER, DEFAULT_IDENTITY_PROVIDER),
+            space_path=os.getenv(ENV_IDENTITY_SPACE_PATH, DEFAULT_IDENTITY_SPACE_PATH),
+            api_endpoint=os.getenv(ENV_IDENTITY_API_ENDPOINT),
+        )
+
+    def _init_api_settings(self) -> APISettings:
+        """Initialize API settings from environment."""
+        return APISettings(
+            port=int(os.getenv(ENV_API_PORT, DEFAULT_API_PORT)),
+            api_key=os.getenv(ENV_API_KEY, DEFAULT_API_KEY),
+        )
+
+    def _init_knowledge_settings(self) -> KnowledgeSettings:
+        """Initialize content knowledge settings from environment and config."""
+        val = os.getenv(ENV_KNOWLEDGE_VAULT) or os.getenv(
+            ENV_CONTENT_KNOWLEDGE_DIR,
+            DEFAULT_CONTENT_KNOWLEDGE_DIR,
+        )
+        if val:
+            val = str(Path(val).expanduser().resolve())
+        return KnowledgeSettings(content_knowledge_dir=val)
+
+    def _init_hashing_settings(self) -> HashingSettings:
+        """Initialize hashing settings from environment."""
+        env_algo = None
+        if os.getenv("CLM_HASH_CONFIG"):
+            env_algo = os.getenv("CLM_HASH_CONFIG").split("|")[0].strip().lower()
+        elif os.getenv("CLM_HASH_ALGO"):
+            env_algo = os.getenv("CLM_HASH_ALGO").strip().lower()
+        elif os.getenv(ENV_HASH_ALGORITHM):
+            env_algo = os.getenv(ENV_HASH_ALGORITHM).strip().lower()
+
+        if not env_algo:
+            env_algo = DEFAULT_HASH_ALGORITHM
+
+        return HashingSettings(
+            algorithm=env_algo,
+            custom_module=os.getenv(ENV_HASH_CUSTOM_MODULE, DEFAULT_HASH_CUSTOM_MODULE),
+            custom_function=os.getenv(
+                ENV_HASH_CUSTOM_FUNCTION, DEFAULT_HASH_CUSTOM_FUNCTION
+            ),
+            custom_length=int(
+                os.getenv(ENV_HASH_CUSTOM_LENGTH, DEFAULT_HASH_CUSTOM_LENGTH)
+            ),
+        )
+
+    def _init_logging_settings(self) -> LoggingSettings:
+        """Initialize logging settings from environment."""
+        return LoggingSettings(
+            level=os.getenv(ENV_SERVICE_LOG_LEVEL, DEFAULT_LOG_LEVEL),
+        )
+
+    def _init_file_processing_settings(self) -> FileProcessingSettings:
+        """Initialize file processing settings from environment."""
+        return FileProcessingSettings(
+            wrap_width_default=int(
+                os.getenv(ENV_WRAP_WIDTH_DEFAULT, DEFAULT_WRAP_WIDTH_DEFAULT)
+            ),
+            wrap_width_known=int(
+                os.getenv(ENV_WRAP_WIDTH_KNOWN, DEFAULT_WRAP_WIDTH_KNOWN)
+            ),
+            max_problem_text_bytes=int(
+                os.getenv(ENV_MAX_PROBLEM_TEXT_BYTES, DEFAULT_MAX_PROBLEM_TEXT_BYTES)
+            ),
+            read_timeout_secs=float(
+                os.getenv(ENV_READ_TIMEOUT_SECS, DEFAULT_READ_TIMEOUT_SECS)
+            ),
+            max_file_size=int(os.getenv(ENV_MAX_FILE_SIZE, DEFAULT_MAX_FILE_SIZE)),
+        )
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Properties
+    # ─────────────────────────────────────────────────────────────────────────
+
+    @property
+    def database(self) -> DatabaseSettings:
+        """Database configuration."""
+        return self._database
+
+    @property
+    def identity(self) -> IdentitySettings:
+        """Identity space configuration."""
+        return self._identity
+
+    @property
+    def api(self) -> APISettings:
+        """API server configuration."""
+        return self._api
+
+    @property
+    def bootstrap(self) -> BootstrapSettings:
+        """Bootstrap database logic configuration."""
+        return self._bootstrap
+
+    @property
+    def knowledge(self) -> KnowledgeSettings:
+        """Content knowledge source configuration."""
+        return self._knowledge
+
+    @property
+    def pagination(self) -> PaginationSettings:
+        """Pagination configuration."""
+        return self._pagination
+
+    @property
+    def hashing(self) -> HashingSettings:
+        """Hashing algorithm configuration."""
+        return self._hashing
+
+    @property
+    def logging(self) -> LoggingSettings:
+        """Logging configuration."""
+        return self._logging
+
+    @property
+    def file_processing(self) -> FileProcessingSettings:
+        """File processing configuration."""
+        return self._file_processing
+
+    @property
+    def ptr(self) -> PTRSettings:
+        """Polynomial Type Runtime configuration."""
+        return self._ptr
+
+    @property
+    def http_status(self) -> HTTPStatus:
+        """HTTP status code constants."""
+        return self._http_status
+
+    def reload(self) -> None:
+        """Reload settings from environment (for testing)."""
+        Settings._initialized = False
+        self.__init__()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Singleton Instance
+# ─────────────────────────────────────────────────────────────────────────────
+
+# The canonical settings instance
+settings = Settings()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Module Exports
+# ─────────────────────────────────────────────────────────────────────────────
+
+__all__ = [
+    # Main settings object
+    "settings",
+    "Settings",
+    # Category classes (for type hints)
+    "DatabaseSettings",
+    "IdentitySettings",
+    "APISettings",
+    "BootstrapSettings",
+    "KnowledgeSettings",
+    "PaginationSettings",
+    "HashingSettings",
+    "LoggingSettings",
+    "FileProcessingSettings",
+    "PTRSettings",
+    "HTTPStatus",
+]

clm/cross_cutting/context.py

@@ -0,0 +1,5 @@
+"""Re-export of CLMContext and EvaluationContext (Sprint 176)."""
+
+from clm.layer0.context import CLMContext, EvaluationContext
+
+__all__ = ["CLMContext", "EvaluationContext"]

clm/cross_cutting/domain_models.py

@@ -0,0 +1,55 @@
+"""Pydantic v2 Domain Models for CLM Mathematical Entities (Sprint 176 / Sprint 384).
+
+Canonical definitions have been relocated to clm.layer0.model.card_triad (DEL-384-01).
+This module provides backward-compatible re-exports for all legacy callers (DEL-384-02).
+"""
+
+from __future__ import annotations
+
+from clm.layer0.model.card_triad import (
+    AgentDid,
+    BailVerdict,
+    BooleanPCard,
+    CardModel,
+    ContentHash,
+    CordisCoeffects,
+    DynamicPCard,
+    InvariantPhase,
+    MarkingModel,
+    MCard,
+    PCard,
+    PCardDefinition,
+    PlaceId,
+    PlaceModel,
+    PrimitivePCard,
+    TokenModel,
+    TransitionId,
+    TransitionModel,
+    VCard,
+    compute_canonical_hash,
+    compute_canonical_serialized,
+)
+
+__all__ = [
+    "AgentDid",
+    "BailVerdict",
+    "BooleanPCard",
+    "CardModel",
+    "ContentHash",
+    "CordisCoeffects",
+    "DynamicPCard",
+    "InvariantPhase",
+    "MarkingModel",
+    "MCard",
+    "PCard",
+    "PCardDefinition",
+    "PlaceId",
+    "PlaceModel",
+    "PrimitivePCard",
+    "TokenModel",
+    "TransitionId",
+    "TransitionModel",
+    "VCard",
+    "compute_canonical_hash",
+    "compute_canonical_serialized",
+]

clm/cross_cutting/domain_types.py

@@ -0,0 +1,61 @@
+"""Domain NewTypes and invariant constructors for CLM (Sprint 176).
+
+Defines strongly-typed wrappers for primitive identifiers to prevent cross-assignment errors
+at static analysis time and runtime.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NewType
+
+# Content-addressed hash (raw 64-char hex or algorithm-prefixed e.g. blake3:..., sha256:...)
+ContentHash = NewType("ContentHash", str)
+
+# W3C Decentralized Identifier (e.g. did:key:z6Mku..., did:pkc:ca:...)
+AgentDid = NewType("AgentDid", str)
+
+# Semantic handle identifier (e.g. mcard:kernel:schema, pcard:eval:split)
+HandleName = NewType("HandleName", str)
+
+# Petri Net topology identifiers
+PlaceId = NewType("PlaceId", str)
+TransitionId = NewType("TransitionId", str)
+MarkingHash = NewType("MarkingHash", str)
+
+_HASH_REGEX = re.compile(r"^(?:(blake3|sha256):)?[a-fA-F0-9]{8,64}$")
+_DID_REGEX = re.compile(r"^did:[a-zA-Z0-9_-]+:.+$")
+
+
+def make_content_hash(val: str) -> ContentHash:
+    """Validate and wrap a content-addressed hash string.
+
+    Raises ValueError if string is empty or does not match hex/algorithm-prefixed hash format.
+    """
+    clean = val.strip()
+    if not clean:
+        raise ValueError("ContentHash cannot be empty")
+    if not _HASH_REGEX.match(clean):
+        # Allow existing legacy formats if non-empty, but enforce non-empty
+        if len(clean) < 4:
+            raise ValueError(f"Invalid ContentHash format: '{val}'")
+    return ContentHash(clean)
+
+
+def make_agent_did(val: str) -> AgentDid:
+    """Validate and wrap a W3C DID string.
+
+    Raises ValueError if string does not start with 'did:'.
+    """
+    clean = val.strip()
+    if not clean.startswith("did:") or len(clean) < 5:
+        raise ValueError(f"Invalid DID format: '{val}' (must start with 'did:')")
+    return AgentDid(clean)
+
+
+def make_handle_name(val: str) -> HandleName:
+    """Validate and wrap a semantic handle string."""
+    clean = val.strip()
+    if not clean:
+        raise ValueError("HandleName cannot be empty")
+    return HandleName(clean)

clm/cross_cutting/effects.py

@@ -0,0 +1,67 @@
+"""EffectRegistry — side-effect isolation (Thunk pattern).
+
+Extracted from ``cel_store.py`` in Sprint 132.1. The Thunk pattern is a
+peer of the State monad (CelStore), not a sibling helper bolted onto it.
+
+Side effects (env vars, file I/O, subprocess) are registered here and
+dispatched through the store, not called directly by op handlers.
+This makes them mockable, loggable, and auditable.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class EffectRegistry:
+    """Registry for side-effect handlers (Thunk pattern)."""
+
+    def __init__(self) -> None:
+        self._effects: dict[str, Callable] = {}
+
+    def register(self, name: str, handler: Callable) -> None:
+        self._effects[name] = handler
+
+    def execute(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        handler = self._effects.get(name)
+        if handler is None:
+            raise ValueError(f"Unknown effect: {name}")
+        return handler(*args, **kwargs)
+
+
+def register_default_effects(effects_registry: EffectRegistry) -> None:
+    """Register default side-effect handlers into an EffectRegistry."""
+    import os as _os
+    import shutil as _shutil
+
+    def _write_file_effect(filepath: str, content: str) -> bool:
+        try:
+            _os.makedirs(_os.path.dirname(filepath), exist_ok=True)
+            with open(filepath, "w", encoding="utf-8") as fw:
+                fw.write(content)
+            return True
+        except Exception:
+            return False
+
+    def _run_test_suite_effect(test_path: str, clm_root: str, env: dict | None = None, timeout: int = 300) -> int:
+        import subprocess
+
+        from clm.cross_cutting._test_runner import build_test_command
+        cmd_env = _os.environ.copy()
+        if env:
+            cmd_env.update({k: str(v) for k, v in env.items()})
+        cmd = build_test_command(test_path, clm_root)
+        proc = subprocess.Popen(cmd, env=cmd_env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        try:
+            proc.communicate(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.communicate()
+        return proc.returncode
+
+    effects_registry.register("set_env", lambda var, val: _os.environ.__setitem__(var, val))
+    effects_registry.register("unset_env", lambda var: _os.environ.pop(var, None))
+    effects_registry.register("write_file", _write_file_effect)
+    effects_registry.register("run_test_suite", _run_test_suite_effect)
+    effects_registry.register("copy_file", lambda src, dest: _shutil.copy(src, dest))