clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/errors.py

@@ -0,0 +1,153 @@
+"""CLM Domain Error Hierarchy (Sprint 175).
+
+Stratified domain exception hierarchy for the CLM Python reference runtime.
+Enforces cause chaining (raise ... from err), zero swallowed exceptions,
+and machine-readable JSON-RPC serialization (to_payload()) for Satori protocol bridges.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+
+class ClmDomainError(Exception):
+    """Base exception for all domain errors within CLM."""
+
+    code: int = 1000
+    category: str = "kernel"
+    is_retriable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+        is_retriable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+        self.is_retriable = is_retriable
+        self.timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        if cause is not None:
+            self.__cause__ = cause
+
+    def to_payload(self) -> dict[str, Any]:
+        """Serialize into a machine-readable JSON-RPC error payload for Satori bridges and Maxwell's Demon."""
+        return {
+            "error": {
+                "code": self.code,
+                "category": self.category,
+                "name": self.__class__.__name__,
+                "message": self.message,
+                "details": self.details,
+                "is_retriable": self.is_retriable,
+                "timestamp": self.timestamp,
+            }
+        }
+
+
+class ExecutionEngineError(ClmDomainError):
+    """Execution error within CLM runtime adapters or runner engines."""
+    code: int = 1500
+    category: str = "kernel.execution"
+
+
+# -- Layer 0: Kenotic Core & Type System ---------------------------
+class TypeLatticeError(ClmDomainError):
+    code = 1100
+    category = "layer0.type_lattice"
+
+
+class StratificationViolationError(TypeLatticeError):
+    code = 1101  # Level N item referencing Level N+1 item
+
+
+class AlgebraicClosedOperatorError(ClmDomainError):
+    code = 1200  # Split, Exclude, Augment, Substitute, Invert, Port failure
+    category = "layer0.algebra"
+
+
+# -- Layer 1: Colored Petri Net VM & VCard Gates -------------------
+class CpnVMError(ClmDomainError):
+    code = 2000
+    category = "layer1.cpn"
+
+
+class TokenConservationViolationError(CpnVMError):
+    code = 2001  # x^T D != 0 Noetherian conservation failure
+
+
+class DeadlockDetectedError(CpnVMError):
+    code = 2002  # Net locked with non-terminal markings
+
+
+class TransitionAclDeniedError(CpnVMError):
+    code = 2003  # Agent DID not authorized to fire transition
+
+
+class VCardGateError(ClmDomainError):
+    code = 2100
+    category = "layer1.vcard"
+
+
+class PreconditionViolationError(VCardGateError):
+    code = 2101  # {P} failed before PCard execution
+
+
+class PostconditionViolationError(VCardGateError):
+    code = 2102  # {Q} failed after PCard execution
+
+
+class VCardEvaluationFaultError(VCardGateError):
+    code = 2103  # Unexpected system/IO fault during gate execution
+
+
+# -- Layer 2: Storage, CAS & Merkle DAG ----------------------------
+class StorageEngineError(ClmDomainError):
+    code = 3000
+    category = "layer2.storage"
+
+
+class ContentHashMismatchError(StorageEngineError):
+    code = 3001  # Computed BLAKE3/SHA-256 does not match MCard key
+
+
+class HandleNotFoundError(StorageEngineError):
+    code = 3002
+
+
+class DatabaseLockTimeoutError(StorageEngineError):
+    code = 3003
+
+
+class ManifestParseError(StorageEngineError):
+    code = 3004
+
+
+# -- Layer 3: Identity, Auth & Network Mesh -------------------------
+class IdentityAuthError(ClmDomainError):
+    code = 4000
+    category = "layer3.auth"
+
+
+class InvalidDidSignatureError(IdentityAuthError):
+    code = 4001
+
+
+class PeerUnreachableError(ClmDomainError):
+    code = 4100
+    category = "layer3.network"
+
+
+# -- Layer 4: CEL, Dispatch & Surface ------------------------------
+class CelEvaluationError(ClmDomainError):
+    code = 5000
+    category = "layer4.cel"
+
+
+class OperationNotFoundError(ClmDomainError):
+    code = 5100
+    category = "layer4.dispatch"

clm/cross_cutting/governance.py

