clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/ontology/collection.py

@@ -0,0 +1,125 @@
+"""
+mcard/ontology/collection.py
+MCardCollection Resolver Prototype
+Implements unified management and resolution across all three MCard morphologies:
+- DirectoryMCard
+- FileMCard
+- UriMCard
+"""
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class MorphologyType(str, Enum):
+    DIRECTORY = "directory"
+    FILE = "file"
+    URI = "uri"
+
+
+@dataclass
+class DirectoryMCard:
+    path: Path
+    role: str
+    manifest: dict[str, Any]
+    mcard_morphology: str = "directory"
+    tree_hash: str = ""
+
+    def __post_init__(self):
+        if not self.tree_hash:
+            self.tree_hash = self._compute_tree_hash()
+
+    def _compute_tree_hash(self) -> str:
+        # Canonical hash of manifest content
+        manifest_str = yaml.dump(self.manifest, sort_keys=True)
+        return hashlib.sha256(manifest_str.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class FileMCard:
+    hash: str
+    content: str | dict[str, Any]
+    mime_type: str
+    g_time: int
+    mcard_morphology: str = "file"
+    tags: list[str] = field(default_factory=list)
+    handles: list[str] = field(default_factory=list)
+
+
+@dataclass
+class UriMCard:
+    uri: str
+    protocol: str
+    mcard_morphology: str = "uri"
+    digest: str = ""
+    entrypoint: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class MCardCollection:
+    """Unified collection and resolver for all three MCard morphologies."""
+
+    def __init__(self):
+        self._entries: dict[str, DirectoryMCard | FileMCard | UriMCard] = {}
+
+    def register_directory(self, path: str | Path) -> DirectoryMCard:
+        dir_path = Path(path).expanduser().resolve()
+        manifest_file = dir_path / "mcard.yaml"
+        if not manifest_file.exists():
+            raise FileNotFoundError(f"Missing mcard.yaml in directory: {dir_path}")
+
+        with open(manifest_file, encoding="utf-8") as f:
+            manifest = yaml.safe_load(f)
+
+        role = manifest.get("role", "developmental-subsystem")
+        dm = DirectoryMCard(path=dir_path, role=role, manifest=manifest)
+        self._entries[f"dir:{dir_path.name}"] = dm
+        return dm
+
+    def register_file(
+        self,
+        content: str | dict[str, Any],
+        mime_type: str = "text/plain",
+        g_time: int = 1,
+    ) -> FileMCard:
+        if isinstance(content, dict):
+            raw_bytes = yaml.dump(content, sort_keys=True).encode("utf-8")
+        else:
+            raw_bytes = content.encode("utf-8")
+
+        file_hash = hashlib.sha256(raw_bytes).hexdigest()
+        fm = FileMCard(
+            hash=file_hash, content=content, mime_type=mime_type, g_time=g_time
+        )
+        self._entries[f"file:{file_hash}"] = fm
+        return fm
+
+    def register_uri(
+        self, uri: str, protocol: str = "", entrypoint: str = ""
+    ) -> UriMCard:
+        if not protocol:
+            protocol = uri.split("://")[0] if "://" in uri else "uri"
+
+        um = UriMCard(uri=uri, protocol=protocol, entrypoint=entrypoint)
+        self._entries[f"uri:{uri}"] = um
+        return um
+
+    def get(self, key: str) -> DirectoryMCard | FileMCard | UriMCard | None:
+        return self._entries.get(key)
+
+    def list_by_morphology(
+        self, morphology: str
+    ) -> list[DirectoryMCard | FileMCard | UriMCard]:
+        return [
+            item
+            for item in self._entries.values()
+            if item.mcard_morphology == morphology
+        ]
+
+    def count(self) -> int:
+        return len(self._entries)

clm/layer0/parser.py

@@ -0,0 +1,429 @@
+"""Unified Two-Pass CLM Parser (DV-374-01).
+
+Implements the unified CLM interpretation pipeline:
+- Pass 1 (Structural - ⊤): Path reference interception, CAS file wrapping into MCards,
+  environment variable substitution, and dimension extraction. Fully subsumes legacy ClmRoot.
+- Pass 2 (Semantic - Lattice Descent): Triadic normalization ({abstract, concrete, balanced, meta}),
+  compilation of CEL pre/postcondition invariants into VCard meet gates, and compilation of
+  Baldwin modularity operators into Coloured Petri Net (CPN) subgraphs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+import yaml
+
+from clm.layer0.cel_eval import CelEvaluator
+from clm.layer0.model.card import MCard
+from clm.layer0.model.dictionary import ClmReservedWords, DataSemanticType
+from clm.layer0.model.pcard import PCard
+from clm.layer0.model.vcard import VCard
+
+_ENV_VAR_PATTERN = re.compile(r"\$\{([A-Za-z0-9_]+)(?::-([^}]*))?\}|\$([A-Za-z0-9_]+)")
+
+# Compiler hook for Baldwin Modularity Operators (Dependency Inversion: Layer 1 registers compiler)
+BaldwinCompilerFn = Callable[[list[dict[str, Any]]], dict[str, Any]]
+_baldwin_compiler: BaldwinCompilerFn | None = None
+
+
+def register_baldwin_compiler(compiler: BaldwinCompilerFn) -> None:
+    """Register a Baldwin CPN compiler from Layer 1."""
+    global _baldwin_compiler
+    _baldwin_compiler = compiler
+
+
+def substitute_env_vars(text: str, env: dict[str, str] | None = None) -> str:
+    """Substitutes ${VAR:-default} and $VAR occurrences from env or os.environ."""
+    source_env = os.environ if env is None else env
+
+    def _replace(match: re.Match) -> str:
+        var_name = match.group(1) or match.group(3)
+        default_val = match.group(2) if match.group(2) is not None else ""
+        return source_env.get(var_name, default_val)
+
+    return _ENV_VAR_PATTERN.sub(_replace, text)
+
+
+@dataclass
+class ParsedClmAst:
+    """Canonical representation of a parsed CLM specification."""
+
+    raw: dict[str, Any]
+    abstract: dict[str, Any]
+    concrete: dict[str, Any]
+    balanced: dict[str, Any]
+    meta: dict[str, Any]
+    preconditions: list[str] = field(default_factory=list)
+    postconditions: list[str] = field(default_factory=list)
+    cel_evaluators: dict[str, CelEvaluator] = field(default_factory=dict)
+    baldwin_nets: dict[str, Any] = field(default_factory=dict)
+    cards: tuple[MCard, MCard, PCard, VCard, list[MCard]] | None = None
+    chapter: dict[str, Any] | None = None
+    chapter_name: str | None = None
+    chapter_number: int | None = None
+    narrative: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the AST into a structural dictionary for AST parity validation."""
+        data = {
+            "abstract": self.abstract,
+            "concrete": self.concrete,
+            "balanced": self.balanced,
+            "meta": self.meta,
+            "preconditions": self.preconditions,
+            "postconditions": self.postconditions,
+            "baldwin_operator_count": len(self.baldwin_nets),
+        }
+        if self.chapter_name is not None:
+            data["chapter_name"] = self.chapter_name
+        if self.chapter_number is not None:
+            data["chapter_number"] = self.chapter_number
+        if self.narrative is not None:
+            data["narrative"] = self.narrative
+        return data
+
+
+class UnifiedClmParser:
+    """Unified Two-Pass CLM Parser subsuming legacy ClmRoot and implementing multi-pass semantic descent."""
+
+    # ── Pass 1: Structural Resolution & Path Interception ───────────────────
+
+    @classmethod
+    def extract_dimension(cls, val: Any, keys: list[str]) -> Any:
+        """Recursively searches through a YAML dict tree to find dimension keys."""
+        if isinstance(val, dict):
+            for key_str in keys:
+                if key_str in val:
+                    return val[key_str]
+            for child_val in val.values():
+                found = cls.extract_dimension(child_val, keys)
+                if found is not None:
+                    return found
+        return None
+
+    @classmethod
+    def traverse_and_intercept(
+        cls,
+        value: Any,
+        dictionary: ClmReservedWords | None,
+        g_time: str,
+        extra_cards: list[MCard],
+        clm_dir: Path | None = None,
+    ) -> None:
+        """Mutably traverses the YAML tree, wrapping physical files into CAS MCards and replacing paths with content hashes."""
+        if isinstance(value, dict):
+            changes = {}
+            for k, v in value.items():
+                is_path_ref = False
+                if dictionary and isinstance(k, str):
+                    semantic_type = dictionary.lookup(k)
+                    if semantic_type == DataSemanticType.PathReference:
+                        is_path_ref = True
+                elif isinstance(k, str) and k in {
+                    "file",
+                    "file_path",
+                    "path",
+                    "source_path",
+                    "script_path",
+                    "content_path",
+                }:
+                    is_path_ref = True
+
+                if is_path_ref and isinstance(v, str):
+                    target_path = (clm_dir / v) if clm_dir else Path(v)
+                    if target_path.exists() and target_path.is_file():
+                        try:
+                            bytes_content = target_path.read_bytes()
+                            new_card = MCard(content=bytes_content)
+                            changes[k] = str(new_card.hash)
+                            extra_cards.append(new_card)
+                        except Exception:
+                            pass
+
+                cls.traverse_and_intercept(v, dictionary, g_time, extra_cards, clm_dir)
+
+            for k_str, new_val in changes.items():
+                value[k_str] = new_val
+
+        elif isinstance(value, list):
+            for element in value:
+                cls.traverse_and_intercept(
+                    element, dictionary, g_time, extra_cards, clm_dir
+                )
+
+    @classmethod
+    def map_to_cards(
+        cls,
+        yaml_bytes: bytes,
+        g_time: str,
+        dictionary: ClmReservedWords | None = None,
+        clm_dir: Path | None = None,
+    ) -> tuple[MCard, MCard, PCard, VCard, list[MCard]]:
+        """Maps raw YAML bytes into Card topology (root, abstract, concrete, balanced, extra)."""
+        yaml_str = yaml_bytes.decode("utf-8")
+        extra_cards: list[MCard] = []
+
+        root_mcard = MCard(content=yaml_bytes)
+        parsed = yaml.safe_load(yaml_str) or {}
+
+        if dictionary or clm_dir:
+            cls.traverse_and_intercept(parsed, dictionary, g_time, extra_cards, clm_dir)
+
+        # 2. Abstract Section -> MCard
+        abstract_dim = cls.extract_dimension(parsed, ["abstract", "abstract_spec", "A"])
+        abstract_bytes = (
+            yaml.safe_dump(abstract_dim).encode("utf-8")
+            if abstract_dim is not None
+            else b"null\n"
+        )
+        abstract_mcard = MCard(content=abstract_bytes)
+
+        # 3. Concrete Section -> PCard
+        concrete_dim = cls.extract_dimension(parsed, ["concrete", "concrete_impl", "C"])
+        concrete_bytes = (
+            yaml.safe_dump(concrete_dim).encode("utf-8")
+            if concrete_dim is not None
+            else b"{}\n"
+        )
+        pcard = PCard(concrete_bytes)
+
+        # 4. Balanced Section -> VCard
+        balanced_dim = cls.extract_dimension(parsed, ["balanced", "balanced_exp", "B"])
+        balanced_bytes = (
+            yaml.safe_dump(balanced_dim).encode("utf-8")
+            if balanced_dim is not None
+            else b"{}\n"
+        )
+        vcard = VCard(balanced_bytes)
+
+        return (root_mcard, abstract_mcard, pcard, vcard, extra_cards)
+
+    # ── Pass 2: Semantic Analysis & Lattice Descent ─────────────────────────
+
+    @classmethod
+    def parse(
+        cls,
+        input_data: str | bytes | dict[str, Any],
+        clm_dir: Path | None = None,
+        env: dict[str, str] | None = None,
+        g_time: str = "1970-01-01T00:00:00Z",
+        dictionary: ClmReservedWords | None = None,
+    ) -> ParsedClmAst:
+        """Full Two-Pass CLM Parse: Structural Ingestion + Semantic Descent."""
+        # Normalize input to string and raw dict
+        if isinstance(input_data, bytes):
+            raw_text = input_data.decode("utf-8")
+            raw_text = substitute_env_vars(raw_text, env)
+            raw_dict = yaml.safe_load(raw_text) or {}
+            source_bytes = input_data
+        elif isinstance(input_data, str):
+            raw_text = substitute_env_vars(input_data, env)
+            raw_dict = yaml.safe_load(raw_text) or {}
+            source_bytes = raw_text.encode("utf-8")
+        elif isinstance(input_data, dict):
+            raw_dict = input_data
+            source_bytes = yaml.safe_dump(raw_dict).encode("utf-8")
+        else:
+            raise TypeError(f"Unsupported input type for CLM parser: {type(input_data)}")
+
+        # Pass 1: Card mapping & path interception
+        cards = cls.map_to_cards(
+            yaml_bytes=source_bytes,
+            g_time=g_time,
+            dictionary=dictionary,
+            clm_dir=clm_dir,
+        )
+
+        # Pass 2: Triadic Normalization & Dialect Detection
+        clm_root = raw_dict.get("clm", raw_dict) if isinstance(raw_dict, dict) else {}
+        if not isinstance(clm_root, dict):
+            clm_root = {}
+
+        abstract = (
+            clm_root.get("abstract")
+            or clm_root.get("abstract_spec")
+            or clm_root.get("A")
+            or {}
+        )
+        concrete = (
+            clm_root.get("concrete")
+            or clm_root.get("concrete_impl")
+            or clm_root.get("C")
+            or {}
+        )
+        balanced = (
+            clm_root.get("balanced")
+            or clm_root.get("balanced_exp")
+            or clm_root.get("B")
+            or {}
+        )
+        meta = (
+            clm_root.get("_meta")
+            or clm_root.get("meta")
+            or raw_dict.get("_meta")
+            or raw_dict.get("meta")
+            or {}
+        )
+
+        # Dialect B Synthesis: Formal CPN Net Specification
+        places = raw_dict.get("places") or clm_root.get("places")
+        transitions = raw_dict.get("transitions") or clm_root.get("transitions")
+        if places or transitions:
+            if not abstract:
+                abstract = {"places": places or [], "transitions": transitions or []}
+            if not concrete:
+                concrete = {"transitions": transitions or [], "arrows": raw_dict.get("arrows", [])}
+            if not balanced:
+                balanced = {"guards": raw_dict.get("guards", []), "invariants": raw_dict.get("invariants", [])}
+
+        # Chapter & Narrative Metadata Extraction
+        chapter_data = raw_dict.get("chapter") or clm_root.get("chapter")
+        chapter_dict: dict[str, Any] | None = chapter_data if isinstance(chapter_data, dict) else None
+        chapter_name: str | None = None
+        chapter_number: int | None = None
+        narrative: str | None = None
+
+        if chapter_dict:
+            chapter_name = chapter_dict.get("title") or chapter_dict.get("name")
+            num_val = chapter_dict.get("id") or chapter_dict.get("number")
+            if num_val is not None:
+                try:
+                    chapter_number = int(num_val)
+                except (ValueError, TypeError):
+                    chapter_number = None
+            narrative = chapter_dict.get("narrative") or chapter_dict.get("description")
+        else:
+            narrative = raw_dict.get("narrative") or clm_root.get("narrative")
+
+        # Precondition / Postcondition Extraction
+        preconditions: list[str] = []
+        postconditions: list[str] = []
+
+        if isinstance(concrete, dict):
+            pre = concrete.get("precondition") or concrete.get("vcard_pre")
+            if isinstance(pre, str):
+                preconditions.append(pre)
+            elif isinstance(pre, dict):
+                vpre = pre.get("vcard_pre") or pre.get("expr")
+                if isinstance(vpre, str):
+                    preconditions.append(vpre)
+
+            post = concrete.get("postcondition") or concrete.get("vcard_post")
+            if isinstance(post, str):
+                postconditions.append(post)
+            elif isinstance(post, dict):
+                vpost = post.get("vcard_post") or post.get("expr")
+                if isinstance(vpost, str):
+                    postconditions.append(vpost)
+
+        # Compile CEL Invariant Gates
+        cel_evaluators: dict[str, CelEvaluator] = {}
+        for idx, cond in enumerate(preconditions):
+            cel_evaluators[f"pre_{idx}"] = CelEvaluator(cond)
+        for idx, cond in enumerate(postconditions):
+            cel_evaluators[f"post_{idx}"] = CelEvaluator(cond)
+
+        # Compile Baldwin Modularity Operators (Dependency Inversion for INV-383-02)
+        baldwin_nets: dict[str, Any] = {}
+        operators = (
+            raw_dict.get("operators")
+            or clm_root.get("operators")
+            or (concrete.get("operators") if isinstance(concrete, dict) else None)
+        )
+        if isinstance(operators, list):
+            if _baldwin_compiler is not None:
+                try:
+                    baldwin_nets = _baldwin_compiler(operators)
+                except Exception:
+                    pass
+            else:
+                import sys
+
+                gen_mod = sys.modules.get("clm.layer1.algebra_baldwin_generators")
+                arrow_mod = sys.modules.get("clm.layer1.arrow_compiler")
+                if gen_mod and arrow_mod:
+                    try:
+                        Arrow = getattr(arrow_mod, "Arrow", None)
+                        BaldwinCpnGenerators = getattr(gen_mod, "BaldwinCpnGenerators", None)
+                        if Arrow and BaldwinCpnGenerators:
+                            for op_def in operators:
+                                if not isinstance(op_def, dict):
+                                    continue
+                                op_name = op_def.get("name")
+                                if not op_name:
+                                    continue
+                                if op_name == "split":
+                                    base_arr = Arrow.arr(lambda x: x, name="base")
+                                    net = BaldwinCpnGenerators.split(
+                                        base_arr,
+                                        branch_a_fn=lambda x: x,
+                                        branch_b_fn=lambda x: x,
+                                        name_prefix=f"ast_{op_name}",
+                                    )
+                                    baldwin_nets[op_name] = net
+                                elif op_name == "invert":
+                                    pair_arr = Arrow.arr(lambda x: (x, x), name="pair")
+                                    net = BaldwinCpnGenerators.invert(pair_arr)
+                                    baldwin_nets[op_name] = net
+                    except Exception:
+                        pass
+
+        return ParsedClmAst(
+            raw=raw_dict,
+            abstract=abstract if isinstance(abstract, dict) else {"spec": abstract},
+            concrete=concrete if isinstance(concrete, dict) else {"impl": concrete},
+            balanced=balanced if isinstance(balanced, dict) else {"exp": balanced},
+            meta=meta if isinstance(meta, dict) else {"meta": meta},
+            preconditions=preconditions,
+            postconditions=postconditions,
+            cel_evaluators=cel_evaluators,
+            baldwin_nets=baldwin_nets,
+            cards=cards,
+            chapter=chapter_dict,
+            chapter_name=chapter_name,
+            chapter_number=chapter_number,
+            narrative=narrative,
+        )
+
+    @classmethod
+    def parse_file(
+        cls,
+        file_path: str | Path,
+        env: dict[str, str] | None = None,
+        g_time: str = "1970-01-01T00:00:00Z",
+        dictionary: ClmReservedWords | None = None,
+    ) -> ParsedClmAst:
+        """Parses a CLM manifest or chapter specification file from disk."""
+        path = Path(file_path).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"CLM specification file not found: {path}")
+
+        if path.is_dir():
+            candidates = ["manifest.yaml", "manifest.yml", "clm.yaml", "clm.yml", "index.yaml"]
+            for cand in candidates:
+                cand_path = path / cand
+                if cand_path.exists():
+                    return cls.parse_file(cand_path, env=env, g_time=g_time, dictionary=dictionary)
+            yaml_files = sorted(list(path.glob("*.yaml")) + list(path.glob("*.yml")))
+            if yaml_files:
+                return cls.parse_file(yaml_files[0], env=env, g_time=g_time, dictionary=dictionary)
+            raise ValueError(f"No CLM YAML manifests found in directory: {path}")
+
+        source_bytes = path.read_bytes()
+        return cls.parse(
+            input_data=source_bytes,
+            clm_dir=path.parent,
+            env=env,
+            g_time=g_time,
+            dictionary=dictionary,
+        )
+
+
+# Canonical alias for backward compatibility across the repository
+ClmRoot = UnifiedClmParser
+

