clm-kernel 0.0.0__py3-none-any.whl

clm/layer3/reticulum/transport.py

@@ -0,0 +1,133 @@
+"""Layer 3 Reticulum Link Transport (DEL-390-01).
+
+Implements:
+- Single-roundtrip ephemeral Link handshake (X25519 ECDH + HKDF)
+- Authenticated AES-256 session encryption with Perfect Forward Secrecy (PFS)
+- Initiator anonymity (packets omit sender identity)
+- Clean session teardown with key zeroization
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+from typing import Optional, Tuple
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import x25519
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+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
+
+
+class ReticulumLinkSession:
+    """Manages an authenticated, encrypted point-to-point session between two
+    conversational PKC nodes over Reticulum transport.
+    """
+
+    def __init__(
+        self,
+        destination_hash: bytes,
+        is_initiator: bool = True,
+        link_id: Optional[bytes] = None,
+    ) -> None:
+        self.destination_hash = destination_hash
+        self.is_initiator = is_initiator
+        self.link_id = link_id or hashlib.sha256(os.urandom(32)).digest()[:16]
+        self._ephemeral_prv: Optional[x25519.X25519PrivateKey] = x25519.X25519PrivateKey.generate()
+        self._ephemeral_pub: Optional[x25519.X25519PublicKey] = self._ephemeral_prv.public_key()
+        self.derived_key: Optional[bytes] = None
+        self._cipher: Optional[AESGCM] = None
+        self._seq: int = 0
+        self.is_closed: bool = False
+
+    @property
+    def ephemeral_public_bytes(self) -> bytes:
+        if self._ephemeral_pub is None:
+            raise RuntimeError("Session is closed or key dropped")
+        return self._ephemeral_pub.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+
+    def complete_handshake(self, peer_ephemeral_pub_bytes: bytes) -> None:
+        """Executes X25519 ECDH exchange and HKDF key derivation using link_id as salt.
+        Derives 32-byte key for AES-256-GCM session cipher.
+        """
+        if self._ephemeral_prv is None:
+            raise RuntimeError("Session is closed")
+
+        peer_pub = x25519.X25519PublicKey.from_public_bytes(peer_ephemeral_pub_bytes)
+        shared_secret = self._ephemeral_prv.exchange(peer_pub)
+
+        hkdf = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=self.link_id,
+            info=b"clm:reticulum:link:session",
+        )
+        self.derived_key = hkdf.derive(shared_secret)
+        self._cipher = AESGCM(self.derived_key)
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        """Encrypts plaintext payload using AES-256-GCM.
+        Framing: [12-byte nonce (seq + random)] + [ciphertext + 16-byte tag]
+        Does NOT leak sender address (INV-L3-RET-355-03).
+        """
+        if self._cipher is None or self.is_closed:
+            raise RuntimeError("Cannot encrypt on unestablished or closed session")
+
+        self._seq += 1
+        nonce = self._seq.to_bytes(4, byteorder="big") + os.urandom(8)
+        ciphertext = self._cipher.encrypt(nonce, plaintext, associated_data=self.link_id)
+        return nonce + ciphertext
+
+    def decrypt(self, frame: bytes) -> bytes:
+        """Decrypts and authenticates AES-256-GCM frame."""
+        if self._cipher is None or self.is_closed:
+            raise RuntimeError("Cannot decrypt on unestablished or closed session")
+
+        if len(frame) < 12 + 16:
+            raise ValueError("Encrypted frame too short")
+
+        nonce = frame[:12]
+        ciphertext = frame[12:]
+        return self._cipher.decrypt(nonce, ciphertext, associated_data=self.link_id)
+
+    def close(self) -> None:
+        """Drops ephemeral keys and zeroes session key (INV-L3-RET-355-02: PFS)."""
+        self._ephemeral_prv = None
+        self._ephemeral_pub = None
+        self.derived_key = None
+        self._cipher = None
+        self.is_closed = True
+
+
+def establish_link_pair(dest_hash: bytes) -> Tuple[ReticulumLinkSession, ReticulumLinkSession]:
+    """Helper that creates an initiator and responder session and handshakes them."""
+    link_id = hashlib.sha256(os.urandom(32)).digest()[:16]
+    initiator = ReticulumLinkSession(dest_hash, is_initiator=True, link_id=link_id)
+    responder = ReticulumLinkSession(dest_hash, is_initiator=False, link_id=link_id)
+
+    # Handshake exchange
+    initiator.complete_handshake(responder.ephemeral_public_bytes)
+    responder.complete_handshake(initiator.ephemeral_public_bytes)
+
+    return initiator, responder
+
+
+ReticulumTransport = ReticulumLinkSession
+
+__all__ = [
+    "ReticulumLinkSession",
+    "ReticulumTransport",
+    "establish_link_pair",
+]

clm/layer3/satori/__init__.py

@@ -0,0 +1,209 @@
+"""Satori Speech-Act, Delimited Continuation, Sheaf Consensus & Lambda Calculus Package (DEL-390-02).
+
+Normative Reference:
+    docs/spec/20-architecture/system-architecture.md § 3 (Layer 3 Reticulum & Satori)
+    docs/spec/20-architecture/card-triad-architecture.md § Thermodynamic Maxwell's Demon Gate
+
+Invariants:
+    INV-390-01: Searle-Austin Speech Act Taxonomy (Assertive, Directive, Commissive, Expressive, Declarative).
+    INV-390-02: Sheaf Cohomology Obstruction Vanishing (H¹ = 0 consensus, L = S_T - H_T).
+    INV-390-03: Delimited Conversational Continuations (prompt/shift turn execution).
+"""
+from __future__ import annotations
+
+# Lambda Term ADT
+# Alpha Conversion
+from clm.layer3.satori.alpha_conversion import (
+    alpha_equivalent,
+    alpha_normalize,
+    alpha_rename,
+)
+
+# Beta Reduction
+from clm.layer3.satori.beta_reduction import (
+    NormalizationResult,
+    ReductionStrategy,
+    beta_reduce,
+    find_innermost_redex,
+    find_leftmost_redex,
+    has_normal_form,
+    is_normal_form,
+    is_redex,
+    normalize,
+    reduce_step,
+    substitute_with_capture,
+)
+
+# Delimited Continuations
+from clm.layer3.satori.continuation import ContinuationToken
+
+# Eta Conversion
+from clm.layer3.satori.eta_conversion import (
+    beta_eta_normalize,
+    beta_eta_reduce,
+    eta_equivalent,
+    eta_expand,
+    eta_reduce,
+    fully_eta_reduce,
+)
+
+# Free Variables
+from clm.layer3.satori.free_variables import (
+    bound_variables,
+    free_variables,
+    generate_fresh,
+    generate_fresh_for,
+    is_closed,
+    is_free_in,
+)
+
+# Lambda Runtime
+from clm.layer3.satori.lambda_runtime import (
+    LambdaConfig,
+    LambdaOperation,
+    LambdaParser,
+    LambdaRuntime,
+    LambdaRuntimeResult,
+    ParseError,
+    parse_lambda_expression,
+)
+from clm.layer3.satori.lambda_term import (
+    AbsTerm,
+    AppTerm,
+    LambdaTerm,
+    VarTerm,
+    deserialize_term,
+    is_abs,
+    is_app,
+    is_var,
+    load_term,
+    mcard_to_term,
+    mk_abs,
+    mk_app,
+    mk_var,
+    pretty_print_deep,
+    pretty_print_shallow,
+    serialize_term,
+    store_term,
+    term_exists,
+    term_to_mcard,
+)
+
+# Sheaf Cohomology & Maxwell's Demon
+from clm.layer3.satori.sheaf_audit import (
+    Marking,
+    OpenSet,
+    Place,
+    Section,
+    Sheaf,
+    SheafAuditor,
+    SheafAuditReport,
+    audit_maxwell_demon,
+)
+
+# Speech Acts & Binary AST
+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,
+)
+
+__all__ = [
+    # Speech Acts & Binary AST
+    "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 Cohomology & Maxwell's Demon
+    "Place",
+    "Marking",
+    "OpenSet",
+    "Section",
+    "Sheaf",
+    "SheafAuditReport",
+    "SheafAuditor",
+    "audit_maxwell_demon",
+    # Delimited Continuations
+    "ContinuationToken",
+    # Lambda Term ADT
+    "LambdaTerm",
+    "VarTerm",
+    "AbsTerm",
+    "AppTerm",
+    "mk_var",
+    "mk_abs",
+    "mk_app",
+    "serialize_term",
+    "deserialize_term",
+    "term_to_mcard",
+    "mcard_to_term",
+    "store_term",
+    "load_term",
+    "term_exists",
+    "pretty_print_shallow",
+    "pretty_print_deep",
+    "is_var",
+    "is_abs",
+    "is_app",
+    # Free Variables
+    "free_variables",
+    "bound_variables",
+    "is_free_in",
+    "is_closed",
+    "generate_fresh",
+    "generate_fresh_for",
+    # Alpha Conversion
+    "alpha_rename",
+    "alpha_equivalent",
+    "alpha_normalize",
+    # Beta Reduction
+    "ReductionStrategy",
+    "NormalizationResult",
+    "substitute_with_capture",
+    "is_redex",
+    "find_leftmost_redex",
+    "find_innermost_redex",
+    "beta_reduce",
+    "reduce_step",
+    "normalize",
+    "is_normal_form",
+    "has_normal_form",
+    # Eta Conversion
+    "eta_reduce",
+    "eta_expand",
+    "eta_equivalent",
+    "fully_eta_reduce",
+    "beta_eta_reduce",
+    "beta_eta_normalize",
+    # Lambda Runtime
+    "parse_lambda_expression",
+    "ParseError",
+    "LambdaParser",
+    "LambdaOperation",
+    "LambdaConfig",
+    "LambdaRuntimeResult",
+    "LambdaRuntime",
+]

clm/layer3/satori/alpha_conversion.py

@@ -0,0 +1,168 @@
+"""
+Alpha Conversion - Variable renaming in Lambda Calculus
+
+Alpha conversion (α-conversion) allows renaming of bound variables
+without changing the meaning of the term:
+  λx.M ≡α λy.M[x:=y]  (where y is fresh)
+
+This module provides Python parity with mcard-js/src/ptr/lambda/AlphaConversion.ts
+"""
+
+from clm.layer2.card_collection import CardCollection
+from clm.layer3.satori.lambda_term import (
+    is_abs,
+    is_app,
+    is_var,
+    load_term,
+    mk_abs,
+    mk_app,
+    mk_var,
+    store_term,
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Alpha Renaming
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def alpha_rename(
+    collection: CardCollection, hash_value: str, old_name: str, new_name: str
+) -> str | None:
+    """
+    Rename a bound variable in a Lambda term.
+    Returns the hash of the renamed term, or None if term not found.
+
+    Only renames the binding occurrence and all bound occurrences.
+    """
+    term = load_term(collection, hash_value)
+    if term is None:
+        return None
+
+    if is_var(term):
+        # Variable: rename if it matches
+        if term.name == old_name:
+            return store_term(collection, mk_var(new_name))
+        return hash_value
+
+    elif is_abs(term):
+        if term.param == old_name:
+            # This is the binder we're renaming
+            new_body = alpha_rename(collection, term.body, old_name, new_name)
+            if new_body is None:
+                return None
+            return store_term(collection, mk_abs(new_name, new_body))
+        else:
+            # Not bound here, recurse into body
+            new_body = alpha_rename(collection, term.body, old_name, new_name)
+            if new_body is None:
+                return None
+            return store_term(collection, mk_abs(term.param, new_body))
+
+    elif is_app(term):
+        new_func = alpha_rename(collection, term.func, old_name, new_name)
+        new_arg = alpha_rename(collection, term.arg, old_name, new_name)
+        if new_func is None or new_arg is None:
+            return None
+        return store_term(collection, mk_app(new_func, new_arg))
+
+    return hash_value
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Alpha Equivalence
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def alpha_equivalent(
+    collection: CardCollection,
+    hash1: str,
+    hash2: str,
+    env: dict[str, str] | None = None,
+) -> bool | None:
+    """
+    Check if two Lambda terms are α-equivalent.
+
+    Two terms are α-equivalent if they differ only in the names of bound variables.
+    Uses a bijection to track corresponding bound variable names.
+    """
+    if env is None:
+        env = {}
+
+    term1 = load_term(collection, hash1)
+    term2 = load_term(collection, hash2)
+
+    if term1 is None or term2 is None:
+        return None
+
+    if is_var(term1) and is_var(term2):
+        # Check if variables correspond via environment
+        mapped = env.get(term1.name)
+        if mapped is not None:
+            return mapped == term2.name
+        # Not bound - must be same free variable
+        return term1.name == term2.name
+
+    elif is_abs(term1) and is_abs(term2):
+        # Extend environment with parameter correspondence
+        new_env = dict(env)
+        new_env[term1.param] = term2.param
+        return alpha_equivalent(collection, term1.body, term2.body, new_env)
+
+    elif is_app(term1) and is_app(term2):
+        func_eq = alpha_equivalent(collection, term1.func, term2.func, env)
+        if not func_eq:
+            return func_eq
+        return alpha_equivalent(collection, term1.arg, term2.arg, env)
+
+    return False
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Alpha Normalization
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def alpha_normalize(
+    collection: CardCollection, hash_value: str, counter: list | None = None
+) -> str | None:
+    """
+    Normalize bound variable names using de Bruijn-style naming.
+
+    All bound variables are renamed to x0, x1, x2, etc. in order of binding.
+    This produces a canonical form for α-equivalent terms.
+    """
+    if counter is None:
+        counter = [0]
+
+    term = load_term(collection, hash_value)
+    if term is None:
+        return None
+
+    if is_var(term):
+        return hash_value
+
+    elif is_abs(term):
+        # Generate fresh normalized name
+        new_name = f"x{counter[0]}"
+        counter[0] += 1
+
+        # Rename this binding
+        renamed_body = alpha_rename(collection, term.body, term.param, new_name)
+        if renamed_body is None:
+            return None
+
+        # Recursively normalize the body
+        normalized_body = alpha_normalize(collection, renamed_body, counter)
+        if normalized_body is None:
+            return None
+
+        return store_term(collection, mk_abs(new_name, normalized_body))
+
+    elif is_app(term):
+        norm_func = alpha_normalize(collection, term.func, counter)
+        norm_arg = alpha_normalize(collection, term.arg, counter)
+        if norm_func is None or norm_arg is None:
+            return None
+        return store_term(collection, mk_app(norm_func, norm_arg))
+
+    return hash_value