clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/spec_tester.py

@@ -0,0 +1,165 @@
+"""
+Specification Tester for the Polynomial Type Runtime.
+
+Isolates testing and validation capabilities that match PCards against
+their defined `balanced` expectations (e.g. unit tests encoded inside the PCard).
+"""
+
+from typing import Any
+
+import yaml
+
+from clm.layer0.model.card import MCard
+from clm.layer1.engine import PTREngine
+
+
+class SpecTester:
+    """Evaluates balanced tests defined in a PCard's CLM."""
+
+    def __init__(self, engine: PTREngine):
+        self.engine = engine
+        self.collection = engine.collection
+
+    def run_balanced_tests(
+        self, pcard_hash: str, context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Run all test cases defined in the PCard's balanced dimension."""
+        pcard = self.collection.get(pcard_hash)
+        if not pcard:
+            raise ValueError(f"PCard not found: {pcard_hash}")
+
+        pcard_content = pcard.get_content().decode("utf-8")
+        pcard_data = yaml.safe_load(pcard_content)
+
+        balanced = pcard_data.get("confirmation", pcard_data.get("balanced", {}))
+        test_cases = balanced.get("test_cases", [])
+
+        results = {"total": len(test_cases), "passed": 0, "failed": 0, "details": []}
+
+        for i, test_case in enumerate(test_cases):
+            description = test_case.get("description", f"Test Case #{i + 1}")
+
+            given = test_case.get("assumption", test_case.get("given", {}))
+            expected = test_case.get("confirmation", test_case.get("then", {}))
+
+            input_val = given
+            if isinstance(given, dict) and "input" in given:
+                input_val = given["input"]
+            elif isinstance(given, dict) and len(given) == 1:
+                input_val = list(given.values())[0]
+
+            when = test_case.get("behavior", test_case.get("when", {}))
+            test_context = when.get("params", {})
+
+            full_context = (context or {}).copy()
+            full_context.update(test_context)
+
+            if isinstance(input_val, str):
+                target_content = input_val.encode("utf-8")
+            else:
+                import json
+
+                target_content = json.dumps(input_val).encode("utf-8")
+
+            target = MCard(target_content)
+            self.collection.add(target)
+
+            try:
+                result = self.engine.execute_pcard(
+                    pcard_hash, target.hash, context=full_context
+                )
+
+                passed = True
+                failure_reason = ""
+                actual = result.output
+
+                for key, expected_val in expected.items():
+                    if key == "epsilon":
+                        continue
+
+                    actual_val = actual
+                    if isinstance(actual, dict) and key in actual:
+                        actual_val = actual[key]
+                    elif isinstance(actual, int | float | str) and key in [
+                        "result",
+                        "sine_value",
+                        "value",
+                    ]:
+                        actual_val = actual
+
+                    if isinstance(expected_val, int | float) and isinstance(
+                        actual_val, int | float
+                    ):
+                        epsilon = float(expected.get("epsilon", 0))
+                        if abs(actual_val - expected_val) > epsilon:
+                            passed = False
+                            failure_reason = f"Expected {key}={expected_val} (epsilon={epsilon}), got {actual_val}"
+                            break
+                    elif isinstance(expected_val, dict) and isinstance(
+                        actual_val, dict
+                    ):
+
+                        def check_subset(exp, act, path=""):
+                            for k, v in exp.items():
+                                if k not in act:
+                                    return False, f"Missing key '{path}{k}'"
+
+                                if isinstance(v, dict) and isinstance(act[k], dict):
+                                    sub_ok, sub_reason = check_subset(
+                                        v, act[k], f"{path}{k}."
+                                    )
+                                    if not sub_ok:
+                                        return False, sub_reason
+                                elif v != act[k]:
+                                    return (
+                                        False,
+                                        f"Value mismatch at '{path}{k}': expected {v}, got {act[k]}",
+                                    )
+                            return True, ""
+
+                        subset_ok, subset_reason = check_subset(
+                            expected_val, actual_val
+                        )
+                        if not subset_ok:
+                            passed = False
+                            failure_reason = f"Dict mismatch for {key}: {subset_reason}"
+                            break
+                    elif actual_val != expected_val:
+                        passed = False
+                        failure_reason = (
+                            f"Expected {key}={expected_val}, got {actual_val}"
+                        )
+                        break
+
+                if passed:
+                    results["passed"] += 1
+                    status = "PASSED"
+                else:
+                    results["failed"] += 1
+                    status = "FAILED"
+
+                results["details"].append(
+                    {
+                        "id": i + 1,
+                        "description": description,
+                        "status": status,
+                        "input": input_val,
+                        "expected": expected,
+                        "actual": actual,
+                        "reason": failure_reason,
+                    }
+                )
+
+            except Exception as e:
+                results["failed"] += 1
+                results["details"].append(
+                    {
+                        "id": i + 1,
+                        "description": description,
+                        "status": "ERROR",
+                        "input": input_val,
+                        "error": str(e),
+                    }
+                )
+
+        return results

clm/layer1/store.py

@@ -0,0 +1,295 @@
+"""PTR Shared Store - Standardized data contract for PCard execution.
+
+Canonical Path: kernel/scripts/clm/layer1/store.py
+Parity: TypeScript `mcard-js/src/ptr/core/SharedStore.ts`
+
+Based on PocketFlow's Shared Store pattern, this module provides a formalized
+data structure for communication between PCards in the PTR execution pipeline.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+
+@dataclass
+class PTRSharedStore:
+    """Standardized shared store for PTR execution.
+
+    All nodes (PCards) agree upon this data contract for communication.
+    Replaces ad-hoc context dictionaries with typed, validated fields.
+
+    Layers:
+    - Identity: Zero-Trust routing and caller verification
+    - Content: PCard and target artifacts
+    - Execution: Runtime inputs, outputs, and configuration
+    - Verification: VCard proofs and validation results
+    - Observability: Metrics, timing, and correctness tracking
+    """
+
+    # =========================================================================
+    # IDENTITY LAYER - Zero-Trust routing and authentication
+    # =========================================================================
+    caller_identity_hash: str | None = None
+    """DID or hash of the calling identity for AuthZ/AuthN checks."""
+
+    agent_identities: Any = field(default=None, repr=False)
+    """CardCollection reference to agent_identities.db for Zero-Trust routing."""
+
+    # =========================================================================
+    # CONTENT LAYER - PCard and target artifacts
+    # =========================================================================
+    pcard: Any = field(default=None, repr=False)
+    """The PCard (Polynomial Card) being executed."""
+
+    target: Any = field(default=None, repr=False)
+    """The target MCard the PCard operates upon."""
+
+    pcard_hash: str | None = None
+    """Content-addressed hash of the PCard."""
+
+    target_hash: str | None = None
+    """Content-addressed hash of the target."""
+
+    # =========================================================================
+    # EXECUTION LAYER - Runtime inputs, outputs, and configuration
+    # =========================================================================
+    inputs: dict[str, Any] = field(default_factory=dict)
+    """Input parameters for execution (replaces raw context dict)."""
+
+    outputs: dict[str, Any] = field(default_factory=dict)
+    """Output results from execution."""
+
+    runtime_config: dict[str, Any] = field(default_factory=dict)
+    """Runtime configuration (timeouts, language, sandbox settings, etc.)."""
+
+    # =========================================================================
+    # VERIFICATION LAYER - VCard proofs and validation
+    # =========================================================================
+    v_pre: Any = field(default=None, repr=False)
+    """Pre-condition VCard (verification before execution)."""
+
+    v_post: Any = field(default=None, repr=False)
+    """Post-condition VCard (verification after execution)."""
+
+    verification_result: Any = field(default=None, repr=False)
+    """Result from CLMVerifier.validate() or similar."""
+
+    # =========================================================================
+    # OBSERVABILITY LAYER - Metrics, timing, and correctness
+    # =========================================================================
+    execution_time_ms: int = 0
+    """Total execution time in milliseconds."""
+
+    alignment_score: float | None = None
+    """Directional alignment score (if enabled)."""
+
+    invariants_preserved: bool = True
+    """Whether all correctness invariants were preserved."""
+
+    # =========================================================================
+    # TRI-DATABASE TOPOLOGY - Four-Database context (§Key Arch Principles #4)
+    # =========================================================================
+    tri_db: Any = field(default=None, repr=False)
+    """TriDatabase reference — soul-bound SSOT for the agency.
+    Carries the complete Who/What/How cognitive mapping."""
+
+    data_plane_hash: str | None = None
+    """Current Data Plane input hash — bits-to-hash guarantee (§1.1 Data Plane)."""
+
+    control_plane_phase: str | None = None
+    """Current PTR lifecycle phase: prep/exec/post/await (§1.1 Control Plane)."""
+
+    chl_temporal: Any = field(default=None, repr=False)
+    """Active CHL temporal dimension (CHLTemporal instance).
+    Tracks Design/Compile/Execute time per §1.5."""
+
+    retry_count: int = 0
+    """Number of retries attempted (for retry mechanism)."""
+
+    # =========================================================================
+    # GOVERNANCE TELEMETRY LAYER (Token Arithmetics)
+    # Computed during prep→exec→post lifecycle per Architecture §03 Token Arithmetics
+    # and Specifications §04 §2.5 Type-Based Possibility Arithmetics
+    # =========================================================================
+    possibility_magnitude: float | None = None
+    """M(B^A) = |B|^|A| — total combinatorial possibility space."""
+
+    governance_narrowing: float | None = None
+    """N = 1 - |B'|^|A'| / |B|^|A| — policy restrictiveness ratio."""
+
+    epiplexity_yield: float | None = None
+    """E = S_T / M — structured knowledge per possibility (using alignment_score as S_T)."""
+
+    product_dependency_count: int | None = None
+    """Pi = |A1 × A2 × ... × An| — concurrent precondition count."""
+
+    # =========================================================================
+    # LEGACY COMPATIBILITY - Support dict-style access
+    # =========================================================================
+
+    def __getitem__(self, key: str) -> Any:
+        """Enable dict-style access for backward compatibility."""
+        if hasattr(self, key):
+            return getattr(self, key)
+        # Fallback to inputs dict for arbitrary keys
+        if key in self.inputs:
+            return self.inputs[key]
+        raise KeyError(f"'{key}' not found in store attributes or inputs")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Enable dict-style assignment for backward compatibility."""
+        if hasattr(self, key) and not key.startswith("_"):
+            setattr(self, key, value)
+        else:
+            # Store arbitrary keys in inputs dict
+            self.inputs[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Dict-style .get() method for backward compatibility."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert store to dictionary (for serialization)."""
+        result = {
+            # Identity
+            "caller_identity_hash": self.caller_identity_hash,
+            "agent_identities": self.agent_identities,
+            # Content
+            "pcard_hash": self.pcard_hash,
+            "target_hash": self.target_hash,
+            # Execution
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+            "runtime_config": self.runtime_config,
+            # Verification
+            "verification_result": self.verification_result,
+            # Observability
+            "execution_time_ms": self.execution_time_ms,
+            "alignment_score": self.alignment_score,
+            "invariants_preserved": self.invariants_preserved,
+            "retry_count": self.retry_count,
+            # Governance telemetry
+            "possibility_magnitude": self.possibility_magnitude,
+            "governance_narrowing": self.governance_narrowing,
+            "epiplexity_yield": self.epiplexity_yield,
+            "product_dependency_count": self.product_dependency_count,
+        }
+        # Tri-Database topology (only include when set)
+        if self.data_plane_hash is not None:
+            result["data_plane_hash"] = self.data_plane_hash
+        if self.control_plane_phase is not None:
+            result["control_plane_phase"] = self.control_plane_phase
+        if self.chl_temporal is not None:
+            result["chl_temporal"] = (
+                self.chl_temporal.to_dict()
+                if hasattr(self.chl_temporal, "to_dict")
+                else self.chl_temporal
+            )
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PTRSharedStore:
+        """Create store from dictionary (for deserialization)."""
+        # Extract known fields
+        known_fields = {
+            "caller_identity_hash",
+            "agent_identities",
+            "pcard_hash",
+            "target_hash",
+            "inputs",
+            "outputs",
+            "runtime_config",
+            "verification_result",
+            "execution_time_ms",
+            "alignment_score",
+            "invariants_preserved",
+            "retry_count",
+            # Tri-Database topology fields
+            "tri_db",
+            "data_plane_hash",
+            "control_plane_phase",
+            "chl_temporal",
+            # Governance telemetry fields
+            "possibility_magnitude",
+            "governance_narrowing",
+            "epiplexity_yield",
+            "product_dependency_count",
+        }
+
+        store_data = {k: v for k, v in data.items() if k in known_fields}
+
+        # Unknown fields go into inputs
+        unknown_fields = {k: v for k, v in data.items() if k not in known_fields}
+        if unknown_fields:
+            store_data.setdefault("inputs", {}).update(unknown_fields)
+
+        return cls(**store_data)
+
+    def merge_inputs(self, additional: dict[str, Any]) -> PTRSharedStore:
+        """Return new store with merged inputs (immutable update pattern)."""
+        new_inputs = {**self.inputs, **additional}
+        return replace(self, inputs=new_inputs)
+
+    def with_outputs(self, outputs: dict[str, Any]) -> PTRSharedStore:
+        """Return new store with outputs set (immutable update pattern)."""
+        return replace(self, outputs=outputs)
+
+
+def create_store_from_context(
+    context: dict[str, Any],
+    pcard: Any | None = None,
+    target: Any | None = None,
+    agent_identities: Any | None = None,
+) -> PTRSharedStore:
+    """Create a PTRSharedStore from a legacy context dictionary.
+
+    This helper enables gradual migration from dict-based context to typed store.
+
+    Args:
+        context: Legacy context dictionary
+        pcard: PCard instance (if available)
+        target: Target MCard instance (if available)
+        agent_identities: Identity space collection (if available)
+
+    Returns:
+        PTRSharedStore with context data properly partitioned
+    """
+    known_mapping = {
+        "caller_identity_hash": "caller_identity_hash",
+        "pcard_hash": "pcard_hash",
+        "target_hash": "target_hash",
+        "execution_time_ms": "execution_time_ms",
+        "alignment_score": "alignment_score",
+        "invariants_preserved": "invariants_preserved",
+    }
+
+    store_kwargs: dict[str, Any] = {}
+    remaining_context = dict(context)  # Copy
+
+    for context_key, store_key in known_mapping.items():
+        if context_key in remaining_context:
+            store_kwargs[store_key] = remaining_context.pop(context_key)
+
+    # Handle boolean string conversion for invariants_preserved
+    if "invariants_preserved" in store_kwargs:
+        val = store_kwargs["invariants_preserved"]
+        if isinstance(val, str):
+            store_kwargs["invariants_preserved"] = val.lower() == "true"
+
+    # Add object references
+    store_kwargs["pcard"] = pcard
+    store_kwargs["target"] = target
+    store_kwargs["agent_identities"] = agent_identities
+
+    # Remaining context goes into inputs
+    store_kwargs["inputs"] = remaining_context
+
+    return PTRSharedStore(**store_kwargs)
+
+
+__all__ = ["PTRSharedStore", "create_store_from_context"]