@@ -0,0 +1,331 @@
+"""
+Token Arithmetics Governance Computation Module.
+
+Pure-function module containing the quantitative governance metrics defined in:
+- Architecture §1.7: Inherent Governance
+- Architecture §03: Token Arithmetics — Governance Through Possibility Space Assessment
+- Specifications §04 §2.5: Type-Based Possibility Arithmetics
+
+All functions are side-effect-free and operate exclusively on primitive values.
+No database access, no I/O — just math.
+
+Metrics computed:
+- M (Possibility Magnitude):  |B|^|A| — total combinatorial space
+- N (Governance Narrowing):   1 - |B'|^|A'| / |B|^|A| — policy restrictiveness
+- E (Epiplexity Yield):       S_T / M — structured knowledge per possibility
+- Pi (Product Dependency Count): number of concurrent precondition evaluations
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class GovernanceTelemetry:
+    """Immutable governance telemetry triple (+ product dependency count).
+
+    Embedded as structured metadata within VCard postconditions.
+    """
+
+    possibility_magnitude: float | None = None
+    governance_narrowing: float | None = None
+    epiplexity_yield: float | None = None
+    product_dependency_count: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict for VCard metadata embedding."""
+        result: dict[str, Any] = {}
+        if self.possibility_magnitude is not None:
+            result["M"] = self.possibility_magnitude
+        if self.governance_narrowing is not None:
+            result["N"] = self.governance_narrowing
+        if self.epiplexity_yield is not None:
+            result["E"] = self.epiplexity_yield
+        if self.product_dependency_count is not None:
+            result["Pi"] = self.product_dependency_count
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> GovernanceTelemetry:
+        """Deserialize from a plain dict."""
+        return cls(
+            possibility_magnitude=data.get("M"),
+            governance_narrowing=data.get("N"),
+            epiplexity_yield=data.get("E"),
+            product_dependency_count=data.get("Pi"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Core metric computations
+# ---------------------------------------------------------------------------
+
+
+def compute_possibility_magnitude(inputs_count: int, outputs_count: int) -> float:
+    """Compute Possibility Magnitude M = |B|^|A|.
+
+    Args:
+        inputs_count: |A| — number of input dimensions (Categorical Types).
+        outputs_count: |B| — number of output options (Categorical Types).
+
+    Returns:
+        The total combinatorial space as a float.
+        Returns 1.0 when both counts are 0 (trivial identity transition).
+    """
+    if inputs_count < 0 or outputs_count < 0:
+        raise ValueError(
+            f"Type counts must be non-negative: inputs={inputs_count}, outputs={outputs_count}"
+        )
+    if inputs_count == 0 and outputs_count == 0:
+        return 1.0
+    if outputs_count == 0:
+        return 0.0
+    return float(outputs_count**inputs_count)
+
+
+def compute_governance_narrowing(m_full: float, m_admitted: float) -> float:
+    """Compute Governance Narrowing N = 1 - M_admitted / M_full.
+
+    Args:
+        m_full: |B|^|A| — full possibility magnitude before VCard constraints.
+        m_admitted: |B'|^|A'| — admitted possibility magnitude after VCard constraints.
+
+    Returns:
+        Fraction of the possibility space excluded by governance policy.
+        Range: [0.0, 1.0] where 1.0 means total restriction, 0.0 means no restriction.
+    """
+    if m_full <= 0:
+        return 0.0
+    if m_admitted < 0:
+        raise ValueError(f"Admitted magnitude must be non-negative: {m_admitted}")
+    ratio = m_admitted / m_full
+    # Clamp to [0.0, 1.0] to handle floating-point edge cases
+    return max(0.0, min(1.0, 1.0 - ratio))
+
+
+def compute_epiplexity_yield(structured_knowledge: float, magnitude: float) -> float:
+    """Compute Epiplexity Yield E = S_T / M.
+
+    Uses alignment_score as the proxy for S_T (semantic vector confidence score).
+
+    Args:
+        structured_knowledge: S_T — semantic confidence score (e.g., alignment_score).
+        magnitude: M — possibility magnitude computed during PREP.
+
+    Returns:
+        Ratio of structured knowledge extracted per possibility explored.
+        Returns 0.0 when magnitude is 0 (no possibilities to explore).
+    """
+    if magnitude <= 0:
+        return 0.0
+    return structured_knowledge / magnitude
+
+
+# ---------------------------------------------------------------------------
+# CLM spec extraction helpers
+# ---------------------------------------------------------------------------
+
+
+def extract_type_counts_from_clm(clm_spec: dict[str, Any]) -> tuple[int, int]:
+    """Extract |A| and |B| from a parsed CLM abstract_spec.
+
+    Looks for typed inputs/outputs in the CLM YAML structure:
+    - abstract_spec.inputs → list of input type descriptors → |A|
+    - abstract_spec.outputs → list of output type descriptors → |B|
+
+    Args:
+        clm_spec: Parsed CLM YAML as a dict (the full PCard content).
+
+    Returns:
+        Tuple of (inputs_count, outputs_count). Returns (0, 0) if the CLM
+        spec does not contain typed inputs/outputs (graceful degradation).
+    """
+    abstract = clm_spec.get("abstract_spec", {})
+    if not abstract:
+        # Try alternative key names
+        abstract = clm_spec.get("abstract", {})
+
+    inputs = abstract.get("inputs", [])
+    outputs = abstract.get("outputs", [])
+
+    # Handle both list and dict formats
+    inputs_count = len(inputs) if isinstance(inputs, list | dict) else 0
+    outputs_count = len(outputs) if isinstance(outputs, list | dict) else 0
+
+    return (inputs_count, outputs_count)
+
+
+def extract_admitted_counts_from_vcard(
+    clm_spec: dict[str, Any],
+    vcard_constraints: dict[str, Any] | None,
+) -> tuple[int, int]:
+    """Extract |A'| and |B'| — the admitted subsets after VCard policy application.
+
+    The admitted counts are derived by intersecting the CLM's full type space
+    with the VCard precondition constraints. If no constraints are specified,
+    the admitted space equals the full space (N = 0, no narrowing).
+
+    Args:
+        clm_spec: Parsed CLM YAML.
+        vcard_constraints: VCard precondition constraints (may be None).
+
+    Returns:
+        Tuple of (admitted_inputs, admitted_outputs).
+    """
+    full_a, full_b = extract_type_counts_from_clm(clm_spec)
+
+    if not vcard_constraints:
+        return (full_a, full_b)
+
+    # Check for explicit admitted type lists in VCard constraints
+    admitted_inputs = vcard_constraints.get("admitted_inputs")
+    admitted_outputs = vcard_constraints.get("admitted_outputs")
+
+    # If constraints specify admitted subsets, use their counts
+    a_prime = (
+        len(admitted_inputs) if isinstance(admitted_inputs, list | dict) else full_a
+    )
+    b_prime = (
+        len(admitted_outputs) if isinstance(admitted_outputs, list | dict) else full_b
+    )
+
+    # Check for exclusion lists (alternative constraint format)
+    excluded_inputs = vcard_constraints.get("excluded_inputs")
+    excluded_outputs = vcard_constraints.get("excluded_outputs")
+
+    if isinstance(excluded_inputs, list) and admitted_inputs is None:
+        a_prime = max(0, full_a - len(excluded_inputs))
+    if isinstance(excluded_outputs, list) and admitted_outputs is None:
+        b_prime = max(0, full_b - len(excluded_outputs))
+
+    return (a_prime, b_prime)
+
+
+def count_product_dependencies(clm_spec: dict[str, Any]) -> int:
+    """Count the Product Dependency Count (Pi).
+
+    Pi = number of concurrent precondition evaluations required for
+    transition firing. Derived from the CLM's preconditions list.
+
+    Args:
+        clm_spec: Parsed CLM YAML.
+
+    Returns:
+        Number of precondition evaluations (minimum 1 for any valid CLM).
+    """
+    abstract = clm_spec.get("abstract_spec", {}) or clm_spec.get("abstract", {})
+    preconditions = abstract.get("preconditions", [])
+
+    if isinstance(preconditions, list):
+        return max(1, len(preconditions))
+    if isinstance(preconditions, dict):
+        return max(1, len(preconditions))
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# High-level orchestration
+# ---------------------------------------------------------------------------
+
+
+def compute_prep_governance(
+    clm_spec: dict[str, Any],
+    vcard_constraints: dict[str, Any] | None = None,
+) -> GovernanceTelemetry:
+    """Compute governance metrics available during the PREP phase.
+
+    Called after CLM verification succeeds. Computes M, N, and Pi.
+    E (Epiplexity Yield) is deferred to the POST phase.
+
+    Args:
+        clm_spec: Parsed CLM YAML spec.
+        vcard_constraints: Optional VCard precondition constraints.
+
+    Returns:
+        GovernanceTelemetry with M, N, Pi populated (E = None).
+    """
+    try:
+        a, b = extract_type_counts_from_clm(clm_spec)
+
+        if a == 0 and b == 0:
+            # CLM spec lacks typed inputs/outputs → graceful degradation
+            logger.debug(
+                "[GOVERNANCE] CLM spec has no typed inputs/outputs; "
+                "governance metrics set to None."
+            )
+            return GovernanceTelemetry()
+
+        m_full = compute_possibility_magnitude(a, b)
+
+        a_prime, b_prime = extract_admitted_counts_from_vcard(
+            clm_spec, vcard_constraints
+        )
+        m_admitted = compute_possibility_magnitude(a_prime, b_prime)
+
+        narrowing = compute_governance_narrowing(m_full, m_admitted)
+        pi = count_product_dependencies(clm_spec)
+
+        logger.info(
+            f"[GOVERNANCE] PREP metrics: M={m_full}, N={narrowing:.4f}, Pi={pi} "
+            f"(|A|={a}, |B|={b}, |A'|={a_prime}, |B'|={b_prime})"
+        )
+
+        return GovernanceTelemetry(
+            possibility_magnitude=m_full,
+            governance_narrowing=narrowing,
+            product_dependency_count=pi,
+        )
+
+    except Exception:
+        logger.warning(
+            "[GOVERNANCE] Failed to compute PREP governance metrics", exc_info=True
+        )
+        return GovernanceTelemetry()
+
+
+def compute_post_governance(
+    prep_telemetry: GovernanceTelemetry,
+    alignment_score: float | None,
+) -> GovernanceTelemetry:
+    """Compute the final governance telemetry including Epiplexity Yield.
+
+    Called during the POST phase after execution and alignment scoring.
+    Uses alignment_score as the proxy for S_T (semantic confidence).
+
+    Args:
+        prep_telemetry: GovernanceTelemetry from the PREP phase.
+        alignment_score: The directional alignment score (proxy for S_T).
+
+    Returns:
+        Complete GovernanceTelemetry with all four metrics.
+    """
+    if alignment_score is None or prep_telemetry.possibility_magnitude is None:
+        return prep_telemetry
+
+    try:
+        epiplexity = compute_epiplexity_yield(
+            alignment_score, prep_telemetry.possibility_magnitude
+        )
+
+        logger.info(
+            f"[GOVERNANCE] POST metrics: E={epiplexity:.6f} "
+            f"(S_T={alignment_score}, M={prep_telemetry.possibility_magnitude})"
+        )
+
+        return GovernanceTelemetry(
+            possibility_magnitude=prep_telemetry.possibility_magnitude,
+            governance_narrowing=prep_telemetry.governance_narrowing,
+            epiplexity_yield=epiplexity,
+            product_dependency_count=prep_telemetry.product_dependency_count,
+        )
+
+    except Exception:
+        logger.warning(
+            "[GOVERNANCE] Failed to compute POST governance metrics", exc_info=True
+        )
+        return prep_telemetry

clm/cross_cutting/guards.py

@@ -0,0 +1,41 @@
+"""RAII Resource Guards for Process Descriptors and Temporary Storage (Sprint 178).
+
+Ensures deterministic cleanup of redirected file descriptors and temporary directories.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+from contextlib import contextmanager
+from typing import Any, Generator
+
+
+@contextmanager
+def fd_redirect_guard(
+    stdout: Any | None = None,
+    stderr: Any | None = None,
+) -> Generator[None, None, None]:
+    """RAII guard that redirects stdout and stderr, guaranteeing restoration on exit."""
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+    try:
+        if stdout is not None:
+            sys.stdout = stdout
+        if stderr is not None:
+            sys.stderr = stderr
+        yield
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+
+@contextmanager
+def temp_dir_guard(prefix: str = "clm_tmp_") -> Generator[str, None, None]:
+    """RAII temporary directory manager with guaranteed recursive cleanup even on exceptions."""
+    tmp_path = tempfile.mkdtemp(prefix=prefix)
+    try:
+        yield tmp_path
+    finally:
+        shutil.rmtree(tmp_path, ignore_errors=True)