clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/rule_evaluator.py

@@ -0,0 +1,251 @@
+"""Hermetic Rule and Expression Evaluator (Sprint 394 / DEL-394-02).
+
+Safe, sandboxed AST-based expression evaluator for Hoare pre- and post-condition invariants.
+Supports CEL-like syntax, arithmetic, comparisons, logic, and bound MCard scope access.
+Strict Zero-Host-Authority: Does NOT invoke Python eval() or exec().
+
+Acceptance Criteria:
+- AC-394-02-01: Evaluates expressions across boolean, numeric, string, collection attributes in <500µs.
+- AC-394-02-02: Rejects arbitrary code execution, imports, or attributes outside bound scope.
+- AC-394-02-03: Descriptive diagnostics pinpointing exact sub-expression evaluating to false.
+
+Layer 0 module (zero dependencies on L1-L5).
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any
+
+
+class RuleEvaluationError(Exception):
+    """Raised when an expression cannot be safely parsed or evaluated."""
+
+
+class ScopeWrapper:
+    """Read-only wrapper providing dot-notation access to dictionaries and objects."""
+
+    def __init__(self, data: Any) -> None:
+        self._data = data
+
+    def __getattr__(self, name: str) -> Any:
+        if isinstance(self._data, dict):
+            if name in self._data:
+                val = self._data[name]
+                return ScopeWrapper(val) if isinstance(val, (dict, list)) else val
+            raise AttributeError(f"Field '{name}' not found in scope")
+        if hasattr(self._data, name):
+            val = getattr(self._data, name)
+            return ScopeWrapper(val) if isinstance(val, (dict, list)) else val
+        raise AttributeError(f"Attribute '{name}' not found on object {type(self._data)}")
+
+    def __getitem__(self, item: Any) -> Any:
+        if isinstance(self._data, (dict, list)):
+            val = self._data[item]
+            return ScopeWrapper(val) if isinstance(val, (dict, list)) else val
+        raise KeyError(f"Cannot index non-collection: {type(self._data)}")
+
+    def __contains__(self, item: Any) -> bool:
+        if isinstance(self._data, (dict, list, set, str)):
+            return item in self._data
+        return False
+
+    def __len__(self) -> int:
+        if hasattr(self._data, "__len__"):
+            return len(self._data)
+        return 0
+
+    def unwrap(self) -> Any:
+        return self._data
+
+
+class SafeRuleEvaluator:
+    """Safe AST-based evaluator for CEL-style invariant expressions."""
+
+    ALLOWED_FUNCTIONS = {
+        "len": len,
+        "str": str,
+        "int": int,
+        "float": float,
+        "bool": bool,
+        "min": min,
+        "max": max,
+        "sum": sum,
+    }
+
+    @classmethod
+    def evaluate(cls, expression: str, context: dict[str, Any]) -> bool:
+        """Evaluate a boolean expression against the given context dictionary."""
+        val = cls.eval_expr(expression, context)
+        return bool(val)
+
+    @classmethod
+    def eval_expr(cls, expression: str, context: dict[str, Any]) -> Any:
+        """Evaluate an arbitrary safe arithmetic or boolean expression."""
+        clean_expr = cls._preprocess_syntax(expression)
+        try:
+            tree = ast.parse(clean_expr, mode="eval")
+        except SyntaxError as e:
+            raise RuleEvaluationError(f"Syntax error in expression '{expression}': {e}") from e
+
+        wrapped_ctx = {k: ScopeWrapper(v) if isinstance(v, (dict, list)) else v for k, v in context.items()}
+        return cls._eval_node(tree.body, wrapped_ctx)
+
+    @classmethod
+    def _preprocess_syntax(cls, expr: str) -> str:
+        """Normalize CEL/JS operators (&&, ||, !) into Python-compatible operators."""
+        res = expr.replace("&&", " and ").replace("||", " or ")
+        res = re.sub(r"!\s*(?!=)", "not ", res)
+        return res
+
+    @classmethod
+    def _eval_node(cls, node: ast.AST, ctx: dict[str, Any]) -> Any:
+        """Recursively evaluate an AST node within the hermetic sandbox."""
+        if isinstance(node, ast.Constant):
+            return node.value
+
+        if isinstance(node, ast.Name):
+            name = node.id
+            if name in ctx:
+                val = ctx[name]
+                return val.unwrap() if isinstance(val, ScopeWrapper) else val
+            if name in cls.ALLOWED_FUNCTIONS:
+                return cls.ALLOWED_FUNCTIONS[name]
+            if name in ("true", "True"):
+                return True
+            if name in ("false", "False"):
+                return False
+            if name in ("null", "None"):
+                return None
+            raise RuleEvaluationError(f"Undefined identifier in rule: '{name}'")
+
+        if isinstance(node, ast.Attribute):
+            val = cls._eval_node(node.value, ctx)
+            attr = node.attr
+            if isinstance(val, ScopeWrapper):
+                val = val.unwrap()
+            if isinstance(val, dict):
+                if attr in val:
+                    return val[attr]
+                if attr == "contains":
+                    return lambda item: item in val
+                raise RuleEvaluationError(f"Attribute '{attr}' not found in dict")
+            if attr == "contains" and isinstance(val, (list, tuple, set, str)):
+                return lambda item: item in val
+            if hasattr(val, attr):
+                attr_val = getattr(val, attr)
+                # Disallow dunder methods / internal attributes
+                if attr.startswith("_"):
+                    raise RuleEvaluationError(f"Access to private attribute '{attr}' is forbidden")
+                return attr_val
+            raise RuleEvaluationError(f"Attribute '{attr}' does not exist on {type(val)}")
+
+        if isinstance(node, ast.Subscript):
+            val = cls._eval_node(node.value, ctx)
+            if isinstance(val, ScopeWrapper):
+                val = val.unwrap()
+            idx = cls._eval_node(node.slice, ctx)
+            try:
+                return val[idx]
+            except (KeyError, IndexError, TypeError) as e:
+                raise RuleEvaluationError(f"Subscript error: {e}") from e
+
+        if isinstance(node, ast.UnaryOp):
+            operand = cls._eval_node(node.operand, ctx)
+            if isinstance(node.op, ast.Not):
+                return not operand
+            if isinstance(node.op, ast.USub):
+                return -operand
+            if isinstance(node.op, ast.UAdd):
+                return +operand
+            raise RuleEvaluationError(f"Unsupported unary operator: {type(node.op)}")
+
+        if isinstance(node, ast.BinOp):
+            left = cls._eval_node(node.left, ctx)
+            right = cls._eval_node(node.right, ctx)
+            if isinstance(left, ScopeWrapper):
+                left = left.unwrap()
+            if isinstance(right, ScopeWrapper):
+                right = right.unwrap()
+
+            if isinstance(node.op, ast.Add):
+                return left + right
+            if isinstance(node.op, ast.Sub):
+                return left - right
+            if isinstance(node.op, ast.Mult):
+                return left * right
+            if isinstance(node.op, ast.Div):
+                return left / right
+            if isinstance(node.op, ast.FloorDiv):
+                return left // right
+            if isinstance(node.op, ast.Mod):
+                return left % right
+            raise RuleEvaluationError(f"Unsupported binary operator: {type(node.op)}")
+
+        if isinstance(node, ast.BoolOp):
+            if isinstance(node.op, ast.And):
+                for val_node in node.values:
+                    if not cls._eval_node(val_node, ctx):
+                        return False
+                return True
+            if isinstance(node.op, ast.Or):
+                for val_node in node.values:
+                    if cls._eval_node(val_node, ctx):
+                        return True
+                return False
+            raise RuleEvaluationError(f"Unsupported boolean operator: {type(node.op)}")
+
+        if isinstance(node, ast.Compare):
+            left = cls._eval_node(node.left, ctx)
+            if isinstance(left, ScopeWrapper):
+                left = left.unwrap()
+            for op, comparator in zip(node.ops, node.comparators):
+                right = cls._eval_node(comparator, ctx)
+                if isinstance(right, ScopeWrapper):
+                    right = right.unwrap()
+
+                res = False
+                if isinstance(op, ast.Eq):
+                    res = (left == right)
+                elif isinstance(op, ast.NotEq):
+                    res = (left != right)
+                elif isinstance(op, ast.Lt):
+                    res = (left < right)
+                elif isinstance(op, ast.LtE):
+                    res = (left <= right)
+                elif isinstance(op, ast.Gt):
+                    res = (left > right)
+                elif isinstance(op, ast.GtE):
+                    res = (left >= right)
+                elif isinstance(op, ast.In):
+                    res = (left in right)
+                elif isinstance(op, ast.NotIn):
+                    res = (left not in right)
+                else:
+                    raise RuleEvaluationError(f"Unsupported comparison operator: {type(op)}")
+
+                if not res:
+                    return False
+                left = right
+            return True
+
+        if isinstance(node, ast.Call):
+            func = cls._eval_node(node.func, ctx)
+            args = [cls._eval_node(arg, ctx) for arg in node.args]
+            # Ensure safe method call
+            if callable(func):
+                return func(*args)
+            raise RuleEvaluationError(f"Object '{func}' is not callable")
+
+        if isinstance(node, ast.List):
+            return [cls._eval_node(elt, ctx) for elt in node.elts]
+
+        if isinstance(node, ast.Dict):
+            return {
+                cls._eval_node(k, ctx): cls._eval_node(v, ctx)
+                for k, v in zip(node.keys, node.values)
+                if k is not None
+            }
+
+        raise RuleEvaluationError(f"Disallowed AST expression element: {type(node).__name__}")

clm/layer0/schema/__init__.py

@@ -0,0 +1,38 @@
+"""Layer 0 Kenotic Schema Package (Sprint 387, DEL-387-02).
+
+Pure static DDL definitions, table specifications, and Empty Schema constants (⊥)
+free from database drivers or active filesystem side-effects.
+"""
+from clm.layer0.schema.ddl import (
+    CANONICAL_TRIAD_DDL,
+    CARD_TABLE_SPEC,
+    EMPTY_SCHEMA_VERSION,
+    HANDLE_HISTORY_SPEC,
+    HANDLE_REGISTRY_SPEC,
+    SQL_CREATE_CARD,
+    SQL_CREATE_HANDLE_HISTORY,
+    SQL_CREATE_HANDLE_REGISTRY,
+    SQL_CREATE_SCHEMA_VERSION,
+    TABLE_CARD,
+    TABLE_HANDLE_HISTORY,
+    TABLE_HANDLE_REGISTRY,
+    TABLE_SCHEMA_VERSION,
+    TableSpec,
+)
+
+__all__ = [
+    "TableSpec",
+    "TABLE_CARD",
+    "TABLE_HANDLE_REGISTRY",
+    "TABLE_HANDLE_HISTORY",
+    "TABLE_SCHEMA_VERSION",
+    "EMPTY_SCHEMA_VERSION",
+    "CARD_TABLE_SPEC",
+    "HANDLE_REGISTRY_SPEC",
+    "HANDLE_HISTORY_SPEC",
+    "SQL_CREATE_CARD",
+    "SQL_CREATE_HANDLE_REGISTRY",
+    "SQL_CREATE_HANDLE_HISTORY",
+    "SQL_CREATE_SCHEMA_VERSION",
+    "CANONICAL_TRIAD_DDL",
+]

clm/layer0/schema/ddl.py

@@ -0,0 +1,97 @@
+"""Static DDL schemas and Empty Schema (⊥) definitions (Sprint 387, INV-01).
+
+Layer 0 Kenotic Purity: Schema definitions are pure static strings and table
+specifications without physical database connections or active disk I/O.
+"""
+from __future__ import annotations
+
+from typing import Final, NamedTuple
+
+# Canonical Table Names across the Sovereign Triad
+TABLE_CARD: Final[str] = "card"
+TABLE_HANDLE_REGISTRY: Final[str] = "handle_registry"
+TABLE_HANDLE_HISTORY: Final[str] = "handle_history"
+TABLE_SCHEMA_VERSION: Final[str] = "schema_version"
+
+# Kenotic Empty Schema (⊥): The triad tables possess zero domain-specific columns.
+# Domain semantics enter purely through content stored in MCards, never schema structure.
+EMPTY_SCHEMA_VERSION: Final[str] = "3.0.3"
+
+
+class TableSpec(NamedTuple):
+    """Declarative specification of an MCard triad table."""
+    name: str
+    columns: tuple[str, ...]
+    primary_key: tuple[str, ...]
+    description: str
+
+
+CARD_TABLE_SPEC = TableSpec(
+    name=TABLE_CARD,
+    columns=("hash", "content", "g_time"),
+    primary_key=("hash",),
+    description="Content-Addressed Storage CAS table (Monad/Exponent).",
+)
+
+HANDLE_REGISTRY_SPEC = TableSpec(
+    name=TABLE_HANDLE_REGISTRY,
+    columns=("handle", "current_hash", "created_at", "updated_at"),
+    primary_key=("handle",),
+    description="Semantic handle mapping mutable names to immutable CAS hashes (Sum/Appetition).",
+)
+
+HANDLE_HISTORY_SPEC = TableSpec(
+    name=TABLE_HANDLE_HISTORY,
+    columns=("id", "handle", "previous_hash", "changed_at", "change_type"),
+    primary_key=("id",),
+    description="Append-only audit trail witnessing all handle transitions (η-conversion).",
+)
+
+# Pure static DDL strings (executable by Layer 2 storage engines)
+SQL_CREATE_CARD: Final[str] = """\
+CREATE TABLE IF NOT EXISTS card (
+    hash TEXT PRIMARY KEY,
+    content BLOB NOT NULL,
+    g_time TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+"""
+
+SQL_CREATE_HANDLE_REGISTRY: Final[str] = """\
+CREATE TABLE IF NOT EXISTS handle_registry (
+    handle TEXT PRIMARY KEY,
+    current_hash TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY (current_hash) REFERENCES card(hash)
+);
+CREATE INDEX IF NOT EXISTS idx_handle_current_hash ON handle_registry(current_hash);
+"""
+
+SQL_CREATE_HANDLE_HISTORY: Final[str] = """\
+CREATE TABLE IF NOT EXISTS handle_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    handle TEXT NOT NULL,
+    previous_hash TEXT NOT NULL,
+    changed_at TEXT NOT NULL,
+    change_type TEXT DEFAULT 'UPDATE',
+    FOREIGN KEY (handle) REFERENCES handle_registry(handle),
+    FOREIGN KEY (previous_hash) REFERENCES card(hash)
+);
+CREATE INDEX IF NOT EXISTS idx_handle_history_handle ON handle_history(handle);
+"""
+
+SQL_CREATE_SCHEMA_VERSION: Final[str] = """\
+CREATE TABLE IF NOT EXISTS schema_version (
+    version TEXT PRIMARY KEY,
+    applied_at TEXT NOT NULL,
+    description TEXT
+);
+"""
+
+# Complete canonical DDL script for the empty schema (Kenosis ⊥)
+CANONICAL_TRIAD_DDL: Final[str] = (
+    SQL_CREATE_CARD
+    + SQL_CREATE_HANDLE_REGISTRY
+    + SQL_CREATE_HANDLE_HISTORY
+    + SQL_CREATE_SCHEMA_VERSION
+)

clm/layer0/templates/abstract.yaml

@@ -0,0 +1,99 @@
+# Abstract Specification Template for CLM
+# This template defines the WHAT dimension - the specification and intent
+
+# Purpose and Intent
+purpose: "Transform input data according to specified requirements"  # Clear description of what this component does (min 10 characters)
+
+# Input Specifications
+inputs:
+  # Define expected inputs with types and constraints
+  # Example:
+  # data:
+  #   type: "string"
+  #   description: "Input data to process"
+  #   constraints:
+  #     min_length: 1
+  #     max_length: 1000
+
+# Output Specifications  
+outputs:
+  # Define expected outputs with types and constraints
+  # Example:
+  # result:
+  #   type: "string"
+  #   description: "Processed output data"
+  #   constraints:
+  #     min_length: 1
+
+# Pre-conditions
+preconditions:
+  # Conditions that must be true before execution
+  # Example:
+  # - "input data is valid UTF-8"
+  # - "system has sufficient memory"
+  # - "required permissions are granted"
+
+# Post-conditions
+postconditions:
+  # Conditions that must be true after execution
+  # Example:
+  # - "output is derived from input"
+  # - "system state remains consistent"
+  # - "no side effects beyond specified outputs"
+
+# Success Criteria
+success_criteria:
+  # Metrics for determining successful execution
+  # Example:
+  # functional:
+  #   - "transformation preserves data integrity"
+  # performance:
+  #   - "execution time < 100ms"
+  # quality:
+  #   - "output meets specification requirements"
+
+# Dependencies
+dependencies:
+  # External dependencies and requirements
+  # Example:
+  # system:
+  #   - "Python 3.9+"
+  # libraries:
+  #   - "yaml"
+  # external:
+  #   - "database connection"
+
+# Constraints and Limitations
+constraints:
+  # Known limitations and constraints
+  # Example:
+  # technical:
+  #   - "maximum input size: 1MB"
+  # operational:
+  #   - "requires internet connectivity"
+  # security:
+  #   - "no access to filesystem"
+
+# Version and Compatibility
+version: "1.0.0"
+compatibility:
+  min_version: "1.0.0"
+  max_version: "2.0.0"
+
+# Tags and Classification
+tags:
+  # Categorization for discovery and organization
+  # Example:
+  # - "data_processing"
+  # - "transformation"
+  # - "validation"
+
+domain: "data_processing"  # Application domain (e.g., "data_processing", "security", "ui")
+
+# Documentation References
+documentation:
+  # Links to additional documentation
+  # Example:
+  # specification: "link_to_spec"
+  # examples: "link_to_examples"
+  # tests: "link_to_tests"