clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/pcard.py

@@ -0,0 +1,434 @@
+"""Cross-Cutting — PCard (Π-type / Control Plane / Lens)
+
+PCard is the computation type / Dependent Product (Π-type) of the MVP Cards triad.
+It encodes transformations as polynomial functors over MCard references.
+PCard functions as the Monadic Executor: handling dynamic control flow and
+dependent sequencing via Reader, State, and Writer monadic patterns.
+
+Design references:
+    - MVP Cards Design Rationale (§PCard — Control Plane)
+    - Function-Number Duality
+    - The Currying Adjunction
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+import time
+from collections.abc import Callable
+from typing import Any
+
+from clm.cross_cutting.cel_engine import (  # noqa: F401
+    _DEP_LOGGER,
+    _DEPRECATED_FUNCS,
+    _evaluate_cel,
+    _evaluate_expr,
+    _resolve_arg,
+    _smart_evaluate,
+)
+from clm.cross_cutting.clm_logger import get_logger
+from clm.cross_cutting.telemetry import jsonl_emit_typed
+from clm.cross_cutting.timeutil import default_agent_did
+from clm.layer0.context import CLMContext
+from clm.layer0.utils import clm_hash_string as hash_string
+
+_logger = get_logger("clm.pcard")
+
+# ---------------------------------------------------------------------------
+# Sprint 384 (DEL-384-02): Re-export canonical PCard from Layer 0 card_triad
+from clm.layer0.model.card_triad import PCard  # noqa: F401
+
+# Dependency Inversion hooks for Layer 2 classifier integration
+_classifier_hook: tuple[Callable, Callable] | None = None
+_classifier_hook_resolver: Callable[[], tuple[Callable, Callable] | None] | None = None
+
+
+def register_classifier_hook(classify_fn: Callable, dialect_fn: Callable) -> None:
+    """Register classifier and dialect detection functions (Dependency Inversion)."""
+    global _classifier_hook
+    _classifier_hook = (classify_fn, dialect_fn)
+
+
+def register_classifier_hook_resolver(resolver: Callable[[], tuple[Callable, Callable] | None]) -> None:
+    """Register lazy resolver for classifier hook."""
+    global _classifier_hook_resolver
+    _classifier_hook_resolver = resolver
+
+
+# ---------------------------------------------------------------------------
+# PCard Serialization
+# ---------------------------------------------------------------------------
+
+def serialize_pcard(
+    ctx: CLMContext,
+    operation: str,
+    runtime: str,
+    script_hash: str,
+    input_place_hashes: list[str],
+    timestamp: str,
+) -> str:
+    """Serialize a PCard token and persist it to the execution log.
+
+    A PCard (Π-type / Dependent Product) encodes a transformation as a
+    polynomial functor over MCard references. This function freezes the
+    live PCard into an MCard (Function-Number Duality: a verb stored as
+    a noun / gerund) and commits it to the execution_log pillar.
+
+    Sprint 131.5: YAML emission now delegates to ``Card(token_type="pcard", ...).to_yaml()``
+    so the unified model is the single source of truth; the ``save_card_and_handle``
+    and ``jsonl_emit`` side effects are preserved.
+    """
+    from clm.cross_cutting.mcard import Card
+
+    pcard_yaml = Card(
+        token_type="pcard",
+        operation=operation,
+        runtime=runtime,
+        script_hash=script_hash,
+        timestamp=timestamp,
+        input_place_hashes=input_place_hashes,
+    ).to_yaml()
+
+    pcard_hash = hash_string(pcard_yaml)
+
+    handle_name = f"pcard:{operation}:{pcard_hash}"
+    ctx.repo.save_card_and_handle(
+        handle_name, pcard_hash, pcard_yaml, "execution_log",
+        timestamp=timestamp, replace=False,
+    )
+
+    jsonl_emit_typed("pcard_serialized", {
+        "pcard_hash": pcard_hash,
+        "operation": operation,
+        "runtime": runtime,
+        "script_hash": script_hash,
+        "input_place_hashes": input_place_hashes,
+    }, ctx.root)
+    return pcard_hash
+
+
+# ---------------------------------------------------------------------------
+# Operation Registry
+# ---------------------------------------------------------------------------
+
+_TRIDB_OP_NAMES = [
+    "verify_tables", "evaluator_functions", "mcard_kernel", "memorize_mcard",
+    "polyglot_ingest", "modular_adapters", "polyglot_execution", "polyglot_parity",
+    "polyglot_generalization", "normalize_syntax", "validate_type_lattice",
+    "type_system", "exclude", "assert_algebraic_operators", "check_precondition",
+    "execute_composed_pcard", "verify_authorization", "validate_session_lifecycle",
+    "verify_zero_fs_isolation", "dispatch_over_loopback",
+]
+
+
+class OperationRegistry:
+    """Maps operation names to callable implementations.
+
+    The default registry bootstraps the Tri-Database for all Stage 1
+    operations.  Additional operations can be registered at runtime.
+    """
+
+    def __init__(self) -> None:
+        import sys
+        target = "clm.layer2.storage"
+        mod = sys.modules.get(target)
+        if mod is None:
+            __import__(target)
+            mod = sys.modules.get(target)
+        init_tridb = mod.init_tridb
+        # Sprint 132.3: replaced 20 identical lambdas with functools.partial
+        # Sprint 132.5: lazy-init TriDB once per tmp_dir (was 20x init_tridb)
+        self._init_tridb = init_tridb
+        self._tridb_initialised: set[str] = set()
+        self._ops: dict[str, Callable] = dict.fromkeys(_TRIDB_OP_NAMES, self._lazy_tridb)
+
+    def _lazy_tridb(self, tmp_dir: str, **kw: Any) -> int:
+        """Lazy-init TriDB once per tmp_dir, then no-op (Sprint 132.5)."""
+        if tmp_dir not in self._tridb_initialised:
+            self._init_tridb(tmp_dir)
+            self._tridb_initialised.add(tmp_dir)
+        return 0
+
+    def register(self, name: str, fn: Callable) -> None:
+        """Register an operation handler: ``fn(tmp_dir, **kw) -> int``."""
+        self._ops[name] = fn
+
+    def dispatch(self, operation: str, tmp_dir: str, **kwargs: Any) -> int:
+        """Dispatch *operation* and return its exit code."""
+        fn = self._ops.get(operation)
+        if fn is None:
+            raise ValueError(f"Unknown operation: {operation}")
+        return fn(tmp_dir, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Post-context builder — DELETED in Sprint 128.5
+# Replaced by clm.cross_cutting.cel_store.build_store() which returns a
+# CelStore (typed, Flux-pattern) whose .to_dict() produces the same context
+# dict shape that op handlers expect.
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Sprint 130.2 — Runtime-agnostic verify_test_file expansion
+# ---------------------------------------------------------------------------
+
+_TEST_RUNTIMES = {
+    ".py": ("python", lambda clm_root: {
+        "CLM_ROOT": {"ref": "env.clm_root"},
+        "PYTHONPATH": {"op": "path_join", "parts": [{"ref": "env.clm_root"}, "kernel/scripts"]},
+    }),
+    ".sh": ("shell", lambda clm_root: {
+        "CLM_ROOT": {"ref": "env.clm_root"},
+    }),
+    ".rs": ("rust", lambda clm_root: {
+        "CLM_ROOT": {"ref": "env.clm_root"},
+        "CARGO_TARGET_DIR": {"op": "path_join", "parts": [{"ref": "env.clm_root"}, "target"]},
+    }),
+}
+
+
+def _expand_verify_test_file(verify_file: str, operation: str) -> dict:
+    """Expand a ``verify_test_file`` shorthand into vcard_pre + vcard_post blocks.
+
+    Auto-detects the test file extension (.py, .sh, .rs) and builds
+    runtime-appropriate env vars.  Returns a dict with ``vcard_pre`` and
+    ``vcard_post`` keys.
+    """
+    import os
+
+    ext = os.path.splitext(verify_file)[1]
+    runtime_info = _TEST_RUNTIMES.get(ext, _TEST_RUNTIMES[".py"])
+    label, env_builder = runtime_info
+
+    return {
+        "vcard_pre": [{
+            "test_case": f"{operation} {label} suite exists",
+            "gate": "gate:file_exists",
+            "value": {
+                "op": "path_join",
+                "parts": [{"ref": "env.clm_root"}, verify_file],
+            },
+        }],
+        "vcard_post": [{
+            "test_case": f"{operation} {label} suite passes",
+            "gate": "gate:hash_matches",
+            "expected": 0,
+            "actual": {
+                "op": "run_test_suite",
+                "test_file": verify_file,
+                "env": env_builder({"ref": "env.clm_root"}),
+            },
+        }],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Balanced Runner (Orchestrator)
+# ---------------------------------------------------------------------------
+
+class BalancedRunner:
+    """Orchestrates Face B (Balanced Expectations) verification.
+
+    For each ``pending_case`` in the manifest:
+
+    1. Evaluates ``vcard_pre`` gates (precondition checks).
+    2. Creates a sandboxed environment (``CLMTestSandbox``).
+    3. Wraps execution in a ``VCardSandwich`` (Gatekeeper Pattern).
+    4. Dispatches the operation via ``OperationRegistry``.
+    5. Evaluates ``vcard_post`` gates (postcondition assertions).
+    6. Seals the sandwich with pass/fail.
+    7. Reports aggregate results.
+    """
+
+    def __init__(
+        self,
+        clm_root: str,
+        gate_evaluator: Any | None = None,
+        op_registry: OperationRegistry | None = None,
+    ) -> None:
+        self.clm_root = clm_root
+        # Sprint 132.1: GateEvaluator import moved to cross_cutting/__init__.py;
+        # import here to avoid circular dependency at module load
+        from clm.cross_cutting.vcard import GateEvaluator
+        self.gates = gate_evaluator or GateEvaluator()
+        self.ops = op_registry or OperationRegistry()
+
+    def run(self, clm_file: str) -> int:
+        """Execute all pending cases from a Face B manifest.
+
+        Returns 0 if every case passes, 1 otherwise.
+        """
+        import yaml
+
+        test_harness_path = os.path.join(self.clm_root, "tests", "00_microkernel")
+        if test_harness_path not in sys.path:
+            sys.path.insert(0, test_harness_path)
+
+        import test_utils
+
+        from clm.cross_cutting.vcard import VCardSandwich
+        from clm.layer0.context import CLMContext
+
+        if _classifier_hook is not None:
+            classify_clm, detect_dialect = _classifier_hook
+        elif _classifier_hook_resolver is not None:
+            hook = _classifier_hook_resolver()
+            classify_clm, detect_dialect = hook if hook else (lambda *a, **k: None, lambda *a, **k: None)
+        else:
+            classify_clm, detect_dialect = (lambda *a, **k: None, lambda *a, **k: None)
+
+        if not os.path.exists(clm_file):
+            _logger.error(f"FATAL: CLM manifest file not found at {clm_file}")
+            return 1
+
+        with open(clm_file, encoding="utf-8") as f:
+            manifest = yaml.safe_load(f)
+
+        clm_block = manifest.get("clm", manifest)
+        pending_cases = clm_block.get("pending_cases", [])
+
+        overall_failed = 0
+
+        for case in pending_cases:
+            rc = self._run_case(
+                case, test_utils, CLMDB, CLMRepository, CLMContext,
+                VCardSandwich, classify_clm, detect_dialect,
+            )
+            if rc != 0:
+                overall_failed += 1
+
+        if overall_failed == 0:
+            _logger.info("All dynamic Face B assertions verified successfully!")
+            return 0
+        else:
+            _logger.error(f"Face B verification failed: {overall_failed} test suite(s) had errors.")
+            return 1
+
+    def _run_case(
+        self, case: dict, test_utils: Any,
+        CLMDB: type, CLMRepository: type, CLMContext: type,
+        VCardSandwich: type, classify_clm: Callable, detect_dialect: Callable,
+    ) -> int:
+        """Execute a single pending case. Returns 0 on success, 1 on failure.
+
+        Sprint 128.5: Uses a unified ``CelStore`` for both pre and post gates
+            (progressive enrichment).
+        Sprint 130.2: Adds Phase 0 (verify_test_file expansion) and passes
+            ``store=`` to ``seal()`` so ``flush_action_log()`` persists the
+            action_log to ``execution_log.db``.
+        """
+        from clm.cross_cutting.cel_store import CelStore, EnvSlice, StateSlice
+
+        given = case.get("given", {})
+        step_seq = given.get("step_sequence")
+        inputs = given.get("inputs", {})
+
+        when = case.get("when", {})
+        operation = when.get("operation")
+
+        then = case.get("then", {})
+        assertions = then.get("assertions", {})
+        expected_outputs = then.get("outputs", {})
+
+        suite = test_utils.CLMTestSuite(f"Test Suite: {operation} (Step {step_seq})")
+
+        # ---- 0. Dynamic Gate Expansion (Sprint 130.2) ---------------------
+        # If verify_test_file is declared, expand it into vcard_pre +
+        # vcard_post gate blocks before evaluation.  User-defined gates
+        # take precedence (prepended, not overwritten).
+        verify_file = then.get("verify_test_file")
+        if verify_file:
+            expanded = _expand_verify_test_file(verify_file, operation)
+            for gate_key in ("vcard_pre", "vcard_post"):
+                if gate_key not in assertions:
+                    assertions[gate_key] = []
+                assertions[gate_key] = expanded[gate_key] + assertions[gate_key]
+
+        # ---- A. VCard Pre-Gate (minimal store) -----------------------------
+        store = CelStore(
+            state=StateSlice(inputs=inputs),
+            env=EnvSlice(
+                clm_root=self.clm_root,
+                os=os, sys=sys, time=time, hashlib=hashlib, str=str,
+            ),
+        )
+
+        for pre_item in assertions.get("vcard_pre", []):
+            if not self.gates.evaluate_pre(pre_item, store.to_dict(), suite):
+                suite.report_results()
+                return 1
+
+        # ---- B. Sandbox + VCardSandwich (Sprint 133.4: via thunk()) ------
+        with test_utils.CLMTestSandbox(self.clm_root, copy_schema=True) as tmp_dir:
+            db = CLMDB(tmp_dir)
+            ctx = CLMContext(root=tmp_dir, db=db, zero_fs=False)
+            repo = CLMRepository(db, tmp_dir)
+
+            agent_did = default_agent_did()
+
+            # Sprint 133.4: dispatch_fn replaces manual sandwich.__enter__/seal.
+            def _dispatch_fn(sandwich, store_arg):
+                step_passed = True
+                error_msg = ""
+                rc = 0
+                try:
+                    rc = self.ops.dispatch(operation, tmp_dir)
+                except Exception as e:
+                    step_passed = False
+                    error_msg = str(e)
+                    suite.tu_fail(f"Exception during transition execution: {e}")
+
+                # ---- D. VCard Post-Gate (enriched store) -----------------
+                from clm.cross_cutting.cel_store import build_store
+                post_store = build_store(
+                    inputs=inputs, outputs=expected_outputs, rc=rc,
+                    tmp_dir=tmp_dir, db=db, ctx=ctx, repo=repo,
+                    classify_clm=classify_clm, detect_dialect=detect_dialect,
+                    clm_root=self.clm_root,
+                )
+
+                for post_item in assertions.get("vcard_post", []):
+                    if not self.gates.evaluate_post(post_item, post_store.to_dict(), suite):
+                        step_passed = False
+
+                if suite.failed > 0 or not step_passed:
+                    return 1, f"Verification failed: {error_msg or 'Suite assertions failed.'}"
+                return 0, "success"
+
+            from clm.cross_cutting.vcard import thunk
+            exit_code, _ = thunk(
+                store=None, action={}, ctx=ctx, operation=operation,
+                agent_did=agent_did,
+                dispatch_fn=_dispatch_fn,
+            )
+
+            if exit_code != 0:
+                suite.report_results()
+                return 1
+
+        suite.report_results()
+        return 0
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def run_balanced_expectations(clm_root: str, clm_file: str) -> int:
+    """Run all pending_cases from a Face B (Balanced Expectations) manifest.
+
+    This is the public entry point.  Internally it creates a
+    :class:`BalancedRunner` with default gates and operations, then
+    delegates to :meth:`BalancedRunner.run`.
+    """
+    runner = BalancedRunner(clm_root)
+    return runner.run(clm_file)
+
+
+# ---------------------------------------------------------------------------
+# Absorbed re-exports — MOVED to cross_cutting/__init__.py in Sprint 132.1
+# (facade inversion: pcard/ no longer imports upward into layer0/1/2)
+# ---------------------------------------------------------------------------

clm/cross_cutting/registry.py

@@ -0,0 +1,71 @@
+"""Declarative CLM Operation Registry (Sprint 179).
+
+Replaces string-patched exec() with a strongly-typed, decorator-based dispatch mechanism.
+Supports command aliases, metadata inspection, and isolated context injection.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from clm.cross_cutting.errors import OperationNotFoundError
+from clm.layer0.context import CLMContext
+
+_OPERATION_REGISTRY: dict[str, Callable[[list[str], CLMContext], int]] = {}
+_OPERATION_METADATA: dict[str, dict[str, Any]] = {}
+
+
+def clm_operation(
+    name: str,
+    *,
+    aliases: list[str] | None = None,
+    description: str = "",
+) -> Callable:
+    """Decorator to register a function as a CLM CLI / evaluator operation."""
+
+    def decorator(
+        fn: Callable[[list[str], CLMContext], int]
+    ) -> Callable[[list[str], CLMContext], int]:
+        _OPERATION_REGISTRY[name] = fn
+        meta = {
+            "name": name,
+            "description": description,
+            "aliases": aliases or [],
+            "fn_name": fn.__name__,
+            "module": fn.__module__,
+        }
+        _OPERATION_METADATA[name] = meta
+        if aliases:
+            for alias in aliases:
+                _OPERATION_REGISTRY[alias] = fn
+                _OPERATION_METADATA[alias] = meta
+        return fn
+
+    return decorator
+
+
+def dispatch_operation(
+    name: str,
+    args: list[str] | None = None,
+    ctx: CLMContext | None = None,
+) -> int:
+    """Dispatch a registered operation by name with typed arguments and isolated context."""
+    fn = _OPERATION_REGISTRY.get(name)
+    if not fn:
+        available = ", ".join(sorted(set(_OPERATION_REGISTRY.keys())))
+        raise OperationNotFoundError(
+            f"Unknown CLM operation: '{name}'. Available operations: [{available}]"
+        )
+    context = ctx or CLMContext.current()
+    return fn(args or [], context)
+
+
+def get_registered_operations() -> list[str]:
+    """Return all unique registered operation names."""
+    return sorted(set(_OPERATION_REGISTRY.keys()))
+
+
+def get_operation_metadata(name: str) -> dict[str, Any] | None:
+    """Return metadata dict for an operation name or alias."""
+    return _OPERATION_METADATA.get(name)

