clm-kernel 0.0.0__py3-none-any.whl

clm/layer2/storage/sqlite_wal.py

@@ -0,0 +1,74 @@
+"""SQLite WAL Connection Pooling & Tri-Database Consolidation (DEL-389-02).
+
+Provides high-concurrency WAL-mode connection pools for the three canonical
+tri-database pillars:
+1. agent_identities.db (DIDs, keys, and ZTA credentials)
+2. content_memory.db (Immutable CAS MCards and content payloads)
+3. execution_log.db (Append-only audit traces, markings, and learning events)
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from clm.layer2.storage.db_pool import ClmDbPool
+
+# Class alias
+SqliteWalPool = ClmDbPool
+
+
+class TriDatabasePoolRegistry:
+    """Singleton registry of SQLite WAL connection pools for the Triad."""
+
+    _instance: TriDatabasePoolRegistry | None = None
+
+    def __init__(self, clm_root: str | None = None) -> None:
+        self.clm_root = clm_root or os.environ.get("CLM_ROOT", ".")
+        self._pools: dict[str, ClmDbPool] = {}
+
+    @classmethod
+    def get_instance(cls, clm_root: str | None = None) -> TriDatabasePoolRegistry:
+        if cls._instance is None:
+            cls._instance = cls(clm_root)
+        return cls._instance
+
+    def get_pool(self, pillar: str) -> ClmDbPool:
+        """Get or initialize connection pool for a specific pillar."""
+        if pillar in self._pools:
+            return self._pools[pillar]
+
+        root = Path(self.clm_root).resolve()
+        data_dir = root / "data"
+
+        pillar_paths = {
+            "agent_identities": data_dir / "agent_identities.db",
+            "content_memory": data_dir / "content_memory.db",
+            "execution_log": data_dir / "execution_log.db",
+        }
+
+        db_path = str(pillar_paths.get(pillar, data_dir / f"{pillar}.db"))
+        pool = ClmDbPool(db_path)
+        self._pools[pillar] = pool
+        return pool
+
+    def close_all(self) -> None:
+        for pool in self._pools.values():
+            pool.close()
+        self._pools.clear()
+
+
+def get_tridb_pools(clm_root: str | None = None) -> dict[str, ClmDbPool]:
+    """Return initialized pools for the three canonical pillars."""
+    reg = TriDatabasePoolRegistry.get_instance(clm_root)
+    return {
+        "agent_identities": reg.get_pool("agent_identities"),
+        "content_memory": reg.get_pool("content_memory"),
+        "execution_log": reg.get_pool("execution_log"),
+    }
+
+
+__all__ = [
+    "SqliteWalPool",
+    "TriDatabasePoolRegistry",
+    "get_tridb_pools",
+]

clm/layer2/tridb.py

@@ -0,0 +1,245 @@
+"""Layer 2: Content-Addressed Storage & Tri-Database Engine.
+
+Canonical Path: kernel/scripts/clm/layer2/tridb.py
+Parity: Rust `src/layer2/storage.rs`, TypeScript `src/layer2/triDb.ts`
+
+Per 00_Architecture_Overview.md §Key Arch Principles #4:
+The Tri-Database (agent_identities.db, content_memory.db, execution_log.db)
+is the soul-bound memory of the agency — a central, non-transferable Single
+Source of Truth. The three databases are cryptographically inseparable:
+identity proofs, semantic knowledge, and episodic traces cannot be
+meaningfully moved independently.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from clm.layer2.card_collection import CardCollection
+from clm.layer2.storage import (
+    CLMDB,
+    CLMRepository,
+    init_tridb,
+    memorize_mcard,
+    register_handle,
+    resolve_handle_content,
+    resolve_handle_hash,
+)
+
+logger = logging.getLogger(__name__)
+
+# Canonical handle URIs for Kenotic Root resolution
+HANDLE_AGENT_IDENTITIES = "pkc://db/agent_identities"
+HANDLE_CONTENT_MEMORY = "pkc://db/content_memory"
+HANDLE_EXECUTION_LOG = "pkc://db/execution_log"
+
+# Default database filenames (per Four-Database Topology)
+DB_AGENT_IDENTITIES = "agent_identities.db"
+DB_CONTENT_MEMORY = "content_memory.db"
+DB_EXECUTION_LOG = "execution_log.db"
+
+
+@dataclass
+class TriDatabase:
+    """Soul-bound Tri-Database: the non-transferable SSOT for the agency.
+
+    Architectural Invariant (00_Architecture_Overview §1.1):
+    The three databases are cryptographically inseparable. Identity proofs,
+    semantic knowledge, and episodic traces cannot be meaningfully moved
+    independently. This soul-bound property is itself a Polynomial Type
+    manifestation: the identical frozen 3-table schema is interpreted
+    polymorphically across three distinct cognitive domains (Who, What, How/When).
+
+    Three-Plane Mapping:
+      - agent_identities → Application Plane (Zero-Trust AuthZ/AuthN)
+      - content_memory   → Data Plane (bits-to-hash guarantees)
+      - execution_log    → Control Plane (PTR lifecycle traces)
+
+    Args:
+        agent_identities: CardCollection for agent identity proofs (Who).
+        content_memory: CardCollection for semantic domain knowledge (What).
+        execution_log: CardCollection for episodic execution traces (How/When).
+        tri_db_dir: Root directory containing the three database files.
+    """
+
+    agent_identities: Any  # CardCollection (Who am I? Application Plane)
+    content_memory: Any  # CardCollection (What do I know? Data Plane)
+    execution_log: Any  # CardCollection (How did I do it? Control Plane)
+    tri_db_dir: Path | None = None  # Configurable root directory
+
+    @classmethod
+    def from_kenotic_root(cls, root: Any) -> TriDatabase:
+        """Resolve Tri-Database paths from the Kenotic Root (meta_functionality.db).
+
+        Implements the Handle↔Hash duality (§Key Arch Principles #5):
+        Each pkc://db/* handle in the Kenotic Root resolves to an MCard
+        whose content encodes the database path. This is a directed morphism
+        from semantic name to content hash to physical location.
+
+        Args:
+            root: The Kenotic Root CardCollection (meta_functionality.db)
+                  containing handle→hash mappings for the three databases.
+
+        Returns:
+            TriDatabase with collections resolved from handle metadata.
+
+        Raises:
+            ValueError: If required handles are not found in the Kenotic Root.
+        """
+        import yaml
+
+
+        paths = {}
+        for handle_uri, db_key in [
+            (HANDLE_AGENT_IDENTITIES, "agent_identities"),
+            (HANDLE_CONTENT_MEMORY, "content_memory"),
+            (HANDLE_EXECUTION_LOG, "execution_log"),
+        ]:
+            resolved_hash = root.resolve_handle(handle_uri)
+            if not resolved_hash:
+                raise ValueError(
+                    f"Kenotic Root missing handle: {handle_uri}. "
+                    f"Run bootstrap to provision the Four-Database topology."
+                )
+            card = root.get(resolved_hash)
+            if not card:
+                raise ValueError(
+                    f"Kenotic Root handle {handle_uri} points to missing card: {resolved_hash}"
+                )
+            # Parse the card content to extract the 'path' field
+            raw_content = card.get_content(as_text=True) if hasattr(card, "get_content") else getattr(card, "content", "")
+            content = yaml.safe_load(raw_content)
+            db_path = content.get("path")
+            if not db_path:
+                raise ValueError(
+                    f"Card for {handle_uri} missing 'path' field in content"
+                )
+            paths[db_key] = Path(db_path)
+
+        # Derive tri_db_dir from the common parent of the three paths
+        parents = {p.parent for p in paths.values()}
+        tri_db_dir = parents.pop() if len(parents) == 1 else None
+
+        return cls(
+            agent_identities=CardCollection(db_path=str(paths["agent_identities"])),
+            content_memory=CardCollection(db_path=str(paths["content_memory"])),
+            execution_log=CardCollection(db_path=str(paths["execution_log"])),
+            tri_db_dir=tri_db_dir,
+        )
+
+    @classmethod
+    def from_paths(cls, tri_db_dir: Path | str) -> TriDatabase:
+        """Create TriDatabase with explicit directory path.
+
+        Instantiates three CardCollections in the given directory using
+        the canonical filenames defined by the Four-Database Topology.
+
+        Args:
+            tri_db_dir: Directory containing (or to create) the three databases.
+
+        Returns:
+            TriDatabase with collections at canonical paths.
+        """
+
+        tri_db_dir = Path(tri_db_dir)
+        tri_db_dir.mkdir(parents=True, exist_ok=True)
+
+        return cls(
+            agent_identities=CardCollection(
+                db_path=str(tri_db_dir / DB_AGENT_IDENTITIES)
+            ),
+            content_memory=CardCollection(db_path=str(tri_db_dir / DB_CONTENT_MEMORY)),
+            execution_log=CardCollection(db_path=str(tri_db_dir / DB_EXECUTION_LOG)),
+            tri_db_dir=tri_db_dir,
+        )
+
+    @classmethod
+    def in_memory(cls) -> TriDatabase:
+        """Create an in-memory TriDatabase for testing.
+
+        All three databases use in-memory SQLite, enabling fast,
+        isolated test execution without filesystem side effects.
+
+        Returns:
+            TriDatabase with ephemeral, in-memory collections.
+        """
+
+        return cls(
+            agent_identities=CardCollection(db_path=":memory:"),
+            content_memory=CardCollection(db_path=":memory:"),
+            execution_log=CardCollection(db_path=":memory:"),
+            tri_db_dir=None,
+        )
+
+    def monotonic_merge(self, other: TriDatabase) -> TriDatabase:
+        """CRDT lattice-join: merge two Tri-Databases via monotonic union.
+
+        Per §Key Arch Principles #10: all data merges are mathematically
+        defined by monotonic lattice joins, guaranteeing Strong Eventual
+        Consistency (SEC). This means:
+
+        - Commutativity:  A.merge(B) == B.merge(A)
+        - Associativity:  (A.merge(B)).merge(C) == A.merge(B.merge(C))
+        - Idempotency:    A.merge(A) == A
+        - Monotonicity:   A ⊑ A.merge(B) — merged state is always "more defined"
+
+        The merge operation unions the card tables (content-addressed
+        deduplication is automatic via hash identity) and takes the latest
+        handle_registry entries by timestamp ordering.
+
+        Args:
+            other: The TriDatabase to merge from.
+
+        Returns:
+            A new TriDatabase containing the lattice-join of both inputs.
+
+        Note:
+            This is a foundational operation for future distributed mesh
+            replication. Currently supports local backup/restore with
+            provable convergence guarantees.
+        """
+        merged = TriDatabase.in_memory()
+
+        for src_db_name in ("agent_identities", "content_memory", "execution_log"):
+            src_self = getattr(self, src_db_name)
+            src_other = getattr(other, src_db_name)
+            dst = getattr(merged, src_db_name)
+
+            # Union card tables — hash identity gives automatic deduplication
+            raw_self = src_self.get_all_mcards_raw() if hasattr(src_self, "get_all_mcards_raw") else []
+            for card in raw_self:
+                try:
+                    dst.add(card)
+                except Exception:
+                    pass  # Already exists (idempotent by hash)
+
+            raw_other = src_other.get_all_mcards_raw() if hasattr(src_other, "get_all_mcards_raw") else []
+            for card in raw_other:
+                try:
+                    dst.add(card)
+                except Exception:
+                    pass  # Already exists (idempotent by hash)
+
+        logger.info("TriDatabase monotonic merge completed (lattice-join)")
+        return merged
+
+
+__all__ = [
+    "CLMDB",
+    "CLMRepository",
+    "init_tridb",
+    "memorize_mcard",
+    "register_handle",
+    "resolve_handle_content",
+    "resolve_handle_hash",
+    "HANDLE_AGENT_IDENTITIES",
+    "HANDLE_CONTENT_MEMORY",
+    "HANDLE_EXECUTION_LOG",
+    "DB_AGENT_IDENTITIES",
+    "DB_CONTENT_MEMORY",
+    "DB_EXECUTION_LOG",
+    "TriDatabase",
+]

