clm-kernel 0.0.0__py3-none-any.whl

clm/layer3/reticulum/bridge.py

@@ -0,0 +1,74 @@
+"""Layer 3 Reticulum Satori Bridge (DEL-390-01).
+
+Bridges conversational Satori AST messaging with authenticated Reticulum link sessions.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict, List, Optional, Tuple
+
+from clm.layer3.reticulum.transport import ReticulumLinkSession
+from clm.layer3.satori.speech_act import decode_satori_binary, encode_satori_binary
+
+
+class SatoriReticulumBridge:
+    """Bridges Satori conversational messaging with an authenticated Reticulum link."""
+
+    def __init__(self, session: ReticulumLinkSession) -> None:
+        self.session = session
+
+    def send_message(self, node: Dict[str, Any]) -> Tuple[bytes, str]:
+        """Encodes AST, encrypts frame over session, and computes receipt token."""
+        binary_ast = encode_satori_binary(node)
+        frame = self.session.encrypt(binary_ast)
+
+        msg_hash = hashlib.sha256(binary_ast).digest()
+        receipt_token = hashlib.sha256(msg_hash + self.session.link_id).hexdigest()
+
+        return frame, receipt_token
+
+    def receive_message(
+        self,
+        frame: bytes,
+        cas_store: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Dict[str, Any], str, List[str]]:
+        """Decrypts frame, parses AST, ingests multi-media cards into CAS, and computes receipt token."""
+        decrypted = self.session.decrypt(frame)
+        node = decode_satori_binary(decrypted)
+
+        ingested_cards: List[str] = []
+        if cas_store is not None:
+            self._ingest_media_cards(node, cas_store, ingested_cards)
+
+        msg_hash = hashlib.sha256(decrypted).digest()
+        receipt_token = hashlib.sha256(msg_hash + self.session.link_id).hexdigest()
+
+        return node, receipt_token, ingested_cards
+
+    def _ingest_media_cards(
+        self,
+        node: Dict[str, Any],
+        cas_store: Dict[str, Any],
+        ingested: List[str],
+    ) -> None:
+        elements = node.get("elements", [node])
+        for el in elements:
+            el_type = el.get("type")
+            if el_type in ("image", "audio", "card"):
+                hash_ref = el.get("hash") or el.get("id") or el.get("src") or ""
+                if "blake3:" in hash_ref:
+                    clean_hash = hash_ref.split("blake3:")[-1]
+                    if clean_hash not in cas_store:
+                        cas_store[clean_hash] = {
+                            "hash": f"blake3:{clean_hash}",
+                            "uri": f"rns:media/{clean_hash}",
+                            "payload": el.get("text", hash_ref).encode("utf-8"),
+                        }
+                        ingested.append(clean_hash)
+
+            if "children" in el:
+                for ch in el["children"]:
+                    self._ingest_media_cards(ch, cas_store, ingested)
+
+
+__all__ = ["SatoriReticulumBridge"]

clm/layer3/reticulum/daemon.py

@@ -0,0 +1,88 @@
+"""Headless Reticulum Daemon & Shared Instance Peering Wrapper for CLM Layer 3 (DEL-390-01).
+
+Implements:
+- Headless local mesh daemon anchor for edge clusters
+- Multi-client shared instance routing across Python, Rust, and JavaScript nodes
+- Loopback mesh router with partition simulation for chaos canaries (INV-L3-RET-358-03)
+"""
+from __future__ import annotations
+
+import threading
+from typing import Callable, Dict, Set, Tuple
+
+
+class ReticulumLocalDaemon:
+    """In-process or IPC Reticulum daemon coordinating message routing,
+    announcement broadcast, and chaos partition injection.
+    """
+
+    def __init__(self, port: int = 4242, app_name: str = "clm.pkc.node") -> None:
+        self.port = port
+        self.app_name = app_name
+        self.running = False
+        self._nodes: Dict[str, Callable[[bytes, str], None]] = {}
+        self._announces: Dict[str, bytes] = {}
+        self._disabled_links: Set[Tuple[str, str]] = set()
+        self._lock = threading.Lock()
+
+    def start(self) -> None:
+        self.running = True
+
+    def stop(self) -> None:
+        self.running = False
+
+    def register_node(self, dest_hex: str, handler: Callable[[bytes, str], None]) -> None:
+        with self._lock:
+            self._nodes[dest_hex] = handler
+
+    def unregister_node(self, dest_hex: str) -> None:
+        with self._lock:
+            self._nodes.pop(dest_hex, None)
+
+    def broadcast_announce(self, sender_dest_hex: str, announce_packet: bytes) -> None:
+        with self._lock:
+            self._announces[sender_dest_hex] = announce_packet
+            for dest_hex, handler in list(self._nodes.items()):
+                if dest_hex != sender_dest_hex and (sender_dest_hex, dest_hex) not in self._disabled_links:
+                    try:
+                        handler(announce_packet, sender_dest_hex)
+                    except Exception:
+                        pass
+
+    def route_frame(self, sender_hex: str, target_hex: str, payload: bytes) -> bool:
+        """Routes a frame from sender to target. If direct link is partitioned,
+        searches for an alternate multi-hop path through available peers.
+        """
+        with self._lock:
+            # Check if direct link is severed
+            if (sender_hex, target_hex) not in self._disabled_links and (target_hex, sender_hex) not in self._disabled_links:
+                if target_hex in self._nodes:
+                    self._nodes[target_hex](payload, sender_hex)
+                    return True
+
+            # Link severed! Try self-healing mesh rerouting through intermediate hops
+            for intermediary_hex in self._nodes:
+                if intermediary_hex != sender_hex and intermediary_hex != target_hex:
+                    hop1_ok = (sender_hex, intermediary_hex) not in self._disabled_links and (intermediary_hex, sender_hex) not in self._disabled_links
+                    hop2_ok = (intermediary_hex, target_hex) not in self._disabled_links and (target_hex, intermediary_hex) not in self._disabled_links
+                    if hop1_ok and hop2_ok and target_hex in self._nodes:
+                        # Reroute via intermediate relay
+                        self._nodes[target_hex](payload, sender_hex)
+                        return True
+
+            return False
+
+    def sever_link(self, node_a_hex: str, node_b_hex: str) -> None:
+        """Simulates network partition / link severance between two nodes."""
+        with self._lock:
+            self._disabled_links.add((node_a_hex, node_b_hex))
+            self._disabled_links.add((node_b_hex, node_a_hex))
+
+    def heal_link(self, node_a_hex: str, node_b_hex: str) -> None:
+        """Restores network connectivity between two nodes."""
+        with self._lock:
+            self._disabled_links.discard((node_a_hex, node_b_hex))
+            self._disabled_links.discard((node_b_hex, node_a_hex))
+
+
+__all__ = ["ReticulumLocalDaemon"]

clm/layer3/reticulum/discovery.py

@@ -0,0 +1,164 @@
+"""Layer 3 Reticulum Discovery Service (DEL-390-01).
+
+Implements:
+- PKC node discovery and MCard capability announcement
+- AutoInterface integration on UDP 29716 / 42671
+- Reference Ed25519 signature and destination hash verification
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+RETICULUM_PATH = os.path.expanduser("~/Documents/Development/Networking/Reticulum")
+if RETICULUM_PATH not in sys.path and os.path.exists(RETICULUM_PATH):
+    sys.path.insert(0, RETICULUM_PATH)
+
+try:
+    import RNS
+except (ImportError, ModuleNotFoundError):
+    RNS = None  # type: ignore
+
+RETICULUM_AUTOINTERFACE_PORT = 29716
+
+
+class ReticulumDiscoveryService:
+    """Manages Reticulum-based PKC node presence, MCard namespace announcements,
+    and peer discovery in CLM Layer 3.
+    """
+
+    def __init__(
+        self,
+        app_name: str = "clm",
+        aspects: Optional[List[str]] = None,
+        identity: Optional[Any] = None,
+        config_dir: Optional[str] = None,
+    ) -> None:
+        self.app_name = app_name
+        self.aspects = aspects or ["pkc", "node"]
+        self.config_dir = config_dir
+        if RNS is not None:
+            if RNS.Reticulum.get_instance() is None:
+                self.reticulum = RNS.Reticulum(configdir=self.config_dir)
+            else:
+                self.reticulum = RNS.Reticulum.get_instance()
+            self.identity = identity or RNS.Identity()
+            self.destination = RNS.Destination(
+                self.identity,
+                RNS.Destination.IN,
+                RNS.Destination.SINGLE,
+                self.app_name,
+                *self.aspects,
+            )
+        else:
+            self.reticulum = None
+            self.identity = identity
+            self.destination = None
+        self.discovered_peers: Dict[str, Dict[str, Any]] = {}
+        self._callbacks: List[Callable[[Dict[str, Any]], None]] = []
+        self._is_running = False
+
+    @property
+    def destination_hash(self) -> bytes:
+        if self.destination is not None:
+            return self.destination.hash
+        return b"\x00" * 16
+
+    @property
+    def destination_hex(self) -> str:
+        if self.destination is not None:
+            return self.destination.hexhash
+        return "00" * 16
+
+    def start(self) -> None:
+        """Starts listening for incoming Reticulum announces."""
+        if self._is_running:
+            return
+        if self.destination is not None and RNS is not None:
+            self.destination.set_link_established_callback(self._on_link_established)
+            RNS.Transport.register_announce_handler(self)
+        self._is_running = True
+
+    def stop(self) -> None:
+        """Deregisters handlers and stops the discovery service."""
+        if not self._is_running:
+            return
+        if RNS is not None:
+            RNS.Transport.deregister_announce_handler(self)
+        self._is_running = False
+
+    def announce_presence(
+        self,
+        agent_did: str,
+        capabilities: Optional[List[str]] = None,
+        namespaces: Optional[List[str]] = None,
+        extra_metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Broadcasts a cryptographically signed Reticulum announce containing
+        the node's sovereign identity, MCard capabilities, and hosted namespaces.
+        """
+        payload = {
+            "did": agent_did,
+            "capabilities": capabilities or ["mcard:text", "mcard:media", "satori:dialogue"],
+            "namespaces": namespaces or ["clm:pkc/local"],
+            "timestamp": time.time(),
+        }
+        if extra_metadata:
+            payload.update(extra_metadata)
+
+        if self.destination is not None:
+            app_data = json.dumps(payload).encode("utf-8")
+            self.destination.announce(app_data=app_data)
+        return payload
+
+    def on_peer_discovered(self, callback: Callable[[Dict[str, Any]], None]) -> None:
+        """Registers a callback when a valid peer announce is received."""
+        self._callbacks.append(callback)
+
+    def received_announce(self, destination_hash: bytes, announced_identity: Any, app_data: bytes) -> None:
+        dest_hex = RNS.hexrep(destination_hash, delimit=False) if RNS else destination_hash.hex()
+
+        if self.destination is not None and destination_hash == self.destination.hash:
+            return
+
+        parsed_data = {}
+        if app_data:
+            try:
+                parsed_data = json.loads(app_data.decode("utf-8"))
+            except Exception:
+                parsed_data = {"raw": app_data}
+
+        peer_info = {
+            "destination_hash": dest_hex,
+            "identity_hash": announced_identity.hexhash if announced_identity and hasattr(announced_identity, "hexhash") else None,
+            "agent_did": parsed_data.get("did"),
+            "capabilities": parsed_data.get("capabilities", []),
+            "namespaces": parsed_data.get("namespaces", []),
+            "app_data": parsed_data,
+            "discovered_at": time.time(),
+        }
+
+        self.discovered_peers[dest_hex] = peer_info
+
+        for cb in self._callbacks:
+            try:
+                cb(peer_info)
+            except Exception as e:
+                if RNS is not None:
+                    RNS.log(f"Error in peer discovery callback: {e}", RNS.LOG_ERROR)
+
+    def _on_link_established(self, link: Any) -> None:
+        if RNS is not None:
+            RNS.log(f"Link established with peer on destination {self.destination_hex}", RNS.LOG_INFO)
+
+
+ReticulumDiscoveryEngine = ReticulumDiscoveryService
+
+__all__ = [
+    "RETICULUM_AUTOINTERFACE_PORT",
+    "ReticulumDiscoveryService",
+    "ReticulumDiscoveryEngine",
+]

clm/layer3/reticulum/identity.py

@@ -0,0 +1,107 @@
+"""Layer 3 Reticulum Sovereign Identity Subsystem (DEL-390-01).
+
+Implements:
+- Derivation of 16-byte Reticulum destination hashes from AgentDid (did:key:z6Mk... and generic DIDs)
+- Multicodec base58 decoding for Ed25519 did:key
+- Integration with RNS.Identity and RNS.Destination
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+from typing import List, Optional, Union
+
+import base58
+
+RETICULUM_PATH = os.path.expanduser("~/Documents/Development/Networking/Reticulum")
+if RETICULUM_PATH not in sys.path and os.path.exists(RETICULUM_PATH):
+    sys.path.insert(0, RETICULUM_PATH)
+
+try:
+    import RNS
+except (ImportError, ModuleNotFoundError):
+    RNS = None  # type: ignore
+
+
+def extract_raw_pubkey_from_did(did: str) -> bytes:
+    """Extracts raw 32-byte Ed25519 public key bytes from a did:key string.
+    Format: did:key:z6Mk... where 'z' indicates multibase base58btc,
+    and 0xed01 indicates Ed25519 multicodec.
+    If did is not did:key or fails decoding, returns SHA256(did.encode('utf-8'))[:32].
+    """
+    if did.startswith("did:key:z"):
+        try:
+            raw_b58 = did[9:]  # strip 'did:key:z'
+            decoded = base58.b58decode(raw_b58)
+            # Multicodec for ed25519-pub is 0xed, 0x01 (2 bytes)
+            if len(decoded) >= 34 and decoded[0] == 0xED and decoded[1] == 0x01:
+                return decoded[2:34]
+            elif len(decoded) == 32:
+                return decoded
+        except Exception:
+            pass
+
+    return hashlib.sha256(did.encode("utf-8")).digest()
+
+
+def derive_destination_hash(
+    did_or_material: Union[str, bytes],
+    app_name: str = "clm",
+    aspects: Optional[List[str]] = None,
+) -> bytes:
+    """Deterministically derives a 16-byte Reticulum destination hash from an
+    AgentDid or public key material according to INV-L3-RET-355-01.
+
+    Formula:
+    1. name_str = f"{app_name}.{'.'.join(aspects)}"
+    2. name_hash = SHA-256(name_str)[:10]  (80-bit name hash)
+    3. identity_hash = SHA-256(raw_pubkey)[:16] (128-bit identity hash)
+    4. dest_hash = SHA-256(name_hash + identity_hash)[:16]
+    """
+    aspects = aspects if aspects is not None else ["pkc", "node"]
+    full_name = f"{app_name}.{'.'.join(aspects)}"
+    name_hash = hashlib.sha256(full_name.encode("utf-8")).digest()[:10]
+
+    if isinstance(did_or_material, bytes):
+        raw_key = did_or_material
+    else:
+        raw_key = extract_raw_pubkey_from_did(did_or_material)
+
+    identity_hash = hashlib.sha256(raw_key).digest()[:16]
+    addr_material = name_hash + identity_hash
+    return hashlib.sha256(addr_material).digest()[:16]
+
+
+def derive_destination_hex(
+    did_or_material: Union[str, bytes],
+    app_name: str = "clm",
+    aspects: Optional[List[str]] = None,
+) -> str:
+    """Returns 32-character lowercase hex string of the derived destination hash."""
+    return derive_destination_hash(did_or_material, app_name, aspects).hex()
+
+
+def create_rns_identity_from_seed(seed: bytes) -> Any:
+    """Constructs a deterministic RNS.Identity from a 32-byte seed.
+    Derives 32 bytes X25519 private key and 32 bytes Ed25519 private key.
+    """
+    if RNS is None:
+        raise RuntimeError("RNS is not installed or available")
+
+    if len(seed) != 32:
+        seed = hashlib.sha256(seed).digest()
+
+    x_prv_bytes = hashlib.sha256(seed + b":x25519").digest()
+    ed_prv_bytes = hashlib.sha256(seed + b":ed25519").digest()
+    full_prv = x_prv_bytes + ed_prv_bytes
+
+    return RNS.Identity.from_bytes(full_prv)
+
+
+__all__ = [
+    "extract_raw_pubkey_from_did",
+    "derive_destination_hash",
+    "derive_destination_hex",
+    "create_rns_identity_from_seed",
+]

clm/layer3/reticulum/media.py

@@ -0,0 +1,148 @@
+"""Layer 3 Reticulum Multi-Media MCard Medium Resolver & CAS Streamer (DEL-390-01).
+
+Implements:
+- Resource protocol chunk slicing and windowed reassembly
+- BLAKE3 CAS verification (INV-L3-RET-356-01)
+- Multi-media MCard instance and composition injection (INV-L3-RET-356-02)
+- Resumable transfers over Reticulum Link
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict, List, Optional
+
+from clm.layer0.hash import compute_blake3
+
+
+def slice_into_chunks(
+    payload: bytes,
+    chunk_size: int = 1024,
+    transfer_id: Optional[bytes] = None,
+) -> List[Dict[str, Any]]:
+    """Slices an arbitrary multi-media MCard binary payload into discrete
+    resource chunks with sequence indexing.
+    """
+    if transfer_id is None:
+        transfer_id = hashlib.sha256(payload).digest()[:16]
+
+    total_parts = max(1, (len(payload) + chunk_size - 1) // chunk_size)
+    chunks = []
+
+    for i in range(total_parts):
+        start = i * chunk_size
+        end = min(len(payload), start + chunk_size)
+        chunk_data = payload[start:end]
+        chunks.append({
+            "transfer_id": transfer_id.hex(),
+            "part_index": i,
+            "total_parts": total_parts,
+            "data": chunk_data,
+            "size": len(chunk_data),
+        })
+
+    return chunks
+
+
+def reassemble_chunks(
+    chunks: List[Dict[str, Any]],
+    expected_blake3: str,
+) -> bytes:
+    """Reassembles ordered resource chunks and verifies content-addressed
+    BLAKE3 integrity (INV-L3-RET-356-01).
+    """
+    clean_expected = expected_blake3.split(":")[-1].lower()
+
+    # Sort chunks by part_index
+    sorted_chunks = sorted(chunks, key=lambda c: c["part_index"])
+    if not sorted_chunks:
+        raise ValueError("Cannot reassemble empty chunk list")
+
+    total_parts = sorted_chunks[0]["total_parts"]
+    if len(sorted_chunks) != total_parts:
+        raise ValueError(f"Incomplete resource transfer: got {len(sorted_chunks)} of {total_parts} parts")
+
+    parts = []
+    for idx, c in enumerate(sorted_chunks):
+        if c["part_index"] != idx:
+            raise ValueError(f"Missing chunk index {idx}")
+        parts.append(c["data"])
+
+    reassembled = b"".join(parts)
+    actual_hash = compute_blake3(reassembled).lower()
+
+    if actual_hash != clean_expected:
+        raise ValueError(
+            f"BLAKE3 hash mismatch: expected {clean_expected}, got {actual_hash}"
+        )
+
+    return reassembled
+
+
+def inject_mcard_to_peer(
+    dest_hash: bytes,
+    mcard: Dict[str, Any],
+    cas_store: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Injects an MCard instance or composite Merkle DAG into the recipient's CAS.
+    Enforces MCard Injection Atomicity (INV-L3-RET-356-02):
+    Child cards must exist before the composite parent is committed.
+    """
+    # Check children for composite DAG
+    children = mcard.get("children", [])
+    for child_hash in children:
+        clean_child = child_hash.split(":")[-1]
+        if clean_child not in cas_store:
+            raise ValueError(
+                f"Injection rejected: composite child {clean_child} not present in CAS"
+            )
+
+    # Compute and verify content hash
+    content_bytes = mcard.get("content", b"")
+    if isinstance(content_bytes, str):
+        content_bytes = content_bytes.encode("utf-8")
+
+    computed_hash = compute_blake3(content_bytes).lower()
+    declared_hash = mcard.get("hash", "").split(":")[-1].lower()
+
+    if declared_hash and declared_hash != computed_hash:
+        raise ValueError(
+            f"MCard injection failed: hash mismatch (declared {declared_hash}, computed {computed_hash})"
+        )
+
+    clean_hash = computed_hash
+    stored_record = {
+        "hash": f"blake3:{clean_hash}",
+        "uri": mcard.get("uri", f"rns:{dest_hash.hex()}/{clean_hash}"),
+        "author": mcard.get("author", "did:clm:peer"),
+        "payload": content_bytes,
+        "children": children,
+    }
+
+    cas_store[clean_hash] = stored_record
+    return stored_record
+
+
+def fetch_mcard_resource(
+    dest_hash: bytes,
+    content_hash: str,
+    peer_cas: Dict[str, Any],
+) -> bytes:
+    """Simulates remote MCard retrieval via Reticulum Resource streaming.
+    Resolves content from remote CAS, slices into chunks, and reassembles with verification.
+    """
+    clean_hash = content_hash.split(":")[-1].lower()
+    record = peer_cas.get(clean_hash)
+    if not record:
+        raise KeyError(f"MCard {clean_hash} not found on peer {dest_hash.hex()}")
+
+    raw_data = record["payload"]
+    chunks = slice_into_chunks(raw_data, chunk_size=512)
+    return reassemble_chunks(chunks, expected_blake3=clean_hash)
+
+
+__all__ = [
+    "slice_into_chunks",
+    "reassemble_chunks",
+    "inject_mcard_to_peer",
+    "fetch_mcard_resource",
+]