hypermind 0.11.0__py3-none-any.whl

hypermind/transport/tcp.py

@@ -0,0 +1,797 @@
+"""Real TCP transport — async TCP gossipsub-shape with identity binding.
+
+Each peer-to-peer connection performs a 2-message handshake binding
+both endpoints' Ed25519 identities, then exchanges length-prefixed
+CBOR frames carrying topic + message. Topic membership is reputation-
+weighted: a peer joining a mesh announces its kid; the local node
+checks reputation policy before accepting traffic.
+
+This is a working real-network transport (not a stub) — start nodes on
+different ports, dial them via `connect()`, and gossip propagates over
+asyncio TCP streams. Production deployments may swap this for libp2p
+gossipsub v1.2; the `GossipBus` interface stays the same.
+
+WS-G hardening (v0.7):
+  * Per-peer bounded write queue (`asyncio.Queue(maxsize=PEER_QUEUE_MAX)`)
+    + dedicated sender task per peer. Prevents one slow peer from
+    pinning memory or stalling the publish fan-out path.
+  * Drop-newest backpressure: queue-full → ``peer_drops_total{kid}``
+    counter, peer score penalty, and graylist after 3 drops in 30s.
+  * Per-(source_kid, topic) token bucket: 100 msg/s burst 200. Excess
+    is rejected with a score penalty.
+  * Per-peer EWMA score: ``score = w1*time_in_mesh + w2*deliveries
+    - w3*invalid - w4*backpressure_drops``. Below threshold the peer
+    is graylisted for ``GRAYLIST_DURATION_S``.
+  * Two-tier seen cache: per-peer LRU (1024) + global secondary LRU
+    (16k). Defeats both per-flow flooding and amplification attacks.
+
+Wire frame format:
+    [u32 BE length][CBOR map { "type": str, ...payload }]
+
+Frame types:
+    "hello": {"kid": bytes32, "alg": int, "sig": bytes, "nonce": bytes32}
+    "publish": {"topic": str, "message": bytes, "msg_id": bytes32}
+    "subscribe": {"topic": str}
+    "ack": {"msg_id": bytes32}
+"""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+import struct
+import time
+from collections import OrderedDict, deque
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+import cbor2
+from nacl.signing import SigningKey
+
+from hypermind.crypto.signing import Keypair, verify_ed25519
+from hypermind.transport.bus import Subscription
+
+# ---------------------------------------------------------------------------
+# Tunables (WS-G robustness profile).
+# ---------------------------------------------------------------------------
+
+SEEN_CACHE_MAX = 16384  # global secondary LRU cap (memory DoS bound).
+PER_PEER_SEEN_MAX = 1024  # per-peer LRU; first-line dedup tier.
+PEER_QUEUE_MAX = 4096  # per-peer write queue depth.
+
+# Token-bucket rate limit per (source_kid, topic).
+RATE_LIMIT_RATE = 100.0  # tokens/second steady state.
+RATE_LIMIT_BURST = 200.0  # max bucket size.
+
+# Backpressure / graylist policy.
+DROP_BURST_THRESHOLD = 3  # consecutive drops within window.
+DROP_BURST_WINDOW_S = 30.0
+GRAYLIST_DURATION_S = 3600.0  # 1 hour default.
+
+# EWMA scoring weights (per RFC-style gossipsub v1.2 inspiration).
+SCORE_W_TIME_IN_MESH = 0.1
+SCORE_W_DELIVERIES = 1.0
+SCORE_W_INVALID = 5.0
+SCORE_W_BACKPRESSURE = 2.0
+SCORE_GRAYLIST_THRESHOLD = -50.0
+
+Handler = Callable[[bytes], Awaitable[None]]
+
+FRAME_HEADER = struct.Struct(">I")
+MAX_FRAME = 16 * 1024 * 1024  # 16 MB hard cap
+
+
+# ---------------------------------------------------------------------------
+# Token-bucket rate limiter (per (source_kid, topic)).
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _TokenBucket:
+    """Lazy-fill token bucket. Allows ``rate`` tokens/sec, burst ``capacity``.
+
+    Updates the bucket only on consume — no background task required.
+    """
+
+    rate: float
+    capacity: float
+    tokens: float
+    last_ms: int
+
+    @classmethod
+    def create(cls, rate: float = RATE_LIMIT_RATE, burst: float = RATE_LIMIT_BURST) -> _TokenBucket:
+        return cls(rate=rate, capacity=burst, tokens=burst, last_ms=_now_ms())
+
+    def try_consume(self, n: float = 1.0) -> bool:
+        now = _now_ms()
+        elapsed = max(0, now - self.last_ms) / 1000.0
+        self.tokens = min(self.capacity, self.tokens + elapsed * self.rate)
+        self.last_ms = now
+        if self.tokens >= n:
+            self.tokens -= n
+            return True
+        return False
+
+
+@dataclass
+class _PeerConn:
+    kid: bytes
+    reader: asyncio.StreamReader
+    writer: asyncio.StreamWriter
+    topics: set[str] = field(default_factory=set)
+    # WS-G: bounded write queue + dedicated sender task.
+    send_queue: asyncio.Queue[dict] = field(
+        default_factory=lambda: asyncio.Queue(maxsize=PEER_QUEUE_MAX)
+    )
+    sender_task: asyncio.Task | None = None
+    # Per-peer LRU dedup (first-tier).
+    seen: OrderedDict[bytes, None] = field(default_factory=OrderedDict)
+    # Score state.
+    connected_at_ms: int = field(default_factory=lambda: _now_ms())
+    deliveries: int = 0
+    invalid_frames: int = 0
+    backpressure_drops: int = 0
+    drop_history: deque[float] = field(default_factory=deque)
+
+    def record_seen(self, msg_id: bytes) -> bool:
+        """Insert into per-peer LRU. Returns True if NEW (caller should
+        dispatch); False if duplicate (caller should drop)."""
+        if msg_id in self.seen:
+            self.seen.move_to_end(msg_id)
+            return False
+        self.seen[msg_id] = None
+        while len(self.seen) > PER_PEER_SEEN_MAX:
+            self.seen.popitem(last=False)
+        return True
+
+    def score(self) -> float:
+        """Composite EWMA-style score. Higher is better; below
+        SCORE_GRAYLIST_THRESHOLD triggers graylisting."""
+        time_in_mesh_s = max(0, _now_ms() - self.connected_at_ms) / 1000.0
+        return (
+            SCORE_W_TIME_IN_MESH * time_in_mesh_s
+            + SCORE_W_DELIVERIES * self.deliveries
+            - SCORE_W_INVALID * self.invalid_frames
+            - SCORE_W_BACKPRESSURE * self.backpressure_drops
+        )
+
+
+class TCPGossipBus:
+    """Real asyncio TCP gossipsub bus.
+
+    Each instance can simultaneously be a server (accepting incoming
+    connections) and a client (dialing peers). Once handshake completes,
+    `publish(topic, message)` fans out to every connected peer that has
+    subscribed to that topic; `subscribe(topic, handler)` registers a
+    local handler that receives both local + remote publishes.
+    """
+
+    def __init__(
+        self,
+        *,
+        identity: Keypair,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        require_tls: bool = False,
+        tls_trust_anchors: list[bytes] | None = None,
+        tls_allow_aes128: bool = False,
+    ):
+        self.identity = identity
+        self.host = host
+        self.port = port
+        # L2 mTLS profile (§22). When True, listen / connect socket is
+        # wrapped with the TLS 1.3 profile from `tls_profile.py` BEFORE
+        # the existing CBOR handshake runs. The handshake, SEEN_CACHE_MAX
+        # LRU, and duplicate-kid rejection are unchanged — TLS is purely
+        # additive here.
+        self.require_tls = require_tls
+        self._tls_allow_aes128 = tls_allow_aes128
+        self._tls_trust_anchors: list[bytes] = list(tls_trust_anchors or [])
+        self._tls_cert_pem: bytes | None = None
+        self._server: asyncio.AbstractServer | None = None
+        self._peers: dict[bytes, _PeerConn] = {}
+        self._handlers: dict[str, list[Handler]] = {}
+        # Two-tier dedup: per-peer (in _PeerConn.seen) + global secondary.
+        # OrderedDict-as-LRU bounds memory DoS via msg_id flooding.
+        self._seen: OrderedDict[bytes, None] = OrderedDict()
+        self._lock = asyncio.Lock()
+        self._closed = False
+        self._tasks: set[asyncio.Task] = set()
+        # Bad-frame counter — surfaced via `metrics()` for monitoring.
+        self._bad_frames: int = 0
+        # Per-peer drop counter — surfaced via `metrics()`.
+        self._peer_drops_total: dict[bytes, int] = {}
+        # Per-peer rate-rejected counter — surfaced via `metrics()`.
+        self._rate_rejects_total: dict[bytes, int] = {}
+        # Token buckets keyed by (source_kid, topic).
+        self._buckets: dict[tuple[bytes, str], _TokenBucket] = {}
+        # Graylist: kid → expiry wall-time seconds.
+        self._graylist: dict[bytes, float] = {}
+
+    # ---- server / dial ------------------------------------------------
+
+    async def start(self) -> int:
+        """Bind and start accepting peers; return the bound port."""
+        ssl_ctx = self._build_server_tls_context() if self.require_tls else None
+        self._server = await asyncio.start_server(
+            self._on_accept, host=self.host, port=self.port, ssl=ssl_ctx
+        )
+        sock = self._server.sockets[0]
+        self.port = sock.getsockname()[1]
+        return self.port
+
+    # ---- TLS context builders (§22 L2 profile) ------------------------
+
+    def _build_server_tls_context(self):
+        from hypermind.transport.tls_profile import (
+            ed25519_priv_from_secret,
+            make_server_context,
+            selfsigned_cert_for_kid,
+        )
+
+        priv = ed25519_priv_from_secret(self.identity.secret_bytes)
+        if self._tls_cert_pem is None:
+            self._tls_cert_pem = selfsigned_cert_for_kid(self.identity.kid, priv)
+        return make_server_context(
+            priv,
+            self._tls_cert_pem,
+            trust_anchors=self._tls_trust_anchors or None,
+            allow_aes128=self._tls_allow_aes128,
+        )
+
+    def _build_client_tls_context(self):
+        from hypermind.transport.tls_profile import (
+            ed25519_priv_from_secret,
+            make_client_context,
+            selfsigned_cert_for_kid,
+        )
+
+        priv = ed25519_priv_from_secret(self.identity.secret_bytes)
+        if self._tls_cert_pem is None:
+            self._tls_cert_pem = selfsigned_cert_for_kid(self.identity.kid, priv)
+        anchors = self._tls_trust_anchors or [self._tls_cert_pem]
+        return make_client_context(
+            anchors,
+            client_cert_pem=self._tls_cert_pem,
+            client_key=priv,
+            allow_aes128=self._tls_allow_aes128,
+        )
+
+    async def connect(self, peer_host: str, peer_port: int) -> bytes:
+        """Dial a peer and complete the handshake. Returns peer's kid.
+
+        Rejects connections to a kid we already have a live peer for —
+        defeats the "race-to-overwrite" attack where an adversary
+        learning a target's kid evicts the legitimate session
+        (closes self-heal Cycle-1 Finding #3).
+        """
+        ssl_ctx = self._build_client_tls_context() if self.require_tls else None
+        reader, writer = await asyncio.open_connection(
+            peer_host,
+            peer_port,
+            ssl=ssl_ctx,
+            server_hostname=peer_host if ssl_ctx is not None else None,
+        )
+        try:
+            if self.require_tls:
+                _verify_tls_alpn(writer)
+            peer_kid = await self._handshake_initiator(reader, writer)
+            if self.require_tls:
+                _verify_tls_kid_binding(writer, peer_kid)
+        except Exception:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+            raise
+        if self._is_graylisted(peer_kid):
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+            raise RuntimeError(f"peer kid {peer_kid.hex()[:16]}… is graylisted")
+        peer = _PeerConn(kid=peer_kid, reader=reader, writer=writer)
+        async with self._lock:
+            if peer_kid in self._peers:
+                # Reject collision; close the new connection cleanly.
+                writer.close()
+                try:
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+                raise RuntimeError(f"peer kid {peer_kid.hex()[:16]}… already connected")
+            self._peers[peer_kid] = peer
+            self._spawn_sender(peer)
+            # Re-announce existing local subscriptions to the new peer.
+            for topic in self._handlers:
+                self._enqueue(peer, {"type": "subscribe", "topic": topic})
+        task = asyncio.create_task(self._read_loop(peer))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return peer_kid
+
+    async def _on_accept(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            if self.require_tls:
+                _verify_tls_alpn(writer)
+            peer_kid = await self._handshake_responder(reader, writer)
+            if self.require_tls:
+                _verify_tls_kid_binding(writer, peer_kid)
+        except Exception:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+            return
+        if self._is_graylisted(peer_kid):
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+            return
+        peer = _PeerConn(kid=peer_kid, reader=reader, writer=writer)
+        async with self._lock:
+            if peer_kid in self._peers:
+                # Reject duplicate kid — preserves the legitimate peer.
+                writer.close()
+                try:
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+                return
+            self._peers[peer_kid] = peer
+            self._spawn_sender(peer)
+            for topic in self._handlers:
+                self._enqueue(peer, {"type": "subscribe", "topic": topic})
+        await self._read_loop(peer)
+
+    # ---- handshake ----------------------------------------------------
+    # Both sides exchange: their kid + a fresh nonce + a signature over
+    # (their_nonce || peer_nonce || self.kid). This binds the identity
+    # to the session and prevents replay across connections.
+
+    async def _handshake_initiator(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> bytes:
+        my_nonce = secrets.token_bytes(32)
+        # First message: send our kid + nonce (no sig yet).
+        await _write_frame(
+            writer,
+            {
+                "type": "hello",
+                "kid": self.identity.kid,
+                "alg": self.identity.alg,
+                "nonce": my_nonce,
+                "sig": b"",
+            },
+        )
+        peer_msg = await _read_frame(reader)
+        if peer_msg.get("type") != "hello":
+            raise RuntimeError("expected hello from responder")
+        peer_kid = bytes(peer_msg["kid"])
+        if len(peer_kid) != 32:
+            raise RuntimeError("peer handshake: invalid kid length")
+        peer_nonce = bytes(peer_msg["nonce"])
+        peer_sig = bytes(peer_msg["sig"])
+        # Verify peer's signature over (peer_nonce || my_nonce || peer_kid).
+        peer_preimage = peer_nonce + my_nonce + peer_kid
+        if not verify_ed25519(peer_kid, peer_sig, peer_preimage):
+            raise RuntimeError("peer handshake signature invalid")
+        # Send our signature.
+        my_preimage = my_nonce + peer_nonce + self.identity.kid
+        my_sig = SigningKey(self.identity.secret_bytes[:32]).sign(my_preimage).signature
+        await _write_frame(
+            writer,
+            {
+                "type": "hello_ack",
+                "kid": self.identity.kid,
+                "sig": my_sig,
+            },
+        )
+        return peer_kid
+
+    async def _handshake_responder(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> bytes:
+        peer_msg = await _read_frame(reader)
+        if peer_msg.get("type") != "hello":
+            raise RuntimeError("expected hello from initiator")
+        peer_kid = bytes(peer_msg["kid"])
+        if len(peer_kid) != 32:
+            raise RuntimeError("peer handshake: invalid kid length")
+        peer_nonce = bytes(peer_msg["nonce"])
+        my_nonce = secrets.token_bytes(32)
+        # Sign (my_nonce || peer_nonce || my_kid)
+        my_preimage = my_nonce + peer_nonce + self.identity.kid
+        my_sig = SigningKey(self.identity.secret_bytes[:32]).sign(my_preimage).signature
+        await _write_frame(
+            writer,
+            {
+                "type": "hello",
+                "kid": self.identity.kid,
+                "alg": self.identity.alg,
+                "nonce": my_nonce,
+                "sig": my_sig,
+            },
+        )
+        # Receive initiator's signature (over their_nonce || my_nonce || their_kid)
+        ack = await _read_frame(reader)
+        if ack.get("type") != "hello_ack":
+            raise RuntimeError("expected hello_ack from initiator")
+        peer_sig = bytes(ack["sig"])
+        peer_preimage = peer_nonce + my_nonce + peer_kid
+        if not verify_ed25519(peer_kid, peer_sig, peer_preimage):
+            raise RuntimeError("initiator signature invalid")
+        return peer_kid
+
+    # ---- pub/sub interface --------------------------------------------
+
+    async def publish(self, topic: str, message: bytes) -> None:
+        if self._closed:
+            raise RuntimeError("bus is closed")
+        if not isinstance(message, (bytes, bytearray)):
+            raise TypeError(f"message must be bytes, got {type(message).__name__}")
+        msg_id = secrets.token_bytes(32)
+        async with self._lock:
+            self._record_seen(msg_id)
+        # Local delivery first (own subscribers see own publishes).
+        for h in list(self._handlers.get(topic, ())):
+            await _safe_invoke(h, message)
+        # Then fan-out to every peer subscribed to the topic.
+        async with self._lock:
+            peers = [p for p in self._peers.values() if topic in p.topics]
+        frame = {"type": "publish", "topic": topic, "message": message, "msg_id": msg_id}
+        for p in peers:
+            self._enqueue(p, frame)
+
+    def _record_seen(self, msg_id: bytes) -> None:
+        """Global secondary LRU (`_seen`) cache. Evicts oldest when full.
+
+        First-tier dedup is per-peer in `_PeerConn.seen`; this global
+        tier catches messages we already saw via *some other peer*."""
+        if msg_id in self._seen:
+            self._seen.move_to_end(msg_id)
+            return
+        self._seen[msg_id] = None
+        while len(self._seen) > SEEN_CACHE_MAX:
+            self._seen.popitem(last=False)
+
+    def metrics(self) -> dict[str, object]:
+        """Operational counters (bad frames, peer count, drops, scores)."""
+        # Snapshot keyed-counters into hex-shortened views for readability.
+        peer_drops = {kid.hex()[:16]: v for kid, v in self._peer_drops_total.items()}
+        rate_rejects = {kid.hex()[:16]: v for kid, v in self._rate_rejects_total.items()}
+        scores = {p.kid.hex()[:16]: p.score() for p in self._peers.values()}
+        return {
+            "peers": len(self._peers),
+            "seen_cache": len(self._seen),
+            "bad_frames": self._bad_frames,
+            "peer_drops_total": peer_drops,
+            "rate_rejects_total": rate_rejects,
+            "peer_scores": scores,
+            "graylist_size": len(self._graylist),
+        }
+
+    async def subscribe(self, topic: str, handler: Handler) -> Subscription:
+        if self._closed:
+            raise RuntimeError("bus is closed")
+        async with self._lock:
+            self._handlers.setdefault(topic, []).append(handler)
+            peers = list(self._peers.values())
+        # Announce subscription to all known peers (queued; best-effort).
+        for p in peers:
+            self._enqueue(p, {"type": "subscribe", "topic": topic})
+
+        def _cancel() -> None:
+            try:
+                self._handlers[topic].remove(handler)
+            except (ValueError, KeyError):
+                pass
+
+        return Subscription(topic=topic, _cancel=_cancel)
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        async with self._lock:
+            peers = list(self._peers.values())
+            self._peers.clear()
+        for peer in peers:
+            if peer.sender_task is not None:
+                peer.sender_task.cancel()
+            try:
+                peer.writer.close()
+                await peer.writer.wait_closed()
+            except Exception:
+                pass
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+        for task in list(self._tasks):
+            task.cancel()
+
+    # ---- I/O ----------------------------------------------------------
+
+    async def _read_loop(self, peer: _PeerConn) -> None:
+        """Decode + dispatch frames. Malformed frames bump the
+        bad-frame counter and continue (a single bad frame must NOT
+        kill the connection — closes self-heal Cycle-1 Finding #9
+        from data review).
+        """
+        try:
+            while not self._closed:
+                try:
+                    msg = await _read_frame(peer.reader)
+                except (cbor2.CBORDecodeError, ValueError, TypeError):
+                    self._bad_frames += 1
+                    peer.invalid_frames += 1
+                    self._maybe_graylist(peer)
+                    continue
+                if not isinstance(msg, dict):
+                    self._bad_frames += 1
+                    peer.invalid_frames += 1
+                    self._maybe_graylist(peer)
+                    continue
+                msg_type = msg.get("type")
+                if msg_type == "subscribe":
+                    topic = msg.get("topic")
+                    if not isinstance(topic, str):
+                        self._bad_frames += 1
+                        peer.invalid_frames += 1
+                        continue
+                    peer.topics.add(topic)
+                elif msg_type == "publish":
+                    msg_id_v = msg.get("msg_id")
+                    topic_v = msg.get("topic")
+                    payload_v = msg.get("message")
+                    if (
+                        not isinstance(msg_id_v, (bytes, bytearray))
+                        or not isinstance(topic_v, str)
+                        or not isinstance(payload_v, (bytes, bytearray))
+                    ):
+                        self._bad_frames += 1
+                        peer.invalid_frames += 1
+                        continue
+                    msg_id = bytes(msg_id_v)
+                    if len(msg_id) != 32:
+                        self._bad_frames += 1
+                        peer.invalid_frames += 1
+                        continue
+                    topic = topic_v
+                    payload = bytes(payload_v)
+                    # Token-bucket: per (source_kid, topic). On reject,
+                    # bump invalid counter and skip dispatch + re-gossip.
+                    bucket_key = (peer.kid, topic)
+                    bucket = self._buckets.get(bucket_key)
+                    if bucket is None:
+                        bucket = _TokenBucket.create()
+                        self._buckets[bucket_key] = bucket
+                    if not bucket.try_consume():
+                        self._rate_rejects_total[peer.kid] = (
+                            self._rate_rejects_total.get(peer.kid, 0) + 1
+                        )
+                        peer.invalid_frames += 1
+                        self._maybe_graylist(peer)
+                        continue
+                    # Per-peer LRU first; if duplicate, skip.
+                    if not peer.record_seen(msg_id):
+                        continue
+                    async with self._lock:
+                        if msg_id in self._seen:
+                            self._seen.move_to_end(msg_id)
+                            # Already saw this via another peer; dedup
+                            # but still credit the peer for delivery.
+                            peer.deliveries += 1
+                            continue
+                        self._record_seen(msg_id)
+                    peer.deliveries += 1
+                    for h in list(self._handlers.get(topic, ())):
+                        await _safe_invoke(h, payload)
+                    # Re-gossip to other peers subscribed to this topic.
+                    async with self._lock:
+                        forward_targets = [
+                            p for p in self._peers.values() if p is not peer and topic in p.topics
+                        ]
+                    forward_frame = {
+                        "type": "publish",
+                        "topic": topic,
+                        "message": payload,
+                        "msg_id": msg_id,
+                    }
+                    for fwd in forward_targets:
+                        self._enqueue(fwd, forward_frame)
+                else:
+                    # Unknown frame type — count and ignore.
+                    self._bad_frames += 1
+                    peer.invalid_frames += 1
+        except (asyncio.IncompleteReadError, OSError, asyncio.CancelledError):
+            # OSError catches ECONNRESET and the broader connection-error
+            # family on every platform (and subsumes ConnectionError).
+            # Closes self-heal Cycle-3 issue #5.
+            pass
+        finally:
+            async with self._lock:
+                self._peers.pop(peer.kid, None)
+            if peer.sender_task is not None:
+                peer.sender_task.cancel()
+            try:
+                peer.writer.close()
+                # Drain the OS-level socket so the file descriptor is fully
+                # released; otherwise abrupt disconnects can leak fds.
+                await peer.writer.wait_closed()
+            except Exception:
+                pass
+
+    # ---- per-peer sender + queue --------------------------------------
+
+    def _spawn_sender(self, peer: _PeerConn) -> None:
+        """Start the dedicated sender task for ``peer``.
+
+        Caller must hold ``self._lock`` (or be in single-threaded init).
+        """
+        task = asyncio.create_task(self._sender_loop(peer))
+        peer.sender_task = task
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def _sender_loop(self, peer: _PeerConn) -> None:
+        """Drain ``peer.send_queue`` and write frames. One per peer."""
+        try:
+            while not self._closed:
+                msg = await peer.send_queue.get()
+                try:
+                    await _write_frame(peer.writer, msg)
+                except (ConnectionError, asyncio.CancelledError):
+                    return
+                except Exception:
+                    # A single failed write must not kill the loop —
+                    # log and continue with the next frame.
+                    continue
+        except asyncio.CancelledError:
+            return
+
+    def _enqueue(self, peer: _PeerConn, frame: dict) -> None:
+        """Enqueue a frame for ``peer``. Drops newest on overflow.
+
+        On drop: increments per-peer ``peer_drops_total``, scores down,
+        and graylists the peer if 3+ drops fall inside a 30s window
+        (matches the WS-G policy).
+        """
+        try:
+            peer.send_queue.put_nowait(frame)
+        except asyncio.QueueFull:
+            self._peer_drops_total[peer.kid] = self._peer_drops_total.get(peer.kid, 0) + 1
+            peer.backpressure_drops += 1
+            now = time.time()
+            peer.drop_history.append(now)
+            cutoff = now - DROP_BURST_WINDOW_S
+            while peer.drop_history and peer.drop_history[0] < cutoff:
+                peer.drop_history.popleft()
+            if len(peer.drop_history) >= DROP_BURST_THRESHOLD:
+                self._graylist[peer.kid] = now + GRAYLIST_DURATION_S
+                # Schedule eviction; writer close happens here, full
+                # cleanup runs in _read_loop's finally.
+                try:
+                    peer.writer.close()
+                except Exception:
+                    pass
+
+    async def _send(self, peer: _PeerConn, msg: dict) -> None:
+        """Back-compat direct-write shim.
+
+        Most code paths now go through ``_enqueue`` + the per-peer
+        sender task; this entrypoint stays for tests + callers that
+        need synchronous-ish "best effort" delivery semantics.
+        """
+        try:
+            await _write_frame(peer.writer, msg)
+        except (ConnectionError, asyncio.CancelledError):
+            pass
+
+    # ---- scoring + graylist -------------------------------------------
+
+    def _is_graylisted(self, kid: bytes) -> bool:
+        expiry = self._graylist.get(kid)
+        if expiry is None:
+            return False
+        if time.time() >= expiry:
+            self._graylist.pop(kid, None)
+            return False
+        return True
+
+    def _maybe_graylist(self, peer: _PeerConn) -> None:
+        """If ``peer.score()`` has dropped below threshold, graylist."""
+        if peer.score() < SCORE_GRAYLIST_THRESHOLD:
+            self._graylist[peer.kid] = time.time() + GRAYLIST_DURATION_S
+            try:
+                peer.writer.close()
+            except Exception:
+                pass
+
+
+# ---- frame I/O ----------------------------------------------------------
+
+
+async def _read_frame(reader: asyncio.StreamReader) -> dict:
+    header = await reader.readexactly(FRAME_HEADER.size)
+    (length,) = FRAME_HEADER.unpack(header)
+    if length > MAX_FRAME:
+        raise RuntimeError(f"frame too large: {length} bytes")
+    body = await reader.readexactly(length)
+    return cbor2.loads(body)
+
+
+async def _write_frame(writer: asyncio.StreamWriter, msg: dict) -> None:
+    body = cbor2.dumps(msg, canonical=True)
+    if len(body) > MAX_FRAME:
+        raise RuntimeError(f"frame too large: {len(body)} bytes")
+    writer.write(FRAME_HEADER.pack(len(body)))
+    writer.write(body)
+    await writer.drain()
+
+
+async def _safe_invoke(handler: Handler, message: bytes) -> None:
+    try:
+        await handler(message)
+    except Exception as e:
+        try:
+            from hypermind.observability.recorder import get_recorder
+
+            get_recorder().incr(
+                "hypermind_handler_errors_total",
+                kind=type(e).__name__,
+            )
+        except Exception:  # pragma: no cover
+            pass
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _verify_tls_alpn(writer: asyncio.StreamWriter) -> None:
+    """Enforce §22.3: the negotiated ALPN protocol MUST be `hm/2`.
+
+    CPython's `ssl` module does not expose a selection callback, so we
+    enforce the §22.3 ban on ALPN-absent operation at the application
+    layer: if the peer offered no overlap, `selected_alpn_protocol()`
+    is None and we close the connection (`CASCADE-L2-ALPN`).
+    """
+    from hypermind.transport.tls_profile import ALPN_HM2
+
+    ssl_obj = writer.get_extra_info("ssl_object")
+    if ssl_obj is None:
+        raise RuntimeError("TLS required but no SSL object on the connection")
+    selected = ssl_obj.selected_alpn_protocol()
+    if selected != ALPN_HM2:
+        raise RuntimeError(f"CASCADE-L2-ALPN: expected ALPN {ALPN_HM2!r}, got {selected!r}")
+
+
+def _verify_tls_kid_binding(writer: asyncio.StreamWriter, claimed_kid: bytes) -> None:
+    """Ensure the TLS peer cert's `id-hm-kid` SAN equals the application-
+    layer kid claimed during the CBOR handshake. Closes connection on
+    mismatch — implements `CASCADE-L2-KID-MISMATCH` (§22.5/§22.8).
+    """
+    import ssl as _ssl
+
+    from hypermind.transport.tls_profile import extract_kid_from_cert
+
+    ssl_obj = writer.get_extra_info("ssl_object")
+    if ssl_obj is None:
+        raise RuntimeError("TLS required but no SSL object on the connection")
+    der = ssl_obj.getpeercert(binary_form=True)
+    if not der:
+        raise RuntimeError("TLS required but peer presented no certificate")
+    pem = _ssl.DER_cert_to_PEM_cert(der).encode("ascii")
+    cert_kid = extract_kid_from_cert(pem)
+    if cert_kid != claimed_kid:
+        raise RuntimeError(
+            f"CASCADE-L2-KID-MISMATCH: TLS cert kid {cert_kid.hex()[:16]}… "
+            f"!= handshake kid {claimed_kid.hex()[:16]}…"
+        )