clm/layer2/vcard_receipt.py

@@ -0,0 +1,71 @@
+"""VCard Receipt & Proof Generator (Sprint 394 / DEL-394-03).
+
+Generates cryptographic proof receipts (archetype VCardReceipt) verifying that an
+Action executed successfully within the Hoare Sandwich ({V_pre} Action {V_post}).
+
+Acceptance Criteria:
+- AC-394-03-03: Produces signed VCardReceipt containing input/output hashes, timestamps, and witness.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from clm.cross_cutting.domain_models import MCard
+from clm.layer0.model.card_triad import compute_canonical_hash
+from clm.layer0.utils import clm_hash_string
+
+
+def generate_vcard_receipt(
+    action_name: str,
+    action_hash: str,
+    input_hashes: dict[str, str],
+    output_hashes: dict[str, str],
+    precondition_verdicts: list[dict[str, Any]],
+    postcondition_verdicts: list[dict[str, Any]],
+    author: str = "did:clm:verifier",
+    metrics: dict[str, Any] | None = None,
+) -> MCard:
+    """Generate an immutable VCard proof receipt certifying valid execution."""
+    now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    # Compute triadic witness hash: H(V_pre || Action || V_post)
+    pre_digest = compute_canonical_hash(precondition_verdicts)
+    post_digest = compute_canonical_hash(postcondition_verdicts)
+    witness_preimage = f"{pre_digest}:{action_hash}:{post_digest}"
+    witness_hash = clm_hash_string(witness_preimage)
+
+    payload = {
+        "archetype": "VCardReceipt",
+        "action": {
+            "name": action_name,
+            "hash": action_hash,
+        },
+        "inputs": input_hashes,
+        "outputs": output_hashes,
+        "verification": {
+            "all_passed": True,
+            "postconditions": postcondition_verdicts,
+            "preconditions": precondition_verdicts,
+        },
+        "witness": witness_hash,
+    }
+
+    receipt_hash = compute_canonical_hash(payload)
+    uri = f"mcard://receipts/{receipt_hash[:16]}"
+
+    mcard = MCard.create(
+        uri=uri,
+        payload=payload,
+        author=author,
+        metadata={
+            "format": "json",
+            "archetype": "VCardReceipt",
+            "action_name": action_name,
+            "witness": witness_hash,
+            "metrics": metrics or {},
+            "timestamp": now,
+        },
+    )
+    return mcard

clm/layer2/vfs.py

@@ -0,0 +1,17 @@
+"""Layer 2: MCard Virtual Filesystem (VFS) & Shared State Store.
+
+Canonical Path: kernel/scripts/clm/layer2/vfs.py
+Parity: Rust `src/layer2/vfs.rs`, TypeScript `src/layer2/mcardFs/filesystem.ts`
+"""
+
+from __future__ import annotations
+
+from clm.layer2.mcard_fs import MCardFileSystem, MCardStat
+from clm.layer2.shared_store import PTRSharedStore, create_store_from_context
+
+__all__ = [
+    "MCardFileSystem",
+    "MCardStat",
+    "PTRSharedStore",
+    "create_store_from_context",
+]

clm/layer3/__init__.py

@@ -0,0 +1,141 @@
+"""CLM layer3 package — Distributed Network Gateway, Reticulum Mesh & Satori Protocols (Sprint 390).
+
+Stratified subpackages:
+- clm.layer3.reticulum: Sovereign mesh transport, discovery, identity, media, daemon
+- clm.layer3.satori: Speech-act protocol, delimited continuations, sheaf auditing, lambda calculus
+- clm.layer3.agency: Autonomous roles and LLM runtime
+- clm.layer3.rag: Retrieval-Augmented Generation engine
+- clm.layer3.gateway: Handle routing across local and remote mediums
+"""
+from __future__ import annotations
+
+# Subpackages
+from clm.layer3 import agency, rag, reticulum, satori
+from clm.layer3.gateway import remote_handle_resolver, route_handle
+from clm.layer3.reticulum.bridge import SatoriReticulumBridge
+from clm.layer3.reticulum.daemon import ReticulumLocalDaemon
+
+# Reticulum Primitives
+from clm.layer3.reticulum.discovery import (
+    RETICULUM_AUTOINTERFACE_PORT,
+    ReticulumDiscoveryEngine,
+    ReticulumDiscoveryService,
+)
+from clm.layer3.reticulum.identity import (
+    create_rns_identity_from_seed,
+    derive_destination_hash,
+    derive_destination_hex,
+    extract_raw_pubkey_from_did,
+)
+from clm.layer3.reticulum.media import (
+    fetch_mcard_resource,
+    inject_mcard_to_peer,
+    reassemble_chunks,
+    slice_into_chunks,
+)
+from clm.layer3.reticulum.transport import (
+    ReticulumLinkSession,
+    ReticulumTransport,
+    establish_link_pair,
+)
+from clm.layer3.satori.continuation import ContinuationToken
+from clm.layer3.satori.sheaf_audit import (
+    Marking,
+    OpenSet,
+    Place,
+    Section,
+    Sheaf,
+    SheafAuditor,
+    SheafAuditReport,
+    audit_maxwell_demon,
+)
+
+# Satori Speech Acts & Sheaf Consensus
+from clm.layer3.satori.speech_act import (
+    OPCODES_TO_TYPE,
+    SATORI_OPCODES,
+    SpeechAct,
+    SpeechActType,
+    classify_speech_act,
+    create_assert,
+    create_commissive,
+    create_commit,
+    create_declarative,
+    create_declare,
+    create_directive,
+    create_expressive,
+    create_request,
+    decode_satori_binary,
+    encode_satori_binary,
+)
+
+# Sprint 383 (DEL-383-04): Register Layer 3 runtimes with Layer 1 runtime factory
+try:
+    from clm.layer1.runtimes.factory import register_external_executor
+    from clm.layer3.satori.lambda_runtime import LambdaRuntime
+
+    register_external_executor("lambda", LambdaRuntime)
+except Exception:
+    pass
+
+try:
+    from clm.layer1.runtimes.factory import register_external_executor
+    from clm.layer3.agency.runtime import LLMRuntime
+
+    register_external_executor("llm", LLMRuntime)
+except Exception:
+    pass
+
+__all__ = [
+    # Subpackages
+    "agency",
+    "rag",
+    "reticulum",
+    "satori",
+    # Gateway
+    "route_handle",
+    "remote_handle_resolver",
+    # Reticulum
+    "RETICULUM_AUTOINTERFACE_PORT",
+    "ReticulumDiscoveryService",
+    "ReticulumDiscoveryEngine",
+    "ReticulumLinkSession",
+    "ReticulumTransport",
+    "establish_link_pair",
+    "create_rns_identity_from_seed",
+    "derive_destination_hash",
+    "derive_destination_hex",
+    "extract_raw_pubkey_from_did",
+    "fetch_mcard_resource",
+    "inject_mcard_to_peer",
+    "reassemble_chunks",
+    "slice_into_chunks",
+    "ReticulumLocalDaemon",
+    "SatoriReticulumBridge",
+    # Satori Speech Acts
+    "SATORI_OPCODES",
+    "OPCODES_TO_TYPE",
+    "SpeechActType",
+    "SpeechAct",
+    "encode_satori_binary",
+    "decode_satori_binary",
+    "classify_speech_act",
+    "create_assert",
+    "create_directive",
+    "create_request",
+    "create_commissive",
+    "create_commit",
+    "create_expressive",
+    "create_declarative",
+    "create_declare",
+    # Sheaf
+    "Place",
+    "Marking",
+    "OpenSet",
+    "Section",
+    "Sheaf",
+    "SheafAuditReport",
+    "SheafAuditor",
+    "audit_maxwell_demon",
+    "ContinuationToken",
+]

clm/layer3/agency/__init__.py

@@ -0,0 +1,19 @@
+"""
+LLM Runtime Package
+
+Provides LLM execution capabilities integrated with the PTR engine.
+"""
+
+from .config import DEFAULT_LLM_CONFIG, LLM_PROVIDERS, LLMConfig
+from .router import IntelligenceRouter
+from .runtime import LLMRuntime, chat_monad, prompt_monad
+
+__all__ = [
+    "LLMConfig",
+    "LLM_PROVIDERS",
+    "DEFAULT_LLM_CONFIG",
+    "LLMRuntime",
+    "prompt_monad",
+    "chat_monad",
+    "IntelligenceRouter",
+]