clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/README.md

@@ -0,0 +1,50 @@
+# CLM Layer 0: Algebraic Baldwin Modularity Operators
+
+## Mathematical Foundations & Lattice Generator Dynamics
+
+The CLM interpretation pipeline formalizes design evolution and architectural transformations through Carliss Baldwin and Kim Clark's six modularity operators ("Design Rules: The Power of Modularity"). In CLM, each operator acts as a native lattice generator over Coloured Petri Nets (CPNs) and Arrow Categories $\mathbf{Arr}(\mathbf{C})$.
+
+### 1. Split Operator ($\sigma$)
+- **Formal Definition**: Decomposes a monolithic arrow $A: X \to Y$ into parallel, orthogonal sub-arrows $B: X \to Y_1$ and $C: X \to Y_2$, recombining their outputs via product pairing:
+  $$\sigma(A, B, C) = A \gg (B \times C)$$
+- **Algebraic Laws**:
+  - **Functorial Factorization**: $\sigma(A, B, C)$ preserves typing $X \to Y_1 \times Y_2$.
+  - **Token Conservation**: Incidence matrix column sum invariance: $\sum_{i} D_{i, j} = 0 \quad \forall j \in \mathcal{T}$.
+  - **Product Commutativity**: $\sigma(A, B, C) \cong \tau \circ \sigma(A, C, B)$ where $\tau(y_1, y_2) = (y_2, y_1)$ is swap.
+
+### 2. Augment Operator ($\alpha$)
+- **Formal Definition**: Additively composes an extension arrow $E: Y \to Z$ onto an existing CPN net $\mathcal{N}_A$:
+  $$\alpha(\mathcal{N}_A, E) = \mathcal{N}_A \gg \mathcal{N}_E$$
+- **Algebraic Laws**:
+  - **Associativity**: $\alpha(\alpha(\mathcal{N}_A, E_1), E_2) \equiv \alpha(\mathcal{N}_A, E_1 \gg E_2)$.
+  - **Identity**: For identity arrow $\mathrm{id}$, $\alpha(\mathcal{N}_A, \mathrm{id}) \equiv \mathcal{N}_A$.
+  - **Token Conservation**: Inflow into $E$ equals outflow from $A$, conserving overall token balance.
+
+### 3. Exclude Operator ($\epsilon$)
+- **Formal Definition**: Prunes an internal arrow step $S_k$ from a composite pipeline $\mathcal{N} = S_1 \gg \dots \gg S_k \gg \dots \gg S_n$, producing a bypass net and an immutable audit descriptor $\mathcal{A}$:
+  $$\epsilon(\mathcal{N}, S_k) = (\mathcal{N} \setminus \{S_k\}, \mathcal{A}_{\epsilon}(S_k))$$
+- **Algebraic Laws**:
+  - **Audit Immutability**: Every exclusion generates a cryptographic record containing timestamp, hash, and operator provenance.
+  - **Idempotence with Audit**: $\epsilon(\epsilon(\mathcal{N}, S_k), S_k) = \epsilon(\mathcal{N}, S_k)$.
+
+### 4. Substitute Operator ($\rho$)
+- **Formal Definition**: Hot-swaps an internal constituent arrow $S_k$ with an interface-compatible replacement arrow $S'_k$:
+  $$\rho(\mathcal{N}, S_k, S'_k) = \mathcal{N}[S_k \mapsto S'_k]$$
+- **Algebraic Laws**:
+  - **Interface Invariance**: $\mathrm{dom}(S_k) = \mathrm{dom}(S'_k) \land \mathrm{cod}(S_k) = \mathrm{cod}(S'_k)$.
+  - **Homomorphic Replacement**: If $S'_k \sim S_k$ semantically, the external behavior of $\rho(\mathcal{N}, S_k, S'_k)$ preserves all boundary contracts.
+  - **Identity Replacement**: $\rho(\mathcal{N}, S_k, S_k) \equiv \mathcal{N}$.
+
+### 5. Invert Operator ($\iota$)
+- **Formal Definition**: Reverses coordinate tuples or dualizes state space transitions:
+  $$\iota(A: X \to Y_1 \times Y_2) = A \gg \mathrm{swap}$$
+- **Algebraic Laws**:
+  - **Involution**: $\iota(\iota(A)) \equiv A$.
+  - **Duality**: Inverting an incidence matrix transition flips prep/seal directional dynamics while maintaining state reachability.
+
+### 6. Port Operator ($\pi$)
+- **Formal Definition**: Translates an arrow module across different runtime execution environments (e.g., Python $\to$ TypeScript $\to$ WASM) using a standardized boundary adapter:
+  $$\pi(\mathcal{N}, R_{\mathrm{target}}) = \mathcal{A}_{\mathrm{in}} \gg \mathcal{N}_{R_{\mathrm{target}}} \gg \mathcal{A}_{\mathrm{out}}$$
+- **Algebraic Laws**:
+  - **Target Parity**: $\forall x \in \mathrm{dom}(\mathcal{N}): \pi(\mathcal{N}, R_2)(\pi(\mathcal{N}, R_1)(x)) = \mathcal{N}(x)$.
+  - **Cross-Runtime Behavioral Equivalence**: Byte-level bit-identical assertion parity across polyglot targets under canonical inputs.

