clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/neural_runtime.py

@@ -0,0 +1,221 @@
+"""
+Layer 1: Dual-Tier Neural Runtime (DV-373-04).
+
+Implements the Galois Adjunction between System 1 (Jev-Native Fast Discrete Projection)
+and System 2 (Autoregressive Deliberative LLM):
+    System 1 ⊣ System 2
+
+Features:
+- System 1: Single-pass linear projection π_τ: X -> (U_τ x [0, 1]) over discrete variants.
+  Latency <= 70ms, zero output token costs, 0% type errors by construction.
+- RLCD Calibrated Meet Gate: Admissible(d) = d ∧ 1_{P(d | x) >= 1 - ε}.
+- System 2: Deliberative LLM synthesis with V_pre / V_post verification and Z4 rollback.
+- Automatic escalation: P < 1 - ε collapses to ⊥_uncertainty, deterministically invoking System 2.
+- Emits immutable InferenceMCard instances to the CAS.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from clm.cross_cutting.domain_models import MCard
+from clm.layer1.savepoint_guard import VCardMeetViolation
+
+
+@dataclass
+class DiscreteDecision:
+    """Represents a discrete typed decision produced by System 1 or System 2."""
+
+    variant: str
+    probability: float
+    admissible: bool
+    tier: str  # "system1" | "system2"
+    latency_ms: float
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "variant": self.variant,
+            "probability": round(self.probability, 4),
+            "admissible": self.admissible,
+            "tier": self.tier,
+            "latency_ms": round(self.latency_ms, 2),
+            "metadata": self.metadata,
+        }
+
+
+class System1RuntimeAdapter:
+    """
+    Jev-Native Machine-Level System 1 Runtime Adapter.
+    Performs fast, discrete linear projection onto discrete sub-lattices.
+    """
+
+    def __init__(
+        self,
+        variants: list[str],
+        epsilon: float = 0.05,
+        decision_head: Callable[[Any], tuple[str, float]] | None = None,
+    ) -> None:
+        """
+        Args:
+            variants: Allowed discrete decision variants (e.g. ['APPROVE', 'REJECT', 'ESCALATE'])
+            epsilon: RLCD uncertainty tolerance threshold. 1 - epsilon is the acceptance bar.
+            decision_head: Optional custom linear projection head.
+        """
+        self.variants = variants
+        self.epsilon = epsilon
+        self.acceptance_bar = 1.0 - epsilon
+        self.decision_head = decision_head or self._default_projection
+
+    def _default_projection(self, input_features: Any) -> tuple[str, float]:
+        """Default fast projection simulation (sub-millisecond)."""
+        if isinstance(input_features, dict) and "forced_variant" in input_features:
+            return input_features["forced_variant"], float(input_features.get("forced_prob", 0.99))
+        if self.variants:
+            return self.variants[0], 0.98
+        return "UNKNOWN", 0.5
+
+    def evaluate(self, input_features: Any) -> DiscreteDecision:
+        """
+        Executes single-pass linear projection under RLCD Calibrated Meet Gate:
+            Admissible(d) = d ∧ 1_{P(d | x) >= 1 - ε}
+        """
+        start_time = time.perf_counter()
+        variant, prob = self.decision_head(input_features)
+        latency_ms = (time.perf_counter() - start_time) * 1000.0
+
+        # Enforce MISU: variant must belong to allowed lattice
+        if variant not in self.variants:
+            admissible = False
+        else:
+            admissible = prob >= self.acceptance_bar
+
+        return DiscreteDecision(
+            variant=variant,
+            probability=prob,
+            admissible=admissible,
+            tier="system1",
+            latency_ms=latency_ms,
+            metadata={"epsilon": self.epsilon, "acceptance_bar": self.acceptance_bar},
+        )
+
+
+class System2RuntimeAdapter:
+    """
+    Autoregressive Deliberative LLM Runtime Adapter (System 2).
+    Absorbs mcard/ptr/core/llm/ providers with VCard pre/post validation.
+    """
+
+    def __init__(
+        self,
+        llm_client: Callable[[str, dict[str, Any]], str] | None = None,
+        max_tokens: int = 4096,
+    ) -> None:
+        self.llm_client = llm_client or self._default_mock_llm
+        self.max_tokens = max_tokens
+
+    def _default_mock_llm(self, prompt: str, ctx: dict[str, Any]) -> str:
+        """Default deterministic mock synthesizer."""
+        target_variant = ctx.get("fallback_variant", "APPROVE")
+        return f'{{"decision": "{target_variant}", "rationale": "Deliberated by System 2"}}'
+
+    def evaluate(
+        self,
+        prompt: str,
+        context: dict[str, Any] | None = None,
+        allowed_variants: list[str] | None = None,
+    ) -> DiscreteDecision:
+        """
+        Executes deliberative System 2 reasoning wrapped in V_pre and V_post checks.
+        """
+        start_time = time.perf_counter()
+        ctx = context or {}
+
+        # V_pre: Validate prompt length and token limits
+        if not prompt or len(prompt) > self.max_tokens * 10:
+            raise VCardMeetViolation(f"System 2 V_pre failed: prompt size exceeds limit ({len(prompt)} chars)")
+
+        # Deliberative synthesis
+        raw_output = self.llm_client(prompt, ctx)
+        latency_ms = (time.perf_counter() - start_time) * 1000.0
+
+        # V_post: Validate output conforms to schema
+        import json
+        try:
+            parsed = json.loads(raw_output)
+            variant = parsed.get("decision", "UNKNOWN")
+            rationale = parsed.get("rationale", "")
+        except Exception:
+            variant = raw_output.strip()
+            rationale = "Raw string response"
+
+        variants = allowed_variants or []
+        admissible = variant in variants if variants else True
+
+        if not admissible:
+            raise VCardMeetViolation(
+                f"System 2 V_post failed: variant '{variant}' not in allowed variants {variants}"
+            )
+
+        return DiscreteDecision(
+            variant=variant,
+            probability=1.0,  # System 2 deliberative verdict treated as discrete deterministic
+            admissible=True,
+            tier="system2",
+            latency_ms=latency_ms,
+            metadata={"rationale": rationale, "prompt_length": len(prompt)},
+        )
+
+
+class DualTierNeuralCoordinator:
+    """
+    Galois Adjoint Coordinator between System 1 (Fast Jev) and System 2 (Deliberative LLM).
+    """
+
+    def __init__(
+        self,
+        system1: System1RuntimeAdapter,
+        system2: System2RuntimeAdapter | None = None,
+    ) -> None:
+        self.system1 = system1
+        self.system2 = system2 or System2RuntimeAdapter()
+
+    def decide(
+        self,
+        features: Any,
+        prompt_fallback: str = "Synthesize decision",
+        context: dict[str, Any] | None = None,
+    ) -> tuple[DiscreteDecision, MCard]:
+        """
+        Evaluates System 1 first. If admissible, returns immediately.
+        If System 1 collapses to ⊥_uncertainty, cleanly hands off to System 2.
+        Emits an immutable InferenceMCard to the Sovereign Triad CAS.
+        """
+        s1_decision = self.system1.evaluate(features)
+
+        if s1_decision.admissible:
+            final_decision = s1_decision
+        else:
+            # Deterministic escalation to System 2 via Galois adjoint
+            final_decision = self.system2.evaluate(
+                prompt=prompt_fallback,
+                context=context,
+                allowed_variants=self.system1.variants,
+            )
+
+        # Emit immutable InferenceMCard
+        inference_payload = {
+            "schema_archetype": "InferenceMCard",
+            "decision": final_decision.to_dict(),
+            "timestamp_iso": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "id": f"inf_{uuid.uuid4().hex[:12]}",
+        }
+        mcard = MCard.create(
+            uri=f"inference:{final_decision.variant}",
+            payload=inference_payload,
+            author="did:key:z6MkhaXgBZDvotDkL5257faiz48Z8x28xhr554x4tp4MaEBx",
+        )
+        return final_decision, mcard

clm/layer1/operations/__init__.py

@@ -0,0 +1,123 @@
+"""Operations Module for Python Runtime (Layer 1 Petri / Algebraic Strata).
+========================================================================
+
+Normative Reference:
+    docs/spec/40-behavior/baldwin_monadic_pcard_algebra.md § 0 (Baldwin Modularity Algebra)
+    docs/spec/20-architecture/card-triad-architecture.md § 1.1 (PCard & Dynamic Operators)
+
+Invariants:
+    INV-02: Function-Number Duality (Function ≅ Number†).
+    INV-388-01: Syntactic Closure (preserves abstract_spec, concrete_impl, balanced_exp).
+    INV-388-02: Semantic Closure (produces valid morphisms in Poly(X)).
+
+Implements the 6 Baldwin Modularity Operators:
+- split, substitute, augment, exclude, invert, port.
+"""
+
+from .augment import op_augment, op_insert, op_load_file
+from .base import ExampleRunnerMixin, Operation, OperationRegistry
+from .builtins import (
+    op_arithmetic,
+    op_fetch_url,
+    op_identity,
+    op_invoke_library,
+    op_postcondition_witness,
+    op_precondition_witness,
+    op_session_record,
+    op_string,
+    op_transform,
+)
+from .dispatch import (
+    BALDWIN_OPERATIONS,
+    BaldwinOperationDispatcher,
+    dispatch_baldwin_operation,
+    get_baldwin_registry,
+    register_baldwin_operations,
+    verify_semantic_closure,
+    verify_syntactic_closure,
+)
+from .exclude import op_exclude
+from .handle import (
+    op_handle_prune,
+    op_handle_version,
+)
+from .identity import op_provision_genesis_ca, op_provision_genesis_eoa
+from .invert import op_invert
+from .loader import op_loader
+from .port import op_port
+from .services import (
+    op_static_server,
+    op_websocket_server,
+)
+from .split import op_split
+from .substitute import op_substitute
+
+# Default operation registry with all built-in and Baldwin operations
+DEFAULT_OPERATIONS = {
+    "identity": op_identity,
+    "transform": op_transform,
+    "arithmetic": op_arithmetic,
+    "string_op": op_string,
+    "fetch_url": op_fetch_url,
+    "loader": op_loader,
+    "ingest_files": op_loader,
+    "load_files": op_loader,
+    "session_record": op_session_record,
+    "static_server": op_static_server,
+    "websocket_server": op_websocket_server,
+    "handle_version": op_handle_version,
+    "handle_prune": op_handle_prune,
+    "load_file": op_load_file,
+    "insert": op_insert,
+    "provision_genesis_eoa": op_provision_genesis_eoa,
+    "provision_genesis_ca": op_provision_genesis_ca,
+    "precondition_witness": op_precondition_witness,
+    "postcondition_witness": op_postcondition_witness,
+    "invoke_library": op_invoke_library,
+    # Baldwin Modularity Operators (Sprint 388)
+    "split": op_split,
+    "substitute": op_substitute,
+    "augment": op_augment,
+    "exclude": op_exclude,
+    "invert": op_invert,
+    "port": op_port,
+}
+
+__all__ = [
+    "Operation",
+    "OperationRegistry",
+    "ExampleRunnerMixin",
+    "DEFAULT_OPERATIONS",
+    "BALDWIN_OPERATIONS",
+    "op_identity",
+    "op_transform",
+    "op_arithmetic",
+    "op_string",
+    "op_fetch_url",
+    "op_session_record",
+    "op_static_server",
+    "op_websocket_server",
+    "op_loader",
+    "op_handle_version",
+    "op_handle_prune",
+    "op_load_file",
+    "op_insert",
+    "op_provision_genesis_eoa",
+    "op_provision_genesis_ca",
+    "op_precondition_witness",
+    "op_postcondition_witness",
+    "op_invoke_library",
+    # Baldwin Modularity Operators
+    "op_split",
+    "op_substitute",
+    "op_augment",
+    "op_exclude",
+    "op_invert",
+    "op_port",
+    "dispatch_baldwin_operation",
+    "BaldwinOperationDispatcher",
+    "register_baldwin_operations",
+    "get_baldwin_registry",
+    "verify_syntactic_closure",
+    "verify_semantic_closure",
+]

clm/layer1/operations/augment.py

@@ -0,0 +1,156 @@
+"""
+Augment operations for reading CLM files and inserting MCards.
+
+These are native operations registered with the PythonRuntime's
+DEFAULT_OPERATIONS registry. They implement the two atomic phases
+of the "augment" operator:
+
+  1. load_file  — Read a file from the filesystem and return its content (text or binary).
+  2. insert     — Insert content into a CardCollection as an MCard
+                      and register it under a named handle.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from clm.layer0.model.card import MCard
+
+
+def op_load_file(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Read a file from the filesystem and return its content (text or binary).
+
+    Context params:
+        file_path: Path to the file to read (required).
+    """
+    file_path = ctx.get("file_path", ctx.get("clm_file_path", ""))
+    if not file_path or not str(file_path).strip():
+        return {"success": False, "error": "No file_path provided in context."}
+
+    p = Path(str(file_path).strip()).resolve()
+    if not p.exists():
+        return {"success": False, "error": f"File not found: {p}"}
+
+    with open(p, "rb") as f:
+        content = f.read()
+
+    try:
+        content = content.decode("utf-8")
+    except UnicodeDecodeError:
+        pass  # Keep as bytes for binary files
+
+    return {"success": True, "content": content}
+
+
+def op_insert(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Insert content into a CardCollection as an MCard and register a handle.
+
+    Context params:
+        __input_content__: Raw content or VCard JSON string/bytes to insert.
+        target_db:         Database path (default: meta_functionality.db).
+        handle_name:       Handle to register (default: clm_reserved_words.yaml).
+    """
+    from clm.layer1.protocols import get_store
+
+    raw_input = ctx.get("__input_content__", "")
+    if not raw_input and target:
+        raw_input = target.get_content()
+
+    content = raw_input
+
+    if isinstance(raw_input, bytes):
+        try:
+            decoded = raw_input.decode("utf-8")
+            vcard_data = json.loads(decoded)
+            execution_result = vcard_data.get("execution_result", decoded)
+            if isinstance(execution_result, dict):
+                content = execution_result.get("content", str(execution_result))
+            else:
+                content = execution_result
+        except (UnicodeDecodeError, json.JSONDecodeError, TypeError, AttributeError):
+            content = raw_input
+    else:
+        # Try to extract execution_result from VCard JSON envelope
+        try:
+            vcard_data = json.loads(raw_input)
+            execution_result = vcard_data.get("execution_result", raw_input)
+            if isinstance(execution_result, dict):
+                content = execution_result.get("content", str(execution_result))
+            else:
+                content = execution_result
+        except (json.JSONDecodeError, TypeError, AttributeError):
+            content = raw_input
+
+    target_db = ctx.get("target_db", "meta_functionality.db")
+    handle_name = ctx.get("handle_name", "clm_reserved_words.yaml")
+
+    mcard_obj = MCard(content)
+    db_path = Path.cwd() / target_db
+    collection = get_store(str(db_path))
+    collection.add(mcard_obj)
+
+    try:
+        collection.update_handle(handle_name, mcard_obj)
+        status = "Updated"
+    except Exception:
+        try:
+            collection.add_with_handle(mcard_obj, handle_name)
+            status = "Created"
+        except Exception as e:
+            status = f"Failed to register handle: {e}"
+
+    return {"success": True, "status": status, "hash": mcard_obj.hash}
+
+
+def op_augment(impl: dict[str, Any], target: MCard, ctx: dict[str, Any]) -> dict[str, Any]:
+    """Execute the Baldwin Augment (+) operation.
+
+    Additive Extension: A -> A ⊕ E.
+    Adds a new facet, metadata, or extension step without disturbing existing invariants,
+    preserving triadic syntactic closure.
+
+    Args:
+        impl: Configuration dict for augment:
+              facet (str): Name of the facet or extension.
+              extension (dict): Additional attributes or execution step.
+        target: Target MCard to augment.
+        ctx: Execution context.
+
+    Returns:
+        Dict containing the augmented manifest, new MCard, and closure proof.
+    """
+    import copy
+
+    import yaml
+
+    from clm.layer1.operations.split import _parse_manifest, ensure_triadic_closure
+
+    manifest = _parse_manifest(target)
+    facet = impl.get("facet", ctx.get("facet", "extension"))
+    extension = impl.get("extension", ctx.get("extension", {"augmented": True}))
+
+    updated = copy.deepcopy(manifest)
+    if isinstance(updated.get(facet), dict) and isinstance(extension, dict):
+        updated[facet].update(extension)
+    elif isinstance(updated.get(facet), list) and isinstance(extension, list):
+        updated[facet].extend(extension)
+    else:
+        updated[facet] = extension
+
+    final_manifest = ensure_triadic_closure(updated)
+    yaml_content = yaml.dump(final_manifest, default_flow_style=False)
+    new_card = MCard(yaml_content)
+
+    return {
+        "success": True,
+        "operator": "augment",
+        "facet": facet,
+        "syntactic_closure": True,
+        "manifest": final_manifest,
+        "hash": new_card.hash,
+        "content": yaml_content,
+        "mcard": new_card,
+    }
+
+
+__all__ = ["op_load_file", "op_insert", "op_augment"]

clm/layer1/operations/base.py

@@ -0,0 +1,109 @@
+"""
+Base classes and protocols for operations.
+"""
+
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
+
+from clm.layer0.model.card import MCard
+
+
+@runtime_checkable
+class Operation(Protocol):
+    """Protocol for operation callables.
+
+    All operations must be callable with signature:
+        (impl: Dict, target: MCard, ctx: Dict) -> Any
+    """
+
+    def __call__(self, impl: dict[str, Any], target: MCard, ctx: dict[str, Any]) -> Any:
+        """Execute the operation.
+
+        Args:
+            impl: Concrete implementation configuration from CLM
+            target: The target MCard
+            ctx: Execution context
+
+        Returns:
+            Operation result (type depends on operation)
+        """
+        ...
+
+
+class OperationRegistry:
+    """Registry for operation handlers.
+
+    Provides a centralized place to register and retrieve operations.
+    Supports dynamic registration for extending with custom operations.
+    """
+
+    def __init__(self):
+        self._operations: dict[str, Callable] = {}
+
+    def register(self, name: str, handler: Callable) -> None:
+        """Register an operation handler."""
+        self._operations[name] = handler
+
+    def register_many(self, operations: dict[str, Callable]) -> None:
+        """Register multiple operation handlers at once."""
+        self._operations.update(operations)
+
+    def get(self, name: str) -> Callable | None:
+        """Get an operation handler by name."""
+        return self._operations.get(name)
+
+    def has(self, name: str) -> bool:
+        """Check if an operation is registered."""
+        return name in self._operations
+
+    def list_operations(self) -> list:
+        """List all registered operation names."""
+        return list(self._operations.keys())
+
+
+class ExampleRunnerMixin:
+    """Mixin providing generic example running capability.
+
+    Reduces code duplication in operations that need to run
+    batches of examples and aggregate results.
+    """
+
+    @staticmethod
+    def run_examples(
+        examples: list,
+        executor: Callable[[dict], dict[str, Any]],
+        validator: Callable[[dict[str, Any], dict[str, Any]], bool],
+    ) -> dict[str, Any]:
+        """Run examples through an executor and validate results.
+
+        Args:
+            examples: List of example dicts with 'input' and optionally 'expected_output'
+            executor: Function that takes input_data and returns result dict
+            validator: Function that takes (result, expected) and returns bool
+
+        Returns:
+            Aggregated result with 'success' and 'results' keys
+        """
+        results = []
+        for example in examples:
+            input_data = example.get("input", example)
+
+            # Execute
+            try:
+                result = executor(input_data)
+            except Exception as e:
+                result = {"success": False, "error": str(e)}
+
+            result["example_name"] = example.get("name", "unnamed")
+
+            # Validate against expected if provided
+            expected = example.get("expected_output", {})
+            if expected:
+                result["passed"] = validator(result, expected)
+            else:
+                result["passed"] = result.get("success", False)
+
+            results.append(result)
+
+        all_passed = all(r.get("passed", False) for r in results)
+        return {"success": all_passed, "results": results}