clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/arrow_compiler.py

@@ -0,0 +1,525 @@
+"""
+Layer 1: Arrow to Colored Petri Net (CPN) Compiler (DV-373-01).
+
+Compiles Arrow combinators (arr, >>>, first, ***, &&&) into bipartite Colored
+Petri Net topologies operating under the 4-phase PTR lifecycle:
+    prep (P_in -> P_pre) -> exec (P_pre -> P_exec) -> post (P_exec -> P_post) -> seal (P_post -> P_out)
+
+Satisfies:
+- INV-REF-01: Headless Kernel Purity (no browser/DOM imports)
+- INV-REF-02: Single Implementation Home (lives in clm/layer1)
+- Noetherian conservation invariants (x^T · D = 0)
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class VCardGuard:
+    """Represents a pre- or post-condition guard for an Arrow."""
+
+    name: str
+    predicate: Callable[[Any], bool]
+    error_message: str = "VCard guard condition not satisfied"
+
+    def check(self, val: Any) -> bool:
+        try:
+            return bool(self.predicate(val))
+        except Exception:
+            return False
+
+
+class Arrow:
+    """Arrow abstraction for composable computation with VCard sandwich gates."""
+
+    def __init__(
+        self,
+        func: Callable[[Any], Any],
+        name: str = "arrow",
+        v_pre: VCardGuard | list[VCardGuard] | None = None,
+        v_post: VCardGuard | list[VCardGuard] | None = None,
+        agent_did: str | None = None,
+        node_id: str | None = None,
+    ) -> None:
+        self.func = func
+        self.name = name
+        self.node_id = node_id or f"arrow_{uuid.uuid4().hex[:8]}"
+        self.v_pre: list[VCardGuard] = (
+            [v_pre] if isinstance(v_pre, VCardGuard) else (v_pre or [])
+        )
+        self.v_post: list[VCardGuard] = (
+            [v_post] if isinstance(v_post, VCardGuard) else (v_post or [])
+        )
+        self.agent_did = agent_did or "did:key:z6MkhaXgBZDvotDkL5257faiz48Z8x28xhr554x4tp4MaEBx"
+
+    def __call__(self, input_val: Any) -> Any:
+        return self.func(input_val)
+
+    def __rshift__(self, other: Arrow) -> Arrow:
+        """Sequential composition combinator: a1 >>> a2."""
+        return self.compose(self, other)
+
+    @classmethod
+    def arr(
+        cls,
+        func: Callable[[Any], Any],
+        name: str = "arr",
+        v_pre: VCardGuard | list[VCardGuard] | None = None,
+        v_post: VCardGuard | list[VCardGuard] | None = None,
+        agent_did: str | None = None,
+    ) -> Arrow:
+        """Lifts a pure or effectful function into an Arrow."""
+        return cls(func, name=name, v_pre=v_pre, v_post=v_post, agent_did=agent_did)
+
+    @classmethod
+    def compose(cls, first: Arrow, second: Arrow) -> Arrow:
+        """Sequential composition: first >>> second."""
+        composed_name = f"({first.name} >>> {second.name})"
+
+        def composed_fn(x: Any) -> Any:
+            res1 = first(x)
+            return second(res1)
+
+        arrow = cls(
+            composed_fn,
+            name=composed_name,
+            v_pre=first.v_pre,
+            v_post=second.v_post,
+            agent_did=first.agent_did,
+        )
+        arrow._is_composite = True
+        arrow._first = first
+        arrow._second = second
+        return arrow
+
+    def first(self) -> Arrow:
+        """Lifts this Arrow (A -> B) to (A x C -> B x C)."""
+        orig_fn = self.func
+
+        def first_fn(pair: tuple[Any, Any]) -> tuple[Any, Any]:
+            if not isinstance(pair, (tuple, list)) or len(pair) != 2:
+                raise TypeError(f"Arrow.first expects a 2-tuple, got {type(pair)}")
+            a, c = pair[0], pair[1]
+            return (orig_fn(a), c)
+
+        return Arrow(
+            first_fn,
+            name=f"first({self.name})",
+            v_pre=self.v_pre,
+            v_post=self.v_post,
+            agent_did=self.agent_did,
+        )
+
+    def second(self) -> Arrow:
+        """Lifts this Arrow (A -> B) to (C x A -> C x B)."""
+        orig_fn = self.func
+
+        def second_fn(pair: tuple[Any, Any]) -> tuple[Any, Any]:
+            if not isinstance(pair, (tuple, list)) or len(pair) != 2:
+                raise TypeError(f"Arrow.second expects a 2-tuple, got {type(pair)}")
+            c, a = pair[0], pair[1]
+            return (c, orig_fn(a))
+
+        return Arrow(
+            second_fn,
+            name=f"second({self.name})",
+            v_pre=self.v_pre,
+            v_post=self.v_post,
+            agent_did=self.agent_did,
+        )
+
+    def split(self, other: Arrow) -> Arrow:
+        """Parallel product combinator (***): (A -> B) x (C -> D) -> (A x C -> B x D)."""
+        f = self.func
+        g = other.func
+
+        def split_fn(pair: tuple[Any, Any]) -> tuple[Any, Any]:
+            if not isinstance(pair, (tuple, list)) or len(pair) != 2:
+                raise TypeError(f"Arrow.split expects a 2-tuple, got {type(pair)}")
+            return (f(pair[0]), g(pair[1]))
+
+        return Arrow(
+            split_fn,
+            name=f"({self.name} *** {other.name})",
+            agent_did=self.agent_did,
+        )
+
+    def __mul__(self, other: Arrow) -> Arrow:
+        """Operator alias for split (***)."""
+        return self.split(other)
+
+    def fanout(self, other: Arrow) -> Arrow:
+        """Fanout combinator (&&&): A -> (B x C)."""
+        f = self.func
+        g = other.func
+
+        def fanout_fn(x: Any) -> tuple[Any, Any]:
+            return (f(x), g(x))
+
+        return Arrow(
+            fanout_fn,
+            name=f"({self.name} &&& {other.name})",
+            agent_did=self.agent_did,
+        )
+
+    def __and__(self, other: Arrow) -> Arrow:
+        """Operator alias for fanout (&&&)."""
+        return self.fanout(other)
+
+
+@dataclass
+class CPNCompiledNet:
+    """Compiled Colored Petri Net representation of an Arrow or Arrow pipeline."""
+
+    net_id: str
+    places: list[dict[str, Any]]
+    transitions: list[dict[str, Any]]
+    incidence_matrix: list[list[int]]
+    place_index: dict[str, int]
+    transition_index: dict[str, int]
+    entry_place: str
+    exit_place: str
+    arrow: Arrow | None = None
+    steps: list[Arrow] = field(default_factory=list)
+
+    def __call__(self, val: Any) -> Any:
+        """Executes the underlying Arrow computation."""
+        if self.arrow is not None:
+            return self.arrow(val)
+        raise RuntimeError("No executable Arrow attached to CPNCompiledNet")
+
+    def to_dict(self) -> dict[str, Any]:
+        serializable_transitions = []
+        for t in self.transitions:
+            t_copy = dict(t)
+            if "arrow_ref" in t_copy and hasattr(t_copy["arrow_ref"], "name"):
+                t_copy["arrow_ref"] = t_copy["arrow_ref"].name
+            serializable_transitions.append(t_copy)
+
+        return {
+            "net_id": self.net_id,
+            "places": self.places,
+            "transitions": serializable_transitions,
+            "incidence_matrix": self.incidence_matrix,
+            "entry_place": self.entry_place,
+            "exit_place": self.exit_place,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def to_graphviz(self) -> str:
+        """Exports CPN net topology as Graphviz DOT notation."""
+        lines = [f'digraph "{self.net_id}" {{', '  rankdir=LR;', '  node [fontname="Helvetica"];']
+        for p in self.places:
+            pid = p["id"]
+            label = f"{p.get('label', pid)}\\n(tokens={p.get('initial_tokens', 0)})"
+            lines.append(f'  "{pid}" [shape=circle, label="{label}"];')
+        for t in self.transitions:
+            tid = t["id"]
+            label = t.get("label", tid)
+            lines.append(f'  "{tid}" [shape=box, style=filled, fillcolor="#e0e7ff", label="{label}"];')
+        for t in self.transitions:
+            tid = t["id"]
+            for inp in t.get("inputs", []):
+                lines.append(f'  "{inp}" -> "{tid}";')
+            for out in t.get("outputs", []):
+                lines.append(f'  "{tid}" -> "{out}";')
+        lines.append("}")
+        return "\n".join(lines)
+
+    def to_mermaid(self) -> str:
+        """Exports CPN net topology as Mermaid flowchart diagram."""
+        lines = ["graph LR"]
+        for p in self.places:
+            pid = p["id"]
+            label = p.get("label", pid)
+            lines.append(f'  {pid}(("{label}"))')
+        for t in self.transitions:
+            tid = t["id"]
+            label = t.get("label", tid)
+            lines.append(f'  {tid}["{label}"]')
+        for t in self.transitions:
+            tid = t["id"]
+            for inp in t.get("inputs", []):
+                lines.append(f"  {inp} --> {tid}")
+            for out in t.get("outputs", []):
+                lines.append(f"  {tid} --> {out}")
+        return "\n".join(lines)
+
+
+def _flatten_arrow_sequence(arrow: Arrow) -> list[Arrow]:
+    """Flattens a tree of sequentially composed arrows into an ordered list."""
+    if getattr(arrow, "_is_composite", False):
+        return _flatten_arrow_sequence(arrow._first) + _flatten_arrow_sequence(arrow._second)
+    return [arrow]
+
+
+def compile_to_cpn(arrow: Arrow, net_id: str | None = None) -> CPNCompiledNet:
+    """
+    Compiles an Arrow (or sequentially composed Arrow chain) into a Colored Petri Net.
+
+    For each atomic Arrow i in the sequence:
+        Places:
+            P_in_{i}: Input token place
+            P_pre_{i}: Pre-condition satisfied place
+            P_exec_{i}: PCard execution completed place
+            P_post_{i}: Post-condition verified place
+            P_out_{i}: Sealed output place
+        Transitions:
+            T_prep_{i}: Consumes P_in_{i}, verifies identity and V_pre, produces P_pre_{i}
+            T_exec_{i}: Consumes P_pre_{i}, executes PCard, produces P_exec_{i}
+            T_post_{i}: Consumes P_exec_{i}, verifies V_post and Noetherian P-invariant, produces P_post_{i}
+            T_seal_{i}: Consumes P_post_{i}, commits token, produces P_out_{i}
+    Sequential composition joins P_out_{i} with P_in_{i+1}.
+    """
+    net_id = net_id or f"cpn_{uuid.uuid4().hex[:8]}"
+    arrows = _flatten_arrow_sequence(arrow)
+
+    places: list[dict[str, Any]] = []
+    transitions: list[dict[str, Any]] = []
+
+    prev_out_place: str | None = None
+    entry_place: str = ""
+    exit_place: str = ""
+
+    for idx, sub_arr in enumerate(arrows):
+        prefix = f"{net_id}_step_{idx}"
+
+        if idx == 0:
+            in_place = f"{prefix}_p_in"
+            places.append({"id": in_place, "label": f"P_in_{idx}", "initial_tokens": 1})
+            entry_place = in_place
+        else:
+            in_place = prev_out_place
+
+        p_pre = f"{prefix}_p_pre"
+        p_exec = f"{prefix}_p_exec"
+        p_post = f"{prefix}_p_post"
+        p_out = f"{prefix}_p_out"
+
+        places.extend([
+            {"id": p_pre, "label": f"P_pre_{idx}", "initial_tokens": 0},
+            {"id": p_exec, "label": f"P_exec_{idx}", "initial_tokens": 0},
+            {"id": p_post, "label": f"P_post_{idx}", "initial_tokens": 0},
+            {"id": p_out, "label": f"P_out_{idx}", "initial_tokens": 0},
+        ])
+
+        # 4-Phase Transitions
+        t_prep = {
+            "id": f"{prefix}_t_prep",
+            "label": f"Prep ({sub_arr.name})",
+            "inputs": [in_place],
+            "outputs": [p_pre],
+            "phase": "prep",
+            "agent_did": sub_arr.agent_did,
+            "v_pre_count": len(sub_arr.v_pre),
+        }
+        t_exec = {
+            "id": f"{prefix}_t_exec",
+            "label": f"Exec ({sub_arr.name})",
+            "inputs": [p_pre],
+            "outputs": [p_exec],
+            "phase": "exec",
+            "arrow_ref": sub_arr,
+        }
+        t_post = {
+            "id": f"{prefix}_t_post",
+            "label": f"Post ({sub_arr.name})",
+            "inputs": [p_exec],
+            "outputs": [p_post],
+            "phase": "post",
+            "v_post_count": len(sub_arr.v_post),
+        }
+        t_seal = {
+            "id": f"{prefix}_t_seal",
+            "label": f"Seal ({sub_arr.name})",
+            "inputs": [p_post],
+            "outputs": [p_out],
+            "phase": "seal",
+        }
+
+        transitions.extend([t_prep, t_exec, t_post, t_seal])
+        prev_out_place = p_out
+        if idx == len(arrows) - 1:
+            exit_place = p_out
+
+    # Compute Incidence Matrix D = D^+ - D^-
+    place_ids = [p["id"] for p in places]
+    trans_ids = [t["id"] for t in transitions]
+    place_index = {pid: i for i, pid in enumerate(place_ids)}
+    trans_index = {tid: j for j, tid in enumerate(trans_ids)}
+
+    num_p = len(places)
+    num_t = len(transitions)
+    d_matrix = [[0 for _ in range(num_t)] for _ in range(num_p)]
+
+    for j, t in enumerate(transitions):
+        for inp in t.get("inputs", []):
+            i = place_index[inp]
+            d_matrix[i][j] -= 1
+        for out in t.get("outputs", []):
+            i = place_index[out]
+            d_matrix[i][j] += 1
+
+    return CPNCompiledNet(
+        net_id=net_id,
+        places=places,
+        transitions=transitions,
+        incidence_matrix=d_matrix,
+        place_index=place_index,
+        transition_index=trans_index,
+        entry_place=entry_place,
+        exit_place=exit_place,
+        arrow=arrow,
+        steps=arrows,
+    )
+
+
+class PCardResolver:
+    """Resolve PCard references by content hash, CLM handle, or URL (Layer 1).
+
+    The resolver is the bridge between symbolic PCard references stored
+    in PetriNet transitions and the actual PCard MCards in the collection.
+    """
+
+    def __init__(
+        self,
+        collection: Any,
+        trusted_urls: list[str] | None = None,
+        allow_file_refs: bool = True,
+    ) -> None:
+        self.collection = collection
+        self.trusted_urls = trusted_urls or []
+        self.allow_file_refs = allow_file_refs
+        self._resolution_cache: dict[str, str] = {}
+        self._recursion_guard: set[str] = set()
+
+    def resolve_to_hash(self, ref: str) -> str | None:
+        """Resolve a PCard reference to a content hash."""
+        if not ref:
+            return None
+
+        if ref in self._resolution_cache:
+            return self._resolution_cache[ref]
+
+        resolved = None
+
+        if self._is_hash_ref(ref):
+            resolved = self._resolve_hash(ref)
+        elif ref.startswith("/") or "/" in ref:
+            resolved = self._resolve_handle(ref)
+        elif ref.startswith("file://"):
+            resolved = self._resolve_file(ref)
+        elif ref.startswith("http://") or ref.startswith("https://"):
+            resolved = self._resolve_url(ref)
+        else:
+            resolved = self._resolve_hash(ref)
+
+        if resolved:
+            self._resolution_cache[ref] = resolved
+
+        return resolved
+
+    @staticmethod
+    def _is_hash_ref(ref: str) -> bool:
+        if ref.startswith("sha256:") or ref.startswith("sha512:"):
+            return True
+        if len(ref) >= 32 and all(c in "0123456789abcdef" for c in ref[:32]):
+            return True
+        return False
+
+    def _resolve_hash(self, ref: str) -> str | None:
+        hash_val = ref
+        if ":" in ref and ref.index(":") < 10:
+            hash_val = ref.split(":", 1)[1] if not ref.startswith("clm:") else ref
+
+        if hasattr(self.collection, "get"):
+            card = self.collection.get(hash_val)
+            if card:
+                return getattr(card, "hash", hash_val)
+
+            card = self.collection.get(ref)
+            if card:
+                return getattr(card, "hash", ref)
+
+        return None
+
+    def _resolve_handle(self, ref: str) -> str | None:
+        if hasattr(self.collection, "resolve_handle"):
+            resolved = self.collection.resolve_handle(ref)
+            if resolved:
+                return resolved
+
+        if hasattr(self.collection, "get_by_handle"):
+            card = self.collection.get_by_handle(ref)
+            if card:
+                return getattr(card, "hash", None)
+
+        return None
+
+    def _resolve_file(self, ref: str) -> str | None:
+        if not self.allow_file_refs:
+            return None
+
+        try:
+            from pathlib import Path
+
+            path_str = ref[len("file://") :] if ref.startswith("file://") else ref
+            file_path = Path(path_str)
+            if not file_path.exists():
+                return None
+
+            content = file_path.read_bytes()
+            from clm.layer0.mcard import MCard
+
+            card = MCard(content)
+            if hasattr(self.collection, "add"):
+                self.collection.add(card)
+            return getattr(card, "hash", None)
+        except Exception:
+            return None
+
+    def _resolve_url(self, ref: str) -> str | None:
+        if not self._is_trusted_url(ref):
+            return None
+
+        try:
+            import urllib.request
+
+            from clm.layer0.mcard import MCard
+
+            response = urllib.request.urlopen(ref, timeout=30)  # noqa: S310
+            content = response.read()
+            card = MCard(content)
+            if hasattr(self.collection, "add"):
+                self.collection.add(card)
+            return getattr(card, "hash", None)
+        except Exception:
+            return None
+
+    def _is_trusted_url(self, url: str) -> bool:
+        return any(url.startswith(prefix) for prefix in self.trusted_urls)
+
+    def clear_cache(self) -> None:
+        self._resolution_cache.clear()
+
+    def add_trusted_url(self, url_prefix: str) -> None:
+        if url_prefix not in self.trusted_urls:
+            self.trusted_urls.append(url_prefix)
+
+
+__all__ = [
+    "Arrow",
+    "CPNCompiledNet",
+    "VCardGuard",
+    "compile_to_cpn",
+    "PCardResolver",
+]
+

clm/layer1/batch_processor.py

@@ -0,0 +1,152 @@
+"""Layer 1: Batch Processor for PTREngine execution.
+
+Handles sequential and parallel batch execution logic for PTREngine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+from clm.layer0.types import ExecutionResult
+from clm.layer1.store import PTRSharedStore
+
+if TYPE_CHECKING:
+    pass
+
+
+class BatchProcessor:
+    """
+    Composition object handling sequential and parallel batch execution logic for the PTREngine.
+    """
+
+    def __init__(self, engine: Any):
+        self.engine = engine
+        self.logger = logging.getLogger(__name__)
+
+    def execute_batch(
+        self,
+        pcard_hash: str,
+        target_hashes: list[str],
+        context: dict[str, Any] | PTRSharedStore = None,
+        specification_embedding: list[float] | None = None,
+        fail_fast: bool = False,
+    ) -> list[ExecutionResult]:
+        context = context or {}
+        results = []
+        failed_count = 0
+
+        self.logger.info(
+            f"[BATCH] Starting sequential batch execution: "
+            f"PCard {pcard_hash[:16]} against {len(target_hashes)} targets"
+        )
+
+        for i, target_hash in enumerate(target_hashes):
+            self.logger.debug(
+                f"[BATCH] Processing {i + 1}/{len(target_hashes)}: {target_hash[:16]}"
+            )
+
+            result = self.engine.execute_pcard(
+                pcard_hash, target_hash, context, specification_embedding
+            )
+            results.append(result)
+
+            if not result.success:
+                failed_count += 1
+                self.logger.warning(
+                    f"[BATCH] Failed {i + 1}/{len(target_hashes)}: {target_hash[:16]} - {result.error_message}"
+                )
+                if fail_fast:
+                    self.logger.error(
+                        "[BATCH] Fail-fast triggered, stopping batch execution"
+                    )
+                    break
+
+        self.engine.correctness_tracker.record_liveness_metric(
+            "batch_completed", 1.0 if failed_count == 0 else 0.5
+        )
+        self.engine.correctness_tracker.record_liveness_metric(
+            "batch_success_rate", (len(results) - failed_count) / len(target_hashes)
+        )
+
+        self.logger.info(
+            f"[BATCH] Completed: {len(results) - failed_count}/{len(target_hashes)} succeeded"
+        )
+        return results
+
+    async def execute_batch_parallel(
+        self,
+        pcard_hash: str,
+        target_hashes: list[str],
+        context: dict[str, Any] | PTRSharedStore = None,
+        specification_embedding: list[float] | None = None,
+        max_concurrency: int = 10,
+    ) -> list[ExecutionResult]:
+        context = context or {}
+
+        self.logger.info(
+            f"[BATCH_PARALLEL] Starting parallel batch execution: "
+            f"PCard {pcard_hash[:16]} against {len(target_hashes)} targets "
+            f"(max_concurrency={max_concurrency})"
+        )
+
+        async def execute_single(target_hash: str) -> ExecutionResult:
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(
+                None,
+                self.engine.execute_pcard,
+                pcard_hash,
+                target_hash,
+                context,
+                specification_embedding,
+            )
+
+        semaphore = asyncio.Semaphore(max_concurrency)
+
+        async def execute_with_limit(target_hash: str) -> ExecutionResult:
+            async with semaphore:
+                return await execute_single(target_hash)
+
+        results = await asyncio.gather(
+            *[execute_with_limit(th) for th in target_hashes], return_exceptions=True
+        )
+
+        processed_results = []
+        failed_count = 0
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                failed_count += 1
+                error_result = ExecutionResult(
+                    success=False,
+                    output=None,
+                    verification_vcard=None,
+                    execution_time_ms=0,
+                    alignment_score=None,
+                    invariants_preserved=False,
+                    safety_violations=[],
+                    liveness_metrics={},
+                    error_message=str(result),
+                )
+                processed_results.append(error_result)
+                self.logger.error(f"[BATCH_PARALLEL] Exception in {i + 1}: {result}")
+            else:
+                processed_results.append(result)
+                if not result.success:
+                    failed_count += 1
+
+        self.engine.correctness_tracker.record_liveness_metric(
+            "batch_parallel_completed", 1.0 if failed_count == 0 else 0.5
+        )
+        self.engine.correctness_tracker.record_liveness_metric(
+            "batch_parallel_success_rate",
+            (len(processed_results) - failed_count) / len(target_hashes),
+        )
+
+        self.logger.info(
+            f"[BATCH_PARALLEL] Completed: {len(processed_results) - failed_count}/{len(target_hashes)} succeeded"
+        )
+        return processed_results
+
+
+__all__ = ["BatchProcessor"]

clm/layer1/cel/__init__.py

@@ -0,0 +1,27 @@
+"""Stratified Runtime CEL Execution in Layer 1 (Sprint 384 / DEL-384-04).
+
+Provides runtime store builder and evaluation engines conforming to the
+Six-Layer Stratification architecture.
+"""
+
+from __future__ import annotations
+
+from clm.layer1.cel.builder import (
+    Listener,
+    PostMiddleware,
+    PreMiddleware,
+    action_log_middleware,
+    build_store,
+    vcard_post_middleware,
+    vcard_pre_middleware,
+)
+
+__all__ = [
+    "Listener",
+    "PostMiddleware",
+    "PreMiddleware",
+    "action_log_middleware",
+    "build_store",
+    "vcard_post_middleware",
+    "vcard_pre_middleware",
+]