clm/layer0/__init__.py

@@ -0,0 +1,223 @@
+"""CLM Layer 0 Kenotic Microkernel package (Sprint 387, DEL-387-07).
+
+Provides pure algebraic primitives, AST parsers, codecs, hashing, and static schemas.
+Heavy, I/O-bound, and storage subsystems are loaded lazily via __getattr__ to maintain
+Kenotic Purity (INV-01, INV-09, INV-10) upon `import clm.layer0`.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from clm.layer0.assembler import (
+    AssembledCLM,
+    CLMAssembler,
+    CLMComponent,
+    ValidationResult,
+)
+from clm.layer0.codec import (
+    canonical_json,
+    canonical_yaml,
+    from_base58,
+    from_hex,
+    to_base58,
+    to_hex,
+)
+from clm.layer0.context import CLMContext
+from clm.layer0.exceptions import (
+    AlgebraError,
+    CLMError,
+    DatabaseError,
+    ExecutionError,
+    GatewayError,
+    KenoticPurityViolationError,
+    TypeValidationError,
+)
+from clm.layer0.gates import (
+    GatePredicate,
+    evaluate_gate,
+    evaluate_gate_set,
+)
+from clm.layer0.hash import (
+    BLAKE3_PREFIX,
+    SHA256_PREFIX,
+    compute_blake3,
+    compute_sha256,
+    prefixed_hash,
+    verify_hash,
+)
+from clm.layer0.loader import (
+    CLMChapterLoader,
+    YAMLTemplateLoader,
+)
+from clm.layer0.math_utils import math_gcd, math_lcm, solve_nullspace
+from clm.layer0.mcard import (
+    MCard,
+    MCardPayload,
+    create_mcard,
+    payload_to_bytes,
+    to_canonical_bytes,
+    verify_mcard_integrity,
+)
+from clm.layer0.narrative import (
+    Chapter,
+    CLMConfiguration,
+    NarrativeMonad,
+)
+from clm.layer0.parser import (
+    ClmRoot,
+    ParsedClmAst,
+    UnifiedClmParser,
+)
+from clm.layer0.type_registry import TypeRegistry, load_clm_features
+from clm.layer0.types import (
+    ArchitecturalPlane,
+    CHLDimension,
+    CHLTemporal,
+    ExecutionResult,
+    LivenessMetric,
+    PolynomialTerm,
+    PostconditionViolation,
+    PreconditionViolation,
+    PrimeHash,
+    SafetyViolation,
+    TemporalPhase,
+    VerificationStatus,
+)
+
+# Lazy export routing table to preserve import-time purity
+_LAZY_EXPORTS: dict[str, str] = {
+    # algebra
+    "assess_equivalence_py": "clm.layer0.algebra",
+    "directory_fs_scan_py": "clm.layer0.algebra",
+    "directory_to_db_py": "clm.layer0.algebra",
+    "load_normalized_manifest": "clm.layer0.algebra",
+    # db (storage facade)
+    "CLMDB": "clm.layer0.db",
+    "CLMRepository": "clm.layer0.db",
+    "init_tridb": "clm.layer0.db",
+    "memorize_mcard": "clm.layer0.db",
+    "register_handle": "clm.layer0.db",
+    "resolve_handle_content": "clm.layer0.db",
+    "resolve_handle_hash": "clm.layer0.db",
+    # utils
+    "clm_hash_file": "clm.layer0.utils",
+    "clm_hash_string": "clm.layer0.utils",
+    "detect_host_os": "clm.layer0.utils",
+    "extract_python_script_from_yaml": "clm.layer0.utils",
+    "get_bash_command": "clm.layer0.utils",
+    "is_docker_live": "clm.layer0.utils",
+    "normalize_line_endings_bytes": "clm.layer0.utils",
+    "normalize_line_endings_str": "clm.layer0.utils",
+    "resolve_clm_path": "clm.layer0.utils",
+    "verify_file_hash": "clm.layer0.utils",
+}
+
+
+def __getattr__(name: str) -> Any:
+    target_mod = _LAZY_EXPORTS.get(name)
+    if target_mod:
+        mod = sys.modules.get(target_mod)
+        if mod is None:
+            __import__(target_mod)
+            mod = sys.modules.get(target_mod)
+        if mod is not None and hasattr(mod, name):
+            return getattr(mod, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # exceptions
+    "CLMError",
+    "TypeValidationError",
+    "DatabaseError",
+    "ExecutionError",
+    "AlgebraError",
+    "GatewayError",
+    "KenoticPurityViolationError",
+    # utils (lazy)
+    "resolve_clm_path",
+    "clm_hash_file",
+    "clm_hash_string",
+    "detect_host_os",
+    "is_docker_live",
+    "get_bash_command",
+    "normalize_line_endings_bytes",
+    "normalize_line_endings_str",
+    "verify_file_hash",
+    "extract_python_script_from_yaml",
+    # db (lazy)
+    "CLMDB",
+    "CLMRepository",
+    "init_tridb",
+    "memorize_mcard",
+    "resolve_handle_content",
+    "resolve_handle_hash",
+    "register_handle",
+    # math & context
+    "math_gcd",
+    "math_lcm",
+    "solve_nullspace",
+    "TypeRegistry",
+    "load_clm_features",
+    "CLMContext",
+    # algebra (lazy)
+    "load_normalized_manifest",
+    "assess_equivalence_py",
+    "directory_fs_scan_py",
+    "directory_to_db_py",
+    # hash
+    "compute_blake3",
+    "compute_sha256",
+    "prefixed_hash",
+    "verify_hash",
+    "BLAKE3_PREFIX",
+    "SHA256_PREFIX",
+    # codec
+    "to_hex",
+    "from_hex",
+    "to_base58",
+    "from_base58",
+    "canonical_json",
+    "canonical_yaml",
+    # mcard
+    "MCard",
+    "MCardPayload",
+    "payload_to_bytes",
+    "create_mcard",
+    "verify_mcard_integrity",
+    "to_canonical_bytes",
+    # gates
+    "GatePredicate",
+    "evaluate_gate",
+    "evaluate_gate_set",
+    # parser
+    "UnifiedClmParser",
+    "ParsedClmAst",
+    "ClmRoot",
+    # narrative
+    "Chapter",
+    "NarrativeMonad",
+    "CLMConfiguration",
+    # loader
+    "CLMChapterLoader",
+    "YAMLTemplateLoader",
+    # assembler
+    "CLMAssembler",
+    "AssembledCLM",
+    "CLMComponent",
+    "ValidationResult",
+    # types
+    "PrimeHash",
+    "PolynomialTerm",
+    "SafetyViolation",
+    "LivenessMetric",
+    "VerificationStatus",
+    "ExecutionResult",
+    "CHLDimension",
+    "TemporalPhase",
+    "CHLTemporal",
+    "ArchitecturalPlane",
+    "PreconditionViolation",
+    "PostconditionViolation",
+]

clm/layer0/algebra.py

@@ -0,0 +1,60 @@
+"""Layer 0 — Baldwin Algebra and Equivalence Assessment (Sprint 133.1 shim).
+
+Sprint 133.1 decomposed this 896-line god-module into four sibling modules:
+    - ``algebra_manifest_io.py`` — manifest loading, hashing, PCard execution, value canonicalization
+    - ``algebra_equivalence.py`` — Homotopy Equivalence Gate (assess_equivalence_py)
+    - ``algebra_ingest.py`` — directory scanning and DB ingestion (Function-Number Duality bridge)
+    - ``algebra_baldwin.py`` — Baldwin Exclude operator
+
+This file remains as a thin re-export shim for backward compatibility.
+Full shim removal deferred to Sprint 134.
+"""
+from clm.cross_cutting.clm_logger import get_logger
+
+from .algebra_baldwin import exclude_clm_py
+from .algebra_equivalence import _ANSI_RE, _find_divergence, _normalize_output, assess_equivalence_py
+from .algebra_ingest import _storage_fallback_warn_or_fail, directory_fs_scan_py, directory_to_db_py
+from .algebra_manifest_io import (
+    canonical_value_py,
+    check_content_equivalent_py,
+    clean_data_py,
+    compare_numerical_py,
+    compute_stripped_file_hash_py,
+    execute_pcard_py,
+    load_normalized_manifest,
+    load_normalized_manifest_str,
+    parse_json_or_yaml_py,
+)
+from .assembler import (
+    AssembledCLM,
+    CLMAssembler,
+    CLMComponent,
+    ValidationResult,
+)
+
+_logger = get_logger("clm.algebra")
+
+__all__ = [
+    "_ANSI_RE",
+    "_find_divergence",
+    "_normalize_output",
+    "_storage_fallback_warn_or_fail",
+    "assess_equivalence_py",
+    "canonical_value_py",
+    "check_content_equivalent_py",
+    "clean_data_py",
+    "compare_numerical_py",
+    "compute_stripped_file_hash_py",
+    "directory_fs_scan_py",
+    "directory_to_db_py",
+    "exclude_clm_py",
+    "execute_pcard_py",
+    "load_normalized_manifest",
+    "load_normalized_manifest_str",
+    "parse_json_or_yaml_py",
+    "AssembledCLM",
+    "CLMAssembler",
+    "CLMComponent",
+    "ValidationResult",
+]
+

clm/layer0/algebra_baldwin.py

@@ -0,0 +1,133 @@
+"""Baldwin Exclude Operator (Sprint 133.1).
+
+Extracted from ``algebra.py``. Python-native implementation of the Baldwin
+Modularity Operator: Exclude. Prunes constraints/paths from a CLM manifest
+and archives the excluded content as an audit trail.
+"""
+import contextlib
+import os
+from typing import Any
+
+import yaml
+
+from clm.layer0.utils import clm_hash_string
+
+from .utils import resolve_clm_path
+
+
+def exclude_clm_py(clm_root: str, clm_file: str, exclude_path: str) -> tuple[int, str, str]:
+    """
+    Python-native implementation of Baldwin Modularity Operator: Exclude.
+    Prunes constraints/paths from a CLM manifest and archives the excluded content as an audit trail.
+
+    Args:
+        clm_root (str): The workspace root directory.
+        clm_file (str): The path to the CLM file to modify.
+        exclude_path (str): The dot-separated yq-style path to prune (e.g. '.clm.abstract.invariants').
+
+    Returns:
+        Tuple[int, str, str]: (exit_code, stdout, stderr)
+    """
+    clm_file = resolve_clm_path(clm_root, clm_file)
+    if not os.path.exists(clm_file):
+        return 1, "", f"Target file not found: {clm_file}"
+
+    # Load manifest
+    with open(clm_file, encoding='utf-8') as f:
+        try:
+            data = yaml.safe_load(f)
+        except Exception as e:
+            return 1, "", f"Failed to parse YAML manifest: {e}"
+
+    # Normalize exclude path format (strip leading dot if needed)
+    path_str = exclude_path.strip()
+    if path_str.startswith('.'):
+        path_str = path_str[1:]
+    parts = [p for p in path_str.split('.') if p]
+
+    # Helper to retrieve value by path
+    def get_by_path(d: Any, path_parts: list[str]) -> Any:
+        curr = d
+        for p in path_parts:
+            if isinstance(curr, dict) and p in curr:
+                curr = curr[p]
+            else:
+                return None
+        return curr
+
+    existing = get_by_path(data, parts)
+    if existing is None:
+        msg = f"[EXCLUDE] ⚠️ Path not found: {exclude_path} — nothing to exclude"
+        return 0, msg, ""
+
+    # Archive the excluded content as an Execution MCard (audit trail)
+    excluded_content = yaml.dump(existing, default_flow_style=False)
+    excl_hash = clm_hash_string(excluded_content)
+
+    from clm.layer0.verifier_core import emit_exec_mcard_py
+    indented_content = "\n".join("  " + line for line in excluded_content.splitlines())
+    extra_yaml = f"source_clm: \"{clm_file}\"\nexcluded_path: \"{exclude_path}\"\ncontent:\n{indented_content}"
+
+    try:
+        audit_file = emit_exec_mcard_py(clm_root, "exclude", excl_hash, extra_yaml)
+    except Exception as e:
+        return 1, "", f"Failed to emit audit execution MCard: {e}"
+
+    # Calculate hash of original file to derive pruned file name
+    with open(clm_file, 'rb') as f:
+        orig_bytes = f.read()
+    pruned_hash = clm_hash_string(orig_bytes)
+
+    output_dir = os.path.join(clm_root, "data/content_memory")
+    os.makedirs(output_dir, exist_ok=True)
+    pruned_file = os.path.join(output_dir, f"excluded_{pruned_hash[:12]}.yaml")
+
+    # Helper to delete key by path
+    def delete_by_path(d: Any, path_parts: list[str]) -> bool:
+        if not path_parts:
+            return False
+        curr = d
+        for p in path_parts[:-1]:
+            if isinstance(curr, dict) and p in curr:
+                curr = curr[p]
+            else:
+                return False
+        last_part = path_parts[-1]
+        if isinstance(curr, dict) and last_part in curr:
+            del curr[last_part]
+            return True
+        return False
+
+    # Perform the deletion
+    delete_by_path(data, parts)
+
+    # Write pruned content to file
+    with open(pruned_file, 'w', encoding='utf-8') as f:
+        yaml.dump(data, f, default_flow_style=False)
+
+    # Validate that pruned CLM still passes grammar in strict type mode
+    from clm.layer0.verifier_core import verify_precondition
+    orig_strict = os.environ.get("CLM_STRICT_TYPES")
+    os.environ["CLM_STRICT_TYPES"] = "true"
+
+    try:
+        valid = verify_precondition(clm_root, pruned_file)
+    except Exception as e:
+        valid = False
+        err_msg = str(e)
+    else:
+        err_msg = "Grammar validation failed"
+    finally:
+        if orig_strict is not None:
+            os.environ["CLM_STRICT_TYPES"] = orig_strict
+        else:
+            with contextlib.suppress(KeyError):
+                del os.environ["CLM_STRICT_TYPES"]
+
+    if not valid:
+        if os.path.exists(pruned_file):
+            os.remove(pruned_file)
+        return 1, "", f"Exclusion REJECTED — would produce invalid CLM: {err_msg}"
+
+    stdout_msg = f"Archived excluded content: {audit_file}\nExcluded CLM: {pruned_file}"
+    return 0, stdout_msg, ""

clm/layer0/algebra_baldwin_generators.py

@@ -0,0 +1,36 @@
+"""Deprecated backward-compatibility shim for Baldwin CPN generators (INV-383-02).
+
+Canonical path: clm.layer1.algebra_baldwin_generators
+All new code should import from clm.layer1.algebra_baldwin_generators directly.
+"""
+
+from __future__ import annotations
+
+import sys
+import warnings
+from typing import Any
+
+warnings.warn(
+    "clm.layer0.algebra_baldwin_generators is deprecated. "
+    "Import from clm.layer1.algebra_baldwin_generators instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [
+    "BaldwinAlgebraicError",
+    "BaldwinAuditRecord",
+    "BaldwinCpnGenerators",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        target = "clm.layer1.algebra_baldwin_generators"
+        mod = sys.modules.get(target)
+        if mod is None:
+            __import__(target)
+            mod = sys.modules.get(target)
+        if mod is not None:
+            return getattr(mod, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")