clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/context.py

@@ -0,0 +1,122 @@
+"""Runtime context container for the CLM environment (Sprint 176).
+
+Provides thread-safe, fiber-isolated execution scoping via contextvars.ContextVar,
+eliminating process-global os.environ mutations while preserving 100% backward compatibility.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import os
+from dataclasses import dataclass, field
+from typing import Any, Generator
+
+_CURRENT_CONTEXT: contextvars.ContextVar[CLMContext | None] = contextvars.ContextVar(
+    "clm_current_context", default=None
+)
+
+
+@dataclass
+class CLMContext:
+    """Unified runtime context container holding storage, configuration, and execution flags.
+
+    Implements Cordis-style monadic scoping (current, scope, isolate) to guarantee
+    zero residual global environment mutations.
+    """
+
+    root: str
+    db: Any | None = None
+    zero_fs: bool = False
+    repo: Any | None = field(default=None)
+    petri_kenotic: bool = False
+    runner: str = "rust"
+    active_agent_did: str | None = None
+    hash_algorithm: str = "blake3"
+    custom_flags: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.repo is None and self.db is not None:
+            try:
+                import sys
+                target = "clm.layer2.storage"
+                mod = sys.modules.get(target)
+                if mod is None:
+                    __import__(target)
+                    mod = sys.modules.get(target)
+                if mod is not None:
+                    repo_cls = getattr(mod, "CLMRepository", None)
+                    if repo_cls:
+                        self.repo = repo_cls(self.db, self.root)
+            except Exception:
+                pass
+
+    @property
+    def clm_root(self) -> str:
+        """Alias for root directory."""
+        return self.root
+
+    @classmethod
+    def current(cls) -> CLMContext:
+        """Retrieve the context bound to the current thread/fiber, or bootstrap defaults from environment."""
+        ctx = _CURRENT_CONTEXT.get()
+        if ctx is None:
+            return cls.create_default()
+        return ctx
+
+    @classmethod
+    def create_default(cls, root: str | None = None) -> CLMContext:
+        """Create a default CLMContext without binding to thread local."""
+        root_dir = root or os.environ.get("CLM_ROOT", os.getcwd())
+        return cls(
+            root=root_dir,
+            zero_fs=os.environ.get("CLM_ZERO_FS", "").lower() in ("true", "1"),
+            petri_kenotic=os.environ.get("CLM_PETRI_KENOTIC", "").lower() in ("true", "1"),
+            runner=os.environ.get("CLM_RUNNER", "rust"),
+            hash_algorithm=os.environ.get("CLM_HASH_ALGO", "blake3"),
+        )
+
+    @contextlib.contextmanager
+    def scope(self) -> Generator[CLMContext, None, None]:
+        """Bind this context to the current thread/task scope, restoring previous on exit."""
+        token = _CURRENT_CONTEXT.set(self)
+        try:
+            yield self
+        finally:
+            _CURRENT_CONTEXT.reset(token)
+
+    def isolate(self, **overrides: Any) -> CLMContext:
+        """Create a child isolated context with specific overrides without mutating parent state."""
+        params: dict[str, Any] = {
+            "root": self.root,
+            "db": self.db,
+            "zero_fs": self.zero_fs,
+            "repo": self.repo,
+            "petri_kenotic": self.petri_kenotic,
+            "runner": self.runner,
+            "active_agent_did": self.active_agent_did,
+            "hash_algorithm": self.hash_algorithm,
+            "custom_flags": self.custom_flags.copy(),
+        }
+        params.update(overrides)
+        return CLMContext(**params)
+
+    def to_env_dict(self) -> dict[str, str]:
+        """Export context flags as an environment dictionary for safe subprocess passing."""
+        env = os.environ.copy()
+        env["CLM_ROOT"] = self.root
+        env["CLM_ZERO_FS"] = "true" if self.zero_fs else "false"
+        env["CLM_PETRI_KENOTIC"] = "true" if self.petri_kenotic else "false"
+        env["CLM_RUNNER"] = self.runner
+        env["CLM_HASH_ALGO"] = self.hash_algorithm
+        if self.active_agent_did:
+            env["CLM_AGENT_DID"] = self.active_agent_did
+        for k, v in self.custom_flags.items():
+            env[f"CLM_FLAG_{k.upper()}"] = str(v)
+        return env
+
+
+# Backward and forward compatibility alias
+EvaluationContext = CLMContext
+
+__all__ = ["CLMContext", "EvaluationContext"]

clm/layer0/db.py

@@ -0,0 +1,160 @@
+"""Deprecated backward-compatibility facade for Tri-Database Engine (Sprint 387, INV-01, INV-09, INV-10).
+
+Layer 0 Kenotic Purity: Physical database storage, drivers, pools, and repositories
+have been relocated to `clm.layer2.storage`.
+Layer 0 defines only abstract protocols (TriDatabaseEngineProtocol, CardRepositoryProtocol)
+and static schemas (`clm.layer0.schema`).
+
+All active production callers must import from `clm.layer2.storage` directly.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import warnings
+from typing import Any, Protocol, runtime_checkable
+
+from clm.layer0.exceptions import CLMError, DatabaseError, KenoticPurityViolationError
+
+# =============================================================================
+# PEP 544 Structural Protocols (Pure Layer 0 Contracts)
+# =============================================================================
+
+@runtime_checkable
+class TriDatabaseEngineProtocol(Protocol):
+    """Protocol for low-level Tri-Database driver operations."""
+
+    def execute(self, pillar: str, sql: str, params: list[Any] | None = None) -> str:
+        """Execute SQL query against the designated pillar."""
+        ...
+
+
+@runtime_checkable
+class CardRepositoryProtocol(Protocol):
+    """Protocol for MCard and semantic handle persistence."""
+
+    def has_card(self, hash_val: str, pillar: str) -> bool:
+        """Check if an MCard exists in the CAS by content hash."""
+        ...
+
+    def get_card_content(self, hash_val: str, pillar: str) -> str | None:
+        """Retrieve MCard content from the CAS by content hash."""
+        ...
+
+    def save_card(self, hash_val: str, content: str, pillar: str, timestamp: str | None = None, replace: bool = False) -> None:
+        """Persist an MCard to the CAS."""
+        ...
+
+    def save_card_and_handle(self, handle_name: str, hash_val: str, content: str, pillar: str, timestamp: str | None = None, replace: bool = True) -> None:
+        """Persist an MCard and update the semantic handle pointer."""
+        ...
+
+    def resolve_handle_hash(self, handle_name: str, pillar: str = "content_memory") -> str:
+        """Resolve a semantic handle to its current content hash."""
+        ...
+
+    def resolve_handle_content(self, handle_name: str, pillar: str = "content_memory") -> str:
+        """Resolve a semantic handle to its current content string."""
+        ...
+
+
+# =============================================================================
+# Backward-Compatibility Delegation Facade
+# =============================================================================
+
+_warned_symbols: set[str] = set()
+
+
+def _warn_deprecated(symbol: str) -> None:
+    if symbol not in _warned_symbols and os.environ.get("CLM_ZERO_FS", "").lower() != "true":
+        warnings.warn(
+            f"clm.layer0.db (symbol: {symbol}) is deprecated as part of Layer 0 Kenotic Purification. "
+            "Import from clm.layer2.storage instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        _warned_symbols.add(symbol)
+
+
+__all__ = [
+    "TriDatabaseEngineProtocol",
+    "CardRepositoryProtocol",
+    "CLMDB",
+    "CLMRepository",
+    "CardCollection",
+    "ClmDbPool",
+    "RepositoryBase",
+    "BitemporalMixin",
+    "HyperlinkMixin",
+    "savepoint",
+    "DisposableList",
+    "reset_shared_socket",
+    "init_tridb",
+    "memorize_mcard",
+    "resolve_handle_hash",
+    "resolve_handle_content",
+    "register_handle",
+    "resolve_handle_hash_at",
+    "resolve_handle_content_at",
+    "parse_yaml_mcard",
+    "_ENGINES",
+    "_SHARED_SOCKET",
+    "DatabaseError",
+    "CLMError",
+    "KenoticPurityViolationError",
+    "resolve_clm_path",
+    "get_bash_command",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in (
+        "CLMDB",
+        "CLMRepository",
+        "CardCollection",
+        "ClmDbPool",
+        "RepositoryBase",
+        "BitemporalMixin",
+        "HyperlinkMixin",
+        "savepoint",
+        "DisposableList",
+        "reset_shared_socket",
+        "init_tridb",
+        "memorize_mcard",
+        "resolve_handle_hash",
+        "resolve_handle_content",
+        "register_handle",
+        "resolve_handle_hash_at",
+        "resolve_handle_content_at",
+        "parse_yaml_mcard",
+        "_ENGINES",
+        "_SHARED_SOCKET",
+    ):
+        _warn_deprecated(name)
+        target = "clm.layer2.storage"
+        mod = sys.modules.get(target)
+        if mod is None:
+            __import__(target)
+            mod = sys.modules.get(target)
+        if mod is not None:
+            return getattr(mod, name)
+
+    if name in ("DatabaseError", "CLMError", "KenoticPurityViolationError"):
+        target_exc = "clm.layer0.exceptions"
+        mod = sys.modules.get(target_exc)
+        if mod is None:
+            __import__(target_exc)
+            mod = sys.modules.get(target_exc)
+        if mod is not None:
+            return getattr(mod, name)
+
+    if name in ("resolve_clm_path", "get_bash_command"):
+        target_utils = "clm.layer0.utils"
+        mod = sys.modules.get(target_utils)
+        if mod is None:
+            __import__(target_utils)
+            mod = sys.modules.get(target_utils)
+        if mod is not None:
+            return getattr(mod, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

clm/layer0/exceptions.py

@@ -0,0 +1,73 @@
+from clm.cross_cutting.errors import (
+    AlgebraicClosedOperatorError,
+    CelEvaluationError,
+    ClmDomainError,
+    ContentHashMismatchError,
+    CpnVMError,
+    DatabaseLockTimeoutError,
+    DeadlockDetectedError,
+    ExecutionEngineError,
+    HandleNotFoundError,
+    IdentityAuthError,
+    InvalidDidSignatureError,
+    ManifestParseError,
+    OperationNotFoundError,
+    PeerUnreachableError,
+    PostconditionViolationError,
+    PreconditionViolationError,
+    StorageEngineError,
+    StratificationViolationError,
+    TokenConservationViolationError,
+    TransitionAclDeniedError,
+    TypeLatticeError,
+    VCardEvaluationFaultError,
+    VCardGateError,
+)
+
+# Backward-compatibility aliases
+CLMError = ClmDomainError
+TypeValidationError = TypeLatticeError
+DatabaseError = StorageEngineError
+ExecutionError = ExecutionEngineError
+AlgebraError = AlgebraicClosedOperatorError
+GatewayError = IdentityAuthError
+
+class KenoticPurityViolationError(ClmDomainError):
+    """Raised when an operation in Layer 0 violates Kenotic Purity (e.g. physical disk I/O under CLM_ZERO_FS)."""
+    pass
+
+
+__all__ = [
+    "AlgebraError",
+    "AlgebraicClosedOperatorError",
+    "CLMError",
+    "CelEvaluationError",
+    "ClmDomainError",
+    "ContentHashMismatchError",
+    "CpnVMError",
+    "DatabaseError",
+    "DatabaseLockTimeoutError",
+    "DeadlockDetectedError",
+    "ExecutionEngineError",
+    "ExecutionError",
+    "GatewayError",
+    "HandleNotFoundError",
+    "IdentityAuthError",
+    "InvalidDidSignatureError",
+    "KenoticPurityViolationError",
+    "ManifestParseError",
+    "OperationNotFoundError",
+    "PeerUnreachableError",
+    "PostconditionViolationError",
+    "PreconditionViolationError",
+    "StorageEngineError",
+    "StratificationViolationError",
+    "TokenConservationViolationError",
+    "TransitionAclDeniedError",
+    "TypeLatticeError",
+    "TypeValidationError",
+    "VCardEvaluationFaultError",
+    "VCardGateError",
+]
+
+

clm/layer0/fibration.py

@@ -0,0 +1,106 @@
+r"""Grothendieck Fibration Category: Process -> MCard.
+Canonical Path: kernel/scripts/clm/layer0/fibration.py
+Deliverable: DEL-254-01 / DEL-254-03
+
+Formalizes the total category `Process = \int P` over the base category `MCard`.
+Each object in Process is a pair `(M, F)` where:
+- `M \in MCard`: Immutable spatial carrier resting state in content-addressed storage (CAS).
+- `F \in Fiber(M)`: Active cordis execution fiber equipped with an unwinding stack of
+  reversible side-effects (`DisposableList`).
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Any, Callable
+
+from clm.cross_cutting.domain_models import MCard
+
+_target = "clm.layer2.fiber"
+_mod = sys.modules.get(_target)
+if _mod is None:
+    __import__(_target)
+    _mod = sys.modules.get(_target)
+DisposableList = _mod.DisposableList
+
+
+class FibrationError(Exception):
+    """Base error for Fibration axiom violations or unwinding failures."""
+    pass
+
+
+class ProcessObject:
+    r"""An object in the Total Category Process (\int P).
+
+    Represents the coupled pair (M, F) with execution fiber state.
+    """
+
+    def __init__(
+        self,
+        carrier: MCard,
+        carrier_handle: str | None = None,
+        pcard: Any | None = None,
+    ) -> None:
+        self.carrier = carrier
+        self.carrier_handle = carrier_handle
+        self.disposables = DisposableList()
+        self.pcard = pcard
+        self.created_at = int(time.time() * 1000)
+        self.is_active = True
+
+    def project(self) -> MCard:
+        r"""Projection functor \pi(M, F) = M."""
+        return self.carrier
+
+    def register_disposable(self, disposer: Callable[[], None]) -> None:
+        """Registers a reversible cleanup callback onto the fiber's LIFO stack."""
+        self.disposables.push(disposer)
+
+    @property
+    def pending_disposers_count(self) -> int:
+        """Returns the number of registered disposers awaiting execution."""
+        return len(self.disposables)
+
+    def unwind(self) -> list[Exception]:
+        """Unwinds all registered disposers in strict LIFO order."""
+        return self.disposables.dispose()
+
+    def lift_mutation(self, next_carrier: MCard) -> None:
+        """Executes Cartesian lift of mutation f: M -> M'.
+
+        Unwinds existing fiber disposables in strict LIFO order, then updates the carrier.
+        """
+        errors = self.unwind()
+        if errors:
+            raise FibrationError(f"Disposable unwind failed during lift: {errors}")
+
+        self.carrier = next_carrier
+        self.disposables = DisposableList()
+        self.is_active = True
+
+    def lift_handle_rebind(self, new_handle: str) -> None:
+        """Executes Cartesian lift of handle re-binding."""
+        self.carrier_handle = new_handle
+
+
+def verify_fibration_axioms(
+    initial: ProcessObject,
+    lifted: ProcessObject,
+    target_carrier: MCard,
+) -> None:
+    r"""Validates Grothendieck fibration axioms:
+    1. Base Projection Commutativity: \pi(lift(f)) == cod(f).
+    2. Zero Residual State: Fiber disposables after lift == 0.
+    """
+    # Axiom 1: Base projection commutativity
+    if lifted.project().hash != target_carrier.hash:
+        raise FibrationError(
+            f"Projection commutativity failed: {lifted.project().hash} != {target_carrier.hash}"
+        )
+
+    # Axiom 2: Zero residual state
+    if lifted.pending_disposers_count != 0:
+        raise FibrationError(
+            f"Zero residual state failed: {lifted.pending_disposers_count} disposers remaining"
+        )

clm/layer0/gates.py

@@ -0,0 +1,50 @@
+"""Layer 0: Stateless Kenotic Boolean Gate Predicates (FND X -> 2).
+
+Canonical Path: kernel/scripts/clm/layer0/gates.py
+Parity: Rust `src/layer0/gates.rs`, TypeScript `src/layer0/gates.ts`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GatePredicate:
+    gate_type: str  # 'AlwaysTrue', 'AlwaysFalse', 'Equals', 'NotEquals', 'And', 'Or', 'Not', 'Threshold'
+    config: Any = None
+
+
+def evaluate_gate(predicate: GatePredicate, input_val: Any) -> bool:
+    """Evaluates a gate predicate against an input value in a purely stateless manner."""
+    t = predicate.gate_type
+    if t == "AlwaysTrue":
+        return True
+    elif t == "AlwaysFalse":
+        return False
+    elif t == "Equals":
+        return input_val == predicate.config
+    elif t == "NotEquals":
+        return input_val != predicate.config
+    elif t == "And":
+        preds: list[GatePredicate] = predicate.config
+        return all(evaluate_gate(p, input_val) for p in preds)
+    elif t == "Or":
+        preds = predicate.config
+        return any(evaluate_gate(p, input_val) for p in preds)
+    elif t == "Not":
+        p: GatePredicate = predicate.config
+        return not evaluate_gate(p, input_val)
+    elif t == "Threshold":
+        required: int = predicate.config["required"]
+        preds = predicate.config["predicates"]
+        satisfied = sum(1 for p in preds if evaluate_gate(p, input_val))
+        return satisfied >= required
+    else:
+        raise ValueError(f"Unknown gate type: {t}")
+
+
+def evaluate_gate_set(gates: list[tuple[str, GatePredicate]], state: Any) -> list[tuple[str, bool]]:
+    """Evaluates a list of named gates against an input state."""
+    return [(name, evaluate_gate(pred, state)) for name, pred in gates]

clm/layer0/hash.py

@@ -0,0 +1,80 @@
+"""Layer 0: Stateless Kenotic Cryptographic Hashing.
+
+Normative Reference:
+    docs/spec/20-architecture/system-architecture.md § 1.1 (Universal MCard Ontology)
+    docs/spec/20-architecture/card-triad-architecture.md § 0 (Parameterized Content Hashing, INV-02)
+
+Invariants:
+    INV-02: Cryptographic Content Hashing (BLAKE3 default, SHA-256 fallback).
+    INV-01: Stateless Kenotic Purity (pure memory, zero disk or network I/O).
+
+Parity: Rust `src/layer0/hash.rs`, TypeScript `src/layer0/hash.ts`
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from clm.layer0.utils import pure_python_blake3
+
+BLAKE3_PREFIX = "blake3:"
+SHA256_PREFIX = "sha256:"
+
+
+def _to_bytes(data: bytes | str) -> bytes:
+    if isinstance(data, str):
+        return data.encode("utf-8")
+    return data
+
+
+def compute_blake3(data: bytes | str) -> str:
+    """Compute raw 64-character lowercase hex BLAKE3 digest."""
+    b = _to_bytes(data)
+    try:
+        import blake3  # type: ignore
+        return blake3.blake3(b).hexdigest()
+    except ImportError:
+        return pure_python_blake3(b)
+
+
+def compute_sha256(data: bytes | str) -> str:
+    """Compute raw 64-character lowercase hex SHA-256 digest."""
+    b = _to_bytes(data)
+    return hashlib.sha256(b).hexdigest()
+
+
+def prefixed_hash(data: bytes | str) -> str:
+    """Compute prefixed hash using default algorithm (BLAKE3): 'blake3:<hex>'."""
+    return f"{BLAKE3_PREFIX}{compute_blake3(data)}"
+
+
+def verify_hash(data: bytes | str, expected_hash: str) -> bool:
+    """Verify that data matches expected hash (prefixed or 64-char raw hex)."""
+    b = _to_bytes(data)
+    expected = expected_hash.strip()
+    if expected.startswith(BLAKE3_PREFIX):
+        target = expected[len(BLAKE3_PREFIX):]
+        actual = compute_blake3(b)
+        return hmac.compare_digest(actual.lower(), target.lower())
+    if expected.startswith(SHA256_PREFIX):
+        target = expected[len(SHA256_PREFIX):]
+        actual = compute_sha256(b)
+        return hmac.compare_digest(actual.lower(), target.lower())
+    if len(expected) == 64:
+        actual_b3 = compute_blake3(b)
+        actual_sha = compute_sha256(b)
+        return hmac.compare_digest(actual_b3.lower(), expected.lower()) or hmac.compare_digest(
+            actual_sha.lower(), expected.lower()
+        )
+    return False
+
+
+__all__ = [
+    "BLAKE3_PREFIX",
+    "SHA256_PREFIX",
+    "compute_blake3",
+    "compute_sha256",
+    "prefixed_hash",
+    "verify_hash",
+]