clm/layer0/relations.py

@@ -0,0 +1,73 @@
+"""Relational card queries (Sprint 133.1 + 133.6).
+
+Extracted from ``CLMRepository`` in ``db.py``. These methods import ``Card``
+from ``cross_cutting.mcard`` lazily (inside function bodies) to avoid a
+``layer0 -> cross_cutting`` import cycle. Isolating them here makes the
+cycle explicit and documented rather than hidden inside a 1,100-line
+god-module.
+
+Long-term fix (Sprint 134): move ``Card`` to ``layer0/card.py`` so
+``layer0`` has no upward dependency on ``cross_cutting`` at all.
+"""
+import contextlib
+import json as _json
+from typing import Any
+
+
+def query_card_relations(repo: Any, card_hash: str, pillar: str = "execution_log") -> dict[str, list]:
+    """Resolve related cards via SQLite relational calculus (Sprint 131.2).
+
+    Returns ``{"inputs": [...], "outputs": [...], "processes": [...]}``
+    where each entry is a parsed ``Card``.
+    """
+    from clm.cross_cutting.mcard import Card
+
+    relations: dict[str, list] = {"inputs": [], "outputs": [], "processes": []}
+
+    content = repo.get_card_content(card_hash, pillar)
+    if not content:
+        return relations
+    try:
+        card = Card.from_yaml(content)
+    except Exception:
+        return relations
+
+    if card.token_type == "pcard":
+        for h in card.input_place_hashes:
+            c = repo.get_card_content(h, pillar)
+            if c:
+                with contextlib.suppress(Exception):
+                    relations["inputs"].append(Card.from_yaml(c))
+        for cand in _scan_cards_containing(repo, pillar, card_hash):
+            if getattr(cand, "producer_pcard_hash", None) == card_hash:
+                relations["outputs"].append(cand)
+
+    elif card.token_type == "vcard":
+        if card.pcard_hash:
+            c = repo.get_card_content(card.pcard_hash, pillar)
+            if c:
+                with contextlib.suppress(Exception):
+                    relations["processes"].append(Card.from_yaml(c))
+
+    else:  # mcard or state
+        for cand in _scan_cards_containing(repo, pillar, card_hash):
+            if (cand.token_type == "pcard" and card_hash in (cand.input_place_hashes or [])) \
+                    or getattr(cand, "producer_pcard_hash", None) == card_hash:
+                relations["processes"].append(cand)
+
+    return relations
+
+
+def _scan_cards_containing(repo: Any, pillar: str, needle: str) -> list:
+    """Scan all cards in a pillar and return parsed Cards whose content
+    mentions ``needle``. Used as the FTS5 fallback per §6.2 risk row."""
+    from clm.cross_cutting.mcard import Card
+
+    rows_json = repo.db.execute(pillar, "SELECT content FROM card;", as_json=True)
+    out = []
+    for row in _json.loads(rows_json or "[]"):
+        content = row.get("content", "")
+        if needle in content:
+            with contextlib.suppress(Exception):
+                out.append(Card.from_yaml(content))
+    return out