clm/cross_cutting/resources.py

@@ -0,0 +1,84 @@
+"""Resource resolution module for CLM packages and developmental workspaces.
+
+Provides robust resolution of bundled schema definitions, SQL scripts, and
+configuration templates via PEP 302/366/3002 importlib.resources standards with
+seamless fallback to local source tree layouts during development.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import os
+from pathlib import Path
+
+
+def get_schema_path(filename: str = "mcard_schema.sql") -> Path:
+    """Resolve the absolute filesystem path for a schema file.
+
+    Search priority:
+    1. Bundled package resources in `clm.schemas` (wheel/installed mode)
+    2. Package-relative path `clm/schemas/`
+    3. Monorepo workspace `CLM_ROOT/types/schemas/` or `types/schemas/`
+    4. Parent directory `../types/schemas/`
+
+    Args:
+        filename: Name of the schema file (e.g. 'mcard_schema.sql', 'cel_schema.yaml').
+
+    Returns:
+        Path object pointing to the existing schema file.
+
+    Raises:
+        FileNotFoundError: If the schema file cannot be located across all candidates.
+    """
+    # 1. Try importlib.resources (installed wheel package mode)
+    try:
+        resource_ref = importlib.resources.files("clm.schemas").joinpath(filename)
+        # In Python 3.9+, Traversable might be a concrete path or in a zip
+        candidate = Path(str(resource_ref))
+        if candidate.is_file():
+            return candidate
+    except Exception:
+        pass
+
+    # 2. Try relative to this file's package tree: kernel/scripts/clm/schemas/
+    pkg_schema = Path(__file__).resolve().parent.parent / "schemas" / filename
+    if pkg_schema.is_file():
+        return pkg_schema
+
+    # 3. Try CLM_ROOT environment variable or current directory
+    clm_root_env = os.environ.get("CLM_ROOT")
+    if clm_root_env:
+        root_path = Path(clm_root_env).resolve()
+        candidate = root_path / "types" / "schemas" / filename
+        if candidate.is_file():
+            return candidate
+        candidate = root_path / "clm" / "types" / "schemas" / filename
+        if candidate.is_file():
+            return candidate
+
+    # 4. Try current working directory and parent paths
+    cwd = Path.cwd().resolve()
+    for base in [cwd, cwd.parent, cwd.parent.parent]:
+        candidate = base / "types" / "schemas" / filename
+        if candidate.is_file():
+            return candidate
+        candidate = base / "clm" / "types" / "schemas" / filename
+        if candidate.is_file():
+            return candidate
+
+    raise FileNotFoundError(
+        f"CLM schema '{filename}' could not be resolved via importlib.resources or workspace search."
+    )
+
+
+def get_schema_content(filename: str = "mcard_schema.sql") -> str:
+    """Read and return the text contents of a CLM schema file.
+
+    Args:
+        filename: Name of the schema file.
+
+    Returns:
+        String content of the schema file decoded as UTF-8.
+    """
+    path = get_schema_path(filename)
+    return path.read_text(encoding="utf-8")

clm/cross_cutting/secrets.py

@@ -0,0 +1,44 @@
+"""Cryptographic secret container with explicit zeroization and RAII protection (Sprint 176).
+
+Prevents accidental key leaks into log files or tracebacks via custom __repr__ and __str__,
+and scrubs memory buffer with null bytes on drop or context exit.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Self
+
+
+class SecretBytes:
+    """Container for sensitive cryptographic material with explicit zeroization."""
+
+    def __init__(self, data: bytes) -> None:
+        self._buf = bytearray(data)
+
+    def reveal(self) -> bytes:
+        """Access raw bytes. Caller should avoid assigning to long-lived variables."""
+        if not self._buf:
+            raise ValueError("SecretBytes buffer has been zeroized")
+        return bytes(self._buf)
+
+    def zeroize(self) -> None:
+        """Explicitly overwrite buffer memory with null bytes."""
+        if self._buf:
+            ctypes.memset((ctypes.c_char * len(self._buf)).from_buffer(self._buf), 0, len(self._buf))
+            self._buf.clear()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        self.zeroize()
+
+    def __del__(self) -> None:
+        self.zeroize()
+
+    def __repr__(self) -> str:
+        return "<SecretBytes [REDACTED]>"
+
+    def __str__(self) -> str:
+        return "<SecretBytes [REDACTED]>"