clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/mcard.py

@@ -0,0 +1,321 @@
+"""Cross-Cutting — MCard (Σ-type / Data Plane / Carrier)
+
+MCard is the root type / Dependent Sum (Σ-type) of the MVP Cards triad.
+It is the irreducible, content-addressed, immutable unit of data.
+Every other card (PCard, VCard) is ultimately stored *as* an MCard
+(the Empty Schema Principle).
+
+Design references:
+    - MVP Cards Design Rationale (§MCard — Data Plane)
+    - The Empty Schema Principle
+    - Function-Number Duality
+"""
+
+import os
+import time
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from clm.cross_cutting.telemetry import jsonl_emit_typed
+from clm.cross_cutting.timeutil import default_agent_did as _default_agent_did
+from clm.cross_cutting.timeutil import now_g_time as _now_g_time
+from clm.layer0.context import CLMContext
+from clm.layer0.utils import clm_hash_string as hash_string
+from clm.layer0.utils import prefixed_hash_raw
+
+# Unified Card Model (Sprint 131.1)
+# ---------------------------------------------------------------------------
+
+_TOKEN_WRAPPER = {
+    "mcard": "mcard",
+    "state": "state_token",
+    "pcard": "pcard_token",
+    "vcard": "vcard_token",
+}
+_WRAPPER_TO_TOKEN = {v: k for k, v in _TOKEN_WRAPPER.items()}
+
+
+class Card(BaseModel):
+    """The unified Monadic Card primitive (Sprint 131).
+
+    CLM is the single meta-language; this is its one object. ``token_type``
+    selects both the MLTT role and the YAML wrapper key emitted by
+    :meth:`to_yaml`, preserving byte-parity with the four legacy manual
+    formatters (``make_mcard_content``, ``emit_state_token``,
+    ``serialize_pcard``, ``vcard_gate``):
+
+        mcard  -> mcard:        (Σ-type / Noun Phrase / data plane)
+        state  -> state_token:  (Σ-subtype / PCard output snapshot)
+        pcard  -> pcard_token:  (Π-type / Verb Phrase / control plane)
+        vcard  -> vcard_token:  (Id-type / Sentence / verification witness)
+    """
+    token_type: Literal["mcard", "state", "pcard", "vcard"] = "mcard"
+    g_time: str = Field(default_factory=_now_g_time)
+    agent_did: str = Field(default_factory=_default_agent_did)
+    timestamp: str | None = None
+    operation: str | None = None
+
+    # mcard (data) payload
+    content_hash: str | None = None
+    content: str | None = None
+    source: dict[str, str] | None = None
+    runtime_facts: Any | None = None
+
+    # state (PCard output) payload
+    producer_pcard_hash: str | None = None
+    vcard_dispatch_hash: str | None = None
+    content_snapshot: str | None = None
+
+    # pcard (control) payload
+    runtime: str | None = None
+    script_hash: str | None = None
+    input_place_hashes: list[str] = Field(default_factory=list)
+    pcard_hash: str | None = None
+
+    # vcard (witness) payload
+    gate_type: Literal["callback", "dispatch"] | None = None
+    result: Literal["pass", "fail"] | None = None
+    sponsor_did: str | None = None
+    delegation_proof: str | None = None
+    execution_locale_hash: str | None = None
+    transport_ref: str | None = None
+    failure_reason: str | None = None
+    triggering_dispatch_hash: str | None = None
+    downstream_callback_targets: list[str] | None = None
+
+    # Sprint 132.5: cached hash (manual _hash_cache instead of frozen=True +
+    # cached_property, to avoid breaking list[str]/Any fields per spec §9.4).
+    _hash_cache: str | None = None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name != "_hash_cache" and hasattr(self, "_hash_cache"):
+            object.__setattr__(self, "_hash_cache", None)
+        super().__setattr__(name, value)
+
+    # -- serialization ------------------------------------------------
+
+    def _q(self, v: Any) -> str:
+        """Quote a scalar the way the legacy formatters do (always double-quoted)."""
+        s = str(v).replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{s}"'
+
+    def _yaml_list(self, key: str, items: list[str] | None, indent: str = "  ") -> str:
+        """Render a list field exactly like the legacy formatters."""
+        if not items:
+            return f"{indent}{key}: []"
+        out = f"{indent}{key}:\n"
+        for h in items:
+            out += f'{indent}  - {self._q(h)}\n'
+        return out.rstrip("\n")
+
+    def to_yaml(self) -> str:
+        """Canonical YAML with the wrapper key preserved.
+
+        Byte-parity target for the four legacy formatters. Each token_type
+        emits only the fields its legacy counterpart emits, in the same
+        order, with the same double-quoting and 4-space list indentation.
+        """
+        tt = self.token_type
+        if tt == "mcard":
+            src = self.source or {}
+            parts = ["mcard:"]
+            parts.append(f'  g_time: {self._q(self.g_time)}')
+            if self.content_hash is not None:
+                parts.append(f'  content_hash: {self._q(self.content_hash)}')
+            if src:
+                parts.append("  source:")
+                for k in ("filename", "mime_type", "encoding"):
+                    if k in src:
+                        parts.append(f'    {k}: {self._q(src[k])}')
+            if self.content is not None:
+                parts.append(f'  content: {self._q(self.content)}')
+            return "\n".join(parts) + "\n"
+
+        if tt == "pcard":
+            parts = ["pcard_token:"]
+            parts.append(f'  operation: {self._q(self.operation or "")}')
+            parts.append(f'  runtime: {self._q(self.runtime or "")}')
+            parts.append(f'  script_hash: {self._q(self.script_hash or "")}')
+            parts.append(f'  timestamp: {self._q(self.timestamp or "")}')
+            parts.append(self._yaml_list("input_place_hashes", self.input_place_hashes))
+            return "\n".join(parts)
+
+        if tt == "state":
+            parts = ["state_token:"]
+            parts.append(f'  token_type: {self._q("state")}')
+            parts.append(f'  producer_pcard_hash: {self._q(self.producer_pcard_hash or "")}')
+            parts.append(f'  vcard_dispatch_hash: {self._q(self.vcard_dispatch_hash or "")}')
+            parts.append(f'  timestamp: {self._q(self.timestamp or "")}')
+            parts.append(f'  agent_did: {self._q(self.agent_did)}')
+            parts.append(f'  content_snapshot: {self._q(self.content_snapshot or "")}')
+            return "\n".join(parts)
+
+        if tt == "vcard":
+            parts = ["vcard_token:"]
+            parts.append(f'  gate_type: {self._q(self.gate_type or "")}')
+            parts.append(f'  result: {self._q(self.result or "")}')
+            parts.append(f'  pcard_hash: {self._q(self.pcard_hash or "")}')
+            if self.gate_type == "callback":
+                parts.append(f'  triggering_dispatch_hash: {self._q(self.triggering_dispatch_hash or "")}')
+            parts.append(f'  timestamp: {self._q(self.timestamp or "")}')
+            parts.append(f'  agent_did: {self._q(self.agent_did)}')
+            parts.append(f'  sponsor_did: {self._q(self.sponsor_did or "")}')
+            parts.append(f'  delegation_proof: {self._q(self.delegation_proof or "")}')
+            parts.append(f'  execution_locale_hash: {self._q(self.execution_locale_hash or "")}')
+            parts.append(f'  transport_ref: {self._q(self.transport_ref or "")}')
+            if self.failure_reason is not None:
+                parts.append(f'  failure_reason: {self._q(self.failure_reason)}')
+            if self.gate_type == "callback":
+                # callback mode omits input_place_hashes entirely when empty
+                # (matches legacy formatter); only renders when non-empty
+                if self.input_place_hashes:
+                    parts.append(self._yaml_list("input_place_hashes", self.input_place_hashes))
+            else:
+                parts.append(self._yaml_list("downstream_callback_targets", self.downstream_callback_targets))
+            return "\n".join(parts)
+
+        raise ValueError(f"Unknown token_type: {tt}")
+
+    @classmethod
+    def from_yaml(cls, yaml_str: str) -> "Card":
+        """Parse a Card from its wrapper-key YAML representation."""
+        import yaml
+        data = yaml.safe_load(yaml_str)
+        if isinstance(data, dict) and len(data) == 1:
+            wrapper, payload = next(iter(data.items()))
+            token_type = _WRAPPER_TO_TOKEN.get(wrapper, "mcard")
+            if isinstance(payload, dict):
+                return cls(**{**payload, "token_type": token_type})
+        raise ValueError(f"Unrecognized card YAML: {yaml_str[:80]!r}")
+
+    def compute_hash(self) -> str:
+        """SHA-256 of the canonical YAML (deterministic, cached).
+
+        Sprint 132.5: result is cached via ``_hash_cache`` and invalidated
+        on any field mutation via ``__setattr__``.
+        """
+        if self._hash_cache is None:
+            object.__setattr__(self, "_hash_cache", hash_string(self.to_yaml()))
+        return self._hash_cache
+
+
+# ---------------------------------------------------------------------------
+# Sprint 384 (DEL-384-02): Re-export canonical MCard from Layer 0 card_triad
+from clm.layer0.model.card_triad import MCard  # noqa: F401
+
+# ---------------------------------------------------------------------------
+
+def emit_state_token(
+    ctx: CLMContext,
+    pcard_hash: str,
+    vcard_dispatch_hash: str,
+    content_input: str,
+) -> str:
+    """Emit a state token MCard and persist it to the execution log.
+
+    A state token captures the output of a PCard execution as a new
+    MCard, maintaining the algebraic closure invariant:
+    PCard(MCard) → MCard'.
+
+    Sprint 131.5: YAML emission now delegates to ``Card(token_type="state", ...).to_yaml()``
+    so the unified model is the single source of truth; the ``save_card_and_handle``,
+    ``jsonl_emit``, and on-disk log side effects are preserved.
+    """
+    timestamp = _now_g_time()
+    agent_did = _default_agent_did()
+
+    if os.path.exists(content_input):
+        file_size = os.path.getsize(content_input)
+        if file_size > 4096:
+            with open(content_input, "rb") as f:
+                h = hash_string(f.read())
+            content_snapshot = prefixed_hash_raw(h)
+        else:
+            with open(content_input, encoding="utf-8") as f:
+                content_snapshot = f.read()
+    else:
+        content_snapshot = content_input
+
+    state_yaml = Card(
+        token_type="state",
+        producer_pcard_hash=pcard_hash,
+        vcard_dispatch_hash=vcard_dispatch_hash,
+        timestamp=timestamp,
+        agent_did=agent_did,
+        content_snapshot=content_snapshot,
+    ).to_yaml()
+
+    state_hash = hash_string(state_yaml)
+    handle_name = f"mcard:state:{state_hash}"
+    ctx.repo.save_card_and_handle(
+        handle_name, state_hash, state_yaml, "execution_log",
+        timestamp=timestamp, replace=False,
+    )
+
+    jsonl_emit_typed("state_emitted", {
+        "state_hash": state_hash,
+        "producer_pcard_hash": pcard_hash,
+        "vcard_dispatch_hash": vcard_dispatch_hash,
+    }, ctx.root)
+
+    if not ctx.zero_fs:
+        logs_dir = os.path.join(ctx.root, "data", "execution_logs")
+        os.makedirs(logs_dir, exist_ok=True)
+        unix_ts = int(time.time())
+        log_file = os.path.join(logs_dir, f"state_{unix_ts}_{state_hash[:8]}.yaml")
+        with open(log_file, "w", encoding="utf-8") as fh:
+            fh.write(state_yaml)
+
+    return state_hash
+
+
+def emit_state_failed(
+    ctx: CLMContext,
+    pcard_hash: str,
+    exit_code: str,
+    reason: str,
+) -> None:
+    """Emit a state-failed event for a PCard that did not complete."""
+    jsonl_emit_typed("state_failed", {
+        "pcard_hash": pcard_hash,
+        "exit_code": exit_code,
+        "reason": reason,
+    }, ctx.root)
+
+
+def make_mcard_content(
+    content_hash: str,
+    content: str,
+    filename: str = "test.txt",
+    mime: str = "text/plain",
+) -> str:
+    """Return a canonical MCard YAML content block (Sprint 131.5: thin delegate).
+
+    Delegates to :class:`Card` so the unified model is the single source of
+    truth for serialization, while preserving the exact signature and output
+    that ``build_store``'s ``services.modules`` injection and the
+    ``make_mcard_content`` CLM expression op depend on.
+    """
+    return Card(
+        token_type="mcard",
+        g_time="sha256|2026-04-29T00:00:00+0800|Asia/Makassar",
+        content_hash=content_hash,
+        content=content,
+        source={"filename": filename, "mime_type": mime, "encoding": "inline"},
+    ).to_yaml()
+
+
+# Sprint 133.1: moved from layer0/db.py — parses MCard YAML, belongs with Card.
+def parse_yaml_mcard(mcard_content_str: str) -> tuple[str | None, str | None, str | None]:
+    """Extract content_hash, g_time, and source filename from MCard YAML."""
+    import re
+    hash_match = re.search(r'content_hash:\s*["\']?([a-fA-F0-9]{64})["\']?', mcard_content_str)
+    gtime_match = re.search(r'g_time:\s*["\']?([^"\n\']+)["\']?', mcard_content_str)
+    filename_match = re.search(r'filename:\s*["\']?([^"\n\']+)["\']?', mcard_content_str)
+
+    content_hash = hash_match.group(1) if hash_match else None
+    g_time = gtime_match.group(1) if gtime_match else None
+    source_filename = filename_match.group(1) if filename_match else None
+
+    return content_hash, g_time, source_filename

