clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/verifier_core.py

@@ -0,0 +1,262 @@
+"""Layer 0 Verifier Core — Precondition validation and Execution MCard emission.
+
+Extracted from clm.layer1.verifier to resolve Girard paradox violation V-1:
+algebra_baldwin.py (Layer 0) was importing emit_exec_mcard_py and
+verify_precondition from verifier.py (Layer 1), creating an upward
+dependency that breaks the Type Lattice SSOT principle (type_lattice.md §4.5).
+
+These functions depend only on Layer 0 primitives:
+  - clm.layer0.db (CLMDB, CLMRepository, resolve_clm_path)
+  - clm.layer0.utils (clm_hash_file, clm_hash_string, detect_host_os)
+  - clm.layer0.algebra (load_normalized_manifest_str — lazy)
+  - clm.layer0.type_registry (TypeRegistry — lazy)
+  - clm.cross_cutting.clm_logger (get_logger)
+"""
+
+import os
+import sys
+import time
+
+import yaml
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.utils import (
+    clm_hash_file,
+    clm_hash_string,
+    detect_host_os,
+    resolve_clm_path,
+)
+
+
+def _get_storage():
+    target = "clm.layer2.storage"
+    mod = sys.modules.get(target)
+    if mod is None:
+        __import__(target)
+        mod = sys.modules.get(target)
+    return mod
+
+_logger = get_logger("clm.layer0.verifier_core")
+
+
+def _get_load_manifest_str():
+    from clm.layer0.algebra import load_normalized_manifest_str
+    return load_normalized_manifest_str
+
+
+def verify_precondition(clm_root: str, clm_file: str) -> bool:
+    """
+    Validates the precondition bounds and zero-trust identity before executing a PCard.
+
+    Args:
+        clm_root (str): The root directory of the CLM workspace.
+        clm_file (str): The path to the CLM PCard file.
+
+    Returns:
+        bool: True if authorized and validated, False otherwise.
+    """
+    load_normalized_manifest_str_fn = _get_load_manifest_str()
+    clm_file = resolve_clm_path(clm_root, clm_file)
+    stub = os.path.join(clm_root, "kernel", "scripts", "clmEval")
+    eval_yaml = os.path.join(clm_root, "computable_knowledge/Abstract/layer5_system/bootstrap/evaluator/clmEval.yaml")
+    if os.path.exists(stub) and os.path.exists(eval_yaml):
+        stub_cert = ""
+        with open(stub, encoding="utf-8") as f:
+            for line in f:
+                if "_EXPECTED_HASH=" in line:
+                    parts = line.split('="')
+                    if len(parts) > 1:
+                        stub_cert = parts[1].split('"')[0]
+                        break
+        yaml_hash = clm_hash_file(eval_yaml)
+        if stub_cert and stub_cert != yaml_hash:
+            import hashlib
+            with open(eval_yaml, "rb") as yf:
+                norm_yaml = yf.read().replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+            if stub_cert != hashlib.sha256(norm_yaml).hexdigest():
+                _logger.error("[VERIFY] ❌ Integrity failure: stub certificate mismatch")
+                _logger.info(f"[VERIFY]   Stub expects: {stub_cert}")
+                _logger.info(f"[VERIFY]   YAML actual:  {yaml_hash}")
+                return False
+        _logger.info("[VERIFY] ✅ Bidirectional integrity verified")
+        _logger.info(f"[VERIFY]   YAML hash: {yaml_hash}")
+        _logger.info(f"[VERIFY]   Stub hash: {clm_hash_file(stub)}")
+
+    host_os = detect_host_os()
+
+    root_did = f"did:pkc:ca:{host_os}:root-agent"
+    storage = _get_storage()
+    db = storage.CLMDB(clm_root) if storage else None
+    repo = storage.CLMRepository(db, clm_root) if storage and db else None
+
+    if not repo.has_card(root_did, "agent_identities"):
+        _logger.info(f"[VERIFY] Bootstrapping root CA agent: {root_did}")
+        g_time = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+        yaml_content = f"""agent:
+  did: "{root_did}"
+  type: "CA"
+  metadata:
+    os: "{host_os}"
+    name: "Root CA Agent"
+  capabilities:
+    - "admin"
+    - "exec"
+"""
+        repo.save_card_and_handle("agent:root", root_did, yaml_content, "agent_identities", timestamp=g_time, replace=False)
+
+    virtual_dids = ["did:clm:evaluator", "did:clm:cache_manager", "did:clm:iam_agent", "did:clm:ci_pipeline"]
+    for v_did in virtual_dids:
+        if not repo.has_card(v_did, "agent_identities"):
+            g_time = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+            yaml_content = f"""agent:
+  did: "{v_did}"
+  type: "CA"
+  metadata:
+    name: "Virtual {v_did} Agent"
+  capabilities:
+    - "admin"
+    - "exec"
+"""
+            repo.save_card(v_did, yaml_content, "agent_identities", timestamp=g_time, replace=False)
+
+    if "ACTIVE_AGENT_DID" not in os.environ:
+        os.environ["ACTIVE_AGENT_DID"] = root_did
+
+    active_did = os.environ["ACTIVE_AGENT_DID"]
+    _logger.info(f"[VERIFY] Active Agent DID: {active_did}")
+
+    agent_card_res = repo.get_card_content(active_did, "agent_identities")
+    if not agent_card_res or not agent_card_res.strip():
+        _logger.error(f"[VERIFY] ❌ Unauthorized agent: {active_did} is not registered.")
+        return False
+
+    try:
+        agent_data = yaml.safe_load(agent_card_res.strip())
+        caps = agent_data.get("agent", {}).get("capabilities", [])
+        if not any(c in caps for c in ["exec", "admin"]):
+            _logger.error(f"[VERIFY] ❌ Agent {active_did} lacks required 'exec' or 'admin' capability.")
+            return False
+    except Exception as e:
+        _logger.error(f"[VERIFY] ❌ Failed to parse agent capabilities: {e}")
+        return False
+
+    _logger.info("[VERIFY] ✅ Agent authorized successfully")
+
+    strict_types = os.environ.get("CLM_STRICT_TYPES", "").lower() == "true"
+    if clm_file and os.path.exists(clm_file):
+        content_str = load_normalized_manifest_str_fn(clm_root, clm_file)
+        type_name = "mcard"
+        extract_key = None
+        if "_meta:" in content_str:
+            type_name = "clm_manifest"
+            extract_key = "_meta"
+        elif "vpre:" in content_str or "vpost:" in content_str or "vcard_token:" in content_str:
+            type_name = "vcard_token"
+            extract_key = "vcard_token"
+        elif "abstract_spec:" in content_str:
+            type_name = "a_mcard"
+            extract_key = "abstract_spec"
+
+        payload_content = content_str
+        try:
+            parsed = yaml.safe_load(content_str)
+            inner = parsed.get("clm", parsed)
+            if extract_key and isinstance(inner, dict) and extract_key in inner:
+                payload_content = yaml.dump(inner[extract_key])
+        except Exception:
+            pass
+
+        try:
+            from clm.layer0.type_registry import TypeRegistry
+            registry = TypeRegistry(clm_root)
+            if type_name == "mcard" and not registry.get_type_info("mcard"):
+                _logger.warning("[VERIFY] ⚠️ Skipping type validation: 'mcard' is not registered.")
+            else:
+                registry.validate(type_name, payload_content)
+                _logger.info(f"[VERIFY] ✅ Type validation passed (type: {type_name})")
+        except Exception as e:
+            if strict_types:
+                _logger.error(f"[VERIFY] ❌ TYPE_ERROR: Type validation failed for '{clm_file}'!")
+                _logger.error(f"Error: {e}")
+                return False
+            else:
+                _logger.warning(f"[VERIFY] ⚠️ TYPE_WARNING: Type validation failed for '{clm_file}' (Strict mode is OFF)")
+                _logger.info(f"Details: {e}")
+    return True
+
+
+def emit_exec_mcard_py(
+    clm_root: str,
+    operation: str,
+    content_hash: str,
+    extra_yaml: str = "",
+    a_hash: str = "",
+    c_hash: str = "",
+) -> str:
+    """
+    Emits an Execution MCard to the Tri-Database to track state changes.
+
+    Args:
+        clm_root (str): The root directory of the CLM workspace.
+        operation (str): The operation being performed.
+        content_hash (str): The hash of the content involved.
+        extra_yaml (str): Additional YAML content to append.
+        a_hash (str): The Abstract Specification hash.
+        c_hash (str): The Concrete Implementation hash.
+
+    Returns:
+        str: The path to the emitted MCard file.
+    """
+    storage = _get_storage()
+    db = storage.CLMDB(clm_root) if storage else None
+    zero_fs = db.zero_fs if db else (os.environ.get("CLM_ZERO_FS", "").lower() in ("true", "1"))
+    mcard_dir = os.path.join(clm_root, "data/execution_logs")
+    if zero_fs:
+        mcard_dir = os.path.join(os.environ.get("TMPDIR", "/tmp"), "data/execution_logs")
+    os.makedirs(mcard_dir, exist_ok=True)
+
+    g_time = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+    unix_ts = int(time.time())
+    mcard_file = os.path.join(mcard_dir, f"exec_{unix_ts}_{content_hash[:8]}.yaml")
+
+    lines = []
+    lines.append("mcard:")
+    lines.append(f'  g_time: "{g_time}"')
+    lines.append(f'  content_hash: "{content_hash}"')
+    lines.append(f'  operation: "{operation}"')
+    lines.append(f'  agent_did: "{os.environ.get("ACTIVE_AGENT_DID", "")}"')
+
+    if extra_yaml:
+        for line in extra_yaml.strip().splitlines():
+            lines.append(f"  {line}")
+
+    if a_hash or c_hash:
+        lines.append("  source:")
+        if a_hash:
+            lines.append(f'    a_hash: "{a_hash}"')
+        if c_hash:
+            lines.append(f'    c_hash: "{c_hash}"')
+        lines.append(f'    operation: "{operation}"')
+        facts = os.environ.get("CLM_RUNTIME_FACTS")
+        if facts:
+            lines.append("    runtime_facts:")
+            for line in facts.strip().splitlines():
+                lines.append(f"      {line}")
+    else:
+        facts = os.environ.get("CLM_RUNTIME_FACTS")
+        if facts:
+            lines.append("  runtime_facts:")
+            for line in facts.strip().splitlines():
+                lines.append(f"    {line}")
+
+    mcard_content = "\n".join(lines) + "\n"
+
+    if not zero_fs:
+        with open(mcard_file, "w", encoding="utf-8") as f:
+            f.write(mcard_content)
+
+    mcard_hash = clm_hash_string(mcard_content)
+    if storage and db:
+        repo = storage.CLMRepository(db, clm_root)
+        repo.save_card(mcard_hash, mcard_content, "execution_log", timestamp=g_time, replace=False)
+    return mcard_file

