clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/math_utils.py

@@ -0,0 +1,163 @@
+"""Mathematical utility functions for the CLM Petri Net runtime."""
+
+
+def math_gcd(a: int, b: int) -> int:
+    """
+    Computes the greatest common divisor of two integers.
+    """
+    a = abs(a)
+    b = abs(b)
+    while b > 0:
+        a, b = b, a % b
+    return a
+
+def math_lcm(a: int, b: int) -> int:
+    """
+    Computes the least common multiple of two integers.
+    """
+    if a == 0 or b == 0:
+        return 0
+    return abs(a * b) // math_gcd(a, b)
+
+def solve_nullspace(matrix: list[list[int]], rows: int, cols: int, transpose: bool = False) -> list[list[int]]:
+    """
+    Solves for the rational nullspace of a matrix.
+
+    Args:
+        matrix (List[List[int]]): The matrix to evaluate.
+        rows (int): The number of rows.
+        cols (int): The number of columns.
+        transpose (bool): True if the matrix should be transposed before solving.
+
+    Returns:
+        List[List[int]]: A basis for the nullspace.
+    """
+    work_rows, work_cols = (cols, rows) if transpose else (rows, cols)
+    if work_rows == 0 or work_cols == 0:
+        return []
+
+    a_mat = [[0] * work_cols for _ in range(work_rows)]
+    for r in range(work_rows):
+        for c in range(work_cols):
+            if transpose:
+                if c < len(matrix) and r < len(matrix[c]):
+                    a_mat[r][c] = matrix[c][r]
+            else:
+                if r < len(matrix) and c < len(matrix[r]):
+                    a_mat[r][c] = matrix[r][c]
+
+    pivot_row = [-1] * work_cols
+    is_free = [True] * work_cols
+
+    p = 0
+    c = 0
+    while c < work_cols and p < work_rows:
+        pr = p
+        found = False
+        while pr < work_rows:
+            if a_mat[pr][c] != 0:
+                found = True
+                break
+            pr += 1
+
+        if not found:
+            c += 1
+            continue
+
+        if pr != p:
+            a_mat[p], a_mat[pr] = a_mat[pr], a_mat[p]
+
+        pivot = a_mat[p][c]
+        is_free[c] = False
+        pivot_row[c] = p
+
+        for i in range(work_rows):
+            if i != p:
+                val_i = a_mat[i][c]
+                if val_i != 0:
+                    g = math_gcd(pivot, val_i)
+                    factor_p = val_i // g
+                    factor_i = pivot // g
+
+                    for j in range(work_cols):
+                        a_mat[i][j] = factor_i * a_mat[i][j] - factor_p * a_mat[p][j]
+
+                    # Simplify row i
+                    r_gcd = 0
+                    for j in range(work_cols):
+                        r_gcd = math_gcd(r_gcd, a_mat[i][j])
+                    if r_gcd > 1:
+                        for j in range(work_cols):
+                            a_mat[i][j] //= r_gcd
+
+        # Simplify pivot row
+        p_gcd = 0
+        for j in range(work_cols):
+            p_gcd = math_gcd(p_gcd, a_mat[p][j])
+        if p_gcd > 1:
+            for j in range(work_cols):
+                a_mat[p][j] //= p_gcd
+
+        p += 1
+        c += 1
+
+    # Back-Substitution & Basis Generation
+    basis_vectors = []
+    for f in range(work_cols):
+        if is_free[f]:
+            num_vec = [0] * work_cols
+            den_vec = [1] * work_cols
+
+            for j in range(work_cols):
+                if is_free[j]:
+                    if j == f:
+                        num_vec[j] = 1
+                        den_vec[j] = 1
+                    else:
+                        num_vec[j] = 0
+                        den_vec[j] = 1
+                else:
+                    pr = pivot_row[j]
+                    a_pr_j = a_mat[pr][j]
+                    a_pr_f = a_mat[pr][f]
+
+                    num = -a_pr_f
+                    den = a_pr_j
+                    if den < 0:
+                        num = -num
+                        den = -den
+                    g = math_gcd(num, den)
+                    num_vec[j] = num // g
+                    den_vec[j] = den // g
+
+            # Find LCM of denominators
+            lcm = 1
+            for j in range(work_cols):
+                lcm = math_lcm(lcm, den_vec[j])
+
+            # Multiply by LCM to get integer vector
+            int_vec = [0] * work_cols
+            for j in range(work_cols):
+                int_vec[j] = num_vec[j] * (lcm // den_vec[j])
+
+            # Simplify vector by dividing by overall GCD
+            vec_gcd = 0
+            for j in range(work_cols):
+                vec_gcd = math_gcd(vec_gcd, int_vec[j])
+            if vec_gcd > 1:
+                for j in range(work_cols):
+                    int_vec[j] //= vec_gcd
+
+            # Normalize direction
+            all_non_positive = True
+            for j in range(work_cols):
+                if int_vec[j] > 0:
+                    all_non_positive = False
+                    break
+            if all_non_positive:
+                for j in range(work_cols):
+                    int_vec[j] = -int_vec[j]
+
+            basis_vectors.append(int_vec)
+
+    return basis_vectors

clm/layer0/mcard.py

@@ -0,0 +1,96 @@
+"""Layer 0: Stateless Kenotic MCard Data Entity.
+
+Canonical Path: kernel/scripts/clm/layer0/mcard.py
+Parity: Rust `src/layer0/mcard.rs`, TypeScript `src/layer0/mcard.ts`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from clm.layer0.codec import canonical_json
+from clm.layer0.hash import compute_blake3, verify_hash
+
+
+@dataclass(frozen=True)
+class MCardPayload:
+    kind: str  # 'Scalar', 'Text', 'Binary', 'Structured', 'Uri'
+    value: Any
+
+
+@dataclass
+class MCard:
+    uri: str
+    hash: str
+    payload: MCardPayload
+    author: str
+    sequence: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_canonical_bytes(self) -> bytes:
+        return to_canonical_bytes(self)
+
+    def verify_integrity(self) -> bool:
+        return verify_mcard_integrity(self)
+
+
+def payload_to_bytes(payload: MCardPayload) -> bytes:
+    """Serializes payload to deterministic bytes for cryptographic hashing."""
+    kind = payload.kind
+    if kind == "Text":
+        return payload.value.encode("utf-8")
+    elif kind == "Binary":
+        data = payload.value.get("data") if isinstance(payload.value, dict) else payload.value
+        return data if isinstance(data, bytes) else bytes(data)
+    elif kind in ("Scalar", "Structured"):
+        return canonical_json(payload.value).encode("utf-8")
+    elif kind == "Uri":
+        return payload.value.encode("utf-8")
+    else:
+        return str(payload.value).encode("utf-8")
+
+
+def create_mcard(
+    uri: str,
+    payload: MCardPayload,
+    author: str,
+    sequence: int = 0,
+    metadata: dict[str, Any] | None = None,
+) -> MCard:
+    """Constructs a new immutable MCard, computing its BLAKE3 hash from payload."""
+    payload_bytes = payload_to_bytes(payload)
+    h = compute_blake3(payload_bytes)
+    return MCard(
+        uri=uri,
+        hash=h,
+        payload=payload,
+        author=author,
+        sequence=sequence,
+        metadata=metadata if metadata is not None else {},
+    )
+
+
+def verify_mcard_integrity(card: MCard) -> bool:
+    """Verifies that the MCard hash matches its underlying payload."""
+    payload_bytes = payload_to_bytes(card.payload)
+    return verify_hash(payload_bytes, card.hash)
+
+
+def to_canonical_bytes(card: MCard) -> bytes:
+    """Serializes the entire MCard into canonical JSON UTF-8 bytes."""
+    card_dict = {
+        "uri": card.uri,
+        "hash": card.hash,
+        "payload": {
+            "kind": card.payload.kind,
+            "value": card.payload.value if card.payload.kind != "Binary" else {
+                "mime_type": card.payload.value.get("mime_type", "application/octet-stream"),
+                "data": list(card.payload.value.get("data", b"")),
+            },
+        },
+        "metadata": card.metadata,
+        "author": card.author,
+        "sequence": card.sequence,
+    }
+    return canonical_json(card_dict).encode("utf-8")

clm/layer0/model/action.py

@@ -0,0 +1,223 @@
+"""Declarative Action Manifest Domain Models (Sprint 392 / DEL-392-01).
+
+Implements Pydantic V2 domain models for canonical CLM Action specifications (clm.action.v1).
+An Action represents a temporal morphism (the C face of the Operational Triad)
+operating on spatial carrier MCards (A face) and bracketed by Hoare invariants (B face).
+
+Zero dependencies on Layer 1 through Layer 5.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+ActionFormat = Literal[
+    "csv",
+    "json",
+    "yaml",
+    "markdown",
+    "text",
+    "binary",
+    "media",
+    "image",
+    "audio",
+    "model3d",
+]
+
+BaldwinOperator = Literal[
+    "split",
+    "substitute",
+    "augment",
+    "exclude",
+    "invert",
+    "port",
+    "custom",
+]
+
+ActionRuntime = Literal[
+    "builtin",
+    "python",
+    "cel",
+    "shell",
+    "wasm",
+]
+
+
+class ActionMetadata(BaseModel):
+    """Metadata block identifying the Action and its algebraic role in CLM."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    type: Literal["action", "pcard_action"] = "action"
+    name: str = Field(..., pattern=r"^[a-z0-9_\-]+$")
+    description: str | None = None
+    face: Literal["C", "concrete_impl"] = "C"
+    operator: BaldwinOperator
+    author: str = "did:clm:system"
+
+
+class ActionInput(BaseModel):
+    """Specification of an input MCard bound to the Action."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    uri: str | None = None
+    format: ActionFormat | None = None
+    required: bool = True
+    description: str | None = None
+
+
+class ActionPrecondition(BaseModel):
+    """Precondition invariant rule (V_pre Gate) verified before Action execution."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    invariant: str
+    rule: str
+    schema_ref: str | None = None
+    description: str | None = None
+
+
+class ActionOperation(BaseModel):
+    """Algebraic operation definition specifying the Baldwin operator and parameters."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    operator: BaldwinOperator
+    strategy: str | None = None
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    runtime: ActionRuntime = "builtin"
+
+
+class ActionPostcondition(BaseModel):
+    """Postcondition invariant rule (V_post Witness) verified before committing output."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    invariant: str
+    rule: str
+    schema_ref: str | None = None
+    description: str | None = None
+
+
+class ActionOutput(BaseModel):
+    """Specification of an output MCard emitted by the Action."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    handle: str | None = None
+    format: ActionFormat | None = None
+    description: str | None = None
+
+
+class ActionManifest(BaseModel):
+    """Canonical Declarative Action Manifest (clm.action.v1).
+
+    Encapsulates inputs, Hoare preconditions (V_pre), Baldwin algebraic operation,
+    Hoare postconditions (V_post), and outputs.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: Literal["1.0", "1.0.0"] = "1.0"
+    clm: ActionMetadata
+    inputs: list[ActionInput] = Field(..., min_length=1)
+    preconditions: list[ActionPrecondition] = Field(default_factory=list)
+    operation: ActionOperation
+    postconditions: list[ActionPostcondition] = Field(default_factory=list)
+    outputs: list[ActionOutput] = Field(..., min_length=1)
+
+    @field_validator("operation")
+    @classmethod
+    def validate_operator_congruence(cls, v: ActionOperation, info: Any) -> ActionOperation:
+        """Validate that clm.operator and operation.operator are congruent."""
+        clm_meta = info.data.get("clm")
+        if clm_meta and isinstance(clm_meta, ActionMetadata):
+            if clm_meta.operator != v.operator:
+                raise ValueError(
+                    f"Operator mismatch: clm.operator='{clm_meta.operator}' != operation.operator='{v.operator}'"
+                )
+        return v
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ActionManifest:
+        """Parse an ActionManifest from a Python dictionary."""
+        return cls(**data)
+
+    @classmethod
+    def from_yaml(cls, yaml_content: str | Path) -> ActionManifest:
+        """Parse an ActionManifest from a YAML string or file path."""
+        if isinstance(yaml_content, Path):
+            return cls.from_yaml_file(yaml_content)
+        if isinstance(yaml_content, str):
+            # If it's a short string without newlines that points to an existing file
+            if "\n" not in yaml_content and len(yaml_content) < 260:
+                try:
+                    p = Path(yaml_content)
+                    if p.is_file():
+                        return cls.from_yaml_file(p)
+                except OSError:
+                    pass
+            data = yaml.safe_load(yaml_content)
+            if not isinstance(data, dict):
+                raise ValueError("YAML content does not represent a valid dictionary")
+            return cls(**data)
+        raise TypeError(f"Expected str or Path, got {type(yaml_content)}")
+
+    @classmethod
+    def from_yaml_file(cls, path: str | Path) -> ActionManifest:
+        """Parse an ActionManifest from a YAML file path."""
+        p = Path(path)
+        raw = p.read_text(encoding="utf-8")
+        data = yaml.safe_load(raw)
+        if not isinstance(data, dict):
+            raise ValueError(f"File {path} does not contain a valid YAML dictionary")
+        return cls(**data)
+
+    @classmethod
+    def from_json(cls, json_content: str | Path) -> ActionManifest:
+        """Parse an ActionManifest from a JSON string or file path."""
+        if isinstance(json_content, Path):
+            return cls.from_json_file(json_content)
+        if isinstance(json_content, str):
+            if "\n" not in json_content and not json_content.strip().startswith("{") and len(json_content) < 260:
+                try:
+                    p = Path(json_content)
+                    if p.is_file():
+                        return cls.from_json_file(p)
+                except OSError:
+                    pass
+            data = json.loads(json_content)
+            if not isinstance(data, dict):
+                raise ValueError("JSON content does not represent a valid dictionary")
+            return cls(**data)
+        raise TypeError(f"Expected str or Path, got {type(json_content)}")
+
+    @classmethod
+    def from_json_file(cls, path: str | Path) -> ActionManifest:
+        """Parse an ActionManifest from a JSON file path."""
+        p = Path(path)
+        raw = p.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError(f"File {path} does not contain a valid JSON dictionary")
+        return cls(**data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert manifest to Python dictionary."""
+        return self.model_dump(exclude_none=True)
+
+    def to_yaml(self) -> str:
+        """Convert manifest to YAML string."""
+        return yaml.dump(self.to_dict(), sort_keys=False)
+
+    def to_json(self, indent: int = 2) -> str:
+        """Convert manifest to formatted JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)