clm/cross_cutting/native.py

@@ -0,0 +1,185 @@
+"""Native acceleration dispatcher with transparent pure-Python fallback.
+
+Provides high-performance in-memory bindings to the Rust core runtime (_rust)
+via PyO3 when compiled wheels or maturin development environments are available.
+Automatically falls back to pure-Python implementations when native extensions
+are absent, ensuring zero runtime disruption in interpreted environments.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Optional, Union
+
+from clm.cross_cutting.clm_logger import get_logger
+
+_logger = get_logger("clm.native")
+
+try:
+    from clm import _rust  # type: ignore[attr-defined]
+    HAS_RUST_ACCELERATION: bool = True
+except (ImportError, ModuleNotFoundError):
+    try:
+        import clm_rust_core as _rust  # type: ignore[no-redef]
+        HAS_RUST_ACCELERATION = True
+    except (ImportError, ModuleNotFoundError):
+        try:
+            import _rust  # type: ignore[no-redef]
+            HAS_RUST_ACCELERATION = True
+        except (ImportError, ModuleNotFoundError):
+            _rust = None  # type: ignore[assignment]
+            HAS_RUST_ACCELERATION = False
+            _logger.debug("Rust native extension (_rust) unavailable; utilizing pure-Python engine.")
+
+
+def compute_blake3(data: Union[bytes, bytearray, memoryview, str]) -> str:
+    """Compute cryptographic hash via native Rust engine if available, or Python fallback.
+
+    Args:
+        data: Input bytes or string to hash.
+
+    Returns:
+        Hex-encoded hash digest string.
+    """
+    raw_bytes = data.encode("utf-8") if isinstance(data, str) else bytes(data)
+
+    if HAS_RUST_ACCELERATION and _rust is not None:
+        try:
+            return _rust.blake3_hash_bytes(raw_bytes)
+        except Exception as e:
+            _logger.warning(f"Native blake3_hash_bytes failed ({e}); falling back to Python.")
+
+    # Pure-Python fallback using layer0 cryptographic hash
+    from clm.layer0.hash import compute_blake3 as _l0_blake3
+    return _l0_blake3(raw_bytes)
+
+
+def clm_hash_file_fast(path: str) -> str:
+    """Compute content hash for a file, releasing GIL in Rust or using Python fallback.
+
+    Args:
+        path: Filesystem path to the target file.
+
+    Returns:
+        Hex-encoded content hash string.
+    """
+    if HAS_RUST_ACCELERATION and _rust is not None:
+        try:
+            return _rust.clm_hash_file(path)
+        except Exception as e:
+            _logger.warning(f"Native clm_hash_file failed ({e}); falling back to Python.")
+
+    from clm.layer0.utils import clm_hash_file
+    return clm_hash_file(path)
+
+
+def crdt_merge_fast(log_a_json: str, log_b_json: str) -> str:
+    """Merge two CRDT logs idempotently via native Rust engine or pure-Python fallback.
+
+    Args:
+        log_a_json: Primary CRDT log serialized as JSON.
+        log_b_json: Secondary CRDT log serialized as JSON.
+
+    Returns:
+        Merged CRDT log serialized as JSON.
+    """
+    if HAS_RUST_ACCELERATION and _rust is not None and hasattr(_rust, "crdt_merge"):
+        try:
+            return _rust.crdt_merge(log_a_json, log_b_json)
+        except Exception as e:
+            _logger.warning(f"Native crdt_merge failed ({e}); falling back to Python.")
+
+    # Pure Python JSON-level idempotent union fallback
+    try:
+        a = json.loads(log_a_json)
+        b = json.loads(log_b_json)
+        key = "entries" if "entries" in a else "events"
+        events_a = a.get(key, [])
+        events_b = b.get(key, [])
+        seen_ids = {e.get("event_id") for e in events_a if "event_id" in e}
+        for ev in events_b:
+            eid = ev.get("event_id")
+            if eid and eid not in seen_ids:
+                events_a.append(ev)
+                seen_ids.add(eid)
+        a[key] = events_a
+        return json.dumps(a)
+    except Exception:
+        return log_a_json
+
+
+ManifestEvaluatorFn = Callable[[str], Any]
+_manifest_evaluator: ManifestEvaluatorFn | None = None
+_manifest_evaluator_resolver: Callable[[], ManifestEvaluatorFn | None] | None = None
+
+
+def register_manifest_evaluator(evaluator: ManifestEvaluatorFn) -> None:
+    """Register a manifest evaluator callback (Dependency Inversion for layer stratification)."""
+    global _manifest_evaluator
+    _manifest_evaluator = evaluator
+
+
+def register_manifest_evaluator_resolver(resolver: Callable[[], ManifestEvaluatorFn | None]) -> None:
+    """Register a lazy resolver for the manifest evaluator."""
+    global _manifest_evaluator_resolver
+    _manifest_evaluator_resolver = resolver
+
+
+def evaluate_manifest(manifest_yaml: str) -> str:
+    """Evaluate manifest using in-memory native CPN-VM or pure-Python verifier.
+
+    Propagates active Cordis monadic context (session_id, agent_did, trace_id)
+    across the FFI boundary. Falls back to Python verifier if Rust extension is absent
+    or encounters error.
+
+    Args:
+        manifest_yaml: Raw YAML string of the CLM specification.
+
+    Returns:
+        Evaluation result string or generated MCard handle.
+    """
+    from clm.layer0.context import CLMContext
+    current_ctx = CLMContext.current()
+    context_json: Optional[str] = None
+    if current_ctx is not None:
+        context_json = json.dumps({
+            "session_id": getattr(current_ctx, "session_id", None),
+            "agent_did": getattr(current_ctx, "agent_did", None),
+            "trace_id": getattr(current_ctx, "trace_id", None),
+            "zero_fs": getattr(current_ctx, "zero_fs", False),
+        })
+
+    if HAS_RUST_ACCELERATION and _rust is not None:
+        try:
+            return _rust.evaluate_manifest_fast(manifest_yaml, context_json)
+        except Exception as e:
+            _logger.warning(f"Native evaluate_manifest_fast failed ({e}); falling back to Python.")
+
+    if _manifest_evaluator is not None:
+        return _manifest_evaluator(manifest_yaml)
+
+    if _manifest_evaluator_resolver is not None:
+        evaluator = _manifest_evaluator_resolver()
+        if evaluator is not None:
+            return evaluator(manifest_yaml)
+
+    raise RuntimeError(
+        "No manifest evaluator registered with cross_cutting.native. "
+        "Initialize Layer 1 verifier (clm.layer1.verifier) before evaluating manifests."
+    )
+
+
+def evaluate_in_process(clm_root: str, clm_file: str, payload: Optional[str] = None) -> Optional[tuple[int, str]]:
+    """Direct in-process evaluation of a CLM manifest via PyO3 C-extension without process forks.
+
+    Returns:
+        (exit_code, output) tuple, or None if native extension is unavailable.
+    """
+    if HAS_RUST_ACCELERATION and _rust is not None and hasattr(_rust, "evaluate_in_process"):
+        try:
+            return _rust.evaluate_in_process(clm_root, clm_file, payload)
+        except Exception as e:
+            _logger.warning(f"Native evaluate_in_process failed ({e}); falling back.")
+            return None
+    return None
+