clm/layer1/__init__.py

@@ -0,0 +1,31 @@
+"""CLM layer1 layer package."""
+
+from clm.layer1.gate_composer import compose_conditions_cmd, run_nested_evaluate
+from clm.layer1.matrix import IncidenceMatrix, math_gcd, math_lcm, solve_nullspace
+from clm.layer1.petri import ColoredPetriVM, petri_run_net
+from clm.layer1.runtime_adapter import (
+    evaluate_compose,
+    evaluate_polyglot,
+    run_internal_reference_test,
+)
+from clm.layer1.test_runner import run_algebra_op, test_baldwin_operators
+from clm.layer1.verifier import (
+    check_precondition_py,
+    emit_exec_mcard_py,
+    get_load_manifest,
+    get_load_manifest_str,
+    normalize_output_py,
+    resolve_active_hashes_py,
+    validate_postcondition,
+    verify_precondition,
+)
+from clm.layer1.vm import PetriVM
+
+__all__ = [
+    'petri_run_net', 'ColoredPetriVM', 'PetriVM', 'IncidenceMatrix', 'solve_nullspace', 'math_gcd', 'math_lcm',
+    'compose_conditions_cmd', 'run_nested_evaluate', 'run_internal_reference_test', 'evaluate_polyglot',
+    'evaluate_compose', 'get_load_manifest_str', 'get_load_manifest', 'verify_precondition',
+    'validate_postcondition', 'emit_exec_mcard_py', 'resolve_active_hashes_py', 'check_precondition_py',
+    'normalize_output_py', 'run_algebra_op', 'test_baldwin_operators'
+]
+

