clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/cel_eval.py

@@ -0,0 +1,491 @@
+"""CEL Evaluator — Common Expression Language Evaluator for CLM.
+
+Layer 0 Canonical Path: clm/kernel/scripts/clm/layer0/cel_eval.py
+Provides side-effect-free deterministic evaluation of VCard pre/post constraints,
+gate predicates, field assertions, and RLCD calibrated meet predicates.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class BailVerdict:
+    verdict: str  # "pass" or "bail"
+    reason: str = ""
+    invariant_code: str = ""
+
+    @classmethod
+    def pass_verdict(cls) -> BailVerdict:
+        return cls(verdict="pass")
+
+    @classmethod
+    def bail(cls, reason: str, invariant_code: str = "") -> BailVerdict:
+        return cls(verdict="bail", reason=reason, invariant_code=invariant_code)
+
+
+@dataclass
+class CelEvaluationResult:
+    matched: bool
+    verdict: BailVerdict
+    evaluated_value: Any = None
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict.verdict == "pass"
+
+
+def _is_payload_empty(card: Any) -> bool:
+    if card is None:
+        return True
+    if isinstance(card, dict):
+        if "payload" in card:
+            payload = card["payload"]
+        elif "content" in card:
+            payload = card["content"]
+        else:
+            payload = card
+    else:
+        payload = getattr(card, "payload", getattr(card, "content", None))
+
+    if payload is None:
+        return True
+    if isinstance(payload, (bytes, str)):
+        return len(payload) == 0
+    if isinstance(payload, list):
+        return len(payload) == 0
+
+    # Check payload object / dict
+    if isinstance(payload, dict):
+        kind = payload.get("kind")
+        val = payload.get("value")
+        data = payload.get("data")
+        if kind == "scalar":
+            return val is None or val == ""
+        if kind == "text":
+            return val is None or str(val).strip() == ""
+        if kind == "binary":
+            return data is None or len(data) == 0
+        if kind == "structured":
+            if val is None:
+                return True
+            if isinstance(val, (list, dict)):
+                return len(val) == 0
+        if "kind" not in payload:
+            return len(payload) == 0
+        return val is None or val == ""
+
+    # Attribute-based payload
+    kind = getattr(payload, "kind", None)
+    val = getattr(payload, "value", None)
+    data = getattr(payload, "data", None)
+    if kind == "scalar":
+        return val is None or val == ""
+    if kind == "text":
+        return val is None or str(val).strip() == ""
+    if kind == "binary":
+        return data is None or len(data) == 0
+    if kind == "structured":
+        if val is None:
+            return True
+        if isinstance(val, (list, dict)):
+            return len(val) == 0
+        return False
+    return False
+
+
+def _resolve_context_value(key: str, context: dict) -> Any:
+    key = key.strip()
+    if not key:
+        return None
+
+    # Handle RLCD access e.g., rlcd(decision).confidence or rlcd(decision).is_admissible
+    rlcd_match = re.match(r"^rlcd\(([^)]+)\)\.([a-zA-Z0-9_]+)$", key)
+    if rlcd_match:
+        target_name, prop = rlcd_match.groups()
+        target_obj = _resolve_context_value(target_name, context)
+        if isinstance(target_obj, dict):
+            if prop == "confidence":
+                return float(target_obj.get("confidence", target_obj.get("prob", 0.0)))
+            if prop == "is_admissible":
+                return bool(target_obj.get("is_admissible", target_obj.get("admissible", False)))
+            return target_obj.get(prop)
+        if hasattr(target_obj, prop):
+            return getattr(target_obj, prop)
+        return None
+
+    # Strip optional context. prefix if looking inside context root
+    if key.startswith("context."):
+        clean_key = key[len("context."):]
+        resolved = _resolve_context_value(clean_key, context)
+        if resolved is not None:
+            return resolved
+
+    # Handle context direct lookups
+    parts = key.split(".")
+    curr: Any = context
+    for p in parts:
+        if isinstance(curr, dict):
+            if p in curr:
+                curr = curr[p]
+            elif p.lower() in curr:
+                curr = curr[p.lower()]
+            else:
+                return None
+        elif hasattr(curr, p):
+            curr = getattr(curr, p)
+        elif hasattr(curr, "payload"):
+            payload = curr.payload
+            if isinstance(payload, dict) and p in payload:
+                curr = payload[p]
+            elif hasattr(payload, "value") and isinstance(payload.value, dict) and p in payload.value:
+                curr = payload.value[p]
+            elif hasattr(payload, p):
+                curr = getattr(payload, p)
+            elif hasattr(curr, "metadata") and isinstance(curr.metadata, dict) and p in curr.metadata:
+                curr = curr.metadata[p]
+            else:
+                return None
+        elif hasattr(curr, "metadata") and isinstance(curr.metadata, dict) and p in curr.metadata:
+            curr = curr.metadata[p]
+        else:
+            return None
+    return curr
+
+
+def _compare_values(left: Any, op: str, right: Any) -> bool:
+    try:
+        # Numeric coerce
+        if isinstance(left, (int, float, str)) and isinstance(right, (int, float, str)):
+            try:
+                lf = float(left)
+                rf = float(right)
+                if op == "==":
+                    return math.isclose(lf, rf, rel_tol=1e-6, abs_tol=1e-9)
+                if op == "!=":
+                    return not math.isclose(lf, rf, rel_tol=1e-6, abs_tol=1e-9)
+                if op == "<":
+                    return lf < rf
+                if op == "<=":
+                    return lf <= rf
+                if op == ">":
+                    return lf > rf
+                if op == ">=":
+                    return lf >= rf
+            except (ValueError, TypeError):
+                pass
+
+        # String coerce for booleans
+        if isinstance(right, bool) and isinstance(left, str):
+            left = left.lower() in ("true", "1", "yes")
+        elif isinstance(left, bool) and isinstance(right, str):
+            right = right.lower() in ("true", "1", "yes")
+
+        if op == "==":
+            return left == right
+        if op == "!=":
+            return left != right
+        if op == "<":
+            return left < right
+        if op == "<=":
+            return left <= right
+        if op == ">":
+            return left > right
+        if op == ">=":
+            return left >= right
+    except Exception:
+        return False
+    return False
+
+
+def _parse_scalar_literal(val_str: str) -> Any:
+    val_str = val_str.strip()
+    if val_str.lower() == "true":
+        return True
+    if val_str.lower() == "false":
+        return False
+    if val_str.lower() == "null" or val_str.lower() == "none":
+        return None
+    if (val_str.startswith('"') and val_str.endswith('"')) or (
+        val_str.startswith("'") and val_str.endswith("'")
+    ):
+        return val_str[1:-1]
+    try:
+        if "." in val_str:
+            return float(val_str)
+        return int(val_str)
+    except ValueError:
+        return val_str
+
+
+class _EvaluatorDescriptor:
+    def __get__(self, obj: Any, objtype: type | None = None) -> Any:
+        if obj is None:
+            assert objtype is not None
+            return objtype._evaluate_impl
+        def _instance_evaluate(expr_or_context: Any = None, context: dict | None = None) -> CelEvaluationResult:
+            if isinstance(expr_or_context, str):
+                return objtype._evaluate_impl(expr_or_context, context)
+            ctx = expr_or_context if isinstance(expr_or_context, dict) else (context or {})
+            return objtype._evaluate_impl(obj.expr, ctx)
+        return _instance_evaluate
+
+
+class CelEvaluator:
+    """Canonical CEL (Common Expression Language) evaluator for CLM."""
+
+    def __init__(self, expr: str = "") -> None:
+        self.expr = expr
+
+    def __call__(self, context: dict | None = None) -> CelEvaluationResult:
+        return self.evaluate(context=context)
+
+    evaluate = _EvaluatorDescriptor()
+
+    @classmethod
+    def evaluate_atomic(cls, expr: str, context: dict) -> CelEvaluationResult:
+        expr = expr.strip()
+        lower = expr.lower()
+
+        # 0. Literal constants
+        if lower in ("true", "pass"):
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict(), evaluated_value=True)
+        if lower in ("false", "fail"):
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f'Expression explicitly fails: "{expr}"', expr),
+                evaluated_value=False,
+            )
+
+        # 1. Gate predicates
+        if lower == "gate:payload_nonempty":
+            inp = context.get("input") or context.get("mcard")
+            if inp is None and "payload" in context:
+                inp = {"payload": context["payload"]}
+            if inp is None:
+                return CelEvaluationResult(
+                    matched=True,
+                    verdict=BailVerdict.bail("gate:payload_nonempty failed — no input MCard", expr),
+                )
+            if _is_payload_empty(inp):
+                return CelEvaluationResult(
+                    matched=True,
+                    verdict=BailVerdict.bail("gate:payload_nonempty failed — input payload is empty", expr),
+                )
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+
+        if lower == "gate:result_sealed":
+            out = context.get("output") or context.get("input")
+            if out is None or not getattr(out, "hash", None):
+                return CelEvaluationResult(
+                    matched=True,
+                    verdict=BailVerdict.bail("gate:result_sealed failed — output MCard has no sealed hash", expr),
+                )
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+
+        if lower == "gate:authorized":
+            card = context.get("input")
+            author = ""
+            if isinstance(card, dict):
+                author = str(card.get("author", "") or "")
+            elif card is not None:
+                author = str(getattr(card, "author", "") or "")
+            if not author.startswith("did:"):
+                return CelEvaluationResult(
+                    matched=True,
+                    verdict=BailVerdict.bail("gate:authorized failed — ungrounded DID", expr),
+                )
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+
+        # 2. Metadata field existence: exists:field
+        if lower.startswith("exists:"):
+            field_name = expr[7:].strip()
+            card = context.get("input")
+            has_field = False
+            if isinstance(card, dict):
+                meta = card.get("metadata", {})
+                if isinstance(meta, dict) and field_name in meta or field_name in card:
+                    has_field = True
+            elif card is not None:
+                meta = getattr(card, "metadata", None)
+                if isinstance(meta, dict) and field_name in meta or hasattr(meta, "has") and meta.has(field_name) or hasattr(card, field_name):
+                    has_field = True
+
+            if not has_field and "variables" in context and isinstance(context["variables"], dict):
+                has_field = field_name in context["variables"]
+            if not has_field and field_name in context:
+                has_field = True
+
+            if has_field:
+                return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f'Field "{field_name}" not found in metadata', expr),
+            )
+
+        # 3. Type check: type:kind
+        if lower.startswith("type:"):
+            expected_kind = expr[5:].strip()
+            card = context.get("input")
+            actual_kind = None
+            if isinstance(card, dict):
+                payload = card.get("payload")
+                if isinstance(payload, dict):
+                    actual_kind = payload.get("kind")
+                else:
+                    actual_kind = card.get("kind")
+            elif card is not None:
+                payload = getattr(card, "payload", None)
+                actual_kind = getattr(payload, "kind", None) if payload else None
+                if actual_kind is None and isinstance(payload, dict):
+                    actual_kind = payload.get("kind")
+
+            if actual_kind == expected_kind:
+                return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(
+                    f'Expected payload kind "{expected_kind}", got "{actual_kind}"', expr
+                ),
+            )
+
+        # 4. Built-in size checks e.g. size(str) > 0
+        size_match = re.match(r"^size\(([^)]+)\)\s*(==|!=|<=|>=|<|>)\s*(.*)$", expr)
+        if size_match:
+            var_name, op, right_str = size_match.groups()
+            val = _resolve_context_value(var_name, context)
+            length = len(val) if val is not None and hasattr(val, "__len__") else 0
+            right_val = _parse_scalar_literal(right_str)
+            passed = _compare_values(length, op, right_val)
+            if passed:
+                return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict(), evaluated_value=passed)
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f"Size constraint failed: size({var_name})={length} {op} {right_val}", expr),
+                evaluated_value=passed,
+            )
+
+        # 5. Comparison: leftKey op rightVal
+        comp_match = re.match(r"^([a-zA-Z0-9_.()]+)\s*(==|!=|<=|>=|<|>)\s*(.*)$", expr)
+        if comp_match:
+            left_key, op, right_str = comp_match.groups()
+            left_val = _parse_scalar_literal(left_key)
+            if isinstance(left_val, str) and not (left_key.startswith('"') or left_key.startswith("'")):
+                resolved_left = _resolve_context_value(left_key, context)
+                if resolved_left is not None:
+                    left_val = resolved_left
+                elif left_key not in ("true", "false", "null"):
+                    left_val = None
+
+            right_val = _parse_scalar_literal(right_str)
+            if isinstance(right_val, str) and not (right_str.startswith('"') or right_str.startswith("'")):
+                resolved_right = _resolve_context_value(right_val, context)
+                if resolved_right is not None:
+                    right_val = resolved_right
+
+            result = _compare_values(left_val, op, right_val)
+            if result:
+                return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict(), evaluated_value=result)
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f"Comparison failed: {left_key} ({left_val}) {op} {right_str}", expr),
+                evaluated_value=result,
+            )
+
+        # 6. Boolean identifier / property lookup e.g. "is_valid", "rlcd(decision).is_admissible"
+        val = _resolve_context_value(expr, context)
+        if val is not None:
+            if bool(val):
+                return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict(), evaluated_value=True)
+            return CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f"Boolean expression '{expr}' evaluated to {val}", expr),
+                evaluated_value=False,
+            )
+
+        # Default fallback
+        return CelEvaluationResult(matched=False, verdict=BailVerdict.pass_verdict())
+
+    @classmethod
+    def _evaluate_impl(cls, expr: str, context: dict | None = None) -> CelEvaluationResult:
+        if context is None:
+            context = {}
+        expr = expr.strip()
+        if not expr:
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+
+        # Handle logical AND (&&)
+        if "&&" in expr:
+            parts = [p.strip() for p in expr.split("&&")]
+            for part in parts:
+                res = cls._evaluate_impl(part, context)
+                if not res.passed:
+                    return res
+            return CelEvaluationResult(matched=True, verdict=BailVerdict.pass_verdict())
+
+        # Handle logical OR (||)
+        if "||" in expr:
+            parts = [p.strip() for p in expr.split("||")]
+            last_res = None
+            for part in parts:
+                res = cls._evaluate_impl(part, context)
+                if res.passed:
+                    return res
+                last_res = res
+            return last_res or CelEvaluationResult(
+                matched=True,
+                verdict=BailVerdict.bail(f"All branches of OR failed: {expr}", expr),
+            )
+
+        return cls.evaluate_atomic(expr, context)
+
+    evaluate = _EvaluatorDescriptor()
+
+    @classmethod
+    def evaluate_vcard_meet(
+        cls,
+        input_card: Any,
+        output_card: Any,
+        v_pre: str | list[str] | None = None,
+        v_post: str | list[str] | None = None,
+        context: dict | None = None,
+    ) -> bool:
+        """Evaluates formal lattice meet: T_valid = T_cand ∧ V_pre ∧ V_post.
+
+        Returns True if all preconditions and postconditions hold, else False (collapses to ⊥).
+        """
+        ctx = dict(context or {})
+        ctx["input"] = input_card
+        ctx["output"] = output_card
+
+        pre_list = []
+        if isinstance(v_pre, str):
+            pre_list = [v_pre]
+        elif isinstance(v_pre, list):
+            pre_list = v_pre
+
+        for cond in pre_list:
+            res = cls.evaluate(cond, ctx)
+            if not res.passed:
+                return False
+
+        post_list = []
+        if isinstance(v_post, str):
+            post_list = [v_post]
+        elif isinstance(v_post, list):
+            post_list = v_post
+
+        for cond in post_list:
+            res = cls.evaluate(cond, ctx)
+            if not res.passed:
+                return False
+
+        return True
+
+
+evaluate_vcard_meet = CelEvaluator.evaluate_vcard_meet
+

clm/layer0/codec.py

@@ -0,0 +1,106 @@
+"""Layer 0: Stateless Kenotic Codecs & Canonical Serialization.
+
+Canonical Path: kernel/scripts/clm/layer0/codec.py
+Parity: Rust `src/layer0/codec.rs`, TypeScript `src/layer0/codec.ts`
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import yaml
+
+_B58_ALPHABET = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_B58_MAP = [-1] * 128
+for i, c in enumerate(_B58_ALPHABET):
+    _B58_MAP[c] = i
+
+
+def to_hex(data: bytes) -> str:
+    """Encode bytes to lowercase hexadecimal string."""
+    return data.hex().lower()
+
+
+def from_hex(hex_str: str) -> bytes:
+    """Decode hexadecimal string into bytes."""
+    return bytes.fromhex(hex_str.strip())
+
+
+def to_base58(data: bytes) -> str:
+    """Encode bytes to Base58 string (Bitcoin alphabet)."""
+    zeroes = 0
+    while zeroes < len(data) and data[zeroes] == 0:
+        zeroes += 1
+
+    size = (len(data) - zeroes) * 138 // 100 + 1
+    b58 = bytearray(size)
+
+    for b in data[zeroes:]:
+        carry = b
+        j = 0
+        for k in range(size - 1, -1, -1):
+            if carry == 0 and j >= size:
+                break
+            carry += 256 * b58[k]
+            b58[k] = carry % 58
+            carry //= 58
+            j += 1
+
+    it = 0
+    while it < size and b58[it] == 0:
+        it += 1
+
+    res = "1" * zeroes + "".join(chr(_B58_ALPHABET[d]) for d in b58[it:])
+    return res
+
+
+def from_base58(s: str) -> bytes:
+    """Decode Base58 string into bytes."""
+    clean = s.strip()
+    zeroes = 0
+    while zeroes < len(clean) and clean[zeroes] == "1":
+        zeroes += 1
+
+    size = len(clean) * 733 // 1000 + 1
+    b256 = bytearray(size)
+
+    for ch in clean[zeroes:]:
+        code = ord(ch)
+        if code >= 128 or _B58_MAP[code] == -1:
+            raise ValueError(f"Invalid Base58 character: {ch}")
+        carry = _B58_MAP[code]
+        j = 0
+        for k in range(size - 1, -1, -1):
+            if carry == 0 and j >= size:
+                break
+            carry += 58 * b256[k]
+            b256[k] = carry % 256
+            carry //= 256
+            j += 1
+
+    it = 0
+    while it < size and b256[it] == 0:
+        it += 1
+
+    return bytes(zeroes) + bytes(b256[it:])
+
+
+def _sort_json_value(val: Any) -> Any:
+    if isinstance(val, dict):
+        return {k: _sort_json_value(v) for k, v in sorted(val.items())}
+    if isinstance(val, list):
+        return [_sort_json_value(x) for x in val]
+    return val
+
+
+def canonical_json(val: Any) -> str:
+    """Canonical JSON serialization with recursively sorted keys and no whitespace."""
+    sorted_obj = _sort_json_value(val)
+    return json.dumps(sorted_obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def canonical_yaml(val: Any) -> str:
+    """Canonical YAML serialization."""
+    sorted_obj = _sort_json_value(val)
+    return yaml.safe_dump(sorted_obj, sort_keys=True)