clm/layer1/action_dispatcher.py

@@ -0,0 +1,275 @@
+"""Action Execution Dispatcher (Sprint 393 / DEL-393-01).
+
+Bridges declarative Action manifests (clm.action.v1) to the Layer 1 algebraic execution core.
+Resolves content-addressed MCards, dispatches to domain-aware Baldwin manipulators,
+enforces the Zero Mutation Invariant on inputs, and registers output MCards in CAS.
+
+Acceptance Criteria:
+- AC-393-01-01: ActionDispatcher.execute() resolves inputs from CAS and returns typed ExecutionResult.
+- AC-393-01-02: Zero Mutation Invariant on input MCards (input hash unchanged post-execution).
+- AC-393-01-03: Unresolved input URIs raise InputResolutionError prior to operator execution.
+- AC-393-01-04: Execution metrics (wall time, bytes processed) recorded in ExecutionResult.
+
+Layer 1 module (no imports above L1).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from clm.cross_cutting.domain_models import MCard
+from clm.layer0.exceptions import CLMError
+from clm.layer0.model.action import ActionManifest
+from clm.layer0.model.card_triad import compute_canonical_hash
+from clm.layer0.utils import clm_hash_string
+from clm.layer1.operations.manipulators import (
+    DocumentManipulator,
+    MediaManipulator,
+    StructuredManipulator,
+    TabularManipulator,
+)
+
+
+class InputResolutionError(CLMError):
+    """Raised when an action input cannot be resolved from bindings or CAS."""
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """Certified outcome of an Action execution."""
+
+    status: str
+    operator: str
+    outputs: dict[str, MCard] = field(default_factory=dict)
+    input_hashes: dict[str, str] = field(default_factory=dict)
+    output_hashes: dict[str, str] = field(default_factory=dict)
+    metrics: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    @property
+    def is_success(self) -> bool:
+        return self.status == "success"
+
+
+class ActionDispatcher:
+    """Dispatches declarative Action manifests to Baldwin modality manipulators."""
+
+    @classmethod
+    def execute(
+        cls,
+        manifest: ActionManifest | str | Path | dict[str, Any],
+        input_bindings: dict[str, Any] | None = None,
+        fs: Any = None,
+    ) -> ExecutionResult:
+        """Execute an Action manifest against content-addressed MCards."""
+        t_start = time.perf_counter()
+        bindings = dict(input_bindings or {})
+
+        # 1. Parse manifest if string, Path, or dict
+        if isinstance(manifest, (str, Path)):
+            action = ActionManifest.from_yaml(manifest)
+        elif isinstance(manifest, dict):
+            action = ActionManifest.from_dict(manifest)
+        elif isinstance(manifest, ActionManifest):
+            action = manifest
+        else:
+            raise TypeError(f"Invalid manifest type: {type(manifest)}")
+
+        operator = action.operation.operator
+        params = action.operation.parameters or {}
+
+        # 2. Resolve inputs and check AC-393-01-03 (InputResolutionError)
+        resolved_inputs: dict[str, MCard] = {}
+        input_hashes_before: dict[str, str] = {}
+        original_card_hashes: dict[str, str] = {}
+        bytes_processed = 0
+
+        for inp in action.inputs:
+            card: MCard | None = None
+            # Check direct binding by input name or URI
+            if inp.name in bindings:
+                bound = bindings[inp.name]
+                if isinstance(bound, MCard):
+                    card = bound
+                else:
+                    # Raw payload provided, wrap in transient MCard
+                    digest = clm_hash_string(bound) if isinstance(bound, str) else compute_canonical_hash(bound)
+                    card = MCard.create(
+                        uri=f"mcard:{digest[:16]}",
+                        payload=bound,
+                        author="did:clm:user",
+                    )
+            elif inp.uri and inp.uri in bindings:
+                bound = bindings[inp.uri]
+                if isinstance(bound, MCard):
+                    card = bound
+                else:
+                    digest = clm_hash_string(bound) if isinstance(bound, str) else compute_canonical_hash(bound)
+                    card = MCard.create(
+                        uri=inp.uri,
+                        payload=bound,
+                        author="did:clm:user",
+                    )
+            elif inp.uri and fs is not None:
+                # Attempt resolution from CAS filesystem
+                try:
+                    clean_uri = inp.uri
+                    if clean_uri.startswith("mcard://"):
+                        clean_uri = "mcard:" + clean_uri[len("mcard://"):]
+                    card = fs.read_file(clean_uri)
+                except Exception:
+                    card = None
+
+            if card is None and inp.required:
+                raise InputResolutionError(
+                    f"Required input '{inp.name}' (uri={inp.uri}) could not be resolved"
+                )
+
+            if card is not None:
+                resolved_inputs[inp.name] = card
+                original_card_hashes[inp.name] = str(card.hash)
+                if isinstance(card.payload, str):
+                    h_str = clm_hash_string(card.payload)
+                elif isinstance(card.payload, bytes):
+                    from clm.layer0.utils import clm_hash_bytes
+                    h_str = clm_hash_bytes(card.payload)
+                else:
+                    h_str = str(card.hash)
+                input_hashes_before[inp.name] = h_str
+                # Count bytes
+                if isinstance(card.payload, (str, bytes)):
+                    bytes_processed += len(card.payload)
+                elif card.content:
+                    bytes_processed += len(card.content)
+
+        # 3. Select Modality Manipulator
+        primary_input = next(iter(resolved_inputs.values())) if resolved_inputs else None
+        primary_format = action.inputs[0].format if action.inputs else None
+
+        if primary_format is None and primary_input and hasattr(primary_input, "metadata"):
+            primary_format = primary_input.metadata.get("format")
+
+        manipulator = cls._select_manipulator(primary_format, primary_input)
+
+        # 4. Invoke Algebraic Operator
+        try:
+            payload = primary_input.payload if primary_input else None
+            op_method = getattr(manipulator, operator, None)
+            if not op_method:
+                raise ValueError(f"Manipulator {manipulator.__name__} does not support operator '{operator}'")
+
+            op_out = op_method(payload, params)
+
+            # 5. AC-393-01-02: Enforce Zero Mutation Invariant on inputs
+            for name, card in resolved_inputs.items():
+                expected_hash = original_card_hashes[name]
+                current_hash = str(card.hash)
+                if current_hash != expected_hash:
+                    raise AssertionError(
+                        f"Zero Mutation Invariant violated for input '{name}': hash mutated from {expected_hash} to {current_hash}"
+                    )
+
+            # 6. Map operator output to ActionOutputs
+            outputs: dict[str, MCard] = {}
+            output_hashes: dict[str, str] = {}
+
+            if isinstance(op_out, dict) and len(action.outputs) > 1:
+                # Multi-output split
+                for out_spec in action.outputs:
+                    out_name = out_spec.name
+                    part_payload = op_out.get(out_name)
+                    if part_payload is None:
+                        # Fallback to key index
+                        part_payload = next(iter(op_out.values()), "")
+
+                    digest = clm_hash_string(part_payload) if isinstance(part_payload, str) else compute_canonical_hash(part_payload)
+                    handle = out_spec.handle or f"mcard:{out_name}"
+                    clean_uri = handle if handle.startswith("mcard:") else f"mcard:{handle}"
+                    out_card = MCard.create(
+                        uri=clean_uri,
+                        payload=part_payload,
+                        author=action.clm.author,
+                        metadata={"format": out_spec.format or primary_format, "generator": action.clm.name},
+                    )
+                    outputs[out_name] = out_card
+                    output_hashes[out_name] = digest
+                    if fs is not None:
+                        fs.write_file(uri=clean_uri, payload=part_payload, author=action.clm.author, metadata=out_card.metadata)
+
+            else:
+                # Single output or undivided result
+                out_spec = action.outputs[0]
+                out_name = out_spec.name
+                part_payload = op_out.get(out_name, op_out) if isinstance(op_out, dict) else op_out
+
+                digest = clm_hash_string(part_payload) if isinstance(part_payload, str) else compute_canonical_hash(part_payload)
+                handle = out_spec.handle or f"mcard:{out_name}"
+                clean_uri = handle if handle.startswith("mcard:") else f"mcard:{handle}"
+                out_card = MCard.create(
+                    uri=clean_uri,
+                    payload=part_payload,
+                    author=action.clm.author,
+                    metadata={"format": out_spec.format or primary_format, "generator": action.clm.name},
+                )
+                outputs[out_name] = out_card
+                output_hashes[out_name] = digest
+                if fs is not None:
+                    fs.write_file(uri=clean_uri, payload=part_payload, author=action.clm.author, metadata=out_card.metadata)
+
+            t_elapsed = (time.perf_counter() - t_start) * 1000.0
+
+            return ExecutionResult(
+                status="success",
+                operator=operator,
+                outputs=outputs,
+                input_hashes=input_hashes_before,
+                output_hashes=output_hashes,
+                metrics={
+                    "wall_time_ms": round(t_elapsed, 3),
+                    "bytes_processed": bytes_processed,
+                    "operator": operator,
+                    "action_name": action.clm.name,
+                },
+            )
+
+        except Exception as e:
+            t_elapsed = (time.perf_counter() - t_start) * 1000.0
+            return ExecutionResult(
+                status="failed",
+                operator=operator,
+                input_hashes=input_hashes_before,
+                metrics={"wall_time_ms": round(t_elapsed, 3), "bytes_processed": bytes_processed},
+                error=str(e),
+            )
+
+    @staticmethod
+    def _select_manipulator(fmt: str | None, primary_input: MCard | None) -> type:
+        """Select appropriate modality manipulator."""
+        if fmt in ("csv", "tsv", "tabular"):
+            return TabularManipulator
+        if fmt in ("markdown", "text", "txt", "md"):
+            return DocumentManipulator
+        if fmt in ("json", "yaml", "yml"):
+            return StructuredManipulator
+        if fmt in ("image", "audio", "media", "binary", "model3d"):
+            return MediaManipulator
+
+        # Infer from payload
+        if primary_input and primary_input.payload is not None:
+            p = primary_input.payload
+            if isinstance(p, (dict, list)):
+                return StructuredManipulator
+            if isinstance(p, bytes):
+                return MediaManipulator
+            if isinstance(p, str):
+                if "\n" in p and ("," in p.splitlines()[0] or "\t" in p.splitlines()[0]):
+                    return TabularManipulator
+                if p.startswith("#") or "##" in p:
+                    return DocumentManipulator
+                if p.strip().startswith("{") or p.strip().startswith("["):
+                    return StructuredManipulator
+
+        return TabularManipulator